sherick-ui 2.5.0 → 2.6.0

package/dist/types/index.d.ts

@@ -1,9 +1,10 @@
 import { Accordion as Accordion$1 } from '@base-ui/react/accordion';
 import * as React from 'react';
-import React__default, { ReactNode, ButtonHTMLAttributes, ImgHTMLAttributes, HTMLAttributes, ComponentPropsWithoutRef, AnchorHTMLAttributes, ComponentProps, Ref, ReactElement, InputHTMLAttributes, ForwardRefExoticComponent, RefAttributes, MouseEventHandler, ComponentPropsWithRef, TextareaHTMLAttributes } from 'react';
+import React__default, { ReactNode, ButtonHTMLAttributes, ImgHTMLAttributes, HTMLAttributes, ComponentPropsWithoutRef, AnchorHTMLAttributes, ComponentProps, Ref, ClipboardEvent, ReactElement, InputHTMLAttributes, ForwardRefExoticComponent, RefAttributes, MouseEventHandler, ComponentPropsWithRef, TextareaHTMLAttributes } from 'react';
 import { Collapsible as Collapsible$1 } from '@base-ui/react/collapsible';
 import { AlertDialog as AlertDialog$1 } from '@base-ui/react/alert-dialog';
 import { Checkbox as Checkbox$1 } from '@base-ui/react/checkbox';
+import { CheckboxGroup as CheckboxGroup$1 } from '@base-ui/react/checkbox-group';
 import { Toggle } from '@base-ui/react/toggle';
 import { ToggleGroup as ToggleGroup$1 } from '@base-ui/react/toggle-group';
 import { Combobox as Combobox$1 } from '@base-ui/react/combobox';
@@ -12,6 +13,7 @@ import { Dialog as Dialog$1 } from '@base-ui/react/dialog';
 import { Popover as Popover$1 } from '@base-ui/react/popover';
 import { Select as Select$1 } from '@base-ui/react/select';
 import { Field as Field$1 } from '@base-ui/react/field';
+import { Form as Form$1 } from '@base-ui/react/form';
 import { Input as Input$1 } from '@base-ui/react/input';
 import { Menu as Menu$1 } from '@base-ui/react/menu';
 import { NumberField as NumberField$1 } from '@base-ui/react/number-field';
@@ -324,6 +326,55 @@ interface CheckboxProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "v
  */
 declare const Checkbox: React__default.ForwardRefExoticComponent<CheckboxProps & React__default.RefAttributes<HTMLButtonElement>>;
 
+type ChoiceAppearance = "default" | "surface";
+
+interface CheckboxGroupOption {
+    value: string;
+    label: ReactNode;
+    /** Supporting copy beneath the label, such as the domains a casino answers on. */
+    description?: ReactNode;
+    disabled?: boolean;
+}
+type CheckboxGroupChangeDetails = Parameters<NonNullable<CheckboxGroup$1.Props["onValueChange"]>>[1];
+interface CheckboxGroupProps extends Omit<ComponentProps<"div">, "onChange" | "defaultValue" | "children"> {
+    options: CheckboxGroupOption[];
+    /** Gives each choice its own selectable surface. The default keeps the compact, unfilled rows. */
+    appearance?: ChoiceAppearance;
+    /** The group's own label. Base names the group from it. */
+    label?: ReactNode;
+    /** Supporting copy beneath the group. */
+    description?: ReactNode;
+    /**
+     * The message shown while the group is invalid. Its presence is what makes the group invalid; omit
+     * it and the group shows what Base reports, including an error a `Form` returns for its `name`.
+     */
+    error?: ReactNode;
+    /** The ticked options' values. */
+    value?: string[];
+    defaultValue?: string[];
+    /** Base's own change callback, event details included. */
+    onValueChange?: (value: string[], eventDetails: CheckboxGroupChangeDetails) => void;
+    /** Identifies the group when a form is submitted: one entry per ticked option. */
+    name?: string;
+    /**
+     * At least one option must be ticked. It marks the label and is checked when a `Form` validates;
+     * the message is `requiredMessage`.
+     */
+    required?: boolean;
+    /** The message a required group shows when nothing is ticked. */
+    requiredMessage?: string;
+    disabled?: boolean;
+    readOnly?: boolean;
+    /** Styles the labelled group. */
+    className?: string;
+}
+/**
+ * Any number of choices out of a list — the options-API sibling of `RadioGroup`, with the same rows,
+ * the same opt-in `surface` row and the same labelled column. Base UI owns the value, the group
+ * semantics and the form participation; Sherick UI owns the rows and the marks.
+ */
+declare const CheckboxGroup: React__default.ForwardRefExoticComponent<Omit<CheckboxGroupProps, "ref"> & React__default.RefAttributes<HTMLDivElement>>;
+
 /** The parts every chip has, whichever of its two forms it takes. */
 interface ChipAnatomy {
     children: ReactNode;
@@ -402,23 +453,35 @@ interface ChipGroupProps extends Omit<ToggleGroup$1.Props<string>, "multiple" |
  */
 declare const ChipGroup: React__default.ForwardRefExoticComponent<Omit<ChipGroupProps, "ref"> & React__default.RefAttributes<HTMLDivElement>>;
 
+interface OptionGroup<Option> {
+    /** The heading the group is filed under. The primitive names the group from it. */
+    label: string;
+    options: Option[];
+}
+
 interface ComboboxOption {
     label: string;
     value: string;
     disabled?: boolean;
 }
+/** Options filed under one heading, such as channels under their category. */
+type ComboboxOptionGroup = OptionGroup<ComboboxOption>;
 type ComboboxRootProps = Combobox$1.Root.Props<ComboboxOption>;
 type ComboboxChangeDetails = Parameters<NonNullable<ComboboxRootProps["onValueChange"]>>[1];
-interface ComboboxProps {
-    options: ComboboxOption[];
-    /** The selected option's value, or `null` for no selection. */
-    value?: string | null;
-    defaultValue?: string | null;
+/**
+ * A change Base did not make: several entries pasted at once into a creatable combobox. It carries
+ * the paste event itself, and nothing to cancel — the entries are added in one step.
+ */
+interface ComboboxPasteDetails {
+    reason: "input-paste";
+    event: ClipboardEvent<HTMLInputElement>["nativeEvent"];
+}
+interface ComboboxCommonProps {
     /**
-     * The selected option's own `value`, so two equal options compare equal even when a caller
-     * rebuilds its options array. Base's event details are passed through unchanged.
+     * The options, in the order they read. Any of them may be filed under a heading by passing a group
+     * (`{ label, options }`) in its place; an option outside every group is listed where it stands.
      */
-    onValueChange?: (value: string | null, eventDetails: ComboboxChangeDetails) => void;
+    options: Array<ComboboxOption | ComboboxOptionGroup>;
     placeholder?: string;
     /** Shown in place of the list when the query matches no option. */
     emptyMessage?: ReactNode;
@@ -447,12 +510,48 @@ interface ComboboxProps {
     readOnly?: boolean;
     disabled?: boolean;
 }
+interface ComboboxSingleProps extends ComboboxCommonProps {
+    multiple?: false;
+    /** The selected option's value, or `null` for no selection. */
+    value?: string | null;
+    defaultValue?: string | null;
+    /**
+     * The selected option's own `value`, so two equal options compare equal even when a caller
+     * rebuilds its options array. Base's event details are passed through unchanged.
+     */
+    onValueChange?: (value: string | null, eventDetails: ComboboxChangeDetails) => void;
+    creatable?: never;
+    createLabel?: never;
+    chipsLabel?: never;
+}
+interface ComboboxMultipleProps extends ComboboxCommonProps {
+    /** Holds any number of options, each shown as a removable chip inside the field. */
+    multiple: true;
+    /** The selected options' values, in the order they were chosen. */
+    value?: string[];
+    defaultValue?: string[];
+    /**
+     * The selected options' own values. Base's event details are passed through unchanged; a
+     * multi-line paste into a creatable field reports `{ reason: "input-paste" }` instead.
+     */
+    onValueChange?: (value: string[], eventDetails: ComboboxChangeDetails | ComboboxPasteDetails) => void;
+    /**
+     * Accepts entries that are not among the options: the typed text is offered as an "Add" row, and
+     * pasting several lines adds one entry per line. A created entry's value is its own text.
+     */
+    creatable?: boolean;
+    /** The "Add" row's copy for the current query. */
+    createLabel?: (query: string) => ReactNode;
+    /** The accessible name of the chip row. */
+    chipsLabel?: string;
+}
+type ComboboxProps = ComboboxSingleProps | ComboboxMultipleProps;
 /**
- * A text field that filters a list of options and selects one of them. It is the searchable
- * sibling of `Select`: the same option shape, the same value contract and the same box, with an
- * input instead of a trigger. Base UI owns filtering, the listbox semantics, keyboard
- * interaction, the anchored popup and the hidden form input; Sherick UI owns the field, the row
- * treatment and the tone of the selected option.
+ * A text field that filters a list of options and selects one of them, or several. It is the
+ * searchable sibling of `Select`: the same option shape, the same value contract and the same box,
+ * with an input instead of a trigger. Base UI owns filtering, the listbox semantics, keyboard
+ * interaction, chip navigation and removal, the anchored popup and the hidden form inputs; Sherick UI
+ * owns the field, the row treatment, the chips and the tone of the selected option.
  *
  * Filtering is Base's and it is local — an application that needs remote results owns the
  * fetching, the debounce and the loading state around this control.
@@ -772,10 +871,16 @@ interface SelectOption {
     value: string;
     disabled?: boolean;
 }
+/** Options filed under one heading, such as channels under their category. */
+type SelectOptionGroup = OptionGroup<SelectOption>;
 type SelectRootProps = Select$1.Root.Props<string>;
 type SelectChangeDetails = Parameters<NonNullable<SelectRootProps["onValueChange"]>>[1];
 interface SelectProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "value" | "defaultValue"> {
-    options: SelectOption[];
+    /**
+     * The options, in the order they read. Any of them may be filed under a heading by passing a group
+     * (`{ label, options }`) in its place; an option outside every group is listed where it stands.
+     */
+    options: Array<SelectOption | SelectOptionGroup>;
     variant?: Variant;
     value?: string | null;
     defaultValue?: string | null;
@@ -882,6 +987,32 @@ interface FileUploadProps extends Omit<HTMLAttributes<HTMLDivElement>, "children
 }
 declare const FileUpload: React__default.ForwardRefExoticComponent<FileUploadProps & React__default.RefAttributes<HTMLInputElement>>;
 
+/** Messages keyed by each field's `name`: one message, or several. */
+type FormErrors = Record<string, string | string[]>;
+interface FormProps extends Omit<ComponentProps<typeof Form$1>, "className" | "render" | "errors" | "children" | "ref"> {
+    /**
+     * Errors returned from outside the form — typically a server's answer to a submission — keyed by
+     * each field's `name`. Each field shows its own message, the form moves focus to the first field
+     * that has one, and a field's entry clears as soon as its value changes.
+     */
+    errors?: FormErrors;
+    /** Styles the form's own column. The fields inside it style themselves. */
+    className?: string;
+    children?: ReactNode;
+}
+/**
+ * A form whose fields report what is wrong where it is wrong. On submit, Base UI validates every
+ * field it holds, keeps the submission from leaving while any is invalid and moves focus to the
+ * first invalid field in document order, so a submit button at the bottom of a long form never
+ * answers with nothing. The same happens when `errors` arrive after a submission.
+ *
+ * Every Sherick field takes part through its `name`: `Input`, `Textarea`, `RadioGroup` and
+ * `CheckboxGroup` carry their own; `Select`, `Combobox`, `NumberField`, `Checkbox`, `Switch` and
+ * `Slider` take part inside a `Field` given the `name`. Base UI owns validation, the errors map and
+ * the focus move; Sherick UI owns only the column the fields stand in.
+ */
+declare const Form: React__default.ForwardRefExoticComponent<FormProps & React__default.RefAttributes<HTMLFormElement>>;
+
 type IconButtonAppearance = "tonal" | "ghost" | "acrylic";
 interface IconButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
     variant?: Variant;
@@ -891,7 +1022,7 @@ interface IconButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
 }
 declare const IconButton: React__default.ForwardRefExoticComponent<IconButtonProps & React__default.RefAttributes<HTMLButtonElement>>;
 
-interface InputProps extends InputHTMLAttributes<HTMLInputElement> {
+interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "prefix"> {
     label?: ReactNode;
     description?: ReactNode;
     error?: boolean;
@@ -899,6 +1030,13 @@ interface InputProps extends InputHTMLAttributes<HTMLInputElement> {
     inputClassName?: string;
     /** Base's value-change callback, event details included. */
     onValueChange?: Input$1.Props["onValueChange"];
+    /**
+     * Text or a mark at the start of the field, such as `€` or `https://`. It is presentation only and
+     * hidden from assistive technology, so the label must carry whatever the reader needs from it.
+     */
+    prefix?: ReactNode;
+    /** Text or a mark at the end of the field, such as `tickets` or `.discord.gg`. Presentation only. */
+    suffix?: ReactNode;
 }
 declare const Input: React__default.ForwardRefExoticComponent<InputProps & React__default.RefAttributes<HTMLInputElement>>;
 
@@ -1084,7 +1222,7 @@ interface NavItemProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
 }
 declare const NavItem: ({ children, icon, className, href, active, ...props }: NavItemProps) => React__default.JSX.Element;
 
-interface NumberFieldProps extends Omit<ComponentProps<"input">, "value" | "defaultValue" | "onChange" | "min" | "max" | "step" | "type" | "size" | "ref"> {
+interface NumberFieldProps extends Omit<ComponentProps<"input">, "value" | "defaultValue" | "onChange" | "min" | "max" | "step" | "type" | "size" | "ref" | "prefix"> {
     value?: number | null;
     defaultValue?: number;
     onValueChange?: NumberField$1.Root.Props["onValueChange"];
@@ -1093,6 +1231,23 @@ interface NumberFieldProps extends Omit<ComponentProps<"input">, "value" | "defa
     min?: number;
     max?: number;
     step?: number;
+    /**
+     * How the value is written: Base's `Intl.NumberFormatOptions`, passed through unchanged —
+     * `{ style: "currency", currency: "EUR" }`, `{ minimumFractionDigits: 2 }`, `{ style: "percent" }`.
+     */
+    format?: NumberField$1.Root.Props["format"];
+    /** The locale the value is parsed and written in. Defaults to the runtime's own. */
+    locale?: NumberField$1.Root.Props["locale"];
+    /**
+     * A unit written before the value, such as `€`. It is presentation only and hidden from assistive
+     * technology, so the field's label must name the unit as well ("Price (€)").
+     */
+    prefix?: ReactNode;
+    /**
+     * A unit written after the value, such as `×` or `tickets`. Presentation only, like `prefix`:
+     * name the unit in the label as well.
+     */
+    suffix?: ReactNode;
     disabled?: boolean;
     readOnly?: boolean;
     required?: boolean;
@@ -1209,15 +1364,24 @@ declare const Progress: React__default.ForwardRefExoticComponent<Omit<ProgressPr
 interface RadioGroupOption {
     value: string;
     label: ReactNode;
+    /** Supporting copy beneath the label. It describes the choice rather than naming it. */
+    description?: ReactNode;
     disabled?: boolean;
 }
 interface RadioGroupProps extends Omit<ComponentProps<"div">, "onChange" | "defaultValue" | "children"> {
     options: RadioGroupOption[];
     /** Gives each choice its own selectable surface. The default keeps the compact, unfilled rows. */
-    appearance?: "default" | "surface";
+    appearance?: ChoiceAppearance;
     /** The group's own label. Naming the group is the group's job, not a field's: an
      *  enclosing `Field` names one control, while every option here is its own control. */
     label?: ReactNode;
+    /** Supporting copy beneath the group. */
+    description?: ReactNode;
+    /**
+     * The message shown while the group is invalid. Its presence is what makes the group invalid; omit
+     * it and the group shows what Base reports, including an error a `Form` returns for its `name`.
+     */
+    error?: ReactNode;
     value?: string;
     defaultValue?: string;
     onValueChange?: RadioGroup$1.Props<string>["onValueChange"];
@@ -1726,5 +1890,5 @@ interface DirectionProviderProps {
 /** Declares writing direction to the interaction and positioning primitives, including portals. */
 declare const DirectionProvider: ({ direction, children }: DirectionProviderProps) => React__default.JSX.Element;
 
-export { Accordion, Alert, AlertDialog, Avatar, Badge, Breadcrumb, Button, Calendar, Card, Checkbox, Chip, ChipGroup, Collapsible, Combobox, Command, CommandPalette, DatePicker, DateRangePicker, DateTimePicker, Dialog, DirectionProvider, Divider, Drawer, Field, FileUpload, IconButton, Input, Media, Menu, NavGroup, NavItem, NumberField, Pagination, Popover, Progress, RadioGroup, Search, SegmentedControl, Select, Skeleton, Slider, Spinner, Stepper, Switch, Table, Tabs, Textarea, ToastProvider, ToastViewport, ToggleGroup, Tooltip, TreeView, createToastManager, useToast };
-export type { AccordionHeadingLevel, AccordionItemProps, AccordionPanelProps, AccordionProps, AccordionTriggerProps, AlertDialogProps, AlertProps, AvatarProps, BadgeProps, BreadcrumbItem, BreadcrumbProps, ButtonAppearance, ButtonProps, ButtonSize, CalendarDate, CalendarDateTime, CalendarLabels, CalendarProps, CardProps, CheckboxProps, ChipGroupProps, ChipProps, CollapsiblePanelProps, CollapsibleProps, CollapsibleTriggerProps, ComboboxOption, ComboboxProps, CommandItem, CommandPaletteProps, CommandProps, DatePickerProps, DateRange, DateRangePickerProps, DateTimePickerLabels, DateTimePickerProps, DialogContentProps, DialogDescriptionProps, DialogFooterProps, DialogHeaderProps, DialogProps, DirectionProviderProps, DividerProps, DividerWeight, DrawerContentProps, DrawerDescriptionProps, DrawerFooterProps, DrawerHeaderProps, DrawerProps, DrawerSide, DrawerTriggerProps, FieldProps, FileRejection, FileUploadProps, IconButtonAppearance, IconButtonProps, InputProps, MediaImageProps, MediaVideoProps, MenuContentProps, MenuItemProps, MenuProps, MenuSeparatorProps, MenuTriggerProps, NavGroupHeadingLevel, NavGroupItem, NavGroupProps, NavItemProps, NumberFieldProps, OverlayAlign, OverlaySide, PaginationProps, PopoverContentProps, PopoverProps, PopoverTriggerProps, ProgressProps, RadioGroupOption, RadioGroupProps, SearchProps, SegmentedControlOption, SegmentedControlProps, SelectOption, SelectProps, SkeletonProps, SliderProps, SpinnerProps, StepperItem, StepperProps, SwitchProps, Tab, TableColumn, TableProps, TabsProps, TextareaProps, ToastActionOptions, ToastManager, ToastOptions, ToastPosition, ToastPromiseOptions, ToastProviderProps, ToastType, ToastUpdateOptions, ToastViewportProps, ToggleGroupItemProps, ToggleGroupProps, TooltipProps, TreeViewItem, TreeViewProps, Variant };
+export { Accordion, Alert, AlertDialog, Avatar, Badge, Breadcrumb, Button, Calendar, Card, Checkbox, CheckboxGroup, Chip, ChipGroup, Collapsible, Combobox, Command, CommandPalette, DatePicker, DateRangePicker, DateTimePicker, Dialog, DirectionProvider, Divider, Drawer, Field, FileUpload, Form, IconButton, Input, Media, Menu, NavGroup, NavItem, NumberField, Pagination, Popover, Progress, RadioGroup, Search, SegmentedControl, Select, Skeleton, Slider, Spinner, Stepper, Switch, Table, Tabs, Textarea, ToastProvider, ToastViewport, ToggleGroup, Tooltip, TreeView, createToastManager, useToast };
+export type { AccordionHeadingLevel, AccordionItemProps, AccordionPanelProps, AccordionProps, AccordionTriggerProps, AlertDialogProps, AlertProps, AvatarProps, BadgeProps, BreadcrumbItem, BreadcrumbProps, ButtonAppearance, ButtonProps, ButtonSize, CalendarDate, CalendarDateTime, CalendarLabels, CalendarProps, CardProps, CheckboxGroupOption, CheckboxGroupProps, CheckboxProps, ChipGroupProps, ChipProps, CollapsiblePanelProps, CollapsibleProps, CollapsibleTriggerProps, ComboboxMultipleProps, ComboboxOption, ComboboxOptionGroup, ComboboxPasteDetails, ComboboxProps, ComboboxSingleProps, CommandItem, CommandPaletteProps, CommandProps, DatePickerProps, DateRange, DateRangePickerProps, DateTimePickerLabels, DateTimePickerProps, DialogContentProps, DialogDescriptionProps, DialogFooterProps, DialogHeaderProps, DialogProps, DirectionProviderProps, DividerProps, DividerWeight, DrawerContentProps, DrawerDescriptionProps, DrawerFooterProps, DrawerHeaderProps, DrawerProps, DrawerSide, DrawerTriggerProps, FieldProps, FileRejection, FileUploadProps, FormErrors, FormProps, IconButtonAppearance, IconButtonProps, InputProps, MediaImageProps, MediaVideoProps, MenuContentProps, MenuItemProps, MenuProps, MenuSeparatorProps, MenuTriggerProps, NavGroupHeadingLevel, NavGroupItem, NavGroupProps, NavItemProps, NumberFieldProps, OverlayAlign, OverlaySide, PaginationProps, PopoverContentProps, PopoverProps, PopoverTriggerProps, ProgressProps, RadioGroupOption, RadioGroupProps, SearchProps, SegmentedControlOption, SegmentedControlProps, SelectOption, SelectOptionGroup, SelectProps, SkeletonProps, SliderProps, SpinnerProps, StepperItem, StepperProps, SwitchProps, Tab, TableColumn, TableProps, TabsProps, TextareaProps, ToastActionOptions, ToastManager, ToastOptions, ToastPosition, ToastPromiseOptions, ToastProviderProps, ToastType, ToastUpdateOptions, ToastViewportProps, ToggleGroupItemProps, ToggleGroupProps, TooltipProps, TreeViewItem, TreeViewProps, Variant };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sherick-ui",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "A reusable React component library inspired by Material 3 Expressive.",
   "repository": {
     "type": "git",