@esheet/renderer 0.0.1

package/README.md

@@ -0,0 +1,212 @@
+# @esheet/renderer
+
+Read-only questionnaire form renderer for eSheet. Renders forms in fill-out mode with conditional visibility logic.
+
+## Features
+
+- ✅ Renders all 19 eSheet field types (reuses `@esheet/fields` components)
+- ✅ Conditional visibility enforcement (fields/sections hide based on logic rules)
+- ✅ Section nesting with recursive rendering
+- ✅ Initial response pre-fill support
+- ✅ YAML/JSON schema parsing with Zod validation
+- ✅ Ref API for collecting responses
+- ✅ TypeScript-first with full type safety
+
+## Installation
+
+```bash
+npm install @esheet/renderer @esheet/fields @esheet/core
+```
+
+Standalone and Blaze integrations now ship as separate packages:
+
+```bash
+npm install @esheet/renderer-standalone
+npm install @esheet/renderer-blaze
+```
+
+Migration for old subpath imports:
+
+- `@esheet/renderer/standalone` -> `@esheet/renderer-standalone`
+- `@esheet/renderer/blaze` -> `@esheet/renderer-blaze`
+
+## Usage
+
+### Basic Example
+
+```tsx
+import { EsheetRenderer } from '@esheet/renderer';
+import type { FormDefinition } from '@esheet/core';
+
+const myForm: FormDefinition = {
+  schemaType: 'mieforms-v1.0',
+  title: 'Patient Intake',
+  fields: [
+    {
+      id: 'name',
+      fieldType: 'text',
+      question: 'Full Name',
+      required: true,
+    },
+    {
+      id: 'age',
+      fieldType: 'text',
+      question: 'Age',
+    },
+  ],
+};
+
+function App() {
+  return (
+    <div className="app-container">
+      <EsheetRenderer formData={myForm} />
+    </div>
+  );
+}
+```
+
+### With Response Collection
+
+```tsx
+import { useRef } from 'react';
+import { EsheetRenderer, type EsheetRendererHandle } from '@esheet/renderer';
+
+function App() {
+  const rendererRef = useRef<EsheetRendererHandle>(null);
+
+  const handleSubmit = () => {
+    const responses = rendererRef.current?.getResponse();
+    console.log('Form responses:', responses);
+    // { name: '...', age: '...' }
+  };
+
+  return (
+    <>
+      <EsheetRenderer formData={myForm} ref={rendererRef} />
+      <button onClick={handleSubmit}>Submit</button>
+    </>
+  );
+}
+```
+
+### With Pre-filled Data
+
+```tsx
+<EsheetRenderer
+  formData={myForm}
+  initialResponses={{
+    name: 'John Doe',
+    age: '42',
+  }}
+/>
+```
+
+### With YAML/JSON String
+
+```tsx
+const yamlSchema = `
+schemaType: mieforms-v1.0
+title: Simple Form
+fields:
+  - id: q1
+    fieldType: text
+    question: Your name?
+`;
+
+<EsheetRenderer formData={yamlSchema} />;
+```
+
+## API
+
+### `<EsheetRenderer>`
+
+**Props:**
+
+- `formData: FormDefinition | string` - Form schema (object, JSON string, or YAML string)
+- `initialResponses?: FormResponse` - Pre-fill form with initial data
+- `className?: string` - Additional CSS classes for root container
+- `ref?: Ref<EsheetRendererHandle>` - Access ref API for collecting responses
+
+**Ref API:**
+
+```tsx
+interface EsheetRendererHandle {
+  getResponse: () => FormResponse;
+  getFormStore: () => FormStore;
+  getUIStore: () => UIStore;
+}
+```
+
+## Architecture
+
+EsheetRenderer is a thin wrapper that:
+
+1. Creates form and UI stores (vanilla Zustand)
+2. Parses and validates input (YAML/JSON → Zod schema check)
+3. Loads definition into store
+4. Sets preview mode (read-only, no editing UI)
+5. Iterates over visible fields via `RendererBody`
+6. Renders each field via `FieldNode` (uses `@esheet/fields` components)
+
+**Conditional Logic:**
+
+- Reuses `form.isVisible()`, `form.isEnabled()`, `form.isRequired()` from core
+- Sections auto-hide when all children are invisible
+- Field visibility updates reactively when responses change
+
+**Section Nesting:**
+
+- `FieldNode` recursively renders section children
+- Each depth level adds left border and padding
+- Respects visibility rules at every level
+
+## Example: Conditional Visibility
+
+```tsx
+const conditionalForm: FormDefinition = {
+  schemaType: 'mieforms-v1.0',
+  title: 'Conditional Form',
+  fields: [
+    {
+      id: 'hasAllergies',
+      fieldType: 'boolean',
+      question: 'Do you have any allergies?',
+    },
+    {
+      id: 'allergyList',
+      fieldType: 'longtext',
+      question: 'Please list your allergies',
+      visible: {
+        conditions: [
+          {
+            conditionType: 'comparison',
+            fieldId: 'hasAllergies',
+            operator: '==',
+            value: true,
+          },
+        ],
+        logicalOperator: 'AND',
+      },
+    },
+  ],
+};
+
+// "allergyList" only shows when "hasAllergies" is checked
+<EsheetRenderer formData={conditionalForm} />;
+```
+
+## CSS Architecture
+
+The renderer uses Tailwind CSS v4 with `ms:` prefix. CSS is compiled via `@tailwindcss/cli` and embedded into the JS bundle at build time — consumers never need to import a stylesheet. A scoped reset on `.esheet-renderer-root` prevents style leakage in either direction. Dark mode is supported via `.dark` class on the root.
+
+## License
+
+MIT
+
+## Building
+
+Run `nx build @esheet/renderer` to build the library.
+
+## Running unit tests
+
+Run `nx test @esheet/renderer` to execute the unit tests via [Vitest](https://vitest.dev/).

package/dist/index.d.ts

@@ -0,0 +1,97 @@
+import { default as default_2 } from 'react';
+import { FormDefinition } from '@esheet/core';
+import { FormResponse } from '@esheet/core';
+import { FormStore } from '@esheet/core';
+import { JSX } from 'react/jsx-runtime';
+import { UIStore } from '@esheet/core';
+import { ValidationError } from '@esheet/core';
+
+/**
+ * EsheetRenderer - Read-only questionnaire form renderer
+ *
+ * Renders a form in fill-out mode with conditional visibility logic.
+ * Reuses all field components from @esheet/fields.
+ *
+ * @example
+ * ```tsx
+ * const rendererRef = useRef<EsheetRendererHandle>(null);
+ *
+ * <EsheetRenderer
+ *   formData={myFormDefinition}
+ *   initialResponses={{ field1: 'answer' }}
+ *   ref={rendererRef}
+ * />
+ *
+ * // Later: get responses
+ * const responses = rendererRef.current?.getResponse();
+ * ```
+ */
+export declare const EsheetRenderer: default_2.ForwardRefExoticComponent<EsheetRendererProps & default_2.RefAttributes<EsheetRendererHandle>>;
+
+export declare interface EsheetRendererHandle {
+    /** Get current form responses */
+    getResponse: () => FormResponse;
+    /** Get form store instance */
+    getFormStore: () => FormStore;
+    /** Get UI store instance */
+    getUIStore: () => UIStore;
+    /** Get validated form responses (returns null if invalid) */
+    getValidResponse: () => {
+        response: FormResponse | null;
+        errors: ValidationError[];
+    };
+}
+
+export declare interface EsheetRendererProps {
+    /** Form definition (JSON object, JSON string, or YAML string) */
+    formData: FormDefinition | string;
+    /** Additional CSS classes for root container */
+    className?: string;
+    /** Initial form responses (pre-fill data) */
+    initialResponses?: FormResponse;
+}
+
+/**
+ * FieldNode - Renders a single field or section with recursive children
+ *
+ * Looks up the field component from the registry and passes field props.
+ * For sections, recursively renders visible children.
+ */
+export declare const FieldNode: default_2.NamedExoticComponent<FieldNodeProps>;
+
+declare interface FieldNodeProps {
+    id: string;
+    form: FormStore;
+    ui: UIStore;
+    /** Nesting depth for visual styling (default: 0) */
+    depth?: number;
+}
+
+/**
+ * RendererBody - Iterates over visible root fields and renders them
+ *
+ * Respects conditional visibility logic from form store.
+ * Only renders fields where isVisible() returns true.
+ * Sections recursively render their visible children.
+ */
+export declare function RendererBody({ form, ui }: RendererBodyProps): JSX.Element;
+
+declare interface RendererBodyProps {
+    form: FormStore;
+    ui: UIStore;
+}
+
+/**
+ * Initialize renderer with form definition
+ *
+ * - Parses YAML/JSON string input or accepts object directly
+ * - Validates against formDefinitionSchema
+ * - Loads definition into form store
+ * - Sets UI to preview mode
+ * - Applies initial responses if provided
+ */
+export declare function useRendererInit(form: FormStore, ui: UIStore, formData: FormDefinition | string, initialResponses?: FormResponse): void;
+
+export { ValidationError }
+
+export { }