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

package/{src/codemods → codemods}/transforms/v0.1.8/rename-avatar-size-scale.mjs

@@ -80,7 +80,7 @@ const UNIQUE = new Set(['tiny', 'xsmall']);
  * Unwraps `'small' as const`. In non-precise contexts, ambiguous names are
  * skipped. Returns true when a rename occurred.
  */
-function renameValue(node, {precise = false} = {}) {
+function renameValue(/** @type {any} */ node, {precise = false} = {}) {
   if (!node) return false;
   const target = node.type === 'TSAsExpression' ? node.expression : node;
   const isString =
@@ -95,7 +95,7 @@ function renameValue(node, {precise = false} = {}) {
 }
 
 /** Extract a plain string value from a literal-ish node, or null. */
-function literalString(node) {
+function literalString(/** @type {any} */ node) {
   const target = node?.type === 'TSAsExpression' ? node.expression : node;
   if (
     target &&
@@ -107,6 +107,11 @@ function literalString(node) {
   return null;
 }
 
+/**
+ * @param {import('../../../types/codemod').AstryxCodemodFile} file
+ * @param {import('../../../types/codemod').CodemodTransformApi} api
+ * @returns {string | null | undefined}
+ */
 export default function transformer(file, api) {
   const j = api.jscodeshift;
   const root = j(file.source);
@@ -114,7 +119,7 @@ export default function transformer(file, api) {
 
   // Track alias-aware local names for the target components.
   const targetLocals = new Set();
-  root.find(j.ImportDeclaration).forEach((path) => {
+  root.find(j.ImportDeclaration).forEach((/** @type {any} */ path) => {
     if (!IMPORT_SOURCES.has(path.node.source.value)) return;
     for (const spec of path.node.specifiers ?? []) {
       if (
@@ -128,14 +133,14 @@ export default function transformer(file, api) {
 
   if (targetLocals.size === 0) return undefined;
 
-  function renameArrayElements(node) {
+  function renameArrayElements(/** @type {any} */ node) {
     let arr = node;
     if (arr.type === 'TSAsExpression') arr = arr.expression;
     if (arr.type !== 'ArrayExpression') return;
     // If the array contains a name unique to Avatar's scale (tiny/xsmall), the
     // whole collection is unambiguously the Avatar size enum, so it is safe to
     // rename the ambiguous members too. Otherwise stay conservative.
-    const precise = arr.elements.some((el) => UNIQUE.has(literalString(el)));
+    const precise = arr.elements.some((/** @type {any} */ el) => UNIQUE.has(literalString(el)));
     for (const el of arr.elements) {
       if (renameValue(el, {precise})) hasChanges = true;
     }
@@ -143,7 +148,7 @@ export default function transformer(file, api) {
 
   // 1. `size` JSX attributes on target components — PRECISE (component known),
   //    so all five names, including the ambiguous ones, are renamed here.
-  root.find(j.JSXOpeningElement).forEach((path) => {
+  root.find(j.JSXOpeningElement).forEach((/** @type {any} */ path) => {
     const name = path.node.name;
     const componentName = name.type === 'JSXIdentifier' ? name.name : null;
     if (!componentName || !targetLocals.has(componentName)) return;
@@ -182,7 +187,7 @@ export default function transformer(file, api) {
   //    arrays — NON-PRECISE (the component isn't known here), so only the
   //    unique names tiny/xsmall are renamed.
   const PropertyType = j.ObjectProperty ?? j.Property;
-  root.find(PropertyType).forEach((path) => {
+  root.find(PropertyType).forEach((/** @type {any} */ path) => {
     const key = path.node.key;
     const keyName =
       key.type === 'Identifier'
@@ -204,7 +209,7 @@ export default function transformer(file, api) {
     // size: { control: 'select', options: ['tiny', ...] }
     if (value.type === 'ObjectExpression') {
       const optionsProp = value.properties.find(
-        (p) => p.key && (p.key.name === 'options' || p.key.value === 'options'),
+        (/** @type {any} */ p) => p.key && (p.key.name === 'options' || p.key.value === 'options'),
       );
       if (optionsProp) renameArrayElements(optionsProp.value);
     }
@@ -216,7 +221,7 @@ export default function transformer(file, api) {
   //    are renamed. This avoids corrupting unrelated unions that happen to use
   //    common words like 'medium' (e.g. a priority or breakpoint type) in a
   //    file that also imports Avatar.
-  root.find(j.TSLiteralType).forEach((path) => {
+  root.find(j.TSLiteralType).forEach((/** @type {any} */ path) => {
     if (renameValue(path.node.literal)) hasChanges = true;
   });
 
@@ -225,7 +230,7 @@ export default function transformer(file, api) {
   //    e.g. `(['tiny', 'xsmall', 'small', 'medium', 'large'] as const).map(...)`
   //    used to render every size. The unique name proves the whole array is the
   //    Avatar enum, so its ambiguous members can be renamed safely.
-  root.find(j.ArrayExpression).forEach((path) => {
+  root.find(j.ArrayExpression).forEach((/** @type {any} */ path) => {
     renameArrayElements(path.node);
   });
 

package/docs/internationalization.doc.mjs

@@ -7,7 +7,7 @@ export const docs = {
   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.',
+    'Set the active locale for astryx components, load locale catalogs, coexist with your own i18n library, swap languages at runtime, and test translations with the pseudo locale.',
 
   sections: [
     {
@@ -16,13 +16,13 @@ export const docs = {
       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.',
+          text: 'Internationalization ships with `@astryxdesign/core`. There is nothing to install. Wrap your app in `<InternationalizationProvider>` and set the active `locale`; astryx components pick up localized strings from that provider.',
         },
         {
           type: 'code',
           lang: 'tsx',
           label: 'Wrap your app',
-          code: `import {InternationalizationProvider} from '@astryxdesign/core';
+          code: `import {InternationalizationProvider} from '@astryxdesign/core/i18n';
 
 function App() {
   return (
@@ -32,53 +32,56 @@ function App() {
   );
 }`,
         },
+        {
+          type: 'prose',
+          text: 'The provider always has the built-in English catalog. Pass additional catalogs through `messages` when you enable another locale.',
+        },
         {
           type: 'code',
           lang: 'tsx',
-          label: 'Read strings inside a component',
-          code: `import {useTranslator} from '@astryxdesign/core';
+          label: 'Load an astryx locale catalog',
+          code: `import {InternationalizationProvider} from '@astryxdesign/core/i18n';
+import fr from '@astryxdesign/core/locales/fr.json';
 
-function SaveButton() {
-  const t = useTranslator();
-  return <button>{t('@myapp.actions.save')}</button>;
-}`,
+<InternationalizationProvider locale="fr" messages={{fr}}>
+  <App />
+</InternationalizationProvider>;`,
         },
         {
           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.',
+          text: 'Astryx ships English today, with first-party translations for other locales on the roadmap. Until a locale is available from `@astryxdesign/core/locales/*`, apps can pass a local catalog with the same shape. See `@astryxdesign/core/locales/en.json` for the current key inventory. Missing keys fall back through the locale chain to English (for example, `pt-BR` walks to `pt`, then to shipped `en`).',
         },
         {
           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.",
+          text: 'Locale catalogs only affect astryx strings. Your app can continue using its own i18n system for product copy.',
         },
       ],
     },
     {
-      title: 'Providing locale catalogs',
+      title: 'Runtime language swap',
       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.',
+          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: 'Add French',
-          code: `import {InternationalizationProvider} from '@astryxdesign/core';
-import fr from './locales/astryx/fr.json';
+          label: 'Toggle between locales',
+          code: `const [locale, setLocale] = useState<'en' | 'fr'>('en');
 
-<InternationalizationProvider locale="fr" messages={{fr}}>
+<InternationalizationProvider locale={locale} messages={{fr}}>
+  <Button
+    label={locale === 'en' ? 'Français' : 'English'}
+    onClick={() => setLocale(l => (l === 'en' ? 'fr' : 'en'))}
+  />
   <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.',
+          text: "Persisting the user's choice (localStorage, cookie, URL segment, account setting) is up to the consumer. Astryx reads whatever `locale` you pass in.",
         },
       ],
     },
@@ -119,7 +122,7 @@ import fr from './locales/astryx/fr.json';
           type: 'code',
           lang: 'tsx',
           label: 'Astryx + react-intl side by side',
-          code: `import {InternationalizationProvider} from '@astryxdesign/core';
+          code: `import {InternationalizationProvider} from '@astryxdesign/core/i18n';
 import {Selector} from '@astryxdesign/core/Selector';
 import {Button} from '@astryxdesign/core/Button';
 import {FormattedMessage, IntlProvider, useIntl} from 'react-intl';
@@ -169,35 +172,56 @@ export default function App() {
         },
         {
           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.",
+          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 [facebook/astryx#4029](https://github.com/facebook/astryx/issues/4029). For now, run the two providers side by side as shown above.",
         },
       ],
     },
     {
-      title: 'Runtime language swap',
+      title: 'Using astryx as your i18n library',
       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.',
+          text: "For production apps with substantial localization needs, we recommend a dedicated i18n library such as react-intl, i18next, next-intl, or LinguiJS. If your app is small or you do not want another runtime, you can resolve your own strings through astryx too. Keep app keys in a separate namespace from `@astryx.*`, and include your own `en` catalog because astryx's built-in English fallback only contains astryx component strings.",
         },
         {
           type: 'code',
           lang: 'tsx',
-          label: 'Toggle between locales',
-          code: `const [locale, setLocale] = useState<'en' | 'fr'>('en');
+          label: 'Translate app strings with astryx',
+          code: `import {Button} from '@astryxdesign/core/Button';
+import {
+  InternationalizationProvider,
+  useTranslator,
+  type Catalog,
+  type MessagesByLocale,
+} from '@astryxdesign/core/i18n';
 
-<InternationalizationProvider locale={locale} messages={{fr}}>
-  <Button
-    label={locale === 'en' ? 'Français' : 'English'}
-    onClick={() => setLocale(l => (l === 'en' ? 'fr' : 'en'))}
-  />
-  <App />
-</InternationalizationProvider>;`,
+const en: Catalog = {
+  '@myapp.actions.save': {defaultMessage: 'Save'},
+};
+
+const fr: Catalog = {
+  '@myapp.actions.save': {defaultMessage: 'Enregistrer'},
+};
+
+const messages: MessagesByLocale = {en, fr};
+
+function SaveButton() {
+  const t = useTranslator();
+  return <Button label={t('@myapp.actions.save')} />;
+}
+
+export default function App() {
+  return (
+    <InternationalizationProvider locale="fr" messages={messages}>
+      <SaveButton />
+    </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.",
+          text: '`Catalog` types a single locale file; `MessagesByLocale` types the map passed to `messages`. A catalog entry uses the same `{defaultMessage, description?}` shape as `@astryxdesign/core/locales/en.json`.',
         },
       ],
     },
@@ -207,36 +231,58 @@ export default function App() {
       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.',
+          text: 'Astryx generates a `pseudo` locale that wraps every string in `⟦…⟧` and replaces letters with accented look-alikes. Switch to it in development to catch hardcoded astryx strings and layout issues caused by longer text.',
         },
         {
           type: 'code',
           lang: 'tsx',
           label: 'Turn on pseudo-localization',
-          code: `import pseudo from '@astryxdesign/core/locales/pseudo.json';
+          code: `import {InternationalizationProvider} from '@astryxdesign/core/i18n';
+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: 'heading',
+          level: 3,
+          text: 'Developers',
+        },
+        {
+          type: 'prose',
+          text: 'Astryx component authors read strings with `useTranslator()` rather than hardcoding user-facing text.',
+        },
+        {
+          type: 'code',
+          lang: 'tsx',
+          label: 'Read an astryx string',
+          code: `import {useTranslator} from '@astryxdesign/core/i18n';
+
+function SaveButton() {
+  const t = useTranslator();
+  return <button>{t('@astryx.actions.save')}</button>;
+}`,
+        },
         {
           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.",
         },
+        {
+          type: 'heading',
+          level: 3,
+          text: 'Translators',
+        },
+        {
+          type: 'prose',
+          text: 'Crowdin is the preferred way to contribute — [join a language](https://crowdin.com/project/astryx), translate strings in the web UI, and your work syncs back to the repo without opening a PR. Direct PRs against `packages/core/locales/*.json` also work if you prefer that flow.',
+        },
       ],
     },
   ],

package/{src/commands → lib/agent-docs}/agent-docs.mjs

@@ -20,13 +20,13 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import {findCoreDir, CLI_ROOT} from '../utils/paths.mjs';
-import {assertWithin, PathSafetyError} from '../utils/path-safety.mjs';
-import {getCliInvocation} from '../utils/package-manager.mjs';
-import {discoverComponents} from '../lib/component-discovery.mjs';
-import {humanLog} from '../lib/json.mjs';
-import {cliError} from '../lib/cli-error.mjs';
-import {ERROR_CODES} from '../lib/error-codes.mjs';
+import {findCoreDir, CLI_ROOT} from '../../utils/paths.mjs';
+import {assertWithin, PathSafetyError} from '../../utils/path-safety.mjs';
+import {getCliInvocation} from '../../utils/package-manager.mjs';
+import {discoverComponents} from '../../lib/component-discovery.mjs';
+import {humanLog} from '../../lib/json.mjs';
+import {cliError} from '../../lib/cli-error.mjs';
+import {ERROR_CODES} from '../../lib/error-codes.mjs';
 
 const AGENTS_MD = 'AGENTS.md';
 const CLAUDE_MD = 'CLAUDE.md';
@@ -143,9 +143,11 @@ export function parseBlockVersion(content) {
  */
 export function inspectAgentDocs(targetDir, installedVersion) {
   const version = installedVersion ?? getXdsVersion(findCoreDir(targetDir));
+  /** @type {Array<{path: string, blockVersion: string|null, legacy: boolean, stale: boolean}>} */
   const files = [];
 
   for (const rel of discoverAgentDocs(targetDir)) {
+    /** @type {string} */
     let content;
     try {
       content = fs.readFileSync(path.join(targetDir, rel), 'utf-8');
@@ -165,9 +167,10 @@ export function inspectAgentDocs(targetDir, installedVersion) {
   const staleEntries = files.filter(f => f.stale);
   const staleFiles = staleEntries.map(f => f.path);
   const blockVersions = [
-    ...new Set(staleEntries.map(f => f.blockVersion).filter(Boolean)),
+    ...new Set(staleEntries.map(f => f.blockVersion).filter(/** @returns {v is string} */ (v) => v != null)),
   ];
 
+  /** @type {'missing' | 'stale' | 'current'} */
   let status;
   if (files.length === 0) status = 'missing';
   else if (staleFiles.length > 0) status = 'stale';
@@ -195,7 +198,7 @@ export function resolveAgentPaths(targetDir, agent) {
     return {inject: [], create: [AGENTS_MD, CLAUDE_DIR_MD]};
   }
 
-  const searchPaths = AGENT_PRESETS[agent];
+  const searchPaths = /** @type {Record<string, string[]>} */ (AGENT_PRESETS)[agent];
   if (!searchPaths) {
     return {inject: [], create: [AGENTS_MD]};
   }
@@ -258,6 +261,10 @@ export function detectStylingSystem(targetDir) {
  * `stylingSystem` tailors the custom-styling guidance to what the project has
  * configured (see {@link detectStylingSystem}) so the agent never reaches for a
  * styling path that isn't compiled here.
+ *
+ * @param {string} version
+ * @param {{coreDir?: string|null, invocation?: string, stylingSystem?: 'stylex'|'tailwind'|'css', zh?: boolean, lang?: string}} [options]
+ * @returns {string}
  */
 export function generateCompressedIndex(version, {coreDir, invocation = getCliInvocation(), stylingSystem = 'css'} = {}) {
   const run = invocation;
@@ -337,7 +344,7 @@ export function generateCompressedIndex(version, {coreDir, invocation = getCliIn
   if (fs.existsSync(docsDir)) {
     const topics = fs.readdirSync(docsDir)
       .map(f => f.match(/^(\w+)\.doc\.mjs$/))
-      .filter(Boolean)
+      .filter(/** @returns {m is RegExpMatchArray} */ (m) => m != null)
       .map(m => m[1])
       .sort();
     if (topics.length > 0) lines.push(`  docs <topic>       ${topics.join(', ')}`);
@@ -351,6 +358,8 @@ export function generateCompressedIndex(version, {coreDir, invocation = getCliIn
 
 /**
  * Get Astryx version from core package.
+ * @param {string|null} coreDir
+ * @returns {string}
  */
 export function getXdsVersion(coreDir) {
   if (coreDir) {
@@ -419,6 +428,9 @@ export function injectXdsBlock(filePath, compressedIndex, {createIfMissing = fal
 /**
  * Inject or update Astryx section in AGENTS.md.
  * Always creates the file if it doesn't exist.
+ *
+ * @param {string} targetDir
+ * @param {string} version
  */
 export function injectAgentsMd(targetDir, version) {
   const agentsPath = path.join(targetDir, AGENTS_MD);
@@ -436,6 +448,8 @@ export function injectAgentsMd(targetDir, version) {
  * Inject or update Astryx section in CLAUDE.md.
  * Only injects if CLAUDE.md already exists.
  *
+ * @param {string} targetDir
+ * @param {string} version
  * @returns {boolean} Whether the file was written
  */
 export function injectClaudeMd(targetDir, version) {
@@ -451,6 +465,8 @@ export function injectClaudeMd(targetDir, version) {
  * Remove Astryx section from a file.
  * If the file becomes empty (only boilerplate header remains), deletes it.
  *
+ * @param {string} filePath
+ * @param {{deleteIfEmpty?: boolean}} [options]
  * @returns {boolean} Whether the Astryx section was found and removed
  */
 export function removeXdsBlock(filePath, {deleteIfEmpty = false} = {}) {
@@ -487,6 +503,7 @@ export function removeXdsBlock(filePath, {deleteIfEmpty = false} = {}) {
 
 /**
  * Remove Astryx section from all known agent doc files.
+ * @param {string} targetDir
  */
 export function removeAgentDocs(targetDir) {
   const allPaths = discoverAgentDocs(targetDir);
@@ -528,6 +545,7 @@ export function installAgentDocs(targetDir, {zh = false, lang, agent, paths, onl
   const invocation = getCliInvocation(targetDir);
   const stylingSystem = detectStylingSystem(targetDir);
   const compressedIndex = generateCompressedIndex(version, {coreDir, zh, lang, invocation, stylingSystem});
+  /** @type {string[]} */
   const written = [];
 
   // Explicit paths override everything
@@ -603,6 +621,7 @@ export function installAgentDocs(targetDir, {zh = false, lang, agent, paths, onl
 
 const VALID_AGENTS = ['claude', 'cursor', 'codex', 'hermes', 'all'];
 
+/** @param {import('commander').Command} program */
 export function registerAgentDocs(program) {
   program
     .command('agent-docs')
@@ -610,7 +629,7 @@ export function registerAgentDocs(program) {
     .option('--remove', 'Remove the design system section from all agent doc files')
     .option('--agent <tool>', 'Target tool: claude, cursor, codex, hermes, all')
     .option('--agent-docs-path <path...>', 'Explicit file path(s) to write to')
-    .action(options => {
+    .action(/** @param {{remove?: boolean, agent?: string, agentDocsPath?: string|string[]}} options */ options => {
       const targetDir = process.cwd();
       const coreDir = findCoreDir(targetDir);
       const version = getXdsVersion(coreDir);

package/{src/commands → lib/agent-docs}/agent-docs.path-safety.test.mjs

@@ -16,7 +16,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import {installAgentDocs} from './agent-docs.mjs';
-import {PathSafetyError} from '../utils/path-safety.mjs';
+import {PathSafetyError} from '../../utils/path-safety.mjs';
 
 let tmpDir;
 beforeEach(() => {