@yahoo/uds-v5-wip 1.39.0 → 1.41.0

package/dist/config/dist/defineStyleProp.d.ts

@@ -51,6 +51,14 @@ interface AnyStyleProp {
   readonly cssType?: CssValueTypeName;
   readonly metadata: StylePropMetadata;
 }
-/** Intermediate builder — the only callable method is `.metadata()`. */
+/**
+ * Return shape of {@link defineStyleProp}. The `metadata` field doubles as
+ * a callable chain: read it to access `{ label?, description? }` (both
+ * optional, so an unset metadata reads `undefined` for either field) or
+ * call it as `.metadata({ label, description })` to attach metadata and
+ * get back a plain {@link StyleProp}. A function satisfies the
+ * {@link StylePropMetadata} structural shape because both fields are
+ * optional, so the dual nature is type-safe.
+ */
 //#endregion
 export { AnyStyleProp, ArbitraryEntry, ArbitrarySpec, StylePropMetadata };

package/dist/config/dist/defineStyleProp.js

@@ -1,25 +1,39 @@
 //#region ../config/dist/defineStyleProp.js
 const CUSTOM_PROPERTY_PREFIX = "--";
 /**
-* Author a style prop. Returns a builder whose `.metadata({...})` finalizes
-* the {@link StyleProp} record. Pure — no global registration.
+* Author a style prop. Returns a {@link StyleProp} directly so callers can
+* skip the `.metadata({...})` chain when there's nothing to attach:
+*
+* ```ts
+* defineStyleProp({ cssProperty: 'flex-direction', classPrefix: 'flex', values: ['row', 'col'] })
+* ```
+*
+* The returned object still supports `.metadata({...})` for the common
+* case where you want to attach a label/description — the chain returns a
+* plain {@link StyleProp} with the metadata baked in. Pure — no global
+* registration.
 */
 function defineStyleProp(spec) {
 	const { cssProperty, classPrefix, values, arbitrary, cssType } = spec;
 	const isCustomProperty = cssProperty.startsWith(CUSTOM_PROPERTY_PREFIX);
 	if (isCustomProperty && cssType === void 0) throw new Error(`defineStyleProp: cssType is required for custom CSS properties (got cssProperty=${JSON.stringify(cssProperty)}).`);
 	if (!isCustomProperty && cssType !== void 0) throw new Error(`defineStyleProp: cssType is only allowed for custom CSS properties (--*). Got cssProperty=${JSON.stringify(cssProperty)} with cssType=${JSON.stringify(cssType)}.`);
-	return { metadata(meta = {}) {
-		return {
-			kind: "styleProp",
-			cssProperty,
-			classPrefix,
-			values: values ?? [],
-			arbitrary,
-			cssType,
-			metadata: meta
-		};
-	} };
+	const baseFields = {
+		kind: "styleProp",
+		cssProperty,
+		classPrefix,
+		values: values ?? [],
+		arbitrary,
+		cssType
+	};
+	const metadata = (meta = {}) => ({
+		...baseFields,
+		metadata: meta
+	});
+	return {
+		...baseFields,
+		metadata
+	};
 }
 //#endregion
 export { defineStyleProp };

package/dist/config/dist/index.js

@@ -2,11 +2,11 @@ import "./component-resolution.js";
 import "./consts/defaultColors.js";
 import "./createComponent.js";
 import "./propertyAcceptedTypes.js";
+import "./refs.js";
 import "./resolveTokenTypes.js";
 import "./resolveStyleProp.js";
 import "./createConfig.js";
 import "./defineComponent.js";
 import "./defineStyleProp.js";
 import "./propertyGroups.js";
-import "./refs.js";
 import "./serialize.js";

package/dist/config/dist/refs.js

@@ -1 +1,66 @@
+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.
+*/
+function parseTokenRef(value) {
+	const match = REF_PATTERN.exec(value);
+	if (!match) return null;
+	const namespace = match[1];
+	const name = match[2];
+	if (!namespace || !name) return null;
+	return {
+		namespace,
+		name
+	};
+}
+/**
+* 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;
+	const cssPrefix = kebabCase(ref.namespace);
+	const cssName = safeTokenName(ref.name);
+	return `var(${configPrefix ? `--${configPrefix}-${cssPrefix}-${cssName}` : `--${cssPrefix}-${cssName}`})`;
+}
+//#endregion
+export { parseTokenRef, resolveTokenRef };

package/dist/config/dist/resolveStyleProp.js

@@ -1,6 +1,7 @@
 import { safeTokenName } from "../../utils/dist/string-utils/cssVar.js";
 import "../../utils/dist/index.js";
 import { isTokenAcceptedByProperty } from "./propertyAcceptedTypes.js";
+import { resolveTokenRef } from "./refs.js";
 import { sniffTokenTypeFromValue } from "./resolveTokenTypes.js";
 //#region ../config/dist/resolveStyleProp.js
 /**
@@ -194,18 +195,8 @@ function resolveStyleProp(propName, styleProp, config) {
 			const aliasKey = aliasEntry.alias;
 			const aliasMapKey = typeof aliasKey === "string" ? aliasKey : String(aliasKey);
 			let resolvedValue;
-			if (typeof aliasEntry.value === "string") {
-				resolvedValue = aliasEntry.value;
-				const parsedRef = parseGroupRef(aliasEntry.value);
-				if (parsedRef?.key) {
-					const group = findGroup(config.atomic, parsedRef.group);
-					const token = group?.tokens.find((t) => t.name === parsedRef.key);
-					if (group && token) {
-						const safeName = safeTokenName(token.name);
-						resolvedValue = `var(${buildCssVar(configPrefix, group.cssPrefix ?? group.namespace ?? parsedRef.group, safeName)})`;
-					}
-				}
-			} else resolvedValue = aliasEntry.value;
+			if (typeof aliasEntry.value === "string") resolvedValue = resolveTokenRef(aliasEntry.value, configPrefix);
+			else resolvedValue = aliasEntry.value;
 			if (!literals.includes(aliasKey)) literals.push(aliasKey);
 			literalAliases[aliasMapKey] = resolvedValue;
 		}

package/dist/core/dist/color-opacity-map.d.ts

@@ -1,5 +1,4 @@
 //#region ../core/dist/color-opacity-map.d.ts
-//#region src/color-opacity-map.d.ts
 /**
  * Maps each color prop name to its corresponding opacity prop name.
  * Used by the runtime (`getStyles`) and loader (`style-transform`) to merge
@@ -8,6 +7,6 @@
  * @example
  * `bg="primary"` + `bgOpacity="75"` → class `bg-primary_75`
  */
-declare const colorPropToOpacityProp: Record<string, string>; //#endregion
+declare const colorPropToOpacityProp: Record<string, string>;
 //#endregion
 export { colorPropToOpacityProp };

package/dist/core/dist/compositeStyles.d.ts

@@ -1,7 +1,6 @@
 import { CompositeStylesConfig } from "@uds/types";
 
 //#region ../core/dist/compositeStyles.d.ts
-//#region src/compositeStyles.d.ts
 /** Set the composite-styles config (called by loader at build time) */
 declare function setCompositeStylesConfig(config: CompositeStylesConfig): void;
 /** Get the current composite-styles config */
@@ -17,6 +16,6 @@ declare function getCompositeStylesConfig(): CompositeStylesConfig;
 declare function expandCompositeStyles(props: Record<string, unknown>, config?: CompositeStylesConfig): {
   expanded: Record<string, unknown>;
   markerClasses: string[];
-}; //#endregion
+};
 //#endregion
 export { expandCompositeStyles, getCompositeStylesConfig, setCompositeStylesConfig };

package/dist/core/dist/configurable-prop-helpers.d.ts

@@ -2,7 +2,6 @@ import { PropMapping } from "./style-prop-data.js";
 import { ConfigurableProp } from "@uds/types";
 
 //#region ../core/dist/configurable-prop-helpers.d.ts
-//#region src/configurable-prop-helpers.d.ts
 /** Look up a {@link PropMapping} by ConfigurableProp name. */
 declare function getConfigurablePropMapping(prop: ConfigurableProp): PropMapping | undefined;
 interface ConfigurablePropertyEntry {
@@ -27,6 +26,6 @@ interface CssVariablePrefixEntry {
  * Only includes props that have both `cssProperty` and `defaultVarPrefix`.
  * Deduplicates by `defaultVarPrefix` so each namespace appears once.
  */
-declare function getCssVariablePrefixes(): CssVariablePrefixEntry[]; //#endregion
+declare function getCssVariablePrefixes(): CssVariablePrefixEntry[];
 //#endregion
 export { ConfigurablePropertyEntry, CssVariablePrefixEntry, getConfigurablePropMapping, getConfigurableProperties, getCssVariablePrefixes };

package/dist/core/dist/createComponent.d.ts

@@ -1,7 +1,6 @@
 import { CreateComponentConfig, CreateComponentProps, CreateComponentRenderFn, CreateComponentSlotTagConfig, CreateComponentTypeInput } from "@uds/types";
 
 //#region ../core/dist/createComponent.d.ts
-//#region src/createComponent.d.ts
 type PrimitiveTag = keyof React.JSX.IntrinsicElements;
 type SpecConfig<TSpec> = TSpec extends {
   config: infer TConfig extends CreateComponentTypeInput;
@@ -52,6 +51,6 @@ declare function createComponent<TSpecOrProps = {}>(tag: PrimitiveTag): React.FC
   props: infer TOwnProps;
 } ? CreateComponentProps<TConfig, TOwnProps, PrimitiveTag> : PrimitiveOwnProps<TSpecOrProps>>;
 declare function createComponent<TSpec>(renderFn: CreateComponentRenderFn<SpecConfig<TSpec>, SpecOwnProps<TSpec>, SpecSlotConfig<TSpec>>): React.FC<CreateComponentProps<SpecConfig<TSpec>, SpecOwnProps<TSpec>, SpecSlotConfig<TSpec>>>;
-declare function createComponent(config: CreateComponentConfig<string>, renderFn: CreateComponentRenderFn<any, any, any>): React.FC<any>; //#endregion
+declare function createComponent(config: CreateComponentConfig<string>, renderFn: CreateComponentRenderFn<any, any, any>): React.FC<any>;
 //#endregion
 export { createComponent };

package/dist/core/dist/createComponentExample.d.ts

@@ -1,7 +1,6 @@
 import { ComponentProps, ComponentType } from "react";
 
 //#region ../core/dist/createComponentExample.d.ts
-//#region src/createComponentExample.d.ts
 /**
  * Extracts variant fixtures from a Component's props type.
  * If Button has `variant?: 'brand' | 'outline'` and `size?: 'sm' | 'md'`,
@@ -37,6 +36,6 @@ type ExamplesResult<TComponent extends ComponentType<any>> = {
  * }));
  * ```
  */
-declare function createComponentExample<TComponent extends ComponentType<any>, T extends Record<string, ExampleFn<TComponent>>>(Component: TComponent, examplesFn: (fixtures: VariantFixtures<TComponent>) => ExamplesResult<TComponent>): ComponentExample<T>; //#endregion
+declare function createComponentExample<TComponent extends ComponentType<any>, T extends Record<string, ExampleFn<TComponent>>>(Component: TComponent, examplesFn: (fixtures: VariantFixtures<TComponent>) => ExamplesResult<TComponent>): ComponentExample<T>;
 //#endregion
 export { ComponentExample, createComponentExample };

package/dist/core/dist/createProvider.d.ts

@@ -1,5 +1,4 @@
 //#region ../core/dist/createProvider.d.ts
-//#region src/createProvider.d.ts
 type ProviderRenderFn<TContext, TProps = Record<never, never>> = (props: {
   children: React.ReactNode;
 } & TProps) => {
@@ -8,6 +7,6 @@ type ProviderRenderFn<TContext, TProps = Record<never, never>> = (props: {
 };
 declare function createProvider<TContext, TProps = Record<never, never>>(name: string, renderFn: ProviderRenderFn<TContext, TProps>): [React.FC<{
   children: React.ReactNode;
-} & TProps>, () => TContext]; //#endregion
+} & TProps>, () => TContext];
 //#endregion
 export { createProvider };

package/dist/core/dist/generated/stylePropsTwMap.d.ts

@@ -1,5 +1,4 @@
 //#region ../core/dist/generated/stylePropsTwMap.d.ts
-//#region src/generated/stylePropsTwMap.d.ts
 declare const stylePropsTwMap: {
   readonly "border-boolean": {
     readonly border: "boolean";
@@ -1696,6 +1695,6 @@ declare const stylePropsTwMap: {
   readonly "hyphens-manual": {
     readonly hyphens: "manual";
   };
-}; //#endregion
+};
 //#endregion
 export { stylePropsTwMap };

package/dist/core/dist/getComponentStyles.d.ts

@@ -1,7 +1,6 @@
 import { ComponentRegistry, ComponentSlotsOf, ComponentVariantsOf } from "@uds/types";
 
 //#region ../core/dist/getComponentStyles.d.ts
-//#region src/getComponentStyles.d.ts
 type ResolveSlots<Name extends string> = Name extends keyof ComponentRegistry ? ComponentSlotsOf<Name> : string;
 type ResolveVariants<Name extends string> = Name extends keyof ComponentRegistry ? ComponentVariantsOf<Name> : Record<string, string>;
 interface UdsRuntimeMeta {
@@ -45,6 +44,6 @@ interface ComponentStyler<Name extends string> {
  * @param slots - Array of slot names
  * @param element - Optional HTML element tag for element-specific prop forwarding
  */
-declare function createComponentStyler<Name extends string>(componentName: Name, slots: readonly string[], element?: string, variants?: readonly string[]): ComponentStyler<Name>; //#endregion
+declare function createComponentStyler<Name extends string>(componentName: Name, slots: readonly string[], element?: string, variants?: readonly string[]): ComponentStyler<Name>;
 //#endregion
 export { createComponentStyler };

package/dist/core/dist/getStyles.d.ts

@@ -2,7 +2,6 @@ import { ClassValue } from "clsx";
 import { ModifierProp, ModifierProps, StyleAndModifierProps, StyleProps } from "@uds/types";
 
 //#region ../core/dist/getStyles.d.ts
-//#region src/getStyles.d.ts
 /** Convert kebab-case CSS property to camelCase for React inline styles.
  *  CSS custom properties (--*) are kept as-is since React supports them verbatim. */
 declare function toCamelCase(str: string): string;
@@ -38,6 +37,6 @@ interface GetStylesParams extends StyleProps, ModifierProps {
  *  so they can be included in the CSS safelist.
  */
 declare function getStyles(props: GetStylesParams): string;
-declare function getVariantClassName(componentName: string, variant: string | undefined): string; //#endregion
+declare function getVariantClassName(componentName: string, variant: string | undefined): string;
 //#endregion
 export { createVariants, cx, getStyles, getVariantClassName, processStyleProps, toCamelCase };

package/dist/core/dist/modifier-mappings.d.ts

@@ -1,13 +1,12 @@
 import { ModifierProp } from "@uds/types";
 
 //#region ../core/dist/modifier-mappings.d.ts
-//#region src/modifier-mappings.d.ts
 declare const modifierMappings: Record<ModifierProp, string>;
 interface ModifierEntry {
   prop: string;
   cssSelector: string;
   category: string;
   description: string;
-} //#endregion
+}
 //#endregion
 export { ModifierEntry, modifierMappings };

package/dist/core/dist/resolveMotionState.d.ts

@@ -1,5 +1,4 @@
 //#region ../core/dist/resolveMotionState.d.ts
-//#region src/resolveMotionState.d.ts
-declare function resolveMotionState(stateKeyframe: Record<string, unknown>, index: number): Record<string, number>; //#endregion
+declare function resolveMotionState(stateKeyframe: Record<string, unknown>, index: number): Record<string, number>;
 //#endregion
 export { resolveMotionState };

package/dist/core/dist/style-prop-data.d.ts

@@ -1,7 +1,6 @@
 import { StyleProp } from "@uds/types";
 
 //#region ../core/dist/style-prop-data.d.ts
-//#region src/style-prop-data.d.ts
 interface PropMapping {
   /** Class name prefix for runtime class generation. 'no-prefix' means value IS the class. */
   classPrefix: string;
@@ -28,6 +27,6 @@ interface PropMapping {
 }
 /** Exclude className — it's passed through, not mapped to a utility class */
 type MappedStyleProp = Exclude<StyleProp, 'className'>;
-declare const propMappings: Record<MappedStyleProp, PropMapping>; //#endregion
+declare const propMappings: Record<MappedStyleProp, PropMapping>;
 //#endregion
 export { PropMapping, propMappings };

package/dist/core/dist/transformPreset.d.ts

@@ -1,7 +1,6 @@
 import { MotionPreset } from "@uds/types";
 
 //#region ../core/dist/transformPreset.d.ts
-//#region src/transformPreset.d.ts
 interface TransformedMotionProps {
   initial?: Record<string, unknown>;
   animate?: Record<string, unknown>;
@@ -13,6 +12,6 @@ interface TransformedMotionProps {
 /**
  * Convert a JS-runtime MotionPreset to a motion/react-compatible props object.
  */
-declare function transformPreset(preset: MotionPreset): TransformedMotionProps; //#endregion
+declare function transformPreset(preset: MotionPreset): TransformedMotionProps;
 //#endregion
 export { TransformedMotionProps, transformPreset };

package/dist/core/dist/withDefaultStyleProps.d.ts

@@ -1,7 +1,6 @@
 import { BorderRadius, GridSpan, GridStartEnd, GridTemplate, StyleAndModifierProps } from "@uds/types";
 
 //#region ../core/dist/withDefaultStyleProps.d.ts
-//#region src/withDefaultStyleProps.d.ts
 interface StackDefaultsInput extends StyleAndModifierProps {
   gap?: StyleAndModifierProps['gap'];
 }
@@ -39,6 +38,6 @@ declare const withDefaultStyleProps: {
     shape?: BorderRadius;
   }) => StyleAndModifierProps;
   Svg: (props: SvgDefaultsInput) => StyleAndModifierProps;
-}; //#endregion
+};
 //#endregion
 export { withDefaultStyleProps };

package/dist/foundational-presets/dist/motion.d.ts

@@ -1,4 +1,5 @@
 //#region ../foundational-presets/dist/motion.d.ts
+//#region src/motion.d.ts
 interface InterpolateMarker {
   __type: 'interpolate';
   output: number[];
@@ -7,6 +8,6 @@ interface InterpolateMarker {
 declare function interpolate(config: {
   output: number[];
   extrapolate?: 'clamp' | 'extend' | 'identity';
-}): InterpolateMarker;
+}): InterpolateMarker; //#endregion
 //#endregion
 export { InterpolateMarker, interpolate };