@yahoo/uds-create-config 4.10.2 → 4.10.4

package/dist/entities/system/icon-library.d.ts

@@ -1,45 +1,105 @@
 import { Config } from "../../framework/Config.js";
+import { Icon, IconVariantAs } from "./Icon.js";
 
 //#region src/entities/system/icon-library.d.ts
-/** An icon library, as its group node describes it. */
-interface IconLibrary {
-  /** The group path — the `slug` half of a placed glyph's type. */
+/**
+ * An icon library as its group node reads: the path, the stored set facts (`sizes`, `variants`,
+ * `package`, `variantAs`, `metadata`) and the computeds the entity declares (`members`, `module`,
+ * `version`), plus the per-member and drawer-side facts this projection derives. Typed off
+ * `Icon.groups`, so a field added on the entity is visible here without a second declaration.
+ */
+type IconLibrary = {
   readonly path: string;
-  /** The glyphs it ships, by leaf name. */
-  readonly members: readonly string[];
-  /** Named sizes (`sm: 16`). */
+} & Undefinable<Omit<ReturnType<typeof Icon.groups>[number]['meta'], 'items' | 'sizes' | 'variants'>> & {
   readonly sizes: Readonly<Record<string, number>>;
-  /** Weights/styles the set ships. */
   readonly variants: readonly string[];
-  /** The component a placed glyph renders through, if the set declares one. */
-  readonly component?: string;
-  /** The npm module that supplies the library's glyph implementations. */
-  readonly module?: string;
-  /** The version of the package the glyphs come from, when the set pins one —
-   *  what an assets index shows beside the library's name. */
-  readonly version?: string;
-  /** The variant the bound component declares in its `defaultProps` — what a
-   *  picker seeds when nothing is stored. Passed through as DECLARED; a policy
-   *  read validates against {@link variants} before trusting it. */
+  /** For a ragged set, the members whose own `variants` differ from the set's, by leaf. A member
+   *  listing exactly the set's variants is left out, so the map stays as sparse as the
+   *  raggedness. */
+  readonly memberVariants?: Readonly<Record<string, readonly string[]>>;
+  /** The variant the library's drawer declares in its `defaultProps` — what a picker seeds when nothing is
+   *  stored. Passed through as declared; a policy read validates it against {@link variants}
+   *  before trusting it. */
   readonly defaultVariant?: string;
-  /** The size bucket the bound component declares in its `defaultProps`.
-   *  Same contract as {@link defaultVariant}: declared, not validated. */
+  /** The size bucket the library's drawer declares in its `defaultProps`. Same contract as
+   *  {@link defaultVariant}: declared, not validated. */
   readonly defaultSizeKey?: string;
-}
+};
+/** A field that may hold `undefined` may be left out: a computed's `string | undefined` reads as an
+ *  optional key, so a literal need not spell the absence. */
+type Undefinable<T> = { readonly [K in keyof T as undefined extends T[K] ? K : never]?: T[K] } & { readonly [K in keyof T as undefined extends T[K] ? never : K]: T[K] };
 /** The spec `type` a placed glyph of this library carries — its own ref. */
-declare function assetType(library: IconLibrary, member: string): string;
+declare function glyphType(library: IconLibrary, member: string): string;
 /** One library by its group path — `undefined` when the config has no such set. */
 declare function iconLibrary(config: Config | null | undefined, path: string): IconLibrary | undefined;
+/**
+ * The exports a glyph is drawn from: its own name, plus the export each `variantAs.export`
+ * template names for it. A per-glyph module has to carry all of them, since the glyph resolver
+ * swaps between them at render; a `prop` strategy or no declaration needs the bare export alone.
+ * With `variants`, the member's own list, only the templates for variants it ships are added: a
+ * ragged set's member has no export for the rest, and naming one fails the module's bundle.
+ */
+declare function glyphExportNames({
+  variantAs,
+  name,
+  variants
+}: {
+  variantAs: IconVariantAs | undefined;
+  name: string;
+  variants?: readonly string[];
+}): string[];
+/**
+ * The element a glyph is PLACED as: an instance of the component that draws from its library, the
+ * member on that component's glyph prop and the set's axes as the component's own props — so a
+ * placed glyph paints exactly as the component would, and the panel edits it as one. A library no
+ * component draws from places the member raw, under its own `icon:` type.
+ *
+ * Only for placing. A node a render wrote (`<StarIcon size={12} />`) stays the raw member it is.
+ */
+declare function placedGlyphElement(config: Config | null | undefined, glyph: string, props?: Record<string, unknown>): {
+  type: string;
+  props: Record<string, unknown>;
+};
 /** Every icon library the config declares. */
 declare function iconLibraries(config: Config | null | undefined): IconLibrary[];
 /**
- * The library a surface should show: the hinted one when a caller carries a slug (a slot's
- * `accepts` ref, a stored fill), else the first library that actually has members. One home for
- * that policy — the toolbar, placement, and the panel all resolve through here, so no surface
- * carries its own idea of a default set. A hint that names no library resolves to `undefined`
- * rather than falling back: the caller knows whether a stale slug should show empty or pick anew.
+ * The libraries a surface should offer: the hinted ones in the order given (a prop whose domain
+ * lists several sets), else every library that actually has members. One home for that policy — the
+ * toolbar, placement and the panel all resolve through here, so no surface carries its own idea of
+ * a default set. A hint naming no library is dropped rather than failing the list, so one stale
+ * slug in a pair still shows the other set. An empty list of hints offers nothing: the caller had a
+ * domain and it named no library, which is not the same as having no domain.
  */
-declare function resolveIconLibrary(config: Config | null | undefined, hint?: string): IconLibrary | undefined;
+declare function resolveIconLibraries({
+  config,
+  hints
+}: {
+  config: Config | null | undefined;
+  hints?: readonly string[];
+}): IconLibrary[];
+/**
+ * The libraries a component binds: every icon group one of its variant props names as its domain,
+ * in the order the props and their lists declare them. A surface handed a bare glyph name by the
+ * component resolves it against this list, so a set outside the domain never answers for one in it.
+ * A facet ref (`icon:phosphor#variants`) offers the set's variants rather than its glyphs, so it
+ * binds nothing — `glyphLibrariesOf` is the one reading of the edge, shared with
+ * {@link glyphComponentOf}.
+ */
+declare function librariesBoundBy({
+  config,
+  component
+}: {
+  config: Config | null | undefined;
+  component: string;
+}): IconLibrary[];
+/** The library holding `member`, among the ones a surface offers. */
+declare function libraryHolding({
+  libraries,
+  member
+}: {
+  libraries: readonly IconLibrary[];
+  member: string | undefined;
+}): IconLibrary | undefined;
 /**
  * Every category the library's members carry, RAW as stored (lowercase, unsorted within a member,
  * plural per member), deduplicated and sorted for a filter menu. Casing is display policy — a
@@ -47,13 +107,12 @@ declare function resolveIconLibrary(config: Config | null | undefined, hint?: st
  */
 declare function iconCategories(config: Config | null | undefined, libraryPath: string): readonly string[];
 /**
- * The variants a placed glyph may take.
- *
- * The whole library's variants: nothing in the model describes one glyph's own set yet
- * (config-v2 model gap 8 — per-item `variants` narrowing). So a set that ships a variant only
- * some of its glyphs support will offer it for all of them until that closes.
+ * The variants a placed glyph may take: the member's own `variants` when its metadata lists them (a
+ * ragged set), else the whole library's. Kept in the library's order, so a picker's axis reads the
+ * same across glyphs. A member listing only variants the set doesn't ship falls back to the set's,
+ * so the axis is never empty for a set that ships one.
  */
-declare function memberVariantOptions(library: IconLibrary, _member: string): readonly string[];
+declare function memberVariantOptions(library: IconLibrary, member: string): readonly string[];
 /**
  * Whether an element type declares a prop that may survive layer-style projection. A placed
  * glyph's type isn't a component, so its prop surface comes from its library instead: the
@@ -61,4 +120,4 @@ declare function memberVariantOptions(library: IconLibrary, _member: string): re
  */
 declare function isDeclaredElementProp(config: Config | null | undefined, elementType: string, propName: string): boolean;
 //#endregion
-export { IconLibrary, assetType, iconCategories, iconLibraries, iconLibrary, isDeclaredElementProp, memberVariantOptions, resolveIconLibrary };
+export { IconLibrary, glyphExportNames, glyphType, iconCategories, iconLibraries, iconLibrary, isDeclaredElementProp, librariesBoundBy, libraryHolding, memberVariantOptions, placedGlyphElement, resolveIconLibraries };

package/dist/entities/system/icon-library.js

@@ -1,68 +1,237 @@
-import { pathOf } from "../../framework/utils/refs.js";
-import { resolveComponentProps } from "../../framework/projections.js";
+import { createSliceMemo } from "../../framework/memo.js";
+import { glyphComponentOf, glyphLibrariesOf, resolveComponentProps } from "../../framework/projections.js";
 import { Component } from "./Component.js";
 import { Icon } from "./Icon.js";
-import { parseAssetType } from "../../spec/asset-jsx.js";
+import { parseGlyphType } from "../../spec/glyph-jsx.js";
 //#region src/entities/system/icon-library.ts
 /**
-* The icon-library READ projection — an icon group's node and members as one plain value, beside
-* the entity that stores them.
+* Icon-library reads — an icon group's node with its computeds, and the policy reads over it.
 *
 * An icon is an entity (`icon:phosphor/StarIcon`) and everything describing the SET lives on the
-* emergent group node — the sizes and variants it ships, and the component a placed glyph renders
-* through. {@link IconLibrary} is that group node read once, so a surface asks a plain value
-* rather than re-querying the config per member.
+* group node: the sizes and variants it ships, the package its glyphs come from, and the members
+* and module the entity computes from those. {@link IconLibrary} is that node flattened with its
+* path, so a surface asks a plain value rather than re-querying the config per member.
 *
 * A placed glyph's spec `type` IS the member's ref (`icon:phosphor/StarIcon`) — the same identity
-* the config uses, which is what `parseAssetType` reads.
+* the config uses, which is what `parseGlyphType` reads.
 *
 * This is the one home for the question "what icon sets does this system have" — Studio owns only
-* UI policy on top (picker state, grid geometry, recents, search ranking). Like `Component.list`,
-* the functions here build fresh values per call: consume them in place or memoize on the config.
+* UI policy on top (picker state, grid geometry, recents, search ranking). A library is cached on
+* the slices it reads — the set (`icon`), its drawer's defaults (`component`) and the package row
+* its version comes from (`package`) — so it is reference-stable across calls on one config and
+* safe in a dep array.
 */
-const EMPTY_VARIANTS = Object.freeze([]);
-const EMPTY_SIZES = Object.freeze({});
 const EMPTY_CATEGORIES = Object.freeze([]);
+const EMPTY_SIZES = Object.freeze({});
+const EMPTY_VARIANTS = Object.freeze([]);
+const NO_LIBRARIES = [];
 /** The spec `type` a placed glyph of this library carries — its own ref. */
-function assetType(library, member) {
+function glyphType(library, member) {
 	return `icon:${library.path}/${member}`;
 }
 /** One library by its group path — `undefined` when the config has no such set. */
 function iconLibrary(config, path) {
 	if (!config) return void 0;
-	const meta = config.groupMeta("icon", path);
-	if (!meta) return void 0;
-	const component = meta.component ? pathOf(meta.component) : void 0;
-	const defaults = component ? Component.get(config, component)?.defaultProps : void 0;
-	const defaultVariant = typeof defaults?.variant === "string" ? defaults.variant : void 0;
-	const defaultSizeKey = typeof defaults?.size === "string" ? defaults.size : void 0;
+	const cache = librariesOf(config);
+	if (cache.has(path)) return cache.get(path);
+	const library = readIconLibrary(config, path);
+	cache.set(path, library);
+	return library;
+}
+/** Per-config cache of {@link iconLibrary} answers. `package` is in the key because the set's
+*  `version` resolves through the package row, not off the group node. The member walk underneath
+*  keys on the icon slice alone, so a component write re-reads only each library's drawer defaults. */
+const librariesOf = createSliceMemo({
+	kinds: [
+		"icon",
+		"component",
+		"package"
+	],
+	compute: (_config) => /* @__PURE__ */ new Map()
+});
+function readIconLibrary(config, path) {
+	const group = Icon.groups(config).find((entry) => entry.path === path);
+	if (!group) return void 0;
+	const { items: _items, sizes, variants, ...meta } = group.meta;
+	const set = setMembers({
+		config,
+		path,
+		declared: variants
+	});
 	return {
+		...meta,
 		path,
-		members: config.members("icon", path).map((member) => member.path.startsWith(`${path}/`) ? member.path.slice(path.length + 1) : member.path),
-		sizes: meta.sizes ?? EMPTY_SIZES,
-		variants: meta.variants ?? EMPTY_VARIANTS,
-		...component !== void 0 ? { component } : {},
-		...typeof meta.module === "string" ? { module: meta.module } : {},
-		...meta.version !== void 0 ? { version: meta.version } : {},
-		...defaultVariant !== void 0 ? { defaultVariant } : {},
-		...defaultSizeKey !== void 0 ? { defaultSizeKey } : {}
+		members: set.members,
+		sizes: sizes ?? EMPTY_SIZES,
+		variants: variants ?? EMPTY_VARIANTS,
+		...set.memberVariants ? { memberVariants: set.memberVariants } : {},
+		...drawerDefaults({
+			config,
+			library: path
+		})
+	};
+}
+/**
+* The defaults the set's drawer declares: the component whose own variant prop names this library
+* carries "what a bare glyph looks like", read back here so every picker seeds from that one
+* declaration rather than its own literal. A library no component draws from has no defaults.
+*/
+function drawerDefaults({ config, library }) {
+	const drawer = glyphComponentOf(config, library);
+	if (!drawer) return {};
+	const defaults = Component.get(config, drawer.path)?.defaultProps;
+	const variant = defaults?.variant;
+	const size = defaults?.size;
+	return {
+		...typeof variant === "string" ? { defaultVariant: variant } : {},
+		...typeof size === "string" ? { defaultSizeKey: size } : {}
+	};
+}
+/** Per-config cache of the member walk, which is the cost a large set carries. */
+const membersOf = createSliceMemo({
+	kinds: ["icon"],
+	compute: (_config) => /* @__PURE__ */ new Map()
+});
+function setMembers({ config, path, declared }) {
+	const walked = membersOf(config);
+	const hit = walked.get(path);
+	if (hit) return hit;
+	const members = [];
+	const memberVariants = {};
+	for (const member of config.members("icon", path)) {
+		const leaf = member.path.startsWith(`${path}/`) ? member.path.slice(path.length + 1) : member.path;
+		members.push(leaf);
+		const own = ownVariantsOf(member.body);
+		if (own && own.length > 0 && !sameVariants({
+			own,
+			declared
+		})) memberVariants[leaf] = own;
+	}
+	const set = {
+		members,
+		...Object.keys(memberVariants).length > 0 ? { memberVariants } : {}
+	};
+	walked.set(path, set);
+	return set;
+}
+/** A member body's `variants`, when it is a list of names. */
+function ownVariantsOf(body) {
+	const declared = body.variants;
+	if (!Array.isArray(declared)) return void 0;
+	return declared.filter((variant) => typeof variant === "string");
+}
+/** Whether a member's list names exactly the set's variants, in any order. */
+function sameVariants({ own, declared }) {
+	if (!declared || declared.length !== own.length) return false;
+	const set = new Set(declared);
+	return own.every((variant) => set.has(variant));
+}
+/**
+* The exports a glyph is drawn from: its own name, plus the export each `variantAs.export`
+* template names for it. A per-glyph module has to carry all of them, since the glyph resolver
+* swaps between them at render; a `prop` strategy or no declaration needs the bare export alone.
+* With `variants`, the member's own list, only the templates for variants it ships are added: a
+* ragged set's member has no export for the rest, and naming one fails the module's bundle.
+*/
+function glyphExportNames({ variantAs, name, variants }) {
+	const names = new Set([name]);
+	if (variantAs && "export" in variantAs) for (const [variant, template] of Object.entries(variantAs.export)) {
+		if (variants && !variants.includes(variant)) continue;
+		names.add(template.replaceAll("{name}", name));
+	}
+	return [...names];
+}
+/**
+* The element a glyph is PLACED as: an instance of the component that draws from its library, the
+* member on that component's glyph prop and the set's axes as the component's own props — so a
+* placed glyph paints exactly as the component would, and the panel edits it as one. A library no
+* component draws from places the member raw, under its own `icon:` type.
+*
+* Only for placing. A node a render wrote (`<StarIcon size={12} />`) stays the raw member it is.
+*/
+function placedGlyphElement(config, glyph, props = {}) {
+	const parsed = parseGlyphType(glyph);
+	const drawer = parsed && config ? glyphComponentOf(config, parsed.slug) : void 0;
+	if (!parsed || !drawer) return {
+		type: glyph,
+		props
+	};
+	return {
+		type: `component:${drawer.path}`,
+		props: {
+			[drawer.prop]: parsed.member,
+			...props
+		}
 	};
 }
 /** Every icon library the config declares. */
 function iconLibraries(config) {
-	if (!config) return [];
-	return Icon.groups(config).map(({ path }) => iconLibrary(config, path)).filter((library) => library !== void 0);
+	if (!config) return NO_LIBRARIES;
+	return allLibrariesOf(config);
 }
+const allLibrariesOf = createSliceMemo({
+	kinds: [
+		"icon",
+		"component",
+		"package"
+	],
+	compute: (config) => Icon.groups(config).map(({ path }) => iconLibrary(config, path)).filter((library) => library !== void 0)
+});
 /**
-* The library a surface should show: the hinted one when a caller carries a slug (a slot's
-* `accepts` ref, a stored fill), else the first library that actually has members. One home for
-* that policy — the toolbar, placement, and the panel all resolve through here, so no surface
-* carries its own idea of a default set. A hint that names no library resolves to `undefined`
-* rather than falling back: the caller knows whether a stale slug should show empty or pick anew.
+* The libraries a surface should offer: the hinted ones in the order given (a prop whose domain
+* lists several sets), else every library that actually has members. One home for that policy — the
+* toolbar, placement and the panel all resolve through here, so no surface carries its own idea of
+* a default set. A hint naming no library is dropped rather than failing the list, so one stale
+* slug in a pair still shows the other set. An empty list of hints offers nothing: the caller had a
+* domain and it named no library, which is not the same as having no domain.
 */
-function resolveIconLibrary(config, hint) {
-	if (hint) return iconLibrary(config, hint);
-	return iconLibraries(config).find((library) => library.members.length > 0);
+function resolveIconLibraries({ config, hints }) {
+	if (hints !== void 0) return hints.map((hint) => iconLibrary(config, hint)).filter((library) => library !== void 0);
+	return iconLibraries(config).filter((library) => library.members.length > 0);
+}
+/**
+* The libraries a component binds: every icon group one of its variant props names as its domain,
+* in the order the props and their lists declare them. A surface handed a bare glyph name by the
+* component resolves it against this list, so a set outside the domain never answers for one in it.
+* A facet ref (`icon:phosphor#variants`) offers the set's variants rather than its glyphs, so it
+* binds nothing — `glyphLibrariesOf` is the one reading of the edge, shared with
+* {@link glyphComponentOf}.
+*/
+function librariesBoundBy({ config, component }) {
+	if (!config) return NO_LIBRARIES;
+	const cache = boundLibrariesOf(config);
+	const hit = cache.get(component);
+	if (hit) return hit;
+	const bound = readBoundLibraries({
+		config,
+		component
+	});
+	cache.set(component, bound);
+	return bound;
+}
+/** Per-config cache of {@link librariesBoundBy}, keyed on the slices a prop's domain and the
+*  libraries it names read. */
+const boundLibrariesOf = createSliceMemo({
+	kinds: [
+		"component",
+		"icon",
+		"package"
+	],
+	compute: (_config) => /* @__PURE__ */ new Map()
+});
+function readBoundLibraries({ config, component }) {
+	const paths = /* @__PURE__ */ new Set();
+	for (const declaration of Object.values(resolveComponentProps(config, component))) {
+		const declared = declaration;
+		if (declared?.type !== "variant") continue;
+		for (const path of glyphLibrariesOf(declared.value)) paths.add(path);
+	}
+	return [...paths].map((path) => iconLibrary(config, path)).filter((library) => library !== void 0);
+}
+/** The library holding `member`, among the ones a surface offers. */
+function libraryHolding({ libraries, member }) {
+	if (!member) return void 0;
+	return libraries.find((library) => library.members.includes(member));
 }
 /**
 * Every category the library's members carry, RAW as stored (lowercase, unsorted within a member,
@@ -79,14 +248,16 @@ function iconCategories(config, libraryPath) {
 	return [...categories].sort((a, b) => a.localeCompare(b));
 }
 /**
-* The variants a placed glyph may take.
-*
-* The whole library's variants: nothing in the model describes one glyph's own set yet
-* (config-v2 model gap 8 — per-item `variants` narrowing). So a set that ships a variant only
-* some of its glyphs support will offer it for all of them until that closes.
+* The variants a placed glyph may take: the member's own `variants` when its metadata lists them (a
+* ragged set), else the whole library's. Kept in the library's order, so a picker's axis reads the
+* same across glyphs. A member listing only variants the set doesn't ship falls back to the set's,
+* so the axis is never empty for a set that ships one.
 */
-function memberVariantOptions(library, _member) {
-	return library.variants;
+function memberVariantOptions(library, member) {
+	const own = library.memberVariants?.[member];
+	if (!own || own.length === 0) return library.variants;
+	const narrowed = library.variants.filter((variant) => own.includes(variant));
+	return narrowed.length > 0 ? narrowed : library.variants;
 }
 /**
 * Whether an element type declares a prop that may survive layer-style projection. A placed
@@ -101,16 +272,13 @@ function isDeclaredElementProp(config, elementType, propName) {
 		if (propName.startsWith("--")) return false;
 		return config.resolve("style-property", propName) === void 0;
 	}
-	const parsed = parseAssetType(elementType);
+	const parsed = parseGlyphType(elementType);
 	if (!parsed) return false;
 	const library = iconLibrary(config, parsed.slug);
 	if (!library?.members.includes(parsed.member)) return false;
-	if (library.component) {
-		if (resolveComponentProps(config, library.component)[propName] !== void 0) return true;
-	}
 	if (propName === "size") return Object.keys(library.sizes).length > 0;
 	if (propName === "variant") return memberVariantOptions(library, parsed.member).length > 0;
 	return false;
 }
 //#endregion
-export { assetType, iconCategories, iconLibraries, iconLibrary, isDeclaredElementProp, memberVariantOptions, resolveIconLibrary };
+export { glyphExportNames, glyphType, iconCategories, iconLibraries, iconLibrary, isDeclaredElementProp, librariesBoundBy, libraryHolding, memberVariantOptions, placedGlyphElement, resolveIconLibraries };

package/dist/entities/system/icon-metadata.d.ts

@@ -16,10 +16,11 @@ import { z } from "zod";
  * name). The list and the adapter table are one file so they cannot drift apart.
  */
 /** The formats an icon group's `metadata.format` may declare — exactly the shipped adapters. */
-declare const ICON_METADATA_FORMATS: readonly ["phosphor", "uds"];
+declare const ICON_METADATA_FORMATS: readonly ["phosphor", "uds", "tabler"];
 declare const iconMetadataFormat: z.ZodEnum<{
   uds: "uds";
   phosphor: "phosphor";
+  tabler: "tabler";
 }>;
 type IconMetadataFormat = (typeof ICON_METADATA_FORMATS)[number];
 /**
@@ -30,6 +31,7 @@ declare const iconMemberMetadata: z.ZodObject<{
   categories: z.ZodOptional<z.ZodArray<z.ZodString>>;
   tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
   codepoint: z.ZodOptional<z.ZodNumber>;
+  variants: z.ZodOptional<z.ZodArray<z.ZodString>>;
   knockoutVariants: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
 type IconMemberMetadata = z.infer<typeof iconMemberMetadata>;
@@ -42,10 +44,11 @@ declare const iconMetadataDeclaration: z.ZodObject<{
   from: EntityClass<z.ZodObject<{
     version: z.ZodOptional<z.ZodString>;
     exports: z.ZodOptional<SubEntityClass<z.ZodObject<{}, z.core.$strict>>>;
-  }, z.core.$strict>, z.ZodObject<Record<never, never>, z.core.$strip>, "package", Record<never, never>, Record<never, never>, false>;
+  }, z.core.$strict>, z.ZodObject<Record<never, never>, z.core.$strip>, "package", Record<never, never>, Record<never, never>, false, Record<never, never>, Record<never, never>>;
   format: z.ZodEnum<{
     uds: "uds";
     phosphor: "phosphor";
+    tabler: "tabler";
   }>;
 }, z.core.$strict>;
 type IconMetadataDeclaration = z.infer<typeof iconMetadataDeclaration>;
@@ -53,7 +56,7 @@ type IconMetadataDeclaration = z.infer<typeof iconMetadataDeclaration>;
 type IconMetadataAdapter = (raw: unknown) => Record<string, IconMemberMetadata>;
 /**
  * The uds format IS this file schema — `{ [memberName]: { categories?, tags?, codepoint?,
- * knockoutVariants? } }` —
+ * variants?, knockoutVariants? } }` —
  * the escape hatch a consumer's own script writes. Exported (with a JSON-Schema form below) so
  * writing that script is a validated contract rather than a guess.
  */
@@ -61,12 +64,15 @@ declare const iconMetadataFile: z.ZodRecord<z.ZodString, z.ZodObject<{
   categories: z.ZodOptional<z.ZodArray<z.ZodString>>;
   tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
   codepoint: z.ZodOptional<z.ZodNumber>;
+  variants: z.ZodOptional<z.ZodArray<z.ZodString>>;
   knockoutVariants: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>>;
 type IconMetadataFile = z.infer<typeof iconMetadataFile>;
 /** The uds file contract as JSON Schema — what a generator stamps into `$schema`-aware tooling. */
 declare function iconMetadataFileJsonSchema(): Record<string, unknown>;
+/** `brand-4chan` → `IconBrand4chan`: the react package's export for a slug. */
+declare function tablerExportName(slug: string): string;
 /** Run the named format's adapter. The host resolved and read `raw`; this stays pure. */
 declare function iconMetadata(format: IconMetadataFormat, raw: unknown): Record<string, IconMemberMetadata>;
 //#endregion
-export { ICON_METADATA_FORMATS, IconMemberMetadata, IconMetadataAdapter, IconMetadataDeclaration, IconMetadataFile, IconMetadataFormat, iconMemberMetadata, iconMetadata, iconMetadataDeclaration, iconMetadataFile, iconMetadataFileJsonSchema, iconMetadataFormat };
+export { ICON_METADATA_FORMATS, IconMemberMetadata, IconMetadataAdapter, IconMetadataDeclaration, IconMetadataFile, IconMetadataFormat, iconMemberMetadata, iconMetadata, iconMetadataDeclaration, iconMetadataFile, iconMetadataFileJsonSchema, iconMetadataFormat, tablerExportName };

package/dist/entities/system/icon-metadata.js

@@ -14,7 +14,11 @@ import { z } from "zod";
 * name). The list and the adapter table are one file so they cannot drift apart.
 */
 /** The formats an icon group's `metadata.format` may declare — exactly the shipped adapters. */
-const ICON_METADATA_FORMATS = ["phosphor", "uds"];
+const ICON_METADATA_FORMATS = [
+	"phosphor",
+	"uds",
+	"tabler"
+];
 const iconMetadataFormat = z.enum(ICON_METADATA_FORMATS);
 /**
 * One member's descriptive facts — the same schema `Icon.fields` registers, owned here so the
@@ -29,6 +33,9 @@ const iconMemberMetadata = z.strictObject({
 	tags: z.array(z.string()).optional(),
 	/** The glyph's code point in a font-backed set — what a native glyphmap reads. */
 	codepoint: z.number().optional(),
+	/** The subset of the set's `variants` this glyph ships, for a ragged set (Tabler draws `filled`
+	*  for a third of its glyphs). Absent means every variant the set declares. */
+	variants: z.array(z.string().min(1)).optional(),
 	/** Variants whose glyph paints a literal white fill by design (a "knockout" meant for dark or
 	*  branded surfaces) rather than `currentColor`. Such a glyph is invisible on a light surface,
 	*  so pickers and catalogs preview these variants on a dark one. Rendering is untouched — the
@@ -47,7 +54,7 @@ const iconMetadataDeclaration = z.strictObject({
 });
 /**
 * The uds format IS this file schema — `{ [memberName]: { categories?, tags?, codepoint?,
-* knockoutVariants? } }` —
+* variants?, knockoutVariants? } }` —
 * the escape hatch a consumer's own script writes. Exported (with a JSON-Schema form below) so
 * writing that script is a validated contract rather than a guess.
 */
@@ -95,17 +102,50 @@ const phosphor = (raw) => {
 };
 const uds = (raw) => {
 	const parsed = iconMetadataFile.safeParse(raw);
-	if (!parsed.success) throw new Error(`uds metadata source did not match the uds file contract ({ [memberName]: { categories?, tags?, codepoint?, knockoutVariants? } }) — ${describeIssues(parsed.error)}`);
+	if (!parsed.success) throw new Error(`uds metadata source did not match the uds file contract ({ [memberName]: { categories?, tags?, codepoint?, variants?, knockoutVariants? } }) — ${describeIssues(parsed.error)}`);
 	return parsed.data;
 };
+/**
+* Tabler's catalogue: `@tabler/icons` ships `icons.json`, a record keyed by kebab slug. Each entry
+* carries a singular `category`, `tags` that mix strings and numbers, and a `styles` record whose
+* keys are the variants the glyph draws (`outline` always, `filled` for a subset). Loose for the
+* same reason as Phosphor's.
+*/
+const tablerCatalog = z.record(z.string().min(1), z.looseObject({
+	name: z.string().min(1),
+	category: z.string().optional(),
+	tags: z.array(z.union([z.string(), z.number()])).optional(),
+	styles: z.record(z.string().min(1), z.looseObject({ unicode: z.string().optional() }))
+}));
+/** `brand-4chan` → `IconBrand4chan`: the react package's export for a slug. */
+function tablerExportName(slug) {
+	return `Icon${slug.split("-").map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1)).join("")}`;
+}
+const tabler = (raw) => {
+	const parsed = tablerCatalog.safeParse(raw);
+	if (!parsed.success) throw new Error(`tabler metadata source did not match @tabler/icons' icons.json shape — ${describeIssues(parsed.error)}`);
+	const members = {};
+	for (const [slug, entry] of Object.entries(parsed.data)) {
+		const outline = entry.styles.outline?.unicode;
+		const codepoint = outline !== void 0 && /^[0-9a-fA-F]+$/.test(outline) ? Number.parseInt(outline, 16) : void 0;
+		members[tablerExportName(slug)] = {
+			...entry.category ? { categories: [entry.category] } : {},
+			...entry.tags && entry.tags.length > 0 ? { tags: entry.tags.map(String) } : {},
+			...codepoint !== void 0 ? { codepoint } : {},
+			variants: Object.keys(entry.styles)
+		};
+	}
+	return members;
+};
 /** Exhaustive by type: a format added to the list without an adapter here fails to compile. */
 const ADAPTERS = {
 	phosphor,
-	uds
+	uds,
+	tabler
 };
 /** Run the named format's adapter. The host resolved and read `raw`; this stays pure. */
 function iconMetadata(format, raw) {
 	return ADAPTERS[format](raw);
 }
 //#endregion
-export { ICON_METADATA_FORMATS, iconMemberMetadata, iconMetadata, iconMetadataDeclaration, iconMetadataFile, iconMetadataFileJsonSchema, iconMetadataFormat };
+export { ICON_METADATA_FORMATS, iconMemberMetadata, iconMetadata, iconMetadataDeclaration, iconMetadataFile, iconMetadataFileJsonSchema, iconMetadataFormat, tablerExportName };

package/dist/entities/system/runtime-modules.js

@@ -1,3 +1,4 @@
+import { isRef, pathOf } from "../../framework/utils/refs.js";
 import { Icon } from "./Icon.js";
 //#region src/entities/system/runtime-modules.ts
 /**
@@ -20,14 +21,13 @@ function declaredRuntimeModules(config) {
 		});
 	}
 	for (const group of Icon.groups(config)) {
-		const specifier = group.meta.module;
-		if (typeof specifier !== "string") continue;
+		const named = group.meta.package;
+		const specifier = isRef(named) ? pathOf(named) : void 0;
+		if (specifier === void 0) continue;
 		const existing = bySpecifier.get(specifier);
-		const groupVersion = group.meta.version;
-		const version = existing?.version ?? (typeof groupVersion === "string" ? groupVersion : void 0);
 		bySpecifier.set(specifier, {
 			specifier,
-			...version ? { version } : {},
+			...existing?.version ? { version: existing.version } : {},
 			...existing?.exports ? { exports: existing.exports } : {},
 			iconLibrary: true
 		});