@joewinke/jatui 0.1.25 → 0.1.27

package/dist/actions/collapse.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Tall-content collapse — Svelte action.
+ *
+ * Caps an arbitrarily-tall block at a max height with a fade-out gradient so it
+ * shows a preview instead of overflowing its container. The consumer renders the
+ * "Show more / Show less" toggle and owns the `expanded` boolean; the action does
+ * the measuring and applies the collapse styling.
+ *
+ * Why an action (not a wrapper-only component): most adoption sites are existing
+ * elements (`<p>`, a `prose` div, a `<ul>`, a `<pre>`), and an action attaches
+ * with zero DOM restructuring. A batteries-included `<Collapse>` wrapper that
+ * uses this action is also provided for greenfield use.
+ *
+ * ─── Why inline styles, not a CSS class ───────────────────────────────────────
+ *
+ * The action writes `max-height` / `overflow` / `mask-image` directly on the node
+ * when collapsed. That means it needs NO accompanying stylesheet — it works
+ * identically in Tailwind-utility components and scoped-CSS components, and
+ * consumers don't have to copy a `.collapse-*` rule into their app.css (the same
+ * trap rail.css has). Expanding clears the inline styles.
+ *
+ * ─── Why ResizeObserver, not a one-shot rAF ───────────────────────────────────
+ *
+ * Streaming chat answers and `{@html}` markdown bodies grow AFTER mount. A
+ * one-shot measurement on mount would miss them (and would wrongly hide the
+ * toggle on content that hasn't streamed in yet). A ResizeObserver re-measures
+ * whenever the content's natural height changes, so `collapsible` stays correct.
+ *
+ * `scrollHeight` reports the FULL content height even while `max-height` +
+ * `overflow:hidden` are applied, so the action can keep measuring without ever
+ * having to un-collapse first.
+ *
+ * ─── Usage — action form (most sites) ─────────────────────────────────────────
+ *
+ *   <script>
+ *     import { collapse } from 'jatui'
+ *     let collapsible = $state(false)
+ *     let expanded = $state(false)
+ *     const bodyId = `collapse-${$props.id()}`
+ *   </script>
+ *
+ *   <div id={bodyId} use:collapse={{ expanded, onCollapsible: (c) => (collapsible = c) }}>
+ *     {content}
+ *   </div>
+ *   {#if collapsible}
+ *     <button
+ *       aria-expanded={expanded}
+ *       aria-controls={bodyId}
+ *       onclick={() => (expanded = !expanded)}
+ *     >
+ *       {expanded ? 'Show less ↑' : 'Show more ↓'}
+ *     </button>
+ *   {/if}
+ *
+ * The `id`/`aria-expanded`/`aria-controls` trio is not optional — without it the
+ * toggle is keyboard-operable but invisible to screen readers as a disclosure
+ * control. For mapped lists, give each row its own `id`/`expanded`/`collapsible`
+ * state (e.g. a `SvelteSet` of ids, with the id interpolating the row's own id) —
+ * one action instance attaches per row element.
+ */
+export interface CollapseOptions {
+    /** Max collapsed height in px. Content taller than this collapses. Default 120. */
+    threshold?: number;
+    /** Controlled expand state. When true, the node is never collapsed. Default false. */
+    expanded?: boolean;
+    /** Where the fade-to-transparent begins, as a %. Default 55. */
+    fadeStart?: number;
+    /** Slack (px) added to the threshold so a near-fit doesn't toggle. Default 4. */
+    epsilon?: number;
+    /**
+     * Called whenever collapsibility changes (content crosses the threshold).
+     * Drive the toggle button's visibility from this — it self-hides when the
+     * content is shorter than the threshold.
+     */
+    onCollapsible?: (collapsible: boolean) => void;
+}
+export declare function collapse(node: HTMLElement, options?: CollapseOptions): {
+    update(next?: CollapseOptions): void;
+    destroy(): void;
+};

package/dist/actions/collapse.js

@@ -0,0 +1,134 @@
+/**
+ * Tall-content collapse — Svelte action.
+ *
+ * Caps an arbitrarily-tall block at a max height with a fade-out gradient so it
+ * shows a preview instead of overflowing its container. The consumer renders the
+ * "Show more / Show less" toggle and owns the `expanded` boolean; the action does
+ * the measuring and applies the collapse styling.
+ *
+ * Why an action (not a wrapper-only component): most adoption sites are existing
+ * elements (`<p>`, a `prose` div, a `<ul>`, a `<pre>`), and an action attaches
+ * with zero DOM restructuring. A batteries-included `<Collapse>` wrapper that
+ * uses this action is also provided for greenfield use.
+ *
+ * ─── Why inline styles, not a CSS class ───────────────────────────────────────
+ *
+ * The action writes `max-height` / `overflow` / `mask-image` directly on the node
+ * when collapsed. That means it needs NO accompanying stylesheet — it works
+ * identically in Tailwind-utility components and scoped-CSS components, and
+ * consumers don't have to copy a `.collapse-*` rule into their app.css (the same
+ * trap rail.css has). Expanding clears the inline styles.
+ *
+ * ─── Why ResizeObserver, not a one-shot rAF ───────────────────────────────────
+ *
+ * Streaming chat answers and `{@html}` markdown bodies grow AFTER mount. A
+ * one-shot measurement on mount would miss them (and would wrongly hide the
+ * toggle on content that hasn't streamed in yet). A ResizeObserver re-measures
+ * whenever the content's natural height changes, so `collapsible` stays correct.
+ *
+ * `scrollHeight` reports the FULL content height even while `max-height` +
+ * `overflow:hidden` are applied, so the action can keep measuring without ever
+ * having to un-collapse first.
+ *
+ * ─── Usage — action form (most sites) ─────────────────────────────────────────
+ *
+ *   <script>
+ *     import { collapse } from 'jatui'
+ *     let collapsible = $state(false)
+ *     let expanded = $state(false)
+ *     const bodyId = `collapse-${$props.id()}`
+ *   </script>
+ *
+ *   <div id={bodyId} use:collapse={{ expanded, onCollapsible: (c) => (collapsible = c) }}>
+ *     {content}
+ *   </div>
+ *   {#if collapsible}
+ *     <button
+ *       aria-expanded={expanded}
+ *       aria-controls={bodyId}
+ *       onclick={() => (expanded = !expanded)}
+ *     >
+ *       {expanded ? 'Show less ↑' : 'Show more ↓'}
+ *     </button>
+ *   {/if}
+ *
+ * The `id`/`aria-expanded`/`aria-controls` trio is not optional — without it the
+ * toggle is keyboard-operable but invisible to screen readers as a disclosure
+ * control. For mapped lists, give each row its own `id`/`expanded`/`collapsible`
+ * state (e.g. a `SvelteSet` of ids, with the id interpolating the row's own id) —
+ * one action instance attaches per row element.
+ */
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var DEFAULTS = { threshold: 120, expanded: false, fadeStart: 55, epsilon: 4 };
+export function collapse(node, options) {
+    if (options === void 0) { options = {}; }
+    var opts = __assign(__assign({}, DEFAULTS), options);
+    var collapsible = false;
+    var rafId = 0;
+    var applied = false;
+    function gradient() {
+        return "linear-gradient(to bottom, black ".concat(opts.fadeStart, "%, transparent 100%)");
+    }
+    function apply() {
+        var shouldCollapse = collapsible && !opts.expanded;
+        if (shouldCollapse === applied)
+            return; // idempotent — avoids RO feedback loops
+        applied = shouldCollapse;
+        if (shouldCollapse) {
+            node.style.maxHeight = "".concat(opts.threshold, "px");
+            node.style.overflow = 'hidden';
+            node.style.maskImage = gradient();
+            node.style.webkitMaskImage = gradient();
+        }
+        else {
+            node.style.maxHeight = '';
+            node.style.overflow = '';
+            node.style.maskImage = '';
+            node.style.webkitMaskImage = '';
+        }
+    }
+    function measure() {
+        var _a;
+        // scrollHeight is the full content height even while collapsed.
+        var next = node.scrollHeight > opts.threshold + opts.epsilon;
+        if (next !== collapsible) {
+            collapsible = next;
+            (_a = opts.onCollapsible) === null || _a === void 0 ? void 0 : _a.call(opts, collapsible);
+        }
+        apply();
+    }
+    function scheduleMeasure() {
+        cancelAnimationFrame(rafId);
+        rafId = requestAnimationFrame(measure);
+    }
+    // Re-measure when the content's natural size changes (streaming, {@html}, lazy images).
+    var ro = new ResizeObserver(scheduleMeasure);
+    ro.observe(node);
+    scheduleMeasure();
+    return {
+        update: function (next) {
+            if (next === void 0) { next = {}; }
+            opts = __assign(__assign({}, DEFAULTS), next);
+            // expanded/threshold/fade may have changed — re-measure and let
+            // apply() compare the freshly computed shouldCollapse against the
+            // real last-applied state. (Force-flipping `applied` here used to make
+            // that comparison spuriously match on a plain expand/collapse toggle,
+            // silently skipping the style update.)
+            scheduleMeasure();
+        },
+        destroy: function () {
+            cancelAnimationFrame(rafId);
+            ro.disconnect();
+        },
+    };
+}

package/dist/actions/railNav.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Keyboard-rail navigation primitive — action + composable.
+ *
+ * A drawer / form is a vertical sequence of "rungs". Focus starts in the first
+ * field. Up / Down (and j / k when NOT typing) step between rungs. Left / Right
+ * acts on the focused rung (cycle a value, switch a tab, open a picker). Escape
+ * pops focus out of a field back to the container, then fires `onEscape`.
+ *
+ * Rungs are ordinary HTML elements tagged with a `data-rail-id` attribute (or
+ * whatever attribute `attr` specifies). The consumer supplies an `order` array
+ * of ids that defines traversal; ids whose element is not currently rendered
+ * in the container are skipped at move time.
+ *
+ * ─── CSS contract ─────────────────────────────────────────────────────────────
+ *
+ * The controller applies two classes to rung host elements. Style them in your
+ * stylesheet (or in a parent scope):
+ *
+ *   .rail-focus   — persistent: applied to the currently active rung host. Use
+ *                   `:focus-visible` / `:has(:focus-visible)` inside the rule so
+ *                   only keyboard-driven focus shows a visible ring.
+ *
+ *   .rail-cycled  — transient (~280ms): applied when Left / Right changes a
+ *                   rung's value via `rail.bump(host)`. Use for a brief pulse
+ *                   that confirms the value changed.
+ *
+ * ─── Usage — action form (simplest) ──────────────────────────────────────────
+ *
+ *   <div use:railNav={{
+ *     order: () => ['title', 'type', 'priority'],
+ *     onAction: (id, dir, host) => cycleField(id, dir),
+ *     onEscape: () => closeDrawer(),
+ *   }}>
+ *     <input data-rail-id="title" />
+ *     <div   data-rail-id="type"     tabindex="-1">…</div>
+ *     <div   data-rail-id="priority" tabindex="-1">…</div>
+ *   </div>
+ *
+ * ─── Usage — composable form ──────────────────────────────────────────────────
+ *
+ *   const rail = createRailNav({
+ *     container: panelEl,
+ *     order: () => currentOrder,
+ *     onAction: (id, dir, host) => { rail.bump(host); cycleField(id, dir); },
+ *     onEscape: () => closeDrawer(),
+ *   });
+ *
+ *   // Wire both listeners on the container:
+ *   panelEl.addEventListener('keydown',  (e) => rail.handleKeydown(e));
+ *   panelEl.addEventListener('focusin',  (e) => rail.handleFocusin(e));
+ *
+ * ─── How to wire a drawer to railNav ──────────────────────────────────────────
+ *
+ *   1. Tag each rung host with `data-rail-id`:
+ *        <div data-rail-id="type" tabindex="-1">…</div>
+ *
+ *   2. Apply the action (or composable) to the drawer panel:
+ *        <div bind:this={panel} use:railNav={{ order, onAction, onEscape }} …>
+ *
+ *   3. Handle Left/Right in `onAction` and call `rail.bump(host)` on change:
+ *        onAction: (id, dir, host) => { formData[id] = cycle(opts[id], …, dir); rail.bump(host); }
+ */
+import type { Action } from 'svelte/action';
+export interface RailNavOptions {
+    /**
+     * Rung id order, top → bottom. May be a plain array or a getter (called on
+     * every navigation event so reactive lists stay in sync).
+     */
+    order: string[] | (() => string[]);
+    /**
+     * Called when Left / Right is pressed on a non-text rung.
+     * `dir` is `1` for Right and `-1` for Left.
+     * Call `rail.bump(host)` inside this handler if you want the pulse effect.
+     */
+    onAction?: (rungId: string, dir: 1 | -1, host: HTMLElement) => void;
+    /**
+     * Called when Escape is pressed while focus is already on (or has been
+     * popped back to) the container itself. Typically closes the drawer / modal.
+     */
+    onEscape?: () => void;
+    /**
+     * Optional: when a child popover currently owns keyboard focus, return `true`
+     * here to suppress rail navigation. Escape will call `onPopoverEscape` first.
+     */
+    isPopoverOpen?: () => boolean;
+    /** Called on Escape when `isPopoverOpen()` returns true. */
+    onPopoverEscape?: () => void;
+    /**
+     * When `true` (default), keystrokes on non-text rungs are stopped from
+     * bubbling to window-level listeners behind a modal.
+     */
+    trap?: boolean;
+    /**
+     * Attribute used as the rung identifier. Default: `'data-rail-id'`.
+     * The controller looks for elements matching `[<attr>="<id>"]`.
+     */
+    attr?: string;
+    /**
+     * The container element to search for rung hosts.
+     *
+     * Required for `createRailNav`. The `railNav` action fills this automatically
+     * from the action's `node`.
+     */
+    container?: HTMLElement;
+}
+export interface RailNavController {
+    /**
+     * Feed a keydown event. Returns `true` if the event was consumed.
+     * Attach to the container's `keydown` listener (or `onkeydown` in Svelte).
+     */
+    handleKeydown(event: KeyboardEvent): boolean;
+    /**
+     * Feed a focusin event so the controller can track which rung the user
+     * Tabbed into. Attach to the container's `focusin` listener.
+     */
+    handleFocusin(event: FocusEvent): void;
+    /** Step one rung in direction `1` (down) or `-1` (up). Wraps around. */
+    moveRung(dir: 1 | -1): void;
+    /** Focus the rung with the given id. No-op if the element is not rendered. */
+    focus(id: string): void;
+    /**
+     * Re-derive the current rung list after a conditional rung appears or
+     * disappears. The action calls this automatically in its `update` hook.
+     * Call manually in the composable form after reactive state changes.
+     */
+    refresh(): void;
+    /** The id of the last rung that received focus, or `''` if none. */
+    currentId(): string;
+    /**
+     * Applies the transient `rail-cycled` class to `host` for ~280ms.
+     * Call this inside `onAction` when a Left / Right key changes a value.
+     */
+    bump(host: HTMLElement | null): void;
+}
+/**
+ * Cycle through `list`, returning the item `dir` steps from `current`.
+ * Wraps around. Returns `current` unchanged when the list is empty.
+ *
+ * @example
+ *   cycle(['bug', 'feature', 'task'], 'feature',  1)  // → 'task'
+ *   cycle(['bug', 'feature', 'task'], 'bug',      -1)  // → 'task'
+ *   cycle(['a', 'b'],                'z',          1)  // → 'a'  (not found → start)
+ */
+export declare function cycle<T>(list: readonly T[], current: T, dir: 1 | -1): T;
+/**
+ * Imperative composable — use when you already own keydown / focusin handlers
+ * and want `railNav` to decide whether to consume the event.
+ *
+ * You **must** supply `options.container` and wire both events:
+ *
+ *   const rail = createRailNav({ container: panel, order, onAction, onEscape });
+ *   panel.addEventListener('keydown', (e) => rail.handleKeydown(e));
+ *   panel.addEventListener('focusin', (e) => rail.handleFocusin(e));
+ */
+export declare function createRailNav(options: RailNavOptions): RailNavController;
+/**
+ * Svelte action — attaches `keydown` and `focusin` listeners to `node` and
+ * handles rung stepping, horizontal action dispatch, and Escape cascade.
+ *
+ * @example
+ *   <div use:railNav={{ order, onAction, onEscape }}>
+ *     <input data-rail-id="title" />
+ *     <div   data-rail-id="type"     tabindex="-1">…</div>
+ *     <div   data-rail-id="priority" tabindex="-1">…</div>
+ *   </div>
+ */
+export declare const railNav: Action<HTMLElement, RailNavOptions | undefined>;