@astryxdesign/cli 0.6.3 → 0.6.4-canary.078fd25

package/assets/codemods/transforms/v0.6.4/__tests__/migrate-theme-catalog-to-descriptors.test.mjs

@@ -0,0 +1,220 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import manifest from '../index.mjs';
+import migrate from '../migrate-theme-catalog-to-descriptors.mjs';
+import {runCodemods} from '../../../runner.mjs';
+import {discoverThemeDirectory} from '../../../../../foundation/discovery/theme-discovery.mjs';
+
+let root;
+
+beforeEach(() => {
+  root = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-theme-catalog-'));
+});
+
+afterEach(() => {
+  fs.rmSync(root, {recursive: true, force: true});
+});
+
+/** A catalog entry exactly as `astryx integration add theme <slug>` wrote it in 0.6. */
+function entry(slug, overrides = {}) {
+  const identifier = slug.replace(/-([a-z0-9])/gu, (_, c) => c.toUpperCase());
+  const displayName = slug
+    .split('-')
+    .map(part => part[0].toUpperCase() + part.slice(1))
+    .join(' ');
+  return {
+    slug,
+    displayName,
+    description: `${displayName} theme.`,
+    maintained: true,
+    entry: `${identifier}Theme.ts`,
+    exportName: `${identifier}Theme`,
+    files: [`${identifier}Theme.ts`],
+    ...overrides,
+  };
+}
+
+/** @param {ReturnType<typeof entry>[]} themes */
+function writeKit(themes, {sources = true} = {}) {
+  fs.writeFileSync(
+    path.join(root, 'package.json'),
+    '{"name":"@acme/kit","version":"1.0.0"}\n',
+  );
+  fs.writeFileSync(
+    path.join(root, 'astryx.integration.mjs'),
+    "export default {themes: './themes'};\n",
+  );
+  for (const theme of themes) {
+    const source = path.join(root, 'themes', theme.slug, theme.entry);
+    fs.mkdirSync(path.dirname(source), {recursive: true});
+    if (sources) {
+      fs.writeFileSync(
+        source,
+        `import {defineTheme} from '@astryxdesign/core/theme';\n\nexport const ${theme.exportName} = defineTheme({\n  name: '${theme.slug}',\n});\n`,
+      );
+    }
+  }
+  fs.mkdirSync(path.join(root, 'themes'), {recursive: true});
+  fs.writeFileSync(
+    path.join(root, 'themes', 'manifest.json'),
+    `${JSON.stringify({version: 1, themes}, null, 2)}\n`,
+  );
+}
+
+const catalog = () => path.join(root, 'themes', 'manifest.json');
+
+/** @param {boolean} apply @param {string} [srcPath] */
+const run = (apply, srcPath = root) =>
+  runCodemods([{version: 'next', transforms: manifest}], {
+    apply,
+    path: srcPath,
+    codemod: undefined,
+    silent: true,
+    root,
+  });
+
+describe('migrate-theme-catalog-to-descriptors', () => {
+  it('is staged for the next release as a project codemod', () => {
+    expect(manifest.map(t => [t.name, t.meta.codemodType])).toEqual([
+      ['migrate-theme-catalog-to-descriptors', 'project'],
+      ['migrate-native-picker-to-presentation', undefined],
+    ]);
+  });
+
+  it('writes one typed descriptor per catalog theme and removes the catalog', async () => {
+    writeKit([
+      entry('ocean'),
+      entry('deep-sea', {
+        displayName: "Deep 'Sea'",
+        description: 'Line one\nline two \\ done.',
+        maintained: false,
+      }),
+    ]);
+
+    const result = await run(true);
+
+    expect(result).toMatchObject({errors: [], totalFilesChanged: 3});
+    expect(fs.existsSync(catalog())).toBe(false);
+    expect(
+      fs.readFileSync(
+        path.join(root, 'themes/ocean/oceanTheme.doc.mjs'),
+        'utf-8',
+      ),
+    ).toBe(
+      "/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */\nexport default {\n  type: 'theme',\n  name: 'ocean',\n  displayName: 'Ocean',\n  description: 'Ocean theme.',\n  maintained: true,\n};\n",
+    );
+    const themes = discoverThemeDirectory(
+      path.join(root, 'themes'),
+      '@acme/kit',
+    );
+    expect(
+      themes.map(({slug, displayName, description, maintained}) => ({
+        slug,
+        displayName,
+        description,
+        maintained,
+      })),
+    ).toEqual([
+      {
+        slug: 'deep-sea',
+        displayName: "Deep 'Sea'",
+        description: 'Line one\nline two \\ done.',
+        maintained: false,
+      },
+      {
+        slug: 'ocean',
+        displayName: 'Ocean',
+        description: 'Ocean theme.',
+        maintained: true,
+      },
+    ]);
+  });
+
+  it('previews without writing, even with no source folder', async () => {
+    writeKit([entry('ocean')]);
+    // A staged code codemod (migrate-native-picker-to-presentation) requires
+    // the source folder to exist; an empty one exercises the same preview.
+    fs.mkdirSync(path.join(root, 'src'), {recursive: true});
+
+    const result = await run(false, path.join(root, 'src'));
+
+    expect(result).toMatchObject({
+      errors: [],
+      totalFilesChanged: 2,
+      writtenFiles: [],
+    });
+    expect(fs.existsSync(catalog())).toBe(true);
+    expect(
+      fs.existsSync(path.join(root, 'themes/ocean/oceanTheme.doc.mjs')),
+    ).toBe(false);
+  });
+
+  it('keeps a descriptor that already exists and still removes the catalog', async () => {
+    writeKit([entry('ocean'), entry('reef')]);
+    const kept = path.join(root, 'themes/ocean/oceanTheme.doc.mjs');
+    fs.writeFileSync(
+      kept,
+      "export default {type: 'theme', name: 'ocean', displayName: 'Mine', description: '', maintained: true};\n",
+    );
+
+    const result = await run(true);
+
+    expect(result.errors).toEqual([]);
+    expect(fs.readFileSync(kept, 'utf-8')).toContain("displayName: 'Mine'");
+    expect(
+      fs.existsSync(path.join(root, 'themes/reef/reefTheme.doc.mjs')),
+    ).toBe(true);
+    expect(fs.existsSync(catalog())).toBe(false);
+  });
+
+  it('changes nothing and names each entry that cannot convert', async () => {
+    writeKit([
+      entry('ocean'),
+      entry('sea', {exportName: 'oceanBlue'}),
+      entry('nested', {
+        entry: 'src/nestedTheme.ts',
+        files: ['src/nestedTheme.ts'],
+      }),
+    ]);
+    fs.rmSync(path.join(root, 'themes/ocean/oceanTheme.ts'));
+    const before = fs.readFileSync(catalog(), 'utf-8');
+
+    const result = await run(true);
+
+    expect(result.errors.map(e => [e.file, e.error])).toEqual([
+      ['themes/ocean', 'holds no oceanTheme.ts for theme "ocean".'],
+      [
+        'themes/manifest.json',
+        'theme "sea" exports "oceanBlue" from seaTheme.ts; a descriptor takes the export name from the file name, so rename the export or the file to match.',
+      ],
+      [
+        'themes/manifest.json',
+        'theme "nested" has entry "src/nestedTheme.ts"; a descriptor sits beside a .ts, .tsx, .mjs, or .js source directly in themes/nested/.',
+      ],
+    ]);
+    expect(fs.readFileSync(catalog(), 'utf-8')).toBe(before);
+    expect(fs.existsSync(path.join(root, 'themes/sea/seaTheme.doc.mjs'))).toBe(
+      false,
+    );
+  });
+
+  it('leaves a package with no catalog to convert alone', async () => {
+    const empty = {writes: [], deletes: [], problems: []};
+    await expect(migrate(root)).resolves.toEqual(empty);
+    fs.writeFileSync(
+      path.join(root, 'astryx.integration.mjs'),
+      'export default {};\n',
+    );
+    await expect(migrate(root)).resolves.toEqual(empty);
+    fs.writeFileSync(
+      path.join(root, 'astryx.integration.mjs'),
+      "export default {themes: './themes'};\n",
+    );
+    fs.mkdirSync(path.join(root, 'themes'));
+    await expect(migrate(root)).resolves.toEqual(empty);
+  });
+});

package/assets/codemods/transforms/v0.6.4/index.mjs

@@ -0,0 +1,31 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file next transform manifest
+ *
+ * Staged codemods for the next release. The Version Packages PR promotes
+ * this file into the resolved version folder.
+ */
+
+import migrateThemeCatalogToDescriptors, {
+  meta as migrateThemeCatalogToDescriptorsMeta,
+} from './migrate-theme-catalog-to-descriptors.mjs';
+import migrateNativePickerToPresentation, {
+  meta as migrateNativePickerToPresentationMeta,
+} from './migrate-native-picker-to-presentation.mjs';
+
+export default [
+  {
+    name: 'migrate-theme-catalog-to-descriptors',
+    transform:
+      /** @type {import('../../../../authoring/codemod/type').CodemodTransform} */ (
+        /** @type {unknown} */ (migrateThemeCatalogToDescriptors)
+      ),
+    meta: migrateThemeCatalogToDescriptorsMeta,
+  },
+  {
+    name: 'migrate-native-picker-to-presentation',
+    transform: migrateNativePickerToPresentation,
+    meta: migrateNativePickerToPresentationMeta,
+  },
+];

package/assets/codemods/transforms/v0.6.4/migrate-native-picker-to-presentation.mjs

@@ -0,0 +1,148 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: migrate nativePicker to presentation on date/time inputs
+ *
+ * `spec:AST-043` FR3 mapping, applied only to static literals written
+ * directly on imported `DateInput`, `DateTimeInput`, and `TimeInput`
+ * elements: the prop is renamed to `presentation` and its value mapped.
+ * When the element already sets `presentation`, the deprecated prop is
+ * removed (presentation wins, FR4). Dynamic values are left unchanged —
+ * the deprecated prop keeps working, so an unmigrated callsite is still
+ * correct, and guessing at an expression's values would not be.
+ */
+
+import {transformProp} from '../../transform-prop.mjs';
+
+export const meta = {
+  title: 'Migrate nativePicker to presentation',
+  description:
+    'Renames `nativePicker` to `presentation` on DateInput, DateTimeInput, ' +
+    'and TimeInput, mapping touch→adaptive-native, always→native, and ' +
+    'never→adaptive-bottom-sheet (text-input for TimeInput). Dynamic ' +
+    'values are left for manual migration; the deprecated prop still works.',
+};
+
+const CORE_IMPORT_RE = /^@(astryxdesign|xds)\/core(?:\/|$)/;
+
+const COMPONENT_PROPS = new Map([
+  ['DateInput', new Set(['nativePicker'])],
+  ['DateTimeInput', new Set(['nativePicker'])],
+  ['TimeInput', new Set(['nativePicker'])],
+]);
+
+/** @param {string} component @param {string} value */
+function mapValue(component, value) {
+  switch (value) {
+    case 'touch':
+      return 'adaptive-native';
+    case 'always':
+      return 'native';
+    case 'never':
+      return component === 'TimeInput' ? 'text-input' : 'adaptive-bottom-sheet';
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Collect the string-literal leaves of a value expression without mutating
+ * anything. Returns false for any dynamic or non-string node.
+ * @param {any} node
+ * @param {any[]} leaves
+ * @returns {boolean}
+ */
+function collectStaticLeaves(node, leaves) {
+  if (!node) return false;
+  if (
+    node.type === 'TSAsExpression' ||
+    node.type === 'TSSatisfiesExpression' ||
+    node.type === 'TypeCastExpression' ||
+    node.type === 'ParenthesizedExpression'
+  ) {
+    return collectStaticLeaves(node.expression, leaves);
+  }
+  if (node.type === 'ConditionalExpression') {
+    return (
+      collectStaticLeaves(node.consequent, leaves) &&
+      collectStaticLeaves(node.alternate, leaves)
+    );
+  }
+  if (
+    (node.type !== 'StringLiteral' && node.type !== 'Literal') ||
+    typeof node.value !== 'string'
+  ) {
+    return false;
+  }
+  leaves.push(node);
+  return true;
+}
+
+/**
+ * Map every leaf, or none of them: a mixed static/dynamic conditional must
+ * stay byte-identical, never half-migrated.
+ * @param {any} node
+ * @param {string} component
+ */
+function mapStaticValue(node, component) {
+  /** @type {any[]} */
+  const leaves = [];
+  if (!collectStaticLeaves(node, leaves)) return false;
+  if (leaves.some(leaf => mapValue(component, leaf.value) === undefined)) {
+    return false;
+  }
+  for (const leaf of leaves) {
+    leaf.value = mapValue(component, leaf.value);
+    if (leaf.raw) leaf.raw = undefined;
+  }
+  return true;
+}
+
+/**
+ * @param {import('../../../../authoring/codemod/type').AstryxCodemodFile} file
+ * @param {import('../../../../authoring/codemod/type').CodemodTransformApi} api
+ * @returns {string | null | undefined}
+ */
+export default function transformer(file, api) {
+  if (!file.source.includes('nativePicker')) return undefined;
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  let hasChanges = false;
+
+  transformProp(
+    root,
+    j,
+    {
+      matchesImport: source => CORE_IMPORT_RE.test(source),
+      components: COMPONENT_PROPS,
+    },
+    (propPath, {component}) => {
+      const opening = propPath.parent?.node;
+      const attributes = opening?.attributes ?? [];
+      const hasPresentation = attributes.some(
+        (/** @type {any} */ attribute) =>
+          attribute.type === 'JSXAttribute' &&
+          attribute.name?.name === 'presentation',
+      );
+      const prop = propPath.node;
+      if (hasPresentation) {
+        // FR4: presentation wins; drop the deprecated prop.
+        opening.attributes = attributes.filter(
+          (/** @type {any} */ attribute) => attribute !== prop,
+        );
+        hasChanges = true;
+        return;
+      }
+      const value =
+        prop.value?.type === 'JSXExpressionContainer'
+          ? prop.value.expression
+          : prop.value;
+      if (!mapStaticValue(value, component)) return;
+      prop.name.name = 'presentation';
+      hasChanges = true;
+    },
+  );
+
+  if (!hasChanges) return undefined;
+  return root.toSource({quote: 'single'});
+}

package/assets/codemods/transforms/v0.6.4/migrate-theme-catalog-to-descriptors.mjs

@@ -0,0 +1,141 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Give each integration theme a typed descriptor instead of the
+ *   `manifest.json` theme catalog.
+ *
+ * Astryx 0.6 scaffolded integration themes into one catalog,
+ * `<themes root>/manifest.json`. Each theme now carries a strongly typed
+ * same-stem `.doc.mjs` descriptor, and a themes root that still holds the
+ * catalog is refused. This project codemod reads the package's integration
+ * manifest, plans one descriptor per catalog entry beside that theme's source,
+ * and removes the catalog. When any entry cannot convert, it plans nothing and
+ * names the entry, so the package is never left half converted.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {loadManifestObject} from '../../../../foundation/integrations/integrations.mjs';
+import {findLocalIntegrationManifestOrNull} from '../../../../foundation/integrations/manifest-writer.mjs';
+import {themeDescriptorSource} from '../../../../foundation/integrations/theme-descriptor.mjs';
+
+export const meta = {
+  title:
+    'Give each integration theme a typed descriptor instead of the manifest.json catalog',
+  description:
+    'Writes <name>Theme.doc.mjs beside each theme the catalog lists, then removes the catalog.',
+  codemodType: 'project',
+};
+
+const SLUG = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u;
+const SOURCE = /\.(?:ts|tsx|mjs|js)$/u;
+
+/**
+ * @param {string} root the package directory
+ * @returns {Promise<import('../../runner.mjs').ProjectCodemodPlan>}
+ */
+export default async function migrateThemeCatalogToDescriptors(root) {
+  /** @type {import('../../runner.mjs').ProjectCodemodPlan} */
+  const plan = {writes: [], deletes: [], problems: []};
+  /** @param {string} file @returns {string} */
+  const rel = file => path.relative(root, file).split(path.sep).join('/');
+  /** @param {string} file @param {string} message */
+  const problem = (file, message) => plan.problems.push({file, message});
+
+  const manifestFile = findLocalIntegrationManifestOrNull(root);
+  if (!manifestFile) return plan;
+  const manifest = await loadManifestObject(
+    manifestFile,
+    `Integration manifest ${path.basename(manifestFile)}`,
+    {fresh: true},
+  );
+  if (typeof manifest.themes !== 'string') return plan;
+  const themesRoot = path.resolve(root, manifest.themes);
+  const fromRoot = path.relative(root, themesRoot);
+  if (fromRoot.startsWith('..') || path.isAbsolute(fromRoot)) return plan;
+  const catalogFile = path.join(themesRoot, 'manifest.json');
+  if (!fs.existsSync(catalogFile)) return plan;
+  const catalogPath = rel(catalogFile);
+
+  let catalog;
+  try {
+    catalog = JSON.parse(fs.readFileSync(catalogFile, 'utf-8'));
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    problem(catalogPath, `is not valid JSON (${reason}).`);
+    return plan;
+  }
+  if (
+    !catalog ||
+    typeof catalog !== 'object' ||
+    catalog.version !== 1 ||
+    !Array.isArray(catalog.themes)
+  ) {
+    problem(catalogPath, 'is not a version 1 theme catalog.');
+    return plan;
+  }
+
+  for (const [index, entry] of catalog.themes.entries()) {
+    const slug = entry?.slug;
+    if (typeof slug !== 'string' || !SLUG.test(slug)) {
+      problem(
+        catalogPath,
+        `themes[${index}] has no lowercase kebab-case slug; fix the entry or add that theme's descriptor by hand.`,
+      );
+      continue;
+    }
+    const themeDir = path.join(themesRoot, slug);
+    const source = entry.entry;
+    if (
+      typeof source !== 'string' ||
+      !SOURCE.test(source) ||
+      source !== path.basename(source)
+    ) {
+      problem(
+        catalogPath,
+        `theme "${slug}" has entry ${JSON.stringify(source)}; a descriptor sits beside a .ts, .tsx, .mjs, or .js source directly in ${rel(themeDir)}/.`,
+      );
+      continue;
+    }
+    const stem = source.replace(SOURCE, '');
+    if (entry.exportName !== stem) {
+      problem(
+        catalogPath,
+        `theme "${slug}" exports ${JSON.stringify(entry.exportName)} from ${source}; a descriptor takes the export name from the file name, so rename the export or the file to match.`,
+      );
+      continue;
+    }
+    if (typeof entry.displayName !== 'string' || !entry.displayName.trim()) {
+      problem(catalogPath, `theme "${slug}" has no displayName.`);
+      continue;
+    }
+    if (typeof entry.description !== 'string') {
+      problem(catalogPath, `theme "${slug}" has no description string.`);
+      continue;
+    }
+    if (typeof entry.maintained !== 'boolean') {
+      problem(catalogPath, `theme "${slug}" has no maintained flag.`);
+      continue;
+    }
+    if (!fs.existsSync(path.join(themeDir, source))) {
+      problem(rel(themeDir), `holds no ${source} for theme "${slug}".`);
+      continue;
+    }
+    const descriptor = path.join(themeDir, `${stem}.doc.mjs`);
+    if (fs.existsSync(descriptor)) continue;
+    plan.writes.push({
+      path: descriptor,
+      contents: themeDescriptorSource({
+        type: 'theme',
+        name: slug,
+        displayName: entry.displayName,
+        description: entry.description,
+        maintained: entry.maintained,
+      }),
+    });
+  }
+  if (plan.problems.length > 0)
+    return {writes: [], deletes: [], problems: plan.problems};
+  plan.deletes.push(catalogFile);
+  return plan;
+}

package/assets/docs/README.md

@@ -21,13 +21,15 @@ Someone building a product with Astryx. Their questions:
 ## Tells that you are writing for us instead
 
 - second person aimed at the wrong reader — "reviewers should…", "before promoting a component…", "attach evidence for…"
-- **rubric, readiness, gate, audit, checklist, sign-off, promotion, evidence** as things the reader must produce
+- an internal rubric, readiness gate, audit checklist, or sign-off that the reader must satisfy for Astryx maintainers
 - a table of things to verify rather than things to use
 - anything about lab → core, which is our lifecycle, not theirs
 - Storybook, Playwright, CI or the Simulator named as tools the reader runs
 
 One subtlety: a statement about the **system's behavior** is caller-facing even when it sounds like process. "A component's theme targets are stable once published" tells a caller what they can rely on; "reviewers must check that theme targets are stable" is ours. Same fact, different reader — **rewrite it rather than move it**.
 
+A public authoring-quality rubric is also caller-facing when it helps someone evaluate an artifact they create through Astryx. It must be complete and actionable from public inputs. It must not include Astryx's internal approval, promotion, evidence-publication, or CI process. A current system spec must assign the shipped guide as the rubric's owner.
+
 ## Where the rest goes
 
 The material is usually good; the finding is placement, not quality. It goes in the [wiki](https://github.com/facebook/astryx/wiki) — **as a section on the page that already covers it, not a new page.** The wiki is at nearly 60 pages, several of them overlapping, because every stray section got its own.
@@ -48,3 +50,12 @@ The material is usually good; the finding is placement, not quality. It goes in
 **Fits no row?** It is still not caller-facing. Default it to [Contributing](https://github.com/facebook/astryx/wiki/Contributing), or `CONTRIBUTING.md` when it is a step someone follows with the repo cloned. Never default it back to this directory.
 
 Worked example: a responsive-and-interaction readiness rubric is grading criteria → **Component-Audit-Rubric**, or **Component-Lifecycle** if it is a promotion gate.
+
+## Sections are read one at a time
+
+`astryx docs <topic> --index` lists a topic's sections, and readers then open
+one section by its key. A section's key is its `id`, or a key derived from its
+title when it has none. Give a section an `id` when its title may change, since
+readers and extensions link to the key. Two sections in one topic cannot share
+a key. Keep each section small enough to read on its own: `astryx doctor` warns on
+any section over 32 KB.

package/assets/docs/authoring.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs authoring`: every authoring schema, one section each.
+ *
+ * Built from the self-docs colocated under packages/cli/authoring, so it cannot
+ * drift from the schemas it describes. `astryx doctor` names a self-doc this
+ * topic cannot reach.
+ */
+
+import {buildAuthoringTopic} from '../../foundation/discovery/authoring-self-docs.mjs';
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = await buildAuthoringTopic();

package/assets/docs/browser-support.doc.mjs

@@ -73,7 +73,7 @@ export const docs = {
               'Baseline 2026: the tightest requirement.',
             ],
             [
-              '[`Popover`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) API',
+              '`Popover` API',
               'Opens, stacks, and light-dismisses layered surfaces via the top layer.',
               'Baseline 2025.',
             ],
@@ -86,7 +86,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'The gap that matters is between Tier 1 and Tier 2: the [`Popover`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) API and `light-dark()` reached wide availability well before anchor positioning. So in Tier 2 browsers, layered surfaces open and dismiss correctly; they just are not positioned. This is the one feature most consumers will need to reason about.',
+          text: 'The gap that matters is between Tier 1 and Tier 2: the `Popover` API and `light-dark()` reached wide availability well before anchor positioning. So in Tier 2 browsers, layered surfaces open and dismiss correctly; they just are not positioned. This is the one feature most consumers will need to reason about.',
         },
       ],
     },
@@ -95,24 +95,24 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'The browser requirement is concentrated in the layered-surface components: anything that renders content in an overlay positioned against a trigger:',
+          text: 'Any component that opens a menu, popover, tooltip, or dropdown carries the browser requirement: it renders that surface in an overlay positioned against its trigger. That includes:',
         },
         {
           type: 'list',
           style: 'unordered',
           items: [
-            'Tooltip',
-            'HoverCard',
-            'Popover',
-            'ContextMenu',
-            'Selector and MultiSelector (dropdown surfaces)',
+            'Tooltip, HoverCard, and Popover, and any prop that shows one (such as the Button `tooltip`)',
+            'DropdownMenu, MoreMenu, and ContextMenu',
+            'Selector, MultiSelector, ComplexSelector, Typeahead, and PowerSearch (dropdown surfaces)',
+            'DateInput, DateRangeInput, and DateTimeInput (calendar popovers)',
             'Tokenizer (suggestion menu)',
+            'The overflow and flyout menus in Breadcrumbs, TabList, TopNav, and SideNav',
             'Carousel (anchored controls)',
           ],
         },
         {
           type: 'prose',
-          text: 'If your product does not use any of these, it has no anchor-positioning requirement at all; it needs only `light-dark()` (Tier 2 and up) for correct theme colors. Page layout, typography, forms, buttons, cards, tables, and navigation all work down to Tier 2 with no special handling.',
+          text: 'If your product opens no menus, popovers, tooltips, or dropdowns, it has no anchor-positioning requirement; it needs only `light-dark()` (Tier 2 and up) for correct theme colors. Page layout, typography, forms, buttons, cards, and tables work down to Tier 2 with no special handling.',
         },
       ],
     },
@@ -123,7 +123,7 @@ export const docs = {
           type: 'list',
           style: 'do',
           items: [
-            'Components never throw on missing platform APIs. Where a browser lacks the [`Popover`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) API, layers fall back to plain visibility instead of crashing.',
+            'Components never throw on missing platform APIs. Where a browser lacks the `Popover` API, layers fall back to plain visibility instead of crashing.',
             'Tier 1 and Tier 2 are officially supported and tested.',
             'Non-layered components render correctly down to Tier 2.',
           ],
@@ -192,7 +192,7 @@ const hasLightDark = CSS.supports('color', 'light-dark(#000, #fff)');`,
         },
         {
           type: 'prose',
-          text: 'This is not an arbitrary window: Baseline − 2 is close to where anchor positioning stops being available while the [`Popover`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) API and `light-dark()` still are, so the tier boundary tracks a real capability edge, not a guessed date. The version floors above are reviewed and advanced roughly once a year as new Baseline years land. Always feature-detect rather than hardcoding version numbers, so your app adapts automatically as the platform moves.',
+          text: 'This is not an arbitrary window: Baseline − 2 is close to where anchor positioning stops being available while the `Popover` API and `light-dark()` still are, so the tier boundary tracks a real capability edge, not a guessed date. The version floors above are reviewed and advanced roughly once a year as new Baseline years land. Always feature-detect rather than hardcoding version numbers, so your app adapts automatically as the platform moves.',
         },
       ],
     },

package/assets/docs/color.doc.mjs

@@ -22,7 +22,8 @@ export const docs = {
       ],
     },
     {
-      title: 'Surface Colors',
+      id: 'surface-colors',
+      title: 'Color Tokens',
   category: 'foundations',
       content: [
         {
@@ -37,9 +38,14 @@ export const docs = {
       ],
     },
     {
-      title: 'Usage',
+      id: 'usage',
+      title: 'Use color tokens in StyleX',
   category: 'foundations',
       content: [
+        {
+          type: 'prose',
+          text: 'Import the typed color tokens and use them in `stylex.create()`; they resolve to the active theme and color mode.',
+        },
         {
           type: 'code',
           lang: 'tsx',