@milktop/react-ui 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,174 @@
-# Temporary Holding Version
+# @milktop/react-ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React components on [Ark UI](https://ark-ui.com) (and so on
+[Zag](https://zagjs.com) state machines), with
+[imba-ui](https://github.com/milktop/imba-ui)'s and
+[svelte-ui](https://github.com/milktop/svelte-ui)'s API, tokens and design.
+
+## One component, or its parts
+
+Every component is a **shortcut**: one element, props in, done.
+
+```jsx
+import { Field, Select, Checkbox, Button } from '@milktop/react-ui'
+
+<Field label="Student" error={errors.student}>
+  <Select items={students} labelKey="name" valueKey="id" value={student} onValueChange={setStudent} />
+</Field>
+<Checkbox label="Remind them" checked={remind} onCheckedChange={setRemind} />
+<Button variant="primary" loading={saving}>Save</Button>
+```
+
+The same component carries its **parts**, for the times the shortcut's
+layout isn't what you need. They're Ark's own parts, styled by the same CSS,
+so a hand-built component looks just like the shortcut:
+
+```jsx
+<Checkbox.Root>
+  <Checkbox.Label>Terms</Checkbox.Label>
+  <Checkbox.Control><Checkbox.Indicator>✓</Checkbox.Indicator></Checkbox.Control>
+  <a href="/terms">read them</a>
+  <Checkbox.HiddenInput />
+</Checkbox.Root>
+```
+
+No CLI and no copied snippets: every shortcut ships in the package, and
+where one doesn't fit you build from the parts.
+
+## Components
+
+So far:
+
+- Actions: Button · CopyButton
+- Display: Avatar · AvatarGroup · Badge · Card (props or composed from Card.Header/Body/Footer) ·
+  Table (sorting, selection with Shift ranges, loading, custom cells; `sortRows`) ·
+  Pagination · DataList · Stat · Stats · Timeline · TreeView · Editable (edit in place) · Attachments (tiles or a list,
+  click-to-enlarge images) · Charts (AreaChart, BarChart, DonutChart, Sparkline; d3 for the maths)
+- Text and numbers: FormatNumber · FormatBytes · FormatRelative (and `formatNumber`, `formatBytes`,
+  `formatRelative`) · RollingNumber · Divider · Kbd · Prose (rich text as the Editor shows it) · Highlight (search matches)
+- Feedback: Alert · Banner · Progress · Skeleton · Spinner · EmptyState
+- Inputs: Input · Textarea · Editor (rich text on TipTap, with image uploads) · NumberInput · PasswordInput · PinInput · TagsInput ·
+  Slider · FileUpload
+- Pickers: TimeInput · NativeSelect · SwatchPicker · Select (one component: searchable, server `load`, `onCreate`,
+  multiple, tags; Combobox's parts for building one by hand) · DatePicker
+- Choices: Checkbox · CheckboxGroup · Switch · RadioGroup · Segmented ·
+  ThemeToggle (`colorScheme`, `useColorScheme`)
+- Forms: Field · Fields
+- Overlays: Tooltip · Popover · HoverCard · Dialog · Sheet (both: props or
+  composed from Header/Body/Footer) · ActionBar · Menu · ContextMenu (Menu.Item,
+  Separator, Group, Checkbox, RadioGroup/Radio, Submenu; also as MenuItem…) ·
+  Toaster (`toaster.success(…)` from anywhere) · `confirm()` (`await confirm({ … })`
+  from anywhere, no state or markup)
+- Scheduling and ordering (React only): EventCalendar (day, n days, work week or
+  week by the hour, with resources such as vets or rooms as columns; drag to
+  select a time, drag or arrow-key events to move and resize them, all-day
+  events, a date jump) · SortableList (drag or keyboard, on dnd-kit)
+- Disclosure: Tabs/Tab (with counts and dots, inline or in the corner) · Accordion · Collapsible
+- Navigation: AppShell (flat or inset; the sidebar collapses to a rail with ⌘B
+  and is a drawer on phones) · Topbar · Sidebar (NavSection, NavGroup, NavItem,
+  SidebarUser; also Sidebar.Section…) · Page · Breadcrumbs · Command (⌘K)
+
+That's all of svelte-ui's components.
+
+The playground runs on the library's own AppShell, Sidebar, Topbar, Page,
+Breadcrumbs and Command, with an Appearance panel (accent, font, radius,
+density, layout), Theming and Installation guides, and blocks: whole pages
+(dashboard, students, profile, inbox, settings, sign-in) and sections.
+
+## Locale
+
+Wrap the app in `<LocaleProvider locale="fr-FR">` and formatting, DatePicker,
+EventCalendar, Progress, Slider and the charts follow it (each still takes its
+own `locale`). `useLocale()` gives it to your own code.
+
+The components' own words (placeholders, empty states, "Showing 1–10 of 95",
+screen-reader labels, Zag's included) follow it too: English and French are
+built in, in `src/format/messages.ts`. Change any of them with `messages`,
+merged over the built-in list:
+
+    <LocaleProvider locale="fr-FR" messages={{ table: { empty: 'Aucun patient' } }}>
+
+For another language, give a whole list (start from the exported `en`). A
+prop given to a component (`placeholder`, `emptyText`, EventCalendar's
+`translations`) still wins. `confirm()`, which renders in its own root, uses
+the words of the app's provider.
+
+## Every component works the same way
+
+- One package and namespace: `import { Button, Select } from '@milktop/react-ui'`.
+- Values: `value` (or `checked`, `open`) to control it, `defaultValue` to
+  start it, and `onValueChange` (or `onCheckedChange`, `onOpenChange`) called
+  with the new value itself, not Ark's details object.
+- `className`: classes for the outer element.
+- `classes`: classes per part, keyed by camelCased part name
+  (`classes={{ itemText: 'font-mono' }}`).
+- Slots replace a part's content: a node, or a function given its state
+  (`indicator={({ indeterminate }) => …}`, `renderItem={(item) => …}`).
+- `style={{ '--ui-accent': … }}`: tokens for one instance; on `:root` for the whole app.
+- Typed: written in TypeScript, shipped as JS with `.d.ts` types, so TSX apps
+  get checked props (Select's value is the type of your items' `valueKey`)
+  and JSX apps get autocomplete, with no errors either way.
+- Other props go to the natural element (the button, the input, Ark's root).
+
+Parts carry Zag's `data-scope` and `data-part` attributes, which the CSS
+targets, all in `@layer ui`. So your classes and Tailwind's utilities always
+win without `!important`. Part names are Ark's, so they match what you'd
+write by hand (a Field's hint is `helper-text`, its error `error-text`).
+
+## Setup
+
+Components import their own CSS. With Tailwind, declare the layer order at
+the top of your app's CSS, so its reset stays below the library and its
+utilities above:
+
+```css
+@layer theme, base, ui, components, utilities;
+@import "tailwindcss";
+```
+
+Theme it by setting tokens (see `src/theme.css`, shared with svelte-ui);
+dark values apply under `html.dark`:
+
+```css
+:root { --ui-accent: #e11d48; --ui-radius: 10px; }
+```
+
+### React Server Components
+
+Not supported yet, and not needed in Vite apps. A server component can't
+read `Checkbox.Root` off a client component; when that's needed, the parts
+will also be exported by name (`CheckboxRoot`…), and the files will get
+`'use client'`.
+
+## Develop
+
+```sh
+npm install
+npm run dev        # the playground, http://localhost:5194
+npm run check      # types (tsc) and React's hook rules
+npm run build      # the playground as a static site, in playground/dist
+npm run build:lib  # the package: src/ to dist/ (JS, .d.ts, CSS); runs before npm publish
+```
+
+Releasing (logged in with `npm login`, on a clean main): each runs the checks
+and the build, bumps the version, commits and tags it, pushes with the tag,
+then publishes.
+
+```sh
+npm run release:patch   # 0.1.0 → 0.1.1
+npm run release:minor   # 0.1.0 → 0.2.0
+npm run release:major   # 0.1.0 → 1.0.0
+npm run release:beta    # 0.1.0 → 0.1.1-beta.0, published under the beta tag
+```
+
+Each playground page shows its component's doc comment, and its examples are
+the files in `playground/examples/<component>/`, shown with their code. The
+playground compiles the TSX source directly, so it never needs `build:lib`.
+
+## Deploy the playground
+
+`npm run build` writes a static, client-side site to `playground/dist`, set
+up for **Cloudflare Pages** just like svelte-ui: framework preset None, build
+command `npm run build`, output directory `playground/dist`, Node 22 from
+`.nvmrc`. The site routes on the URL hash (no SPA fallback needed) and is kept
+out of search results by a `noindex` meta tag and `playground/public/_headers`.

package/dist/accordion/Accordion.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Sections behind headings that expand them.
+ *
+ *   <Accordion value={open} onValueChange={setOpen}>
+ *     <Accordion.Item value="pricing" heading="How much are lessons?">…</Accordion.Item>
+ *     <Accordion.Item value="cancel" heading="Can I cancel?">…</Accordion.Item>
+ *   </Accordion>
+ *
+ *   <Accordion items={[{ value: 'pricing', heading: 'How much are lessons?', content: '…' }]} />
+ *
+ * Arrow keys move between headings, Home/End jump to the ends.
+ *
+ * - `value`, `defaultValue`: the open item's value (or null), or an array of
+ *   them with `multiple`; `onValueChange`: called with the new one
+ * - `multiple`: several open at once
+ * - `collapsible`: the open item can be closed again (default true)
+ * - `items`: `{ value, heading, content, disabled }`, before any children
+ * - Accordion.Item (also AccordionItem): `value`, `heading` (text or
+ *   markup), `disabled`; its content is what it expands
+ *
+ * By hand, Ark's parts are here too: Accordion.Root, ItemTrigger,
+ * ItemIndicator, ItemContent… (Accordion.Item is ours; Ark's is
+ * Accordion.RawItem).
+ */
+import { type ReactNode } from 'react';
+import { Accordion as Ark } from '@ark-ui/react/accordion';
+import 'iconify-icon';
+import { type Classes } from '../utils.js';
+import '../theme.css';
+import './accordion.css';
+type Value = string | number;
+export type AccordionEntry = {
+    value: Value;
+    heading: ReactNode;
+    content?: ReactNode;
+    disabled?: boolean;
+};
+export type AccordionProps<V extends Value = Value> = Omit<Ark.RootProps, 'value' | 'defaultValue' | 'onValueChange' | 'multiple' | 'collapsible'> & {
+    value?: V | V[] | null;
+    defaultValue?: V | V[] | null;
+    onValueChange?: (value: V | V[] | null) => void;
+    multiple?: boolean;
+    collapsible?: boolean;
+    items?: AccordionEntry[] | null;
+    classes?: Classes<'root' | 'item' | 'heading' | 'itemTrigger' | 'headingText' | 'itemIndicator' | 'itemContent' | 'inner'>;
+};
+declare function AccordionShortcut<V extends Value = Value>({ value, defaultValue, onValueChange, multiple, collapsible, items, className, classes, children, ...rest }: AccordionProps<V>): import("react").JSX.Element;
+export type AccordionItemProps = Omit<Ark.ItemProps, 'value'> & {
+    value: Value;
+    heading?: ReactNode;
+};
+/** One section of an Accordion: a heading button and the content it expands. */
+export declare function AccordionItem({ value, heading, disabled, className, children, ...rest }: AccordionItemProps): import("react").JSX.Element;
+export declare const Accordion: typeof AccordionShortcut & {
+    Item: typeof AccordionItem;
+    Root: import("react").ForwardRefExoticComponent<Ark.RootProps & import("react").RefAttributes<HTMLDivElement>>;
+    RootProvider: import("react").ForwardRefExoticComponent<Ark.RootProviderProps & import("react").RefAttributes<HTMLDivElement>>;
+    RawItem: import("react").ForwardRefExoticComponent<Ark.ItemProps & import("react").RefAttributes<HTMLDivElement>>;
+    ItemTrigger: import("react").ForwardRefExoticComponent<Ark.ItemTriggerProps & import("react").RefAttributes<HTMLButtonElement>>;
+    ItemIndicator: import("react").ForwardRefExoticComponent<Ark.ItemIndicatorProps & import("react").RefAttributes<HTMLDivElement>>;
+    ItemContent: import("react").ForwardRefExoticComponent<Ark.ItemContentProps & import("react").RefAttributes<HTMLDivElement>>;
+    Context: (props: Ark.ContextProps) => ReactNode;
+    ItemContext: (props: Ark.ItemContextProps) => ReactNode;
+};
+export {};

package/dist/accordion/Accordion.js

@@ -0,0 +1,61 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Sections behind headings that expand them.
+ *
+ *   <Accordion value={open} onValueChange={setOpen}>
+ *     <Accordion.Item value="pricing" heading="How much are lessons?">…</Accordion.Item>
+ *     <Accordion.Item value="cancel" heading="Can I cancel?">…</Accordion.Item>
+ *   </Accordion>
+ *
+ *   <Accordion items={[{ value: 'pricing', heading: 'How much are lessons?', content: '…' }]} />
+ *
+ * Arrow keys move between headings, Home/End jump to the ends.
+ *
+ * - `value`, `defaultValue`: the open item's value (or null), or an array of
+ *   them with `multiple`; `onValueChange`: called with the new one
+ * - `multiple`: several open at once
+ * - `collapsible`: the open item can be closed again (default true)
+ * - `items`: `{ value, heading, content, disabled }`, before any children
+ * - Accordion.Item (also AccordionItem): `value`, `heading` (text or
+ *   markup), `disabled`; its content is what it expands
+ *
+ * By hand, Ark's parts are here too: Accordion.Root, ItemTrigger,
+ * ItemIndicator, ItemContent… (Accordion.Item is ours; Ark's is
+ * Accordion.RawItem).
+ */
+import { createContext, useContext, useRef } from 'react';
+import { Accordion as Ark } from '@ark-ui/react/accordion';
+import 'iconify-icon';
+import { cx, partsOf, useControllable, withParts } from '../utils.js';
+import '../theme.css';
+import './accordion.css';
+// The items register their values (numbers stay numbers) by string key.
+const AccordionContext = createContext(null);
+const keys = (value) => [].concat(value ?? []).map(String);
+function AccordionShortcut({ value, defaultValue = null, onValueChange, multiple = false, collapsible = true, items = null, className, classes, children, ...rest }) {
+    const part = partsOf('accordion', classes);
+    const values = useRef(new Map());
+    const [current, setCurrent] = useControllable(value, defaultValue, onValueChange);
+    return (_jsx(AccordionContext, { value: { part, remember: (v) => { values.current.set(String(v), v); } }, children: _jsxs(Ark.Root, { ...rest, ...part('root'), className: cx(className, classes?.root), multiple: multiple, collapsible: multiple || collapsible, value: keys(current), onValueChange: (details) => {
+                const picked = details.value.map((key) => (values.current.get(key) ?? key));
+                setCurrent(multiple ? picked : (picked[0] ?? null));
+            }, children: [(items ?? []).map((item) => (_jsx(AccordionItem, { value: item.value, heading: item.heading, disabled: item.disabled, children: item.content }, item.value))), children] }) }));
+}
+/** One section of an Accordion: a heading button and the content it expands. */
+export function AccordionItem({ value, heading = null, disabled = false, className, children, ...rest }) {
+    const accordion = useContext(AccordionContext);
+    const part = accordion?.part ?? partsOf('accordion');
+    accordion?.remember(value);
+    return (_jsxs(Ark.Item, { ...rest, ...part('item'), className: cx(className, part('item').className), value: String(value), disabled: disabled, children: [_jsx("h3", { ...part('heading'), children: _jsxs(Ark.ItemTrigger, { ...part('item-trigger'), children: [_jsx("span", { ...part('heading-text'), children: heading }), _jsx(Ark.ItemIndicator, { ...part('item-indicator'), children: _jsx("iconify-icon", { icon: "lucide:chevron-down" }) })] }) }), _jsx(Ark.ItemContent, { ...part('item-content'), children: _jsx("div", { ...part('inner'), children: children }) })] }));
+}
+export const Accordion = withParts(AccordionShortcut, {
+    Item: AccordionItem,
+    Root: Ark.Root,
+    RootProvider: Ark.RootProvider,
+    RawItem: Ark.Item,
+    ItemTrigger: Ark.ItemTrigger,
+    ItemIndicator: Ark.ItemIndicator,
+    ItemContent: Ark.ItemContent,
+    Context: Ark.Context,
+    ItemContext: Ark.ItemContext,
+});

package/dist/accordion/accordion.css

@@ -0,0 +1,17 @@
+@layer ui {
+  [data-scope=accordion][data-part=root] { display: block; width: 100%; color: var(--ui-text); font-family: var(--ui-font); border-top: 1px solid var(--ui-border); }
+  [data-scope=accordion][data-part=item] { display: block; border-bottom: 1px solid var(--ui-border); }
+  [data-scope=accordion][data-part=heading] { margin: 0; font-size: inherit; font-weight: inherit; }
+  [data-scope=accordion][data-part=item-trigger] {
+    display: flex; align-items: center; justify-content: space-between; gap: 1rem; width: 100%; padding: 1rem 0;
+    border: none; background: transparent; color: inherit; font: inherit; font-size: 14px; font-weight: 500; text-align: left; cursor: pointer;
+    &:hover { text-decoration: underline; }
+    &:focus-visible { outline: 2px solid var(--ui-ring-soft); outline-offset: 2px; border-radius: 4px; }
+    &:disabled { opacity: 0.5; cursor: not-allowed; text-decoration: none; }
+  }
+  [data-scope=accordion][data-part=item-indicator] { display: inline-flex; color: var(--ui-muted); font-size: 16px; transition: transform 200ms;
+    &[data-state=open] { transform: rotate(180deg); } }
+  [data-scope=accordion][data-part=item-content] { &[data-state=open] { animation: ui-accordion-in 180ms ease-out; } }
+  [data-scope=accordion][data-part=inner] { padding-bottom: 1rem; color: var(--ui-muted); font-size: 14px; }
+  @keyframes ui-accordion-in { from { opacity: 0; transform: translateY(-4px); } }
+}

package/dist/action-bar/ActionBar.d.ts

@@ -0,0 +1,33 @@
+/**
+ * A small toolbar floating at the bottom of the screen while something is
+ * selected, e.g. table rows.
+ *
+ *   <ActionBar open={picked.length > 0} onClose={() => setPicked([])} selection={`${picked.length} selected`}>
+ *     <Button size="sm">Message</Button>
+ *     <Button size="sm" variant="danger">Archive</Button>
+ *   </ActionBar>
+ *
+ * It isn't modal: the page stays usable (keep ticking rows) and focus isn't
+ * moved. It's rendered at the end of <body>, a toolbar for assistive tech,
+ * centred over the main area beside an AppShell's sidebar.
+ *
+ * - `open`: shows it
+ * - `selection`: the count or summary on the left
+ * - `closable`: false hides the close button; it (and Escape inside the bar)
+ *   calls `onClose`, where you'd clear the selection
+ * - `label`: the toolbar's accessible name
+ */
+import { type ComponentProps, type ReactNode } from 'react';
+import 'iconify-icon';
+import { type Classes } from '../utils.js';
+import '../theme.css';
+import './action-bar.css';
+export type ActionBarProps = ComponentProps<'div'> & {
+    open?: boolean;
+    closable?: boolean;
+    label?: string;
+    onClose?: (() => void) | null;
+    selection?: ReactNode;
+    classes?: Classes<'positioner' | 'content' | 'selection' | 'separator' | 'actions' | 'close'>;
+};
+export declare function ActionBar({ open, closable, label: labelProp, onClose, selection, className, classes, children, ...rest }: ActionBarProps): import("react").JSX.Element | null;

package/dist/action-bar/ActionBar.js

@@ -0,0 +1,48 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * A small toolbar floating at the bottom of the screen while something is
+ * selected, e.g. table rows.
+ *
+ *   <ActionBar open={picked.length > 0} onClose={() => setPicked([])} selection={`${picked.length} selected`}>
+ *     <Button size="sm">Message</Button>
+ *     <Button size="sm" variant="danger">Archive</Button>
+ *   </ActionBar>
+ *
+ * It isn't modal: the page stays usable (keep ticking rows) and focus isn't
+ * moved. It's rendered at the end of <body>, a toolbar for assistive tech,
+ * centred over the main area beside an AppShell's sidebar.
+ *
+ * - `open`: shows it
+ * - `selection`: the count or summary on the left
+ * - `closable`: false hides the close button; it (and Escape inside the bar)
+ *   calls `onClose`, where you'd clear the selection
+ * - `label`: the toolbar's accessible name
+ */
+import { useEffect, useState } from 'react';
+import { Portal } from '@ark-ui/react/portal';
+import 'iconify-icon';
+import { cx, partsOf } from '../utils.js';
+import { useMessages } from '../format/LocaleProvider.js';
+import '../theme.css';
+import './action-bar.css';
+export function ActionBar({ open = false, closable = true, label: labelProp, onClose = null, selection = null, className, classes, children, ...rest }) {
+    const t = useMessages();
+    const label = labelProp ?? t.actionBar.label;
+    const part = partsOf('action-bar', classes);
+    // Kept in the page until its closing animation ends (or 300 ms, if none
+    // runs, as with reduced motion).
+    const [present, setPresent] = useState(open);
+    if (open && !present)
+        setPresent(true);
+    useEffect(() => {
+        if (open || !present)
+            return;
+        const timer = setTimeout(() => setPresent(false), 300);
+        return () => clearTimeout(timer);
+    }, [open, present]);
+    if (!present)
+        return null;
+    return (_jsx(Portal, { children: _jsx("div", { ...part('positioner'), children: _jsxs("div", { ...rest, ...part('content'), className: cx(className, classes?.content), role: "toolbar", "aria-label": label, "data-state": open ? 'open' : 'closed', onAnimationEnd: (e) => { if (e.target === e.currentTarget && !open)
+                    setPresent(false); }, onKeyDown: (e) => { if (e.key === 'Escape')
+                    onClose?.(); }, children: [selection != null && _jsxs(_Fragment, { children: [_jsx("div", { ...part('selection'), children: selection }), _jsx("span", { ...part('separator'), "aria-hidden": "true" })] }), _jsx("div", { ...part('actions'), children: children }), closable && _jsx("button", { ...part('close'), type: "button", "aria-label": t.common.close, onClick: () => onClose?.(), children: _jsx("iconify-icon", { icon: "lucide:x" }) })] }) }) }));
+}

package/dist/action-bar/action-bar.css

@@ -0,0 +1,22 @@
+@layer ui {
+  /* Centred along the bottom (over the main area, beside AppShell's sidebar); only the bar takes clicks. */
+  [data-scope=action-bar][data-part=positioner] { position: fixed; left: var(--ui-main-left, 0px); right: 0; bottom: 1rem; z-index: 90;
+    display: flex; justify-content: center; padding: 0 1rem; pointer-events: none; transition: left 200ms ease;
+    @media (min-width: 768px) { bottom: 1.5rem; } }
+  [data-scope=action-bar][data-part=content] {
+    display: flex; align-items: center; gap: 0.5rem; max-width: 100%; min-height: 2.75rem; padding: 0.375rem 0.375rem 0.375rem 1rem; box-sizing: border-box;
+    background: var(--ui-surface); color: var(--ui-text); font-family: var(--ui-font); font-size: 14px;
+    border: 1px solid var(--ui-border); border-radius: calc(var(--ui-radius) + 6px); box-shadow: var(--ui-shadow); pointer-events: auto;
+    &[data-state=open] { animation: ui-action-bar-in 180ms cubic-bezier(0.32, 0.72, 0, 1); }
+    &[data-state=closed] { animation: ui-action-bar-out 140ms ease-in forwards; }
+  }
+  [data-scope=action-bar][data-part=selection] { font-weight: 500; white-space: nowrap; }
+  [data-scope=action-bar][data-part=separator] { width: 1px; height: 1.25rem; background: var(--ui-border); flex-shrink: 0; }
+  [data-scope=action-bar][data-part=actions] { display: flex; align-items: center; gap: 0.375rem; flex-wrap: wrap; }
+  [data-scope=action-bar][data-part=close] { display: grid; place-items: center; width: 2rem; height: 2rem; flex-shrink: 0;
+    border: none; border-radius: var(--ui-radius); background: transparent; color: var(--ui-muted); cursor: pointer; font-size: 14px;
+    &:hover { background: var(--ui-hover); color: var(--ui-text); }
+    &:focus-visible { outline: 2px solid var(--ui-ring-soft); } }
+  @keyframes ui-action-bar-in { from { opacity: 0; transform: translateY(12px); } }
+  @keyframes ui-action-bar-out { to { opacity: 0; transform: translateY(12px); } }
+}

package/dist/alert/Alert.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A message in the page (not a popup; see Toast for those).
+ *
+ *   <Alert variant="warning" heading="Payment overdue">Ada's invoice is 5 days late.</Alert>
+ *
+ * - `variant`: 'info' (default), 'success', 'warning' or 'danger'
+ * - `heading`: a bold first line; the content is the message
+ * - `icon`: an Iconify name in place of the variant's, or false for none
+ * - `onDismiss`: shows a close button that calls it (hide the alert in response)
+ * - `actions`: buttons under the message
+ *
+ * Danger and warning alerts are role=alert, so assistive tech announces them
+ * when they appear; the others are role=status.
+ */
+import type { ComponentProps, ReactNode } from 'react';
+import 'iconify-icon';
+import { type Classes } from '../utils.js';
+import '../theme.css';
+import './alert.css';
+export type AlertProps = ComponentProps<'div'> & {
+    variant?: 'info' | 'success' | 'warning' | 'danger';
+    heading?: ReactNode;
+    icon?: string | boolean;
+    onDismiss?: (() => void) | null;
+    actions?: ReactNode;
+    classes?: Classes<'root' | 'icon' | 'text' | 'heading' | 'description' | 'actions' | 'close'>;
+};
+export declare function Alert({ variant, heading, icon, onDismiss, actions, className, classes, children, ...rest }: AlertProps): import("react").JSX.Element;

package/dist/alert/Alert.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import 'iconify-icon';
+import { cx, partsOf } from '../utils.js';
+import { useMessages } from '../format/LocaleProvider.js';
+import '../theme.css';
+import './alert.css';
+const icons = { info: 'lucide:info', success: 'lucide:circle-check', warning: 'lucide:triangle-alert', danger: 'lucide:circle-alert' };
+export function Alert({ variant = 'info', heading = null, icon = true, onDismiss = null, actions = null, className, classes, children, ...rest }) {
+    const t = useMessages();
+    const part = partsOf('alert', classes);
+    return (_jsxs("div", { ...rest, ...part('root'), className: cx(className, classes?.root), "data-variant": variant, role: variant === 'danger' || variant === 'warning' ? 'alert' : 'status', children: [icon && _jsx("iconify-icon", { ...part('icon'), icon: icon === true ? icons[variant] ?? icons.info : icon, "aria-hidden": "true" }), _jsxs("div", { ...part('text'), children: [heading && _jsx("div", { ...part('heading'), children: heading }), children != null && _jsx("div", { ...part('description'), children: children }), actions && _jsx("div", { ...part('actions'), children: actions })] }), onDismiss && (_jsx("button", { ...part('close'), type: "button", "aria-label": t.common.dismiss, onClick: onDismiss, children: _jsx("iconify-icon", { icon: "lucide:x" }) }))] }));
+}

package/dist/alert/alert.css

@@ -0,0 +1,26 @@
+@layer ui {
+  [data-scope=alert][data-part=root] {
+    display: flex; align-items: flex-start; gap: 0.75rem; padding: 1rem; box-sizing: border-box;
+    border: 1px solid var(--ui-border); border-radius: var(--ui-radius); background: var(--ui-surface);
+    color: var(--ui-text); font-family: var(--ui-font); font-size: 14px; line-height: 1.45;
+    --tint: var(--ui-text);
+    &[data-variant=info] { background: var(--ui-accent-soft); border-color: transparent; --tint: var(--ui-accent-soft-text); }
+    &[data-variant=success] { background: #f0fdf4; border-color: #bbf7d0; --tint: #166534; }
+    &[data-variant=warning] { background: #fffbeb; border-color: #fde68a; --tint: #92400e; }
+    &[data-variant=danger] { background: #fef2f2; border-color: #fecaca; --tint: #991b1b; }
+    :is(.dark, [data-theme=dark]) &[data-variant=success] { background: #052e16; border-color: #14532d; --tint: #86efac; }
+    :is(.dark, [data-theme=dark]) &[data-variant=warning] { background: #1c1004; border-color: #451a03; --tint: #fcd34d; }
+    :is(.dark, [data-theme=dark]) &[data-variant=danger] { background: #1f0505; border-color: #450a0a; --tint: #fca5a5; }
+  }
+  [data-scope=alert][data-part=icon] { flex-shrink: 0; margin-top: 1px; font-size: 18px; color: var(--tint); }
+  [data-scope=alert][data-part=text] { flex: 1; min-width: 0; }
+  [data-scope=alert][data-part=heading] { font-weight: 600; margin-bottom: 0.125rem; color: var(--tint); }
+  [data-scope=alert][data-part=description] { color: var(--ui-muted); }
+  [data-scope=alert][data-part=actions] { display: flex; flex-wrap: wrap; gap: 0.5rem; margin-top: 0.75rem; }
+  [data-scope=alert][data-part=close] {
+    display: grid; place-items: center; flex-shrink: 0; width: 1.5rem; height: 1.5rem; margin: -0.25rem -0.25rem 0 0;
+    border: none; background: transparent; border-radius: 4px; color: var(--ui-muted); cursor: pointer; font-size: 14px;
+    &:hover { background: rgba(0, 0, 0, 0.06); color: var(--ui-text); }
+    &:focus-visible { outline: 2px solid var(--ui-ring-soft); }
+  }
+}

package/dist/app-shell/AppShell.d.ts

@@ -0,0 +1,38 @@
+/**
+ * An app layout: the sidebar down the left, the top bar and page beside it.
+ * Put a Sidebar, a Topbar and a Page inside; each takes its place.
+ *
+ *   <AppShell inset persist="app:sidebar">
+ *     <Sidebar logo="TutorApp">…</Sidebar>
+ *     <Topbar end={<Button icon="lucide:bell" aria-label="Notifications" />}>…</Topbar>
+ *     <Page heading="Students">…</Page>
+ *   </AppShell>
+ *
+ * - `inset`: the page as a rounded panel on a frame, with a grey sidebar
+ *   whose hovered and current items go white (the `--ui-sidebar-inset-*` tokens)
+ * - `collapsed`, `defaultCollapsed`; `onCollapsedChange`: the sidebar as an
+ *   icon rail
+ * - `persist`: a localStorage key to remember `collapsed`
+ * - `breakpoint`: below this width (768px) the sidebar is a drawer, opened
+ *   from the top bar's menu button
+ * - `shortcut`: false to leave ⌘B alone (for a second shell on the page)
+ *
+ * ⌘B (Ctrl+B) collapses the sidebar, or opens the drawer on phones; Escape
+ * closes the drawer. Parts inside read the shell with `useShell()`.
+ */
+import { type HTMLAttributes } from 'react';
+import { type Classes } from '../utils.js';
+import '../theme.css';
+import './app-shell.css';
+export type AppShellProps = HTMLAttributes<HTMLDivElement> & {
+    inset?: boolean;
+    collapsed?: boolean;
+    defaultCollapsed?: boolean;
+    onCollapsedChange?: (collapsed: boolean) => void;
+    persist?: string | null;
+    breakpoint?: number;
+    shortcut?: boolean;
+    classes?: Classes<'root' | 'backdrop'>;
+};
+export declare function AppShell({ inset, collapsed: collapsedProp, defaultCollapsed, onCollapsedChange, persist, breakpoint, shortcut, className, classes, children, ...rest }: AppShellProps): import("react").JSX.Element;
+export { useShell } from './shell.js';

package/dist/app-shell/AppShell.js

@@ -0,0 +1,92 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * An app layout: the sidebar down the left, the top bar and page beside it.
+ * Put a Sidebar, a Topbar and a Page inside; each takes its place.
+ *
+ *   <AppShell inset persist="app:sidebar">
+ *     <Sidebar logo="TutorApp">…</Sidebar>
+ *     <Topbar end={<Button icon="lucide:bell" aria-label="Notifications" />}>…</Topbar>
+ *     <Page heading="Students">…</Page>
+ *   </AppShell>
+ *
+ * - `inset`: the page as a rounded panel on a frame, with a grey sidebar
+ *   whose hovered and current items go white (the `--ui-sidebar-inset-*` tokens)
+ * - `collapsed`, `defaultCollapsed`; `onCollapsedChange`: the sidebar as an
+ *   icon rail
+ * - `persist`: a localStorage key to remember `collapsed`
+ * - `breakpoint`: below this width (768px) the sidebar is a drawer, opened
+ *   from the top bar's menu button
+ * - `shortcut`: false to leave ⌘B alone (for a second shell on the page)
+ *
+ * ⌘B (Ctrl+B) collapses the sidebar, or opens the drawer on phones; Escape
+ * closes the drawer. Parts inside read the shell with `useShell()`.
+ */
+import { useCallback, useEffect, useMemo, useState, useSyncExternalStore } from 'react';
+import { cx, partsOf, useControllable } from '../utils.js';
+import { ShellContext } from './shell.js';
+import '../theme.css';
+import './app-shell.css';
+function saved(key) {
+    try {
+        const value = key ? localStorage.getItem(key) : null;
+        return value === null ? null : value === 'true';
+    }
+    catch {
+        return null;
+    }
+}
+// Whether the window is narrower than the breakpoint, kept current.
+function useNarrow(breakpoint) {
+    const query = `(max-width: ${breakpoint - 1}px)`;
+    const subscribe = useCallback((change) => {
+        const list = matchMedia(query);
+        list.addEventListener('change', change);
+        return () => list.removeEventListener('change', change);
+    }, [query]);
+    return useSyncExternalStore(subscribe, () => matchMedia(query).matches, () => false);
+}
+export function AppShell({ inset = false, collapsed: collapsedProp, defaultCollapsed = false, onCollapsedChange, persist = null, breakpoint = 768, shortcut = true, className, classes, children, ...rest }) {
+    const part = partsOf('app-shell', classes);
+    const [initial] = useState(() => saved(persist) ?? defaultCollapsed);
+    const [collapsed, setCollapsed] = useControllable(collapsedProp, initial, onCollapsedChange);
+    const mobile = useNarrow(breakpoint);
+    const [drawer, setDrawer] = useState(false);
+    // Widening the window past the breakpoint closes the drawer.
+    const drawerOpen = drawer && mobile;
+    const rail = collapsed && !mobile;
+    const toggle = useCallback(() => {
+        if (mobile)
+            return setDrawer(!drawerOpen);
+        setCollapsed(!collapsed);
+        try {
+            if (persist)
+                localStorage.setItem(persist, String(!collapsed));
+        }
+        catch { /* private mode */ }
+    }, [mobile, drawerOpen, collapsed, setCollapsed, persist]);
+    const shell = useMemo(() => ({ rail, mobile, drawerOpen, toggle, close: () => setDrawer(false) }), [rail, mobile, drawerOpen, toggle]);
+    // Where the main area starts, for things fixed to the viewport that centre
+    // over it (ActionBar).
+    useEffect(() => {
+        if (!shortcut)
+            return;
+        const left = mobile ? '0px' : rail ? 'var(--ui-sidebar-rail-width)' : 'var(--ui-sidebar-width)';
+        document.documentElement.style.setProperty('--ui-main-left', left);
+        return () => { document.documentElement.style.removeProperty('--ui-main-left'); };
+    }, [shortcut, mobile, rail]);
+    useEffect(() => {
+        function keydown(e) {
+            // Not in rich text editors, where it means bold.
+            if (shortcut && (e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'b' && !e.target?.isContentEditable) {
+                e.preventDefault();
+                toggle();
+            }
+            else if (e.key === 'Escape' && drawerOpen)
+                setDrawer(false);
+        }
+        addEventListener('keydown', keydown);
+        return () => removeEventListener('keydown', keydown);
+    }, [shortcut, toggle, drawerOpen]);
+    return (_jsx(ShellContext, { value: shell, children: _jsxs("div", { ...rest, ...part('root'), className: cx(className, classes?.root), "data-inset": inset || undefined, "data-rail": rail || undefined, "data-mobile": mobile || undefined, children: [children, drawerOpen && _jsx("div", { ...part('backdrop'), role: "presentation", onClick: () => setDrawer(false) })] }) }));
+}
+export { useShell } from './shell.js';