@trunkjs/form 1.0.0

package/.ai-usage-info.md

@@ -0,0 +1,8 @@
+# @trunkjs/form
+
+> Die gepflegte Agent-Dokumentation liegt unter `skills/form-usage/SKILL.md`.
+
+`@trunkjs/form` verwendet `FormDataAccessor` aus `@trunkjs/browser-utils` und ergänzt `<tj-form>` für global
+registrierte Lifecycle-Callbacks. Verwende `data` zum Lesen/Schreiben, `entries` für direkten Elementzugriff und
+`formData` zum Versenden. Ergänze keine Remote-Wrapper oder Value-Plugins, solange ein konkreter Control-Typ sie nicht
+erfordert.

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## Unreleased
+
+- `tj-form` auf eine kleine objektwertige `value`- und `getElements()`-API reduziert
+- `FormDataAccessor` aus `@trunkjs/browser-utils` als gemeinsame DOM-Utility verwendet
+- Benannte verschachtelte Forms werden als eigener Objektwert statt als doppelte flache Controls gelesen
+- Bundle-übergreifende globale Preset-Registry für ein Default- oder benanntes Preset ergänzt
+- `EnterNextPlugin` für konfigurierbare Validierung und Fokuswechsel per Enter ergänzt
+- Native Form-, Fetch- und Validierungs-Lifecycle-Logik entfernt
+
+## 1.0.0
+
+- Initiale Grundstruktur für `@trunkjs/form`
+- Vite-Demo-Viewer-Setup ergänzt
+- `FormScope` mit Plugin-System ergänzt
+- Standard-Value-Plugins für `input`, `checkbox`, `radio`, `textarea` und `select` ergänzt

package/README.md

@@ -0,0 +1,98 @@
+# @trunkjs/form
+
+`<tj-form>` ist ein kleines Value-Element. Es sammelt die Werte benannter nativer oder kompatibler Custom Elements und
+liefert sie über `value` immer als Objekt zurück. Validierung, Requests und weitere Abläufe gehören nicht zum Kern.
+
+## Value und verschachtelte Forms
+
+```html
+<tj-form id="profile">
+  <input name="displayName" />
+  <tj-form name="address">
+    <input name="street" />
+    <input name="city" />
+  </tj-form>
+</tj-form>
+```
+
+```ts
+const form = document.querySelector<TjForm>('#profile')!;
+
+form.value = {
+  displayName: 'Erika',
+  address: { street: 'Musterweg 1', city: 'Berlin' },
+};
+
+console.log(form.value);
+// { displayName: 'Erika', address: { street: 'Musterweg 1', city: 'Berlin' } }
+```
+
+Ein Element wird berücksichtigt, wenn es einen nicht leeren `name` und eine les-/schreibbare `value`-Property besitzt.
+Damit funktionieren native Controls sowie kompatible Custom Elements wie `<nte-input>`. Ein benanntes Value-Element
+besitzt seinen gesamten Wert; seine Unterelemente werden vom übergeordneten `FormDataAccessor` nicht erneut gelesen.
+
+`entries` liefert dynamische Element-/Wert-Paare. `getElements()` gibt die aktuell sichtbaren Controls direkt zurück.
+
+## Globale Presets und Submit
+
+Presets werden ausschließlich programmatisch registriert und im Markup über das Attribut `preset` ausgewählt. Die
+Registry liegt auf `globalThis.__trunkjsFormRegistry`, sodass unabhängig gebaute Bundles dieselben Presets verwenden.
+
+`registerFormPreset(preset)` registriert das Standard-Preset. Es gilt automatisch, wenn ein `<tj-form>` kein
+`preset`-Attribut besitzt:
+
+```ts
+import { enterNextPlugin, registerFormPreset } from '@trunkjs/form';
+
+registerFormPreset({
+  value: { displayName: 'Erika' },
+  async onSubmit({ value, submitter, getElements }) {
+    getElements().forEach((element) => element.toggleAttribute('disabled', true));
+    await saveProfile(value, submitter);
+  },
+});
+```
+
+```html
+<tj-form>
+  <input name="displayName" required />
+  <button type="submit">Speichern</button>
+</tj-form>
+```
+
+Alternativ wird genau ein benanntes Preset ausgewählt:
+
+```ts
+registerFormPreset('profile', {
+  value: { displayName: 'Erika' },
+  plugins: [enterNextPlugin()],
+  onSubmit({ value }) {
+    return saveProfile(value);
+  },
+});
+```
+
+```html
+<tj-form preset="profile">
+  <!-- controls -->
+</tj-form>
+```
+
+Ein fehlendes oder leeres `preset`-Attribut wählt das Standard-Preset. Es werden nie mehrere Presets für dasselbe
+`<tj-form>` kombiniert.
+
+`<tj-form>` erzeugt bewusst kein natives `<form>`. Ein Klick auf einen zugehörigen Submit-Button oder
+`requestSubmit()` löst das abbrechbare Event `tj-form-submit` aus und ruft anschließend `onSubmit` auf. Buttons und
+Events verschachtelter Forms bleiben bei ihrer nächstgelegenen Form.
+
+`enterNextPlugin()` verhindert Submit per Enter, validiert das aktuelle Element und fokussiert bei Erfolg das nächste.
+Für Custom Controls kann `validate` oder `focus` konfiguriert werden.
+
+## Demo lokal starten
+
+```bash
+cd packages/form
+npx vite
+```
+
+Der Demo-Viewer ist anschließend unter `/__tdemo` verfügbar.

package/components/tj-form/tj-form.d.ts

@@ -0,0 +1,36 @@
+import { FormDataAccessorEntry } from '@trunkjs/browser-utils';
+import { TjFormContext, TjFormRegistry } from '../../lib/TjFormRegistry';
+export type TjFormSubmitDetail = TjFormContext;
+/** A small named value container for native and custom form controls. */
+export declare class TjForm extends HTMLElement {
+    registry: TjFormRegistry;
+    static get observedAttributes(): string[];
+    private readonly dataAccessor;
+    private unsubscribeRegistry;
+    private pluginCleanups;
+    private activePreset;
+    constructor(registry?: TjFormRegistry);
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(): void;
+    get name(): string;
+    set name(value: string);
+    get preset(): string;
+    set preset(value: string);
+    get value(): Record<string, unknown>;
+    set value(value: Record<string, unknown>);
+    get entries(): FormDataAccessorEntry[];
+    getElements(): HTMLElement[];
+    requestSubmit(submitter?: HTMLElement | null, sourceEvent?: Event | null): Promise<unknown>;
+    private readonly handleClick;
+    private isSubmitter;
+    private createContext;
+    private watchPreset;
+    private activatePreset;
+    private disconnectPlugins;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'tj-form': TjForm;
+    }
+}

package/index.d.ts

@@ -0,0 +1,3 @@
+export * from './components/tj-form/tj-form';
+export * from './lib/TjFormRegistry';
+export * from './plugins/EnterNextPlugin';

package/index.js

@@ -0,0 +1,179 @@
+import { FormDataAccessor as l } from "@trunkjs/browser-utils";
+const u = "default";
+class h {
+  constructor() {
+    this.presets = /* @__PURE__ */ new Map(), this.listeners = /* @__PURE__ */ new Map();
+  }
+  register(t, e) {
+    const s = this.normalizeName(t);
+    return this.presets.set(s, e), this.notify(s, e), this;
+  }
+  unregister(t) {
+    const e = t.trim(), s = this.presets.delete(e);
+    return s && this.notify(e, void 0), s;
+  }
+  get(t) {
+    return t ? this.presets.get(t.trim()) : void 0;
+  }
+  has(t) {
+    return this.presets.has(t.trim());
+  }
+  subscribe(t, e) {
+    const s = this.normalizeName(t), i = this.listeners.get(s) ?? /* @__PURE__ */ new Set();
+    return i.add(e), this.listeners.set(s, i), () => {
+      i.delete(e), i.size === 0 && this.listeners.delete(s);
+    };
+  }
+  normalizeName(t) {
+    const e = t.trim();
+    if (!e)
+      throw new Error("A form preset name must not be empty.");
+    return e;
+  }
+  notify(t, e) {
+    for (const s of this.listeners.get(t) ?? [])
+      s(e);
+  }
+}
+const c = globalThis.__trunkjsFormRegistry ?? (globalThis.__trunkjsFormRegistry = new h());
+function g(n, t) {
+  if (typeof n == "string") {
+    if (!t)
+      throw new Error("A named form preset requires a preset definition.");
+    return c.register(n, t);
+  }
+  return c.register(u, n);
+}
+class d extends HTMLElement {
+  constructor(t = c) {
+    super(), this.registry = t, this.dataAccessor = new l(this), this.unsubscribeRegistry = null, this.pluginCleanups = [], this.handleClick = (e) => {
+      const s = e.target instanceof Element ? e.target : null, i = s == null ? void 0 : s.closest('button, input, [type="submit"]');
+      !i || i.closest("tj-form") !== this || !this.isSubmitter(i) || (e.preventDefault(), this.requestSubmit(i, e));
+    };
+  }
+  static get observedAttributes() {
+    return ["preset"];
+  }
+  connectedCallback() {
+    this.addEventListener("click", this.handleClick), this.watchPreset();
+  }
+  disconnectedCallback() {
+    var t;
+    this.removeEventListener("click", this.handleClick), (t = this.unsubscribeRegistry) == null || t.call(this), this.unsubscribeRegistry = null, this.disconnectPlugins();
+  }
+  attributeChangedCallback() {
+    this.isConnected && this.watchPreset();
+  }
+  get name() {
+    return this.getAttribute("name") ?? "";
+  }
+  set name(t) {
+    t ? this.setAttribute("name", t) : this.removeAttribute("name");
+  }
+  get preset() {
+    var t;
+    return ((t = this.getAttribute("preset")) == null ? void 0 : t.trim()) || u;
+  }
+  set preset(t) {
+    t && t !== u ? this.setAttribute("preset", t) : this.removeAttribute("preset");
+  }
+  get value() {
+    return this.dataAccessor.data;
+  }
+  set value(t) {
+    this.dataAccessor.data = t;
+  }
+  get entries() {
+    return this.dataAccessor.entries;
+  }
+  getElements() {
+    return this.entries.map(({ element: t }) => t);
+  }
+  async requestSubmit(t = null, e = null) {
+    var r, o;
+    const s = this.createContext(t, e);
+    if (this.dispatchEvent(
+      new CustomEvent("tj-form-submit", {
+        bubbles: !0,
+        cancelable: !0,
+        detail: s
+      })
+    ))
+      return (o = (r = this.activePreset) == null ? void 0 : r.onSubmit) == null ? void 0 : o.call(r, s);
+  }
+  isSubmitter(t) {
+    var e;
+    return t instanceof HTMLButtonElement ? (t.getAttribute("type") ?? "submit").toLowerCase() === "submit" : t instanceof HTMLInputElement ? ["submit", "image"].includes(t.type.toLowerCase()) : ((e = t.getAttribute("type")) == null ? void 0 : e.toLowerCase()) === "submit";
+  }
+  createContext(t, e) {
+    return {
+      form: this,
+      submitter: t,
+      sourceEvent: e,
+      value: this.value,
+      getElements: () => this.getElements()
+    };
+  }
+  watchPreset() {
+    var t;
+    (t = this.unsubscribeRegistry) == null || t.call(this), this.unsubscribeRegistry = this.registry.subscribe(this.preset, (e) => this.activatePreset(e)), this.activatePreset(this.registry.get(this.preset));
+  }
+  activatePreset(t) {
+    if (this.disconnectPlugins(), this.activePreset = t, !!t) {
+      t.value && (this.value = t.value);
+      for (const e of t.plugins ?? []) {
+        const s = e.connect(this);
+        s && this.pluginCleanups.push(s);
+      }
+    }
+  }
+  disconnectPlugins() {
+    this.pluginCleanups.splice(0).forEach((t) => t());
+  }
+}
+typeof customElements < "u" && !customElements.get("tj-form") && customElements.define("tj-form", d);
+class m {
+  constructor(t = {}) {
+    this.options = t;
+  }
+  connect(t) {
+    const e = (s) => {
+      if (s.key !== "Enter" || s.defaultPrevented || s.isComposing)
+        return;
+      const i = s.target instanceof HTMLElement ? s.target : null;
+      if (!i || i.closest("tj-form") !== t || this.isMultiline(i))
+        return;
+      const r = t.getElements().filter((a) => !this.isDisabled(a)), o = r.find((a) => a === i || a.contains(i));
+      o && (s.preventDefault(), this.moveNext(t, o, r));
+    };
+    return t.addEventListener("keydown", e), () => t.removeEventListener("keydown", e);
+  }
+  async moveNext(t, e, s) {
+    if (!(this.options.validate ? await this.options.validate(e, t) : this.validate(e)))
+      return;
+    const r = s[s.indexOf(e) + 1];
+    r && (this.options.focus ?? ((o) => o.focus()))(r);
+  }
+  validate(t) {
+    const e = t;
+    return typeof e.reportValidity == "function" ? e.reportValidity() : typeof e.checkValidity == "function" ? e.checkValidity() : !t.matches(":invalid");
+  }
+  isDisabled(t) {
+    return t.hasAttribute("disabled") || t.matches(":disabled");
+  }
+  isMultiline(t) {
+    return t instanceof HTMLTextAreaElement || t.getAttribute("contenteditable") === "true";
+  }
+}
+function b(n = {}) {
+  return new m(n);
+}
+export {
+  u as DEFAULT_FORM_PRESET,
+  m as EnterNextPlugin,
+  d as TjForm,
+  h as TjFormRegistry,
+  b as enterNextPlugin,
+  g as registerFormPreset,
+  c as tjFormRegistry
+};

package/lib/TjFormRegistry.d.ts

@@ -0,0 +1,36 @@
+import { TjForm } from '../components/tj-form/tj-form';
+export interface TjFormContext {
+    readonly form: TjForm;
+    readonly submitter: HTMLElement | null;
+    readonly sourceEvent: Event | null;
+    readonly value: Record<string, unknown>;
+    getElements(): HTMLElement[];
+}
+export interface TjFormPlugin {
+    connect(form: TjForm): void | (() => void);
+}
+export interface TjFormPreset {
+    value?: Record<string, unknown>;
+    plugins?: readonly TjFormPlugin[];
+    onSubmit?: (context: TjFormContext) => unknown | Promise<unknown>;
+}
+export type TjFormRegistryListener = (preset: TjFormPreset | undefined) => void;
+export declare const DEFAULT_FORM_PRESET = "default";
+/** Stores reusable form values, submit callbacks, and opt-in plugins. */
+export declare class TjFormRegistry {
+    private readonly presets;
+    private readonly listeners;
+    register(name: string, preset: TjFormPreset): this;
+    unregister(name: string): boolean;
+    get(name: string | null | undefined): TjFormPreset | undefined;
+    has(name: string): boolean;
+    subscribe(name: string, listener: TjFormRegistryListener): () => void;
+    private normalizeName;
+    private notify;
+}
+declare global {
+    var __trunkjsFormRegistry: TjFormRegistry | undefined;
+}
+export declare const tjFormRegistry: TjFormRegistry;
+export declare function registerFormPreset(preset: TjFormPreset): TjFormRegistry;
+export declare function registerFormPreset(name: string, preset: TjFormPreset): TjFormRegistry;

package/package.json

@@ -0,0 +1,19 @@
+{
+    "name": "@trunkjs/form",
+    "version": "1.0.0",
+    "main": "./index.js",
+    "repository": {
+        "directory": "packages/form",
+        "type": "git",
+        "url": "git+https://github.com/trunkjs/trunkjs-monorepo.git"
+    },
+    "dependencies": {
+        "@trunkjs/browser-utils": "*"
+    },
+    "devDependencies": {
+        "@trunkjs/demo-viewer": "*",
+        "@trunkjs/vite-demo-viewer": "*"
+    },
+    "type": "module",
+    "types": "./index.d.ts"
+}

package/plugins/EnterNextPlugin.d.ts

@@ -0,0 +1,17 @@
+import { TjForm } from '../components/tj-form/tj-form';
+import { TjFormPlugin } from '../lib/TjFormRegistry';
+export interface EnterNextPluginOptions {
+    validate?: (element: HTMLElement, form: TjForm) => boolean | Promise<boolean>;
+    focus?: (element: HTMLElement) => void;
+}
+/** Moves Enter to the next named control after the current control validates. */
+export declare class EnterNextPlugin implements TjFormPlugin {
+    private readonly options;
+    constructor(options?: EnterNextPluginOptions);
+    connect(form: TjForm): () => void;
+    private moveNext;
+    private validate;
+    private isDisabled;
+    private isMultiline;
+}
+export declare function enterNextPlugin(options?: EnterNextPluginOptions): EnterNextPlugin;

package/skills/form-usage/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: form-usage
+description: Use @trunkjs/form TjForm and <tj-form> (programmatic API and element), TjFormRegistry and registerFormPreset() (programmatic APIs), and EnterNextPlugin and enterNextPlugin() (programmatic APIs).
+---
+
+# @trunkjs/form usage
+
+- `TjForm` / `<tj-form>` — Named object-valued container for native and custom controls, nested forms, element access,
+  and custom submit dispatch. See [README](../../README.md) and [demo](../../demo/basic.demo.ts).
+- `TjFormRegistry` / `registerFormPreset()` — Registers a globally shared default or named preset containing initial
+  values, a submit callback, and plugins for declarative `preset` selection. See [README](../../README.md).
+- `EnterNextPlugin` / `enterNextPlugin()` — Opt-in Enter validation and focus-next behavior. See
+  [demo](../../demo/basic.demo.ts).