@astryxdesign/cli 0.1.7 → 0.1.8-canary.07362a9

package/scripts/postinstall.mjs

@@ -0,0 +1,74 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file @astryxdesign/cli postinstall — nudge to run `astryx init`.
+ *
+ * Enforcement layer 2 of making `astryx init` foolproof: when the CLI is
+ * installed as a project dependency and the project hasn't run init yet, print a
+ * one-line next-step so agents/humans discover it.
+ *
+ * Reuses the ONE setup check (isAstryxInitialized from agent-docs.mjs — a
+ * dep-free import chain, safe at install time). Non-interactive, never fails the
+ * install, and stays quiet:
+ *   - in the monorepo/source build (not under node_modules),
+ *   - during npx's transient fetch (npx runs the bin — likely `init` — right
+ *     after, so nudging here would double up), and
+ *   - once setup is already done.
+ */
+
+import {fileURLToPath, pathToFileURL} from 'node:url';
+
+const HERE = fileURLToPath(import.meta.url);
+
+/**
+ * Pure decision: should the postinstall print the setup nudge? Split out so the
+ * matrix is unit-testable without an actual npm install.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.scriptPath] - Absolute path of this script (location tells
+ *   us dependency vs monorepo vs npx-cache).
+ * @param {string} [opts.npmCommand] - process.env.npm_command ('install', 'exec', …).
+ * @param {boolean} [opts.isSetUp] - Whether the project already ran init.
+ * @returns {boolean}
+ */
+export function shouldNudge({scriptPath, npmCommand, isSetUp} = {}) {
+  if (!scriptPath || !scriptPath.includes('node_modules')) return false; // monorepo/source build
+  if (scriptPath.includes('_npx') || npmCommand === 'exec') return false; // npx transient — init runs next
+  if (isSetUp) return false; // already set up — stay quiet
+  return true;
+}
+
+/** @param {string} root @returns {Promise<boolean>} */
+async function projectIsSetUp(root) {
+  try {
+    const {isAstryxInitialized} = await import('../lib/agent-docs/agent-docs.mjs');
+    return isAstryxInitialized(root);
+  } catch {
+    return false; // best-effort — if the check can't load, fall through and nudge
+  }
+}
+
+async function main() {
+  const root = process.env.INIT_CWD || process.cwd();
+  const nudge = shouldNudge({
+    scriptPath: HERE,
+    npmCommand: process.env.npm_command,
+    isSetUp: await projectIsSetUp(root),
+  });
+  if (nudge) {
+    // Scoped package form (`@astryxdesign/cli`) — always resolves to us. Bare
+    // `npx astryx` would fetch an unrelated look-alike package (see PR #4151).
+    // After that lands, switch this to its getCliInvocation() single source of truth.
+    process.stdout.write(
+      '\nNext step: run `npx @astryxdesign/cli init` to finish setup and install the Astryx agent prompt.\n\n',
+    );
+  }
+}
+
+// Run only when executed directly (`node scripts/postinstall.mjs`), never when
+// imported by tests.
+if (import.meta.url === pathToFileURL(process.argv[1] || '').href) {
+  main()
+    .catch(() => {})
+    .finally(() => process.exit(0));
+}

package/templates/blocks/components/Avatar/AvatarFallbackChain.tsx

@@ -13,7 +13,7 @@ export default function AvatarFallbackChain() {
         <Avatar
           src="https://lookaside.facebook.com/assets/astryx/DATA-Daniela-Gimenez.png"
           name="Daniela Gimenez"
-          size="medium"
+          size="lg"
         />
         <Text type="supporting">Valid src</Text>
       </HStack>
@@ -22,7 +22,7 @@ export default function AvatarFallbackChain() {
           src="https://lookaside.facebook.com/assets/astryx/does-not-exist-primary.jpg"
           fallbackSrc="https://lookaside.facebook.com/assets/astryx/DATA-Ami-Pena.png"
           name="Invalid User"
-          size="medium"
+          size="lg"
         />
         <Text type="supporting">Invalid src, valid fallbackSrc</Text>
       </HStack>
@@ -31,14 +31,14 @@ export default function AvatarFallbackChain() {
           src="https://lookaside.facebook.com/assets/astryx/does-not-exist-primary.jpg"
           fallbackSrc="https://lookaside.facebook.com/assets/astryx/does-not-exist-fallback.jpg"
           name="Test User"
-          size="medium"
+          size="lg"
         />
         <Text type="supporting">Both invalid, has name</Text>
       </HStack>
       <HStack gap={3} vAlign="center">
         <Avatar
           src="https://lookaside.facebook.com/assets/astryx/does-not-exist-primary.jpg"
-          size="medium"
+          size="lg"
         />
         <Text type="supporting">All invalid, no name</Text>
       </HStack>

package/templates/blocks/components/Avatar/AvatarGroup.tsx

@@ -37,7 +37,7 @@ export default function AvatarGroupBlock() {
         <Text type="supporting" color="secondary">
           Team members
         </Text>
-        <AvatarGroup size="medium">
+        <AvatarGroup size="lg">
           {USERS.map(user => (
             <Avatar key={user.name} src={user.src} name={user.name} />
           ))}
@@ -48,7 +48,7 @@ export default function AvatarGroupBlock() {
         <Text type="supporting" color="secondary">
           Larger group
         </Text>
-        <AvatarGroup size="medium">
+        <AvatarGroup size="lg">
           {USERS.slice(0, 3).map(user => (
             <Avatar key={user.name} src={user.src} name={user.name} />
           ))}

package/templates/blocks/components/Avatar/AvatarInitialsFallback.tsx

@@ -18,7 +18,7 @@ export default function AvatarInitialsFallback() {
     <Stack direction="horizontal" gap={6} vAlign="center">
       {NAMES.map(({name, note}) => (
         <Stack key={name} direction="vertical" gap={2} hAlign="center">
-          <Avatar name={name} size="medium" />
+          <Avatar name={name} size="lg" />
           <Text type="supporting" color="secondary">
             {note}
           </Text>

package/templates/blocks/components/Avatar/AvatarShowcase.tsx

@@ -11,24 +11,24 @@ export default function AvatarShowcase() {
       <Avatar
         src="https://lookaside.facebook.com/assets/astryx/DATA-Ana-Thomas.png"
         name="Ana Thomas"
-        size="large"
+        size="xl"
         status={<AvatarStatusDot variant="success" label="Online" />}
       />
       <Avatar
         src="https://lookaside.facebook.com/assets/astryx/DATA-Drew-Young.png"
         name="Drew Young"
-        size="large"
+        size="xl"
       />
       <Avatar
         src="https://lookaside.facebook.com/assets/astryx/DATA-Jihoo-Song.png"
         name="Jihoo Song"
-        size="large"
+        size="xl"
       />
       <Avatar
         src="https://lookaside.facebook.com/assets/astryx/DATA-Nam-Tran.png"
         name="Nam Tran"
-        size="large"
-        status={<AvatarStatusDot variant="error" label="Online" />}
+        size="xl"
+        status={<AvatarStatusDot variant="error" label="Busy" />}
       />
     </Stack>
   );

package/templates/blocks/components/Avatar/AvatarUserCard.tsx

@@ -35,7 +35,7 @@ export default function AvatarUserCard() {
           <Avatar
             src={user.src}
             name={user.name}
-            size="medium"
+            size="lg"
             status={
               <AvatarStatusDot variant={user.variant} label={user.variant} />
             }

package/templates/blocks/components/Avatar/AvatarWithImage.tsx

@@ -11,22 +11,22 @@ export default function AvatarWithImage() {
       <Avatar
         src="https://lookaside.facebook.com/assets/astryx/DATA-Ami-Pena.png"
         name="Ami Pena"
-        size="tiny"
+        size="xsm"
       />
       <Avatar
         src="https://lookaside.facebook.com/assets/astryx/DATA-Ana-Thomas.png"
         name="Ana Thomas"
-        size="small"
+        size="md"
       />
       <Avatar
         src="https://lookaside.facebook.com/assets/astryx/DATA-Daniela-Gimenez.png"
         name="Daniela Gimenez"
-        size="medium"
+        size="lg"
       />
       <Avatar
         src="https://lookaside.facebook.com/assets/astryx/DATA-Gabriela-Fernandez.png"
         name="Gabriela Fernandez"
-        size="large"
+        size="xl"
       />
     </Stack>
   );

package/templates/blocks/components/Avatar/AvatarWithStatus.tsx

@@ -11,19 +11,19 @@ export default function AvatarWithStatus() {
       <Avatar
         src="https://lookaside.facebook.com/assets/astryx/DATA-Itai-Jordaan.png"
         name="Itai Jordaan"
-        size="large"
+        size="xl"
         status={<AvatarStatusDot variant="success" label="Online" />}
       />
       <Avatar
         src="https://lookaside.facebook.com/assets/astryx/DATA-Margot-Schroder.png"
         name="Margot Schroder"
-        size="large"
+        size="xl"
         status={<AvatarStatusDot variant="neutral" label="Offline" />}
       />
       <Avatar
         src="https://lookaside.facebook.com/assets/astryx/DATA-Pablo-Morales.png"
         name="Pablo Morales"
-        size="large"
+        size="xl"
         status={<AvatarStatusDot variant="error" label="Busy" />}
       />
     </Stack>

package/templates/blocks/components/AvatarGroup/AvatarGroupShowcase.tsx

@@ -36,7 +36,7 @@ export default function AvatarGroupShowcase() {
         <Text type="supporting" color="secondary">
           Team members
         </Text>
-        <AvatarGroup size="medium">
+        <AvatarGroup size="lg">
           {USERS.map(u => (
             <Avatar key={u.key} name={u.name} />
           ))}
@@ -46,7 +46,7 @@ export default function AvatarGroupShowcase() {
         <Text type="supporting" color="secondary">
           With overflow
         </Text>
-        <AvatarGroup size="medium">
+        <AvatarGroup size="lg">
           {USERS.slice(0, 3).map(u => (
             <Avatar key={u.key} name={u.name} />
           ))}

package/templates/blocks/components/AvatarGroupOverflow/AvatarGroupOverflowCustomText.tsx

@@ -24,7 +24,7 @@ export default function AvatarGroupOverflowCustomText() {
       <Text type="supporting" color="secondary">
         Team members
       </Text>
-      <AvatarGroup size="medium">
+      <AvatarGroup size="lg">
         {TEAM.map(member => (
           <Avatar key={member.name} name={member.name} />
         ))}

package/templates/blocks/components/AvatarGroupOverflow/AvatarGroupOverflowDefault.tsx

@@ -24,7 +24,7 @@ export default function AvatarGroupOverflowDefault() {
       <Text type="supporting" color="secondary">
         Reviewers
       </Text>
-      <AvatarGroup size="medium">
+      <AvatarGroup size="lg">
         {REVIEWERS.map(reviewer => (
           <Avatar key={reviewer.name} name={reviewer.name} />
         ))}

package/templates/blocks/components/AvatarGroupOverflow/AvatarGroupOverflowShowcase.tsx

@@ -25,7 +25,7 @@ export default function AvatarGroupOverflowShowcase() {
         <Text type="supporting" color="secondary">
           Default overflow
         </Text>
-        <AvatarGroup size="medium">
+        <AvatarGroup size="lg">
           {USERS.map(user => (
             <Avatar key={user.name} name={user.name} />
           ))}
@@ -36,7 +36,7 @@ export default function AvatarGroupOverflowShowcase() {
         <Text type="supporting" color="secondary">
           Custom count text
         </Text>
-        <AvatarGroup size="medium">
+        <AvatarGroup size="lg">
           {USERS.slice(0, 2).map(user => (
             <Avatar key={user.name} name={user.name} />
           ))}

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

@@ -10,17 +10,17 @@ export default function AvatarStatusDotShowcase() {
     <HStack gap={4} vAlign="center">
       <Avatar
         name="Online User"
-        size="large"
+        size="xl"
         status={<AvatarStatusDot variant="success" label="Online" />}
       />
       <Avatar
         name="Away User"
-        size="large"
+        size="xl"
         status={<AvatarStatusDot variant="neutral" label="Away" />}
       />
       <Avatar
         name="Busy User"
-        size="large"
+        size="xl"
         status={<AvatarStatusDot variant="error" label="Busy" />}
       />
     </HStack>

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

@@ -10,17 +10,17 @@ export default function AvatarStatusDotVariants() {
     <HStack gap={4} vAlign="center">
       <Avatar
         name="Ana Silva"
-        size="large"
+        size="xl"
         status={<AvatarStatusDot variant="success" label="Online" />}
       />
       <Avatar
         name="Ben Okafor"
-        size="large"
+        size="xl"
         status={<AvatarStatusDot variant="neutral" label="Away" />}
       />
       <Avatar
         name="Cleo Marsh"
-        size="large"
+        size="xl"
         status={<AvatarStatusDot variant="error" label="Do not disturb" />}
       />
     </HStack>

package/templates/blocks/components/Banner/BannerFloating.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: 'Banner',
+  name: 'Banner — Floating',
+  displayName: 'Banner — Floating',
+  description:
+    'A floating banner raised with `elevation="med"`. Banners are inline by default; raise one when it should read as an overlay above content.',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['Banner'],
+};

package/templates/blocks/components/Banner/BannerFloating.tsx

@@ -0,0 +1,16 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {Banner} from '@astryxdesign/core/Banner';
+
+export default function BannerFloating() {
+  return (
+    <Banner
+      status="info"
+      title="You have unsaved changes"
+      description="A raised banner reads as an overlay floating above the page."
+      elevation="med"
+    />
+  );
+}

package/templates/blocks/components/Button/ButtonFloating.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: 'Button',
+  name: 'Button — Floating',
+  displayName: 'Button — Floating',
+  description:
+    'A floating action button raised with `elevation="med"`. Use elevation for buttons that hover above content, like a FAB.',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['Button', 'Icon', 'Layout', 'Text'],
+};

package/templates/blocks/components/Button/ButtonFloating.tsx

@@ -0,0 +1,37 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {Button} from '@astryxdesign/core/Button';
+import {Icon} from '@astryxdesign/core/Icon';
+import {Stack} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+import {PlusIcon} from '@heroicons/react/24/outline';
+
+const VARIANTS = [
+  {variant: 'primary' as const, label: 'Primary'},
+  {variant: 'secondary' as const, label: 'Secondary'},
+  {variant: 'ghost' as const, label: 'Ghost'},
+  {variant: 'destructive' as const, label: 'Destructive'},
+];
+
+export default function ButtonFloating() {
+  return (
+    <Stack direction="vertical" gap={4}>
+      <Text type="supporting" color="secondary">
+        Floating action buttons — raised above content with `elevation="med"`
+      </Text>
+      <Stack direction="horizontal" gap={3} vAlign="center">
+        {VARIANTS.map(({variant, label}) => (
+          <Button
+            key={variant}
+            label={label}
+            variant={variant}
+            icon={<Icon icon={PlusIcon} />}
+            elevation="med"
+          />
+        ))}
+      </Stack>
+    </Stack>
+  );
+}

package/templates/blocks/components/ButtonGroup/ButtonGroupFloating.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 — Floating',
+  displayName: 'ButtonGroup — Floating',
+  description:
+    'A grouped action bar raised with `elevation="med"`. The connected buttons share one surface, so the shadow lifts them as a unit.',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['ButtonGroup', 'Button', 'Layout', 'Text'],
+};

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

@@ -0,0 +1,23 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {ButtonGroup} from '@astryxdesign/core/ButtonGroup';
+import {Button} from '@astryxdesign/core/Button';
+import {Stack} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+
+export default function ButtonGroupFloating() {
+  return (
+    <Stack direction="vertical" gap={3} hAlign="start">
+      <Text type="supporting" color="secondary">
+        The whole group shares one raised surface — a floating action bar
+      </Text>
+      <ButtonGroup label="Zoom controls" elevation="med">
+        <Button label="Zoom out" />
+        <Button label="Reset" />
+        <Button label="Zoom in" />
+      </ButtonGroup>
+    </Stack>
+  );
+}

package/templates/blocks/components/Card/CardElevations.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: 'Card',
+  name: 'Card — Elevations',
+  displayName: 'Card — Elevations',
+  description:
+    'The four elevation levels side by side. Cards are flat by default; raise a card with `elevation` only when it needs to float above surrounding content.',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['Card', 'Layout', 'Text'],
+};

package/templates/blocks/components/Card/CardElevations.tsx

@@ -0,0 +1,32 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {Card} from '@astryxdesign/core/Card';
+import {Stack} from '@astryxdesign/core/Layout';
+import {Grid} from '@astryxdesign/core/Grid';
+import {Text, Heading} from '@astryxdesign/core/Text';
+
+const LEVELS = [
+  {elevation: 'none' as const, caption: 'Flat — sits on the page (default)'},
+  {elevation: 'low' as const, caption: 'Low — lifts off slightly'},
+  {elevation: 'med' as const, caption: 'Med — clearly raised'},
+  {elevation: 'high' as const, caption: 'High — floats well above'},
+];
+
+export default function CardElevations() {
+  return (
+    <Grid columns={2} gap={4} width={520}>
+      {LEVELS.map(({elevation, caption}) => (
+        <Card key={elevation} elevation={elevation}>
+          <Stack direction="vertical" gap={1}>
+            <Heading level={4}>elevation=&quot;{elevation}&quot;</Heading>
+            <Text type="supporting" color="secondary">
+              {caption}
+            </Text>
+          </Stack>
+        </Card>
+      ))}
+    </Grid>
+  );
+}

package/templates/blocks/components/Card/ClickableCardElevated.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: 'ClickableCard',
+  name: 'ClickableCard — Elevated',
+  displayName: 'Clickable Card — Elevated',
+  description:
+    'A clickable card raised with `elevation="med"` so the shadow signals the whole surface is interactive.',
+  isReady: true,
+  aspectRatio: 1,
+  componentsUsed: ['ClickableCard', 'Layout', 'Text'],
+};

package/templates/blocks/components/Card/ClickableCardElevated.tsx

@@ -0,0 +1,21 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {ClickableCard} from '@astryxdesign/core/ClickableCard';
+import {Stack} from '@astryxdesign/core/Layout';
+import {Text, Heading} from '@astryxdesign/core/Text';
+
+export default function ClickableCardElevated() {
+  return (
+    <ClickableCard label="Open report" href="#" elevation="med" width={320}>
+      <Stack direction="vertical" gap={2}>
+        <Heading level={4}>Quarterly report</Heading>
+        <Text type="body" color="secondary">
+          A raised shadow signals the whole card is clickable, lifting it above
+          the surrounding content.
+        </Text>
+      </Stack>
+    </ClickableCard>
+  );
+}

package/templates/blocks/components/Card/SelectableCardElevated.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: 'SelectableCard',
+  name: 'SelectableCard — Elevated',
+  displayName: 'Selectable Card — Elevated',
+  description:
+    'Raised selectable cards with `elevation="low"`. The inset selection ring composes on top of the shadow, so a selected card keeps its elevation.',
+  isReady: true,
+  aspectRatio: 2,
+  componentsUsed: ['SelectableCard', 'Layout', 'Text'],
+};

package/templates/blocks/components/Card/SelectableCardElevated.tsx

@@ -0,0 +1,37 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {SelectableCard} from '@astryxdesign/core/SelectableCard';
+import {Grid} from '@astryxdesign/core/Grid';
+import {Text} from '@astryxdesign/core/Text';
+
+const PLANS = [
+  {id: 'starter', name: 'Starter'},
+  {id: 'pro', name: 'Pro'},
+];
+
+export default function SelectableCardElevated() {
+  const [selected, setSelected] = useState('pro');
+
+  return (
+    <Grid columns={2} gap={3} width={420}>
+      {PLANS.map(plan => (
+        <SelectableCard
+          key={plan.id}
+          label={plan.name}
+          isSelected={selected === plan.id}
+          onChange={() => setSelected(plan.id)}
+          elevation="low">
+          <Text type="body" weight="bold">
+            {plan.name}
+          </Text>
+          <Text type="supporting" color="secondary">
+            The resting shadow stays put — the selection ring layers on top.
+          </Text>
+        </SelectableCard>
+      ))}
+    </Grid>
+  );
+}

package/templates/blocks/components/Carousel/CarouselSnap.tsx

@@ -27,7 +27,7 @@ export default function CarouselSnap() {
         {TEAM.map(person => (
           <Card key={person.name} width={180} minHeight={140}>
             <Stack direction="vertical" gap={3} hAlign="center">
-              <Avatar name={person.name} size="medium" />
+              <Avatar name={person.name} size="lg" />
               <Stack direction="vertical" gap={1} hAlign="center">
                 <Text type="body" weight="bold">
                   {person.name}

package/templates/blocks/components/ChatComposer/ChatComposerFlat.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: 'ChatComposer',
+  name: 'ChatComposer — Flat',
+  displayName: 'ChatComposer — Flat',
+  description:
+    'The composer is raised by default (`elevation="low"`). Set `elevation="none"` to flatten it — it then draws a border with the same rest / hover / focus treatment as a text input.',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['ChatComposer', 'Layout', 'Text'],
+};