@astryxdesign/cli 0.1.6-canary.eb23da7 → 0.1.6-canary.eba4f34

package/src/lib/component-discovery.importpath.test.mjs

@@ -1,59 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Verifies that `.ts`-authored sources (hooks and other functions) are
- * found by `findComponentSource`, so `resolveImportPath` derives a
- * tree-shakeable subpath instead of falling back to the bare package root.
- *
- * Runs against the real packages/core source, not mocks.
- */
-
-import {describe, it, expect} from 'vitest';
-import {
-  findComponentSource,
-  resolveImportPath,
-} from './component-discovery.mjs';
-import {findCoreDir} from '../utils/paths.mjs';
-
-describe('findComponentSource resolves .ts-authored sources', () => {
-  const coreDir = findCoreDir();
-
-  it('finds a hook authored as a .ts file (not just .tsx)', () => {
-    const src = findComponentSource(coreDir, 'useMediaQuery');
-    expect(src).toBeTruthy();
-    expect(src.endsWith('useMediaQuery.ts')).toBe(true);
-  });
-
-  it('still finds a component authored as .tsx', () => {
-    const src = findComponentSource(coreDir, 'Button');
-    expect(src).toBeTruthy();
-    expect(src.endsWith('.tsx')).toBe(true);
-  });
-});
-
-describe('resolveImportPath reproduces authored hook importPaths', () => {
-  const coreDir = findCoreDir();
-
-  // Representative sample of core hooks whose sources are `.ts` files. Before
-  // the `.ts` fix these fell back to bare `@astryxdesign/core`; the derived
-  // subpath must now match the value each hook's doc currently authors.
-  const cases = [
-    ['useMediaQuery', '@astryxdesign/core/hooks'],
-    ['useResizable', '@astryxdesign/core/Resizable'],
-    ['useTheme', '@astryxdesign/core/theme'],
-    ['useFocusTrap', '@astryxdesign/core/hooks'],
-    ['useOverflow', '@astryxdesign/core/hooks'],
-  ];
-
-  for (const [name, expected] of cases) {
-    it(`${name} derives ${expected}`, () => {
-      expect(resolveImportPath(coreDir, name)).toBe(expected);
-    });
-  }
-
-  it('never falls back to the bare package root for a .ts hook', () => {
-    for (const [name] of cases) {
-      expect(resolveImportPath(coreDir, name)).not.toBe('@astryxdesign/core');
-    }
-  });
-});

package/src/types/doc.d.ts

@@ -1,139 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * Authoring surface for Astryx docs, exported from `@astryxdesign/cli/doc`.
- *
- * A doc lives in a `{Name}.doc.{ts,mjs,js}` file. Authors default-export a
- * factory result (`createComponentDoc`/`createFunctionDoc`/`createDoc`) —
- * preferred — or, for the current loose docs, name-export `docs`. The doc's
- * shape is validated at the load boundary against `ComponentDocSchema` (see
- * `doc.mjs`), which accepts BOTH the new stamped formats and the legacy loose
- * shape.
- *
- * The factories inject the `type` discriminant, so authors never write it. The
- * inputs are kept as broad records so authoring never fails to typecheck when a
- * richer core type surface is not resolvable; the precise per-field guidance
- * lives on the doc types in `@astryxdesign/core/docs-types`.
- */
-
-/**
- * Fields shared by every doc kind (component + function + generic).
- *
- * `group` vs `parent` are distinct:
- *   - `group` is a FLAT sidebar bucket label; many docs can share it and it is
- *     NOT an inheritance key.
- *   - `parent` is a DIRECTED inheritance/composition pointer — a doc naming the
- *     doc it belongs to (e.g. a sub-component naming its parent component). The
- *     legacy `subComponentOf` field is a synonym.
- *
- * `relatedDocs` is a single flat curated cross-reference list; it replaces the
- * legacy split `relatedComponents` + `relatedHooks`.
- */
-export interface AstryxBaseDocInput {
-  /** Name of the documented unit, without any prefix, PascalCase. Required. */
-  name: string;
-  /** Human-readable display name for gallery/sidebar. */
-  displayName?: string;
-  /** Short description. */
-  description?: string;
-  /** Usage documentation (description, best practices, anatomy, slotElements). */
-  usage?: unknown;
-  /** Flat sidebar grouping label (not an inheritance key). */
-  group?: string;
-  /** Overview-page functional category. */
-  category?: string;
-  /** CLI fuzzy-search keywords. */
-  keywords?: string[];
-  /** Directed inheritance/composition pointer to the doc this belongs to. */
-  parent?: string;
-  /** Flat curated cross-reference list of related doc names. */
-  relatedDocs?: string[];
-  /** Hide the whole doc from human-facing UI (stays importable/discoverable). */
-  hidden?: boolean;
-  /** Exclude from the categorized overview page (kept in sidebar/CLI). */
-  isHiddenFromOverview?: boolean;
-  /** Any additional fields the rich doc surface carries. */
-  [key: string]: unknown;
-}
-
-/** A single documented prop (mirrors `PropDoc` from core docs-types). */
-export interface AstryxPropInput {
-  name: string;
-  type: string;
-  description: string;
-  default?: string;
-  required?: boolean;
-  [key: string]: unknown;
-}
-
-/** A single documented param (mirrors `HookParamDoc`). */
-export interface AstryxParamInput {
-  name: string;
-  type: string;
-  description: string;
-  default?: string;
-  required?: boolean;
-  [key: string]: unknown;
-}
-
-/** A single documented return field (mirrors `HookReturnDoc`). */
-export interface AstryxReturnInput {
-  name: string;
-  type: string;
-  description: string;
-  [key: string]: unknown;
-}
-
-/**
- * Input accepted by {@link createComponentDoc}. A component (or a family). The
- * `type` discriminant is injected by the factory. `anatomy`/`slotElements` live
- * inside `usage`; `importPath` is DERIVED (never authored).
- */
-export interface AstryxComponentDocInput extends AstryxBaseDocInput {
-  /** All public props for the component. */
-  props: AstryxPropInput[];
-  /** Theming/selector-surface metadata. */
-  theming?: unknown;
-  /** Interactive-preview playground configuration. */
-  playground?: unknown;
-  /** Short code examples rendered after the props table. */
-  examples?: unknown[];
-}
-
-/**
- * Input accepted by {@link createFunctionDoc}. Covers any function, including
- * hooks: an inputs (`params`) + outputs (`returns`) surface. The `type`
- * discriminant is injected by the factory; `importPath` is DERIVED.
- */
-export interface AstryxFunctionDocInput extends AstryxBaseDocInput {
-  /** Function/hook parameters or options-object fields. */
-  params: AstryxParamInput[];
-  /** Return value documentation. One entry per field (or a single primitive). */
-  returns: AstryxReturnInput[];
-}
-
-/**
- * Input accepted by {@link createDoc}. A generic reference/topic doc — just the
- * shared base. The `type` discriminant is injected by the factory.
- */
-export type AstryxGenericDocInput = AstryxBaseDocInput;
-
-/**
- * Back-compat alias. Previously `createDoc` accepted a broad component-doc
- * record; the union of the three input kinds preserves that permissiveness for
- * any code referring to the old name.
- */
-export type AstryxComponentDoc =
-  AstryxComponentDocInput | AstryxFunctionDocInput | AstryxGenericDocInput;
-
-export declare function createComponentDoc<T extends AstryxComponentDocInput>(
-  def: T,
-): T & {type: 'component'};
-
-export declare function createFunctionDoc<T extends AstryxFunctionDocInput>(
-  def: T,
-): T & {type: 'function'};
-
-export declare function createDoc<T extends AstryxGenericDocInput>(
-  def: T,
-): T & {type: 'generic'};

package/templates/blocks/components/VisuallyHidden/VisuallyHiddenLiveRegion.doc.mjs

@@ -1,14 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
-  type: 'block',
-  exampleFor: 'VisuallyHidden',
-  name: 'VisuallyHidden — Live Region',
-  displayName: 'VisuallyHidden — Live Region',
-  description:
-    'A polite aria-live region announces visual-only state changes to assistive technology.',
-  isReady: true,
-  aspectRatio: 4 / 3,
-  componentsUsed: ['VisuallyHidden', 'Button', 'HStack', 'VStack', 'Text'],
-};

package/templates/blocks/components/VisuallyHidden/VisuallyHiddenLiveRegion.tsx

@@ -1,41 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-'use client';
-
-import {useState} from 'react';
-import {VisuallyHidden} from '@astryxdesign/core/VisuallyHidden';
-import {Button} from '@astryxdesign/core/Button';
-import {HStack, VStack} from '@astryxdesign/core/Layout';
-import {Text} from '@astryxdesign/core/Text';
-
-const columns = ['Backlog', 'In progress', 'Done'] as const;
-
-export default function VisuallyHiddenLiveRegion() {
-  const [column, setColumn] = useState(0);
-  const current = columns[column];
-
-  function move() {
-    setColumn(c => (c + 1) % columns.length);
-  }
-
-  return (
-    <VStack gap={4} hAlign="start">
-      <Text type="supporting" color="secondary">
-        Drag-and-drop and other visual-only changes are silent to screen
-        readers. A live region narrates them.
-      </Text>
-      <HStack gap={3} vAlign="center">
-        <Button label="Move task" variant="secondary" onClick={move} />
-        <Text type="body">
-          Task is in{' '}
-          <Text as="span" weight="bold">
-            {current}
-          </Text>
-        </Text>
-      </HStack>
-      <VisuallyHidden as="div" aria-live="polite">
-        {`Task moved to ${current}`}
-      </VisuallyHidden>
-    </VStack>
-  );
-}

package/templates/blocks/components/VisuallyHidden/VisuallyHiddenShowcase.doc.mjs

@@ -1,13 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
-  type: 'block',
-  exampleFor: 'VisuallyHidden',
-  name: 'VisuallyHidden',
-  displayName: 'VisuallyHidden',
-  isReady: true,
-  aspectRatio: 16 / 9,
-  isShowcase: true,
-  componentsUsed: ['VisuallyHidden', 'IconButton', 'Card', 'HStack', 'VStack', 'Text', 'Icon'],
-};

package/templates/blocks/components/VisuallyHidden/VisuallyHiddenShowcase.tsx

@@ -1,78 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-'use client';
-
-import {VisuallyHidden} from '@astryxdesign/core/VisuallyHidden';
-import {IconButton} from '@astryxdesign/core/IconButton';
-import {Card} from '@astryxdesign/core/Card';
-import {HStack, VStack} from '@astryxdesign/core/Layout';
-import {Text} from '@astryxdesign/core/Text';
-import {Icon} from '@astryxdesign/core/Icon';
-import {
-  ArrowDownTrayIcon,
-  ShareIcon,
-  TrashIcon,
-} from '@heroicons/react/24/outline';
-import {SpeakerWaveIcon} from '@heroicons/react/24/solid';
-
-const actions = [
-  {label: 'Download', icon: ArrowDownTrayIcon},
-  {label: 'Share', icon: ShareIcon},
-  {label: 'Delete', icon: TrashIcon},
-] as const;
-
-/**
- * VisuallyHidden is invisible by design, so this hero teaches the concept by
- * contrast: the icon-only buttons are all a sighted user sees, while the
- * caption spells out the accessible name each one exposes. A live
- * <VisuallyHidden> region below announces the same names to assistive tech,
- * so the demo genuinely exercises the component it documents.
- */
-export default function VisuallyHiddenShowcase() {
-  return (
-    <VStack gap={5} hAlign="center">
-      <HStack gap={6} vAlign="stretch" wrap="wrap" hAlign="center">
-        <Card variant="muted">
-          <VStack gap={4} hAlign="center">
-            <Text type="supporting" color="secondary">
-              What you see
-            </Text>
-            <HStack gap={2}>
-              {actions.map(({label, icon}) => (
-                <IconButton
-                  key={label}
-                  label={label}
-                  icon={<Icon icon={icon} />}
-                  variant="ghost"
-                />
-              ))}
-            </HStack>
-          </VStack>
-        </Card>
-
-        <Card variant="muted">
-          <VStack gap={4} hAlign="start">
-            <HStack gap={2} vAlign="center">
-              <Icon icon={SpeakerWaveIcon} size="sm" />
-              <Text type="supporting" color="secondary">
-                What a screen reader hears
-              </Text>
-            </HStack>
-            <VStack gap={2}>
-              {actions.map(({label}) => (
-                <Text key={label} type="body">
-                  {label}, button
-                </Text>
-              ))}
-            </VStack>
-          </VStack>
-        </Card>
-      </HStack>
-
-      {/* A real live region: silent to sighted users, announced by AT. */}
-      <VisuallyHidden as="div" aria-live="polite">
-        Actions available: Download, Share, Delete.
-      </VisuallyHidden>
-    </VStack>
-  );
-}

package/templates/blocks/components/VisuallyHidden/VisuallyHiddenStructuralHeading.doc.mjs

@@ -1,14 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
-  type: 'block',
-  exampleFor: 'VisuallyHidden',
-  name: 'VisuallyHidden — Structural Heading',
-  displayName: 'VisuallyHidden — Structural Heading',
-  description:
-    'Give a visually implicit section an accessible name so screen-reader users can navigate to it.',
-  isReady: true,
-  aspectRatio: 4 / 3,
-  componentsUsed: ['VisuallyHidden', 'Card', 'HStack', 'VStack', 'Text', 'Badge'],
-};

package/templates/blocks/components/VisuallyHidden/VisuallyHiddenStructuralHeading.tsx

@@ -1,38 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-'use client';
-
-import {VisuallyHidden} from '@astryxdesign/core/VisuallyHidden';
-import {Card} from '@astryxdesign/core/Card';
-import {HStack, VStack} from '@astryxdesign/core/Layout';
-import {Text} from '@astryxdesign/core/Text';
-import {Badge} from '@astryxdesign/core/Badge';
-
-const items = [
-  {name: 'astryx-core', status: 'Passing', variant: 'success'},
-  {name: 'astryx-charts', status: 'Failing', variant: 'error'},
-  {name: 'astryx-cli', status: 'Passing', variant: 'success'},
-] as const;
-
-export default function VisuallyHiddenStructuralHeading() {
-  return (
-    <VStack gap={3} hAlign="start">
-      <Text type="supporting" color="secondary">
-        The layout makes this group obvious to sighted users. A hidden heading
-        gives screen-reader users the same landmark to jump to.
-      </Text>
-      {/* No visible heading is needed here, but AT users navigate by heading. */}
-      <VisuallyHidden as="h2">Build status</VisuallyHidden>
-      <VStack gap={2}>
-        {items.map(({name, status, variant}) => (
-          <Card key={name} variant="muted" padding={3}>
-            <HStack gap={3} vAlign="center">
-              <Text type="body">{name}</Text>
-              <Badge label={status} variant={variant} />
-            </HStack>
-          </Card>
-        ))}
-      </VStack>
-    </VStack>
-  );
-}

package/templates/blocks/components/VisuallyHidden/VisuallyHiddenSupplementaryContext.doc.mjs

@@ -1,14 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
-  type: 'block',
-  exampleFor: 'VisuallyHidden',
-  name: 'VisuallyHidden — Supplementary Context',
-  displayName: 'VisuallyHidden — Supplementary Context',
-  description:
-    'Add screen-reader-only context to terse visual data, like spelling out what a trend arrow means.',
-  isReady: true,
-  aspectRatio: 4 / 3,
-  componentsUsed: ['VisuallyHidden', 'Card', 'HStack', 'VStack', 'Text', 'Icon'],
-};

package/templates/blocks/components/VisuallyHidden/VisuallyHiddenSupplementaryContext.tsx

@@ -1,47 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-'use client';
-
-import {VisuallyHidden} from '@astryxdesign/core/VisuallyHidden';
-import {Card} from '@astryxdesign/core/Card';
-import {HStack, VStack} from '@astryxdesign/core/Layout';
-import {Text} from '@astryxdesign/core/Text';
-import {Icon} from '@astryxdesign/core/Icon';
-import {ArrowUpIcon, ArrowDownIcon} from '@heroicons/react/24/solid';
-
-const stats = [
-  {label: 'Revenue', value: '$48.2k', delta: '+12%', direction: 'up'},
-  {label: 'Churn', value: '2.1%', delta: '-4%', direction: 'down'},
-] as const;
-
-export default function VisuallyHiddenSupplementaryContext() {
-  return (
-    <HStack gap={4} wrap="wrap">
-      {stats.map(({label, value, delta, direction}) => (
-        <Card key={label} variant="muted">
-          <VStack gap={1}>
-            <Text type="supporting" color="secondary">
-              {label}
-            </Text>
-            <Text type="display-3">{value}</Text>
-            <HStack gap={1} vAlign="center">
-              <Icon
-                icon={direction === 'up' ? ArrowUpIcon : ArrowDownIcon}
-                size="sm"
-                color={direction === 'up' ? 'accent' : 'secondary'}
-              />
-              <Text type="body">
-                {delta}
-                {/* The arrow is decorative; spell out the trend for AT. */}
-                <VisuallyHidden>
-                  {direction === 'up' ? ' increase' : ' decrease'} from last
-                  month
-                </VisuallyHidden>
-              </Text>
-            </HStack>
-          </VStack>
-        </Card>
-      ))}
-    </HStack>
-  );
-}