declarative-forms 2.0.0 → 2.1.0

package/README.md

@@ -1,102 +1,110 @@
 # declarative-forms
 
-Declarative forms for the web that make front-end development less front-end development.
+**Ask the user for an object, the way `prompt()` asks for a string.**
 
-Whenever you need input from a user, you describe the data you need and the rules around it. `declarative-forms` takes care of the front-end work to ask for that information: rendering the fields, wiring updates, loading async option sets, managing nested structures, handling modal stacks, tabs, and keeping the UI in sync as values change.
+Every other form library gives you a _component to mount_. This one gives you a
+_function to call_. There is no component, no form state, no mount point, and no
+place in your tree where the form has to live. You ask a question from wherever
+you happen to be standing in your code, and you get the answer back.
 
-📖 **[Read the documentation](https://wolfoo2931.github.io/declarative-forms/)**
+```ts
+import { ask } from 'declarative-forms';
+
+const release = await ask([
+  { name: 'title', displayName: 'Release title' },
+  { name: 'notes', kind: 'textarea', displayName: 'What changed' },
+  {
+    name: 'reviewers',
+    kind: 'select',
+    multiple: true,
+    displayName: 'Sign-off from',
+    options: () => fetchReviewers(),
+  },
+]);
 
-You do not have to build the front-end plumbing by hand just to collect structured input. Instead, you provide a schema-like description of the form and the library handles the rest.
+// { title: 'Sunrise 2.0', notes: '…', reviewers: ['Ada', 'Grace'] }
+```
 
-This is especially useful for complex forms, complex data structures, and workflows where the interface is mostly there to collect and validate user input rather than to render bespoke product UI.
+That is the whole integration. No `<Form>`, no `useForm`, no `onChange`, no
+`useState`, no layout, no `<div>`. The dialog draws itself, loads its own
+options, keeps every field in sync, and resolves.
 
-## What it is
+`ask` ships with the library —
+[what it takes and what it resolves with](https://wolfoo2931.github.io/declarative-forms/guide/asking-for-data#the-ask-function).
 
-At its core, `declarative-forms` is a framework-agnostic form engine.
+📖 **[Read the documentation](https://wolfoo2931.github.io/declarative-forms/)** ·
+🎛 **[Try the live demo](https://wolfoo2931.github.io/declarative-forms/#demo)**
 
-You define a form like this:
+## Why a call and not a component
 
-```ts
-import 'declarative-forms/styles.css';
-import { DeclarativeForm } from 'declarative-forms';
+`window.prompt()` is the one form API the browser gives you for free. You ask,
+the browser draws the dialog, you get the answer. No markup, no state, no
+layout, no lifecycle. Its only flaw is that it can ask for exactly one string.
 
-const form = new DeclarativeForm({
-  fields: [
-    { name: 'title', displayName: 'Title' },
-    {
-      name: 'language',
-      kind: 'select',
-      displayName: 'Language',
-      options: [
-        { value: 'en', label: 'English' },
-        { value: 'de', label: 'German' },
-      ],
-      defaultValue: 'en',
-    },
-    {
-      name: 'repo',
-      kind: 'select',
-      displayName: 'Repository',
-      reloadOnChangeOf: ['language'],
-      options: async ({ data }) => {
-        const lang = String(data['language'] ?? 'en');
-        return [{ value: `repo-${lang}`, label: `Repo (${lang})` }];
-      },
-    },
-  ],
-  onConfirm: (values) => console.log(values),
-  onCancel: () => {},
-});
+Everything the industry built to replace it went the other way — into the
+component tree:
 
-form.openInModal();
+```jsx
+// The component model: the form is a thing that lives somewhere.
+const { register, handleSubmit } = useForm();
+return (
+  <Modal open={open} onClose={() => setOpen(false)}>
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register('title')} />…
+    </form>
+  </Modal>
+);
 ```
 
-This is not a generated UI package or a full application framework. It is a runtime for declarative form behavior: you describe the data model and form rules, and it turns that into a working user flow with the UI concerns handled for you.
-
-## What makes it different
-
-The library is built around a few real strengths that show up in the codebase:
+Now the form has a _location_. It needs a parent, a piece of `open` state, a
+close handler, a submit handler, and a route from the answer back to the code
+that wanted it. For a product's signup page, that is fine — you were going to
+lay that page out anyway. For the two hundredth settings dialog in an internal
+tool, it is all overhead: you did not want a form, you wanted an answer.
 
-- Data-first form definitions instead of manual DOM creation
-- Cross-field reactivity via `reloadOnChangeOf`, `isActive`, `defaultValue`, and `onFormChange`
-- Async option loading and async button predicates
-- Built-in modal stack support for nested dialogs and wizards
-- Tabbed forms and array-of-record editing
-- Automatic handling of many front-end concerns: layout, state sync, stacking, dialog behavior, and reusable field logic
-- Zero runtime dependencies
-- Works in plain JavaScript or TypeScript, not just React/Vue/Svelte
+`declarative-forms` keeps `prompt()`'s shape and removes its one-string limit.
+The form is not a thing that lives somewhere. It is a question, asked and
+answered:
 
-The library also includes a few opinionated features that are especially useful for interactive tools:
-
-- computed fields that recalculate before confirmation
-- file fields that require a `persistFile` callback to convert a local file into a stored URL
-- custom render fields for embedding arbitrary DOM or widget logic inside a form
-- message, cards, and custom field types for dynamic UI without a separate component library
-
-## When to use this library
+```ts
+if (await confirmDetails()) { … }
 
-Use `declarative-forms` when the form is more like an application workflow than a static input form.
+const filters = await ask(filterFields);
+const entry   = await ask(entryFields, { confirmLabel: 'Add' });
+```
 
-It fits especially well for:
+## What that model gives you that a component cannot
 
-- admin panels and settings dialogs
-- configuration flows with conditions and dependencies
-- modal-based wizards with step logic
-- forms whose options depend on other fields
-- array/list editing with nested record forms
-- internal tools that need compact, data-driven UI without a UI framework dependency
+**Dialogs stack, and the inner one can read the outer ones.** Because a form is
+a call and not a node, opening one from inside another is just... calling it.
+The library keeps the stack, and any field in any dialog can read the values of
+every dialog beneath it through `stackData` — with no lifted state, no context
+provider, and no prop drilling, because there is no tree to lift through.
 
-## Core ideas in the codebase
+```ts
+{
+  name: 'recap',
+  kind: 'message',
+  // stackData[0] is the outermost dialog, still open behind this one.
+  message: ({ data, stackData }) =>
+    `Publishing ${stackData[0]['title']} ${data['when'] === 'now' ? 'now' : 'later'}.`,
+}
+```
 
-The library is centered on a few runtime concepts:
+**Lists of records are just the same call again.** An `array` field opens one
+dialog per entry, which is the natural shape for a record, and awkward to do
+inline.
 
-- `DeclarativeForm`: the main runtime that owns rendering, values, tabs, and modal behavior
-- `FieldDescriptor`: a plain object describing each field (`name`, `kind`, `options`, `tab`, `isActive`, etc.)
-- `FormValues`: the current data dictionary keyed by field name
-- `subscribeOnInput`: a way to observe form updates without wiring lots of DOM listeners
-- `ButtonDescriptor`: supports async enable/disable logic and “do not close” actions for wizards
+**Works anywhere, because it needs nothing.** Plain DOM plus one web component,
+no runtime dependencies. Call it from React, Vue, Svelte, Angular, an Electron
+main-window script, or a `<script type="module">` tag in a static page. It never
+touches your render tree, so there is nothing to integrate.
 
-This is why the project feels more like a small “form engine” than a typical form component library.
+**The descriptor is live, not static.** `options`, `isActive`, `defaultValue`,
+`placeholder`, `message`, `tab` and `compute` may each be a _function of the
+current values_, and `reloadOnChangeOf` declares which field depends on which.
+Options loaded from your API that change when another field changes are the
+core feature, not an extension point.
 
 ## Install
 
@@ -104,96 +112,92 @@ This is why the project feels more like a small “form engine” than a typical
 npm install declarative-forms
 ```
 
-And include the default CSS:
-
 ```ts
 import 'declarative-forms/styles.css';
 ```
 
-## Example: modal form
+That is the default look, and it follows the operating system's light/dark
+setting on its own. The v1 look ships as `declarative-forms/classic.css`.
+
+No build step is required — the ESM build loads directly in a `<script type="module">`.
+
+## The full API, if you want the object instead of the promise
+
+`ask` is a thin wrapper over the object underneath — a normal object you can
+hold on to, embed in a page instead of a dialog, subscribe to, and drive from
+code:
 
 ```ts
 import { DeclarativeForm } from 'declarative-forms';
 
 const form = new DeclarativeForm({
-  fields: [
-    { name: 'name', displayName: 'Name' },
-    {
-      name: 'role',
-      kind: 'select',
-      displayName: 'Role',
-      options: ['Admin', 'Editor', 'Viewer'],
-      defaultValue: 'Editor',
-    },
-  ],
-  onConfirm: (values) => {
-    console.log('submitted', values);
-  },
-  onCancel: () => {
-    console.log('cancelled');
-  },
+  fields: [...],
+  onConfirm: (values) => save(values),
+  onCancel: () => {},
 });
 
-form.openInModal();
-```
-
-## Example: reactive field logic
+form.openInModal();                       // …or:
+form.appendInElement(document.querySelector('#panel'));
 
-```ts
-const form = new DeclarativeForm({
-  fields: [
-    {
-      name: 'source',
-      kind: 'select',
-      displayName: 'Source',
-      options: ['GitHub', 'GitLab'],
-      defaultValue: 'GitHub',
-    },
-    {
-      name: 'token',
-      displayName: 'Token',
-      type: 'password',
-      isActive: ({ data }) => data['source'] === 'GitLab',
-    },
-    {
-      name: 'repo',
-      kind: 'select',
-      displayName: 'Repository',
-      reloadOnChangeOf: ['source'],
-      options: async ({ data }) => {
-        const source = String(data['source'] ?? 'GitHub');
-        return [{ value: `${source}-repo`, label: `${source} repo` }];
-      },
-    },
-  ],
-  onConfirm: (values) => console.log(values),
-});
+form.subscribeOnInput((values) => renderPreview(values));
+form.field('role')?.setValue('Admin');
 ```
 
-This is the sort of behavior the library is designed to make practical without building a lot of custom event wiring.
+See [the API reference](https://wolfoo2931.github.io/declarative-forms/reference/api).
 
-## Documentation
+## The ten field kinds
 
-Full documentation is at **[wolfoo2931.github.io/declarative-forms](https://wolfoo2931.github.io/declarative-forms/)**:
+`text` · `textarea` · `select` (single, multiple, async, searchable) ·
+`checkbox` · `message` · `file` · `computed` · `cards` · `custom` · `array`
 
-- [Getting started](https://wolfoo2931.github.io/declarative-forms/guide/getting-started)
-- [Field kinds](https://wolfoo2931.github.io/declarative-forms/guide/fields/) — the ten built-in kinds
-- [Reactivity](https://wolfoo2931.github.io/declarative-forms/guide/reactivity) — `isActive`, `reloadOnChangeOf`, computed fields
-- [API reference](https://wolfoo2931.github.io/declarative-forms/reference/api)
-- [Migrating from v1](https://wolfoo2931.github.io/declarative-forms/migration-v1)
+Full descriptions in **[Field kinds](https://wolfoo2931.github.io/declarative-forms/guide/fields/)**.
 
-## Status and limitations
+## Where it fits
 
-Worth knowing before you adopt it:
+Best in **settings and metadata dialogs for tool-like apps**: many optional
+fields, grouped into tabs, where the available choices depend on what the user
+already picked.
 
-- **Accessibility is a work in progress.** Labels, ids and focusable buttons are correct; dialog semantics, combobox ARIA and keyboard-reachable checkboxes are not there yet. The [accessibility page](https://wolfoo2931.github.io/declarative-forms/accessibility) lists every known gap.
-- **There is no validation framework.** `isActive` handles conditional fields and button predicates gate submission, but there is no rule engine or error-message system.
-- **The rendered DOM is a frozen contract.** Class names, ids and structure are stable across the v1 → v2 rewrite, so existing stylesheets keep working. See the [DOM contract](https://wolfoo2931.github.io/declarative-forms/dom-contract).
+- admin panels and settings dialogs
+- configuration flows with conditions and dependencies
+- modal wizards with several steps
+- forms whose options come from a server and depend on other fields
+- editing lists whose entries are records of their own
+- internal tools that need a data-driven UI without a framework dependency
+
+## Where it does not fit
+
+Plainly, so you can rule it out fast:
+
+- **It is not a general-purpose form library.** It renders one fixed layout. If
+  you need control over the markup — a product signup page, a marketing form —
+  use a state library and write the markup yourself.
+- **There is no validation framework.** No `required`, no rule objects, no
+  schema. There _are_ per-field error, warning and loading messages
+  (`setTooltipError` and friends), and `isValidRecord` and a button's `isActive`
+  gate submission — but you write each check yourself, and the message and the
+  gate are separate things you wire up separately. See
+  [Validation](https://wolfoo2931.github.io/declarative-forms/guide/validation).
+- **Accessibility is unfinished.** Labels, ids, focusable buttons and
+  keyboard-reachable checkboxes are correct. Dialog semantics, a focus trap, and
+  combobox ARIA are not. Read
+  [Accessibility](https://wolfoo2931.github.io/declarative-forms/accessibility)
+  in full before using it where conformance is required.
+- **The rendered DOM is a frozen contract.** Class names, ids and structure are
+  stable across the v1 → v2 rewrite, so existing stylesheets keep working. See
+  the [DOM contract](https://wolfoo2931.github.io/declarative-forms/dom-contract).
 
-## Summary
+## Documentation
 
-`declarative-forms` is best thought of as a declarative form runtime for web dialogs and tool-like workflows.
+- [Asking for data](https://wolfoo2931.github.io/declarative-forms/guide/asking-for-data) — the model, and `ask`
+- [Getting started](https://wolfoo2931.github.io/declarative-forms/guide/getting-started)
+- [Field kinds](https://wolfoo2931.github.io/declarative-forms/guide/fields/)
+- [Reactivity](https://wolfoo2931.github.io/declarative-forms/guide/reactivity) — `isActive`, `reloadOnChangeOf`, computed fields
+- [Validation](https://wolfoo2931.github.io/declarative-forms/guide/validation) — checks, tooltip messages, gating submit
+- [Modals & stacking](https://wolfoo2931.github.io/declarative-forms/guide/modals)
+- [API reference](https://wolfoo2931.github.io/declarative-forms/reference/api)
+- [Migrating from v1](https://wolfoo2931.github.io/declarative-forms/migration-v1)
 
-It is for the cases where the main job is not “build another UI component,” but “ask the user for structured data.” You define what needs to be collected, and the library handles the front-end work to gather it: field rendering, behavior, defaults, dynamic changes, nested records, modal stacking, and workflow handling.
+## License
 
-That is the core difference: instead of writing front-end code for every form interaction, you describe the data and rules, and the runtime takes care of the responsibilities that usually consume most of the work in form-heavy interfaces.
+MIT © Oliver Wolf

package/dist/index.cjs

@@ -195,6 +195,21 @@ var Field = class {
     );
     if (value !== void 0) this.setValue(value);
   }
+  /**
+   * Apply a plainly declared default value straight away.
+   *
+   * {@link applyDefaultValue} is awaited during initialisation, so a value it
+   * applies cannot be seen by the first layout pass. A default that is neither a
+   * function nor a promise needs no awaiting, so it is applied at build time and
+   * `isActive` predicates reading it are right from the first paint. The async
+   * pass runs afterwards regardless and simply sets the same value again.
+   */
+  applyStaticDefaultValue() {
+    const value = this.descriptor.defaultValue;
+    if (value === void 0 || typeof value === "function") return;
+    if (value instanceof Promise) return;
+    this.setValue(value);
+  }
   /**
    * Hook for setup that cannot happen in {@link build} — loading select
    * options, or a first render that needs the form context. May be synchronous.
@@ -2106,6 +2121,7 @@ var DeclarativeForm = class _DeclarativeForm {
       closeWith: (action) => this.close(action)
     });
     this.buildFields();
+    this.applyInitialLayout();
     this.ready = this.initialize();
   }
   // ------------------------------------------------------------------ setup
@@ -2127,12 +2143,40 @@ var DeclarativeForm = class _DeclarativeForm {
         );
       }
       const field = this.registry.create(descriptor, context);
+      field.applyStaticDefaultValue();
       this.fieldList.push(field);
       this.fieldsByName.set(descriptor.name, field);
       this.tooltips.register(descriptor.name, field.tooltipMarker);
       this.formElement.appendChild(field.wrapper);
     }
   }
+  /**
+   * Decide field visibility and build the tab strip synchronously, before the
+   * caller gets the form back.
+   *
+   * {@link initialize} is async — it awaits option loads and default values —
+   * but `openInModal()` normally runs in the same tick as the constructor.
+   * Without this pass the dialog paints every field of every tab, then collapses
+   * to the active tab once that first async update lands, which is a visible
+   * layout shift as soon as any field loads its options over the network.
+   *
+   * Only visibility is decided here: no `onFormChange`, no `onFormUpdate`, and
+   * the value model is left untouched, so the regular update cycle still sees
+   * the first real change and refreshes the buttons.
+   */
+  applyInitialLayout() {
+    const values = this.getValues();
+    const activeTabs = /* @__PURE__ */ new Set();
+    for (const field of this.fieldList) {
+      const active = field.descriptor.isActive?.({
+        ...this.contextFor(field.descriptor),
+        data: values
+      }) ?? true;
+      field.setActive(active);
+      if (active) for (const tab of field.tabs()) activeTabs.add(tab);
+    }
+    this.renderTabs(activeTabs);
+  }
   async initialize() {
     await Promise.allSettled(
       this.fieldList.map(
@@ -2470,6 +2514,44 @@ var DeclarativeForm = class _DeclarativeForm {
   }
 };
 
+// src/core/ask.ts
+function ask(fields, options = {}) {
+  return askWith(DeclarativeForm, fields, options);
+}
+function askWith(FormClass, fields, options = {}) {
+  const { modal, dismissable = true, buttons, ...formOptions } = options;
+  return new Promise((resolve) => {
+    let settled = false;
+    const settle = (values) => {
+      if (settled) return;
+      settled = true;
+      setTimeout(() => resolve(values), 0);
+    };
+    new FormClass({
+      ...formOptions,
+      fields,
+      buttons: buttons && settleOnClose(buttons, settle),
+      onConfirm: (values) => settle(values),
+      onCancel: dismissable ? () => settle(void 0) : void 0
+    }).openInModal(modal);
+  });
+}
+function settleOnClose(buttons, settle) {
+  return Object.fromEntries(
+    Object.entries(buttons).map(([label, descriptor]) => [
+      label,
+      descriptor.doNotCloseModal ? descriptor : {
+        ...descriptor,
+        action: async (values) => {
+          const result = await descriptor.action?.(values);
+          settle(values);
+          return result;
+        }
+      }
+    ])
+  );
+}
+
 exports.ArrayField = ArrayField;
 exports.ButtonBar = ButtonBar;
 exports.CardsField = CardsField;
@@ -2496,6 +2578,7 @@ exports.TextAreaField = TextAreaField;
 exports.TextField = TextField;
 exports.TooltipController = TooltipController;
 exports.UpdateScheduler = UpdateScheduler;
+exports.ask = ask;
 exports.deepEqual = deepEqual;
 exports.defaultFieldRegistry = defaultFieldRegistry;
 exports.defineDlSelect = defineDlSelect;