@sanity/ui 5.0.0-alpha.7 → 5.0.0-alpha.9

package/README.md

@@ -46,7 +46,7 @@ import '@sanity/ui/styles.css'
 
 ```tsx
 import {Box, Flex, Card, Heading, Text, Button} from '@sanity/ui'
-import {AddIcon} from '@sanity/icons'
+import {AddIcon} from '@sanity/icons/Add'
 
 export default function App() {
   return (

package/dist/cli/install.js

@@ -23,7 +23,8 @@ function exactFromRange(range) {
  *
  * Icons is already a dependency, so the package manager installs it either way.
  * It is listed explicitly because apps import icons directly to pass to
- * components (`<Button iconStart={AddIcon} />`), and under pnpm an import that
+ * components (`import {AddIcon} from '@sanity/icons/Add'`, then
+ * `<Button iconStart={AddIcon} />`), and under pnpm an import that
  * isn't in the app's own package.json doesn't resolve. Dependencies the app
  * never imports itself (react-refractor, clsx) are left to the package manager.
  * React/react-dom are peers that belong to the host app, so they are left out

package/dist/index.d.ts

@@ -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>;
@@ -44,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>;
 }
 
@@ -71,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;
 }
 
@@ -104,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>;
 }
 
@@ -116,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;
 }
 
@@ -140,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>;
 }
 
@@ -166,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>;
 }
 
@@ -203,13 +274,22 @@ export declare interface DialogProps extends Omit<
   React.ComponentProps<"dialog">,
   "open"
 > {
-  /** Text to be displayed as the dialog's heading; optional but recommended for optimal accessibility and presentation */
+  /**
+   * Text for the dialog heading.
+   * @remarks Recommended for accessibility. The component sets `aria-labelledby` to the heading when you give this prop.
+   */
   header?: string;
-  /** Used to set the value of open to false. Fires whenever the dialog is closed, either programmatically or by the user (via Esc key, clicking background, clicking the dialog's close button, or any other means.)  */
+  /**
+   * 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>;
-  /** Whether the dialog is open; defaults to false. */
+  /**
+   * Toggles the dialog's open state.
+   * @remarks `true` calls `showModal()` on the element. `false` calls `close()`.
+   */
   open?: boolean;
-  /** Max width of the dialog */
+  /** Sets the max width of the dialog */
   size?: Responsive<ContainerSize>;
 }
 
@@ -257,9 +337,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>;
 }
 
@@ -311,9 +395,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>;
 }
 
@@ -387,9 +475,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>;
 }
 
@@ -407,9 +499,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>;
 }
 
@@ -436,7 +534,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;
 }
 
@@ -458,9 +558,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>>;
 }
 
@@ -471,9 +576,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>;
 }
 
@@ -491,9 +600,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;
 }
 
@@ -507,7 +620,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;
 }
 
@@ -522,9 +637,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>;
 }
 
@@ -553,8 +672,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;
 }
 
@@ -579,12 +704,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;
 }
@@ -604,9 +729,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;
 }
 
@@ -616,11 +745,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;
 }
 
@@ -633,11 +768,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;
 }
 
@@ -646,7 +787,9 @@ export declare interface ListProps<T extends ListTag = "ul"> extends Pick<
   GapProps,
   "gap"
 > {
-  /** Element to render */
+  /**
+   * HTML element to render.
+   */
   as?: T;
 }
 
@@ -754,13 +897,23 @@ export declare interface PopoverProps
   extends
     Omit<React.ComponentProps<"div">, "children" | "content">,
     PlacementProps {
-  /** Anchor name for positioning */
+  /**
+   * Shared anchor identifier.
+   * @remarks Set the same value on a Tooltip and a Popover to point both at one trigger.
+   */
   anchorName?: React.ReactNode;
-  /** Focusable trigger element */
+  /**
+   * The trigger element.
+   * @remarks Popover clones it and attaches the `popovertarget` attribute that opens the floating layer.
+   */
   children: React.ReactElement<Record<string, unknown>>;
-  /** Popover content */
+  /**
+   * The floating content.
+   */
   content?: React.ReactNode;
-  /** Render tooltip in portal */
+  /**
+   * Renders the content into `document.body` through a React portal instead of inline.
+   */
   portal?: boolean;
 }
 
@@ -807,7 +960,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>;
 }
 
@@ -817,9 +972,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;
 }
 
@@ -867,12 +1027,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;
 }
 
@@ -922,6 +1088,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>;
 }
 
@@ -931,9 +1100,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;
 }
 
@@ -956,9 +1130,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>;
 }
 
@@ -994,7 +1172,9 @@ 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;
 }
 
@@ -1003,13 +1183,21 @@ export declare interface TooltipProps
   extends
     Omit<React.ComponentProps<"div">, "children" | "content">,
     PlacementProps {
-  /** Anchor name for positioning */
+  /**
+   * Shared anchor identifier.
+   */
   anchorName?: React.ReactNode;
-  /** Focusable trigger element */
+  /**
+   * The trigger element.
+   */
   children: React.ReactElement<Record<string, unknown>>;
-  /** Tooltip content */
+  /**
+   * The tooltip label.
+   */
   content?: React.ReactNode;
-  /** Render tooltip in portal */
+  /**
+   * Renders the label into `document.body` through a React portal instead of inline.
+   */
   portal?: boolean;
 }
 
@@ -1047,9 +1235,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;
 }
 
@@ -1062,7 +1254,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;
 }