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!' },
  },