@astryxdesign/cli 0.4.7-canary.a7bedb2 → 0.4.7-canary.b6c0501

package/api/search/search.mjs

@@ -34,10 +34,12 @@ import {pathToFileURL} from 'node:url';
 import {findCoreDir} from '../../foundation/fs/paths.mjs';
 import {
   discoverComponents,
+  discoverIntegrationComponents,
   findComponentReadme,
   resolveImportPath,
 } from '../../foundation/discovery/component-discovery.mjs';
 import {discoverHooks, findHookDoc} from '../../foundation/discovery/hook-discovery.mjs';
+import {loadIntegrationsSafely} from '../component/_adapter.mjs';
 import {levenshteinDistance} from '../../foundation/text/string-utils.mjs';
 import {discoverTemplates, extractComponents} from '../template/template.mjs';
 import {loadDocsCatalog, loadTopicDoc} from '../docs/_adapter.mjs';
@@ -350,12 +352,12 @@ async function loadModuleDoc(docPath, exportName = 'docs') {
 }
 
 /**
- * Build component candidates: name + keywords + usage/description from the
- * component's .doc.mjs.
+ * Build component candidates from core's own tree: name + keywords +
+ * usage/description from the component's .doc.mjs.
  * @param {string} coreDir
  * @returns {Promise<Candidate[]>}
  */
-async function gatherComponents(coreDir) {
+async function gatherCoreComponents(coreDir) {
   const grouped = discoverComponents(coreDir);
   const names = Object.values(grouped).flat();
   /** @type {Candidate[]} */
@@ -383,6 +385,50 @@ async function gatherComponents(coreDir) {
   return candidates;
 }
 
+/**
+ * Build component candidates contributed by the project's configured
+ * integrations (astryx.config's `integrations`): name + keywords +
+ * usage/description from each component's .doc.mjs, same as core. Without
+ * this, an integration component is invisible to `search`/`build` even
+ * though `component --list`/`component <Name>` already resolve it — the two
+ * discovery paths silently disagreed.
+ * @param {string} cwd
+ * @returns {Promise<Candidate[]>}
+ */
+async function gatherIntegrationComponents(cwd) {
+  const loadedIntegrations = await loadIntegrationsSafely(cwd);
+  /** @type {Candidate[]} */
+  const candidates = [];
+  for (const integration of loadedIntegrations) {
+    for (const rec of discoverIntegrationComponents(integration)) {
+      const doc = await loadModuleDoc(rec.docPath);
+      candidates.push({
+        domain: 'component',
+        name: rec.name,
+        keywords: doc && Array.isArray(doc.keywords) ? doc.keywords : [],
+        description: doc ? doc.usage?.description || doc.description || '' : '',
+        _import: rec.package,
+      });
+    }
+  }
+  return candidates;
+}
+
+/**
+ * Build component candidates: core's own tree plus every configured
+ * integration's components.
+ * @param {string} coreDir
+ * @param {string} cwd
+ * @returns {Promise<Candidate[]>}
+ */
+async function gatherComponents(coreDir, cwd) {
+  const [core, integrations] = await Promise.all([
+    gatherCoreComponents(coreDir),
+    gatherIntegrationComponents(cwd),
+  ]);
+  return [...core, ...integrations];
+}
+
 /**
  * Build hook candidates: name + keywords + usage/description from the hook's
  * .doc.mjs.
@@ -611,7 +657,7 @@ export async function search(query, options = {}) {
   /** @param {string} d */
   const wants = d => !type || type === d;
   const [components, hooks, docTopics, templates] = await Promise.all([
-    wants('component') ? gatherComponents(coreDir) : [],
+    wants('component') ? gatherComponents(coreDir, cwd) : [],
     wants('hook') ? gatherHooks(coreDir) : [],
     wants('doc') ? gatherDocs(cwd) : [],
     wants('template') ? gatherTemplates(cwd) : [],

package/api/search/search.test.mjs

@@ -10,9 +10,17 @@
  * `limit`, an empty query, and a bad `--type` all throw AstryxError with the
  * ERR_INVALID_ARGUMENT code, so a direct `@astryxdesign/cli/api` caller gets the
  * same contract as `astryx search` on the command line.
+ *
+ * The last describe block covers integration-contributed components, using the
+ * same temp-consumer harness as template-integration.test.mjs. Before this,
+ * `search`/`build` only ever scanned @astryxdesign/core — an integration's own
+ * components were invisible to both, even though `component --list` and
+ * `component <Name>` already resolved them. The two discovery paths silently
+ * disagreed.
  */
 
 import {describe, it, expect} from 'vitest';
+import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {fileURLToPath} from 'node:url';
 import {search, SEARCH_DOMAINS} from './search.mjs';
@@ -92,3 +100,66 @@ describe('search leaf — limit validation (API matches the CLI contract)', () =
     });
   }, SLOW);
 });
+
+describe('search leaf — integration components', () => {
+  /**
+   * A minimal consumer project: a stub `@astryxdesign/core` (so `findCoreDir`
+   * resolves without needing the real package) plus an installed
+   * `@acme/widgets` integration that contributes one component.
+   */
+  function makeConsumerWithIntegrationComponent() {
+    const dir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-search-it-'));
+    fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({name: 'consumer'}));
+    fs.writeFileSync(
+      path.join(dir, 'astryx.config.mjs'),
+      `export default { integrations: ['@acme/widgets'] };\n`,
+    );
+
+    // Stub core: just needs to exist with an (empty) src/ so discoverComponents
+    // doesn't throw. Its own component list is irrelevant to this test.
+    const coreDir = path.join(dir, 'node_modules', '@astryxdesign', 'core');
+    fs.mkdirSync(path.join(coreDir, 'src'), {recursive: true});
+
+    const widgetsDir = path.join(dir, 'node_modules', '@acme', 'widgets');
+    fs.mkdirSync(path.join(widgetsDir, 'components'), {recursive: true});
+    fs.writeFileSync(
+      path.join(widgetsDir, 'package.json'),
+      JSON.stringify({name: '@acme/widgets', version: '1.0.0'}),
+    );
+    fs.writeFileSync(
+      path.join(widgetsDir, 'astryx.integration.mjs'),
+      `export default { components: './components' };\n`,
+    );
+    fs.writeFileSync(
+      path.join(widgetsDir, 'components', 'FancyGizmo.doc.mjs'),
+      `export const docs = {
+        name: 'FancyGizmo',
+        keywords: ['gizmo', 'widget'],
+        usage: {description: 'A fancy gizmo widget.'},
+      };\n`,
+    );
+
+    return dir;
+  }
+
+  it('includes a component contributed by a configured integration', async () => {
+    const dir = makeConsumerWithIntegrationComponent();
+    try {
+      const r = await search('gizmo', {cwd: dir, type: 'component'});
+      expect(r.data.results.some(x => x.name === 'FancyGizmo')).toBe(true);
+    } finally {
+      fs.rmSync(dir, {recursive: true, force: true});
+    }
+  }, SLOW);
+
+  it('reports the contributing package as the import hint', async () => {
+    const dir = makeConsumerWithIntegrationComponent();
+    try {
+      const r = await search('FancyGizmo', {cwd: dir, type: 'component'});
+      const hit = r.data.results.find(x => x.name === 'FancyGizmo');
+      expect(hit?.import).toBe('@acme/widgets');
+    } finally {
+      fs.rmSync(dir, {recursive: true, force: true});
+    }
+  }, SLOW);
+});

package/assets/codemods/transforms/next/__tests__/next-codemods.test.mjs

@@ -0,0 +1,127 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Unit tests for the staged (next-release) codemods.
+ *
+ * Mirrors v0.4.0/__tests__/next-codemods.test.mjs, which covers the codemods
+ * after promotion. Keeping a copy here means a staged transform is tested from
+ * the day it is written rather than the day it is released.
+ */
+
+import {describe, expect, it} from 'vitest';
+import jscodeshift from 'jscodeshift';
+
+const j = jscodeshift.withParser('tsx');
+const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+
+async function apply(name, source) {
+  const {default: transform} = await import(`../${name}.mjs`);
+  return transform({source, path: 'test.tsx'}, api) ?? source;
+}
+
+const TRANSFORM = 'banner-collapsible-content';
+
+const IMPORT = "import {Banner} from '@astryxdesign/core/Banner';\n";
+
+describe('banner-collapsible-content', () => {
+  it('rewrites a bare defaultIsExpanded to a starts-open config', async () => {
+    const output = await apply(
+      TRANSFORM,
+      `${IMPORT}const el = <Banner status="info" title="T" defaultIsExpanded><p>d</p></Banner>;`,
+    );
+    expect(output).toContain('defaultIsOpen: true');
+    expect(output).not.toContain('defaultIsExpanded');
+  });
+
+  it('rewrites defaultIsExpanded={true} the same way', async () => {
+    const output = await apply(
+      TRANSFORM,
+      `${IMPORT}const el = <Banner status="info" title="T" defaultIsExpanded={true}><p>d</p></Banner>;`,
+    );
+    expect(output).toContain('defaultIsOpen: true');
+    expect(output).not.toContain('defaultIsExpanded');
+  });
+
+  it('drops defaultIsExpanded={false}, which is the default', async () => {
+    const output = await apply(
+      TRANSFORM,
+      `${IMPORT}const el = <Banner status="info" title="T" defaultIsExpanded={false}><p>d</p></Banner>;`,
+    );
+    expect(output).not.toContain('defaultIsExpanded');
+    // No config needed: starting collapsed is what a Banner does by default.
+    expect(output).not.toContain('collapsible');
+    // Untouched attributes keep their original text (recast only reprints
+    // what changed), so the element is exactly the base minus the prop.
+    expect(output).toContain('<Banner status="info" title="T">');
+  });
+
+  it('keeps a dynamic default dynamic', async () => {
+    const output = await apply(
+      TRANSFORM,
+      `${IMPORT}const el = <Banner status="info" title="T" defaultIsExpanded={isOpen}><p>d</p></Banner>;`,
+    );
+    expect(output).toContain('defaultIsOpen: isOpen');
+    expect(output).not.toContain('defaultIsExpanded');
+  });
+
+  it('leaves a banner that never set the prop alone', async () => {
+    // The default is unchanged, so this banner still behaves as it did. The
+    // migration must not touch it — that is the whole point of the shape.
+    const source = `${IMPORT}const el = <Banner status="error" title="T"><ul><li>a</li></ul></Banner>;`;
+    const output = await apply(TRANSFORM, source);
+    expect(output).toBe(source);
+  });
+
+  it('leaves a childless banner alone', async () => {
+    const source = `${IMPORT}const el = <Banner status="info" title="T" />;`;
+    const output = await apply(TRANSFORM, source);
+    expect(output).toBe(source);
+  });
+
+  it('leaves a banner that already uses collapsible alone', async () => {
+    const source = `${IMPORT}const el = <Banner status="info" title="T" collapsible={false} defaultIsExpanded><p>d</p></Banner>;`;
+    const output = await apply(TRANSFORM, source);
+    expect(output).toBe(source);
+  });
+
+  it('does not guess around a spread', async () => {
+    const source = `${IMPORT}const el = <Banner status="info" title="T" defaultIsExpanded {...rest}><p>d</p></Banner>;`;
+    const output = await apply(TRANSFORM, source);
+    expect(output).toBe(source);
+  });
+
+  it("leaves another component's defaultIsExpanded alone", async () => {
+    // ChatToolCalls has a prop of the same name that this migration must not
+    // touch.
+    const source = `import {ChatToolCalls} from '@astryxdesign/core/Chat';
+const el = <ChatToolCalls calls={calls} defaultIsExpanded />;`;
+    const output = await apply(TRANSFORM, source);
+    expect(output).toBe(source);
+  });
+
+  it('leaves a Banner that is not the core Banner alone', async () => {
+    const source = `import {Banner} from './ui/Banner';
+const el = <Banner status="info" title="T" defaultIsExpanded><p>d</p></Banner>;`;
+    const output = await apply(TRANSFORM, source);
+    expect(output).toBe(source);
+  });
+
+  it('leaves the prop inside a props object alone', async () => {
+    // Out of scope by design: which component the object feeds is a guess,
+    // and the removed prop makes those sites a type error anyway.
+    const source = `${IMPORT}const args = {status: 'info', title: 'T', defaultIsExpanded: true};
+const el = <Banner {...args} />;`;
+    const output = await apply(TRANSFORM, source);
+    expect(output).toBe(source);
+  });
+
+  it('migrates a Banner imported from the package root', async () => {
+    const output = await apply(
+      TRANSFORM,
+      `import {Banner, Button} from '@astryxdesign/core';
+const el = <Banner status="info" title="T" defaultIsExpanded><p>d</p></Banner>;`,
+    );
+    expect(output).toContain('defaultIsOpen: true');
+    expect(output).not.toContain('defaultIsExpanded');
+  });
+});

package/assets/codemods/transforms/next/banner-collapsible-content.mjs

@@ -0,0 +1,171 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: migrate Banner's `defaultIsExpanded` onto `collapsible`
+ *
+ * Banner's collapse axis used to be a single knob, `defaultIsExpanded`, with
+ * the disclosure itself inferred from the presence of `children`. There was no
+ * way to have content without a toggle, and no controlled mode. The axis now
+ * lives on one `boolean | CollapsibleConfig` prop, per the boolean-or-config
+ * convention:
+ *
+ *   <Banner>{children}</Banner>                     → collapsible, starts closed
+ *   <Banner collapsible={{defaultIsOpen: true}}>    → collapsible, starts open
+ *   <Banner collapsible={{isOpen, onOpenChange}}>   → controlled
+ *   <Banner collapsible={false}>                    → always visible, no toggle
+ *
+ * The default is unchanged, so a Banner that never mentioned the old prop needs
+ * no rewrite at all — this transform is a prop rename and nothing more:
+ *
+ *   defaultIsExpanded            → collapsible={{defaultIsOpen: true}}
+ *   defaultIsExpanded={true}     → collapsible={{defaultIsOpen: true}}
+ *   defaultIsExpanded={false}    → (removed — it is the default)
+ *   defaultIsExpanded={expr}     → collapsible={{defaultIsOpen: expr}}
+ *
+ * Only elements named `Banner` are touched, and only when the file imports that
+ * name from `@astryxdesign/core`: `defaultIsExpanded` is also a ChatToolCalls
+ * prop, which this migration must leave alone.
+ *
+ * Scope: JSX attributes only. `defaultIsExpanded` inside a props object (a
+ * Storybook `args`, a spread built up in a variable) is left alone rather than
+ * rewritten on a guess about which component the object is for — removing the
+ * prop from the type makes those sites a type error, which is loud enough to
+ * find them.
+ */
+
+export const meta = {
+  title: "Rename Banner's `defaultIsExpanded` to the `collapsible` config",
+  description:
+    "Banner's collapse axis is now a single `collapsible?: boolean | " +
+    'CollapsibleConfig` prop. Rewrites `defaultIsExpanded` to the equivalent ' +
+    'config (`{defaultIsOpen: true}`), and drops ' +
+    '`defaultIsExpanded={false}`, which is the default. Banners that never ' +
+    'set the prop are untouched — the default is unchanged. Pass ' +
+    '`collapsible={false}` for content that is always visible.',
+  pr: '#5255',
+};
+
+const OLD_PROP = 'defaultIsExpanded';
+const NEW_PROP = 'collapsible';
+const COMPONENT = 'Banner';
+
+/**
+ * Does this file use the core `Banner`?
+ *
+ * `defaultIsExpanded` is a ChatToolCalls prop too, and a local component may
+ * well be called Banner, so an unqualified element-name match is not enough.
+ *
+ * @param {any} j
+ * @param {any} root
+ * @returns {boolean}
+ */
+function importsCoreBanner(j, root) {
+  let found = false;
+  root.find(j.ImportDeclaration).forEach((/** @type {any} */ path) => {
+    const source = path.node.source?.value;
+    if (typeof source !== 'string' || !source.startsWith('@astryxdesign/core')) {
+      return;
+    }
+    for (const spec of path.node.specifiers ?? []) {
+      if (
+        (spec.type === 'ImportSpecifier' && spec.imported?.name === COMPONENT) ||
+        (spec.local?.name === COMPONENT &&
+          (spec.type === 'ImportDefaultSpecifier' ||
+            spec.type === 'ImportSpecifier'))
+      ) {
+        found = true;
+      }
+    }
+  });
+  return found;
+}
+
+/**
+ * @param {import('../../../../authoring/codemod/type').AstryxCodemodFile} file
+ * @param {import('../../../../authoring/codemod/type').CodemodTransformApi} api
+ * @returns {string | null | undefined}
+ */
+export default function transformer(file, api) {
+  // Cheap bail-out: nothing to rename without the old prop.
+  if (!file.source.includes(OLD_PROP)) {
+    return undefined;
+  }
+
+  const j = api.jscodeshift;
+  const root = j(file.source);
+
+  if (!importsCoreBanner(j, root)) {
+    return undefined;
+  }
+
+  let hasChanges = false;
+
+  /** `collapsible={{defaultIsOpen: <expr>}}` */
+  const collapsibleWithDefault = (/** @type {any} */ expression) =>
+    j.jsxAttribute(
+      j.jsxIdentifier(NEW_PROP),
+      j.jsxExpressionContainer(
+        j.objectExpression([
+          j.objectProperty(j.identifier('defaultIsOpen'), expression),
+        ]),
+      ),
+    );
+
+  root.find(j.JSXOpeningElement).forEach((/** @type {any} */ path) => {
+    const name = path.node.name;
+    if (name?.type !== 'JSXIdentifier' || name.name !== COMPONENT) {
+      return;
+    }
+
+    const attrs = path.node.attributes ?? [];
+    const oldIndex = attrs.findIndex(
+      (/** @type {any} */ a) =>
+        a.type === 'JSXAttribute' && a.name?.name === OLD_PROP,
+    );
+    if (oldIndex === -1) {
+      return;
+    }
+
+    // Already migrated by hand, or a spread that may carry either prop:
+    // in both cases a rewrite would be guesswork.
+    const hasNewProp = attrs.some(
+      (/** @type {any} */ a) =>
+        a.type === 'JSXAttribute' && a.name?.name === NEW_PROP,
+    );
+    const hasSpread = attrs.some(
+      (/** @type {any} */ a) => a.type === 'JSXSpreadAttribute',
+    );
+    if (hasNewProp || hasSpread) {
+      return;
+    }
+
+    const value = attrs[oldIndex].value;
+
+    if (value == null) {
+      // Bare `defaultIsExpanded` — starts open.
+      attrs[oldIndex] = collapsibleWithDefault(j.booleanLiteral(true));
+    } else if (value.type === 'JSXExpressionContainer') {
+      const expression = value.expression;
+      const isBooleanLiteral =
+        expression.type === 'BooleanLiteral' ||
+        (expression.type === 'Literal' && typeof expression.value === 'boolean');
+      if (isBooleanLiteral && expression.value === false) {
+        // Starting closed is the default now, so the prop simply goes.
+        attrs.splice(oldIndex, 1);
+      } else if (isBooleanLiteral) {
+        attrs[oldIndex] = collapsibleWithDefault(j.booleanLiteral(true));
+      } else {
+        // A dynamic default stays dynamic.
+        attrs[oldIndex] = collapsibleWithDefault(expression);
+      }
+    } else {
+      // `defaultIsExpanded="something"` is not valid for a boolean prop;
+      // leave it for a human rather than inventing a meaning.
+      return;
+    }
+
+    hasChanges = true;
+  });
+
+  return hasChanges ? root.toSource({quote: 'single'}) : undefined;
+}

package/assets/codemods/transforms/next/index.mjs

@@ -7,4 +7,14 @@
  * this file into the resolved version folder.
  */
 
-export default [];
+import bannerCollapsibleContent, {
+  meta as bannerCollapsibleContentMeta,
+} from './banner-collapsible-content.mjs';
+
+export default [
+  {
+    name: 'banner-collapsible-content',
+    transform: bannerCollapsibleContent,
+    meta: bannerCollapsibleContentMeta,
+  },
+];

package/assets/templates/blocks/components/Banner/BannerCollapsibleContent.doc.mjs

@@ -6,7 +6,7 @@ export const doc = {
   exampleFor: 'Banner',
   name: 'Banner — Collapsible',
   displayName: 'Banner — Collapsible',
-  description: 'Combine an action button, dismiss control, and expandable detail area in one banner. Use for complex notifications like config changes or deployment summaries.',
+  description: 'Combine an action button, dismiss control, and a collapsible detail area in one banner. Children sit behind the toggle by default; `collapsible={{defaultIsOpen: true}}` starts it open, and `collapsible={false}` drops the toggle entirely. Use for complex notifications like config changes or deployment summaries.',
   isReady: true,
   aspectRatio: 16 / 9,
   componentsUsed: ['Banner', 'Button', 'List', 'Layout', 'Text'],

package/assets/templates/blocks/components/Banner/BannerCollapsibleContent.tsx

@@ -16,7 +16,7 @@ export default function BannerCollapsibleContent() {
       description="Review the changes before they take effect."
       endContent={<Button label="Review" variant="secondary" size="sm" />}
       isDismissable
-      defaultIsExpanded>
+      collapsible={{defaultIsOpen: true}}>
       <Stack direction="vertical" gap={2}>
         <Text type="supporting" color="secondary">
           Changed settings:

package/assets/templates/pages/table-grouped/page.tsx

@@ -37,6 +37,7 @@ import {Divider} from '@astryxdesign/core/Divider';
 import {MetadataList, MetadataListItem} from '@astryxdesign/core/MetadataList';
 import {
   Table,
+  TableBody,
   TableRow,
   TableCell,
   proportional,
@@ -963,161 +964,167 @@ export default function DataTableTemplate() {
                   />
                 ))}
               </colgroup>
-              {groupKeys.map(key => {
-                const tasks = grouped.get(key);
-                if (!tasks || tasks.length === 0) {
-                  return null;
-                }
-                const isExpanded = expandedGroups.has(key);
+              <TableBody>
+                {groupKeys.map(key => {
+                  const tasks = grouped.get(key);
+                  if (!tasks || tasks.length === 0) {
+                    return null;
+                  }
+                  const isExpanded = expandedGroups.has(key);
 
-                return (
-                  <React.Fragment key={key}>
-                    {groupBy !== 'none' && (
-                      <TableRow
-                        role="button"
-                        tabIndex={0}
-                        onClick={() => toggleGroup(key)}
-                        onKeyDown={e => {
-                          if (e.key === 'Enter' || e.key === ' ') {
-                            e.preventDefault();
-                            toggleGroup(key);
-                          }
-                        }}>
-                        <TableCell colSpan={COL_COUNT} style={groupHeaderCell}>
-                          <HStack gap={2} vAlign="center">
-                            <Icon
-                              icon={
-                                isExpanded ? ChevronDownIcon : ChevronRightIcon
-                              }
-                              size="sm"
-                              color="secondary"
-                            />
-                            <Text type="body" weight="bold">
-                              {getGroupLabel(groupBy, key)}
-                            </Text>
-                            <Badge
-                              variant="neutral"
-                              label={String(tasks.length)}
-                            />
-                          </HStack>
-                        </TableCell>
-                      </TableRow>
-                    )}
-                    {(groupBy === 'none' || isExpanded) &&
-                      tasks.map(task => (
+                  return (
+                    <React.Fragment key={key}>
+                      {groupBy !== 'none' && (
                         <TableRow
-                          key={task.id}
-                          onClick={() => setSelectedTask(task)}>
-                          <TableCell>
-                            <Center axis="horizontal">
-                              <StatusDot
-                                variant={STATUS_DOT_VARIANT[task.status]}
-                                label={STATUS_LABEL[task.status]}
-                              />
-                            </Center>
-                          </TableCell>
-                          <TableCell>
-                            <HStack gap={3} vAlign="center">
+                          role="button"
+                          tabIndex={0}
+                          onClick={() => toggleGroup(key)}
+                          onKeyDown={e => {
+                            if (e.key === 'Enter' || e.key === ' ') {
+                              e.preventDefault();
+                              toggleGroup(key);
+                            }
+                          }}>
+                          <TableCell
+                            colSpan={COL_COUNT}
+                            style={groupHeaderCell}>
+                            <HStack gap={2} vAlign="center">
                               <Icon
-                                icon={ChartBarIcon}
+                                icon={
+                                  isExpanded
+                                    ? ChevronDownIcon
+                                    : ChevronRightIcon
+                                }
                                 size="sm"
-                                color={PRIORITY_COLOR[task.priority]}
+                                color="secondary"
                               />
-                              <Text type="supporting" color="secondary">
-                                {task.taskId}
+                              <Text type="body" weight="bold">
+                                {getGroupLabel(groupBy, key)}
                               </Text>
-                              <Text type="body" maxLines={1}>
-                                {task.title}
-                              </Text>
-                              {task.subtitle && (
-                                <Text
-                                  type="body"
-                                  color="secondary"
-                                  maxLines={1}>
-                                  › {task.subtitle}
-                                </Text>
-                              )}
+                              <Badge
+                                variant="neutral"
+                                label={String(tasks.length)}
+                              />
                             </HStack>
                           </TableCell>
-                          <TableCell>
-                            {task.project ? (
-                              <Text type="body" maxLines={1}>
-                                {task.project}
+                        </TableRow>
+                      )}
+                      {(groupBy === 'none' || isExpanded) &&
+                        tasks.map(task => (
+                          <TableRow
+                            key={task.id}
+                            onClick={() => setSelectedTask(task)}>
+                            <TableCell>
+                              <Center axis="horizontal">
+                                <StatusDot
+                                  variant={STATUS_DOT_VARIANT[task.status]}
+                                  label={STATUS_LABEL[task.status]}
+                                />
+                              </Center>
+                            </TableCell>
+                            <TableCell>
+                              <HStack gap={3} vAlign="center">
+                                <Icon
+                                  icon={ChartBarIcon}
+                                  size="sm"
+                                  color={PRIORITY_COLOR[task.priority]}
+                                />
+                                <Text type="supporting" color="secondary">
+                                  {task.taskId}
+                                </Text>
+                                <Text type="body" maxLines={1}>
+                                  {task.title}
+                                </Text>
+                                {task.subtitle && (
+                                  <Text
+                                    type="body"
+                                    color="secondary"
+                                    maxLines={1}>
+                                    › {task.subtitle}
+                                  </Text>
+                                )}
+                              </HStack>
+                            </TableCell>
+                            <TableCell>
+                              {task.project ? (
+                                <Text type="body" maxLines={1}>
+                                  {task.project}
+                                </Text>
+                              ) : (
+                                <Text type="supporting" color="secondary">
+                                  —
+                                </Text>
+                              )}
+                            </TableCell>
+                            <TableCell>
+                              <Text type="supporting" color="secondary">
+                                {task.created}
                               </Text>
-                            ) : (
+                            </TableCell>
+                            <TableCell>
                               <Text type="supporting" color="secondary">
-                                —
+                                {task.updated}
                               </Text>
-                            )}
-                          </TableCell>
-                          <TableCell>
-                            <Text type="supporting" color="secondary">
-                              {task.created}
-                            </Text>
-                          </TableCell>
-                          <TableCell>
-                            <Text type="supporting" color="secondary">
-                              {task.updated}
-                            </Text>
-                          </TableCell>
-                          <TableCell>
-                            <Avatar name={task.assignee} size="sm" />
-                          </TableCell>
-                          <TableCell>
-                            <DropdownMenu
-                              button={{
-                                label: 'Actions',
-                                variant: 'ghost',
-                                size: 'sm',
-                                icon: (
-                                  <Icon
-                                    icon={EllipsisHorizontalIcon}
-                                    size="sm"
-                                  />
-                                ),
-                                isIconOnly: true,
-                              }}
-                              hasChevron={false}
-                              items={[
-                                {
-                                  label: 'Edit issue',
-                                  icon: PencilIcon,
-                                  onClick: () => {},
-                                },
-                                {
-                                  label: 'Assign to...',
-                                  icon: UserIcon,
-                                  onClick: () => {},
-                                },
-                                {
-                                  label: 'Add label',
-                                  icon: TagIcon,
-                                  onClick: () => {},
-                                },
-                                {
-                                  label: 'Duplicate',
-                                  icon: DocumentDuplicateIcon,
-                                  onClick: () => {},
-                                },
-                                {
-                                  label: 'Move to project',
-                                  icon: ArrowRightIcon,
-                                  onClick: () => {},
-                                },
-                                {type: 'divider' as const},
-                                {
-                                  label: 'Delete issue',
-                                  icon: TrashIcon,
-                                  onClick: () => {},
-                                },
-                              ]}
-                            />
-                          </TableCell>
-                        </TableRow>
-                      ))}
-                  </React.Fragment>
-                );
-              })}
+                            </TableCell>
+                            <TableCell>
+                              <Avatar name={task.assignee} size="sm" />
+                            </TableCell>
+                            <TableCell>
+                              <DropdownMenu
+                                button={{
+                                  label: 'Actions',
+                                  variant: 'ghost',
+                                  size: 'sm',
+                                  icon: (
+                                    <Icon
+                                      icon={EllipsisHorizontalIcon}
+                                      size="sm"
+                                    />
+                                  ),
+                                  isIconOnly: true,
+                                }}
+                                hasChevron={false}
+                                items={[
+                                  {
+                                    label: 'Edit issue',
+                                    icon: PencilIcon,
+                                    onClick: () => {},
+                                  },
+                                  {
+                                    label: 'Assign to...',
+                                    icon: UserIcon,
+                                    onClick: () => {},
+                                  },
+                                  {
+                                    label: 'Add label',
+                                    icon: TagIcon,
+                                    onClick: () => {},
+                                  },
+                                  {
+                                    label: 'Duplicate',
+                                    icon: DocumentDuplicateIcon,
+                                    onClick: () => {},
+                                  },
+                                  {
+                                    label: 'Move to project',
+                                    icon: ArrowRightIcon,
+                                    onClick: () => {},
+                                  },
+                                  {type: 'divider' as const},
+                                  {
+                                    label: 'Delete issue',
+                                    icon: TrashIcon,
+                                    onClick: () => {},
+                                  },
+                                ]}
+                              />
+                            </TableCell>
+                          </TableRow>
+                        ))}
+                    </React.Fragment>
+                  );
+                })}
+              </TableBody>
             </Table>
           </LayoutContent>
         }

package/foundation/discovery/theming-targets.d.mts

@@ -13,6 +13,23 @@
  * @returns {Promise<ThemingTarget[]>}
  */
 export function collectThemingTargets(coreSrc: string): Promise<ThemingTarget[]>;
+/**
+ * One public custom property a theme may set on a component's target.
+ * @typedef {object} ThemingVar
+ * @property {string} name - the custom property, e.g. `--tree-list-indent`
+ * @property {string} component - the component whose doc declares it
+ * @property {string} dir - absolute path to the directory the doc lives in
+ * @property {string} default - the documented default value
+ */
+/**
+ * Every PUBLIC theming var declared under a core `src` directory, sorted by
+ * name. Private `--_*` vars are a component's own plumbing, not a theme's to
+ * set, so they are not enumerated here.
+ *
+ * @param {string} coreSrc - absolute path to `<core>/src`
+ * @returns {Promise<ThemingVar[]>}
+ */
+export function collectThemingVars(coreSrc: string): Promise<ThemingVar[]>;
 /**
  * Collapse the enumeration into the `{key: [props and states]}` map theme
  * validation checks override keys against — both are legal override keys, so
@@ -46,3 +63,24 @@ export type ThemingTarget = {
      */
     states: string[];
 };
+/**
+ * One public custom property a theme may set on a component's target.
+ */
+export type ThemingVar = {
+    /**
+     * - the custom property, e.g. `--tree-list-indent`
+     */
+    name: string;
+    /**
+     * - the component whose doc declares it
+     */
+    component: string;
+    /**
+     * - absolute path to the directory the doc lives in
+     */
+    dir: string;
+    /**
+     * - the documented default value
+     */
+    default: string;
+};

package/foundation/discovery/theming-targets.mjs

@@ -108,6 +108,73 @@ export async function collectThemingTargets(coreSrc) {
   return targets;
 }
 
+/**
+ * One public custom property a theme may set on a component's target.
+ * @typedef {object} ThemingVar
+ * @property {string} name - the custom property, e.g. `--tree-list-indent`
+ * @property {string} component - the component whose doc declares it
+ * @property {string} dir - absolute path to the directory the doc lives in
+ * @property {string} default - the documented default value
+ */
+
+/**
+ * Every PUBLIC theming var declared under a core `src` directory, sorted by
+ * name. Private `--_*` vars are a component's own plumbing, not a theme's to
+ * set, so they are not enumerated here.
+ *
+ * @param {string} coreSrc - absolute path to `<core>/src`
+ * @returns {Promise<ThemingVar[]>}
+ */
+export async function collectThemingVars(coreSrc) {
+  if (!coreSrc || !fs.existsSync(coreSrc)) return [];
+
+  /** @type {Map<string, ThemingVar>} */
+  const vars = new Map();
+
+  /** @param {string} dir */
+  async function scan(dir) {
+    for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name)) continue;
+        await scan(full);
+        continue;
+      }
+      if (!entry.name.endsWith('.doc.mjs')) continue;
+
+      /** @type {any} */
+      let doc;
+      try {
+        doc = await loadComponentDoc(full);
+      } catch {
+        continue;
+      }
+
+      const component =
+        typeof doc?.name === 'string' && doc.name
+          ? doc.name
+          : path.basename(path.dirname(full));
+
+      for (const entryVar of doc?.theming?.vars || []) {
+        const name = entryVar?.name;
+        if (typeof name !== 'string') continue;
+        if (entryVar.private === true || name.startsWith('--_')) continue;
+        if (vars.has(name)) continue;
+        vars.set(name, {
+          name,
+          component,
+          dir: path.dirname(full),
+          default: typeof entryVar.default === 'string' ? entryVar.default : '',
+        });
+      }
+    }
+  }
+
+  await scan(coreSrc);
+
+  return [...vars.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
 /**
  * Collapse the enumeration into the `{key: [props and states]}` map theme
  * validation checks override keys against — both are legal override keys, so

package/foundation/discovery/theming-targets.test.mjs

@@ -10,9 +10,19 @@
  * while `theme targets` says another. That divergence is the failure the
  * listing exists to prevent: a target list that can drift from the components
  * is worse than no list.
+ *
+ * The public vars a target carries get the same treatment, one step further:
+ * being enumerable is not the same as being settable. A documented var no
+ * component reads compiles to a declaration that never applies (#5012), and a
+ * var the component writes inline outranks every cascade layer, so no theme can
+ * reach it (#4530). Both shipped. Neither is visible in the generated theme CSS
+ * — the artifact the jsdom suites assert on — so the wiring is checked here
+ * against source. Whether the cascade then lands the value on the element is a
+ * browser fact and no jsdom test can stand in for it.
  */
 
 import {describe, it, expect} from 'vitest';
+import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {findCoreDir} from '../fs/paths.mjs';
 import {
@@ -20,7 +30,11 @@ import {
   findComponentReadme,
 } from './component-discovery.mjs';
 import {loadComponentDoc} from './component-loader.mjs';
-import {collectThemingTargets, targetsByKey} from './theming-targets.mjs';
+import {
+  collectThemingTargets,
+  collectThemingVars,
+  targetsByKey,
+} from './theming-targets.mjs';
 
 const coreDir = /** @type {string} */ (findCoreDir(process.cwd()));
 const coreSrc = path.join(coreDir, 'src');
@@ -125,3 +139,107 @@ describe('collectThemingTargets', () => {
     expect(missing).toEqual([]);
   }, 60_000);
 });
+
+// ---------------------------------------------------------------------------
+// Public vars — enumerable is not the same as settable
+// ---------------------------------------------------------------------------
+
+/** @type {Promise<import('./theming-targets.mjs').ThemingVar[]>} */
+const enumeratedVars = collectThemingVars(coreSrc);
+
+/** Every non-test source file under a component directory. */
+function sourcesIn(dir) {
+  /** @type {string[]} */
+  const out = [];
+  for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules' || entry.name === '__tests__') continue;
+      out.push(...sourcesIn(path.join(dir, entry.name)));
+      continue;
+    }
+    if (!/\.tsx?$/.test(entry.name)) continue;
+    if (/\.(test|stories)\.tsx?$/.test(entry.name)) continue;
+    out.push(path.join(dir, entry.name));
+  }
+  return out;
+}
+
+/**
+ * The text of every inline style a file writes — `style={{…}}` objects and
+ * `setProperty` calls. A custom property written from either outranks every
+ * cascade layer, so a theme cannot reach it.
+ */
+function inlineStyleText(src) {
+  const chunks = [];
+  for (const m of src.matchAll(/style=\{\{/g)) {
+    const end = src.indexOf('}}', m.index);
+    chunks.push(src.slice(m.index, end === -1 ? src.length : end));
+  }
+  for (const m of src.matchAll(/setProperty\(\s*'[^']+'/g)) chunks.push(m[0]);
+  return chunks.join('\n');
+}
+
+describe('collectThemingVars', () => {
+  it('enumerates the public vars and drops the private plumbing', async () => {
+    const names = (await enumeratedVars).map(v => v.name);
+    expect(names.length).toBeGreaterThan(0);
+    expect(names.every(n => !n.startsWith('--_'))).toBe(true);
+    expect(names).toEqual([...names].sort((a, b) => a.localeCompare(b)));
+    expect(names).toEqual([...new Set(names)]);
+  });
+
+  it('carries the component and the documented default', async () => {
+    const indent = (await enumeratedVars).find(
+      v => v.name === '--tree-list-indent',
+    );
+    expect(indent).toMatchObject({
+      name: '--tree-list-indent',
+      component: 'TreeList',
+      default: 'var(--spacing-4)',
+    });
+  });
+
+  // #5012: the theme docs advertised `--button-press-scale`, which no component
+  // ever read. A theme setting it compiled to a declaration nothing consumed,
+  // and nothing failed — the var was in the docs, so every existence check
+  // passed. Reading it is the minimum that makes a documented var mean anything.
+  it('every documented var is read by the component that documents it', async () => {
+    /** @type {string[]} */
+    const unread = [];
+    for (const v of await enumeratedVars) {
+      const read = sourcesIn(v.dir).some(f =>
+        fs.readFileSync(f, 'utf-8').includes(`var(${v.name}`),
+      );
+      if (!read) unread.push(`${v.component}: nothing reads var(${v.name})`);
+    }
+    expect(
+      unread,
+      `A documented public var no component reads compiles to a declaration ` +
+        `that never applies (#5012). Either wire it up or drop it from the doc.`,
+    ).toEqual([]);
+  });
+
+  // #4530: TreeList's indent was an inline `margin-inline-start` on the element
+  // carrying the theme target. An inline declaration outranks every cascade
+  // layer, so `@layer astryx-theme` could not reach it — the var was real, read,
+  // and documented, and still unsettable. The fix moved it into a StyleX rule.
+  it('no documented var is written inline, where no theme can outrank it', async () => {
+    /** @type {string[]} */
+    const clobbered = [];
+    for (const v of await enumeratedVars) {
+      for (const f of sourcesIn(v.dir)) {
+        if (inlineStyleText(fs.readFileSync(f, 'utf-8')).includes(v.name)) {
+          clobbered.push(
+            `${v.component}: ${path.basename(f)} sets ${v.name} inline`,
+          );
+        }
+      }
+    }
+    expect(
+      clobbered,
+      `An inline custom property beats every cascade layer, so a theme setting ` +
+        `it through @layer astryx-theme is silently ignored (#4530). Declare it ` +
+        `in a StyleX rule instead.`,
+    ).toEqual([]);
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.4.7-canary.a7bedb2",
+  "version": "0.4.7-canary.b6c0501",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -87,10 +87,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/charts": "0.4.7-canary.a7bedb2",
-    "@astryxdesign/core": "0.4.7-canary.a7bedb2",
-    "@astryxdesign/lab": "0.4.7-canary.a7bedb2",
-    "@astryxdesign/theme-neutral": "0.4.7-canary.a7bedb2",
+    "@astryxdesign/charts": "0.4.7-canary.b6c0501",
+    "@astryxdesign/core": "0.4.7-canary.b6c0501",
+    "@astryxdesign/lab": "0.4.7-canary.b6c0501",
+    "@astryxdesign/theme-neutral": "0.4.7-canary.b6c0501",
     "gpt-tokenizer": "^3.4.0"
   },
   "peerDependenciesMeta": {
@@ -108,10 +108,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.4.7-canary.a7bedb2",
-    "@astryxdesign/core": "0.4.7-canary.a7bedb2",
-    "@astryxdesign/lab": "0.4.7-canary.a7bedb2",
-    "@astryxdesign/theme-neutral": "0.4.7-canary.a7bedb2",
+    "@astryxdesign/charts": "0.4.7-canary.b6c0501",
+    "@astryxdesign/core": "0.4.7-canary.b6c0501",
+    "@astryxdesign/lab": "0.4.7-canary.b6c0501",
+    "@astryxdesign/theme-neutral": "0.4.7-canary.b6c0501",
     "gpt-tokenizer": "^3.4.0"
   },
   "scripts": {