@minimalstuff/ui 4.0.0 → 4.1.0

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;
@@ -298,6 +301,7 @@ export declare type IconButtonProps = ComponentPropsWithRef<'button'> & {
     'aria-label': string;
     size?: ControlSize;
     children?: ReactNode;
+    tooltip?: IconButtonTooltip;
 } & IconButtonStyle;
 
 declare type IconButtonStyle = {
@@ -309,10 +313,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,9 +503,10 @@ 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;
@@ -497,6 +520,10 @@ export declare interface ModalProps {
     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 +532,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 +606,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 +616,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;
@@ -678,10 +708,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 +730,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 +746,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 +796,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 +878,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 {}
+}