@minimalstuff/ui 3.2.0 → 4.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sonny
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -53,7 +53,6 @@ export declare type BadgeSize = ControlSize;
 
 export declare type BadgeVariant = 'solid' | 'outline' | 'subtle';
 
-/** Chrome shared by every text-entry control (Input, Textarea, Select, Combobox). */
 export declare const BASE_INPUT_STYLES = "w-full border border-gray-300 dark:border-gray-600 bg-white dark:bg-gray-800 text-gray-900 dark:text-gray-100 placeholder-gray-500 dark:placeholder-gray-400 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent transition-all duration-200 disabled:opacity-50 disabled:cursor-not-allowed";
 
 export declare function Button(buttonProps: Readonly<ButtonProps>): JSX.Element;
@@ -122,7 +121,7 @@ export declare interface CardProps {
     className?: string;
 }
 
-export declare function CharacterCount({ current, min, max, showMin, showMax, unstyled, className, }: Readonly<CharacterCountProps>): JSX.Element;
+export declare function CharacterCount({ current, min, max, showMin, showMax, unstyled, id, className, }: Readonly<CharacterCountProps>): JSX.Element;
 
 export declare interface CharacterCountProps {
     current: number;
@@ -131,10 +130,33 @@ export declare interface CharacterCountProps {
     showMin?: boolean;
     showMax?: boolean;
     unstyled?: boolean;
+    id?: string;
     className?: string;
 }
 
-export declare function Checkbox({ label, description, error, radius, unstyled, className, wrapperClassName, checked, defaultChecked, onChange, id, ...props }: Readonly<CheckboxProps>): JSX.Element;
+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 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[];
+    orientation?: 'vertical' | 'horizontal';
+    values?: readonly string[];
+    defaultValues?: readonly string[];
+    onChange?: (values: readonly string[]) => void;
+    name?: string;
+    label?: string | React.ReactNode;
+    error?: string;
+    required?: boolean;
+    requiredLabel?: string;
+    radius?: Radius;
+    unstyled?: boolean;
+    className?: string;
+    wrapperClassName?: string;
+    id?: string;
+}
 
 export declare interface CheckboxProps extends Omit<ComponentPropsWithRef<'input'>, 'type' | 'className'> {
     label?: string | React.ReactNode;
@@ -142,17 +164,28 @@ export declare interface CheckboxProps extends Omit<ComponentPropsWithRef<'input
     error?: string;
     radius?: Radius;
     unstyled?: boolean;
+    fullWidth?: boolean;
+    variant?: 'inline' | 'card';
     className?: string;
     wrapperClassName?: string;
 }
 
+/** One choice in a `RadioOptions` or `CheckboxOptions` list. */
+export declare interface ChoiceOption {
+    	value: string;
+    	label: string;
+    	description?: string;
+    	icon?: string;
+    	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 interface ClientOnlyProps extends React.PropsWithChildren {
     fallback?: React.ReactNode;
 }
 
-export declare function Combobox({ options, label, error, placeholder, noResultsText, clearLabel, radius, unstyled, disabled, required, className, wrapperClassName, value, defaultValue, onChange, id, }: Readonly<ComboboxProps>): JSX.Element;
+export declare function Combobox({ options, label, '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;
@@ -162,6 +195,7 @@ export declare interface ComboboxOption {
 export declare interface ComboboxProps {
     options: ComboboxOption[];
     label?: string | ReactNode;
+    'aria-label'?: string;
     error?: string;
     placeholder?: string;
     noResultsText?: string;
@@ -202,10 +236,16 @@ export declare type ConfirmModalResponse = boolean;
  * `MenuSeparator`s — at the cursor position. Right-click again elsewhere on
  * the wrapped area to reposition it.
  *
+ * Keyboard-only users reach it via Shift+F10 or the Menu key instead of a
+ * right-click, but only once the wrapped area (or something inside it) can
+ * hold focus — give `children` a focusable element, or a `tabIndex={0}` plus
+ * a `role` and `aria-label` on the wrapper itself, or Shift+F10 has nothing
+ * to fire on. See `context_menu.stories.tsx`'s `Default` story.
+ *
  * For a menu anchored to a specific button (e.g. a kebab icon) instead of a
  * right-click, use `Menu`.
  */
-export declare function ContextMenu({ children, items, radius, className, ref, }: Readonly<ContextMenuProps>): JSX.Element;
+export declare function ContextMenu({ children, items, radius, className, ref, 'aria-label': ariaLabel, }: Readonly<ContextMenuProps>): JSX.Element;
 
 export declare interface ContextMenuProps {
     /** The area that opens the menu on right-click. */
@@ -215,6 +255,8 @@ export declare interface ContextMenuProps {
     radius?: Radius;
     className?: string;
     ref?: Ref<HTMLDivElement>;
+    /** Names the menu for assistive tech, since there is no trigger element to label it from. */
+    'aria-label'?: string;
 }
 
 /** The size scale every inline control shares (Button, IconButton, Badge, Kbd). */
@@ -267,7 +309,7 @@ declare type IconButtonStyle = {
     radius?: Radius;
 };
 
-export declare function Input({ label, error, showCharCount, minLength, maxLength, radius, unstyled, className, wrapperClassName, value, defaultValue, onChange, id, ...props }: Readonly<InputProps>): JSX.Element;
+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;
 
 export declare interface InputProps extends ComponentPropsWithRef<'input'> {
     label?: string | ReactNode;
@@ -295,20 +337,27 @@ export declare type KbdSize = ControlSize;
 
 /**
  * A dropdown anchored to `trigger` (e.g. a kebab `IconButton`): click to
- * open, click again/click outside/Escape to close. `children` is made of
- * `MenuItem`s, optionally wrapped in `MenuGroup`s and split by
- * `MenuSeparator`s.
+ * open, click again/click outside/Escape to close, or ArrowDown/ArrowUp on
+ * the closed trigger to open focused on the first/last item respectively.
+ * `children` is made of `MenuItem`s, optionally wrapped in `MenuGroup`s and
+ * split by `MenuSeparator`s.
  *
  * For "right-click anywhere on this area" instead of a specific trigger
  * button, use `ContextMenu`.
  *
- * Opening a `Modal` from a `MenuItem`'s `onClick` is safe: the menu returns
- * focus to `trigger` synchronously during the click, then the modal mounts a
- * render later and takes focus from there. That ordering is what makes the
- * modal record `trigger` as its restore target, so focus lands back on the
- * trigger when the modal closes. The menu panel outlives the click by one
- * exit animation, but the modal sits above it and owns Escape (a document
- * listener), so the fading panel is inert. See `menu_with_modal.test.tsx`.
+ * Safe to nest inside a `Modal`: Escape on the open menu calls
+ * `event.preventDefault()` before closing it (see `MenuSurface`), so the
+ * modal's own Escape handler — which ignores an already-`defaultPrevented`
+ * event — leaves the dialog open and only the menu closes.
+ *
+ * Opening a `Modal` from a `MenuItem`'s `onClick` is also safe: the menu
+ * returns focus to `trigger` synchronously during the click, then the modal
+ * mounts a render later and takes focus from there. That ordering is what
+ * makes the modal record `trigger` as its restore target, so focus lands
+ * back on the trigger when the modal closes. The menu panel outlives the
+ * click by one exit animation, but the modal sits above it and owns Escape
+ * (a document listener), so the fading panel is inert. See
+ * `menu_with_modal.test.tsx`.
  */
 export declare function Menu({ trigger, children, side, align, radius, className, ref, }: Readonly<MenuProps>): JSX.Element;
 
@@ -448,6 +497,8 @@ export declare interface ModalProps {
     className?: string;
     dismissible?: boolean;
     closeLabel?: string;
+    /** Names the dialog when there is no `title`; ignored when `title` is set since the title labels it. */
+    'aria-label'?: string;
 }
 
 export declare function ModalProvider(): JSX.Element;
@@ -456,15 +507,56 @@ declare type ModalRenderProp = ReactNode | ((close: () => void) => ReactNode);
 
 export declare type ModalSize = 'sm' | 'md' | 'lg' | 'xl';
 
-export declare interface RadioOption {
+/**
+ * Multi-select combobox: a trigger button showing the selected options as
+ * 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, '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;
     label: string;
-    description?: string;
-    icon?: string;
+}
+
+export declare interface MultiComboboxProps {
+    options: readonly MultiComboboxOption[];
+    label?: string | ReactNode;
+    'aria-label'?: string;
+    error?: string;
+    placeholder?: string;
+    searchPlaceholder?: string;
+    noResultsText?: string;
+    clearLabel?: string;
+    clearText?: string;
+    maxSelectedValues?: number;
+    isOptionDisabled?: (optionValue: string, selectedValues: readonly string[]) => boolean;
+    maxDisplayedValues?: number;
+    formatOverflowCount?: (hiddenCount: number) => string;
+    formatSelectedCount?: (selectedCount: number) => string;
+    formatMaxSelectedHint?: (maxSelectedValues: number) => string;
+    radius?: Radius;
+    unstyled?: boolean;
     disabled?: boolean;
+    required?: boolean;
+    className?: string;
+    wrapperClassName?: string;
+    values?: readonly string[];
+    defaultValues?: readonly string[];
+    onChange?: (values: readonly string[]) => void;
+    /**
+     * Fires with the final selection whenever the user is done editing:
+     * when the dropdown closes (Escape, outside click, focus leaving the
+     * wrapper), and when the selection is cleared from the trigger's X
+     * button while the dropdown is closed.
+     */
+    onDropdownClose?: (values: readonly string[]) => void;
+    id?: string;
 }
 
-export declare function RadioOptions({ options, orientation, value, defaultValue, onChange, name: nameProp, label, error, required, disabled, radius, unstyled, className, wrapperClassName, id, ...props }: Readonly<RadioOptionsProps>): JSX.Element;
+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[];
@@ -485,7 +577,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, ...props }: Readonly<SelectProps>): JSX.Element;
+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 interface SelectOption {
     value: string;
@@ -543,13 +635,14 @@ export declare function splitIntoHighlightSegments(
     	return segments;
 }
 
-export declare function Switch({ label, description, error, unstyled, className, wrapperClassName, checked, defaultChecked, onChange, id, ...props }: Readonly<SwitchProps>): JSX.Element;
+export declare function Switch({ label, description, error, unstyled, fullWidth, className, wrapperClassName, checked, defaultChecked, onChange, id, 'aria-describedby': callerDescribedBy, ...props }: Readonly<SwitchProps>): JSX.Element;
 
 export declare interface SwitchProps extends Omit<ComponentPropsWithRef<'input'>, 'type' | 'className'> {
     label?: string | ReactNode;
     description?: string | ReactNode;
     error?: string;
     unstyled?: boolean;
+    fullWidth?: boolean;
     className?: string;
     wrapperClassName?: string;
 }
@@ -561,21 +654,31 @@ export declare interface TabItem {
     icon?: string;
 }
 
-export declare function Tabs({ items, value, defaultIndex, radius, unstyled, className, tabListClassName, panelClassName, onChange, }: Readonly<TabsProps>): JSX.Element;
+export declare function Tabs({ items, value, defaultIndex, variant, size, radius, fullWidth, unstyled, animated, className, tabListClassName, panelClassName, onChange, }: Readonly<TabsProps>): JSX.Element;
 
 export declare interface TabsProps {
     items: TabItem[];
     value?: number;
     defaultIndex?: number;
+    variant?: TabsVariant;
+    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;
+    fullWidth?: boolean;
     unstyled?: boolean;
+    animated?: boolean;
     className?: string;
     tabListClassName?: string;
     panelClassName?: string;
     onChange?: (index: number) => void;
 }
 
-export declare function Textarea({ label, error, showCharCount, minLength, maxLength, radius, unstyled, className, wrapperClassName, value, defaultValue, onChange, id, ...props }: Readonly<TextareaProps>): JSX.Element;
+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 interface TextareaProps extends ComponentPropsWithRef<'textarea'> {
     label?: string | ReactNode;
@@ -591,11 +694,9 @@ export declare interface TextareaProps extends ComponentPropsWithRef<'textarea'>
 
 export declare type Theme = 'light' | 'dark' | 'system';
 
-declare type Theme_2 = 'light' | 'dark' | 'system';
-
 declare interface ThemeStore {
-    theme: Theme_2;
-    setTheme: (theme: Theme_2) => void;
+    theme: Theme;
+    setTheme: (theme: Theme) => void;
 }
 
 export declare function ThemeToggle({ isTransitionEnabled, transitionDuration, transitionEasing, size, radius, variant, getAriaLabel, }: Readonly<ThemeToggleProps>): JSX.Element;
@@ -607,9 +708,15 @@ export declare interface ThemeToggleProps {
     size?: 'sm' | 'md' | 'lg';
     radius?: Radius;
     variant?: ButtonVariant;
-    getAriaLabel?: (theme: Theme_2) => string;
+    getAriaLabel?: (theme: Theme) => string;
 }
 
+/**
+ * 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 type TooltipPosition = 'top' | 'bottom' | 'left' | 'right';