@astryxdesign/cli 0.1.8-canary.0c4d8d7 → 0.1.8-canary.0db5dfd

package/templates/blocks/components/InternationalizationProvider/InternationalizationProvider01ShippedLocale.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: 'InternationalizationProvider',
+  name: 'InternationalizationProvider — Shipped Locale',
+  displayName: 'Internationalization Provider — Shipped Locale',
+  description:
+    'Load a locale catalog shipped by Astryx and re-render InternationalizationProvider with a new locale to update Astryx strings live.',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: [
+    'InternationalizationProvider',
+    'SegmentedControl',
+    'Selector',
+    'Layout',
+  ],
+};

package/templates/blocks/components/InternationalizationProvider/InternationalizationProvider01ShippedLocale.tsx

@@ -0,0 +1,46 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {InternationalizationProvider} from '@astryxdesign/core/i18n';
+import frFR from '@astryxdesign/core/locales/fr-FR.json';
+import {Stack} from '@astryxdesign/core/Layout';
+import {
+  SegmentedControl,
+  SegmentedControlItem,
+} from '@astryxdesign/core/SegmentedControl';
+import {Selector} from '@astryxdesign/core/Selector';
+
+type Locale = 'en' | 'fr-FR';
+
+export default function InternationalizationProviderShippedLocale() {
+  const [locale, setLocale] = useState<Locale>('en');
+  const [value, setValue] = useState<string | null>(null);
+  return (
+    <InternationalizationProvider locale={locale} messages={{'fr-FR': frFR}}>
+      <Stack direction="vertical" gap={4} hAlign="center">
+        <SegmentedControl
+          label="Language"
+          value={locale}
+          onChange={nextLocale => setLocale(nextLocale as Locale)}
+          size="sm">
+          <SegmentedControlItem value="en" label="EN" />
+          <SegmentedControlItem value="fr-FR" label="FR" />
+        </SegmentedControl>
+        <Selector
+          style={{width: 300}}
+          label="Billing region"
+          options={[
+            {value: 'americas', label: 'Americas'},
+            {value: 'emea', label: 'EMEA'},
+            {value: 'apac', label: 'APAC'},
+          ]}
+          value={value}
+          onChange={setValue}
+          hasClear
+        />
+      </Stack>
+    </InternationalizationProvider>
+  );
+}

package/templates/blocks/components/InternationalizationProvider/InternationalizationProvider02Overrides.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: 'InternationalizationProvider',
+  name: 'InternationalizationProvider — Overrides',
+  displayName: 'Internationalization Provider — Overrides',
+  description:
+    'Override a small number of Astryx strings without providing a full locale catalog.',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['InternationalizationProvider', 'Selector'],
+};

package/templates/blocks/components/InternationalizationProvider/InternationalizationProvider02Overrides.tsx

@@ -0,0 +1,33 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {InternationalizationProvider} from '@astryxdesign/core/i18n';
+import {Selector} from '@astryxdesign/core/Selector';
+
+export default function InternationalizationProviderOverrides() {
+  const [value, setValue] = useState<string | null>(null);
+  return (
+    <InternationalizationProvider
+      locale="en"
+      overrides={{
+        en: {
+          '@astryx.selector.placeholder': 'Choose...',
+        },
+      }}>
+      <Selector
+        style={{width: 300}}
+        label="Billing region"
+        options={[
+          {value: 'americas', label: 'Americas'},
+          {value: 'emea', label: 'EMEA'},
+          {value: 'apac', label: 'APAC'},
+        ]}
+        value={value}
+        onChange={setValue}
+        hasClear
+      />
+    </InternationalizationProvider>
+  );
+}

package/{src/types → types}/api.contract.assert.ts

@@ -31,14 +31,14 @@
  */
 
 import type * as Api from './api';
-import type {component} from '../api/component.mjs';
-import type {docs} from '../api/docs.mjs';
-import type {discover} from '../api/discover.mjs';
-import type {template} from '../api/template.mjs';
+import type {component} from '../api/component/component.mjs';
+import type {docs} from '../api/docs/docs.mjs';
+import type {discover} from '../api/discover/discover.mjs';
+import type {template} from '../api/template/template.mjs';
 
 /** Resolve to `true` only when `A` and `B` are mutually assignable. */
 type Equal<A, B> =
-  (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2)
+  (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2
     ? true
     : false;
 
@@ -52,16 +52,25 @@ type Opt<T> = NonNullable<T>;
 // must describe the same set of keys/types, in both directions. ──────────────
 
 type _ComponentOptions = Expect<
-  Equal<Opt<Parameters<typeof Api.component>[1]>, Opt<Parameters<typeof component>[1]>>
+  Equal<
+    Opt<Parameters<typeof Api.component>[1]>,
+    Opt<Parameters<typeof component>[1]>
+  >
 >;
 type _DocsOptions = Expect<
   Equal<Opt<Parameters<typeof Api.docs>[2]>, Opt<Parameters<typeof docs>[2]>>
 >;
 type _DiscoverOptions = Expect<
-  Equal<Opt<Parameters<typeof Api.discover>[1]>, Opt<Parameters<typeof discover>[1]>>
+  Equal<
+    Opt<Parameters<typeof Api.discover>[1]>,
+    Opt<Parameters<typeof discover>[1]>
+  >
 >;
 type _TemplateOptions = Expect<
-  Equal<Opt<Parameters<typeof Api.template>[1]>, Opt<Parameters<typeof template>[1]>>
+  Equal<
+    Opt<Parameters<typeof Api.template>[1]>,
+    Opt<Parameters<typeof template>[1]>
+  >
 >;
 
 // ── Positional-argument parity: arity and positional types must match. ───────

package/{src/types → types}/api.d.ts

@@ -44,6 +44,16 @@ import type {
 import type {SearchResponse, SearchDomain} from './search';
 import type {ErrorCode} from './error-codes';
 import type {DoctorResponse} from './doctor';
+import type {
+  LayoutForm,
+  LayoutExpandResponse,
+  LayoutCheckResponse,
+  LayoutGrammarResponse,
+} from './layout';
+import type {ValidateIntegrationResponse} from './validate-integration';
+import type {AstryxIntegrationIssue} from './integration';
+import type {BuildHelpResponse, BuildKitResponse} from './build';
+import type {SwizzleListResponse, SwizzleCopyResponse} from './swizzle';
 import type {Suggestion} from './base';
 
 /** Structured API error with a stable machine-readable code. */
@@ -186,6 +196,47 @@ export declare function search(
   options?: SearchOptions,
 ): Promise<SearchResponse>;
 
+// ── Build ────────────────────────────────────────────────────────────
+
+export interface BuildOptions {
+  cwd?: string;
+  type?: SearchDomain;
+  limit?: number;
+}
+
+/**
+ * Page-building assistant. No query → `build.help` (playbook signal); a query →
+ * `build.kit` (grouped composition kit of raw search entries + frame/foundation).
+ */
+export declare function build(
+  query?: string,
+  options?: BuildOptions,
+): Promise<BuildHelpResponse | BuildKitResponse>;
+
+// ── Swizzle ──────────────────────────────────────────────────────────
+
+export interface SwizzleOptions {
+  cwd?: string;
+  /** Output directory (must resolve inside cwd). Defaults to ./components/astryx. */
+  output?: string;
+  /** Scope to a specific owning package when a name is ambiguous. */
+  package?: string;
+  /** Force the list response even with a component argument. */
+  list?: boolean;
+  /** Overwrite existing files instead of erroring. */
+  overwrite?: boolean;
+}
+
+/**
+ * List swizzlable components (no name / `list`) or copy one component's source
+ * into the project (side effect) and return a `swizzle.copy` receipt. Errors
+ * throw AstryxError (ERR_UNKNOWN_COMPONENT, ERR_AMBIGUOUS_COMPONENT, …).
+ */
+export declare function swizzle(
+  component?: string,
+  options?: SwizzleOptions,
+): Promise<SwizzleListResponse | SwizzleCopyResponse>;
+
 // ── Doctor ──────────────────────────────────
 
 export interface DoctorOptions {
@@ -195,3 +246,58 @@ export interface DoctorOptions {
 export declare function doctor(
   options?: DoctorOptions,
 ): Promise<DoctorResponse>;
+
+// ── Layout ───────────────────────────────────────────────────────────
+
+export interface LayoutExpandOptions {
+  targetPath?: string;
+  form?: LayoutForm;
+  loose?: boolean;
+  name?: string;
+  cwd?: string;
+}
+
+export declare function layoutExpand(
+  expression: string,
+  options?: LayoutExpandOptions,
+): Promise<LayoutExpandResponse>;
+
+export interface LayoutCheckOptions {
+  form?: LayoutForm;
+  loose?: boolean;
+  cwd?: string;
+}
+
+export declare function layoutCheck(
+  expression: string,
+  options?: LayoutCheckOptions,
+): Promise<LayoutCheckResponse>;
+
+export interface LayoutGrammarOptions {
+  cwd?: string;
+}
+
+export declare function layoutGrammar(
+  options?: LayoutGrammarOptions,
+): Promise<LayoutGrammarResponse>;
+
+// ── Validate integration ─────────────────────────────────────────────
+
+export interface ValidateIntegrationOptions {
+  cwd?: string;
+}
+
+/**
+ * Validate the local integration (no `pkg`) or an installed one (`pkg` given).
+ * The no-manifest local case returns `{ name: null, version: null, issues: [] }`.
+ */
+export declare function validateIntegration(
+  pkg?: string,
+  options?: ValidateIntegrationOptions,
+): Promise<ValidateIntegrationResponse>;
+
+/** Count issues by severity. */
+export declare function summarizeIssues(issues: AstryxIntegrationIssue[]): {
+  errors: number;
+  warnings: number;
+};

package/{src/types → types}/base.d.ts

@@ -43,14 +43,23 @@ import type {
   HookDetailParamsResponse,
 } from './hook';
 import type {SwizzleListResponse, SwizzleCopyResponse} from './swizzle';
-import type {ThemeBuildResponse} from './theme';
+import type {
+  ThemeBuildResponse,
+  ThemeListResponse,
+  ThemeAddResponse,
+} from './theme';
 import type {
   UpgradeListResponse,
   UpgradeRunResponse,
   UpgradeStatusResponse,
 } from './upgrade';
 import type {SearchResponse} from './search';
-import type {BuildHelpResponse} from './build';
+import type {
+  LayoutExpandResponse,
+  LayoutCheckResponse,
+  LayoutGrammarResponse,
+} from './layout';
+import type {BuildHelpResponse, BuildKitResponse} from './build';
 import type {ErrorCode} from './error-codes';
 import type {ManifestResponse} from './manifest';
 import type {DoctorResponse} from './doctor';
@@ -116,11 +125,17 @@ export type CLIAnyResponse =
   | SwizzleListResponse
   | SwizzleCopyResponse
   | ThemeBuildResponse
+  | ThemeListResponse
+  | ThemeAddResponse
   | UpgradeListResponse
   | UpgradeRunResponse
   | UpgradeStatusResponse
   | SearchResponse
+  | LayoutExpandResponse
+  | LayoutCheckResponse
+  | LayoutGrammarResponse
   | BuildHelpResponse
+  | BuildKitResponse
   | ManifestResponse
   | DoctorResponse
   | ValidateIntegrationResponse;

package/types/build.d.ts

@@ -0,0 +1,53 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Build command JSON responses.
+ *
+ * `astryx build` is the "assemble a page" verb. With no query it emits the
+ * workflow playbook; with a query it delegates to the search pipeline and
+ * emits a `search` response (see search.d.ts).
+ *
+ * Invocation                    -> type discriminator
+ * ---------------------------------------------------
+ * xds --json build              -> build.help
+ * xds --json build "<idea>"     -> build.kit
+ */
+
+import type {SearchResultEntry} from './search';
+
+/** xds --json build (no query) — the "how to build a page" playbook signal. */
+export interface BuildHelpResponse {
+  type: 'build.help';
+  data: {
+    /** Always true; marks this envelope as the playbook rather than a result set. */
+    playbook: true;
+  };
+}
+
+/**
+ * xds --json build "<idea>" — the composition kit for what you're building.
+ *
+ * Entries are raw `SearchResultEntry` objects (no package-manager-prefixed
+ * command strings — the CLI adds those); `frame`/`foundation` are static
+ * component-name arrays surfaced on every kit.
+ */
+export interface BuildKitResponse {
+  type: 'build.kit';
+  data: {
+    query: string;
+    /** False when search returned nothing (renderer shows "No matches"). */
+    hasResults: boolean;
+    /** True when the top page template is a confident direct match. */
+    directMatch: boolean;
+    /** Closest page templates (≤3). */
+    pages: SearchResultEntry[];
+    /** Drop-in block patterns covering parts of the idea (≤5). */
+    blocks: SearchResultEntry[];
+    /** Idea-specific components/hooks (≤6), excluding frame/foundation. */
+    domain: SearchResultEntry[];
+    /** Always-on page-shell component names. */
+    frame: string[];
+    /** Always-on layout/typography/action component names. */
+    foundation: string[];
+  };
+}

package/types/codemod.d.ts

@@ -0,0 +1,166 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Public type surface for the file-based codemod-authoring API exported from
+ * `@astryxdesign/cli/codemod`.
+ */
+
+/** A single source file presented to a codemod's transform. */
+export interface AstryxCodemodFile {
+  /** Absolute path to the file being transformed. */
+  path: string;
+  /** The current source contents of the file. */
+  source: string;
+}
+
+/** Helpers and context passed to a codemod's transform as the second argument. */
+export interface AstryxCodemodApi {
+  /** A jscodeshift instance configured with a parser for the file. */
+  jscodeshift: unknown;
+  /** Report a statistic (no-op-friendly; provided for jscodeshift parity). */
+  stats: (...args: unknown[]) => void;
+  /** Report progress (no-op-friendly; provided for jscodeshift parity). */
+  report: (...args: unknown[]) => void;
+}
+
+/**
+ * A codemod's transform. Return the new source to rewrite the file, or
+ * `null`/`undefined` to leave the file unchanged.
+ */
+export type AstryxCodemodTransform = (
+  file: AstryxCodemodFile,
+  api: AstryxCodemodApi,
+) => string | null | undefined;
+
+/** Definition accepted by {@link createCodemod}. */
+export interface AstryxCodemodDef {
+  /** Short, human-readable title shown in upgrade output. */
+  title: string;
+  /** Optional longer description. */
+  description?: string;
+  /** When true, the codemod runs only when explicitly requested. */
+  isOptional?: boolean;
+  /** File extensions this codemod applies to (e.g. ['.tsx', '.ts']). */
+  fileExtensions?: string[];
+  /** The transform function. */
+  transform: AstryxCodemodTransform;
+}
+
+/** Result of {@link createCodemod}. */
+export interface AstryxCodemod extends AstryxCodemodDef {
+  isOptional: boolean;
+  type: 'code';
+}
+
+/** Definition accepted by {@link createConfigCodemod}. */
+export interface AstryxConfigCodemodDef {
+  /** Short, human-readable title shown in upgrade output. */
+  title: string;
+  /** Optional longer description. */
+  description?: string;
+  /** When true, the codemod runs only when explicitly requested. */
+  isOptional?: boolean;
+  /** The transform function applied to the astryx.config.* file. */
+  transform: AstryxCodemodTransform;
+}
+
+/** Result of {@link createConfigCodemod}. */
+export interface AstryxConfigCodemod extends AstryxConfigCodemodDef {
+  isOptional: boolean;
+  type: 'config';
+}
+
+/** Define a file-transforming codemod. */
+export declare function createCodemod<T extends AstryxCodemodDef>(
+  def: T,
+): AstryxCodemod;
+
+/** Define a codemod that targets the consumer's astryx.config.* file. */
+export declare function createConfigCodemod<T extends AstryxConfigCodemodDef>(
+  def: T,
+): AstryxConfigCodemod;
+
+// ---------------------------------------------------------------------------
+// Internal types (used by the CLI codemod runner infrastructure & transforms).
+// These are not part of the public authoring surface but are shared across the
+// .mjs files under src/codemods/ so JSDoc annotations stay consistent.
+// ---------------------------------------------------------------------------
+
+/**
+ * jscodeshift transform signature. jscodeshift ships no type declarations, so
+ * the AST surface (`api.jscodeshift`, paths, node attributes) is untyped by
+ * design; transforms operate on it dynamically.
+ */
+export type CodemodTransform = (
+  file: AstryxCodemodFile,
+  api: CodemodTransformApi,
+) => string | null | undefined;
+
+/**
+ * The `api` argument as seen INSIDE a transform implementation. Identical to
+ * {@link AstryxCodemodApi} except `jscodeshift` is typed as the callable
+ * factory (jscodeshift ships no types, so the AST it returns is untyped). Used
+ * by the .mjs transforms so `const j = api.jscodeshift; j(file.source)` type-checks.
+ */
+export interface CodemodTransformApi {
+  jscodeshift: JscodeshiftFactory;
+  stats: (...args: unknown[]) => void;
+  report: (...args: unknown[]) => void;
+}
+
+/**
+ * A normalized codemod entry as produced by both the core registry runner and
+ * integration discovery. See the header of `run-codemod.mjs` for the contract.
+ */
+export interface CodemodEntry {
+  /** Unique id within its package/version (e.g. the transform module name). */
+  id: string;
+  /** Whether this is a source-file codemod or a config-file codemod. */
+  type: 'code' | 'config';
+  /** The codemod itself. */
+  codemod: {
+    title: string;
+    description?: string;
+    isOptional?: boolean;
+    fileExtensions?: string[];
+    transform: CodemodTransform;
+  };
+  /** Owning package name. */
+  package: string;
+  /** Owning package version. */
+  version?: string;
+}
+
+/** The result of running a single codemod over one or more files. */
+export interface CodemodRunResult {
+  filesChanged: number;
+  writtenFiles: string[];
+  errors: Array<{file: string; codemod: string; error: string}>;
+}
+
+/** The console-like log surface used across the codemod runners. */
+export interface CliLog {
+  step: (...args: unknown[]) => void;
+  info: (...args: unknown[]) => void;
+  success: (...args: unknown[]) => void;
+  warn: (...args: unknown[]) => void;
+  error: (...args: unknown[]) => void;
+  message?: (...args: unknown[]) => void;
+}
+
+/**
+ * The jscodeshift factory (the module's default export / `withParser` root).
+ * Callable and carries `withParser`; both return an untyped jscodeshift API.
+ *
+ * `any` is unavoidable here: jscodeshift ships no types and its AST/builder
+ * surface is fully dynamic (`j(src)`, `j.JSXElement`, `path.node`, …). `unknown`
+ * would break the callable + index access the transforms rely on.
+ */
+export interface JscodeshiftFactory {
+  /* eslint-disable @typescript-eslint/no-explicit-any */
+  (...args: any[]): any;
+  withParser: (parser: string) => any;
+  /** AST node types and builders (j.JSXElement, j.jsxAttribute, ...) are untyped. */
+  [key: string]: any;
+  /* eslint-enable @typescript-eslint/no-explicit-any */
+}

package/{src/types → types}/component.d.ts

@@ -23,7 +23,7 @@
  * (not found)                               -> CLIError
  */
 
-import type {ComponentDoc, PropDoc} from '../../../core/src/docs-types';
+import type {ComponentDoc, PropDoc} from '../../core/src/docs-types';
 
 /** xds --json component [--list] [--category X] [--detail brief] */
 export interface ComponentListResponse {

package/{src/types → types}/discover.d.ts

@@ -13,7 +13,7 @@
  * (not found)                                    -> CLIError
  */
 
-import type {ComponentDoc} from '../../../core/src/docs-types';
+import type {ComponentDoc} from '../../core/src/docs-types';
 
 /** xds --json discover */
 export interface DiscoverListResponse {

package/{src/types → types}/docs.d.ts

@@ -11,10 +11,7 @@
  * (unknown topic/section)                   -> CLIError
  */
 
-import type {
-  ReferenceDoc,
-  ReferenceSection,
-} from '../../../core/src/docs-types';
+import type {ReferenceDoc, ReferenceSection} from '../../core/src/docs-types';
 
 /** xds --json docs */
 export interface DocsListResponse {

package/{src/types → types}/hook.d.ts

@@ -20,7 +20,7 @@
  * (not found)                               -> CLIError
  */
 
-import type {HookDoc, HookParamDoc} from '../../../core/src/docs-types';
+import type {HookDoc, HookParamDoc} from '../../core/src/docs-types';
 
 /** xds --json hook [--list] [--category X] [--detail brief] */
 export interface HookListResponse {

package/types/jscodeshift.d.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Ambient declaration for `jscodeshift`, which ships no type declarations.
+ * The AST surface is intentionally untyped; codemod transforms operate on it
+ * dynamically. This keeps dynamic `import('jscodeshift')` from tripping TS7016
+ * under strict checkJs.
+ */
+declare module 'jscodeshift' {
+  interface JscodeshiftFactory {
+    /* eslint-disable @typescript-eslint/no-explicit-any */
+    (...args: any[]): any;
+    withParser: (parser: string) => any;
+    [key: string]: any;
+    /* eslint-enable @typescript-eslint/no-explicit-any */
+  }
+  const jscodeshift: JscodeshiftFactory;
+  export default jscodeshift;
+}