@yahoo/uds-v5-wip 1.17.0 → 1.18.0

package/dist/config/dist/createConfig.js

@@ -4,9 +4,9 @@ import "../../utils/dist/index.js";
 import { getConfigurablePropMapping } from "../../core/dist/propMappings.js";
 import "../../core/dist/index.js";
 import { buildMotionReference, resolveComponentMotionAliases, validateComponentVariants } from "./component-resolution.js";
+import { applyPresetToData, deepMerge, mergeAtomic } from "./preset-merge.js";
 import { expandPropertyGroups } from "./propertyGroups.js";
 import { resolveTokenType, sniffTokenTypeFromValue } from "./resolveTokenTypes.js";
-import { applyPresetToData, deepMerge, mergeAtomic } from "./preset-merge.js";
 //#region ../config/dist/createConfig.js
 /** biome-ignore-all lint/suspicious/noExplicitAny: necessary for dynamic builder to work correctly */
 /** Build a structured token reference object from atomic tokens */
@@ -43,20 +43,26 @@ function buildMacroReference(macros) {
 /**
 * Convert a VarGroupDef into AtomicToken tokens, extracting modifier overrides.
 *
-* Also extracts `$type` metadata:
+* Also extracts group-level metadata:
 * - A top-level `$type` on the group → `groupType`
+* - A top-level `$description` on the group → `groupDescription`
 * - A `$type` on an individual token → `type` on that token (overrides group)
 *
-* `$type` is filtered out of the emitted tokens; it is metadata only.
+* Metadata keys (`$type`, `$description`) are filtered out of the emitted tokens.
 */
 function varGroupToTokens(varGroup, knownModifiers) {
 	let groupType;
+	let groupDescription;
 	const tokens = [];
 	for (const [tokenName, rawDef] of Object.entries(varGroup)) {
 		if (tokenName === "$type") {
 			if (typeof rawDef === "string") groupType = rawDef;
 			continue;
 		}
+		if (tokenName === "$description") {
+			if (typeof rawDef === "string") groupDescription = rawDef;
+			continue;
+		}
 		if (rawDef == null || typeof rawDef !== "object") continue;
 		const tokenDef = rawDef;
 		const modifiers = {};
@@ -73,7 +79,8 @@ function varGroupToTokens(varGroup, knownModifiers) {
 	}
 	return {
 		tokens,
-		groupType
+		groupType,
+		groupDescription
 	};
 }
 /**
@@ -102,7 +109,7 @@ function synthesizeAtomicFromScopesAndVars(vars, scopes, modes) {
 		if (!varGroup) continue;
 		const properties = expandPropertyGroups(groupIds);
 		if (properties.length === 0) continue;
-		const { tokens, groupType } = varGroupToTokens(varGroup, knownModifiers);
+		const { tokens, groupType, groupDescription } = varGroupToTokens(varGroup, knownModifiers);
 		const cssPfx = (properties.includes(namespace) ? getConfigurablePropMapping(namespace) : void 0)?.defaultVarPrefix ?? kebabCase(namespace);
 		const sorted = sortPropertiesByPrefixMatch(properties, namespace, cssPfx);
 		const resolvedGroupType = resolveTokenType({
@@ -117,7 +124,8 @@ function synthesizeAtomicFromScopesAndVars(vars, scopes, modes) {
 			properties: sorted,
 			tokens,
 			cssPrefix: cssPfx,
-			...resolvedGroupType ? { type: resolvedGroupType } : {}
+			...resolvedGroupType ? { type: resolvedGroupType } : {},
+			...groupDescription ? { description: groupDescription } : {}
 		});
 	}
 	return disambiguateOverlappingProperties(result, scopes);

package/dist/config/dist/preset-merge.js

@@ -15,6 +15,7 @@ function flattenAtomic(atomic) {
 		property,
 		cssPrefix: group.cssPrefix,
 		groupType: group.type,
+		groupDescription: group.description,
 		token
 	});
 	return entries;
@@ -41,12 +42,14 @@ function mergeAtomic(base, incoming, mode) {
 		if (existing) {
 			existing.tokens.push(entry.token);
 			if (entry.groupType) existing.type = entry.groupType;
+			if (entry.groupDescription) existing.description = entry.groupDescription;
 			continue;
 		}
 		regrouped.set(groupKey, {
 			properties: [entry.property],
 			...entry.cssPrefix ? { cssPrefix: entry.cssPrefix } : {},
 			...entry.groupType ? { type: entry.groupType } : {},
+			...entry.groupDescription ? { description: entry.groupDescription } : {},
 			tokens: [entry.token]
 		});
 	}

package/dist/config/dist/types.d.ts

@@ -33,19 +33,23 @@ type VarTokenDef<M extends `_${string}` = `_${string}`> = {
  * A group of named tokens within a var namespace.
  *
  * The group may declare a `$type` that applies to all tokens in the group;
- * individual tokens may override it with their own `$type`.
+ * individual tokens may override it with their own `$type`. A `$description`
+ * is free-form documentation surfaced in Studio (e.g. as the readonly subtitle
+ * on the token group editor) and is otherwise inert at runtime.
  *
  * @example
  * {
  *   $type: 'color',
+ *   $description: 'Brand-aligned semantic colors. Light/dark pairs only.',
  *   brand: { value: '#1167f4', _dark: '#88bcfb' },
  *   accent: { value: '#7c3aed' },
  * }
  */
 type VarGroupDef<M extends `_${string}` = `_${string}`> = {
   $type?: TokenType;
+  $description?: string;
 } & {
-  [tokenName: string]: VarTokenDef<M> | TokenType | undefined;
+  [tokenName: string]: VarTokenDef<M> | TokenType | string | undefined;
 };
 /**
  * Top-level vars config — namespaces to groups of tokens.

package/dist/config.d.ts

@@ -8,7 +8,390 @@ import * as _$_uds_types0 from "@uds/types";
 //#region src/config.d.ts
 declare const uds: UdsConfig<_$_uds_types0.ModifierProp, {}, {}, {}, {}, never, {}>;
 declare const defaultPreset: UdsConfig<_$_uds_types0.ModifierProp | "_light" | "_dark" | "_sm" | "_md" | "_lg" | "_xl" | "_2xl", {
-  [x: string]: Record<string, string>;
+  opacity: {
+    0: string;
+    5: string;
+    10: string;
+    20: string;
+    40: string;
+    60: string;
+    80: string;
+    25: string;
+    30: string;
+    50: string;
+    70: string;
+    75: string;
+    90: string;
+    95: string;
+    100: string;
+  };
+  scale: {
+    0: string;
+    50: string;
+    75: string;
+    90: string;
+    95: string;
+    100: string;
+    105: string;
+    110: string;
+    125: string;
+    150: string;
+    200: string;
+  };
+  rotate: {
+    0: string;
+    2: string;
+    1: string;
+    3: string;
+    6: string;
+    12: string;
+    90: string;
+    45: string;
+    180: string;
+  };
+  color: {
+    inherit: string;
+    current: string;
+    transparent: string;
+    "always/black": string;
+    "always/white": string;
+    brand: string;
+    "on-brand": string;
+    accent: string;
+    "on-accent": string;
+    alert: string;
+    "on-alert": string;
+    positive: string;
+    "on-positive": string;
+    warning: string;
+    "on-warning": string;
+    primary: string;
+    "on-primary": string;
+    secondary: string;
+    "on-secondary": string;
+    tertiary: string;
+    "on-tertiary": string;
+    inverse: string;
+    "on-inverse": string;
+  };
+  borderColor: {
+    brand: string;
+    accent: string;
+    alert: string;
+    positive: string;
+    warning: string;
+    primary: string;
+    secondary: string;
+    tertiary: string;
+    inverse: string;
+    surface: string;
+    "brand-wash": string;
+    "accent-wash": string;
+    "alert-wash": string;
+    "positive-wash": string;
+    "warning-wash": string;
+  };
+  position: {
+    auto: string;
+    full: string;
+    "1/2": string;
+    "1/3": string;
+    "2/3": string;
+    "1/4": string;
+    "2/4": string;
+    "3/4": string;
+  };
+  size: {
+    auto: string;
+    full: string;
+    max: string;
+    min: string;
+    "1/2": string;
+    "1/3": string;
+    "2/3": string;
+    "1/4": string;
+    "2/4": string;
+    "3/4": string;
+    fit: string;
+    "1/5": string;
+    "2/5": string;
+    "3/5": string;
+    "4/5": string;
+    "1/6": string;
+    "2/6": string;
+    "3/6": string;
+    "4/6": string;
+    "5/6": string;
+  };
+  animation: {
+    none: string;
+    ping: string;
+    spin: string;
+  };
+  bg: {
+    overlay: string;
+    brand: string;
+    accent: string;
+    alert: string;
+    positive: string;
+    warning: string;
+    primary: string;
+    secondary: string;
+    tertiary: string;
+    inverse: string;
+    surface: string;
+    "elevation-1": string;
+    "elevation-2": string;
+    "elevation-3": string;
+    "brand-wash": string;
+    "accent-wash": string;
+    "alert-wash": string;
+    "positive-wash": string;
+    "warning-wash": string;
+  };
+  borderWidth: {
+    none: string;
+    thin: string;
+    medium: string;
+    thick: string;
+  };
+  divideWidth: {
+    0: string;
+    4: string;
+    reverse: string;
+    2: string;
+    8: string;
+  };
+  flex: {
+    none: string;
+    initial: string;
+    auto: string;
+    1: string;
+  };
+  flexGrow: {
+    0: string;
+    1: string;
+  };
+  flexShrink: {
+    0: string;
+  };
+  aspectRatio: {
+    square: string;
+    landscape: string;
+    portrait: string;
+    widescreen: string;
+    ultrawide: string;
+    golden: string;
+  };
+  zIndex: {
+    0: string;
+    auto: string;
+    10: string;
+    20: string;
+    40: string;
+    30: string;
+    50: string;
+  };
+  spacing: {
+    0: string;
+    4: string;
+    2: string;
+    5: string;
+    1: string;
+    px: string;
+    8: string;
+    0.5: string;
+    1.5: string;
+    2.5: string;
+    3: string;
+    3.5: string;
+    6: string;
+    7: string;
+    9: string;
+    10: string;
+    11: string;
+    12: string;
+    14: string;
+    16: string;
+    20: string;
+    24: string;
+    28: string;
+    32: string;
+    36: string;
+    40: string;
+    44: string;
+    48: string;
+    52: string;
+    56: string;
+    60: string;
+    64: string;
+    72: string;
+    80: string;
+    96: string;
+  };
+  w: {
+    screen: string;
+    svw: string;
+    lvw: string;
+    dvw: string;
+  };
+  outlineWidth: {
+    0: string;
+    4: string;
+    2: string;
+    1: string;
+    8: string;
+  };
+  outlineOffset: {
+    0: string;
+    4: string;
+    2: string;
+    1: string;
+    8: string;
+  };
+  ringWidth: {
+    0: string;
+    4: string;
+    inset: string;
+    2: string;
+    1: string;
+    8: string;
+  };
+  ringOffsetWidth: {
+    0: string;
+    4: string;
+    2: string;
+    1: string;
+    8: string;
+  };
+  shadow: {
+    none: string;
+    sm: string;
+    md: string;
+    lg: string;
+    xl: string;
+    "2xl": string;
+    "2xs": string;
+    xs: string;
+    inner: string;
+  };
+  strokeWidth: {
+    0: string;
+    2: string;
+    1: string;
+  };
+  fontFamily: {
+    sans: string;
+    serif: string;
+    mono: string;
+  };
+  fontWeight: {
+    normal: string;
+    thin: string;
+    bold: string;
+    light: string;
+    medium: string;
+    extralight: string;
+    semibold: string;
+    extrabold: string;
+    black: string;
+  };
+  letterSpacing: {
+    normal: string;
+    tight: string;
+    tighter: string;
+    wide: string;
+    wider: string;
+    widest: string;
+  };
+  lineHeight: {
+    none: string;
+    normal: string;
+    tight: string;
+    relaxed: string;
+  };
+  textShadow: {
+    none: string;
+    sm: string;
+    md: string;
+    lg: string;
+    "2xs": string;
+    xs: string;
+  };
+  blur: {
+    none: string;
+    sm: string;
+    md: string;
+    lg: string;
+    xl: string;
+    "2xl": string;
+    "3xl": string;
+  };
+  translate: {
+    0: string;
+    4: string;
+    full: string;
+    2: string;
+    5: string;
+    1: string;
+    "1/2": string;
+    "1/3": string;
+    "2/3": string;
+    "1/4": string;
+    "3/4": string;
+    8: string;
+    0.5: string;
+    1.5: string;
+    2.5: string;
+    3: string;
+    3.5: string;
+    6: string;
+    7: string;
+    9: string;
+    10: string;
+    11: string;
+    12: string;
+    14: string;
+    16: string;
+    20: string;
+    24: string;
+    28: string;
+    32: string;
+    36: string;
+    40: string;
+    44: string;
+    48: string;
+    52: string;
+    56: string;
+    60: string;
+    64: string;
+    72: string;
+    80: string;
+    96: string;
+  };
+  radius: {
+    none: string;
+    sm: string;
+    md: string;
+    lg: string;
+    xl: string;
+    xs: string;
+    full: string;
+  };
+  h: {
+    screen: string;
+    svh: string;
+    lvh: string;
+    dvh: string;
+  };
+  skew: {
+    0: string;
+    2: string;
+    1: string;
+    3: string;
+    6: string;
+    12: string;
+  };
 }, {}, {}, {}, "_light" | "_dark" | "_sm" | "_md" | "_lg" | "_xl" | "_2xl", {
   readonly color: {
     readonly $type: "color";

package/dist/core/dist/createComponent.js

@@ -1,6 +1,6 @@
+import { applySlotOverrides, assertTransformedConfig, buildSlotProps, buildUntransformedSlotProps, inferComponentNameFromRenderFn, mergeMotionConfig, mergeRootClassName, mergeSlotMotionProps, partitionMergedProps } from "./createComponent.boundaries.js";
 import { processStyleProps } from "./getStyles.js";
 import { createComponentStyler } from "./getComponentStyles.js";
-import { applySlotOverrides, assertTransformedConfig, buildSlotProps, buildUntransformedSlotProps, inferComponentNameFromRenderFn, mergeMotionConfig, mergeRootClassName, mergeSlotMotionProps, partitionMergedProps } from "./createComponent.boundaries.js";
 import { createElement } from "react";
 //#region ../core/dist/createComponent.js
 function createPrimitiveRenderFn(tag) {