@sanity-labs/ui-poc 0.0.1-alpha.13 → 0.0.1-alpha.15

package/README.md

@@ -0,0 +1,151 @@
+# Sanity UI 4
+
+The next version of Sanity's component library. Faster, simpler, and built on CSS instead of styled-components.
+
+## What's different from v3
+
+- **CSS classes instead of styled-components.** No runtime style generation. Smaller bundles, faster renders.
+- **Direct props for layout.** Width, height, position, border, and overflow are first-class props — no more `style={{ ... }}` escape hatches.
+- **Works alongside v3.** Install both packages in the same app. No forced migration.
+
+## Install
+
+```sh
+pnpm add @sanity-labs/ui-poc
+```
+
+Requires React 19.2+ and Node >=20.19 <22 || >=22.12.
+
+## Setup
+
+Import the stylesheet at your app entry point. Without it, components render as unstyled HTML with no error.
+
+```tsx
+import '@sanity-labs/ui-poc/styles.css'
+```
+
+If your app uses Sanity UI v3, keep the existing `ThemeProvider` setup.
+
+```tsx
+import {ThemeProvider, studioTheme, ToastProvider} from '@sanity/ui'
+import '@sanity-labs/ui-poc/styles.css'
+import App from './App'
+
+createRoot(document.getElementById('root')!).render(
+  <ThemeProvider theme={studioTheme}>
+    <ToastProvider>
+      <App />
+    </ToastProvider>
+  </ThemeProvider>,
+)
+```
+
+## Usage
+
+Import from `@sanity-labs/ui-poc`. Components not yet in v4 — Menu, Dialog, TextInput, Badge — remain in `@sanity/ui`.
+
+```tsx
+import {Box, Flex, Card, Heading, Text, Button} from '@sanity-labs/ui-poc'
+import {AddIcon} from '@sanity/icons'
+
+export default function App() {
+  return (
+    <Flex minHeight="100vh">
+      <Box as="nav" aria-label="Main" padding={3} borderRight width="240px">
+        <Heading as="h2" size={1}>
+          My App
+        </Heading>
+      </Box>
+      <Box as="main" padding={4} flexGrow={1}>
+        <Flex alignItems="center" justifyContent="space-between" flexWrap="wrap" gap={2}>
+          <Heading as="h1" size={2}>
+            Documents
+          </Heading>
+          <Button iconStart={AddIcon} text="New" />
+        </Flex>
+        <Box marginTop={3}>
+          <Card density="loose">
+            <Text size={1}>First document</Text>
+            <Text size={1} muted>
+              Edited 2 hours ago
+            </Text>
+          </Card>
+        </Box>
+      </Box>
+    </Flex>
+  )
+}
+```
+
+## Components
+
+All components below are from `@sanity-labs/ui-poc`.
+
+### Layout
+
+| Component   | What it does                                                                        |
+| ----------- | ----------------------------------------------------------------------------------- |
+| `Box`       | General container. Padding, margin, border, overflow, and position as direct props. |
+| `Flex`      | Flexbox layout. `alignItems`, `justifyContent`, `flexDirection`, `gap`.             |
+| `Grid`      | CSS grid. Use `gridTemplateColumns` with a CSS string (e.g. `"repeat(3, 1fr)"`).    |
+| `Container` | Max-width content wrapper.                                                          |
+| `HStack`    | Horizontal stack. Accepts `gap` and `as` only — use `Flex` for alignment control.   |
+| `VStack`    | Vertical stack. Accepts `gap` and `as` only — use `Flex` for alignment control.     |
+| `Inline`    | Inline flow layout with wrapping and gap.                                           |
+
+### Typography
+
+| Component | What it does                                                            |
+| --------- | ----------------------------------------------------------------------- |
+| `Heading` | Semantic headings (`h1`–`h6`). Always set `as` to match the level.      |
+| `Text`    | Body copy, captions, labels. Props: `size`, `weight`, `muted`, `align`. |
+| `Label`   | Form input label. Use only with form elements.                          |
+| `Code`    | Inline or block code. Uses the system monospace font.                   |
+
+### Interactive
+
+| Component  | What it does                                                                                                             |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `Button`   | `level` (primary/secondary/tertiary), `tone` (neutral/critical), `iconStart`, `iconEnd`, `text`, `fullWidth`, `loading`. |
+| `Checkbox` | Controlled checkbox. Requires `label` (string).                                                                          |
+| `Radio`    | Controlled radio button.                                                                                                 |
+| `Switch`   | Toggle control. Requires `label` (string).                                                                               |
+| `Link`     | Anchor element styled as a link.                                                                                         |
+
+### Display
+
+| Component        | What it does                                                                                                         |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `Card`           | Raised surface with background and `tone`. Does not accept padding, margin, or layout props — wrap content in `Box`. |
+| `Divider`        | Horizontal rule between content sections.                                                                            |
+| `Icon`           | Renders a `@sanity/icons` icon component. Always set `aria-label` or `aria-hidden`.                                  |
+| `Indicator`      | Status dot with `tone`.                                                                                              |
+| `IndicatorGroup` | Grouped `Indicator` elements.                                                                                        |
+| `Spinner`        | Loading indicator.                                                                                                   |
+
+### Lists
+
+| Component | What it does                                        |
+| --------- | --------------------------------------------------- |
+| `List`    | Semantic list. Use `List.Item` and `List.ItemText`. |
+
+### Accessibility
+
+| Component        | What it does                                                                                     |
+| ---------------- | ------------------------------------------------------------------------------------------------ |
+| `SkipToContent`  | Visually hidden skip-nav link. Must be the first focusable element. Requires `hash` and `label`. |
+| `VisuallyHidden` | Hides content visually while keeping it in the accessibility tree.                               |
+
+### Still from `@sanity/ui`
+
+Menu, Dialog, TextInput, Select, Stack, Badge, ThemeProvider, ToastProvider, and other components not yet migrated to v4.
+
+## Contributing
+
+We welcome feedback and contributions. Start here:
+
+1. **Try the components** and report what breaks, what confuses, or what's missing.
+2. **Read the contribution model** — build a recipe with existing building block components, then propose graduating it.
+3. **Open a PR** following the branch naming and checklist in the developer contribution docs.
+
+During preview, the most useful contribution is using the components and telling us what happens.

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import type {ComponentProps} from 'react'
 import {ComponentPropsWithRef} from 'react'
 import {ElementType} from 'react'
 import {JSX} from 'react/jsx-runtime'
+import type {default as React_2} from 'react'
 import type {SVGProps} from 'react'
 
 declare const ALIGN_ITEMS: readonly ['baseline', 'center', 'flex-end', 'flex-start', 'stretch']
@@ -37,6 +38,48 @@ declare interface BoxProps<T extends React.ElementType> extends LayoutProps {
   display?: Responsive<DisplayBlock>
 }
 
+/** @public */
+export declare function Button<T extends ElementType = 'button'>({
+  density,
+  level,
+  tone,
+  ...props
+}: ButtonProps<T> & Omit<ComponentPropsWithRef<T>, keyof ButtonProps<T>>): JSX.Element
+
+declare const BUTTON_DENSITY: readonly ['regular', 'loose']
+
+declare const BUTTON_LEVEL: readonly ['primary', 'secondary', 'tertiary']
+
+declare const BUTTON_TONE: readonly ['neutral', 'critical']
+
+declare type ButtonDensity = (typeof BUTTON_DENSITY)[number]
+
+declare type ButtonLevel = (typeof BUTTON_LEVEL)[number]
+
+/** @public */
+declare interface ButtonProps<T extends React.ElementType> {
+  /** Element to render */
+  as?: InteractiveAs<T>
+  /** Composite prop for setting padding and gap */
+  density?: ButtonDensity
+  /** Set CSS **width** property to 100% */
+  fullWidth?: Responsive<boolean>
+  /** Starting icon */
+  iconStart?: React.ElementType | React.ReactNode
+  /** Ending icon */
+  iconEnd?: React.ElementType | React.ReactNode
+  /** Button level */
+  level?: ButtonLevel
+  /** Loading state */
+  loading?: boolean
+  /** Button text */
+  text?: string
+  /** Button tone */
+  tone?: ButtonTone
+}
+
+declare type ButtonTone = (typeof BUTTON_TONE)[number]
+
 /** @public */
 export declare function Card<T extends ElementType = 'div'>({
   density,
@@ -57,27 +100,31 @@ export declare function Checkbox(props: CheckboxProps): JSX.Element
 
 /** @beta */
 declare interface CheckboxProps extends React.ComponentProps<'input'>, MarginProps {
-  /** Input label */
-  label: React.ReactNode
+  /** Error state */
+  error?: boolean
   /** Indeterminate state */
   indeterminate?: boolean
+  /** Input label */
+  label: React.ReactNode
 }
 
 /** @public */
-export declare function Code<T extends React.ElementType = 'pre'>({
+export declare function Code<T extends CodeTag = 'pre'>({
   size,
   ...props
-}: CodeProps & Omit<React.ComponentPropsWithRef<T>, keyof CodeProps>): JSX.Element
+}: CodeProps<T> & Omit<ComponentPropsWithRef<T>, keyof CodeProps<T>>): JSX.Element
 
 declare const CODE_SIZE: readonly [0, 1, 2, 3, 4]
 
 declare const CODE_TAG: readonly ['pre', 'span']
 
 /** @public */
-declare interface CodeProps
-  extends React.ComponentProps<'pre'>, Omit<TypographyProps, 'align' | 'lineClamp' | 'tone'> {
+declare interface CodeProps<T extends CodeTag> extends Omit<
+  TypographyProps,
+  'align' | 'lineClamp' | 'tone'
+> {
   /** Element to render */
-  as?: CodeTag
+  as?: T
   /** Refractor language for syntax highlighting */
   language?: string
   /** CSS **font-size** property */
@@ -275,22 +322,62 @@ declare interface HStackProps<T extends React.ElementType> extends Pick<GapProps
 }
 
 /** @public */
-export declare function Icon({icon: Component, size, ...props}: IconProps): JSX.Element
+export declare function Icon({size, ...props}: IconProps): JSX.Element
 
 declare const ICON_SIZE: readonly [0, 1, 2, 3, 4]
 
 /** @public */
-declare interface IconProps extends ComponentProps<'svg'>, MarginProps, ToneProps {
+export declare function IconButton<T extends ElementType = 'button'>(
+  props: IconButtonProps<T> & Omit<ComponentPropsWithRef<T>, keyof IconButtonProps<T>>,
+): JSX.Element
+
+/** @public */
+declare interface IconButtonProps<T extends React_2.ElementType> extends Pick<
+  ButtonProps<T>,
+  'as' | 'density' | 'level' | 'loading' | 'tone'
+> {
+  /** Button label */
+  'aria-label': string
+  /** Icon */
+  'icon': React_2.ComponentType<SVGProps<SVGSVGElement>>
+}
+
+/** @public */
+declare interface IconProps
+  extends ComponentProps<'svg'>, Pick<TypographyProps, 'muted'>, MarginProps, ToneProps {
   /** Icon to render */
   icon: React.ComponentType<SVGProps<SVGSVGElement>>
   /** CSS **font-size** property */
   size?: Responsive<IconSize>
-  /** CSS **color** property */
-  muted?: TypographyProps['muted']
 }
 
 declare type IconSize = (typeof ICON_SIZE)[number]
 
+/** @beta */
+export declare function Indicator<T extends ElementType = 'span'>({
+  tone,
+  ...props
+}: IndicatorProps<T> & Omit<ComponentPropsWithRef<T>, keyof IndicatorProps<T>>): JSX.Element
+
+/** @beta */
+declare interface IndicatorProps<T extends React.ElementType> extends ToneProps {
+  /** Element to render */
+  as?: T
+  /** Label for aria-label attribute */
+  label?: string
+}
+
+/** @public */
+export declare function IndicatorStack<T extends ElementType = 'div'>(
+  props: IndicatorStackProps<T> & Omit<ComponentPropsWithRef<T>, keyof IndicatorStackProps<T>>,
+): JSX.Element
+
+/** @public */
+declare interface IndicatorStackProps<T extends React.ElementType> {
+  /** Element to render */
+  as?: T
+}
+
 /** @deprecated Use HStack component instead */
 /** @public */
 export declare function Inline<T extends ElementType = 'div'>(
@@ -306,6 +393,16 @@ declare interface InlineProps<T extends React.ElementType> extends PaddingProps
   gap?: Responsive<SpaceInherit>
 }
 
+declare const INTERACTIVE_TAG: readonly ['button', 'a']
+
+declare type InteractiveAs<T extends React.ElementType> = T extends InteractiveTag
+  ? T
+  : T extends string
+    ? never
+    : T
+
+declare type InteractiveTag = (typeof INTERACTIVE_TAG)[number]
+
 declare const JUSTIFY_CONTENT: readonly [
   'flex-start',
   'flex-end',
@@ -324,6 +421,7 @@ export declare function Label(props: LabelProps): JSX.Element
 declare interface LabelProps extends React.ComponentProps<'label'>, MarginProps {
   /** Element to render */
   disabled?: boolean
+  error?: boolean
 }
 
 declare interface LayoutProps
@@ -356,6 +454,56 @@ declare interface LinkProps extends React.ComponentProps<'a'> {
   underlined?: boolean
 }
 
+/** @beta */
+export declare const List: typeof ListRoot
+
+declare const LIST_TAG: readonly ['ol', 'ul']
+
+declare function ListItem({density, ...props}: ListItemProps): JSX.Element
+
+declare function ListItemImage(props: ComponentProps<'img'>): JSX.Element
+
+/** @beta */
+declare interface ListItemProps extends React_2.ComponentProps<'li'> {
+  /** Composite prop for setting padding and gap */
+  density?: Responsive<Density>
+  /** Trailing slot */
+  trailing?: React_2.ReactNode
+}
+
+declare function ListItemText<T extends ElementType = 'div'>(
+  props: ListItemTextProps<T> & Omit<ComponentPropsWithRef<T>, keyof ListItemTextProps<T>>,
+): JSX.Element
+
+/** @beta */
+declare interface ListItemTextProps<T extends React_2.ElementType> {
+  /** Element to render */
+  as?: T
+  /** Title text */
+  title?: React_2.ReactNode
+  /** Subtitle text */
+  subtitle?: React_2.ReactNode
+}
+
+/** @beta */
+declare interface ListProps<T extends ListTag> {
+  /** Element to render */
+  as?: T
+}
+
+declare function ListRoot<T extends ListTag = 'ul'>(
+  props: ListProps<T> & Omit<ComponentPropsWithRef<T>, keyof ListProps<T>>,
+): JSX.Element
+
+declare namespace ListRoot {
+  var displayName: string
+  var Item: typeof ListItem
+  var ItemText: typeof ListItemText
+  var ItemImage: typeof ListItemImage
+}
+
+declare type ListTag = (typeof LIST_TAG)[number]
+
 declare type MarginProps = {
   /** CSS **margin** property */
   margin?: Responsive<SpaceAutoNegative>
@@ -403,6 +551,28 @@ declare interface PaddingProps {
   paddingLeft?: Responsive<Space>
 }
 
+declare const PLACEMENT: readonly [
+  'top',
+  'top-start',
+  'top-end',
+  'right',
+  'right-start',
+  'right-end',
+  'bottom',
+  'bottom-start',
+  'bottom-end',
+  'left',
+  'left-start',
+  'left-end',
+]
+
+declare type Placement = (typeof PLACEMENT)[number]
+
+declare type PlacementProps = {
+  /** Placement relative to anchor */
+  placement?: Placement
+}
+
 declare const POSITION: readonly ['absolute', 'fixed', 'relative', 'static', 'sticky']
 
 declare type Position = (typeof POSITION)[number]
@@ -427,6 +597,8 @@ export declare function Radio(props: RadioProps): JSX.Element
 
 /** @beta */
 declare interface RadioProps extends React.ComponentProps<'input'>, MarginProps {
+  /** Error state */
+  error?: boolean
   /** Input label */
   label: React.ReactNode
 }
@@ -457,9 +629,13 @@ declare type Responsive<T> =
       length: 6
     })
 
+declare const SHADOW: readonly [0, 1, 2, 3, 4, 5]
+
+declare type Shadow = (typeof SHADOW)[number]
+
 declare type ShadowProps = {
   /** CSS **box-shadow** property */
-  shadow?: string
+  shadow?: Shadow
 }
 
 /** @beta */
@@ -516,15 +692,23 @@ declare type SpaceAutoNegative = (typeof SPACE_AUTO_NEGATIVE)[number]
 
 declare type SpaceInherit = (typeof SPACE_INHERIT)[number]
 
+/** @public */
+export declare function Spinner({size, ...props}: SpinnerProps): JSX.Element
+
+/** @public */
+declare interface SpinnerProps extends React.ComponentProps<'svg'> {
+  size?: Responsive<IconSize>
+}
+
 /** @beta */
 export declare function Switch(props: SwitchProps): JSX.Element
 
 /** @beta */
 declare interface SwitchProps extends React.ComponentProps<'input'>, MarginProps {
+  /** Error state */
+  error?: boolean
   /** Input label */
   label: React.ReactNode
-  /** Indeterminate state */
-  indeterminate?: boolean
 }
 
 /** @public */
@@ -559,6 +743,28 @@ declare type ToneProps = {
   tone?: Tone
 }
 
+/** @public */
+export declare function Tooltip({placement, ...props}: TooltipProps): any
+
+/** @public */
+export declare function TooltipGroup<T extends ElementType = 'div'>(
+  props: TooltipGroupProps<T> & Omit<ComponentPropsWithRef<T>, keyof TooltipGroupProps<T>>,
+): JSX.Element
+
+/** @public */
+declare interface TooltipGroupProps<T extends React.ElementType> {
+  /** Element to render */
+  as?: T
+}
+
+/** @public */
+declare interface TooltipProps extends React.ComponentProps<'div'>, PlacementProps {
+  /** Tooltip text */
+  text?: React.ReactNode
+  /** Disabled state */
+  disabled?: boolean
+}
+
 declare interface TypographyProps extends MarginProps, ToneProps {
   /** CSS **text-align** property */
   align?: TextAlign