@joewinke/jatui 0.1.31 → 0.2.0

package/CLAUDE.md

@@ -239,6 +239,28 @@ If the project uses JST (Joe's Software Template), browse component demos at `/c
 - Check the component source in `src/lib/components/` for full prop types
 - Prefer jatui components over building custom ones when there's a match
 
+# Layering Policy (DaisyUI is an implementation detail)
+
+Three rules keep DaisyUI swappable instead of load-bearing:
+
+1. **jatui is the only API consumers touch.** App code imports `<Button>`,
+   `<TextInput>`, `<Modal>` — it never hand-writes `btn btn-primary` for
+   anything jatui covers. Consumer repos enforce this with the ratchet:
+   `node scripts/check-daisy-leakage.mjs <src> --baseline <file>` (count may
+   only shrink; marketing routes can be `--allow`ed).
+2. **DaisyUI class names live only inside jatui components.** They are
+   internal skin, like vendored CSS — never part of a component's public
+   props/API.
+3. **jatui owns the token layer.** Components consume `--jatui-*`
+   (`styles/tokens.css`: radius/spacing/border) and `--motion-*`
+   (`styles/motion.css`: easing/duration) custom properties. DaisyUI theme
+   variables feed INTO those tokens (as fallback-chained inputs), never
+   appear directly in component styles for values the tokens cover.
+
+Net effect: dropping or replacing DaisyUI would be a change to the token
+files and component internals — a skin swap inside this package, not an
+app-wide migration for consumers.
+
 # Accessibility (a11y)
 
 @~/code/jat/shared/a11y-patterns.md

package/dist/actions/attention.d.ts

@@ -0,0 +1,24 @@
+export type AttentionEffect = 'shake' | 'ping';
+export interface AttentionOptions {
+    effect: AttentionEffect;
+    /** Change this value to retrigger. Any truthy/changing value fires the effect. */
+    trigger?: unknown;
+}
+/**
+ * Retriggerable attention action — fires once per `trigger` change.
+ *
+ * use:attention={{ effect: 'shake', trigger: myTrigger }}
+ *
+ * shake — horizontal translate, 4–6px amplitude, 2–3 oscillations, ≤300ms total.
+ *   Use for invalid-input / reject feedback. Pair with a static error affordance
+ *   (color, icon, label) so the state survives without motion.
+ *   Reduced-motion: skipped entirely.
+ *
+ * ping — single expanding fading ring behind the element. Use for notification
+ *   dots and badges. Fires once per trigger change; NEVER loops infinitely.
+ *   Reduced-motion: skipped entirely.
+ */
+export declare function attention(node: HTMLElement, options: AttentionOptions): {
+    update(newOptions: AttentionOptions): void;
+    destroy(): void;
+};

package/dist/actions/attention.js

@@ -0,0 +1,94 @@
+// direction taxonomy after animista.net (Ana Travas, BSD-2-Clause site license); keyframes re-authored on jatui motion tokens
+/**
+ * Retriggerable attention action — fires once per `trigger` change.
+ *
+ * use:attention={{ effect: 'shake', trigger: myTrigger }}
+ *
+ * shake — horizontal translate, 4–6px amplitude, 2–3 oscillations, ≤300ms total.
+ *   Use for invalid-input / reject feedback. Pair with a static error affordance
+ *   (color, icon, label) so the state survives without motion.
+ *   Reduced-motion: skipped entirely.
+ *
+ * ping — single expanding fading ring behind the element. Use for notification
+ *   dots and badges. Fires once per trigger change; NEVER loops infinitely.
+ *   Reduced-motion: skipped entirely.
+ */
+export function attention(node, options) {
+    var currentTrigger = options.trigger;
+    var pingEl = null;
+    var shakeId = null;
+    function prefersReduced() {
+        return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+    }
+    function clearShake() {
+        node.style.animation = '';
+        if (shakeId !== null) {
+            clearTimeout(shakeId);
+            shakeId = null;
+        }
+    }
+    function clearPing() {
+        if (pingEl) {
+            pingEl.remove();
+            pingEl = null;
+        }
+    }
+    function runShake() {
+        if (prefersReduced())
+            return;
+        clearShake();
+        // 3 oscillations × 2 half-cycles = 6 keyframe segments in ~280ms
+        // translate: 0 → +5px → -5px → +4px → -4px → +2px → 0
+        var kf = [
+            { transform: 'translateX(0)' },
+            { transform: 'translateX(5px)' },
+            { transform: 'translateX(-5px)' },
+            { transform: 'translateX(4px)' },
+            { transform: 'translateX(-4px)' },
+            { transform: 'translateX(2px)' },
+            { transform: 'translateX(0)' }
+        ];
+        node.animate(kf, { duration: 280, easing: 'ease-in-out', fill: 'none' });
+    }
+    function runPing() {
+        if (prefersReduced())
+            return;
+        clearPing();
+        var rect = node.getBoundingClientRect();
+        var size = Math.max(rect.width, rect.height);
+        // Ensure node is position-capable for the pseudo-ring
+        var pos = getComputedStyle(node).position;
+        if (pos === 'static')
+            node.style.position = 'relative';
+        pingEl = document.createElement('span');
+        pingEl.style.cssText = "\n\t\t\tposition:absolute;\n\t\t\tinset:-4px;\n\t\t\tborder-radius:inherit;\n\t\t\tborder:2px solid currentColor;\n\t\t\topacity:0.7;\n\t\t\tpointer-events:none;\n\t\t\tz-index:-1;\n\t\t";
+        node.appendChild(pingEl);
+        var scale = 1 + 24 / size;
+        pingEl.animate([
+            { transform: 'scale(1)', opacity: '0.7' },
+            { transform: "scale(".concat(scale.toFixed(2), ")"), opacity: '0' }
+        ], { duration: 600, easing: 'ease-out', fill: 'forwards' }).onfinish = function () { return clearPing(); };
+    }
+    function fire(effect) {
+        if (effect === 'shake')
+            runShake();
+        else
+            runPing();
+    }
+    // Fire on mount if trigger is set
+    if (options.trigger !== undefined) {
+        fire(options.effect);
+    }
+    return {
+        update: function (newOptions) {
+            if (newOptions.trigger !== currentTrigger) {
+                currentTrigger = newOptions.trigger;
+                fire(newOptions.effect);
+            }
+        },
+        destroy: function () {
+            clearShake();
+            clearPing();
+        }
+    };
+}

package/dist/actions/collapse.js

@@ -58,22 +58,34 @@
  * state (e.g. a `SvelteSet` of ids, with the id interpolating the row's own id) —
  * one action instance attaches per row element.
  */
-const DEFAULTS = { threshold: 120, expanded: false, fadeStart: 55, epsilon: 4 };
-export function collapse(node, options = {}) {
-    let opts = { ...DEFAULTS, ...options };
-    let collapsible = false;
-    let rafId = 0;
-    let applied = false;
+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 ${opts.fadeStart}%, transparent 100%)`;
+        return "linear-gradient(to bottom, black ".concat(opts.fadeStart, "%, transparent 100%)");
     }
     function apply() {
-        const shouldCollapse = collapsible && !opts.expanded;
+        var shouldCollapse = collapsible && !opts.expanded;
         if (shouldCollapse === applied)
             return; // idempotent — avoids RO feedback loops
         applied = shouldCollapse;
         if (shouldCollapse) {
-            node.style.maxHeight = `${opts.threshold}px`;
+            node.style.maxHeight = "".concat(opts.threshold, "px");
             node.style.overflow = 'hidden';
             node.style.maskImage = gradient();
             node.style.webkitMaskImage = gradient();
@@ -86,11 +98,12 @@ export function collapse(node, options = {}) {
         }
     }
     function measure() {
+        var _a;
         // scrollHeight is the full content height even while collapsed.
-        const next = node.scrollHeight > opts.threshold + opts.epsilon;
+        var next = node.scrollHeight > opts.threshold + opts.epsilon;
         if (next !== collapsible) {
             collapsible = next;
-            opts.onCollapsible?.(collapsible);
+            (_a = opts.onCollapsible) === null || _a === void 0 ? void 0 : _a.call(opts, collapsible);
         }
         apply();
     }
@@ -99,12 +112,13 @@ export function collapse(node, options = {}) {
         rafId = requestAnimationFrame(measure);
     }
     // Re-measure when the content's natural size changes (streaming, {@html}, lazy images).
-    const ro = new ResizeObserver(scheduleMeasure);
+    var ro = new ResizeObserver(scheduleMeasure);
     ro.observe(node);
     scheduleMeasure();
     return {
-        update(next = {}) {
-            opts = { ...DEFAULTS, ...next };
+        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
@@ -112,7 +126,7 @@ export function collapse(node, options = {}) {
             // silently skipping the style update.)
             scheduleMeasure();
         },
-        destroy() {
+        destroy: function () {
             cancelAnimationFrame(rafId);
             ro.disconnect();
         },

package/dist/actions/floating.d.ts

@@ -0,0 +1,53 @@
+/**
+ * use:floating — anchored-positioning Svelte action
+ *
+ * Wraps @floating-ui/dom computePosition + autoUpdate so every popover-like
+ * component shares one battle-tested positioning primitive instead of each
+ * hand-rolling viewport clamping.
+ *
+ * Usage (element anchor):
+ *   <div use:floating={{ anchor: triggerEl, placement: 'bottom-start', flip: true, shift: true, offset: 4, onDismiss: close }}>
+ *
+ * Usage (virtual / cursor point anchor):
+ *   const virtualAnchor = makeVirtualAnchor(x, y)
+ *   <div use:floating={{ anchor: virtualAnchor, placement: 'bottom-start', onDismiss: close }}>
+ *
+ * Animation: entrance fade + 2px rise, var(--motion-glide) var(--motion-fast).
+ * Exit is handled by the caller removing the element from the DOM.
+ * Reduced-motion guard: animation is skipped when the user prefers reduced motion.
+ *
+ * Dismiss:
+ *   - Click outside the floating element fires onDismiss
+ *   - Escape key fires onDismiss
+ *   - Focus returns to the anchor element (or document.activeElement before mount)
+ *     when the floating element is dismissed
+ *
+ * Accessibility:
+ *   - The node must already carry role="menu" / role="listbox" etc. — this action
+ *     does not set ARIA roles.
+ */
+import type { Placement, ReferenceElement } from '@floating-ui/dom';
+export type { Placement };
+export interface FloatingOptions {
+    /** Anchor element or virtual element (with getBoundingClientRect). */
+    anchor: ReferenceElement | null;
+    /** Preferred placement. @floating-ui/dom may flip/shift if enabled. Default 'bottom-start'. */
+    placement?: Placement;
+    /** Whether to flip to the opposite side when there's not enough room. Default true. */
+    flip?: boolean;
+    /** Whether to shift along the axis to stay in view. Default true. */
+    shift?: boolean;
+    /** Pixel distance between anchor and floating element. Default 4. */
+    offset?: number;
+    /** Called when the floating element should be dismissed (outside-click or Escape). */
+    onDismiss?: () => void;
+}
+/**
+ * Create a virtual anchor from a viewport point (e.g. cursor coordinates).
+ * Pass the returned object as `anchor` when there is no real DOM element to anchor to.
+ */
+export declare function makeVirtualAnchor(x: number, y: number): ReferenceElement;
+export declare function floating(node: HTMLElement, options: FloatingOptions): {
+    update(next: FloatingOptions): void;
+    destroy(): void;
+};

package/dist/actions/floating.js

@@ -0,0 +1,158 @@
+/**
+ * use:floating — anchored-positioning Svelte action
+ *
+ * Wraps @floating-ui/dom computePosition + autoUpdate so every popover-like
+ * component shares one battle-tested positioning primitive instead of each
+ * hand-rolling viewport clamping.
+ *
+ * Usage (element anchor):
+ *   <div use:floating={{ anchor: triggerEl, placement: 'bottom-start', flip: true, shift: true, offset: 4, onDismiss: close }}>
+ *
+ * Usage (virtual / cursor point anchor):
+ *   const virtualAnchor = makeVirtualAnchor(x, y)
+ *   <div use:floating={{ anchor: virtualAnchor, placement: 'bottom-start', onDismiss: close }}>
+ *
+ * Animation: entrance fade + 2px rise, var(--motion-glide) var(--motion-fast).
+ * Exit is handled by the caller removing the element from the DOM.
+ * Reduced-motion guard: animation is skipped when the user prefers reduced motion.
+ *
+ * Dismiss:
+ *   - Click outside the floating element fires onDismiss
+ *   - Escape key fires onDismiss
+ *   - Focus returns to the anchor element (or document.activeElement before mount)
+ *     when the floating element is dismissed
+ *
+ * Accessibility:
+ *   - The node must already carry role="menu" / role="listbox" etc. — this action
+ *     does not set ARIA roles.
+ */
+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);
+};
+import { computePosition, autoUpdate, flip, shift, offset as fuOffset } from '@floating-ui/dom';
+/**
+ * Create a virtual anchor from a viewport point (e.g. cursor coordinates).
+ * Pass the returned object as `anchor` when there is no real DOM element to anchor to.
+ */
+export function makeVirtualAnchor(x, y) {
+    return {
+        getBoundingClientRect: function () {
+            return {
+                width: 0,
+                height: 0,
+                x: x,
+                y: y,
+                top: y,
+                left: x,
+                right: x,
+                bottom: y,
+                toJSON: function () { return this; }
+            };
+        }
+    };
+}
+function prefersReducedMotion() {
+    return typeof window !== 'undefined' &&
+        window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+export function floating(node, options) {
+    var opts = __assign({ placement: 'bottom-start', flip: true, shift: true, offset: 4 }, options);
+    var cleanup = null;
+    // Remember the element focused before this floating opened so we can return focus on dismiss.
+    var returnFocusTarget = document.activeElement;
+    // Entrance animation
+    node.style.opacity = '0';
+    node.style.transform = 'translateY(2px)';
+    node.style.transition = prefersReducedMotion()
+        ? 'none'
+        : [
+            "opacity var(--motion-fast, 150ms) var(--motion-glide, cubic-bezier(0.16,1,0.3,1))",
+            "transform var(--motion-fast, 150ms) var(--motion-glide, cubic-bezier(0.16,1,0.3,1))"
+        ].join(', ');
+    function applyPosition() {
+        if (!opts.anchor)
+            return;
+        var middlewares = [];
+        if (opts.offset != null)
+            middlewares.push(fuOffset(opts.offset));
+        if (opts.flip)
+            middlewares.push(flip());
+        if (opts.shift)
+            middlewares.push(shift({ padding: 8 }));
+        computePosition(opts.anchor, node, {
+            placement: opts.placement,
+            strategy: 'fixed',
+            middleware: middlewares,
+        }).then(function (_a) {
+            var x = _a.x, y = _a.y;
+            node.style.position = 'fixed';
+            node.style.left = "".concat(x, "px");
+            node.style.top = "".concat(y, "px");
+        });
+    }
+    function startAutoUpdate() {
+        cleanup === null || cleanup === void 0 ? void 0 : cleanup();
+        cleanup = null;
+        if (!opts.anchor)
+            return;
+        // For virtual anchors (plain objects), autoUpdate won't observe DOM mutations
+        // on the reference. That's fine — the caller re-runs update() when coords change.
+        var isVirtual = !('nodeType' in opts.anchor);
+        if (isVirtual) {
+            applyPosition();
+            return;
+        }
+        cleanup = autoUpdate(opts.anchor, node, applyPosition);
+    }
+    function handleOutsidePointer(e) {
+        var _a;
+        if (!node.contains(e.target)) {
+            (_a = opts.onDismiss) === null || _a === void 0 ? void 0 : _a.call(opts);
+        }
+    }
+    function handleKeydown(e) {
+        var _a;
+        if (e.key === 'Escape') {
+            (_a = opts.onDismiss) === null || _a === void 0 ? void 0 : _a.call(opts);
+        }
+    }
+    function returnFocus() {
+        if (returnFocusTarget && typeof returnFocusTarget.focus === 'function') {
+            returnFocusTarget.focus();
+        }
+    }
+    startAutoUpdate();
+    // Animate in after first position has been applied (next microtask)
+    requestAnimationFrame(function () {
+        node.style.opacity = '1';
+        node.style.transform = 'translateY(0)';
+    });
+    // Defer outside-pointer listeners to avoid catching the opening event itself
+    var listenerTimer = setTimeout(function () {
+        document.addEventListener('click', handleOutsidePointer, true);
+        document.addEventListener('contextmenu', handleOutsidePointer, true);
+    }, 0);
+    document.addEventListener('keydown', handleKeydown);
+    return {
+        update: function (next) {
+            opts = __assign({ placement: 'bottom-start', flip: true, shift: true, offset: 4 }, next);
+            startAutoUpdate();
+        },
+        destroy: function () {
+            clearTimeout(listenerTimer);
+            cleanup === null || cleanup === void 0 ? void 0 : cleanup();
+            document.removeEventListener('click', handleOutsidePointer, true);
+            document.removeEventListener('contextmenu', handleOutsidePointer, true);
+            document.removeEventListener('keydown', handleKeydown);
+            returnFocus();
+        }
+    };
+}