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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/ui",
-  "version": "5.0.0-alpha.7",
+  "version": "5.0.0-alpha.9",
   "description": "Sanity UI Library",
   "keywords": [
     "components",
@@ -49,7 +49,7 @@
   },
   "dependencies": {
     "@sanity-labs/design-tokens": "0.0.2-alpha.4",
-    "@sanity/icons": "^3.7.4",
+    "@sanity/icons": "^5.2.1",
     "clsx": "^2.1.1",
     "comment-json": "^5.0.0",
     "dialog-closedby-polyfill": "^1.3.0",

package/src/cli/install.ts

@@ -36,7 +36,8 @@ function exactFromRange(range: string | undefined): string | null {
  *
  * 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/src/components/badge/Badge.tsx

@@ -0,0 +1,53 @@
+import clsx from 'clsx'
+import {isValidElement, type ComponentPropsWithRef, type ElementType} from 'react'
+
+import {getProps} from '../../utils/getProps'
+import {suffixClassName} from '../../utils/suffixClassName'
+import {Icon} from '../icon/Icon'
+import {Text} from '../text/Text'
+import {type BadgeProps, badgeProps} from './badge.props'
+
+const badgeClassName = suffixClassName('sui-Badge')
+
+/** @public */
+export function Badge<T extends ElementType = 'span'>({
+  tone = 'neutral',
+  ...props
+}: BadgeProps<T> & Omit<ComponentPropsWithRef<T>, keyof BadgeProps<T>>) {
+  const {
+    as,
+    children,
+    className,
+    style,
+    iconStart: IconStart,
+    text,
+    ...rest
+  } = getProps({tone, ...props}, badgeProps)
+  const Component = as || 'span'
+
+  const paddingClasses = IconStart ? 'sui-p1' : 'sui-px2 sui-py1'
+
+  const badgeClasses = clsx(
+    badgeClassName,
+    `${paddingClasses} sui-radius-full sui-display-inline-flex sui-align-items-center sui-gap1`,
+  )
+
+  return (
+    <Component className={clsx(badgeClasses, className)} style={style} data-ui="Badge" {...rest}>
+      {IconStart &&
+        (isValidElement(IconStart) ? (
+          IconStart
+        ) : (
+          <Icon icon={IconStart} marginX={-1} marginY={-2} size={0} />
+        ))}
+      {text && (
+        <Text size={1} trim>
+          {text}
+        </Text>
+      )}
+      {children}
+    </Component>
+  )
+}
+
+export type {BadgeProps}

package/src/components/badge/badge.css

@@ -0,0 +1,6 @@
+.sui-Badge {
+  --badge-background: var(--background-high);
+  --badge-color: var(--foreground-high);
+  background-color: var(--badge-background);
+  color: var(--badge-color);
+}

package/src/components/badge/badge.props.ts

@@ -0,0 +1,31 @@
+import {type ToneProps, toneProps} from '../../props/tone'
+import {type PropDef} from '../../types/PropDef'
+
+/** @public */
+export 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
+}
+
+export const badgeProps: Record<string, PropDef> = {
+  as: {
+    type: 'string',
+  },
+  iconStart: {
+    type: 'string',
+  },
+  text: {
+    type: 'string',
+  },
+  ...toneProps,
+}

package/src/components/box/box.props.ts

@@ -5,9 +5,14 @@ import type {Responsive} from '../../types/Responsive'
 
 /** @public */
 export 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>
 }
 

package/src/components/button/button.props.ts

@@ -16,23 +16,41 @@ import type {Responsive} from '../../types/Responsive'
 
 /** @public */
 export 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
 }
 

package/src/components/card/card.props.ts

@@ -9,9 +9,13 @@ import {type Responsive} from '../../types/Responsive'
 
 /** @public */
 export 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>
 }
 

package/src/components/checkbox/Checkbox.tsx

@@ -1,4 +1,5 @@
-import {CheckmarkIcon, RemoveIcon} from '@sanity/icons'
+import {CheckmarkIcon} from '@sanity/icons/Checkmark'
+import {RemoveIcon} from '@sanity/icons/Remove'
 import clsx from 'clsx'
 import {useEffect, useRef} from 'react'
 

package/src/components/checkbox/checkbox.props.ts

@@ -3,11 +3,19 @@ import {type PropDef} from '../../types/PropDef'
 
 /** @beta */
 export 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
 }
 

package/src/components/code/code.props.ts

@@ -9,11 +9,18 @@ export 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>
 }
 

package/src/components/container/container.props.ts

@@ -5,9 +5,13 @@ import type {Responsive} from '../../types/Responsive'
 
 /** @public */
 export 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>
 }
 

package/src/components/dialog/Dialog.tsx

@@ -1,4 +1,4 @@
-import {CloseIcon} from '@sanity/icons'
+import {CloseIcon} from '@sanity/icons/Close'
 import clsx from 'clsx'
 import {type ComponentProps, useEffect, useId, useRef} from 'react'
 

package/src/components/dialog/dialog.props.ts

@@ -4,13 +4,22 @@ import type {Responsive} from '../../types/Responsive'
 
 /** @beta */
 export 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>
 }
 

package/src/components/eyebrow/eyebrow.props.ts

@@ -5,9 +5,13 @@ import type {Responsive} from '../../types/Responsive'
 
 /** @public */
 export 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>
 }
 

package/src/components/flex/flex.props.ts

@@ -8,9 +8,13 @@ import type {Responsive} from '../../types/Responsive'
 /** @public */
 export 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>
 }
 

package/src/components/grid/grid.props.ts

@@ -8,9 +8,13 @@ import type {Responsive} from '../../types/Responsive'
 /** @public */
 export 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>
 }
 

package/src/components/h-stack/hStack.props.ts

@@ -3,7 +3,9 @@ import {type PropDef} from '../../types/PropDef'
 
 /** @public */
 export interface HStackProps<T extends React.ElementType = 'div'> extends Pick<GapProps, 'gap'> {
-  /** Element to render */
+  /**
+   * HTML element or component to render.
+   */
   as?: T
 }
 

package/src/components/heading/heading.props.ts

@@ -5,9 +5,15 @@ import type {Responsive} from '../../types/Responsive'
 
 /** @public */
 export 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>
 }
 

package/src/components/icon/icon.props.ts

@@ -10,9 +10,13 @@ import type {Responsive} from '../../types/Responsive'
 /** @public */
 export interface IconProps
   extends ComponentProps<'svg'>, 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>
 }
 

package/src/components/icon-button/iconButton.props.ts

@@ -9,9 +9,14 @@ export interface IconButtonProps<T extends React.ElementType = 'button'> extends
   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.ComponentType<SVGProps<SVGSVGElement>>
 }
 

package/src/components/index.css

@@ -1,3 +1,4 @@
+@import './badge/badge.css';
 @import './box/box.css';
 @import './button/button.css';
 @import './card/card.css';

package/src/components/indicator/indicator.props.ts

@@ -3,9 +3,13 @@ import {type PropDef} from '../../types/PropDef'
 
 /** @beta */
 export 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
 }
 

package/src/components/indicator-stack/indicatorStack.props.ts

@@ -2,7 +2,9 @@ import {type PropDef} from '../../types/PropDef'
 
 /** @public */
 export interface IndicatorStackProps<T extends React.ElementType = 'div'> {
-  /** Element to render */
+  /**
+   * HTML element to render.
+   */
   as?: T
 }
 

package/src/components/inline/inline.props.ts

@@ -7,9 +7,13 @@ import {SPACE, type SpaceInherit} from '../../types/Space'
 /** @deprecated Use HStack component instead */
 /** @public */
 export 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>
 }
 

package/src/components/label/label.props.ts

@@ -3,8 +3,14 @@ import {type PropDef} from '../../types/PropDef'
 
 /** @beta */
 export 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
 }
 

package/src/components/link/link.props.ts

@@ -2,12 +2,12 @@ import {type PropDef} from '../../types/PropDef'
 
 /** @beta */
 export 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
 }

package/src/components/list/list.props.ts

@@ -11,7 +11,9 @@ import type {Responsive} from '../../types/Responsive'
 
 /** @beta */
 export interface ListProps<T extends ListTag = 'ul'> extends Pick<GapProps, 'gap'> {
-  /** Element to render */
+  /**
+   * HTML element to render.
+   */
   as?: T
 }
 
@@ -24,11 +26,17 @@ export const listProps: Record<string, PropDef> = {
 
 /** @beta */
 export interface ListItemProps extends React.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.ReactNode
-  /** Ending slot */
+  /**
+   * Slot at the right edge of the row.
+   */
   end?: React.ReactNode
 }
 
@@ -73,9 +81,13 @@ export const listItemProps: Record<string, PropDef> = {
 
 /** @beta */
 export interface ListButtonItemProps<T extends React.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
 }
 
@@ -91,11 +103,17 @@ export const listButtonItemProps: Record<string, PropDef> = {
 
 /** @beta */
 export interface ListItemTextProps<T extends React.ElementType = 'div'> {
-  /** Element to render */
+  /**
+   * HTML element to render.
+   */
   as?: T
-  /** Title text */
+  /**
+   * Main label.
+   */
   title?: React.ReactNode
-  /** Subtitle text */
+  /**
+   * Text below the title.
+   */
   subtitle?: React.ReactNode
 }
 

package/src/components/popover/popover.props.ts

@@ -4,13 +4,23 @@ import {type PropDef} from '../../types/PropDef'
 /** @beta */
 export 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
 }
 

package/src/components/press-area/pressArea.props.ts

@@ -3,7 +3,9 @@ import {type PropDef} from '../../types/PropDef'
 
 /** @public */
 export interface PressAreaProps<T extends React.ElementType = 'button'> {
-  /** Element to render */
+  /**
+   * Element or component to render.
+   */
   as?: InteractiveAs<T>
 }
 

package/src/components/radio/radio.props.ts

@@ -3,9 +3,14 @@ import {type PropDef} from '../../types/PropDef'
 
 /** @beta */
 export 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
 }