@rhi-zone/rainbow-ui 0.2.0-alpha.0

package/dist/elements.d.ts

@@ -0,0 +1,95 @@
+/**
+ * @rhi-zone/rainbow-ui/elements
+ *
+ * `defineElement` — wrap a Widget<T> in a native custom element.
+ *
+ * Bridges the HTML attribute/property system into rainbow signals so that
+ * `<my-card label="Alice" count="3">` works from plain HTML, and
+ * `el.label = "Bob"` works from JavaScript, both updating the widget reactively.
+ *
+ * Attributes are treated as a boundary adapter: HTML attributes are always
+ * `string | null`, and `AttrSchema<T>` maps each observed attribute to an
+ * `Optic<string | null, T[K]>` that parses (view) and serialises (review) it.
+ *
+ * Shadow DOM defaults to "open". Styles are applied via `adoptedStyleSheets`
+ * when shadow DOM is used.
+ */
+import type { Optic } from "@rhi-zone/rainbow";
+import type { AnyEl } from "./html.js";
+import type { Widget } from "./widget.js";
+/**
+ * Maps field names of `T` to optics that convert between `string | null`
+ * (raw HTML attribute) and `T[K]` (typed signal field).
+ *
+ * - `optic.view(raw)`    — parse attribute string into `T[K]`;
+ *                          `undefined` means use `defaults[K]`
+ * - `optic.review(v, _)` — serialise `T[K]` back to a string for reflection
+ */
+export type AttrSchema<T> = {
+    [K in keyof T]?: Optic<string | null, T[K]>;
+};
+/**
+ * Pass-through: `view` returns the raw string, or `undefined` when absent.
+ * `review` returns the value unchanged.
+ */
+export declare const attrString: Optic<string | null, string>;
+/**
+ * Numeric attribute: `view` converts with `Number()`; returns `undefined` on
+ * absent attribute or NaN. `review` serialises with `String()`.
+ */
+export declare const attrNumber: Optic<string | null, number>;
+/**
+ * Boolean attribute: absent → `undefined`; `"false"` or `"0"` → `false`;
+ * anything else → `true`. `review` serialises with `String()`.
+ */
+export declare const attrBoolean: Optic<string | null, boolean>;
+/**
+ * JSON attribute: `view` parses with `JSON.parse`; returns `undefined` on
+ * absent attribute or parse error. `review` serialises with `JSON.stringify`.
+ */
+export declare function attrJson<T>(): Optic<string | null, T>;
+/**
+ * Subset of `AttrSchema<T>` containing only the primitive fields of `T`
+ * (`string | number | boolean`).
+ */
+export type PrimitiveAttrSchema<T> = {
+    [K in keyof T as T[K] extends string | number | boolean ? K : never]: Optic<string | null, T[K]>;
+};
+/**
+ * Auto-derive an `AttrSchema` from `defaults` for all primitive fields
+ * (`string`, `number`, `boolean`). Complex fields are excluded.
+ *
+ * @example
+ * // Zero repetition for primitive-only T:
+ * attrs: attrsFrom(defaults)
+ *
+ * // Mixed case — spread and add complex fields:
+ * attrs: { ...attrsFrom(defaults), createdAt: attrJson<Date>() }
+ */
+export declare function attrsFrom<T extends object>(defaults: T): PrimitiveAttrSchema<T>;
+/**
+ * Register a custom element backed by a `Widget<T>`.
+ *
+ * The element's signal starts from `defaults`. Attributes listed in `attrs`
+ * are observed; each attribute change is parsed via the corresponding optic's
+ * `view` method and written into the signal. All fields of `T` get JS property
+ * accessors regardless of whether they appear in `attrs`.
+ *
+ * @example
+ * defineElement("score-card", {
+ *   widget: scoreCardWidget,
+ *   defaults: { label: "", score: 0 },
+ *   attrs: { label: attrString, score: attrNumber },
+ *   styles: `:host { display: block; font-family: sans-serif }`,
+ * })
+ *
+ * // In HTML:
+ * // <score-card label="Alice" score="42"></score-card>
+ */
+export declare function defineElement<T extends object>(tagName: string, config: {
+    widget: Widget<T, AnyEl>;
+    defaults: T;
+    attrs?: AttrSchema<T>;
+    shadow?: "open" | "closed" | false;
+    styles?: CSSStyleSheet | string | (CSSStyleSheet | string)[];
+}): void;

package/dist/elements.js

@@ -0,0 +1,118 @@
+var y = Object.defineProperty;
+var m = (t, e, n) => e in t ? y(t, e, { enumerable: !0, configurable: !0, writable: !0, value: n }) : t[e] = n;
+var a = (t, e, n) => m(t, typeof e != "symbol" ? e + "" : e, n);
+import { signal as v } from "@rhi-zone/rainbow";
+import { mount as S } from "./widget.js";
+const w = {
+  view(t) {
+    return t ?? void 0;
+  },
+  review(t) {
+    return t;
+  }
+}, k = {
+  view(t) {
+    if (t == null) return;
+    const e = Number(t);
+    return isNaN(e) ? void 0 : e;
+  },
+  review(t) {
+    return String(t);
+  }
+}, N = {
+  view(t) {
+    if (t != null)
+      return t !== "false" && t !== "0";
+  },
+  review(t) {
+    return String(t);
+  }
+};
+function A() {
+  return {
+    view(t) {
+      if (t != null)
+        try {
+          return JSON.parse(t);
+        } catch {
+          return;
+        }
+    },
+    review(t) {
+      return JSON.stringify(t);
+    }
+  };
+}
+function J(t) {
+  const e = {};
+  for (const n of Object.keys(t)) {
+    const s = typeof t[n];
+    s === "string" ? e[n] = w : s === "number" ? e[n] = k : s === "boolean" && (e[n] = N);
+  }
+  return e;
+}
+function h(t) {
+  if (typeof t == "string") {
+    const e = new CSSStyleSheet();
+    return e.replaceSync(t), e;
+  }
+  return t;
+}
+function x(t, e) {
+  const {
+    widget: n,
+    defaults: s,
+    attrs: u = {},
+    shadow: l = "open",
+    styles: i
+  } = e, g = Object.keys(u), c = i == null ? [] : Array.isArray(i) ? i.map(h) : [h(i)];
+  class f extends HTMLElement {
+    constructor() {
+      super(...arguments);
+      // Use underscore prefix rather than # so Object.defineProperty below can
+      // access instance state from outside the class body.
+      a(this, "_rb_signal", v({ ...s }));
+      a(this, "_rb_cleanup", null);
+    }
+    static get observedAttributes() {
+      return g;
+    }
+    connectedCallback() {
+      const r = l !== !1 ? this.shadowRoot ?? this.attachShadow({ mode: l }) : this;
+      l !== !1 && c.length > 0 && (r.adoptedStyleSheets = c), this._rb_cleanup = S(n, this._rb_signal, r);
+    }
+    disconnectedCallback() {
+      var r;
+      (r = this._rb_cleanup) == null || r.call(this), this._rb_cleanup = null;
+    }
+    attributeChangedCallback(r, O, _) {
+      const d = u[r];
+      if (d == null) return;
+      const p = d.view(_) ?? s[r];
+      this._rb_signal.set({ ...this._rb_signal.get(), [r]: p });
+    }
+  }
+  for (const o of Object.keys(s))
+    Object.defineProperty(f.prototype, o, {
+      get() {
+        return this._rb_signal.get()[o];
+      },
+      set(b) {
+        this._rb_signal.set({
+          ...this._rb_signal.get(),
+          [o]: b
+        });
+      },
+      configurable: !0,
+      enumerable: !0
+    });
+  customElements.define(t, f);
+}
+export {
+  N as attrBoolean,
+  A as attrJson,
+  k as attrNumber,
+  w as attrString,
+  J as attrsFrom,
+  x as defineElement
+};

package/dist/elements.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/form-state.d.ts

@@ -0,0 +1,173 @@
+/**
+ * @rhi-zone/rainbow-ui/form-state
+ *
+ * Form state as a data model. Rendering is entirely the app's responsibility.
+ *
+ * A form field is just a lens:
+ *
+ *   focus(inputWidget(), composeLens(field("values"), field("name")))
+ *   // Widget<FormState<Profile>, InputEl>
+ *
+ * The data model:
+ *
+ *   FormState<T> = { values, fieldErrors, formErrors, touched, submitting, submitCount }
+ *
+ * Validation adapters: FormValidator<T> is a plain function — bridge your
+ * schema library in the app layer, e.g. valibot:
+ *
+ *   const validate: FormValidator<T> = (values) => {
+ *     const r = v.safeParse(Schema, values)
+ *     if (r.success) return {}
+ *     const fieldErrors: FieldErrors<T> = {}
+ *     for (const issue of r.issues) {
+ *       const key = issue.path?.[0]?.key as keyof T & string
+ *       if (key) (fieldErrors[key] ??= []).push(issue.message)
+ *     }
+ *     return { fieldErrors }
+ *   }
+ */
+import type { Signal } from "@rhi-zone/rainbow";
+import type { Widget } from "./widget.js";
+import type { AnyEl } from "./html.js";
+/** Per-field error arrays keyed by field name. */
+export type FieldErrors<T> = Partial<Record<keyof T & string, string[]>>;
+/**
+ * Complete form state. All fields are readonly — mutations go through
+ * `Signal<FormState<T>>.set`.
+ */
+export type FormState<T> = {
+    readonly values: T;
+    /** Per-field validation errors. Empty array or undefined = no errors. */
+    readonly fieldErrors: FieldErrors<T>;
+    /** Cross-field or server-side errors, not attributed to a specific field. */
+    readonly formErrors: string[];
+    /**
+     * Which fields the user has interacted with. Gate error display on this
+     * using `subscribe` + `on(el, "focusout", ...)` in the app's field renderer.
+     */
+    readonly touched: Partial<Record<keyof T & string, boolean>>;
+    /** True while `handleSubmit`'s `onValid` promise is pending. */
+    readonly submitting: boolean;
+    /**
+     * Increments on each submit attempt. When > 0, show all field errors
+     * immediately (not just for touched fields).
+     */
+    readonly submitCount: number;
+};
+/**
+ * Form-level validator. Receives the full values object; returns any
+ * combination of field errors (keyed by field name) and form-level errors.
+ * Return `{}` or `undefined` when valid.
+ */
+export type FormValidator<T> = (values: T) => {
+    fieldErrors?: FieldErrors<T>;
+    formErrors?: string[];
+} | null | undefined;
+/** Construct initial `FormState<T>` from default values. */
+export declare function createFormState<T>(defaults: T): FormState<T>;
+/**
+ * True when the error for `key` should be shown to the user.
+ * Errors are suppressed until the field is touched OR a submit has been attempted.
+ */
+export declare function shouldShowError<T>(state: FormState<T>, key: keyof T & string): boolean;
+/**
+ * True when `state` has no field errors and no form-level errors.
+ * An empty array for `fieldErrors[key]` is treated as valid.
+ */
+export declare function isFormValid<T>(state: FormState<T>): boolean;
+/**
+ * True when `state.values` differs from `initial` (by JSON equality).
+ * Useful for enabling/disabling a "Save" button.
+ */
+export declare function isDirty<T>(initial: T, state: FormState<T>): boolean;
+/**
+ * Create a form controller backed by a `Signal<FormState<T>>`.
+ *
+ * A form field is a focused widget — no special combinator needed:
+ *
+ *   focus(inputWidget(), composeLens(field("values"), field("name")))
+ *
+ * The app owns error display and touched tracking:
+ *
+ *   subscribe(state, (s) => {
+ *     const show = (s.touched.name || s.submitCount > 0) && s.fieldErrors.name?.length
+ *     errorEl.style.display = show ? "" : "none"
+ *     errorEl.textContent = s.fieldErrors.name?.[0] ?? ""
+ *   })
+ *   on(inputEl, "focusout", () =>
+ *     state.set({ ...state.get(), touched: { ...state.get().touched, name: true } })
+ *   )
+ *
+ * @returns
+ *   `state`        — the reactive form signal; pass to `mount` and `focus`
+ *   `handleSubmit` — returns an event handler; attach to the form's submit event
+ *   `reset`        — restore all state to `defaults`
+ *   `setErrors`    — write server-returned errors back into the signal
+ */
+export declare function createForm<T extends object>(options: {
+    readonly defaults: T;
+    readonly validate?: FormValidator<T>;
+}): {
+    readonly state: Signal<FormState<T>>;
+    /**
+     * Bind a widget to a specific values field. Shorthand for
+     * `focus(widget, composeLens(field("values"), field(key)))`.
+     * `T` is captured by closure so no explicit type parameters are needed.
+     *
+     * @example
+     * const { state, bind } = createForm({ defaults: { name: "", email: "" } })
+     * mount(stack(
+     *   bind("name",  inputWidget({ placeholder: "Name" })),
+     *   bind("email", inputWidget({ placeholder: "Email" })),
+     * ), state, root)
+     */
+    readonly bind: <K extends keyof T & string, E extends AnyEl>(key: K, widget: Widget<T[K], E>) => Widget<FormState<T>, E>;
+    readonly handleSubmit: (onValid: (values: T) => Promise<void>) => (e?: Event) => void;
+    readonly reset: () => void;
+    readonly setErrors: (fieldErrors?: FieldErrors<T>, formErrors?: string[]) => void;
+    /**
+     * Replace the form's defaults and reset all state to a fresh `FormState`
+     * built from `newDefaults`. Use this when reusing the same form instance
+     * across different records (e.g. switching between contacts).
+     */
+    readonly reinitialize: (newDefaults: T) => void;
+    /**
+     * Build a fully-wired form field element: wrapper div → label → input (or
+     * textarea when `rows` is set) → error span.
+     *
+     * The input is bound to `state` via `bind`. A `focusout` listener marks the
+     * field as touched. The error span is shown when
+     * `(touched[key] || submitCount > 0) && fieldErrors[key]?.length > 0`.
+     *
+     * Must be called inside a widget rendering context (i.e. inside a `mount`
+     * call or another widget) so that the `subscribe` for error display is
+     * tracked for cleanup.
+     *
+     * @example
+     * mount(
+     *   stack(
+     *     (s) => form.field("name",  "Full name"),
+     *     (s) => form.field("email", "Email", { type: "email" }),
+     *     (s) => form.field("bio",   "Bio",   { rows: 4 }),
+     *   ),
+     *   form.state,
+     *   root,
+     * )
+     */
+    readonly field: (key: keyof T & string, label: string, options?: {
+        type?: "text" | "email" | "tel" | "password" | "number" | "search";
+        rows?: number;
+    }) => HTMLElement;
+    /**
+     * Return a `<div class="form-errors">` that is hidden when `state.formErrors`
+     * is empty, and shows all form-level errors (one `<p>` per error) when
+     * non-empty. Uses `subscribe` to stay reactive.
+     *
+     * Must be called inside a widget rendering context (i.e. inside a `mount`
+     * call or another widget) so that the subscription is tracked for cleanup.
+     *
+     * @example
+     * formEl.appendChild(editFormState.formErrors())
+     */
+    readonly formErrors: () => HTMLElement;
+};

package/dist/form-state.js

@@ -0,0 +1,98 @@
+import { signal as C, field as h } from "@rhi-zone/rainbow";
+import { subscribe as b, textareaWidget as y, inputWidget as w } from "./widget.js";
+function E(o) {
+  return {
+    values: { ...o },
+    fieldErrors: {},
+    formErrors: [],
+    touched: {},
+    submitting: !1,
+    submitCount: 0
+  };
+}
+function S(o, n) {
+  var d;
+  return (o.touched[n] === !0 || o.submitCount > 0) && (((d = o.fieldErrors[n]) == null ? void 0 : d.length) ?? 0) > 0;
+}
+function x(o) {
+  return o.formErrors.length > 0 ? !1 : Object.values(o.fieldErrors).every(
+    (n) => !n || n.length === 0
+  );
+}
+function W(o, n) {
+  return JSON.stringify(o) !== JSON.stringify(n.values);
+}
+function L(o) {
+  const { defaults: n, validate: d } = o, e = C(E(n)), f = (r, s) => (t) => s(t.focus(h("values")).focus(h(r))), p = (r) => {
+    if (!d) return { fieldErrors: {}, formErrors: [] };
+    const s = d(r) ?? {};
+    return {
+      fieldErrors: s.fieldErrors ?? {},
+      formErrors: s.formErrors ?? []
+    };
+  };
+  return { state: e, bind: f, handleSubmit: (r) => (s) => {
+    s == null || s.preventDefault();
+    const t = e.get(), l = Object.fromEntries(
+      Object.keys(t.values).map((u) => [u, !0])
+    ), { fieldErrors: i, formErrors: m } = p(t.values);
+    e.set({
+      ...t,
+      touched: { ...t.touched, ...l },
+      fieldErrors: i,
+      formErrors: m,
+      submitCount: t.submitCount + 1
+    }), x({ ...t, fieldErrors: i, formErrors: m }) && (e.set({ ...e.get(), submitting: !0, formErrors: [] }), r(e.get().values).then(
+      () => {
+        e.set({ ...e.get(), submitting: !1 });
+      },
+      (u) => {
+        const c = u instanceof Error ? u.message : String(u);
+        e.set({ ...e.get(), submitting: !1, formErrors: [c] });
+      }
+    ));
+  }, reset: () => {
+    e.set(E(n));
+  }, setErrors: (r, s) => {
+    e.set({
+      ...e.get(),
+      fieldErrors: r ?? {},
+      formErrors: s ?? []
+    });
+  }, reinitialize: (r) => {
+    e.set(E(r));
+  }, field: (r, s, t) => {
+    const l = document.createElement("div");
+    l.className = "form-field";
+    const i = document.createElement("label");
+    i.textContent = s, l.appendChild(i);
+    const u = ((t == null ? void 0 : t.rows) != null ? f(r, y({ rows: t.rows })) : f(r, w({ type: (t == null ? void 0 : t.type) ?? "text" })))(e);
+    l.appendChild(u.node), u.node.addEventListener("focusout", () => {
+      const a = e.get();
+      e.set({ ...a, touched: { ...a.touched, [r]: !0 } });
+    });
+    const c = document.createElement("span");
+    return c.className = "field-error", c.style.display = "none", l.appendChild(c), b(e, (a) => {
+      var g;
+      const v = S(a, r);
+      c.style.display = v ? "" : "none", c.textContent = ((g = a.fieldErrors[r]) == null ? void 0 : g[0]) ?? "";
+    }), l;
+  }, formErrors: () => {
+    const r = document.createElement("div");
+    return r.className = "form-errors", r.style.display = "none", b(e, (s) => {
+      const t = s.formErrors.length > 0;
+      if (r.style.display = t ? "" : "none", r.textContent = "", t)
+        for (const l of s.formErrors) {
+          const i = document.createElement("p");
+          i.textContent = l, r.appendChild(i);
+        }
+    }), r;
+  } };
+}
+export {
+  L as createForm,
+  E as createFormState,
+  W as isDirty,
+  x as isFormValid,
+  S as shouldShowError
+};

package/dist/form-state.test.d.ts

@@ -0,0 +1 @@
+export {};