@baseline-ui/core 3.9.1 → 3.10.0

package/dist/index.d.ts

@@ -6240,17 +6240,18 @@ declare function getAbsolutePosition(element: HTMLElement, coordinates?: {
 
 /**
  * This function takes a list of [x, y] coordinates representing a stroke and
- * returns a SVG path string.
+ * returns a SVG path string. Returns an empty string for fewer than four
+ * points.
  *
  * @example
  *   ```ts
- *   const stroke = [[0, 0], [1, 1], [2, 2]];
+ *   const stroke = [[0, 0], [1, 1], [2, 2], [3, 3]];
  *   const path = getSvgPathFromStroke(stroke);
- *   // path === "M0,0Q0.5,0.5,1,1Q1.5,1.5,2,2Z"
+ *   // path === "M0.00,0.00 Q1.00,1.00 1.50,1.50 T2.50,2.50 Z"
  *   ```;
  *
  * @param stroke The stroke to convert to an SVG path
- * @param closed Wether to close the path
+ * @param closed Whether to close the path
  */
 declare function getSvgPathFromStroke(stroke: number[][], closed?: boolean): string;
 
@@ -6268,7 +6269,8 @@ declare function filterTruthyValues<T extends Record<string, unknown>>(obj: T):
 /**
  * This function converts a boolean or an object to a config object. If the
  * value is a boolean, the defaults will be returned. If the value is an object,
- * the defaults will be merged with the value.
+ * the defaults will be merged with the value; a key set to `undefined` keeps
+ * its default.
  *
  * @template T - A type that extends Record<string, unknown>.
  * @param {boolean | Partial<T>} value - The value to convert.
@@ -7612,9 +7614,16 @@ interface NumberInputProps extends StylingProps, Omit<AriaNumberFieldProps, "val
      * @default true
      */
     showStepper?: boolean;
-    /** The description to display below the input. */
+    /**
+     * The description to display below the input. Hidden while an
+     * `errorMessage` is shown.
+     */
     description?: string;
-    /** The error message to display when the input is in an error state. */
+    /**
+     * The error message to display below the input, in place of the
+     * `description`. Shown whenever it is set; it does not put the input in the
+     * error state, so set `isInvalid` for that.
+     */
     errorMessage?: string;
 }
 
@@ -7666,7 +7675,11 @@ interface SwitchProps extends Omit<AriaSwitchProps, "children" | "isRequired" |
     label?: React__default.ReactNode;
     /** Helper text shown below the label and announced as its accessible description. */
     description?: string;
-    /** The position of the label. */
+    /**
+     * The position of the label.
+     *
+     * @default "top"
+     */
     labelPosition?: "top" | "left";
     /** The status label to display next to the switch. */
     statusLabel?: {
@@ -7839,11 +7852,21 @@ interface SharedInputProps extends StylingProps, Pick<AriaTextFieldProps, "isRea
 }
 
 interface InputMessage {
-    /** The description to display below the input. */
+    /**
+     * The description to display below the input. Hidden while an `errorMessage`
+     * or `warningMessage` is shown.
+     */
     description?: string;
-    /** The error message to display when the input is in an error state. */
+    /**
+     * The error message to display below the input, in place of the `description`
+     * and `warningMessage`. Setting it also puts the input in the error state.
+     */
     errorMessage?: string;
-    /** The warning message to display when the input is in a warning state. */
+    /**
+     * The warning message to display below the input, in place of the
+     * `description`. An `errorMessage` takes precedence over it. `FileInput`
+     * shows it only while `validationState` is `"warning"`.
+     */
     warningMessage?: string;
 }
 interface TextInputBaseProps extends StylingProps, InputMessage, Pick<SharedInputProps, "validationState" | "variant" | "labelPosition"> {
@@ -7965,7 +7988,11 @@ declare const ProgressBar: React__default.ForwardRefExoticComponent<ProgressBarP
 declare const TextInput: React__default.ForwardRefExoticComponent<TextInputProps & React__default.RefAttributes<HTMLInputElement>>;
 
 interface ReactionProps extends Omit<AriaSwitchProps & ToggleProps, "validationState" | "isRequired" | "children" | "isInvalid" | "validationBehavior" | "validate" | "aria-errormessage" | "onClick" | "onPress" | "onPressStart" | "onPressEnd" | "onPressUp" | "onPressChange">, StylingProps {
-    /** The size of the reaction. */
+    /**
+     * The size of the reaction.
+     *
+     * @default "md"
+     */
     size?: "sm" | "md";
     /** The number of reactions. */
     count: number;
@@ -8025,7 +8052,11 @@ declare const ToggleButton: React__default.ForwardRefExoticComponent<ToggleButto
 type CalendarSize = "xs" | "sm";
 type CalendarHeaderVariant = "title" | "selectMonth" | "selectMonthAndYear";
 interface CalendarBaseProps {
-    /** The size of the calendar. */
+    /**
+     * The size of the calendar.
+     *
+     * @default "sm"
+     */
     size?: CalendarSize;
     /** Optional title displayed above the calendar (e.g. "Date"). Shows a calendar icon and separator. */
     title?: string;
@@ -8731,7 +8762,10 @@ interface InlineAlertProps extends StylingProps {
      */
     closeLabel?: string;
     /**
-     * The arrangement of the variable.
+     * How the title, description and action button are laid out: `single` keeps
+     * them on one row, `multi` and `compact` stack the title above the
+     * description, and `compact` also places the action button below the
+     * message.
      *
      * @default "single"
      * @typedef {"single" | "multi" | "compact"} Arrangement
@@ -8979,11 +9013,21 @@ interface SharedFileUploadProps extends StylingProps {
      * The accepted file types, passed through to the underlying
      * `<input type="file">` `accept` attribute — a comma-separated list of MIME
      * types and/or extensions (e.g. `"image/png,image/jpeg"` or `"image/*"`).
+     * Dropped, pasted and selected files are all checked against it; a file that
+     * does not match calls `onFileTypeError` and is not used. A file the browser
+     * reports no MIME type for matches any MIME token, so its name is only
+     * checked when `accept` lists extensions alone.
+     *
+     * @default "image/*"
      */
     accept?: string;
     /** The name of the input. */
     name?: string;
-    /** The callback function that is fired when the value changes. */
+    /**
+     * The `change` event of the file input, fired when the user picks a file in
+     * the file dialog. It does not fire for a drop, a paste or a clear; use
+     * `onValueChange` for every change of the image.
+     */
     onChange?: (event: React__default.ChangeEvent<HTMLInputElement>) => void;
     /**
      * The callback function that is fired when the value changes and the value is
@@ -9004,8 +9048,9 @@ interface ImageDropZoneProps extends SharedFileUploadProps, Omit<DropOptions, "r
     defaultImageSrc?: string | File;
     /**
      * The image to display. This will be used as the `src` attribute of the
-     * `<img>` element and will not be able to be changed from within the
-     * component. Basically, this makes the component controlled.
+     * `<img>` element and makes the component controlled: picking, dropping,
+     * pasting or clearing an image calls `onValueChange`, and the shown image
+     * changes only when you update `imageSrc`.
      */
     imageSrc?: string | File;
     /**
@@ -9025,7 +9070,11 @@ interface ImageDropZoneProps extends SharedFileUploadProps, Omit<DropOptions, "r
      * @default true
      */
     includeCheckeredBackground?: boolean;
-    /** Whether the component is inlined. */
+    /**
+     * Whether the component is inlined.
+     *
+     * @default true
+     */
     isInline?: boolean;
     /** The class name to apply to the picker button. */
     pickerButtonClassName?: string;
@@ -9182,10 +9231,10 @@ declare const RadioGroup: React__default.ForwardRefExoticComponent<RadioGroupPro
 
 interface MessageFormatProps {
     /**
-     * By default `<MessageFormat>` will render the formatted string into a
-     * `<React.Fragment>`. If you need to customize rendering, you can either wrap
-     * it with another React element (recommended), specify a different tagName
-     * (e.g., 'div')
+     * The element to render the formatted string into, e.g. `"div"` or `"span"`.
+     * By default it renders into a `<React.Fragment>`.
+     *
+     * @default React.Fragment
      */
     elementType?: React__default.ElementType | "div" | "span";
     /**
@@ -10571,12 +10620,14 @@ interface ImageGalleryProps extends StylingProps, Omit<UNSAFE_ListBoxProps, "ite
     /**
      * The width of the images.
      *
+     * @deprecated Use `imageDimensions` instead.
      * @default "sm"
      */
     imageWidth?: number | "sm" | "md";
     /**
      * The aspect ratio of the images.
      *
+     * @deprecated Use `imageDimensions` instead.
      * @default 3 / 4
      */
     aspectRatio?: number;
@@ -10608,7 +10659,7 @@ interface ImageGalleryProps extends StylingProps, Omit<UNSAFE_ListBoxProps, "ite
     /**
      * The dimensions of the image.
      *
-     * @default { width: imageWidth, aspectRatio }
+     * @default { width: "sm", aspectRatio: 3 / 4 }
      */
     imageDimensions?: Dimension | ((item: Item, options: {
         isSelected: boolean;
@@ -10998,7 +11049,10 @@ interface ColorSwatchPickerProps extends StylingProps, Pick<RadioGroupProps, "op
      * either is written, so `"#FF0000"` or `"red"` selects a `"#ff0000"` item.
      */
     value?: string;
-    /** A function that is called when the selected item changes. */
+    /**
+     * A function that is called when the selected item changes. It receives
+     * `undefined` when the user presses the selected swatch again to clear it.
+     */
     onChange?: (value?: string) => void;
     /** The default value of the picker. Matched to an item like `value`. */
     defaultValue?: string;
@@ -11017,7 +11071,7 @@ interface ColorSwatchPickerProps extends StylingProps, Pick<RadioGroupProps, "op
 
 declare const ColorSwatchPicker: React__default.ForwardRefExoticComponent<ColorSwatchPickerProps & React__default.RefAttributes<HTMLDivElement>>;
 
-declare const TimeField: React__default.ForwardRefExoticComponent<StylingProps & Omit<Omit<TimeFieldStateOptions<TimeValue>, "locale"> & AriaTimeFieldProps<TimeValue>, "validationState" | "isRequired" | "validate" | "isInvalid"> & Pick<SharedInputProps, "label" | "variant" | "validationState" | "labelPosition"> & InputMessage & React__default.RefAttributes<HTMLDivElement>>;
+declare const TimeField: React__default.ForwardRefExoticComponent<StylingProps & Omit<Omit<TimeFieldStateOptions<TimeValue>, "locale"> & AriaTimeFieldProps<TimeValue>, "validationState" | "isRequired" | "validate" | "isInvalid"> & Pick<SharedInputProps, "label" | "validationState" | "variant" | "labelPosition"> & InputMessage & React__default.RefAttributes<HTMLDivElement>>;
 
 type TimeFieldProps = StylingProps & Omit<Omit<TimeFieldStateOptions, "locale"> & AriaTimeFieldProps<TimeValue>, "validationState" | "isInvalid" | "isRequired" | "validate"> & Pick<SharedInputProps, "variant" | "labelPosition" | "validationState" | "label"> & InputMessage;
 
@@ -11248,7 +11302,11 @@ interface PanelProps extends StylingProps {
 interface PanelGroupProps extends StylingProps {
     /** Content comprising `Panel` and `PanelResizeHandle` */
     children: ReactNode;
-    /** Orientation of the layout */
+    /**
+     * Orientation of the layout
+     *
+     * @default "horizontal"
+     */
     direction?: "horizontal" | "vertical";
     /**
      * Called with a map of panel id to size (percentage) when group layout
@@ -11274,6 +11332,11 @@ interface ImperativePanelGroupHandle {
     setLayout?: (layout: Record<string, number>) => void;
 }
 interface ImperativePanelHandle {
+    /**
+     * Resizes the panel. A number is a size in pixels; pass a string with a
+     * unit, such as `"30%"`, for a percentage. This differs from the size props,
+     * where a number is a percentage.
+     */
     resize?: PanelImperativeHandle["resize"];
 }
 
@@ -11303,7 +11366,11 @@ declare const GlobalToastRegion: React__default.ForwardRefExoticComponent<Global
 interface FrameProviderProps extends BlockProps {
     /** The children of the FrameProvider */
     children: React__default.ReactNode;
-    /** The container inside which all the overlays should be confined to */
+    /**
+     * The container inside which all the overlays should be confined to. It must
+     * be positioned (not `position: static`). Without it, the document body is
+     * used and overlays are not contained.
+     */
     container?: HTMLElement | null;
     /** The container inside which all the portals should be confined to */
     portalContainer?: HTMLElement | null;
@@ -11369,7 +11436,7 @@ type DateFieldProps = StylingProps & Omit<Omit<DateFieldStateOptions, "locale">
     openCalendarLabel?: string;
 };
 
-declare const DateField: React__default.ForwardRefExoticComponent<StylingProps & Omit<Omit<DateFieldStateOptions<DateValue>, "locale"> & AriaDateFieldProps<DateValue>, "validationState" | "isRequired" | "validate" | "isInvalid" | "createCalendar"> & Pick<SharedInputProps, "label" | "variant" | "validationState" | "labelPosition"> & InputMessage & {
+declare const DateField: React__default.ForwardRefExoticComponent<StylingProps & Omit<Omit<DateFieldStateOptions<DateValue>, "locale"> & AriaDateFieldProps<DateValue>, "validationState" | "isRequired" | "validate" | "isInvalid" | "createCalendar"> & Pick<SharedInputProps, "label" | "validationState" | "variant" | "labelPosition"> & InputMessage & {
     pickerType?: DateFieldPickerType;
     openCalendarLabel?: string;
 } & React__default.RefAttributes<HTMLDivElement>>;
@@ -11768,8 +11835,10 @@ interface KbdProps extends Omit<StylingProps, "data-block-id" | "data-block-clas
      */
     children: string;
     /**
-     * Whether to use symbols for modifier keys (e.g., "⌘" instead of "Cmd"). Only
-     * applies when the shortcut contains modifiers like Ctrl, Alt, Shift.
+     * Whether to show modifier keys as symbols (e.g., "⌘" instead of "Cmd"). Only
+     * applies on macOS; other platforms show the shortcut as written. `Ctrl`,
+     * `Alt`, `Shift` and `Space` become symbols when another key follows them,
+     * `Enter` anywhere.
      *
      * @default false
      */
@@ -11839,7 +11908,10 @@ interface StepperItem {
     key: Key;
     /** Step title. Omit for indicator-only steps. */
     title?: string;
-    /** Step description. Only rendered when variant="expanded". */
+    /**
+     * Step description. Only rendered when variant="expanded" and the step has a
+     * `title`.
+     */
     description?: string;
     /** Disable this specific step (cannot be selected). */
     isDisabled?: boolean;
@@ -11948,7 +12020,7 @@ interface FileListItem {
     errorExplanation?: React__default.ReactNode;
     /**
      * Secondary text rendered under the name and read as the item's accessible
-     * description. Shown in the `expanded` and `grid` variants.
+     * description. Shown in every variant.
      */
     description?: string;
     /**
@@ -11972,8 +12044,8 @@ interface FileListProps extends AriaLabelingProps {
     /**
      * How the items are rendered.
      *
-     * - `compact` (default): divided rows with a file icon and name, for files
-     *   the user has added. The only variant that renders the remove button,
+     * - `compact` (default): divided rows with a file icon, name and
+     *   `description`, for files the user has added. The only variant that renders the remove button,
      *   the loading spinner and error messages.
      * - `expanded`: bordered cards with the name, `description` and `tag`.
      *   Past about five rows the list scrolls.
@@ -12609,13 +12681,17 @@ declare const defineMessages: <T extends Record<string, MessageDescriptor>>(mess
  *
  * @example
  *   ```tsx
- *   const targetRef = React.useRef<HTMLDivElement>(null);
+ *   function Example() {
+ *     // Hold the element in state: a ref's `current` is still null during the
+ *     // first render, so the hook would not observe until something re-renders.
+ *     const [target, setTarget] = React.useState<HTMLDivElement | null>(null);
  *
- *   useMutationObserver(targetRef.current, { attributes: true }, (mutations) => {
- *    console.log(mutations);
- *    // do something with the mutations
- *    // ...
- *   });
+ *     useMutationObserver(target, { attributes: true }, (mutations) => {
+ *       console.log(mutations);
+ *     });
+ *
+ *     return <div ref={setTarget} />;
+ *   }
  *   ```;
  *
  * @param target The element to observe for changes.