typestyles 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -13,10 +13,33 @@ interface CSSProperties extends CSS.Properties<CSSValue> {
     /** Nested selector (e.g., '&:hover', '& .child', '&::before', '&[data-variant]') */
     [selector: `&${string}`]: CSSProperties;
     /** Attribute selector (e.g., '[data-variant]', '[data-variant="primary"]', '[disabled]') */
-    [attribute: `[${string}`]: CSSProperties;
+    [attribute: `[${string}]`]: CSSProperties;
     /** At-rule (e.g., '@media (max-width: 768px)', '@container', '@supports') */
     [atRule: `@${string}`]: CSSProperties;
 }
+/**
+ * Utility function map used by styles.withUtils().
+ * Each key becomes an extra style property that expands into CSSProperties.
+ */
+type BivariantCallback<Arg, Ret> = {
+    bivarianceHack(value: Arg): Ret;
+}['bivarianceHack'];
+type StyleUtils = Record<string, BivariantCallback<unknown, CSSProperties>>;
+type UtilityValue<U extends StyleUtils, K extends keyof U> = U[K] extends (value: infer V) => CSSProperties ? V : never;
+/**
+ * CSS properties augmented with user-defined utility keys.
+ */
+type CSSPropertiesWithUtils<U extends StyleUtils> = CSS.Properties<CSSValue> & {
+    [K in keyof U]?: UtilityValue<U, K>;
+} & {
+    [selector: `&${string}`]: CSSPropertiesWithUtils<U>;
+    [attribute: `[${string}]`]: CSSPropertiesWithUtils<U>;
+    [atRule: `@${string}`]: CSSPropertiesWithUtils<U>;
+};
+/**
+ * A map of style names to utility-aware CSS property definitions.
+ */
+type StyleDefinitionsWithUtils<U extends StyleUtils> = Record<string, CSSPropertiesWithUtils<U>>;
 /**
  * A map of variant names to their CSS property definitions.
  */
@@ -50,7 +73,16 @@ type KeyframeStops$1 = Record<string, CSSProperties>;
 /**
  * A map of variant dimensions to their options (each option maps to CSSProperties).
  */
+type VariantDimensions = Record<string, Record<string, unknown>>;
 type VariantDefinitions = Record<string, Record<string, CSSProperties>>;
+type SlotStyles<S extends string> = Partial<Record<S, CSSProperties>>;
+type SlotVariantDefinitions<S extends string> = Record<string, Record<string, SlotStyles<S>>>;
+type VariantOptionKey<V extends VariantDimensions, K extends keyof V> = Extract<keyof V[K], string>;
+type VariantSelectionValue<OptionKey extends string> = OptionKey | (Extract<OptionKey, 'true'> extends never ? never : true) | (Extract<OptionKey, 'false'> extends never ? never : false);
+type CompoundSelectionValue<OptionKey extends string> = VariantSelectionValue<OptionKey> | readonly VariantSelectionValue<OptionKey>[];
+type ComponentSelections<V extends VariantDimensions> = {
+    [K in keyof V]?: VariantSelectionValue<VariantOptionKey<V, K>> | null | undefined;
+};
 /**
  * The full config object passed to styles.component().
  */
@@ -59,20 +91,29 @@ type ComponentConfig<V extends VariantDefinitions> = {
     variants?: V;
     compoundVariants?: Array<{
         variants: {
-            [K in keyof V]?: keyof V[K];
+            [K in keyof V]?: CompoundSelectionValue<VariantOptionKey<V, K>>;
         };
         style: CSSProperties;
     }>;
-    defaultVariants?: {
-        [K in keyof V]?: keyof V[K];
-    };
+    defaultVariants?: ComponentSelections<V>;
 };
 /**
  * The function returned by styles.component().
  */
-type ComponentFunction<V extends VariantDefinitions> = (selections?: {
-    [K in keyof V]?: keyof V[K] | false | null | undefined;
-}) => string;
+type ComponentFunction<V extends VariantDefinitions> = (selections?: ComponentSelections<V>) => string;
+type SlotComponentConfig<S extends string, V extends SlotVariantDefinitions<S>> = {
+    slots: readonly S[];
+    base?: SlotStyles<S>;
+    variants?: V;
+    compoundVariants?: Array<{
+        variants: {
+            [K in keyof V]?: CompoundSelectionValue<VariantOptionKey<V, K>>;
+        };
+        style: SlotStyles<S>;
+    }>;
+    defaultVariants?: ComponentSelections<V>;
+};
+type SlotComponentFunction<S extends string, V extends SlotVariantDefinitions<S>> = (selections?: ComponentSelections<V>) => Record<S, string>;
 /**
  * A reference to a CSS custom property created by createVar().
  * The string value is `var(--ts-N)` and can be used directly as a CSS value.
@@ -91,11 +132,11 @@ type CSSVarRef = `var(--${string})`;
  *   },
  * });
  *
- * type ButtonProps = RecipeVariants<typeof button>;
+ * type ButtonProps = ComponentVariants<typeof button>;
  * // { intent?: 'primary' | 'ghost'; size?: 'sm' | 'lg' }
  * ```
  */
-type RecipeVariants<T> = T extends ComponentFunction<infer V> ? {
+type ComponentVariants<T> = T extends (selections?: ComponentSelections<infer V>) => unknown ? {
     [K in keyof V]?: keyof V[K];
 } : never;
 /**
@@ -111,25 +152,70 @@ type FontFaceProps = {
 };
 
 /**
- * Create a style group and return a selector function.
+ * Create a single class with the given styles. Returns the class name string.
+ * Use this when you don't need variants — just a class with typed CSS properties.
  *
- * The selector function accepts variant names and returns a composed
- * class name string. Class names are deterministic and human-readable:
- * `{namespace}-{variant}`.
+ * @example
+ * ```ts
+ * const card = styles.class('card', {
+ *   padding: '1rem',
+ *   borderRadius: '0.5rem',
+ *   backgroundColor: 'white',
+ *   '&:hover': { boxShadow: '0 4px 6px rgb(0 0 0 / 0.1)' },
+ * });
+ *
+ * <div className={card} />  // class="card"
+ * ```
+ */
+declare function createClass(name: string, properties: CSSProperties): string;
+/**
+ * Create a deterministic hashed class from a style object.
+ * The same style object shape+values always returns the same class name.
+ *
+ * Optional `label` is appended as a readable prefix for debugging.
  *
  * @example
  * ```ts
- * const button = createStyles('button', {
- *   base: { padding: '8px 16px', fontSize: '14px' },
- *   primary: { backgroundColor: '#0066ff', color: '#fff' },
- *   large: { padding: '12px 24px', fontSize: '16px' },
+ * const button = styles.hashClass({
+ *   padding: '8px 12px',
+ *   borderRadius: '8px',
+ * });
+ *
+ * const danger = styles.hashClass(
+ *   { backgroundColor: 'red', color: 'white' },
+ *   'danger'
+ * );
+ * ```
+ */
+declare function createHashClass(properties: CSSProperties, label?: string): string;
+/**
+ * Create a style group and return a selector function.
+ *
+ * **Two-argument form** (definitions object with 'base' and variants):
+ * ```ts
+ * const button = styles.create('button', {
+ *   base: { padding: '8px 16px' },
+ *   primary: { backgroundColor: '#0066ff' },
  * });
+ * button('base', 'primary')  // "button-base button-primary"
+ * ```
  *
- * button('base', 'primary')          // "button-base button-primary"
- * button('base', isLarge && 'large') // conditional application
+ * **Three-argument form** (base styles + variants, no 'base' key needed):
+ * ```ts
+ * const button = styles.create('button',
+ *   { padding: '8px 16px', borderRadius: '6px' },  // base styles
+ *   {
+ *     default: { backgroundColor: '#0066ff', color: '#fff' },
+ *     outline: { border: '1px solid', backgroundColor: 'transparent' },
+ *     large: { padding: '12px 24px' },
+ *   }
+ * );
+ * button('default')           // "button-base button-default" — base always included
+ * button('outline', 'large')   // "button-base button-outline button-large"
  * ```
  */
 declare function createStyles<K extends string>(namespace: string, definitions: StyleDefinitions & Record<K, CSSProperties>): SelectorFunction<K>;
+declare function createStyles(namespace: string, base: CSSProperties, variants: Record<string, CSSProperties>): SelectorFunction<string>;
 /**
  * Compose multiple selector functions or class strings into one.
  * Returns a new SelectorFunction that calls all inputs and joins results.
@@ -147,6 +233,32 @@ type AnySelectorFunction = {
     (...args: unknown[]): string;
 };
 declare function compose(...selectors: Array<AnySelectorFunction | string | false | null | undefined>): AnySelectorFunction;
+type StylesWithUtilsApi<U extends StyleUtils> = {
+    class: (name: string, properties: CSSPropertiesWithUtils<U>) => string;
+    hashClass: (properties: CSSPropertiesWithUtils<U>, label?: string) => string;
+    create: {
+        <K extends string>(namespace: string, definitions: StyleDefinitionsWithUtils<U> & Record<K, CSSPropertiesWithUtils<U>>): SelectorFunction<K>;
+        (namespace: string, base: CSSPropertiesWithUtils<U>, variants: Record<string, CSSPropertiesWithUtils<U>>): SelectorFunction<string>;
+    };
+    compose: typeof compose;
+};
+/**
+ * Create a utility-aware styles API, similar to Stitches' `utils`.
+ *
+ * @example
+ * ```ts
+ * const u = createStylesWithUtils({
+ *   marginX: (value: string | number) => ({ marginLeft: value, marginRight: value }),
+ *   size: (value: string | number) => ({ width: value, height: value }),
+ * });
+ *
+ * const card = u.class('card', {
+ *   size: 40,
+ *   marginX: 16,
+ * });
+ * ```
+ */
+declare function createStylesWithUtils<U extends StyleUtils>(utils: U): StylesWithUtilsApi<U>;
 
 /**
  * Create design tokens as CSS custom properties.
@@ -364,7 +476,7 @@ declare namespace colorFns {
 /**
  * Create a multi-variant component style and return a selector function.
  *
- * Class naming convention:
+ * Class naming convention (default `semantic` mode; see `configureClassNaming`):
  *   base                         → `{namespace}-base`
  *   variants.intent.primary      → `{namespace}-intent-primary`
  *   compoundVariants[0]          → `{namespace}-compound-0`
@@ -395,6 +507,7 @@ declare namespace colorFns {
  * ```
  */
 declare function createComponent<V extends VariantDefinitions>(namespace: string, config: ComponentConfig<V>): ComponentFunction<V>;
+declare function createComponent<S extends string, V extends SlotVariantDefinitions<S>>(namespace: string, config: SlotComponentConfig<S, V>): SlotComponentFunction<S, V>;
 
 /**
  * Apply styles to an arbitrary CSS selector.
@@ -469,6 +582,34 @@ declare function createVar(): CSSVarRef;
  */
 declare function assignVars(vars: Partial<Record<CSSVarRef, string>>): Record<string, string>;
 
+/**
+ * How generated class names are formed for `styles.create`, `styles.class`,
+ * `styles.component`, and related APIs.
+ *
+ * - `semantic` — readable names like `button-base`, `button-intent-primary` (default).
+ * - `hashed` — stable hash from namespace, variant segment, and declarations, with a short namespace slug for debugging.
+ * - `atomic` — hash-only names (shortest); same collision properties as `hashed` when `scopeId` differs.
+ */
+type ClassNamingMode = 'semantic' | 'hashed' | 'atomic';
+type ClassNamingConfig = {
+    mode: ClassNamingMode;
+    /** Prefix for hashed / atomic output and for `hashClass`. Default `ts`. */
+    prefix: string;
+    /**
+     * Optional package or app id mixed into hash input so identical logical
+     * names from different packages do not produce the same class string.
+     */
+    scopeId: string;
+};
+declare function getClassNamingConfig(): Readonly<ClassNamingConfig>;
+/**
+ * Set global class naming options. Call once at app or package entry
+ * (e.g. design-system `index.ts`) for per-package adoption in a monorepo.
+ */
+declare function configureClassNaming(partial: Partial<ClassNamingConfig>): void;
+/** Restore defaults (primarily for tests). */
+declare function resetClassNaming(): void;
+
 /**
  * Style creation API.
  *
@@ -479,12 +620,17 @@ declare function assignVars(vars: Partial<Record<CSSVarRef, string>>): Record<st
  *   primary: { backgroundColor: '#0066ff' },
  * });
  *
- * <button className={button('base', 'primary')}>
+ * const hashed = styles.hashClass({ display: 'inline-flex' }, 'button');
+ *
+ * <button className={`${button('base', 'primary')} ${hashed}`}>
  * ```
  */
 declare const styles: {
     readonly create: typeof createStyles;
+    readonly class: typeof createClass;
+    readonly hashClass: typeof createHashClass;
     readonly component: typeof createComponent;
+    readonly withUtils: typeof createStylesWithUtils;
     readonly compose: typeof compose;
 };
 /**
@@ -552,4 +698,4 @@ declare const keyframes: {
  */
 declare const color: typeof colorFns;
 
-export { type CSSProperties, type CSSValue, type CSSVarRef, type ColorMixSpace, type ComponentConfig, type ComponentFunction, type FontFaceProps, type KeyframeStops$1 as KeyframeStops, type RecipeVariants, type SelectorFunction, type StyleDefinitions, type ThemeOverrides, type TokenRef, type TokenValues, type VariantDefinitions, assignVars, color, createVar, global, keyframes, styles, tokens };
+export { type CSSProperties, type CSSPropertiesWithUtils, type CSSValue, type CSSVarRef, type ClassNamingConfig, type ClassNamingMode, type ColorMixSpace, type ComponentConfig, type ComponentFunction, type ComponentVariants, type FontFaceProps, type KeyframeStops$1 as KeyframeStops, type SelectorFunction, type SlotComponentConfig, type SlotComponentFunction, type SlotStyles, type SlotVariantDefinitions, type StyleDefinitions, type StyleDefinitionsWithUtils, type StyleUtils, type ThemeOverrides, type TokenRef, type TokenValues, type VariantDefinitions, assignVars, color, configureClassNaming, createVar, getClassNamingConfig, global, keyframes, resetClassNaming, styles, tokens };

package/dist/index.d.ts

@@ -13,10 +13,33 @@ interface CSSProperties extends CSS.Properties<CSSValue> {
     /** Nested selector (e.g., '&:hover', '& .child', '&::before', '&[data-variant]') */
     [selector: `&${string}`]: CSSProperties;
     /** Attribute selector (e.g., '[data-variant]', '[data-variant="primary"]', '[disabled]') */
-    [attribute: `[${string}`]: CSSProperties;
+    [attribute: `[${string}]`]: CSSProperties;
     /** At-rule (e.g., '@media (max-width: 768px)', '@container', '@supports') */
     [atRule: `@${string}`]: CSSProperties;
 }
+/**
+ * Utility function map used by styles.withUtils().
+ * Each key becomes an extra style property that expands into CSSProperties.
+ */
+type BivariantCallback<Arg, Ret> = {
+    bivarianceHack(value: Arg): Ret;
+}['bivarianceHack'];
+type StyleUtils = Record<string, BivariantCallback<unknown, CSSProperties>>;
+type UtilityValue<U extends StyleUtils, K extends keyof U> = U[K] extends (value: infer V) => CSSProperties ? V : never;
+/**
+ * CSS properties augmented with user-defined utility keys.
+ */
+type CSSPropertiesWithUtils<U extends StyleUtils> = CSS.Properties<CSSValue> & {
+    [K in keyof U]?: UtilityValue<U, K>;
+} & {
+    [selector: `&${string}`]: CSSPropertiesWithUtils<U>;
+    [attribute: `[${string}]`]: CSSPropertiesWithUtils<U>;
+    [atRule: `@${string}`]: CSSPropertiesWithUtils<U>;
+};
+/**
+ * A map of style names to utility-aware CSS property definitions.
+ */
+type StyleDefinitionsWithUtils<U extends StyleUtils> = Record<string, CSSPropertiesWithUtils<U>>;
 /**
  * A map of variant names to their CSS property definitions.
  */
@@ -50,7 +73,16 @@ type KeyframeStops$1 = Record<string, CSSProperties>;
 /**
  * A map of variant dimensions to their options (each option maps to CSSProperties).
  */
+type VariantDimensions = Record<string, Record<string, unknown>>;
 type VariantDefinitions = Record<string, Record<string, CSSProperties>>;
+type SlotStyles<S extends string> = Partial<Record<S, CSSProperties>>;
+type SlotVariantDefinitions<S extends string> = Record<string, Record<string, SlotStyles<S>>>;
+type VariantOptionKey<V extends VariantDimensions, K extends keyof V> = Extract<keyof V[K], string>;
+type VariantSelectionValue<OptionKey extends string> = OptionKey | (Extract<OptionKey, 'true'> extends never ? never : true) | (Extract<OptionKey, 'false'> extends never ? never : false);
+type CompoundSelectionValue<OptionKey extends string> = VariantSelectionValue<OptionKey> | readonly VariantSelectionValue<OptionKey>[];
+type ComponentSelections<V extends VariantDimensions> = {
+    [K in keyof V]?: VariantSelectionValue<VariantOptionKey<V, K>> | null | undefined;
+};
 /**
  * The full config object passed to styles.component().
  */
@@ -59,20 +91,29 @@ type ComponentConfig<V extends VariantDefinitions> = {
     variants?: V;
     compoundVariants?: Array<{
         variants: {
-            [K in keyof V]?: keyof V[K];
+            [K in keyof V]?: CompoundSelectionValue<VariantOptionKey<V, K>>;
         };
         style: CSSProperties;
     }>;
-    defaultVariants?: {
-        [K in keyof V]?: keyof V[K];
-    };
+    defaultVariants?: ComponentSelections<V>;
 };
 /**
  * The function returned by styles.component().
  */
-type ComponentFunction<V extends VariantDefinitions> = (selections?: {
-    [K in keyof V]?: keyof V[K] | false | null | undefined;
-}) => string;
+type ComponentFunction<V extends VariantDefinitions> = (selections?: ComponentSelections<V>) => string;
+type SlotComponentConfig<S extends string, V extends SlotVariantDefinitions<S>> = {
+    slots: readonly S[];
+    base?: SlotStyles<S>;
+    variants?: V;
+    compoundVariants?: Array<{
+        variants: {
+            [K in keyof V]?: CompoundSelectionValue<VariantOptionKey<V, K>>;
+        };
+        style: SlotStyles<S>;
+    }>;
+    defaultVariants?: ComponentSelections<V>;
+};
+type SlotComponentFunction<S extends string, V extends SlotVariantDefinitions<S>> = (selections?: ComponentSelections<V>) => Record<S, string>;
 /**
  * A reference to a CSS custom property created by createVar().
  * The string value is `var(--ts-N)` and can be used directly as a CSS value.
@@ -91,11 +132,11 @@ type CSSVarRef = `var(--${string})`;
  *   },
  * });
  *
- * type ButtonProps = RecipeVariants<typeof button>;
+ * type ButtonProps = ComponentVariants<typeof button>;
  * // { intent?: 'primary' | 'ghost'; size?: 'sm' | 'lg' }
  * ```
  */
-type RecipeVariants<T> = T extends ComponentFunction<infer V> ? {
+type ComponentVariants<T> = T extends (selections?: ComponentSelections<infer V>) => unknown ? {
     [K in keyof V]?: keyof V[K];
 } : never;
 /**
@@ -111,25 +152,70 @@ type FontFaceProps = {
 };
 
 /**
- * Create a style group and return a selector function.
+ * Create a single class with the given styles. Returns the class name string.
+ * Use this when you don't need variants — just a class with typed CSS properties.
  *
- * The selector function accepts variant names and returns a composed
- * class name string. Class names are deterministic and human-readable:
- * `{namespace}-{variant}`.
+ * @example
+ * ```ts
+ * const card = styles.class('card', {
+ *   padding: '1rem',
+ *   borderRadius: '0.5rem',
+ *   backgroundColor: 'white',
+ *   '&:hover': { boxShadow: '0 4px 6px rgb(0 0 0 / 0.1)' },
+ * });
+ *
+ * <div className={card} />  // class="card"
+ * ```
+ */
+declare function createClass(name: string, properties: CSSProperties): string;
+/**
+ * Create a deterministic hashed class from a style object.
+ * The same style object shape+values always returns the same class name.
+ *
+ * Optional `label` is appended as a readable prefix for debugging.
  *
  * @example
  * ```ts
- * const button = createStyles('button', {
- *   base: { padding: '8px 16px', fontSize: '14px' },
- *   primary: { backgroundColor: '#0066ff', color: '#fff' },
- *   large: { padding: '12px 24px', fontSize: '16px' },
+ * const button = styles.hashClass({
+ *   padding: '8px 12px',
+ *   borderRadius: '8px',
+ * });
+ *
+ * const danger = styles.hashClass(
+ *   { backgroundColor: 'red', color: 'white' },
+ *   'danger'
+ * );
+ * ```
+ */
+declare function createHashClass(properties: CSSProperties, label?: string): string;
+/**
+ * Create a style group and return a selector function.
+ *
+ * **Two-argument form** (definitions object with 'base' and variants):
+ * ```ts
+ * const button = styles.create('button', {
+ *   base: { padding: '8px 16px' },
+ *   primary: { backgroundColor: '#0066ff' },
  * });
+ * button('base', 'primary')  // "button-base button-primary"
+ * ```
  *
- * button('base', 'primary')          // "button-base button-primary"
- * button('base', isLarge && 'large') // conditional application
+ * **Three-argument form** (base styles + variants, no 'base' key needed):
+ * ```ts
+ * const button = styles.create('button',
+ *   { padding: '8px 16px', borderRadius: '6px' },  // base styles
+ *   {
+ *     default: { backgroundColor: '#0066ff', color: '#fff' },
+ *     outline: { border: '1px solid', backgroundColor: 'transparent' },
+ *     large: { padding: '12px 24px' },
+ *   }
+ * );
+ * button('default')           // "button-base button-default" — base always included
+ * button('outline', 'large')   // "button-base button-outline button-large"
  * ```
  */
 declare function createStyles<K extends string>(namespace: string, definitions: StyleDefinitions & Record<K, CSSProperties>): SelectorFunction<K>;
+declare function createStyles(namespace: string, base: CSSProperties, variants: Record<string, CSSProperties>): SelectorFunction<string>;
 /**
  * Compose multiple selector functions or class strings into one.
  * Returns a new SelectorFunction that calls all inputs and joins results.
@@ -147,6 +233,32 @@ type AnySelectorFunction = {
     (...args: unknown[]): string;
 };
 declare function compose(...selectors: Array<AnySelectorFunction | string | false | null | undefined>): AnySelectorFunction;
+type StylesWithUtilsApi<U extends StyleUtils> = {
+    class: (name: string, properties: CSSPropertiesWithUtils<U>) => string;
+    hashClass: (properties: CSSPropertiesWithUtils<U>, label?: string) => string;
+    create: {
+        <K extends string>(namespace: string, definitions: StyleDefinitionsWithUtils<U> & Record<K, CSSPropertiesWithUtils<U>>): SelectorFunction<K>;
+        (namespace: string, base: CSSPropertiesWithUtils<U>, variants: Record<string, CSSPropertiesWithUtils<U>>): SelectorFunction<string>;
+    };
+    compose: typeof compose;
+};
+/**
+ * Create a utility-aware styles API, similar to Stitches' `utils`.
+ *
+ * @example
+ * ```ts
+ * const u = createStylesWithUtils({
+ *   marginX: (value: string | number) => ({ marginLeft: value, marginRight: value }),
+ *   size: (value: string | number) => ({ width: value, height: value }),
+ * });
+ *
+ * const card = u.class('card', {
+ *   size: 40,
+ *   marginX: 16,
+ * });
+ * ```
+ */
+declare function createStylesWithUtils<U extends StyleUtils>(utils: U): StylesWithUtilsApi<U>;
 
 /**
  * Create design tokens as CSS custom properties.
@@ -364,7 +476,7 @@ declare namespace colorFns {
 /**
  * Create a multi-variant component style and return a selector function.
  *
- * Class naming convention:
+ * Class naming convention (default `semantic` mode; see `configureClassNaming`):
  *   base                         → `{namespace}-base`
  *   variants.intent.primary      → `{namespace}-intent-primary`
  *   compoundVariants[0]          → `{namespace}-compound-0`
@@ -395,6 +507,7 @@ declare namespace colorFns {
  * ```
  */
 declare function createComponent<V extends VariantDefinitions>(namespace: string, config: ComponentConfig<V>): ComponentFunction<V>;
+declare function createComponent<S extends string, V extends SlotVariantDefinitions<S>>(namespace: string, config: SlotComponentConfig<S, V>): SlotComponentFunction<S, V>;
 
 /**
  * Apply styles to an arbitrary CSS selector.
@@ -469,6 +582,34 @@ declare function createVar(): CSSVarRef;
  */
 declare function assignVars(vars: Partial<Record<CSSVarRef, string>>): Record<string, string>;
 
+/**
+ * How generated class names are formed for `styles.create`, `styles.class`,
+ * `styles.component`, and related APIs.
+ *
+ * - `semantic` — readable names like `button-base`, `button-intent-primary` (default).
+ * - `hashed` — stable hash from namespace, variant segment, and declarations, with a short namespace slug for debugging.
+ * - `atomic` — hash-only names (shortest); same collision properties as `hashed` when `scopeId` differs.
+ */
+type ClassNamingMode = 'semantic' | 'hashed' | 'atomic';
+type ClassNamingConfig = {
+    mode: ClassNamingMode;
+    /** Prefix for hashed / atomic output and for `hashClass`. Default `ts`. */
+    prefix: string;
+    /**
+     * Optional package or app id mixed into hash input so identical logical
+     * names from different packages do not produce the same class string.
+     */
+    scopeId: string;
+};
+declare function getClassNamingConfig(): Readonly<ClassNamingConfig>;
+/**
+ * Set global class naming options. Call once at app or package entry
+ * (e.g. design-system `index.ts`) for per-package adoption in a monorepo.
+ */
+declare function configureClassNaming(partial: Partial<ClassNamingConfig>): void;
+/** Restore defaults (primarily for tests). */
+declare function resetClassNaming(): void;
+
 /**
  * Style creation API.
  *
@@ -479,12 +620,17 @@ declare function assignVars(vars: Partial<Record<CSSVarRef, string>>): Record<st
  *   primary: { backgroundColor: '#0066ff' },
  * });
  *
- * <button className={button('base', 'primary')}>
+ * const hashed = styles.hashClass({ display: 'inline-flex' }, 'button');
+ *
+ * <button className={`${button('base', 'primary')} ${hashed}`}>
  * ```
  */
 declare const styles: {
     readonly create: typeof createStyles;
+    readonly class: typeof createClass;
+    readonly hashClass: typeof createHashClass;
     readonly component: typeof createComponent;
+    readonly withUtils: typeof createStylesWithUtils;
     readonly compose: typeof compose;
 };
 /**
@@ -552,4 +698,4 @@ declare const keyframes: {
  */
 declare const color: typeof colorFns;
 
-export { type CSSProperties, type CSSValue, type CSSVarRef, type ColorMixSpace, type ComponentConfig, type ComponentFunction, type FontFaceProps, type KeyframeStops$1 as KeyframeStops, type RecipeVariants, type SelectorFunction, type StyleDefinitions, type ThemeOverrides, type TokenRef, type TokenValues, type VariantDefinitions, assignVars, color, createVar, global, keyframes, styles, tokens };
+export { type CSSProperties, type CSSPropertiesWithUtils, type CSSValue, type CSSVarRef, type ClassNamingConfig, type ClassNamingMode, type ColorMixSpace, type ComponentConfig, type ComponentFunction, type ComponentVariants, type FontFaceProps, type KeyframeStops$1 as KeyframeStops, type SelectorFunction, type SlotComponentConfig, type SlotComponentFunction, type SlotStyles, type SlotVariantDefinitions, type StyleDefinitions, type StyleDefinitionsWithUtils, type StyleUtils, type ThemeOverrides, type TokenRef, type TokenValues, type VariantDefinitions, assignVars, color, configureClassNaming, createVar, getClassNamingConfig, global, keyframes, resetClassNaming, styles, tokens };