declarative-forms 2.0.0-alpha.0

package/CHANGELOG.md

@@ -0,0 +1,115 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- A second stylesheet, `declarative-forms/theme.css`: a modern redesign with
+  automatic light and dark mode (`prefers-color-scheme`, overridable with
+  `data-dl-theme`), focus rings, fluid widths and a fuller token set. It is a
+  standalone alternative to `styles.css`, renders the identical DOM, and mirrors
+  the default stylesheet's selectors and specificity so existing overrides keep
+  winning. The default stylesheet is unchanged.
+- Under the modern theme, checkboxes are **keyboard-reachable**: the input is
+  styled directly with `appearance: none` rather than hidden behind a
+  pseudo-element. The default stylesheet keeps its existing behaviour.
+- Two wrapper classes for stacked dialogs: `dl-modal-stacked` on a dialog opened
+  on top of another, and `dl-modal-restored` on one revealed again after being
+  covered. Both mark a backdrop that is already on screen, so a theme can skip
+  its entrance animation. A stacked wrapper also carries `--dl-stack-depth`, the
+  number of dialogs underneath it.
+- Under the modern theme, a stacked dialog now **shows the stack**: the dialogs
+  below it, which are hidden, are drawn as card edges peeking out above the
+  dialog on top — one edge for a single dialog below, two for more. Sized with
+  `--dl-stack-peek` and `--dl-stack-inset`. The default stylesheet is unchanged.
+
+### Fixed
+
+- Opening or closing a stacked dialog no longer flashes the page under the
+  backdrop. The covered dialog was hidden in the same frame the new one started
+  fading in, leaving nothing over the page for the length of the animation; the
+  modern theme now skips that animation for stacked and restored dialogs. The
+  default stylesheet was never affected — it has no animations.
+
+## [2.0.0-alpha.0]
+
+Complete rewrite in TypeScript with an object-oriented design.
+
+**The JavaScript API is a clean break; the rendered DOM is deliberately
+unchanged.** Stylesheets and DOM-based end-to-end selectors written against v1
+keep working. See the [migration guide](https://wolfoo2931.github.io/declarative-forms/migration-v1).
+
+### Added
+
+- Discriminated `kind` on field descriptors, making them fully typable.
+- `form.field(name)` — a typed handle with `getValue`, `setValue`, `focus`,
+  `setLoading`, `element` and `wrapper`.
+- `FieldRegistry`, so applications can register their own field kinds.
+- Pluggable `TooltipProvider`, with a native zero-dependency default.
+- `html()` / `escapeHtml()` for explicit, opt-in markup.
+- `whenReady()`, `destroy()`, and an unsubscribe return from
+  `subscribeOnInput()`.
+- `dl-error` event on file-upload failure.
+- A `--dl-*` design-token layer and a dark theme.
+- Documentation site, and a live example playground under `examples/`.
+
+### Changed
+
+- Package renamed to `declarative-forms`; the export is now named
+  (`import { DeclarativeForm }`).
+- Constructor takes a single options object instead of five positional
+  arguments.
+- Descriptor callbacks receive one context object instead of per-callback
+  positional argument lists.
+- Renamed: `mapFiledsOnEdit` → `mapFieldsOnEdit`,
+  `onValuesCalculationFailedMessage` → `onOptionsError`,
+  `closeModalIfOpen` → `close`, `updateCalculatedFields` →
+  `updateComputedFields`, `mulitple-allowed` → `multiple`.
+- `descriptor.domElement` replaced by `form.field(name)`; the library no longer
+  mutates caller-supplied descriptors.
+- Dialog buttons are `<button type="button">` rather than `<div>`, keeping the
+  `.btn` class.
+- Content is rendered as text by default; markup requires `html()`.
+- `message` fields no longer appear in `getValues()`.
+- `buttons` and `onConfirm` are independent — a single-button map no longer
+  silently replaces `onConfirm`.
+- Test tooling replaced with Vitest, Playwright and tsup.
+
+### Removed
+
+- All runtime dependencies: `tippy.js`, `@popperjs/core`,
+  `@react-hookz/deep-equal`, and the unused `uuid`.
+- The v1 Karma/Jasmine/wdio/Browserify setup, which could not run — its
+  packages were referenced by scripts but absent from `devDependencies`.
+
+### Fixed
+
+- `<label for>` pointed at a field name that was never an element id, so no
+  field was ever labelled for assistive technology.
+- Checkbox ids collided between a parent form and its array sub-form.
+- `getValues()` could not represent `''`, `0` or `false`.
+- The internal promise list grew without bound and was never cleared.
+- Tabs and tooltips were resolved with `document.querySelector`, so two open
+  forms fought over each other's state.
+- A slow options load could overwrite a newer one; loads are now
+  generation-guarded.
+- Caller data was interpolated as HTML in 21 places.
+- Option values containing a quote threw a `DOMException`.
+- A keydown listener and a stylesheet were installed as import side effects,
+  breaking server-side rendering.
+- `class DlSelect extends HTMLElement` was evaluated at module load, so simply
+  importing the package threw `HTMLElement is not defined` in Node and broke
+  any server-rendered or prerendered app.
+- `classList.remove` was written as `Element.remove()`, deleting the confirm
+  button whenever it showed its loading state.
+- `<dl-option>` was never registered as a custom element.
+- Buttons flashed disabled on every keystroke, and a well-timed click could be
+  dropped.
+
+[Unreleased]: https://github.com/wolfoo2931/declarative-forms/compare/v2.0.0-alpha.0...HEAD
+[2.0.0-alpha.0]: https://github.com/wolfoo2931/declarative-forms/releases/tag/v2.0.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Wolf Oliver
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,199 @@
+# declarative-forms
+
+Declarative forms for the web that make front-end development less front-end development.
+
+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.
+
+📖 **[Read the documentation](https://wolfoo2931.github.io/declarative-forms/)**
+
+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.
+
+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.
+
+## What it is
+
+At its core, `declarative-forms` is a framework-agnostic form engine.
+
+You define a form like this:
+
+```ts
+import 'declarative-forms/styles.css';
+import { DeclarativeForm } from 'declarative-forms';
+
+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: () => {},
+});
+
+form.openInModal();
+```
+
+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:
+
+- 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
+
+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
+
+Use `declarative-forms` when the form is more like an application workflow than a static input form.
+
+It fits especially well for:
+
+- 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
+
+## Core ideas in the codebase
+
+The library is centered on a few runtime concepts:
+
+- `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
+
+This is why the project feels more like a small “form engine” than a typical form component library.
+
+## Install
+
+```bash
+npm install declarative-forms
+```
+
+And include the default CSS:
+
+```ts
+import 'declarative-forms/styles.css';
+```
+
+## Example: modal form
+
+```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');
+  },
+});
+
+form.openInModal();
+```
+
+## Example: reactive field logic
+
+```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),
+});
+```
+
+This is the sort of behavior the library is designed to make practical without building a lot of custom event wiring.
+
+## Documentation
+
+Full documentation is at **[wolfoo2931.github.io/declarative-forms](https://wolfoo2931.github.io/declarative-forms/)**:
+
+- [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)
+
+## Status and limitations
+
+Worth knowing before you adopt it:
+
+- **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).
+
+## Summary
+
+`declarative-forms` is best thought of as a declarative form runtime for web dialogs and tool-like workflows.
+
+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.
+
+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.