@astryxdesign/cli 0.1.6 → 0.1.7-canary.04cd8f7

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @xds/cli
 
+# 0.1.7
+
+#### New Features
+
+- Export the authoring factories from `@astryxdesign/core`: `createConfig` at `@astryxdesign/core/config` and `createIntegration`/`createPageTemplate`/`createBlockTemplate`/`createComponentDoc`/`createFunctionDoc`/`createDoc` at `@astryxdesign/core/authoring`. Authoring a config or integration no longer requires depending on the CLI. Existing `@astryxdesign/cli/*` imports keep working via re-export.
+- Add the finalized doc-authoring API to `@astryxdesign/cli/doc`: `createComponentDoc`, `createFunctionDoc` (any function, including hooks), and `createDoc` (generic reference/topic docs). Each factory stamps a `type` discriminant and is validated at the load boundary against a matching per-kind schema. The legacy loose `export const docs = {...}` format keeps loading unchanged, and `.ts`-authored hook/function sources now derive their import path to a tree-shakeable subpath instead of the bare package root.
+- New codemod for the Table `tableProps` deprecation: lifts object-literal `tableProps` keys into direct props on `<Table>`, keeps colliding or dynamic values in place with a TODO note. **Codemod:** `npx astryx upgrade --codemod migrate-table-tableprops-to-direct-props` (#3679)
+- New docs topic `internationalization` covering how to localize astryx components, provide translation catalogs, override default strings, coexist with existing i18n libraries (react-intl, i18next, next-intl), swap languages at runtime, and validate coverage with the shipped pseudo locale. Run `npx astryx docs internationalization` or read it at https://astryx.atmeta.com/docs/internationalization.
+- template: accept `.template.{ts,mjs,js}` as the canonical suffix for template-spec files, alongside the legacy `.doc.*` suffix. Template specs export `createBlockTemplate`/`createPageTemplate` — a scaffoldable template, not documentation — so they now get a descriptive name. Core, external-package, and integration discovery (`findShowcase`, `--blocks`, `astryx template <id>` scaffolding) all treat `Foo.template.ts` identically to a legacy `Foo.doc.mjs`; same-stem `.tsx` source resolves for either suffix, and `.template.ts` authoring is loaded via jiti. Additive only — no existing files are renamed.
+
+#### Fixes
+
+- Translated component docs no longer drop props
+  A `docsZh` / `docsDense` block that carried its own `props` array replaced the English component doc **wholesale** rather than overlaying it, so any prop the translation had not caught up with simply ceased to exist. `astryx component Button --zh` silently omitted `isInterruptible` and `isIconOnly`; ten components were affected, including `MobileNav`, `Popover` and `Stack` through the multi-component `components[]` shape.
+- Anchor --dense / --zh doc overlays to their base sections (#2182)
+  The compressed and translated reference docs were merged into the base doc **by array position**, so an overlay whose sections were ordered differently — or which omitted one — grafted every title onto the wrong body.
+- template: inline full demo-image URLs in the Avatar blocks and theme-showcase page so scaffolding strips them to a clean placeholder. Templates that stored only the CDN base in a `const` and appended the filename via interpolation (`` `${CDN}/File.png` ``) previously scaffolded a malformed `src` — the placeholder data URI with the filename glued onto the end — plus a dead `const CDN = 'data:…'`. (#4027)
+
+#### Documentation
+
+- Document the minimal `package.json#exports` recipe an integration needs so its block templates are importable by a bundler-resolution consumer and type-check under `moduleResolution: bundler`: `"./templates/*.tsx": "./templates/*.tsx"` plus an extensionful `import('@acme/widgets/templates/…/…Showcase.tsx')`. Adds `packages/cli/docs/integration-authoring.md` and a fixture test proving the recipe against the repo's own `tsc` and `esbuild`.
+
+#### Contributors
+
+Thanks to everyone who contributed to this release:
+
+- @AKnassa
+- @ejhammond
+- @imdreamrunner
+- @nynexman4464
+
+---
+
 # 0.1.6
 
 ---

package/README.md

@@ -2,15 +2,19 @@
 
 The CLI is the primary interface for working with the design system, for humans and machines alike. It provides component documentation, design tokens, page templates, theming tools, and upgrade codemods, all accessible via terminal commands, a typed JSON API, or programmatic imports. AI agents and build tools use the same API that powers the CLI, enabling end-to-end frontend development loops.
 
+Run it one-off with the scoped package (works whether or not it's installed):
+
 ```bash
-npx astryx --help
-npx astryx search button
-npx astryx component Button
-npx astryx docs tokens
-npx astryx docs migration
-npx astryx template --list
+npx @astryxdesign/cli --help
+npx @astryxdesign/cli search button
+npx @astryxdesign/cli component Button
+npx @astryxdesign/cli docs tokens
+npx @astryxdesign/cli docs migration
+npx @astryxdesign/cli template --list
 ```
 
+Once it's a project dependency (`npm install -D @astryxdesign/cli`), drop the scope and use the shorter `astryx` — e.g. `npx astryx component Button` or `pnpm exec astryx component Button`. Bare `astryx` resolves to an unrelated npm package until the CLI is installed, so prefer the scoped form above for first-run/one-off use.
+
 ## Finding things: `astryx search`
 
 When you don't know whether what you need is a component, a hook, a docs topic,
@@ -20,27 +24,29 @@ fuzzy matching for typos) and tagged with their domain plus the follow-up
 command to run:
 
 ```bash
-$ npx astryx search button
+$ astryx search button
 
 Results for "button" (20):
 
   [component]  Button
                Button triggers an action when clicked. Use it for form submissions…
-               → npx astryx component Button
+               → astryx component Button
 
   [component]  IconButton
                A button that shows only an icon with no visible text…
-               → npx astryx component IconButton
+               → astryx component IconButton
 
   [hook]       useClickableContainer
                Makes a container element clickable while preserving nested…
-               → npx astryx hook useClickableContainer
+               → astryx hook useClickableContainer
 
   [template]   Banner — Collapsible
                Combine an action button, dismiss control, and expandable detail area…
-               → npx astryx template BannerCollapsibleContent
+               → astryx template BannerCollapsibleContent
 ```
 
+(The CLI prints the follow-up commands with your actual runner — `npx astryx …` when installed, or `npx @astryxdesign/cli …` when run one-off.)
+
 Options:
 
 - `--type <component|hook|doc|template>`: restrict to a single domain
@@ -415,7 +421,7 @@ failures (warnings are fine) and `1` when any check fails. That makes it
 usable directly as a CI step:
 
 ```yaml
-- run: npx astryx doctor
+- run: npx @astryxdesign/cli doctor
 ```
 
 Use `--json` for a structured envelope (`{ apiVersion, type: "doctor",
@@ -423,13 +429,103 @@ data: { checks, summary } }`) that AI agents and scripts can parse.
 
 ## Configuration
 
-The CLI reads from an optional `astryx.config.mjs` in your project root:
+The CLI reads an optional `astryx.config.{ts,mjs,js}` from your project root
+(a sibling of `package.json`). Every field is optional; with no config file the
+CLI runs on defaults.
 
-```javascript
-export default {
-  templates: {
-    get: async id => fetchTemplateFromAPI(id),
-  },
+```typescript
+import {createConfig} from '@astryxdesign/core/config';
+
+export default createConfig({
+  integrations: ['@acme/astryx-widgets'],
   issuesUrl: 'https://github.com/your-org/your-repo/issues',
-};
+});
+```
+
+`createConfig` is a type-preserving helper: it returns its argument unchanged
+and exists only to give the config file editor autocomplete and type-checking. A
+plain `export default {}` object works identically. It's exported from
+`@astryxdesign/core` (not the CLI) so your config file gets type feedback
+without depending on the CLI; the same helper is re-exported from
+`@astryxdesign/cli/config` for back-compat.
+
+| Field                         | Type                           | Purpose                                                                                         |
+| ----------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------- |
+| `integrations`                | `string[]`                     | Integration package names to load (see [Integrations](#integrations)).                          |
+| `issuesUrl`                   | `string`                       | Where "report an issue" links point for your project. Defaults to the core issue tracker.       |
+| `hooks.postCodemod`           | `PostCodemodHook[]`            | Commands to run after `astryx upgrade` applies codemods (e.g. reinstall, rebuild, reformat).    |
+| `experimental.xle.components` | `Record<string, XleComponent>` | Register app-local components so layout (XLE) expressions can reference them by name. Unstable. |
+
+The config is validated against a strict schema when the CLI loads it, so an
+unknown field is a hard error rather than a silent no-op. `astryx doctor`
+reports whether the config loads cleanly.
+
+## Integrations
+
+An **integration** is any npm package that contributes its own components,
+templates, and upgrade codemods to Astryx. The CLI surfaces them next to core's,
+through the same commands, so a consumer can `astryx component`,
+`astryx template`, and `astryx upgrade` across core and every integration
+uniformly. Use it to ship a first-party add-on, publish a third-party component
+library, or share an internal design-system package across apps.
+
+The system runs on two files, each with a small typed API:
+
+| File                             | Written by | Role                                      |
+| -------------------------------- | ---------- | ----------------------------------------- |
+| `astryx.config.{ts,mjs,js}`      | Consumer   | Lists which integration packages to load. |
+| `astryx.integration.{ts,mjs,js}` | Author     | Declares what a package contributes.      |
+
+The consumer side is the `integrations` field of [`astryx.config`](#configuration).
+The author side is the integration manifest below.
+
+### The integration manifest
+
+A package becomes an integration by exporting a manifest from
+`astryx.integration.{ts,mjs,js}` at its root (a sibling of `package.json`). The
+manifest points at where each kind of contribution lives; identity (name,
+version) comes from `package.json`, not the manifest.
+
+```typescript
+import {createIntegration} from '@astryxdesign/core/authoring';
+
+export default createIntegration({
+  components: './components',
+  templates: './templates',
+  codemods: './codemods',
+  issuesUrl: 'https://github.com/acme/widgets/issues',
+});
+```
+
+| Field        | Type     | Purpose                                                               |
+| ------------ | -------- | --------------------------------------------------------------------- |
+| `components` | `string` | Directory holding the package's components and their `.doc.*` files.  |
+| `templates`  | `string` | Directory holding the package's page/block templates.                 |
+| `codemods`   | `string` | Directory holding upgrade codemods run by `astryx upgrade`.           |
+| `issuesUrl`  | `string` | Where "report an issue" links for this package's contributions point. |
+
+Every field is optional; declare only the roots the package ships.
+`createIntegration` is a type-preserving helper (editor autocomplete and
+type-checking); it lives in `@astryxdesign/core/authoring` and is re-exported
+from `@astryxdesign/cli/integration` for back-compat.
+
+### How it works
+
+Every command loads the consumer's `astryx.config`, resolves each listed
+integration's manifest from `node_modules`, and discovers its contributions.
+Everything is validated against one strict schema at the load boundary, so the
+CLI presents core and integration contributions through a single, uniform
+surface.
+
+Discovery is resilient: a broken or misconfigured integration is skipped with a
+one-line warning on stderr instead of crashing the CLI, and it never corrupts a
+`--json` envelope. To inspect problems, run
+`astryx validate-integration <package>` for a detailed report on one package, or
+`astryx doctor` for an overall health check.
+
+For the full authoring walkthrough (component doc format, template packaging
+and `exports` requirements, and codemod authoring), see the guide:
+
+```bash
+astryx docs cli-integrations
 ```

package/docs/cli-integrations.doc.mjs

@@ -0,0 +1,150 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../core/src/docs-types').ReferenceDoc} */
+
+export const docs = {
+  name: 'cli-integrations',
+  title: 'CLI Integrations',
+  category: 'guide',
+  description:
+    'Author an npm package that contributes components, templates, and upgrade codemods to Astryx.',
+
+  sections: [
+    {
+      title: 'Overview',
+      category: 'guide',
+      content: [
+        {
+          type: 'prose',
+          text: 'An integration is an npm package that contributes components, templates, and/or upgrade codemods to a consumer\u2019s design-system workflow. Consumers install the package and add it to their `astryx.config`; from then on the integration\u2019s contributions show up alongside core\u2019s in the same CLI commands.',
+        },
+        {
+          type: 'prose',
+          text: 'The system runs on two files. The consumer writes `astryx.config.{ts,mjs,js}` at their project root to list which packages to load. The author writes `astryx.integration.{ts,mjs,js}` at the package root to declare what the package contributes. This page is the author\u2019s guide. For the consumer side, run `npx astryx docs getting-started`.',
+        },
+        {
+          type: 'prose',
+          text: 'On the consumer side, adding your package is one line:',
+        },
+        {
+          type: 'code',
+          lang: 'typescript',
+          code: "import {createConfig} from '@astryxdesign/core/config';\n\nexport default createConfig({\n  integrations: ['@acme/astryx-widgets'],\n});",
+        },
+        {
+          type: 'prose',
+          text: 'Your components and templates then appear next to core\u2019s:',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'astryx component --list --package @acme/astryx-widgets\nastryx component AcmeCarousel --props',
+        },
+      ],
+    },
+    {
+      title: 'The Integration File',
+      category: 'guide',
+      content: [
+        {
+          type: 'prose',
+          text: 'To register your package as an integration, add an `astryx.integration.{ts,mjs,js}` file as a sibling of your `package.json`. It tells the CLI where to find your components, templates, and codemods. Identity (name, version) comes from your `package.json`, not this file.',
+        },
+        {
+          type: 'code',
+          lang: 'typescript',
+          code: "// astryx.integration.ts\nimport {createIntegration} from '@astryxdesign/core/authoring';\n\nexport default createIntegration({\n  components: './components',\n  templates: './templates',\n  codemods: './codemods',\n  issuesUrl: 'https://github.com/acme/widgets/issues',\n});",
+        },
+        {
+          type: 'prose',
+          text: 'Every field is optional. Declare only the contribution roots your package ships. `createIntegration` is a type-preserving helper for editor autocomplete and type-checking. It lives in `@astryxdesign/core/authoring` and is also re-exported from `@astryxdesign/cli/integration` for back-compat.',
+        },
+      ],
+    },
+    {
+      title: 'Components',
+      category: 'guide',
+      content: [
+        {
+          type: 'prose',
+          text: 'Export your components from your library however you like, and consumers still import them from your package. For each component the CLI should document, ship a `.doc.{ts,mjs,js}` file with the same stem, for example `AcmeCarousel.tsx` alongside `AcmeCarousel.doc.ts`.',
+        },
+        {
+          type: 'code',
+          lang: 'typescript',
+          code: "// AcmeCarousel.doc.ts\nimport {createComponentDoc} from '@astryxdesign/core/authoring';\n\nexport default createComponentDoc({\n  name: 'AcmeCarousel',\n  description: 'A carousel that cycles through slides.',\n  // props, usage, examples, ...\n});",
+        },
+      ],
+    },
+    {
+      title: 'Templates',
+      category: 'guide',
+      content: [
+        {
+          type: 'prose',
+          text: 'Templates are usually not exported from the package directly. Instead, consumers browse them through the CLI and materialize them into their app. Define a template with `createPageTemplate` (full pages) or `createBlockTemplate` (smaller chunks) in a `.template.{ts,mjs,js}` file next to the source, for example `AcmeLandingPage.tsx` and `AcmeLandingPage.template.ts`.',
+        },
+        {
+          type: 'code',
+          lang: 'typescript',
+          code: "// AcmeLandingPage.template.ts\nimport {createPageTemplate} from '@astryxdesign/core/authoring';\n\nexport default createPageTemplate({\n  // name, description, preview, ...\n});",
+        },
+        {
+          type: 'prose',
+          text: 'The CLI needs the template source at consume time, so make sure it is included in your published package. This is typically done via the `exports` key in `package.json`. It also lets the docsite render template previews in the future.',
+        },
+        {
+          type: 'code',
+          lang: 'jsonc',
+          code: '{\n  "exports": {\n    // ...\n    "./templates/*.tsx": "./templates/*.tsx"\n  }\n}',
+        },
+        {
+          type: 'prose',
+          text: 'To verify it resolves, try importing the template component with its `.tsx` extension. An extensionless specifier will not resolve under `moduleResolution: bundler`, and the extensionful export above is what lets this type-check without consumers enabling `allowImportingTsExtensions`.',
+        },
+        {
+          type: 'code',
+          lang: 'typescript',
+          code: "import('@acme/astryx-widgets/templates/AcmeLandingPage.tsx');",
+        },
+      ],
+    },
+    {
+      title: 'Codemods',
+      category: 'guide',
+      content: [
+        {
+          type: 'prose',
+          text: 'Ship codemods so `astryx upgrade` can migrate consumers across breaking changes in your package. Point the integration file\u2019s `codemods` field at your codemods root, and author each one with `createCodemod` (transforms source files) or `createConfigCodemod` (rewrites the consumer\u2019s `astryx.config`).',
+        },
+        {
+          type: 'code',
+          lang: 'typescript',
+          code: "// codemods/v2-rename-prop.ts\nimport {createCodemod} from '@astryxdesign/cli/codemod';\n\nexport default createCodemod({\n  // version, description, transform, ...\n});",
+        },
+        {
+          type: 'prose',
+          text: 'The codemod helpers live in `@astryxdesign/cli/codemod`, not `@astryxdesign/core/authoring` like the doc, integration, and template helpers. Consumers can also run their own post-codemod hooks, such as a reinstall or rebuild, via `hooks.postCodemod` in their `astryx.config`.',
+        },
+      ],
+    },
+    {
+      title: 'How It Works',
+      category: 'guide',
+      content: [
+        {
+          type: 'prose',
+          text: 'Every CLI command loads the consumer\u2019s `astryx.config`, resolves each listed integration\u2019s manifest from `node_modules`, and discovers its contributions. Everything is validated against one strict schema at the load boundary. The `create*` helpers do not validate. They are identity functions whose value is their TypeScript surface, so validation happens when the CLI loads the file, not when you author it.',
+        },
+        {
+          type: 'prose',
+          text: 'Discovery is resilient. A broken or misconfigured integration is skipped with a single non-blocking warning on stderr instead of crashing the CLI, and it never corrupts a `--json` stdout envelope. Everyday commands keep working with the remaining valid contributions.',
+        },
+        {
+          type: 'prose',
+          text: 'To inspect problems, run `astryx validate-integration <package>` for a detailed report on one package, or `astryx doctor` for an overall health check of the setup.',
+        },
+      ],
+    },
+  ],
+};

package/docs/getting-started.doc.mjs

@@ -21,7 +21,7 @@ export const docs = {
           type: 'code',
           lang: 'text',
           label: 'Paste this into your AI',
-          code: 'Install @astryxdesign/core, @astryxdesign/theme-neutral, and @astryxdesign/cli in this project. Run `npx astryx init` to set up agent docs. Read the generated files to learn the conventions.',
+          code: 'Install @astryxdesign/core, @astryxdesign/theme-neutral, and @astryxdesign/cli in this project, then run `npx @astryxdesign/cli init` to set up agent docs. Read the generated files to learn the conventions.',
         },
       ],
     },
@@ -40,7 +40,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'Then run the init wizard to set up AI agent docs, pick a starter template, and learn about theming.',
+          text: "Then run `astryx init` to install the AI agent cheat sheet (AGENTS.md/CLAUDE.md). It's non-interactive — no prompts — so it's safe for AI agents, CI, and scripts. Add `--all` for pointers to the theme and page-building workflows.",
         },
         {
           type: 'code',
@@ -67,11 +67,11 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'Available themes: @astryxdesign/theme-neutral (muted minimal, a good starting point), @astryxdesign/theme-butter, @astryxdesign/theme-chocolate, @astryxdesign/theme-gothic (dark-only), @astryxdesign/theme-matcha, @astryxdesign/theme-stone, and @astryxdesign/theme-y2k. See `npx astryx docs theme` for the full theming guide.',
+          text: 'Available themes: @astryxdesign/theme-neutral (muted minimal, a good starting point), @astryxdesign/theme-butter, @astryxdesign/theme-chocolate, @astryxdesign/theme-gothic (dark-only), @astryxdesign/theme-matcha, @astryxdesign/theme-stone, and @astryxdesign/theme-y2k. See `astryx docs theme` for the full theming guide.',
         },
         {
           type: 'prose',
-          text: 'These stylesheets are cascade-layered: the reset loads in @layer reset and component styles in @layer astryx-base. If your project has existing global CSS, a legacy reset, or Tailwind, declare the layer order explicitly and assign every stylesheet to a layer deliberately: unlayered styles and later layers both override astryx-base regardless of specificity. See the Cascade Layer Safety section in `npx astryx docs migration` before building screens.',
+          text: 'These stylesheets are cascade-layered: the reset loads in @layer reset and component styles in @layer astryx-base. If your project has existing global CSS, a legacy reset, or Tailwind, declare the layer order explicitly and assign every stylesheet to a layer deliberately: unlayered styles and later layers both override astryx-base regardless of specificity. See the Cascade Layer Safety section in `astryx docs migration` before building screens.',
         },
       ],
     },
@@ -172,11 +172,11 @@ pnpm dev`,
           type: 'code',
           lang: 'bash',
           label: 'Terminal',
-          code: `npx astryx component          # list all components
-npx astryx component Button   # props, usage, theming for Button
-npx astryx docs               # list all doc topics
-npx astryx template --list    # available page templates
-npx astryx docs tokens        # spacing, color, radius reference`,
+          code: `astryx component          # list all components
+astryx component Button   # props, usage, theming for Button
+astryx docs               # list all doc topics
+astryx template --list    # available page templates
+astryx docs tokens        # spacing, color, radius reference`,
         },
       ],
     },

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`, and 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; 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, since 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.",
+        },
+      ],
+    },
+  ],
+};