@ramme-io/ui 4.1.0 → 4.2.0

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/setupTests.d.ts

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

package/dist/wizardManifest.js

@@ -596,7 +596,7 @@ const e = {
     {
       id: "login-page",
       name: "LoginPage",
-      version: "1.0.0",
+      version: "1.0.1",
       description: "The standard sign-in screen — email and password, with inline error and loading states already wired. Strategic purpose: a drop-in credential form so products don't rebuild one; `quickProfiles` adds one-click demo personas, which is what makes a prototype instantly explorable without real accounts.",
       tags: [
         "auth",
@@ -626,6 +626,21 @@ const e = {
           name: "quickProfiles",
           type: "Array<QuickProfile>",
           description: "Optional one-click demo identities, each `{ name, email, role }`."
+        },
+        {
+          name: "signupHref",
+          type: "string",
+          description: 'Where "Create one" points. Pass `null` to hide that line entirely, which is what an invite-only product wants. Defaults to `/auth/signup`.'
+        },
+        {
+          name: "signupLabel",
+          type: "string",
+          description: 'Text for that link. Defaults to "Create one".'
+        },
+        {
+          name: "forgotHref",
+          type: "string",
+          description: 'Where "Forgot?" points. Pass `null` to hide it — a product with no reset email has nothing to link to. Defaults to `#`.'
         }
       ],
       importPath: "./components/auth/LoginPage",
@@ -1083,7 +1098,7 @@ const e = {
     {
       id: "status-badge",
       name: "StatusBadge",
-      version: "1.0.1",
+      version: "1.0.2",
       description: "A consistent status indicator featuring a color-coded dot and an optional text label. Essential for IoT devices and system states.",
       tags: [
         "status",
@@ -1102,7 +1117,7 @@ const e = {
         {
           name: "color",
           type: "string",
-          description: "Tailwind background class for the dot (e.g. 'bg-emerald-500'). Overrides the `status` preset's color when both are given."
+          description: "Background class for the dot (e.g. 'bg-success'). Use a semantic token — a numeric shade does not adapt to the active theme. Overrides the `status` preset's colour when both are given."
         },
         {
           name: "label",
@@ -1961,31 +1976,53 @@ const e = {
     {
       id: "textarea",
       name: "Textarea",
-      version: "1.0.0",
-      description: "A theme-aware textarea component for multi-line text input.",
+      version: "1.0.1",
+      description: "A theme-aware multi-line text input with label, helper text, and validation state support. Strategic purpose: the multi-line sibling of Input, styled identically so the two are indistinguishable when stacked in one form. Forwards all standard HTML textarea attributes via spread.",
       tags: [
         "form",
         "input",
-        "ui"
+        "ui",
+        "text",
+        "multiline"
       ],
       category: "form",
       props: [
         {
           name: "label",
           type: "string",
-          description: "An optional label to display above the textarea."
+          description: "Optional label displayed above the textarea."
+        },
+        {
+          name: "helperText",
+          type: "string",
+          description: "Supporting text rendered below the textarea. Appears in destructive color when error is true."
+        },
+        {
+          name: "error",
+          type: "boolean",
+          description: "If true, applies destructive border styling to indicate a validation error. Defaults to false."
+        },
+        {
+          name: "required",
+          type: "boolean",
+          description: "If true, appends a required (*) indicator next to the label. Defaults to false."
+        },
+        {
+          name: "showOptionalLabel",
+          type: "boolean",
+          description: "If true, appends an (optional) label when the field is not required. Defaults to false."
         },
         {
           name: "containerClassName",
           type: "string",
-          description: "Optional additional CSS classes for the container div."
+          description: "Additional CSS classes applied to the outer container div."
         }
       ],
       importPath: "./components/forms/Textarea",
       filePath: "src/components/forms/Textarea.tsx",
       sku: "@atom/form/textarea",
       humanLabel: "Textarea",
-      humanDescription: "A theme-aware textarea component for multi-line text input."
+      humanDescription: "A theme-aware multi-line text input with label, helper text, and validation state support. Strategic purpose: the multi-line sibling of Input, styled identically so the two are indistinguishable when stacked in one form. Forwards all standard HTML textarea attributes via spread."
     },
     {
       id: "toggle-switch",
@@ -2619,8 +2656,8 @@ const e = {
     {
       id: "mobile-nav",
       name: "MobileNav",
-      version: "1.0.0",
-      description: 'A fixed bottom tab bar for mobile screens, providing native-feeling navigation with primary icon+label tabs and a "More" drawer for secondary links. Hidden on md: and up via Tailwind. Designed as the mobile counterpart to the desktop Sidebar.',
+      version: "1.0.3",
+      description: `Mobile navigation, in two shapes. 'bar' is a fixed bottom tab bar with icon+label tabs and a "More" drawer for secondary links. 'sheet' drops the bar entirely and puts every destination in a bottom drawer the host opens from its own trigger — the right choice when a mobile browser's toolbar already owns the bottom edge. Hidden on md: and up via Tailwind. The mobile counterpart to the desktop Sidebar.`,
       tags: [
         "navigation",
         "mobile",
@@ -2669,13 +2706,33 @@ const e = {
           name: "className",
           type: "string",
           description: "Additional CSS classes on the root nav bar."
+        },
+        {
+          name: "variant",
+          type: "string",
+          description: `'bar' (default) renders the fixed bottom tab bar with a "More" Drawer. 'sheet' renders no bar at all and puts every destination in a Sheet — opening at 60% and growing to full as you drag or scroll it up — which the host opens itself — use it when a top header can hold the trigger, since a fixed bar and a mobile browser's own toolbar stack into ~120px of lost screen.`
+        },
+        {
+          name: "isOpen",
+          type: "boolean",
+          description: "Controlled drawer state. Required by 'sheet', which has no trigger of its own; ignored by 'bar'."
+        },
+        {
+          name: "onOpenChange",
+          type: "function",
+          description: "Fired when the sheet wants to close (backdrop, Escape, or an item tapped)."
+        },
+        {
+          name: "children",
+          type: "ReactNode",
+          description: "Extra content rendered in the panel body after the destinations, scrolling with them. The mirror of drawerHeader; use it instead of drawerFooter when the content belongs with the list rather than pinned under it."
         }
       ],
       importPath: "./components/navigation/MobileNav",
       filePath: "src/components/navigation/MobileNav.tsx",
       sku: "@molecule/nav/mobile-nav",
       humanLabel: "MobileNav",
-      humanDescription: 'A fixed bottom tab bar for mobile screens, providing native-feeling navigation with primary icon+label tabs and a "More" drawer for secondary links. Hidden on md: and up via Tailwind. Designed as the mobile counterpart to the desktop Sidebar.'
+      humanDescription: `Mobile navigation, in two shapes. 'bar' is a fixed bottom tab bar with icon+label tabs and a "More" drawer for secondary links. 'sheet' drops the bar entirely and puts every destination in a bottom drawer the host opens from its own trigger — the right choice when a mobile browser's toolbar already owns the bottom edge. Hidden on md: and up via Tailwind. The mobile counterpart to the desktop Sidebar.`
     },
     {
       id: "pagination",
@@ -3614,7 +3671,7 @@ const e = {
     {
       id: "detail-drawer",
       name: "DetailDrawer",
-      version: "1.0.0",
+      version: "1.0.2",
       description: 'A resizable side panel for inspecting one record without leaving the list. Strategic purpose: the master-detail companion — `push` compresses its siblings in a flex layout so the list stays visible and usable, while `overlay` floats above the page like a classic drawer. Use this for "click a row, see the detail" flows; use Modal when the task must block everything else.',
       tags: [
         "layout",
@@ -3639,7 +3696,7 @@ const e = {
         {
           name: "variant",
           type: "string",
-          description: "'push' compresses sibling flex content so the list stays visible; 'overlay' floats fixed above the page. Defaults to push."
+          description: "'push' compresses sibling flex content so the list stays visible; 'overlay' floats fixed above the page. Defaults to overlay."
         },
         {
           name: "side",
@@ -3671,6 +3728,11 @@ const e = {
           type: "number",
           description: "Upper bound for resizing. Defaults to 60% of the window width."
         },
+        {
+          name: "title",
+          type: "string",
+          description: 'Names the panel for assistive technology. Not rendered: there is no header row to put it in, and adding one is a design decision. Without it an overlay announces only as "dialog".'
+        },
         {
           name: "children",
           type: "ReactNode",
@@ -4086,6 +4148,69 @@ const e = {
       humanLabel: "SettingsContainer",
       humanDescription: "The canonical settings page arrangement, with a fixed slot per section so every app's settings read the same way. Strategic purpose: settings sprawl fast — this pins the section order and navigation so General, AI Gateway, Theme Lab, and About always live in the same place."
     },
+    {
+      id: "sheet",
+      name: "Sheet",
+      version: "1.0.0",
+      description: "A bottom sheet that opens at a partial height and grows to full screen as you drag or scroll it up. Strategic purpose: the native-feeling surface for mobile navigation, settings and pickers — reachable by thumb, dismissed by flicking down. Use instead of Drawer when the surface is primarily touched.",
+      tags: [
+        "layout",
+        "overlay",
+        "sheet",
+        "mobile",
+        "touch",
+        "drawer",
+        "ui"
+      ],
+      category: "layout",
+      props: [
+        {
+          name: "isOpen",
+          type: "boolean",
+          description: "Controls the open/closed state. Required."
+        },
+        {
+          name: "onClose",
+          type: "function",
+          description: "Fired when the sheet requests dismissal (flick down, drag below the smallest detent, Escape, overlay tap, or the close button). Required."
+        },
+        {
+          name: "detents",
+          type: "Array<number>",
+          description: "Resting heights as fractions of the viewport, ascending. Defaults to [0.6, 1] — opens at 60%, expands to full."
+        },
+        {
+          name: "initialDetent",
+          type: "number",
+          description: "Index into detents to open at. Defaults to 0."
+        },
+        {
+          name: "title",
+          type: "string",
+          description: "Optional title in the sticky header, beside the close button."
+        },
+        {
+          name: "footer",
+          type: "ReactNode",
+          description: "Optional sticky footer, kept clear of the home indicator."
+        },
+        {
+          name: "overlayDismiss",
+          type: "boolean",
+          description: "Tap the dimmed backdrop to close. Defaults to true."
+        },
+        {
+          name: "className",
+          type: "string",
+          description: "Extra classes for the sheet panel."
+        }
+      ],
+      importPath: "./components/layout/Sheet",
+      filePath: "src/components/layout/Sheet.tsx",
+      sku: "@chassis/layout/sheet",
+      humanLabel: "Sheet",
+      humanDescription: "A bottom sheet that opens at a partial height and grows to full screen as you drag or scroll it up. Strategic purpose: the native-feeling surface for mobile navigation, settings and pickers — reachable by thumb, dismissed by flicking down. Use instead of Drawer when the surface is primarily touched."
+    },
     {
       id: "sidebar",
       name: "Sidebar",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ramme-io/ui",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "The structural component library for the Ramme Framework.",
   "license": "MIT",
   "private": false,
@@ -61,6 +61,8 @@
     "@storybook/addon-themes": "^10.5.9",
     "@storybook/react": "^10.5.9",
     "@storybook/react-vite": "^10.5.9",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
     "@types/doctrine": "^0.0.9",
     "@types/node": "^20.12.12",
     "@types/react": "^18.3.23",
@@ -70,16 +72,21 @@
     "ag-grid-community": "^31.3.2",
     "ag-grid-react": "^31.3.2",
     "autoprefixer": "^10.4.19",
+    "axe-core": "^4.13.0",
     "doctrine": "^3.0.0",
+    "jsdom": "^29.0.0",
     "postcss": "^8.4.38",
     "storybook": "^10.5.9",
     "tailwindcss": "^3.4.4",
     "typescript": "^5.4.5",
     "vite": "^5.3.1",
-    "vite-plugin-dts": "^3.9.1"
+    "vite-plugin-dts": "^3.9.1",
+    "vitest": "^2.1.9",
+    "vitest-axe": "^0.1.0"
   },
   "scripts": {
     "dev": "vite",
+    "test": "vitest run",
     "generate:manifest": "node scripts/generate-manifest.js",
     "generate:registry": "node scripts/generate-registry.js",
     "generate": "npm run generate:manifest && npm run generate:registry",