@csszyx/runtime 0.10.10 → 0.10.12

package/dist/index.d.cts

@@ -506,6 +506,10 @@ declare function clearHydrationErrors(): void;
 /**
  * Gets the count of aborted subtrees.
  *
+ * Counts abort marks minus recoveries this session. Aborted elements that were
+ * garbage-collected after leaving the DOM stay counted — the number reports
+ * how many aborts happened, not how many aborted elements are still alive.
+ *
  * @returns {number} Number of aborted subtrees
  */
 declare function getAbortedSubtreeCount(): number;
@@ -630,7 +634,8 @@ declare function startHydration(): void;
 declare function endHydration(): void;
 
 /**
- * Merge className strings with last-wins override per utility, mangle-aware.
+ * Merge className strings with last-wins override per utility, mangle-aware and
+ * memoized (see the memo note above — repeated inputs return in one Map lookup).
  *
  * Intended for the single resolution point in a layered design-system component
  * (typically at the leaf Box): combine the component's default classes with the
@@ -643,6 +648,63 @@ declare function endHydration(): void;
  */
 declare function szcn(...inputs: (string | false | null | undefined)[]): string;
 
+/**
+ * Value-set-aware conflict groups for the ambiguous utility prefixes.
+ *
+ * `szcn` merges by utility prefix, but eight prefixes span MORE than one CSS
+ * property (`text-sm` is font-size, `text-red-500` is color), so they used to
+ * be excluded from dedup entirely — a consumer's `text-sm` override after a
+ * `text-base` default kept BOTH classes and the stylesheet order, not the
+ * className order, picked the winner. This module classifies a token's VALUE
+ * into a property group (closed keyword sets + shape validators), so same-group
+ * tokens dedupe last-wins while different properties keep co-existing.
+ *
+ * Fail-safe contract (inherited from szcn): classification may only ever err
+ * toward `null` = keep-both. A value that matches no group — or matches more
+ * than one — is never merged away.
+ *
+ * Custom `@theme` tokens: the build plugin auto-registers theme token names via
+ * `registerSzcnGroups` (see `virtual:csszyx/theme-groups`); apps can call it
+ * directly for hand-written CSS classes. Registration is guarded: a name that
+ * collides with a static value keyword of an affected prefix (e.g. a color
+ * token named `cover` — `bg-cover` is background-size) or that is registered in
+ * two conflicting categories is dropped with a dev warning, falling back to
+ * keep-both rather than guessing. The ambiguity drop is remembered across
+ * registration batches, so a later batch re-registering only one side cannot
+ * resurrect the name into a single category.
+ *
+ * @module
+ */
+/** Custom token categories accepted by {@link registerSzcnGroups}. */
+interface SzcnThemeGroups {
+    /** Color token names (`brand` → `text-brand`, `bg-brand`, `border-brand`, …). */
+    colors?: readonly string[];
+    /** Font-size token names (`huge` → `text-huge`). */
+    textSizes?: readonly string[];
+    /** Font-family token names (`display` → `font-display`). */
+    fontFamilies?: readonly string[];
+    /** Font-weight token names (`chunky` → `font-chunky`). */
+    fontWeights?: readonly string[];
+}
+/**
+ * Register custom theme token names so szcn can dedupe classes built from them
+ * (`text-brand` + `text-accent` → last wins). Idempotent and additive; called
+ * automatically by the build plugin from the app's `@theme` blocks, or manually
+ * for hand-written CSS utilities.
+ *
+ * Guard rails (both fall back to keep-both, never a wrong merge):
+ * - a name colliding with a static utility keyword of an affected prefix is
+ *   rejected (e.g. a color named `cover`);
+ * - a name registered in two conflicting categories (e.g. both a color and a
+ *   text size — `text-huge` would be unclassifiable) is removed from both,
+ *   and STAYS removed: later batches re-registering only one side are
+ *   rejected too, so registration order can never resurrect an ambiguous
+ *   name into a single category.
+ *
+ * @param groups - Custom token names per theme category.
+ */
+declare function registerSzcnGroups(groups: SzcnThemeGroups): void;
+
 /** Which side of the CSS box-model border a property acts on. */
 type BoxRole = 'outer' | 'inner';
 
@@ -837,6 +899,34 @@ declare function omitSz(sz: SzInput, selector: BoxSelector): SzObject;
  */
 declare function stripSzProps<T extends Record<string, unknown>>(props: T): Omit<T, 'sz'>;
 
+/**
+ * Narrow a compiled `szs` slot to the class string it becomes after build.
+ *
+ * A `Szs` slot is AUTHORED as an sz value (`szs={{ title: { text: 'lg' } }}`),
+ * but the compiler rewrites every slot to its class string before the component
+ * ever runs — so at runtime `szs?.title` IS a string, while its TYPE is still
+ * `SzPropValue`. Forwarding a slot into a `className?: string` prop therefore
+ * needed an `as string` cast in every compound component. This helper does that
+ * narrowing once, typed, and fail-safe: if a slot somehow reaches runtime
+ * uncompiled (a misconfigured build, or a dynamic value the v1 contract
+ * rejects), it returns `undefined` instead of letting an object coerce into
+ * `class="[object Object]"`.
+ *
+ * @param slot - One slot value from an `szs` prop.
+ * @returns The compiled class string, or `undefined` when the slot is absent or
+ *   was not compiled to a string.
+ *
+ * @example
+ * ```tsx
+ * function Card({ szs }: { szs?: Szs<'title' | 'body'> }) {
+ *     return <Box className={szcn('font-medium', szsClass(szs?.title))} />;
+ * }
+ * ```
+ *
+ * @module @csszyx/runtime/szs-class
+ */
+declare function szsClass(slot: unknown): string | undefined;
+
 /**
  * szv() — variant-based sz object factory.
  *
@@ -857,10 +947,14 @@ type VariantSchema = Record<string, Record<string, SzObject>>;
 type VariantSelection<V extends VariantSchema> = {
     [K in keyof V]?: keyof V[K] | null | undefined;
 };
-/** Configuration for a variant component: base styles, variants, and defaults. */
+/**
+ * Configuration for a variant component: base styles, variants, and defaults.
+ * `variants` is optional — a base-only config is a legitimate way to declare
+ * one compiled-and-extracted class bundle for reuse.
+ */
 interface SzvConfig<V extends VariantSchema> {
     base?: SzObject;
-    variants: V;
+    variants?: V;
     defaultVariants?: Partial<VariantSelection<V>>;
 }
 /**
@@ -992,5 +1086,5 @@ declare function isRuntimeInitialized(): boolean;
  */
 declare function resetRuntime(): void;
 
-export { DEFAULT_RUNTIME_CONFIG, VERSION, _sz, _sz2, _sz3, _szMerge, abortHydration, attemptCSRRecovery, classify, classifySzKey, clearHydrationErrors, computeMangleChecksumAsync, disableCSRRecovery, enableCSRRecovery, endHydration, getAbortedSubtreeCount, getHydrationErrors, getRecoveryMode, getRuntimeConfig, getSSRContext, guardHydration, has, hasRecoveryToken, hasSz, initRuntime, isCSRRecoveryAllowed, isHydrating, isHydrationAborted, isRuntimeInitialized, isSSREnvironment, isValidMangleMap, isValidManifest, loadMangleMapFromDOM, loadManifestFromDOM, omit, omitSz, pick, pickSz, resetRuntime, splitBox, splitBoxSz, startHydration, stripSzProps, szcn, szr, szv, validateHydrationClass, verifyAllTokens, verifyMangleChecksum, verifyMangleChecksumAsync, verifyMangleMapIntegrity, verifyRecoveryToken };
-export type { BoxRole, BoxSelector, Classification, HydrationError, HydrationErrorType, MangleMap, RecoveryManifest, RecoveryMode, RuntimeConfig, SSRContext, SplitBoxOptions, SplitBoxResult, SplitBoxSzOptions, SplitBoxSzResult, SzInput, TokenData, VerificationResult };
+export { DEFAULT_RUNTIME_CONFIG, VERSION, _sz, _sz2, _sz3, _szMerge, abortHydration, attemptCSRRecovery, classify, classifySzKey, clearHydrationErrors, computeMangleChecksumAsync, disableCSRRecovery, enableCSRRecovery, endHydration, getAbortedSubtreeCount, getHydrationErrors, getRecoveryMode, getRuntimeConfig, getSSRContext, guardHydration, has, hasRecoveryToken, hasSz, initRuntime, isCSRRecoveryAllowed, isHydrating, isHydrationAborted, isRuntimeInitialized, isSSREnvironment, isValidMangleMap, isValidManifest, loadMangleMapFromDOM, loadManifestFromDOM, omit, omitSz, pick, pickSz, registerSzcnGroups, resetRuntime, splitBox, splitBoxSz, startHydration, stripSzProps, szcn, szr, szsClass, szv, validateHydrationClass, verifyAllTokens, verifyMangleChecksum, verifyMangleChecksumAsync, verifyMangleMapIntegrity, verifyRecoveryToken };
+export type { BoxRole, BoxSelector, Classification, HydrationError, HydrationErrorType, MangleMap, RecoveryManifest, RecoveryMode, RuntimeConfig, SSRContext, SplitBoxOptions, SplitBoxResult, SplitBoxSzOptions, SplitBoxSzResult, SzInput, SzcnThemeGroups, TokenData, VerificationResult };

package/dist/index.d.mts

@@ -506,6 +506,10 @@ declare function clearHydrationErrors(): void;
 /**
  * Gets the count of aborted subtrees.
  *
+ * Counts abort marks minus recoveries this session. Aborted elements that were
+ * garbage-collected after leaving the DOM stay counted — the number reports
+ * how many aborts happened, not how many aborted elements are still alive.
+ *
  * @returns {number} Number of aborted subtrees
  */
 declare function getAbortedSubtreeCount(): number;
@@ -630,7 +634,8 @@ declare function startHydration(): void;
 declare function endHydration(): void;
 
 /**
- * Merge className strings with last-wins override per utility, mangle-aware.
+ * Merge className strings with last-wins override per utility, mangle-aware and
+ * memoized (see the memo note above — repeated inputs return in one Map lookup).
  *
  * Intended for the single resolution point in a layered design-system component
  * (typically at the leaf Box): combine the component's default classes with the
@@ -643,6 +648,63 @@ declare function endHydration(): void;
  */
 declare function szcn(...inputs: (string | false | null | undefined)[]): string;
 
+/**
+ * Value-set-aware conflict groups for the ambiguous utility prefixes.
+ *
+ * `szcn` merges by utility prefix, but eight prefixes span MORE than one CSS
+ * property (`text-sm` is font-size, `text-red-500` is color), so they used to
+ * be excluded from dedup entirely — a consumer's `text-sm` override after a
+ * `text-base` default kept BOTH classes and the stylesheet order, not the
+ * className order, picked the winner. This module classifies a token's VALUE
+ * into a property group (closed keyword sets + shape validators), so same-group
+ * tokens dedupe last-wins while different properties keep co-existing.
+ *
+ * Fail-safe contract (inherited from szcn): classification may only ever err
+ * toward `null` = keep-both. A value that matches no group — or matches more
+ * than one — is never merged away.
+ *
+ * Custom `@theme` tokens: the build plugin auto-registers theme token names via
+ * `registerSzcnGroups` (see `virtual:csszyx/theme-groups`); apps can call it
+ * directly for hand-written CSS classes. Registration is guarded: a name that
+ * collides with a static value keyword of an affected prefix (e.g. a color
+ * token named `cover` — `bg-cover` is background-size) or that is registered in
+ * two conflicting categories is dropped with a dev warning, falling back to
+ * keep-both rather than guessing. The ambiguity drop is remembered across
+ * registration batches, so a later batch re-registering only one side cannot
+ * resurrect the name into a single category.
+ *
+ * @module
+ */
+/** Custom token categories accepted by {@link registerSzcnGroups}. */
+interface SzcnThemeGroups {
+    /** Color token names (`brand` → `text-brand`, `bg-brand`, `border-brand`, …). */
+    colors?: readonly string[];
+    /** Font-size token names (`huge` → `text-huge`). */
+    textSizes?: readonly string[];
+    /** Font-family token names (`display` → `font-display`). */
+    fontFamilies?: readonly string[];
+    /** Font-weight token names (`chunky` → `font-chunky`). */
+    fontWeights?: readonly string[];
+}
+/**
+ * Register custom theme token names so szcn can dedupe classes built from them
+ * (`text-brand` + `text-accent` → last wins). Idempotent and additive; called
+ * automatically by the build plugin from the app's `@theme` blocks, or manually
+ * for hand-written CSS utilities.
+ *
+ * Guard rails (both fall back to keep-both, never a wrong merge):
+ * - a name colliding with a static utility keyword of an affected prefix is
+ *   rejected (e.g. a color named `cover`);
+ * - a name registered in two conflicting categories (e.g. both a color and a
+ *   text size — `text-huge` would be unclassifiable) is removed from both,
+ *   and STAYS removed: later batches re-registering only one side are
+ *   rejected too, so registration order can never resurrect an ambiguous
+ *   name into a single category.
+ *
+ * @param groups - Custom token names per theme category.
+ */
+declare function registerSzcnGroups(groups: SzcnThemeGroups): void;
+
 /** Which side of the CSS box-model border a property acts on. */
 type BoxRole = 'outer' | 'inner';
 
@@ -837,6 +899,34 @@ declare function omitSz(sz: SzInput, selector: BoxSelector): SzObject;
  */
 declare function stripSzProps<T extends Record<string, unknown>>(props: T): Omit<T, 'sz'>;
 
+/**
+ * Narrow a compiled `szs` slot to the class string it becomes after build.
+ *
+ * A `Szs` slot is AUTHORED as an sz value (`szs={{ title: { text: 'lg' } }}`),
+ * but the compiler rewrites every slot to its class string before the component
+ * ever runs — so at runtime `szs?.title` IS a string, while its TYPE is still
+ * `SzPropValue`. Forwarding a slot into a `className?: string` prop therefore
+ * needed an `as string` cast in every compound component. This helper does that
+ * narrowing once, typed, and fail-safe: if a slot somehow reaches runtime
+ * uncompiled (a misconfigured build, or a dynamic value the v1 contract
+ * rejects), it returns `undefined` instead of letting an object coerce into
+ * `class="[object Object]"`.
+ *
+ * @param slot - One slot value from an `szs` prop.
+ * @returns The compiled class string, or `undefined` when the slot is absent or
+ *   was not compiled to a string.
+ *
+ * @example
+ * ```tsx
+ * function Card({ szs }: { szs?: Szs<'title' | 'body'> }) {
+ *     return <Box className={szcn('font-medium', szsClass(szs?.title))} />;
+ * }
+ * ```
+ *
+ * @module @csszyx/runtime/szs-class
+ */
+declare function szsClass(slot: unknown): string | undefined;
+
 /**
  * szv() — variant-based sz object factory.
  *
@@ -857,10 +947,14 @@ type VariantSchema = Record<string, Record<string, SzObject>>;
 type VariantSelection<V extends VariantSchema> = {
     [K in keyof V]?: keyof V[K] | null | undefined;
 };
-/** Configuration for a variant component: base styles, variants, and defaults. */
+/**
+ * Configuration for a variant component: base styles, variants, and defaults.
+ * `variants` is optional — a base-only config is a legitimate way to declare
+ * one compiled-and-extracted class bundle for reuse.
+ */
 interface SzvConfig<V extends VariantSchema> {
     base?: SzObject;
-    variants: V;
+    variants?: V;
     defaultVariants?: Partial<VariantSelection<V>>;
 }
 /**
@@ -992,5 +1086,5 @@ declare function isRuntimeInitialized(): boolean;
  */
 declare function resetRuntime(): void;
 
-export { DEFAULT_RUNTIME_CONFIG, VERSION, _sz, _sz2, _sz3, _szMerge, abortHydration, attemptCSRRecovery, classify, classifySzKey, clearHydrationErrors, computeMangleChecksumAsync, disableCSRRecovery, enableCSRRecovery, endHydration, getAbortedSubtreeCount, getHydrationErrors, getRecoveryMode, getRuntimeConfig, getSSRContext, guardHydration, has, hasRecoveryToken, hasSz, initRuntime, isCSRRecoveryAllowed, isHydrating, isHydrationAborted, isRuntimeInitialized, isSSREnvironment, isValidMangleMap, isValidManifest, loadMangleMapFromDOM, loadManifestFromDOM, omit, omitSz, pick, pickSz, resetRuntime, splitBox, splitBoxSz, startHydration, stripSzProps, szcn, szr, szv, validateHydrationClass, verifyAllTokens, verifyMangleChecksum, verifyMangleChecksumAsync, verifyMangleMapIntegrity, verifyRecoveryToken };
-export type { BoxRole, BoxSelector, Classification, HydrationError, HydrationErrorType, MangleMap, RecoveryManifest, RecoveryMode, RuntimeConfig, SSRContext, SplitBoxOptions, SplitBoxResult, SplitBoxSzOptions, SplitBoxSzResult, SzInput, TokenData, VerificationResult };
+export { DEFAULT_RUNTIME_CONFIG, VERSION, _sz, _sz2, _sz3, _szMerge, abortHydration, attemptCSRRecovery, classify, classifySzKey, clearHydrationErrors, computeMangleChecksumAsync, disableCSRRecovery, enableCSRRecovery, endHydration, getAbortedSubtreeCount, getHydrationErrors, getRecoveryMode, getRuntimeConfig, getSSRContext, guardHydration, has, hasRecoveryToken, hasSz, initRuntime, isCSRRecoveryAllowed, isHydrating, isHydrationAborted, isRuntimeInitialized, isSSREnvironment, isValidMangleMap, isValidManifest, loadMangleMapFromDOM, loadManifestFromDOM, omit, omitSz, pick, pickSz, registerSzcnGroups, resetRuntime, splitBox, splitBoxSz, startHydration, stripSzProps, szcn, szr, szsClass, szv, validateHydrationClass, verifyAllTokens, verifyMangleChecksum, verifyMangleChecksumAsync, verifyMangleMapIntegrity, verifyRecoveryToken };
+export type { BoxRole, BoxSelector, Classification, HydrationError, HydrationErrorType, MangleMap, RecoveryManifest, RecoveryMode, RuntimeConfig, SSRContext, SplitBoxOptions, SplitBoxResult, SplitBoxSzOptions, SplitBoxSzResult, SzInput, SzcnThemeGroups, TokenData, VerificationResult };