@charcuterie/ui 2.6.0 → 2.8.0

package/dist/index.js

@@ -31,22 +31,26 @@
  * this package's README has always told it to do.
  */
 export { Accordion } from "./Accordion/Accordion.js";
+export { AdaptiveGrid } from "./AdaptiveGrid/AdaptiveGrid.js";
+export { chooseColumns, DEFAULT_MAX_AUTO_COLUMNS, DEFAULT_MAX_MANUAL_COLUMNS, DEFAULT_MIN_COLUMN_INLINE_SIZE_PX, getColumnChoices, getContentMaxInlineSize, } from "./AdaptiveGrid/chooseColumns.js";
+export { localStorageColumnPersistence, readStoredChoice, useAdaptiveColumns, viewportBlockSizeResolver, } from "./AdaptiveGrid/useAdaptiveColumns.js";
 export { Alert } from "./Alert/Alert.js";
 export { Badge } from "./Badge/Badge.js";
 export { Button } from "./Button/Button.js";
+export { ButtonLink } from "./ButtonLink/ButtonLink.js";
 export { Card } from "./Card/Card.js";
 export { Checkbox } from "./Checkbox/Checkbox.js";
 export { ColorSchemeSwitcher } from "./ColorSchemeSwitcher/ColorSchemeSwitcher.js";
 export { ColorSchemeToggle } from "./ColorSchemeToggle/ColorSchemeToggle.js";
 export { Combobox } from "./Combobox/Combobox.js";
-export { BADGE_SIZE_CLASS, CONTROL_SIZE_CLASS, DOT_SIZE_CLASS, ICON_CONTROL_SIZE_CLASS, MIN_TOUCH_TARGET_CLASS, SPINNER_SIZE_CLASS, } from "./controlStyles.js";
+export { BADGE_SIZE_CLASS, CONTROL_BASE_CLASS, CONTROL_SIZE_CLASS, DOT_SIZE_CLASS, getControlClassName, ICON_CONTROL_SIZE_CLASS, MIN_TOUCH_TARGET_CLASS, SPINNER_SIZE_CLASS, } from "./controlStyles.js";
 export { Dialog } from "./Dialog/Dialog.js";
 export { EmptyState } from "./EmptyState/EmptyState.js";
 export { Field } from "./Field/Field.js";
 export { FieldGroup } from "./Field/FieldGroup.js";
 export { FileDropZone } from "./FileDropZone/FileDropZone.js";
 export { IconButton } from "./IconButton/IconButton.js";
-export { DISABLED_CLASS, FOCUS_RING_CLASS, INTENT_APPEARANCE_CLASS, INTENT_CONTENT_CLASS, INTENT_HOVER_CLASS, INTENT_SOLID_FILL_CLASS, } from "./intentStyles.js";
+export { ARIA_DISABLED_CLASS, DISABLED_CLASS, FOCUS_RING_CLASS, INTENT_APPEARANCE_CLASS, INTENT_CONTENT_CLASS, INTENT_HOVER_CLASS, INTENT_SOLID_FILL_CLASS, } from "./intentStyles.js";
 export { Lightbox } from "./Lightbox/Lightbox.js";
 export { Listbox } from "./Listbox/Listbox.js";
 export { LiveStatusIndicator } from "./LiveStatusIndicator/LiveStatusIndicator.js";
@@ -59,6 +63,9 @@ export { Popover } from "./Popover/Popover.js";
 export { ProgressBar } from "./ProgressBar/ProgressBar.js";
 export { getProgressIntent, toProgressPercent, toProgressValue, } from "./ProgressBar/progressValue.js";
 export { RadioGroup } from "./RadioGroup/RadioGroup.js";
+export { AnchorLink } from "./RouterLink/AnchorLink.js";
+export { RouterLinkProvider, useRouterLink, } from "./RouterLink/RouterLinkProvider.js";
+export { getIsRoutedHref } from "./RouterLink/routerLink.js";
 export { SegmentedControl } from "./SegmentedControl/SegmentedControl.js";
 export { Select } from "./Select/Select.js";
 export { Skeleton } from "./Skeleton/Skeleton.js";
@@ -69,6 +76,7 @@ export { Switch } from "./Switch/Switch.js";
 export { mergeSlotProps } from "./slotProps.js";
 export { getAsyncIntent, getAsyncLabel, getConnectionIntent, getConnectionLabel, getIsConnectionBusy, } from "./statusIntent.js";
 export { Tabs } from "./Tabs/Tabs.js";
+export { TextLink } from "./TextLink/TextLink.js";
 export { Toast } from "./Toast/Toast.js";
 export { ToastRegion } from "./Toast/ToastRegion.js";
 export { toastTransitions } from "./Toast/toastLifecycle.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/intentStyles.d.ts

@@ -73,4 +73,21 @@ export declare const FOCUS_RING_CLASS = "focus-visible:outline-solid focus-visib
  * Keeping it in one constant is what stops it drifting onto prose.
  */
 export declare const DISABLED_CLASS = "disabled:cursor-not-allowed disabled:border-border-subtle disabled:bg-surface-sunken disabled:text-content-disabled disabled:shadow-none";
+/**
+ * The same treatment for something that cannot *be* disabled.
+ *
+ * **`disabled` is not a thing an `<a>` has.** There is no attribute,
+ * no `:disabled` match, and no browser behaviour to inherit — so a
+ * "disabled link" is entirely something a component has to build, and
+ * the usual build of it is a focusable `<a href>` that silently does
+ * nothing when pressed. `ButtonLink` instead drops `href` (the
+ * platform's own way to make an anchor inert and unfocusable) and
+ * says so with `aria-disabled`, which is what this paints against.
+ *
+ * `pointer-events-none` rather than `cursor-not-allowed`: without a
+ * real `:disabled`, the `hover:` classes still match — CSS `:hover`
+ * fires on disabled elements too — so the hover fill has to be taken
+ * off the table rather than merely overridden.
+ */
+export declare const ARIA_DISABLED_CLASS = "aria-disabled:pointer-events-none aria-disabled:border-border-subtle aria-disabled:bg-surface-sunken aria-disabled:text-content-disabled aria-disabled:shadow-none";
 //# sourceMappingURL=intentStyles.d.ts.map

package/dist/intentStyles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"intentStyles.d.ts","sourceRoot":"","sources":["../src/intentStyles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAErD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,gBAAgB,GACxB,OAAO,GACP,SAAS,GACT,MAAM,GACN,OAAO,CAAA;AAEX,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAC1C,UAAU,EACV,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAwDjC,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CACrC,UAAU,EACV,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAsCjC,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAC1C,UAAU,EACV,MAAM,CAQP,CAAA;AAED,yDAAyD;AACzD,eAAO,MAAM,oBAAoB,EAAE,MAAM,CACvC,UAAU,EACV,MAAM,CAQP,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,sKACwI,CAAA;AAErK;;;;;GAKG;AACH,eAAO,MAAM,cAAc,6IACiH,CAAA"}
+{"version":3,"file":"intentStyles.d.ts","sourceRoot":"","sources":["../src/intentStyles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAErD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,gBAAgB,GACxB,OAAO,GACP,SAAS,GACT,MAAM,GACN,OAAO,CAAA;AAEX,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAC1C,UAAU,EACV,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAwDjC,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CACrC,UAAU,EACV,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAsCjC,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAC1C,UAAU,EACV,MAAM,CAQP,CAAA;AAED,yDAAyD;AACzD,eAAO,MAAM,oBAAoB,EAAE,MAAM,CACvC,UAAU,EACV,MAAM,CAQP,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,sKACwI,CAAA;AAErK;;;;;GAKG;AACH,eAAO,MAAM,cAAc,6IACiH,CAAA;AAE5I;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,mBAAmB,uKACsI,CAAA"}

package/dist/intentStyles.js

@@ -147,4 +147,21 @@ export const FOCUS_RING_CLASS = "focus-visible:outline-solid focus-visible:outli
  * Keeping it in one constant is what stops it drifting onto prose.
  */
 export const DISABLED_CLASS = "disabled:cursor-not-allowed disabled:border-border-subtle disabled:bg-surface-sunken disabled:text-content-disabled disabled:shadow-none";
+/**
+ * The same treatment for something that cannot *be* disabled.
+ *
+ * **`disabled` is not a thing an `<a>` has.** There is no attribute,
+ * no `:disabled` match, and no browser behaviour to inherit — so a
+ * "disabled link" is entirely something a component has to build, and
+ * the usual build of it is a focusable `<a href>` that silently does
+ * nothing when pressed. `ButtonLink` instead drops `href` (the
+ * platform's own way to make an anchor inert and unfocusable) and
+ * says so with `aria-disabled`, which is what this paints against.
+ *
+ * `pointer-events-none` rather than `cursor-not-allowed`: without a
+ * real `:disabled`, the `hover:` classes still match — CSS `:hover`
+ * fires on disabled elements too — so the hover fill has to be taken
+ * off the table rather than merely overridden.
+ */
+export const ARIA_DISABLED_CLASS = "aria-disabled:pointer-events-none aria-disabled:border-border-subtle aria-disabled:bg-surface-sunken aria-disabled:text-content-disabled aria-disabled:shadow-none";
 //# sourceMappingURL=intentStyles.js.map

package/dist/intentStyles.js.map

@@ -1 +1 @@
-{"version":3,"file":"intentStyles.js","sourceRoot":"","sources":["../src/intentStyles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAsBH,MAAM,CAAC,MAAM,uBAAuB,GAGhC;IACF,OAAO,EAAE;QACP,KAAK,EACH,wDAAwD;QAC1D,OAAO,EACL,yEAAyE;QAC3E,IAAI,EAAE,oFAAoF;QAC1F,KAAK,EACH,yEAAyE;KAC5E;IACD,MAAM,EAAE;QACN,KAAK,EACH,8DAA8D;QAChE,OAAO,EACL,uEAAuE;QACzE,IAAI,EAAE,iFAAiF;QACvF,KAAK,EACH,uEAAuE;KAC1E;IACD,OAAO,EAAE;QACP,KAAK,EACH,+DAA+D;QACjE,OAAO,EACL,yEAAyE;QAC3E,IAAI,EAAE,oFAAoF;QAC1F,KAAK,EACH,yEAAyE;KAC5E;IACD,OAAO,EAAE;QACP,KAAK,EACH,+DAA+D;QACjE,OAAO,EACL,yEAAyE;QAC3E,IAAI,EAAE,oFAAoF;QAC1F,KAAK,EACH,yEAAyE;KAC5E;IACD,MAAM,EAAE;QACN,KAAK,EACH,8DAA8D;QAChE,OAAO,EACL,uEAAuE;QACzE,IAAI,EAAE,iFAAiF;QACvF,KAAK,EACH,uEAAuE;KAC1E;IACD,IAAI,EAAE;QACJ,KAAK,EACH,4DAA4D;QAC9D,OAAO,EACL,mEAAmE;QACrE,IAAI,EAAE,2EAA2E;QACjF,KAAK,EACH,mEAAmE;KACtE;CACF,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAG3B;IACF,OAAO,EAAE;QACP,KAAK,EAAE,iCAAiC;QACxC,OAAO,EAAE,iCAAiC;QAC1C,IAAI,EAAE,uCAAuC;QAC7C,KAAK,EAAE,qCAAqC;KAC7C;IACD,MAAM,EAAE;QACN,KAAK,EAAE,gCAAgC;QACvC,OAAO,EAAE,gCAAgC;QACzC,IAAI,EAAE,sCAAsC;QAC5C,KAAK,EAAE,oCAAoC;KAC5C;IACD,OAAO,EAAE;QACP,KAAK,EAAE,iCAAiC;QACxC,OAAO,EAAE,iCAAiC;QAC1C,IAAI,EAAE,uCAAuC;QAC7C,KAAK,EAAE,qCAAqC;KAC7C;IACD,OAAO,EAAE;QACP,KAAK,EAAE,iCAAiC;QACxC,OAAO,EAAE,iCAAiC;QAC1C,IAAI,EAAE,uCAAuC;QAC7C,KAAK,EAAE,qCAAqC;KAC7C;IACD,MAAM,EAAE;QACN,KAAK,EAAE,gCAAgC;QACvC,OAAO,EAAE,gCAAgC;QACzC,IAAI,EAAE,sCAAsC;QAC5C,KAAK,EAAE,oCAAoC;KAC5C;IACD,IAAI,EAAE;QACJ,KAAK,EAAE,8BAA8B;QACrC,OAAO,EAAE,8BAA8B;QACvC,IAAI,EAAE,oCAAoC;QAC1C,KAAK,EAAE,kCAAkC;KAC1C;CACF,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAGhC;IACF,OAAO,EAAE,yBAAyB;IAClC,MAAM,EAAE,wBAAwB;IAChC,OAAO,EAAE,yBAAyB;IAClC,OAAO,EAAE,yBAAyB;IAClC,MAAM,EAAE,wBAAwB;IAChC,IAAI,EAAE,sBAAsB;CAC7B,CAAA;AAED,yDAAyD;AACzD,MAAM,CAAC,MAAM,oBAAoB,GAG7B;IACF,OAAO,EAAE,6BAA6B;IACtC,MAAM,EAAE,4BAA4B;IACpC,OAAO,EAAE,6BAA6B;IACtC,OAAO,EAAE,6BAA6B;IACtC,MAAM,EAAE,4BAA4B;IACpC,IAAI,EAAE,0BAA0B;CACjC,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAC3B,mKAAmK,CAAA;AAErK;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GACzB,0IAA0I,CAAA"}
+{"version":3,"file":"intentStyles.js","sourceRoot":"","sources":["../src/intentStyles.ts"],"names":[],"mappings":"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"}

package/dist/reactRouter/ReactRouterLink.d.ts

@@ -0,0 +1,23 @@
+import type { ReactNode } from "react";
+import type { RouterLinkProps } from "../RouterLink/routerLink.ts";
+/**
+ * react-router's `<Link>`, wearing the seam's `href`.
+ *
+ * The entire adapter, and that is the point: the seam's contract is
+ * "a component that takes `href`", so an adapter is a rename. wouter,
+ * TanStack Router, and a hand-rolled router each get the same four
+ * lines, written in the app rather than here.
+ *
+ * `to` versus `href` is the only mismatch worth naming. Everything
+ * else — `className`, `rel`, `target`, `aria-*`, the ref — passes
+ * through untouched, because react-router renders a real `<a>` and
+ * forwards what it does not understand.
+ *
+ * Imported from `react-router`, not `react-router-dom`. v7 and v8
+ * both export `Link` from the former, and `react-router-dom` v7 (what
+ * bambuddy has) is a re-export shim over exactly that module — so one
+ * import covers both installs, while naming `react-router-dom` would
+ * cover only one.
+ */
+export declare const ReactRouterLink: ({ href, ...linkProps }: RouterLinkProps) => ReactNode;
+//# sourceMappingURL=ReactRouterLink.d.ts.map

package/dist/reactRouter/ReactRouterLink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReactRouterLink.d.ts","sourceRoot":"","sources":["../../src/reactRouter/ReactRouterLink.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAGtC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAA;AAElE;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,eAAe,GAAI,wBAG7B,eAAe,KAAG,SAEpB,CAAA"}

package/dist/reactRouter/ReactRouterLink.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Link } from "react-router";
+/**
+ * react-router's `<Link>`, wearing the seam's `href`.
+ *
+ * The entire adapter, and that is the point: the seam's contract is
+ * "a component that takes `href`", so an adapter is a rename. wouter,
+ * TanStack Router, and a hand-rolled router each get the same four
+ * lines, written in the app rather than here.
+ *
+ * `to` versus `href` is the only mismatch worth naming. Everything
+ * else — `className`, `rel`, `target`, `aria-*`, the ref — passes
+ * through untouched, because react-router renders a real `<a>` and
+ * forwards what it does not understand.
+ *
+ * Imported from `react-router`, not `react-router-dom`. v7 and v8
+ * both export `Link` from the former, and `react-router-dom` v7 (what
+ * bambuddy has) is a re-export shim over exactly that module — so one
+ * import covers both installs, while naming `react-router-dom` would
+ * cover only one.
+ */
+export const ReactRouterLink = ({ href, ...linkProps }) => (_jsx(Link, { ...linkProps, to: href }));
+//# sourceMappingURL=ReactRouterLink.js.map

package/dist/reactRouter/ReactRouterLink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReactRouterLink.js","sourceRoot":"","sources":["../../src/reactRouter/ReactRouterLink.tsx"],"names":[],"mappings":";AACA,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAA;AAInC;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,EAC9B,IAAI,EACJ,GAAG,SAAS,EACI,EAAa,EAAE,CAAC,CAChC,KAAC,IAAI,OAAK,SAAS,EAAE,EAAE,EAAE,IAAI,GAAI,CAClC,CAAA"}

package/dist/reactRouter/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `@charcuterie/ui/react-router` — the react-router adapter for the
+ * link seam.
+ *
+ * **A subpath export with an optional peer dependency**, and both
+ * halves of that matter. The base package must stay router-free: the
+ * fleet runs react-router v8, react-router-dom v7, wouter-preact, two
+ * hand-rolled routers, and five apps with no router at all, so a
+ * `react-router` in `@charcuterie/ui`'s dependencies would be a
+ * package eleven consumers install and six of them use. Optional
+ * peer + separate entry point means an app that never imports this
+ * path never resolves `react-router`, and `sourceRules.test.ts`
+ * asserts exactly that — the main entry is measured for what it
+ * reaches, so this cannot leak into it by accident.
+ *
+ * The wiring is one provider at the app root; `Guides/Routing` in
+ * Storybook is the copy-pasteable version.
+ *
+ * ```tsx
+ * import { RouterLinkProvider } from "@charcuterie/ui"
+ * import { ReactRouterLink } from "@charcuterie/ui/react-router"
+ *
+ * <RouterLinkProvider link={ReactRouterLink}>
+ *   <RouterProvider router={router} />
+ * </RouterLinkProvider>
+ * ```
+ */
+export { ReactRouterLink } from "./ReactRouterLink.tsx";
+//# sourceMappingURL=index.d.ts.map

package/dist/reactRouter/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/reactRouter/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/reactRouter/index.js

@@ -0,0 +1,29 @@
+/**
+ * `@charcuterie/ui/react-router` — the react-router adapter for the
+ * link seam.
+ *
+ * **A subpath export with an optional peer dependency**, and both
+ * halves of that matter. The base package must stay router-free: the
+ * fleet runs react-router v8, react-router-dom v7, wouter-preact, two
+ * hand-rolled routers, and five apps with no router at all, so a
+ * `react-router` in `@charcuterie/ui`'s dependencies would be a
+ * package eleven consumers install and six of them use. Optional
+ * peer + separate entry point means an app that never imports this
+ * path never resolves `react-router`, and `sourceRules.test.ts`
+ * asserts exactly that — the main entry is measured for what it
+ * reaches, so this cannot leak into it by accident.
+ *
+ * The wiring is one provider at the app root; `Guides/Routing` in
+ * Storybook is the copy-pasteable version.
+ *
+ * ```tsx
+ * import { RouterLinkProvider } from "@charcuterie/ui"
+ * import { ReactRouterLink } from "@charcuterie/ui/react-router"
+ *
+ * <RouterLinkProvider link={ReactRouterLink}>
+ *   <RouterProvider router={router} />
+ * </RouterLinkProvider>
+ * ```
+ */
+export { ReactRouterLink } from "./ReactRouterLink.js";
+//# sourceMappingURL=index.js.map

package/dist/reactRouter/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/reactRouter/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAuB,CAAA"}

package/dist/styles.css

@@ -1,14 +1,19 @@
-/* `@charcuterie/ui/styles.css` — the four looping affordances, and
- * nothing else.
+/* `@charcuterie/ui/styles.css` — the four looping affordances and
+ * the token-tinted scrollbar: the visuals a Tailwind utility cannot
+ * express against our tokens, and nothing else.
  *
  * Every other visual in this package is a Tailwind utility reading
  * a token, which is what makes a scheme/density/variant flip a
- * repaint with no re-render. Animation is the one thing utilities
- * cannot express against our tokens: Tailwind's own `animate-spin`
- * and `animate-pulse` hardcode 1s and 2s, ignore
- * `prefers-reduced-motion`, and are therefore beyond the theme's
- * reach — which is exactly why `MotionTokens` carries a separate
- * `loopFast`/`loopSlow` ramp.
+ * repaint with no re-render. Two things sit outside that reach.
+ * Animation is one: Tailwind's own `animate-spin` and `animate-pulse`
+ * hardcode 1s and 2s, ignore `prefers-reduced-motion`, and are
+ * therefore beyond the theme's reach — which is exactly why
+ * `MotionTokens` carries a separate `loopFast`/`loopSlow` ramp. The
+ * scrollbar is the other: the `::-webkit-scrollbar` pseudo-elements
+ * (and Firefox's `scrollbar-width`/`scrollbar-color`) have no
+ * `@theme`-generated utility, so `.charcuterie-scrollbar` at the foot
+ * of this file reads the same `--color-*` roles by hand and flips with
+ * `data-scheme` on the same repaint as everything else.
  *
  * Consumers import this once, after `@charcuterie/tokens/theme.css`.
  *
@@ -128,3 +133,78 @@
     );
   }
 }
+
+/* `.charcuterie-scrollbar` — a token-tinted scrollbar for any element
+ * that scrolls. The fleet grew this twice by hand (gallery-downloader's
+ * `scrollbar-thin-token`, image-viewer's global `::-webkit-scrollbar`
+ * block); this is the one copy, promoted here so a scheme flip
+ * repaints it for free.
+ *
+ * The *designed* look is the `::-webkit-scrollbar` path: a 12px bar, a
+ * rounded thumb, a track-coloured inset, no step arrows. That is what
+ * Chromium, Edge, and Safari paint. Chromium 121+ will *prefer*
+ * `scrollbar-width` / `scrollbar-color` over these pseudo-elements
+ * whenever both are set, which collapses the bar to the thin OS chrome
+ * (arrows and all on Windows) — so the standard properties are scoped
+ * to Firefox only, where `::-webkit-scrollbar` never runs.
+ *
+ * Firefox gets the closest standard-property match (thin, token-tinted
+ * thumb, transparent track). It cannot round a corner or draw a track
+ * inset — a platform limit, not an omission here.
+ *
+ * `::-webkit-scrollbar-button` is suppressed deliberately: the
+ * affordance is the thumb on a track, not step arrows.
+ *
+ * Both engines read the same three roles — `border-strong` for the
+ * thumb, `surface-sunken` for the track, `content-muted` for the thumb
+ * on hover — so the bar is themed by `[data-scheme]` on `<html>` with
+ * nothing in React observing it. `width`/`height` rather than a
+ * logical property is not a lapse: the `::-webkit-scrollbar`
+ * pseudo-elements size only by the physical pair, and a vertical bar's
+ * thickness is its `width` regardless of writing direction. */
+
+/* The designed bar — Chromium, Edge, Safari. */
+.charcuterie-scrollbar::-webkit-scrollbar {
+  width: 12px;
+  height: 12px;
+}
+
+.charcuterie-scrollbar::-webkit-scrollbar-button {
+  display: none;
+  width: 0;
+  height: 0;
+}
+
+.charcuterie-scrollbar::-webkit-scrollbar-track {
+  background-color: var(--color-surface-sunken);
+}
+
+.charcuterie-scrollbar::-webkit-scrollbar-thumb {
+  background-color: var(--color-border-strong);
+  border: 2px solid var(--color-surface-sunken);
+  border-radius: 6px;
+}
+
+.charcuterie-scrollbar::-webkit-scrollbar-thumb:hover {
+  background-color: var(--color-content-muted);
+}
+
+.charcuterie-scrollbar::-webkit-scrollbar-corner {
+  background-color: var(--color-surface-sunken);
+}
+
+/* Firefox only: it never paints `::-webkit-scrollbar`. `-moz-appearance`
+ * is the supports probe that Chromium and Safari reject, so this block
+ * does not reintroduce the standard properties on engines that would
+ * then drop the designed bar. */
+@supports (-moz-appearance: none) {
+  .charcuterie-scrollbar {
+    scrollbar-width: thin;
+    scrollbar-color: color-mix(
+        in oklab,
+        var(--color-border-strong) 70%,
+        transparent
+      )
+      transparent;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@charcuterie/ui",
-  "version": "2.6.0",
+  "version": "2.8.0",
   "description": "The Charcuterie components. Tokens for look, @charcuterie/logic for state, ARIA that agents can actually drive.",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,11 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./react-router": {
+      "source": "./src/reactRouter/index.ts",
+      "types": "./dist/reactRouter/index.d.ts",
+      "default": "./dist/reactRouter/index.js"
+    },
     "./styles.css": "./dist/styles.css",
     "./testing": {
       "source": "./src/testing/index.ts",
@@ -44,13 +49,19 @@
   },
   "dependencies": {
     "@charcuterie/logic": "1.2.0",
-    "@charcuterie/tokens": "1.1.3",
+    "@charcuterie/tokens": "1.2.0",
     "@floating-ui/react": "^0.27.20",
     "@tanstack/react-virtual": "^3.13.12"
   },
   "peerDependencies": {
     "react": ">=19",
-    "react-dom": ">=19"
+    "react-dom": ">=19",
+    "react-router": ">=7"
+  },
+  "peerDependenciesMeta": {
+    "react-router": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@storybook/react": "^10.3.6",
@@ -58,6 +69,7 @@
     "@types/react-dom": "^19.2.3",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
+    "react-router": "^8.3.0",
     "storybook": "^10.3.6",
     "tailwindcss": "^4.3.0",
     "typescript": "^6.0.3",

package/src/AdaptiveGrid/AdaptiveGrid.mdx

@@ -0,0 +1,169 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as AdaptiveGridStories from "./AdaptiveGrid.stories";
+
+<Meta of={AdaptiveGridStories} />
+
+# AdaptiveGrid
+
+**Height is spent before width.** A column is something this grid is *forced* into when
+the items will not stack inside the window — never something it takes because a monitor
+is wide.
+
+That is the opposite of every wrapping grid in the fleet today. `auto-fill, minmax()`
+takes every column the width allows, which is how you end up with seven items strung
+across an ultrawide and nothing below the fold.
+
+<Canvas of={AdaptiveGridStories.Default} />
+
+## Props
+
+<Controls />
+
+## The rule in one sentence
+
+> If you're going to vertically scroll anyway, widen the items. If you're not, keep them
+> in a smaller grid so they all still fit on screen.
+
+Mechanically:
+
+1. Ask how many items stack in the space available — the viewport's block size, minus
+   whatever chrome sits above and below.
+2. Divide the item count by that. **That** is how many columns are needed.
+3. Only then ask how many columns actually fit across the container, and take the smaller
+   of the two.
+
+Step 3 can only ever *reduce* the answer. Width is a veto, not a reason.
+
+## The part that reads backwards
+
+<Canvas of={AdaptiveGridStories.AllVariants} />
+
+Same nine items, same width, three heights — and the **taller** window takes **fewer**
+columns. A 1440x900 laptop gets three columns while a larger 1920x1080 monitor gets two.
+
+That is not a bug and it is not a tuned breakpoint. The taller window stacks the same nine
+items in fewer stacks, so it needs fewer stacks. If you "fix" it, you have thrown the rule
+away and rebuilt `auto-fill`.
+
+## The content cap widens as columns are added
+
+The other half of the complaint this answers is pages that are "1 column, but waaaaaaay
+too wide". So the cap around the grid is not a constant:
+
+| Columns | Cap |
+| --- | --- |
+| 1 | 56rem |
+| 2 | 72rem |
+| 3 | 106rem |
+| 4 | 140rem |
+
+One column stays at a reading measure, because a 2000px-wide card is not a better card —
+it is one line of text the eye has to track from bezel to bezel. The page earns its width
+by having something to fill it with.
+
+The three numbers behind that table are `contentInlineSize` in `@charcuterie/tokens`,
+beside `screen` and `containerQuery`, and every part is overridable per call. The
+arithmetic lives in `getContentMaxInlineSize` and is not a token.
+
+## When to reach for it
+
+Reach for it when **all** of these are true:
+
+- The items wrap, and there could be few or many of them.
+- They are roughly the same height, and you can measure one.
+- Scrolling is a cost rather than the point — a rack of bays, a fleet of hosts, a set of
+  status cards. Ideally the user never scrolls at all.
+
+Do **not** reach for it for a feed, a search-results list, or anything else that is
+inherently long. The rule optimises for "it all fits", and content that will never all fit
+gets nothing from it.
+
+## The one number you must measure
+
+`itemBlockSize` is the only required option and the only genuinely app-specific one.
+Measure it off a running page rather than deriving it from padding, and **err high** — over-
+estimating makes the grid reach for a column slightly early, and a page that scrolls when
+it did not have to is the entire complaint. It only has to be right to within about one
+item; being one out shifts a borderline window by one column, which is taste.
+
+`chromeBlockSize` is everything down the page that is not the grid: header, rails, filter
+rows, labels. It defaults to `0`.
+
+## It measures its container, not the window
+
+<Canvas of={AdaptiveGridStories.Responsive} />
+
+Three grids, one browser window, three different answers. The inline size comes off a
+`ResizeObserver` on the grid's own container, so a grid sitting beside a rail is told the
+truth about the room it has — the container-query thesis this library is built on, applied
+to a layout decision instead of a card's internals.
+
+The block size is the exception, and it has to be: the question is "will this scroll", and
+an element in normal flow is exactly as tall as its contents, so measuring the grid always
+answers "it fits." That number comes from the viewport, behind an injectable
+`blockSizeResolver` for Electron windows, fixed-height kiosk panels, and tests.
+
+⚠️ **Never apply the returned cap to the element being measured.** If you wire
+`useAdaptiveColumns` by hand, the observed box and the capped box must be different
+elements. Collapse them and the fold reads back its own narrowed output: one column,
+forever, with no error anywhere. `AdaptiveGrid` enforces this structurally — an uncapped
+outer box it measures, an inner box it caps.
+
+## Composing with a shell
+
+`AdaptiveGrid` caps itself, so it is correct standing alone. If you want the **page chrome**
+to widen with the grid rather than the grid rattling around inside a fixed column, hoist
+the hook to the page and hand the pieces out:
+
+```tsx
+const layout = useAdaptiveColumns({
+  chromeBlockSize: 260,
+  itemBlockSize: 150,
+  itemCount: bays.length,
+  storageKey: "rip-deck.layout-columns",
+})
+
+<Main maxInlineSize={layout.contentMaxInlineSize} ref={layout.containerRef}>
+  <AdaptiveGrid columns={layout.columns} itemBlockSize={150}>
+    {bays.map(…)}
+  </AdaptiveGrid>
+</Main>
+```
+
+The `Main` region takes a caller-supplied max inline size; the ref goes on whatever box
+sits **outside** that cap.
+
+## Manual override
+
+<Canvas of={AdaptiveGridStories.Interactive} />
+
+`"auto"` is always in the list. A picker that only offers numbers once a number has been
+chosen is a one-way door — it strands someone on a layout they tried once with no route
+back to the mode that adapts.
+
+Pass `storageKey` to remember the choice across visits, namespaced to your app; the
+library will not invent that string for you. Omit it and the choice lasts the session and
+is written nowhere. Every unreadable stored value — a corrupt key, a browser that refuses
+storage, a count the picker cannot offer — falls back to `"auto"`, so a bad value costs a
+preference rather than a page.
+
+## Why the tracks are an inline style
+
+`repeat(N, minmax(0, 1fr))` is interpolated, and a className may not be. Tailwind v4 scans
+source *text* for complete class strings, so `grid-cols-${columns}` generates nothing at
+all — no error, no warning, an unstyled element. A class-per-count would need every count
+to survive the scan; an inline style needs none. `tailwindCandidates.test.ts` rejects the
+interpolated form outright.
+
+## `min-w-0` is not optional
+
+Every child gets `min-w-0`, applied by the component rather than asked for. A grid item's
+automatic minimum size is `min-content`, so one long unbroken string — a file path, a URL —
+widens its own track and shoves the whole grid past the viewport. The rule that stops it
+has to sit on children the caller owns, which is why it is not your job to remember.
+
+You still owe your own items a wrap or a `truncate`; `min-w-0` lets the track get small
+enough for that clipping to matter.
+
+<Canvas of={AdaptiveGridStories.AllStates} />