@astryxdesign/cli 0.7.2-canary.db3a2e7 → 0.7.2-canary.ebcc404

package/assets/templates/blocks/components/DrawerHeader/DrawerHeaderWithCloseButton.tsx

@@ -0,0 +1,42 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @input Controlled open state for a modal Drawer
+ * @output A Drawer whose DrawerHeader renders a close button because it receives onOpenChange
+ * @position Copyable DrawerHeader example
+ */
+
+import {useState} from 'react';
+import {Drawer, DrawerHeader} from '@astryxdesign/core/Drawer';
+import {Button} from '@astryxdesign/core/Button';
+import {Layout, LayoutContent} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+
+export default function DrawerHeaderWithCloseButton() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <>
+      <Button label="Open drawer" onClick={() => setIsOpen(true)} />
+      <Drawer
+        isOpen={isOpen}
+        onOpenChange={setIsOpen}
+        label="Details"
+        width={360}>
+        <Layout
+          header={<DrawerHeader title="Details" onOpenChange={setIsOpen} />}
+          content={
+            <LayoutContent>
+              <Text type="body">
+                Passing onOpenChange renders the close button, which calls it
+                with false.
+              </Text>
+            </LayoutContent>
+          }
+        />
+      </Drawer>
+    </>
+  );
+}

package/assets/templates/pages/detail-page/page.tsx

@@ -600,9 +600,9 @@ export default function DetailPage2Template() {
         }
         end={!isNarrow && showSidePanel ? <RightPanel /> : undefined}
       />
-      {/* Mobile: the side panel content opens as a full-screen dialog. (A
-          side drawer/sheet would be more idiomatic, but Astryx has no Drawer
-          component yet — #2575 — so we use the fullscreen Dialog variant.) */}
+      {/* Mobile: the side-panel content uses the full viewport so order details
+          are not squeezed beside narrow page chrome. Drawer remains available
+          for side-overlay flows that intentionally preserve page context. */}
       <Dialog
         variant="fullscreen"
         isOpen={isNarrow && isPanelDialogOpen}

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

@@ -1652,8 +1652,8 @@ const COMPOSER_TOOLS: {
 /**
  * The compose sheet.
  *
- * **`BottomSheet hasScrim={false}`, which is the only non-modal surface in
- * core.** With the scrim off the sheet opens with `show()` rather than
+ * **`BottomSheet hasScrim={false}` keeps this bottom-edge composer non-modal.**
+ * With the scrim off the sheet opens with `show()` rather than
  * `showModal()`, so it never enters the top layer, never makes the page inert
  * and never locks body scroll: the inbox behind it stays live. That matters
  * more here than anywhere else in this template, because writing a message is
@@ -1661,12 +1661,14 @@ const COMPOSER_TOOLS: {
  * actually said, copy an order number out of a thread. A modal composer
  * answers that with "close me first".
  *
- * The trade is position, and it is worth naming. A sheet rises from the bottom
- * edge, centred: its positioner is `inset-inline: 0` with
- * `justify-content: center`, and there is no anchor, side or width prop. So
- * this cannot be docked to the inline-end corner the way a `Dialog` can be.
- * `Dialog` takes a static `position` and would put the window in that corner —
- * but `Dialog` is always modal, so buying the corner costs the live inbox.
+ * The trade is bottom-edge geometry, and it is worth naming. A non-modal
+ * `Drawer` keeps page context live from an inline edge, but it is a full-height
+ * side panel; this composer intentionally rises from the bottom. A sheet's
+ * positioner is `inset-inline: 0` with `justify-content: center`, and there is
+ * no anchor, side or width prop. So this cannot be docked to the inline-end
+ * corner the way a `Dialog` can be. `Dialog` takes a static `position` and would
+ * put the window in that corner — but `Dialog` is always modal, so buying the
+ * corner costs the live inbox.
  * `ChatComposerDrawer` is a false friend: despite the name it is an in-flow
  * disclosure tray for a ChatComposer's attachments, with no positioning of its
  * own.

package/authoring/doctypes/base/type.ts

@@ -383,6 +383,12 @@ export interface ComponentPropDoc {
    *  ```
    */
   slotElements?: ComponentSlotElement[];
+  /** Lifecycle marker for a prop outside the stable compatibility promise
+   *  (spec:AST-017 FR21). Set `'experimental'` on a stable component's
+   *  optional `experimental` prop object, and say in `description` that its
+   *  contents may change or be removed in a patch release. Omit for stable
+   *  props. */
+  stability?: 'experimental';
 }
 
 /**

package/authoring/doctypes/component/component.doc.mjs

@@ -30,7 +30,7 @@ export const doc = {
       name: 'name',
       type: 'string',
       description:
-        "Stable machine identity and directory name without the Astryx prefix, PascalCase. e.g. 'Button', 'TextInput', 'AppShell'. Change `displayName`, not `name`, to edit the visible label; registry URLs derive from this identity by default.",
+        "Stable machine identity and directory name without the Astryx prefix, PascalCase. e.g. 'Button', 'TextInput', 'AppShell'. For an integration component it is the export apps import: the doc sits beside the file that exports it, and when that file exports nothing under its own name, `name` may name the export it does have. Change `displayName`, not `name`, to edit the visible label; registry URLs derive from this identity by default.",
       required: true,
     },
     {
@@ -56,7 +56,7 @@ export const doc = {
       name: 'replaces',
       type: 'string',
       description:
-        "Integration components only: the exact `name` of the Core ComponentDoc this component takes over for unqualified lookup, so every app that loads the integration gets it from component detail, component lists, search, `swizzle <Name>`, and issue routing; `swizzle --list` keeps listing Core names. The Core original stays reachable with `--package @astryxdesign/core`. It takes effect only when the package's peer range starts at the release that applies it, `\"@astryxdesign/cli\": \">=0.6.7\"` or later; without such a range the component keeps its own name and `doctor integration components` warns. Set it only to intentionally own a Core identity; give an alternative or variant its own name instead.",
+        'Integration components only: the exact `name` of the Core ComponentDoc this component takes over for unqualified lookup, so every app that loads the integration gets it from component detail, component lists, search, `swizzle <Name>`, and issue routing; `swizzle --list` keeps listing Core names. The Core original stays reachable with `--package @astryxdesign/core`. It takes effect only when the package\'s peer range starts at the release that applies it, `"@astryxdesign/cli": ">=0.6.7"` or later; without such a range the component keeps its own name and `doctor integration components` warns. Set it only to intentionally own a Core identity; give an alternative or variant its own name instead.',
     },
     {
       name: 'keywords',
@@ -181,7 +181,7 @@ export const doc = {
       name: 'props',
       type: 'ComponentPropDoc[]',
       description:
-        'SingleComponentDoc variant (required there): all public props for the one primary component. Each prop is {name, type, description, default?, required?, slotElements?}. Skip styling props like xstyle/className/style. Also present on SubComponentDoc.',
+        'SingleComponentDoc variant (required there): all public props for the one primary component. Each prop is {name, type, description, default?, required?, slotElements?, stability?}. Skip styling props like xstyle/className/style. Also present on SubComponentDoc.',
     },
     {
       name: 'components',

package/authoring/doctypes/component/type.ts

@@ -33,9 +33,12 @@ export interface ComponentBaseDoc extends AuthoredDocGraphFields {
   type?: 'component';
   /**
    * Stable machine identity and directory name without the Astryx prefix,
-   * PascalCase (for example `Button`, `Table`, or `AppShell`). Do not change
-   * this to edit the visible label; use `displayName` for that. Registry URLs
-   * derive from this value by default.
+   * PascalCase (for example `Button`, `Table`, or `AppShell`). For an
+   * integration component it is the export apps import: the doc sits beside
+   * the file that exports it, and when that file exports nothing under its own
+   * name, `name` may name the export it does have. Do not change this to edit
+   * the visible label; use `displayName` for that. Registry URLs derive from
+   * this value by default.
    */
   name: string;
   /** Human-readable display name with spaces between words, used by the

package/clients/cli/commands/build-theme.path-safety.test.mjs

@@ -9,6 +9,9 @@
  *   - Multi-file write is atomic: if one file fails, none are left behind.
  *   - An `--out` escape, or an output directory that cannot be created, fails
  *     with a registered error code.
+ *   - Every output stays inside the working directory: an absolute `--out`
+ *     path or a theme file outside it fails before anything is written, while
+ *     absolute paths inside it build, also through a symlinked spelling.
  *
  * Runs the CLI in-process (shared runCli harness) against a tiny synthetic theme file.
  */
@@ -129,6 +132,68 @@ describe('theme build output-path failures carry registered codes', () => {
     expect(fs.existsSync(path.join(tmpDir, 'escaped.css'))).toBe(false);
   });
 
+  it('reports an absolute --out path outside the project as ERR_PATH_TRAVERSAL, with --check too', async () => {
+    const project = path.join(tmpDir, 'project');
+    const outside = path.join(tmpDir, 'outside');
+    fs.mkdirSync(outside, {recursive: true});
+    const themeFile = writeTheme(path.join(project, 'themes'), 'ocean');
+    const out = path.join(outside, 'ocean.css');
+
+    for (const extra of [[], ['--check']]) {
+      const {result, envelope} = await buildJson(
+        [path.relative(project, themeFile), '--out', out, ...extra],
+        project,
+      );
+
+      expect(result.code).toBe(1);
+      expect(envelope.code).toBe(ERROR_CODES.ERR_PATH_TRAVERSAL);
+    }
+    expect(fs.readdirSync(outside)).toEqual([]);
+  });
+
+  it('reports a theme file outside the project as ERR_PATH_TRAVERSAL, because its outputs go beside it', async () => {
+    const project = path.join(tmpDir, 'project');
+    fs.mkdirSync(project, {recursive: true});
+    const shared = path.join(tmpDir, 'shared');
+    const themeFile = writeTheme(shared, 'ocean');
+
+    for (const file of [themeFile, path.relative(project, themeFile)]) {
+      const {result, envelope} = await buildJson([file], project);
+
+      expect(result.code).toBe(1);
+      expect(envelope.code).toBe(ERROR_CODES.ERR_PATH_TRAVERSAL);
+    }
+    expect(fs.readdirSync(shared)).toEqual(['theme.mjs']);
+  });
+
+  it('builds absolute paths inside the project, also when they reach it through a symlink', async () => {
+    const project = path.join(tmpDir, 'project');
+    const themeFile = writeTheme(path.join(project, 'themes'), 'ocean');
+    const alias = path.join(tmpDir, 'alias');
+    fs.symlinkSync(project, alias, 'dir');
+
+    for (const [args, written] of [
+      [
+        [themeFile, '--out', path.join(project, 'dist', 'direct.css')],
+        path.join(project, 'dist', 'direct.css'),
+      ],
+      [
+        [themeFile, '--out', path.join(alias, 'dist', 'aliased.css')],
+        path.join(project, 'dist', 'aliased.css'),
+      ],
+      [
+        [path.join(alias, 'themes', 'theme.mjs')],
+        path.join(project, 'themes', 'ocean.css'),
+      ],
+    ]) {
+      const {result, envelope} = await buildJson(args, project);
+
+      expect(result.code).toBe(0);
+      expect(envelope.type).toBe('theme.build');
+      expect(fs.existsSync(written)).toBe(true);
+    }
+  });
+
   it('reports an --out path that escapes through a symlink as ERR_PATH_TRAVERSAL', async () => {
     const project = path.join(tmpDir, 'project');
     const outside = path.join(tmpDir, 'outside');
@@ -177,4 +242,23 @@ describe('theme build output-path failures carry registered codes', () => {
       code: ERROR_CODES.ERR_PATH_TRAVERSAL,
     });
   });
+
+  it('themeBuild() rejects an output outside cwd: an absolute out path, or the default beside a theme file outside cwd', async () => {
+    const project = path.join(tmpDir, 'project');
+    const inside = writeTheme(path.join(project, 'themes'), 'ocean');
+    const shared = path.join(tmpDir, 'shared');
+    const outsideTheme = writeTheme(shared, 'ocean');
+    const outDir = path.join(tmpDir, 'out');
+
+    for (const [file, options] of [
+      [path.relative(project, inside), {out: path.join(outDir, 'ocean.css')}],
+      [outsideTheme, {}],
+    ]) {
+      await expect(
+        themeBuild(file, options, {cwd: project}),
+      ).rejects.toMatchObject({code: ERROR_CODES.ERR_PATH_TRAVERSAL});
+    }
+    expect(fs.existsSync(outDir)).toBe(false);
+    expect(fs.readdirSync(shared)).toEqual(['theme.mjs']);
+  });
 });

package/clients/cli/commands/build-theme.registry.test.mjs

@@ -126,7 +126,10 @@ describe('theme build emits a live TextInput selector (#4109)', () => {
         `};\n`,
     );
 
-    const result = await runCli(['theme', 'build', themeFile, '-o', outFile]);
+    const result = await runCli(
+      ['theme', 'build', themeFile, '-o', outFile],
+      tmpDir,
+    );
     const css = fs.readFileSync(outFile, 'utf8');
 
     expect(result.status).toBe(0);
@@ -148,7 +151,7 @@ describe('theme build emits a live TextInput selector (#4109)', () => {
         `};\n`,
     );
 
-    await runCli(['theme', 'build', themeFile, '-o', outFile]);
+    await runCli(['theme', 'build', themeFile, '-o', outFile], tmpDir);
     const css = fs.readFileSync(outFile, 'utf8');
 
     expect(css).toContain('.astryx-text-input');

package/clients/cli/commands/theme-build.doc.mjs

@@ -30,7 +30,7 @@ export const doc = {
     {
       flag: '--family',
       description:
-        'Build the selected extension family into one keyed CSS, JS, and declaration set. Requires --family-key; refused with --out or --watch (ERR_THEME_INVALID)',
+        'Build the selected extension family into one keyed CSS, JS, and declaration set, written beside the family root theme file, which must be inside the working directory (ERR_PATH_TRAVERSAL). Requires --family-key; refused with --out or --watch (ERR_THEME_INVALID)',
     },
     {
       flag: '--family-key <key>',
@@ -41,7 +41,7 @@ export const doc = {
       flag: '-o, --out <path>',
       param: 'options.out',
       description:
-        'Output CSS file path; the .js and .d.ts are written beside it (default: <theme name>.css next to the source). A relative path must stay inside the working directory. Single theme only: refused with more than one file or with --family (ERR_THEME_INVALID)',
+        'Output CSS file path, relative or absolute; the .js and .d.ts are written beside it (default: <theme name>.css next to the source). Every output must resolve inside the working directory, the defaults beside the source too (ERR_PATH_TRAVERSAL). Single theme only: refused with more than one file or with --family (ERR_THEME_INVALID)',
     },
     {
       flag: '--icons-specifier <specifier>',

package/clients/cli/lib/component-format.mjs

@@ -68,8 +68,12 @@ function formatPropsTable(props) {
   for (const p of props) {
     const def = p.default ? `\`${mdCell(p.default)}\`` : '-';
     const req = p.required ? ' **(required)**' : '';
+    // The text projection of the prop doc's `stability` field: an
+    // experimental prop is outside the stable compatibility promise.
+    const stability =
+      p.stability === 'experimental' ? ' **(experimental)**' : '';
     lines.push(
-      `| \`${mdCell(p.name)}\` | \`${mdCell(p.type)}\` | ${def} | ${mdCell(p.description)}${req} |`,
+      `| \`${mdCell(p.name)}\` | \`${mdCell(p.type)}\` | ${def} | ${mdCell(p.description)}${req}${stability} |`,
     );
   }
   return lines.join('\n');

package/foundation/discovery/component-discovery.d.mts

@@ -1,8 +1,20 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
+/**
+ * The entry a family doc gives `name` in its `components`, when the doc is not
+ * the component's own (Stack's doc for VStack); null otherwise.
+ * @param {any} docs - a loaded component doc
+ * @param {string} name - bare component name
+ * @returns {any}
+ */
+export function familyMember(docs: any, name: string): any;
 /**
  * Auto-discover components by scanning for Astryx*.tsx files in core/src/.
+ * A component is listed when a doc documents it: a doc in its folder, or, for a
+ * component folder with no doc of its own, the doc `findComponentReadme` finds
+ * elsewhere (Heading's doc in the Text folder; HStack and VStack as members of
+ * Stack's doc).
  *
  * Returns an ordered Record where:
  * - Grouped components use the group name as key: `'Buttons': ['Button', 'IconButton']`
@@ -103,19 +115,36 @@ export function discoverExternalComponentsGrouped(docsDir: string): Record<strin
  * @returns {string | null}
  */
 export function findExternalComponentDoc(docsDir: string, name: string): string | null;
+/** @param {string} docPath */
+export function docStem(docPath: string): string;
+/**
+ * Visit every component doc under an integration's components root, hidden
+ * ones included, in discovery order, with its stem.
+ * @param {string | undefined} componentsDir
+ * @param {(docPath: string, stem: string) => void} visit
+ */
+export function forEachIntegrationDoc(componentsDir: string | undefined, visit: (docPath: string, stem: string) => void): void;
 /**
  * Discover ownership records for the components contributed by a single loaded
  * integration. Scans the integration's resolved `components` dir for same-stem
- * doc files and records each with owner package + issuesUrl + sourcePath.
+ * doc files and records each with owner package + issuesUrl + sourcePath. A doc
+ * that names a differently named export of its file is recorded under that
+ * export unless the name is taken: every doc's file name (a hidden doc's too),
+ * a Core name a doc in the package replaces, and a name an earlier doc records.
  *
  * @param {{name: string, components?: string, issuesUrl?: string}} integration
  *   a single entry from `loadedIntegrations` (lib/integrations.mjs)
+ * @param {{documentedNames?: boolean}} [options] `documentedNames: false`
+ *   records each doc under its file name alone, without reading the names
+ *   docs document: for a caller that needs only what each doc says
  * @returns {Array<{name: string, package: string, docPath: string, sourcePath: string|null, issuesUrl: string|undefined, group: string|null}>}
  */
 export function discoverIntegrationComponents(integration: {
     name: string;
     components?: string;
     issuesUrl?: string;
+}, { documentedNames }?: {
+    documentedNames?: boolean;
 }): Array<{
     name: string;
     package: string;
@@ -129,9 +158,12 @@ export function discoverIntegrationComponents(integration: {
  * Invalid metadata or a missing same-stem source removes only that component;
  * callers can report the returned errors while retaining valid siblings. A
  * component whose doc sets `replaces` carries the value as written; the
- * component replacement resolver decides what it means.
+ * component replacement resolver decides what it means. A doc that fails to
+ * load is reported under its file name: what it says cannot be trusted.
  *
  * @param {{name: string, components?: string, issuesUrl?: string}} integration
+ * @param {{documentedNames?: boolean}} [options] as for
+ *   {@link discoverIntegrationComponents}
  * @returns {Promise<{
  *   components: Array<{name: string, package: string, docPath: string, sourcePath: string, issuesUrl: string|undefined, group: string|null, replaces?: unknown}>,
  *   discovered: Array<{name: string, package: string, docPath: string, sourcePath: string|null, issuesUrl: string|undefined, group: string|null}>,
@@ -142,6 +174,8 @@ export function discoverValidIntegrationComponents(integration: {
     name: string;
     components?: string;
     issuesUrl?: string;
+}, options?: {
+    documentedNames?: boolean;
 }): Promise<{
     components: Array<{
         name: string;
@@ -165,10 +199,43 @@ export function discoverValidIntegrationComponents(integration: {
         message: string;
     }>;
 }>;
+/**
+ * How an owner holds a component name, which the owner rule
+ * ({@link unscopedComponentOwners}) reads: `core` when Core documents it;
+ * `file` when an integration doc named after its file is recorded under it;
+ * `doc` when only a doc records it: an export name, or the file name of a doc
+ * recorded under another export.
+ * @typedef {'core' | 'file' | 'doc'} NameHold
+ */
+/**
+ * How a discovered integration record holds its name.
+ * @param {{name: string, docPath: string|null}} record
+ * @returns {'file' | 'doc'}
+ */
+export function integrationRecordHold(record: {
+    name: string;
+    docPath: string | null;
+}): "file" | "doc";
+/**
+ * The integration component a name finds, as discovery records it, and its
+ * hold: the same-stem doc first, then a doc that records the name.
+ *
+ * @param {{components?: string}} integration
+ * @param {string} name
+ * @returns {{docPath: string, sourcePath: string|null, hold: 'file' | 'doc'} | null}
+ */
+export function findIntegrationComponent(integration: {
+    components?: string;
+}, name: string): {
+    docPath: string;
+    sourcePath: string | null;
+    hold: "file" | "doc";
+} | null;
 /**
  * Find an integration component's doc file by name within a loaded
  * integration's resolved `components` dir. Honors the same-stem convention
- * (`{Name}.doc.{ts,mjs,js}`), preferring `.ts` → `.mjs` → `.js`.
+ * (`{Name}.doc.{ts,mjs,js}`), preferring `.ts` → `.mjs` → `.js`, and finds a
+ * doc that records the component under a differently named export of its file.
  *
  * @param {{components?: string}} integration
  * @param {string} name bare component name (no `XDS`/`Astryx` prefix)
@@ -178,9 +245,9 @@ export function findIntegrationComponentDoc(integration: {
     components?: string;
 }, name: string): string | null;
 /**
- * Find an integration component's swizzleable source file (`{Name}.tsx`) by
- * name within a loaded integration's resolved `components` dir. Returns null
- * when the integration ships docs without source.
+ * Find an integration component's swizzleable source file by name within a
+ * loaded integration's resolved `components` dir: the same-stem `{Name}.tsx`
+ * of its doc. Returns null when the integration ships docs without source.
  *
  * @param {{components?: string}} integration
  * @param {string} name bare component name
@@ -189,6 +256,20 @@ export function findIntegrationComponentDoc(integration: {
 export function findIntegrationComponentSource(integration: {
     components?: string;
 }, name: string): string | null;
+/**
+ * The owner rule: an owner that holds a name only because a doc records it
+ * (`hold: 'doc'`) yields to Core and to every file-named owner; `--package`
+ * still reaches it. Surfaces resolve a replacement first, then this rule, then
+ * which docs load.
+ *
+ * @template {{hold?: string}} T
+ * @param {T[]} owners each with its {@link NameHold}; an owner without one
+ *   counts as Core's or file-named
+ * @returns {T[]}
+ */
+export function unscopedComponentOwners<T extends {
+    hold?: string;
+}>(owners: T[]): T[];
 /**
  * Build a flat list of ownership records for ALL discoverable components —
  * core (built-in) plus every loaded integration. This is the authoritative
@@ -217,3 +298,11 @@ export function discoverOwnedComponents(coreDir: string, loadedIntegrations?: Ar
 }>;
 /** The owner package name for built-in (core) components. */
 export const CORE_PACKAGE: import("../../authoring/index.js").ProviderId;
+/**
+ * How an owner holds a component name, which the owner rule
+ * ({@link unscopedComponentOwners}) reads: `core` when Core documents it;
+ * `file` when an integration doc named after its file is recorded under it;
+ * `doc` when only a doc records it: an export name, or the file name of a doc
+ * recorded under another export.
+ */
+export type NameHold = "core" | "file" | "doc";