Populating Readme/License

.github/workflows/ci.yaml

@@ -21,4 +21,5 @@ jobs:
       - run: npm ci
       - run: npx eslint .
       - run: npx prettier . --check
+      - run: npx tsc --noEmit
       - run: npm test

LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2024 Carlos Rodriguez-Rosario
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,3 +1,53 @@
 # @usewaypoint/document
 
-A library to render waypoint-style documents
+This is the core library used to build the email messages at [Waypoint](https://www.usewaypoint.com). It is non-opinionated and light on dependencies so that it can be used to compose complex documents.
+
+> [!WARNING]
+> This library is still under development and the final interface is subject
+> to change
+
+## Installation
+
+**Installation with npm**
+
+```
+npm install --save @usewaypoint/document
+```
+
+## Usage
+
+The root of the library is the `DocumentBlocksDictionary` dictionary. This is a mapping of block names to an object with a zod schema and a corresponding React Component.
+
+```
+const dictionary = {
+  Alert: {
+    schema: z.object({
+      message: z.string(),
+    }),
+    Component: ({ message }: { message: string }) => {
+      return <div>{message.toUpperCase()}</div>
+    }
+  }
+}
+```
+
+This dictionary object is passed as an argument to the builder functions.
+
+### `buildBlockComponent`
+
+```
+const Block = buildBlockComponent(dictionary);
+
+<Block type="Alert" data={{message: 'Hello World' }} />
+```
+
+### `buildBlockConfigurationSchema`
+
+```
+const Schema = buildBlockConfigurationSchema(dictionary);
+
+const parsedData = Schema.safeParse({
+  type: 'Alert',
+  data: { message: 'Hello World' },
+});
+```

src/builders/buildBlockComponent.ts

@@ -7,7 +7,7 @@ import { BaseZodDictionary, BlockConfiguration, DocumentBlocksDictionary } from
  * @returns React component that can render a BlockConfiguration that is compatible with blocks
  */
 export default function buildBlockComponent<T extends BaseZodDictionary>(blocks: DocumentBlocksDictionary<T>) {
-  return function BlockComponent({ type, data }: BlockConfiguration<T>): React.ReactNode {
+  return function BlockComponent({ type, data }: BlockConfiguration<T>) {
     return React.createElement(blocks[type].Component, data);
   };
 }

src/builders/buildDocumentReader.ts

@@ -1,56 +1,48 @@
-import React, { createContext, useContext, useMemo } from 'react';
+import React, { createContext, useContext } from 'react';
 import { z } from 'zod';
 
 import { BaseZodDictionary, BlockNotFoundError, DocumentBlocksDictionary } from '../utils';
 
 import buildBlockComponent from './buildBlockComponent';
-import buildBlockConfigurationByIdSchema from './buildBlockConfigurationByIdSchema';
+import buildBlockConfigurationSchema from './buildBlockConfigurationSchema';
 
 /**
  * @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 DocumentProvider - Entry point to the DocumentReader
+ * @property BlockSchema - zod schema for a Document block
+ * @property DocumentSchema - zod schema compatible with the value that DocumentReaderProvider expects
+ * @property Block - React Component to render a block by type/data as defined by the DocumentSchema
  * @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);
+  const RawBlock = buildBlockComponent(blocks);
 
-  type TValue = z.infer<typeof schema>;
-  type TDocumentContextState = { value: TValue };
+  const BlockSchema = buildBlockConfigurationSchema(blocks);
+  const DocumentSchema = z.record(z.string(), BlockSchema);
 
-  const Context = createContext<TDocumentContextState>({ value: {} });
+  type TBlock = z.infer<typeof BlockSchema>;
+  type TDocument = Record<string, TBlock>;
 
-  type TProviderProps = {
-    value: z.infer<typeof schema>;
-    children?: Parameters<typeof Context.Provider>[0]['children'];
-  };
-
-  const useDocument = () => useContext(Context).value;
-  const useBlock = (id: string) => useDocument()[id];
+  const Context = createContext<TDocument>({});
+  const useDocument = () => useContext(Context);
 
   return {
+    BlockSchema,
+    DocumentSchema,
+    RawBlock,
     useDocument,
-    useBlock,
-    DocumentConfigurationSchema: schema,
+    DocumentProvider: Context.Provider,
     Block: ({ id }: { id: string }) => {
-      const block = useBlock(id);
+      const block = useDocument()[id];
       if (!block) {
         throw new BlockNotFoundError(id);
       }
-      const { type, data } = block;
-      return React.createElement(BlockComponent, { type, data });
-    },
-    DocumentReaderProvider: ({ value, children }: TProviderProps) => {
-      const v = useMemo(() => ({ value }), [value]);
-      return React.createElement(Context.Provider, { value: v, children });
+      return React.createElement(RawBlock, block);
     },
   };
 }

src/index.tsx

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