@trinityui/design-system 2.11.0 → 2.13.0

package/dist/token-color.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Pure color helpers for the token layer (master plan E-03).
+ *
+ * No imports: `src/tokens.ts` uses this module, and the tokens entry must not pull in
+ * `@mui/material` (ADR-18).
+ */
+/**
+ * The color with its alpha set to `alpha` (0-1), in the format MUI's `alpha()` returns:
+ * `rgba(r, g, b, a)` for hex and rgb input, `hsla(h, s%, l%, a)` for hsl input. A color it
+ * cannot read (a named color or a `var()`) becomes `color-mix(in srgb, <color> <a*100>%,
+ * transparent)`, which renders the same tint in every evergreen browser.
+ */
+export declare function withAlpha(color: string, alpha: number): string;
+//# sourceMappingURL=token-color.d.ts.map

package/dist/token-color.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-color.d.ts","sourceRoot":"","sources":["../src/token-color.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAcH;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAoB9D"}

package/dist/token-merge.d.ts

@@ -0,0 +1,56 @@
+import type { TrinityTokens } from './tokens';
+/**
+ * Every property optional, at every depth. Arrays are replaced whole, so their element type is
+ * kept as is.
+ */
+export type DeepPartial<T> = T extends readonly unknown[] ? T : T extends (...args: never[]) => unknown ? T : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+/**
+ * Token overrides for `createTrinityTheme`, `createTrinityThemePreset({ tokens })` and the
+ * runtime CSS functions: any part of {@link TrinityTokens}, at any depth. Omitted keys keep
+ * their defaults.
+ *
+ * @since 2.13.0
+ */
+export type TrinityTokenOverrides = DeepPartial<TrinityTokens>;
+/**
+ * Test-only: forget which paths have warned, so a test can observe a warning again.
+ *
+ * @internal
+ */
+export declare function __resetTokenMergeWarnings(): void;
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Merge token overrides over a complete base token set. Returns `base` itself when the
+ * overrides change nothing; otherwise a new object that shares every untouched subtree with
+ * `base`.
+ */
+export declare function mergeTokenOverrides<T extends object>(base: T, overrides: DeepPartial<T> | null | undefined): T;
+/**
+ * Token-path references: [target, source]. A target the overrides do not set takes the
+ * resolved source value, so a brand override reaches every role that references it. Role
+ * references whose target is not a token (confidence, verification) have nothing to set.
+ */
+export declare function tokenReferencePaths(): Array<readonly [readonly string[], readonly string[]]>;
+/**
+ * The resolved token set: the defaults with `overrides` deep-merged in, then references
+ * re-resolved. Plain objects merge key by key; arrays and single values replace.
+ *
+ * - A referencing member the overrides do not set takes its source's resolved value. For
+ *   example, overriding `semantic.colors.border.subtle` also changes `component.card.border`,
+ *   and overriding `semantic.colors.brand.secondary` also changes `semantic.colors.ai.primary`.
+ * - A derived role the overrides do not set is recomputed from its resolved source: the light
+ *   `ai.surface`, `ai.border` and `ai.badgeBackground` are tints of `brand.secondary`.
+ * - A member the overrides set explicitly keeps that value. A complete `TrinityTokens` input
+ *   sets every member, so a member that differs from its source counts as an intentional
+ *   override.
+ *
+ * Every Trinity theme carries its resolved set as `theme.trinityTokens`, and the runtime CSS
+ * functions resolve their input the same way, so `injectTrinityCssVariables(theme.trinityTokens)`
+ * matches the theme. Untouched subtrees keep the defaults' object identity.
+ *
+ * @since 2.13.0
+ */
+export declare function resolveTrinityTokens(overrides?: TrinityTokenOverrides | TrinityTokens | null): TrinityTokens;
+//# sourceMappingURL=token-merge.d.ts.map

package/dist/token-merge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-merge.d.ts","sourceRoot":"","sources":["../src/token-merge.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9C;;;GAGG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,SAAS,SAAS,OAAO,EAAE,GACrD,CAAC,GACD,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,GACrC,CAAC,GACD,CAAC,SAAS,MAAM,GACd;KAAG,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,GACtC,CAAC,CAAC;AAEV;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,GAAG,WAAW,CAAC,aAAa,CAAC,CAAC;AAyC/D;;;;GAIG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAI9E;AAoDD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,EAClD,IAAI,EAAE,CAAC,EACP,SAAS,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,GAC3C,CAAC,CAOH;AAmCD;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,KAAK,CAAC,SAAS,CAAC,SAAS,MAAM,EAAE,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAQ5F;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,CAAC,EAAE,qBAAqB,GAAG,aAAa,GAAG,IAAI,GACvD,aAAa,CAyBf"}

package/dist/token-serialization.d.ts

@@ -0,0 +1,65 @@
+export type CssTokenCategory = 'dimension' | 'duration' | 'fontWeight' | 'lineHeight' | 'opacity' | 'raw' | 'zIndex';
+/**
+ * Serialize a token value according to its declared CSS value category.
+ *
+ * Category metadata is supplied by each token emitter. Token names never
+ * influence units here, so static and runtime CSS cannot diverge because a
+ * key happens to contain (or omit) a particular substring.
+ */
+export declare function serializeCssTokenValue(value: unknown, category: CssTokenCategory, tokenName?: string): string;
+export type CssTokenCategoryResolver = (tokenPath: readonly string[], value: unknown) => CssTokenCategory;
+/** Explicit metadata for mixed semantic typography trees. */
+export declare const semanticTypographyCategory: CssTokenCategoryResolver;
+/**
+ * Semantic motion (E-13): every group is a time (`duration`, `loop`, `stagger`) except
+ * `easing`, whose values are timing functions. Shared by the static and runtime generators,
+ * so a duration token that is not a CSS time fails both the same way.
+ */
+export declare const semanticMotionCategory: CssTokenCategoryResolver;
+/**
+ * Component numeric tokens are dimensions except for these explicitly typed
+ * public leaves. Step 6 can replace this contained metadata with the planned
+ * normalized token graph without changing serialization behavior.
+ */
+export declare const componentTokenCategory: CssTokenCategoryResolver;
+/**
+ * A Trinity custom property name: `--trinity-` and lower-case words of
+ * letters and digits joined by single hyphens. A dot is not allowed in an
+ * unescaped CSS identifier, so `--trinity-space-0.5` is dropped by browsers
+ * and rejected by Lightning CSS (A24-F2).
+ */
+export declare const CSS_CUSTOM_PROPERTY_NAME: RegExp;
+/** `true` when `name` is a valid Trinity custom property name. */
+export declare function isValidCssCustomPropertyName(name: string): boolean;
+/**
+ * The custom property name for a token path, shared by the static generator
+ * (scripts/generate-css-from-tokens.ts) and the runtime one (src/theme.ts) so
+ * the two cannot name the same token differently. camelCase segments become
+ * kebab-case, and a fractional key's dot becomes a hyphen
+ * (`spacing[0.5]` → `--trinity-space-0-5`). Any other character outside
+ * `[a-z0-9-]` also becomes a hyphen, so a consumer's token key cannot produce
+ * a declaration the browser drops.
+ */
+export declare function cssCustomPropertyName(segments: ReadonlyArray<string | number>): string;
+/**
+ * A CSS time token in milliseconds: `'200ms'` → 200, `'1.5s'` → 1500; a number is taken as
+ * milliseconds already. Throws on anything else, so a malformed motion token fails loudly
+ * instead of becoming `NaN`. Shared by the theme (theme.transitions) and the internal motion
+ * helpers.
+ */
+export declare function cssTimeToMs(value: string | number, tokenName?: string): number;
+/**
+ * Semantic spacing groups whose members are JavaScript-only: they get no CSS custom property.
+ * `layout.containerQuery` holds container widths for `@container` conditions, and a custom
+ * property cannot be an `@container` or `@media` operand (remediation H-08), so a variable
+ * would be informational at best and removing it later would be a major change (the E-19
+ * amendment).
+ */
+export declare const JS_ONLY_SEMANTIC_SPACING: Readonly<Record<string, readonly string[]>>;
+/**
+ * `semanticTokens.spacing` (or a resolved token set's) without its JavaScript-only members,
+ * for the CSS generators. Both the static and the runtime generator call it, so neither
+ * emits `--trinity-layout-container-query-*`.
+ */
+export declare function cssSemanticSpacing<T extends object>(spacing: T): T;
+//# sourceMappingURL=token-serialization.d.ts.map

package/dist/token-serialization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-serialization.d.ts","sourceRoot":"","sources":["../src/token-serialization.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GACxB,WAAW,GACX,UAAU,GACV,YAAY,GACZ,YAAY,GACZ,SAAS,GACT,KAAK,GACL,QAAQ,CAAC;AA2Bb;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,gBAAgB,EAC1B,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,CA0DR;AAED,MAAM,MAAM,wBAAwB,GAAG,CACrC,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,KAAK,EAAE,OAAO,KACX,gBAAgB,CAAC;AAStB,6DAA6D;AAC7D,eAAO,MAAM,0BAA0B,EAAE,wBACyB,CAAC;AAEnE;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,wBACM,CAAC;AAS5C;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,wBAEc,CAAC;AAMpD;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,QAAyC,CAAC;AAE/E,kEAAkE;AAClE,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAElE;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,aAAa,CAAC,MAAM,GAAG,MAAM,CAAC,GAAG,MAAM,CAQtF;AAQD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAU9E;AAMD;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAEhF,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,CAWlE"}