@astryxdesign/cli 0.7.2-canary.f16dc9f → 0.7.2-canary.fe2c655

package/api/component/component.test.mjs

@@ -17,217 +17,390 @@ import {AstryxError} from '../error.mjs';
 import {runCli} from '../../test-utils/run-cli.mjs';
 
 // api/component/ -> up 4 = repo root (has packages/core, which findCoreDir walks to).
-const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');
+const REPO = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../../..',
+);
 const cwd = REPO;
 const SLOW = 30_000;
 
 describe('component dispatcher — routing', () => {
-  it('routes a bare name to component.detail', async () => {
-    const r = await component('Button', {cwd});
-    expect(r.type).toBe('component.detail');
-    expect(r.data.name).toBe('Button');
-  }, SLOW);
-
-  it('routes no-name to the list leaf (component.list, detail=names)', async () => {
-    const r = await component(undefined, {cwd});
-    expect(r.type).toBe('component.list');
-    expect(r.data.detail).toBe('names');
-    expect(Object.keys(r.data.components).length).toBeGreaterThan(0);
-  }, SLOW);
-
-  it('routes --category to the list leaf, filtered to that group', async () => {
-    const r = await component(undefined, {cwd, category: 'Layout'});
-    expect(r.type).toBe('component.list');
-    expect(Object.keys(r.data.components)).toContain('Layout');
-  }, SLOW);
-
-  it('treats an empty-string name as a list (not a not-found error)', async () => {
-    const r = await component('', {cwd});
-    expect(r.type).toBe('component.list');
-  }, SLOW);
+  it(
+    'routes a bare name to component.detail',
+    async () => {
+      const r = await component('Button', {cwd});
+      expect(r.type).toBe('component.detail');
+      expect(r.data.name).toBe('Button');
+    },
+    SLOW,
+  );
+
+  it(
+    'routes no-name to the list leaf (component.list, detail=names)',
+    async () => {
+      const r = await component(undefined, {cwd});
+      expect(r.type).toBe('component.list');
+      expect(r.data.detail).toBe('names');
+      expect(Object.keys(r.data.components).length).toBeGreaterThan(0);
+    },
+    SLOW,
+  );
+
+  it(
+    'routes --category to the list leaf, filtered to that group',
+    async () => {
+      const r = await component(undefined, {cwd, category: 'Layout'});
+      expect(r.type).toBe('component.list');
+      expect(Object.keys(r.data.components)).toContain('Layout');
+    },
+    SLOW,
+  );
+
+  it(
+    'treats an empty-string name as a list (not a not-found error)',
+    async () => {
+      const r = await component('', {cwd});
+      expect(r.type).toBe('component.list');
+    },
+    SLOW,
+  );
 });
 
 describe('component dispatcher — detail levels on list', () => {
-  it('--detail compact lists with detail=compact', async () => {
-    const r = await component(undefined, {cwd, list: true, detail: 'compact'});
-    expect(r.type).toBe('component.list');
-    expect(r.data.detail).toBe('compact');
-  }, SLOW);
-
-  it('--detail full lists with detail=full', async () => {
-    const r = await component(undefined, {cwd, list: true, detail: 'full'});
-    expect(r.type).toBe('component.list');
-    expect(r.data.detail).toBe('full');
-  }, SLOW);
+  it(
+    '--detail compact lists with detail=compact',
+    async () => {
+      const r = await component(undefined, {
+        cwd,
+        list: true,
+        detail: 'compact',
+      });
+      expect(r.type).toBe('component.list');
+      expect(r.data.detail).toBe('compact');
+    },
+    SLOW,
+  );
+
+  it(
+    '--detail full lists with detail=full',
+    async () => {
+      const r = await component(undefined, {cwd, list: true, detail: 'full'});
+      expect(r.type).toBe('component.list');
+      expect(r.data.detail).toBe('full');
+    },
+    SLOW,
+  );
 });
 
 describe('component dispatcher — projection precedence (locked)', () => {
-  it('--props routes to component.detail.props', async () => {
-    const r = await component('Button', {cwd, props: true});
-    expect(r.type).toBe('component.detail.props');
-  }, SLOW);
-
-  it('--source routes to component.detail.source', async () => {
-    const r = await component('Button', {cwd, source: true});
-    expect(r.type).toBe('component.detail.source');
-  }, SLOW);
-
-  it('--source WINS over --props when both are set (precedence lock)', async () => {
-    const r = await component('Button', {cwd, props: true, source: true});
-    expect(r.type).toBe('component.detail.source');
-  }, SLOW);
-
-  it('--list WINS over a given name (list dispatch precedence lock)', async () => {
-    const r = await component('Button', {cwd, list: true});
-    expect(r.type).toBe('component.list');
-  }, SLOW);
+  it(
+    '--props routes to component.detail.props',
+    async () => {
+      const r = await component('Button', {cwd, props: true});
+      expect(r.type).toBe('component.detail.props');
+    },
+    SLOW,
+  );
+
+  it(
+    '--source routes to component.detail.source',
+    async () => {
+      const r = await component('Button', {cwd, source: true});
+      expect(r.type).toBe('component.detail.source');
+    },
+    SLOW,
+  );
+
+  it(
+    '--source WINS over --props when both are set (precedence lock)',
+    async () => {
+      const r = await component('Button', {cwd, props: true, source: true});
+      expect(r.type).toBe('component.detail.source');
+    },
+    SLOW,
+  );
+
+  it(
+    '--list WINS over a given name (list dispatch precedence lock)',
+    async () => {
+      const r = await component('Button', {cwd, list: true});
+      expect(r.type).toBe('component.list');
+    },
+    SLOW,
+  );
 });
 
 describe('component dispatcher — name resolution', () => {
-  it('strips a legacy XDS prefix (XDSButton -> Button)', async () => {
-    const r = await component('XDSButton', {cwd});
-    expect(r.type).toBe('component.detail');
-    expect(r.data.name).toBe('Button');
-  }, SLOW);
-
-  it('is case-SENSITIVE: a lowercased name is unknown', async () => {
-    let err;
-    try {
-      await component('button', {cwd});
-    } catch (e) {
-      err = e;
-    }
-    expect(err).toBeDefined();
-    expect(err.code).toBe('ERR_UNKNOWN_COMPONENT');
-  }, SLOW);
-
-  it('throws ERR_UNKNOWN_COMPONENT for a genuinely unknown name', async () => {
-    let err;
-    try {
-      await component('ZzzNope99', {cwd});
-    } catch (e) {
-      err = e;
-    }
-    expect(err.code).toBe('ERR_UNKNOWN_COMPONENT');
-  }, SLOW);
-
-  it('throws ERR_UNKNOWN_PACKAGE when --package names a missing package', async () => {
-    let err;
-    try {
-      await component('Button', {cwd, package: '@nonexistent/pkg-xyz'});
-    } catch (e) {
-      err = e;
-    }
-    expect(err).toBeDefined();
-    expect(err.code).toBe('ERR_UNKNOWN_PACKAGE');
-  }, SLOW);
-});
+  it(
+    'strips a legacy XDS prefix (XDSButton -> Button)',
+    async () => {
+      const r = await component('XDSButton', {cwd});
+      expect(r.type).toBe('component.detail');
+      expect(r.data.name).toBe('Button');
+    },
+    SLOW,
+  );
+
+  it(
+    'is case-SENSITIVE: a lowercased name is unknown',
+    async () => {
+      let err;
+      try {
+        await component('button', {cwd});
+      } catch (e) {
+        err = e;
+      }
+      expect(err).toBeDefined();
+      expect(err.code).toBe('ERR_UNKNOWN_COMPONENT');
+    },
+    SLOW,
+  );
 
+  it(
+    'throws ERR_UNKNOWN_COMPONENT for a genuinely unknown name',
+    async () => {
+      let err;
+      try {
+        await component('ZzzNope99', {cwd});
+      } catch (e) {
+        err = e;
+      }
+      expect(err.code).toBe('ERR_UNKNOWN_COMPONENT');
+    },
+    SLOW,
+  );
+
+  it(
+    'throws ERR_UNKNOWN_PACKAGE when --package names a missing package',
+    async () => {
+      let err;
+      try {
+        await component('Button', {cwd, package: '@nonexistent/pkg-xyz'});
+      } catch (e) {
+        err = e;
+      }
+      expect(err).toBeDefined();
+      expect(err.code).toBe('ERR_UNKNOWN_PACKAGE');
+    },
+    SLOW,
+  );
+});
 
 describe('component dispatcher — scoped --package routes all projections', () => {
   const CORE = '@astryxdesign/core';
 
-  it('--package (core) routes --showcase like the no-scope path', async () => {
-    const ns = await component('Button', {cwd, showcase: true});
-    const sc = await component('Button', {cwd, package: CORE, showcase: true});
-    expect(sc.type).toBe(ns.type); // was silently component.detail before the fix
-  }, SLOW);
-
-  it('--package (core) routes --blocks like the no-scope path', async () => {
-    const ns = await component('Button', {cwd, blocks: true});
-    const sc = await component('Button', {cwd, package: CORE, blocks: true});
-    expect(sc.type).toBe(ns.type);
-    expect(sc.type).toBe('component.detail.blocks');
-  }, SLOW);
-
-  it('--package (core) still routes --source and --props', async () => {
-    expect((await component('Button', {cwd, package: CORE, source: true})).type).toBe(
-      'component.detail.source',
-    );
-    expect((await component('Button', {cwd, package: CORE, props: true})).type).toBe(
-      'component.detail.props',
-    );
-  }, SLOW);
+  it(
+    '--package (core) routes --showcase like the no-scope path',
+    async () => {
+      const ns = await component('Button', {cwd, showcase: true});
+      const sc = await component('Button', {
+        cwd,
+        package: CORE,
+        showcase: true,
+      });
+      expect(sc.type).toBe(ns.type); // was silently component.detail before the fix
+    },
+    SLOW,
+  );
+
+  it(
+    '--package (core) routes --blocks like the no-scope path',
+    async () => {
+      const ns = await component('Button', {cwd, blocks: true});
+      const sc = await component('Button', {cwd, package: CORE, blocks: true});
+      expect(sc.type).toBe(ns.type);
+      expect(sc.type).toBe('component.detail.blocks');
+    },
+    SLOW,
+  );
+
+  it(
+    "--props carries a prop doc's stability marker (Drawer's experimental prop)",
+    async () => {
+      const r = await component('Drawer', {cwd, props: true});
+      expect(r.type).toBe('component.detail.props');
+      const experimental = r.data.find(p => p.name === 'experimental');
+      expect(experimental?.stability).toBe('experimental');
+      // Only the experimental prop object is marked; stable props carry no field.
+      expect(
+        r.data.filter(p => p.stability !== undefined).map(p => p.name),
+      ).toEqual(['experimental']);
+    },
+    SLOW,
+  );
+
+  it(
+    '--props --json and the text props table both show the stability marker',
+    async () => {
+      const json = await runCli(
+        ['component', 'Drawer', '--props', '--json'],
+        cwd,
+      );
+      expect(json.status).toBe(0);
+      const envelope = JSON.parse(json.stdout);
+      expect(envelope.type).toBe('component.detail.props');
+      expect(
+        envelope.data.find(p => p.name === 'experimental')?.stability,
+      ).toBe('experimental');
+
+      const text = await runCli(['component', 'Drawer', '--props'], cwd);
+      expect(text.status).toBe(0);
+      const rows = text.stdout
+        .split('\n')
+        .filter(line => line.startsWith('| `'));
+      const experimentalRow = rows.find(line =>
+        line.startsWith('| `experimental` |'),
+      );
+      expect(experimentalRow).toContain('**(experimental)**');
+      expect(
+        rows.filter(line => line.includes('**(experimental)**')),
+      ).toHaveLength(1);
+    },
+    SLOW,
+  );
+
+  it(
+    '--package (core) still routes --source and --props',
+    async () => {
+      expect(
+        (await component('Button', {cwd, package: CORE, source: true})).type,
+      ).toBe('component.detail.source');
+      expect(
+        (await component('Button', {cwd, package: CORE, props: true})).type,
+      ).toBe('component.detail.props');
+    },
+    SLOW,
+  );
 });
 
 describe('component dispatcher — category guard', () => {
-  it('a non-string category throws a coded error (not a raw TypeError)', async () => {
-    for (const bad of [123, {}, [1]]) {
-      const err = await component(undefined, {
-        cwd,
-        category: /** @type {any} */ (bad),
-      }).catch(e => e);
-      expect(err).toBeInstanceOf(AstryxError);
-      expect(err.code).toBe('ERR_UNKNOWN_CATEGORY');
-    }
-  }, SLOW);
+  it(
+    'a non-string category throws a coded error (not a raw TypeError)',
+    async () => {
+      for (const bad of [123, {}, [1]]) {
+        const err = await component(undefined, {
+          cwd,
+          category: /** @type {any} */ (bad),
+        }).catch(e => e);
+        expect(err).toBeInstanceOf(AstryxError);
+        expect(err.code).toBe('ERR_UNKNOWN_CATEGORY');
+      }
+    },
+    SLOW,
+  );
 });
 
 describe('component dispatcher — detail and lang guards', () => {
   // `detail` and `lang` are the same controls as the CLI's --detail and --lang:
   // same accepted values, same error codes.
-  it('rejects a detail level the CLI rejects, with the same code', async () => {
-    const cliRun = await runCli(['--json', 'component', '--list', '--detail', 'bogus'], cwd);
-    expect(cliRun.code).toBe(1);
-    expect(JSON.parse(cliRun.stdout).code).toBe('ERR_INVALID_DETAIL');
-
-    const bogus = /** @type {any} */ ('bogus');
-    for (const call of [
-      () => component(undefined, {cwd, list: true, detail: bogus}),
-      () => component('Button', {cwd, detail: bogus}),
-    ]) {
-      const err = await call().catch(e => e);
-      expect(err).toBeInstanceOf(AstryxError);
-      expect(err.code).toBe('ERR_INVALID_DETAIL');
-    }
-  }, SLOW);
-
-  it('rejects a lang the CLI rejects, with the same code', async () => {
-    const cliRun = await runCli(['--json', 'component', 'Button', '--lang', 'fr'], cwd);
-    expect(cliRun.code).toBe(1);
-    expect(JSON.parse(cliRun.stdout).code).toBe('ERR_INVALID_LANG');
-
-    for (const call of [
-      () => component('Button', {cwd, lang: 'fr'}),
-      () => component(undefined, {cwd, list: true, detail: 'compact', lang: 'fr'}),
-    ]) {
-      const err = await call().catch(e => e);
-      expect(err).toBeInstanceOf(AstryxError);
-      expect(err.code).toBe('ERR_INVALID_LANG');
-    }
-    const zh = await component('Button', {cwd, lang: 'zh'});
-    expect(zh.type).toBe('component.detail');
-  }, SLOW);
+  it(
+    'rejects a detail level the CLI rejects, with the same code',
+    async () => {
+      const cliRun = await runCli(
+        ['--json', 'component', '--list', '--detail', 'bogus'],
+        cwd,
+      );
+      expect(cliRun.code).toBe(1);
+      expect(JSON.parse(cliRun.stdout).code).toBe('ERR_INVALID_DETAIL');
+
+      const bogus = /** @type {any} */ ('bogus');
+      for (const call of [
+        () => component(undefined, {cwd, list: true, detail: bogus}),
+        () => component('Button', {cwd, detail: bogus}),
+      ]) {
+        const err = await call().catch(e => e);
+        expect(err).toBeInstanceOf(AstryxError);
+        expect(err.code).toBe('ERR_INVALID_DETAIL');
+      }
+    },
+    SLOW,
+  );
+
+  it(
+    'rejects a lang the CLI rejects, with the same code',
+    async () => {
+      const cliRun = await runCli(
+        ['--json', 'component', 'Button', '--lang', 'fr'],
+        cwd,
+      );
+      expect(cliRun.code).toBe(1);
+      expect(JSON.parse(cliRun.stdout).code).toBe('ERR_INVALID_LANG');
+
+      for (const call of [
+        () => component('Button', {cwd, lang: 'fr'}),
+        () =>
+          component(undefined, {
+            cwd,
+            list: true,
+            detail: 'compact',
+            lang: 'fr',
+          }),
+      ]) {
+        const err = await call().catch(e => e);
+        expect(err).toBeInstanceOf(AstryxError);
+        expect(err.code).toBe('ERR_INVALID_LANG');
+      }
+      const zh = await component('Button', {cwd, lang: 'zh'});
+      expect(zh.type).toBe('component.detail');
+    },
+    SLOW,
+  );
 });
 
 describe('component dispatcher — detail levels on single component (text only)', () => {
-  it('--detail compact returns less text than full', async () => {
-    const full = await runCli(['component', 'Button'], cwd);
-    const compact = await runCli(['component', 'Button', '--detail', 'compact'], cwd);
-    expect(full.code).toBe(0);
-    expect(compact.code).toBe(0);
-    expect(compact.stdout.length).toBeLessThan(full.stdout.length);
-    // Compact still shows the name and import
-    expect(compact.stdout).toContain('Button');
-    expect(compact.stdout).toContain('@astryxdesign/core');
-  }, SLOW);
-
-  it('--detail brief returns less text than compact', async () => {
-    const compact = await runCli(['component', 'Button', '--detail', 'compact'], cwd);
-    const brief = await runCli(['component', 'Button', '--detail', 'brief'], cwd);
-    expect(brief.code).toBe(0);
-    expect(brief.stdout.length).toBeLessThan(compact.stdout.length);
-    expect(brief.stdout).toContain('Button');
-  }, SLOW);
-
-  it('--json --detail compact returns the same full JSON as --json (contract)', async () => {
-    const full = await runCli(['--json', 'component', 'Button'], cwd);
-    const compact = await runCli(['--json', 'component', 'Button', '--detail', 'compact'], cwd);
-    expect(full.code).toBe(0);
-    expect(compact.code).toBe(0);
-    const fullData = JSON.parse(full.stdout);
-    const compactData = JSON.parse(compact.stdout);
-    // JSON shape is identical — detail is a text-only projection
-    expect(Object.keys(compactData.data).sort()).toEqual(Object.keys(fullData.data).sort());
-  }, SLOW);
+  it(
+    '--detail compact returns less text than full',
+    async () => {
+      const full = await runCli(['component', 'Button'], cwd);
+      const compact = await runCli(
+        ['component', 'Button', '--detail', 'compact'],
+        cwd,
+      );
+      expect(full.code).toBe(0);
+      expect(compact.code).toBe(0);
+      expect(compact.stdout.length).toBeLessThan(full.stdout.length);
+      // Compact still shows the name and import
+      expect(compact.stdout).toContain('Button');
+      expect(compact.stdout).toContain('@astryxdesign/core');
+    },
+    SLOW,
+  );
+
+  it(
+    '--detail brief returns less text than compact',
+    async () => {
+      const compact = await runCli(
+        ['component', 'Button', '--detail', 'compact'],
+        cwd,
+      );
+      const brief = await runCli(
+        ['component', 'Button', '--detail', 'brief'],
+        cwd,
+      );
+      expect(brief.code).toBe(0);
+      expect(brief.stdout.length).toBeLessThan(compact.stdout.length);
+      expect(brief.stdout).toContain('Button');
+    },
+    SLOW,
+  );
+
+  it(
+    '--json --detail compact returns the same full JSON as --json (contract)',
+    async () => {
+      const full = await runCli(['--json', 'component', 'Button'], cwd);
+      const compact = await runCli(
+        ['--json', 'component', 'Button', '--detail', 'compact'],
+        cwd,
+      );
+      expect(full.code).toBe(0);
+      expect(compact.code).toBe(0);
+      const fullData = JSON.parse(full.stdout);
+      const compactData = JSON.parse(compact.stdout);
+      // JSON shape is identical — detail is a text-only projection
+      expect(Object.keys(compactData.data).sort()).toEqual(
+        Object.keys(fullData.data).sort(),
+      );
+    },
+    SLOW,
+  );
 });

package/assets/templates/blocks/components/Drawer/DrawerForm.doc.mjs

@@ -0,0 +1,24 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  name: 'Edit form with footer actions',
+  displayName: 'Edit form with footer actions',
+  description:
+    'Compose a Layout with DrawerHeader, the fields in LayoutContent, and Cancel and Save in a pinned LayoutFooter. purpose="form" keeps Escape but ignores scrim clicks, so a stray click outside does not discard edits.',
+  exampleFor: 'Drawer',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: [
+    'Drawer',
+    'DrawerHeader',
+    'Button',
+    'Layout',
+    'LayoutContent',
+    'LayoutFooter',
+    'HStack',
+    'VStack',
+    'TextInput',
+  ],
+};

package/assets/templates/blocks/components/Drawer/DrawerForm.tsx

@@ -0,0 +1,62 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @input Controlled open state and two editable fields
+ * @output A form drawer with a header, scrolling fields, and pinned footer
+ *   actions; purpose="form" keeps Escape but ignores scrim clicks
+ * @position Copyable Drawer example
+ */
+
+import {useState} from 'react';
+import {Drawer, DrawerHeader} from '@astryxdesign/core/Drawer';
+import {Button} from '@astryxdesign/core/Button';
+import {Layout, LayoutContent, LayoutFooter} from '@astryxdesign/core/Layout';
+import {HStack, VStack} from '@astryxdesign/core/Stack';
+import {TextInput} from '@astryxdesign/core/TextInput';
+
+export default function DrawerForm() {
+  const [isOpen, setIsOpen] = useState(false);
+  const [name, setName] = useState('web-prod-04');
+  const [owner, setOwner] = useState('Platform team');
+
+  return (
+    <>
+      <Button label="Edit host" onClick={() => setIsOpen(true)} />
+      <Drawer
+        isOpen={isOpen}
+        onOpenChange={setIsOpen}
+        label="Edit host"
+        purpose="form">
+        <Layout
+          header={<DrawerHeader title="Edit host" onOpenChange={setIsOpen} />}
+          content={
+            <LayoutContent>
+              <VStack gap={4}>
+                <TextInput label="Name" value={name} onChange={setName} />
+                <TextInput label="Owner" value={owner} onChange={setOwner} />
+              </VStack>
+            </LayoutContent>
+          }
+          footer={
+            <LayoutFooter>
+              <HStack gap={2} hAlign="end">
+                <Button
+                  label="Cancel"
+                  variant="secondary"
+                  onClick={() => setIsOpen(false)}
+                />
+                <Button
+                  label="Save"
+                  variant="primary"
+                  onClick={() => setIsOpen(false)}
+                />
+              </HStack>
+            </LayoutFooter>
+          }
+        />
+      </Drawer>
+    </>
+  );
+}