@astryxdesign/cli 0.7.12 → 0.7.13-canary.a5ad1f2

package/foundation/discovery/template-icons.d.mts

@@ -1,6 +1,46 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
+/**
+ * The placeholder component the CLI declares once in a copied file. It sizes
+ * like an icon (1em, in the current text color). It is hidden from assistive
+ * technology unless a use gives it a label.
+ * @param {string} name
+ */
+export function placeholderDeclaration(name: string): string;
+/**
+ * The comment beside each use of the placeholder, so `astryx doctor` can name
+ * the meaning it stands for.
+ * @param {string[]} definitions
+ */
+export function placeholderNote(definitions: string[]): string;
+/**
+ * Read the meanings back from a placeholder use's comment. Null for a
+ * comment that is not one.
+ * @param {string} comment the comment's text, with or without its markers
+ * @returns {string[] | null}
+ */
+export function placeholderMeanings(comment: string): string[] | null;
+/**
+ * Each use of the placeholder component in a file: the name it is declared
+ * under and the meanings its comment names (null when it names none). Only
+ * the declaration the CLI writes counts, and only code: commented-out code
+ * and text in strings are never uses. A closing JSX tag is part of its
+ * element's use. Null when the source does not parse.
+ * @param {string} source
+ * @returns {Array<{local: string, meanings: string[] | null}> | null}
+ */
+export function placeholderUses(source: string): Array<{
+    local: string;
+    meanings: string[] | null;
+}> | null;
+/**
+ * The commands that give a placeholder icon a real one.
+ * @param {string[]} definitions
+ * @param {string} main the main set's name as the list writes it
+ * @returns {string[]}
+ */
+export function placeholderFixes(definitions: string[], main: string): string[];
 /**
  * The target-set icon whose reviewed `matches` name the source icon with one
  * of `confidences`, ties broken by the order the confidences are given and
@@ -33,6 +73,55 @@ export function matchIcon(source: SourceIcon, target: DiscoveredIconSet): {
  * @returns {string[] | null}
  */
 export function iconsNotImported(source: string, declared: Record<string, string>): string[] | null;
+/**
+ * The value imports a template takes from other packages, as the keys its
+ * `icons` uses: a named import by the name it imports, a default import by
+ * its local name. Astryx's own packages, relative files, namespace imports,
+ * and type-only imports are left out. `renderer` marks a generic renderer:
+ * the key is `Icon`, or every JSX use passes an icon-choosing prop. `icon`
+ * marks an import the template uses as an icon: it renders it as a childless
+ * element or passes it as a value. Null when the source does not parse.
+ * @param {string} source
+ * @returns {Array<{key: string, module: string, renderer: boolean, icon: boolean}> | null}
+ */
+export function packageImports(source: string): Array<{
+    key: string;
+    module: string;
+    renderer: boolean;
+    icon: boolean;
+}> | null;
+/**
+ * The icons each template imports but does not declare in its `icons`. An
+ * import is undeclared when it comes from a module that some template
+ * declares an icon from (an icon library) and the template uses it as an
+ * icon: it renders it as a childless element or passes it as a value. Any
+ * other import from that module, such as a type, a factory it calls, or a
+ * provider with children, is listed as not checked (`use`): declaring it
+ * would make a template swap it for an icon. The check also cannot tell that
+ * an import draws one icon definition when it is a generic renderer, or when
+ * it comes from any other package and only its key ends in `Icon`, so it
+ * lists those as not checked (`architecture:cli-surface` DEC-7). Only
+ * templates that parse are read.
+ * @param {Array<{id: string, source: string, declared: Record<string, string>}>} templates
+ * @returns {{undeclared: Array<{id: string, key: string, module: string}>, unchecked: Array<{id: string, key: string, module: string, why: 'renderer' | 'use' | 'name'}>}}
+ */
+export function undeclaredTemplateIcons(templates: Array<{
+    id: string;
+    source: string;
+    declared: Record<string, string>;
+}>): {
+    undeclared: Array<{
+        id: string;
+        key: string;
+        module: string;
+    }>;
+    unchecked: Array<{
+        id: string;
+        key: string;
+        module: string;
+        why: "renderer" | "use" | "name";
+    }>;
+};
 /**
  * Rewrite a template's icon imports to the project's icon set (FR9, FR10).
  * @param {string} source
@@ -52,6 +141,88 @@ export function mapTemplateIcons(source: string, { sets, choice }: {
     source: string;
     icons: TemplateIconsReport | undefined;
 };
+/** @typedef {import('./icon-set-discovery.mjs').DiscoveredIconSet} DiscoveredIconSet */
+/** @typedef {import('./icon-set-discovery.mjs').IconSetChoice} IconSetChoice */
+/** @typedef {import('../../authoring/doctypes/icon-set/type').IconSetIcon} IconSetIcon */
+/**
+ * A source icon: what an imported icon means.
+ * @typedef {object} SourceIcon
+ * @property {string | null} setName the installed set it comes from, as a
+ *   reviewed match names it; null for an icon only the template declares
+ * @property {string} export the export the template imports
+ * @property {string} [variant] which of its set's declared variants the
+ *   export draws, as a reviewed match names it
+ * @property {string} id
+ * @property {string[]} definitions the Astryx definitions it draws
+ * @property {DiscoveredIconSet} [set] the set it came from, when installed
+ */
+/**
+ * One mapped icon.
+ * @typedef {object} MappedIcon
+ * @property {{module: string, export: string}} source
+ * @property {{set: string, package: string, id: string, module: string, export: string}} target
+ * @property {string[]} [dropped] the library's sizing props (`size`,
+ *   `strokeWidth`, `absoluteStrokeWidth`) removed from its elements: an icon
+ *   set's icons take their size from CSS
+ * @property {'match' | 'definition'} by `match`: a reviewed
+ *   `exact` or `strong` match in the project set's data names the source
+ *   icon; `definition`: the target's `map` names it for the Astryx icon
+ *   definition the source draws
+ * @property {{asked: string, used: string | null}} [variant] present when the
+ *   source draws a look the target set's icon does not have: the look it
+ *   asked for, and the look used (the set's default look)
+ */
+/**
+ * One icon no set in the project's list has: each of its uses in the copied
+ * code renders the placeholder component that the file declares.
+ * @typedef {object} PlaceholderIcon
+ * @property {{module: string, export: string}} source
+ * @property {{local: string}} target the name of the placeholder component
+ *   in the file
+ * @property {string[]} definitions the icon definitions the icon draws
+ * @property {string[]} fixes the commands that give it a real icon: map the
+ *   definition in the main set, or add a backup set that has it
+ * @property {string[]} [dropped] the library's sizing props removed from its
+ *   elements, as for a mapped icon
+ * @property {{set: string, id: string, module: string, export: string, confidence: 'likely'}} [suggestion]
+ *   a `likely` reviewed match in the main set, suggested and never applied
+ */
+/**
+ * One set a template's mapped icons come from.
+ * @typedef {object} UsedIconSet
+ * @property {string} set `<package>/<set>`
+ * @property {string} license
+ * @property {number} icons how many mapped icons it gives
+ */
+/**
+ * One icon kept as the template wrote it.
+ * @typedef {object} KeptIcon
+ * @property {string | null} module the module it is imported or re-exported
+ *   from; null when the template does not import it
+ * @property {string} export the name it is imported by: `default` for a
+ *   default import, `*` for a namespace import
+ * @property {string} reason
+ * @property {{set: string, id: string, module: string, export: string, confidence: 'likely'}} [suggestion]
+ *   a `likely` reviewed match, suggested and never applied
+ */
+/**
+ * What template icon mapping did.
+ * @typedef {object} TemplateIconsReport
+ * @property {'selected' | 'none' | 'ambiguous' | 'missing' | 'withdrawn'} status the
+ *   project's icon-set state; only `selected` maps anything
+ * @property {string | null} set the project set as `<package>/<set>`
+ * @property {string[]} [order] the main set and each backup, as
+ *   `<package>/<set>`, in the order icons are looked up; present when the
+ *   project lists backups
+ * @property {string} reason
+ * @property {MappedIcon[]} mapped
+ * @property {PlaceholderIcon[]} placeholder
+ * @property {KeptIcon[]} kept
+ * @property {UsedIconSet[]} sets each set the mapped icons come from, with
+ *   its license
+ */
+/** The name of the placeholder component, when the file does not use it. */
+export const PLACEHOLDER_NAME: "MissingIcon";
 /** What a template reads with no icon-set state given: nothing is mapped. */
 export const NO_ICON_SETS: Readonly<{
     sets: never[];
@@ -116,6 +287,70 @@ export type MappedIcon = {
      * definition the source draws
      */
     by: "match" | "definition";
+    /**
+     * present when the
+     * source draws a look the target set's icon does not have: the look it
+     * asked for, and the look used (the set's default look)
+     */
+    variant?: {
+        asked: string;
+        used: string | null;
+    } | undefined;
+};
+/**
+ * One icon no set in the project's list has: each of its uses in the copied
+ * code renders the placeholder component that the file declares.
+ */
+export type PlaceholderIcon = {
+    source: {
+        module: string;
+        export: string;
+    };
+    /**
+     * the name of the placeholder component
+     * in the file
+     */
+    target: {
+        local: string;
+    };
+    /**
+     * the icon definitions the icon draws
+     */
+    definitions: string[];
+    /**
+     * the commands that give it a real icon: map the
+     * definition in the main set, or add a backup set that has it
+     */
+    fixes: string[];
+    /**
+     * the library's sizing props removed from its
+     * elements, as for a mapped icon
+     */
+    dropped?: string[] | undefined;
+    /**
+     * a `likely` reviewed match in the main set, suggested and never applied
+     */
+    suggestion?: {
+        set: string;
+        id: string;
+        module: string;
+        export: string;
+        confidence: "likely";
+    } | undefined;
+};
+/**
+ * One set a template's mapped icons come from.
+ */
+export type UsedIconSet = {
+    /**
+     * `<package>/<set>`
+     */
+    set: string;
+    license: string;
+    /**
+     * how many mapped icons it gives
+     */
+    icons: number;
 };
 /**
  * One icon kept as the template wrote it.
@@ -156,7 +391,19 @@ export type TemplateIconsReport = {
      * the project set as `<package>/<set>`
      */
     set: string | null;
+    /**
+     * the main set and each backup, as
+     * `<package>/<set>`, in the order icons are looked up; present when the
+     * project lists backups
+     */
+    order?: string[] | undefined;
     reason: string;
     mapped: MappedIcon[];
+    placeholder: PlaceholderIcon[];
     kept: KeptIcon[];
+    /**
+     * each set the mapped icons come from, with
+     * its license
+     */
+    sets: UsedIconSet[];
 };