@ramme-io/ui 4.0.1 → 4.1.1

package/dist/lib/hooks/useSheetGesture.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The gesture behind a bottom sheet.
+ *
+ * This is the library's first pointer-driven interaction. Nothing else in
+ * @ramme-io/ui uses Pointer Events at all — every interactive component is an
+ * HTML form element — so the rules it establishes are worth stating once:
+ *
+ *  - **Pointer Events only.** One code path for touch, mouse, pen and trackpad.
+ *    Separate `mousemove` and `touchmove` handlers are how you end up with a
+ *    control that works on one and jitters on the other.
+ *  - **`setPointerCapture`.** A drag must survive the finger leaving the
+ *    element. Without capture, dragging a sheet up past its own top edge stops
+ *    tracking, which reads as the sheet sticking.
+ *  - **`touch-action: none`** on the drag surface, applied by the component.
+ *    Without it the browser claims the gesture for scrolling and the sheet
+ *    never moves.
+ *
+ * WHY THE SETTLE MATH IS A PURE FUNCTION
+ *
+ * jsdom has no layout and cannot drag, so the only honest way to test a gesture
+ * is to make its decisions independent of the DOM. `settleTo` below takes
+ * numbers and returns a number; every interesting rule — flick beats position,
+ * dragging below the smallest detent dismisses, a slow drag snaps to nearest —
+ * is checkable without a browser.
+ */
+/** Pixels per millisecond past which a drag counts as a flick rather than a move. */
+export declare const FLICK_VELOCITY = 0.5;
+/**
+ * How far below the smallest detent the sheet must be dragged before release
+ * dismisses it. Expressed as a fraction of the viewport so it scales with the
+ * screen rather than being generous on a tablet and twitchy on a phone.
+ */
+export declare const DISMISS_THRESHOLD = 0.12;
+export interface SettleInput {
+    /** Current height of the sheet as a fraction of the viewport, 0–1. */
+    current: number;
+    /** Allowed resting heights, ascending fractions of the viewport. */
+    detents: number[];
+    /**
+     * Vertical velocity in px/ms. NEGATIVE is upward (the sheet growing), matching
+     * pointer coordinates where y decreases toward the top of the screen.
+     */
+    velocity: number;
+}
+/**
+ * Where the sheet should come to rest when the finger lifts.
+ *
+ * Returns the target detent, or `null` meaning "dismiss".
+ *
+ * Order matters: a flick is honoured before position, because a fast downward
+ * flick from near the top should close the sheet rather than snap it to the
+ * detent it happens to be nearest. That is what every native sheet does, and
+ * getting it backwards makes the sheet feel like it is fighting you.
+ */
+export declare function settleTo({ current, detents, velocity }: SettleInput): number | null;
+export interface SheetGestureOptions {
+    detents: number[];
+    initialDetent?: number;
+    onDismiss: () => void;
+    /** Skips the drag entirely; the sheet still opens and closes, just without motion. */
+    reducedMotion?: boolean;
+}
+export interface SheetGesture {
+    /** Current height as a fraction of the viewport. */
+    height: number;
+    /** True while a finger is down — the component uses this to drop its transition. */
+    dragging: boolean;
+    /** True when the sheet is at its tallest detent. */
+    expanded: boolean;
+    /** Attach to the grabber and header. */
+    onPointerDown: (e: React.PointerEvent) => void;
+    /**
+     * Attach to the scrollable body. Implements the behaviour the pattern is
+     * named for: at a partial detent, dragging up grows the sheet instead of
+     * scrolling; once expanded, the content scrolls normally; and at the top of
+     * the content, dragging down shrinks the sheet again.
+     */
+    onBodyPointerDown: (e: React.PointerEvent) => void;
+    setHeight: (h: number) => void;
+}
+export declare function useSheetGesture({ detents, initialDetent, onDismiss, reducedMotion, }: SheetGestureOptions): SheetGesture;

package/dist/lib/hooks/useSheetGesture.js

@@ -0,0 +1,70 @@
+import { useState as M, useRef as u, useCallback as T, useEffect as C } from "react";
+const D = 0.5, P = 0.12;
+function y({ current: l, detents: f, velocity: a }) {
+  if (!f.length) return null;
+  const s = [...f].sort((r, e) => r - e), n = s[0], c = s[s.length - 1];
+  if (Math.abs(a) >= D) {
+    if (a > 0) {
+      const e = s.filter((g) => g < l - 0.01);
+      return e.length ? e[e.length - 1] : null;
+    }
+    const r = s.filter((e) => e > l + 0.01);
+    return r.length ? r[0] : c;
+  }
+  return l < n - P ? null : s.reduce(
+    (r, e) => Math.abs(e - l) < Math.abs(r - l) ? e : r
+  );
+}
+function R({
+  detents: l,
+  initialDetent: f = 0,
+  onDismiss: a,
+  reducedMotion: s = !1
+}) {
+  const n = [...l].sort((t, i) => t - i), [c, r] = M(n[f] ?? n[0]), [e, g] = M(!1), L = u(0), S = u(0), w = u(0), v = u(0), E = u(0), d = u(null), h = T(
+    (t, i) => {
+      if (!s && t.isPrimary) {
+        if (d.current = i ? t.currentTarget : null, i) {
+          const o = t.currentTarget.scrollTop <= 0;
+          if (c >= n[n.length - 1] - 1e-3 && !o) return;
+        }
+        L.current = t.clientY, w.current = t.clientY, v.current = t.timeStamp, S.current = c, E.current = 0, g(!0), t.currentTarget.setPointerCapture(t.pointerId);
+      }
+    },
+    [c, s, n]
+  ), b = T((t) => h(t, !1), [h]), H = T((t) => h(t, !0), [h]);
+  return C(() => {
+    if (!e) return;
+    const t = (o) => {
+      const Y = window.innerHeight || 1, I = o.clientY - L.current, x = o.timeStamp - v.current;
+      x > 0 && (E.current = (o.clientY - w.current) / x), w.current = o.clientY, v.current = o.timeStamp;
+      let p = S.current - I / Y;
+      const m = n[n.length - 1];
+      p > m && (p = m + (p - m) * 0.25), r(Math.max(0, Math.min(p, m + 0.05))), d.current && (d.current.scrollTop = 0);
+    }, i = () => {
+      g(!1);
+      const o = y({
+        current: c,
+        detents: n,
+        velocity: E.current
+      });
+      o === null ? a() : r(o), d.current = null;
+    };
+    return window.addEventListener("pointermove", t), window.addEventListener("pointerup", i), window.addEventListener("pointercancel", i), () => {
+      window.removeEventListener("pointermove", t), window.removeEventListener("pointerup", i), window.removeEventListener("pointercancel", i);
+    };
+  }, [e, c, a, n]), {
+    height: c,
+    dragging: e,
+    expanded: c >= n[n.length - 1] - 1e-3,
+    onPointerDown: b,
+    onBodyPointerDown: H,
+    setHeight: r
+  };
+}
+export {
+  P as DISMISS_THRESHOLD,
+  D as FLICK_VELOCITY,
+  y as settleTo,
+  R as useSheetGesture
+};

package/dist/lib/theme/themeUtils.d.ts

@@ -1,3 +1,4 @@
+import { DEFAULT_THEME_TOKENS } from '@ramme-io/shared';
 /**
  * Advanced Contrast Guard
  * Adjusts for perceived darkness (like scanline overlays)
@@ -14,6 +15,26 @@ export declare const loadGoogleFont: (headingFont: string, bodyFont: string) =>
  * @example hexToRgbTriplet('#0D6EFD') → '13 110 253'
  */
 export declare const hexToRgbTriplet: (hex: string) => string;
+/**
+ * Every CSS variable `tokensToVars` writes.
+ *
+ * Exported so the code that removes them cannot drift from the code that adds
+ * them — RULE-005 asks for symmetrical purging, and these six were injected on
+ * to documentElement.style and never removed by anything.
+ */
+export declare const THEME_TOKEN_VARS: readonly ["--app-primary-color", "--app-secondary-color", "--app-success-color", "--app-warning-color", "--app-danger-color", "--app-border-radius-md"];
+/**
+ * Has the visitor actually themed anything?
+ *
+ * `activeTheme`/`savedTheme` are always populated — they are seeded with
+ * DEFAULT_THEME_TOKENS — so their presence proves nothing. Only a value that
+ * differs from those defaults means a real choice was made.
+ *
+ * Every place that decides whether to paint the user's layer must agree, or the
+ * layers fight: injecting unconditionally painted the framework's defaults over
+ * the app's own theme for every first-time visitor.
+ */
+export declare const isCustomTheme: (tokens: Partial<Record<keyof typeof DEFAULT_THEME_TOKENS, string>> | null | undefined) => boolean;
 export declare const tokensToVars: (t: Partial<{
     primary: string;
     neutral: string;

package/dist/lib/theme/themeUtils.js

@@ -1,17 +1,18 @@
+import { DEFAULT_THEME_TOKENS as d } from "@ramme-io/shared";
 const m = (o, p) => {
   const a = o.split(" ").map(Number);
   if (a.length !== 3) return o;
   const r = (t) => Math.max(0, Math.min(255, t));
   return `${r(a[0] + p)} ${r(a[1] + p)} ${r(a[2] + p)}`;
-}, d = (o) => {
+}, g = (o) => {
   const [p, a, r] = o.split(" ").map(Number);
   return (0.2126 * p + 0.7152 * a + 0.0722 * r) / 255 > 0.45 ? "15 23 42" : "255 255 255";
-}, h = (o, p) => {
+}, f = (o, p) => {
   if (!o || typeof o != "object") return;
   const a = p || document.documentElement, r = { ...o }, t = r["--app-primary-color"];
-  t && (r["--app-primary-foreground-color"] = d(t));
+  t && (r["--app-primary-foreground-color"] = g(t));
   const l = r["--app-bg-color"];
-  l && (r["--app-text-color"] = d(l)), Object.entries({
+  l && (r["--app-text-color"] = g(l)), Object.entries({
     "--primary": "--app-primary-color",
     "--bg": "--app-bg-color",
     "--text": "--app-text-color",
@@ -32,33 +33,44 @@ const m = (o, p) => {
   ].join(", "), r["--app-secondary-color"] || (r["--app-secondary-color"] = "100 116 139"), r["--app-accent-color"] || (r["--app-accent-color"] = r["--app-primary-color"]), r["--app-input-bg-color"] || (r["--app-input-bg-color"] = r["--app-card-bg-color"]), r["--app-input-border-color"] || (r["--app-input-border-color"] = r["--app-border-color"]), r["--app-border-radius-md"] || (r["--app-border-radius-md"] = "0.375rem"), Object.entries(r).forEach(([s, i]) => {
     s.startsWith("--app-") && a.style.setProperty(s, String(i));
   });
-}, u = (o, p) => {
+}, b = (o, p) => {
   const a = document.head, r = "dynamic-google-fonts", t = document.getElementById(r);
   t && a.removeChild(t);
   const l = `${o.replace(/ /g, "+")}:wght@400;700&family=${p.replace(/ /g, "+")}:wght@400;500;700`, n = document.createElement("link");
   n.id = r, n.rel = "stylesheet", n.crossOrigin = "anonymous", n.href = `https://fonts.googleapis.com/css2?family=${l}&display=swap`, a.insertBefore(n, a.firstChild);
   const e = document.documentElement;
   e.style.setProperty("--app-font-sans", `"${p}", sans-serif`), e.style.setProperty("--app-font-serif", `"${o}", serif`), console.log(`[FontEngine] Applied: ${o} (H) / ${p} (B)`);
-}, f = (o) => {
+}, y = (o) => {
   const p = o.replace("#", ""), a = parseInt(p.substring(0, 2), 16), r = parseInt(p.substring(2, 4), 16), t = parseInt(p.substring(4, 6), 16);
   return `${a} ${r} ${t}`;
-}, g = {
+}, u = {
   none: "0",
   sm: "0.25rem",
   md: "0.375rem",
   lg: "0.5rem",
   full: "9999px"
-}, b = (o) => ({
+}, $ = [
+  "--app-primary-color",
+  "--app-secondary-color",
+  "--app-success-color",
+  "--app-warning-color",
+  "--app-danger-color",
+  "--app-border-radius-md"
+], E = (o) => o ? Object.keys(d).some((p) => o[p] !== void 0 && o[p] !== d[p]) : !1, M = (o) => ({
   "--app-primary-color": o.primary ?? "13 110 253",
   "--app-secondary-color": o.neutral ?? "24 24 27",
   "--app-success-color": o.success ?? "34 197 94",
   "--app-warning-color": o.warning ?? "234 179 8",
-  "--app-destructive-color": o.destructive ?? "239 68 68",
-  "--app-border-radius-md": g[o.radius ?? "md"] ?? "0.375rem"
+  // NOT `--app-destructive-color`, which this wrote until now: that variable
+  // is defined nowhere in index.css and read by nothing, so the Destructive
+  // swatch in ThemeLab changed a value no stylesheet consumed. The token the
+  // preset actually maps `destructive` on to is `--app-danger-color`.
+  "--app-danger-color": o.destructive ?? "239 68 68",
+  "--app-border-radius-md": u[o.radius ?? "md"] ?? "0.375rem"
 }), c = (o = 0, p = 255) => {
   const a = Math.floor(Math.random() * (p - o) + o), r = Math.floor(Math.random() * (p - o) + o), t = Math.floor(Math.random() * (p - o) + o);
   return `${a} ${r} ${t}`;
-}, y = () => {
+}, T = () => {
   const o = Math.random() > 0.5, p = o ? c(10, 40) : c(240, 255), a = o ? c(220, 255) : c(20, 60), r = c(50, 200);
   return {
     "--app-primary-color": r,
@@ -73,11 +85,13 @@ const m = (o, p) => {
   };
 };
 export {
-  h as applyThemeToDom,
-  y as generateRandomTheme,
-  d as getContrastColor,
-  f as hexToRgbTriplet,
-  u as loadGoogleFont,
+  $ as THEME_TOKEN_VARS,
+  f as applyThemeToDom,
+  T as generateRandomTheme,
+  g as getContrastColor,
+  y as hexToRgbTriplet,
+  E as isCustomTheme,
+  b as loadGoogleFont,
   c as randomRgb,
-  b as tokensToVars
+  M as tokensToVars
 };

package/dist/setupTests.d.ts

@@ -0,0 +1 @@
+import '@testing-library/jest-dom/vitest';