@wtfalch/design 0.6.0 → 0.8.0

package/dist/components/Toast.d.ts

@@ -1,27 +1,19 @@
-/**
- * Something happened, and it does not need answering.
- *
- * There is no transient feedback in this app at all. Every outcome is either a
- * `.callout` that stays until the page changes, or nothing -- so "saved",
- * "copied", "model removed" and "conversation deleted" are all silent, and the
- * only way to know a button worked is that something else moved.
- *
- * **A toast is for the outcome you would not have chased.** If the reader has to
- * act on it, it is a callout and belongs on the page. If they have to decide, it
- * is a dialog. This is the third case: it worked, you may carry on, and in four
- * seconds there will be no trace.
- *
- * **`role="status"`, not `alert`.** An alert interrupts whatever a screen reader
- * is saying, which is right for "the download failed" and rude for "copied".
- * The failing case passes `tone="bad"`, which is the one that promotes itself.
- */
 export interface Toast {
     text: string;
     /** The same four words `Callout` and `Pill` use. `warn` was missing here
      *  until 2026-09-05 -- three tones where the rest of the system has four. */
     tone: 'info' | 'good' | 'warn' | 'bad';
 }
-export declare function useToast(): (text: string, tone?: Toast["tone"]) => void;
+type Push = (text: string, tone?: Toast['tone']) => void;
+export declare function useToast(): Push;
+/**
+ * Whether anything above will actually show a toast.
+ *
+ * For a component that has a second way of saying something and would rather
+ * use it than push into the void. `useToast` outside a host is a no-op that
+ * typechecks, which is the failure this exists to let you avoid.
+ */
+export declare function useHasToastHost(): boolean;
 /**
  * The queue and the region, once, at the root.
  *
@@ -37,7 +29,21 @@ export declare function useToast(): (text: string, tone?: Toast["tone"]) => void
  * reachable; React Aria makes each toast an `alertdialog` inside a live
  * `region` for that reason, so the announcement still happens and the button
  * can still be reached.
+ *
+ * **Nesting one inside another is a no-op, and that is what makes this usable
+ * by a package.** `@wtfalch/email`'s mail client wanted to say "Archived."
+ * and could not: `useToast` needs a host above it, so the component would
+ * have had to wrap itself in one -- and then an application that already had
+ * a host would carry two regions announcing into the same page. It wrote its
+ * own `role="status"` strip instead and said so in a docblock, which is a
+ * package working around a package.
+ *
+ * So a `ToastHost` that finds one above it renders its children and steps
+ * aside. A library wraps itself unconditionally and gets the right answer
+ * both ways: its own region in an app that has none, and the app's region --
+ * one queue, one landmark, one place messages pile up -- in an app that does.
  */
 export declare function ToastHost({ children }: {
     children: React.ReactNode;
 }): import("react").JSX.Element;
+export {};

package/dist/components/Toast.js

@@ -1,4 +1,11 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+'use client';
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/* Client, because this module's own JSX attaches handlers or calls hooks. A
+   server component may still import it -- that is the point -- it simply
+   renders on the client. The ones without this line (Brand, Empty, Icon,
+   Illustration, Pill, Progress, Skeleton, Stat, Textarea, Table) render on
+   the server, which is why the directive is per component rather than one
+   line at the package's front door. */
 /**
  * Something happened, and it does not need answering.
  *
@@ -29,9 +36,23 @@ const MARK = {
  *  them does not pile up -- and paused while the pointer or focus is on it,
  *  because a message that expires while you are reading it was never shown. */
 const LINGER = 4000;
-const Ctx = createContext(() => { });
+/* `null`, not a no-op, so `ToastHost` can tell "nobody above me" from "a host
+   above me whose push happens to do nothing". `useToast` still hands back a
+   no-op, which is the old behaviour. */
+const Ctx = createContext(null);
+const NOOP = () => { };
 export function useToast() {
-    return useContext(Ctx);
+    return useContext(Ctx) ?? NOOP;
+}
+/**
+ * Whether anything above will actually show a toast.
+ *
+ * For a component that has a second way of saying something and would rather
+ * use it than push into the void. `useToast` outside a host is a no-op that
+ * typechecks, which is the failure this exists to let you avoid.
+ */
+export function useHasToastHost() {
+    return useContext(Ctx) !== null;
 }
 /**
  * The queue and the region, once, at the root.
@@ -48,8 +69,22 @@ export function useToast() {
  * reachable; React Aria makes each toast an `alertdialog` inside a live
  * `region` for that reason, so the announcement still happens and the button
  * can still be reached.
+ *
+ * **Nesting one inside another is a no-op, and that is what makes this usable
+ * by a package.** `@wtfalch/email`'s mail client wanted to say "Archived."
+ * and could not: `useToast` needs a host above it, so the component would
+ * have had to wrap itself in one -- and then an application that already had
+ * a host would carry two regions announcing into the same page. It wrote its
+ * own `role="status"` strip instead and said so in a docblock, which is a
+ * package working around a package.
+ *
+ * So a `ToastHost` that finds one above it renders its children and steps
+ * aside. A library wraps itself unconditionally and gets the right answer
+ * both ways: its own region in an app that has none, and the app's region --
+ * one queue, one landmark, one place messages pile up -- in an app that does.
  */
 export function ToastHost({ children }) {
+    const outer = useContext(Ctx);
     const queue = useMemo(() => new ToastQueue({ maxVisibleToasts: 4 }), []);
     /* What gets read aloud, and it is not the toast.
   
@@ -74,5 +109,11 @@ export function ToastHost({ children }) {
         say('');
         requestAnimationFrame(() => say(text));
     }, [queue]);
+    /* Somebody above owns the region. Render through: pushing into the outer
+       queue is what keeps one landmark and one pile of messages on the page.
+       After every hook, because a hook count that changes with context is a
+       React error. */
+    if (outer)
+        return _jsx(_Fragment, { children: children });
     return (_jsxs(Ctx.Provider, { value: push, children: [children, _jsx("div", { className: "sr-only", "aria-live": "polite", "aria-atomic": "true", children: polite }), _jsx("div", { className: "sr-only", "aria-live": "assertive", "aria-atomic": "true", children: assertive }), _jsx(ToastRegion, { queue: queue, className: "toasts", children: ({ toast }) => (_jsxs(AriaToast, { toast: toast, className: `toast toast-${toast.content.tone}`, children: [_jsx(Icon, { name: MARK[toast.content.tone], size: 16, className: "toast-mark" }), _jsx(ToastContent, { className: "grow", children: _jsx(Text, { slot: "title", children: toast.content.text }) }), _jsx(Button, { slot: "close", className: "ghost size-sm", "aria-label": "Dismiss", children: _jsx(Icon, { name: "close", size: 14 }) })] })) })] }));
 }

package/dist/components/Toggle.d.ts

@@ -1,33 +1,3 @@
-/**
- * A setting that takes effect as it moves.
- *
- * **A checkbox and a switch are not the same control, and the difference is not
- * visual.** A checkbox collects an answer: you tick it, and it applies when you
- * press Save. A switch *is* the action — flipping it changes the thing, now,
- * and there is nothing to confirm afterwards. That is why a switch reads as on
- * or off rather than ticked or blank: the two states are both settled, and
- * neither is a draft.
- *
- * Six settings in this app saved the moment they changed and were all drawn as
- * tick boxes: whether an applet is enabled, whether it reaches the internet,
- * whether a tool is granted, whether a server is trusted. Every one of them
- * promised a Save button that does not
- * exist. The header's status panel (gone since 2026-09-03) was the only one
- * that had it right, in a comment nobody else read.
- *
- * **`role="switch"`, so it is announced as one.** A screen reader says "on" and
- * "off" instead of "checked" and "not checked" — which is the same distinction
- * in words, and the only signal a non-visual reader gets that pressing it does
- * something immediately.
- *
- * **The label is the hit area.** A 30×18 target fails the minimum on its own,
- * and reaching for the words is what people do anyway.
- *
- * **One switch, or several checkboxes.** A lone binary setting is a switch. A
- * set you pick from is a list of checkboxes — fifteen switches in a column read
- * as fifteen unrelated settings rather than one choice with fifteen parts. See
- * `Checkbox`.
- */
 export default function Toggle({ label, hint, checked, onChange, disabled, said, labelHidden, size, className, }: {
     label: React.ReactNode;
     /** What it does, or what turning it off costs. Under the label, in the same

package/dist/components/Toggle.js

@@ -1,4 +1,11 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/* Client, because this module's own JSX attaches handlers or calls hooks. A
+   server component may still import it -- that is the point -- it simply
+   renders on the client. The ones without this line (Brand, Empty, Icon,
+   Illustration, Pill, Progress, Skeleton, Stat, Textarea, Table) render on
+   the server, which is why the directive is per component rather than one
+   line at the package's front door. */
 /**
  * A setting that takes effect as it moves.
  *

package/dist/components/Tooltip.js

@@ -1,4 +1,11 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/* Client, because this module's own JSX attaches handlers or calls hooks. A
+   server component may still import it -- that is the point -- it simply
+   renders on the client. The ones without this line (Brand, Empty, Icon,
+   Illustration, Pill, Progress, Skeleton, Stat, Textarea, Table) render on
+   the server, which is why the directive is per component rather than one
+   line at the package's front door. */
 /**
  * A tooltip. It was called `Explain`, which named the intention rather than the
  * thing -- so it sat in a catalogue beside Button and Callout as though it were

package/dist/components/Tour.d.ts

@@ -1,26 +1,3 @@
-/**
- * A short walk round the chrome, once, after onboarding.
- *
- * Onboarding answers "what does this need to run". It says nothing about the
- * four controls somebody is then left alone with: two floating buttons in one
- * corner, a cog in another, and a `+` beside the board name. Every one of them
- * is an icon with a `title`, which is a tooltip you have to already suspect is
- * there to go looking for.
- *
- * **It points at the real thing.** Each step finds its target by selector and
- * cuts a hole in the scrim over it, so the control being described is the
- * control you can see — not a screenshot of one, which goes stale the first
- * time the button moves.
- *
- * **A step whose target is missing is skipped, not shown empty.** The chat
- * launcher is not on the page while the dock is open, and the studio button
- * changes what it does when a session is minimised. A tour that insists on
- * pointing at something that is not there would be describing a different app.
- *
- * **Escape ends it and it never comes back on its own.** This is the least
- * important thing on the screen and it is in the way of everything else; the
- * one unforgivable version is the one you cannot get out of.
- */
 export interface TourStop {
     /** Where it points. Missing from the page means the stop is skipped. */
     target: string;

package/dist/components/Tour.js

@@ -1,4 +1,11 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/* Client, because this module's own JSX attaches handlers or calls hooks. A
+   server component may still import it -- that is the point -- it simply
+   renders on the client. The ones without this line (Brand, Empty, Icon,
+   Illustration, Pill, Progress, Skeleton, Stat, Textarea, Table) render on
+   the server, which is why the directive is per component rather than one
+   line at the package's front door. */
 /**
  * A short walk round the chrome, once, after onboarding.
  *

package/dist/components/fieldWiring.d.ts

@@ -0,0 +1,44 @@
+/**
+ * What a `Field` tells the control inside it.
+ *
+ * Its own module for the reason `iconNames.ts` and `tourMarker.ts` are:
+ * `fastRefresh.test.ts` holds every component module to exporting its
+ * component and nothing else, because a module exporting a value beside a
+ * component loses its Fast Refresh boundary and editing it re-runs every
+ * importer instead of swapping the component in place.
+ *
+ * The context exists so `Field`'s children can be elements rather than a
+ * function. A function cannot cross the server boundary, so the render prop
+ * made every page with a form a client component whether or not it needed to
+ * be -- which is the line all three consuming apps have in their
+ * `design.ts`.
+ */
+export interface FieldWiring {
+    id: string;
+    'aria-describedby': string | undefined;
+    'aria-invalid': boolean | undefined;
+    /** The label element's own id, for a control a `<label for>` cannot name.
+     *
+     *  `htmlFor` is enough for an `<input>`, which is what almost every caller
+     *  wraps. It is not enough for `Select`, or for anything else built on a
+     *  `<button>`: a button takes its accessible name from its *contents*, and
+     *  a `<label for>` pointing at one is ignored by the name computation. A
+     *  caller that put a `Select` in a `Field` got a label on screen and a
+     *  control announcing only its current value — and the workaround was an
+     *  `aria-label` repeating the label string, which is two literals and two
+     *  chances to drift apart. That drift is exactly the bug `Field` exists to
+     *  prevent, so: pass this as `aria-labelledby` and there is one string. */
+    labelId: string;
+}
+/** `null` outside a `Field`, so a control can tell "no field around me" from
+ *  "a field that wired me with nothing". */
+export declare const FieldWiringContext: import("react").Context<FieldWiring | null>;
+/**
+ * What the `Field` above this control wired, if there is one.
+ *
+ * For the package's own controls, which apply it when the caller has not
+ * named an `id` themselves. A consumer building its own control can use it
+ * for the same reason: it is how a control gets a label without the caller
+ * threading four attributes by hand.
+ */
+export declare function useFieldWiring(): FieldWiring | null;

package/dist/components/fieldWiring.js

@@ -0,0 +1,30 @@
+/**
+ * What a `Field` tells the control inside it.
+ *
+ * Its own module for the reason `iconNames.ts` and `tourMarker.ts` are:
+ * `fastRefresh.test.ts` holds every component module to exporting its
+ * component and nothing else, because a module exporting a value beside a
+ * component loses its Fast Refresh boundary and editing it re-runs every
+ * importer instead of swapping the component in place.
+ *
+ * The context exists so `Field`'s children can be elements rather than a
+ * function. A function cannot cross the server boundary, so the render prop
+ * made every page with a form a client component whether or not it needed to
+ * be -- which is the line all three consuming apps have in their
+ * `design.ts`.
+ */
+import { createContext, useContext } from 'react';
+/** `null` outside a `Field`, so a control can tell "no field around me" from
+ *  "a field that wired me with nothing". */
+export const FieldWiringContext = createContext(null);
+/**
+ * What the `Field` above this control wired, if there is one.
+ *
+ * For the package's own controls, which apply it when the caller has not
+ * named an `id` themselves. A consumer building its own control can use it
+ * for the same reason: it is how a control gets a label without the caller
+ * threading four attributes by hand.
+ */
+export function useFieldWiring() {
+    return useContext(FieldWiringContext);
+}

package/dist/index.d.ts

@@ -22,7 +22,10 @@ export { default as Brand } from './components/Brand.js';
 export { BRAND_MARKS, BRAND_NAMES } from './components/brandMarks.js';
 export type { BrandName, FillMark, Mark, StrokeMark } from './components/brandMarks.js';
 export { default as Button } from './components/Button.js';
-export type { Props as ButtonProps } from './components/Button.js';
+/** The union: the button's props, or the DOM's when `asChild` hands the
+ *  element to the caller. `ButtonOwnProps` is the button-only half, for a
+ *  wrapper that never slots. */
+export type { ButtonProps, Props as ButtonOwnProps } from './components/Button.js';
 export { default as Callout } from './components/Callout.js';
 export { default as Card } from './components/Card.js';
 export { default as Checkbox } from './components/Checkbox.js';
@@ -33,7 +36,10 @@ export { DangerAction, default as DangerZone } from './components/DangerZone.js'
 export { default as Dialog } from './components/Dialog.js';
 export { default as Empty } from './components/Empty.js';
 export { default as Field } from './components/Field.js';
-export type { FieldWiring } from './components/Field.js';
+/** The wiring a `Field` hands its control, and the hook that reads it —
+ *  its own module, so `Field.tsx` keeps its Fast Refresh boundary. */
+export { useFieldWiring } from './components/fieldWiring.js';
+export type { FieldWiring } from './components/fieldWiring.js';
 export { default as Icon } from './components/Icon.js';
 /** A person in one line -- initials, name, address -- and the two pure
  *  functions behind the disc, exported so a caller colouring something else
@@ -45,6 +51,9 @@ export type { IconName } from './components/iconNames.js';
 export { default as Illustration } from './components/Illustration.js';
 export { default as Input } from './components/Input.js';
 export type { Props as InputProps } from './components/Input.js';
+/** A key, or a chord. The rule `Menu` and `Command` each had a private copy
+ *  of, now one component a consumer can reach. */
+export { default as Kbd } from './components/Kbd.js';
 export { default as Markdown } from './components/Markdown.js';
 export { default as Menu } from './components/Menu.js';
 export type { Item as MenuItem, Section as MenuSection } from './components/Menu.js';
@@ -66,7 +75,12 @@ export { default as ScrollArea } from './components/ScrollArea.js';
 export type { Props as ScrollAreaProps } from './components/ScrollArea.js';
 export { default as Select } from './components/Select.js';
 export { default as SizeGrid } from './components/SizeGrid.js';
+/** The frame a signed-in surface stands in. Gates nothing, on purpose. */
+export { default as Shell } from './components/Shell.js';
 export { default as Skeleton } from './components/Skeleton.js';
+/** One figure, with what it counts over it. Three apps drew this before it
+ *  was here. */
+export { default as Stat } from './components/Stat.js';
 export { default as Slider } from './components/Slider.js';
 /** Two panes and a handle between them, the handle being a real `separator`
  *  widget rather than a div with a mousedown listener. */
@@ -77,8 +91,14 @@ export type { Column } from './components/Table.js';
 export { default as Tabs } from './components/Tabs.js';
 export type { Tab, TabGroup } from './components/Tabs.js';
 export { default as Textarea } from './components/Textarea.js';
+/** The theme control, and the blocking script that beats it to the paint. */
+export { default as ThemeSwitch } from './components/ThemeSwitch.js';
+export { THEME_STORAGE_KEY, themeChoiceScript, themeChoices, storedTheme } from './themes/choice.js';
+export type { ThemeChoice } from './themes/choice.js';
 export type { Props as TextareaProps } from './components/Textarea.js';
-export { Toast, ToastHost, useToast } from './components/Toast.js';
+/** `ToastHost` nests: one inside another renders through, so a package can
+ *  wrap itself and still leave an application with a single region. */
+export { Toast, ToastHost, useHasToastHost, useToast } from './components/Toast.js';
 export { default as Toggle } from './components/Toggle.js';
 export { default as Tooltip } from './components/Tooltip.js';
 export { default as Tour } from './components/Tour.js';

package/dist/index.js

@@ -33,6 +33,9 @@ export { DangerAction, default as DangerZone } from './components/DangerZone.js'
 export { default as Dialog } from './components/Dialog.js';
 export { default as Empty } from './components/Empty.js';
 export { default as Field } from './components/Field.js';
+/** The wiring a `Field` hands its control, and the hook that reads it —
+ *  its own module, so `Field.tsx` keeps its Fast Refresh boundary. */
+export { useFieldWiring } from './components/fieldWiring.js';
 export { default as Icon } from './components/Icon.js';
 /** A person in one line -- initials, name, address -- and the two pure
  *  functions behind the disc, exported so a caller colouring something else
@@ -42,6 +45,9 @@ export { hueOf, initialsOf } from './components/initials.js';
 export { ICON_NAMES } from './components/iconNames.js';
 export { default as Illustration } from './components/Illustration.js';
 export { default as Input } from './components/Input.js';
+/** A key, or a chord. The rule `Menu` and `Command` each had a private copy
+ *  of, now one component a consumer can reach. */
+export { default as Kbd } from './components/Kbd.js';
 export { default as Markdown } from './components/Markdown.js';
 export { default as Menu } from './components/Menu.js';
 export { default as Modal } from './components/Modal.js';
@@ -61,7 +67,12 @@ export { Row, Rows } from './components/Rows.js';
 export { default as ScrollArea } from './components/ScrollArea.js';
 export { default as Select } from './components/Select.js';
 export { default as SizeGrid } from './components/SizeGrid.js';
+/** The frame a signed-in surface stands in. Gates nothing, on purpose. */
+export { default as Shell } from './components/Shell.js';
 export { default as Skeleton } from './components/Skeleton.js';
+/** One figure, with what it counts over it. Three apps drew this before it
+ *  was here. */
+export { default as Stat } from './components/Stat.js';
 export { default as Slider } from './components/Slider.js';
 /** Two panes and a handle between them, the handle being a real `separator`
  *  widget rather than a div with a mousedown listener. */
@@ -69,7 +80,12 @@ export { default as SplitPane } from './components/SplitPane.js';
 export { default as Table } from './components/Table.js';
 export { default as Tabs } from './components/Tabs.js';
 export { default as Textarea } from './components/Textarea.js';
-export { ToastHost, useToast } from './components/Toast.js';
+/** The theme control, and the blocking script that beats it to the paint. */
+export { default as ThemeSwitch } from './components/ThemeSwitch.js';
+export { THEME_STORAGE_KEY, themeChoiceScript, themeChoices, storedTheme } from './themes/choice.js';
+/** `ToastHost` nests: one inside another renders through, so a package can
+ *  wrap itself and still leave an application with a single region. */
+export { ToastHost, useHasToastHost, useToast } from './components/Toast.js';
 export { default as Toggle } from './components/Toggle.js';
 export { default as Tooltip } from './components/Tooltip.js';
 export { default as Tour } from './components/Tour.js';