From 97a83b48a46cef16987760076173fdabc96908d3 Mon Sep 17 00:00:00 2001
From: Daniel Naab <dan@crushingpennies.com>
Date: Fri, 1 Nov 2024 12:47:10 -0500
Subject: [PATCH] Add initial documentation for the forms package and its
 patterns directory

---
 packages/forms/README.md              |  9 +++++
 packages/forms/src/patterns/README.md | 54 +++++++++++++++++++++++++++
 2 files changed, 63 insertions(+)
 create mode 100644 packages/forms/src/patterns/README.md

diff --git a/packages/forms/README.md b/packages/forms/README.md
index e69de29b..7173bc31 100644
--- a/packages/forms/README.md
+++ b/packages/forms/README.md
@@ -0,0 +1,9 @@
+# @atj/forms
+
+This library includes all of the core business logic of the Forms Platform.
+
+- [./src/services](./src/services): The public interface of the Forms Platform is implemented here
+- [./src/patterns](./src/patterns/README.md): Form building blocks, aka "patterns"
+- [./src/repository](./src/repository): Database routines
+- [./src/documents](./src/documents): Document ingest and creation
+- [./src/context](./src/context): Runtime contexts for the platform (testing, in-browser, server-side) are defined here
diff --git a/packages/forms/src/patterns/README.md b/packages/forms/src/patterns/README.md
new file mode 100644
index 00000000..56daa04b
--- /dev/null
+++ b/packages/forms/src/patterns/README.md
@@ -0,0 +1,54 @@
+# Forms Platform - Patterns
+
+Patterns are the Forms Platform's primary building block, a reusable module that may be configured via the no-code form builder to craft custom user experiences.
+
+Patterns are stored on the form `Blueprint`'s pattern attribute.
+
+## Pattern configuration
+
+Each pattern must define a configuration object, which provides the definition of its behavior.
+
+The `PatternConfig` type is defined in [../pattern.ts](../pattern.ts).
+
+## Data structure
+
+Patterns are defined by the generic `Pattern<C>` type in `pattern.ts`.
+
+```typescript
+export type Pattern<C = any> = {
+  type: string;   // A string identifier for the pattern type
+  id: PatternId;  // A unique identifier for the pattern instance
+  data: C;        // The configuration data specific to the pattern type
+};
+```
+
+Constructing patterns may be accomplished manually, or via `PatternBuilder` helper classes.
+
+For example, an input pattern may be defined directly:
+
+```typescript
+const input: InputPattern = {
+  type: 'input',
+  id: 'my-input',
+  data: {
+    label: 'My input',
+    initial: '',
+    required: true,
+    maxLength: 64
+  },
+}
+```
+
+```typescript
+const input = new InputPatternBuilder();
+const page1 = new Page({ title: 'Page 1', patterns: [input1.id] });
+const pageSet = new PageSet({ pages: [page1.id] }, 'page-set');
+const page2 = new Page({ title: 'Page 2', patterns: [input1.id] });
+pageSet.addPage(page2)
+
+// Construct the pattern objects
+page1.toPattern();
+page2.toPattern();
+pageSet.toPattern();
+```
+