@f1studio/form-spec 5.0.0-alpha.101

package/README.TS.md

@@ -0,0 +1,622 @@
+# FormSpec TypeScript API Documentation
+
+## 🚀 F# to TypeScript Interop for Form Specifications
+
+The FormSpec TypeScript API provides a type-safe, validated bridge between F# domain models and TypeScript applications. Built with Fable and Thoth.Json, it enables seamless form specification management across the F#/TypeScript boundary.
+
+## Installation
+
+```bash
+# From Verdaccio local registry
+npm install @f1studio/form-spec@5.0.0-alpha.13 --registry http://localhost:4873
+# or
+pnpm add @f1studio/form-spec@5.0.0-alpha.13 --registry http://localhost:4873
+# or
+yarn add @f1studio/form-spec@5.0.0-alpha.13 --registry http://localhost:4873
+```
+
+## Core Concepts
+
+### FableResult Type
+All validation functions return a `FableResult<T, E>` - a TypeScript-friendly tagged union:
+
+```typescript
+type FableResult<T, E> =
+  | { result: "fableOk"; Item: T }
+  | { result: "fableError"; Item: E }
+```
+
+This enables safe pattern matching in TypeScript:
+
+```typescript
+const result = validateFormSpec(unknownData);
+
+switch (result.result) {
+  case "fableOk":
+    console.log("Valid FormSpec:", result.Item);
+    break;
+  case "fableError":
+    console.error("Validation failed:", result.Item);
+    break;
+}
+```
+
+## Quick Start
+
+### 1. Validate Unknown Data
+
+```typescript
+import {
+  Api_validateFormSpec,
+  Api_validateAndConvertFormSpec
+} from '@f1studio/form-spec/Interop/FormSpec.Api';
+
+// Validate JSON data from an API
+async function loadFormSpec(url: string) {
+  const response = await fetch(url);
+  const data = await response.json();
+
+  // Validate to TypeScript-friendly types
+  const result = Api_validateFormSpec()(data);
+
+  if (result.result === "fableOk") {
+    return result.Item; // Fully typed FormSpecTS
+  } else {
+    throw new Error(result.Item);
+  }
+}
+
+// Validate AND convert to F# domain types
+const domainResult = Api_validateAndConvertFormSpec()(data);
+```
+
+### 2. Create Forms with Builders
+
+```typescript
+import {
+  Api_createFormSpec,
+  Api_createTextField,
+  Api_createCheckboxField,
+  Api_createDropdownField,
+  Api_createFieldOption,
+  Builders_formField,
+  Builders_formStep,
+  Builders_formSpec
+} from '@f1studio/form-spec/Interop/FormSpec.Api';
+
+// Create a new empty FormSpec
+const emptySpec = Api_createFormSpec();
+
+// Build a complete form specification
+function createPatientIntakeForm() {
+  // Create field options
+  const genderOptions = [
+    Api_createFieldOption("Male", "male"),
+    Api_createFieldOption("Female", "female"),
+    Api_createFieldOption("Other", "other")
+  ];
+
+  // Create fields
+  const nameField = Builders_formField(
+    "Patient Name",
+    Api_createTextField(null)
+  )
+    .WithOrder(1)
+    .AsOptional()
+    .Build();
+
+  const genderField = Builders_formField(
+    "Gender",
+    Api_createDropdownField(genderOptions)
+  )
+    .WithOrder(2)
+    .Build();
+
+  const consentField = Builders_formField(
+    "I consent to treatment",
+    Api_createCheckboxField(false, null)
+  )
+    .WithOrder(3)
+    .Build();
+
+  // Create form step
+  const demographicsStep = Builders_formStep("Demographics")
+    .WithOrder(1)
+    .AddField(nameField)
+    .AddField(genderField)
+    .AddField(consentField)
+    .Build();
+
+  // Create complete FormSpec
+  const formSpec = Builders_formSpec("Patient Intake Form")
+    .WithCode("INTAKE-001")
+    .WithAbstract("Standard patient intake and consent form")
+    .WithVersion("2.0.0")
+    .AddStep(demographicsStep)
+    .WithTags(["intake", "patient", "consent"])
+    .RequiresReview()
+    .Build();
+
+  return formSpec;
+}
+```
+
+### 3. Field Types
+
+The API supports all standard HTML input types plus specialized medical fields:
+
+```typescript
+import {
+  Api_createTextField,
+  Api_createTextArea,
+  Api_createEmailField,
+  Api_createPasswordField,
+  Api_createNumberField,
+  Api_createDateField,
+  Api_createTimeField,
+  Api_createCheckboxField,
+  Api_createRadioField,
+  Api_createDropdownField,
+  Api_createMultiChoiceField,
+  Api_createMessageField,
+  Types_MessageTypeTS
+} from '@f1studio/form-spec/Interop/FormSpec.Api';
+
+// Text inputs
+const textField = Api_createTextField("default value");
+const emailField = Api_createEmailField(null);
+const numberField = Api_createNumberField("42");
+
+// Date/Time inputs
+const dateField = Api_createDateField("2024-01-01");
+const timeField = Api_createTimeField("14:30");
+
+// Choice inputs
+const options = [
+  Api_createFieldOption("Option 1", "opt1"),
+  Api_createFieldOption("Option 2", "opt2")
+];
+const radioField = Api_createRadioField(options);
+const dropdownField = Api_createDropdownField(options);
+const multiChoiceField = Api_createMultiChoiceField(options);
+
+// Informational
+const messageField = Api_createMessageField(
+  "Important Notice",
+  "Please read carefully before proceeding",
+  Types_MessageTypeTS.Warning
+);
+```
+
+### 4. Field Dependencies
+
+Create conditional field visibility based on other field values:
+
+```typescript
+import {
+  Types_EvaluatorTS,
+  Api_createFieldKey
+} from '@f1studio/form-spec/Interop/FormSpec.Api';
+
+const hasAllergyField = Builders_formField(
+  "Do you have allergies?",
+  Api_createCheckboxField(false, null)
+)
+  .WithOrder(1)
+  .Build();
+
+const allergyDetailsField = Builders_formField(
+  "Please describe your allergies",
+  Api_createTextField(null)
+)
+  .WithOrder(2)
+  .WithDependency({
+    FieldKey: hasAllergyField.FieldKey,
+    FieldValue: "true",
+    Evaluator: Types_EvaluatorTS.Equals
+  })
+  .Build();
+```
+
+### 5. Serialization
+
+```typescript
+import {
+  Api_serializeFormSpec,
+  Api_deserializeFormSpec
+} from '@f1studio/form-spec/Interop/FormSpec.Api';
+
+// Convert FormSpec to JSON string
+const formSpec = createPatientIntakeForm();
+const json = Api_serializeFormSpec(formSpec);
+localStorage.setItem('formSpec', json);
+
+// Deserialize from JSON string
+const savedJson = localStorage.getItem('formSpec');
+const result = Api_deserializeFormSpec(savedJson);
+
+if (result.result === "fableOk") {
+  const restoredSpec = result.Item;
+  console.log("Loaded form:", restoredSpec.Title);
+}
+```
+
+### 6. Query and Utility Functions
+
+```typescript
+import {
+  Api_getFieldKeys,
+  Api_findFieldByKey,
+  Api_getFieldsByType,
+  Api_isValidFormSpec,
+  Api_getFormSpecSummary
+} from '@f1studio/form-spec/Interop/FormSpec.Api';
+
+const formSpec = createPatientIntakeForm();
+
+// Get all field keys
+const fieldKeys = Api_getFieldKeys(formSpec);
+console.log(`Form has ${fieldKeys.length} fields`);
+
+// Find a specific field
+const field = Api_findFieldByKey(formSpec, fieldKeys[0]);
+if (field) {
+  console.log("Found field:", field.Label);
+}
+
+// Get all text fields
+const textFields = Api_getFieldsByType(formSpec, "Text");
+console.log(`Found ${textFields.length} text fields`);
+
+// Validate structure
+if (Api_isValidFormSpec(formSpec)) {
+  console.log("FormSpec is valid");
+}
+
+// Get summary information
+const summary = Api_getFormSpecSummary(formSpec);
+console.log(summary);
+// Output: { Id, Title, Version, StepCount, FieldCount, RequiresReview, RequiresApproval }
+```
+
+### 7. Scoring System
+
+Add scoring ranges for assessments and evaluations:
+
+```typescript
+import {
+  Types_ScoreColorTS,
+  Api_createScoreRange
+} from '@f1studio/form-spec/Interop/FormSpec.Api';
+
+const scoreRanges = [
+  {
+    Id: "550e8400-e29b-41d4-a716-446655440001",
+    Min: 0,
+    Max: 10,
+    Label: "Low Risk",
+    Tag: Types_ScoreColorTS.Success
+  },
+  {
+    Id: "550e8400-e29b-41d4-a716-446655440002",
+    Min: 11,
+    Max: 20,
+    Label: "Medium Risk",
+    Tag: Types_ScoreColorTS.Warning
+  },
+  {
+    Id: "550e8400-e29b-41d4-a716-446655440003",
+    Min: 21,
+    Max: 30,
+    Label: "High Risk",
+    Tag: Types_ScoreColorTS.Danger
+  }
+];
+
+const formWithScore = Builders_formSpec("Risk Assessment")
+  .WithScore({
+    MaxScore: 30,
+    ScoreRanges: scoreRanges
+  })
+  .Build();
+```
+
+### 8. Matrix/Likert Scale Fields
+
+Create matrix questions for surveys and assessments:
+
+```typescript
+const satisfactionItems = [
+  Api_createFieldOption("Wait time", "wait_time"),
+  Api_createFieldOption("Staff friendliness", "staff"),
+  Api_createFieldOption("Cleanliness", "clean"),
+];
+
+const ratingScale = [
+  Api_createFieldOption("Very Dissatisfied", "1"),
+  Api_createFieldOption("Dissatisfied", "2"),
+  Api_createFieldOption("Neutral", "3"),
+  Api_createFieldOption("Satisfied", "4"),
+  Api_createFieldOption("Very Satisfied", "5"),
+];
+
+const matrixField = Builders_formField(
+  "Please rate your experience",
+  {
+    Type: "Matrix",
+    MatrixInfo: {
+      Items: satisfactionItems,
+      Options: ratingScale
+    },
+    // ... other properties set to null
+  }
+).Build();
+```
+
+## Advanced Usage
+
+### Type Guards and Validation
+
+```typescript
+import { FormSpecTS } from '@f1studio/form-spec/Interop/FormSpec.Api';
+
+// Type guard for FormSpec
+function isFormSpec(obj: any): obj is FormSpecTS {
+  const result = Api_validateFormSpec()(obj);
+  return result.result === "fableOk";
+}
+
+// Use in your code
+function processForm(data: unknown) {
+  if (isFormSpec(data)) {
+    // data is now typed as FormSpecTS
+    console.log(data.Title);
+    data.Steps.forEach(step => {
+      console.log(step.StepLabel);
+    });
+  }
+}
+```
+
+### Batch Validation
+
+```typescript
+import { Api_validateFormSpecs } from '@f1studio/form-spec/Interop/FormSpec.Api';
+
+async function validateMultipleForms(urls: string[]) {
+  const responses = await Promise.all(
+    urls.map(url => fetch(url).then(r => r.json()))
+  );
+
+  const result = Api_validateFormSpecs(responses);
+
+  if (result.result === "fableOk") {
+    return result.Item; // FormSpecTS[]
+  } else {
+    throw new Error(`Validation failed: ${result.Item}`);
+  }
+}
+```
+
+### Working with GUIDs
+
+All keys in the system use GUIDs wrapped in typed objects:
+
+```typescript
+import {
+  Api_createFieldKey,
+  Api_createStateKey,
+  Api_createTransitionKey
+} from '@f1studio/form-spec/Interop/FormSpec.Api';
+
+// Generate new keys
+const fieldKey = Api_createFieldKey();      // { Value: "uuid..." }
+const stateKey = Api_createStateKey();      // { Value: "uuid..." }
+const transitionKey = Api_createTransitionKey(); // { Value: "uuid..." }
+
+// Keys are automatically generated when using builders
+const field = Builders_formField("Name", Api_createTextField(null))
+  .Build();
+console.log(field.FieldKey.Value); // UUID string
+```
+
+## React Integration Example
+
+```typescript
+import React, { useState, useEffect } from 'react';
+import {
+  FormSpecTS,
+  Api_validateFormSpec,
+  Api_getFieldsByType
+} from '@f1studio/form-spec/Interop/FormSpec.Api';
+
+function FormRenderer({ formData }: { formData: unknown }) {
+  const [formSpec, setFormSpec] = useState<FormSpecTS | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    const result = Api_validateFormSpec()(formData);
+
+    if (result.result === "fableOk") {
+      setFormSpec(result.Item);
+      setError(null);
+    } else {
+      setError(result.Item);
+      setFormSpec(null);
+    }
+  }, [formData]);
+
+  if (error) {
+    return <div className="error">Invalid form: {error}</div>;
+  }
+
+  if (!formSpec) {
+    return <div>Loading...</div>;
+  }
+
+  return (
+    <div className="form-renderer">
+      <h1>{formSpec.Title}</h1>
+      <p>{formSpec.Abstract}</p>
+
+      {formSpec.Steps.map((step, stepIdx) => (
+        <div key={stepIdx} className="form-step">
+          <h2>{step.StepLabel}</h2>
+          {step.Fields.map((field, fieldIdx) => (
+            <div key={field.FieldKey.Value} className="form-field">
+              <label>{field.Label}</label>
+              {/* Render appropriate input based on field.FieldType.Type */}
+            </div>
+          ))}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+## Type Definitions
+
+### Core Types
+
+```typescript
+interface FormSpecTS {
+  Id: string;
+  Code?: string;
+  Title: string;
+  Abstract: string;
+  Version: string;
+  FormSpecVersion: string;
+  Steps: FormStepTS[];
+  CategoryTags: string[];
+  Score?: ScoreTS;
+  AssociatedCodes: string[];
+  RequiresReview: boolean;
+  RequiresReviewAndApproval: boolean;
+  ClinicalPathway?: ClinicalPathwaySpecTS;
+}
+
+interface FormStepTS {
+  StepOrder: number;
+  StepLabel: string;
+  Fields: FormFieldTS[];
+}
+
+interface FormFieldTS {
+  FieldOrder: number;
+  FieldKey: FieldKeyTS;
+  Label: string;
+  DependsOn?: DependsOnTS;
+  IsOptional: boolean;
+  IsDeprecated: boolean;
+  FieldType: FieldTypeTS;
+}
+
+interface FieldTypeTS {
+  Type: string; // "Text", "Checkbox", "Radio", etc.
+  TextInfo?: TextInfoTS;
+  BooleanInfo?: BooleanInfoTS;
+  SingleChoiceInfo?: SingleChoiceInfoTS;
+  MultiChoiceInfo?: MultiChoiceInfoTS;
+  MessageInfo?: MessageInfoTS;
+  MatrixInfo?: MatrixInfoTS;
+  SignatureInfo?: SignatureInfoTS;
+  PluginConfig?: PluginFieldConfigTS;
+}
+```
+
+## Best Practices
+
+1. **Always Validate External Data**: Never trust data from APIs, files, or user input without validation
+2. **Use Builders for Type Safety**: Builders ensure all required fields are set correctly
+3. **Handle Both Result Cases**: Always handle both `fableOk` and `fableError` cases
+4. **Leverage TypeScript Types**: Import type definitions for IntelliSense and compile-time checking
+5. **Store GUIDs as Strings**: When persisting to databases, use the `Value` property of key types
+
+## Migration from Legacy Forms
+
+If you have existing form data in a different format:
+
+```typescript
+function migrateOldForm(oldForm: any): FormSpecTS {
+  const builder = Builders_formSpec(oldForm.title || "Untitled Form")
+    .WithVersion(oldForm.version || "1.0.0");
+
+  // Map old fields to new structure
+  oldForm.questions?.forEach((q: any, idx: number) => {
+    const field = Builders_formField(
+      q.text,
+      mapOldFieldType(q.type, q.options)
+    )
+      .WithOrder(idx + 1)
+      .Build();
+
+    // Add to step...
+  });
+
+  return builder.Build();
+}
+
+function mapOldFieldType(type: string, options?: any[]): FieldTypeTS {
+  switch(type) {
+    case 'text': return Api_createTextField(null);
+    case 'select': return Api_createDropdownField(
+      options?.map(o => Api_createFieldOption(o.label, o.value)) || []
+    );
+    // ... map other types
+    default: return Api_createTextField(null);
+  }
+}
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue**: Validation fails with "Invalid GUID for FieldKey"
+**Solution**: Ensure you're using the key creation functions or builders which generate valid GUIDs
+
+**Issue**: TypeScript can't find types
+**Solution**: Import from the specific path: `@f1studio/form-spec/Interop/FormSpec.Api`
+
+**Issue**: FableResult is not being recognized in switch statements
+**Solution**: Check the discriminator property is exactly `result` (lowercase)
+
+## API Reference
+
+### Validation Functions
+- `Api_validateFormSpec(input: any): FableResult<FormSpecTS, string>` - Validate unknown data to FormSpecTS
+- `Api_validateAndConvertFormSpec(input: any): FableResult<FormSpec, string>` - Validate and convert to F# domain type
+- `Api_validateFormField(input: any): FableResult<FormFieldTS, string>` - Validate a single field
+- `Api_validateFormStep(input: any): FableResult<FormStepTS, string>` - Validate a form step
+- `Api_validateFieldType(input: any): FableResult<FieldTypeTS, string>` - Validate a field type
+
+### Builder Functions
+- `Api_createFormSpec(): FormSpecTS` - Create empty FormSpec
+- `Api_createFieldKey(): FieldKeyTS` - Generate new field key
+- `Api_createFieldOption(description: string, value: string): FieldOptionTS` - Create field option
+- `Api_createTextField(value: string | null): FieldTypeTS` - Create text field
+- `Api_createCheckboxField(defaultValue: boolean | null, selection: boolean | null): FieldTypeTS` - Create checkbox
+- `Api_createRadioField(options: FieldOptionTS[]): FieldTypeTS` - Create radio button group
+- `Api_createDropdownField(options: FieldOptionTS[]): FieldTypeTS` - Create dropdown
+
+### Serialization Functions
+- `Api_serializeFormSpec(spec: FormSpecTS): string` - Convert to JSON string
+- `Api_deserializeFormSpec(json: string): FableResult<FormSpecTS, string>` - Parse from JSON
+
+### Query Functions
+- `Api_getFieldKeys(spec: FormSpecTS): FieldKeyTS[]` - Get all field keys
+- `Api_findFieldByKey(spec: FormSpecTS, key: FieldKeyTS): FormFieldTS | undefined` - Find field by key
+- `Api_getFieldsByType(spec: FormSpecTS, type: string): FormFieldTS[]` - Get fields of specific type
+- `Api_isValidFormSpec(spec: FormSpecTS): boolean` - Check if spec is valid
+- `Api_getFormSpecSummary(spec: FormSpecTS): object` - Get spec summary
+
+## Support
+
+For issues, questions, or contributions:
+- GitHub: https://github.com/f1-studio/f1-monorepo
+- Documentation: https://f1studio.ai/docs
+
+## License
+
+MIT © F1 Studio

package/README.md

@@ -0,0 +1,85 @@
+# FormSpec – Build & Publish
+
+TypeScript package generated from F# via Fable. Runtime uses external `@fable-org/fable-library-js`.
+
+## Build & Publish (Unified Script)
+
+From `packages/core/form-spec`:
+
+```bash
+# Publish to Verdaccio (local testing)
+./build-and-publish.sh none --verdaccio
+
+# Publish to npm (public registry)
+./build-and-publish.sh none --npm
+
+# Publish to both registries
+./build-and-publish.sh none --both
+
+# Bump version and publish
+./build-and-publish.sh alpha --npm    # or beta, rc, release
+```
+
+The unified script handles:
+1. **Version bumping** (if requested)
+2. **.NET build** (NuGet package)
+3. **Fable compilation** (F# → TypeScript with `--fableLib` flag)
+4. **JS artifact creation** (TypeScript → JavaScript via SWC, type declarations)
+5. **NPM packaging** (creates `dist/package.json`)
+6. **Publishing to selected registry** (Verdaccio, npm, or both)
+7. **Verification** (checks package availability, JS files, exports)
+8. **Reporting** (version, install instructions, artifact list)
+
+**📖 For complete publishing documentation, see [docs/PUBLISHING.md](./docs/PUBLISHING.md)**
+
+Outputs to `dist/` with:
+- JS: `FormSpec.TS/Interop/*.js` (compiled JavaScript)
+- d.ts: `Interop/*.d.ts` (TypeScript definitions)
+- Exports map for all interop modules
+- Source maps and original TS under `dist/src/`
+
+Notes:
+- SWC is used for TS→JS; tsc declaration step may emit non-fatal TS errors from generated Thoth.Json TS (ignored in script).
+- The `--fableLib` flag externalizes fable-library dependencies (critical for packaging).
+
+## Install (consumer)
+
+### From Verdaccio (local testing)
+```bash
+npm install @f1studio/form-spec@<version> --registry http://localhost:4873
+pnpm add @f1studio/form-spec@<version> --registry http://localhost:4873
+bun add @f1studio/form-spec@<version> --registry http://localhost:4873
+```
+
+### From npm (public registry)
+```bash
+npm install @f1studio/form-spec@<version>
+pnpm add @f1studio/form-spec@<version>
+bun add @f1studio/form-spec@<version>
+```
+
+Entry points:
+- Main: `@f1studio/form-spec` → `FormSpec.TS/Interop/FormSpec.Api.Option.js` (main API)
+- Types: `@f1studio/form-spec/Interop/FormSpec.Api.Option` (d.ts + js)
+- Result: `@f1studio/form-spec/Interop/FormSpec.Api.Result` (d.ts + js)
+- TryCatch: `@f1studio/form-spec/Interop/FormSpec.Api.TryCatch` (d.ts + js)
+- Values: `@f1studio/form-spec/Interop/FormSpec.Values.Api.Option` (d.ts + js)
+
+## Quick JS usage
+
+```ts
+import { FormSpec_create, FormSpec_validate, FormSpec_tryFromJson } from '@f1studio/form-spec';
+import { FormSpec_Values_create } from '@f1studio/form-spec/Interop/FormSpec.Values.Api.Option';
+
+const form = FormSpec_create({
+  title: 'Example',
+  steps: [{ label: 'Step 1', fields: [] }],
+});
+
+const res = FormSpec_validate(form);
+if (!res.success) throw new Error(res.errors[0].message);
+```
+
+## Runtime dependency
+- `@fable-org/fable-library-js@1.11.0` (exact version; external; not bundled)
+