@yahoo/uds-v5-wip 1.60.0 → 1.62.0

package/dist/config/dist/markers.d.ts

@@ -0,0 +1,218 @@
+import { AssetGroupRef } from "./refs.js";
+import { ComponentDefinition } from "./types.js";
+
+//#region ../config/dist/markers.d.ts
+//#region src/markers.d.ts
+/**
+ * A slot's `.accepts(...)` argument: a registered component definition, or a
+ * placeable asset group returned by `defineAssetGroup(...).config(...)` (it
+ * carries the `AssetGroupRef` tag). The two are kept distinct downstream —
+ * component names land on `SlotInfo.accepts`, the asset-group slug on
+ * `SlotInfo.acceptsAssetGroup` — so the designer panel can pick the right
+ * picker. Non-placeable groups (fonts) are admitted by the type but rejected
+ * at config load.
+ */
+type SlotAccepts = ComponentDefinition | AssetGroupRef;
+/**
+ * Brand applied to a marker by `.required()`. Lives alongside the
+ * marker interfaces so the slot factories (whose `.required()`
+ * implementation is co-located with `.accepts()` rather than going
+ * through `attachRequired`) can return the brand-narrowed type via
+ * the interface signature.
+ *
+ * `RenderPropsFromConfig` reads this brand to decide whether a render-
+ * fn destructure entry is optional (`T | undefined`) or non-optional
+ * (`T`). Distinct from `__required?: boolean` on the marker bodies —
+ * that field is the runtime flag codegen reads; the brand is the
+ * compile-time signal the render-arg type-flow keys on.
+ */
+type RequiredBrand = {
+  __required: true;
+};
+/**
+ * Author-declared slot value kind. A slot holds renderable content; the only
+ * explicit kind is text:
+ *
+ *   - `'string'` — plain text content (e.g. Button's `children` label).
+ *
+ * An open `slot()` is a node container (`ReactNode`) by default — it accepts
+ * dropped layers and is narrowed to specific components via `.accepts(...)`;
+ * `'string'` instead marks a text surface, so tools like the Studio canvas
+ * inline-edit it rather than treat it as a reparent target. Scalars like
+ * boolean and number are *not* slots — use the dedicated `bool()` / `number()`
+ * markers. (A `'string'` slot still *resolves* to `SlotValueKind: 'ReactNode'`,
+ * since a string is a valid `ReactNode`; `authoredType` records the intent.)
+ *
+ *   - `'component'` — the slot resolves to a `FunctionComponent`, not rendered
+ *     content. Used by the aliased `Icon` pattern (`name: slot({ type:
+ *     'component' }).accepts(icons)`), where the render fn receives the icon
+ *     component itself (`({ name: SvgIcon }) => <SvgIcon … />`) and the saved
+ *     value is the inline asset-name string (`"Trophy"`), not a `$slot` ref.
+ *     A `'component'` slot *requires* an asset-group `.accepts(...)` — config
+ *     load throws otherwise.
+ */
+type SlotValueType = 'string' | 'component';
+/**
+ * Open-slot marker — `slot()` with no arguments. Codegen treats it as
+ * `ReactNode` accepted at the component's own children. Carries no
+ * cross-reference; `__accepts` / `__required` may still be set via the
+ * chain methods to constrain the slot's children or mark it required.
+ * `__valueType` records an explicit `slot({ type })` override (absent ⇒
+ * the default `ReactNode`).
+ */
+interface SlotMarker {
+  readonly __kind: 'slot';
+  readonly __required?: boolean;
+  readonly __accepts?: readonly SlotAccepts[];
+  readonly __valueType?: SlotValueType;
+  /**
+   * Stamp `__required: true` on the marker. Codegen reads this per-prop
+   * and emits the JSX prop without a trailing `?`, so the slot becomes
+   * mandatory at call sites. The return type also intersects
+   * `RequiredBrand` so `RenderPropsFromConfig` narrows the render-fn
+   * destructure entry to non-optional.
+   */
+  required(): SlotMarker & RequiredBrand;
+  /**
+   * Constrain the slot's accepted children to one or more registered
+   * components, or to a placeable asset group (`slot().accepts(icons)`).
+   */
+  accepts(component: SlotAccepts | readonly SlotAccepts[]): SlotMarker;
+}
+/**
+ * A `slot({ type: 'component' })` marker — the aliased `Icon` pattern. Carries
+ * the literal `__valueType: 'component'` so `ResolveMarker` resolves the prop
+ * to a `ComponentType` (the render fn receives the icon component itself), and
+ * narrows `.accepts(...)` to asset groups only (a component-typed slot must
+ * accept an asset group). The chained `.accepts(...)` preserves this type so
+ * the literal survives to the render-fn inference.
+ */
+interface ComponentSlotMarker extends SlotMarker {
+  readonly __valueType: 'component';
+  accepts(group: AssetGroupRef | readonly AssetGroupRef[]): ComponentSlotMarker;
+}
+/**
+ * Layer-targeting slot ref — `slot('layer')`, `slot('layer/prop')`, or
+ * `slot('layer', { prop })`. Routes a JSX prop into the named layer's
+ * `layerProp` (defaults to `'children'` when only a layer is given).
+ * The `layer` field is the cross-reference — that's what makes this a
+ * Ref rather than a Marker.
+ */
+interface SlotRef<TLayer extends string = string, TAs extends string = string> {
+  readonly __kind: 'slot';
+  readonly layer: TLayer;
+  readonly layerProp: TAs;
+  readonly __required?: boolean;
+  readonly __accepts?: readonly SlotAccepts[];
+  /** Output adapter set via `.transform(fn)` — codegen wraps the
+   *  layer's prop so the consumer-facing handler receives `fn(arg)`
+   *  instead of the raw layer value (e.g. an input event → its
+   *  string value). Must be self-contained (no closure over outer
+   *  scope) since codegen lifts it into the generated module. */
+  readonly __transform?: (arg: never) => unknown;
+  readonly __valueType?: SlotValueType;
+  required(): SlotRef<TLayer, TAs> & RequiredBrand;
+  accepts(component: SlotAccepts | readonly SlotAccepts[]): SlotRef<TLayer, TAs>;
+  transform<Out>(fn: (arg: unknown) => Out): SlotRef<TLayer, TAs> & {
+    readonly __transformOut: Out;
+  };
+}
+/**
+ * Runtime guard for any slot binding (open marker or layered ref).
+ * Callers that need to distinguish the two forms narrow further by
+ * checking for the `layer` field — `'layer' in value`.
+ */
+declare function isSlotMarker(value: unknown): value is SlotMarker | SlotRef;
+interface BooleanMarker {
+  readonly __kind: 'boolean';
+  readonly __required?: boolean;
+  readonly values?: {
+    true?: Record<string, Record<string, unknown>>;
+    false?: Record<string, Record<string, unknown>>;
+  };
+}
+declare function isBoolMarker(value: unknown): value is BooleanMarker;
+interface VariantMarkerObject<V extends Record<string, Record<string, unknown>> = Record<string, Record<string, unknown>>> {
+  readonly __kind: 'variant';
+  readonly __required?: boolean;
+  readonly values: V;
+  readonly default?: keyof V & string;
+}
+interface VariantMarkerArray<V extends readonly (string | number)[] = readonly (string | number)[]> {
+  readonly __kind: 'variant';
+  readonly __required?: boolean;
+  readonly values: V;
+  readonly default?: V[number];
+}
+type VariantMarker<V = unknown> = V extends readonly (string | number)[] ? VariantMarkerArray<V> : V extends Record<string, Record<string, unknown>> ? VariantMarkerObject<V> : VariantMarkerObject | VariantMarkerArray;
+declare function isVariantMarker(value: unknown): value is VariantMarker;
+/**
+ * Distinguish the two variant forms. `Array.isArray(marker.values)` is the
+ * single source of truth — every downstream consumer that branches on
+ * the form goes through this helper rather than duplicating the check.
+ */
+declare function isVariantArrayMarker(value: VariantMarker): value is VariantMarkerArray;
+interface StringMarker {
+  readonly __kind: 'string';
+  readonly __required?: boolean;
+}
+interface NumberMarker {
+  readonly __kind: 'number';
+  readonly __required?: boolean;
+}
+declare function isStringMarker(value: unknown): value is StringMarker;
+declare function isNumberMarker(value: unknown): value is NumberMarker;
+interface LayerMarker {
+  readonly __kind: 'layer';
+  readonly layer: string;
+  readonly styles: Record<string, unknown>;
+}
+declare function isLayerMarker(value: unknown): value is LayerMarker;
+/**
+ * One conditional override for a `props` axis: apply `props` to the cell
+ * when every key in `when` matches the cell's other-axis values. A rule
+ * with no `when` always applies (the base). Later matching rules win.
+ */
+interface PreviewPropsRule {
+  readonly when?: Readonly<Record<string, unknown>>;
+  readonly props: Readonly<Record<string, unknown>>;
+}
+/**
+ * Synthetic discriminator state a `props` axis compiles to, per axis side.
+ * The entry's label is the value. Codegen keys the merged spec's `$cond`
+ * on this, and the studio seeds it per cell — both derive it here so they
+ * never drift. (`columns`/`rows` entries are concatenated as sibling
+ * values of one dimension, so one key per side suffices.)
+ */
+declare const PREVIEW_SEED_KEY: {
+  readonly row: "__previewSeedRow";
+  readonly column: "__previewSeedCol";
+};
+/** True when every key in `when` equals the cell coordinate's value. */
+declare function matchesPreviewWhen(when: Readonly<Record<string, unknown>> | undefined, coord: Readonly<Record<string, unknown>>): boolean;
+/**
+ * Merge the `props` of every rule whose `when` matches `coord` (in order,
+ * so later matching rules win). Shared by codegen's combo enumeration and
+ * the studio's cell assembly so a `props` axis resolves identically.
+ */
+declare function resolvePreviewRules(rules: readonly PreviewPropsRule[], coord: Readonly<Record<string, unknown>>): Record<string, unknown>;
+interface PreviewAxisMarker {
+  readonly __kind: 'previewAxis';
+  /** Axis name — either a prop name or a `_${string}` modifier. */
+  readonly prop?: string;
+  readonly modifier?: string;
+  /**
+   * `props` axis rules — per-cell prop-override bags, optionally guarded
+   * by `when` against the other axes' values. Lets a preview vary
+   * render-extra data per cell (e.g. sample `value`) without declaring a
+   * config prop. Resolved against the cell coordinate by the studio and
+   * by codegen's combo enumeration.
+   */
+  readonly rules?: readonly PreviewPropsRule[];
+  readonly kind: 'prop' | 'modifier' | 'props';
+  readonly nested?: PreviewAxisMarker;
+  nest(child: PreviewAxisMarker): PreviewAxisMarker;
+}
+declare function isPreviewAxisMarker(value: unknown): value is PreviewAxisMarker; //#endregion
+//#endregion
+export { BooleanMarker, ComponentSlotMarker, LayerMarker, NumberMarker, PREVIEW_SEED_KEY, PreviewAxisMarker, PreviewPropsRule, RequiredBrand, SlotMarker, SlotRef, SlotValueType, StringMarker, VariantMarker, VariantMarkerArray, VariantMarkerObject, isBoolMarker, isLayerMarker, isNumberMarker, isPreviewAxisMarker, isSlotMarker, isStringMarker, isVariantArrayMarker, isVariantMarker, matchesPreviewWhen, resolvePreviewRules };

package/dist/config/dist/markers.js

@@ -0,0 +1,67 @@
+//#region ../config/dist/markers.js
+/**
+* Runtime guard for any slot binding (open marker or layered ref).
+* Callers that need to distinguish the two forms narrow further by
+* checking for the `layer` field — `'layer' in value`.
+*/
+function isSlotMarker(value) {
+	return typeof value === "object" && value !== null && value.__kind === "slot";
+}
+function isBoolMarker(value) {
+	return typeof value === "object" && value !== null && value.__kind === "boolean";
+}
+function isVariantMarker(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const v = value;
+	if (v.__kind !== "variant") return false;
+	return Array.isArray(v.values) || typeof v.values === "object";
+}
+/**
+* Distinguish the two variant forms. `Array.isArray(marker.values)` is the
+* single source of truth — every downstream consumer that branches on
+* the form goes through this helper rather than duplicating the check.
+*/
+function isVariantArrayMarker(value) {
+	return Array.isArray(value.values);
+}
+function isStringMarker(value) {
+	return typeof value === "object" && value !== null && value.__kind === "string";
+}
+function isNumberMarker(value) {
+	return typeof value === "object" && value !== null && value.__kind === "number";
+}
+function isLayerMarker(value) {
+	return typeof value === "object" && value !== null && value.__kind === "layer";
+}
+/**
+* Synthetic discriminator state a `props` axis compiles to, per axis side.
+* The entry's label is the value. Codegen keys the merged spec's `$cond`
+* on this, and the studio seeds it per cell — both derive it here so they
+* never drift. (`columns`/`rows` entries are concatenated as sibling
+* values of one dimension, so one key per side suffices.)
+*/
+const PREVIEW_SEED_KEY = {
+	row: "__previewSeedRow",
+	column: "__previewSeedCol"
+};
+/** True when every key in `when` equals the cell coordinate's value. */
+function matchesPreviewWhen(when, coord) {
+	if (!when) return true;
+	for (const key of Object.keys(when)) if (coord[key] !== when[key]) return false;
+	return true;
+}
+/**
+* Merge the `props` of every rule whose `when` matches `coord` (in order,
+* so later matching rules win). Shared by codegen's combo enumeration and
+* the studio's cell assembly so a `props` axis resolves identically.
+*/
+function resolvePreviewRules(rules, coord) {
+	const out = {};
+	for (const rule of rules) if (matchesPreviewWhen(rule.when, coord)) Object.assign(out, rule.props);
+	return out;
+}
+function isPreviewAxisMarker(value) {
+	return typeof value === "object" && value !== null && value.__kind === "previewAxis";
+}
+//#endregion
+export { PREVIEW_SEED_KEY, isBoolMarker, isLayerMarker, isNumberMarker, isPreviewAxisMarker, isSlotMarker, isStringMarker, isVariantArrayMarker, isVariantMarker, matchesPreviewWhen, resolvePreviewRules };

package/dist/config/dist/refs.d.ts

@@ -0,0 +1,159 @@
+//#region ../config/dist/refs.d.ts
+//#region src/refs.d.ts
+/**
+ * Cross-reference markers — the `{ __kind, ref }` shapes that appear in
+ * authored values and in the wire format. Each one represents "this
+ * position holds a pointer to another resource, not a literal."
+ *
+ * Naming:
+ *
+ *  - `<X>Name` — the string-side identifier (`'color/brand'`, `'Box'`).
+ *    Narrowed when the matching `Registered*` interface is augmented;
+ *    falls open to `string` otherwise.
+ *  - `<X>Ref` — the boxed marker shape `{ __kind, ref }` carrying an
+ *    `<X>Name`. Distinguishes a pointer from a literal at every position
+ *    that can hold either.
+ *  - `<x>()` — the helper that constructs an `<X>Ref` from an `<X>Name`.
+ *  - `is<X>Ref(value)` — type guard for use by the resolver and patch
+ *    system.
+ *
+ * # Augmented refs
+ *
+ * The `Registered*` interfaces below are augmentation seams that
+ * consumer codegen populates via `declare module '@uds/config' {
+ * interface Registered* { ... } }`. When augmented, each ref's `ref`
+ * field narrows to only valid references — `token('color/brand')` is OK
+ * but `token('color/nope')` is a compile error. When un-augmented (this
+ * package's own tests, fresh consumers before first build), the ref
+ * accepts any string — codegen narrows it later.
+ */
+interface RegisteredTokenGroups {}
+interface RegisteredModifiers<T> {}
+interface RegisteredModes {}
+interface RegisteredCompositeStyles {}
+interface RegisteredStyleProps {}
+interface RegisteredComponents {}
+interface RegisteredMotionDefs {}
+interface RegisteredAssetGroups {}
+/** `<groupName>/<tokenName>` for every registered token. */
+type TokenName = [keyof RegisteredTokenGroups] extends [never] ? string : { [G in keyof RegisteredTokenGroups & string]: `${G}/${keyof RegisteredTokenGroups[G] & string}` }[keyof RegisteredTokenGroups & string];
+/** Bare group names — `'color'`, `'spacing'`. */
+type TokenGroupName = [keyof RegisteredTokenGroups] extends [never] ? string : keyof RegisteredTokenGroups & string;
+/**
+ * Bare composite name (`'elevation'`) or `<name>/<variant>`
+ * (`'elevation/1'`).
+ *
+ * Indexes straight into `['styles']` rather than routing each member
+ * through an `extends { styles: infer V } ? … : never` conditional, for
+ * the same reason as `ModeName` — same resulting union, but no per-member
+ * conditional check + `infer`, and one consistent shape across every
+ * `*Name` union.
+ */
+type CompositeName = [keyof RegisteredCompositeStyles] extends [never] ? `${string}/${string}` : (keyof RegisteredCompositeStyles & string) | { [C in keyof RegisteredCompositeStyles & string]: `${C}/${keyof RegisteredCompositeStyles[C]['styles'] & string}` }[keyof RegisteredCompositeStyles & string];
+/**
+ * `<modeName>/<optionName>` for every registered mode option.
+ *
+ * Indexes straight into `['options']` rather than routing each member
+ * through an `extends { options: infer O } ? … : never` conditional.
+ * Both yield the same union, but the indexed access skips a per-member
+ * conditional assignability check + `infer`, so it's cheaper for the
+ * checker and keeps every `*Name` union on the one shape `TokenName`
+ * uses.
+ */
+type ModeName = [keyof RegisteredModes] extends [never] ? `${string}/${string}` : { [M in keyof RegisteredModes & string]: `${M}/${keyof RegisteredModes[M]['options'] & string}` }[keyof RegisteredModes & string];
+/** Style-prop names — `'bg'`, `'padding'`. */
+type StylePropName = [keyof RegisteredStyleProps] extends [never] ? string : keyof RegisteredStyleProps & string;
+/** Registered component names — `'Box'`, `'Alert'`. */
+type ComponentName = [keyof RegisteredComponents] extends [never] ? string : keyof RegisteredComponents & string;
+/** Bare asset-group slugs — `'icons'`, `'fonts'`. */
+type AssetGroupName = [keyof RegisteredAssetGroups] extends [never] ? string : keyof RegisteredAssetGroups & string;
+/** HTML tag names — open string for now; could narrow against `keyof JSX.IntrinsicElements`. */
+type TagName = string;
+interface TokenRef<TName extends string = string> {
+  readonly __kind: 'token';
+  readonly ref: TName;
+}
+interface TokenGroupRef<TName extends string = string> {
+  readonly __kind: 'tokenGroup';
+  readonly ref: TName;
+}
+interface CompositeRef<TName extends string = string, TLayer extends string | undefined = string | undefined> {
+  readonly __kind: 'composite';
+  readonly ref: TName;
+  /**
+   * Layer the marker should land on when used as a `.config()` prop
+   * binding (set by `composite(ref).on(layer)`). Absent when the ref
+   * is used as a token value, modifier selector, or as a bare prop
+   * binding that defaults to the `'root'` layer downstream.
+   */
+  readonly layer?: TLayer;
+}
+interface ModeRef<TName extends string = string> {
+  readonly __kind: 'mode';
+  readonly ref: TName;
+}
+interface StylePropRef<TName extends string = string> {
+  readonly __kind: 'styleProp';
+  readonly ref: TName;
+  readonly layer?: string;
+  /**
+   * Bind the style-prop to a specific layer — `styleProp('bg').on('root')`
+   * routes the JSX prop into the named layer instead of the component's
+   * own layer. Codegen reads the `layer` field and emits a class on
+   * that layer. Mirrors the old `@uds/config` `styleProp().on()` chain.
+   */
+  on(layer: string): StylePropRef<TName>;
+}
+interface TagRef<TName extends string = string> {
+  readonly __kind: 'tag';
+  readonly ref: TName;
+}
+interface ComponentRef<TName extends string = string> {
+  readonly __kind: 'component';
+  readonly ref: TName;
+}
+/**
+ * Asset-group pointer. The same `{ __kind, ref }` tag is *embedded* on
+ * the full group definition `defineAssetGroup(...)` returns (the
+ * definition object doubles as its own ref), so `isAssetGroupRef()` accepts
+ * both the bare marker and the live group object. The definition's
+ * `ref` is late-bound at `registerAssetGroups` and throws when read
+ * before registration; the guard only inspects `__kind`, so it is safe
+ * on unregistered groups.
+ */
+interface AssetGroupRef<TName extends string = string> {
+  readonly __kind: 'assetGroup';
+  readonly ref: TName;
+}
+type AnyRef = TokenRef | TokenGroupRef | CompositeRef | ModeRef | StylePropRef | TagRef | ComponentRef | AssetGroupRef;
+/** Doc-alignment alias kept for ergonomic import. */
+type TokenQualifiedName = TokenName;
+declare function token<TName extends TokenName>(ref: TName): TokenRef<TName>;
+declare function tokenGroup<TName extends TokenGroupName>(ref: TName): TokenGroupRef<TName>;
+/**
+ * `composite(ref)` returns a bare `CompositeRef` plus an `.on(layer)`
+ * method that produces the same shape with `layer` filled in — both
+ * forms are `CompositeRef`. Codegen's marker probe in
+ * `transformAuthoringSource.ts` reads `{ __kind, ref, layer? }`
+ * uniformly, so the on-layer marker is just a `CompositeRef` with a
+ * concrete `layer` field.
+ */
+interface CompositeRefBuilder<TName extends string> extends CompositeRef<TName, undefined> {
+  on<TLayer extends string>(layer: TLayer): CompositeRef<TName, TLayer>;
+}
+declare function composite<TName extends CompositeName>(ref: TName): CompositeRefBuilder<TName>;
+declare function mode<TName extends ModeName>(ref: TName): ModeRef<TName>;
+declare function styleProp<TName extends StylePropName>(ref: TName): StylePropRef<TName>;
+declare function tag<TName extends TagName>(ref: TName): TagRef<TName>;
+declare function component<TName extends ComponentName>(ref: TName): ComponentRef<TName>;
+declare function assetGroup<TName extends AssetGroupName>(ref: TName): AssetGroupRef<TName>;
+declare function isTokenRef(value: unknown): value is TokenRef;
+declare function isTokenGroupRef(value: unknown): value is TokenGroupRef;
+declare function isCompositeRef(value: unknown): value is CompositeRef;
+declare function isModeRef(value: unknown): value is ModeRef;
+declare function isStylePropRef(value: unknown): value is StylePropRef;
+declare function isTagRef(value: unknown): value is TagRef;
+declare function isComponentRef(value: unknown): value is ComponentRef;
+declare function isAssetGroupRef(value: unknown): value is AssetGroupRef; //#endregion
+//#endregion
+export { AnyRef, AssetGroupName, AssetGroupRef, ComponentName, ComponentRef, CompositeName, CompositeRef, CompositeRefBuilder, ModeName, ModeRef, RegisteredAssetGroups, RegisteredComponents, RegisteredCompositeStyles, RegisteredModes, RegisteredModifiers, RegisteredMotionDefs, RegisteredStyleProps, RegisteredTokenGroups, StylePropName, StylePropRef, TagName, TagRef, TokenGroupName, TokenGroupRef, TokenName, TokenQualifiedName, TokenRef, assetGroup, component, composite, isAssetGroupRef, isComponentRef, isCompositeRef, isModeRef, isStylePropRef, isTagRef, isTokenGroupRef, isTokenRef, mode, styleProp, tag, token, tokenGroup };

package/dist/config/dist/refs.js

@@ -1,77 +1,104 @@
-import { kebabCase } from "../../utils/dist/string-utils/kebabCase.js";
-import { safeTokenName } from "../../utils/dist/string-utils/cssVar.js";
-import "../../utils/dist/index.js";
 //#region ../config/dist/refs.js
-/**
-* Token references — `'{namespace/key}'` braces in token values.
-*
-* Authors can point one token at another via a brace-wrapped path:
-*
-*   defineVars({
-*     spectrum: { 'blue/500': { value: '#1167f4' } },
-*     color:    { brand:      { value: '{spectrum/blue/500}' } },
-*   })
-*
-* At CSS-declaration time this expands to a CSS variable alias:
-*
-*   --uds-spectrum-blue-500: #1167f4;
-*   --uds-color-brand: var(--uds-spectrum-blue-500);
-*
-* Refs are a purely syntactic transform — no graph walk, no cycle
-* detection. CSS handles aliasing (and any cascade cycles) at runtime.
-* Refs that don't match a declared token resolve to a `var(...)` that
-* has no `:root` declaration; the browser falls back to the property's
-* initial value.
-*
-* Consumption is unchanged: `tokens.color.brand` in component configs
-* still resolves to `var(--uds-color-brand)`, regardless of whether the
-* brand value itself is a literal or a ref.
-*/
-const REF_PATTERN = /^\{([^{}]+)\}$/;
-/**
-* Parse a value as a token ref. Returns `null` when the value isn't a
-* brace-wrapped ref of the form `{namespace/name}`. The `name` portion
-* may contain additional slashes — only the first slash is treated as
-* the namespace separator.
-*
-* Color-modifier values (`darken` / `lighten`) are a structured object
-* form, not a string-encoded suffix. See {@link TokenWithModifier}.
-*/
-function parseTokenRef(value) {
-	const outer = REF_PATTERN.exec(value);
-	if (!outer) return null;
-	const body = outer[1];
-	if (!body) return null;
-	return parseRefBody(body);
-}
-function parseRefBody(body) {
-	if (body.includes("{") || body.includes("}")) return null;
-	const slashIdx = body.indexOf("/");
-	if (slashIdx <= 0 || slashIdx >= body.length - 1) return null;
+function token(ref) {
 	return {
-		namespace: body.slice(0, slashIdx),
-		name: body.slice(slashIdx + 1)
+		__kind: "token",
+		ref
 	};
 }
-/**
-* Resolve a token value to its CSS form. If `value` is a token ref, returns
-* the corresponding `var(--<prefix>-<namespace>-<name>)` string. Otherwise
-* returns the value unchanged.
-*
-* The CSS variable name is built the same way `defineVars` builds its `:root`
-* declarations: `kebabCase` on the namespace, `safeTokenName` on the token
-* name. So `{spectrum/blue/500}` resolves to `var(--uds-spectrum-blue-500)`
-* (matching the namespace's own emitted variable name).
-*/
-function resolveTokenRef(value, configPrefix) {
-	const ref = parseTokenRef(value);
-	if (!ref) return value;
-	return refToVar(ref.namespace, ref.name, configPrefix);
-}
-function refToVar(namespace, name, configPrefix) {
-	const cssPrefix = kebabCase(namespace);
-	const cssName = safeTokenName(name);
-	return `var(${configPrefix ? `--${configPrefix}-${cssPrefix}-${cssName}` : `--${cssPrefix}-${cssName}`})`;
+function tokenGroup(ref) {
+	return {
+		__kind: "tokenGroup",
+		ref
+	};
+}
+function composite(ref) {
+	return Object.assign({
+		__kind: "composite",
+		ref
+	}, { on(layer) {
+		return {
+			__kind: "composite",
+			ref,
+			layer
+		};
+	} });
+}
+function mode(ref) {
+	return {
+		__kind: "mode",
+		ref
+	};
+}
+function styleProp(ref) {
+	const marker = {
+		__kind: "styleProp",
+		ref
+	};
+	Object.defineProperty(marker, "on", {
+		enumerable: false,
+		configurable: true,
+		writable: true,
+		value(layer) {
+			const next = {
+				__kind: "styleProp",
+				ref,
+				layer
+			};
+			Object.defineProperty(next, "on", {
+				enumerable: false,
+				configurable: true,
+				writable: true,
+				value: marker.on
+			});
+			return next;
+		}
+	});
+	return marker;
+}
+function tag(ref) {
+	return {
+		__kind: "tag",
+		ref
+	};
+}
+function component(ref) {
+	return {
+		__kind: "component",
+		ref
+	};
+}
+function assetGroup(ref) {
+	return {
+		__kind: "assetGroup",
+		ref
+	};
+}
+function isRefOf(value, kind) {
+	return typeof value === "object" && value !== null && value.__kind === kind;
+}
+function isTokenRef(value) {
+	return isRefOf(value, "token");
+}
+function isTokenGroupRef(value) {
+	return isRefOf(value, "tokenGroup");
+}
+function isCompositeRef(value) {
+	return isRefOf(value, "composite");
+}
+function isModeRef(value) {
+	return isRefOf(value, "mode");
+}
+function isStylePropRef(value) {
+	return isRefOf(value, "styleProp");
+}
+function isTagRef(value) {
+	return isRefOf(value, "tag");
+}
+function isComponentRef(value) {
+	return isRefOf(value, "component");
+}
+function isAssetGroupRef(value) {
+	return isRefOf(value, "assetGroup");
 }
 //#endregion
-export { parseTokenRef, resolveTokenRef };
+export { assetGroup, component, composite, isAssetGroupRef, isComponentRef, isCompositeRef, isModeRef, isStylePropRef, isTagRef, isTokenGroupRef, isTokenRef, mode, styleProp, tag, token, tokenGroup };