@astryxdesign/cli 0.7.12-canary.ccb4a6d → 0.7.12-canary.da3dbdc

package/clients/cli/lib/resolve-theme.mjs

@@ -73,11 +73,22 @@ function extractTheme(mod) {
   return null;
 }
 
+/**
+ * Print a theme warning as one inert line. The configured theme value and the
+ * generated record come from the checkout, so a newline, an escape sequence or
+ * a bidi override in them must not rewrite the terminal. Control and format
+ * characters print as U+FFFD.
+ * @param {string} message
+ */
+function warnTheme(message) {
+  console.warn(message.replace(/[\p{Cc}\p{Cf}]/gu, '\uFFFD'));
+}
+
 /** @param {unknown} mod @param {string} specifier */
 function resolvedThemeData(mod, specifier) {
   const theme = extractTheme(mod);
   if (!theme) {
-    console.warn(
+    warnTheme(
       `⚠ theme: loaded "${specifier}" but could not find a theme object`,
     );
     return null;
@@ -100,7 +111,7 @@ export async function resolveTheme(cwd = process.cwd()) {
   const loaded = await resolveRecordedTheme(cwd);
   if (loaded.configured) {
     if (!loaded.module) {
-      console.warn(
+      warnTheme(
         `⚠ theme: ${loaded.problem ?? `could not resolve the generated default theme (${loaded.specifier})`}`,
       );
       return null;
@@ -130,15 +141,13 @@ export async function resolveTheme(cwd = process.cwd()) {
   if (specifier.startsWith('.') || specifier.startsWith('/')) {
     mod = tryLoadLegacyModule(specifier, cwd);
     if (!mod) {
-      console.warn(
-        `⚠ theme: could not resolve file "${specifier}" from ${cwd}`,
-      );
+      warnTheme(`⚠ theme: could not resolve file "${specifier}" from ${cwd}`);
       return null;
     }
   } else if (specifier.startsWith('@')) {
     mod = tryLoadLegacyModule(specifier, cwd);
     if (!mod) {
-      console.warn(`⚠ theme: could not resolve package "${specifier}"`);
+      warnTheme(`⚠ theme: could not resolve package "${specifier}"`);
       return null;
     }
   } else {
@@ -147,7 +156,7 @@ export async function resolveTheme(cwd = process.cwd()) {
       tryLoadLegacyModule(conventional, cwd) ??
       tryLoadLegacyModule(specifier, cwd);
     if (!mod) {
-      console.warn(
+      warnTheme(
         `⚠ theme: could not resolve "${specifier}" (tried ${conventional} and ${specifier})`,
       );
       return null;

package/foundation/discovery/hook-discovery.mjs

@@ -12,6 +12,13 @@ import {levenshteinDistance} from '../text/string-utils.mjs';
 
 const SKIP_DIRS = new Set(['utils', '__tests__', 'node_modules']);
 
+// A hook's doc outside src/hooks/: a `use…` hook, or a `create…` factory
+// documented as one (its doc typed `HookDoc`, such as createReorderable).
+const HOOK_DOC_FILE_RE = /^(?:use|create)[A-Z]\w*\.doc\.mjs$/;
+
+// Matches the top-level `relatedHooks: [...]` field in a hook .doc.mjs file.
+const RELATED_HOOKS_RE = /(?:^|\n) {0,4}relatedHooks:\s*\[([^\]]*)\]/;
+
 // Matches the top-level `category: 'categoryName'` field in a hook .doc.mjs file.
 const CATEGORY_RE = /(?:^|\n) {0,4}category:\s*['"]([^'"]+)['"]/;
 
@@ -32,6 +39,25 @@ function readHookMeta(docPath) {
   }
 }
 
+/**
+ * Whether a `create…` factory's doc names its own `use…` hook in
+ * `relatedHooks`, as createAnimator's names useAnimator. Such a factory is
+ * listed beside that hook, not on its own.
+ * @param {string} docPath
+ * @param {string} hookName
+ * @returns {boolean}
+ */
+function isBesideOwnHook(docPath, hookName) {
+  if (!hookName.startsWith('create')) return false;
+  const ownHook = `use${hookName.slice('create'.length)}`;
+  try {
+    const related = RELATED_HOOKS_RE.exec(fs.readFileSync(docPath, 'utf-8'));
+    return related != null && related[1].includes(`'${ownHook}'`);
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Extract the hook name from a doc filename.
  * e.g. 'useFocusTrap.doc.mjs' → 'useFocusTrap'
@@ -70,7 +96,8 @@ export function discoverHooks(coreDir) {
     }
   }
 
-  // 2. Scan ALL component directories for files matching use*.doc.mjs
+  // 2. Scan ALL component directories for hook docs: use*.doc.mjs, and
+  // create*.doc.mjs for a factory documented as a hook (createReorderable)
   if (pathExists(srcDir)) {
     const topEntries = listDirEntries(srcDir);
     for (const entry of topEntries) {
@@ -120,14 +147,10 @@ function scanDirForHookDocs(dirPath, hookCategories) {
   for (const entry of entries) {
     if (entry.isDirectory() && !SKIP_DIRS.has(entry.name)) {
       scanDirForHookDocs(path.join(dirPath, entry.name), hookCategories);
-    } else if (
-      entry.isFile() &&
-      entry.name.startsWith('use') &&
-      entry.name.endsWith('.doc.mjs')
-    ) {
+    } else if (entry.isFile() && HOOK_DOC_FILE_RE.test(entry.name)) {
       const hookName = hookNameFromFile(entry.name);
-      if (!hookCategories.has(hookName)) {
-        const docPath = path.join(dirPath, entry.name);
+      const docPath = path.join(dirPath, entry.name);
+      if (!hookCategories.has(hookName) && !isBesideOwnHook(docPath, hookName)) {
         const {category} = readHookMeta(docPath);
         hookCategories.set(hookName, category || 'Other');
       }

package/foundation/doc-compiler/import.d.mts

@@ -17,7 +17,11 @@ export function importDocModule(file: string): Promise<any>;
 export function importTemplateModule(file: string): Promise<any>;
 /**
  * Import a module natively, by file URL: how the docs API, search, and the
- * unchecked component and hook readers have always imported docs.
+ * unchecked component and hook readers have always imported docs. A `.ts`
+ * file goes through jiti, as {@link importDocModule} imports it: Node cannot
+ * strip types from a file under node_modules, and below 22.18 it does not
+ * strip types at all, so a plain import of an installed or linked
+ * integration's `.doc.ts` fails.
  * @param {string} file
  * @returns {Promise<any>}
  */

package/foundation/doc-compiler/import.mjs

@@ -24,7 +24,12 @@
 
 import {pathToFileURL} from 'node:url';
 import {createJiti} from 'jiti';
-import {importUserModule} from '../fs/module-loader.mjs';
+import {importUrl} from '../fs/import-url.mjs';
+import {
+  importUserModule,
+  readFreshInTurn,
+  readInTurn,
+} from '../fs/module-loader.mjs';
 import {fileStamp, recordContentRead} from '../fs/read-record.mjs';
 
 /** @type {ReturnType<typeof createJiti> | undefined} */
@@ -78,6 +83,28 @@ function freshUrl(file) {
   return url.href;
 }
 
+/**
+ * Import `file` from `url`, in its turn with every other read of the file in
+ * this process (`readInTurn`, ../fs/module-loader.mjs).
+ * @param {string} file
+ * @param {string} url
+ * @returns {Promise<any>}
+ */
+function importInTurn(file, url) {
+  return readInTurn(file, () => importUrl(url));
+}
+
+/**
+ * Import `file` again, for a change, as a new module. Node chooses its format
+ * as for the first import. The read takes its turn without the file's
+ * CommonJS cache entry (`readFreshInTurn`, ../fs/module-loader.mjs).
+ * @param {string} file
+ * @returns {Promise<any>}
+ */
+function importFresh(file) {
+  return readFreshInTurn(file, () => importUrl(freshUrl(file)));
+}
+
 /**
  * Import a component, hook, topic, or self-doc module: `.ts` through jiti,
  * anything else natively.
@@ -105,28 +132,35 @@ export function importTemplateModule(file) {
         jsxJiti ??= createJiti(import.meta.url, {jsx: true});
         return jsxJiti.import(first);
       }
-      return import(`file://${first}`);
+      return importInTurn(first, `file://${first}`);
     },
     changed =>
       changed.endsWith('.ts')
         ? createJiti(import.meta.url, {jsx: true, moduleCache: false}).import(
             changed,
           )
-        : import(freshUrl(changed)),
+        : importFresh(changed),
   );
 }
 
 /**
  * Import a module natively, by file URL: how the docs API, search, and the
- * unchecked component and hook readers have always imported docs.
+ * unchecked component and hook readers have always imported docs. A `.ts`
+ * file goes through jiti, as {@link importDocModule} imports it: Node cannot
+ * strip types from a file under node_modules, and below 22.18 it does not
+ * strip types at all, so a plain import of an installed or linked
+ * integration's `.doc.ts` fails.
  * @param {string} file
  * @returns {Promise<any>}
  */
 export function importNativeModule(file) {
+  if (file.endsWith('.ts')) {
+    return importDocModule(file);
+  }
   return importCurrent(
     file,
     'native',
-    first => import(pathToFileURL(first).href),
-    changed => import(freshUrl(changed)),
+    first => importInTurn(first, pathToFileURL(first).href),
+    changed => importFresh(changed),
   );
 }

package/foundation/fs/import-url.d.mts

@@ -0,0 +1,20 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file The dynamic import of an authored module by its file URL.
+ *
+ * @input An absolute `file:` URL, with any query its caller adds to name a
+ *   fresh module.
+ * @output The module's namespace object, as a plain `import()` gives it.
+ * @position Called by the doc importers (../doc-compiler/import.mjs). The
+ *   node test project loads this file natively, as the CLI does
+ *   (vitest.config.ts). The doc files that a catalog command imports then load
+ *   natively as well, without a request to the test runner for each of them.
+ */
+/**
+ * Import the module at `url`.
+ * @param {string} url an absolute `file:` URL
+ * @returns {Promise<any>}
+ */
+export function importUrl(url: string): Promise<any>;

package/foundation/fs/import-url.mjs

@@ -0,0 +1,22 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The dynamic import of an authored module by its file URL.
+ *
+ * @input An absolute `file:` URL, with any query its caller adds to name a
+ *   fresh module.
+ * @output The module's namespace object, as a plain `import()` gives it.
+ * @position Called by the doc importers (../doc-compiler/import.mjs). The
+ *   node test project loads this file natively, as the CLI does
+ *   (vitest.config.ts). The doc files that a catalog command imports then load
+ *   natively as well, without a request to the test runner for each of them.
+ */
+
+/**
+ * Import the module at `url`.
+ * @param {string} url an absolute `file:` URL
+ * @returns {Promise<any>}
+ */
+export function importUrl(url) {
+  return import(url);
+}

package/foundation/fs/module-loader.d.mts

@@ -4,9 +4,9 @@
 /**
  * Import a user-authored module. `.ts` is loaded via jiti; `.mjs`/`.js` use
  * native dynamic import for ordinary cached reads. A fresh `.ts` read uses a
- * no-cache jiti instance. A fresh CommonJS `.js` read evicts and reloads through
- * `require`; an ESM `.js` or `.mjs` read uses a cache-busted file URL. The
- * nearest package.json `type` decides `.js`, matching Node's package scopes.
+ * no-cache jiti instance. Any other fresh read drops the module from the
+ * require cache and imports a cache-busted file URL. Node then chooses its
+ * format as for the first read, so a fresh read gives what a first read gives.
  * Normal loads retain module caching. `fresh` rereads a file that changed
  * during this process: one a codemod rewrote, or an edited doc file (the doc
  * importers in ../doc-compiler/import.mjs read each change once).
@@ -29,6 +29,27 @@ export function importUserModule(file: string, { fresh }?: {
  * @returns {Promise<Record<string, unknown>>}
  */
 export function importThemeArtifact(specifier: string, cwd: string): Promise<Record<string, unknown>>;
+/**
+ * Run `read`, an import of `file`, once the imports of `file` started before
+ * it have ended. Imports of other files do not wait. A fresh read removes the
+ * file from Node's CommonJS cache. A CommonJS import still in progress needs
+ * that entry until it ends.
+ * @template T
+ * @param {string} file absolute path
+ * @param {() => Promise<T>} read
+ * @returns {Promise<T>}
+ */
+export function readInTurn<T>(file: string, read: () => Promise<T>): Promise<T>;
+/**
+ * Run `read`, a fresh import of `file`, in the file's turn (`readInTurn`),
+ * once the file is gone from Node's CommonJS cache. A new URL names a new ES
+ * module only, so a CommonJS module also needs its cache entry gone.
+ * @template T
+ * @param {string} file absolute path
+ * @param {() => Promise<T>} read
+ * @returns {Promise<T>}
+ */
+export function readFreshInTurn<T>(file: string, read: () => Promise<T>): Promise<T>;
 /**
  * Import a user-authored module, take its default export, and validate it
  * through an authoring parser. This is the single load/validation boundary for

package/foundation/fs/module-loader.mjs

@@ -40,30 +40,6 @@ function getJiti() {
   return jitiInstance;
 }
 
-/**
- * Node treats `.js` as ESM only inside the nearest package scope whose
- * package.json declares `"type": "module"`; no package.json defaults to
- * CommonJS.
- * @param {string} file
- * @returns {boolean}
- */
-function isCommonJsFile(file) {
-  let dir = path.dirname(file);
-  for (;;) {
-    const packageJson = path.join(dir, 'package.json');
-    if (fs.existsSync(packageJson)) {
-      try {
-        return JSON.parse(fs.readFileSync(packageJson, 'utf-8')).type !== 'module';
-      } catch {
-        return true;
-      }
-    }
-    const parent = path.dirname(dir);
-    if (parent === dir) return true;
-    dir = parent;
-  }
-}
-
 let loadsInFlight = 0;
 /** @type {typeof process.stdout.write | undefined} */
 let realStdoutWrite;
@@ -104,9 +80,9 @@ async function withStdoutOnStderr(load) {
 /**
  * Import a user-authored module. `.ts` is loaded via jiti; `.mjs`/`.js` use
  * native dynamic import for ordinary cached reads. A fresh `.ts` read uses a
- * no-cache jiti instance. A fresh CommonJS `.js` read evicts and reloads through
- * `require`; an ESM `.js` or `.mjs` read uses a cache-busted file URL. The
- * nearest package.json `type` decides `.js`, matching Node's package scopes.
+ * no-cache jiti instance. Any other fresh read drops the module from the
+ * require cache and imports a cache-busted file URL. Node then chooses its
+ * format as for the first read, so a fresh read gives what a first read gives.
  * Normal loads retain module caching. `fresh` rereads a file that changed
  * during this process: one a codemod rewrote, or an edited doc file (the doc
  * importers in ../doc-compiler/import.mjs read each change once).
@@ -251,31 +227,77 @@ async function importModule(file, fresh) {
   if (fresh && file.endsWith('.ts')) {
     return await createJiti(import.meta.url, {moduleCache: false}).import(file);
   }
-  if (fresh && file.endsWith('.js') && isCommonJsFile(file)) {
-    const resolved = requireFromHere.resolve(file);
-    delete requireFromHere.cache[resolved];
-    const value = requireFromHere(file);
-    if (
-      value != null &&
-      typeof value === 'object' &&
-      value.__esModule === true &&
-      Object.prototype.hasOwnProperty.call(value, 'default')
-    ) {
-      return value;
-    }
-    return {
-      ...(value != null && typeof value === 'object' ? value : {}),
-      default: value,
-    };
-  }
   if (file.endsWith('.ts')) {
     return await getJiti().import(file);
   }
   const url = pathToFileURL(file);
-  if (fresh) {
-    url.searchParams.set('astryx-fresh', String(++freshImportNonce));
+  if (!fresh) return await readInTurn(file, () => import(url.href));
+  // Node chooses the format again, as for the first import: a package's
+  // "type", the extension, or the source's syntax. The query names a new ES
+  // module. A CommonJS module also needs its cache entry gone.
+  url.searchParams.set('astryx-fresh', String(++freshImportNonce));
+  return await readFreshInTurn(file, () => import(url.href));
+}
+
+/**
+ * The name Node's CommonJS cache gives `file`: its real path, so a link and
+ * its target name one entry. A file that does not resolve keeps its path.
+ * @param {string} file absolute path
+ * @returns {string}
+ */
+function cacheKey(file) {
+  try {
+    return requireFromHere.resolve(file);
+  } catch {
+    return file;
   }
-  return await import(url.href);
+}
+
+/**
+ * Each file's latest read, by its cache name, settled once that read ends.
+ * @type {Map<string, Promise<void>>}
+ */
+const readsInProgress = new Map();
+
+/**
+ * Run `read`, an import of `file`, once the imports of `file` started before
+ * it have ended. Imports of other files do not wait. A fresh read removes the
+ * file from Node's CommonJS cache. A CommonJS import still in progress needs
+ * that entry until it ends.
+ * @template T
+ * @param {string} file absolute path
+ * @param {() => Promise<T>} read
+ * @returns {Promise<T>}
+ */
+export function readInTurn(file, read) {
+  const key = cacheKey(file);
+  const before = readsInProgress.get(key) ?? Promise.resolve();
+  const result = before.then(read);
+  const ended = result.then(
+    () => {},
+    () => {},
+  );
+  readsInProgress.set(key, ended);
+  void ended.then(() => {
+    if (readsInProgress.get(key) === ended) readsInProgress.delete(key);
+  });
+  return result;
+}
+
+/**
+ * Run `read`, a fresh import of `file`, in the file's turn (`readInTurn`),
+ * once the file is gone from Node's CommonJS cache. A new URL names a new ES
+ * module only, so a CommonJS module also needs its cache entry gone.
+ * @template T
+ * @param {string} file absolute path
+ * @param {() => Promise<T>} read
+ * @returns {Promise<T>}
+ */
+export function readFreshInTurn(file, read) {
+  return readInTurn(file, () => {
+    delete requireFromHere.cache[cacheKey(file)];
+    return read();
+  });
 }
 
 

package/foundation/render/charts.d.mts

@@ -0,0 +1,59 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * The size a ResponsiveContainer starts at: its own numbers where it has
+ * them. Otherwise the width follows the height: six times it for a
+ * sparkline, which sits in a narrow card or a table cell, and two and a half
+ * times it for a taller chart. The drawing then scales to the width the
+ * page gives it, so its text stays near its own size in most layouts.
+ * @param {{width?: unknown, height?: unknown, aspect?: unknown}} props
+ * @returns {{width: number, height: number}}
+ */
+export function chartSize({ width, height, aspect }: {
+    width?: unknown;
+    height?: unknown;
+    aspect?: unknown;
+}): {
+    width: number;
+    height: number;
+};
+/**
+ * Mark each container chart whose legend is vertical and on one side with
+ * that side, and whether it sits at the bottom or the middle, for
+ * {@link CHART_CSS}. A vertically centered legend has a `top` near the
+ * middle (no room is kept for it in a container chart). A vertical legend
+ * centered across takes its own row, as a horizontal one does.
+ * @param {any} root the element the charts were drawn in
+ */
+export function markLegends(root: any): void;
+/**
+ * Give this thread the small document a chart draws in: no layout, no
+ * motion, and no frames to wait for.
+ * @returns {Promise<void>}
+ */
+export function chartDocument(): Promise<void>;
+/**
+ * @file Charts in a rendered page. A recharts chart draws only after its
+ * effects run, and a ResponsiveContainer measures its parent in a browser, so
+ * a server render leaves them empty. The render worker draws each one again
+ * in a small document, at the size the container starts at, and puts the
+ * drawing in its place.
+ *
+ * @input The chart elements the server render set aside.
+ * @output Their markup, and the CSS that lets a drawn chart fit its width.
+ * @position foundation/render — read by page-worker.mjs and render-page.mjs.
+ */
+/** The global the render worker installs to set charts aside. SYNC: page-worker.mjs assigns it by this name. */
+export const CHART_GLOBAL: "__astryxRenderChart";
+/** The recharts exports that draw a chart, besides ResponsiveContainer. */
+export const CHART_ROOTS: Set<string>;
+/**
+ * A chart drawn at its starting size scales to the width the page gives it
+ * and keeps its shape, so it never overflows its card. Its legend stays out
+ * of the scaled picture, so its text never covers the chart however narrow
+ * the page is. A horizontal legend takes its own row under the picture, or
+ * above it when it asks for the top. A vertical legend on one side sits
+ * beside the picture, on that side.
+ */
+export const CHART_CSS: string;