@kennycorrea/ui 0.8.1 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.9.0 — 2026-10-18
+
+### Added
+- **`Drawer`**, a bottom sheet with `collapsed` and `expanded` snap points, in two modes:
+  `modal` (scrim, focus trapped, page `inert`, Escape and scrim close) and `non-modal` (a
+  floating banner; the page stays usable). Drag the header with touch or mouse to change snap,
+  or past collapsed to close when `dismissible`. The handle is a real button with
+  `aria-expanded`/`aria-controls`. Controlled or uncontrolled `open` and `snap`.
+- **`UiStrings`: `close`, `expand`, `collapse`**, used by the Drawer's close button and handle.
+  English defaults; the `closeLabel`, `expandLabel` and `collapseLabel` props override them.
+- `examples/Drawers.tsx`: a non-modal promo banner and a modal form sheet.
+
+### Not verified
+- Only exercised in jsdom with simulated pointer events, not on a real touch device.
+
 ## 0.8.1 — 2026-10-11
 
 ### Fixed

package/README.md

@@ -310,3 +310,38 @@ is in `examples/BudgetCycleSlider.tsx`.
 
 ⚠ `--ui-slider-thumb-size` mirrors Themes' size-2 thumb (`--space-2 + --space-1`). The fill
 and the marks are placed from it, so if Themes ever resizes its thumb, change it there.
+
+## Drawer — bottom sheet
+
+A sheet anchored to the bottom of the viewport: full width on phones, `max-w-lg` and centred
+above that (`maxWidthClassName` to change it), safe-area aware, themed from the house tokens.
+
+```tsx
+// Non-modal: a floating banner, the page stays usable, no focus trap.
+<Drawer mode="non-modal" title="Take deposits" peek={<p>Swipe up to see how.</p>}
+  footer={<Button>Get started</Button>}>
+  <ol>…steps…</ol>
+</Drawer>
+
+// Modal: scrim, focus trapped, page inert, Escape and the scrim close it.
+<Drawer open={open} onOpenChange={setOpen} defaultSnap="expanded" title="New client"
+  showCloseButton footer={<Button type="submit" form="f">Save</Button>}>
+  <form id="f">…</form>
+</Drawer>
+```
+
+- **Snap points** `collapsed` (header + `peek`) and `expanded` (body, scrolls inside, up to
+  80vh). Controlled with `snap`/`onSnapChange`, or uncontrolled from `defaultSnap`; likewise
+  `open`/`onOpenChange`/`defaultOpen`.
+- **Drag** the header with touch or mouse: it follows the pointer, then settles past 60px or a
+  flick faster than 0.5px/ms. Down from collapsed closes when `dismissible` (the default).
+  A drag from inside the body counts only when the body is scrolled to the top and moving down.
+- **The handle is a real button** with `aria-expanded`/`aria-controls`, so keyboard and screen
+  reader users toggle it the same way.
+- **No words of its own.** The handle and close button names come from `expandLabel`,
+  `collapseLabel` and `closeLabel`, or the new `expand`, `collapse` and `close` keys of
+  `UiStringsProvider`.
+- Motion is a CSS transform, switched off under `prefers-reduced-motion`.
+
+Built by hand rather than on Radix Dialog because the non-modal half must not do what Dialog
+does to the rest of the page. Both examples are in `examples/Drawers.tsx`.

package/dist/atoms/Drawer/Drawer.d.ts

@@ -0,0 +1,62 @@
+import { type ReactNode } from 'react';
+/** The two resting heights of a drawer. */
+export type DrawerSnap = 'collapsed' | 'expanded';
+/** `modal` traps focus behind a scrim; `non-modal` floats over a page that stays usable. */
+export type DrawerMode = 'modal' | 'non-modal';
+export interface DrawerProps {
+    /** `modal` (scrim, focus trap, inert page) or `non-modal` (floating banner). Default `modal`. */
+    mode?: DrawerMode;
+    /** Controlled visibility. Leave undefined to let the drawer own it. */
+    open?: boolean;
+    /** Initial visibility when uncontrolled. Default `true`. */
+    defaultOpen?: boolean;
+    /** Called whenever the drawer asks to open or close. */
+    onOpenChange?: (open: boolean) => void;
+    /** Called once when the drawer closes, after `onOpenChange(false)`. */
+    onClose?: () => void;
+    /** Controlled snap point. */
+    snap?: DrawerSnap;
+    /** Initial snap point when uncontrolled. Default `collapsed`. */
+    defaultSnap?: DrawerSnap;
+    /** Called whenever the drawer asks to change snap point. */
+    onSnapChange?: (snap: DrawerSnap) => void;
+    /** Whether dragging past collapsed (or the close button, Escape, the scrim) may close it. Default `true`. */
+    dismissible?: boolean;
+    /** Labels the region via `aria-labelledby`. */
+    title: ReactNode;
+    /** Optional, wired up via `aria-describedby`. */
+    description?: ReactNode;
+    /** Shown while collapsed, below the header. */
+    peek?: ReactNode;
+    /** The body, shown when expanded; scrolls inside the sheet. */
+    children?: ReactNode;
+    /** Action row pinned below the body. Shown in both snaps. */
+    footer?: ReactNode;
+    /** Render a close button in the header. Default `false`. */
+    showCloseButton?: boolean;
+    /** Overrides the close button's accessible name (otherwise the `close` UI string). */
+    closeLabel?: string;
+    /** Overrides the handle's accessible name while collapsed (otherwise the `expand` UI string). */
+    expandLabel?: string;
+    /** Overrides the handle's accessible name while expanded (otherwise the `collapse` UI string). */
+    collapseLabel?: string;
+    /** Caps the width on wider screens. Default `max-w-lg`; pass `max-w-none` for full width. */
+    maxWidthClassName?: string;
+    className?: string;
+    /** Where the portal mounts. Default `document.body`. */
+    container?: HTMLElement | null;
+}
+/**
+ * A bottom sheet with two snap points and a drag handle.
+ *
+ * Built by hand rather than on Radix Dialog because half of it is non-modal: Dialog's focus
+ * trap and `aria-hidden` on the rest of the page are exactly what a floating banner must not do.
+ * In `modal` mode the same guarantees are provided here — the page's other top-level nodes are
+ * made `inert` and Tab cycles inside the sheet.
+ *
+ * Dragging follows the pointer with a transform and, on release, settles on the snap point the
+ * gesture points at: past {@link DISTANCE} pixels or faster than {@link VELOCITY} px/ms. A drag
+ * from inside the body only counts when the body is scrolled to its top and moving down, so the
+ * content still scrolls normally.
+ */
+export declare function Drawer({ mode, open: openProp, defaultOpen, onOpenChange, onClose, snap: snapProp, defaultSnap, onSnapChange, dismissible, title, description, peek, children, footer, showCloseButton, closeLabel, expandLabel, collapseLabel, maxWidthClassName, className, container, }: DrawerProps): import("react").ReactPortal | null;

package/dist/atoms/Drawer/Drawer.js

@@ -0,0 +1,190 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useId, useRef, useState, } from 'react';
+import { createPortal } from 'react-dom';
+import { useUiStrings } from '../../strings.js';
+import { cn } from '../../utils/cn.js';
+/** Pixels of travel that commit a drag regardless of speed. */
+const DISTANCE = 60;
+/** Pixels per millisecond that commit a flick regardless of distance. */
+const VELOCITY = 0.5;
+const FOCUSABLE = 'a[href],button:not([disabled]),input:not([disabled]),select:not([disabled]),textarea:not([disabled]),[tabindex]:not([tabindex="-1"])';
+function useControllable(value, initial, onChange) {
+    const [inner, setInner] = useState(initial);
+    const controlled = value !== undefined;
+    const current = controlled ? value : inner;
+    const set = useCallback((next) => {
+        if (!controlled)
+            setInner(next);
+        onChange?.(next);
+    }, [controlled, onChange]);
+    return [current, set];
+}
+/**
+ * A bottom sheet with two snap points and a drag handle.
+ *
+ * Built by hand rather than on Radix Dialog because half of it is non-modal: Dialog's focus
+ * trap and `aria-hidden` on the rest of the page are exactly what a floating banner must not do.
+ * In `modal` mode the same guarantees are provided here — the page's other top-level nodes are
+ * made `inert` and Tab cycles inside the sheet.
+ *
+ * Dragging follows the pointer with a transform and, on release, settles on the snap point the
+ * gesture points at: past {@link DISTANCE} pixels or faster than {@link VELOCITY} px/ms. A drag
+ * from inside the body only counts when the body is scrolled to its top and moving down, so the
+ * content still scrolls normally.
+ */
+export function Drawer({ mode = 'modal', open: openProp, defaultOpen = true, onOpenChange, onClose, snap: snapProp, defaultSnap = 'collapsed', onSnapChange, dismissible = true, title, description, peek, children, footer, showCloseButton = false, closeLabel, expandLabel, collapseLabel, maxWidthClassName = 'max-w-lg', className, container, }) {
+    const strings = useUiStrings();
+    const [open, setOpen] = useControllable(openProp, defaultOpen, onOpenChange);
+    const [snap, setSnap] = useControllable(snapProp, defaultSnap, onSnapChange);
+    const [offset, setOffset] = useState(0);
+    const [dragging, setDragging] = useState(false);
+    const drag = useRef(null);
+    const suppressClick = useRef(false);
+    const sheetRef = useRef(null);
+    const bodyRef = useRef(null);
+    const wrapperRef = useRef(null);
+    const id = useId();
+    const titleId = `${id}-title`;
+    const descId = `${id}-desc`;
+    const bodyId = `${id}-body`;
+    const modal = mode === 'modal';
+    const expanded = snap === 'expanded';
+    const close = useCallback(() => {
+        setOpen(false);
+        onClose?.();
+    }, [setOpen, onClose]);
+    // Modal: everything else on the page goes inert, focus moves in, and comes back on close.
+    useEffect(() => {
+        if (!open || !modal)
+            return;
+        const wrapper = wrapperRef.current;
+        const root = wrapper?.parentElement;
+        const previous = document.activeElement;
+        const made = [];
+        if (root) {
+            for (const el of Array.from(root.children)) {
+                if (el !== wrapper && !el.hasAttribute('inert')) {
+                    el.setAttribute('inert', '');
+                    made.push(el);
+                }
+            }
+        }
+        const first = sheetRef.current?.querySelector(FOCUSABLE);
+        (first ?? sheetRef.current)?.focus();
+        return () => {
+            for (const el of made)
+                el.removeAttribute('inert');
+            previous?.focus?.();
+        };
+    }, [open, modal]);
+    useEffect(() => {
+        if (!open || !modal || !dismissible)
+            return;
+        const onKey = (e) => {
+            if (e.key === 'Escape')
+                close();
+        };
+        document.addEventListener('keydown', onKey);
+        return () => document.removeEventListener('keydown', onKey);
+    }, [open, modal, dismissible, close]);
+    const trapTab = (e) => {
+        if (!modal || e.key !== 'Tab' || !sheetRef.current)
+            return;
+        const items = Array.from(sheetRef.current.querySelectorAll(FOCUSABLE));
+        if (items.length === 0)
+            return;
+        const first = items[0];
+        const last = items[items.length - 1];
+        if (e.shiftKey && document.activeElement === first) {
+            e.preventDefault();
+            last.focus();
+        }
+        else if (!e.shiftKey && document.activeElement === last) {
+            e.preventDefault();
+            first.focus();
+        }
+    };
+    const begin = (e, fromBody) => {
+        if (e.button !== 0)
+            return;
+        if (fromBody && (!expanded || (bodyRef.current?.scrollTop ?? 0) > 0))
+            return;
+        drag.current = {
+            pointerId: e.pointerId,
+            startY: e.clientY,
+            lastY: e.clientY,
+            lastT: e.timeStamp,
+            velocity: 0,
+            moved: false,
+            fromBody,
+        };
+    };
+    const move = (e) => {
+        const d = drag.current;
+        if (!d || d.pointerId !== e.pointerId)
+            return;
+        const dy = e.clientY - d.startY;
+        if (!d.moved) {
+            if (Math.abs(dy) < 4)
+                return;
+            // Scrolling up inside the body is the content's business, not ours.
+            if (d.fromBody && dy < 0) {
+                drag.current = null;
+                return;
+            }
+            d.moved = true;
+            setDragging(true);
+            e.currentTarget.setPointerCapture?.(e.pointerId);
+        }
+        // At least one frame, so two events in the same tick do not read as an infinite flick.
+        const dt = Math.max(16, e.timeStamp - d.lastT);
+        d.velocity = (e.clientY - d.lastY) / dt;
+        d.lastY = e.clientY;
+        d.lastT = e.timeStamp;
+        // Past the top snap the sheet resists rather than detaching.
+        setOffset(dy < 0 && expanded ? dy / 4 : dy);
+    };
+    const end = (e) => {
+        const d = drag.current;
+        if (!d || d.pointerId !== e.pointerId)
+            return;
+        drag.current = null;
+        if (!d.moved)
+            return;
+        suppressClick.current = true;
+        const dy = e.clientY - d.startY;
+        const up = dy < -DISTANCE || d.velocity < -VELOCITY;
+        const down = dy > DISTANCE || d.velocity > VELOCITY;
+        setDragging(false);
+        setOffset(0);
+        if (up && !expanded)
+            setSnap('expanded');
+        else if (down && expanded)
+            setSnap('collapsed');
+        else if (down && dismissible)
+            close();
+    };
+    const cancel = () => {
+        drag.current = null;
+        setDragging(false);
+        setOffset(0);
+    };
+    const onHandleClick = () => {
+        if (suppressClick.current) {
+            suppressClick.current = false;
+            return;
+        }
+        setSnap(expanded ? 'collapsed' : 'expanded');
+    };
+    if (!open)
+        return null;
+    const target = container ?? (typeof document === 'undefined' ? null : document.body);
+    if (!target)
+        return null;
+    const dragHandlers = {
+        onPointerMove: move,
+        onPointerUp: end,
+        onPointerCancel: cancel,
+    };
+    return createPortal(_jsxs("div", { ref: wrapperRef, "data-drawer-root": "", children: [modal ? (_jsx("div", { "data-testid": "drawer-scrim", "aria-hidden": "true", className: "fixed inset-0 z-40 bg-scrim", onClick: dismissible ? close : undefined })) : null, _jsxs("div", { ref: sheetRef, role: modal ? 'dialog' : 'region', "aria-modal": modal ? true : undefined, "aria-labelledby": titleId, "aria-describedby": description ? descId : undefined, tabIndex: -1, "data-snap": snap, "data-mode": mode, onKeyDown: trapTab, style: { transform: `translateY(${Math.max(offset, -40)}px)` }, className: cn('fixed inset-x-0 bottom-0 z-50 mx-auto flex w-full flex-col', 'rounded-t-2xl border border-b-0 border-hairline bg-sheet text-ink shadow-2xl', 'pb-[env(safe-area-inset-bottom)] outline-none', !dragging && 'transition-transform duration-200 ease-out motion-reduce:transition-none', maxWidthClassName, className), children: [_jsxs("div", { className: "touch-none select-none px-5 pt-2", onPointerDown: (e) => begin(e, false), ...dragHandlers, children: [_jsx("button", { type: "button", "aria-expanded": expanded, "aria-controls": bodyId, "aria-label": expanded ? (collapseLabel ?? strings.collapse) : (expandLabel ?? strings.expand), onClick: onHandleClick, className: "mx-auto flex h-6 w-16 cursor-grab items-center justify-center rounded-full focus-visible:outline-2 focus-visible:outline-brand-700 active:cursor-grabbing", children: _jsx("span", { "aria-hidden": "true", className: "h-1.5 w-10 rounded-full bg-hairline" }) }), _jsxs("div", { className: "flex items-start gap-3 pb-3 pt-1", children: [_jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("h2", { id: titleId, className: "m-0 text-base font-medium text-brand-900", children: title }), description ? (_jsx("p", { id: descId, className: "m-0 mt-1 text-sm text-ink-muted", children: description })) : null] }), showCloseButton && dismissible ? (_jsx("button", { type: "button", "aria-label": closeLabel ?? strings.close, onClick: close, className: "-mr-1 flex size-8 shrink-0 items-center justify-center rounded-full text-ink-muted hover:bg-brand-700/8 focus-visible:outline-2 focus-visible:outline-brand-700", children: _jsx("svg", { "aria-hidden": "true", width: "15", height: "15", viewBox: "0 0 15 15", fill: "none", children: _jsx("path", { d: "M3.5 3.5l8 8m0-8l-8 8", stroke: "currentColor", strokeWidth: "1.5", strokeLinecap: "round" }) }) })) : null] })] }), !expanded && peek ? _jsx("div", { className: "px-5 pb-4", children: peek }) : null, _jsx("div", { ref: bodyRef, id: bodyId, hidden: !expanded, className: "max-h-[80vh] overflow-y-auto overscroll-contain px-5 pb-4", onPointerDown: (e) => begin(e, true), ...dragHandlers, children: children }), footer ? (_jsx("div", { className: "flex justify-end gap-2 border-t border-hairline px-5 py-3", children: footer })) : null] })] }), target);
+}

package/dist/atoms/Drawer/index.d.ts

@@ -0,0 +1 @@
+export * from './Drawer.js';

package/dist/atoms/Drawer/index.js

@@ -0,0 +1 @@
+export * from './Drawer.js';

package/dist/atoms/index.d.ts

@@ -6,6 +6,7 @@ export * from './Card/index.js';
 export * from './Checkbox/index.js';
 export * from './ContextMenu/index.js';
 export * from './Dialog/index.js';
+export * from './Drawer/index.js';
 export * from './Icon/index.js';
 export * from './Input/index.js';
 export * from './Label/index.js';

package/dist/atoms/index.js

@@ -6,6 +6,7 @@ export * from './Card/index.js';
 export * from './Checkbox/index.js';
 export * from './ContextMenu/index.js';
 export * from './Dialog/index.js';
+export * from './Drawer/index.js';
 export * from './Icon/index.js';
 export * from './Input/index.js';
 export * from './Label/index.js';

package/dist/strings.d.ts

@@ -28,6 +28,12 @@ export interface UiStrings {
     heading: string;
     bulletList: string;
     orderedList: string;
+    /** Drawer: the close button's accessible name. */
+    close: string;
+    /** Drawer: the handle's accessible name while collapsed. */
+    expand: string;
+    /** Drawer: the handle's accessible name while expanded. */
+    collapse: string;
 }
 /**
  * Feeds the atoms their strings, once, near the root.

package/dist/strings.js

@@ -11,6 +11,9 @@ const DEFAULTS = {
     heading: 'Heading',
     bulletList: 'Bulleted list',
     orderedList: 'Numbered list',
+    close: 'Close',
+    expand: 'Expand',
+    collapse: 'Collapse',
 };
 const StringsContext = createContext(DEFAULTS);
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kennycorrea/ui",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Upfront's house component layer: atoms over Radix Themes, the token bridge, and the accent logic.",
   "private": false,
   "type": "module",