@astryxdesign/cli 0.1.6-canary.aeb5ee6 → 0.1.6-canary.ba37404

package/docs/integration-authoring.md

@@ -0,0 +1,105 @@
+# Authoring an Astryx Integration
+
+> **Status:** working notes. This should eventually move to the public wiki
+> alongside the rest of the integration-authoring guidance; it lives here for
+> now so it ships and is versioned with the CLI.
+
+An **Integration** is an npm package that contributes components, templates, and/or
+codemods to a consumer's design-system workflow. Consumers install the 3rd party
+package, add a line to their astryx.config file:
+
+```js
+import {createConfig} from '@astryxdesign/cli/config';
+
+export default createConfig({
+  integrations: ['@acme/astryx-widgets'],
+  ...
+});
+```
+
+Then the integration's components and templates will be surfaced alongside Astryx
+components in the Astryx CLI.
+
+```sh
+astryx component AcmeCarousel --props
+astryx component --list --package @acme/astryx-widgets
+```
+
+## The Integration File
+
+In order to register your package as an Astryx Integration, create an
+`astryx.integration.{ts,mjs,js}` file as a sibling to your `package.json`. This file
+tells Astryx where to find your components, templates, codemods, etc.
+
+```js
+// astryx.integration.{ts,mjs,js}
+import {createIntegration} from '@astryxdesign/cli/integration';
+
+export default createIntegration({
+  components: './components',
+  templates: './templates',
+  codemods: './codemods',
+  issuesUrl: 'https://github.com/acme/widgets/issues',
+});
+```
+
+## Components
+
+Your components themselves may be exported from your library as you see fit (consumers
+will still import them from your package) but Astryx CLI will look for a .doc.{ts,mjs,js}
+file with the same stem e.g. `AcmeCarousel.tsx` and `AcmeCarousel.doc.ts`.
+
+```js
+// AcmeCarousel.doc.ts
+import {createComponentDoc} from '@astryxdesign/cli/doc';
+
+export default createComponentDoc({
+  name: 'AcmeCarousel',
+  description: '...',
+  ...
+});
+```
+
+## Templates
+
+Templates are typically not exported from the package directly, but instead accessed
+via the Astryx CLI. Consumers can look through your templates and materialize them
+into their apps.
+
+You define a template with the `createPageTemplate` (for full pages) or `createBlockTemplate`
+(for smaller chunks). e.g. `AcmeLandingPage.tsx`, `AcmeLandingPage.template.ts`
+
+```js
+// AcmeLandingPage.template.ts
+import {createPageTemplate} from '@astryxdesign/cli/template';
+
+export default createPageTemplate({
+  ...
+});
+```
+
+Note that, since the CLI needs access to the template source code, you need to make sure
+that it is included in your published package. This will also allow us to render previews
+of templates in the future by bundling your template into a doc site build.
+
+Typically, this is done via the package.json `exports` key.
+
+```jsonc
+{
+  "exports": {
+    // ...
+    "./templates/*.tsx": "./templates/*.tsx",
+  },
+}
+```
+
+In order to verify that it's working, you can test importing the template component like this:
+
+```ts
+import('@acme/astryx-widgets/templates/AcmeLandingPage.tsx');
+```
+
+Import **with the `.tsx` extension** — an extensionless specifier won't resolve
+under `moduleResolution: bundler`. The extensionful `"./templates/*.tsx"` export
+above is what lets that import type-check without consumers enabling
+`allowImportingTsExtensions`.

package/docs/internationalization.doc.mjs

@@ -0,0 +1,243 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../core/src/docs-types').ReferenceDoc} */
+
+export const docs = {
+  name: 'internationalization',
+  title: 'Internationalization',
+  category: 'guide',
+  description:
+    'Localize astryx component strings, provide translation catalogs, override default text, coexist with your own i18n library, swap languages at runtime, and test translations with the pseudo locale.',
+
+  sections: [
+    {
+      title: 'Quick Start',
+      category: 'guide',
+      content: [
+        {
+          type: 'prose',
+          text: 'Internationalization ships with `@astryxdesign/core`. There is nothing to install. Wrap your app in `<InternationalizationProvider>` and set a `locale` — astryx components pick up localized strings automatically.',
+        },
+        {
+          type: 'code',
+          lang: 'tsx',
+          label: 'Wrap your app',
+          code: `import {InternationalizationProvider} from '@astryxdesign/core';
+
+function App() {
+  return (
+    <InternationalizationProvider locale="en">
+      <YourApp />
+    </InternationalizationProvider>
+  );
+}`,
+        },
+        {
+          type: 'code',
+          lang: 'tsx',
+          label: 'Read strings inside a component',
+          code: `import {useTranslator} from '@astryxdesign/core';
+
+function SaveButton() {
+  const t = useTranslator();
+  return <button>{t('@myapp.actions.save')}</button>;
+}`,
+        },
+        {
+          type: 'prose',
+          text: 'The hook is available to consumer components too, but using it is entirely optional — many teams keep their app strings on their existing i18n library (react-intl, i18next, next-intl, LinguiJS) and only use `useTranslator` when reading astryx keys. If you do route your own strings through it, we recommend namespacing them (`@myapp.*` or your npm scope) to keep them separated from `@astryx.*`, but this is a convention, not a requirement — the resolver treats every key as an opaque string.',
+        },
+        {
+          type: 'prose',
+          text: "Astryx ships translations only for English today. First-party translations for other locales are on the roadmap and coming soon — track https://github.com/facebook/astryx/issues/3641. In the meantime, if you want astryx UI translated into another locale, you can ship your own catalog through the `messages` prop (covered in the next section). If you're using `useTranslator` for your own strings, you'll want to ship your own catalog either way — astryx only carries the fallback for `@astryx.*` keys, not the ones you author.",
+        },
+      ],
+    },
+    {
+      title: 'Providing locale catalogs',
+      category: 'guide',
+      content: [
+        {
+          type: 'prose',
+          text: 'Astryx bundles only the English catalog today. To render in any other locale, provide a translation catalog through the `messages` prop and set `locale` accordingly. This matches how MUI, Ant Design, and AG Grid work — the consumer app supplies the catalogs it actually needs so unused translations stay out of the bundle.',
+        },
+        {
+          type: 'code',
+          lang: 'tsx',
+          label: 'Add French',
+          code: `import {InternationalizationProvider} from '@astryxdesign/core';
+import fr from './locales/astryx/fr.json';
+
+<InternationalizationProvider locale="fr" messages={{fr}}>
+  <App />
+</InternationalizationProvider>;`,
+        },
+        {
+          type: 'prose',
+          text: "See `@astryxdesign/core/locales/en.json` for the full inventory of keys to translate. Copy it as the starting point — every key you translate replaces the English default; anything you omit falls back through the locale chain to English (e.g. `pt-BR` walks to `pt` then to shipped `en`), so a partial translation renders as a mix rather than empty text or raw key names.",
+        },
+        {
+          type: 'prose',
+          text: 'A community-maintained set of astryx translations is on the roadmap but not shipped yet. For now, consumer apps that ship in multiple languages own their astryx catalogs alongside their app catalogs. Contributions to a first-party set are welcome — track discussion at https://github.com/facebook/astryx/issues/3641.',
+        },
+      ],
+    },
+    {
+      title: "Overriding astryx's default text",
+      category: 'guide',
+      content: [
+        {
+          type: 'prose',
+          text: 'Use `overrides` to change individual strings without shipping a full catalog. Overrides are keyed by locale and merged on top of the built-in and user-supplied catalogs.',
+        },
+        {
+          type: 'code',
+          lang: 'tsx',
+          label: 'Change one string in English',
+          code: `<InternationalizationProvider
+  locale="en"
+  overrides={{en: {'@astryx.pagination.next': 'Next →'}}}
+>
+  <App />
+</InternationalizationProvider>`,
+        },
+        {
+          type: 'prose',
+          text: 'Overrides win over both bundled English and any `messages` catalog for the same key. Use them for brand voice tweaks or one-off wording changes.',
+        },
+      ],
+    },
+    {
+      title: 'Using astryx with your own i18n library',
+      category: 'guide',
+      content: [
+        {
+          type: 'prose',
+          text: "Astryx components render astryx strings through astryx's provider. Consumer components render consumer strings through whatever i18n library you already use — react-intl, i18next, next-intl, LinguiJS, and so on. The two systems coexist and read from the same source of truth for the active locale.",
+        },
+        {
+          type: 'code',
+          lang: 'tsx',
+          label: 'Astryx + react-intl side by side',
+          code: `import {InternationalizationProvider} from '@astryxdesign/core';
+import {Selector} from '@astryxdesign/core/Selector';
+import {Button} from '@astryxdesign/core/Button';
+import {FormattedMessage, IntlProvider, useIntl} from 'react-intl';
+import astryxFr from './locales/astryx/fr.json'; // astryx's UI, in French
+import appFr from './locales/app/fr.json';       // your app strings, in French
+
+function Pricing() {
+  // Consumer strings — resolved by react-intl.
+  const intl = useIntl();
+
+  return (
+    <section>
+      <h1><FormattedMessage id="pricing.heading" /></h1>
+
+      {/* Astryx Selector — trigger placeholder, search-box placeholder,
+          clear-button aria-label all resolved by
+          <InternationalizationProvider>. Options come from react-intl. */}
+      <Selector
+        label={intl.formatMessage({id: 'pricing.region.label'})}
+        options={[
+          {value: 'na', label: intl.formatMessage({id: 'pricing.region.na'})},
+          {value: 'eu', label: intl.formatMessage({id: 'pricing.region.eu'})},
+        ]}
+        hasSearch
+        hasClear
+      />
+
+      <Button label={intl.formatMessage({id: 'pricing.cta.subscribe'})} />
+    </section>
+  );
+}
+
+export default function App() {
+  return (
+    // Same locale, two providers reading their own catalogs.
+    <IntlProvider locale="fr" messages={appFr}>
+      <InternationalizationProvider locale="fr" messages={{fr: astryxFr}}>
+        <Pricing />
+      </InternationalizationProvider>
+    </IntlProvider>
+  );
+}`,
+        },
+        {
+          type: 'prose',
+          text: 'Keep the two providers in sync on locale, and each library owns its own catalog. Astryx never sees your app strings, and your i18n library never sees astryx internals. Runtime locale swap works the same way — re-render both providers with a new `locale` prop and the whole tree updates live.',
+        },
+        {
+          type: 'prose',
+          text: "Single-catalog usage — where an external i18n runtime like react-intl or i18next resolves both your app strings AND astryx's strings through one provider — is on the roadmap via a `Translator` adapter. Track https://github.com/facebook/astryx/issues/4029. For now, run the two providers side by side as shown above.",
+        },
+      ],
+    },
+    {
+      title: 'Runtime language swap',
+      category: 'guide',
+      content: [
+        {
+          type: 'prose',
+          text: 'Re-render `<InternationalizationProvider>` with a new `locale` prop and every astryx string updates live. No reload, no separate API call.',
+        },
+        {
+          type: 'code',
+          lang: 'tsx',
+          label: 'Toggle between locales',
+          code: `const [locale, setLocale] = useState<'en' | 'fr'>('en');
+
+<InternationalizationProvider locale={locale} messages={{fr}}>
+  <Button
+    label={locale === 'en' ? 'Français' : 'English'}
+    onClick={() => setLocale(l => (l === 'en' ? 'fr' : 'en'))}
+  />
+  <App />
+</InternationalizationProvider>;`,
+        },
+        {
+          type: 'prose',
+          text: "Persisting the user's choice (localStorage, cookie, URL segment, account setting) is up to the consumer. Astryx reads whatever `locale` you pass in.",
+        },
+      ],
+    },
+    {
+      title: 'Testing your translations',
+      category: 'guide',
+      content: [
+        {
+          type: 'prose',
+          text: 'Astryx generates a `pseudo` locale that wraps every string in `⟦…⟧` and replaces letters with accented look-alikes. Switching to it in development instantly reveals any astryx string that isn\'t going through the translator, plus any layout that breaks under longer text.',
+        },
+        {
+          type: 'code',
+          lang: 'tsx',
+          label: 'Turn on pseudo-localization',
+          code: `import pseudo from '@astryxdesign/core/locales/pseudo.json';
+
+<InternationalizationProvider locale="pseudo" messages={{pseudo}}>
+  <App />
+</InternationalizationProvider>;`,
+        },
+        {
+          type: 'prose',
+          text: 'Any bare English text you still see on screen is a hardcoded string that needs to be routed through `useTranslator`.',
+        },
+        {
+          type: 'prose',
+          text: "Pseudoloc also has a subtle caveat worth knowing: the pseudo catalog is complete (astryx generates it from every shipped key), so a component using an astryx-shipped key will always render its pseudo version. Your handwritten translation catalogs, on the other hand, only cover the keys you translated — anything missing falls back to English. That means \"looks perfect in pseudo\" is not the same guarantee as \"looks perfect in French.\" Check each real locale by hand for coverage gaps.",
+        },
+      ],
+    },
+    {
+      title: 'For contributors',
+      category: 'guide',
+      content: [
+        {
+          type: 'prose',
+          text: "Astryx's own strings live in `packages/core/locales/en.json`. New user-facing strings must go through `useTranslator` — this is enforced by the `@astryx/no-hardcoded-i18n-string` ESLint rule. See the AI contribution guide for the alias-and-resolve pattern used when adding new keys.",
+        },
+      ],
+    },
+  ],
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.1.6-canary.aeb5ee6",
+  "version": "0.1.6-canary.ba37404",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -75,10 +75,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/charts": "0.1.6-canary.aeb5ee6",
-    "@astryxdesign/core": "0.1.6-canary.aeb5ee6",
-    "@astryxdesign/lab": "0.1.6-canary.aeb5ee6",
-    "@astryxdesign/theme-neutral": "0.1.6-canary.aeb5ee6",
+    "@astryxdesign/charts": "0.1.6-canary.ba37404",
+    "@astryxdesign/core": "0.1.6-canary.ba37404",
+    "@astryxdesign/lab": "0.1.6-canary.ba37404",
+    "@astryxdesign/theme-neutral": "0.1.6-canary.ba37404",
     "gpt-tokenizer": "^3.4.0"
   },
   "peerDependenciesMeta": {
@@ -96,10 +96,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.1.6-canary.aeb5ee6",
-    "@astryxdesign/core": "0.1.6-canary.aeb5ee6",
-    "@astryxdesign/lab": "0.1.6-canary.aeb5ee6",
-    "@astryxdesign/theme-neutral": "0.1.6-canary.aeb5ee6",
+    "@astryxdesign/charts": "0.1.6-canary.ba37404",
+    "@astryxdesign/core": "0.1.6-canary.ba37404",
+    "@astryxdesign/lab": "0.1.6-canary.ba37404",
+    "@astryxdesign/theme-neutral": "0.1.6-canary.ba37404",
     "gpt-tokenizer": "^3.4.0"
   },
   "scripts": {

package/src/api/integration-block-exports.test.mjs

@@ -0,0 +1,240 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Proves the minimal `exports` recipe an integration package needs so a
+ * bundler-resolution consumer can `import()` its block templates AND type-check
+ * them under `moduleResolution: bundler`.
+ *
+ * Integration packages in this ecosystem ship TypeScript SOURCE — their block
+ * templates are `.tsx` files with no compiled `.d.ts`. A later feature renders
+ * showcase previews by a REAL dynamic `import()` of a block's `.tsx` source
+ * (e.g. `import('@acme/widgets/templates/Gauge/GaugeShowcase.tsx')`) instead of
+ * eval'ing source text. For that import to resolve, the integration's
+ * `package.json#exports` map must GATE the deep path.
+ *
+ * These tests stand up a throwaway `@acme/widgets` fixture and drive the two
+ * gates that matter with the repo's own toolchain:
+ *   1. `tsc --noEmit` under `moduleResolution: bundler` (the consumer profile
+ *      used by the Next.js example apps — NO `allowImportingTsExtensions`).
+ *   2. `esbuild --bundle` (a real bundler resolving + loading the deep import).
+ *
+ * CANONICAL RECIPE (see integration-authoring.md):
+ *   exports: { "./templates/*.tsx": "./templates/*.tsx" }
+ *   import:  import('@acme/widgets/templates/<Name>/<Name>Showcase.tsx')   // WITH .tsx
+ *
+ * The negative controls lock in WHY the extension is required: a bare
+ * `./templates/*` export with an extensionless import fails to type-check under
+ * bundler resolution (TS cannot infer the `.tsx` extension for a deep
+ * specifier), and an extensionless import fails to bundle.
+ */
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {createRequire} from 'node:module';
+import {execFileSync} from 'node:child_process';
+
+const require = createRequire(import.meta.url);
+
+/** Resolve the workspace tsc/esbuild binaries; null if unavailable. */
+function resolveBin(spec) {
+  try {
+    return require.resolve(spec);
+  } catch {
+    return null;
+  }
+}
+const TSC_BIN = resolveBin('typescript/bin/tsc');
+const ESBUILD_BIN = resolveBin('esbuild/bin/esbuild');
+
+let tmpDir;
+
+/**
+ * Build an @acme/widgets fixture: a block template (`.template.ts` doc +
+ * same-stem `.tsx` source) under `templates/`, plus an astryx.integration
+ * manifest, plus a caller-supplied `exports` map.
+ * @param {Record<string, string> | undefined} exportsMap
+ */
+function makeWidgets(exportsMap) {
+  const pkgDir = path.join(tmpDir, 'node_modules', '@acme', 'widgets');
+  const blockDir = path.join(pkgDir, 'templates', 'Gauge');
+  fs.mkdirSync(blockDir, {recursive: true});
+
+  const pkg = {name: '@acme/widgets', version: '2.0.0', type: 'module'};
+  if (exportsMap) pkg.exports = exportsMap;
+  fs.writeFileSync(
+    path.join(pkgDir, 'package.json'),
+    JSON.stringify(pkg, null, 2),
+  );
+  fs.writeFileSync(
+    path.join(pkgDir, 'astryx.integration.mjs'),
+    `export default { templates: './templates' };\n`,
+  );
+  // The template-spec doc (canonical `.template.*` family).
+  fs.writeFileSync(
+    path.join(blockDir, 'GaugeShowcase.template.ts'),
+    `export default { name: 'Gauge showcase', description: 'A gauge.' };\n`,
+  );
+  // The same-stem `.tsx` SOURCE that a preview will dynamically import().
+  // Returns a plain value so the fixture type-checks without React types.
+  fs.writeFileSync(
+    path.join(blockDir, 'GaugeShowcase.tsx'),
+    `const GaugeShowcase = (): string => 'gauge-showcase';\n` +
+      `export default GaugeShowcase;\n`,
+  );
+  return pkgDir;
+}
+
+/** Write a consumer that dynamically imports the given specifier. */
+function writeConsumer(specifier) {
+  fs.writeFileSync(
+    path.join(tmpDir, 'consumer.ts'),
+    `const load = () => import('${specifier}');\nexport default load;\n`,
+  );
+}
+
+/**
+ * The realistic consumer tsconfig: matches the repo's Next.js example apps
+ * (`moduleResolution: bundler`, `noEmit`, and deliberately NO
+ * `allowImportingTsExtensions`).
+ */
+function writeTsconfig() {
+  fs.writeFileSync(
+    path.join(tmpDir, 'tsconfig.json'),
+    JSON.stringify(
+      {
+        compilerOptions: {
+          target: 'ES2022',
+          lib: ['ES2022', 'DOM', 'DOM.Iterable'],
+          module: 'ESNext',
+          moduleResolution: 'bundler',
+          jsx: 'react-jsx',
+          strict: true,
+          skipLibCheck: true,
+          esModuleInterop: true,
+          noEmit: true,
+          isolatedModules: true,
+        },
+        include: ['consumer.ts'],
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+/** @returns {{ok: boolean, out: string}} */
+function runTsc() {
+  try {
+    execFileSync(process.execPath, [TSC_BIN, '--noEmit', '-p', 'tsconfig.json'], {
+      cwd: tmpDir,
+      stdio: 'pipe',
+    });
+    return {ok: true, out: ''};
+  } catch (e) {
+    return {ok: false, out: `${e.stdout ?? ''}${e.stderr ?? ''}`};
+  }
+}
+
+/** @returns {{ok: boolean, out: string}} */
+function runEsbuild() {
+  try {
+    // esbuild's bin is a native executable (not a node script), so invoke it
+    // directly rather than through process.execPath.
+    execFileSync(
+      ESBUILD_BIN,
+      [
+        'consumer.ts',
+        '--bundle',
+        '--format=esm',
+        '--loader:.tsx=tsx',
+        '--outfile=/dev/null',
+        '--log-level=error',
+      ],
+      {cwd: tmpDir, stdio: 'pipe'},
+    );
+    return {ok: true, out: ''};
+  } catch (e) {
+    return {ok: false, out: `${e.stdout ?? ''}${e.stderr ?? ''}`};
+  }
+}
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-block-exports-'));
+  fs.writeFileSync(
+    path.join(tmpDir, 'package.json'),
+    JSON.stringify({name: 'consumer', private: true, type: 'module'}),
+  );
+  writeTsconfig();
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+const CANONICAL = 'import(@acme/widgets/templates/Gauge/GaugeShowcase.tsx)';
+const SPEC = '@acme/widgets/templates/Gauge/GaugeShowcase.tsx';
+
+describe('integration block-template exports recipe', () => {
+  it.runIf(TSC_BIN != null)(
+    `CANONICAL: exports {"./templates/*.tsx"} + ${CANONICAL} type-checks under bundler resolution`,
+    () => {
+      makeWidgets({'./templates/*.tsx': './templates/*.tsx'});
+      writeConsumer(SPEC);
+      const {ok, out} = runTsc();
+      expect(out).toBe('');
+      expect(ok).toBe(true);
+    },
+    30_000,
+  );
+
+  it.runIf(ESBUILD_BIN != null)(
+    `CANONICAL: the same import resolves + bundles with a real bundler`,
+    () => {
+      makeWidgets({'./templates/*.tsx': './templates/*.tsx'});
+      writeConsumer(SPEC);
+      const {ok, out} = runEsbuild();
+      expect(out).toBe('');
+      expect(ok).toBe(true);
+    },
+    30_000,
+  );
+
+  it.runIf(TSC_BIN != null)(
+    'NEGATIVE: an extensionless import does NOT type-check (TS cannot infer .tsx)',
+    () => {
+      makeWidgets({'./templates/*.tsx': './templates/*.tsx'});
+      writeConsumer('@acme/widgets/templates/Gauge/GaugeShowcase');
+      const {ok, out} = runTsc();
+      expect(ok).toBe(false);
+      expect(out).toContain('TS2307');
+    },
+    30_000,
+  );
+
+  it.runIf(TSC_BIN != null)(
+    'NEGATIVE: a bare "./templates/*" export (no .tsx entry) does NOT type-check the .tsx import',
+    () => {
+      // Only a bare mapping — the extensionful subpath is not exported.
+      makeWidgets({'./templates/*': './templates/*'});
+      writeConsumer(SPEC);
+      const {ok, out} = runTsc();
+      expect(ok).toBe(false);
+      // Bare export forces the TS5097 opt-in requirement (allowImportingTsExtensions).
+      expect(out).toContain('TS5097');
+    },
+    30_000,
+  );
+
+  it.runIf(ESBUILD_BIN != null)(
+    'NEGATIVE: an extensionless import does NOT bundle against the .tsx-only export',
+    () => {
+      makeWidgets({'./templates/*.tsx': './templates/*.tsx'});
+      writeConsumer('@acme/widgets/templates/Gauge/GaugeShowcase');
+      const {ok} = runEsbuild();
+      expect(ok).toBe(false);
+    },
+    30_000,
+  );
+});

package/src/api/template-suffix.test.mjs

@@ -0,0 +1,246 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The canonical `.template.{ts,mjs,js}` suffix is discovered identically
+ * to the legacy `.doc.{ts,mjs,js}` suffix.
+ *
+ * Template-spec files are named for what they are: a scaffoldable TEMPLATE that
+ * exports `createBlockTemplate`/`createPageTemplate`. The `.doc.*` suffix was
+ * inherited from the component-doc convention and is still accepted during the
+ * transition. These tests stand up integration templates and external blocks in
+ * both families and assert byte-for-byte-equivalent discovery + scaffolding.
+ */
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {
+  template,
+  findShowcase,
+  findRelatedBlocks,
+} from './template.mjs';
+
+/** Absolute path to the CLI package so fixtures can import /src/template.mjs. */
+const CLI_PKG = path.resolve(import.meta.dirname, '..', '..');
+
+let tmpDir;
+let originalCwd;
+
+function makeConsumer() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-template-suffix-'));
+  fs.writeFileSync(
+    path.join(dir, 'package.json'),
+    JSON.stringify({name: 'consumer'}),
+  );
+  fs.writeFileSync(
+    path.join(dir, 'astryx.config.mjs'),
+    `export default { integrations: ['@acme/widgets'] };\n`,
+  );
+  return dir;
+}
+
+function installWidgets(consumerDir) {
+  const pkgDir = path.join(consumerDir, 'node_modules', '@acme', 'widgets');
+  fs.mkdirSync(path.join(pkgDir, 'templates'), {recursive: true});
+  fs.writeFileSync(
+    path.join(pkgDir, 'package.json'),
+    JSON.stringify({name: '@acme/widgets', version: '2.0.0'}),
+  );
+  fs.writeFileSync(
+    path.join(pkgDir, 'astryx.integration.mjs'),
+    `export default { templates: './templates' };\n`,
+  );
+  return pkgDir;
+}
+
+/**
+ * Write a template-spec file (default-export createPageTemplate/BlockTemplate)
+ * plus its same-stem `.tsx` source under the templates root.
+ * @param {string} pkgDir
+ * @param {string} id
+ * @param {{kind: 'page'|'block', suffix: string}} opts
+ */
+function writeTemplate(pkgDir, id, {kind, suffix}) {
+  const docPath = path.join(pkgDir, 'templates', `${id}${suffix}`);
+  fs.mkdirSync(path.dirname(docPath), {recursive: true});
+  const create =
+    kind === 'page' ? 'createPageTemplate' : 'createBlockTemplate';
+  fs.writeFileSync(
+    docPath,
+    `import {${create}} from '${CLI_PKG}/src/template.mjs';\n` +
+      `export default ${create}({name: '${id} name', description: '${id} desc'});\n`,
+  );
+  fs.writeFileSync(
+    path.join(pkgDir, 'templates', `${id}.tsx`),
+    `export default function ${id.replace(/[^a-zA-Z0-9]/g, '')}() { return null; }\n`,
+  );
+}
+
+beforeEach(() => {
+  originalCwd = process.cwd();
+  tmpDir = makeConsumer();
+  process.chdir(tmpDir);
+});
+
+afterEach(() => {
+  process.chdir(originalCwd);
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('integration templates: .template.* discovered like legacy .doc.*', () => {
+  for (const suffix of ['.template.ts', '.template.mjs', '.doc.mjs']) {
+    it(`discovers + lists a page template authored as ${suffix}`, async () => {
+      const pkgDir = installWidgets(tmpDir);
+      writeTemplate(pkgDir, 'pricing', {kind: 'page', suffix});
+
+      const result = await template(undefined, {list: true, cwd: tmpDir});
+      const entry = result.data.find(t => t.id === 'pricing');
+      expect(entry).toBeTruthy();
+      expect(entry.type).toBe('page');
+      expect(entry.package).toBe('@acme/widgets');
+      expect(entry.name).toBe('pricing name');
+      expect(entry.description).toBe('pricing desc');
+    });
+
+    it(`scaffolds a page template authored as ${suffix}`, async () => {
+      const pkgDir = installWidgets(tmpDir);
+      writeTemplate(pkgDir, 'pricing', {kind: 'page', suffix});
+
+      const result = await template('pricing', {
+        targetPath: './dest',
+        cwd: tmpDir,
+      });
+      expect(result.type).toBe('template.copy');
+      expect(result.data.fileName).toBe('page.tsx');
+      expect(fs.existsSync(path.join(tmpDir, 'dest', 'page.tsx'))).toBe(true);
+    });
+
+    it(`scaffolds a nested block template authored as ${suffix}`, async () => {
+      const pkgDir = installWidgets(tmpDir);
+      writeTemplate(pkgDir, 'marketing/hero', {kind: 'block', suffix});
+
+      const result = await template('marketing/hero', {
+        targetPath: './dest',
+        cwd: tmpDir,
+      });
+      expect(result.type).toBe('template.copy');
+      expect(result.data.fileName).toBe('hero.tsx');
+      expect(fs.existsSync(path.join(tmpDir, 'dest', 'hero.tsx'))).toBe(true);
+    });
+  }
+
+  it('treats a .template.ts and a legacy .doc.mjs identically (same shape)', async () => {
+    const pkgDir = installWidgets(tmpDir);
+    writeTemplate(pkgDir, 'gauge', {kind: 'block', suffix: '.template.ts'});
+    writeTemplate(pkgDir, 'chip', {kind: 'block', suffix: '.doc.mjs'});
+
+    const result = await template(undefined, {list: true, cwd: tmpDir});
+    const gauge = result.data.find(t => t.id === 'gauge');
+    const chip = result.data.find(t => t.id === 'chip');
+
+    // Both discovered, both blocks, both from the same package, both ready.
+    for (const entry of [gauge, chip]) {
+      expect(entry).toBeTruthy();
+      expect(entry.type).toBe('block');
+      expect(entry.package).toBe('@acme/widgets');
+    }
+    // Field-by-field parity apart from the (intentionally different) id/name.
+    expect(gauge.type).toBe(chip.type);
+    expect(gauge.package).toBe(chip.package);
+  });
+});
+
+describe('external showcase blocks: .template.* discovered like legacy .doc.*', () => {
+  /**
+   * Create a consumer whose @test/ext package contributes two showcase blocks,
+   * one authored as `Foo.template.ts` and one as legacy `Bar.doc.mjs`.
+   */
+  function makeShowcaseFixture() {
+    // Symlink the real core package (needed by findCoreDir during discovery).
+    const realCoreDir = path.resolve(
+      import.meta.dirname,
+      '..',
+      '..',
+      '..',
+      'core',
+    );
+    const coreDir = path.join(tmpDir, 'packages', 'core');
+    fs.mkdirSync(path.dirname(coreDir), {recursive: true});
+    fs.symlinkSync(realCoreDir, coreDir);
+
+    const extDir = path.join(tmpDir, 'node_modules', '@test', 'ext');
+    const blocksDir = path.join(extDir, 'blocks', 'components');
+
+    // Foo showcase — canonical .template.ts (default-export createBlockTemplate).
+    const fooDir = path.join(blocksDir, 'Foo');
+    fs.mkdirSync(fooDir, {recursive: true});
+    fs.writeFileSync(
+      path.join(fooDir, 'FooShowcase.template.ts'),
+      `import {createBlockTemplate} from '${CLI_PKG}/src/template.mjs';\n` +
+        `export default createBlockTemplate({\n` +
+        `  name: 'Foo — Showcase',\n` +
+        `  description: 'Foo showcase.',\n` +
+        `  isShowcase: true,\n` +
+        `  aspectRatio: 16 / 9,\n` +
+        `  componentsUsed: ['Foo'],\n` +
+        `});\n`,
+    );
+    fs.writeFileSync(
+      path.join(fooDir, 'FooShowcase.tsx'),
+      "'use client';\nexport default function FooShowcase() { return <div>Foo</div>; }",
+    );
+
+    // Bar showcase — legacy .doc.mjs (export const doc).
+    const barDir = path.join(blocksDir, 'Bar');
+    fs.mkdirSync(barDir, {recursive: true});
+    fs.writeFileSync(
+      path.join(barDir, 'BarShowcase.doc.mjs'),
+      `export const doc = {\n` +
+        `  type: 'block',\n` +
+        `  name: 'Bar — Showcase',\n` +
+        `  description: 'Bar showcase.',\n` +
+        `  isReady: true,\n` +
+        `  isShowcase: true,\n` +
+        `  aspectRatio: 4 / 3,\n` +
+        `  componentsUsed: ['Bar', 'Chip'],\n` +
+        `};\n`,
+    );
+    fs.writeFileSync(
+      path.join(barDir, 'BarShowcase.tsx'),
+      "'use client';\nexport default function BarShowcase() { return <div>Bar</div>; }",
+    );
+
+    fs.writeFileSync(
+      path.join(extDir, 'package.json'),
+      JSON.stringify({
+        name: '@test/ext',
+        astryx: {docs: './src', category: 'Common', blocks: './blocks/components'},
+      }),
+    );
+    fs.mkdirSync(path.join(extDir, 'src'), {recursive: true});
+  }
+
+  it('findShowcase resolves a .template.ts external block by directory name', async () => {
+    makeShowcaseFixture();
+    const result = await findShowcase('Foo', tmpDir);
+    expect(result).not.toBeNull();
+    expect(result.name).toBe('Foo — Showcase');
+    expect(result.filePath).toContain('FooShowcase.tsx');
+  });
+
+  it('findShowcase resolves a legacy .doc.mjs external block by componentsUsed', async () => {
+    makeShowcaseFixture();
+    const result = await findShowcase('Bar', tmpDir);
+    expect(result).not.toBeNull();
+    expect(result.name).toBe('Bar — Showcase');
+  });
+
+  it('findRelatedBlocks finds both suffix families', async () => {
+    makeShowcaseFixture();
+    const foo = await findRelatedBlocks('Foo', tmpDir);
+    expect(foo.map(b => b.dirName)).toContain('FooShowcase');
+    const chip = await findRelatedBlocks('Chip', tmpDir);
+    expect(chip.map(b => b.dirName)).toContain('BarShowcase');
+  });
+});

package/src/api/template.mjs

@@ -6,6 +6,7 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import {createJiti} from 'jiti';
 import {loadModuleWithSchema} from '../lib/module-loader.mjs';
 import {TemplateEnvelopeSchema} from '../template.mjs';
 import {CLI_ROOT, discoverExternalPackages} from '../utils/paths.mjs';
@@ -21,9 +22,54 @@ import {Project} from '../lib/project.mjs';
 /** Identity used for core (built-in) templates in package-scoped listings. */
 const CORE_PACKAGE = '@astryxdesign/core';
 
-/** Doc-file basename suffixes for integration templates, in precedence order. */
+/**
+ * Canonical basename suffixes for template-spec files, in precedence order.
+ * A template spec exports a `createBlockTemplate`/`createPageTemplate` result
+ * (a scaffoldable TEMPLATE), so `.template.*` is the descriptive family name.
+ */
+const TEMPLATE_SUFFIXES = ['.template.ts', '.template.mjs', '.template.js'];
+
+/**
+ * Legacy basename suffixes for template-spec files, in precedence order.
+ * `.doc.*` was inherited from the component-doc convention before templates
+ * had their own name; it is still accepted during the transition window.
+ */
 const DOC_SUFFIXES = ['.doc.ts', '.doc.mjs', '.doc.js'];
 
+/**
+ * The union of canonical + legacy template-spec suffixes, canonical first so
+ * `.template.*` wins over `.doc.*` when both stems exist. All template
+ * discovery matches this union so a `Foo.template.ts` file is treated exactly
+ * like a legacy `Foo.doc.mjs`.
+ */
+const ALL_TEMPLATE_SUFFIXES = [...TEMPLATE_SUFFIXES, ...DOC_SUFFIXES];
+
+/**
+ * The template-spec suffix present on `file`, or null if none matches.
+ * Recognizes both the canonical `.template.*` and legacy `.doc.*` families.
+ * @param {string} file
+ * @returns {string | null}
+ */
+function matchedTemplateSuffix(file) {
+  return ALL_TEMPLATE_SUFFIXES.find(suffix => file.endsWith(suffix)) ?? null;
+}
+
+/**
+ * RegExp matching either template-spec suffix family at end of a basename.
+ * Used where a per-file regex is convenient (e.g. block discovery walks).
+ */
+const TEMPLATE_SUFFIX_RE = /\.(template|doc)\.(ts|mjs|js)$/;
+
+let jitiInstance;
+/** Lazily-created jiti for loading `.ts` template specs (JSX-capable). */
+function getJiti() {
+  if (!jitiInstance) {
+    jitiInstance = createJiti(import.meta.url, {jsx: true});
+  }
+  return jitiInstance;
+}
+
+
 /**
  * Load an integration template doc module and validate it against the template
  * envelope at the load boundary. Default export only — `.ts` via jiti,
@@ -87,12 +133,29 @@ export function stripTemplateAssetRefs(source) {
     source,
   );
 }
+/**
+ * Load a template-spec module and return its metadata object. Supports both
+ * families of suffix:
+ *   - Legacy `.doc.*` core/external specs export `export const doc = {...}`.
+ *   - Specs authored with `createPageTemplate`/`createBlockTemplate` export the
+ *     stamped object as the default export.
+ * Prefers the default export, falling back to the named `doc` export, so a
+ * `Foo.template.ts` (default export) is read identically to a legacy
+ * `Foo.doc.mjs` (`doc` export). `.ts` is loaded via jiti; `.mjs`/`.js` via a
+ * native dynamic import. Returns null if the file does not exist.
+ *
+ * @param {string} docPath absolute path to the spec file
+ * @returns {Promise<Record<string, unknown> | undefined | null>}
+ */
 async function loadDocModule(docPath) {
   if (!fs.existsSync(docPath)) return null;
-  const docModule = await import(`file://${docPath}`);
-  return docModule.doc;
+  const docModule = docPath.endsWith('.ts')
+    ? await getJiti().import(docPath)
+    : await import(`file://${docPath}`);
+  return docModule.default ?? docModule.doc;
 }
 
+
 export {discoverAll as discoverTemplates};
 
 export function listTemplates() {
@@ -122,6 +185,20 @@ function findDocFiles(dir, pattern) {
   return results;
 }
 
+/**
+ * Resolve the template-spec file for a core page directory: the first existing
+ * `template.<suffix>` in canonical-then-legacy precedence, or null.
+ * @param {string} dirPath
+ * @returns {string | null}
+ */
+function findPageDocFile(dirPath) {
+  for (const suffix of ALL_TEMPLATE_SUFFIXES) {
+    const candidate = path.join(dirPath, `template${suffix}`);
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
 async function discoverPages() {
   if (!fs.existsSync(PAGES_DIR)) return [];
   const dirs = fs
@@ -131,7 +208,9 @@ async function discoverPages() {
   const templates = [];
   for (const dir of dirs) {
     const dirPath = path.join(PAGES_DIR, dir.name);
-    const doc = await loadDocModule(path.join(dirPath, 'template.doc.mjs'));
+    const docPath =
+      findPageDocFile(dirPath) ?? path.join(dirPath, 'template.doc.mjs');
+    const doc = await loadDocModule(docPath);
     templates.push({
       type: 'page',
       dirName: dir.name,
@@ -141,17 +220,18 @@ async function discoverPages() {
       isReady: doc?.isReady ?? true,
       scaffold: doc?.scaffold ?? false,
       filePath: path.join(dirPath, 'page.tsx'),
-      docPath: path.join(dirPath, 'template.doc.mjs'),
+      docPath,
     });
   }
   return templates;
 }
 
 async function discoverBlocks() {
-  const docFiles = findDocFiles(BLOCKS_DIR, /\.doc\.mjs$/);
+  const docFiles = findDocFiles(BLOCKS_DIR, TEMPLATE_SUFFIX_RE);
   const blocks = [];
   for (const docPath of docFiles) {
-    const basename = path.basename(docPath, '.doc.mjs');
+    const suffix = matchedTemplateSuffix(docPath);
+    const basename = path.basename(docPath, suffix);
     const tsxPath = path.join(path.dirname(docPath), basename + '.tsx');
     if (!fs.existsSync(tsxPath)) continue;
     const doc = await loadDocModule(docPath);
@@ -173,6 +253,7 @@ async function discoverBlocks() {
   return blocks;
 }
 
+
 /**
  * Discover blocks from external packages that declare `astryx.blocks` in
  * their package.json. Same shape as discoverBlocks() output.
@@ -185,9 +266,10 @@ async function discoverExternalBlocks(cwd = process.cwd()) {
 
   for (const ext of externals) {
     if (!ext.blocksDir || !fs.existsSync(ext.blocksDir)) continue;
-    const docFiles = findDocFiles(ext.blocksDir, /\.doc\.mjs$/);
+    const docFiles = findDocFiles(ext.blocksDir, TEMPLATE_SUFFIX_RE);
     for (const docPath of docFiles) {
-      const basename = path.basename(docPath, '.doc.mjs');
+      const suffix = matchedTemplateSuffix(docPath);
+      const basename = path.basename(docPath, suffix);
       const tsxPath = path.join(path.dirname(docPath), basename + '.tsx');
       if (!fs.existsSync(tsxPath)) continue;
       const doc = await loadDocModule(docPath);
@@ -258,8 +340,9 @@ async function discoverAllWithErrors(cwd = process.cwd()) {
 export {discoverAllWithErrors};
 
 /**
- * Recursively collect integration template doc files under `root`.
- * Returns absolute paths to files ending in one of DOC_SUFFIXES.
+ * Recursively collect integration template-spec files under `root`.
+ * Returns absolute paths to files ending in one of ALL_TEMPLATE_SUFFIXES
+ * (canonical `.template.*` or legacy `.doc.*`).
  *
  * @param {string} root
  * @returns {string[]}
@@ -272,7 +355,7 @@ function findIntegrationDocFiles(root) {
       const full = path.join(dir, entry.name);
       if (entry.isDirectory()) {
         walk(full);
-      } else if (DOC_SUFFIXES.some(suffix => entry.name.endsWith(suffix))) {
+      } else if (ALL_TEMPLATE_SUFFIXES.some(suffix => entry.name.endsWith(suffix))) {
         results.push(full);
       }
     }
@@ -281,24 +364,17 @@ function findIntegrationDocFiles(root) {
   return results;
 }
 
-/**
- * The doc-file suffix present on `file`, or null if none matches.
- * @param {string} file
- */
-function matchedDocSuffix(file) {
-  return DOC_SUFFIXES.find(suffix => file.endsWith(suffix)) ?? null;
-}
-
 /**
  * Discover templates contributed by configured integrations.
  *
  * For each integration with a resolved `templates` root, every
- * `<id>.doc.{ts,mjs,js}` file is a template whose id is its path relative to
- * the templates root with the `.doc.*` suffix stripped (kebab-case, may be
- * nested). The doc's `type` (page|block) decides scaffolding — there is no
- * `/pages` vs `/blocks` requirement. A same-stem sibling source file
- * (`<id>.tsx`) is required; a doc missing its source, or missing `type`, is
- * an integration error and that template is skipped (recorded in `errors`).
+ * `<id>.template.{ts,mjs,js}` (or legacy `<id>.doc.{ts,mjs,js}`) file is a
+ * template whose id is its path relative to the templates root with the
+ * matched suffix stripped (kebab-case, may be nested). The doc's `type`
+ * (page|block) decides scaffolding — there is no `/pages` vs `/blocks`
+ * requirement. A same-stem sibling source file (`<id>.tsx`) is required; a doc
+ * missing its source, or missing `type`, is an integration error and that
+ * template is skipped (recorded in `errors`).
  *
  * @param {string} [cwd]
  * @returns {Promise<{templates: object[], errors: {package: string, template?: string, message: string}[]}>}
@@ -344,7 +420,7 @@ export async function discoverIntegrationTemplatesForOne(integration) {
   if (!root || !fs.existsSync(root)) return {templates, errors};
 
   for (const docPath of findIntegrationDocFiles(root)) {
-    const suffix = matchedDocSuffix(docPath);
+    const suffix = matchedTemplateSuffix(docPath);
     const id = path
       .relative(root, docPath)
       .slice(0, -suffix.length)

package/templates/blocks/components/ChatComposerInput/ChatComposerInputControlledInput.tsx

@@ -10,7 +10,7 @@ import {Text} from '@astryxdesign/core/Text';
 export default function ChatComposerInputControlledInput() {
   const [value, setValue] = useState('');
   return (
-    <Stack direction="vertical" gap={3} style={{width: '100%', maxWidth: 450}}>
+    <Stack direction="vertical" gap={3} style={{width: 450, maxWidth: '100%'}}>
       <ChatComposer
         onSubmit={() => setValue('')}
         value={value}

package/templates/blocks/components/ChatComposerInput/ChatComposerInputDisabled.tsx

@@ -7,7 +7,7 @@ import {Stack} from '@astryxdesign/core/Layout';
 
 export default function ChatComposerInputDisabled() {
   return (
-    <Stack direction="vertical" style={{width: '100%', maxWidth: 450}}>
+    <Stack direction="vertical" style={{width: 450, maxWidth: '100%'}}>
       <ChatComposer
         onSubmit={() => {}}
         isDisabled

package/templates/blocks/components/ChatComposerInput/ChatComposerInputMentionTrigger.tsx

@@ -43,7 +43,7 @@ export default function ChatComposerInputMentionTrigger() {
   };
 
   return (
-    <Stack direction="vertical" gap={3} style={{width: '100%', maxWidth: 450}}>
+    <Stack direction="vertical" gap={3} style={{width: 450, maxWidth: '100%'}}>
       <ChatComposer
         onSubmit={() => setValue('')}
         input={

package/templates/blocks/components/ChatComposerInput/ChatComposerInputMultipleTriggers.tsx

@@ -54,7 +54,7 @@ export default function ChatComposerInputMultipleTriggers() {
   };
 
   return (
-    <Stack direction="vertical" gap={3} style={{width: '100%', maxWidth: 450}}>
+    <Stack direction="vertical" gap={3} style={{width: 450, maxWidth: '100%'}}>
       <Text type="supporting" color="secondary">
         Type @ for mentions (blue) or / for commands (yellow)
       </Text>

package/templates/blocks/components/ChatComposerInput/ChatComposerInputShowcase.tsx

@@ -7,7 +7,7 @@ import {Stack} from '@astryxdesign/core/Layout';
 
 export default function ChatComposerInputShowcase() {
   return (
-    <Stack direction="vertical" style={{width: '100%', maxWidth: 450}}>
+    <Stack direction="vertical" style={{width: 450, maxWidth: '100%'}}>
       <ChatComposer
         onSubmit={() => {}}
         input={

package/templates/blocks/components/ChatComposerInput/ChatComposerInputSlashCommands.tsx

@@ -40,7 +40,7 @@ export default function ChatComposerInputSlashCommands() {
   };
 
   return (
-    <Stack direction="vertical" style={{width: '100%', maxWidth: 450}}>
+    <Stack direction="vertical" style={{width: 450, maxWidth: '100%'}}>
       <ChatComposer
         onSubmit={() => {}}
         input={