@splenddev/kreativ-core 0.0.1 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. package/README.md +70 -13
  2. package/dist/{common-CxqD2cxB.d.cts → common-1QyKLdTc.d.cts} +1 -1
  3. package/dist/{common-CxqD2cxB.d.ts → common-1QyKLdTc.d.ts} +1 -1
  4. package/dist/{hooks.cjs → hooks/index.cjs} +2 -2
  5. package/dist/hooks/index.cjs.map +1 -0
  6. package/dist/{hooks.d.ts → hooks/index.d.cts} +10 -4
  7. package/dist/{hooks.d.cts → hooks/index.d.ts} +10 -4
  8. package/dist/{hooks.js → hooks/index.js} +2 -2
  9. package/dist/hooks/index.js.map +1 -0
  10. package/dist/index.cjs +25 -1039
  11. package/dist/index.cjs.map +1 -1
  12. package/dist/index.d.cts +351 -7
  13. package/dist/index.d.ts +351 -7
  14. package/dist/index.js +26 -1010
  15. package/dist/index.js.map +1 -1
  16. package/dist/types/index.cjs +4 -0
  17. package/dist/types/index.cjs.map +1 -0
  18. package/dist/{types.d.ts → types/index.d.cts} +2 -2
  19. package/dist/{types.d.cts → types/index.d.ts} +2 -2
  20. package/dist/types/index.js +3 -0
  21. package/dist/types/index.js.map +1 -0
  22. package/dist/{utils.cjs → utils/index.cjs} +2 -2
  23. package/dist/utils/index.cjs.map +1 -0
  24. package/dist/{utils.d.cts → utils/index.d.cts} +1 -1
  25. package/dist/{utils.d.ts → utils/index.d.ts} +1 -1
  26. package/dist/{utils.js → utils/index.js} +2 -2
  27. package/dist/utils/index.js.map +1 -0
  28. package/package.json +1 -6
  29. package/dist/hooks.cjs.map +0 -1
  30. package/dist/hooks.js.map +0 -1
  31. package/dist/theme.cjs +0 -1183
  32. package/dist/theme.cjs.map +0 -1
  33. package/dist/theme.d.cts +0 -2724
  34. package/dist/theme.d.ts +0 -2724
  35. package/dist/theme.js +0 -1142
  36. package/dist/theme.js.map +0 -1
  37. package/dist/types.cjs +0 -4
  38. package/dist/types.cjs.map +0 -1
  39. package/dist/types.js +0 -3
  40. package/dist/types.js.map +0 -1
  41. package/dist/useColorMode-B7eyS27H.d.ts +0 -10
  42. package/dist/useColorMode-tvcgvc4V.d.cts +0 -10
  43. package/dist/utils.cjs.map +0 -1
  44. package/dist/utils.js.map +0 -1
package/dist/index.d.ts CHANGED
@@ -1,10 +1,354 @@
1
- export { A as AnimationTokens, B as BaseBreakpoint, a as BaseColor, b as BaseProps, c as BaseVariant, d as BreakpointTokens, C as CSSPropertiesWithVars, e as ClearableProps, f as ColorModeValue, g as ColorProps, h as ColorScale, i as ColorTokens, j as ControlledProps, D as DeepPartial, k as DesignTokens, l as DisabledProps, E as Easing, m as EmbeddedProps, F as FontSizeTokens, n as FontTokens, o as FontWeightTokens, p as FormFieldStatus, q as FullWidthProps, L as LetterSpacingTokens, r as LineHeightTokens, s as LoadingProps, O as Orientation, t as OrientationProps, R as RadiusTokens, u as ReportedValidity, v as RequiredStateControlProps, w as ResponsiveStyles, x as ResponsiveValue, S as SemanticColorTokens, y as SemanticToken, z as SemanticTokens, G as ShadowTokens, H as Size, I as SizeProps, J as SizeValue, K as SpacingTokens, M as StateControlProps, N as StateProps, P as StatusProps, Q as Styleable, T as ThemeAnimation, U as TokenDefinition, V as TokenGroup, W as TokenReferenceString, X as TokenValue, Y as TrimProps, Z as Typography, _ as TypographyProps, $ as TypographyStyle, a0 as UndoRedoProps, a1 as ValidateOn, a2 as ValidateProps, a3 as ValidationResult, a4 as ValueProps, a5 as Variant, a6 as VariantProps } from './common-CxqD2cxB.js';
2
- import { Theme, ColorMode, ResolvedTokens } from './types.js';
3
- export { CustomRecipes, DefaultRecipeCollection, IntensityMap, RecipeCollection, RecipeCompoundVariant, RecipeDefinition, RecipeStyle, RecipeVariant, RecipeVariantValue, SizeScale, SizeToken, StyleObject, StyleValue, ThemeOverride, ThemeTogglerTransition, ThemeTransition } from './types.js';
4
- export { CycleValidationResult, ExtractPath, Invalid, IsTokenReference, PathExists, ResolvePath, SplitPath, ValidateRecipeSection, ValidateRecipes, ValidateReferenceExists, ValidateSemanticTokenSection, ValidateSemanticTokens, ValidateSizes, ValidateSizesSection, ValidateTheme, ValidateTokenSection, ValidateTokens, ValidateTypography, ValidateTypographyReferencesSection, ValidateTypographySection, assertNoCycles, buttonBase, buttonColors, buttonGroupRecipe, buttonRecipe, buttonVariants, checkboxRecipe, containerReccipe, defaultRecipes, defaultSemanticTokens, defaultSizes, defaultTheme, defaultTokens, defaultTypography, defineRecipe, defineSemanticToken, defineSemanticTokens, defineSize, defineSizes, defineTheme, defineToken, defineTokens, defineTypography, extendRecipe, extendRecipes, extendSemanticTokens, extendSizes, extendTheme, extendTokens, extendTypography, formControlBase, formControlRecipe, formControlVariants, inputBase, inputRecipe, linkRecipe, markdownEditorRecipe, switchRecipe, textareaRecipe, validateNoCycles } from './theme.js';
1
+ import { T as TokenValue, b as SemanticToken, c as Typography, D as DesignTokens, d as TokenDefinition, e as TokenReferenceString$1, f as SemanticTokens } from './common-1QyKLdTc.js';
2
+ export { A as AnimationTokens, B as BaseBreakpoint, g as BaseColor, h as BaseProps, i as BaseVariant, j as BreakpointTokens, C as CSSPropertiesWithVars, k as ClearableProps, l as ColorModeValue, m as ColorProps, n as ColorScale, o as ColorTokens, p as ControlledProps, q as DeepPartial, r as DisabledProps, E as Easing, s as EmbeddedProps, F as FontSizeTokens, t as FontTokens, u as FontWeightTokens, v as FormFieldStatus, w as FullWidthProps, L as LetterSpacingTokens, x as LineHeightTokens, y as LoadingProps, O as Orientation, z as OrientationProps, G as RadiusTokens, H as ReportedValidity, I as RequiredStateControlProps, a as ResponsiveStyles, R as ResponsiveValue, J as SemanticColorTokens, K as ShadowTokens, S as Size, M as SizeProps, N as SizeValue, P as SpacingTokens, Q as StateControlProps, U as StateProps, V as StatusProps, W as Styleable, X as ThemeAnimation, Y as TokenGroup, Z as TrimProps, _ as TypographyProps, $ as TypographyStyle, a0 as UndoRedoProps, a1 as ValidateOn, a2 as ValidateProps, a3 as ValidationResult, a4 as ValueProps, a5 as Variant, a6 as VariantProps } from './common-1QyKLdTc.js';
3
+ import { SizeToken, SizeScale, RecipeDefinition, Theme, ColorMode, ResolvedTokens } from './types/index.js';
4
+ export { CustomRecipes, DefaultRecipeCollection, IntensityMap, RecipeCollection, RecipeCompoundVariant, RecipeStyle, RecipeVariant, RecipeVariantValue, StyleObject, StyleValue, ThemeOverride, ThemeTogglerTransition, ThemeTransition } from './types/index.js';
5
5
  import * as React from 'react';
6
- export { U as UseColorModeReturn, u as useColorMode } from './useColorMode-B7eyS27H.js';
7
- export { CreateComponentConfig, CreateFromPropsInput, KuiComponent, KuiMeta, KuiRole, KuiSkeletonHint, KuiSupports, ResolvedResponsiveValue, composeRefs, createComponent, createFromProps, deepMerge, hasKuiMeta, isResponsiveValue, mergeResponsiveValue, resolveResponsiveValue, resolveTokenReference, resolveTypography, toResponsiveClasses } from './utils.js';
6
+ export { CreateComponentConfig, CreateFromPropsInput, KuiComponent, KuiMeta, KuiRole, KuiSkeletonHint, KuiSupports, ResolvedResponsiveValue, composeRefs, createComponent, createFromProps, deepMerge, hasKuiMeta, isResponsiveValue, mergeResponsiveValue, resolveResponsiveValue, resolveTokenReference, resolveTypography, toResponsiveClasses } from './utils/index.js';
7
+
8
+ declare function defineToken<T extends TokenValue>(value: T): {
9
+ value: T;
10
+ };
11
+ declare function defineTokens<T extends Record<string, TokenValue>>(tokens: T): { [K in keyof T]: ReturnType<typeof defineToken<T[K]>>; };
12
+
13
+ /**
14
+ * Defines a semantic token that shares a single value across both
15
+ * light and dark modes (the explicit sameForBothModes shorthand).
16
+ */
17
+ declare function defineSemanticToken<T extends TokenValue>(value: T): SemanticToken<T>;
18
+ /**
19
+ * Defines a semantic token with distinct light and dark values.
20
+ */
21
+ declare function defineSemanticToken<T extends TokenValue>(light: T, dark: T): SemanticToken<T>;
22
+ type SemanticTokenInput<T extends TokenValue> = T | {
23
+ light: T;
24
+ dark: T;
25
+ };
26
+ declare function defineSemanticTokens<T extends Record<string, SemanticTokenInput<TokenValue>>>(tokens: T): {
27
+ [K in keyof T]: SemanticToken<T[K] extends {
28
+ light: infer V;
29
+ dark: infer _;
30
+ } ? V extends TokenValue ? V : never : T[K] extends TokenValue ? T[K] : never>;
31
+ };
32
+
33
+ declare function defineSize<const T extends SizeToken>(size: T): T;
34
+ declare function defineSizes<const T extends SizeScale>(sizes: T): T;
35
+
36
+ declare function defineTypography<const T extends Typography>(typography: T): T;
37
+
38
+ declare function defineRecipe<const T extends RecipeDefinition>(recipe: T): T;
39
+
40
+ /**
41
+ * Branded type-level error, surfaced at the defineTheme() call site
42
+ * when a section validator fails. Section validators wrap this in a
43
+ * section-named key (e.g. { semanticTokens: Invalid<...> }) rather
44
+ * than composing into an unreadable anonymous intersection.
45
+ *
46
+ * Path-tracking (__kuiPath) is a locked stretch goal, not yet built —
47
+ * ship section-named base errors first, confirm they render legibly
48
+ * in editor tooltips, then treat path-tracking as a follow-on.
49
+ */
50
+ type Invalid<Message extends string> = {
51
+ readonly __kuiError: Message;
52
+ };
53
+
54
+ /**
55
+ * A token reference string, e.g. "{colors.brand.500}" — legal for
56
+ * semantic tokens, but NOT legal for primitive tokens. defineToken's
57
+ * "no token references" rule is what makes defineTheme's cycle
58
+ * detection tractable (cycle detection only needs to walk
59
+ * semantic→semantic edges).
60
+ */
61
+ type TokenReferenceString = `{${string}}`;
62
+ type IsTokenReference$1<T> = T extends TokenReferenceString ? true : false;
63
+ /**
64
+ * Recursively checks that every leaf in a token tree is a real
65
+ * terminal TokenValue, never a "{...}" reference string.
66
+ */
67
+ type ValidateTokenLeaf<T> = T extends TokenDefinition<infer V> ? IsTokenReference$1<V> extends true ? Invalid<"Primitive tokens cannot contain token references — use defineSemanticToken instead"> : unknown : T extends Record<string, unknown> ? ValidateTokenTree<T> : unknown;
68
+ type ValidateTokenTree<T> = {
69
+ [K in keyof T]: ValidateTokenLeaf<T[K]>;
70
+ }[keyof T] extends infer Result ? Result extends Invalid<any> ? Result : unknown : never;
71
+ type ValidateTokens<T extends {
72
+ tokens?: unknown;
73
+ }> = T["tokens"] extends DesignTokens ? ValidateTokenTree<T["tokens"]> : unknown;
74
+ type ValidateTokenSection<T extends {
75
+ tokens?: unknown;
76
+ }> = ValidateTokens<T> extends infer Result ? Result extends Invalid<any> ? {
77
+ tokens: Result;
78
+ } : unknown : never;
79
+
80
+ type IsTokenReference<T> = T extends TokenReferenceString$1 ? true : false;
81
+ /**
82
+ * Strips the surrounding "{" "}" from a reference string, giving the
83
+ * raw dotted path, e.g. "{colors.brand.500}" -> "colors.brand.500".
84
+ */
85
+ type ExtractPath<T extends string> = T extends `{${infer Path}}` ? Path : never;
86
+ /**
87
+ * Splits a dotted path string into a tuple of segments.
88
+ * "colors.brand.500" -> ["colors", "brand", "500"]
89
+ */
90
+ type SplitPath<S extends string> = S extends `${infer Head}.${infer Rest}` ? [Head, ...SplitPath<Rest>] : [S];
91
+ /**
92
+ * Looks up a single path segment against T's keys, tolerating the
93
+ * common case where the segment is a numeric-looking string
94
+ * ("500") but the actual object key is a numeric literal (500) —
95
+ * e.g. color scale steps. TS's keyof does not match these directly.
96
+ */
97
+ type LookupKey<T, Head extends string> = Head extends keyof T ? Head : Head extends `${infer N extends number}` ? N extends keyof T ? N : never : never;
98
+ /**
99
+ * Walks an object tree along a tuple of path segments. Resolves to
100
+ * the value at that path, or `never` if any segment doesn't exist.
101
+ */
102
+ type ResolvePath<T, Path extends readonly string[]> = Path extends [infer Head extends string, ...infer Rest] ? LookupKey<T, Head> extends infer K ? K extends keyof T ? Rest extends readonly string[] ? Rest["length"] extends 0 ? T[K] : ResolvePath<T[K], Rest> : never : never : never : never;
103
+ /**
104
+ * True if a dotted-path reference resolves to something inside T.
105
+ */
106
+ type PathExists<T, Ref extends string> = ResolvePath<T, SplitPath<ExtractPath<Ref>>> extends never ? false : true;
107
+ /**
108
+ * Validates that a single reference string, if it is one, actually
109
+ * resolves against the given tokens/semanticTokens tree. Non-reference
110
+ * values pass through as `unknown` (valid).
111
+ */
112
+ type ValidateReferenceExists<Value, Tokens, _Path extends string = "unknown path"> = Value extends TokenReferenceString$1 ? PathExists<Tokens, Value> extends true ? unknown : Invalid<`References an unknown token: "${Value}"`> : unknown;
113
+
114
+ /**
115
+ * Extracts the underlying value(s) out of a semantic token's
116
+ * ColorModeValue, to run existence checks against each.
117
+ */
118
+ type ExtractCheckableValues<V> = V extends {
119
+ sameForBothModes: true;
120
+ value: infer X;
121
+ } ? [X] : V extends {
122
+ light: infer L;
123
+ dark: infer D;
124
+ } ? [L, D] : [];
125
+ /**
126
+ * Validates a single semantic token leaf: every reference it
127
+ * contains (light and/or dark) must resolve against the combined
128
+ * tokens+semanticTokens tree.
129
+ *
130
+ * NOTE: semantic->semantic cycle detection is NOT done here — it
131
+ * was attempted at the type level and hit TypeScript inference
132
+ * edge cases in recursive conditional types that made it unreliable
133
+ * (false positives on valid semantic->primitive references). Cycle
134
+ * detection is handled at runtime instead — see validateNoCycles in
135
+ * runtime/validateCycles.ts, called from defineTheme/extendTheme.
136
+ */
137
+ type ValidateSemanticLeaf<Leaf, AllTokens> = Leaf extends {
138
+ value: infer V;
139
+ } ? ExtractCheckableValues<V> extends infer Values extends readonly unknown[] ? {
140
+ [I in keyof Values]: Values[I] extends TokenReferenceString$1 ? ValidateReferenceExists<Values[I], AllTokens> : unknown;
141
+ }[number] extends infer Result ? Result extends Invalid<any> ? Result : unknown : never : unknown : unknown;
142
+ /**
143
+ * Recursively walks the semanticTokens tree, validating every leaf.
144
+ */
145
+ type ValidateSemanticTree<Tree, AllTokens> = {
146
+ [K in keyof Tree]: Tree[K] extends {
147
+ value: unknown;
148
+ } ? ValidateSemanticLeaf<Tree[K], AllTokens> : ValidateSemanticTree<Tree[K], AllTokens>;
149
+ }[keyof Tree] extends infer Result ? Result extends Invalid<any> ? Result : unknown : never;
150
+ type ValidateSemanticTokens<T extends {
151
+ tokens?: unknown;
152
+ semanticTokens?: unknown;
153
+ }> = T["semanticTokens"] extends SemanticTokens ? ValidateSemanticTree<T["semanticTokens"], (T["tokens"] extends DesignTokens ? T["tokens"] : {}) & T["semanticTokens"]> : unknown;
154
+ type ValidateSemanticTokenSection<T extends {
155
+ tokens?: unknown;
156
+ semanticTokens?: unknown;
157
+ }> = ValidateSemanticTokens<T> extends infer Result ? Result extends Invalid<any> ? {
158
+ semanticTokens: Result;
159
+ } : unknown : never;
160
+
161
+ /**
162
+ * Validates a single SizeToken's fontSize: if present, it MUST be a
163
+ * "{typography.someVariant}"-style reference into the theme's
164
+ * Typography collection — a raw CSS value (e.g. "1rem") is invalid.
165
+ *
166
+ * This is a cross-section rule (spans sizes + typography), which is
167
+ * why it lives in defineTheme's territory rather than defineSize or
168
+ * defineTypography individually — neither of those functions can see
169
+ * the other section in isolation.
170
+ */
171
+ type ValidateSizeFontSize<FontSize, TypographyTree> = FontSize extends undefined ? unknown : FontSize extends TokenReferenceString$1 ? ValidateReferenceExists<FontSize, {
172
+ typography: TypographyTree;
173
+ }> : Invalid<`SizeToken.fontSize must reference a typography preset (e.g. "{typography.body}"), not a raw value: "${FontSize & string}"`>;
174
+ /**
175
+ * Walks every size in the SizeScale, validating each one's fontSize.
176
+ */
177
+ type ValidateSizeScaleFontSizes<Sizes, TypographyTree> = {
178
+ [K in keyof Sizes]: Sizes[K] extends {
179
+ fontSize?: infer F;
180
+ } ? ValidateSizeFontSize<F, TypographyTree> : unknown;
181
+ }[keyof Sizes] extends infer Result ? Result extends Invalid<any> ? Result : unknown : never;
182
+ type ValidateTypography<T extends {
183
+ typography?: unknown;
184
+ sizes?: unknown;
185
+ }> = T["sizes"] extends SizeScale ? ValidateSizeScaleFontSizes<T["sizes"], T["typography"] extends Typography ? T["typography"] : {}> : unknown;
186
+ /**
187
+ * Cross-section rule: SizeToken.fontSize -> Typography preset.
188
+ *
189
+ * Despite the name (kept for continuity with the ownership-tree
190
+ * discussion, which described this as "the typography section" of
191
+ * cross-section rules), the actual invalid DATA here always lives on
192
+ * the `sizes` side (a bad fontSize value on a SizeToken), never on
193
+ * `typography` itself — so the resulting error is keyed under
194
+ * `sizes`, not `typography`. Keying it under `typography` would
195
+ * collide with T's own real `typography` field when intersected onto
196
+ * T in defineTheme's signature (T & ValidateTheme<T>), since TS would
197
+ * then require the theme's actual typography VALUE to also satisfy
198
+ * the Invalid<...> shape — which is a real bug that surfaced and was
199
+ * fixed during end-to-end testing of defineTheme.
200
+ */
201
+ type ValidateTypographySection<T extends {
202
+ typography?: unknown;
203
+ sizes?: unknown;
204
+ }> = ValidateTypography<T> extends infer Result ? Result extends Invalid<any> ? {
205
+ sizes: Result;
206
+ } : unknown : never;
207
+ /**
208
+ * Validates a single TypographyStyle field: if its value is a
209
+ * "{...}" reference, it MUST resolve against the theme's primitive
210
+ * tokens (e.g. "{fonts.body}", "{fontWeights.bold}"). A raw literal
211
+ * value (e.g. "16px", 400) is always valid — references are opt-in,
212
+ * not required. This is DIFFERENT from the sizes.fontSize rule above:
213
+ * there, a reference is REQUIRED; here, a reference is OPTIONAL but
214
+ * must resolve if present.
215
+ */
216
+ type ValidateTypographyField<FieldValue, TokensTree> = FieldValue extends TokenReferenceString$1 ? ValidateReferenceExists<FieldValue, TokensTree> : unknown;
217
+ /**
218
+ * Walks every field of a single TypographyStyle variant (fontFamily,
219
+ * fontSize, fontWeight, lineHeight, letterSpacing).
220
+ */
221
+ type ValidateTypographyStyleFields<Style, TokensTree> = {
222
+ [K in keyof Style]: ValidateTypographyField<Style[K], TokensTree>;
223
+ }[keyof Style] extends infer Result ? Result extends Invalid<any> ? Result : unknown : never;
224
+ /**
225
+ * Walks every variant in the Typography collection (body, heading,
226
+ * label, etc.), validating every field's token references.
227
+ */
228
+ type ValidateTypographyTokenReferences<TypographyTree, TokensTree> = {
229
+ [K in keyof TypographyTree]: ValidateTypographyStyleFields<TypographyTree[K], TokensTree>;
230
+ }[keyof TypographyTree] extends infer Result ? Result extends Invalid<any> ? Result : unknown : never;
231
+ /**
232
+ * Cross-section rule: TypographyStyle fields (fontFamily, fontSize,
233
+ * fontWeight, lineHeight, letterSpacing) MAY reference primitive
234
+ * tokens (e.g. "{fonts.body}") — if they do, the reference must
235
+ * resolve. This is a genuinely typography-owned rule (the invalid
236
+ * data lives in `typography` itself, not `sizes`), so it's kept as
237
+ * its own separately-exported section validator rather than folded
238
+ * into ValidateTypographySection above — composing both under one
239
+ * name would reintroduce the same key-collision risk that rule
240
+ * already caused once, since this one's natural key IS `typography`.
241
+ */
242
+ type ValidateTypographyReferencesSection<T extends {
243
+ typography?: unknown;
244
+ tokens?: unknown;
245
+ }> = (T["typography"] extends Typography ? ValidateTypographyTokenReferences<T["typography"], T["tokens"] extends DesignTokens ? T["tokens"] : {}> : unknown) extends infer Result ? Result extends Invalid<any> ? {
246
+ typography: Result;
247
+ } : unknown : never;
248
+
249
+ type ValidateRecipes<_T extends {
250
+ recipes?: unknown;
251
+ }> = unknown;
252
+ type ValidateRecipeSection<_T extends {
253
+ recipes?: unknown;
254
+ }> = unknown;
255
+
256
+ /**
257
+ * Sizes section validator.
258
+ *
259
+ * Deliberately a no-op / pass-through. A SizeToken's fields are:
260
+ * height, width, paddingX, paddingY, fontSize, gap, iconSize, radius,
261
+ * separatorSize — and fontSize is the ONLY one of those that
262
+ * references another theme section (a typography preset). Every
263
+ * other field is a raw CSS length with no cross-section relationship
264
+ * to validate.
265
+ *
266
+ * The fontSize -> typography-preset rule is already fully owned by
267
+ * ValidateTypographySection (see typography.ts) — that's where it's
268
+ * implemented and tested, since it's conceptually "does this
269
+ * typography reference resolve", not "is this size valid". There is
270
+ * currently no independent rule left for ValidateSizesSection to own.
271
+ *
272
+ * This slot still exists (rather than being omitted from
273
+ * ValidateTheme's composition) so the "why is this empty" reasoning
274
+ * is documented in code, and so a real future sizes-only rule has an
275
+ * obvious home to land in without restructuring the composition.
276
+ */
277
+ type ValidateSizes<_T extends {
278
+ sizes?: unknown;
279
+ }> = unknown;
280
+ type ValidateSizesSection<_T extends {
281
+ sizes?: unknown;
282
+ }> = unknown;
283
+
284
+ /**
285
+ * Composes all section validators into one type. Each section
286
+ * resolves to `unknown` (a no-op in the intersection) on success, or
287
+ * a section-named `{ sectionName: Invalid<...> }` object on failure
288
+ * — so a failing theme surfaces as a legible, named error at the
289
+ * defineTheme() call site instead of an anonymous intersection wall.
290
+ *
291
+ * ValidateRecipeSection and ValidateSizesSection are currently
292
+ * documented no-ops (see recipes.ts / sizes.ts for why) but are kept
293
+ * in the composition so the full section list is visible here and
294
+ * either can gain real rules later without changing this shape.
295
+ *
296
+ * ValidateTypographySection and ValidateTypographyReferencesSection
297
+ * are two DIFFERENT rules kept as separate types (not merged): the
298
+ * former validates sizes.fontSize -> typography (keyed under `sizes`,
299
+ * required reference), the latter validates typography's own fields
300
+ * -> tokens (keyed under `typography`, optional reference). Merging
301
+ * them would risk reintroducing the same key-collision bug already
302
+ * found and fixed once during this effort.
303
+ */
304
+ type ValidateTheme<T extends Theme> = ValidateTokenSection<T> & ValidateSemanticTokenSection<T> & ValidateTypographySection<T> & ValidateTypographyReferencesSection<T> & ValidateRecipeSection<T> & ValidateSizesSection<T>;
305
+
306
+ /**
307
+ * Defines a Kreativ UI theme.
308
+ *
309
+ * Type-safe boundary for creating themes while preserving the exact
310
+ * structure and types of the supplied theme. Does not merge with the
311
+ * default theme or mutate the provided object — extension/resolution
312
+ * are handled separately by extendTheme.
313
+ *
314
+ * `T & ValidateTheme<T>` is what actually enforces validation at the
315
+ * call site: ValidateTheme<T> resolves to `unknown` (a no-op) when
316
+ * every section passes, or a section-named `{ tokens: Invalid<...> }`
317
+ * / `{ semanticTokens: Invalid<...> }` / etc. object when a section
318
+ * fails. Intersecting that onto the parameter type means a failing
319
+ * theme produces a real compile error naming the failing section and
320
+ * message, not just a generic "not assignable to Theme".
321
+ *
322
+ * Reference *existence* (does "{colors.brand.500}" resolve to a real
323
+ * token) is checked at compile time via ValidateSemanticTokenSection,
324
+ * as part of ValidateTheme above. Reference *cycles* (semantic token
325
+ * A -> B -> A) can't be reliably caught at the type level (hit TS
326
+ * inference edge cases in recursive conditional types), so they're
327
+ * checked here at call time instead, via assertNoCycles.
328
+ */
329
+ declare function defineTheme<T extends Theme>(theme: T & ValidateTheme<T>): T;
330
+
331
+ interface CycleValidationResult {
332
+ valid: boolean;
333
+ cyclePath?: string[];
334
+ }
335
+ /**
336
+ * Walks every semantic token's reference chain looking for a
337
+ * semantic->semantic cycle. Reference *existence* (does the path
338
+ * resolve at all) is validated separately at the type level via
339
+ * ValidateSemanticTokenSection — this function only detects cycles
340
+ * among references that do resolve to another semantic token.
341
+ *
342
+ * A reference that resolves to nothing (dangling) or to a primitive
343
+ * token is a dead end for cycle-walking purposes here, not an error
344
+ * this function raises — that's the type-level existence check's job.
345
+ */
346
+ declare function validateNoCycles(semanticTokens: SemanticTokens): CycleValidationResult;
347
+ /**
348
+ * Throws a descriptive error if a semantic->semantic cycle is found.
349
+ * Intended to be called from defineTheme/extendTheme.
350
+ */
351
+ declare function assertNoCycles(semanticTokens: SemanticTokens): void;
8
352
 
9
353
  interface ThemeContextValue {
10
354
  theme: Theme;
@@ -18,4 +362,4 @@ declare const ThemeContext: React.Context<ThemeContextValue | null>;
18
362
 
19
363
  declare function useTheme(): ThemeContextValue;
20
364
 
21
- export { ColorMode, ResolvedTokens, Theme, ThemeContext, type ThemeContextValue, useTheme };
365
+ export { ColorMode, type CycleValidationResult, DesignTokens, type ExtractPath, type Invalid, type IsTokenReference, type PathExists, RecipeDefinition, type ResolvePath, ResolvedTokens, SemanticToken, SemanticTokens, SizeScale, SizeToken, type SplitPath, Theme, ThemeContext, type ThemeContextValue, TokenDefinition, TokenReferenceString$1 as TokenReferenceString, TokenValue, Typography, type ValidateRecipeSection, type ValidateRecipes, type ValidateReferenceExists, type ValidateSemanticTokenSection, type ValidateSemanticTokens, type ValidateSizes, type ValidateSizesSection, type ValidateTheme, type ValidateTokenSection, type ValidateTokens, type ValidateTypography, type ValidateTypographyReferencesSection, type ValidateTypographySection, assertNoCycles, defineRecipe, defineSemanticToken, defineSemanticTokens, defineSize, defineSizes, defineTheme, defineToken, defineTokens, defineTypography, useTheme, validateNoCycles };