@astryxdesign/cli 0.1.2 → 0.1.3

package/src/utils/github.mjs

@@ -4,69 +4,9 @@
  * @file GitHub utilities for Astryx CLI
  *
  * Shared helpers for interacting with the GitHub CLI (`gh`).
- * Used by gap-report and swizzle commands.
- *
- * Gap reporting can be configured via astryx.config.mjs:
- *   gapReport: false                                — disable entirely
- *   gapReport: { command: './scripts/report-gap.sh' } — run custom script (receives JSON on stdin)
- *
- * Or via environment variable:
- *   ASTRYX_GAP_REPORT=off                              — disable entirely
- *   ASTRYX_GAP_REPORT=./scripts/report-gap.sh          — run custom script
  */
 
 import {execFileSync} from 'node:child_process';
-import * as path from 'node:path';
-import {loadConfig} from '../lib/config.mjs';
-
-/** Default target repository for gap report issues. */
-const DEFAULT_REPO = 'facebookexperimental/xds';
-
-/** Gap report category options. */
-export const GAP_CATEGORIES = [
-  {value: 'missing_component', label: 'Missing component'},
-  {value: 'missing_variant', label: 'Missing variant or prop'},
-  {value: 'layout_gap', label: 'Layout gap'},
-  {value: 'styling_gap', label: 'Styling gap'},
-  {value: 'a11y_gap', label: 'Accessibility gap'},
-  {value: 'api_friction', label: 'API friction'},
-  {value: 'docs_gap', label: 'Documentation gap'},
-  {value: 'other', label: 'Other'},
-];
-
-/**
- * Load gap report configuration.
- *
- * Priority: env var > astryx.config.mjs > default (GitHub issue)
- *
- * Returns { enabled: boolean, command?: string }
- *   - enabled: false → gap reporting disabled
- *   - command: string → run this script instead of creating a GitHub issue
- *   - neither → default behavior (GitHub issue to facebookexperimental/xds)
- */
-export async function loadGapReportConfig() {
-  // 1. Check environment variable
-  const envVar = process.env.ASTRYX_GAP_REPORT;
-  if (envVar) {
-    if (envVar === 'off' || envVar === 'false' || envVar === '0') {
-      return {enabled: false};
-    }
-    // Treat as custom command
-    return {enabled: true, command: envVar};
-  }
-
-  // 2. Check astryx.config.mjs + integration manifests
-  const config = await loadConfig(process.cwd());
-  if (config.gapReport !== undefined) {
-    if (config.gapReport === false) return {enabled: false};
-    if (config.gapReport?.command) {
-      return {enabled: true, command: config.gapReport.command};
-    }
-  }
-
-  // 3. Default
-  return {enabled: true};
-}
 
 /**
  * Check if `gh` CLI is installed and authenticated.
@@ -80,180 +20,3 @@ export function checkGhCli() {
     return false;
   }
 }
-
-/**
- * Idempotently create the `gap-report` and `gap-analysis` labels.
- * Uses `--force` to avoid errors if labels already exist.
- */
-function ensureGapReportLabel() {
-  try {
-    execFileSync(
-      'gh',
-      [
-        'label',
-        'create',
-        'gap-report',
-        '--repo',
-        DEFAULT_REPO,
-        '--color',
-        'D4C5F9',
-        '--description',
-        'Auto-filed gap report from swizzle/gap-report CLI',
-        '--force',
-      ],
-      {stdio: 'ignore'},
-    );
-    execFileSync(
-      'gh',
-      [
-        'label',
-        'create',
-        'gap-analysis',
-        '--repo',
-        DEFAULT_REPO,
-        '--color',
-        '0E8A16',
-        '--description',
-        'Curated gap analysis summary',
-        '--force',
-      ],
-      {stdio: 'ignore'},
-    );
-  } catch {
-    // Best-effort — labels may already exist or user may lack permissions
-  }
-}
-
-/**
- * Run a custom gap report command, piping report data as JSON to stdin.
- *
- * @param {string} command  Script path to execute
- * @param {object} report   Report data (component, category, intention, detail, source)
- * @returns {string} stdout from the command
- */
-function runCustomCommand(command, report) {
-  const resolved = path.resolve(process.cwd(), command);
-  const json = JSON.stringify(report, null, 2);
-
-  const result = execFileSync(resolved, [], {
-    input: json,
-    encoding: 'utf-8',
-  });
-
-  return result.trim();
-}
-
-/**
- * Build the report payload + rendered title/body for a gap report.
- * Pure function — no side effects, never calls `gh` or external scripts.
- *
- * @returns {{
- *   enabled: boolean,
- *   mode: 'disabled' | 'custom' | 'github',
- *   command?: string,
- *   report: object,
- *   title: string,
- *   body: string,
- *   repo: string,
- * }}
- */
-export async function buildGapReportPreview({
-  component,
-  category,
-  intention,
-  detail,
-  source = 'cli',
-}) {
-  const config = await loadGapReportConfig();
-  const categoryLabel =
-    GAP_CATEGORIES.find(c => c.value === category)?.label ?? category;
-
-  const report = {
-    component,
-    category,
-    categoryLabel,
-    intention,
-    detail: detail || null,
-    source,
-    timestamp: new Date().toISOString(),
-  };
-
-  const title = `[gap] ${component}: ${intention.slice(0, 70)}`;
-  const body = [
-    '| Field | Value |',
-    '|-------|-------|',
-    `| **Component** | ${component} |`,
-    `| **Category** | ${categoryLabel} |`,
-    `| **Source** | ${source} |`,
-    `| **Timestamp** | ${report.timestamp} |`,
-    '',
-    '## User Intention',
-    '',
-    intention,
-    ...(detail ? ['', '## Additional Context', '', detail] : []),
-  ].join('\n');
-
-  let mode = 'github';
-  if (!config.enabled) mode = 'disabled';
-  else if (config.command) mode = 'custom';
-
-  return {
-    enabled: config.enabled,
-    mode,
-    command: config.command,
-    report,
-    title,
-    body,
-    repo: DEFAULT_REPO,
-  };
-}
-
-/**
- * Create a gap report — either via GitHub issue or custom command.
- *
- * SAFETY: This actually invokes `gh issue create` (or runs the custom command).
- * Callers MUST gate this behind explicit user confirmation or a `--commit`-style
- * flag in non-interactive contexts. Use `buildGapReportPreview` for dry-run.
- *
- * @param {object} opts
- * @param {string} opts.component  Component name (e.g. "Button")
- * @param {string} opts.category   One of GAP_CATEGORIES values
- * @param {string} opts.intention  What the user was trying to achieve
- * @param {string} [opts.detail]   Additional context
- * @param {string} [opts.source]   Who filed it: "interactive", "llm-auto", "cli"
- * @returns {string|null} URL of the created issue (or custom command output), null if disabled
- */
-export async function createGapReport(opts) {
-  const preview = await buildGapReportPreview(opts);
-
-  if (!preview.enabled) {
-    return null;
-  }
-
-  // Custom command mode — pipe JSON to the script
-  if (preview.mode === 'custom') {
-    return runCustomCommand(preview.command, preview.report);
-  }
-
-  // Default mode — create GitHub issue
-  ensureGapReportLabel();
-
-  const result = execFileSync(
-    'gh',
-    [
-      'issue',
-      'create',
-      '--repo',
-      preview.repo,
-      '--title',
-      preview.title,
-      '--body',
-      preview.body,
-      '--label',
-      'gap-report',
-    ],
-    {encoding: 'utf-8'},
-  );
-
-  return result.trim();
-}

package/src/utils/interactive.mjs

@@ -18,8 +18,8 @@
  *     fail fast (exit 1) with actionable, non-interactive guidance.
  *
  *   - `isInteractive()` — for commands with an OPTIONAL secondary prompt
- *     (e.g. swizzle's post-copy "report a gap?"). The primary work already
- *     succeeded; callers use this to skip the prompt gracefully.
+ *     that runs after the primary work has already succeeded; callers use
+ *     this to skip the prompt gracefully in non-interactive contexts.
  */
 
 /**

package/templates/blocks/components/AvatarStatusDot/AvatarStatusDotVariants.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'AvatarStatusDot',
+  name: 'AvatarStatusDot — Variants',
+  displayName: 'AvatarStatusDot — Variants',
+  description:
+    'Presence dots on Avatars using the success, neutral, and error variants. Pass an AvatarStatusDot to the Avatar status prop; the dot sizes itself to match the Avatar.',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['Avatar', 'AvatarStatusDot', 'HStack'],
+};

package/templates/blocks/components/AvatarStatusDot/AvatarStatusDotVariants.tsx

@@ -0,0 +1,28 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {Avatar, AvatarStatusDot} from '@astryxdesign/core/Avatar';
+import {HStack} from '@astryxdesign/core/Layout';
+
+export default function AvatarStatusDotVariants() {
+  return (
+    <HStack gap={4} vAlign="center">
+      <Avatar
+        name="Ana Silva"
+        size="large"
+        status={<AvatarStatusDot variant="success" label="Online" />}
+      />
+      <Avatar
+        name="Ben Okafor"
+        size="large"
+        status={<AvatarStatusDot variant="neutral" label="Away" />}
+      />
+      <Avatar
+        name="Cleo Marsh"
+        size="large"
+        status={<AvatarStatusDot variant="error" label="Do not disturb" />}
+      />
+    </HStack>
+  );
+}

package/templates/blocks/components/Blockquote/BlockquoteTestimonials.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'Blockquote',
+  name: 'Blockquote — Testimonials',
+  displayName: 'Blockquote — Testimonials',
+  description:
+    'Multiple quotes arranged in a card grid for a testimonials section. Combine with Card and Grid to create social-proof layouts.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['Blockquote', 'Card', 'Grid', 'GridSpan'],
+};

package/templates/blocks/components/Blockquote/BlockquoteTestimonials.tsx

@@ -0,0 +1,34 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {Blockquote} from '@astryxdesign/core/Blockquote';
+import {Grid, GridSpan} from '@astryxdesign/core/Grid';
+import {Card} from '@astryxdesign/core/Card';
+
+export default function BlockquoteTestimonials() {
+  return (
+    <Grid columns={2} gap={3} style={{maxWidth: 600}}>
+      <Card padding={4}>
+        <Blockquote cite="Sarah K., Lead Engineer">
+          Shipping UI has never been this fast. Our team went from design to
+          production in a single afternoon.
+        </Blockquote>
+      </Card>
+      <Card padding={4}>
+        <Blockquote cite="Marcus T., Product Designer">
+          The token system means every new screen just looks right — no manual
+          color or spacing decisions.
+        </Blockquote>
+      </Card>
+      <GridSpan columns={2}>
+        <Card padding={4}>
+          <Blockquote cite="Priya L., Engineering Manager">
+            Onboarding a new engineer used to take a week of design review. Now
+            they're shipping accessible, polished components on day one.
+          </Blockquote>
+        </Card>
+      </GridSpan>
+    </Grid>
+  );
+}

package/templates/blocks/components/Blockquote/BlockquoteWithCite.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'Blockquote',
+  name: 'Blockquote — With Attribution',
+  displayName: 'Blockquote — With Attribution',
+  description:
+    'A plain quote and a quote with a cite attribution. Use cite to credit the original author or source.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['Blockquote', 'Layout'],
+};

package/templates/blocks/components/Blockquote/BlockquoteWithCite.tsx

@@ -0,0 +1,21 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {Blockquote} from '@astryxdesign/core/Blockquote';
+import {VStack} from '@astryxdesign/core/Layout';
+
+export default function BlockquoteWithCite() {
+  return (
+    <VStack gap={4} style={{maxWidth: 500}}>
+      <Blockquote>
+        Design is not just what it looks like and feels like. Design is how it
+        works.
+      </Blockquote>
+      <Blockquote cite="Steve Jobs">
+        The people who are crazy enough to think they can change the world are
+        the ones who do.
+      </Blockquote>
+    </VStack>
+  );
+}

package/templates/blocks/components/BreadcrumbItem/BreadcrumbItemBasic.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'BreadcrumbItem',
+  name: 'BreadcrumbItem — Basic',
+  displayName: 'BreadcrumbItem — Basic',
+  description:
+    'Breadcrumb links inside a Breadcrumbs trail. Ancestor pages get an href; mark the last item with isCurrent to render it as plain text for the current page.',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['Breadcrumbs', 'BreadcrumbItem'],
+};

package/templates/blocks/components/BreadcrumbItem/BreadcrumbItemBasic.tsx

@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {Breadcrumbs, BreadcrumbItem} from '@astryxdesign/core/Breadcrumbs';
+
+export default function BreadcrumbItemBasic() {
+  return (
+    <Breadcrumbs>
+      <BreadcrumbItem href="/">Home</BreadcrumbItem>
+      <BreadcrumbItem href="/settings">Settings</BreadcrumbItem>
+      <BreadcrumbItem isCurrent>Profile</BreadcrumbItem>
+    </Breadcrumbs>
+  );
+}

package/templates/blocks/components/ButtonGroup/ButtonGroupBasic.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'ButtonGroup',
+  name: 'ButtonGroup — Basic',
+  displayName: 'ButtonGroup — Basic',
+  description:
+    'Three related actions joined into a single connected control. Provide a group label for accessibility and keep all buttons the same variant so they read as one unit.',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['ButtonGroup', 'Button'],
+};

package/templates/blocks/components/ButtonGroup/ButtonGroupBasic.tsx

@@ -0,0 +1,16 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {ButtonGroup} from '@astryxdesign/core/ButtonGroup';
+import {Button} from '@astryxdesign/core/Button';
+
+export default function ButtonGroupBasic() {
+  return (
+    <ButtonGroup label="Text editing actions">
+      <Button label="Copy" />
+      <Button label="Cut" />
+      <Button label="Paste" />
+    </ButtonGroup>
+  );
+}

package/templates/blocks/components/ChatDictationButton/ChatDictationButtonBasic.doc.mjs

@@ -0,0 +1,19 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'ChatDictationButton',
+  name: 'ChatDictationButton — Basic',
+  displayName: 'ChatDictationButton — Basic',
+  description:
+    'A dictation button wired to useChatDictation and placed in the sendActions slot of a ChatComposer. Click the microphone to transcribe speech into the input.',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: [
+    'Chat',
+    'ChatDictationButton',
+    'ChatComposer',
+    'ChatComposerInput',
+  ],
+};

package/templates/blocks/components/ChatDictationButton/ChatDictationButtonBasic.tsx

@@ -0,0 +1,34 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useRef} from 'react';
+import {
+  ChatDictationButton,
+  ChatComposer,
+  ChatComposerInput,
+  useChatDictation,
+} from '@astryxdesign/core/Chat';
+import type {ChatComposerInputHandle} from '@astryxdesign/core/Chat';
+import {Stack} from '@astryxdesign/core/Layout';
+
+export default function ChatDictationButtonBasic() {
+  const inputRef = useRef<ChatComposerInputHandle>(null);
+
+  const dictation = useChatDictation({
+    inputRef,
+    onResult: text => {
+      console.log('Dictation result:', text);
+    },
+  });
+
+  return (
+    <Stack direction="vertical" width="100%" style={{maxWidth: 450}}>
+      <ChatComposer
+        onSubmit={value => console.log('Submit:', value)}
+        input={<ChatComposerInput handleRef={inputRef} />}
+        sendActions={<ChatDictationButton dictation={dictation} />}
+      />
+    </Stack>
+  );
+}

package/templates/blocks/components/CheckboxListItem/CheckboxListItemBasic.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'CheckboxListItem',
+  name: 'CheckboxListItem — Basic',
+  displayName: 'CheckboxListItem — Basic',
+  description:
+    'Checkbox items with labels and descriptions inside a controlled CheckboxList. Use for multi-select option groups like notification preferences.',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['CheckboxList', 'CheckboxListItem'],
+};

package/templates/blocks/components/CheckboxListItem/CheckboxListItemBasic.tsx

@@ -0,0 +1,30 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {CheckboxList, CheckboxListItem} from '@astryxdesign/core/CheckboxList';
+
+export default function CheckboxListItemBasic() {
+  const [value, setValue] = useState<string[]>(['updates']);
+
+  return (
+    <CheckboxList label="Email preferences" value={value} onChange={setValue}>
+      <CheckboxListItem
+        label="Product updates"
+        value="updates"
+        description="New features and improvements"
+      />
+      <CheckboxListItem
+        label="Security alerts"
+        value="security"
+        description="Important account security notifications"
+      />
+      <CheckboxListItem
+        label="Marketing"
+        value="marketing"
+        description="Tips, offers, and promotions"
+      />
+    </CheckboxList>
+  );
+}

package/templates/blocks/components/CollapsibleGroup/CollapsibleGroupAccordion.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'CollapsibleGroup',
+  name: 'CollapsibleGroup — Accordion',
+  displayName: 'CollapsibleGroup — Accordion',
+  description:
+    'An accordion built with type="single": opening one Collapsible automatically closes the others. Use defaultValue to pre-expand the most important section.',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['CollapsibleGroup', 'Collapsible', 'VStack', 'Text'],
+};

package/templates/blocks/components/CollapsibleGroup/CollapsibleGroupAccordion.tsx

@@ -0,0 +1,31 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {Collapsible, CollapsibleGroup} from '@astryxdesign/core/Collapsible';
+import {VStack} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+
+export default function CollapsibleGroupAccordion() {
+  return (
+    <CollapsibleGroup type="single" defaultValue="account">
+      <VStack gap={2} width="100%">
+        <Collapsible trigger="Account" value="account">
+          <Text type="body" color="secondary">
+            Manage your profile details, email address, and password.
+          </Text>
+        </Collapsible>
+        <Collapsible trigger="Notifications" value="notifications">
+          <Text type="body" color="secondary">
+            Choose which activity triggers email and push notifications.
+          </Text>
+        </Collapsible>
+        <Collapsible trigger="Billing" value="billing">
+          <Text type="body" color="secondary">
+            View invoices and update your payment method.
+          </Text>
+        </Collapsible>
+      </VStack>
+    </CollapsibleGroup>
+  );
+}

package/templates/blocks/components/CommandPaletteEmpty/CommandPaletteEmptyBasic.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'CommandPaletteEmpty',
+  name: 'CommandPaletteEmpty — Basic',
+  displayName: 'CommandPaletteEmpty — Basic',
+  description:
+    'A command palette with no results, showing a custom empty message via emptyBootstrapText. Use to explain why the palette is empty and what the user can do next.',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['CommandPalette', 'CommandPaletteEmpty', 'Text'],
+};

package/templates/blocks/components/CommandPaletteEmpty/CommandPaletteEmptyBasic.tsx

@@ -0,0 +1,26 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useMemo} from 'react';
+import {CommandPalette} from '@astryxdesign/core/CommandPalette';
+import {Text} from '@astryxdesign/core/Text';
+import {createStaticSource} from '@astryxdesign/core/Typeahead';
+
+export default function CommandPaletteEmptyBasic() {
+  const emptySource = useMemo(() => createStaticSource([]), []);
+
+  return (
+    <CommandPalette
+      isOpen
+      isInline
+      onOpenChange={() => {}}
+      searchSource={emptySource}
+      emptyBootstrapText={
+        <Text type="supporting" color="secondary">
+          No commands available
+        </Text>
+      }
+    />
+  );
+}

package/templates/blocks/components/CommandPaletteFooter/CommandPaletteFooterBasic.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'CommandPaletteFooter',
+  name: 'CommandPaletteFooter — Basic',
+  displayName: 'CommandPaletteFooter — Basic',
+  description:
+    'A command palette footer with no children, rendering the built-in keyboard navigation hints. Use CommandPaletteFooter without content to get the default arrow-key, Enter, and Esc hints below the results list.',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['CommandPalette', 'CommandPaletteFooter'],
+};