@astryxdesign/cli 0.7.12-canary.ed58688 → 0.7.12-canary.f124c2f

package/api/component/__fixtures__/resolutions/modules.txt

@@ -282,7 +282,7 @@ useOverlay useOverlay Overlay/useOverlay.doc.mjs Overlay/useOverlay.tsx
 useOwnScrollGesture useOwnScrollGesture DateInput/DateInput.doc.mjs DateInput/useOwnScrollGesture.ts
 usePager usePager hooks/useAnimatedLayout.doc.mjs hooks/usePager.ts
 usePointerDragScroll usePointerDragScroll DateInput/DateInput.doc.mjs DateInput/usePointerDragScroll.ts
-usePowerSearchConfig usePowerSearchConfig PowerSearch/PowerSearch.doc.mjs PowerSearch/usePowerSearchConfig.ts
+usePowerSearchConfig usePowerSearchConfig PowerSearch/usePowerSearchConfig.doc.mjs PowerSearch/usePowerSearchConfig.ts
 usePowerSearchSource usePowerSearchSource PowerSearch/PowerSearch.doc.mjs PowerSearch/usePowerSearchSource.ts
 useRenamedProp useRenamedProp hooks/useAnimatedLayout.doc.mjs hooks/useRenamedProp.ts
 useResolvedRequired useResolvedRequired hooks/useAnimatedLayout.doc.mjs hooks/useResolvedRequired.ts

package/assets/discover/official-packages.json

@@ -100,6 +100,10 @@
           "kind": "component",
           "name": "ChatUnreadDivider"
         },
+        {
+          "kind": "component",
+          "name": "ChatVirtualizer"
+        },
         {
           "kind": "component",
           "name": "CircleCheckIndicator"

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/tailwind.doc.mjs

@@ -19,6 +19,8 @@ export const docs = {
     'tailwind-theme.css',
     'utility classes',
     'preflight',
+    'existing Tailwind app',
+    'cascade layer order',
   ],
 
   sections: [
@@ -69,7 +71,45 @@ import {themes, defaultThemeSlug} from './astryx-themes';`,
         },
         {
           type: 'prose',
-          text: 'The Tailwind bridge is the concrete example of the general interop pattern: expose another library\'s semantic API, but point the values at system token variables.',
+          text: "The Tailwind bridge is the concrete example of the general interop pattern: expose another library's semantic API, but point the values at system token variables.",
+        },
+      ],
+    },
+    {
+      title: 'Add Astryx to an app that already uses Tailwind',
+      content: [
+        {
+          type: 'prose',
+          text: 'The recipe in the Tailwind section is a whole `globals.css` for a new app. An app that already uses Tailwind keeps its own file: its `@import "tailwindcss"`, its `@theme` mapping, and its `:root` variables stay as they are. Add one `@layer` line above the Tailwind import and the Astryx stylesheets below it.',
+        },
+        {
+          type: 'code',
+          lang: 'css',
+          label: 'globals.css (existing Tailwind app)',
+          code: `@layer reset, theme, base, astryx-base, astryx-theme, components, utilities;
+
+@import "tailwindcss"; /* the app's own entry, unchanged */
+@import "@astryxdesign/core/reset.css";
+@import "@astryxdesign/core/astryx.css";
+@import "@astryxdesign/theme-neutral/theme.css";
+
+/* The app's own @theme and :root rules stay below, unchanged. */`,
+        },
+        {
+          type: 'prose',
+          text: "This recipe leaves out `tailwind-theme.css`. The bridge maps Tailwind theme names to system tokens, including Tailwind's own defaults such as `rounded-lg` and `shadow-md`, so in an existing app it changes what the app's own classes paint. Add it only when the app does not use the names it maps.",
+        },
+        {
+          type: 'prose',
+          text: "Astryx's theme defines its own CSS custom properties (color, spacing, radius, shadow, font, motion and more), and {@link namespace:tokens} has the full list. An app token with one of those names collides in one of two ways. An app `@theme` key takes Astryx's value, because `astryx.css` sets the tokens on `:root` above Tailwind's `theme` layer: with `@theme { --spacing-4: 1.5rem }`, the app's `gap-4` stays 16px. Marking the block `@theme inline` keeps the app's value in its utilities. An app `:root` variable replaces Astryx's value, so Astryx's own components change: `:root { --spacing-4: 1.5rem }` widens Astryx's spacing step 4 from 16px to 24px. Where the root Theme component sets a token again, such as `--color-warning`, the app's own rules inside it read Astryx's value instead. Rename any app token that shares a name.",
+        },
+        {
+          type: 'prose',
+          text: "Put the `@layer` line above the app's `@import \"tailwindcss\"`, never below it. A `@layer` statement orders only the layer names the page has not seen yet, and the Tailwind import names `theme`, `base`, `components`, and `utilities` as it loads. Below that import, the statement can only add `reset`, `astryx-base`, and `astryx-theme` after Tailwind's `utilities`. That inverts the cascade: the Astryx reset then outranks every utility class in the app, and, for example, removes the borders and padding the app's utilities give its controls. Nothing reports it: the build and the browser console stay clean, and the `@layer` line still looks right in the source, so only the rendered page shows the problem.",
+        },
+        {
+          type: 'prose',
+          text: 'The load-order rule from the Tailwind section still applies: `globals.css` must be the first stylesheet the page loads, so its `@layer` line names the layers first.',
         },
       ],
     },

package/assets/templates/blocks/components/PowerSearch/usePowerSearchConfigHookUsage.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'usePowerSearchConfig',
+  name: 'usePowerSearchConfig — Filtered Directory Table',
+  displayName: 'usePowerSearchConfig — Filtered Directory Table',
+  description:
+    'A people directory with a PowerSearch bar over a Table: typed field definitions feed usePowerSearchConfig, returning the search config and an applyFilters helper that updates Table rows.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['PowerSearch', 'Table', 'Layout'],
+};

package/assets/templates/blocks/components/PowerSearch/usePowerSearchConfigHookUsage.tsx

@@ -0,0 +1,83 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {VStack} from '@astryxdesign/core/Layout';
+import {
+  PowerSearch,
+  usePowerSearchConfig,
+} from '@astryxdesign/core/PowerSearch';
+import type {PowerSearchFilter} from '@astryxdesign/core/PowerSearch';
+import {Table} from '@astryxdesign/core/Table';
+import type {TableColumn} from '@astryxdesign/core/Table';
+
+const statusValues = [
+  {value: 'active', label: 'Active'},
+  {value: 'on-leave', label: 'On Leave'},
+  {value: 'contractor', label: 'Contractor'},
+];
+
+const fieldDefs = [
+  {key: 'name', type: 'string', label: 'Name'},
+  {key: 'status', type: 'enum', label: 'Status', enumValues: statusValues},
+  {key: 'startDate', type: 'date', label: 'Start date'},
+] as const;
+
+interface Person extends Record<string, unknown> {
+  id: string;
+  name: string;
+  status: string;
+  startDate: number;
+}
+
+const people: Person[] = [
+  {id: '1', name: 'Alice Chen', status: 'active', startDate: 1672531200},
+  {id: '2', name: 'Bob Dylan', status: 'on-leave', startDate: 1680307200},
+  {id: '3', name: 'Charlie Kim', status: 'active', startDate: 1688169600},
+  {id: '4', name: 'Dana Scully', status: 'contractor', startDate: 1696118400},
+  {id: '5', name: 'Evan Wright', status: 'active', startDate: 1704067200},
+];
+
+const columns: TableColumn<Person>[] = [
+  {key: 'name', header: 'Name'},
+  {
+    key: 'status',
+    header: 'Status',
+    renderCell: (person: Person) =>
+      statusValues.find(s => s.value === person.status)?.label ?? person.status,
+  },
+  {
+    key: 'startDate',
+    header: 'Start Date',
+    renderCell: (person: Person) =>
+      new Date(person.startDate * 1000).toLocaleDateString('en-US', {
+        timeZone: 'UTC',
+        year: 'numeric',
+        month: 'short',
+        day: 'numeric',
+      }),
+  },
+];
+
+export default function UsePowerSearchConfigHookUsage() {
+  const [filters, setFilters] = useState<PowerSearchFilter[]>([]);
+  const {config, applyFilters} = usePowerSearchConfig(
+    fieldDefs,
+    'PeopleDirectory',
+  );
+  const filteredPeople = applyFilters(filters, people);
+
+  return (
+    <VStack gap={4}>
+      <PowerSearch
+        config={config}
+        filters={filters}
+        onChange={newFilters => setFilters([...newFilters])}
+        placeholder="Filter directory by name, status, start date..."
+        resultCount={filteredPeople.length}
+      />
+      <Table data={filteredPeople} columns={columns} idKey="id" hasHover />
+    </VStack>
+  );
+}

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/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

@@ -25,7 +25,11 @@
 import {pathToFileURL} from 'node:url';
 import {createJiti} from 'jiti';
 import {importUrl} from '../fs/import-url.mjs';
-import {importUserModule} from '../fs/module-loader.mjs';
+import {
+  importUserModule,
+  readFreshInTurn,
+  readInTurn,
+} from '../fs/module-loader.mjs';
 import {fileStamp, recordContentRead} from '../fs/read-record.mjs';
 
 /** @type {ReturnType<typeof createJiti> | undefined} */
@@ -79,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.
@@ -106,28 +132,35 @@ export function importTemplateModule(file) {
         jsxJiti ??= createJiti(import.meta.url, {jsx: true});
         return jsxJiti.import(first);
       }
-      return importUrl(`file://${first}`);
+      return importInTurn(first, `file://${first}`);
     },
     changed =>
       changed.endsWith('.ts')
         ? createJiti(import.meta.url, {jsx: true, moduleCache: false}).import(
             changed,
           )
-        : importUrl(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 => importUrl(pathToFileURL(first).href),
-    changed => importUrl(freshUrl(changed)),
+    first => importInTurn(first, pathToFileURL(first).href),
+    changed => importFresh(changed),
   );
 }

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

@@ -40,6 +40,16 @@ export function importThemeArtifact(specifier: string, cwd: string): Promise<Rec
  * @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

@@ -236,10 +236,7 @@ async function importModule(file, fresh) {
   // "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 readInTurn(file, () => {
-    delete requireFromHere.cache[cacheKey(file)];
-    return import(url.href);
-  });
+  return await readFreshInTurn(file, () => import(url.href));
 }
 
 /**
@@ -287,6 +284,22 @@ export function readInTurn(file, read) {
   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();
+  });
+}
+
 
 /**
  * Import a user-authored module, take its default export, and validate it

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.7.12-canary.ed58688",
+  "version": "0.7.12-canary.f124c2f",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -125,7 +125,7 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/core": "0.7.12-canary.ed58688"
+    "@astryxdesign/core": "0.7.12-canary.f124c2f"
   },
   "peerDependenciesMeta": {
     "@astryxdesign/core": {
@@ -133,10 +133,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.7.12-canary.ed58688",
-    "@astryxdesign/core": "0.7.12-canary.ed58688",
-    "@astryxdesign/lab": "0.7.12-canary.ed58688",
-    "@astryxdesign/theme-neutral": "0.7.12-canary.ed58688",
+    "@astryxdesign/charts": "0.7.12-canary.f124c2f",
+    "@astryxdesign/core": "0.7.12-canary.f124c2f",
+    "@astryxdesign/lab": "0.7.12-canary.f124c2f",
+    "@astryxdesign/theme-neutral": "0.7.12-canary.f124c2f",
     "@heroicons/react": "^2.2.0",
     "@stylexjs/stylex": "^0.19.0",
     "@types/babel__core": "^7.20.5",