Adding JSDoc, removing id from block config and including schemna in …

…reader/editor (#4)

* Adding JSDoc
* Updating tests to not include id
* Including schema in reader/editor
* Bumping version

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usewaypoint/document",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "Tools to render waypoint-style documents.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

src/builders/buildBlockComponent.ts

@@ -1,15 +1,13 @@
 import React from 'react';
-import { z } from 'zod';
 
-import { BaseZodDictionary, DocumentBlocksDictionary } from '../utils';
+import { BaseZodDictionary, BlockConfiguration, DocumentBlocksDictionary } from '../utils';
 
+/**
+ * @param blocks Main DocumentBlocksDictionary
+ * @returns React component that can render a BlockConfiguration that is compatible with blocks
+ */
 export default function buildBlockComponent<T extends BaseZodDictionary>(blocks: DocumentBlocksDictionary<T>) {
-  type BaseBlockComponentProps<TType extends keyof T> = {
-    type: TType;
-    data: z.infer<T[TType]>;
-  };
-
-  return function BlockComponent({ type, data }: BaseBlockComponentProps<keyof T>): React.ReactNode {
+  return function BlockComponent({ type, data }: BlockConfiguration<T>): React.ReactNode {
     return React.createElement(blocks[type].Component, data);
   };
 }

src/builders/buildBlockConfigurationByIdSchema.ts

@@ -4,6 +4,10 @@ import { BaseZodDictionary, DocumentBlocksDictionary } from '../utils';
 
 import buildBlockConfigurationSchema from './buildBlockConfigurationSchema';
 
+/**
+ * @param blocks Main DocumentBlocksDictionary
+ * @returns zod schema that can parse arbitrary objects into { [id]: BlockConfiguration } pairs
+ */
 export default function buildBlockConfigurationByIdSchema<T extends BaseZodDictionary>(
   blocks: DocumentBlocksDictionary<T>
 ) {

src/builders/buildBlockConfigurationSchema.ts

@@ -1,24 +1,22 @@
 import { z } from 'zod';
 
-import { BaseZodDictionary, DocumentBlocksDictionary } from '../utils';
+import { BaseZodDictionary, BlockConfiguration, DocumentBlocksDictionary } from '../utils';
 
+/**
+ *
+ * @param blocks Main DocumentBlocksDictionary
+ * @returns zod schema that can parse arbitary objects into a single BlockConfiguration
+ */
 export default function buildBlockConfigurationSchema<T extends BaseZodDictionary>(
   blocks: DocumentBlocksDictionary<T>
 ) {
-  type BaseBlockComponentProps<TType extends keyof T> = {
-    id: string;
-    type: TType;
-    data: z.infer<T[TType]>;
-  };
-
   const blockObjects = Object.keys(blocks).map((type: keyof T) =>
     z.object({
-      id: z.string(),
       type: z.literal(type),
       data: blocks[type].schema,
     })
   );
 
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  return z.discriminatedUnion('type', blockObjects as any).transform((v) => v as BaseBlockComponentProps<keyof T>);
+  return z.discriminatedUnion('type', blockObjects as any).transform((v) => v as BlockConfiguration<T>);
 }

src/builders/buildDocumentEditor.ts

@@ -6,6 +6,19 @@ import { BaseZodDictionary, BlockNotFoundError, DocumentBlocksDictionary } from
 import buildBlockComponent from './buildBlockComponent';
 import buildBlockConfigurationByIdSchema from './buildBlockConfigurationByIdSchema';
 
+/**
+ * @typedef {Object} DocumentEditor
+ * @property DocumentEditorProvider - Entry point to the DocumentEditor
+ * @property DocumentConfigurationSchema - zod schema compatible with the value that DocumentReaderProvider expects
+ * @property Block - Component to render a block given an id
+ * @property useDocumentState - Hook that returns the current DocumentState and a setter
+ * @property useBlockState - Hook that returns the Block value and setter given an id
+ */
+
+/**
+ * @param {DocumentBlocksDictionary} blocks root configuration
+ * @returns {DocumentEditor}
+ */
 export default function buildDocumentEditor<T extends BaseZodDictionary>(blocks: DocumentBlocksDictionary<T>) {
   const schema = buildBlockConfigurationByIdSchema(blocks);
   const BlockComponent = buildBlockComponent(blocks);
@@ -21,28 +34,30 @@ export default function buildDocumentEditor<T extends BaseZodDictionary>(blocks:
   };
 
   const useDocumentState = () => useContext(Context);
-  const useBlockState = (id: string) => {
+  const useBlockState = (id: string | null | undefined) => {
     const [value, setValue] = useDocumentState();
-    return useMemo(
-      () =>
-        [
-          value[id],
-          (block: TValue[string]) => {
-            setValue({ ...value, [id]: block });
-          },
-        ] as const,
-      [value, setValue, id]
-    );
+    return useMemo(() => {
+      if (id === null || id === undefined) {
+        return null;
+      }
+      return [
+        value[id],
+        (block: TValue[string]) => {
+          setValue({ ...value, [id]: block });
+        },
+      ] as const;
+    }, [value, setValue, id]);
   };
   return {
     useDocumentState,
     useBlockState,
+    DocumentConfigurationSchema: schema,
     Block: ({ id }: { id: string }) => {
-      const [block] = useBlockState(id);
-      if (!block) {
+      const state = useBlockState(id);
+      if (state === null || !state[0]) {
         throw new BlockNotFoundError(id);
       }
-      const { type, data } = block;
+      const { type, data } = state[0];
       return React.createElement(BlockComponent, { type, data });
     },
     DocumentEditorProvider: ({ value, children }: TProviderProps) => {

src/builders/buildDocumentReader.ts

@@ -6,6 +6,19 @@ import { BaseZodDictionary, BlockNotFoundError, DocumentBlocksDictionary } from
 import buildBlockComponent from './buildBlockComponent';
 import buildBlockConfigurationByIdSchema from './buildBlockConfigurationByIdSchema';
 
+/**
+ * @typedef {Object} DocumentReader
+ * @property DocumentReaderProvider - Entry point to the DocumentReader
+ * @property DocumentConfigurationSchema - zod schema compatible with the value that DocumentReaderProvider expects
+ * @property Block - Component to render a block given an id
+ * @property useDocument - Hook that returns the current Document
+ * @property useBlock - Hook that returns the block given an id
+ */
+
+/**
+ * @param {DocumentBlocksDictionary} blocks root configuration
+ * @returns {DocumentReader}
+ */
 export default function buildDocumentReader<T extends BaseZodDictionary>(blocks: DocumentBlocksDictionary<T>) {
   const schema = buildBlockConfigurationByIdSchema(blocks);
   const BlockComponent = buildBlockComponent(blocks);
@@ -26,6 +39,7 @@ export default function buildDocumentReader<T extends BaseZodDictionary>(blocks:
   return {
     useDocument,
     useBlock,
+    DocumentConfigurationSchema: schema,
     Block: ({ id }: { id: string }) => {
       const block = useBlock(id);
       if (!block) {

src/index.tsx

@@ -3,4 +3,4 @@ export { default as buildBlockConfigurationSchema } from './builders/buildBlockC
 export { default as buildBlockConfigurationByIdSchema } from './builders/buildBlockConfigurationByIdSchema';
 export { default as buildDocumentReader } from './builders/buildDocumentReader';
 export { default as buildDocumentEditor } from './builders/buildDocumentEditor';
-export { DocumentBlocksDictionary } from './utils';
+export { BlockConfiguration, DocumentBlocksDictionary } from './utils';

src/utils.ts

@@ -9,6 +9,13 @@ export type DocumentBlocksDictionary<T extends BaseZodDictionary> = {
   };
 };
 
+export type BlockConfiguration<T extends BaseZodDictionary> = {
+  [TType in keyof T]: {
+    type: TType;
+    data: z.infer<T[TType]>;
+  };
+}[keyof T];
+
 export class BlockNotFoundError extends Error {
   blockId: string;
   constructor(blockId: string) {

tests/builder/buildBlockConfigurationByIdSchema.spec.tsx

@@ -13,7 +13,6 @@ describe('builders/buildBlockConfigurationByIdSchema', () => {
     });
     const parsedData = schema.safeParse({
       'my id': {
-        id: 'my id',
         type: 'SampleBlock',
         data: { text: 'Test text!' },
       },
@@ -22,7 +21,6 @@ describe('builders/buildBlockConfigurationByIdSchema', () => {
       success: true,
       data: {
         'my id': {
-          id: 'my id',
           type: 'SampleBlock',
           data: { text: 'Test text!' },
         },

tests/builder/buildBlockConfigurationSchema.spec.tsx

@@ -12,14 +12,12 @@ describe('builders/buildBlockConfigurationSchema', () => {
       },
     });
     const parsedData = blockConfigurationSchema.safeParse({
-      id: 'my id',
       type: 'SampleBlock',
       data: { text: 'Test text!' },
     });
     expect(parsedData).toEqual({
       success: true,
       data: {
-        id: 'my id',
         type: 'SampleBlock',
         data: { text: 'Test text!' },
       },