@minimalstuff/ui 4.0.0 → 4.2.0

package/README.md

@@ -23,6 +23,10 @@ export function App() {
 
 The `@minimalstuff/ui/style.css` import is required for styles and icons to render.
 
+### 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.
+
 ## Development
 
 ```bash
@@ -39,11 +43,7 @@ CI (lint, test, build) and npm publish run together when a GitHub Release is pub
 
 ### Prerequisites
 
-1. **NPM token**
-   Create an automation token at [npmjs.com/access-tokens](https://www.npmjs.com/access-tokens) (scope: package publish for `@minimalstuff/ui`).
-
-2. **Repository secret**
-   In the repo: **Settings → Secrets and variables → Actions**. Add a secret named `NPM_TOKEN` with the token value.
+Publishing uses npm [trusted publishing](https://docs.npmjs.com/trusted-publishers) (OIDC), no token needed. On npmjs.com, `@minimalstuff/ui` > **Settings > Trusted publishing** must list GitHub Actions with organization `minimalstuff`, repository `ui` and workflow `publish.yml`.
 
 ### Procedure
 

package/dist/index.d.ts

@@ -8,6 +8,7 @@ import { ReactElement } from 'react';
 import { ReactNode } from 'react';
 import { ReactPortal } from 'react';
 import { Ref } from 'react';
+import { RefObject } from 'react';
 import { StoreApi } from 'zustand';
 import { UseBoundStore } from 'zustand';
 
@@ -134,7 +135,7 @@ export declare interface CharacterCountProps {
     className?: string;
 }
 
-export declare function Checkbox({ label, description, error, radius, unstyled, fullWidth, variant, className, wrapperClassName, checked, defaultChecked, onChange, id, 'aria-describedby': callerDescribedBy, ...props }: Readonly<CheckboxProps>): JSX.Element;
+export declare function Checkbox({ label, indeterminate, description, error, radius, unstyled, fullWidth, variant, className, wrapperClassName, checked, defaultChecked, onChange, id, 'aria-describedby': callerDescribedBy, ref, ...props }: Readonly<CheckboxProps>): JSX.Element;
 
 export declare type CheckboxOption = ChoiceOption;
 
@@ -160,6 +161,8 @@ export declare interface CheckboxOptionsProps extends Omit<ComponentPropsWithRef
 
 export declare interface CheckboxProps extends Omit<ComponentPropsWithRef<'input'>, 'type' | 'className'> {
     label?: string | React.ReactNode;
+    /** Shows a dash instead of the checkmark and exposes the mixed state to assistive technology. */
+    indeterminate?: boolean;
     description?: string | React.ReactNode;
     error?: string;
     radius?: Radius;
@@ -273,6 +276,35 @@ export declare interface CopyButtonProps {
     onError?: (error: unknown) => void;
 }
 
+/** 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 interface DrawerProps {
+    isOpen: boolean;
+    onClose: () => void;
+    /** Names the dialog. */
+    title: ReactNode;
+    children: ReactNode;
+    /** Pinned below the body; a `ModalFooter` inside `children` renders in the same place. */
+    footer?: ReactNode;
+    size?: DrawerSize;
+    /** The edge of the viewport the panel is attached to. */
+    side?: DrawerSide;
+    /** Applied to the corners on the edge facing the page only. */
+    radius?: Radius;
+    /** Applied to the scrollable body. */
+    className?: string;
+    /** `false` hides the close button and blocks Escape and backdrop dismissal. */
+    dismissible?: boolean;
+    closeLabel?: string;
+    /** 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>;
+}
+
+export declare type DrawerSide = 'right' | 'left';
+
+export declare type DrawerSize = 'sm' | 'md' | 'lg';
+
 declare interface GlobalHotkeysStore {
     globalHotkeysEnabled: boolean;
     setGlobalHotkeysEnabled: (value: boolean) => void;
@@ -298,6 +330,7 @@ export declare type IconButtonProps = ComponentPropsWithRef<'button'> & {
     'aria-label': string;
     size?: ControlSize;
     children?: ReactNode;
+    tooltip?: IconButtonTooltip;
 } & IconButtonStyle;
 
 declare type IconButtonStyle = {
@@ -309,10 +342,28 @@ declare type IconButtonStyle = {
     radius?: Radius;
 };
 
-export declare function Input({ label, error, showCharCount, minLength, maxLength, radius, unstyled, className, wrapperClassName, value, defaultValue, onChange, id, 'aria-describedby': callerDescribedBy, ...props }: Readonly<InputProps>): JSX.Element;
+/**
+ * Wraps the button in a `Tooltip`. `true` shows the `aria-label` at the
+ * default position, a position string moves it, and an object also allows
+ * custom `content`. When the tooltip repeats the `aria-label` it does not
+ * describe the button, so screen readers do not announce the name twice.
+ */
+export declare type IconButtonTooltip =
+	| boolean
+	| TooltipPosition
+	| IconButtonTooltipOptions;
+
+declare interface IconButtonTooltipOptions {
+    	position?: TooltipPosition;
+    	/** Defaults to the button's `aria-label`. */
+    	content?: ReactNode;
+}
+
+export declare function Input({ label, description, error, showCharCount, minLength, maxLength, radius, unstyled, className, wrapperClassName, value, defaultValue, onChange, id, 'aria-describedby': callerDescribedBy, ...props }: Readonly<InputProps>): JSX.Element;
 
 export declare interface InputProps extends ComponentPropsWithRef<'input'> {
     label?: string | ReactNode;
+    description?: string | ReactNode;
     error?: string;
     showCharCount?: boolean;
     minLength?: number;
@@ -481,22 +532,31 @@ export declare const Modal: Callable<ModalProps, void, {}>;
  * Declares `children` as the modal's pinned footer, wherever this is
  * rendered in the content tree — including inside a separate content
  * component, any number of levels below `Modal`'s own `children`. Renders
- * nothing itself; `Modal` places the actual footer in its own layout.
+ * nothing in place; the children are portaled into the modal's own footer
+ * slot, so they stay React children of this component.
  */
-export declare function ModalFooter({ children }: Readonly<ModalFooterProps>): null;
+export declare function ModalFooter({ children }: Readonly<ModalFooterProps>): ReactPortal | null;
 
 export declare interface ModalFooterProps {
     children: ReactNode;
 }
 
+export declare type ModalHeight = 'auto' | 'fixed';
+
 export declare interface ModalProps {
     title?: ReactNode;
     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;
     radius?: Radius;
     className?: string;
     dismissible?: boolean;
     closeLabel?: string;
+    /** `alertdialog` for urgent messages that need a response (describes the dialog by its content); pair with `dismissible={false}` when it must not be dismissed. */
+    role?: ModalRole;
+    /** Wins over the first-tabbable rule for where focus lands on open; may point at an element in the content or in a `ModalFooter`. */
+    initialFocusRef?: RefObject<HTMLElement | null>;
     /** Names the dialog when there is no `title`; ignored when `title` is set since the title labels it. */
     'aria-label'?: string;
 }
@@ -505,6 +565,8 @@ export declare function ModalProvider(): JSX.Element;
 
 declare type ModalRenderProp = ReactNode | ((close: () => void) => ReactNode);
 
+export declare type ModalRole = 'dialog' | 'alertdialog';
+
 export declare type ModalSize = 'sm' | 'md' | 'lg' | 'xl';
 
 /**
@@ -577,7 +639,7 @@ export declare interface RadioOptionsProps extends Omit<ComponentPropsWithRef<'f
 
 declare type Radius = 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'full';
 
-export declare function Select({ options, label, error, placeholder, radius, unstyled, className, wrapperClassName, value, defaultValue, onChange, id, 'aria-describedby': callerDescribedBy, ...props }: Readonly<SelectProps>): JSX.Element;
+export declare function Select({ options, label, description, error, placeholder, radius, unstyled, className, wrapperClassName, value, defaultValue, onChange, id, 'aria-describedby': callerDescribedBy, ...props }: Readonly<SelectProps>): JSX.Element;
 
 export declare interface SelectOption {
     value: string;
@@ -587,6 +649,7 @@ export declare interface SelectOption {
 export declare interface SelectProps extends Omit<ComponentPropsWithRef<'select'>, 'children'> {
     options: SelectOption[];
     label?: string | ReactNode;
+    description?: string | ReactNode;
     error?: string;
     placeholder?: string;
     radius?: Radius;
@@ -652,24 +715,52 @@ export declare interface TabItem {
     content: ReactNode;
     disabled?: boolean;
     icon?: string;
+    /**
+     * Rendered after the title inside the tab button and part of the tab's
+     * accessible name. Meant for short text such as an error count ("1 error"),
+     * never a coloured dot alone. Separate from `title`, which is the React key
+     * and must stay stable.
+     */
+    badge?: ReactNode;
 }
 
-export declare function Tabs({ items, value, defaultIndex, variant, size, radius, fullWidth, unstyled, animated, className, tabListClassName, panelClassName, onChange, }: Readonly<TabsProps>): JSX.Element;
+export declare function Tabs({ items, value, defaultIndex, variant, orientation, size, radius, fullWidth, unstyled, animated, keepMounted, className, tabListClassName, panelClassName, onChange, }: Readonly<TabsProps>): JSX.Element;
+
+export declare type TabsOrientation = 'horizontal' | 'vertical';
 
 export declare interface TabsProps {
     items: TabItem[];
     value?: number;
     defaultIndex?: number;
     variant?: TabsVariant;
+    /**
+     * Direction the tabs are laid out in. `vertical` stacks the tablist beside
+     * the panel and navigates with ArrowDown/ArrowUp instead of
+     * ArrowRight/ArrowLeft. Give the root a height (e.g. `className="min-h-0
+     * flex-1"` in a fixed-height parent) and the tablist and panel scroll
+     * independently. Defaults to `horizontal`.
+     */
+    orientation?: TabsOrientation;
     size?: ControlSize;
     /**
      * Only visibly rounds the `segmented` variant's track and tabs. The `line`
      * variant has no filled surface to round, so radius is a no-op there.
      */
     radius?: Radius;
+    /** Stretches the tabs across the tablist. A no-op when `orientation` is `vertical`. */
     fullWidth?: boolean;
     unstyled?: boolean;
     animated?: boolean;
+    /**
+     * Keeps every panel in the DOM and only hides the inactive ones, so React
+     * state (typed input, scroll position) inside a panel survives tab
+     * switches. Every tab then carries `aria-controls` pointing at its own
+     * panel. When `false`, only the active panel is rendered, so only the
+     * active tab carries `aria-controls` (it must reference an existing
+     * element; a dangling id fails `aria-valid-attr-value`). Defaults to
+     * `false`.
+     */
+    keepMounted?: boolean;
     className?: string;
     tabListClassName?: string;
     panelClassName?: string;
@@ -678,10 +769,11 @@ export declare interface TabsProps {
 
 export declare type TabsVariant = 'line' | 'segmented';
 
-export declare function Textarea({ label, error, showCharCount, minLength, maxLength, radius, unstyled, className, wrapperClassName, value, defaultValue, onChange, id, 'aria-describedby': callerDescribedBy, ...props }: Readonly<TextareaProps>): JSX.Element;
+export declare function Textarea({ label, description, error, showCharCount, minLength, maxLength, radius, unstyled, className, wrapperClassName, value, defaultValue, onChange, id, 'aria-describedby': callerDescribedBy, ...props }: Readonly<TextareaProps>): JSX.Element;
 
 export declare interface TextareaProps extends ComponentPropsWithRef<'textarea'> {
     label?: string | ReactNode;
+    description?: string | ReactNode;
     error?: string;
     showCharCount?: boolean;
     minLength?: number;
@@ -699,9 +791,15 @@ declare interface ThemeStore {
     setTheme: (theme: Theme) => void;
 }
 
-export declare function ThemeToggle({ isTransitionEnabled, transitionDuration, transitionEasing, size, radius, variant, getAriaLabel, }: Readonly<ThemeToggleProps>): JSX.Element;
+export declare function ThemeToggle({ isTransitionEnabled, transitionDuration, transitionEasing, size, radius, variant, getAriaLabel, tooltip, }: Readonly<ThemeToggleProps>): JSX.Element;
 
 export declare interface ThemeToggleProps {
+    /**
+     * Animate the theme change with the View Transition API.
+     * Defaults to automatic: enabled, except on WebKitGTK where
+     * `startViewTransition` crashes the web process (2.54).
+     * `prefers-reduced-motion` is always respected.
+     */
     isTransitionEnabled?: boolean;
     transitionDuration?: number;
     transitionEasing?: string;
@@ -709,15 +807,42 @@ export declare interface ThemeToggleProps {
     radius?: Radius;
     variant?: ButtonVariant;
     getAriaLabel?: (theme: Theme) => string;
+    tooltip?: IconButtonTooltip;
 }
 
+/**
+ * A group of related controls with a single tab stop (WAI-ARIA toolbar).
+ * Tab enters the toolbar on the last focused item (the first enabled one
+ * initially); the arrow keys of the orientation (Left/Right horizontally,
+ * Up/Down vertically) move focus between items and wrap at the ends, Home and
+ * End jump to the first and last item, and disabled items are skipped. Arrow
+ * keys are left alone inside text fields. Requires `aria-label` or
+ * `aria-labelledby`.
+ */
+export declare function Toolbar(toolbarProps: Readonly<ToolbarProps>): JSX.Element;
+
+declare type ToolbarAccessibleName = {
+    'aria-label': string;
+    'aria-labelledby'?: undefined;
+} | {
+    'aria-labelledby': string;
+    'aria-label'?: undefined;
+};
+
+declare type ToolbarOrientation = 'horizontal' | 'vertical';
+
+export declare type ToolbarProps = Omit<ComponentPropsWithRef<'div'>, 'role' | 'aria-label' | 'aria-labelledby' | 'aria-orientation'> & {
+    orientation?: ToolbarOrientation;
+    unstyled?: boolean;
+} & ToolbarAccessibleName;
+
 /**
  * The trigger (`children`) must be focusable, otherwise the tooltip is
  * unreachable by keyboard. Shows on hover and focus; Escape dismisses it.
  * `temporaryContent` is announced to screen readers through a polite status
  * region.
  */
-export declare function Tooltip({ content, children, position, showOnClick, temporaryContent, temporaryDuration, disabled, radius, onTemporaryShow, className, ref, }: Readonly<TooltipProps>): JSX.Element;
+export declare function Tooltip({ content, children, position, showOnClick, temporaryContent, temporaryDuration, disabled, radius, onTemporaryShow, className, describeChild, portalContainer, ref, }: Readonly<TooltipProps>): JSX.Element;
 
 export declare type TooltipPosition = 'top' | 'bottom' | 'left' | 'right';
 
@@ -732,10 +857,76 @@ export declare interface TooltipProps {
     radius?: Radius;
     onTemporaryShow?: () => void;
     className?: string;
+    /**
+     * Whether the trigger is described by the tooltip (`aria-describedby`).
+     * `true` always describes, `false` never does. By default the trigger is
+     * described unless the tooltip text repeats its accessible name, which
+     * screen readers would otherwise announce twice.
+     */
+    describeChild?: boolean;
+    /**
+     * Where the tooltip is rendered. Defaults to the trigger's closest
+     * landmark or dialog (so it stays inside a landmark and inside an open
+     * modal), falling back to `document.body`. Transformed ancestors (such as the modal
+     * panel) can clip it; pass `portalContainer` to escape.
+     */
+    portalContainer?: HTMLElement | null;
     /** Attaches to the wrapper `<span>` around `children`, alongside `Tooltip`'s own internal ref. */
     ref?: Ref<HTMLSpanElement>;
 }
 
+export declare interface UILabels {
+    	/** Accessible name of the modal close button. */
+    	close: string;
+    	/** Confirm button of `ConfirmModal`. */
+    	confirm: string;
+    	/** Cancel button of `ConfirmModal`. */
+    	cancel: string;
+    	/** Empty state of `Combobox` and `MultiCombobox`. */
+    	noResults: string;
+    	/** Accessible name of the button clearing a selection. */
+    	clearSelection: string;
+    	/** Placeholder and accessible name of the `MultiCombobox` search field. */
+    	search: string;
+    	/** Visible text of the `MultiCombobox` clear button. */
+    	clear: string;
+    	/** Screen-reader suffix of a required `CheckboxOptions` group. */
+    	required: string;
+    	/** Accessible name of `ThemeToggle` for the current theme. */
+    	currentTheme: (theme: Theme) => string;
+    	/** `MultiCombobox` badge summarising the values that do not fit. */
+    	overflowCount: (hiddenCount: number) => string;
+    	/** `MultiCombobox` summary of the number of selected values. */
+    	selectedCount: (selectedCount: number) => string;
+    	/** `MultiCombobox` hint shown when the selection limit is reached. */
+    	maxSelectedHint: (maxSelectedValues: number) => string;
+}
+
+/**
+ * Provides default user-facing labels (close, confirm, no results...) to every
+ * component below it. Precedence: explicit prop > provider > English default.
+ *
+ * `Modal` and `ConfirmModal` render where `<ModalProvider />` is mounted, so
+ * mount `ModalProvider` inside `UIProvider` for them to receive the labels.
+ */
+export declare function UIProvider({ labels, announceFieldErrors, children, }: Readonly<UIProviderProps>): JSX.Element;
+
+export declare interface UIProviderProps {
+    /** Overrides the default labels. Nested providers merge over their parent. */
+    labels?: Partial<UILabels>;
+    /**
+     * Whether field errors are announced as they appear (`role="alert"`).
+     * Defaults to `true`; nested providers inherit the parent value unless set.
+     * Set it to `false` when the app announces errors itself (an error summary
+     * or focus on the first invalid field): it avoids several alerts firing at
+     * once on submit, and lets WebKitGTK re-read the error on focus, since it
+     * leaves `role="alert"` content out of the computed description. The error
+     * stays linked by `aria-describedby` either way.
+     */
+    announceFieldErrors?: boolean;
+    children: ReactNode;
+}
+
 export declare function useDisableHotkeysWhileMounted(): void;
 
 export declare const useGlobalHotkeysStore: UseBoundStore<StoreApi<GlobalHotkeysStore>>;
@@ -748,3 +939,10 @@ export declare const useThemeStore: UseBoundStore<StoreApi<ThemeStore>>;
 export declare const withClientOnly: <TProps extends object>(Component: React.ComponentType<TProps>) => React.ComponentType<TProps>;
 
 export { }
+
+
+
+declare module 'vitest' {
+	interface Assertion<T = unknown> extends AxeMatchers {}
+	interface AsymmetricMatchersContaining extends AxeMatchers {}
+}