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

package/dist/keybinds.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @rhi-zone/rainbow-ui/keybinds
+ *
+ * Reactive integration between the `keybinds` library and rainbow signals.
+ *
+ * `keybindsContext` wires a `Signal<S>` into a keybinds registration so that
+ * context is always evaluated from current signal state on each keypress.
+ *
+ * `bindingsStoreSignal` wraps a `BindingsStore` (from keybinds) in a
+ * `ReadonlySignal` so that user-customized bindings are reactive.
+ */
+import type { Signal, ReadonlySignal } from "@rhi-zone/rainbow";
+/** Minimal shape of a keybinds Command object. */
+export interface Command {
+    id: string;
+    label: string;
+    description?: string;
+    category?: string;
+    keys?: string[];
+    mouse?: string[];
+    when?: (ctx: Record<string, unknown>) => boolean;
+    execute: (ctx: Record<string, unknown>, event?: Event) => unknown;
+    hidden?: boolean;
+    captureInput?: boolean;
+    menu?: string | string[];
+}
+/** Options accepted by the keybinds() function. */
+export interface KeybindsOptions {
+    target?: EventTarget;
+    onExecute?: (cmd: Command, ctx: Record<string, unknown>) => void;
+}
+/**
+ * The `keybinds` function signature from the keybinds library.
+ * Accept this as a parameter so callers supply the concrete import —
+ * no hard dependency on the `keybinds` package from `@rhi-zone/rainbow-ui`.
+ */
+export type KeybindsFn = (commands: Command[], getContext: () => Record<string, unknown>, options?: KeybindsOptions) => () => void;
+/** The BindingsStore class shape from keybinds (extends EventTarget). */
+export interface BindingsStore<T = Record<string, unknown>> extends EventTarget {
+    schema: T;
+    storageKey: string;
+    overrides: Record<string, unknown>;
+    bindings: T;
+    get(): T;
+    getOverrides(): Record<string, unknown>;
+    save(newOverrides: Record<string, unknown>): void;
+}
+/**
+ * Register keybindings whose context is derived from a reactive signal.
+ *
+ * The `getContext` callback is invoked on each keypress, reading current
+ * signal state at that moment. No re-registration is needed when state
+ * changes — the closure is inherently fresh.
+ *
+ * The subscription to `state` is established so that callers can extend
+ * this helper without forking it (e.g. to rebuild command lists reactively).
+ * It also serves as a documented contract: this integration owns the signal.
+ *
+ * Pass the `keybinds` function imported from the `keybinds` package as the
+ * first argument. This avoids a hard package dependency on `keybinds` from
+ * `@rhi-zone/rainbow-ui` — callers bring their own import.
+ *
+ * @example
+ * ```ts
+ * import { keybinds } from "keybinds"
+ * import { keybindsContext } from "@rhi-zone/rainbow-ui"
+ *
+ * const dispose = keybindsContext(keybinds, commands, appState, s => ({
+ *   isAdmin: s.role === "admin",
+ *   hasSelection: s.selection.length > 0,
+ * }))
+ * ```
+ *
+ * @param keybindsFn   - The `keybinds` function from the keybinds library.
+ * @param commands     - Array of command definitions.
+ * @param state        - Signal whose value supplies the keybind context.
+ * @param buildContext - Pure function mapping signal state to a context object.
+ * @param options      - Optional keybinds options (target element, onExecute hook).
+ * @returns A dispose function that removes event listeners and unsubscribes
+ *          from the signal. Call it when the component or scope unmounts.
+ */
+export declare function keybindsContext<S>(keybindsFn: KeybindsFn, commands: Command[], state: Signal<S> | ReadonlySignal<S>, buildContext: (s: S) => Record<string, unknown>, options?: KeybindsOptions): () => void;
+/**
+ * Wrap a `BindingsStore` from the keybinds library in a `ReadonlySignal<T>`
+ * so that user-customized bindings propagate reactively.
+ *
+ * The signal holds the current merged bindings (schema + overrides). When the
+ * user saves new overrides via `BindingsStore.save()`, the store dispatches a
+ * `'change'` CustomEvent and this signal updates automatically.
+ *
+ * The returned dispose function removes the event listener. Call it when the
+ * component or scope unmounts to prevent memory leaks.
+ *
+ * @example
+ * ```ts
+ * const store = new BindingsStore(schema, "app-bindings")
+ * const [bindingsSignal, disposeBindings] = bindingsStoreSignal(store)
+ *
+ * // bindingsSignal.get() always returns the latest merged bindings
+ * // bindingsSignal.subscribe(...) fires whenever the user customizes a key
+ * ```
+ */
+export declare function bindingsStoreSignal<T>(store: BindingsStore<T>): [ReadonlySignal<T>, () => void];

package/dist/widget.d.ts

@@ -0,0 +1,420 @@
+/**
+ * @rhi-zone/rainbow-ui/widget
+ *
+ * Algebraic widget combinators for rainbow signals.
+ *
+ *   Widget<T, E> = (signal: Signal<T>) => E
+ *
+ * A widget is a pure function from a reactive signal to a typed DOM node.
+ * The second type parameter E (defaults to FlowContent) tracks what kind of
+ * element the widget produces, so the HTML content model flows through
+ * composition and invalid nesting is a type error.
+ *
+ * The seven combinators:
+ *   focus    — zoom into a product field via a Lens
+ *   narrow   — zoom into a sum variant via a Prism; renders nothing when unmatched
+ *   each     — render a list; re-renders on length change, item signals handle diffs
+ *   beside   — pair two widgets side by side; state is the product [A, B]
+ *   above    — pair two widgets vertically; state is the product [A, B]
+ *   dynamic  — pair local state S with an external signal A via stateful()
+ *   map      — reinterpret the signal type via a total Prism (iso)
+ *   show     — boolean gate; renders nothing when predicate is false
+ *   concat   — combine two list widgets over the same signal
+ *
+ * Lifecycle / cleanup:
+ *   All subscriptions created inside a widget call are tracked via a
+ *   thread-local (synchronous) context. mount() collects them and returns
+ *   a single cleanup function that unsubscribes everything.
+ *
+ *   Combinators that conditionally render (narrow, show) manage inner cleanup
+ *   themselves: they tear down child subscriptions when the condition becomes
+ *   false and rebuild them when it becomes true again.
+ */
+import { type Signal, type ReadonlySignal, type Lens, type Prism, type AsyncData } from "@rhi-zone/rainbow";
+import type { AnyEl, El, FlowContent, DivEl, InputEl, InputAttrs, TextareaEl, TextareaAttrs, SelectEl, SelectAttrs } from "./html.js";
+/**
+ * A widget is a pure function from a reactive signal to a typed DOM node.
+ * Calling a widget subscribes it to the signal; the returned node is updated
+ * in place whenever the signal changes.
+ *
+ * @typeParam T - The signal value type
+ * @typeParam E - The element type produced (defaults to FlowContent)
+ */
+export type Widget<T, E extends AnyEl = FlowContent> = (signal: Signal<T>) => E;
+/**
+ * Run `fn` in an explicit cleanup scope. Returns the result and a dispose
+ * function. Use at the top level (bootstrap, app root) where there is no
+ * enclosing widget context for `register()` calls to land in.
+ *
+ * @example
+ * const [, disposeApp] = withScope(() => {
+ *   register(disposeInit)
+ *   renderContactList(sidebar)
+ *   renderDetailPanel(detail)
+ * })
+ */
+export declare function withScope<T>(fn: () => T): [T, () => void];
+/** Minimal interface satisfied by both Signal<T> and ReadonlySignal<T>. */
+type Subscribable<T> = Pick<Signal<T> | ReadonlySignal<T>, "subscribe">;
+/**
+ * Subscribe to a signal (or readonly signal) and register the unsubscribe in
+ * the current context. Must be called during a widget call (directly or via a
+ * combinator).
+ */
+export declare function subscribe<T>(s: Subscribable<T>, fn: (value: T) => void): void;
+/**
+ * Register an arbitrary cleanup function in the current widget call context.
+ * Called on unmount alongside subscription cleanups. Use for event listeners,
+ * timers, or `fromAsync` dispose functions.
+ *
+ * @example
+ * const [data, dispose] = fromAsync(querySignal, fetch)
+ * register(dispose)
+ */
+export declare function register(fn: () => void): void;
+/**
+ * Render a widget into a container and return a cleanup function.
+ * The cleanup removes the rendered node and unsubscribes all signals.
+ *
+ * @example
+ * const cleanup = mount(counterWidget, countSignal, document.getElementById('root')!)
+ * // later:
+ * cleanup()
+ */
+export declare function mount<T, E extends AnyEl>(widget: Widget<T, E>, signal: Signal<T> | ReadonlySignal<T>, container: HTMLElement): () => void;
+/**
+ * Zoom into a product field. The child widget operates on `B`; the parent
+ * signal carries `A`. Reads and writes pass through the lens.
+ *
+ * @example
+ * // Widget<CompareExpr> that only sees the 'op' field
+ * focus(opPicker, field('op'))
+ */
+export declare function focus<A, B, E extends AnyEl>(w: Widget<B, E>, l: Lens<A, B>): Widget<A, E>;
+/**
+ * Zoom into a sum variant. The child widget renders when the prism matches;
+ * renders an empty container when it doesn't. Container switches on match
+ * status changes; in-variant updates are handled by the child's own signal.
+ *
+ * @example
+ * narrow(compareWidget, comparePrism)  // Widget<Expr>: visible only for compare nodes
+ */
+export declare function narrow<A, B>(w: Widget<B, FlowContent>, prism: Prism<A, B>): Widget<A, DivEl>;
+/**
+ * Render a list. Each item gets a focused signal via an index lens. Fully
+ * re-renders on length change; per-item updates are handled by each item
+ * signal (no explicit keying yet — that is a future optimisation).
+ *
+ * @example
+ * each(rowWidget)  // Widget<Row[]>
+ */
+export declare function each<A>(w: Widget<A, FlowContent>): Widget<A[], DivEl>;
+/**
+ * Render two widgets side by side. The combined signal is the product [A, B].
+ * Layout (flex/grid) is the caller's responsibility via CSS.
+ *
+ * @example
+ * beside(focus(opPicker, field('op')), focus(exprWidget, field('left')))
+ */
+export declare function beside<A, B>(wa: Widget<A, FlowContent>, wb: Widget<B, FlowContent>): Widget<[A, B], DivEl>;
+/**
+ * Render two widgets stacked vertically. The combined signal is the product [A, B].
+ *
+ * @example
+ * above(labelWidget, inputWidget)
+ */
+export declare function above<A, B>(wa: Widget<A, FlowContent>, wb: Widget<B, FlowContent>): Widget<[A, B], DivEl>;
+/**
+ * Pair local state `S` with an external signal `A`. The child widget sees the
+ * product `[S, A]`. Local state changes do not propagate to the parent.
+ *
+ * Implemented via rainbow's `stateful(init, outer)`.
+ *
+ * @example
+ * // Combobox with open/closed state independent of the value signal
+ * dynamic(false, comboboxWidget)  // Widget<Value>
+ */
+export declare function dynamic<S, A, E extends AnyEl>(init: S, w: Widget<[S, A], E>): Widget<A, E>;
+/**
+ * Reinterpret the widget's value type via a total prism (isomorphism).
+ * The prism must be a bijection: `match` must always return a value.
+ *
+ * Useful for display transforms such as number ↔ string for text inputs.
+ *
+ * @example
+ * const numToStr = iso((n: number) => String(n), (s) => Number(s))
+ * map(numberWidget, numToStr)  // Widget<string>
+ */
+export declare function map<A, B, E extends AnyEl>(w: Widget<A, E>, isoP: Prism<B, A>): Widget<B, E>;
+/**
+ * Boolean gate. Renders the child widget when `predicate` holds; renders an
+ * empty container otherwise. Simpler than `narrow` when there is no Prism —
+ * just a boolean condition. SolidJS `<Show>` is the prior art.
+ *
+ * @example
+ * show(detailsWidget, (form) => form.advanced)
+ */
+/**
+ * Boolean gate. Renders the child widget when `predicate` holds; hides it
+ * (via `display:none`) otherwise. Simpler than `narrow` when there is no
+ * Prism — just a boolean condition. SolidJS `<Show>` is the prior art.
+ *
+ * The child is rendered **eagerly** and kept alive in the DOM. Toggling
+ * visibility is a single style-property write — no DOM teardown/rebuild, no
+ * GC pressure, and subscriptions remain active so the child stays current
+ * while hidden (showing is instant, no catch-up render required).
+ *
+ * @example
+ * show(detailsWidget, (form) => form.advanced)
+ */
+export declare function show<A>(w: Widget<A, FlowContent>, predicate: (a: A) => boolean): Widget<A, DivEl>;
+/**
+ * Append two list widgets over the same signal. Both widgets see the full
+ * list; use `show`/`narrow`/filtering inside each to render different subsets.
+ * Corresponds to unicorn's concat combinator.
+ *
+ * @example
+ * // Active rows, then archived rows, in the same <tbody>
+ * concat(
+ *   each(show(rowWidget, r => r.active)),
+ *   each(show(rowWidget, r => !r.active))
+ * )
+ */
+export declare function concat<A>(wa: Widget<A[], DivEl>, wb: Widget<A[], DivEl>): Widget<A[], DivEl>;
+/**
+ * Render N widgets all receiving the same signal, stacked into one container.
+ * The same-signal variant of `above` — no product type required.
+ *
+ * Primary use case: form fields that all operate on `FormState<T>`.
+ *
+ * @example
+ * stack(formField("name", inputWidget()), formField("email", inputWidget()))
+ */
+export declare function stack<A>(...widgets: Widget<A, FlowContent>[]): Widget<A, DivEl>;
+/**
+ * Maps a `refs` dict `{ refName: tagName }` to a typed El map:
+ *   `{ refName: El<tagName, HTMLElementTagNameMap[tagName]> }`
+ */
+export type RefsMap<R extends Record<string, keyof HTMLElementTagNameMap>> = {
+    readonly [K in keyof R]: El<R[K] & string, HTMLElementTagNameMap[R[K]]>;
+};
+/**
+ * Template combinator. Parses `innerHTML` once (at definition time), then for
+ * each widget instantiation clones the template, queries out typed DOM refs via
+ * `data-ref` attributes, and calls `bind` with the signal and those refs.
+ *
+ * Refs are queried as `tagName[data-ref="refName"]`, so `{ name: "span" }`
+ * expects `<span data-ref="name">` in the template. Using `data-ref` rather
+ * than `id` means the same template can be cloned many times (e.g. inside
+ * `eachKeyed`) without duplicate-ID issues.
+ *
+ * `bind` is called inside the widget call context, so any `subscribe` calls
+ * inside it are tracked and cleaned up by `mount` / parent combinators.
+ *
+ * @throws if a declared ref is absent from the cloned template.
+ *
+ * @example
+ * const cardWidget = template(
+ *   `<div class="card"><span data-ref="name"></span><b data-ref="score"></b></div>`,
+ *   { name: "span", score: "b" } as const,
+ *   (s, { name, score }) => {
+ *     name.node.textContent = s.get().label
+ *     score.node.textContent = String(s.get().value)
+ *     subscribe(s, v => {
+ *       name.node.textContent = v.label
+ *       score.node.textContent = String(v.value)
+ *     })
+ *   }
+ * )
+ */
+export declare function template<const R extends Record<string, keyof HTMLElementTagNameMap>, T>(innerHTML: string, refs: R, bind: (signal: Signal<T>, refs: RefsMap<R>) => void): Widget<T, DivEl>;
+/**
+ * Render a keyed list. Each item gets a stable Signal<T> for its lifetime —
+ * only added/removed items trigger mount/unmount. Reordering and in-place
+ * updates are handled without remounting.
+ *
+ * Write-back: if an item widget sets its signal (e.g. an editable field),
+ * the change propagates back to the parent list signal at the item's current
+ * key position — but only when `s` is a writable Signal (has a `set` method).
+ * A flag prevents the resulting list update from cycling back.
+ *
+ * GC note: O(n) `Object.is` comparisons per list update (to sync item
+ * signals), but O(new keys) DOM/signal allocations. Stable lists are cheap.
+ *
+ * @param s       - Signal carrying the full array
+ * @param getKey  - Stable key function (like React's `key` prop)
+ * @param widget  - Widget factory receiving a per-item Signal<T>
+ * @param options - Optional container tag (default "div"); pass a specific
+ *                  HTML tag to fix CSS grid/flex layout issues that arise
+ *                  from an extra wrapper div.
+ *
+ * @example
+ * eachKeyed(todosSignal, t => t.id, todoWidget)
+ * eachKeyed(rowsSignal, r => r.id, rowWidget, { container: "ul" })
+ */
+export declare function eachKeyed<T>(s: Signal<T[]> | ReadonlySignal<T[]>, getKey: (item: T) => string, widget: (itemSignal: Signal<T>) => AnyEl, options?: {
+    container?: keyof HTMLElementTagNameMap;
+}): AnyEl;
+/**
+ * Attach a typed event listener and register its removal as cleanup.
+ * Must be called during a widget call context (directly or via a combinator).
+ *
+ * @example
+ * on(buttonEl.node, "click", () => s.set(s.get() + 1))
+ */
+export declare function on<K extends keyof HTMLElementEventMap>(el: EventTarget, event: K, fn: (e: HTMLElementEventMap[K]) => void): void;
+/**
+ * Two-way bind a text `<input>` or `<textarea>` to a `Signal<string>`.
+ *
+ * Sets `el.value` immediately from the signal, then:
+ * - DOM → signal: `input` event calls `s.set(el.value)`
+ * - signal → DOM: updates `el.value` only when the new value differs
+ *   (guards against cursor-position jumps on mid-type updates)
+ *
+ * When called inside a widget call context, cleanup is registered
+ * automatically. When called outside (e.g. imperative bootstrap), use the
+ * returned cleanup function.
+ *
+ * @returns A cleanup function that unsubscribes and removes the event listener.
+ */
+export declare function bindInput(el: HTMLInputElement | HTMLTextAreaElement, s: Signal<string>): () => void;
+/**
+ * Two-way bind a `<select>` to a `Signal<string>`.
+ * DOM → signal on `change` event; signal → DOM when value differs.
+ *
+ * Must be called during a widget call context.
+ */
+export declare function bindSelect(el: HTMLSelectElement, s: Signal<string>): void;
+/**
+ * Two-way bind a checkbox `<input>` to a `Signal<boolean>`.
+ * DOM → signal on `change` event; signal → DOM when checked state differs.
+ *
+ * Must be called during a widget call context.
+ */
+export declare function bindCheckbox(el: HTMLInputElement, s: Signal<boolean>): void;
+/**
+ * Run `fn` immediately with the current signal value, then subscribe to future
+ * changes. Registers the subscription cleanup in the current widget context.
+ *
+ * Eliminates the `fn(s.get()); subscribe(s, fn)` boilerplate in template bind
+ * callbacks.
+ *
+ * Must be called during a widget call context.
+ */
+export declare function subscribeNow<T>(s: Signal<T> | ReadonlySignal<T>, fn: (v: T) => void): void;
+/**
+ * Reactively set `el.textContent` to the value of `s`. Sets the initial value
+ * synchronously, then subscribes for future changes.
+ *
+ * Must be called during a widget call context.
+ *
+ * @example
+ * bindText(nameSpan.node, nameSignal)
+ */
+export declare function bindText(el: {
+    textContent: string | null;
+}, s: Signal<string> | ReadonlySignal<string>): void;
+/**
+ * Reactively set an attribute on `el` to the value of `s`. Sets the initial
+ * value synchronously, then subscribes for future changes.
+ *
+ * Must be called during a widget call context.
+ *
+ * @example
+ * bindAttr(imgEl.node, "src", urlSignal)
+ */
+export declare function bindAttr(el: Element, attr: string, s: Signal<string> | ReadonlySignal<string>): void;
+/**
+ * Reactively toggle a CSS class on `el` based on the boolean value of `s`.
+ * Sets the initial state synchronously, then subscribes for future changes.
+ *
+ * Must be called during a widget call context.
+ *
+ * @example
+ * bindClass(rowEl.node, "selected", isSelectedSignal)
+ */
+export declare function bindClass(el: Element, className: string, s: Signal<boolean> | ReadonlySignal<boolean>): void;
+/**
+ * Subscribe to multiple signals and run `fn` whenever any of them changes.
+ * Calls `fn()` immediately on invocation, then re-runs on each change.
+ * Returns a cleanup function that unsubscribes from all signals.
+ *
+ * Replaces the repetitive `subscribe(a, fn); subscribe(b, fn); fn()` pattern
+ * when a single side-effectful function depends on N signals.
+ *
+ * @example
+ * const stop = watchAll([contacts, panel, searchQuery, sortBy], renderList)
+ * // later:
+ * stop()
+ */
+export declare function watchAll(signals: ReadonlyArray<ReadonlySignal<unknown>>, fn: () => void): () => void;
+/**
+ * Show or hide `el` (via `style.display`) based on the boolean signal `s`.
+ * Sets `display` to `""` when `s` is true, `"none"` when false.
+ * Applies the initial value synchronously on call.
+ * Returns a cleanup function that unsubscribes the signal.
+ *
+ * Use `signal.map(...)` to derive the boolean from a richer signal:
+ *
+ * @example
+ * const stop = bindShow(viewPanel, panel.map(p => p.mode === 'viewing'))
+ * // later:
+ * stop()
+ */
+export declare function bindShow(el: HTMLElement, s: ReadonlySignal<boolean>): () => void;
+/**
+ * Reactively render one of four states of an `AsyncData` signal into a
+ * container div. Each state maps to an optional render function; missing cases
+ * render an empty div. Replaces the container's single child on every state
+ * change.
+ *
+ * Modelled after `narrow` — manages inner cleanup when swapping states.
+ * Must be called during a widget call context.
+ *
+ * @example
+ * const container = foldWidget(asyncDataSignal, {
+ *   notAsked: () => text("—"),
+ *   loading:  () => text("Loading…"),
+ *   failure:  (err) => text(String(err)),
+ *   success:  (data) => renderData(data),
+ * })
+ */
+export declare function foldWidget<T, E>(s: Signal<AsyncData<T, E>> | ReadonlySignal<AsyncData<T, E>>, cases: {
+    notAsked?: () => AnyEl;
+    loading?: () => AnyEl;
+    failure?: (err: E) => AnyEl;
+    success?: (value: T) => AnyEl;
+}): DivEl;
+/**
+ * Text input widget. The `value` attr is omitted from `attrs` — the signal
+ * owns the value. Use `focus` to connect to a field on a larger signal.
+ *
+ * @example
+ * focus(inputWidget({ placeholder: "Name" }), field("name"))
+ */
+export declare function inputWidget(attrs?: Omit<InputAttrs, "value">): Widget<string, InputEl>;
+/**
+ * Textarea widget. Signal owns the value.
+ */
+export declare function textareaWidget(attrs?: TextareaAttrs): Widget<string, TextareaEl>;
+/**
+ * Checkbox widget. Signal owns the checked state.
+ */
+export declare function checkboxWidget(attrs?: Omit<InputAttrs, "type" | "checked">): Widget<boolean, InputEl>;
+/**
+ * Number input widget. Signal owns the numeric value. NaN inputs are ignored
+ * (the signal is only updated when the parsed value is a valid number).
+ */
+export declare function numberInputWidget(attrs?: Omit<InputAttrs, "value" | "type">): Widget<number, InputEl>;
+/**
+ * Select widget with a static options list. Signal owns the selected value.
+ * For dynamic options, compose `each` + `focus` over a list signal instead.
+ *
+ * @example
+ * selectWidget([{ value: "au", label: "Australia" }, { value: "nz", label: "New Zealand" }])
+ */
+export declare function selectWidget(options: {
+    value: string;
+    label: string;
+}[], attrs?: SelectAttrs): Widget<string, SelectEl>;
+export {};