@sanity/ui 5.0.0-alpha.6 → 5.0.0-alpha.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/ui",
-  "version": "5.0.0-alpha.6",
+  "version": "5.0.0-alpha.8",
   "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/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/{modal/Modal.tsx → 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'
 
@@ -8,28 +8,28 @@ import {Box} from '../box/Box'
 import {Flex} from '../flex/Flex'
 import {Heading} from '../heading/Heading'
 import {IconButton} from '../icon-button/IconButton'
-import {type ModalProps, modalProps} from './modal.props'
+import {type DialogProps, dialogProps} from './dialog.props'
 
-const modalClassName = suffixClassName('sui-Modal')
-const modalContentClassName = suffixClassName('sui-ModalContent')
-const modalFooterClassName = suffixClassName('sui-ModalFooter')
+const dialogClassName = suffixClassName('sui-Dialog')
+const dialogContentClassName = suffixClassName('sui-DialogContent')
+const dialogFooterClassName = suffixClassName('sui-DialogFooter')
 
-function ModalRoot({open = false, size = 0, ...props}: ModalProps) {
+function DialogRoot({open = false, size = 0, ...props}: DialogProps) {
   const {children, className, style, header, onClose, ...rest} = getProps(
     {size, ...props},
-    modalProps,
+    dialogProps,
   )
 
-  const modalRef = useRef<HTMLDialogElement>(null)
+  const dialogRef = useRef<HTMLDialogElement>(null)
   const headerId = useId()
 
-  const modalClasses = clsx(
-    modalClassName,
+  const dialogClasses = clsx(
+    dialogClassName,
     'sui-inset0 sui-m-auto sui-radius5 sui-shadow3 sui-p4 sui-flex-direction-column sui-gap4 sui-overflow-y-auto',
   )
 
   useEffect(() => {
-    const dialogElement = modalRef.current
+    const dialogElement = dialogRef.current
     if (!dialogElement) return
 
     // `open` = `open` prop
@@ -46,7 +46,7 @@ function ModalRoot({open = false, size = 0, ...props}: ModalProps) {
       }
     }
 
-    // Ensure the modal is closed (and thus its `open` attribute updated)
+    // Ensure the dialog is closed (and thus its `open` attribute updated)
     // when the component is unmounted.
     return () => {
       dialogElement.close()
@@ -56,13 +56,13 @@ function ModalRoot({open = false, size = 0, ...props}: ModalProps) {
   return (
     <dialog
       {...rest}
-      ref={modalRef}
+      ref={dialogRef}
       closedby="any"
       aria-labelledby={header ? headerId : undefined}
       onClose={onClose}
-      className={clsx(modalClasses, className)}
+      className={clsx(dialogClasses, className)}
       style={style}
-      data-ui="Modal"
+      data-ui="Dialog"
     >
       <Flex flexShrink={0} justifyContent="space-between" alignItems="center">
         {header ? (
@@ -76,7 +76,7 @@ function ModalRoot({open = false, size = 0, ...props}: ModalProps) {
           aria-label="Close"
           level="tertiary"
           icon={CloseIcon}
-          onClick={() => modalRef.current?.close()}
+          onClick={() => dialogRef.current?.close()}
         />
       </Flex>
       {children}
@@ -84,15 +84,15 @@ function ModalRoot({open = false, size = 0, ...props}: ModalProps) {
   )
 }
 
-function ModalContent(props: ComponentProps<'div'>) {
+function DialogContent(props: ComponentProps<'div'>) {
   const {children, className, style, ...rest} = getProps(props, {})
 
   return (
     <Box
       {...rest}
-      className={clsx(modalContentClassName, className)}
+      className={clsx(dialogContentClassName, className)}
       style={style}
-      data-ui="ModalContent"
+      data-ui="DialogContent"
       flexGrow={1}
       overflowY="auto"
     >
@@ -101,15 +101,15 @@ function ModalContent(props: ComponentProps<'div'>) {
   )
 }
 
-function ModalFooter(props: ComponentProps<'div'>) {
+function DialogFooter(props: ComponentProps<'div'>) {
   const {children, className, style, ...rest} = getProps(props, {})
 
   return (
     <Box
       {...rest}
-      className={clsx(modalFooterClassName, className)}
+      className={clsx(dialogFooterClassName, className)}
       style={style}
-      data-ui="ModalFooter"
+      data-ui="DialogFooter"
       flexShrink={0}
     >
       {children}
@@ -117,7 +117,7 @@ function ModalFooter(props: ComponentProps<'div'>) {
   )
 }
 
-ModalRoot.displayName = 'Modal'
+DialogRoot.displayName = 'Dialog'
 
 /**
  * @beta
@@ -126,14 +126,14 @@ ModalRoot.displayName = 'Modal'
  * 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 modal element and its descendants.
+ * 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 const Modal = ModalRoot
+export const Dialog = DialogRoot
 
-ModalRoot.Content = ModalContent
-ModalRoot.Footer = ModalFooter
+DialogRoot.Content = DialogContent
+DialogRoot.Footer = DialogFooter
 
-export type {ModalProps}
+export type {DialogProps}

package/src/components/{modal/modal.css → dialog/dialog.css}

@@ -1,5 +1,5 @@
-.sui-Modal {
-  /* Computed width is moderated by Modal's size prop, which controls max-width */
+.sui-Dialog {
+  /* Computed width is moderated by Dialog's size prop, which controls max-width */
   width: calc(100dvw - 2rem);
   max-height: calc(100dvh - 2rem);
   transition:
@@ -9,41 +9,41 @@
     scale 150ms var(--timing-curve);
 }
 
-.sui-Modal:not([open]) {
+.sui-Dialog:not([open]) {
   opacity: 0;
   scale: 0.9;
 }
 
-.sui-Modal[open] {
+.sui-Dialog[open] {
   display: flex;
   opacity: 1;
   scale: 1;
 }
 
-.sui-Modal::backdrop {
-  --modal-backdrop: hsl(from var(--separator-high) h s l / var(--overlay-opacity));
-  background-color: var(--modal-backdrop);
+.sui-Dialog::backdrop {
+  --dialog-backdrop: hsl(from var(--separator-high) h s l / var(--overlay-opacity));
+  background-color: var(--dialog-backdrop);
   transition:
     display 150ms allow-discrete,
     overlay 150ms allow-discrete,
     opacity 150ms var(--timing-linear);
 }
 
-.sui-Modal:not([open])::backdrop {
+.sui-Dialog:not([open])::backdrop {
   opacity: 0;
 }
 
-.sui-Modal[open]::backdrop {
+.sui-Dialog[open]::backdrop {
   opacity: 1;
 }
 
 @starting-style {
-  .sui-Modal[open] {
+  .sui-Dialog[open] {
     opacity: 0;
     scale: 0.9;
   }
 
-  .sui-Modal[open]::backdrop {
+  .sui-Dialog[open]::backdrop {
     opacity: 0;
   }
 }

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

@@ -0,0 +1,38 @@
+import {CONTAINER_SIZE, type ContainerSize} from '../../types/Container'
+import {type PropDef} from '../../types/PropDef'
+import type {Responsive} from '../../types/Responsive'
+
+/** @beta */
+export 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>
+}
+
+export const dialogProps: Record<string, PropDef> = {
+  header: {
+    type: 'string',
+  },
+  open: {
+    type: 'boolean',
+  },
+  size: {
+    type: 'union',
+    className: 'container',
+    values: CONTAINER_SIZE,
+  },
+}

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

@@ -4,6 +4,7 @@
 @import './checkbox/checkbox.css';
 @import './code/code.css';
 @import './container/container.css';
+@import './dialog/dialog.css';
 @import './eyebrow/eyebrow.css';
 @import './flex/flex.css';
 @import './grid/grid.css';
@@ -15,7 +16,6 @@
 @import './label/label.css';
 @import './link/link.css';
 @import './list/list.css';
-@import './modal/modal.css';
 @import './popover/popover.css';
 @import './press-area/press-area.css';
 @import './radio/radio.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
 }