@formspec/constraints 0.1.0-alpha.10

package/README.md

@@ -0,0 +1,263 @@
+# @formspec/constraints
+
+Define and enforce constraints on which FormSpec DSL features are allowed in your project.
+
+## Overview
+
+The constraints package lets you restrict which parts of the FormSpec DSL can be used. This is useful for:
+
+- **Standardization**: Enforce consistent form patterns across a team
+- **Compatibility**: Restrict to features your renderer supports
+- **Simplicity**: Keep forms simple by disallowing complex nesting or conditionals
+- **Linting**: Catch constraint violations at development time via ESLint
+
+## Installation
+
+```bash
+npm install @formspec/constraints
+# or
+pnpm add @formspec/constraints
+```
+
+## Configuration
+
+Create a `.formspec.yml` file in your project root:
+
+```yaml
+constraints:
+  fieldTypes:
+    text: off # Allow text fields
+    number: off # Allow number fields
+    boolean: off # Allow boolean fields
+    staticEnum: off # Allow static enums
+    dynamicEnum: warn # Warn on dynamic enums
+    dynamicSchema: error # Disallow dynamic schemas
+    array: off # Allow arrays
+    object: off # Allow objects
+
+  layout:
+    group: off # Allow groups
+    conditionals: off # Allow when() conditionals
+    maxNestingDepth: 3 # Max nesting depth (0 = flat only)
+
+  fieldOptions:
+    label: off
+    placeholder: off
+    required: off
+    minValue: off
+    maxValue: off
+    minItems: off
+    maxItems: off
+```
+
+### Severity Levels
+
+Each constraint can be set to:
+
+| Severity  | Behavior                     |
+| --------- | ---------------------------- |
+| `"off"`   | Feature is allowed (default) |
+| `"warn"`  | Emit warning but allow       |
+| `"error"` | Disallow - fail validation   |
+
+## Constraint Categories
+
+### Field Types (`fieldTypes`)
+
+Control which DSL field builders are allowed:
+
+| Constraint      | DSL Function                                 |
+| --------------- | -------------------------------------------- |
+| `text`          | `field.text()`                               |
+| `number`        | `field.number()`                             |
+| `boolean`       | `field.boolean()`                            |
+| `staticEnum`    | `field.enum()`                               |
+| `dynamicEnum`   | `field.dynamicEnum()`                        |
+| `dynamicSchema` | `field.dynamicSchema()`                      |
+| `array`         | `field.array()`, `field.arrayWithConfig()`   |
+| `object`        | `field.object()`, `field.objectWithConfig()` |
+
+### Layout (`layout`)
+
+Control structure and nesting:
+
+| Constraint        | Description                             |
+| ----------------- | --------------------------------------- |
+| `group`           | `group()` visual grouping               |
+| `conditionals`    | `when()` conditional visibility         |
+| `maxNestingDepth` | Maximum depth for nested objects/arrays |
+
+### Field Options (`fieldOptions`)
+
+Control which field configuration options are allowed:
+
+| Constraint             | Description               |
+| ---------------------- | ------------------------- |
+| `label`                | Field label text          |
+| `placeholder`          | Input placeholder         |
+| `required`             | Required field validation |
+| `minValue`, `maxValue` | Number field constraints  |
+| `minItems`, `maxItems` | Array length constraints  |
+
+### UI Schema (`uiSchema`)
+
+Control JSON Forms-specific features:
+
+```yaml
+constraints:
+  uiSchema:
+    layouts:
+      VerticalLayout: off
+      HorizontalLayout: off
+      Group: off
+      Categorization: error # Disallow tabbed interfaces
+      Category: error
+    rules:
+      enabled: off
+      effects:
+        SHOW: off
+        HIDE: off
+        ENABLE: warn
+        DISABLE: warn
+```
+
+## Programmatic Usage
+
+### Loading Configuration
+
+```typescript
+import { loadConfig, mergeWithDefaults } from "@formspec/constraints";
+
+// Load from .formspec.yml (searches up directory tree)
+const config = await loadConfig();
+
+// Or load from specific path
+const config = await loadConfig("/path/to/.formspec.yml");
+
+// Merge with defaults to get fully resolved config
+const resolved = mergeWithDefaults(config.constraints);
+```
+
+### Validating Forms
+
+```typescript
+import { validateFormSpec } from "@formspec/constraints";
+import { formspec, field, when, is } from "@formspec/dsl";
+
+const form = formspec(
+  field.text("name"),
+  field.dynamicEnum("country", "fetch_countries"),
+  when(is("country", "US"), field.text("state"))
+);
+
+const result = validateFormSpec(form, resolved);
+
+if (!result.valid) {
+  for (const issue of result.issues) {
+    console.log(`${issue.severity}: ${issue.message}`);
+  }
+}
+```
+
+### Validation Result
+
+```typescript
+interface ValidationResult {
+  valid: boolean; // true if no errors (warnings OK)
+  issues: ValidationIssue[];
+}
+
+interface ValidationIssue {
+  code: string; // e.g., "FIELD_TYPE_NOT_ALLOWED"
+  message: string; // Human-readable description
+  severity: "error" | "warning";
+  category: "fieldTypes" | "layout" | "uiSchema" | "fieldOptions" | "controlOptions";
+  path?: string; // JSON pointer to issue location
+  fieldName?: string; // Affected field name
+  fieldType?: string; // Affected field type
+}
+```
+
+## ESLint Integration
+
+Use `@formspec/eslint-plugin` to catch constraint violations at development time:
+
+```javascript
+// eslint.config.js
+import formspec from "@formspec/eslint-plugin";
+
+export default [
+  {
+    plugins: { formspec },
+    rules: {
+      // Enforce allowed field types from .formspec.yml
+      "formspec/constraints-allowed-field-types": "error",
+      // Enforce allowed layouts from .formspec.yml
+      "formspec/constraints-allowed-layouts": "error",
+    },
+  },
+];
+```
+
+The ESLint rules automatically load constraints from your `.formspec.yml` file.
+
+## Example Configurations
+
+### Simple Forms Only
+
+Restrict to flat forms with basic field types:
+
+```yaml
+constraints:
+  fieldTypes:
+    array: error
+    object: error
+    dynamicEnum: error
+    dynamicSchema: error
+  layout:
+    conditionals: error
+    maxNestingDepth: 0
+```
+
+### JSON Forms Compatible
+
+Restrict to features supported by standard JSON Forms renderers:
+
+```yaml
+constraints:
+  fieldTypes:
+    dynamicSchema: error # Not supported by JSON Forms
+  uiSchema:
+    layouts:
+      Categorization: warn # May not be supported by all renderers
+```
+
+### Warn on Advanced Features
+
+Allow all features but warn on complex ones:
+
+```yaml
+constraints:
+  fieldTypes:
+    dynamicEnum: warn
+    dynamicSchema: warn
+    array: warn
+    object: warn
+  layout:
+    conditionals: warn
+    maxNestingDepth: 2
+```
+
+## JSON Schema
+
+A JSON Schema for `.formspec.yml` is available for editor autocompletion:
+
+```yaml
+# .formspec.yml
+# yaml-language-server: $schema=node_modules/@formspec/constraints/formspec.schema.json
+
+constraints:
+  fieldTypes:
+    text: off
+    # ... autocomplete available
+```

package/dist/__tests__/loader.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=loader.test.d.ts.map

package/dist/__tests__/loader.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/loader.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/loader.test.js

@@ -0,0 +1,133 @@
+import { describe, it, expect } from "vitest";
+import { loadConfigFromString, defineConstraints } from "../index.js";
+describe("loadConfigFromString", () => {
+    it("parses YAML with constraints section", () => {
+        const yaml = `
+constraints:
+  fieldTypes:
+    dynamicEnum: error
+    dynamicSchema: error
+  layout:
+    group: error
+    conditionals: warn
+`;
+        const config = loadConfigFromString(yaml);
+        expect(config.fieldTypes.dynamicEnum).toBe("error");
+        expect(config.fieldTypes.dynamicSchema).toBe("error");
+        expect(config.layout.group).toBe("error");
+        expect(config.layout.conditionals).toBe("warn");
+    });
+    it("applies defaults for missing values", () => {
+        const yaml = `
+constraints:
+  fieldTypes:
+    dynamicEnum: error
+`;
+        const config = loadConfigFromString(yaml);
+        expect(config.fieldTypes.dynamicEnum).toBe("error");
+        expect(config.fieldTypes.text).toBe("off");
+        expect(config.fieldTypes.number).toBe("off");
+        expect(config.layout.group).toBe("off");
+    });
+    it("handles empty YAML", () => {
+        const config = loadConfigFromString("");
+        // Should return all defaults
+        expect(config.fieldTypes.text).toBe("off");
+        expect(config.layout.group).toBe("off");
+    });
+    it("handles YAML with only comments", () => {
+        const yaml = `
+# This is a comment
+# Another comment
+`;
+        const config = loadConfigFromString(yaml);
+        expect(config.fieldTypes.text).toBe("off");
+    });
+    it("parses nested uiSchema constraints", () => {
+        const yaml = `
+constraints:
+  uiSchema:
+    layouts:
+      VerticalLayout: off
+      HorizontalLayout: error
+      Group: error
+    rules:
+      enabled: error
+`;
+        const config = loadConfigFromString(yaml);
+        expect(config.uiSchema.layouts.VerticalLayout).toBe("off");
+        expect(config.uiSchema.layouts.HorizontalLayout).toBe("error");
+        expect(config.uiSchema.layouts.Group).toBe("error");
+        expect(config.uiSchema.rules.enabled).toBe("error");
+    });
+    it("parses fieldOptions constraints", () => {
+        const yaml = `
+constraints:
+  fieldOptions:
+    minItems: error
+    maxItems: error
+    placeholder: warn
+`;
+        const config = loadConfigFromString(yaml);
+        expect(config.fieldOptions.minItems).toBe("error");
+        expect(config.fieldOptions.maxItems).toBe("error");
+        expect(config.fieldOptions.placeholder).toBe("warn");
+        expect(config.fieldOptions.label).toBe("off");
+    });
+    it("parses maxNestingDepth as number", () => {
+        const yaml = `
+constraints:
+  layout:
+    maxNestingDepth: 2
+`;
+        const config = loadConfigFromString(yaml);
+        expect(config.layout.maxNestingDepth).toBe(2);
+    });
+    it("throws on invalid YAML structure", () => {
+        const yaml = `
+- this
+- is
+- an array
+`;
+        expect(() => loadConfigFromString(yaml)).toThrow();
+    });
+});
+describe("defineConstraints", () => {
+    it("creates config from object literal", () => {
+        const config = defineConstraints({
+            fieldTypes: {
+                dynamicEnum: "error",
+                array: "warn",
+            },
+            layout: {
+                group: "error",
+                maxNestingDepth: 1,
+            },
+        });
+        expect(config.fieldTypes.dynamicEnum).toBe("error");
+        expect(config.fieldTypes.array).toBe("warn");
+        expect(config.fieldTypes.text).toBe("off"); // default
+        expect(config.layout.group).toBe("error");
+        expect(config.layout.maxNestingDepth).toBe(1);
+    });
+    it("handles empty config", () => {
+        const config = defineConstraints({});
+        // All defaults
+        expect(config.fieldTypes.text).toBe("off");
+        expect(config.layout.group).toBe("off");
+        expect(config.uiSchema.layouts.VerticalLayout).toBe("off");
+    });
+    it("handles partial nested config", () => {
+        const config = defineConstraints({
+            uiSchema: {
+                rules: {
+                    enabled: "error",
+                },
+            },
+        });
+        expect(config.uiSchema.rules.enabled).toBe("error");
+        expect(config.uiSchema.rules.effects.SHOW).toBe("off"); // default
+        expect(config.uiSchema.layouts.VerticalLayout).toBe("off"); // default
+    });
+});
+//# sourceMappingURL=loader.test.js.map

package/dist/__tests__/loader.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.test.js","sourceRoot":"","sources":["../../src/__tests__/loader.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/validators.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=validators.test.d.ts.map

package/dist/__tests__/validators.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/validators.test.ts"],"names":[],"mappings":""}