@sanity/ui 5.0.0-alpha.1 → 5.0.0-alpha.10

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import type { ComponentProps } from "react";
+import { ComponentProps } from "react";
 import { ComponentPropsWithRef } from "react";
 import { ElementType } from "react";
 import { JSX } from "react";
@@ -16,6 +16,31 @@ declare const ALIGN_ITEMS: readonly [
 /** @public */
 export declare type AlignItems = (typeof ALIGN_ITEMS)[number];
 
+/** @public */
+export declare function Badge<T extends ElementType = "span">({
+  tone,
+  ...props
+}: BadgeProps<T> &
+  Omit<ComponentPropsWithRef<T>, keyof BadgeProps<T>>): JSX.Element;
+
+/** @public */
+export declare interface BadgeProps<
+  T extends React.ElementType = "span",
+> extends ToneProps {
+  /**
+   * HTML element to render.
+   */
+  as?: T;
+  /**
+   * Shows an icon in the start position (left side in left-to-right languages).
+   */
+  iconStart?: React.ElementType | React.ReactNode;
+  /**
+   * Sets Badge's text label. Use instead of children unless you have a special use case.
+   */
+  text?: string;
+}
+
 declare type BorderProps = {
   /** CSS **border** property */
   border?: Responsive<boolean>;
@@ -34,6 +59,8 @@ declare type BorderProps = {
 /** @public */
 export declare function Box<T extends ElementType = "div">({
   display,
+  minHeight,
+  minWidth,
   ...props
 }: BoxProps<T> &
   Omit<ComponentPropsWithRef<T>, keyof BoxProps<T>>): JSX.Element;
@@ -42,9 +69,14 @@ export declare function Box<T extends ElementType = "div">({
 export declare interface BoxProps<
   T extends React.ElementType = "div",
 > extends LayoutProps {
-  /** Element to render */
+  /**
+   * HTML element or component to render.
+   */
   as?: T;
-  /** CSS **display** property */
+  /**
+   * CSS `display` property.
+   * @remarks Does not include `'flex'` or `'grid'`. Use the Flex or Grid components for those.
+   */
   display?: Responsive<DisplayBlock>;
 }
 
@@ -69,23 +101,41 @@ declare type ButtonLevel = (typeof BUTTON_LEVEL)[number];
 
 /** @public */
 export declare interface ButtonProps<T extends React.ElementType = "button"> {
-  /** Element to render */
+  /**
+   * HTML element to render.
+   */
   as?: InteractiveAs<T>;
-  /** Composite prop for setting padding and gap */
+  /**
+   * Sets padding and gap together to specify size.
+   */
   density?: ButtonDensity;
-  /** Set CSS **width** property to 100% */
+  /**
+   * Sets Button to fill the width of its container.
+   */
   fullWidth?: Responsive<boolean>;
-  /** Starting icon */
+  /**
+   * Shows an icon in the start position (left side in left-to-right languages).
+   */
   iconStart?: React.ElementType | React.ReactNode;
-  /** Ending icon */
+  /**
+   * Shows an icon in the end position (right side in left-to-right languages).
+   */
   iconEnd?: React.ElementType | React.ReactNode;
-  /** Button level */
+  /**
+   * Sets the importance of Button's action.
+   */
   level?: ButtonLevel;
-  /** Loading state */
+  /**
+   * Places Button into a loading state.
+   */
   loading?: boolean;
-  /** Button text */
+  /**
+   * Sets Button's text label.
+   */
   text?: string;
-  /** Button tone */
+  /**
+   * Sets Button's semantic meaning and related color.
+   */
   tone?: ButtonTone;
 }
 
@@ -102,9 +152,13 @@ export declare function Card<T extends ElementType = "div">({
 /** @public */
 export declare interface CardProps<T extends React.ElementType = "div">
   extends MarginProps, ToneProps {
-  /** Element to render */
+  /**
+   * HTML element or component to render.
+   */
   as?: T;
-  /** Composite prop for setting padding and border radius */
+  /**
+   * Sets padding, gap, and border-radius together to specify size. This prop is used in place of separate `padding`, `gap`, and `border-radius` props.
+   */
   density?: Responsive<Density>;
 }
 
@@ -114,11 +168,19 @@ export declare function Checkbox(props: CheckboxProps): JSX.Element;
 /** @beta */
 export declare interface CheckboxProps
   extends React.ComponentProps<"input">, MarginProps {
-  /** Error state */
+  /**
+   * Applies error styling to the checkbox mark.
+   * @remarks Use when form validation fails. Pair with a visible error message. The prop is visual only.
+   */
   error?: boolean;
-  /** Indeterminate state */
+  /**
+   * Renders the "mixed state" mark (a horizontal line).
+   * @remarks Use when the checkbox controls a group with some-but-not-all children checked.
+   */
   indeterminate?: boolean;
-  /** Input label */
+  /**
+   * Visible label next to the checkbox.
+   */
   label: React.ReactNode;
 }
 
@@ -138,11 +200,18 @@ export declare interface CodeProps<T extends CodeTag = "pre"> extends Omit<
   TypographyProps,
   "align" | "truncate" | "tone"
 > {
-  /** Element to render */
+  /**
+   * HTML element or component to render.
+   * @remarks The defined element wraps an inner `<code>` tag.
+   */
   as?: T;
-  /** Refractor language for syntax highlighting */
+  /**
+   * Refractor language for syntax highlighting.
+   */
   language?: string;
-  /** CSS **font-size** property */
+  /**
+   * Sets font size.
+   */
   size?: Responsive<CodeSize>;
 }
 
@@ -164,9 +233,13 @@ declare const CONTAINER_SIZE: readonly [0, 1, 2, 3, 4, 5];
 export declare interface ContainerProps<
   T extends React.ElementType = "div",
 > extends LayoutProps {
-  /** Element to render */
+  /**
+   * HTML element or component to render.
+   */
   as?: T;
-  /** CSS **max-width** property */
+  /**
+   * Maximum width of the container.
+   */
   size?: Responsive<ContainerSize>;
 }
 
@@ -178,6 +251,58 @@ declare const DENSITY: readonly ["compact", "regular", "loose"];
 /** @public */
 export declare type Density = (typeof DENSITY)[number];
 
+/**
+ * @beta
+ *
+ * Renders a modal dialog element — should not be used for nonmodal dialogs.
+ * Modal dialogs make their containing documents inert, and render on the topmost
+ * layer within that containing document; they must be dimissed before the containing
+ * document and its contents become unblocked. They also trap focus within the bounds
+ * of the dialog element and its descendants.
+ *
+ * For more on dialogs and modality, refer to the HTML specification for the dialog element:
+ * https://html.spec.whatwg.org/dev/interactive-elements.html#the-dialog-element
+ */
+export declare const Dialog: typeof DialogRoot;
+
+declare function DialogContent(props: ComponentProps<"div">): JSX.Element;
+
+declare function DialogFooter(props: ComponentProps<"div">): JSX.Element;
+
+/** @beta */
+export declare interface DialogProps extends Omit<
+  React.ComponentProps<"dialog">,
+  "open"
+> {
+  /**
+   * Text for the dialog heading.
+   * @remarks Recommended for accessibility. The component sets `aria-labelledby` to the heading when you give this prop.
+   */
+  header?: string;
+  /**
+   * A function to call alongside the native `close` event.
+   * @remarks Use it to set `open` back to `false`. It runs for every close cause: the Escape key, a backdrop click, the close button, or a programmatic close.
+   */
+  onClose: React.ReactEventHandler<HTMLDialogElement>;
+  /**
+   * Toggles the dialog's open state.
+   * @remarks `true` calls `showModal()` on the element. `false` calls `close()`.
+   */
+  open?: boolean;
+  /** Sets the max width of the dialog */
+  size?: Responsive<ContainerSize>;
+  /** CSS length value used to set the Dialog’s distance from the top of the viewport; Dialog is centered if not provided */
+  topAnchor?: string;
+}
+
+declare function DialogRoot({ open, size, ...props }: DialogProps): JSX.Element;
+
+declare namespace DialogRoot {
+  var displayName: string;
+  var Content: typeof DialogContent;
+  var Footer: typeof DialogFooter;
+}
+
 declare const DISPLAY_BLOCK: readonly ["block", "inline-block", "none"];
 
 declare const DISPLAY_FLEX: readonly ["flex", "inline-flex", "none"];
@@ -214,9 +339,13 @@ declare const EYEBROW_SIZE: readonly [0, 1, 2, 3, 4];
 export declare interface EyebrowProps<
   T extends React.ElementType = "span",
 > extends TypographyProps {
-  /** Element to render */
+  /**
+   * HTML element to render.
+   */
   as?: T;
-  /** CSS **font-size** property */
+  /**
+   * Sets font size. Uses the same scale as Label.
+   */
   size?: Responsive<EyebrowSize>;
 }
 
@@ -226,6 +355,8 @@ export declare type EyebrowSize = (typeof EYEBROW_SIZE)[number];
 /** @public */
 export declare function Flex<T extends ElementType = "div">({
   display,
+  minHeight,
+  minWidth,
   ...props
 }: FlexProps<T> &
   Omit<ComponentPropsWithRef<T>, keyof FlexProps<T>>): JSX.Element;
@@ -266,9 +397,13 @@ export declare type FlexParentProps = {
 /** @public */
 export declare interface FlexProps<T extends React.ElementType = "div">
   extends FlexParentProps, GapProps, LayoutProps {
-  /** Element to render */
+  /**
+   * HTML element or component to render.
+   */
   as?: T;
-  /** CSS **display** property */
+  /**
+   * CSS `display` property.
+   */
   display?: Responsive<DisplayFlex>;
 }
 
@@ -293,6 +428,8 @@ export declare type GapProps = {
 /** @public */
 export declare function Grid<T extends ElementType = "div">({
   display,
+  minHeight,
+  minWidth,
   ...props
 }: GridProps<T> &
   Omit<ComponentPropsWithRef<T>, keyof GridProps<T>>): JSX.Element;
@@ -340,9 +477,13 @@ export declare type GridParentProps = {
 /** @public */
 export declare interface GridProps<T extends React.ElementType = "div">
   extends GridParentProps, GapProps, LayoutProps {
-  /** Element to render */
+  /**
+   * HTML element or component to render.
+   */
   as?: T;
-  /** CSS **display** property */
+  /**
+   * CSS `display` property.
+   */
   display?: Responsive<DisplayGrid>;
 }
 
@@ -360,9 +501,15 @@ declare const HEADING_TAG: readonly ["h1", "h2", "h3", "h4", "h5", "h6"];
 
 /** @public */
 export declare interface HeadingProps extends TypographyProps {
-  /** Element to render */
+  /**
+   * Semantic heading element to render.
+   * @remarks Always set this explicitly.
+   */
   as?: HeadingTag;
-  /** CSS **font-size** property */
+  /**
+   * Sets font size.
+   * @remarks Independent of `as`.
+   */
   size?: Responsive<HeadingSize>;
 }
 
@@ -389,7 +536,9 @@ export declare function HStack<T extends ElementType = "div">(
 export declare interface HStackProps<
   T extends React.ElementType = "div",
 > extends Pick<GapProps, "gap"> {
-  /** Element to render */
+  /**
+   * HTML element or component to render.
+   */
   as?: T;
 }
 
@@ -411,9 +560,14 @@ export declare interface IconButtonProps<
   ButtonProps<T>,
   "as" | "density" | "level" | "loading" | "tone"
 > {
-  /** Button label */
+  /**
+   * Accessible name for the button.
+   * @remarks Because IconButtons have no visible text, this is required.
+   */
   "aria-label": string;
-  /** Icon */
+  /**
+   * Icon to render.
+   */
   icon: React_2.ComponentType<SVGProps<SVGSVGElement>>;
 }
 
@@ -424,9 +578,13 @@ export declare interface IconProps
     Pick<TypographyProps, "muted">,
     MarginProps,
     ToneProps {
-  /** Icon to render */
+  /**
+   * The icon component to render.
+   */
   icon: React.ComponentType<SVGProps<SVGSVGElement>>;
-  /** CSS **font-size** property */
+  /**
+   * Sets icon size.
+   */
   size?: Responsive<IconSize>;
 }
 
@@ -444,9 +602,13 @@ export declare function Indicator<T extends ElementType = "span">({
 export declare interface IndicatorProps<
   T extends React.ElementType = "span",
 > extends ToneProps {
-  /** Element to render */
+  /**
+   * HTML element to render.
+   */
   as?: T;
-  /** Label for aria-label attribute */
+  /**
+   * Accessible label.
+   */
   label?: string;
 }
 
@@ -460,7 +622,9 @@ export declare function IndicatorStack<T extends ElementType = "div">(
 export declare interface IndicatorStackProps<
   T extends React.ElementType = "div",
 > {
-  /** Element to render */
+  /**
+   * HTML element to render.
+   */
   as?: T;
 }
 
@@ -475,9 +639,13 @@ export declare function Inline<T extends ElementType = "div">(
 export declare interface InlineProps<
   T extends React.ElementType = "div",
 > extends PaddingProps {
-  /** Element to render */
+  /**
+   * HTML element or component to render.
+   */
   as?: T;
-  /** CSS **gap** property */
+  /**
+   * Space between children.
+   */
   gap?: Responsive<SpaceInherit>;
 }
 
@@ -506,8 +674,14 @@ export declare function Label(props: LabelProps): JSX.Element;
 /** @beta */
 export declare interface LabelProps
   extends React.ComponentProps<"label">, MarginProps {
-  /** Element to render */
+  /**
+   * Renders the label in a muted color.
+   */
   disabled?: boolean;
+  /**
+   * Renders the label in the error color.
+   * @remarks Use when the linked input has a validation error.
+   */
   error?: boolean;
 }
 
@@ -532,12 +706,12 @@ export declare function Link({ underlined, ...props }: LinkProps): JSX.Element;
 
 /** @beta */
 export declare interface LinkProps extends React.ComponentProps<"a"> {
-  /** If true, sets `target="_blank"` and `rel="noopener noreferrer"` */
+  /**
+   * Sets the link to `target="_blank"` and `rel="noopener noreferrer"`.
+   */
   openInNewTab?: boolean;
   /**
-   * If true, sets `text-decoration: underline`
-   *
-   * @defaultValue true
+   * Underlines the link.
    */
   underlined?: boolean;
 }
@@ -557,9 +731,13 @@ declare function ListButtonItem<T extends ElementType = "button">({
 export declare interface ListButtonItemProps<
   T extends React_2.ElementType = "button",
 > extends ListItemProps {
-  /** Element to render */
+  /**
+   * Element or component to render for the press target.
+   */
   as?: InteractiveAs<T>;
-  /** Selected state */
+  /**
+   * Marks the row as the current selection.
+   */
   selected?: boolean;
 }
 
@@ -569,11 +747,17 @@ declare function ListItemImage(props: ComponentProps<"img">): JSX.Element;
 
 /** @beta */
 export declare interface ListItemProps extends React_2.ComponentProps<"li"> {
-  /** Composite prop for setting padding and gap */
+  /**
+   * Sets horizontal padding, gap, and minimum row height together.
+   */
   density?: Responsive<Density>;
-  /** Starting slot */
+  /**
+   * Slot at the left edge of the row.
+   */
   start?: React_2.ReactNode;
-  /** Ending slot */
+  /**
+   * Slot at the right edge of the row.
+   */
   end?: React_2.ReactNode;
 }
 
@@ -586,11 +770,17 @@ declare function ListItemText<T extends ElementType = "div">(
 export declare interface ListItemTextProps<
   T extends React_2.ElementType = "div",
 > {
-  /** Element to render */
+  /**
+   * HTML element to render.
+   */
   as?: T;
-  /** Title text */
+  /**
+   * Main label.
+   */
   title?: React_2.ReactNode;
-  /** Subtitle text */
+  /**
+   * Text below the title.
+   */
   subtitle?: React_2.ReactNode;
 }
 
@@ -599,7 +789,9 @@ export declare interface ListProps<T extends ListTag = "ul"> extends Pick<
   GapProps,
   "gap"
 > {
-  /** Element to render */
+  /**
+   * HTML element to render.
+   */
   as?: T;
 }
 
@@ -697,6 +889,43 @@ export declare type PlacementProps = {
   placement?: Placement;
 };
 
+/** @beta */
+export declare const Popover: typeof PopoverRoot & {
+  forwardsTriggerProps: boolean;
+};
+
+/** @beta */
+export declare interface PopoverProps
+  extends
+    Omit<React.ComponentProps<"div">, "children" | "content">,
+    PlacementProps {
+  /**
+   * Shared anchor identifier.
+   * @remarks Set the same value on a Tooltip and a Popover to point both at one trigger.
+   */
+  anchorName?: React.ReactNode;
+  /**
+   * The trigger element.
+   * @remarks Popover clones it and attaches the `popovertarget` attribute that opens the floating layer.
+   */
+  children: React.ReactElement<Record<string, unknown>>;
+  /**
+   * The floating content.
+   */
+  content?: React.ReactNode;
+  /**
+   * Renders the content into `document.body` through a React portal instead of inline.
+   */
+  portal?: boolean;
+}
+
+declare function PopoverRoot({
+  placement,
+  ...props
+}: PopoverProps & {
+  triggerProps?: Record<string, unknown>;
+}): JSX.Element;
+
 declare const POSITION: readonly [
   "absolute",
   "fixed",
@@ -733,7 +962,9 @@ export declare function PressArea<T extends ElementType = "button">(
 export declare interface PressAreaProps<
   T extends React.ElementType = "button",
 > {
-  /** Element to render */
+  /**
+   * Element or component to render.
+   */
   as?: InteractiveAs<T>;
 }
 
@@ -743,9 +974,14 @@ export declare function Radio(props: RadioProps): JSX.Element;
 /** @beta */
 export declare interface RadioProps
   extends React.ComponentProps<"input">, MarginProps {
-  /** Error state */
+  /**
+   * Applies error styling to the radio mark.
+   * @remarks Use when form validation fails. Pair with a visible error message. The prop is visual only.
+   */
   error?: boolean;
-  /** Input label */
+  /**
+   * Visible label next to the radio.
+   */
   label: React.ReactNode;
 }
 
@@ -793,12 +1029,18 @@ export declare function SkipToContent(props: SkipToContentProps): JSX.Element;
 /** @beta */
 export declare interface SkipToContentProps extends React.ComponentProps<"a"> {
   /**
-   * Anchor href. The target element should be focusable or have `tabindex="-1"`.
+   * Same-page fragment to jump to.
+   * @remarks Note: The hash character # is required for proper linking.
    */
   href: string;
-  /** Visible/announced label */
+  /**
+   * Visible and announced text.
+   */
   label: string;
-  /** Use label instead */
+  /**
+   * Not accepted.
+   * @remarks Pass text via `label`.
+   */
   children?: never;
 }
 
@@ -848,6 +1090,9 @@ export declare function Spinner({ size, ...props }: SpinnerProps): JSX.Element;
 
 /** @public */
 export declare interface SpinnerProps extends React.ComponentProps<"svg"> {
+  /**
+   * Size of the spinner icon.
+   */
   size?: Responsive<IconSize>;
 }
 
@@ -857,9 +1102,14 @@ export declare function Switch(props: SwitchProps): JSX.Element;
 /** @beta */
 export declare interface SwitchProps
   extends React.ComponentProps<"input">, MarginProps {
-  /** Error state */
+  /**
+   * Applies error styling to the switch track.
+   * @remarks Use when form validation fails. Pair with a visible error message. The prop is visual only.
+   */
   error?: boolean;
-  /** Input label */
+  /**
+   * Visible label next to the switch.
+   */
   label: React.ReactNode;
 }
 
@@ -882,9 +1132,13 @@ export declare type TextAlign = (typeof TEXT_ALIGN)[number];
 export declare interface TextProps<
   T extends React.ElementType = "span",
 > extends TypographyProps {
-  /** Element to render */
+  /**
+   * HTML element to render.
+   */
   as?: T;
-  /** CSS **font-size** property */
+  /**
+   * Sets font size.
+   */
   size?: Responsive<TextSize>;
 }
 
@@ -907,8 +1161,8 @@ declare type ToneProps = {
   tone?: Tone;
 };
 
-/** @public */
-export declare function Tooltip({ placement, ...props }: TooltipProps): any;
+/** @beta */
+export declare const Tooltip: typeof TooltipRoot;
 
 /** @public */
 export declare function TooltipGroup<T extends ElementType = "div">(
@@ -920,19 +1174,42 @@ export declare function TooltipGroup<T extends ElementType = "div">(
 export declare interface TooltipGroupProps<
   T extends React.ElementType = "div",
 > {
-  /** Element to render */
+  /**
+   * HTML element to render.
+   */
   as?: T;
 }
 
-/** @public */
+/** @beta */
 export declare interface TooltipProps
-  extends React.ComponentProps<"div">, PlacementProps {
-  /** Tooltip text */
-  text?: React.ReactNode;
-  /** Disabled state */
-  disabled?: boolean;
+  extends
+    Omit<React.ComponentProps<"div">, "children" | "content">,
+    PlacementProps {
+  /**
+   * Shared anchor identifier.
+   */
+  anchorName?: React.ReactNode;
+  /**
+   * The trigger element.
+   */
+  children: React.ReactElement<Record<string, unknown>>;
+  /**
+   * The tooltip label.
+   */
+  content?: React.ReactNode;
+  /**
+   * Renders the label into `document.body` through a React portal instead of inline.
+   */
+  portal?: boolean;
 }
 
+declare function TooltipRoot({
+  placement,
+  ...props
+}: TooltipProps & {
+  triggerProps?: Record<string, unknown>;
+}): JSX.Element;
+
 /** @public */
 export declare interface TypographyProps extends MarginProps, ToneProps {
   /** CSS **text-align** property */
@@ -947,6 +1224,9 @@ export declare interface TypographyProps extends MarginProps, ToneProps {
   weight?: FontWeight;
 }
 
+/** @public */
+export declare function useIsClient(): boolean;
+
 /** @public */
 export declare function VisuallyHidden<T extends ElementType = "span">(
   props: VisuallyHiddenProps<T> &
@@ -957,9 +1237,13 @@ export declare function VisuallyHidden<T extends ElementType = "span">(
 export declare interface VisuallyHiddenProps<
   T extends React.ElementType = "span",
 > {
-  /** Element to render */
+  /**
+   * HTML element to render.
+   */
   as?: T;
-  /** If true, element is visible on :focus-visible */
+  /**
+   * If true, the element becomes visible on `:focus-visible`.
+   */
   visibleOnFocus?: boolean;
 }
 
@@ -972,7 +1256,9 @@ export declare function VStack<T extends ElementType = "div">(
 export declare interface VStackProps<
   T extends React.ElementType = "div",
 > extends Pick<GapProps, "gap"> {
-  /** Element to render */
+  /**
+   * HTML element or component to render.
+   */
   as?: T;
 }