@astryxdesign/cli 0.7.12-canary.f543ec7 → 0.7.12

package/api/swizzle/_moduleGraph.mjs

@@ -14,6 +14,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {isBuiltin} from 'node:module';
 import {packageOf} from '../../foundation/render/served-packages.mjs';
+import {resolveInstalledPackageDir} from '../../foundation/integrations/installed-package.mjs';
 import {parse} from '@babel/parser';
 import {
   inspectPackageExport,
@@ -390,6 +391,8 @@ function publicSurfaceOf(packageDir, srcRoot, originsOf) {
  *   file the copy holds (absolute source path), with the edits its imports need
  * @property {Map<string, Set<string>>} dependsOn file -> carried files its
  *   computed specifiers point at
+ * @property {Map<string, string>} otherPackages the source root of each other
+ *   Astryx package the copy carries modules from, with its package name
  * @property {Record<string, string>} dependencies each npm package the copied
  *   files import, other than the owner package and Node's built-in modules,
  *   with the range the owner package declares
@@ -429,19 +432,6 @@ export function planCopy({
     });
   /** @param {string} file @param {string} name */
   const originOf = (file, name) => originsOf(file, 'type').get(name) ?? null;
-  /**
-   * The subpaths that export a module's export: as a value when the import
-   * takes a value, since a type-only export is erased at runtime.
-   * @param {string} file
-   * @param {string} name
-   * @param {boolean} typeOnly
-   */
-  const exportersOf = (file, name, typeOnly) => {
-    const origin = originOf(file, name);
-    if (!origin) return [];
-    const kind = typeOnly ? 'type' : 'value';
-    return surface.byOrigin[kind].get(`${origin.file}#${origin.name}`) ?? [];
-  };
   /**
    * The name a module exports one of its own bindings under, or null.
    * @param {{file: string, name: string}} origin
@@ -454,7 +444,6 @@ export function planCopy({
   };
   /** @type {Map<string, string|null>} */
   const resolutions = new Map();
-  const surface = publicSurfaceOf(packageDir, srcRoot, originsOf);
   /** @type {CopyPlan['files']} */
   const files = new Map();
   /** @type {CopyPlan['dependsOn']} */
@@ -472,73 +461,162 @@ export function planCopy({
   };
   /** @param {string} file */
   const inComponent = file => file.startsWith(componentDir + path.sep);
-  /** @param {string} file */
-  const inSource = file => file.startsWith(srcRoot + path.sep);
 
   /**
-   * The subpath that exports every name a module exports, with the same
-   * definition. An exactly exported file is its own subpath.
-   * @param {string} file
-   * @returns {string|null}
+   * @typedef {ReturnType<typeof makeContext>} PackageContext
    */
-  const subpathCoveringModule = file => {
-    const exact = surface.byFile.get(file);
-    if (exact) return exact;
-    const names = [...originsOf(file, 'type').keys()];
-    if (names.length === 0) return null;
-    const values = originsOf(file, 'value');
-    const options = names.map(name =>
-      exportersOf(file, name, !values.has(name))
-        .filter(o => o.name === name)
-        .map(o => o.subpath),
-    );
-    const common = options.reduce((acc, list) =>
-      acc.filter(s => list.includes(s)),
-    );
-    return STYLEX_FILE.test(file) ? null : pickSubpath(common, file);
-  };
 
   /**
-   * The public subpath to take a name from. A StyleX module is imported by
-   * its own exported path, because the StyleX compiler resolves styles and
-   * variables from the real module; when that path is not exported, there is
-   * no public import.
-   * @param {string[]} subpaths subpaths that export the name
-   * @param {string} target the module the import names
-   * @param {string} [originFile] the module that defines the name
-   * @returns {string|null}
+   * How references inside one package's source are planned: its public
+   * surface and the subpaths a name or module is imported from.
+   * @param {{packageDir: string, srcRoot: string, ownerPackage: string}} pkg
    */
-  const choosePublic = (subpaths, target, originFile) => {
-    const exact = originFile ? surface.byFile.get(originFile) : undefined;
-    if (exact && subpaths.includes(exact)) return exact;
-    if (
-      STYLEX_FILE.test(target) ||
-      (originFile && STYLEX_FILE.test(originFile))
-    )
-      return null;
-    return pickSubpath(subpaths, target);
+  function makeContext({packageDir, srcRoot, ownerPackage}) {
+    const surface = publicSurfaceOf(packageDir, srcRoot, originsOf);
+    /** @param {string} file */
+    const inSource = file => file.startsWith(srcRoot + path.sep);
+    /**
+     * The subpaths that export a module's export: as a value when the import
+     * takes a value, since a type-only export is erased at runtime.
+     * @param {string} file
+     * @param {string} name
+     * @param {boolean} typeOnly
+     */
+    const exportersOf = (file, name, typeOnly) => {
+      const origin = originOf(file, name);
+      if (!origin) return [];
+      const kind = typeOnly ? 'type' : 'value';
+      return surface.byOrigin[kind].get(`${origin.file}#${origin.name}`) ?? [];
+    };
+    /**
+     * The subpath that exports every name a module exports, with the same
+     * definition. An exactly exported file is its own subpath.
+     * @param {string} file
+     * @returns {string|null}
+     */
+    const subpathCoveringModule = file => {
+      const exact = surface.byFile.get(file);
+      if (exact) return exact;
+      const names = [...originsOf(file, 'type').keys()];
+      if (names.length === 0) return null;
+      const values = originsOf(file, 'value');
+      const options = names.map(name =>
+        exportersOf(file, name, !values.has(name))
+          .filter(o => o.name === name)
+          .map(o => o.subpath),
+      );
+      const common = options.reduce((acc, list) =>
+        acc.filter(s => list.includes(s)),
+      );
+      return STYLEX_FILE.test(file) ? null : pickSubpath(common, file);
+    };
+
+    /**
+     * The public subpath to take a name from. A StyleX module is imported by
+     * its own exported path, because the StyleX compiler resolves styles and
+     * variables from the real module; when that path is not exported, there is
+     * no public import.
+     * @param {string[]} subpaths subpaths that export the name
+     * @param {string} target the module the import names
+     * @param {string} [originFile] the module that defines the name
+     * @returns {string|null}
+     */
+    const choosePublic = (subpaths, target, originFile) => {
+      const exact = originFile ? surface.byFile.get(originFile) : undefined;
+      if (exact && subpaths.includes(exact)) return exact;
+      if (
+        STYLEX_FILE.test(target) ||
+        (originFile && STYLEX_FILE.test(originFile))
+      )
+        return null;
+      return pickSubpath(subpaths, target);
+    };
+
+    /**
+     * Prefer the subpath of the module's top folder, then the package root.
+     * @param {string[]} subpaths
+     * @param {string} file
+     * @returns {string|null}
+     */
+    const pickSubpath = (subpaths, file) => {
+      if (subpaths.length === 0) return null;
+      const top = `./${toPosix(path.relative(srcRoot, file)).split('/')[0]}`;
+      return (
+        subpaths.find(s => s === top) ??
+        subpaths.find(s => s === '.') ??
+        [...subpaths].sort((a, b) => a.length - b.length)[0]
+      );
+    };
+
+    /** @param {string} subpath */
+    const publicSpecifier = subpath =>
+      subpath === '.' ? ownerPackage : `${ownerPackage}/${subpath.slice(2)}`;
+
+    return {
+      packageDir,
+      srcRoot,
+      ownerPackage,
+      surface,
+      inSource,
+      exportersOf,
+      subpathCoveringModule,
+      choosePublic,
+      publicSpecifier,
+    };
+  }
+  const owner = makeContext({packageDir, srcRoot, ownerPackage});
+  /** @type {Map<string, PackageContext>} other packages' contexts, by source root */
+  const others = new Map();
+  /** @param {string} file */
+  const contextOf = file => {
+    if (file.startsWith(srcRoot + path.sep)) return owner;
+    for (const [root, context] of others) {
+      if (file.startsWith(root + path.sep)) return context;
+    }
+    return owner;
   };
 
   /**
-   * Prefer the subpath of the module's top folder, then the package root.
-   * @param {string[]} subpaths
+   * The source module a bare import of another Astryx package's
+   * `./internal/*` path names, or null. That module is carried, and its
+   * package gets a context of its own.
    * @param {string} file
+   * @param {string} specifier
    * @returns {string|null}
    */
-  const pickSubpath = (subpaths, file) => {
-    if (subpaths.length === 0) return null;
-    const top = `./${toPosix(path.relative(srcRoot, file)).split('/')[0]}`;
-    return (
-      subpaths.find(s => s === top) ??
-      subpaths.find(s => s === '.') ??
-      [...subpaths].sort((a, b) => a.length - b.length)[0]
-    );
+  const internalModuleOf = (file, specifier) => {
+    const name = packageOf(specifier);
+    const sub = specifier.slice(name.length + 1);
+    if (!name.startsWith('@astryxdesign/') || name === ownerPackage)
+      return null;
+    if (!/^internal(\/|$)/.test(sub)) return null;
+    const installed = resolveInstalledPackageDir(name, path.dirname(file));
+    if (!installed) return null;
+    const dir = fs.realpathSync(installed.packageDir);
+    /** @type {{exports?: unknown}} */
+    let pkg;
+    try {
+      pkg = JSON.parse(
+        fs.readFileSync(path.join(dir, 'package.json'), 'utf-8'),
+      );
+    } catch {
+      return null;
+    }
+    const target = sourceExportTarget(pkg, dir, `./${sub}`);
+    // A StyleX module's identity is its path, so the copy keeps importing it
+    // by its exported path and agrees with the package on it.
+    if (!target || STYLEX_FILE.test(target)) return null;
+    const src = path.join(dir, 'src');
+    const root = target.startsWith(src + path.sep) ? src : dir;
+    if (!others.has(root)) {
+      others.set(
+        root,
+        makeContext({packageDir: dir, srcRoot: root, ownerPackage: name}),
+      );
+    }
+    return target;
   };
 
-  /** @param {string} subpath */
-  const publicSpecifier = subpath =>
-    subpath === '.' ? ownerPackage : `${ownerPackage}/${subpath.slice(2)}`;
-
   /**
    * Carry a module in the copy.
    * @param {string} from
@@ -560,8 +638,14 @@ export function planCopy({
     const edits = [];
     files.set(file, {code: parsed.code, edits});
     if (!CODE_FILE.test(file)) continue;
+    const context = contextOf(file);
     for (const ref of parsed.references) {
       if (!ref.source.startsWith('.')) {
+        const internal = internalModuleOf(file, ref.source);
+        if (internal) {
+          edits.push(sourceEdit(parsed.code, ref, carry(file, internal)));
+          continue;
+        }
         const builtin = ref.source.startsWith('node:') || isBuiltin(ref.source);
         const name = packageOf(ref.source);
         if (!builtin && name !== ownerPackage) packages.add(name);
@@ -576,44 +660,61 @@ export function planCopy({
         else edits.push(sourceEdit(parsed.code, ref, carry(file, target)));
         continue;
       }
-      if (!CODE_FILE.test(target) || !inSource(target)) {
+      if (!CODE_FILE.test(target) || !context.inSource(target)) {
         // An asset, such as `../../locales/en.json` or a stylesheet, that the
         // package exports by its own path is imported from the package.
-        const subpath = `./${toPosix(path.relative(packageDir, target))}`;
+        const subpath = `./${toPosix(path.relative(context.packageDir, target))}`;
         if (
-          subpathDeclaration(surface.exportsField, subpath).state === 'declared'
+          subpathDeclaration(context.surface.exportsField, subpath).state ===
+          'declared'
         ) {
+          if (context !== owner) packages.add(context.ownerPackage);
           edits.push(
-            sourceEdit(parsed.code, ref, `${ownerPackage}/${subpath.slice(2)}`),
+            sourceEdit(
+              parsed.code,
+              ref,
+              `${context.ownerPackage}/${subpath.slice(2)}`,
+            ),
           );
           continue;
         }
         // An unexported asset in the source is carried; one outside it is
         // left for the build to report.
-        if (!inSource(target)) continue;
+        if (!context.inSource(target)) continue;
         edits.push(sourceEdit(parsed.code, ref, carry(file, target)));
         continue;
       }
-      edits.push(planReference(file, parsed.code, ref, target));
+      edits.push(planReference(context, file, parsed.code, ref, target));
     }
   }
-  return {files, dependsOn, dependencies: declaredRanges(packageDir, packages)};
+  return {
+    files,
+    dependsOn,
+    dependencies: declaredRanges(packageDir, packages),
+    otherPackages: new Map(
+      [...others].map(([root, c]) => [root, c.ownerPackage]),
+    ),
+  };
 
   /**
    * Decide one reference that leaves the component folder.
+   * @param {PackageContext} context the package the importing file is in
    * @param {string} file
    * @param {string} code
    * @param {ModuleReference} ref
    * @param {string} target
    * @returns {PlannedEdit}
    */
-  function planReference(file, code, ref, target) {
+  function planReference(context, file, code, ref, target) {
+    // A carried module of another package imports that package's public names
+    // from it, so the copy depends on it.
+    if (context !== owner) packages.add(context.ownerPackage);
     if (ref.kind !== 'named' && ref.kind !== 'reexportNamed') {
-      const covering = subpathCoveringModule(target);
+      const covering = context.subpathCoveringModule(target);
       return sourceEdit(
         code,
         ref,
-        covering ? publicSpecifier(covering) : carry(file, target),
+        covering ? context.publicSpecifier(covering) : carry(file, target),
       );
     }
     /** @type {Array<{choice: SpecifierChoice, specs: ImportSpecifier[]}>} */
@@ -630,13 +731,20 @@ export function planCopy({
     };
     for (const spec of ref.specifiers) {
       if (spec.imported === '*') {
-        const covering = subpathCoveringModule(target);
-        add(covering ? publicSpecifier(covering) : carry(file, target), spec);
+        const covering = context.subpathCoveringModule(target);
+        add(
+          covering ? context.publicSpecifier(covering) : carry(file, target),
+          spec,
+        );
         continue;
       }
       const origin = originOf(target, spec.imported);
-      const publicOptions = exportersOf(target, spec.imported, spec.typeOnly);
-      const chosen = choosePublic(
+      const publicOptions = context.exportersOf(
+        target,
+        spec.imported,
+        spec.typeOnly,
+      );
+      const chosen = context.choosePublic(
         publicOptions.map(o => o.subpath),
         target,
         origin?.file,
@@ -645,7 +753,7 @@ export function planCopy({
         const exported = /** @type {{name: string}} */ (
           publicOptions.find(o => o.subpath === chosen)
         ).name;
-        add(publicSpecifier(chosen), {...spec, imported: exported});
+        add(context.publicSpecifier(chosen), {...spec, imported: exported});
       } else {
         // Take the name from the module that defines it, so the copy carries
         // that module and not a whole barrel. An origin names a binding, so
@@ -654,7 +762,7 @@ export function planCopy({
         const definingExport =
           origin &&
           origin.file !== target &&
-          inSource(origin.file) &&
+          context.inSource(origin.file) &&
           !parseModule(target).declares.has(spec.imported)
             ? exportNameOf(origin)
             : null;

package/api/swizzle/copy/copy.mjs

@@ -361,12 +361,32 @@ export async function swizzleCopy(component, options = {}) {
   );
   /** @type {Map<string, string>} */
   const rootDests = new Map();
+  // A module from another Astryx package goes under a folder named after that
+  // package, at its path in that package's source.
+  /** @param {string} file */
+  const otherPackageOf = file => {
+    for (const [root, name] of plan.otherPackages) {
+      if (file.startsWith(root + path.sep)) return {root, folder: name.split('/').pop() ?? name};
+    }
+    return null;
+  };
+  /** @param {string} file the version of the package a helper comes from */
+  const versionOf = file => {
+    const other = otherPackageOf(file);
+    return other
+      ? packageVersionOf(findPackageRoot(other.root) ?? other.root)
+      : ownerVersion;
+  };
   for (const file of [...allFiles].sort()) {
     if (layoutDestOf(file) != null) continue;
-    const packagePath = path.relative(graphRoot, file);
-    let dest = path.join(outputBase, packagePath);
+    const other = otherPackageOf(file);
+    const base = other ? other.folder : path.basename(packageDir);
+    const packagePath = path.relative(other ? other.root : graphRoot, file);
+    let dest = other
+      ? path.join(outputBase, base, packagePath)
+      : path.join(outputBase, packagePath);
     for (let n = 1; takenDests.has(dest); n++) {
-      const folder = n === 1 ? path.basename(packageDir) : `${path.basename(packageDir)}-${n}`;
+      const folder = n === 1 && !other ? base : `${base}-${n}`;
       dest = path.join(outputBase, folder, packagePath);
     }
     takenDests.add(dest);
@@ -381,15 +401,17 @@ export async function swizzleCopy(component, options = {}) {
   // A private attribute owner module and the unexported style modules it
   // imports travel whole and are replaced only with --overwrite.
   const ownerGroup = new Set();
+  /** @param {string} file the source root a carried module sits under */
+  const rootOf = file => otherPackageOf(file)?.root ?? srcRoot;
   const ownerQueue = helpers.filter(f =>
-    OWNER_MODULE.test(toModulePath(srcRoot, f)),
+    OWNER_MODULE.test(toModulePath(rootOf(f), f)),
   );
   while (ownerQueue.length > 0) {
     const file = /** @type {string} */ (ownerQueue.shift());
     if (ownerGroup.has(file)) continue;
     ownerGroup.add(file);
     for (const dep of plan.dependsOn.get(file) ?? []) {
-      if (!isComponentFile(dep) && STYLEX_MODULE.test(toModulePath(srcRoot, dep))) {
+      if (!isComponentFile(dep) && STYLEX_MODULE.test(toModulePath(rootOf(dep), dep))) {
         ownerQueue.push(dep);
       }
     }
@@ -431,7 +453,7 @@ export async function swizzleCopy(component, options = {}) {
       attempts.set(file, attempt);
       redirected.set(
         file,
-        versionedPath(baseDestOf(file), ownerVersion, attempt),
+        versionedPath(baseDestOf(file), versionOf(file), attempt),
       );
       moved = true;
     }

package/api/template/skeleton/skeleton.mjs

@@ -146,7 +146,7 @@ function extractSkeleton(source) {
 
     // Match a JSX opening tag, e.g. `<Section` or the legacy `<XDSSection`.
     // The `XDS` prefix is optional (templates author bare names post
-    // un-prefix migration P2380608025). `tagName` is the full authored name
+    // un-prefix migration). `tagName` is the full authored name
     // (used for the self-closing lookahead); `comp` is the bare display name.
     const openMatch = t.match(/^<((XDS)?([A-Z]\w+))/);
     if (openMatch && !t.startsWith('</')) {

package/api/template/template.mjs

@@ -193,6 +193,7 @@ export async function template(name, options = {}) {
       `Unknown template "${name}"`,
       orderByAffinity(name, templates, t => [t.dirName, t.name], {
         closest: true,
+        typos: true,
       }).map(t => ({
         name: t.dirName,
         reason: `${t.type} template`,

package/assets/codemods/transforms/v0.1.0/drop-xds-prefix-imports.mjs

@@ -3,7 +3,7 @@
 /**
  * @file Codemod: Drop the `XDS` prefix from @xds/core imports and their usages
  *
- * Part of the XDS-prefix migration (P2380608025). Rewrites consumer code from
+ * Part of the XDS-prefix migration. Rewrites consumer code from
  * the prefixed names to their bare equivalents:
  *
  *   XDSButton      -> Button

package/assets/codemods/transforms/v0.1.0/index.mjs

@@ -24,7 +24,7 @@ import migrateXdsCssSurfaces, {
 
 export default [
   {
-    // XDS-prefix migration (P2380608025). Mandatory in v0.1.0: the release
+    // XDS-prefix migration. Mandatory in v0.1.0: the release
     // dropped the prefixed compatibility aliases (useXDSTheme, XDSButton,
     // XDSIconRegistry, ...), so consumers upgrading from 0.0.x MUST rewrite
     // prefixed imports to their bare names.

package/assets/discover/official-packages.json

@@ -100,6 +100,10 @@
           "kind": "component",
           "name": "ChatUnreadDivider"
         },
+        {
+          "kind": "component",
+          "name": "ChatVirtualizer"
+        },
         {
           "kind": "component",
           "name": "CircleCheckIndicator"
@@ -128,6 +132,10 @@
           "kind": "component",
           "name": "CommentThread"
         },
+        {
+          "kind": "component",
+          "name": "DialogHeroHeader"
+        },
         {
           "kind": "component",
           "name": "DiffViewer"
@@ -136,6 +144,10 @@
           "kind": "component",
           "name": "EmojiPicker"
         },
+        {
+          "kind": "component",
+          "name": "LineClamp"
+        },
         {
           "kind": "component",
           "name": "ListInput"
@@ -252,6 +264,10 @@
           "kind": "template",
           "name": "CommentThreadShowcase"
         },
+        {
+          "kind": "template",
+          "name": "DialogHeroHeaderShowcase"
+        },
         {
           "kind": "template",
           "name": "DiffViewerShowcase"

package/assets/docs/styling-overview.doc.mjs

@@ -90,7 +90,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'bash',
-          label: 'Install (add to an existing Tailwind v4 app)',
+          label: 'Install',
           code: '{@pm install @astryxdesign/core @stylexjs/stylex @astryxdesign/theme-neutral}',
         },
         {
@@ -113,7 +113,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'For Tailwind v3, see the layer workaround in {@link generic:migration-setup}.',
+          text: 'A project with Tailwind already set up needs a smaller change, which {@link generic:tailwind} shows. For Tailwind v3, see the layer workaround in {@link generic:migration-setup}.',
         },
       ],
     },
@@ -162,7 +162,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: '`{@command swizzle <Component>}` writes an `astryx-swizzle.json` marker into an output folder it owns (one the copy creates, an empty one, or one it marked before); every module under that folder then compiles as Astryx source, so keep copies in a folder of their own, such as the default `components/astryx`. For a folder that already holds other files it writes no marker and says how to add one by hand. With `@astryxdesign/build`\'s Babel, PostCSS and Vite integrations, or `withAstryx()` under webpack, a copy under that folder compiles into `astryx-base`, below `astryx-theme`, so theme component overrides reach it as they reach the package component. Under Turbopack, and with the stock StyleX plugins above, a copy\'s rules land in your own styles, above `astryx-theme`, and theme component overrides do not reach it.',
+          text: "`{@command swizzle <Component>}` writes an `astryx-swizzle.json` marker into an output folder it owns (one the copy creates, an empty one, or one it marked before); every module under that folder then compiles as Astryx source, so keep copies in a folder of their own, such as the default `components/astryx`. For a folder that already holds other files it writes no marker and says how to add one by hand. With `@astryxdesign/build`'s Babel, PostCSS and Vite integrations, or `withAstryx()` under webpack, a copy under that folder compiles into `astryx-base`, below `astryx-theme`, so theme component overrides reach it as they reach the package component. Under Turbopack, and with the stock StyleX plugins above, a copy's rules land in your own styles, above `astryx-theme`, and theme component overrides do not reach it.",
         },
       ],
     },

package/assets/docs/tree/icon-sets.doc.mjs

@@ -61,7 +61,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: "`outline.doc.mjs` is the descriptor: name, display name and description (`--display-name`, `--description`), and `license`, the SPDX license of the artwork (it starts as your package's own). `outline.icons.json` starts with no icons and an empty `map`; its `module` is your package name. `outline.generated.js` is the set's generated module, with its declaration file `outline.generated.d.ts`: the CLI writes both, and every icon and the theme map are exports of it. Every field is in {@link schema:icon-set-doc} and {@link schema:icon-set-data}.",
+          text: "`outline.doc.mjs` is the descriptor: name, display name and description (`--display-name`, `--description`), and `license`, the SPDX license of the artwork (it starts as your package's own). `outline.icons.json` starts with no icons and an empty `map`; its `module` is your package name. After you rename the package, the next command that writes the data file (`new-set` on the existing set, with or without `--from`, `add`, `map`, or `new-definition --icon`) writes the new name and keeps any subpath (`@acme/old-icons/outline` becomes `@acme/new-icons/outline`), and its receipt says so. `outline.generated.js` is the set's generated module, with its declaration file `outline.generated.d.ts`: the CLI writes both, and every icon and the theme map are exports of it. Every field is in {@link schema:icon-set-doc} and {@link schema:icon-set-data}.",
         },
         {
           type: 'prose',
@@ -121,7 +121,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: "Every component the library exports becomes an icon (an alias of one component is recorded once), named `<Name>Icon`, with an id from its name (`Squares2X2Icon` is `squares-2x2`: a dimension stays one word). `map` is filled only where a definition's name is an icon's id (`delete` → icon `delete`), and the receipt lists those entries under Mapped by name: a library can draw another meaning under the same name (one library's `delete` is a backspace key), so check each. An icon whose id is only one of a definition's words (`trash` for `delete`) may mean something else in this library, so the receipt lists it under Suggestions, with the `experimental icon map <definition> <icon>` command for each, and writes nothing for it: check the meaning, then run the ones that fit. Run it again after a library release to refresh the icons that library supplies; `map` entries whose icon still exists are kept, and the receipt names any icon the library dropped, any icon `--exclude` left out, and the `map` entries each took with it. Icons you added from your own files or another library are left as they are. Icons you added one file at a time from the same package (`--from <package>/dist/XIcon`) move to the root import when you refresh from the package root and the root exports the same icon; each keeps its id, export, `map` entries, variants, and words on that refresh and every later one, and the receipt lists it under `moved`. A library icon whose id or name a moved icon already has is left out. When another icon of the set already reads the same root export, the icon stays on its own file, and the receipt says why. An icon you already have is known by the library export it re-exports, so it keeps its export name exactly, its `map` entries, variants, and words, even when a newer CLI spells its id differently or your `--exclude` lets a library prefix come off new ids; the receipt lists each changed id under `renamed`. An id you chose that is not a spelling of the library name (`dismiss` for `XIcon`) is kept. A refresh with `--dry-run` writes nothing and prints the Mapped by name and Suggestions lists again; `--display-name` and `--description` on a refresh rewrite the descriptor. Variants added with `add --variant … --all` are kept too; run that `add` again to pick up icons the release added. `experimental icon --list` shows how many definitions the set maps.",
+          text: "Every component the library exports becomes an icon (an alias of one component is recorded once), named `<Name>Icon`, with an id from its name (`Squares2X2Icon` is `squares-2x2`: a dimension stays one word). An export name cannot start with a digit, so an icon whose id would start with one once the library prefix comes off keeps the prefix (`fa0` is id `fa-0`, exported as `Fa0Icon`), and an id you give with `--id` must start with a letter. `map` is filled only where a definition's name is an icon's id (`delete` → icon `delete`), and the receipt lists those entries under Mapped by name: a library can draw another meaning under the same name (one library's `delete` is a backspace key), so check each. An icon whose id is only one of a definition's words (`trash` for `delete`) may mean something else in this library, so the receipt lists it under Suggestions, with the `experimental icon map <definition> <icon>` command for each, and writes nothing for it: check the meaning, then run the ones that fit. Run it again after a library release to refresh the icons that library supplies; `map` entries whose icon still exists are kept, and the receipt names any icon the library dropped, any icon `--exclude` left out, and the `map` entries each took with it. Icons you added from your own files or another library are left as they are. Icons you added one file at a time from the same package (`--from <package>/dist/XIcon`) move to the root import when you refresh from the package root and the root exports the same icon; each keeps its id, export, `map` entries, variants, and words on that refresh and every later one, and the receipt lists it under `moved`. A library icon whose id or name a moved icon already has is left out. When another icon of the set already reads the same root export, the icon stays on its own file, and the receipt says why. An icon you already have is known by the library export it re-exports, so it keeps its export name exactly, its `map` entries, variants, and words, even when a newer CLI spells its id differently or your `--exclude` lets a library prefix come off new ids; the receipt lists each changed id under `renamed`. An id you chose that is not a spelling of the library name (`dismiss` for `XIcon`) is kept. A refresh with `--dry-run` writes nothing and prints the Mapped by name and Suggestions lists again; `--display-name` and `--description` on a refresh rewrite the descriptor. Variants added with `add --variant … --all` are kept too; run that `add` again to pick up icons the release added. `experimental icon --list` shows how many definitions the set maps.",
         },
         {
           type: 'prose',
@@ -139,11 +139,11 @@ astryx experimental icon add --variant solid --from @heroicons/react/24/solid --
         },
         {
           type: 'prose',
-          text: "A library that redraws its artwork for small sizes (Heroicons' 20px mini and 16px micro) ships each of those as its own set in its own package (their export names match the 24px ones), not as variants: a variant's size comes from CSS. `--variants` lists the variants; `--default-variant` names the one each icon's own export draws (when omitted, the look a library that names its looks draws; otherwise the set's current default, else, on a set without icons, the first variant; a set with icons changes it only with `--from`, and only in a library that names its looks). `--all` adds the variant for every icon whose id an export of `--from` has (`TrashIcon` in the solid module becomes `TrashSolidIcon`, the solid variant of `trash`), and the receipt lists the icons the module has no export for. Running it again changes nothing.",
+          text: "A library that redraws its artwork for small sizes (Heroicons' 20px mini and 16px micro) ships each of those as its own set in its own package (their export names match the 24px ones), not as variants: a variant's size comes from CSS. `--variants` lists the variants; `--default-variant` names the one each icon's own export draws (when omitted, the look a library that names its looks draws; otherwise the set's current default, else, on a set without icons, the first variant; a set with icons changes it only with `--from`, and only in a library that names its looks). `--all` adds the variant for every icon whose id an export of `--from` has (`TrashIcon` in the solid module becomes `TrashSolidIcon`, the solid variant of `trash`), and the receipt lists the icons the module has no export for. A library may ship each look as its own package (Font Awesome's solid and regular packages): `--from` may then name the other package, and an icon gains the variant from the export of the same name there; the receipt lists the icons that package has no export for. Running it again changes nothing.",
         },
         {
           type: 'prose',
-          text: 'A library whose icons are data (objects or SVG strings) has no components to find: create the set, declare an `adapter` in its data file (see library shapes), and run the command again; every data export then becomes an icon through the adapter. When every icon export shares a leading word, such as `feather` in `featherEye` and `featherSun`, ids and export names leave it out: `featherEye` becomes id `eye`, exported as `EyeIcon`. The prefix is read over icon-like exports only: SCREAMING_CASE constants (`README`, `VERSION`), number and boolean exports, and, next to components or icon objects, plain strings are never icons. Components named `…Provider` or `…Context` are never icons either. Leave out any other export that is not an icon with `--exclude meta,version`: the data file keeps the list in `exclude`, so a refresh leaves them out too. When a library exports one icon under several names (`Trash2` and `Trash`), the icon is recorded once and its other names become words, so `experimental icon trash-2` finds it and `experimental icon map delete trash-2` maps it. `experimental icon add` reads the prefix the same way, and reuses the icon an export already has, so its commands need no `--id`.',
+          text: 'A library whose icons are data (objects or SVG strings) has no components to find: create the set, declare an `adapter` in its data file (see library shapes), and run the command again; every data export then becomes an icon through the adapter. When every icon export shares a leading word, such as `feather` in `featherEye` and `featherSun`, ids and export names leave it out: `featherEye` becomes id `eye`, exported as `EyeIcon`. The prefix is read over icon-like exports only: SCREAMING_CASE constants (`README`, `VERSION`), number and boolean exports, and, next to components or icon objects, plain strings are never icons. Components named `…Provider` or `…Context` are never icons either, and neither is a pack: an object whose keys are all other exports of the module, such as `fas` next to `faXmark`. Leave out any other export that is not an icon with `--exclude meta,version`: the data file keeps the list in `exclude`, so a refresh leaves them out too. When a library exports one icon under several names (`Trash2` and `Trash`), the icon is recorded once and its other names become words, so `experimental icon trash-2` finds it and `experimental icon map delete trash-2` maps it. `experimental icon add` reads the prefix the same way, and reuses the icon an export already has, so its commands need no `--id`.',
         },
       ],
     },

package/assets/docs/tree/render-pages.doc.mjs

@@ -57,7 +57,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'What it cannot keep: anything that needs a browser while running. State, effects, click handlers and data loaded after the first paint are gone, and a chart sized by its container is empty, so give charts a fixed size. Read browser-only values such as window inside an effect, or the render stops with ERR_RENDER_BROWSER_API.',
+          text: 'What it cannot keep: anything that needs a browser while running. State, effects, click handlers and data loaded after the first paint are gone. Charts made with recharts are the exception: the render draws each chart and ResponsiveContainer a module of the page (not an installed package) imports from recharts by name (`import {LineChart} from \'recharts\'`), inside the page, so a custom tick, label or shape sees the page\'s React context. A chart sized by its container scales to the width the page gives it, and its legend stays out of the picture: a horizontal legend takes its own row under it (above it when the legend asks for the top), and a vertical legend on one side sits beside it, on that side; in a chart of fixed size, a legend keeps the place its props give it. Charts show the data and props of the page\'s first render, before its effects run: when the page cannot be drawn again without a browser, or its effects change its charts or re-render the component that makes them, each chart is drawn by itself and its parts see React context defaults. A value a chart\'s parts read from a React context that an effect changes may still show its later value. A `chart-size` warning counts the charts the render cannot draw (one used through `import * as R`, say), and says when charts were drawn by themselves. Read browser-only values such as window inside an effect, or the render stops with ERR_RENDER_BROWSER_API.',
         },
       ],
     },
@@ -67,7 +67,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Each warning names something that may look different from what you meant, and what to change. The most common is a component that ignores its children: `<ListItem>Save</ListItem>` renders an empty row because ListItem takes `label="Save"`. Others flag remote images (a sandboxed viewer cannot load them; save the image next to the page and import it), a `<script>`, `<link>` or `<iframe>` the page itself renders (the file promises to run and load nothing, so remove them), missing images, and output the page printed while rendering.',
+          text: 'Each warning names something that may look different from what you meant, and what to change. The most common is a component that ignores its children: `<ListItem>Save</ListItem>` renders an empty row because ListItem takes `label="Save"`. Others flag remote images (a sandboxed viewer cannot load them; save the image next to the page and import it), a `<script>`, `<link>` or `<iframe>` the page itself renders (the file promises to run and load nothing, so remove them), missing images, and output the page printed while rendering. A `node-crash` warning names a Node build that crashes in `Intl.Segmenter` (its version and path). The page rendered without it, so the output may differ slightly: initials and character counts (such as Avatar initials) can split a joined emoji, a flag, or a letter written with a separate accent mark. Names in ordinary composed letters (`José`, `Zoë`, `李小龙`) come out the same. Render with an official Node.js build to remove the difference.',
         },
       ],
     },
@@ -86,7 +86,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'It writes the page, the modules, stylesheets and JSON files the page reaches through its own imports, and the images, fonts and media the render carried (however the page named them, as long as their bytes really are one): each goes where the page\'s relative imports find it from wherever you put the page, and a file the page imports through a path alias (`@/components/Header`) goes where your project\'s `tsconfig.json` or `jsconfig.json` alias points. Every file but the page goes inside the one new folder the restore creates (the topmost folder on the page\'s path that does not exist yet), never into a folder that already exists: a page that imports other files comes back into a new folder (`--out restored/app/page.tsx`), and a file it imports through a path alias comes back only when that alias points inside the new folder. Nor does it write a file that a test, story or benchmark runner would run by its default patterns (Jest, Vitest, Bun, AVA, Playwright, Storybook, Cypress and `node --test`: names such as `*.test.*`, `*.spec.*`, `*_test.*`, `*-test.*`, `*.bench.*`, `*.stories.*`, `*.cy.*`, and anything under `test/`, `tests/` or `__tests__/`), judged from the repository root (every folder above the file up to it), else the topmost folder with a package.json. Restored files are the sender\'s code: read them before you run or import them. Without `--out`, everything comes back into a new folder beside the HTML file, named after it (`page.html` comes back into `page-restored/`). A received file that carries anything else (a file the page never imports, a dotfile, `package.json`, a tool configuration, a path that leaves the folder) is refused with nothing written. An existing file is never replaced unless you pass `--overwrite`, and the refusal names every one; a generated, vendored or ignored file, and any path through a symbolic link, is not written even then. Add `--json` for the result as data: what was written, how big it is, and every warning.',
+          text: 'It writes the page, the modules, stylesheets and JSON files the page reaches through its own imports, and the images, fonts and media the render carried (however the page named them, as long as their bytes really are one): each goes where the page\'s relative imports find it from wherever you put the page, and a file the page imports through a path alias (`@/components/Header`) goes where your project\'s `tsconfig.json` or `jsconfig.json` alias points. Every file but the page goes inside the one new folder the restore creates (the topmost folder on the page\'s path that does not exist yet), never into a folder that already exists: a page that imports other files comes back into a new folder (`--out restored/app/page.tsx`), and a file it imports through a path alias comes back only when that alias points inside the new folder. Nor does it write a file that a test, story or benchmark runner would run by its default patterns (Jest, Vitest, Bun, AVA, Playwright, Storybook, Cypress and `node --test`: names such as `*.test.*`, `*.spec.*`, `*_test.*`, `*-test.*`, `*.bench.*`, `*.stories.*`, `*.cy.*`, and anything under `test/`, `tests/` or `__tests__/`), judged from the repository root (every folder above the file up to it), else the topmost folder with a package.json. Restored files are the sender\'s code: read them before you run or import them. Without `--out`, everything comes back into a new folder beside the HTML file, named after it (`page.html` comes back into `page-restored/`). A received file that carries anything else (a file the page never imports, a dotfile, `package.json`, a tool configuration, a path that leaves the folder) is refused with nothing written. A rendered file that lost its embedded source on the way (a sanitizer or an editor strips `<script>` blocks) and has no Astryx components to rebuild from is refused with `ERR_RENDER_SOURCE_DAMAGED`. An existing file is never replaced unless you pass `--overwrite`, and the refusal names every one; a generated, vendored or ignored file, and any path through a symbolic link, is not written even then. Add `--json` for the result as data: what was written, how big it is, and every warning.',
         },
       ],
     },