@minimalstuff/ui 5.0.1 → 5.2.0

package/README.md

@@ -42,10 +42,31 @@ export function Root() {
 }
 ```
 
+For French, pass the bundled preset: `<UIProvider labels={FRENCH_UI_LABELS}>` (import `FRENCH_UI_LABELS` from `@minimalstuff/ui`).
+
 ### Dark mode
 
 Dark styles apply when `<html>` has the `dark` class. `useThemeStore` (and the `ThemeToggle` built on it) sets that class from the `light`, `dark` or `system` preference and keeps it in `localStorage`.
 
+To avoid a light flash before your bundle runs, inline `THEME_INIT_SCRIPT` in `<head>`, before the stylesheet. It reads the same `localStorage` key as the store and sets the `dark` class the same way.
+
+```tsx
+import { THEME_INIT_SCRIPT } from '@minimalstuff/ui';
+
+<head>
+	<script dangerouslySetInnerHTML={{ __html: THEME_INIT_SCRIPT }} />
+	<link rel="stylesheet" href="/style.css" />
+</head>;
+```
+
+With a strict Content-Security-Policy, either add the script's SHA-256 hash to `script-src` (`'sha256-<hash>'`), or write `THEME_INIT_SCRIPT` to a file at build time and load it with `<script src>`. Compute the hash with:
+
+```bash
+node --input-type=module -e "import { THEME_INIT_SCRIPT } from '@minimalstuff/ui'; import { createHash } from 'node:crypto'; console.log(createHash('sha256').update(THEME_INIT_SCRIPT).digest('base64'))"
+```
+
+The hash changes if a release changes the script: recompute it when you upgrade.
+
 ### Modals and drawers lock page scroll
 
 While a `Modal` or `Drawer` is open, page scroll is locked on `<html>`. The scrollbar width this frees is compensated with right padding on `<html>`, so the page does not shift. That padding does not move `position: fixed` elements: anchor right-aligned ones with `right: var(--scrollbar-compensation, 0px)`. Paint the page background on `<html>` or `<body>` rather than only on a wrapper element, or the padding shows the root's background as a strip on the right.

package/dist/index.d.ts

@@ -13,6 +13,27 @@ import { RefObject } from 'react';
 import { StoreApi } from 'zustand';
 import { UseBoundStore } from 'zustand';
 
+/**
+ * A thin application bar with a `start` slot on the left, a centered `title`
+ * and an `end` slot on the right. It is a plain `<header>` (the `banner`
+ * landmark when it is not nested in another sectioning element), not a
+ * WAI-ARIA toolbar: put your own links and buttons in the slots, or use
+ * `Toolbar` for a group of controls with arrow-key navigation. Its minimum
+ * height grows with enlarged text and its horizontal padding honours the
+ * device safe area.
+ */
+export declare function AppBar(appBarProps: Readonly<AppBarProps>): JSX.Element;
+
+export declare type AppBarProps = Omit<ComponentPropsWithRef<'header'>, 'title'> & {
+    start?: ReactNode;
+    title?: ReactNode;
+    end?: ReactNode;
+    startClassName?: string;
+    titleClassName?: string;
+    endClassName?: string;
+    unstyled?: boolean;
+};
+
 /**
  * The picture of a person, or the initial of `name` when there is none.
  * Labelled with the full `name` so screen readers announce the person rather
@@ -64,6 +85,31 @@ export declare const BASE_INPUT_STYLES = "w-full border border-gray-300 dark:bor
 
 export declare function Button(buttonProps: Readonly<ButtonProps>): JSX.Element;
 
+/**
+ * The exact class string `Button` renders, for styling another element as a
+ * button, typically a router `<Link>` or an `<a>`. Keyboard focus ring included.
+ * For a selected link, add `pressed` and `aria-current`, not `aria-pressed`.
+ */
+export declare function buttonClassName(options?: Readonly<ButtonClassNameOptions>): string;
+
+export declare type ButtonClassNameOptions = {
+    variant?: ButtonVariant;
+    color?: ButtonColor;
+    size?: ControlSize;
+    radius?: Radius;
+    fullWidth?: boolean;
+    /**
+     * Applies the pressed look, for a real `<button>` toggle paired with
+     * `aria-pressed`. Never put `aria-pressed` on a link (not allowed on role
+     * link): on an `<a>`, pair the selected look with `aria-current`, for
+     * example `aria-current="page"`.
+     */
+    pressed?: boolean;
+    /** Keeps only the layout classes, like `Button`'s `unstyled` prop. */
+    unstyled?: boolean;
+    className?: string;
+};
+
 declare type ButtonColor =
 	| 'primary'
 	| 'neutral'
@@ -85,6 +131,11 @@ export declare type ButtonProps = Omit<ComponentPropsWithRef<'button'>, 'childre
      * the tab order, exposed as `aria-disabled`.
      */
     loading?: boolean;
+    /**
+     * Turns the button into a toggle: sets `aria-pressed` and a pressed look (dark fill and inset ring).
+     * Leave it `undefined` for a regular button (no attribute).
+     */
+    pressed?: boolean;
     startIcon?: string;
     endIcon?: string;
 } & ButtonStyle;
@@ -153,7 +204,7 @@ export declare type CheckboxOption = ChoiceOption;
 export declare function CheckboxOptions({ options, orientation, values, defaultValues, onChange, name: nameProp, label, error, required, requiredLabel, disabled, radius, unstyled, className, wrapperClassName, id, 'aria-describedby': callerDescribedBy, ...props }: Readonly<CheckboxOptionsProps>): JSX.Element;
 
 export declare interface CheckboxOptionsProps extends Omit<ComponentPropsWithRef<'fieldset'>, 'onChange'> {
-    options: string[] | CheckboxOption[];
+    options: readonly string[] | readonly CheckboxOption[];
     orientation?: 'vertical' | 'horizontal';
     values?: readonly string[];
     defaultValues?: readonly string[];
@@ -193,13 +244,13 @@ export declare interface ChoiceOption {
     	disabled?: boolean;
 }
 
-export declare function ClientOnly({ children, fallback }: Readonly<ClientOnlyProps>): string | number | bigint | boolean | JSX.Element | Iterable< ReactNode> | Promise<string | number | bigint | boolean | ReactPortal | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable< ReactNode> | null | undefined> | null;
+export declare function ClientOnly({ children, fallback }: Readonly<ClientOnlyProps>): string | number | bigint | boolean | Iterable< ReactNode> | Promise<string | number | bigint | boolean | ReactPortal | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable< ReactNode> | null | undefined> | JSX.Element | null;
 
 export declare interface ClientOnlyProps extends React.PropsWithChildren {
     fallback?: React.ReactNode;
 }
 
-export declare function Combobox({ options, label, description, 'aria-label': ariaLabel, error, placeholder, noResultsText, clearLabel, radius, unstyled, disabled, required, className, wrapperClassName, value, defaultValue, onChange, id, }: Readonly<ComboboxProps>): JSX.Element;
+export declare function Combobox({ options, filterOption, label, description, 'aria-label': ariaLabel, error, placeholder, noResultsText, clearLabel, radius, unstyled, disabled, required, className, wrapperClassName, value, defaultValue, onChange, id, }: Readonly<ComboboxProps>): JSX.Element;
 
 export declare interface ComboboxOption {
     value: string;
@@ -207,7 +258,13 @@ export declare interface ComboboxOption {
 }
 
 export declare interface ComboboxProps {
-    options: ComboboxOption[];
+    options: readonly ComboboxOption[];
+    /**
+     * Decides whether an option matches the text typed in the field. Replaces
+     * the default case-insensitive "label contains the query" match, for
+     * example to ignore accents.
+     */
+    filterOption?: (option: ComboboxOption, query: string) => boolean;
     label?: string | ReactNode;
     description?: string | ReactNode;
     'aria-label'?: string;
@@ -289,14 +346,20 @@ export declare interface ContextMenuProps {
 /** The size scale every inline control shares (Button, IconButton, Badge, Kbd). */
 declare type ControlSize = 'xs' | 'sm' | 'md' | 'lg';
 
-export declare function CopyButton({ value, children, onError, }: Readonly<CopyButtonProps>): JSX.Element;
+export declare function CopyButton({ value, children, label, onError, }: Readonly<CopyButtonProps>): JSX.Element;
 
 export declare interface CopyButtonProps {
     value: string;
-    children: (props: {
+    /**
+     * Render prop for a custom control. Omit it to get the default icon button,
+     * which swaps its copy icon for a check while `copied`.
+     */
+    children?: (props: {
         copied: boolean;
         copy: () => void | Promise<void>;
     }) => ReactNode;
+    /** Accessible name of the default icon button. Defaults to `labels.copy`. */
+    label?: string;
     onError?: (error: unknown) => void;
 }
 
@@ -307,8 +370,24 @@ export declare interface CopyButtonProps {
  */
 export declare type DismissGuard = () => boolean | Promise<boolean>;
 
+/**
+ * Asks the topmost open dialog (`Modal`, `ConfirmModal`, `Drawer`) to close,
+ * exactly as an Escape press would: dismiss guards are honoured, and a
+ * dialog with `dismissible={false}` stays open. Only the topmost dialog is
+ * affected, and a dialog already closing does not count.
+ *
+ * Call it first from a hardware back button handler (for example Capacitor's
+ * `backButton` listener on Android) and navigate back only when it returns
+ * `false`.
+ *
+ * @returns `true` when a dialog was open and the press was consumed (even if
+ * it stayed open because it is not dismissible or a guard refused), `false`
+ * when no dialog is open.
+ */
+export declare function dismissTopmostModal(): boolean;
+
 /** A modal side panel with the same focus handling, stacking and footer slot as `Modal`. */
-export declare function Drawer({ isOpen, onClose, size, side, radius, dismissible, ...dialogProps }: Readonly<DrawerProps>): JSX.Element | null;
+export declare function Drawer({ isOpen, onClose, size, side, radius, dismissible, onExited, ...dialogProps }: Readonly<DrawerProps>): JSX.Element | null;
 
 export declare interface DrawerProps {
     isOpen: boolean;
@@ -334,6 +413,8 @@ export declare interface DrawerProps {
     /** `false` hides the close button and blocks Escape and backdrop dismissal. */
     dismissible?: boolean;
     closeLabel?: string;
+    /** Called once per close, when the exit has finished and the panel is unmounted. Not called when the drawer reopens during the exit, nor on an initial render with `isOpen={false}`. */
+    onExited?: () => void;
     /** Wins over the first-tabbable rule for where focus lands on open; may point at an element in the body or in the footer. */
     initialFocusRef?: RefObject<HTMLElement | null>;
 }
@@ -342,6 +423,9 @@ export declare type DrawerSide = 'right' | 'left';
 
 export declare type DrawerSize = 'sm' | 'md' | 'lg';
 
+/** French translation of every `UILabels` entry, ready for `<UIProvider labels={FRENCH_UI_LABELS}>`. */
+export declare const FRENCH_UI_LABELS: UILabels;
+
 declare interface GlobalHotkeysStore {
     globalHotkeysEnabled: boolean;
     setGlobalHotkeysEnabled: (value: boolean) => void;
@@ -383,6 +467,11 @@ export declare type IconButtonProps = ComponentPropsWithRef<'button'> & {
     size?: ControlSize;
     children?: ReactNode;
     tooltip?: IconButtonTooltip;
+    /**
+     * Turns the button into a toggle: sets `aria-pressed` and a pressed look (dark fill and inset ring).
+     * Leave it `undefined` for a regular button (no attribute).
+     */
+    pressed?: boolean;
 } & IconButtonStyle;
 
 declare type IconButtonStyle = {
@@ -670,7 +759,7 @@ export declare type ModalSize = 'sm' | 'md' | 'lg' | 'xl';
  * pills opens a searchable dropdown of checkbox-style options. Selecting an
  * option never closes the dropdown, unlike the single-select `Combobox`.
  */
-export declare function MultiCombobox({ options, label, description, 'aria-label': ariaLabel, error, placeholder, searchPlaceholder, noResultsText, clearLabel, clearText, maxSelectedValues, isOptionDisabled, maxDisplayedValues, formatOverflowCount, formatSelectedCount, formatMaxSelectedHint, radius, unstyled, disabled, required, className, wrapperClassName, values, defaultValues, onChange, onDropdownClose, id, }: Readonly<MultiComboboxProps>): ReactElement;
+export declare function MultiCombobox({ options, filterOption, label, description, 'aria-label': ariaLabel, error, placeholder, searchPlaceholder, noResultsText, clearLabel, clearText, maxSelectedValues, isOptionDisabled, maxDisplayedValues, formatOverflowCount, formatSelectedCount, formatMaxSelectedHint, radius, unstyled, disabled, required, className, wrapperClassName, values, defaultValues, onChange, onDropdownClose, id, }: Readonly<MultiComboboxProps>): ReactElement;
 
 export declare interface MultiComboboxOption {
     value: string;
@@ -679,6 +768,12 @@ export declare interface MultiComboboxOption {
 
 export declare interface MultiComboboxProps {
     options: readonly MultiComboboxOption[];
+    /**
+     * Decides whether an option matches the text typed in the search field.
+     * Replaces the default case-insensitive "label contains the query" match,
+     * for example to ignore accents.
+     */
+    filterOption?: (option: MultiComboboxOption, query: string) => boolean;
     label?: string | ReactNode;
     description?: string | ReactNode;
     'aria-label'?: string;
@@ -718,7 +813,7 @@ export declare type RadioOption = ChoiceOption;
 export declare function RadioOptions({ options, orientation, value, defaultValue, onChange, name: nameProp, label, error, required, disabled, radius, unstyled, className, wrapperClassName, id, 'aria-describedby': callerDescribedBy, ...props }: Readonly<RadioOptionsProps>): JSX.Element;
 
 export declare interface RadioOptionsProps extends Omit<ComponentPropsWithRef<'fieldset'>, 'onChange'> {
-    options: string[] | RadioOption[];
+    options: readonly string[] | readonly RadioOption[];
     orientation?: 'vertical' | 'horizontal';
     value?: string;
     defaultValue?: string;
@@ -744,7 +839,7 @@ export declare interface SelectOption {
 }
 
 export declare interface SelectProps extends Omit<ComponentPropsWithRef<'select'>, 'children'> {
-    options: SelectOption[];
+    options: readonly SelectOption[];
     label?: string | ReactNode;
     description?: string | ReactNode;
     error?: string;
@@ -755,6 +850,28 @@ export declare interface SelectProps extends Omit<ComponentPropsWithRef<'select'
     wrapperClassName?: string;
 }
 
+/**
+ * A loading indicator exposed as a `role="status"` live region. It uses the
+ * icon `Button` shows while loading; under `prefers-reduced-motion` it swaps
+ * to a static icon.
+ *
+ * The region is empty on first render and filled right after mount, because
+ * many screen readers ignore a live region inserted already filled. The most
+ * robust setup is still a persistent `role="status"` wrapper in your own
+ * markup that stays mounted while a `Spinner` appears and disappears inside it.
+ */
+export declare function Spinner(spinnerProps: Readonly<SpinnerProps>): JSX.Element;
+
+export declare type SpinnerProps = Omit<ComponentPropsWithRef<'span'>, 'children'> & {
+    size?: ControlSize;
+    /** Visible text next to the icon. Without it, `labels.loading` is announced instead. */
+    label?: string;
+    /** Strips the built-in layout, text size and icon size; size the icon with `iconClassName`. */
+    unstyled?: boolean;
+    iconClassName?: string;
+    labelClassName?: string;
+};
+
 /**
  * A primary action joined to a chevron `Menu` trigger that offers secondary
  * variants of that action. Both halves share variant, color, size and radius:
@@ -869,7 +986,7 @@ export declare function Tabs({ items, value, defaultIndex, variant, orientation,
 export declare type TabsOrientation = 'horizontal' | 'vertical';
 
 export declare interface TabsProps {
-    items: TabItem[];
+    items: readonly TabItem[];
     value?: number;
     defaultIndex?: number;
     variant?: TabsVariant;
@@ -930,6 +1047,15 @@ export declare interface TextareaProps extends ComponentPropsWithRef<'textarea'>
 
 export declare type Theme = 'light' | 'dark' | 'system';
 
+/**
+ * A self-contained script that applies the saved theme to `<html>` before the
+ * first paint, so a dark-mode visitor never sees a light flash. It mirrors
+ * `useThemeStore`: the `dark` class is set for a stored `dark`, or for a
+ * stored `system` (or a missing, invalid or unreadable value) while the OS
+ * prefers dark. Inline it in `<head>` before the stylesheet.
+ */
+export declare const THEME_INIT_SCRIPT: string;
+
 declare interface ThemeStore {
     theme: Theme;
     setTheme: (theme: Theme) => void;
@@ -1060,8 +1186,14 @@ export declare interface UILabels {
     	required: string;
     	/** Screen-reader announcement of `CopyButton` after a successful copy. */
     	copied: string;
-    	/** Screen-reader text added to a `Button` while it is loading. */
+    	/** Screen-reader text added to a `Button` while it is loading, and announced by `Spinner` without a visible label. */
     	loading: string;
+    	/**
+     	 * Accessible name of the default `CopyButton` icon button. Optional so that
+     	 * existing complete label objects keep compiling: a translated label set
+     	 * must add it, otherwise the English "Copy" is used.
+     	 */
+    	copy?: string;
     	/** Screen-reader announcement of `CharacterCount` near and at the limit. */
     	charactersRemaining: (remainingCount: number) => string;
     	/** Accessible name of `ThemeToggle` for the current theme. */