@openwarelabs/ui 0.3.0 → 0.4.0

package/dist/components/Form/Form.d.cts

@@ -0,0 +1,63 @@
+import { type FormEvent, type FormHTMLAttributes, type MutableRefObject, type ReactNode, type RefObject } from "react";
+/** What onSubmit and validate get: each name in the form with its value, or a string[] when the name appears more than once. */
+export type FormValues = Record<string, string | string[]>;
+/** Messages by field name. */
+export type FormErrors = Partial<Record<string, string>>;
+/** The browser's own checks, by their ValidityState names. */
+export type ValidityCheck = "valueMissing" | "typeMismatch" | "patternMismatch" | "tooShort" | "tooLong" | "rangeUnderflow" | "rangeOverflow" | "stepMismatch" | "badInput";
+/** What to say when a browser check fails: one message for any of them, or one per check. */
+export type ValidityMessages = string | Partial<Record<ValidityCheck, string>>;
+/** What a Form tells the components inside it, through the render function or useFormStatus(). */
+export interface FormStatus {
+    /** True while the promise onSubmit returned is pending. */
+    isSubmitting: boolean;
+    /** The errors showing now, by field name. */
+    errors: FormErrors;
+}
+export interface FormProps extends Omit<FormHTMLAttributes<HTMLFormElement>, "onSubmit" | "children"> {
+    /**
+     * Called with the values once every check passes. Return a promise to keep the form busy until it settles; if it
+     * rejects, the error's message shows in FormError ("That didn't work. Try again." when it has none). Without
+     * onSubmit, a valid form submits the usual way, to its `action`.
+     */
+    onSubmit?(values: FormValues, event: FormEvent<HTMLFormElement>): unknown;
+    /** Checks the values after the browser's own checks, for rules it can't express: return { [name]: message } for what's wrong. */
+    validate?(values: FormValues): FormErrors | void;
+    /** Errors from the server, by field name. Each shows under its field until the person changes that field. */
+    validationErrors?: FormErrors;
+    /** The fields and buttons, or a function of the form's status: ({ isSubmitting, errors }) => … */
+    children?: ReactNode | ((status: FormStatus) => ReactNode);
+}
+/** @internal What a Field tells its Form, so the Form can word its errors, focus it and tell which field lost focus. */
+export interface FormFieldEntry {
+    name: string | undefined;
+    root: RefObject<HTMLElement>;
+    controlId: string;
+    errorMessages: ValidityMessages | undefined;
+}
+interface FormContextValue {
+    status: FormStatus;
+    formError: string | undefined;
+    register(entry: MutableRefObject<FormFieldEntry>): () => void;
+    changed(name: string): void;
+    addErrorSlot(): () => void;
+}
+/** @internal */
+export declare const FormContext: import("react").Context<FormContextValue | null>;
+/**
+ * A form that checks its fields before it submits. On submit it runs the browser's checks (required, type, minLength,
+ * pattern, min, max…), then `validate`, then any `validationErrors`; each message shows under its Field and focus goes to
+ * the first wrong field. Only when everything passes does it call onSubmit with the values.
+ */
+export declare const Form: import("react").ForwardRefExoticComponent<FormProps & import("react").RefAttributes<HTMLFormElement>>;
+export interface FormErrorProps {
+    className?: string;
+}
+/**
+ * Where a Form says why a submission failed: the message from a rejected onSubmit, in a danger Alert (role="alert").
+ * Put it just above the buttons. Without one, the Form shows the message at its end.
+ */
+export declare function FormError({ className }: FormErrorProps): import("react").JSX.Element | null;
+/** The status of the Form around a component, for a submit button that shows `loading` while it submits. */
+export declare function useFormStatus(): FormStatus;
+export {};

package/dist/components/Form/Form.d.ts

@@ -0,0 +1,63 @@
+import { type FormEvent, type FormHTMLAttributes, type MutableRefObject, type ReactNode, type RefObject } from "react";
+/** What onSubmit and validate get: each name in the form with its value, or a string[] when the name appears more than once. */
+export type FormValues = Record<string, string | string[]>;
+/** Messages by field name. */
+export type FormErrors = Partial<Record<string, string>>;
+/** The browser's own checks, by their ValidityState names. */
+export type ValidityCheck = "valueMissing" | "typeMismatch" | "patternMismatch" | "tooShort" | "tooLong" | "rangeUnderflow" | "rangeOverflow" | "stepMismatch" | "badInput";
+/** What to say when a browser check fails: one message for any of them, or one per check. */
+export type ValidityMessages = string | Partial<Record<ValidityCheck, string>>;
+/** What a Form tells the components inside it, through the render function or useFormStatus(). */
+export interface FormStatus {
+    /** True while the promise onSubmit returned is pending. */
+    isSubmitting: boolean;
+    /** The errors showing now, by field name. */
+    errors: FormErrors;
+}
+export interface FormProps extends Omit<FormHTMLAttributes<HTMLFormElement>, "onSubmit" | "children"> {
+    /**
+     * Called with the values once every check passes. Return a promise to keep the form busy until it settles; if it
+     * rejects, the error's message shows in FormError ("That didn't work. Try again." when it has none). Without
+     * onSubmit, a valid form submits the usual way, to its `action`.
+     */
+    onSubmit?(values: FormValues, event: FormEvent<HTMLFormElement>): unknown;
+    /** Checks the values after the browser's own checks, for rules it can't express: return { [name]: message } for what's wrong. */
+    validate?(values: FormValues): FormErrors | void;
+    /** Errors from the server, by field name. Each shows under its field until the person changes that field. */
+    validationErrors?: FormErrors;
+    /** The fields and buttons, or a function of the form's status: ({ isSubmitting, errors }) => … */
+    children?: ReactNode | ((status: FormStatus) => ReactNode);
+}
+/** @internal What a Field tells its Form, so the Form can word its errors, focus it and tell which field lost focus. */
+export interface FormFieldEntry {
+    name: string | undefined;
+    root: RefObject<HTMLElement>;
+    controlId: string;
+    errorMessages: ValidityMessages | undefined;
+}
+interface FormContextValue {
+    status: FormStatus;
+    formError: string | undefined;
+    register(entry: MutableRefObject<FormFieldEntry>): () => void;
+    changed(name: string): void;
+    addErrorSlot(): () => void;
+}
+/** @internal */
+export declare const FormContext: import("react").Context<FormContextValue | null>;
+/**
+ * A form that checks its fields before it submits. On submit it runs the browser's checks (required, type, minLength,
+ * pattern, min, max…), then `validate`, then any `validationErrors`; each message shows under its Field and focus goes to
+ * the first wrong field. Only when everything passes does it call onSubmit with the values.
+ */
+export declare const Form: import("react").ForwardRefExoticComponent<FormProps & import("react").RefAttributes<HTMLFormElement>>;
+export interface FormErrorProps {
+    className?: string;
+}
+/**
+ * Where a Form says why a submission failed: the message from a rejected onSubmit, in a danger Alert (role="alert").
+ * Put it just above the buttons. Without one, the Form shows the message at its end.
+ */
+export declare function FormError({ className }: FormErrorProps): import("react").JSX.Element | null;
+/** The status of the Form around a component, for a submit button that shows `loading` while it submits. */
+export declare function useFormStatus(): FormStatus;
+export {};

package/dist/components/InputOTP/InputOTP.d.cts

@@ -22,10 +22,16 @@ export interface InputOTPProps {
     "aria-label"?: string;
     /** The form field name; a hidden input carries the whole code. */
     name?: string;
+    /** Names the code by another element's id, in place of aria-label. */
+    "aria-labelledby"?: string;
+    /** Ids of the hint or error that describe it, read from every box; Field sets this. */
+    "aria-describedby"?: string;
+    /** The id of the first box, so a Field's label points at it and clicking the label starts there; Field sets this. */
+    id?: string;
     className?: string;
 }
 /**
  * A one-time code in separate boxes. Typing moves forward, Backspace moves back,
  * and pasting a code fills every box. The browser can fill it from a text message.
  */
-export declare function InputOTP({ length, value, defaultValue, onChange, onComplete, type, groupSize, isInvalid, disabled, autoFocus, "aria-label": ariaLabel, name, className, }: InputOTPProps): import("react").JSX.Element;
+export declare function InputOTP({ length, value, defaultValue, onChange, onComplete, type, groupSize, isInvalid, disabled, autoFocus, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, id, name, className, }: InputOTPProps): import("react").JSX.Element;

package/dist/components/InputOTP/InputOTP.d.ts

@@ -22,10 +22,16 @@ export interface InputOTPProps {
     "aria-label"?: string;
     /** The form field name; a hidden input carries the whole code. */
     name?: string;
+    /** Names the code by another element's id, in place of aria-label. */
+    "aria-labelledby"?: string;
+    /** Ids of the hint or error that describe it, read from every box; Field sets this. */
+    "aria-describedby"?: string;
+    /** The id of the first box, so a Field's label points at it and clicking the label starts there; Field sets this. */
+    id?: string;
     className?: string;
 }
 /**
  * A one-time code in separate boxes. Typing moves forward, Backspace moves back,
  * and pasting a code fills every box. The browser can fill it from a text message.
  */
-export declare function InputOTP({ length, value, defaultValue, onChange, onComplete, type, groupSize, isInvalid, disabled, autoFocus, "aria-label": ariaLabel, name, className, }: InputOTPProps): import("react").JSX.Element;
+export declare function InputOTP({ length, value, defaultValue, onChange, onComplete, type, groupSize, isInvalid, disabled, autoFocus, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, id, name, className, }: InputOTPProps): import("react").JSX.Element;

package/dist/components/ListBox/ListBox.d.cts

@@ -0,0 +1,65 @@
+import { type ReactElement, type ReactNode, type RefAttributes } from "react";
+import type { SelectOption } from "../Select/Select.cjs";
+/** An option, shaped like Select's, with an optional icon. */
+export interface ListBoxOption extends SelectOption {
+    /** A 16px icon between the checkmark and the label. */
+    icon?: ReactNode;
+    /** Plain text for type-to-find, when `label` isn't a string. */
+    textValue?: string;
+}
+/** Options under a heading, like a Select's groups. */
+export interface ListBoxGroup {
+    /** The heading, shown in uppercase above the options and read out as the group's name. */
+    label: string;
+    options: ListBoxOption[];
+}
+export type ListBoxItem = ListBoxOption | ListBoxGroup;
+export type ListBoxSelectionMode = "single" | "multiple";
+/** ListBox's props for one selection mode: `value` is a string in single mode and an array in multiple mode. */
+export interface ListBoxModeProps<Mode extends ListBoxSelectionMode> {
+    /** The options, and groups of options under a heading. */
+    options: ListBoxItem[];
+    /** `single` chooses one option; `multiple` any number.
+     * @default "single" */
+    selectionMode?: Mode;
+    /** The selected option's value in single mode ("" for none), or the selected values in multiple mode. */
+    value?: Mode extends "multiple" ? string[] : string;
+    /** The starting value when uncontrolled.
+     * @default "" or [] */
+    defaultValue?: Mode extends "multiple" ? string[] : string;
+    /** Called with the new value: a string in single mode, the selected values in the options' order in multiple mode. */
+    onChange?(value: Mode extends "multiple" ? string[] : string): void;
+    /** Keeps at least one option selected: choosing the selected option again doesn't clear it.
+     * @default false */
+    disallowEmptySelection?: boolean;
+    /** Shown in the list when there are no options.
+     * @default "No options" */
+    emptyMessage?: ReactNode;
+    /** Scrolls the options past this height, e.g. 240 or "40vh". */
+    maxHeight?: number | string;
+    /** md rows are 36px; sm rows are 32px with 12px text, like a small Select's list.
+     * @default "md" */
+    size?: "sm" | "md";
+    /** Shows the list as wrong: a red border, and a red halo when focused. Also sets aria-invalid. Field passes it.
+     * @default false */
+    isInvalid?: boolean;
+    /** The options can be moved through and read, but the selection can't change.
+     * @default false */
+    isReadOnly?: boolean;
+    /** Fades the list and takes it out of the tab order.
+     * @default false */
+    disabled?: boolean;
+    id?: string;
+    /** Names the list for screen readers when it isn't in a Field. */
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    "aria-describedby"?: string;
+    className?: string;
+}
+/** ListBox's props. `value`, `defaultValue` and `onChange` take a string in single mode and an array in multiple mode. */
+export interface ListBoxProps extends ListBoxModeProps<ListBoxSelectionMode> {
+}
+/**
+ * Select's list of options on its own: a choice that stays on the page. `selectionMode="multiple"` makes `value` an array.
+ */
+export declare const ListBox: <Mode extends ListBoxSelectionMode = "single">(props: ListBoxModeProps<Mode> & RefAttributes<HTMLDivElement>) => ReactElement | null;

package/dist/components/ListBox/ListBox.d.ts

@@ -0,0 +1,65 @@
+import { type ReactElement, type ReactNode, type RefAttributes } from "react";
+import type { SelectOption } from "../Select/Select.js";
+/** An option, shaped like Select's, with an optional icon. */
+export interface ListBoxOption extends SelectOption {
+    /** A 16px icon between the checkmark and the label. */
+    icon?: ReactNode;
+    /** Plain text for type-to-find, when `label` isn't a string. */
+    textValue?: string;
+}
+/** Options under a heading, like a Select's groups. */
+export interface ListBoxGroup {
+    /** The heading, shown in uppercase above the options and read out as the group's name. */
+    label: string;
+    options: ListBoxOption[];
+}
+export type ListBoxItem = ListBoxOption | ListBoxGroup;
+export type ListBoxSelectionMode = "single" | "multiple";
+/** ListBox's props for one selection mode: `value` is a string in single mode and an array in multiple mode. */
+export interface ListBoxModeProps<Mode extends ListBoxSelectionMode> {
+    /** The options, and groups of options under a heading. */
+    options: ListBoxItem[];
+    /** `single` chooses one option; `multiple` any number.
+     * @default "single" */
+    selectionMode?: Mode;
+    /** The selected option's value in single mode ("" for none), or the selected values in multiple mode. */
+    value?: Mode extends "multiple" ? string[] : string;
+    /** The starting value when uncontrolled.
+     * @default "" or [] */
+    defaultValue?: Mode extends "multiple" ? string[] : string;
+    /** Called with the new value: a string in single mode, the selected values in the options' order in multiple mode. */
+    onChange?(value: Mode extends "multiple" ? string[] : string): void;
+    /** Keeps at least one option selected: choosing the selected option again doesn't clear it.
+     * @default false */
+    disallowEmptySelection?: boolean;
+    /** Shown in the list when there are no options.
+     * @default "No options" */
+    emptyMessage?: ReactNode;
+    /** Scrolls the options past this height, e.g. 240 or "40vh". */
+    maxHeight?: number | string;
+    /** md rows are 36px; sm rows are 32px with 12px text, like a small Select's list.
+     * @default "md" */
+    size?: "sm" | "md";
+    /** Shows the list as wrong: a red border, and a red halo when focused. Also sets aria-invalid. Field passes it.
+     * @default false */
+    isInvalid?: boolean;
+    /** The options can be moved through and read, but the selection can't change.
+     * @default false */
+    isReadOnly?: boolean;
+    /** Fades the list and takes it out of the tab order.
+     * @default false */
+    disabled?: boolean;
+    id?: string;
+    /** Names the list for screen readers when it isn't in a Field. */
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    "aria-describedby"?: string;
+    className?: string;
+}
+/** ListBox's props. `value`, `defaultValue` and `onChange` take a string in single mode and an array in multiple mode. */
+export interface ListBoxProps extends ListBoxModeProps<ListBoxSelectionMode> {
+}
+/**
+ * Select's list of options on its own: a choice that stays on the page. `selectionMode="multiple"` makes `value` an array.
+ */
+export declare const ListBox: <Mode extends ListBoxSelectionMode = "single">(props: ListBoxModeProps<Mode> & RefAttributes<HTMLDivElement>) => ReactElement | null;

package/dist/components/Meter/Meter.d.cts

@@ -0,0 +1,62 @@
+import { type ReactNode } from "react";
+import type { ProgressTone } from "../Progress/Progress.cjs";
+export interface MeterProps {
+    /** The amount measured, from min to max. */
+    value: number;
+    /** @default 0 */
+    min?: number;
+    /** @default 100 */
+    max?: number;
+    /** Shown above the bar, and names it for screen readers. */
+    label?: ReactNode;
+    /** Shows the value label at the right of the label.
+     * @default true */
+    showValue?: boolean;
+    /**
+     * The text shown and read out for the value: a string ("Strong"), or a function given the value, min and max
+     * formatted with `formatOptions`, such as `({ value, max }) => \`${value} of ${max}\``. Defaults to the formatted value.
+     */
+    valueLabel?: string | ((formatted: {
+        value: string;
+        min: string;
+        max: string;
+    }) => string);
+    /**
+     * How the value is written, as Intl.NumberFormat options. The percent style shows where the value sits in the range;
+     * any other formats the value itself, such as `{ style: "unit", unit: "gigabyte" }`.
+     * @default { style: "percent" }
+     */
+    formatOptions?: Intl.NumberFormatOptions;
+    /** The locale numbers are written in, such as "de-CH". Defaults to the browser's. */
+    locale?: string;
+    /** The fill's colour. Leave it out to work it out from `low`, `high` and `optimum`; with none of those, it's primary. */
+    tone?: ProgressTone;
+    /** Values below this are in the low range, as on the meter element.
+     * @default min */
+    low?: number;
+    /** Values above this are in the high range.
+     * @default max */
+    high?: number;
+    /**
+     * The best value. The range it's in is good (success), the middle range otherwise middling (warning), and the range
+     * at the far end bad (danger). With optimum between low and high, both outer ranges are middling.
+     * @default halfway between min and max
+     */
+    optimum?: number;
+    /** sm is 4px; md is 8px.
+     * @default "sm" */
+    size?: "sm" | "md";
+    /** Draws the bar as this many separate blocks, such as 4 for a password's strength. */
+    segments?: number;
+    id?: string;
+    /** Names the meter for screen readers when there's no `label`. */
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    "aria-describedby"?: string;
+    className?: string;
+}
+/**
+ * An amount within a known range: storage used, runs against a plan's limit, a password's strength. Unlike ProgressBar,
+ * it doesn't mean something will finish.
+ */
+export declare function Meter({ value, min, max, label, showValue, valueLabel, formatOptions, locale, tone, low, high, optimum, size, segments, id, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, className, }: MeterProps): import("react").JSX.Element;

package/dist/components/Meter/Meter.d.ts

@@ -0,0 +1,62 @@
+import { type ReactNode } from "react";
+import type { ProgressTone } from "../Progress/Progress.js";
+export interface MeterProps {
+    /** The amount measured, from min to max. */
+    value: number;
+    /** @default 0 */
+    min?: number;
+    /** @default 100 */
+    max?: number;
+    /** Shown above the bar, and names it for screen readers. */
+    label?: ReactNode;
+    /** Shows the value label at the right of the label.
+     * @default true */
+    showValue?: boolean;
+    /**
+     * The text shown and read out for the value: a string ("Strong"), or a function given the value, min and max
+     * formatted with `formatOptions`, such as `({ value, max }) => \`${value} of ${max}\``. Defaults to the formatted value.
+     */
+    valueLabel?: string | ((formatted: {
+        value: string;
+        min: string;
+        max: string;
+    }) => string);
+    /**
+     * How the value is written, as Intl.NumberFormat options. The percent style shows where the value sits in the range;
+     * any other formats the value itself, such as `{ style: "unit", unit: "gigabyte" }`.
+     * @default { style: "percent" }
+     */
+    formatOptions?: Intl.NumberFormatOptions;
+    /** The locale numbers are written in, such as "de-CH". Defaults to the browser's. */
+    locale?: string;
+    /** The fill's colour. Leave it out to work it out from `low`, `high` and `optimum`; with none of those, it's primary. */
+    tone?: ProgressTone;
+    /** Values below this are in the low range, as on the meter element.
+     * @default min */
+    low?: number;
+    /** Values above this are in the high range.
+     * @default max */
+    high?: number;
+    /**
+     * The best value. The range it's in is good (success), the middle range otherwise middling (warning), and the range
+     * at the far end bad (danger). With optimum between low and high, both outer ranges are middling.
+     * @default halfway between min and max
+     */
+    optimum?: number;
+    /** sm is 4px; md is 8px.
+     * @default "sm" */
+    size?: "sm" | "md";
+    /** Draws the bar as this many separate blocks, such as 4 for a password's strength. */
+    segments?: number;
+    id?: string;
+    /** Names the meter for screen readers when there's no `label`. */
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    "aria-describedby"?: string;
+    className?: string;
+}
+/**
+ * An amount within a known range: storage used, runs against a plan's limit, a password's strength. Unlike ProgressBar,
+ * it doesn't mean something will finish.
+ */
+export declare function Meter({ value, min, max, label, showValue, valueLabel, formatOptions, locale, tone, low, high, optimum, size, segments, id, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, className, }: MeterProps): import("react").JSX.Element;

package/dist/components/Slider/Slider.d.cts

@@ -22,6 +22,12 @@ export interface SliderProps<V extends SliderValue = number> {
     formatValue?(value: number): string;
     /** Names the slider when there's no visible label. */
     "aria-label"?: string;
+    /** Names the slider by another element's id, such as a Field's label. */
+    "aria-labelledby"?: string;
+    /** Ids of the hint or error that describe it; Field sets this. */
+    "aria-describedby"?: string;
+    /** The id of the (first) handle's input, so a Field's label points at it; Field sets this. */
+    id?: string;
     disabled?: boolean;
     className?: string;
 }
@@ -29,5 +35,5 @@ export interface SliderProps<V extends SliderValue = number> {
  * Picks a number, or a range, by dragging. It's built on native range inputs, so the arrow keys,
  * PageUp, PageDown, Home and End work as people expect.
  */
-export declare function Slider<V extends SliderValue = number>({ value, defaultValue, onChange, onChangeEnd, min, max, step, label, showValue, formatValue, "aria-label": ariaLabel, disabled, className, }: SliderProps<V>): import("react").JSX.Element;
+export declare function Slider<V extends SliderValue = number>({ value, defaultValue, onChange, onChangeEnd, min, max, step, label, showValue, formatValue, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, id, disabled, className, }: SliderProps<V>): import("react").JSX.Element;
 export {};

package/dist/components/Slider/Slider.d.ts

@@ -22,6 +22,12 @@ export interface SliderProps<V extends SliderValue = number> {
     formatValue?(value: number): string;
     /** Names the slider when there's no visible label. */
     "aria-label"?: string;
+    /** Names the slider by another element's id, such as a Field's label. */
+    "aria-labelledby"?: string;
+    /** Ids of the hint or error that describe it; Field sets this. */
+    "aria-describedby"?: string;
+    /** The id of the (first) handle's input, so a Field's label points at it; Field sets this. */
+    id?: string;
     disabled?: boolean;
     className?: string;
 }
@@ -29,5 +35,5 @@ export interface SliderProps<V extends SliderValue = number> {
  * Picks a number, or a range, by dragging. It's built on native range inputs, so the arrow keys,
  * PageUp, PageDown, Home and End work as people expect.
  */
-export declare function Slider<V extends SliderValue = number>({ value, defaultValue, onChange, onChangeEnd, min, max, step, label, showValue, formatValue, "aria-label": ariaLabel, disabled, className, }: SliderProps<V>): import("react").JSX.Element;
+export declare function Slider<V extends SliderValue = number>({ value, defaultValue, onChange, onChangeEnd, min, max, step, label, showValue, formatValue, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, id, disabled, className, }: SliderProps<V>): import("react").JSX.Element;
 export {};

package/dist/components/ToggleButtonGroup/ToggleButtonGroup.d.cts

@@ -0,0 +1,74 @@
+import { type ReactNode } from "react";
+export interface ToggleButtonGroupOption {
+    /** Identifies the option in `value`. */
+    value: string;
+    /** The visible text. Leave it out for an icon-only option, and give that an aria-label. */
+    label?: ReactNode;
+    /** A 16px icon before the label, or on its own. */
+    icon?: ReactNode;
+    /** Names an icon-only option for screen readers; a tooltip shows the same words. */
+    "aria-label"?: string;
+    /** Greys the option out; the arrow keys skip it.
+     * @default false */
+    disabled?: boolean;
+}
+export interface ToggleButtonGroupProps {
+    /** The toggles, in order. */
+    options: ToggleButtonGroupOption[];
+    /** `multiple` lets any number be on, like bold and italic; `single` allows at most one, like an alignment.
+     * Either way all can be off, unless `disallowEmptySelection`.
+     * @default "single" */
+    selectionMode?: "single" | "multiple";
+    /** What's on: in single mode a value, or "" for none; in multiple mode an array of values. Leave it out to let the
+     * group keep its own state. */
+    value?: string | string[];
+    /** The starting value when uncontrolled.
+     * @default "" or [] */
+    defaultValue?: string | string[];
+    /** Called with the new value: a string ("" for none) in single mode, an array in the options' order in multiple mode. */
+    onChange?(value: string | string[]): void;
+    /** Keeps one option on: pressing the only one that's on leaves it on.
+     * @default false */
+    disallowEmptySelection?: boolean;
+    /** sm 32px, md 40px tall, like Button. Inside a Toolbar it takes the toolbar's size.
+     * @default "md" */
+    size?: "sm" | "md";
+    /** Inside a Toolbar it takes the toolbar's orientation.
+     * @default "horizontal" */
+    orientation?: "horizontal" | "vertical";
+    /** Disables every option, keeping what's on visible.
+     * @default false */
+    disabled?: boolean;
+    /** Names the group for screen readers, e.g. "Text style". */
+    "aria-label"?: string;
+    /** The id of a visible label for the group, in place of aria-label. */
+    "aria-labelledby"?: string;
+    /** The id of a hint or description for the group. */
+    "aria-describedby"?: string;
+    /** An id for the group's element. */
+    id?: string;
+    /** Extra classes for the group. */
+    className?: string;
+}
+type SharedProps = Omit<ToggleButtonGroupProps, "selectionMode" | "value" | "defaultValue" | "onChange">;
+/** The props in single mode: `value` is one option's value, or "" when none is on. */
+export type ToggleButtonGroupSingleProps = SharedProps & {
+    selectionMode?: "single";
+    value?: string;
+    defaultValue?: string;
+    onChange?(value: string): void;
+};
+/** The props in multiple mode: `value` is the values of the options that are on. */
+export type ToggleButtonGroupMultipleProps = SharedProps & {
+    selectionMode: "multiple";
+    value?: string[];
+    defaultValue?: string[];
+    onChange?(value: string[]): void;
+};
+/**
+ * Toggle buttons joined into one control: several can be on (bold, italic, underline) or at most one (an alignment),
+ * and, unlike a SegmentedControl, all can be off. On its own it's one tab stop with the arrow keys moving between its
+ * buttons; inside a Toolbar it leaves the arrow keys to the toolbar.
+ */
+export declare function ToggleButtonGroup(props: ToggleButtonGroupSingleProps | ToggleButtonGroupMultipleProps): import("react").JSX.Element;
+export {};

package/dist/components/ToggleButtonGroup/ToggleButtonGroup.d.ts

@@ -0,0 +1,74 @@
+import { type ReactNode } from "react";
+export interface ToggleButtonGroupOption {
+    /** Identifies the option in `value`. */
+    value: string;
+    /** The visible text. Leave it out for an icon-only option, and give that an aria-label. */
+    label?: ReactNode;
+    /** A 16px icon before the label, or on its own. */
+    icon?: ReactNode;
+    /** Names an icon-only option for screen readers; a tooltip shows the same words. */
+    "aria-label"?: string;
+    /** Greys the option out; the arrow keys skip it.
+     * @default false */
+    disabled?: boolean;
+}
+export interface ToggleButtonGroupProps {
+    /** The toggles, in order. */
+    options: ToggleButtonGroupOption[];
+    /** `multiple` lets any number be on, like bold and italic; `single` allows at most one, like an alignment.
+     * Either way all can be off, unless `disallowEmptySelection`.
+     * @default "single" */
+    selectionMode?: "single" | "multiple";
+    /** What's on: in single mode a value, or "" for none; in multiple mode an array of values. Leave it out to let the
+     * group keep its own state. */
+    value?: string | string[];
+    /** The starting value when uncontrolled.
+     * @default "" or [] */
+    defaultValue?: string | string[];
+    /** Called with the new value: a string ("" for none) in single mode, an array in the options' order in multiple mode. */
+    onChange?(value: string | string[]): void;
+    /** Keeps one option on: pressing the only one that's on leaves it on.
+     * @default false */
+    disallowEmptySelection?: boolean;
+    /** sm 32px, md 40px tall, like Button. Inside a Toolbar it takes the toolbar's size.
+     * @default "md" */
+    size?: "sm" | "md";
+    /** Inside a Toolbar it takes the toolbar's orientation.
+     * @default "horizontal" */
+    orientation?: "horizontal" | "vertical";
+    /** Disables every option, keeping what's on visible.
+     * @default false */
+    disabled?: boolean;
+    /** Names the group for screen readers, e.g. "Text style". */
+    "aria-label"?: string;
+    /** The id of a visible label for the group, in place of aria-label. */
+    "aria-labelledby"?: string;
+    /** The id of a hint or description for the group. */
+    "aria-describedby"?: string;
+    /** An id for the group's element. */
+    id?: string;
+    /** Extra classes for the group. */
+    className?: string;
+}
+type SharedProps = Omit<ToggleButtonGroupProps, "selectionMode" | "value" | "defaultValue" | "onChange">;
+/** The props in single mode: `value` is one option's value, or "" when none is on. */
+export type ToggleButtonGroupSingleProps = SharedProps & {
+    selectionMode?: "single";
+    value?: string;
+    defaultValue?: string;
+    onChange?(value: string): void;
+};
+/** The props in multiple mode: `value` is the values of the options that are on. */
+export type ToggleButtonGroupMultipleProps = SharedProps & {
+    selectionMode: "multiple";
+    value?: string[];
+    defaultValue?: string[];
+    onChange?(value: string[]): void;
+};
+/**
+ * Toggle buttons joined into one control: several can be on (bold, italic, underline) or at most one (an alignment),
+ * and, unlike a SegmentedControl, all can be off. On its own it's one tab stop with the arrow keys moving between its
+ * buttons; inside a Toolbar it leaves the arrow keys to the toolbar.
+ */
+export declare function ToggleButtonGroup(props: ToggleButtonGroupSingleProps | ToggleButtonGroupMultipleProps): import("react").JSX.Element;
+export {};

package/dist/components/Toolbar/Toolbar.d.cts

@@ -0,0 +1,36 @@
+import { type HTMLAttributes } from "react";
+export interface ToolbarProps extends HTMLAttributes<HTMLDivElement> {
+    /** Names the toolbar for screen readers, e.g. "Formatting". Every toolbar needs a name, from this or aria-labelledby. */
+    "aria-label"?: string;
+    /** The id of a visible heading that names the toolbar, in place of aria-label. */
+    "aria-labelledby"?: string;
+    /** Which way it runs. The arrow keys follow it: Left and Right across a horizontal toolbar, Up and Down a vertical one.
+     * @default "horizontal" */
+    orientation?: "horizontal" | "vertical";
+    /** `raised` is a bar of its own: a surface with a hairline border and a soft shadow. `plain` has no ground, for a
+     * toolbar in a card or panel header.
+     * @default "raised" */
+    variant?: "raised" | "plain";
+    /** The bar's padding and gaps, and the size its ToggleButtonGroups and separators take. Give its Buttons the same size.
+     * @default "md" */
+    size?: "sm" | "md";
+}
+export interface ToolbarSeparatorProps {
+    /** Extra classes for the line. */
+    className?: string;
+}
+interface ToolbarContextValue {
+    orientation: "horizontal" | "vertical";
+    size: "sm" | "md";
+}
+/** Lets what's inside a Toolbar follow its orientation and size, and leave the arrow keys to it. */
+export declare const ToolbarContext: import("react").Context<ToolbarContextValue | null>;
+/**
+ * A row of controls for one context: an editor's formatting bar, a table's actions. It's a single tab stop: the
+ * arrow keys move between every control inside it, ToggleButtonGroups' buttons included, and Tab leaves it, coming
+ * back to the control that was focused last.
+ */
+export declare const Toolbar: import("react").ForwardRefExoticComponent<ToolbarProps & import("react").RefAttributes<HTMLDivElement>>;
+/** A line between groups of controls in a Toolbar, across the toolbar's direction. */
+export declare function ToolbarSeparator({ className }: ToolbarSeparatorProps): import("react").JSX.Element;
+export {};