@yahoo/uds-v5-wip 1.60.0 → 1.62.0

package/dist/config/dist/defineAssetGroup.js

@@ -0,0 +1,263 @@
+import { attachSourcePath, captureCallerPath } from "./captureCallerPath.js";
+import { isComponentRef } from "./refs.js";
+//#region ../config/dist/defineAssetGroup.js
+/**
+* `defineAssetGroup(members).config({...})` — the asset registration
+* factory. Members are positional (matching
+* `defineTokenGroup(tokens)`, wildcard-import friendly); everything
+* else lives in one chained `.config({...})` discriminated-union.
+*
+* The return value does double duty, the same way `BoundComponent` is
+* both a `ComponentDefinition` and an `FC`:
+*
+*  - it is the registerable group (`uds.registerAssetGroups({ icons })`
+*    reads `members` + config fields off it), and
+*  - it carries the embedded `__kind: 'assetGroup'` / `ref` tag that
+*    `isAssetGroupRef()` / `slot().accepts(...)` read.
+*
+* The `ref` slug is bound late: `registerAssetGroups` stamps the
+* registration key onto the object (the key IS the slug — same
+* late-binding precedent as `Component.registryKey`'s namespace
+* getter). Reading `ref` before registration throws — an unregistered
+* group has no identity to point at.
+*/
+/** Icon-class asset names are PascalCase identifiers — each asset class has its own naming rule (fonts use kebab-case below). */
+const PASCAL_CASE = /^[A-Z][A-Za-z0-9]*$/;
+/** Font-class asset names are kebab-case `FontID`s (`yas`, `centra-no2`). */
+const KEBAB_CASE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+/**
+* Component-shaped: a plain function component, or a forwardRef/memo
+* exotic (an object stamped with React's `$$typeof` symbol).
+*/
+function isComponentShaped(value) {
+	if (typeof value === "function") return true;
+	return typeof value === "object" && value !== null && typeof value.$$typeof === "symbol";
+}
+/**
+* Read and *sanitize* a member's static `.metadata`. The harvest is the
+* trust boundary for arbitrary wildcard imports, so loosely-shaped
+* fields are dropped rather than cast — `variants: 'outline'` must not
+* iterate char-by-char into `['o','u','t',…]` downstream.
+*/
+function readIconMetadata(value) {
+	if (typeof value !== "function" && typeof value !== "object") return;
+	if (value === null) return void 0;
+	const metadata = value.metadata;
+	if (metadata === null || typeof metadata !== "object") return void 0;
+	const raw = metadata;
+	const out = {};
+	if (typeof raw.name === "string" && raw.name.length > 0) out.name = raw.name;
+	if (typeof raw.isSvgIcon === "boolean") out.isSvgIcon = raw.isSvgIcon;
+	if (isStringArray(raw.variants)) out.variants = raw.variants;
+	if (typeof raw.category === "string") out.category = raw.category;
+	if (isStringArray(raw.tags)) out.tags = raw.tags;
+	return out;
+}
+function isStringArray(value) {
+	return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+/**
+* Icon-class harvest. Wildcard `import * as` carries everything a
+* package exports — helpers, constants, possibly `default` — so
+* non-matching exports are *skipped*, not errors:
+*
+*  - `.metadata.isSvgIcon === true` is definitive — the member is an
+*    icon (named via `.metadata.name`, falling back to the export key).
+*  - `.metadata.isSvgIcon === false` is the explicit opt-out — skipped.
+*    Unrelated metadata (no `isSvgIcon` field) does NOT opt out; the
+*    convention below still applies, so one foreign metadata shape
+*    can't silently shrink the harvest.
+*  - Otherwise the documented convention applies: PascalCase export
+*    key + component-shaped value (covers metadata-less Phosphor-style
+*    libraries).
+*  - `default` is never registered literally — it registers only when
+*    explicit icon metadata supplies a usable PascalCase name (i.e. it
+*    gets renamed), and is otherwise skipped as wildcard noise. This
+*    deliberately includes an explicit-icon `default` whose
+*    `.metadata.name` fails the PascalCase rule: it is *skipped*, not
+*    thrown — unlike the same mistake on a named export (below). A
+*    `default` carries no authored intent to register under a literal
+*    name, so an unusable name on it is noise, not an author error.
+*
+* The loud failures inside the skip-friendly walk: an explicit icon
+* (`isSvgIcon: true`) on a *named* export whose resolved name fails the
+* PascalCase rule, or two members resolving to the same name — both
+* are author errors, not wildcard noise.
+*/
+function harvestIconMembers(raw, include) {
+	const members = {};
+	const memberMetadata = {};
+	for (const [key, value] of Object.entries(raw)) {
+		if (include && !include(key)) continue;
+		if (!isComponentShaped(value)) continue;
+		const metadata = readIconMetadata(value);
+		const isExplicitIcon = metadata?.isSvgIcon === true;
+		if (metadata?.isSvgIcon === false) continue;
+		const name = isExplicitIcon ? metadata?.name ?? key : key;
+		if (key === "default") {
+			if (!isExplicitIcon || !PASCAL_CASE.test(name)) continue;
+		} else if (!isExplicitIcon) {
+			if (!PASCAL_CASE.test(key)) continue;
+		} else if (!PASCAL_CASE.test(name)) throw new Error(`defineAssetGroup: icon member "${key}" resolves to asset name "${name}", which is not a PascalCase identifier — icon asset names become the asset-id name segment. Rename the export or set \`.metadata.name\`.`);
+		if (members[name] !== void 0) throw new Error(`defineAssetGroup: two icon members resolve to the asset name "${name}" — asset names must be unique within a group.`);
+		members[name] = value;
+		memberMetadata[name] = metadata ?? {};
+	}
+	if (Object.keys(members).length === 0) throw new Error("defineAssetGroup: no icon members harvested — expected PascalCase component exports (or components carrying `.metadata.isSvgIcon`). For a font group, declare `.config({ type: 'font' })`.");
+	return {
+		members,
+		memberMetadata
+	};
+}
+/**
+* Font-class guard. Unlike the icon wildcard filter, font members come
+* from an explicit data map where every entry is intended — a member
+* failing the class contract (`fontFamily` + `declarations[]`) is a
+* named config-load error, never a silent skip.
+*/
+function guardFontMembers(raw) {
+	const members = {};
+	for (const [key, value] of Object.entries(raw)) {
+		if (!KEBAB_CASE.test(key)) throw new Error(`defineAssetGroup: font member "${key}" is not a kebab-case FontID — font asset names become the asset-id name segment (e.g. "yas", "centra-no2").`);
+		const record = value;
+		const fontFamily = record?.fontFamily;
+		const declarations = record?.declarations;
+		if (typeof fontFamily !== "string" || fontFamily.length === 0) throw new Error(`defineAssetGroup: font member "${key}" fails the 'font' class contract — missing a non-empty \`fontFamily\` string.`);
+		if (!Array.isArray(declarations)) throw new Error(`defineAssetGroup: font member "${key}" fails the 'font' class contract — missing a \`declarations\` array.`);
+		members[key] = value;
+	}
+	if (Object.keys(members).length === 0) throw new Error("defineAssetGroup: font group has no members — pass the font declarations map (e.g. FONT_DECLARATIONS_MAP).");
+	return members;
+}
+/**
+* Variant superset when `config.variants` is omitted: the harvested
+* union of members' `.metadata.variants`, first-seen order.
+*/
+function deriveVariantUnion(memberMetadata) {
+	const union = [];
+	for (const metadata of Object.values(memberMetadata)) for (const variant of metadata.variants ?? []) if (!union.includes(variant)) union.push(variant);
+	return union;
+}
+/** Internal slug slot the late-bound `ref` getter reads. @internal */
+const ASSET_GROUP_SLUG_KEY = "__slug";
+/**
+* Safe slug read for error messages — never throws, unlike the `ref`
+* getter. Returns `undefined` for an unregistered group. @internal
+*/
+function readAssetGroupSlug(value) {
+	if (typeof value !== "object" || value === null) return void 0;
+	const slug = value[ASSET_GROUP_SLUG_KEY];
+	return typeof slug === "string" ? slug : void 0;
+}
+function defineHidden(target, key, value) {
+	Object.defineProperty(target, key, {
+		enumerable: false,
+		configurable: true,
+		writable: true,
+		value
+	});
+}
+/**
+* Stamp the invariant `__kind: 'assetGroup'` ref tag. Deliberately
+* deferred to the end of `.config()` so an unconfigured builder never
+* passes `isAssetGroupRef()` — the guard's truth implies a complete,
+* registerable group.
+*/
+function stampRefTag(target) {
+	Object.defineProperty(target, "__kind", {
+		enumerable: false,
+		configurable: true,
+		writable: false,
+		value: "assetGroup"
+	});
+}
+/**
+* Attach icon metadata to a single one-off icon and hand it back
+* unchanged. `isSvgIcon: true` is implied —
+* the point of the call is to mark the component as an icon so the
+* group harvest picks it up. Slots still point at the *group*, never
+* at this.
+*/
+function defineAssetIcon(component, metadata) {
+	Object.defineProperty(component, "metadata", {
+		enumerable: true,
+		configurable: true,
+		writable: true,
+		value: {
+			isSvgIcon: true,
+			...metadata
+		}
+	});
+	return component;
+}
+function defineAssetGroup(members) {
+	const out = {};
+	attachSourcePath(out, captureCallerPath());
+	Object.defineProperty(out, ASSET_GROUP_SLUG_KEY, {
+		enumerable: false,
+		configurable: true,
+		writable: true,
+		value: void 0
+	});
+	Object.defineProperty(out, "ref", {
+		enumerable: false,
+		configurable: true,
+		get() {
+			const slug = readAssetGroupSlug(out);
+			if (slug === void 0) throw new Error("AssetGroup.ref read before registration — the slug is late-bound from the `registerAssetGroups({ <slug>: group })` record key. Register the group first.");
+			return slug;
+		}
+	});
+	Object.defineProperty(out, "config", {
+		enumerable: false,
+		configurable: true,
+		writable: true,
+		value(config) {
+			if (out.assetKind !== void 0) throw new Error("defineAssetGroup: .config({...}) may only be called once per group.");
+			if (config.label !== void 0) out.label = config.label;
+			if (config.description !== void 0) out.description = config.description;
+			if (config.type === "font") {
+				const fontMembers = guardFontMembers(members);
+				out.assetKind = "font";
+				defineHidden(out, "members", fontMembers);
+				stampRefTag(out);
+				return out;
+			}
+			let resolvedSizes = config.sizes;
+			let resolvedVariants = config.variants;
+			if (config.props !== void 0) {
+				if (config.sizes !== void 0 || config.variants !== void 0) throw new Error("defineAssetGroup: `props` cannot be combined with the flat `sizes`/`variants` fields — use one or the other.");
+				const mapEntries = [];
+				const arrayEntries = [];
+				for (const [key, value] of Object.entries(config.props)) {
+					if (value === void 0) continue;
+					if (Array.isArray(value)) arrayEntries.push([key, value]);
+					else if (typeof value === "object" && value !== null) mapEntries.push([key, value]);
+					else throw new Error(`defineAssetGroup: \`props.${key}\` must be a named→px map (size axis) or an array (variant axis).`);
+				}
+				if (mapEntries.length !== 1) throw new Error("defineAssetGroup: `props` requires exactly one named→px map entry (the size axis).");
+				if (arrayEntries.length > 1) throw new Error("defineAssetGroup: `props` supports at most one array entry (the variant axis) — the serialized format holds a single variant axis.");
+				const [, sizeMap] = mapEntries[0];
+				resolvedSizes = sizeMap;
+				if (arrayEntries.length === 1) {
+					const [, variantValues] = arrayEntries[0];
+					resolvedVariants = variantValues;
+				}
+			}
+			if (resolvedSizes === void 0 || Object.keys(resolvedSizes).length === 0) throw new Error("defineAssetGroup: icon groups require a non-empty `sizes` map (named size → px) — declare it via `props: { size: {…} }` or the flat `sizes` field. The picker derives its size options from the keys.");
+			const { members: harvested, memberMetadata } = harvestIconMembers(members, config.include);
+			out.assetKind = "icon";
+			defineHidden(out, "members", harvested);
+			defineHidden(out, "memberMetadata", memberMetadata);
+			out.sizes = { ...resolvedSizes };
+			out.variants = resolvedVariants ? [...resolvedVariants] : deriveVariantUnion(memberMetadata);
+			const componentName = isComponentRef(config.component) ? config.component.ref : config.component;
+			if (componentName !== void 0) out.component = componentName;
+			stampRefTag(out);
+			return out;
+		}
+	});
+	return out;
+}
+//#endregion
+export { ASSET_GROUP_SLUG_KEY, defineAssetGroup, defineAssetIcon, readAssetGroupSlug };

package/dist/config/dist/defineProvider.d.ts

@@ -0,0 +1,30 @@
+import { ProviderComponent, ProviderRenderFn } from "./factories.js";
+
+//#region ../config/dist/defineProvider.d.ts
+//#region src/defineProvider.d.ts
+/**
+ * Pair a React context with a Provider component + matching hook in
+ * one declaration. The render-fn receives the props, returns
+ * `{ context, render }` — `context` is what the hook returns; `render`
+ * is the JSX (typically `<>{children}<Portal /></>` and similar).
+ *
+ *     export const [ToastProvider, useToast] = defineProvider<ToastCtx>(
+ *       ({ children }) => {
+ *         const [toasts, setToasts] = useState<ToastItem[]>([]);
+ *         return {
+ *           context: { addToast, dismissToast, updateToast },
+ *           render: <>{children}<Portal /></>,
+ *         };
+ *       },
+ *     );
+ *
+ *     uds.registerProviders({ ToastProvider });
+ *
+ * Lives in its own module so the React (`createContext`) imports don't
+ * land in the static graph of every consumer importing `@uds/config`
+ * — Turbopack flags `createContext` reaching a server-component module
+ * as an error.
+ */
+declare function defineProvider<TContext, TProps = Record<never, never>>(renderFn: ProviderRenderFn<TContext, TProps>): [ProviderComponent<TProps>, () => TContext]; //#endregion
+//#endregion
+export { defineProvider };

package/dist/config/dist/defineProvider.js

@@ -0,0 +1,60 @@
+"use client";
+import { attachSourcePath, captureCallerPath } from "./captureCallerPath.js";
+import { createContext, createElement, useContext } from "react";
+//#region ../config/dist/defineProvider.js
+/**
+* Pair a React context with a Provider component + matching hook in
+* one declaration. The render-fn receives the props, returns
+* `{ context, render }` — `context` is what the hook returns; `render`
+* is the JSX (typically `<>{children}<Portal /></>` and similar).
+*
+*     export const [ToastProvider, useToast] = defineProvider<ToastCtx>(
+*       ({ children }) => {
+*         const [toasts, setToasts] = useState<ToastItem[]>([]);
+*         return {
+*           context: { addToast, dismissToast, updateToast },
+*           render: <>{children}<Portal /></>,
+*         };
+*       },
+*     );
+*
+*     uds.registerProviders({ ToastProvider });
+*
+* Lives in its own module so the React (`createContext`) imports don't
+* land in the static graph of every consumer importing `@uds/config`
+* — Turbopack flags `createContext` reaching a server-component module
+* as an error.
+*/
+function defineProvider(renderFn) {
+	const Context = createContext(null);
+	const marker = {};
+	function Provider(props) {
+		const result = renderFn(props);
+		return createElement(Context.Provider, { value: result.context }, result.render);
+	}
+	Provider.displayName = "Provider";
+	Object.defineProperty(Provider, "__udsProvider", {
+		enumerable: false,
+		configurable: true,
+		writable: false,
+		value: marker
+	});
+	function useProviderContext() {
+		let ctx;
+		try {
+			ctx = useContext(Context);
+		} catch {
+			return {};
+		}
+		if (ctx === null) {
+			const name = marker.name ?? "Provider";
+			const hookName = name.replace(/Provider$/, "");
+			throw new Error(`use${hookName} must be used within ${name}`);
+		}
+		return ctx;
+	}
+	attachSourcePath(Provider, captureCallerPath());
+	return [Provider, useProviderContext];
+}
+//#endregion
+export { defineProvider };

package/dist/config/dist/element-marker.d.ts

@@ -0,0 +1,55 @@
+//#region ../config/dist/element-marker.d.ts
+//#region src/element-marker.d.ts
+declare const ELEMENT_MARKER_KIND = "element";
+/** Serializable stand-in for a React element authored as a preview prop value. */
+interface ElementMarker {
+  readonly __kind: typeof ELEMENT_MARKER_KIND;
+  /**
+   * Registry-resolvable type — `foreign:<Name>` for a third-party leaf,
+   * a registered UDS component's name, or an intrinsic tag (`'svg'`).
+   */
+  readonly type: string;
+  /** Author-set element key (preserved so revived list children stay keyed). */
+  readonly key?: string;
+  /** Serialized props; a nested element value is itself an `ElementMarker`. */
+  readonly props?: Record<string, unknown>;
+}
+declare function isElementMarker(value: unknown): value is ElementMarker;
+/**
+ * A live React element or its `$$typeof`-less husk. `Config.toJSON` runs on the
+ * in-memory config, where preview elements are still live (carry `$$typeof`);
+ * the husk shape (`_owner`/`_store`, no live `type`) only appears after a
+ * structuredClone/JSON round-trip and is matched here defensively.
+ */
+declare function isElementLikeValue(value: unknown): boolean;
+/**
+ * Treat a matched object as an opaque leaf the deep walk stops at, rather than
+ * recursing into it. The walks run at render time, where a prop may already
+ * hold a live React element whose `_owner` fiber chain is circular — descending
+ * into one never terminates, and it can't contain an un-revived marker anyway.
+ * Defaults to {@link isElementLikeValue}.
+ */
+type OpaqueLeafPredicate = (value: object) => boolean;
+/**
+ * Does `value` hold an {@link ElementMarker} anywhere in its plain-data subtree?
+ * Lets a caller skip the revive walk entirely (and keep prop references stable)
+ * when there's nothing to revive.
+ */
+declare function hasElementMarkerDeep(value: unknown, isOpaqueLeaf?: OpaqueLeafPredicate): boolean;
+/**
+ * Inverse of {@link serializeElementsDeep}: deep-walk `value` and turn each
+ * {@link ElementMarker} into a renderable node via `renderMarker`, preserving
+ * the surrounding plain data (arrays, objects). A marker's OWN props are left
+ * for `renderMarker` to handle — they are not pre-revived here, so a marker
+ * nested inside another marker's props stays inert until its enclosing marker
+ * renders. This mirrors how `$slot` resolution defers and avoids handing a live
+ * element (circular `_owner`) back into a renderer that deep-walks props.
+ *
+ * `renderMarker` is the framework seam — studio renders each marker through its
+ * preview `UdsRenderer`; the playground does the same with its bundled renderer.
+ * Guard with {@link hasElementMarkerDeep} to preserve referential stability for
+ * marker-free values (this walk always rebuilds the containers it descends).
+ */
+declare function reviveElementMarkersDeep(value: unknown, renderMarker: (marker: ElementMarker) => unknown, isOpaqueLeaf?: OpaqueLeafPredicate): unknown; //#endregion
+//#endregion
+export { ELEMENT_MARKER_KIND, ElementMarker, OpaqueLeafPredicate, hasElementMarkerDeep, isElementLikeValue, isElementMarker, reviveElementMarkersDeep };

package/dist/config/dist/element-marker.js

@@ -0,0 +1,113 @@
+import { foreignRegistryKey } from "./foreign-component-name.js";
+//#region ../config/dist/element-marker.js
+const ELEMENT_MARKER_KIND = "element";
+function isElementMarker(value) {
+	return value !== null && typeof value === "object" && value.__kind === "element" && typeof value.type === "string";
+}
+/**
+* A live React element or its `$$typeof`-less husk. `Config.toJSON` runs on the
+* in-memory config, where preview elements are still live (carry `$$typeof`);
+* the husk shape (`_owner`/`_store`, no live `type`) only appears after a
+* structuredClone/JSON round-trip and is matched here defensively.
+*/
+function isElementLikeValue(value) {
+	return value !== null && typeof value === "object" && ("$$typeof" in value || "_owner" in value || "_store" in value);
+}
+/**
+* The registry key for a React element's `type`: a UDS component's stamped
+* `__componentName`, a `foreign:<Name>` for a `forwardRef`/`memo` leaf, an
+* intrinsic tag string, or a plain function component's display/name. Returns
+* `null` when the type can't be named (an anonymous wrapper) — the caller then
+* drops the value rather than emit an unresolvable marker.
+*/
+function elementTypeName(type) {
+	if (typeof type === "string") return type;
+	if (!(type !== null && (typeof type === "object" || typeof type === "function"))) return null;
+	const udsName = type.__componentName;
+	if (typeof udsName === "string") return udsName;
+	const foreign = foreignRegistryKey(type);
+	if (foreign !== null) return foreign;
+	if (typeof type === "function") {
+		const fn = type;
+		if (typeof fn.displayName === "string" && fn.displayName.length > 0) return fn.displayName;
+		if (typeof fn.name === "string" && fn.name.length > 0) return fn.name;
+	}
+	return null;
+}
+function elementToMarker(element) {
+	const el = element;
+	const type = elementTypeName(el.type);
+	if (type === null) return void 0;
+	const marker = {
+		__kind: ELEMENT_MARKER_KIND,
+		type
+	};
+	if (typeof el.key === "string") marker.key = el.key;
+	if (el.props !== null && typeof el.props === "object") {
+		const props = serializeElementsDeep(el.props);
+		if (Object.keys(props).length > 0) marker.props = props;
+	}
+	return marker;
+}
+/**
+* Deeply convert every React element value to an {@link ElementMarker},
+* preserving the surrounding plain data (axis markers, primitive props, nested
+* arrays/objects). A value that can't be named drops out (`undefined`), so an
+* anonymous wrapper or a clone-stripped husk is removed rather than serialized
+* into something unrenderable. Already-serialized markers carry none of the
+* element internals {@link isElementLikeValue} matches, so they pass through.
+*/
+function serializeElementsDeep(value) {
+	if (isElementLikeValue(value)) return elementToMarker(value);
+	if (Array.isArray(value)) return value.map(serializeElementsDeep).filter((entry) => entry !== void 0);
+	if (value !== null && typeof value === "object") {
+		const out = {};
+		for (const [key, entry] of Object.entries(value)) {
+			const cleaned = serializeElementsDeep(entry);
+			if (cleaned !== void 0) out[key] = cleaned;
+		}
+		return out;
+	}
+	return value;
+}
+/**
+* Does `value` hold an {@link ElementMarker} anywhere in its plain-data subtree?
+* Lets a caller skip the revive walk entirely (and keep prop references stable)
+* when there's nothing to revive.
+*/
+function hasElementMarkerDeep(value, isOpaqueLeaf = isElementLikeValue) {
+	if (isElementMarker(value)) return true;
+	if (Array.isArray(value)) return value.some((entry) => hasElementMarkerDeep(entry, isOpaqueLeaf));
+	if (value !== null && typeof value === "object") {
+		if (isOpaqueLeaf(value)) return false;
+		return Object.values(value).some((entry) => hasElementMarkerDeep(entry, isOpaqueLeaf));
+	}
+	return false;
+}
+/**
+* Inverse of {@link serializeElementsDeep}: deep-walk `value` and turn each
+* {@link ElementMarker} into a renderable node via `renderMarker`, preserving
+* the surrounding plain data (arrays, objects). A marker's OWN props are left
+* for `renderMarker` to handle — they are not pre-revived here, so a marker
+* nested inside another marker's props stays inert until its enclosing marker
+* renders. This mirrors how `$slot` resolution defers and avoids handing a live
+* element (circular `_owner`) back into a renderer that deep-walks props.
+*
+* `renderMarker` is the framework seam — studio renders each marker through its
+* preview `UdsRenderer`; the playground does the same with its bundled renderer.
+* Guard with {@link hasElementMarkerDeep} to preserve referential stability for
+* marker-free values (this walk always rebuilds the containers it descends).
+*/
+function reviveElementMarkersDeep(value, renderMarker, isOpaqueLeaf = isElementLikeValue) {
+	if (isElementMarker(value)) return renderMarker(value);
+	if (Array.isArray(value)) return value.map((entry) => reviveElementMarkersDeep(entry, renderMarker, isOpaqueLeaf));
+	if (value !== null && typeof value === "object") {
+		if (isOpaqueLeaf(value)) return value;
+		const out = {};
+		for (const [key, entry] of Object.entries(value)) out[key] = reviveElementMarkersDeep(entry, renderMarker, isOpaqueLeaf);
+		return out;
+	}
+	return value;
+}
+//#endregion
+export { ELEMENT_MARKER_KIND, hasElementMarkerDeep, isElementLikeValue, isElementMarker, reviveElementMarkersDeep, serializeElementsDeep };

package/dist/config/dist/entity-utils.d.ts

@@ -0,0 +1,27 @@
+//#region ../config/dist/entity-utils.d.ts
+/**
+ * Build a `tokenRef → 'var(--<prefix>-<ns>-<name>)'` resolver — the callback
+ * `resolveColorExpression` consumes to turn `token('ns/name')` refs into CSS var
+ * references. Splits a ref on its FIRST slash into namespace + name; a ref with
+ * no usable slash passes through unchanged (already a literal).
+ *
+ * The single source of truth shared by the config render-spec bake and codegen
+ * (`tokenValue.ts`, `prepareCss.ts`), so config-baked and codegen-emitted CSS
+ * stay byte-identical. The name segment uses the `@uds/utils` `safeTokenName`
+ * transform (dots→`_`, slashes→`-`) — NOT `cssSafeSegment` (which also
+ * kebab-cases) — so multi-segment paths like `spectrum/carbon/0` resolve to a
+ * valid `--<prefix>-spectrum-carbon-0`.
+ */
+declare function makeTokenRefToCss(prefix: string | undefined): (ref: string) => string;
+/**
+ * Build a composite style's CSS class name: `<prefix>-<name>-<variant>`.
+ * Both name/variant segments are sanitized so subpath variants like
+ * `ui5/emphasized` emit `.yos-text-variant-ui5-emphasized` instead of an
+ * invalid `.text-variant-ui5/emphasized` (which the browser splits at `/`).
+ *
+ * The `prefix` namespaces the class the same way it namespaces CSS
+ * variables and component classes (`componentClassNames`) — an empty
+ * prefix yields the bare, unprefixed form.
+ */
+//#endregion
+export { makeTokenRefToCss };

package/dist/config/dist/entity-utils.js

@@ -0,0 +1,105 @@
+import { cssClassName, cssVar } from "./brands.js";
+//#region ../config/dist/entity-utils.js
+/**
+* Shared helpers used by entity `.derived` getters.
+*/
+/**
+* Kebab-case a single identifier. Inserts a hyphen at each upper-case
+* boundary and lower-cases the result. Single-segment only — for slashed
+* `'namespace/name'` paths, kebab each segment separately.
+*/
+function kebabCase(value) {
+	return value.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/([A-Z])([A-Z][a-z])/g, "$1-$2").toLowerCase();
+}
+/**
+* Kebab-case + sanitize a single identifier for use inside a CSS custom
+* property name or class name. Dots become `_` and slashes become `-`
+* (so `1.5` → `1_5`, `1/2` → `1-2`, `ui5/emphasized` → `ui5-emphasized`).
+* Mirrors the `safeTokenName` transform used by the runtime styler in
+* `@uds/utils`, so codegen-declared identifiers and runtime-referenced
+* identifiers stay in lockstep.
+*/
+function cssSafeSegment(value) {
+	return kebabCase(value).replace(/\./g, "_").replace(/\//g, "-");
+}
+/**
+* Build a CSS variable name from a prefix + namespace + token name.
+* Each segment is kebab-cased; dots in the token name are mapped to
+* `_` and slashes to `-` since CSS custom-property identifiers reject
+* both `.` and `/` (so a `1.5` spacing token emits
+* `--<prefix>-spacing-1_5`, and a subpath token `1/2` or
+* `always/white` emits `--<prefix>-position-1-2` /
+* `--<prefix>-global-always-white` — both valid).
+*/
+function buildCssVar(prefix, namespace, name) {
+	return cssVar(`--${prefix}-${kebabCase(namespace)}-${cssSafeSegment(name)}`);
+}
+/**
+* Build a `tokenRef → 'var(--<prefix>-<ns>-<name>)'` resolver — the callback
+* `resolveColorExpression` consumes to turn `token('ns/name')` refs into CSS var
+* references. Splits a ref on its FIRST slash into namespace + name; a ref with
+* no usable slash passes through unchanged (already a literal).
+*
+* The single source of truth shared by the config render-spec bake and codegen
+* (`tokenValue.ts`, `prepareCss.ts`), so config-baked and codegen-emitted CSS
+* stay byte-identical. The name segment uses the `@uds/utils` `safeTokenName`
+* transform (dots→`_`, slashes→`-`) — NOT `cssSafeSegment` (which also
+* kebab-cases) — so multi-segment paths like `spectrum/carbon/0` resolve to a
+* valid `--<prefix>-spectrum-carbon-0`.
+*/
+function makeTokenRefToCss(prefix) {
+	return (ref) => {
+		const slashIdx = ref.indexOf("/");
+		if (slashIdx <= 0 || slashIdx >= ref.length - 1) return ref;
+		const namespace = kebabCase(ref.slice(0, slashIdx));
+		const name = ref.slice(slashIdx + 1).replace(/\./g, "_").replace(/\//g, "-");
+		return prefix ? `var(--${prefix}-${namespace}-${name})` : `var(--${namespace}-${name})`;
+	};
+}
+/**
+* Build a composite style's CSS class name: `<prefix>-<name>-<variant>`.
+* Both name/variant segments are sanitized so subpath variants like
+* `ui5/emphasized` emit `.yos-text-variant-ui5-emphasized` instead of an
+* invalid `.text-variant-ui5/emphasized` (which the browser splits at `/`).
+*
+* The `prefix` namespaces the class the same way it namespaces CSS
+* variables and component classes (`componentClassNames`) — an empty
+* prefix yields the bare, unprefixed form.
+*/
+function buildCompositeClassName(prefix, name, variant) {
+	const body = `${cssSafeSegment(name)}-${cssSafeSegment(variant)}`;
+	return cssClassName(prefix ? `${prefix}-${body}` : body);
+}
+/**
+* Build the marker custom-property name a composite group writes (and
+* its container style queries read): `--<prefix>-composite-<kebab-name>`.
+* Single source of truth — the setter emission and `@container style(...)`
+* query both consume this so they stay in lockstep.
+*/
+function buildCompositeMarkerVarName(prefix, name) {
+	return cssVar(`--${prefix}-composite-${kebabCase(name)}`);
+}
+/**
+* Token names that aren't valid CSS identifiers (`2xl`, `3xs`) get an
+* underscore prefix so they survive in CSS contexts. Dots are mapped
+* to `_` and slashes to `-` — `1.5` would otherwise produce a class
+* string the browser splits at the dot (`class="text-1.5"` parses as
+* `.text-1` and `.5`), and a subpath token like `1/2` would emit
+* `text-1/2` which the browser treats as `.text-1` followed by
+* `/2`. Mirrors `safeTokenName` from `@uds/utils`.
+*/
+function toCssSafeName(name) {
+	return cssClassName(cssSafeSegment(/^[0-9]/.test(name) ? `_${name}` : name));
+}
+/**
+* Filter undefined fields out of a partial object literal so optional
+* authored properties don't show up as `key: undefined` in `toJSON()`
+* output. Mirrors the pattern used by `@uds/config` `defineX` builders.
+*/
+function compact(input) {
+	const out = {};
+	for (const [key, value] of Object.entries(input)) if (value !== void 0) out[key] = value;
+	return out;
+}
+//#endregion
+export { buildCompositeClassName, buildCompositeMarkerVarName, buildCssVar, compact, cssSafeSegment, kebabCase, makeTokenRefToCss, toCssSafeName };