@astryxdesign/cli 0.7.11 → 0.7.12-canary.ccb4a6d

package/assets/templates/pages/theme-showcase/template.doc.mjs

@@ -6,7 +6,8 @@ export const doc = {
   name: 'Theme Showcase',
   displayName: 'Theme Showcase',
   description:
-    'Several unrelated product surfaces rendered together on one canvas so a token change can be judged across contexts at once. A comparison harness rather than a layout to ship.',
+    'Multi-surface comparison shell: preview palettes, typography, icons and control states across a storefront, checkout, chat and inventory on one responsive canvas. A theme preview and design-system showcase, with an embeddable content view for an existing app shell.',
+  category: 'Shell - Top Nav',
   keywords: [
     'theme',
     'tokens',
@@ -16,10 +17,8 @@ export const doc = {
     'design system preview',
   ],
   isReady: true,
-  // Surfaced via the Themes page "Open in Playground" action, not the
-  // Templates gallery, so keep it out of the overview + playground menu.
-  // No `category` — it's hidden from the overview gallery (the only consumer
-  // of `category`), and 'Showcase' isn't part of the TemplateCategory taxonomy.
+  // The standalone entry demonstrates an application shell; the named preview
+  // composes into its host without nesting AppShell. Keep it out of the gallery.
   isHiddenFromOverview: true,
   icons: {
     Banknote: 'money',

package/authoring/doctypes/template/type.ts

@@ -186,6 +186,7 @@ export type TemplateCategory =
   | 'Content - Order Detail'
   | 'Content - Product Detail'
   | 'Content - Work Item Detail'
+  | 'Content - Course Detail'
   | 'Content - Product List'
   | 'Content - Documentation Catalog'
   | 'Content - Documentation Design'

package/clients/cli/commands/experimental/icon.mjs

@@ -20,6 +20,7 @@ import {
   getCliInvocation,
 } from '../../../../foundation/env/package-manager.mjs';
 import {jsonOut} from '../../../../foundation/response/json.mjs';
+import {logger} from '../../../../api/logger.mjs';
 import {resultSet} from '../../../../foundation/debug/index.mjs';
 import {
   emit,
@@ -140,7 +141,7 @@ export function registerExperimentalIcon(group, program) {
             ),
           ),
           text(
-            `Built-in definitions are the ones every set maps. Map one: ${run} experimental icon map <definition> <icon id>`,
+            `Built-in definitions are the ones every set maps. Map one: ${run} experimental icon map <definition> <icon id> --set <set>`,
           ),
         );
         return answered;
@@ -157,7 +158,9 @@ export function registerExperimentalIcon(group, program) {
                 `${each.id}: ${each.words.join(', ')}${each.definitions.length > 0 ? ` = ${each.definitions.join(', ')}` : ''}`,
             ),
           ),
-          text(`Map one: ${run} experimental icon map <definition> <id>`),
+          text(
+            `Map one: ${run} experimental icon map <definition> <id> --set ${set}`,
+          ),
         );
         return answered;
       }
@@ -308,6 +311,9 @@ export function registerExperimentalIcon(group, program) {
    * @param {(result: any) => void} print
    */
   const run = async (call, print) => {
+    // Reading a large library reports its progress through the shared
+    // logger: on stderr in text mode, never under --json.
+    logger.setSilent(Boolean(program.opts().json));
     let result;
     try {
       result = await call();
@@ -436,7 +442,7 @@ export function registerExperimentalIcon(group, program) {
             return;
           }
           if (result.type === 'icon.definitionMatches') {
-            const {matches, newDefinition} = result.data;
+            const {matches, newDefinition, variant} = result.data;
             emit(
               section(
                 `Icon definitions for ${result.data.export} (${matches.length})`,
@@ -466,6 +472,13 @@ export function registerExperimentalIcon(group, program) {
                     ),
                   ]
                 : []),
+              ...(variant
+                ? [
+                    text(
+                      `The set already has this glyph in another look. Add this one as its variant: ${formatCliCommand(variant)}`,
+                    ),
+                  ]
+                : []),
               text(
                 `All icon definitions: ${cli} docs cli/experimental/icon-definitions`,
               ),
@@ -500,17 +513,25 @@ export function registerExperimentalIcon(group, program) {
       const {root, manifest, files, written, dryRun} = data;
       const state = dryRun ? 'plan' : written ? 'ok' : 'unchanged';
       const refreshed = data.refreshed === true;
+      const updated = data.updated === true;
+      const What = `${what[0].toUpperCase()}${what.slice(1)}`;
       emit(
         section(
           refreshed
             ? dryRun
               ? `Refresh ${what} plan`
-              : `${what[0].toUpperCase()}${what.slice(1)} refreshed`
-            : dryRun
-              ? `New ${what} plan`
-              : written
-                ? `New ${what} added`
-                : `New ${what} unchanged`,
+              : `${What} refreshed`
+            : updated
+              ? dryRun
+                ? `${What} update plan`
+                : written && files.length > 0
+                  ? `${What} updated`
+                  : `${What} unchanged`
+              : dryRun
+                ? `New ${what} plan`
+                : written
+                  ? `New ${what} added`
+                  : `New ${what} unchanged`,
         ),
         text(`[${state}] ${data.name}`),
         // What the command did (or, in a dry run, would do): never a step
@@ -542,7 +563,7 @@ export function registerExperimentalIcon(group, program) {
               list(
                 data.suggestions.map(
                   each =>
-                    `${each.definition} -> ${each.icon} (${each.word}): ${formatCliCommand(`astryx experimental icon map ${each.definition} ${each.icon}`)}`,
+                    `${each.definition} -> ${each.icon} (${each.word}): ${formatCliCommand(`astryx experimental icon map ${each.definition} ${each.icon} --set ${data.name}`)}`,
                 ),
               ),
             ]

package/clients/cli/commands/experimental-icon-add.doc.mjs

@@ -30,7 +30,7 @@ export const doc = {
       flag: '--new-definition <name>',
       param: 'options.newDefinition',
       description:
-        "Add your set's own definition, then map the icon to it; needs --description and --words",
+        "Add your set's own definition, named in camelCase (aiHelper) or kebab-case (ai-helper), then map the icon to it; needs --description and --words",
     },
     {
       flag: '--description <text>',

package/clients/cli/commands/experimental-icon-new-definition.doc.mjs

@@ -18,7 +18,8 @@ export const doc = {
       name: 'name',
       param: 'name',
       required: true,
-      description: 'The definition name, in camelCase (rocketLaunch)',
+      description:
+        'The definition name, in camelCase (rocketLaunch) or kebab-case (rocket-launch)',
     },
   ],
   options: [

package/clients/cli/commands/experimental-icon-new-set.doc.mjs

@@ -11,7 +11,7 @@ export const doc = {
   stability: 'experimental',
   summary: 'Start an icon set in your integration package',
   description:
-    "Run inside an integration package. Writes the set's folder with its descriptor, its data file, and its generated module, and declares the manifest's `experimental.iconSets` root on first use. With --from it wraps every icon component of a library, records the library and its version as the set's source, copies its license notice, and maps each Astryx icon definition whose name is an icon's id; definitions an icon only shares a word with are listed as suggestions, never written. Run it again to refresh. --variants and --default-variant declare the set's variants. Experimental: it may change or be removed in a patch release.",
+    "Run inside an integration package. Writes the set's folder with its descriptor, its data file, and its generated module, and declares the manifest's `experimental.iconSets` root on first use. With --from it wraps every icon component of a library, records the library and its version as the set's source, copies its license notice, and maps each Astryx icon definition whose name is an icon's id; definitions an icon only shares a word with are listed as suggestions, never written. A library whose export names end in looks (XOutline24WGHT500Icon) gives one icon per glyph, by its glyph id (x), in the look the default variant names, else the library's usual default. Run it again with --from to refresh. --variants and --default-variant declare the set's variants; over an existing set without --from, they, --display-name and --description update the set in place and leave its icons as they are; a set with icons changes its default variant only with --from, and only in a library whose export names encode looks. Experimental: it may change or be removed in a patch release.",
   fn: 'iconNewSet',
   args: [
     {
@@ -49,7 +49,7 @@ export const doc = {
       flag: '--default-variant <variant>',
       param: 'options.defaultVariant',
       description:
-        "With --variants: the variant each icon's own export draws (the first variant when omitted)",
+        "With --variants: the variant each icon's own export draws. When omitted: in a library whose export names encode looks, the look the icons draw (the library's usual default for a new set), which --variants must list; otherwise the set's current default, which --variants must list when the set has icons, else, on a set without icons, the first variant. A set with icons changes it only with --from, and only in a library whose export names encode looks",
     },
     {
       flag: '--display-name <text>',

package/clients/cli/commands/swizzle.doc.mjs

@@ -16,8 +16,13 @@ export const doc = {
   summary: 'Copy component source for customization',
   description:
     "Ejects a component's source from the resolved @astryxdesign/core (or its owning " +
-    'integration) into your project for deep customization, rewriting imports that ' +
-    'escape the component directory. With no name it lists the swizzlable components. ' +
+    'integration) into your project for deep customization. Every import in the copy ' +
+    'names a file the copy holds or a path the package exports: names the package ' +
+    'exports come from the package, and every internal module the component needs ' +
+    "is copied beside it in the package's folder layout. " +
+    'Tests, stories and docs are not copied. It lists the npm packages the copy imports, ' +
+    'with the ranges the owner package declares, to install if your project lacks them. ' +
+    'With no name it lists the swizzlable components. ' +
     'An integration component that replaces a Core component is what that Core name ' +
     'copies; --package @astryxdesign/core copies the original. --list lists Core ' +
     'components, including one an integration replaces.',
@@ -46,7 +51,7 @@ export const doc = {
       flag: '-f, --overwrite',
       param: 'options.overwrite',
       description:
-        'Replace existing files. Without it, existing files fail the command with ERR_FILE_EXISTS and nothing is written',
+        "Replace the component's existing files. Without it, existing files fail the command with ERR_FILE_EXISTS and nothing is written. A helper an earlier swizzle wrote is reused when it is the same and is never replaced by a copy that carries it: a different one stays, and this copy writes its own under a version-suffixed name. Swizzling the component whose folder holds that helper counts it as one of that component's own files. A changed private attribute owner module, or a style module it imports, fails the command without --overwrite and is replaced with it",
     },
   ],
   examples: [

package/clients/cli/commands/swizzle.mjs

@@ -3,11 +3,10 @@
 /**
  * @file swizzle command — thin wrapper around api/swizzle.
  *
- * Copies a component's source into the consumer project for customization
- * (imports rewritten to the owner package's subpaths). All logic — owner
- * resolution, copy, import rewriting, StyleX detection, maintainer feedback —
- * lives in api/swizzle; this file only parses flags, prints, and prefixes
- * commands for the caller's package manager.
+ * Copies a component's source into the consumer project for customization,
+ * with the internal modules it needs. All logic — owner resolution, the copy,
+ * StyleX detection, maintainer feedback — lives in api/swizzle; this file only
+ * parses flags, prints, and prefixes commands for the caller's package manager.
  */
 
 import {jsonOut} from '../../../foundation/response/json.mjs';
@@ -85,18 +84,31 @@ export function registerSwizzle(program) {
         text(`[ok] Copied ${filesCopied} files to ${outputDir}/`),
         text(
           [
-            `Relative imports have been rewritten to use ${ownerPackage}.`,
+            `What ${ownerPackage} exports is imported from ${ownerPackage}; the internal modules the component needs are copied beside it.`,
             'You can now customize the component source freely.',
           ].join('\n'),
         ),
       ];
-      // Files the copy wrote outside the component folder: the owner modules
-      // and their unexported style modules (spec:AST-110 FR4).
+      // Files the copy wrote outside the component folder: the internal
+      // modules it needs, in the package's folder layout.
       const shared = (result.data.files ?? []).filter(f => f.startsWith('../'));
       if (shared.length > 0) {
         out.push(
           text(
-            `Shared modules: ${shared.join(', ')} (copied whole; their imports between each other stay relative)`,
+            `Copied beside it: ${shared.join(', ')} (in the package's folder layout; imported by relative path)`,
+          ),
+        );
+      }
+
+      // npm packages the copy imports, each range quoted so the list pastes
+      // safely after an install command.
+      const dependencies = Object.entries(result.data.dependencies ?? {});
+      if (dependencies.length > 0) {
+        out.push(
+          text(
+            `It imports these npm packages; install any your project lacks: ${dependencies
+              .map(([name, range]) => (range === '*' ? name : `${name}@"${range}"`))
+              .join(' ')}`,
           ),
         );
       }

package/foundation/discovery/component-loader.d.mts

@@ -43,5 +43,5 @@ export type LoadDocOptions = {
      * which root reads the doc
      * (default: components)
      */
-    root?: "hooks" | "components" | undefined;
+    root?: "components" | "hooks" | undefined;
 };

package/foundation/discovery/doc-types.mjs

@@ -27,7 +27,8 @@
  *   none), and a `<topic>.doc.<lang>.mjs` overlay against
  *   `ReferenceTranslationDoc`;
  * - themes root: `ThemeDoc`;
- * - iconSets root: `IconSetDoc`.
+ * - iconSets root: `IconSetDoc`, and a set's own definition (stamped
+ *   `type: 'icon-definition'`) `IconDefinitionDoc`.
  * Every finding is a warning, names the field, and says how to fix it.
  *
  * @input Doc files with the root each was found in, the package root, and the
@@ -312,7 +313,13 @@ function expectedType(ts, root, exportName, node, core = false) {
     return {typeExpr: authoring('ThemeDoc'), typeName: 'ThemeDoc'};
   }
   if (root === 'icon-sets') {
-    return {typeExpr: authoring('IconSetDoc'), typeName: 'IconSetDoc'};
+    // A set's own definitions live in its folder too.
+    return shape?.stamp === 'icon-definition'
+      ? {
+          typeExpr: authoring('IconDefinitionDoc'),
+          typeName: 'IconDefinitionDoc',
+        }
+      : {typeExpr: authoring('IconSetDoc'), typeName: 'IconSetDoc'};
   }
   if (translation) {
     return {

package/foundation/discovery/icon-ranking.d.mts

@@ -30,7 +30,9 @@ export function iconRecord(set: DiscoveredIconSet, icon: IconSetIcon, definition
  * @property {boolean} meaning the query is one of the icon's tags (never
  *   both: a tag is a word that is not the id or one of its parts)
  * @property {number} rank within-tier key, lower first: for a name match 0
- *   (whole id) or 1 (an id part); for a meaning match the tag's position
+ *   (whole id), 1 (the whole id's plural or singular), 2 (an id part), or 3
+ *   (an id part's plural or singular); for a meaning match the tag's
+ *   position
  * @property {string} reason
  */
 /**
@@ -41,6 +43,24 @@ export function iconRecord(set: DiscoveredIconSet, icon: IconSetIcon, definition
  * @returns {IconMatch | null}
  */
 export function matchIcon(query: string, icon: IconSetIcon, definitions?: string[]): IconMatch | null;
+/**
+ * The query without the words that only phrase it, when it has several
+ * words and some word names something; else the query as typed.
+ * @param {string} query
+ */
+export function iconQuery(query: string): string;
+/**
+ * The matches that answer a query: the whole-word ones (a definition or an
+ * exact match, 80 and up) when there are any, else word starts (60) when
+ * there are any, else partial matches. A longer word that only starts with
+ * the query (`start` for `star`) never stands beside a whole-word answer.
+ * @template {{score: number}} T
+ * @param {T[]} ranked best first
+ * @returns {T[]}
+ */
+export function answeringMatches<T extends {
+    score: number;
+}>(ranked: T[]): T[];
 /**
  * Which exact reading leads for a set of matches: meaning, unless more icons
  * carry the query as a name than as a tag.
@@ -78,7 +98,9 @@ export function withDefinitionWords(icon: IconSetIcon, definitions: string[], lo
     words: string[];
 } | undefined): IconSetIcon;
 /**
- * Every icon in `sets` that answers the query, ranked (FR6).
+ * Every icon in `sets` that answers the query, ranked. The query is
+ * scored as typed; when nothing answers it with a whole word (80 and up),
+ * it is scored again without its filler words ({@link iconQuery}).
  * @param {DiscoveredIconSet[]} sets in tie order
  * @param {string} query
  * @returns {IconMatchEntry[]}
@@ -106,7 +128,9 @@ export type IconMatch = {
     meaning: boolean;
     /**
      * within-tier key, lower first: for a name match 0
-     * (whole id) or 1 (an id part); for a meaning match the tag's position
+     * (whole id), 1 (the whole id's plural or singular), 2 (an id part), or 3
+     * (an id part's plural or singular); for a meaning match the tag's
+     * position
      */
     rank: number;
     reason: string;

package/foundation/discovery/icon-ranking.mjs

@@ -9,8 +9,18 @@
  *    90  an exact match in the reading the searched sets favor (below)
  *    80  an exact match in the other reading
  *    60  one of its words starts with the query
- *    40  a partial match: the id or a word contains the query, or every
- *        word of the query starts one of the icon's words or id parts
+ *    40  a partial match: the id or a word contains the query (three
+ *        letters or more), or every word of the query starts one of the
+ *        icon's words or id parts
+ *
+ * A word matches a whole word: a word's plural or singular (`stars` for
+ * `star`) is an exact match, while a longer word that only starts with it
+ * (`start`) is a word-start match, and {@link answeringMatches} keeps
+ * word-start and partial matches only when nothing matches a whole word.
+ * A query is scored as typed first. Only when nothing answers it with a
+ * whole word are the words that only phrase it (`go`, `the`, `icon`) left
+ * out of a query of several words, so `go home` asks for `home` while
+ * `arrow up to line` still names `arrow-up-to-line`.
  *
  * An exact match is a NAME match when the query is the icon's id, or one of
  * its words that is also a part of its id (`trash` for `trash-2`); it is a
@@ -26,7 +36,8 @@
  *
  * Equal scores keep the set order first (the project's set, then load
  * order), so the project's set always leads at a score. Within one set, a
- * name match on the whole id comes before one on a part of it, and a meaning
+ * name match on the whole id (or its plural or singular) comes before one on
+ * a part of it, and a meaning
  * match whose query sits earlier among the icon's tags comes first (sets list
  * an icon's most telling tags first). Remaining ties keep id order, so the
  * same installation always answers the same way.
@@ -93,7 +104,9 @@ const squash = value => value.toLowerCase().replace(/[\s_-]+/g, '');
  * @property {boolean} meaning the query is one of the icon's tags (never
  *   both: a tag is a word that is not the id or one of its parts)
  * @property {number} rank within-tier key, lower first: for a name match 0
- *   (whole id) or 1 (an id part); for a meaning match the tag's position
+ *   (whole id), 1 (the whole id's plural or singular), 2 (an id part), or 3
+ *   (an id part's plural or singular); for a meaning match the tag's
+ *   position
  * @property {string} reason
  */
 
@@ -127,10 +140,27 @@ export function matchIcon(query, icon, definitions = []) {
       tier: 'exact',
       name: wholeId || partWord,
       meaning: !wholeId && !partWord,
-      rank: wholeId ? 0 : partWord ? 1 : tagAt,
+      rank: wholeId ? 0 : partWord ? 2 : tagAt,
       reason: wholeId ? `id "${icon.id}"` : `word "${query}"`,
     };
   }
+  const plural = icon.words.find(word => sameWord(word, query));
+  if (plural) {
+    const named = parts.has(plural);
+    return {
+      tier: 'exact',
+      name: named,
+      meaning: !named,
+      // The whole id's plural or singular right after the whole id, then
+      // after the word itself, wherever it sits.
+      rank: named
+        ? plural === icon.id
+          ? 1
+          : 3
+        : tags.length + tags.indexOf(plural),
+      reason: `word "${plural}"`,
+    };
+  }
   const prefix = icon.words.find(word => word.startsWith(query));
   if (prefix) {
     return {
@@ -141,7 +171,11 @@ export function matchIcon(query, icon, definitions = []) {
       reason: `word "${prefix}" starts with "${query}"`,
     };
   }
-  const contains = [icon.id, ...icon.words].find(text => text.includes(query));
+  // A letter or two inside a word (`x` in `box`) says nothing about it.
+  const contains =
+    query.replace(/\s+/gu, '').length >= 3
+      ? [icon.id, ...icon.words].find(text => text.includes(query))
+      : undefined;
   if (contains) {
     return {
       tier: 'partial',
@@ -170,6 +204,72 @@ export function matchIcon(query, icon, definitions = []) {
   return null;
 }
 
+/**
+ * Whether two words are one word's singular and plural (`star`, `stars`;
+ * `box`, `boxes`), never the same word.
+ * @param {string} a
+ * @param {string} b
+ */
+function sameWord(a, b) {
+  if (a === b || /\s/u.test(a) || /\s/u.test(b)) return false;
+  const [short, long] = a.length < b.length ? [a, b] : [b, a];
+  return short.length >= 2 && (long === `${short}s` || long === `${short}es`);
+}
+
+/**
+ * Words that phrase a query without naming anything: left out of a query of
+ * several words that nothing answers as typed (`go home` asks for `home`).
+ */
+const FILLER_WORDS = new Set([
+  'a',
+  'an',
+  'the',
+  'go',
+  'to',
+  'my',
+  'of',
+  'for',
+  'icon',
+  'icons',
+]);
+
+/**
+ * A query as typed: trimmed and lower-case, one space between words.
+ * @param {string} query
+ */
+function typedQuery(query) {
+  return query.trim().toLowerCase().split(/\s+/u).filter(Boolean).join(' ');
+}
+
+/**
+ * The query without the words that only phrase it, when it has several
+ * words and some word names something; else the query as typed.
+ * @param {string} query
+ */
+export function iconQuery(query) {
+  const words = typedQuery(query).split(' ').filter(Boolean);
+  const named = words.filter(word => !FILLER_WORDS.has(word));
+  return (words.length > 1 && named.length > 0 ? named : words).join(' ');
+}
+
+/**
+ * The matches that answer a query: the whole-word ones (a definition or an
+ * exact match, 80 and up) when there are any, else word starts (60) when
+ * there are any, else partial matches. A longer word that only starts with
+ * the query (`start` for `star`) never stands beside a whole-word answer.
+ * @template {{score: number}} T
+ * @param {T[]} ranked best first
+ * @returns {T[]}
+ */
+export function answeringMatches(ranked) {
+  for (const floor of [80, 60]) {
+    if (ranked.some(each => each.score >= floor)) {
+      return ranked.filter(each => each.score >= floor);
+    }
+  }
+  return ranked;
+}
+
 /**
  * The score of one match, given which exact reading leads.
  * @param {IconMatch} match
@@ -249,13 +349,30 @@ export function withDefinitionWords(icon, definitions, lookup) {
 }
 
 /**
- * Every icon in `sets` that answers the query, ranked (FR6).
+ * Every icon in `sets` that answers the query, ranked. The query is
+ * scored as typed; when nothing answers it with a whole word (80 and up),
+ * it is scored again without its filler words ({@link iconQuery}).
  * @param {DiscoveredIconSet[]} sets in tie order
  * @param {string} query
  * @returns {IconMatchEntry[]}
  */
 export function rankIcons(sets, query) {
-  const term = query.trim().toLowerCase();
+  const typed = typedQuery(query);
+  const asTyped = rankTerm(sets, typed);
+  if (asTyped.some(each => each.score >= 80)) return asTyped;
+  const named = iconQuery(query);
+  if (named === typed) return asTyped;
+  const withoutFiller = rankTerm(sets, named);
+  return withoutFiller.length > 0 ? withoutFiller : asTyped;
+}
+
+/**
+ * {@link rankIcons} for one normalized query.
+ * @param {DiscoveredIconSet[]} sets
+ * @param {string} term
+ * @returns {IconMatchEntry[]}
+ */
+function rankTerm(sets, term) {
   const astryx = astryxDefinitionsByName();
   /** @type {Array<{set: DiscoveredIconSet, icon: IconSetIcon, definitions: string[], match: IconMatch, setIndex: number}>} */
   const hits = [];