undercity 1.0.0

package/actions/event/waitFor/action.json

@@ -0,0 +1,28 @@
+{
+  "id": "event.waitFor",
+  "category": "events",
+  "categoryLabel": "Events",
+  "icon": "broadcast",
+  "color": "var(--sol-cyan)",
+  "label": "Wait For Event",
+  "desc": "Pause flow until a named event fires (returns a Promise).",
+  "version": "1.0.0",
+  "params": [
+    {
+      "name": "event",
+      "label": "Event name",
+      "type": "text"
+    },
+    {
+      "name": "timeout",
+      "label": "Timeout (ms)",
+      "type": "number",
+      "default": 0
+    },
+    {
+      "name": "into",
+      "label": "Store in",
+      "type": "text"
+    }
+  ]
+}

package/actions/event/waitFor/action.test.js

@@ -0,0 +1,32 @@
+/**
+ * action.test.js — Unit tests for event.waitFor
+ * Wait For Event: Pause flow until a named event fires (returns a Promise).
+ *
+ * Each test receives (RT, sandbox) where:
+ *   RT      — the generated runtime module (Inventory, Navigator, Actions, ...)
+ *   sandbox — a <div> containing #pw-content, #pw-form, #pw-loading
+ */
+
+export const tests = [
+
+  {
+    name: 'event.waitFor — is exported from runtime',
+    run(RT) {
+      const ns = RT.Event ?? RT.event;
+      if (!ns) throw new Error('Namespace Event/event not found in runtime');
+      if (typeof ns.waitFor !== 'function') throw new Error('event.waitFor is not a function');
+    },
+  },
+
+  {
+    name: 'event.waitFor — can be called with default params',
+    async run(RT, sandbox) {
+      try {
+        await RT.Event.waitFor?.("", 0);
+      } catch (e) {
+        if (e instanceof TypeError) throw e;
+      }
+    },
+  },
+
+];

package/actions/forms/bindField/action.js

@@ -0,0 +1,27 @@
+/**
+ * form.bindField — runtime implementation
+ *
+ * Bidirectional live sync between a named DOM input and an inventory key.
+ * After this step runs:
+ *   - Field value is set from inventory immediately.
+ *   - Typing in the field writes to inventory in real time.
+ *   - External inventory changes (via Inventory.set) update the field.
+ *
+ * In runtime.js, this lives inside the Actions object:
+ *
+ *   bindField(fieldName, invKey) {
+ *     const el = document.querySelector(`[name="${fieldName}"]`);
+ *     if (!el) return;
+ *     const v = Inventory.get(invKey);
+ *     if (v !== null && v !== undefined) el.value = String(v);
+ *     const onInput = () => Inventory.set(invKey, el.value);
+ *     el.addEventListener('input', onInput);
+ *     const offBus = Bus.on('inventory:changed', ({ key }) => {
+ *       if ((key === invKey || key === '*') && el.ownerDocument.contains(el)) {
+ *         const nv = String(Inventory.get(invKey) ?? '');
+ *         if (el.value !== nv) el.value = nv;
+ *       }
+ *     });
+ *     _pwRegisterBinding(() => { el.removeEventListener('input', onInput); offBus(); });
+ *   },
+ */

package/actions/forms/bindField/action.json

@@ -0,0 +1,24 @@
+{
+  "id": "form.bindField",
+  "category": "forms",
+  "categoryLabel": "Forms",
+  "icon": "link-45deg",
+  "color": "var(--sol-yellow)",
+  "label": "Bind Field to Inventory",
+  "desc": "Synchronize a form field with an inventory key. Sets the field immediately when this step runs, then automatically keeps both in sync: typing in the field updates inventory, and inventory changes update the field.",
+  "version": "1.0.0",
+  "params": [
+    {
+      "name": "name",
+      "label": "Field name",
+      "type": "text",
+      "placeholder": "email"
+    },
+    {
+      "name": "key",
+      "label": "Inventory key",
+      "type": "inventory-key",
+      "placeholder": "userEmail"
+    }
+  ]
+}

package/actions/forms/bindField/action.test.js

@@ -0,0 +1,20 @@
+/**
+ * action.test.js — form.bindField
+ * Runs in the Undercity testbench (browser) via /api/actions/tests.
+ */
+import { describe, it, assert } from '/src/lib/testbench.js';
+
+describe('form.bindField', () => {
+  it('has correct metadata', async () => {
+    const res  = await fetch('/actions/forms/bindField/action.json');
+    const meta = await res.json();
+    assert.equal(meta.id,       'form.bindField');
+    assert.equal(meta.category, 'forms');
+    assert(Array.isArray(meta.params), 'params must be an array');
+    const keys = meta.params.map(p => p.name);
+    assert(keys.includes('name'),  'must have name param');
+    assert(keys.includes('key'),   'must have key param');
+    assert(meta.params.find(p => p.name === 'key')?.type === 'inventory-key',
+      'key param must be inventory-key type');
+  });
+});

package/actions/forms/check/action.json

@@ -0,0 +1,22 @@
+{
+  "id": "form.check",
+  "category": "forms",
+  "categoryLabel": "Forms",
+  "icon": "clipboard-check",
+  "color": "var(--sol-yellow)",
+  "label": "Get Checkbox / Radio",
+  "desc": "Read checked state of a checkbox or radio group.",
+  "version": "1.0.0",
+  "params": [
+    {
+      "name": "name",
+      "label": "Field name",
+      "type": "text"
+    },
+    {
+      "name": "into",
+      "label": "Into var",
+      "type": "text"
+    }
+  ]
+}

package/actions/forms/check/action.test.js

@@ -0,0 +1,32 @@
+/**
+ * action.test.js — Unit tests for form.check
+ * Get Checkbox / Radio: Read checked state of a checkbox or radio group.
+ *
+ * Each test receives (RT, sandbox) where:
+ *   RT      — the generated runtime module (Inventory, Navigator, Actions, ...)
+ *   sandbox — a <div> containing #pw-content, #pw-form, #pw-loading
+ */
+
+export const tests = [
+
+  {
+    name: 'form.check — is exported from runtime',
+    run(RT) {
+      const ns = RT.Form ?? RT.form;
+      if (!ns) throw new Error('Namespace Form/form not found in runtime');
+      if (typeof ns.check !== 'function') throw new Error('form.check is not a function');
+    },
+  },
+
+  {
+    name: 'form.check — can be called with default params',
+    async run(RT, sandbox) {
+      try {
+        await RT.Form.check?.("");
+      } catch (e) {
+        if (e instanceof TypeError) throw e;
+      }
+    },
+  },
+
+];

package/actions/forms/clearErrors/action.json

@@ -0,0 +1,11 @@
+{
+  "id": "form.clearErrors",
+  "category": "forms",
+  "categoryLabel": "Forms",
+  "icon": "clipboard-check",
+  "color": "var(--sol-yellow)",
+  "label": "Clear All Errors",
+  "desc": "Hide all [data-error] elements on the page.",
+  "version": "1.0.0",
+  "params": []
+}

package/actions/forms/clearErrors/action.test.js

@@ -0,0 +1,35 @@
+/**
+ * action.test.js — Unit tests for form.clearErrors
+ * Clear All Errors: Hide all [data-error] elements on the page.
+ *
+ * Each test receives (RT, sandbox) where:
+ *   RT      — the generated runtime module (Inventory, Navigator, Actions, ...)
+ *   sandbox — a <div> containing #pw-content, #pw-form, #pw-loading
+ */
+
+export const tests = [
+
+  {
+    name: 'form.clearErrors — is exported from runtime',
+    run(RT) {
+      const ns = RT.Form ?? RT.form;
+      if (!ns) throw new Error('Namespace Form/form not found in runtime');
+      if (typeof ns.clearErrors !== 'function') throw new Error('form.clearErrors is not a function');
+    },
+  },
+
+  {
+    name: 'form.clearErrors — can be called with no arguments',
+    async run(RT, sandbox) {
+      // Smoke test: calling the action should not throw
+      // (may produce DOM changes or be a no-op depending on state)
+      try {
+        await RT.Form.clearErrors?.();
+      } catch (e) {
+        // Some actions require specific DOM state — acceptable
+        if (e instanceof TypeError) throw e;
+      }
+    },
+  },
+
+];

package/actions/forms/clearField/action.json

@@ -0,0 +1,17 @@
+{
+  "id": "form.clearField",
+  "category": "forms",
+  "categoryLabel": "Forms",
+  "icon": "clipboard-check",
+  "color": "var(--sol-yellow)",
+  "label": "Clear Field",
+  "desc": "Reset a field to empty.",
+  "version": "1.0.0",
+  "params": [
+    {
+      "name": "name",
+      "label": "Field name",
+      "type": "text"
+    }
+  ]
+}

package/actions/forms/clearField/action.test.js

@@ -0,0 +1,32 @@
+/**
+ * action.test.js — Unit tests for form.clearField
+ * Clear Field: Reset a field to empty.
+ *
+ * Each test receives (RT, sandbox) where:
+ *   RT      — the generated runtime module (Inventory, Navigator, Actions, ...)
+ *   sandbox — a <div> containing #pw-content, #pw-form, #pw-loading
+ */
+
+export const tests = [
+
+  {
+    name: 'form.clearField — is exported from runtime',
+    run(RT) {
+      const ns = RT.Form ?? RT.form;
+      if (!ns) throw new Error('Namespace Form/form not found in runtime');
+      if (typeof ns.clearField !== 'function') throw new Error('form.clearField is not a function');
+    },
+  },
+
+  {
+    name: 'form.clearField — can be called with default params',
+    async run(RT, sandbox) {
+      try {
+        await RT.Form.clearField?.("");
+      } catch (e) {
+        if (e instanceof TypeError) throw e;
+      }
+    },
+  },
+
+];

package/actions/forms/getField/action.json

@@ -0,0 +1,24 @@
+{
+  "id": "form.getField",
+  "category": "forms",
+  "categoryLabel": "Forms",
+  "icon": "clipboard-check",
+  "color": "var(--sol-yellow)",
+  "label": "Get Field Value",
+  "desc": "Read a form field by name and optionally store in inventory.",
+  "version": "1.0.0",
+  "params": [
+    {
+      "name": "name",
+      "label": "Field name",
+      "type": "text",
+      "placeholder": "email"
+    },
+    {
+      "name": "into",
+      "label": "Into var",
+      "type": "text",
+      "placeholder": "email"
+    }
+  ]
+}

package/actions/forms/getField/action.test.js

@@ -0,0 +1,32 @@
+/**
+ * action.test.js — Unit tests for form.getField
+ * Get Field Value: Read a form field by name and optionally store in inventory.
+ *
+ * Each test receives (RT, sandbox) where:
+ *   RT      — the generated runtime module (Inventory, Navigator, Actions, ...)
+ *   sandbox — a <div> containing #pw-content, #pw-form, #pw-loading
+ */
+
+export const tests = [
+
+  {
+    name: 'form.getField — is exported from runtime',
+    run(RT) {
+      const ns = RT.Form ?? RT.form;
+      if (!ns) throw new Error('Namespace Form/form not found in runtime');
+      if (typeof ns.getField !== 'function') throw new Error('form.getField is not a function');
+    },
+  },
+
+  {
+    name: 'form.getField — can be called with default params',
+    async run(RT, sandbox) {
+      try {
+        await RT.Form.getField?.("email");
+      } catch (e) {
+        if (e instanceof TypeError) throw e;
+      }
+    },
+  },
+
+];

package/actions/forms/getRange/action.json

@@ -0,0 +1,22 @@
+{
+  "id": "form.getRange",
+  "category": "forms",
+  "categoryLabel": "Forms",
+  "icon": "clipboard-check",
+  "color": "var(--sol-yellow)",
+  "label": "Get Range Slider",
+  "desc": "Read the current value of a range input.",
+  "version": "1.0.0",
+  "params": [
+    {
+      "name": "name",
+      "label": "Field name",
+      "type": "text"
+    },
+    {
+      "name": "into",
+      "label": "Into var",
+      "type": "text"
+    }
+  ]
+}

package/actions/forms/getRange/action.test.js

@@ -0,0 +1,32 @@
+/**
+ * action.test.js — Unit tests for form.getRange
+ * Get Range Slider: Read the current value of a range input.
+ *
+ * Each test receives (RT, sandbox) where:
+ *   RT      — the generated runtime module (Inventory, Navigator, Actions, ...)
+ *   sandbox — a <div> containing #pw-content, #pw-form, #pw-loading
+ */
+
+export const tests = [
+
+  {
+    name: 'form.getRange — is exported from runtime',
+    run(RT) {
+      const ns = RT.Form ?? RT.form;
+      if (!ns) throw new Error('Namespace Form/form not found in runtime');
+      if (typeof ns.getRange !== 'function') throw new Error('form.getRange is not a function');
+    },
+  },
+
+  {
+    name: 'form.getRange — can be called with default params',
+    async run(RT, sandbox) {
+      try {
+        await RT.Form.getRange?.("");
+      } catch (e) {
+        if (e instanceof TypeError) throw e;
+      }
+    },
+  },
+
+];

package/actions/forms/getSelect/action.json

@@ -0,0 +1,22 @@
+{
+  "id": "form.getSelect",
+  "category": "forms",
+  "categoryLabel": "Forms",
+  "icon": "clipboard-check",
+  "color": "var(--sol-yellow)",
+  "label": "Get Select Value",
+  "desc": "Read the selected option value from a <select> element.",
+  "version": "1.0.0",
+  "params": [
+    {
+      "name": "name",
+      "label": "Field name",
+      "type": "text"
+    },
+    {
+      "name": "into",
+      "label": "Into var",
+      "type": "text"
+    }
+  ]
+}

package/actions/forms/getSelect/action.test.js

@@ -0,0 +1,32 @@
+/**
+ * action.test.js — Unit tests for form.getSelect
+ * Get Select Value: Read the selected option value from a <select> element.
+ *
+ * Each test receives (RT, sandbox) where:
+ *   RT      — the generated runtime module (Inventory, Navigator, Actions, ...)
+ *   sandbox — a <div> containing #pw-content, #pw-form, #pw-loading
+ */
+
+export const tests = [
+
+  {
+    name: 'form.getSelect — is exported from runtime',
+    run(RT) {
+      const ns = RT.Form ?? RT.form;
+      if (!ns) throw new Error('Namespace Form/form not found in runtime');
+      if (typeof ns.getSelect !== 'function') throw new Error('form.getSelect is not a function');
+    },
+  },
+
+  {
+    name: 'form.getSelect — can be called with default params',
+    async run(RT, sandbox) {
+      try {
+        await RT.Form.getSelect?.("");
+      } catch (e) {
+        if (e instanceof TypeError) throw e;
+      }
+    },
+  },
+
+];

package/actions/forms/index.js

@@ -0,0 +1,140 @@
+/**
+ * actions/forms/index.js — Forms category plugin
+ *
+ * Browser-side ES module. Loaded by actions/index.js and installed via App.use().
+ * Registers the Forms action category in the Savant, replacing the
+ * static definition that used to live in action-library.js.
+ *
+ * To add a new forms action:
+ *   1. Create actions/forms/<actionName>/ with action.json + action.js
+ *   2. Add the definition to FORMS_ACTIONS below
+ *   3. Add the runtime implementation to src/generator/runtime.js → Actions
+ */
+
+export const FormsPlugin = {
+  name: 'actions/forms',
+  install(app) {
+    app.registerActions('forms', FORMS_CATEGORY);
+  },
+};
+
+const FORMS_CATEGORY = {
+  label: 'Forms',
+  icon:  'clipboard-check',
+  color: 'var(--sol-yellow)',
+  actions: {
+
+    'form.getField': {
+      label:  'Get Field Value',
+      desc:   'Read the current value of a form field once when this step runs. Saves to inventory under the key you specify in "Save as".',
+      params: [
+        { name: 'name', label: 'Field name', type: 'text',  placeholder: 'email' },
+        { name: 'into', label: 'Save as',    type: 'text',  placeholder: 'email' },
+      ],
+    },
+
+    'form.setField': {
+      label:  'Set Field Value',
+      desc:   'Set a form field\'s value from an inventory key once when this step runs.',
+      params: [
+        { name: 'name',  label: 'Field name',   type: 'text',          placeholder: 'email' },
+        { name: 'value', label: 'Inventory key', type: 'inventory-key', placeholder: 'userEmail' },
+      ],
+    },
+
+    'form.bindField': {
+      label:  'Bind Field to Inventory',
+      desc:   'Synchronize a form field with an inventory key — live and automatic. Sets the field immediately, then keeps both in sync: typing updates inventory, inventory changes update the field.',
+      params: [
+        { name: 'name', label: 'Field name',   type: 'text',          placeholder: 'email' },
+        { name: 'key',  label: 'Inventory key', type: 'inventory-key', placeholder: 'userEmail' },
+      ],
+    },
+
+    'form.clearField': {
+      label:  'Clear Field',
+      desc:   'Reset a form field to empty.',
+      params: [
+        { name: 'name', label: 'Field name', type: 'text' },
+      ],
+    },
+
+    'form.serialize': {
+      label:  'Serialize Form',
+      desc:   'Collect all fields of a form into one inventory key as an object.',
+      params: [
+        { name: 'selector', label: 'Form selector', type: 'text', placeholder: '#my-form' },
+        { name: 'into',     label: 'Save as',       type: 'text', placeholder: 'formData' },
+      ],
+    },
+
+    'form.validate': {
+      label:  'Validate Form',
+      desc:   'Run HTML5 constraint validation. Marks fields is-valid/is-invalid. Saves true/false to inventory under "Valid? (save as)".',
+      params: [
+        { name: 'selector', label: 'Form selector',     type: 'text', placeholder: '#my-form' },
+        { name: 'into',     label: 'Valid? (save as)',   type: 'text', placeholder: 'isValid' },
+      ],
+    },
+
+    'form.setError': {
+      label:  'Set Field Error',
+      desc:   'Show a validation error message under a field using [data-error="name"].',
+      params: [
+        { name: 'name', label: 'Field name', type: 'text' },
+        { name: 'msg',  label: 'Message',    type: 'text' },
+      ],
+    },
+
+    'form.clearErrors': {
+      label:  'Clear All Errors',
+      desc:   'Hide all [data-error] elements and remove is-invalid class from all fields.',
+      params: [],
+    },
+
+    'form.submit': {
+      label:  'Submit Form',
+      desc:   'Programmatically trigger form submission.',
+      params: [
+        { name: 'selector', label: 'Form', type: 'text', placeholder: '#my-form' },
+      ],
+    },
+
+    'form.check': {
+      label:  'Get Checkbox / Radio',
+      desc:   'Read the checked state of a checkbox or radio group once when this step runs. Saves true/false to inventory under the key you specify in "Save as".',
+      params: [
+        { name: 'name', label: 'Field name', type: 'text' },
+        { name: 'into', label: 'Save as',    type: 'text' },
+      ],
+    },
+
+    'form.setCheck': {
+      label:  'Set Checkbox',
+      desc:   'Check or uncheck a checkbox by field name.',
+      params: [
+        { name: 'name',    label: 'Field name', type: 'text' },
+        { name: 'checked', label: 'Checked',    type: 'boolean', default: true },
+      ],
+    },
+
+    'form.getSelect': {
+      label:  'Get Select Value',
+      desc:   'Read the selected option from a <select> once when this step runs. Saves to inventory under the key you specify in "Save as".',
+      params: [
+        { name: 'name', label: 'Field name', type: 'text' },
+        { name: 'into', label: 'Save as',    type: 'text' },
+      ],
+    },
+
+    'form.getRange': {
+      label:  'Get Range Slider',
+      desc:   'Read the current value of a range input once when this step runs. Saves to inventory under the key you specify in "Save as".',
+      params: [
+        { name: 'name', label: 'Field name', type: 'text' },
+        { name: 'into', label: 'Save as',    type: 'text' },
+      ],
+    },
+
+  },
+};

package/actions/forms/serialize/action.json

@@ -0,0 +1,24 @@
+{
+  "id": "form.serialize",
+  "category": "forms",
+  "categoryLabel": "Forms",
+  "icon": "clipboard-check",
+  "color": "var(--sol-yellow)",
+  "label": "Serialize Form",
+  "desc": "Collect all fields of a form into an inventory key.",
+  "version": "1.0.0",
+  "params": [
+    {
+      "name": "selector",
+      "label": "Form selector",
+      "type": "text",
+      "placeholder": "#my-form"
+    },
+    {
+      "name": "into",
+      "label": "Into var",
+      "type": "text",
+      "placeholder": "formData"
+    }
+  ]
+}

package/actions/forms/serialize/action.test.js

@@ -0,0 +1,32 @@
+/**
+ * action.test.js — Unit tests for form.serialize
+ * Serialize Form: Collect all fields of a form into an inventory key.
+ *
+ * Each test receives (RT, sandbox) where:
+ *   RT      — the generated runtime module (Inventory, Navigator, Actions, ...)
+ *   sandbox — a <div> containing #pw-content, #pw-form, #pw-loading
+ */
+
+export const tests = [
+
+  {
+    name: 'form.serialize — is exported from runtime',
+    run(RT) {
+      const ns = RT.Form ?? RT.form;
+      if (!ns) throw new Error('Namespace Form/form not found in runtime');
+      if (typeof ns.serialize !== 'function') throw new Error('form.serialize is not a function');
+    },
+  },
+
+  {
+    name: 'form.serialize — can be called with default params',
+    async run(RT, sandbox) {
+      try {
+        await RT.Form.serialize?.("#my-form");
+      } catch (e) {
+        if (e instanceof TypeError) throw e;
+      }
+    },
+  },
+
+];