An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
* @file `icon.add` and `icon.definitionMatches` leaf (AST-084 FR13): register
* one icon the caller chose from a source module, against an icon
* definition.
*
* The caller (usually an agent that knows the library) picks the export; the
* CLI never searches the source library. It proves the export is a runtime
* component of the source module, read statically, and then:
* - with no definition flag, answers the definitions that fit the export
* (`icon.definitionMatches`), Astryx's and the set's own, ranked by the
* icon lookup's scorer, and writes nothing;
* - with `definition`, adds the icon (or a variant of an existing icon)
* and maps the definition to it. The icon becomes an export of the set's
* generated icons module (`generated`): a re-export of a component, or,
* for anything else, the set's `adapter` applied to it. The data file
* names the set's own module, so every reader gets a component;
* - with `newDefinition`, writes the set's own definition file first.
* Running it again with the same arguments changes nothing.
*
* @output the `icon.add` or `icon.definitionMatches` envelope
* @position api/icon/add — dispatched by the `experimental icon add` command
*/
import * as path from 'node:path';
import {AstryxError} from '../../error.mjs';
import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
import {
assertIconExport,
astryxIconDefinitions,
authoring,
checkNewDefinition,
definitionNameFromInput,
closestNames,
findLocalIconSet,
iconIdOf,
mappableDefinitions,
exportValueKind,
generatedModulePath,
generatedNamesOf,
generatedOrigins,
iconModulePackage,
localSourceNote,
definitionNameOf,
libraryIcons,
moduleNaming,
iconNamingWithoutLook,
iconNaming,
iconExportName,
sameIconModule,
splitLook,
variantExportName,
answeringMatches,
checkVariantLook,
drawnLooks,
rankIcons,
resolveIconSource,
setModuleNote,
writeGeneratedIcons,
THEME_MAP_NAME,
writeDefinitionFile,
writeIconSetData,
refuseOutsideProject,
} from '../_adapter.mjs';
import {passed, refuseIgnoredPairs} from '../_options.mjs';
import {logger} from '../../logger.mjs';
import {shellArg} from '../../../foundation/text/shell-arg.mjs';
/** The lowest score a definition match needs: an exact word or name. */
const FIT_FLOOR = 80;
/** How many definition matches the answer lists. */
const MATCH_LIMIT = 10;
/**
* Register one icon in the set being authored, or list the definitions that
* fit it.
* Experimental (spec:AST-017 FR27): may change or be removed in a patch
* release.
* @experimental
* @param {string | undefined} exportName the export the set exposes the icon as; absent with `all`
* @param {import('../icon.type.mjs').IconAddOptions} options
* @returns {Promise<import('../icon.type.mjs').IconAddResponse | import('../icon.type.mjs').IconDefinitionMatchesResponse | import('../icon.type.mjs').IconAddVariantsResponse>}
*/
export async function iconAdd(exportName, options) {
const {
cwd = process.cwd(),
from,
set: selector,
definition: givenDefinition,
newDefinition: givenNewDefinition,
description,
words,
useDefault = false,
variant,
id: givenId,
all = false,
} = options ?? {};
refuseOutsideProject(cwd, 'experimental icon add', 'the icon-set package');
// The docs' kebab-case (`ai-helper`) names the same new definition.
const newDefinition =
givenNewDefinition == null
? undefined
: definitionNameFromInput(givenNewDefinition);
// `--all` adds a declared variant to existing icons, so it names no icon
// and maps nothing; a description and words describe only a new
// definition (spec:AST-042 FR5).
refuseIgnoredPairs(
{
'an export name': passed(exportName),
'--definition': passed(givenDefinition),
'--new-definition': passed(newDefinition),
'--description': passed(description),
'--words': passed(words),
'--default': passed(useDefault),
'--id': passed(givenId),
'--all': passed(all),
},
[
['--all', 'an export name'],
['--all', '--definition'],
['--all', '--new-definition'],
['--all', '--description'],
['--all', '--words'],
['--all', '--default'],
['--all', '--id'],
['--definition', '--new-definition'],
['--definition', '--description'],
['--definition', '--words'],
],
);
for (const [flag, value] of /** @type {const} */ ([
['--description', description],
['--words', words],
])) {
if (passed(value) && !passed(newDefinition)) {
throw new AstryxError(
`${flag} describes a new definition, so it needs --new-definition`,
[
{
name: `--new-definition <name> --description '<what it is for>' --words a,b`,
reason: 'add your own definition',
},
],
ERROR_CODES.ERR_INVALID_OPTION,
);
}
}
// An export name cannot start with a digit, and an id the author gives has
// no library prefix to keep.
if (givenId != null && /^[0-9]/u.test(givenId)) {
throw new AstryxError(
`The icon id "${givenId}" starts with a digit, and an export name cannot. Pass --id with an id that starts with a letter.`,
undefined,
ERROR_CODES.ERR_INVALID_ARGUMENT,
);
}
if (all) {
return authoring(() => addVariantForAll({cwd, from, selector, variant}));
}
return authoring(async () => {
if (
typeof exportName !== 'string' ||
!/^[$A-Z_a-z][$\w]*$/u.test(exportName)
) {
throw new AstryxError(
`Name the icon's export, such as TrashIcon; received "${String(exportName)}".`,
undefined,
ERROR_CODES.ERR_INVALID_ARGUMENT,
);
}
if (typeof from !== 'string' || from.trim() === '') {
throw new AstryxError(
'Pass --from with the module the icon is exported from: a package, a package subpath, or a relative path in this package.',
undefined,
ERROR_CODES.ERR_MISSING_ARGUMENT,
);
}
const where = await findLocalIconSet(cwd, selector);
const {packageDir, set} = where;
// The docs' kebab id (`eye-slash`) names the same definition.
const definition =
givenDefinition == null
? undefined
: definitionNameOf(givenDefinition, mappableDefinitions(set));
const source = resolveIconSource(from, where);
const sourceExport = useDefault ? 'default' : exportName;
assertIconExport(source.file, source.module, sourceExport);
// A component is re-exported; anything else goes through the set's
// adapter. Either way the icon is an export of the set's own module.
const adapt = exportValueKind(source.file, sourceExport) !== 'component';
if (adapt && !set.data.adapter) {
throw new AstryxError(
`"${sourceExport}" in "${source.module}" is not a component, so this set needs an adapter: a function in your package that turns it into one. Declare "adapter": {"module": "./src/adapt.js", "export": "adapt"} in ${set.name}.icons.json (astryx docs cli/experimental/icon-sets library-shapes).`,
undefined,
ERROR_CODES.ERR_INVALID_ARGUMENT,
);
}
const generated = generatedModulePath(set, packageDir);
const module = set.data.module;
// A library prefix every icon export shares (`feather` in `featherEye`)
// is left out of the id and the set's export name, as the bulk wrap does,
// and so are the look words a library's names end in (`Outline24WGHT500`
// in `XOutline24WGHT500Icon`). A ./ path is the author's own files, named
// as written: never a library prefix (`CheckDouble` and
// `CheckDoubleSolid` share `check`).
const libraryNaming =
useDefault || source.module.startsWith('./')
? {prefix: [], positions: []}
: moduleNaming(source.file, {
adapter: Boolean(set.data.adapter),
module: source.module,
progress: line => logger.warn(line),
});
const nameWords = iconIdOf(exportName).split('-');
const shared = libraryNaming.prefix;
const prefix =
shared.length > 0 &&
nameWords.length > shared.length &&
shared.every((word, index) => nameWords[index] === word)
? shared
: [];
// A library export the set already has keeps its icon's name and id.
const already = generatedNamesOf(
packageDir,
generated,
source.module,
sourceExport,
);
const known = set.data.icons.find(each => already.includes(each.export));
const glyph = known
? {id: known.id, name: known.export}
: iconNamingWithoutLook(exportName, {
prefix,
positions: libraryNaming.positions,
});
const asVariant = variant != null;
// The set may already export the glyph's name for another export of the
// library (its outline look, when this is the filled one). This export
// then keeps its look words in its id and name, or takes its name from
// --id, and the listing offers it as a variant of that icon instead.
const origin = generatedOrigins(packageDir, generated).get(glyph.name);
const glyphTaken =
!known &&
!asVariant &&
origin != null &&
!(
sameIconModule(origin.module, source.module) &&
origin.source === sourceExport
);
const naming = !glyphTaken
? glyph
: givenId != null
? {id: givenId, name: nameFromId(givenId)}
: iconNaming(exportName, prefix);
const id = givenId ?? naming.id;
// The name the set exports it as: `<Name>Icon`, or for a variant the
// icon's name with the variant's name.
const baseIcon = set.data.icons.find(each => each.id === id);
const setName = asVariant
? variantExportName(baseIcon?.export ?? naming.name, variant)
: naming.name;
if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(id)) {
throw new AstryxError(
`"${exportName}" gives no icon id; pass --id with a lower-kebab id.`,
undefined,
ERROR_CODES.ERR_INVALID_ARGUMENT,
);
}
if (definition == null && newDefinition == null && !asVariant) {
return definitionMatches(set, exportName, from, id, {
useDefault,
id: givenId,
look:
glyphTaken && origin != null
? lookVariantOf(
iconNaming(exportName, prefix).id,
iconNaming(origin.source, prefix).id,
libraryNaming.positions,
set,
)
: null,
glyphId: glyph.id,
});
}
/** @type {{name: string, description: string, words: string[]} | null} */
let created = null;
let mapped = definition ?? newDefinition ?? null;
if (newDefinition != null) {
const own = set.definitions.find(each => each.doc.name === newDefinition);
if (own) {
mapped = own.doc.name;
} else {
created = checkNewDefinition(set, {
name: newDefinition,
description,
words,
});
}
} else if (
definition != null &&
!mappableDefinitions(set).has(definition)
) {
throw new AstryxError(
`"${definition}" is not an icon definition.`,
[
...closestNames(definition, [...mappableDefinitions(set)]).map(
name => ({
name: `--definition ${name}`,
reason: 'a known icon definition',
}),
),
{
name: `--new-definition ${definitionNameFromInput(definition)} --description '<what it is for>' --words a,b`,
reason: 'add it as your own definition',
},
],
ERROR_CODES.ERR_NOT_FOUND,
);
}
// The icon keeps only its own words: search also matches it by the
// words of every definition it is mapped to, so they are not copied.
const icons = set.data.icons.map(each => ({...each}));
const existing = icons.find(each => each.id === id);
if (asVariant) {
checkVariantLook({
set,
variant,
module: source.module,
positions: libraryNaming.positions,
drawn: drawnLooks(set, packageDir, each =>
sameIconModule(each, source.module) ? libraryNaming.positions : null,
),
});
if (!existing) {
throw new AstryxError(
`Icon set "${set.name}" has no icon "${id}" to add a variant to. Add the icon first, or pass --id.`,
closestNames(
id,
icons.map(each => each.id),
).map(name => ({
name: `--id ${name}`,
reason: 'an icon in this set',
})),
ERROR_CODES.ERR_NOT_FOUND,
);
}
const own = generatedOrigins(packageDir, generated).get(existing.export);
if (
own != null &&
own.source === sourceExport &&
sameIconModule(own.module, source.module)
) {
throw new AstryxError(
`"${sourceExport}" is icon "${id}"'s own export, which draws its default look, so it can't be its ${variant} variant too.`,
undefined,
ERROR_CODES.ERR_INVALID_ARGUMENT,
);
}
const variants = [...(existing.variants ?? [])];
const same = variants.find(each => each.export === setName);
if (!same) {
variants.push({variant, export: setName});
existing.variants = variants;
}
} else if (existing) {
if (
existing.export !== setName ||
(existing.module ?? set.data.module) !== module
) {
throw new AstryxError(
`Icon set "${set.name}" already has an icon "${id}" (${existing.export}). Pass --id to add this one under another id.`,
undefined,
ERROR_CODES.ERR_FILE_EXISTS,
);
}
} else {
icons.push({
id,
export: setName,
words: id.split('-'),
});
}
const map = {...(set.data.map ?? {})};
if (mapped) map[mapped] = id;
const next = {
...set.data,
...(set.data.generated ? {} : {generated}),
...(set.data.themeMap ? {} : {themeMap: THEME_MAP_NAME}),
map,
icons,
};
const dataChanged =
JSON.stringify(next) !== JSON.stringify(set.data) || where.moduleRenamed;
/** @type {string[]} */
const files = [];
// Every write happens inside this try, so any failure undoes the ones
// before it and leaves every file as it was (AST-084 FR13).
let undoDefinition = () => {};
let undoGenerated = () => {};
/** @type {boolean} */
let generatedChanged;
try {
if (created) undoDefinition = writeDefinitionFile(set, created);
const written = writeGeneratedIcons(packageDir, generated, next, [
{name: setName, from: source.module, source: sourceExport, adapt},
]);
undoGenerated = written.undo;
generatedChanged = written.changed;
files.push(...written.files);
if (created) {
files.push(
path
.relative(
packageDir,
path.join(set.dir, 'definitions', `${created.name}.doc.mjs`),
)
.split(path.sep)
.join('/'),
);
}
if (dataChanged) {
writeIconSetData(set, next, {
extraDefinitions: created ? [created.name] : [],
});
files.push(
path.relative(packageDir, set.dataPath).split(path.sep).join('/'),
);
}
} catch (error) {
undoGenerated();
undoDefinition();
if (error instanceof Error && /is not in variants/u.test(error.message)) {
throw new AstryxError(
`${error.message} Declare it in "variants" in ${set.name}.icons.json first.`,
undefined,
ERROR_CODES.ERR_INVALID_ARGUMENT,
);
}
throw error;
}
// A renamed package's new name alone is not an added icon.
const added =
JSON.stringify(next) !== JSON.stringify(set.data) ||
created != null ||
generatedChanged;
const changed = dataChanged || added;
// A ./ file publishes only when package.json `files` lists it; the
// author adds it (architecture:cli-surface INV16).
const note =
[
localSourceNote(packageDir, source.module),
setModuleNote(set, where, generated, setName),
]
.filter(Boolean)
.join(' ') || null;
return {
type: /** @type {const} */ ('icon.add'),
data: {
set: set.name,
package: set.package,
icon: {id, export: setName, module},
...(asVariant ? {variant} : {}),
definition: mapped,
...(created ? {newDefinition: created.name} : {}),
files,
changed,
added,
...(where.moduleUpdate ? {moduleUpdate: where.moduleUpdate} : {}),
...(note ? {note} : {}),
},
};
});
}
/**
* The definitions that fit an export, Astryx's and the set's own, ranked by
* the icon lookup's scorer: each word of the export's name is a query
* against every definition's name and words; a definition keeps its best.
* @param {import('../../../foundation/discovery/icon-set-discovery.mjs').DiscoveredIconSet} set
* @param {string} exportName
* @param {string} from
* @param {string} id
* @param {{useDefault?: boolean, id?: string, look?: string | null, glyphId?: string}} passed the
* options the author passed, repeated in each listed command so it runs as
* printed; `look`, when the set already has an icon for the export's
* glyph (`glyphId`): the variant it is of that icon
* @returns {import('../icon.type.mjs').IconDefinitionMatchesResponse}
*/
function definitionMatches(set, exportName, from, id, passed = {}) {
const astryx = astryxIconDefinitions().definitions.map(each => ({
doc: each.doc,
source: /** @type {const} */ ('astryx'),
}));
const own = set.definitions
.filter(each => !astryx.some(a => a.doc.name === each.doc.name))
.map(each => ({doc: each.doc, source: /** @type {const} */ ('set')}));
const all = [...astryx, ...own];
// Each definition reads as an icon: its name's words as the id, then its
// words, so the lookup's tiers apply unchanged.
const asSet = /** @type {any} */ ({
name: 'definitions',
package: set.package,
data: {
module: set.data.module,
icons: all.map(({doc}) => ({
id: doc.name.replace(/([a-z0-9])([A-Z])/gu, '$1-$2').toLowerCase(),
export: doc.name,
words: [
...doc.name
.replace(/([a-z0-9])([A-Z])/gu, '$1 $2')
.toLowerCase()
.split(' '),
...doc.words,
],
})),
},
});
const queries = [
id.replace(/-/gu, ' '),
...id.split('-').filter(word => /[a-z]/u.test(word)),
];
/** @type {Map<string, {score: number, reason: string}>} */
const best = new Map();
for (const query of queries) {
for (const match of answeringMatches(rankIcons([asSet], query))) {
const prior = best.get(match.export);
if (!prior || match.score > prior.score) {
best.set(match.export, {score: match.score, reason: match.reason});
}
}
}
const base = [
`astryx experimental icon add ${exportName} --from ${shellArg(from)}`,
`--set ${shellArg(set.name)}`,
...(passed.useDefault ? ['--default'] : []),
...(passed.id != null ? [`--id ${shellArg(passed.id)}`] : []),
].join(' ');
const matches = all
.filter(({doc}) => best.has(doc.name))
.map(({doc, source}) => {
const hit = /** @type {{score: number, reason: string}} */ (
best.get(doc.name)
);
return {
name: doc.name,
description: doc.description,
source,
score: hit.score,
reason: hit.reason,
command: `${base} --definition ${doc.name}`,
};
})
.sort(
(a, b) =>
b.score - a.score ||
(a.source === b.source ? 0 : a.source === 'astryx' ? -1 : 1) ||
(a.name < b.name ? -1 : a.name > b.name ? 1 : 0),
)
.slice(0, MATCH_LIMIT);
const fits = matches.some(match => match.score >= FIT_FLOOR);
const asLook =
passed.look && passed.glyphId
? [
`astryx experimental icon add ${exportName} --from ${shellArg(from)}`,
`--set ${shellArg(set.name)}`,
...(passed.useDefault ? ['--default'] : []),
`--id ${passed.glyphId} --variant ${passed.look}`,
].join(' ')
: null;
const name = id.replace(/-([a-z0-9])/gu, (_, c) => c.toUpperCase());
return {
type: 'icon.definitionMatches',
data: {
export: exportName,
from,
id,
matches,
newDefinition: fits
? null
: `${base} --new-definition ${/^[a-z]/u.test(name) ? name : `icon${name}`} --description '<what the icon is for>' --words <word>,<word>`,
...(asLook ? {variant: asLook} : {}),
},
};
}
/**
* `--all`: add one variant for every icon of the set whose library export
* has a counterpart in `from` with the same id (`TrashIcon` in the solid
* module is the solid variant of `trash`), in one write.
* @param {{cwd: string, from: string | undefined, selector: string | undefined, variant: string | undefined}} args
* @returns {Promise<import('../icon.type.mjs').IconAddVariantsResponse>}
*/
async function addVariantForAll({cwd, from, selector, variant}) {
if (variant == null || variant === '') {
throw new AstryxError(
'--all adds one variant for every icon: pass --variant with the variant, such as solid.',
undefined,
ERROR_CODES.ERR_MISSING_ARGUMENT,
);
}
if (typeof from !== 'string' || from.trim() === '') {
throw new AstryxError(
'Pass --from with the module that exports the variant, such as @heroicons/react/24/solid.',
undefined,
ERROR_CODES.ERR_MISSING_ARGUMENT,
);
}
const where = await findLocalIconSet(cwd, selector);
const {packageDir, set} = where;
const source = resolveIconSource(from, where);
// In a library that draws each icon in several looks, the variant is the
// glyph's look the variant's name picks (`filled`), and an icon is known
// by any look of its glyph.
/** @type {Array<Set<string>>} */
let positions = [];
const found = libraryIcons(source.file, {
adapter: Boolean(set.data.adapter),
prefer: [variant],
module: source.module,
progress: line => logger.warn(line),
summary: each => {
positions = each.positions.map(words => new Set(words));
},
});
checkVariantLook({
set,
variant,
module: source.module,
positions,
drawn: drawnLooks(set, packageDir, each =>
sameIconModule(each, source.module) ? positions : null,
),
});
const byId = new Map(found.map(each => [each.id, each]));
const byLook = new Map(
found.flatMap(each => (each.looks ?? []).map(look => [look, each])),
);
// An existing icon is known by the library export it re-exports, then by
// its own export, then by its id: an icon whose id or name an older rule
// wrote (`squares-2-x2`, `Squares2X2Icon`) still meets its variant
// (`HiSquares2X2Icon` in the solid module).
const byLibraryExport = new Map(found.map(each => [each.export, each]));
const byName = new Map(found.map(each => [each.name, each]));
const origins = generatedOrigins(
packageDir,
generatedModulePath(set, packageDir),
);
// Only icons from the same package as the variant module can have a
// variant there: an icon from your own `./` file, or from another library,
// is left as it is and never listed as missing. Some libraries ship each
// look as its own package (Font Awesome's solid and regular packages): an
// icon from another package meets its variant only under the same export
// name and of the same kind, a component or data for the adapter. Once
// one icon of a package meets its twin, that package is a look package of
// the variant module, so its other icons are listed as missing.
const variantPackage = iconModulePackage(source.module);
/** @param {{module: string, source: string, adapt: boolean}} origin */
const otherPackageTwin = origin => {
if (origin.module.startsWith('.')) return false;
const twin = byLibraryExport.get(origin.source);
return twin != null && twin.adapt === origin.adapt;
};
const lookPackages = new Set(
set.data.icons.flatMap(icon => {
const origin = origins.get(icon.export);
return origin && otherPackageTwin(origin)
? [iconModulePackage(origin.module)]
: [];
}),
);
const generated = generatedModulePath(set, packageDir);
/** @type {import('../../../foundation/discovery/icon-set-writer.mjs').GeneratedIcon[]} */
const toWrite = [];
/** @type {string[]} */
const added = [];
/** @type {string[]} */
const already = [];
/** @type {string[]} */
const missing = [];
/** @type {string[]} icons whose own export is the one the variant picks */
const own = [];
const icons = set.data.icons.map(icon => {
const origin = origins.get(icon.export);
if (
origin &&
iconModulePackage(origin.module) !== variantPackage &&
!lookPackages.has(iconModulePackage(origin.module))
) {
return icon;
}
const librarySource =
origin && origin.source !== 'default' ? origin.source : undefined;
const match =
(librarySource ? byLibraryExport.get(librarySource) : undefined) ??
(librarySource ? byLook.get(librarySource) : undefined) ??
byName.get(icon.export) ??
byId.get(icon.id);
if (!match) {
missing.push(icon.id);
return icon;
}
if (match.adapt && !set.data.adapter) {
missing.push(icon.id);
return icon;
}
// A glyph the library draws in no look of that name has no variant,
// and neither has one whose own export is the one that look picks.
if (match.look && !match.look.includes(variant)) {
missing.push(icon.id);
return icon;
}
if (
match.export === librarySource &&
origin != null &&
sameIconModule(origin.module, source.module)
) {
own.push(icon.id);
missing.push(icon.id);
return icon;
}
const name = variantExportName(icon.export, variant);
const variants = [...(icon.variants ?? [])];
if (variants.some(each => each.variant === variant)) {
already.push(icon.id);
return icon;
}
toWrite.push({
name,
from: source.module,
source: match.export,
adapt: match.adapt,
});
variants.push({variant, export: name});
added.push(icon.id);
return {...icon, variants};
});
if (
added.length === 0 &&
already.length === 0 &&
own.length > 0 &&
set.data.default?.variant == null
) {
// The module is the one the icons' own exports come from, so the
// variant names the look they draw now: the set's undeclared default.
const variants = [
variant,
...(set.data.variants ?? []).filter(each => each !== variant),
];
throw new AstryxError(
`"${source.module}" is the module the ${own.length} icons of "${set.name}" come from: its exports are those icons in the look they draw now, so "${variant}" is that look and can't be a variant of them. "${set.name}" declares no default variant; declare "${variant}" as the default first.`,
[
{
name: `astryx experimental icon new-set ${set.name} --variants ${variants.join(',')} --default-variant ${variant}`,
reason: `declare ${variant}, the look each icon draws, as the default`,
},
],
ERROR_CODES.ERR_INVALID_ARGUMENT,
);
}
if (added.length === 0 && already.length === 0) {
throw new AstryxError(
`"${source.module}" exports no icon with the id of an icon in "${set.name}". Pass the module that exports the ${variant} variant under the same names.`,
undefined,
ERROR_CODES.ERR_NOT_FOUND,
);
}
const next = {
...set.data,
...(set.data.generated ? {} : {generated}),
...(set.data.themeMap ? {} : {themeMap: THEME_MAP_NAME}),
icons,
};
/** @type {string[]} */
const files = [];
const written = writeGeneratedIcons(packageDir, generated, next, toWrite);
files.push(...written.files);
const dataChanged =
JSON.stringify(next) !== JSON.stringify(set.data) || where.moduleRenamed;
if (dataChanged) {
try {
writeIconSetData(set, next);
} catch (error) {
written.undo();
throw error;
}
files.push(
path.relative(packageDir, set.dataPath).split(path.sep).join('/'),
);
}
return {
type: /** @type {const} */ ('icon.addVariants'),
data: {
set: set.name,
package: set.package,
variant,
from: source.module,
added: added.length,
already: already.length,
missing,
files,
changed: dataChanged || written.changed,
...(where.moduleUpdate ? {moduleUpdate: where.moduleUpdate} : {}),
},
};
}
/**
* The set's export name for an id: `x-filled` is `XFilledIcon`.
* @param {string} id
*/
function nameFromId(id) {
return iconExportName(
id
.split('-')
.map(word => word[0].toUpperCase() + word.slice(1))
.join(''),
);
}
/**
* The variant an export of a library of looks is of the icon the set
* already wraps for its glyph: its word at the first look position, in name
* order, where it differs from the wrapped export. That word is a variant
* only when the set declares it and it is not the default, which the icon's
* own export draws. Otherwise null, so the listing offers no variant
* command that the set's data would refuse.
* @param {string} id the export's id, look words kept
* @param {string} wrappedId the wrapped export's id, look words kept
* @param {Array<Set<string>>} positions the library's look positions, the
* last word first
* @param {import('../../../foundation/discovery/icon-set-discovery.mjs').DiscoveredIconSet} set
* @returns {string | null}
*/
function lookVariantOf(id, wrappedId, positions, set) {
const {look} = splitLook(id.split('-'), positions);
const {look: wrapped} = splitLook(wrappedId.split('-'), positions);
let word = null;
for (let index = look.length - 1; index >= 0; index--) {
if (look[index] !== wrapped[index]) {
word = look[index];
break;
}
}
return word != null &&
(set.data.variants ?? []).includes(word) &&
word !== set.data.default?.variant
? word
: null;
}