@sanity/ui 4.0.0-static.9 → 5.0.0-alpha.1

package/README.md

@@ -1,31 +1,215 @@
-# @sanity/ui
+# Sanity UI 5
 
-The Sanity UI components.
+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.** Both versions run in the same app, in the same component tree. No forced migration.
+
+Requires React 19.2+ and Node >=20.19 <22 || >=22.12.
+
+## For new apps
+
+### Install
+
+#### Recommended: the setup CLI
 
 ```sh
-npm install @sanity/ui
+npx @sanity/ui@alpha init
+```
+
+`init` detects your framework and package manager, checks your React and Node versions, then installs the package along with `@sanity/icons`, adds the stylesheet import to your entry file, reconciles `tsconfig.json`, and writes a `sanity-ui.json`. It prints a plan and asks before changing anything.
+
+`@sanity/icons` is a dependency of this package, so your package manager installs it either way. `init` also adds it to your own `package.json` because you import icons directly to pass to components, and under pnpm an import that isn't declared in your project doesn't resolve.
+
+- `--dry` print the plan and exit without changing anything
+- `--yes` accept every prompt with its default (non-interactive, for CI and agents)
+- `--cwd <dir>` run against another directory
+
+#### Manual
+
+```sh
+pnpm add @sanity/ui@alpha
+```
+
+Using npm or yarn? Use `npm add` or `yarn add` instead. (`init` above picks the right one for you.)
 
-# Install peer dependencies
-npm install react react-dom react-is
+Then import the stylesheet at your app entry point. Without it, components render as unstyled HTML.
+
+```tsx
+import '@sanity/ui/styles.css'
+```
+
+### Usage
+
+```tsx
+import {Box, Flex, Card, Heading, Text, Button} from '@sanity/ui'
+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>
+  )
+}
 ```
 
-[![npm version](https://img.shields.io/npm/v/@sanity/ui.svg?style=flat-square)](https://www.npmjs.com/package/@sanity/ui)
+### Checking your setup
+
+Run `doctor` at any time to verify an install and get a one-line fix for anything broken:
 
-## Usage
+```sh
+npx @sanity/ui@alpha doctor
+```
 
-```jsx
-import '@sanity/ui/css/index.css'
+It checks that the package and `@sanity/icons` are installed, the stylesheet resolves and is imported, `tsconfig.json` has the options the components need, and your React and Node versions are supported.
+
+## For apps using Sanity UI v3
+
+### Install
+
+v3 and v5 are the same npm package at different majors, so an app that wants both needs a package alias to tell them apart.
+
+In apps still using v3 components, we recommend installing v5 with a package alias. This way, your existing `@sanity/ui` imports keep resolving to v3, so nothing you have already written needs to change.
+
+```sh
+pnpm add ui5@npm:@sanity/ui@alpha
+```
 
-import {Button, Root} from '@sanity/ui'
-import {createRoot} from 'react-dom/client'
+This gives you:
 
-createRoot(document).render(
-  <Root lang="en">
-    <Button text="Hello, world" />
-  </Root>,
+```json
+{
+  "dependencies": {
+    "@sanity/ui": "^3.5.1",
+    "ui5": "npm:@sanity/ui@alpha"
+  }
+}
+```
+
+Now `@sanity/ui` means v3 everywhere in your codebase and `ui5` means v5. You migrate one import at a time, at whatever pace suits you, instead of rewriting every file before anything runs.
+
+The alias name is yours to choose. `ui5` is what we use internally. npm, pnpm, and yarn all support the `npm:` protocol.
+
+### Setup
+
+v5 has no `ThemeProvider`, and it does not read v3's theme. Keep your existing provider setup exactly as it is: v3 components still need it, and it has no effect on v5.
+
+With v5 installed under an alias, the stylesheet comes from the alias too.
+
+```tsx
+import {ThemeProvider, studioTheme, ToastProvider} from '@sanity/ui' // v3
+import 'ui5/styles.css' // v5
+import App from './App'
+
+createRoot(document.getElementById('root')!).render(
+  <ThemeProvider theme={studioTheme}>
+    <ToastProvider>
+      <App />
+    </ToastProvider>
+  </ThemeProvider>,
 )
 ```
 
-## License
+### Usage
+
+With v5 aliased, which version you get is just which specifier you import from. Anything without a v5 equivalent keeps coming from `@sanity/ui`, and the two sit next to each other in the same tree.
+
+```tsx
+import {Dialog} from '@sanity/ui' // v3
+import {Button, Card, Text} from 'ui5' // v5
+```
+
+## Components
+
+### 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`.                                                                                              |
+| `IndicatorStack` | 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 `href` and `label`. |
+| `VisuallyHidden` | Hides content visually while keeping it in the accessibility tree.                               |
+
+### Still only in v3
+
+Menu, Dialog, TextInput, Select, Stack, Badge, ThemeProvider, ToastProvider, and other components not yet migrated to v5. Import these from `@sanity/ui` exactly as you do today.
+
+## 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.
 
-MIT-licensed. See LICENSE.
+During preview, the most useful contribution is using the components and telling us what happens.

package/bin/sanity-ui.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+import process from 'node:process'
+
+import {main} from '../dist/cli/index.js'
+import {errorLine} from '../dist/cli/log.js'
+
+try {
+  const code = await main(process.argv.slice(2))
+  process.exitCode = code ?? 0
+} catch (error) {
+  errorLine(error instanceof Error ? error.message : String(error))
+  process.exitCode = 1
+}

package/dist/_chunks-es/LazyRefractor.js

@@ -0,0 +1,20 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { c } from "react/compiler-runtime";
+import { hasLanguage, Refractor } from "react-refractor";
+function LazyRefractor(t0) {
+  const $ = c(5), {
+    language,
+    value
+  } = t0;
+  if (!hasLanguage(language)) {
+    let t12;
+    return $[0] !== value ? (t12 = /* @__PURE__ */ jsx("code", { children: value }), $[0] = value, $[1] = t12) : t12 = $[1], t12;
+  }
+  let t1;
+  return $[2] !== language || $[3] !== value ? (t1 = /* @__PURE__ */ jsx(Refractor, { inline: !0, language, value }), $[2] = language, $[3] = value, $[4] = t1) : t1 = $[4], t1;
+}
+export {
+  LazyRefractor as default
+};
+//# sourceMappingURL=LazyRefractor.js.map

package/dist/_chunks-es/LazyRefractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LazyRefractor.js","sources":["../../src/components/code/LazyRefractor.tsx"],"sourcesContent":["import {hasLanguage, Refractor, type RefractorProps} from 'react-refractor'\n\nexport default function LazyRefractor({language, value}: RefractorProps) {\n  if (!hasLanguage(language)) {\n    return <code>{value}</code>\n  }\n\n  return <Refractor inline language={language} value={value} />\n}\n"],"names":["LazyRefractor","t0","$","_c","language","value","hasLanguage","t1"],"mappings":";;;;AAEA,SAAeA,cAAAC,IAAA;AAAA,QAAAC,IAAAC,EAAA,CAAA,GAAuB;AAAA,IAAAC;AAAAA,IAAAC;AAAAA,EAAAA,IAAAJ;AACpC,MAAI,CAACK,YAAYF,QAAQ,GAAC;AAAA,QAAAG;AAAA,WAAAL,SAAAG,SACjBE,MAAA,oBAAA,QAAA,EAAOF,iBAAM,GAAOH,OAAAG,OAAAH,OAAAK,OAAAA,MAAAL,EAAA,CAAA,GAApBK;AAAAA,EAAoB;AAC5B,MAAAA;AAAA,SAAAL,EAAA,CAAA,MAAAE,YAAAF,SAAAG,SAEME,yBAAC,WAAA,EAAU,YAAiBH,UAAiBC,MAAAA,CAAK,GAAIH,OAAAE,UAAAF,OAAAG,OAAAH,OAAAK,MAAAA,KAAAL,EAAA,CAAA,GAAtDK;AAAsD;"}

package/dist/cli/checks.js

@@ -0,0 +1,148 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import process from 'node:process';
+import { detect, isPackageInstalled, isLegacyUiVersion, PACKAGE_NAME, readInstalledPackageVersion, } from './detect.js';
+import { inspectStylesheet, STYLES_SPECIFIER } from './styles.js';
+import { inspectTsconfig } from './tsconfig.js';
+import { meetsNode, meetsReact, NODE_REQUIREMENT, REACT_MIN } from './versions.js';
+const ICONS = '@sanity/icons';
+/** Resolves the built stylesheet on disk (not the Node no-op shim). */
+function resolveStylesheet(cwd) {
+    try {
+        const require = createRequire(join(cwd, 'noop.js'));
+        const pkgJsonPath = require.resolve(`${PACKAGE_NAME}/package.json`);
+        const path = join(dirname(pkgJsonPath), 'dist/styles.css');
+        return existsSync(path) ? path : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Without a browser, "a component renders with a computed background" is
+ * verified by confirming the resolved stylesheet ships the component class and
+ * a background declaration for it. If both are present and the import is wired,
+ * the component renders styled.
+ */
+function stylesheetHasComponentStyles(path) {
+    try {
+        const css = readFileSync(path, 'utf8');
+        return /\.sui-Card\b/.test(css) && /background/.test(css);
+    }
+    catch {
+        return false;
+    }
+}
+function check(id, ok, meta) {
+    return {
+        id,
+        title: meta.title,
+        ok,
+        status: meta.status ?? (ok ? 'pass' : 'fail'),
+        detail: meta.detail,
+        fix: meta.fix,
+    };
+}
+/**
+ * Runs every verification and returns structured results. `doctor` prints them
+ * all; `init` reuses a subset on exit. Pure read-only.
+ */
+export function collectChecks(cwd) {
+    const detected = detect(cwd);
+    const checks = [];
+    const installedVersion = readInstalledPackageVersion(cwd, PACKAGE_NAME);
+    checks.push(check('install', Boolean(installedVersion), {
+        title: 'Package installed',
+        detail: installedVersion ? `${PACKAGE_NAME}@${installedVersion}` : 'not installed',
+        fix: `Run \`npx ${PACKAGE_NAME}@alpha init\` or install it with your package manager`,
+    }));
+    if (installedVersion) {
+        const legacyInstalled = isLegacyUiVersion(installedVersion);
+        checks.push(check('version', !legacyInstalled, {
+            title: 'Package version',
+            detail: legacyInstalled
+                ? `${PACKAGE_NAME}@${installedVersion} is pre-v5 (expected v5)`
+                : `${PACKAGE_NAME}@${installedVersion}`,
+            fix: `Remove the existing @sanity/ui version, or install v5 with a package alias — see README "For apps using Sanity UI v3"`,
+        }));
+    }
+    const iconsInstalled = isPackageInstalled(cwd, ICONS);
+    checks.push(check('icons', iconsInstalled, {
+        title: 'Icons installed',
+        detail: iconsInstalled ? `${ICONS} present` : `${ICONS} missing`,
+        fix: `Install it: add ${ICONS}`,
+    }));
+    const stylesheetPath = resolveStylesheet(cwd);
+    const stylesheetResolves = Boolean(stylesheetPath);
+    checks.push(check('stylesheet-resolves', stylesheetResolves, {
+        title: 'Stylesheet resolves',
+        detail: stylesheetResolves ? `${PACKAGE_NAME}/styles.css` : 'cannot resolve styles.css',
+        fix: 'Reinstall the package, or build it if working inside this monorepo',
+    }));
+    const stylesheet = inspectStylesheet(cwd, detected.entry);
+    checks.push(check('stylesheet-wired', stylesheet.imported, {
+        title: 'Stylesheet imported',
+        detail: stylesheet.imported
+            ? `imported in ${stylesheet.importedIn ?? detected.entry}`
+            : stylesheet.exists
+                ? `missing from ${detected.entry}`
+                : `entry file ${detected.entry} not found`,
+        fix: `Add \`import '${STYLES_SPECIFIER}'\` to ${detected.entry}`,
+    }));
+    if (detected.typescript) {
+        const tsconfig = inspectTsconfig(cwd);
+        const loadBearing = tsconfig.changes.filter((c) => c.load);
+        // An unreadable file has no changes to report, so guard against it explicitly
+        // rather than letting an empty change list read as "all good".
+        const ok = tsconfig.exists && !tsconfig.unreadable && loadBearing.length === 0;
+        checks.push(check('tsconfig', ok, {
+            title: 'tsconfig options',
+            detail: !tsconfig.exists
+                ? 'tsconfig.json not found'
+                : tsconfig.unreadable
+                    ? 'tsconfig.json could not be parsed'
+                    : loadBearing.length === 0
+                        ? tsconfig.changes.length === 0
+                            ? 'all required options set'
+                            : 'required options set (some optional additions available)'
+                        : `needs: ${loadBearing.map((c) => `${c.key}: ${String(c.to)}`).join(', ')}`,
+            fix: tsconfig.unreadable
+                ? 'Fix the JSON syntax in tsconfig.json'
+                : `Run \`npx ${PACKAGE_NAME}@alpha init\` to reconcile tsconfig.json`,
+        }));
+    }
+    const reactVersion = detected.react.version;
+    const reactOk = reactVersion ? meetsReact(reactVersion) : false;
+    checks.push(check('react', reactOk, {
+        title: 'React version',
+        status: reactVersion ? (reactOk ? 'pass' : 'fail') : 'warn',
+        detail: reactVersion ? `react ${reactVersion}` : 'react not detected',
+        fix: `Upgrade React to >= ${REACT_MIN}`,
+    }));
+    const nodeVersion = process.versions.node;
+    checks.push(check('node', meetsNode(nodeVersion), {
+        title: 'Node version',
+        detail: `node ${nodeVersion} (requires ${NODE_REQUIREMENT})`,
+        fix: `Use Node ${NODE_REQUIREMENT}`,
+    }));
+    return { detected, checks, stylesheetPath };
+}
+/** The subset `init` verifies on exit, plus the render probe. */
+export function verifyAfterInit(cwd) {
+    const { checks, stylesheetPath } = collectChecks(cwd);
+    const ids = new Set(['stylesheet-resolves', 'stylesheet-wired', 'tsconfig']);
+    const subset = checks.filter((c) => ids.has(c.id));
+    const probeOk = stylesheetPath ? stylesheetHasComponentStyles(stylesheetPath) : false;
+    subset.push({
+        id: 'probe',
+        title: 'Probe renders with background',
+        ok: probeOk,
+        status: probeOk ? 'pass' : 'fail',
+        detail: stylesheetPath
+            ? 'Card ships a background declaration'
+            : 'stylesheet not resolved, cannot probe',
+        fix: 'Ensure the package is installed and built',
+    });
+    return subset;
+}

package/dist/cli/config.js

@@ -0,0 +1,23 @@
+import { existsSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const CONFIG_FILE = 'sanity-ui.json';
+/**
+ * Builds the sanity-ui.json contents: a small record of the detected setup
+ * (framework, entry) written to the project root for tooling to read.
+ */
+export function buildConfig({ framework, entry, }) {
+    return {
+        $schema: 'https://sanity-ui.sanity.dev/schema.json',
+        framework,
+        entry,
+    };
+}
+export function configExists(cwd) {
+    return existsSync(join(cwd, CONFIG_FILE));
+}
+export function writeConfig(cwd, config, { dryRun = false } = {}) {
+    const file = join(cwd, CONFIG_FILE);
+    if (!dryRun)
+        writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`);
+    return { file, wrote: !dryRun };
+}

package/dist/cli/detect.js

@@ -0,0 +1,181 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseVersion } from './versions.js';
+export const PACKAGE_NAME = '@sanity/ui';
+export const LEGACY_COEXISTENCE_HINT = 'To add v5 alongside an existing @sanity/ui install, use a package alias — see the README section "For apps using Sanity UI v3".';
+/**
+ * Framework ids map 1:1 to the `framework` field written into sanity-ui.json.
+ * Each carries the ordered list of candidate entry files where the stylesheet
+ * import belongs.
+ */
+const FRAMEWORK_ENTRIES = {
+    'next-app': ['app/layout.tsx', 'app/layout.jsx', 'src/app/layout.tsx', 'src/app/layout.jsx'],
+    'next-pages': ['pages/_app.tsx', 'pages/_app.jsx', 'src/pages/_app.tsx', 'src/pages/_app.jsx'],
+    'react-router': ['app/root.tsx', 'app/root.jsx'],
+    'remix': ['app/root.tsx', 'app/root.jsx'],
+    'vite': ['src/main.tsx', 'src/main.jsx', 'src/main.ts'],
+    'astro': [],
+    'react': ['src/index.tsx', 'src/main.tsx', 'src/index.jsx', 'src/main.jsx'],
+};
+export function readPackageJson(cwd) {
+    const file = join(cwd, 'package.json');
+    if (!existsSync(file))
+        return null;
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function allDeps(pkg) {
+    if (!pkg)
+        return {};
+    return { ...pkg.dependencies, ...pkg.devDependencies, ...pkg.peerDependencies };
+}
+export function detectPackageManager(cwd) {
+    if (existsSync(join(cwd, 'bun.lockb')) || existsSync(join(cwd, 'bun.lock')))
+        return 'bun';
+    if (existsSync(join(cwd, 'pnpm-lock.yaml')))
+        return 'pnpm';
+    if (existsSync(join(cwd, 'yarn.lock')))
+        return 'yarn';
+    if (existsSync(join(cwd, 'package-lock.json')))
+        return 'npm';
+    const declared = readPackageJson(cwd)?.packageManager;
+    if (typeof declared === 'string') {
+        const name = declared.split('@')[0];
+        if (name === 'pnpm' || name === 'yarn' || name === 'npm' || name === 'bun')
+            return name;
+    }
+    return 'npm';
+}
+export function detectFramework(cwd, pkg = readPackageJson(cwd)) {
+    const deps = allDeps(pkg);
+    const has = (name) => Boolean(deps[name]);
+    const dir = (relative) => existsSync(join(cwd, relative));
+    if (has('next')) {
+        if (dir('app') || dir('src/app'))
+            return 'next-app';
+        if (dir('pages') || dir('src/pages'))
+            return 'next-pages';
+        return 'next-app';
+    }
+    if (has('@remix-run/react') || has('@remix-run/dev'))
+        return 'remix';
+    if (has('@react-router/dev') || has('react-router'))
+        return 'react-router';
+    if (has('astro'))
+        return 'astro';
+    if (has('vite'))
+        return 'vite';
+    return 'react';
+}
+export function detectTypeScript(cwd, pkg = readPackageJson(cwd)) {
+    return existsSync(join(cwd, 'tsconfig.json')) || Boolean(allDeps(pkg)['typescript']);
+}
+/**
+ * Returns the first existing candidate entry file, otherwise the first
+ * candidate as the place to create one. Astro has no fixed entry, so we look
+ * for a layout component.
+ */
+export function detectEntry(cwd, framework) {
+    if (framework === 'astro')
+        return detectAstroLayout(cwd);
+    const candidates = FRAMEWORK_ENTRIES[framework];
+    const existing = candidates.find((rel) => existsSync(join(cwd, rel)));
+    return { entry: existing ?? candidates[0] ?? 'src/index.tsx', exists: Boolean(existing) };
+}
+function detectAstroLayout(cwd) {
+    const candidates = [
+        'src/layouts/Layout.astro',
+        'src/layouts/BaseLayout.astro',
+        'src/layouts/index.astro',
+        'src/pages/index.astro',
+    ];
+    const existing = candidates.find((rel) => existsSync(join(cwd, rel)));
+    return { entry: existing ?? candidates[0] ?? 'src/layouts/Layout.astro', exists: Boolean(existing) };
+}
+/**
+ * Resolves the installed React version from node_modules, falling back to the
+ * declared range in package.json (carets/tildes stripped).
+ */
+export function detectReactVersion(cwd, pkg = readPackageJson(cwd)) {
+    const installed = readInstalledVersion(cwd, 'react');
+    if (installed)
+        return { version: installed, source: 'installed' };
+    const declared = allDeps(pkg)['react'];
+    if (typeof declared === 'string') {
+        return { version: declared.replace(/^[\^~>=<\s]+/, ''), source: 'declared' };
+    }
+    return { version: null, source: 'missing' };
+}
+function readInstalledVersion(cwd, name) {
+    const file = join(cwd, 'node_modules', name, 'package.json');
+    if (!existsSync(file))
+        return null;
+    try {
+        const pkg = JSON.parse(readFileSync(file, 'utf8'));
+        return pkg.version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+export function isPackageInstalled(cwd, name) {
+    return existsSync(join(cwd, 'node_modules', name, 'package.json'));
+}
+export function readInstalledPackageVersion(cwd, name) {
+    return readInstalledVersion(cwd, name);
+}
+export function isLegacyUiVersion(version) {
+    const major = parseVersion(version)?.[0];
+    return major !== undefined && major < 5;
+}
+function detectAliasedInstall(deps) {
+    for (const [name, spec] of Object.entries(deps)) {
+        if (typeof spec === 'string' && /^npm:@sanity\/ui@(5(?:\..*)?|alpha)$/.test(spec))
+            return name;
+    }
+    return null;
+}
+/** Reads the major from a declared range, skipping workspace/catalog/link specs. */
+function declaredMajor(spec) {
+    if (typeof spec !== 'string')
+        return null;
+    if (/^(workspace:|catalog:|link:|file:)/.test(spec))
+        return null;
+    const npmAlias = spec.match(/^npm:@sanity\/ui@(\d+)/);
+    if (npmAlias)
+        return Number(npmAlias[1]);
+    return parseVersion(spec.replace(/^[\^~>=<\s]+/, ''))?.[0] ?? null;
+}
+function detectLegacyInstall(cwd, deps) {
+    const installed = readInstalledPackageVersion(cwd, PACKAGE_NAME);
+    if (installed && isLegacyUiVersion(installed)) {
+        return installed;
+    }
+    const declared = deps[PACKAGE_NAME];
+    const major = declaredMajor(declared);
+    if (major !== null && major < 5) {
+        return declared ?? 'unknown';
+    }
+    return null;
+}
+export function detect(cwd) {
+    const pkg = readPackageJson(cwd);
+    const deps = allDeps(pkg);
+    const framework = detectFramework(cwd, pkg);
+    const entry = detectEntry(cwd, framework);
+    const typescript = detectTypeScript(cwd, pkg) || (entry.exists && /\.tsx?$/.test(entry.entry));
+    return {
+        pkg,
+        packageManager: detectPackageManager(cwd),
+        framework,
+        typescript,
+        ...entry,
+        react: detectReactVersion(cwd, pkg),
+        aliasedInstall: detectAliasedInstall(deps),
+        legacyInstall: detectLegacyInstall(cwd, deps),
+    };
+}

package/dist/cli/doctor.js

@@ -0,0 +1,49 @@
+import { collectChecks } from './checks.js';
+import { detect, LEGACY_COEXISTENCE_HINT, PACKAGE_NAME } from './detect.js';
+import { color, fail, heading, info, success, warn } from './log.js';
+export function printChecks(checks) {
+    for (const c of checks) {
+        const label = `${color.bold(c.title)}${c.detail ? ` ${color.dim(`— ${c.detail}`)}` : ''}`;
+        if (c.status === 'pass')
+            success(label);
+        else if (c.status === 'warn')
+            warn(label);
+        else
+            fail(label);
+        if (c.status !== 'pass' && c.fix) {
+            info(`  ${color.dim('fix:')} ${c.fix}`);
+        }
+    }
+}
+/** Runs every check and prints it. Returns 1 only when something fails; warnings still pass. */
+export function runDoctor({ cwd }) {
+    const detected = detect(cwd);
+    heading('Sanity UI doctor');
+    if (detected.aliasedInstall) {
+        warn(`This project installs v5 under the alias "${detected.aliasedInstall}". doctor checks direct @sanity/ui v5 installs only.`);
+        info(`  ${color.dim('hint:')} ${LEGACY_COEXISTENCE_HINT}`);
+        return 0;
+    }
+    if (detected.legacyInstall) {
+        warn(`This project has ${PACKAGE_NAME}@${detected.legacyInstall} (pre-v5). doctor checks v5 installs only.`);
+        info(`  ${color.dim('hint:')} ${LEGACY_COEXISTENCE_HINT}`);
+        return 0;
+    }
+    const { checks } = collectChecks(cwd);
+    info(color.dim(`framework: ${detected.framework} · package manager: ${detected.packageManager} · entry: ${detected.entry}`));
+    info('');
+    printChecks(checks);
+    const failed = checks.filter((c) => c.status === 'fail');
+    const warned = checks.filter((c) => c.status === 'warn');
+    info('');
+    if (failed.length === 0 && warned.length === 0) {
+        success('Everything looks good.');
+        return 0;
+    }
+    if (failed.length === 0) {
+        warn(`${warned.length} warning${warned.length === 1 ? '' : 's'}, no blocking issues.`);
+        return 0;
+    }
+    fail(`${failed.length} issue${failed.length === 1 ? '' : 's'} found. See fixes above.`);
+    return 1;
+}