@kennycorrea/ui 0.11.4 → 1.7.0

package/dist/atoms/ActionSheet/confirm.js

@@ -25,7 +25,7 @@ function subscribe(l) {
  * Asks and resolves `true` on accept, `false` on Cancel, Escape or any other dismissal.
  * Never rejects.
  *
- *     if (await confirm({ title: 'Delete booking?', confirmLabel: 'Delete', tone: 'danger' })) …
+ *     if (await confirm({ title: 'Delete item?', confirmLabel: 'Delete', tone: 'danger' })) …
  */
 export function confirm(options) {
     return new Promise((resolve) => emit([...queue, { ...options, resolve }]));

package/dist/atoms/Avatar/Avatar.d.ts

@@ -1,5 +1,5 @@
 export interface AvatarProps {
-    /** Absent for most providers — the fallback is the normal case, not the error case. */
+    /** Often absent — the fallback is the normal case, not the error case. */
     src?: string;
     name?: string;
     className?: string;

package/dist/atoms/Badge/Badge.js

@@ -5,12 +5,12 @@ import { warnMissingScales } from '../../utils/scales.js';
  * The five meanings this library names, in Themes' colour vocabulary.
  *
  * **`brand` names no colour on purpose.** Themes falls back to whatever accent the theme
- * carries, so a badge that means "this is ours" follows the business's chosen colour while
+ * carries, so a badge that means "this is ours" follows the app's chosen colour while
  * the four that mean something specific do not. It said `jade` until accents became
- * choosable, which left the service badges green on a purple dashboard.
+ * choosable, which left brand badges green in a purple-accented app.
  *
- * `success` is jade and stays jade. Green means fine in a way purple does not, and a shop
- * that liked orange should not end up with an orange "paid".
+ * `success` is jade and stays jade. Green means fine in a way purple does not, and an app
+ * whose accent is orange should not end up with an orange "paid".
  */
 const COLORS = {
     neutral: 'gray',

package/dist/atoms/Button/Button.js

@@ -5,10 +5,9 @@ import { cn } from '../../utils/cn.js';
 /**
  * The house intents, expressed in Radix Themes' variant-and-colour vocabulary.
  *
- * The mapping exists so three apps keep saying `variant="danger"` rather than
+ * The mapping exists so apps keep saying `variant="danger"` rather than
  * `variant="solid" color="red"` at sixty call sites — and so that when the house style changes
- * its mind about what "secondary" looks like, it changes here and everywhere at once. That
- * second half is what the dashboard and the site did not have, and why they drifted.
+ * its mind about what "secondary" looks like, it changes here and everywhere at once.
  */
 const VARIANTS = {
     primary: { variant: 'solid' },

package/dist/atoms/Button/Button.types.d.ts

@@ -3,13 +3,10 @@ import type { ComponentPropsWithoutRef, ReactNode } from 'react';
 /**
  * The house button intents.
  *
- * **`outline` is new, and it is how the disagreement was resolved.** The dashboard's
- * `secondary` mapped to Themes' `soft` and the marketing site's mapped to `surface` — the same
- * word meaning two things in two products, which is what `docs/ecosystem.md` named as the cost
- * of three repositories with nothing shared. Making one of them win would have been a decision
- * about the word rather than about the need: the site wants the bordered, translucent button
- * because it sits over a dark hero, and the dashboard wants the tinted one because it sits on a
- * panel. So `secondary` means exactly one thing everywhere and the other look has its own name.
+ * **`secondary` and `outline` are two looks with two names.** `secondary` is Themes' `soft`, a
+ * tinted button for use on a panel. `outline` is Themes' `surface`, a bordered, translucent
+ * button for use over a dark or busy background. One word for both would mean different things
+ * in different places, so each look has its own name.
  */
 export type ButtonVariant = 'primary' | 'secondary' | 'outline' | 'ghost' | 'danger';
 /** `touch` is `md` type with a 44px minimum height, for primary actions on touch screens. */
@@ -37,7 +34,7 @@ export interface ButtonProps extends Omit<ComponentPropsWithoutRef<typeof Themed
     /**
      * Renders an anchor, keeping Radix's focus ring and sizing.
      *
-     * From the marketing site, where almost every button is a link. It is `asChild` underneath,
+     * For pages where most buttons are really links. It is `asChild` underneath,
      * so the anchor stays an anchor — middle-click, copy link, the lot — and it is here rather
      * than left to each app because "a button that is really a link" is a house concern.
      */

package/dist/atoms/ContextMenu/ContextMenu.d.ts

@@ -17,7 +17,7 @@ export interface ContextMenuProps extends Omit<HTMLAttributes<HTMLElement>, 'onS
  * The menu a right-click opens, in the house vocabulary.
  *
  * Items are data rather than children, like `Select`'s options, because every caller
- * builds them from something — a booking's status decides which of them make sense.
+ * builds them from something — a record's status decides which of them make sense.
  *
  * **A shortcut, never the only way.** Right-click is invisible, mouse-only and absent on
  * touch, so everything here also has a path through the form the block opens on click.

package/dist/atoms/ContextMenu/ContextMenu.js

@@ -5,7 +5,7 @@ import { Fragment, forwardRef } from 'react';
  * The menu a right-click opens, in the house vocabulary.
  *
  * Items are data rather than children, like `Select`'s options, because every caller
- * builds them from something — a booking's status decides which of them make sense.
+ * builds them from something — a record's status decides which of them make sense.
  *
  * **A shortcut, never the only way.** Right-click is invisible, mouse-only and absent on
  * touch, so everything here also has a path through the form the block opens on click.

package/dist/atoms/Icon/Icon.d.ts

@@ -1,12 +1,10 @@
-/**
- * The handful of icons this app actually uses, drawn inline.
- *
- * No icon library: a dependency for twelve glyphs costs more in bundle and upgrade surface
- * than it saves, and these are all one or two paths. They inherit `currentColor` and size
- * with the text around them, which is what makes them work in a collapsed sidebar and a
- * button alike.
- */
 declare const PATHS: {
+    readonly home: "M3 12l9-8 9 8M5 10v10h5v-6h4v6h5V10";
+    readonly list: "M4 7h16M4 12h16M4 17h10";
+    readonly calendar: "M7 3v3M17 3v3M4 8h16M5 6h14a1 1 0 011 1v12a1 1 0 01-1 1H5a1 1 0 01-1-1V7a1 1 0 011-1z";
+    readonly users: "M16 20v-2a4 4 0 00-4-4H7a4 4 0 00-4 4v2M9.5 9.5a3 3 0 100-6 3 3 0 000 6zM21 20v-2a4 4 0 00-3-3.87";
+    readonly card: "M3 7h18v12H3zM3 11h18M7 15h3";
+    readonly document: "M14 3H7a1 1 0 00-1 1v16a1 1 0 001 1h10a1 1 0 001-1V7zM14 3v4h4M9 13h6M9 17h4";
     readonly overview: "M3 12l9-8 9 8M5 10v10h5v-6h4v6h5V10";
     readonly services: "M4 7h16M4 12h16M4 17h10";
     readonly bookings: "M7 3v3M17 3v3M4 8h16M5 6h14a1 1 0 011 1v12a1 1 0 01-1 1H5a1 1 0 01-1-1V7a1 1 0 011-1z";
@@ -44,7 +42,7 @@ export interface IconProps {
      * A label makes it an image with a name; leaving it out makes it decoration.
      *
      * Decoration is the right answer whenever adjacent text already says the same thing —
-     * a screen reader announcing "Bookings, Bookings" is worse than saying it once.
+     * a screen reader announcing "Settings, Settings" is worse than saying it once.
      */
     label?: string;
 }

package/dist/atoms/Icon/Icon.js

@@ -1,20 +1,35 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { cn } from '../../utils/cn.js';
 /**
- * The handful of icons this app actually uses, drawn inline.
+ * A small set of interface icons, drawn inline. For anything else, use `@radix-ui/react-icons`
+ * (re-exported from this package).
  *
- * No icon library: a dependency for twelve glyphs costs more in bundle and upgrade surface
+ * No icon library: a dependency for a few dozen glyphs costs more in bundle and upgrade surface
  * than it saves, and these are all one or two paths. They inherit `currentColor` and size
  * with the text around them, which is what makes them work in a collapsed sidebar and a
  * button alike.
  */
+const HOME = 'M3 12l9-8 9 8M5 10v10h5v-6h4v6h5V10';
+const LIST = 'M4 7h16M4 12h16M4 17h10';
+const CALENDAR = 'M7 3v3M17 3v3M4 8h16M5 6h14a1 1 0 011 1v12a1 1 0 01-1 1H5a1 1 0 01-1-1V7a1 1 0 011-1z';
+const USERS = 'M16 20v-2a4 4 0 00-4-4H7a4 4 0 00-4 4v2M9.5 9.5a3 3 0 100-6 3 3 0 000 6zM21 20v-2a4 4 0 00-3-3.87';
+const CARD = 'M3 7h18v12H3zM3 11h18M7 15h3';
+const DOCUMENT = 'M14 3H7a1 1 0 00-1 1v16a1 1 0 001 1h10a1 1 0 001-1V7zM14 3v4h4M9 13h6M9 17h4';
 const PATHS = {
-    overview: 'M3 12l9-8 9 8M5 10v10h5v-6h4v6h5V10',
-    services: 'M4 7h16M4 12h16M4 17h10',
-    bookings: 'M7 3v3M17 3v3M4 8h16M5 6h14a1 1 0 011 1v12a1 1 0 01-1 1H5a1 1 0 01-1-1V7a1 1 0 011-1z',
-    clients: 'M16 20v-2a4 4 0 00-4-4H7a4 4 0 00-4 4v2M9.5 9.5a3 3 0 100-6 3 3 0 000 6zM21 20v-2a4 4 0 00-3-3.87',
-    payments: 'M3 7h18v12H3zM3 11h18M7 15h3',
-    compliance: 'M14 3H7a1 1 0 00-1 1v16a1 1 0 001 1h10a1 1 0 001-1V7zM14 3v4h4M9 13h6M9 17h4',
+    home: HOME,
+    list: LIST,
+    calendar: CALENDAR,
+    users: USERS,
+    card: CARD,
+    document: DOCUMENT,
+    // Legacy names for the six above, named after what one app used them for. Kept so nothing
+    // that already passes them breaks; prefer the names above in new code.
+    overview: HOME,
+    services: LIST,
+    bookings: CALENDAR,
+    clients: USERS,
+    payments: CARD,
+    compliance: DOCUMENT,
     settings: 'M12 15.5a3.5 3.5 0 100-7 3.5 3.5 0 000 7zM19.4 15a1.65 1.65 0 00.33 1.82l.06.06a2 2 0 11-2.83 2.83l-.06-.06a1.65 1.65 0 00-1.82-.33 1.65 1.65 0 00-1 1.51V21a2 2 0 11-4 0v-.09A1.65 1.65 0 008 19.4a1.65 1.65 0 00-1.82.33l-.06.06a2 2 0 11-2.83-2.83l.06-.06A1.65 1.65 0 004.6 15a1.65 1.65 0 00-1.51-1H3a2 2 0 110-4h.09A1.65 1.65 0 004.6 9a1.65 1.65 0 00-.33-1.82l-.06-.06a2 2 0 112.83-2.83l.06.06A1.65 1.65 0 009 4.6a1.65 1.65 0 001-1.51V3a2 2 0 114 0v.09a1.65 1.65 0 001 1.51 1.65 1.65 0 001.82-.33l.06-.06a2 2 0 112.83 2.83l-.06.06A1.65 1.65 0 0019.4 9c.14.35.4.65.73.85',
     collapse: 'M15 6l-6 6 6 6',
     expand: 'M9 6l6 6-6 6',

package/dist/atoms/Pill/Pill.d.ts

@@ -0,0 +1,17 @@
+import type { ReactNode } from 'react';
+export interface PillProps {
+    children: ReactNode;
+    /** Shows a remove button. */
+    onRemove?: () => void;
+    /**
+     * The remove button's name. Default: the `remove` UI string with the pill's text, which
+     * needs `children` to be a string; pass this when it is not.
+     */
+    removeLabel?: string;
+    className?: string;
+}
+/**
+ * A small token, removable or not: an active filter, a chosen tag. The remove button has its
+ * own name ("Remove Status: Active"), and a 44px hit area on touch screens.
+ */
+export declare function Pill({ children, onRemove, removeLabel, className }: PillProps): import("react").JSX.Element;

package/dist/atoms/Pill/Pill.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Cross2Icon } from '@radix-ui/react-icons';
+import { useUiStrings } from '../../strings.js';
+/**
+ * A small token, removable or not: an active filter, a chosen tag. The remove button has its
+ * own name ("Remove Status: Active"), and a 44px hit area on touch screens.
+ */
+export function Pill({ children, onRemove, removeLabel, className }) {
+    const strings = useUiStrings();
+    const label = removeLabel ?? (typeof children === 'string' ? strings.remove(children) : undefined);
+    return (_jsxs("span", { className: ['ui-pill', className].filter(Boolean).join(' '), "data-removable": onRemove ? '' : undefined, children: [children, onRemove ? (_jsx("button", { type: "button", className: "ui-pill__remove", "aria-label": label, onClick: onRemove, children: _jsx(Cross2Icon, { "aria-hidden": "true" }) })) : null] }));
+}

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

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

package/dist/atoms/Pill/index.js

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

package/dist/atoms/ResponsiveDialog/ResponsiveDialog.d.ts

@@ -1,13 +1,20 @@
+import { type Breakpoint } from '../../hooks/breakpoints.js';
 import { type DialogProps } from '../Dialog/Dialog.js';
 import { type SheetDetent } from '../Sheet/Sheet.js';
 export interface ResponsiveDialogProps extends DialogProps {
-    /** The detent the sheet opens at below `md`. Default `fit`. */
+    /** The detent the sheet opens at below `breakpoint`. Default `fit`. */
     sheetDetent?: SheetDetent;
+    /**
+     * From this breakpoint up it is a Dialog; below it, a Sheet. Default `sm` (768px), which is
+     * what Tailwind calls `md`.
+     */
+    breakpoint?: Breakpoint;
 }
 /**
  * The same props as {@link Dialog}, presented the way the screen asks: a centred dialog on a
  * desktop, a bottom sheet on a phone. Both sit on Radix Dialog, so the role, the focus trap,
  * Escape and the labelling are the same either way. Crossing the breakpoint while open remounts
  * the content, which loses uncommitted state inside `children` — keep form state in the parent.
+ * Without `matchMedia` (SSR) it renders the Dialog.
  */
-export declare function ResponsiveDialog({ sheetDetent, ...props }: ResponsiveDialogProps): import("react").JSX.Element;
+export declare function ResponsiveDialog({ sheetDetent, breakpoint, ...props }: ResponsiveDialogProps): import("react").JSX.Element;

package/dist/atoms/ResponsiveDialog/ResponsiveDialog.js

@@ -1,27 +1,18 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useSyncExternalStore } from 'react';
+import { minWidth } from '../../hooks/breakpoints.js';
+import { useMediaQuery } from '../../hooks/useMediaQuery.js';
 import { Dialog } from '../Dialog/Dialog.js';
 import { Sheet } from '../Sheet/Sheet.js';
-/** Tailwind's `md`. Below it the dialog becomes a bottom sheet. */
-const MD = '(min-width: 768px)';
-function subscribe(onChange) {
-    const query = window.matchMedia(MD);
-    query.addEventListener('change', onChange);
-    return () => query.removeEventListener('change', onChange);
-}
-/** A Dialog at `md` and up, a Sheet below. Without `matchMedia` (SSR) the Dialog. */
-function useIsMdUp() {
-    return useSyncExternalStore(subscribe, () => window.matchMedia(MD).matches, () => true);
-}
 /**
  * The same props as {@link Dialog}, presented the way the screen asks: a centred dialog on a
  * desktop, a bottom sheet on a phone. Both sit on Radix Dialog, so the role, the focus trap,
  * Escape and the labelling are the same either way. Crossing the breakpoint while open remounts
  * the content, which loses uncommitted state inside `children` — keep form state in the parent.
+ * Without `matchMedia` (SSR) it renders the Dialog.
  */
-export function ResponsiveDialog({ sheetDetent = 'fit', ...props }) {
-    const mdUp = useIsMdUp();
-    if (mdUp)
+export function ResponsiveDialog({ sheetDetent = 'fit', breakpoint = 'sm', ...props }) {
+    const wide = useMediaQuery(minWidth(breakpoint));
+    if (wide)
         return _jsx(Dialog, { ...props });
     return (_jsx(Sheet, { open: props.open, onOpenChange: props.onOpenChange, title: props.title, description: props.description, footer: props.footer, className: props.className, detent: sheetDetent, showCloseButton: true, children: props.children }));
 }

package/dist/atoms/StatusIndicator/StatusIndicator.d.ts

@@ -0,0 +1,14 @@
+export type StatusTone = 'neutral' | 'success' | 'warning' | 'danger' | 'info';
+export interface StatusIndicatorProps {
+    tone?: StatusTone;
+    /** Always shown: the colour is never the only signal. */
+    label: string;
+    /** A slow pulse, for something in progress. Off under reduced motion. */
+    pulse?: boolean;
+    className?: string;
+}
+/**
+ * A coloured dot and a word: "Active", "Failed", "Syncing". Lighter than a Badge, for table
+ * cells and lists where a filled pill per row would be loud.
+ */
+export declare function StatusIndicator({ tone, label, pulse, className, }: StatusIndicatorProps): import("react").JSX.Element;

package/dist/atoms/StatusIndicator/StatusIndicator.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * A coloured dot and a word: "Active", "Failed", "Syncing". Lighter than a Badge, for table
+ * cells and lists where a filled pill per row would be loud.
+ */
+export function StatusIndicator({ tone = 'neutral', label, pulse, className, }) {
+    return (_jsxs("span", { className: ['ui-status', className].filter(Boolean).join(' '), "data-tone": tone, "data-pulse": pulse ? '' : undefined, children: [_jsx("span", { className: "ui-status__dot", "aria-hidden": "true" }), label] }));
+}

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

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

package/dist/atoms/StatusIndicator/index.js

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

package/dist/atoms/TextLink/TextLink.d.ts

@@ -0,0 +1,36 @@
+import type { AnchorHTMLAttributes, MouseEventHandler, ReactElement, ReactNode } from 'react';
+/**
+ * What a `render` function receives to build a router link. Spread it onto the element you
+ * return, e.g. `render={(p) => <RouterLink to={p.href} {...p} />}`.
+ *
+ * Every component in this library that navigates (TextLink, NavItem, Breadcrumbs, PageTabs)
+ * takes the same `render`, so the library never imports a router.
+ */
+export interface LinkRenderProps {
+    href: string;
+    className?: string;
+    children: ReactNode;
+    'aria-current'?: 'page';
+    onClick?: MouseEventHandler<HTMLElement>;
+}
+export type RenderLink = (props: LinkRenderProps) => ReactElement;
+export interface TextLinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href' | 'color' | 'children'> {
+    href: string;
+    children: ReactNode;
+    /** Wraps a router link. Receives {@link LinkRenderProps}. */
+    render?: RenderLink;
+    /**
+     * Opens in a new tab with `rel="noopener noreferrer"`, and says so to screen readers
+     * (the `opensInNewTab` UI string).
+     */
+    external?: boolean;
+    /** Default `hover`, Themes' own default. */
+    underline?: 'auto' | 'hover' | 'always';
+}
+/**
+ * An inline text link in the theme's link style, router-agnostic.
+ *
+ * Named `TextLink` because `Link` is already Radix Themes' own component, re-exported from
+ * this package as a primitive.
+ */
+export declare function TextLink({ href, children, render, external, underline, ...rest }: TextLinkProps): import("react").JSX.Element;

package/dist/atoms/TextLink/TextLink.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Link as ThemedLink } from '@radix-ui/themes';
+import { useUiStrings } from '../../strings.js';
+/**
+ * An inline text link in the theme's link style, router-agnostic.
+ *
+ * Named `TextLink` because `Link` is already Radix Themes' own component, re-exported from
+ * this package as a primitive.
+ */
+export function TextLink({ href, children, render, external = false, underline, ...rest }) {
+    const strings = useUiStrings();
+    const content = external ? (_jsxs(_Fragment, { children: [children, " ", _jsx("span", { className: "ui-sr-only", children: strings.opensInNewTab })] })) : (children);
+    if (render) {
+        return (_jsx(ThemedLink, { asChild: true, underline: underline, children: render({ href, children: content }) }));
+    }
+    return (_jsx(ThemedLink, { href: href, underline: underline, ...(external ? { target: '_blank', rel: 'noopener noreferrer' } : {}), ...rest, children: content }));
+}

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

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

package/dist/atoms/TextLink/index.js

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

package/dist/atoms/Toast/Toast.d.ts

@@ -30,7 +30,7 @@ type Shorthand = (options: Omit<ToastOptions, 'type'>) => string;
  *
  *     toast({ title: 'Saved' });
  *     toast.error({ title: 'Payment failed', duration: Infinity });
- *     toast.success({ title: 'Booking cancelled', action: { label: 'Undo', onClick: restore } });
+ *     toast.success({ title: 'Item archived', action: { label: 'Undo', onClick: restore } });
  *     toast.dismiss(id);
  */
 export declare const toast: typeof show & {

package/dist/atoms/Toast/Toast.js

@@ -36,7 +36,7 @@ function show(options) {
  *
  *     toast({ title: 'Saved' });
  *     toast.error({ title: 'Payment failed', duration: Infinity });
- *     toast.success({ title: 'Booking cancelled', action: { label: 'Undo', onClick: restore } });
+ *     toast.success({ title: 'Item archived', action: { label: 'Undo', onClick: restore } });
  *     toast.dismiss(id);
  */
 export const toast = Object.assign(show, {

package/dist/atoms/index.d.ts

@@ -1,3 +1,4 @@
+export * from './ActionMenu/index.js';
 export * from './ActionSheet/index.js';
 export * from './Alert/index.js';
 export * from './Avatar/index.js';
@@ -15,6 +16,7 @@ export * from './Label/index.js';
 export * from './List/index.js';
 export * from './NavBar/index.js';
 export * from './NotificationCard/index.js';
+export * from './Pill/index.js';
 export * from './Popover/index.js';
 export * from './Progress/index.js';
 export * from './PullToRefresh/index.js';
@@ -29,8 +31,10 @@ export * from './Skeleton/index.js';
 export * from './Slider/index.js';
 export * from './Spinner/index.js';
 export * from './StatTile/index.js';
+export * from './StatusIndicator/index.js';
 export * from './Switch/index.js';
 export * from './TabBar/index.js';
 export * from './Textarea/index.js';
+export * from './TextLink/index.js';
 export * from './Toast/index.js';
 export * from './Tooltip/index.js';

package/dist/atoms/index.js

@@ -1,3 +1,4 @@
+export * from './ActionMenu/index.js';
 export * from './ActionSheet/index.js';
 export * from './Alert/index.js';
 export * from './Avatar/index.js';
@@ -15,6 +16,7 @@ export * from './Label/index.js';
 export * from './List/index.js';
 export * from './NavBar/index.js';
 export * from './NotificationCard/index.js';
+export * from './Pill/index.js';
 export * from './Popover/index.js';
 export * from './Progress/index.js';
 export * from './PullToRefresh/index.js';
@@ -29,8 +31,10 @@ export * from './Skeleton/index.js';
 export * from './Slider/index.js';
 export * from './Spinner/index.js';
 export * from './StatTile/index.js';
+export * from './StatusIndicator/index.js';
 export * from './Switch/index.js';
 export * from './TabBar/index.js';
 export * from './Textarea/index.js';
+export * from './TextLink/index.js';
 export * from './Toast/index.js';
 export * from './Tooltip/index.js';

package/dist/hooks/breakpoints.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Radix Themes' breakpoints, in pixels. `Card`, `TabBar`, `ScrollStrip` and the media queries in
+ * `tokens.css` already use this scale; this constant is the one place JavaScript reads it from.
+ *
+ * Note that `sm` here is 768px, which is what Tailwind calls `md`. A class cannot be generated
+ * for both scales, so components that switch structure in JavaScript take a name from this
+ * scale rather than a Tailwind one.
+ */
+export declare const BREAKPOINTS: {
+    readonly xs: 520;
+    readonly sm: 768;
+    readonly md: 1024;
+    readonly lg: 1280;
+    readonly xl: 1640;
+};
+export type Breakpoint = keyof typeof BREAKPOINTS;
+/** `initial` is below `xs`: the unconditional value, as in `Responsive<T>`. */
+export type BreakpointOrInitial = 'initial' | Breakpoint;
+/** The media query that matches from `bp` up, e.g. `(min-width: 1024px)` for `md`. */
+export declare function minWidth(bp: Breakpoint): string;

package/dist/hooks/breakpoints.js

@@ -0,0 +1,13 @@
+/**
+ * Radix Themes' breakpoints, in pixels. `Card`, `TabBar`, `ScrollStrip` and the media queries in
+ * `tokens.css` already use this scale; this constant is the one place JavaScript reads it from.
+ *
+ * Note that `sm` here is 768px, which is what Tailwind calls `md`. A class cannot be generated
+ * for both scales, so components that switch structure in JavaScript take a name from this
+ * scale rather than a Tailwind one.
+ */
+export const BREAKPOINTS = { xs: 520, sm: 768, md: 1024, lg: 1280, xl: 1640 };
+/** The media query that matches from `bp` up, e.g. `(min-width: 1024px)` for `md`. */
+export function minWidth(bp) {
+    return `(min-width: ${BREAKPOINTS[bp]}px)`;
+}

package/dist/hooks/index.d.ts

@@ -0,0 +1,4 @@
+export * from './breakpoints.js';
+export * from './useControllableState.js';
+export * from './useElementWidth.js';
+export * from './useMediaQuery.js';

package/dist/hooks/index.js

@@ -0,0 +1,4 @@
+export * from './breakpoints.js';
+export * from './useControllableState.js';
+export * from './useElementWidth.js';
+export * from './useMediaQuery.js';

package/dist/hooks/useControllableState.d.ts

@@ -0,0 +1,17 @@
+export interface UseControllableStateOptions<T> {
+    /** Controlled value. When it is not `undefined`, the hook holds no state of its own. */
+    value?: T;
+    /** Initial value when uncontrolled. */
+    defaultValue: T;
+    /** Called with every requested change, whether controlled or not. */
+    onChange?: (value: T) => void;
+}
+/**
+ * The `value` / `defaultValue` / `onValueChange` pattern in one place, so every component that
+ * offers both modes behaves the same way: a controlled component never changes on its own,
+ * and an uncontrolled one still reports each change.
+ *
+ * Whether it is controlled is decided by the first render. Switching between the two is a
+ * bug in the caller, the same rule React applies to inputs.
+ */
+export declare function useControllableState<T>({ value, defaultValue, onChange, }: UseControllableStateOptions<T>): [T, (next: T) => void];

package/dist/hooks/useControllableState.js

@@ -0,0 +1,22 @@
+import { useCallback, useRef, useState } from 'react';
+/**
+ * The `value` / `defaultValue` / `onValueChange` pattern in one place, so every component that
+ * offers both modes behaves the same way: a controlled component never changes on its own,
+ * and an uncontrolled one still reports each change.
+ *
+ * Whether it is controlled is decided by the first render. Switching between the two is a
+ * bug in the caller, the same rule React applies to inputs.
+ */
+export function useControllableState({ value, defaultValue, onChange, }) {
+    const controlled = useRef(value !== undefined).current;
+    const [inner, setInner] = useState(defaultValue);
+    const current = controlled ? value : inner;
+    const onChangeRef = useRef(onChange);
+    onChangeRef.current = onChange;
+    const set = useCallback((next) => {
+        if (!controlled)
+            setInner(next);
+        onChangeRef.current?.(next);
+    }, [controlled]);
+    return [current, set];
+}

package/dist/hooks/useElementWidth.d.ts

@@ -0,0 +1,7 @@
+import { type RefObject } from 'react';
+/**
+ * The content width of an element, kept current with one ResizeObserver. `0` until measured,
+ * and where ResizeObserver does not exist (the server, some test environments), so callers
+ * should fall back to a sensible default.
+ */
+export declare function useElementWidth(ref: RefObject<HTMLElement | null>): number;

package/dist/hooks/useElementWidth.js

@@ -0,0 +1,22 @@
+import { useLayoutEffect, useState } from 'react';
+/**
+ * The content width of an element, kept current with one ResizeObserver. `0` until measured,
+ * and where ResizeObserver does not exist (the server, some test environments), so callers
+ * should fall back to a sensible default.
+ */
+export function useElementWidth(ref) {
+    const [width, setWidth] = useState(0);
+    useLayoutEffect(() => {
+        const el = ref.current;
+        if (!el || typeof ResizeObserver === 'undefined')
+            return;
+        setWidth(el.getBoundingClientRect().width);
+        const observer = new ResizeObserver(([entry]) => {
+            if (entry)
+                setWidth(entry.contentRect.width);
+        });
+        observer.observe(el);
+        return () => observer.disconnect();
+    }, [ref]);
+    return width;
+}

package/dist/hooks/useMediaQuery.d.ts

@@ -0,0 +1,18 @@
+import { type BreakpointOrInitial } from './breakpoints.js';
+/**
+ * Whether a media query matches, kept current as it changes.
+ *
+ * For switching *structure* (a dialog that becomes a sheet). A visual change belongs in CSS,
+ * where it needs no JavaScript and does not flash on hydration.
+ *
+ * On the server, and wherever `matchMedia` is missing, it returns `serverValue`. The default is
+ * `true` because the existing atoms render their desktop branch first.
+ */
+export declare function useMediaQuery(query: string, serverValue?: boolean): boolean;
+/**
+ * The largest breakpoint the viewport has reached, or `initial` below `xs`.
+ *
+ * On the server it returns `serverValue`, default `lg`, for the same desktop-first reason as
+ * {@link useMediaQuery}.
+ */
+export declare function useBreakpoint(serverValue?: BreakpointOrInitial): BreakpointOrInitial;

package/dist/hooks/useMediaQuery.js

@@ -0,0 +1,51 @@
+import { useMemo, useSyncExternalStore } from 'react';
+import { BREAKPOINTS, minWidth } from './breakpoints.js';
+function hasMatchMedia() {
+    return typeof window !== 'undefined' && typeof window.matchMedia === 'function';
+}
+function subscribeTo(queries) {
+    return (onChange) => {
+        if (!hasMatchMedia())
+            return () => { };
+        const lists = queries.map((q) => window.matchMedia(q));
+        for (const l of lists)
+            l.addEventListener('change', onChange);
+        return () => {
+            for (const l of lists)
+                l.removeEventListener('change', onChange);
+        };
+    };
+}
+/**
+ * Whether a media query matches, kept current as it changes.
+ *
+ * For switching *structure* (a dialog that becomes a sheet). A visual change belongs in CSS,
+ * where it needs no JavaScript and does not flash on hydration.
+ *
+ * On the server, and wherever `matchMedia` is missing, it returns `serverValue`. The default is
+ * `true` because the existing atoms render their desktop branch first.
+ */
+export function useMediaQuery(query, serverValue = true) {
+    // A new subscribe function each render would make React resubscribe on every render.
+    const subscribe = useMemo(() => subscribeTo([query]), [query]);
+    return useSyncExternalStore(subscribe, () => (hasMatchMedia() ? window.matchMedia(query).matches : serverValue), () => serverValue);
+}
+const ORDER = Object.keys(BREAKPOINTS);
+const subscribeToBreakpoints = subscribeTo(ORDER.map(minWidth));
+/**
+ * The largest breakpoint the viewport has reached, or `initial` below `xs`.
+ *
+ * On the server it returns `serverValue`, default `lg`, for the same desktop-first reason as
+ * {@link useMediaQuery}.
+ */
+export function useBreakpoint(serverValue = 'lg') {
+    return useSyncExternalStore(subscribeToBreakpoints, () => {
+        if (!hasMatchMedia())
+            return serverValue;
+        let current = 'initial';
+        for (const bp of ORDER)
+            if (window.matchMedia(minWidth(bp)).matches)
+                current = bp;
+        return current;
+    }, () => serverValue);
+}