rift-ds 1.13.0 → 1.15.0

package/README.md

@@ -13,7 +13,7 @@ An open source React design system built for AI products and coding agents: comp
 
 ## Why Rift DS
 
-- **<!-- component-count -->155<!-- /component-count --> components.** Buttons, forms and tables through to charts, navigation and overlays, each typed and documented with live examples. Every one forwards a ref and your own attributes to its element, state you can own works controlled or uncontrolled (a modal opens when your app says so, by design), and every word a component writes has a prop you can localise. The build checks the first two on every component, and the words wherever they sit in markup. React and React DOM are the only required peer dependencies.
+- **<!-- component-count -->159<!-- /component-count --> components.** Buttons, forms and tables through to charts, navigation and overlays, each typed and documented with live examples. Every one forwards a ref and your own attributes to its element, state you can own works controlled or uncontrolled (a modal opens when your app says so, by design), and every word a component writes has a prop you can localise. The build checks the first two on every component, and the words wherever they sit in markup. React and React DOM are the only required peer dependencies.
 - **AI patterns, the whole chat and templates, ready to use.** Composer, streaming chat thread, tool calls, reasoning and thread panel are in the box, the complete AI chat ships assembled as one widget that one command scaffolds, and the docs site has complete template screens built from them.
 - **Fully themeable.** The shipped themes are complete looks to start from, each in light and dark. One `data-brand` attribute applies a theme, and a few CSS overrides make your own.
 - **Ready for coding agents.** One command installs the agent skills, and a public MCP endpoint serves every component's props, so your agent builds with the library as it actually is. No key, no account.
@@ -25,18 +25,25 @@ Everything deep lives on the docs site: **[rift-ds.com](https://rift-ds.com/)**,
 
 ## Install
 
+In a Next.js app router project (a fresh `create-next-app` included), three commands give you a themed first page:
+
 ```bash
 npm install rift-ds
+npx rift-ds init app
+npx rift-ds init block dashboard
 ```
 
-Import the token stylesheet once, then use components:
+`init app` adds a root wrapper that routes every link through Next's `Link`, the script that applies the visitor's colour mode before first paint, and the base theme's font, then prints your root layout: make `app/layout.tsx` that, and drop the `globals.css` import `create-next-app` added. `init block dashboard` adds a dashboard inside an app shell (the sidebar, the top bar and the page header), laid out for a desktop and a phone; the other blocks are on the [blocks page](https://rift-ds.com/docs/blocks). Neither overwrites a file, and the files are yours to change.
+
+In any other React app, import the token stylesheet and the base sheet once, then use components:
 
 ```tsx
 import 'rift-ds/tokens/tokens.css';
+import 'rift-ds/tokens/base.css'; // the reset and page every component is tuned against
 import { Button, Card, Badge } from 'rift-ds';
 ```
 
-React 19+ is a peer dependency. The package is ESM-only and resolved via `exports` subpaths: use a bundler that handles CSS and font imports from `node_modules` (Vite, Next.js, webpack) and set TypeScript's `moduleResolution` to `"bundler"` or `"nodenext"`. The Recharts-backed charts live behind `rift-ds/charts`, so the optional `recharts` peer dependency is only needed if you use them. The chat widget's subpaths bring their own optional peers (`react-markdown` and `remark-gfm` for the panel, `@anthropic-ai/sdk` for the server handlers, `@upstash/ratelimit` and `@upstash/redis` for the guardrails), needed only if you use them. Prefer owning the source? Pull single components through the shadcn CLI (`npx shadcn@latest add https://rift-ds.com/r/button.json`, with details in the [get-started guide](https://rift-ds.com/docs/get-started)), or clone this repo and build on it directly; all of it is MIT.
+React 19+ is a peer dependency. The package's own runtime dependencies, TanStack Table and TanStack Virtual (the headless engine under `DataTable` and the windowing behind its long tables), install with it. The package is ESM-only and resolved via `exports` subpaths: use a bundler that handles CSS and font imports from `node_modules` (Vite, Next.js, webpack) and set TypeScript's `moduleResolution` to `"bundler"` or `"nodenext"`. The Recharts-backed charts live behind `rift-ds/charts`, so the optional `recharts` peer dependency is only needed if you use them. The chat widget's subpaths bring their own optional peers (`react-markdown` and `remark-gfm` for the panel, `@anthropic-ai/sdk` for the server handlers, `@upstash/ratelimit` and `@upstash/redis` for the guardrails), needed only if you use them. Prefer owning the source? Pull single components through the shadcn CLI (`npx shadcn@latest add https://rift-ds.com/r/button.json`, with details in the [get-started guide](https://rift-ds.com/docs/get-started)), or clone this repo and build on it directly; all of it is MIT.
 
 ## The chat widget
 
@@ -84,7 +91,7 @@ Every component's prop contract is also plain markdown (append `.md` to its docs
 
 ## Theming
 
-Theming is CSS custom properties; there is no configuration API and no provider (one exception: wrap your tree in `ToastProvider` if, and only if, you use the toast queue via `useToast`). Complete looks ship as generated stylesheets: import the aggregate once and one attribute rethemes everything, light and dark, typefaces included (each preset self-hosts its faces).
+Theming is CSS custom properties; there is no configuration API and no theme provider (one required exception: wrap your tree in `ToastProvider` if, and only if, you use the toast queue via `useToast`). Two providers are optional: `LinkProvider` hands every component your router's link, and `LocaleProvider` sets the locale numbers, dates and calendars are written in (`en-US` without it, never the browser's). Key bindings go through `useShortcut` from `rift-ds/behaviors/shortcuts`, the listener the components use, so a shortcut stays out of text fields and open overlays. For a right-to-left language, set `dir="rtl"` on `<html>`: every component lays itself out from it. Complete looks ship as generated stylesheets: import the aggregate once and one attribute rethemes everything, light and dark, typefaces included (each preset self-hosts its faces).
 
 ```tsx
 import 'rift-ds/tokens/presets/presets.css';
@@ -100,13 +107,13 @@ import 'rift-ds/tokens/presets/presets.css';
 
 ## Components
 
-<!-- component-count -->155<!-- /component-count --> components, including a chat set for AI products (Chat thread, Composer, Tool call, Reasoning, Thread panel) and Shader field, a WebGL2 ambient background whose light sources read your colour tokens at runtime, so it re-themes with everything else. Details and live examples are on the [docs site](https://rift-ds.com/components).
+<!-- component-count -->159<!-- /component-count --> components, including a chat set for AI products (Chat thread, Composer, Tool call, Reasoning, Thread panel) and Shader field, a WebGL2 ambient background whose light sources read your colour tokens at runtime, so it re-themes with everything else. Details and live examples are on the [docs site](https://rift-ds.com/components).
 
 <details>
 <summary>The full list</summary>
 
 <!-- component-list:start -->
-Accordion · Agent plan · Agent rail · Agent status · AI button · Alert · Alert dialog · Anchor nav · Animated number · App layout · App sidebar · Area chart · Artifact card · Artifact panel · Attachment drop zone · Attachment group · Attachment tile · Attachment viewer · Avatar · Avatar group · Badge · Banner · Bar chart · Bento tile · Bento tile art · Bottom nav · Breadcrumb · Button · Button group · Card · Card stack · Carousel · Chat header · Chat marker · Chat message · Chat thread · Checkbox · Chip · Circular button · Code block · Code diff · Colour picker · Combo chart · Combobox · Command palette · Composer · Contact card · Context menu · Contribution graph · Data table · Date input · Date picker · Dialog · Divider · Document chip · Drawer · Dropdown · Dropdown menu · Empty state · Entity card · Event calendar · Field · Figure · File input · Filter bar · Funnel chart · Gantt chart · Gauge · Globe · Hover card · Image compare · Input · Inspector colour picker · Inspector dropdown · Inspector input · Inspector section · Inspector segments · Inspector slider · Inspector toggle switch · Instructions · Interrupt card · Kbd · Legend tile · Lightbox · Line chart · Link list · Map callout · Map legend · Mention · Message actions · Message card · Meter · Model picker · Nav · Nav list · Notification centre · Number input · Pagination · Panel · Pie chart · Pin input · Pixel avatar · Popover · Progress bar · Prompt suggestions · Prose · Question card · Quote · Radar chart · Radial chart · Radio button · Rating · Reasoning · Rich dropdown · Scatter chart · Section title · Segmented control · Selection card · Shader field · Sidebar panel · Skeleton · Slider · Source chip · Source trail · Sparkline · Spinner · Split button · Split pane · Stacked bar chart · Stat · Status dot · Stepper · Streaming text · Swatch · Table · Tabs · Tag input · Textarea · Thread panel · Thread tabs · Time picker · Timeline · Toast · Toggle group · Toggle switch · Tool call · Toolbar · Tooltip · Top app bar · Tree view · Treemap · Usage card · Waveform · Widget · World map
+Accordion · Agent plan · Agent rail · Agent status · AI button · Alert · Alert dialog · Anchor nav · Animated number · App layout · App sidebar · Area chart · Artifact card · Artifact panel · Attachment drop zone · Attachment group · Attachment tile · Attachment viewer · Avatar · Avatar group · Badge · Banner · Bar chart · Bento tile · Bento tile art · Bottom nav · Breadcrumb · Button · Button group · Card · Card stack · Carousel · Chat header · Chat marker · Chat message · Chat thread · Checkbox · Chip · Circular button · Code block · Code diff · Colour picker · Combo chart · Combobox · Command palette · Command palette trigger · Composer · Contact card · Context menu · Contribution graph · Data table · Date input · Date picker · Dialog · Divider · Document chip · Drawer · Dropdown · Dropdown menu · Empty state · Entity card · Event calendar · Field · Figure · File input · Filter bar · Funnel chart · Gantt chart · Gauge · Globe · Hover card · Image compare · Input · Inspector colour picker · Inspector dropdown · Inspector input · Inspector section · Inspector segments · Inspector slider · Inspector toggle switch · Instructions · Interrupt card · Kbd · Legend tile · Lightbox · Line chart · Link list · Map callout · Map legend · Mention · Message actions · Message card · Meter · Model picker · Nav · Nav list · Notification centre · Number input · Pagination · Panel · Pie chart · Pin input · Pixel avatar · Popover · Progress bar · Prompt suggestions · Prose · Question card · Quote · Radar chart · Radial chart · Radio button · Rating · Reasoning · Rich dropdown · Scatter chart · Section title · Segmented control · Selection card · Shader field · Sidebar panel · Skeleton · Slider · Source chip · Source trail · Sparkline · Spinner · Split button · Split pane · Stacked bar chart · Stat · Status dot · Stepper · Streaming text · Swatch · Table · Table toolbar · Tabs · Tag input · Textarea · Theme picker · Theme toggle · Thread panel · Thread tabs · Time picker · Timeline · Toast · Toggle group · Toggle switch · Tool call · Toolbar · Tooltip · Top app bar · Tree view · Treemap · Usage card · Waveform · Widget · World map
 <!-- component-list:end -->
 
 </details>
@@ -118,6 +125,7 @@ Accordion · Agent plan · Agent rail · Agent status · AI button · Alert · A
 - **Next.js 16**: the documentation site
 - **Storybook 10**: component explorer
 - **Vitest + Playwright + axe**: every Storybook story runs as a render test in headless Chromium, with an accessibility audit on each
+- **TanStack Table + TanStack Virtual**: the headless engine and the windowing under `DataTable`, the package's runtime dependencies
 - **CSS custom properties**: all theming via semantic tokens, no CSS-in-JS
 
 The [overview](https://rift-ds.com/overview) shows the generate-and-validate pipeline behind the docs.

package/behaviors/LinkProvider.d.ts

@@ -27,6 +27,9 @@ export interface LinkProviderProps {
  * read a provider and take the prop alone (design.md's Components intro
  * names them, and scripts/validate-component-contract.mjs keeps them off
  * the provider).
+ *
+ * Published as the `./behaviors/LinkProvider` subpath because consumers
+ * mount it; with the scroll lock it is one of only two behaviors that are.
  */
 export declare function LinkProvider({ linkComponent, children }: LinkProviderProps): React.JSX.Element;
 /**

package/behaviors/LocaleProvider.d.ts

@@ -0,0 +1,27 @@
+import { default as React } from 'react';
+export interface LocaleProviderProps {
+    /**
+     * The BCP 47 locale every rift-ds component under this provider formats
+     * numbers, dates and calendars in, such as `de-DE`. Named like the
+     * instance prop it stands in for.
+     */
+    locale: string;
+    /** The part of the app it applies to, usually the whole app. */
+    children?: React.ReactNode;
+}
+/**
+ * Sets the locale for every client-rendered rift-ds component below it that
+ * formats a number or a date, or lays out a calendar: grouping and decimal
+ * marks, month and weekday names, the first day of the week, and the
+ * 12- or 24-hour clock. A component's own `locale` prop wins over it. The
+ * components that can render on the server cannot read a provider and take
+ * the prop alone. Words stay props of their own: the locale formats, it
+ * never translates.
+ */
+export declare function LocaleProvider({ locale, children }: LocaleProviderProps): React.JSX.Element;
+/**
+ * The locale to format in: the component's own `locale` prop, else the
+ * nearest LocaleProvider's, else `en-US`. Never the runtime's default, so
+ * the server and the browser always agree.
+ */
+export declare function useLocale(override?: string): string;

package/behaviors/LocaleProvider.js

@@ -0,0 +1,16 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+import { DEFAULT_LOCALE } from "./locale.js";
+const LocaleContext = createContext(null);
+function LocaleProvider({ locale, children }) {
+  return /* @__PURE__ */ jsx(LocaleContext.Provider, { value: locale, children });
+}
+function useLocale(override) {
+  const provided = useContext(LocaleContext);
+  return override ?? provided ?? DEFAULT_LOCALE;
+}
+export {
+  LocaleProvider,
+  useLocale
+};

package/behaviors/ScrollRegion.d.ts

@@ -0,0 +1,8 @@
+import { CSSProperties, ReactNode } from 'react';
+export declare function ScrollRegion({ className, style, children, onNode, }: {
+    className?: string;
+    style?: CSSProperties;
+    children: ReactNode;
+    /** Hands the scrolling element to its owner (a virtualised table scrolls its rows inside it). */
+    onNode?: (node: HTMLDivElement | null) => void;
+}): import("react").JSX.Element;

package/behaviors/ScrollRegion.js

@@ -0,0 +1,51 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { useRef, useCallback, useId, useState, useEffect } from "react";
+function ScrollRegion({
+  className,
+  style,
+  children,
+  onNode
+}) {
+  const ref = useRef(null);
+  const setNode = useCallback(
+    (node) => {
+      ref.current = node;
+      onNode?.(node);
+    },
+    [onNode]
+  );
+  const captionId = useId();
+  const [overflows, setOverflows] = useState(false);
+  const [labelledBy, setLabelledBy] = useState();
+  useEffect(() => {
+    const node = ref.current;
+    if (!node) return;
+    const caption = node.querySelector("caption");
+    if (caption) {
+      if (!caption.id) caption.id = captionId;
+      setLabelledBy(caption.id);
+    }
+    const measure = () => setOverflows(node.scrollWidth > node.clientWidth + 1);
+    measure();
+    const observer = new ResizeObserver(measure);
+    observer.observe(node);
+    if (node.firstElementChild) observer.observe(node.firstElementChild);
+    return () => observer.disconnect();
+  }, [captionId]);
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      ref: setNode,
+      className,
+      style,
+      role: overflows ? "region" : void 0,
+      "aria-labelledby": overflows ? labelledBy : void 0,
+      tabIndex: overflows ? 0 : void 0,
+      children
+    }
+  );
+}
+export {
+  ScrollRegion
+};

package/behaviors/devWarning.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Development-only console warnings, the way React writes its own: the
+ * check reads `process.env.NODE_ENV`, which every bundler replaces at build
+ * time, so a production bundle drops the warning and a page with no
+ * bundler (and no `process`) stays silent rather than throwing. Each
+ * message prints once per page load, however many instances trip it.
+ */
+/** Warns once, in development only. */
+export declare function warnOnce(message: string): void;

package/behaviors/devWarning.js

@@ -0,0 +1,16 @@
+const isDevelopment = (() => {
+  try {
+    return process.env.NODE_ENV !== "production";
+  } catch {
+    return false;
+  }
+})();
+const warned = /* @__PURE__ */ new Set();
+function warnOnce(message) {
+  if (!isDevelopment || warned.has(message)) return;
+  warned.add(message);
+  console.warn(`[rift-ds] ${message}`);
+}
+export {
+  warnOnce
+};

package/behaviors/direction.css

@@ -0,0 +1,19 @@
+/* ============================================
+   READING DIRECTION SIGN
+   `--ds-inline-sign` is 1 in a left-to-right context and -1 in a
+   right-to-left one, read from the element's own direction (`:dir()`),
+   so a `dir` attribute anywhere up the tree sets it. A component that
+   moves along the inline axis (a slide-in, a thumb, a shimmer's sweep, an
+   optical nudge) multiplies its offset by it, always with the fallback
+   `var(--ds-inline-sign, 1)`, and imports this file. Logical properties
+   cover placement; this covers motion, which CSS has no logical form for.
+   design.md's "Layout follows the reading direction" owns the contract.
+   ============================================ */
+
+:dir(ltr) {
+  --ds-inline-sign: 1;
+}
+
+:dir(rtl) {
+  --ds-inline-sign: -1;
+}

package/behaviors/direction.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The reading direction, for the code that moves along the inline axis:
+ * arrow keys, drags and anything placed in pixels. Stylesheets read it
+ * through logical properties and `--ds-inline-sign` (direction.css); script
+ * reads it here, from the element itself at the moment it acts, so a `dir`
+ * attribute anywhere up the tree applies and a change to it needs no
+ * re-render. No React and no browser API at import time, so a server
+ * component can import it too. design.md's "Layout follows the reading
+ * direction" owns the contract.
+ */
+/** Whether `element` lays out right to left. False on the server and for a missing element. */
+export declare function isRtl(element: Element | null | undefined): boolean;
+/** 1 when `element` reads left to right, -1 when it reads right to left: the sign to multiply a horizontal pointer delta by. */
+export declare const inlineSign: (element: Element | null | undefined) => 1 | -1;
+/**
+ * An arrow key along the inline axis as a step through the reading order:
+ * `1` for the next item (ArrowRight in English, ArrowLeft in Arabic), `-1`
+ * for the previous one, and 0 for any other key.
+ */
+export declare function inlineStep(key: string, element: Element | null | undefined): -1 | 0 | 1;
+/**
+ * The Material Symbols ligatures that point along the reading direction and
+ * so mirror in a right-to-left context: a "next" chevron points left in
+ * Arabic. A component that draws one adds the `ds-mirror-rtl` class (the
+ * rule lives in src/fonts/material-symbols.css, which every icon imports);
+ * `mirrorClass` decides it for an icon a consumer passes by name.
+ */
+export declare const DIRECTIONAL_ICONS: Set<string>;
+/** Whether the icon named `name` points along the reading direction and should mirror in a right-to-left context. */
+export declare const mirrorsInRtl: (name: unknown) => boolean;
+/**
+ * A key as it would be pressed in a left-to-right layout: ArrowLeft and
+ * ArrowRight swap when `element` reads right to left, and every other key
+ * passes through. A component that steps along the inline axis switches on
+ * this instead of the raw key, so "the next tab" is ArrowRight in English
+ * and ArrowLeft in Arabic with no second branch.
+ */
+export declare function logicalArrowKey(key: string, element: Element | null | undefined): string;
+/** `ds-mirror-rtl` when the icon named `name` mirrors in a right-to-left context, else an empty string, for a className. */
+export declare const mirrorClass: (name: unknown) => string;

package/behaviors/direction.js

@@ -0,0 +1,56 @@
+function isRtl(element) {
+  if (!element || typeof getComputedStyle === "undefined") return false;
+  return getComputedStyle(element).direction === "rtl";
+}
+const inlineSign = (element) => isRtl(element) ? -1 : 1;
+const DIRECTIONAL_ICONS = /* @__PURE__ */ new Set([
+  "chevron_left",
+  "chevron_right",
+  "arrow_back",
+  "arrow_forward",
+  "arrow_back_ios",
+  "arrow_forward_ios",
+  "arrow_back_ios_new",
+  "first_page",
+  "last_page",
+  "keyboard_arrow_left",
+  "keyboard_arrow_right",
+  "keyboard_double_arrow_left",
+  "keyboard_double_arrow_right",
+  "navigate_before",
+  "navigate_next",
+  "east",
+  "west",
+  "trending_flat",
+  "subdirectory_arrow_right",
+  "subdirectory_arrow_left",
+  "reply",
+  "forward",
+  "undo",
+  "redo",
+  "logout",
+  "login",
+  "send",
+  "menu_open",
+  "format_indent_increase",
+  "format_indent_decrease",
+  "view_sidebar",
+  "left_panel_open",
+  "left_panel_close",
+  "right_panel_open",
+  "right_panel_close"
+]);
+const mirrorsInRtl = (name) => typeof name === "string" && DIRECTIONAL_ICONS.has(name);
+function logicalArrowKey(key, element) {
+  if (key !== "ArrowLeft" && key !== "ArrowRight" || !isRtl(element)) return key;
+  return key === "ArrowLeft" ? "ArrowRight" : "ArrowLeft";
+}
+const mirrorClass = (name) => mirrorsInRtl(name) ? "ds-mirror-rtl" : "";
+export {
+  DIRECTIONAL_ICONS,
+  inlineSign,
+  isRtl,
+  logicalArrowKey,
+  mirrorClass,
+  mirrorsInRtl
+};

package/behaviors/focusable.d.ts

@@ -2,7 +2,8 @@
  * Shared focusability queries for the overlay behavior layer.
  *
  * One home for the selector the modal components previously each carried a
- * copy of. Plain DOM utilities — no React, safe to import anywhere.
+ * copy of. Plain DOM utilities — no React, safe to import anywhere. It
+ * serves non-overlay keyboard work too: Toolbar's arrow-key model reads it.
  */
 /** Everything a focus trap must cycle through. */
 export declare const FOCUSABLE = "button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex=\"-1\"])";

package/behaviors/locale.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Locale data every formatting component shares. Server-safe: no React and
+ * no browser API, so a component that renders from a Server Component can
+ * import it too. The client half (the provider and the hook) is
+ * LocaleProvider.tsx.
+ *
+ * The rule it carries: a component never formats in the runtime's default
+ * locale. The server and the browser can disagree on it, which prints
+ * `1,234` on one and `1.234` on the other and breaks hydration, and a
+ * consumer could not choose it. Every number, date and calendar convention
+ * a component prints is resolved from a locale the consumer can set, which
+ * falls back to DEFAULT_LOCALE. scripts/validate-locale-formatting.mjs
+ * enforces it.
+ */
+/** The locale a component formats in when neither its `locale` prop nor a LocaleProvider sets one. */
+export declare const DEFAULT_LOCALE = "en-US";
+/** A day of the week as `Date.getDay()` numbers it: 0 is Sunday, 6 is Saturday. */
+export type Weekday = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+/**
+ * The first day of the week in `locale`, as a `Date.getDay()` number:
+ * Sunday (0) in en-US, Monday (1) in de-DE, Saturday (6) in ar-EG. Read
+ * from the runtime's CLDR week data where it has it, else from the region.
+ */
+export declare function weekStartOf(locale: string): Weekday;
+/** A Sunday-first list of seven, reordered to start on `start`. */
+export declare function rotateWeek<T>(sundayFirst: readonly T[], start: Weekday): T[];
+/** How many days `day` sits after the week's first day: 0 for the first column, 6 for the last. */
+export declare const weekdayOffset: (day: number, start: Weekday) => number;
+/** The seven weekday names in `locale`, Sunday first, at the given width. */
+export declare function weekdayNamesIn(locale: string, width: 'long' | 'short' | 'narrow'): string[];
+/** Whether `locale` is written in English, the language every built-in label defaults to. */
+export declare function isEnglish(locale: string): boolean;
+/** Whether `locale` writes times on a 12-hour clock (en-US) rather than a 24-hour one (en-GB, de-DE). */
+export declare function uses12HourClock(locale: string): boolean;
+/**
+ * A number as `locale` writes it, grouped and with its own decimal mark:
+ * `1,234.5` in en-US, `1.234,5` in de-DE. Formats are cached per locale.
+ */
+export declare function formatNumber(value: number, locale: string): string;
+/**
+ * A number on a chart's value axis as `locale` writes it, grouped only from
+ * five digits up (`12,000` but `2024`), so a tick that happens to be a year
+ * never reads as a quantity.
+ */
+export declare function formatAxisNumber(value: number, locale: string): string;
+/** A whole percentage, given as 0 to 100, as `locale` writes it: `64%` in en-US, `٦٤٪` in ar-EG, `64 %` in de-DE. */
+export declare function formatPercent(percent: number, locale: string): string;

package/behaviors/locale.js

@@ -0,0 +1,87 @@
+const DEFAULT_LOCALE = "en-US";
+const SUNDAY_FIRST = new Set(
+  "AG AS BD BR BS BT BW BZ CA CN CO DM DO ET GT GU HK HN ID IL IN JM JP KE KH KR LA MH MM MO MT MX MZ NI NP PA PE PH PK PR PT PY SA SG SV TH TT TW UM US VE VI WS YE ZA ZW".split(" ")
+);
+const SATURDAY_FIRST = new Set("AE AF BH DJ DZ EG IQ IR JO KW LY OM QA SD SY".split(" "));
+const weekStartCache = /* @__PURE__ */ new Map();
+function weekStartOf(locale) {
+  const cached = weekStartCache.get(locale);
+  if (cached !== void 0) return cached;
+  let start = 1;
+  try {
+    const intlLocale = new Intl.Locale(locale);
+    const info = intlLocale.getWeekInfo?.() ?? intlLocale.weekInfo;
+    if (info) {
+      start = info.firstDay % 7;
+    } else {
+      const region = intlLocale.maximize().region ?? "";
+      start = SUNDAY_FIRST.has(region) ? 0 : SATURDAY_FIRST.has(region) ? 6 : 1;
+    }
+  } catch {
+    start = 1;
+  }
+  weekStartCache.set(locale, start);
+  return start;
+}
+function rotateWeek(sundayFirst, start) {
+  return [...sundayFirst.slice(start), ...sundayFirst.slice(0, start)];
+}
+const weekdayOffset = (day, start) => (day - start + 7) % 7;
+function weekdayNamesIn(locale, width) {
+  const format = new Intl.DateTimeFormat(locale, { weekday: width, timeZone: "UTC" });
+  return Array.from({ length: 7 }, (_, day) => format.format(Date.UTC(2023, 0, 1 + day)));
+}
+function isEnglish(locale) {
+  try {
+    return new Intl.Locale(locale).language === "en";
+  } catch {
+    return false;
+  }
+}
+function uses12HourClock(locale) {
+  const cycle = new Intl.DateTimeFormat(locale, { hour: "numeric" }).resolvedOptions().hourCycle;
+  return cycle === "h11" || cycle === "h12";
+}
+const numberFormats = /* @__PURE__ */ new Map();
+function formatNumber(value, locale) {
+  let format = numberFormats.get(locale);
+  if (!format) {
+    format = new Intl.NumberFormat(locale, { maximumFractionDigits: 3 });
+    numberFormats.set(locale, format);
+  }
+  return format.format(value);
+}
+const axisFormats = /* @__PURE__ */ new Map();
+function formatAxisNumber(value, locale) {
+  let format = axisFormats.get(locale);
+  if (!format) {
+    format = new Intl.NumberFormat(locale, {
+      maximumFractionDigits: 3,
+      // 'min2' is CLDR's grouping for short numbers; the type lags the spec.
+      useGrouping: "min2"
+    });
+    axisFormats.set(locale, format);
+  }
+  return format.format(value);
+}
+const percentFormats = /* @__PURE__ */ new Map();
+function formatPercent(percent, locale) {
+  let format = percentFormats.get(locale);
+  if (!format) {
+    format = new Intl.NumberFormat(locale, { style: "percent", maximumFractionDigits: 0 });
+    percentFormats.set(locale, format);
+  }
+  return format.format(percent / 100);
+}
+export {
+  DEFAULT_LOCALE,
+  formatAxisNumber,
+  formatNumber,
+  formatPercent,
+  isEnglish,
+  rotateWeek,
+  uses12HourClock,
+  weekStartOf,
+  weekdayNamesIn,
+  weekdayOffset
+};

package/behaviors/shortcut-keys.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The shortcut grammar and how a shortcut is drawn, with no React and no
+ * browser API, so a component that renders from a Server Component can
+ * draw or announce a shortcut too. The listener and the hooks are
+ * shortcuts.ts, which owns the grammar's description.
+ */
+/** A shortcut in the grammar above, such as `mod+k`, `shift+?` or `g i`. */
+export type Shortcut = string;
+/** The platform a shortcut is read and drawn for: `apple` maps `mod` to ⌘, `other` to Ctrl. */
+export type ShortcutPlatform = 'apple' | 'other';
+/** The legends a shortcut is drawn with, by modifier or key name. Merged over the platform's defaults. */
+export type ShortcutKeyLabels = Partial<Record<string, string>>;
+/** One step of a shortcut: its key and the modifiers held with it. */
+export type Step = {
+    key: string;
+    mod: boolean;
+    ctrl: boolean;
+    meta: boolean;
+    alt: boolean;
+    shift: boolean;
+};
+export declare const KEY_ALIASES: Record<string, string>;
+/** A shortcut's steps, parsed once. A step written `ctrl++` would be ambiguous, so `plus` names the key. */
+export declare const parseShortcut: (shortcut: Shortcut) => Step[];
+/** The platform this code runs on, read from the browser. `other` on the server. */
+export declare const detectPlatform: () => ShortcutPlatform;
+/**
+ * A shortcut as keycap legends, one array per step: `mod+shift+p` is
+ * `[['⇧', '⌘', 'P']]` on a Mac and `[['Ctrl', 'Shift', 'P']]` elsewhere.
+ * `labels` replaces any legend, such as `{ ctrl: 'Strg' }` for a German
+ * keyboard.
+ */
+export declare function shortcutKeys(shortcut: Shortcut, platform: ShortcutPlatform, labels?: ShortcutKeyLabels): string[][];
+/**
+ * A shortcut as one line of text, for a menu row: `⇧⌘P` on a Mac and
+ * `Ctrl+Shift+P` elsewhere, the steps of a sequence spaced apart.
+ */
+export declare function formatShortcut(shortcut: Shortcut, platform: ShortcutPlatform, labels?: ShortcutKeyLabels): string;
+/**
+ * A single-step shortcut as an `aria-keyshortcuts` value (`Meta+K` on a Mac,
+ * `Control+K` elsewhere). A sequence has no ARIA form, so it gives undefined.
+ */
+export declare function shortcutAria(shortcut: Shortcut, platform: ShortcutPlatform): string | undefined;
+/**
+ * A shortcut as an `aria-keyshortcuts` value for both platforms at once
+ * (`Meta+K Control+K` for `mod+k`), for markup that renders on the server or
+ * before the platform is known. Undefined for a sequence.
+ */
+export declare function shortcutAriaAnyPlatform(shortcut: Shortcut): string | undefined;