@minimalstuff/ui 5.1.0 → 5.3.0

package/README.md

@@ -59,6 +59,28 @@ import { THEME_INIT_SCRIPT } from '@minimalstuff/ui';
 </head>;
 ```
 
+#### Status bar and `theme-color`
+
+To make the browser or installed PWA status bar follow the theme, add a `theme-color` meta with a `data-light` and a `data-dark` color. `THEME_INIT_SCRIPT` and `useThemeStore` copy the matching one into `content` every time the theme is applied (init, `setTheme`, OS change while on `system`, another tab). A meta without both attributes is left alone, and without such a meta nothing changes.
+
+```html
+<head>
+	<meta
+		name="theme-color"
+		content="#ffffff"
+		data-light="#ffffff"
+		data-dark="#0b0b0b"
+	/>
+	<script>
+		/* THEME_INIT_SCRIPT */
+	</script>
+</head>
+```
+
+- Put the meta before the script in `<head>`.
+- Remove any other `theme-color` meta, notably ones with a `media` attribute: the first matching one wins.
+- Keep the meta in the static HTML. A meta recreated by a `<head>` manager (Inertia `<Head>`, react-helmet) is not resynced.
+
 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
@@ -88,6 +110,8 @@ pnpm verify
 
 `pnpm test:stories` runs the stories in a real browser and needs Playwright's Chromium once: `pnpm exec playwright install chromium`.
 
+To change the library from a project that uses it, see [docs/developing_from_a_consumer.md](docs/developing_from_a_consumer.md).
+
 Releases follow [docs/releasing.md](docs/releasing.md). Changes are listed in the [CHANGELOG](CHANGELOG.md).
 
 ## Report a bug

package/dist/index.d.ts

@@ -9,6 +9,7 @@ import { ReactElement } from 'react';
 import { ReactNode } from 'react';
 import { ReactPortal } from 'react';
 import { Ref } from 'react';
+import { RefCallback } from 'react';
 import { RefObject } from 'react';
 import { StoreApi } from 'zustand';
 import { UseBoundStore } from 'zustand';
@@ -250,7 +251,7 @@ export declare interface ClientOnlyProps extends React.PropsWithChildren {
     fallback?: React.ReactNode;
 }
 
-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 function Combobox({ options, filterOption, label, description, 'aria-label': ariaLabel, error, placeholder, noResultsText, clearLabel, radius, unstyled, disabled, required, className, wrapperClassName, dropdownClassName, optionLabelOverflow, value, defaultValue, onChange, id, }: Readonly<ComboboxProps>): JSX.Element;
 
 export declare interface ComboboxOption {
     value: string;
@@ -258,6 +259,7 @@ export declare interface ComboboxOption {
 }
 
 export declare interface ComboboxProps {
+    /** Long lists render faster when the array keeps the same identity between renders (memoize it), and when `optionLabelOverflow` is not `'wrap'`. */
     options: readonly ComboboxOption[];
     /**
      * Decides whether an option matches the text typed in the field. Replaces
@@ -278,6 +280,19 @@ export declare interface ComboboxProps {
     required?: boolean;
     className?: string;
     wrapperClassName?: string;
+    /**
+     * Classes for the dropdown panel, applied last so they can override its
+     * defaults, for example a width wider than the field when option labels are
+     * long (`w-96`, `min-w-80`). The panel is kept inside the viewport.
+     */
+    dropdownClassName?: string;
+    /**
+     * How option labels that do not fit on one line are shown.
+     * - `'wrap'` (default): labels wrap; every option is rendered, so lists of thousands of options open slower.
+     * - `'wrap-active'`: labels are truncated with a native tooltip, except the active option, which wraps in full; long lists only render the visible options. Recommended for long lists.
+     * - `'truncate'`: every label is truncated with a native tooltip, the active one included; keyboard and zoom users can no longer read long labels (WCAG 1.4.10), use only for labels known to be short.
+     */
+    optionLabelOverflow?: OptionLabelOverflow;
     value?: string;
     defaultValue?: string;
     onChange?: (value: string) => void;
@@ -370,8 +385,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;
@@ -397,6 +428,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>;
 }
@@ -509,6 +542,15 @@ export declare interface KbdProps {
 
 export declare type KbdSize = ControlSize;
 
+export declare type KeyboardScrollableProps = {
+    ref: RefCallback<HTMLElement>;
+    tabIndex?: 0;
+    role?: 'region';
+    'aria-labelledby'?: string;
+    'aria-label'?: string;
+    'data-keyboard-scroll-region'?: true;
+};
+
 /**
  * A dropdown anchored to `trigger` (e.g. a kebab `IconButton`): click to
  * open, click again/click outside/Escape to close, or ArrowDown/ArrowUp on
@@ -707,11 +749,15 @@ export declare interface ModalFooterProps {
 
 export declare type ModalHeight = 'auto' | 'fixed';
 
+export declare type ModalPhoneLayout = 'center' | 'sheet';
+
 export declare type ModalProps = {
     children: ModalRenderProp;
     size?: ModalSize;
     /** `fixed` gives the dialog a stable height so it does not jump when content changes; the content area stops scrolling and a child with `flex-1 min-h-0 overflow-y-auto` scrolls on its own. */
     height?: ModalHeight;
+    /** `sheet` turns the dialog into a bottom sheet below the `sm` breakpoint (full width, flush with the bottom edge, only the top corners rounded, at most 85svh tall, bottom padding clearing the safe area, sliding up on open and down on close; plain fade under reduced motion). From `sm` up it renders as `center`. With `height="fixed"` the sheet is 85svh tall on phones. `unstyled` keeps the sheet position and size but drops radius and the slide. */
+    phoneLayout?: ModalPhoneLayout;
     radius?: Radius;
     className?: string;
     /** Applied to the `role=dialog` element. A `transform`, `filter` or `backdrop-filter` on the open panel makes it the containing block of `position: fixed` descendants, so Menus opened inside it get clipped. Keep these off the open state. Carries `data-state="open"` or `"closed"`, so `data-[state=closed]:` variants can animate it. Put your own transitions behind `motion-reduce:` variants, since `unstyled` drops the library's reduced-motion handling along with its animations. */
@@ -741,7 +787,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, 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 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, dropdownClassName, optionLabelOverflow, values, defaultValues, onChange, onDropdownClose, id, }: Readonly<MultiComboboxProps>): ReactElement;
 
 export declare interface MultiComboboxOption {
     value: string;
@@ -749,6 +795,7 @@ export declare interface MultiComboboxOption {
 }
 
 export declare interface MultiComboboxProps {
+    /** Long lists render faster when the array keeps the same identity between renders (memoize it), and when `optionLabelOverflow` is not `'wrap'`. */
     options: readonly MultiComboboxOption[];
     /**
      * Decides whether an option matches the text typed in the search field.
@@ -777,6 +824,19 @@ export declare interface MultiComboboxProps {
     required?: boolean;
     className?: string;
     wrapperClassName?: string;
+    /**
+     * Classes for the dropdown panel, applied last so they can override its
+     * defaults, for example a width wider than the field when option labels are
+     * long (`w-96`, `min-w-80`). The panel is kept inside the viewport.
+     */
+    dropdownClassName?: string;
+    /**
+     * How option labels that do not fit on one line are shown.
+     * - `'wrap'` (default): labels wrap; every option is rendered, so lists of thousands of options open slower.
+     * - `'wrap-active'`: labels are truncated with a native tooltip, except the active option, which wraps in full; long lists only render the visible options. Recommended for long lists.
+     * - `'truncate'`: every label is truncated with a native tooltip, the active one included; keyboard and zoom users can no longer read long labels (WCAG 1.4.10), use only for labels known to be short.
+     */
+    optionLabelOverflow?: OptionLabelOverflow;
     values?: readonly string[];
     defaultValues?: readonly string[];
     onChange?: (values: readonly string[]) => void;
@@ -790,6 +850,8 @@ export declare interface MultiComboboxProps {
     id?: string;
 }
 
+export declare type OptionLabelOverflow = 'wrap' | 'wrap-active' | 'truncate';
+
 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;
@@ -937,7 +999,7 @@ export declare function splitIntoHighlightSegments(
     	return segments;
 }
 
-export declare function Switch({ label, description, error, unstyled, fullWidth, className, wrapperClassName, checked, defaultChecked, onChange, id, 'aria-describedby': callerDescribedBy, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, ...props }: Readonly<SwitchProps>): JSX.Element;
+export declare function Switch({ label, description, error, unstyled, fullWidth, className, wrapperClassName, checked, defaultChecked, onChange, id, 'aria-describedby': callerDescribedBy, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, ref, ...props }: Readonly<SwitchProps>): JSX.Element;
 
 export declare interface SwitchProps extends Omit<ComponentPropsWithRef<'input'>, 'type' | 'className'> {
     label?: string | ReactNode;
@@ -1034,7 +1096,10 @@ export declare type Theme = 'light' | 'dark' | 'system';
  * 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.
+ * prefers dark. Every `<meta name="theme-color" data-light="..." data-dark="...">`
+ * also gets its `content` set from `data-dark` or `data-light`; it must come
+ * before this script in `<head>`. Inline the script in `<head>` before the
+ * stylesheet.
  */
 export declare const THEME_INIT_SCRIPT: string;
 
@@ -1237,6 +1302,43 @@ export declare const useGlobalHotkeysStore: UseBoundStore<StoreApi<GlobalHotkeys
 
 export declare const useIsClient: () => boolean;
 
+/**
+ * Makes a scroll container reachable by keyboard. When the container overflows
+ * and holds nothing tabbable, `scrollableProps` gives it a tab stop, a
+ * `region` role and an accessible name, and `focusClassName` a visible focus
+ * outline. Otherwise only the `ref` is returned. Re-evaluated on resize and on
+ * content changes; a container mounted after the first render is observed too.
+ *
+ * To combine `scrollableProps.ref` with your own ref, use a ref callback that
+ * calls both.
+ *
+ * @example
+ * const { scrollableProps, focusClassName } = useKeyboardScrollable({
+ *   label: 'Release notes',
+ * })
+ * return (
+ *   <div {...scrollableProps} className={cn('h-64 overflow-y-auto', focusClassName)}>
+ *     {content}
+ *   </div>
+ * )
+ */
+export declare function useKeyboardScrollable(options: Readonly<UseKeyboardScrollableOptions>): UseKeyboardScrollableReturn;
+
+/** A scroll region must be named, exactly once: by `label` or by `labelledBy`. */
+export declare type UseKeyboardScrollableOptions = {
+    label: string;
+    labelledBy?: never;
+} | {
+    labelledBy: string;
+    label?: never;
+};
+
+export declare type UseKeyboardScrollableReturn = {
+    scrollableProps: KeyboardScrollableProps;
+    /** Focus outline classes to add to the container's `className`; `undefined` when the container is not a tab stop. */
+    focusClassName: string | undefined;
+};
+
 export declare const useThemeStore: UseBoundStore<StoreApi<ThemeStore>>;
 
 /** Wraps `Component` so it only renders once the client has mounted. */
@@ -1250,3 +1352,10 @@ declare module 'vitest' {
 	interface Assertion<T = unknown> extends AxeMatchers {}
 	interface AsymmetricMatchersContaining extends AxeMatchers {}
 }
+
+declare module 'vitest/browser' {
+    interface BrowserCommands {
+        /** Moves the real mouse cursor to a point outside the story document. */
+        movePointerOutOfStory: () => Promise<void>;
+    }
+}