typestyles 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,477 @@
+import * as CSS from 'csstype';
+export { g as getRegisteredCss } from './hmr-CSDtaPpU.cjs';
+
+/**
+ * A CSS value that can be a standard value or a token reference (var() string).
+ */
+type CSSValue = string | number;
+/**
+ * CSS properties with support for nested selectors and at-rules.
+ * Extends csstype's Properties with nesting capabilities.
+ */
+interface CSSProperties extends CSS.Properties<CSSValue> {
+    /** Nested selector (e.g., '&:hover', '& .child', '&::before') */
+    [selector: `&${string}`]: CSSProperties;
+    /** At-rule (e.g., '@media (max-width: 768px)', '@container', '@supports') */
+    [atRule: `@${string}`]: CSSProperties;
+}
+/**
+ * A map of variant names to their CSS property definitions.
+ */
+type StyleDefinitions = Record<string, CSSProperties>;
+/**
+ * A selector function returned by styles.create().
+ * Accepts variant names (or falsy values for conditional application)
+ * and returns a composed class name string.
+ */
+interface SelectorFunction<K extends string = string> {
+    (...variants: (K | false | null | undefined)[]): string;
+}
+/**
+ * A flat map of token names to their values.
+ */
+type TokenValues = Record<string, string>;
+/**
+ * A typed token reference object. Property access returns var(--namespace-key).
+ */
+type TokenRef<T extends TokenValues> = {
+    readonly [K in keyof T]: string;
+};
+/**
+ * Theme overrides: a map of token namespaces to partial value overrides.
+ */
+type ThemeOverrides = Record<string, Partial<TokenValues>>;
+/**
+ * Keyframe stops: 'from', 'to', or percentage strings mapped to CSS properties.
+ */
+type KeyframeStops$1 = Record<string, CSSProperties>;
+/**
+ * A map of variant dimensions to their options (each option maps to CSSProperties).
+ */
+type VariantDefinitions = Record<string, Record<string, CSSProperties>>;
+/**
+ * The full config object passed to styles.component().
+ */
+type ComponentConfig<V extends VariantDefinitions> = {
+    base?: CSSProperties;
+    variants?: V;
+    compoundVariants?: Array<{
+        variants: {
+            [K in keyof V]?: keyof V[K];
+        };
+        style: CSSProperties;
+    }>;
+    defaultVariants?: {
+        [K in keyof V]?: keyof V[K];
+    };
+};
+/**
+ * The function returned by styles.component().
+ */
+type ComponentFunction<V extends VariantDefinitions> = (selections?: {
+    [K in keyof V]?: keyof V[K] | false | null | undefined;
+}) => string;
+/**
+ * Font face property declarations.
+ */
+type FontFaceProps = {
+    src: string;
+    fontWeight?: string | number;
+    fontStyle?: 'normal' | 'italic' | 'oblique' | string;
+    fontDisplay?: 'auto' | 'block' | 'swap' | 'fallback' | 'optional';
+    fontStretch?: string;
+    unicodeRange?: string;
+};
+
+/**
+ * Create a style group and return a selector function.
+ *
+ * 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 button = createStyles('button', {
+ *   base: { padding: '8px 16px', fontSize: '14px' },
+ *   primary: { backgroundColor: '#0066ff', color: '#fff' },
+ *   large: { padding: '12px 24px', fontSize: '16px' },
+ * });
+ *
+ * button('base', 'primary')          // "button-base button-primary"
+ * button('base', isLarge && 'large') // conditional application
+ * ```
+ */
+declare function createStyles<K extends string>(namespace: string, definitions: StyleDefinitions & Record<K, CSSProperties>): SelectorFunction<K>;
+
+/**
+ * Create design tokens as CSS custom properties.
+ *
+ * Generates a :root rule with the custom properties and returns
+ * a typed object where property access yields var() references.
+ *
+ * @example
+ * ```ts
+ * const color = createTokens('color', {
+ *   primary: '#0066ff',
+ *   secondary: '#6b7280',
+ * });
+ *
+ * color.primary  // "var(--color-primary)"
+ * ```
+ */
+declare function createTokens<T extends TokenValues>(namespace: string, values: T): TokenRef<T>;
+/**
+ * Reference tokens defined elsewhere without injecting CSS.
+ *
+ * Returns a typed proxy that produces var() references.
+ * Useful for consuming shared tokens from a different module.
+ *
+ * @example
+ * ```ts
+ * const color = useTokens('color');
+ * color.primary  // "var(--color-primary)"
+ * ```
+ */
+declare function useTokens<T extends TokenValues = TokenValues>(namespace: string): TokenRef<T>;
+/**
+ * Create a theme class that overrides token values.
+ *
+ * Returns a class name string. Apply it to any element to override
+ * token values for that subtree via CSS custom property cascading.
+ *
+ * @example
+ * ```ts
+ * const dark = createTheme('dark', {
+ *   color: { primary: '#66b3ff', surface: '#1a1a2e' },
+ * });
+ *
+ * <div className={dark}>  // class="theme-dark"
+ * ```
+ */
+declare function createTheme(name: string, overrides: ThemeOverrides): string;
+
+/**
+ * A keyframe stop is either 'from', 'to', or a percentage like '50%'.
+ */
+type KeyframeStops = Record<string, CSSProperties>;
+/**
+ * Create a CSS @keyframes animation and return its name.
+ *
+ * The returned string is the animation name — use it directly in
+ * `animation` shorthand or `animationName`.
+ *
+ * @example
+ * ```ts
+ * const fadeIn = keyframes.create('fadeIn', {
+ *   from: { opacity: 0 },
+ *   to: { opacity: 1 },
+ * });
+ *
+ * const card = styles.create('card', {
+ *   base: { animation: `${fadeIn} 300ms ease` },
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * const bounce = keyframes.create('bounce', {
+ *   '0%': { transform: 'translateY(0)' },
+ *   '50%': { transform: 'translateY(-20px)' },
+ *   '100%': { transform: 'translateY(0)' },
+ * });
+ * ```
+ */
+declare function createKeyframes(name: string, stops: KeyframeStops): string;
+
+/**
+ * Type-safe helpers for CSS color functions.
+ *
+ * Each function returns a plain CSS string — no runtime color math.
+ * Works naturally with token references since tokens are strings too.
+ */
+type ColorValue = string | number;
+/** Color spaces supported by color-mix(). */
+type ColorMixSpace = 'srgb' | 'srgb-linear' | 'display-p3' | 'a98-rgb' | 'prophoto-rgb' | 'rec2020' | 'lab' | 'oklab' | 'xyz' | 'xyz-d50' | 'xyz-d65' | 'hsl' | 'hwb' | 'lch' | 'oklch';
+/**
+ * `rgb(r g b)` or `rgb(r g b / a)`
+ *
+ * @example
+ * ```ts
+ * color.rgb(0, 102, 255)        // "rgb(0 102 255)"
+ * color.rgb(0, 102, 255, 0.5)   // "rgb(0 102 255 / 0.5)"
+ * ```
+ */
+declare function rgb(r: ColorValue, g: ColorValue, b: ColorValue, alpha?: ColorValue): string;
+/**
+ * `hsl(h s l)` or `hsl(h s l / a)`
+ *
+ * @example
+ * ```ts
+ * color.hsl(220, '100%', '50%')       // "hsl(220 100% 50%)"
+ * color.hsl(220, '100%', '50%', 0.8)  // "hsl(220 100% 50% / 0.8)"
+ * ```
+ */
+declare function hsl(h: ColorValue, s: ColorValue, l: ColorValue, alpha?: ColorValue): string;
+/**
+ * `oklch(L C h)` or `oklch(L C h / a)`
+ *
+ * @example
+ * ```ts
+ * color.oklch(0.7, 0.15, 250)       // "oklch(0.7 0.15 250)"
+ * color.oklch(0.7, 0.15, 250, 0.5)  // "oklch(0.7 0.15 250 / 0.5)"
+ * ```
+ */
+declare function oklch(l: ColorValue, c: ColorValue, h: ColorValue, alpha?: ColorValue): string;
+/**
+ * `oklab(L a b)` or `oklab(L a b / alpha)`
+ *
+ * @example
+ * ```ts
+ * color.oklab(0.7, -0.1, -0.1)       // "oklab(0.7 -0.1 -0.1)"
+ * color.oklab(0.7, -0.1, -0.1, 0.5)  // "oklab(0.7 -0.1 -0.1 / 0.5)"
+ * ```
+ */
+declare function oklab(l: ColorValue, a: ColorValue, b: ColorValue, alpha?: ColorValue): string;
+/**
+ * `lab(L a b)` or `lab(L a b / alpha)`
+ *
+ * @example
+ * ```ts
+ * color.lab('50%', 40, -20)  // "lab(50% 40 -20)"
+ * ```
+ */
+declare function lab(l: ColorValue, a: ColorValue, b: ColorValue, alpha?: ColorValue): string;
+/**
+ * `lch(L C h)` or `lch(L C h / alpha)`
+ *
+ * @example
+ * ```ts
+ * color.lch('50%', 80, 250)  // "lch(50% 80 250)"
+ * ```
+ */
+declare function lch(l: ColorValue, c: ColorValue, h: ColorValue, alpha?: ColorValue): string;
+/**
+ * `hwb(h w b)` or `hwb(h w b / alpha)`
+ *
+ * @example
+ * ```ts
+ * color.hwb(220, '10%', '0%')  // "hwb(220 10% 0%)"
+ * ```
+ */
+declare function hwb(h: ColorValue, w: ColorValue, b: ColorValue, alpha?: ColorValue): string;
+/**
+ * `color-mix(in colorspace, color1 p1%, color2 p2%)`
+ *
+ * Mixes two colors in the given color space. Percentages are optional.
+ *
+ * @example
+ * ```ts
+ * color.mix('red', 'blue')                      // "color-mix(in srgb, red, blue)"
+ * color.mix('red', 'blue', 30)                   // "color-mix(in srgb, red 30%, blue)"
+ * color.mix(theme.primary, 'white', 20)          // "color-mix(in srgb, var(--theme-primary) 20%, white)"
+ * color.mix('red', 'blue', 50, 'oklch')          // "color-mix(in oklch, red 50%, blue)"
+ * ```
+ */
+declare function mix(color1: string, color2: string, percentage?: number, colorSpace?: ColorMixSpace): string;
+/**
+ * `light-dark(lightColor, darkColor)`
+ *
+ * Uses the `light-dark()` CSS function that resolves based on
+ * the computed `color-scheme` of the element.
+ *
+ * @example
+ * ```ts
+ * color.lightDark('#111', '#eee')                     // "light-dark(#111, #eee)"
+ * color.lightDark(theme.textLight, theme.textDark)     // "light-dark(var(--theme-textLight), var(--theme-textDark))"
+ * ```
+ */
+declare function lightDark(lightColor: string, darkColor: string): string;
+/**
+ * Adjust the alpha/opacity of any color using `color-mix()`.
+ *
+ * This is a common pattern: mixing a color with transparent to change opacity.
+ * Works with any color value including token references.
+ *
+ * @example
+ * ```ts
+ * color.alpha('red', 0.5)              // "color-mix(in srgb, red 50%, transparent)"
+ * color.alpha(theme.primary, 0.2)      // "color-mix(in srgb, var(--theme-primary) 20%, transparent)"
+ * color.alpha('#0066ff', 0.8, 'oklch') // "color-mix(in oklch, #0066ff 80%, transparent)"
+ * ```
+ */
+declare function alpha(colorValue: string, opacity: number, colorSpace?: ColorMixSpace): string;
+
+type colorFns_ColorMixSpace = ColorMixSpace;
+declare const colorFns_alpha: typeof alpha;
+declare const colorFns_hsl: typeof hsl;
+declare const colorFns_hwb: typeof hwb;
+declare const colorFns_lab: typeof lab;
+declare const colorFns_lch: typeof lch;
+declare const colorFns_lightDark: typeof lightDark;
+declare const colorFns_mix: typeof mix;
+declare const colorFns_oklab: typeof oklab;
+declare const colorFns_oklch: typeof oklch;
+declare const colorFns_rgb: typeof rgb;
+declare namespace colorFns {
+  export { type colorFns_ColorMixSpace as ColorMixSpace, colorFns_alpha as alpha, colorFns_hsl as hsl, colorFns_hwb as hwb, colorFns_lab as lab, colorFns_lch as lch, colorFns_lightDark as lightDark, colorFns_mix as mix, colorFns_oklab as oklab, colorFns_oklch as oklch, colorFns_rgb as rgb };
+}
+
+/**
+ * Create a multi-variant component style and return a selector function.
+ *
+ * Class naming convention:
+ *   base                         → `{namespace}-base`
+ *   variants.intent.primary      → `{namespace}-intent-primary`
+ *   compoundVariants[0]          → `{namespace}-compound-0`
+ *
+ * @example
+ * ```ts
+ * const button = styles.component('button', {
+ *   base: { padding: '8px 16px' },
+ *   variants: {
+ *     intent: {
+ *       primary: { backgroundColor: '#0066ff', color: '#fff' },
+ *       ghost:   { backgroundColor: 'transparent', border: '1px solid currentColor' },
+ *     },
+ *     size: {
+ *       sm: { fontSize: '12px' },
+ *       lg: { fontSize: '18px' },
+ *     },
+ *   },
+ *   compoundVariants: [
+ *     { variants: { intent: 'primary', size: 'lg' }, style: { fontWeight: 700 } },
+ *   ],
+ *   defaultVariants: { intent: 'primary', size: 'sm' },
+ * });
+ *
+ * button()                        // "button-base button-intent-primary button-size-sm"
+ * button({ intent: 'ghost' })     // "button-base button-intent-ghost button-size-sm"
+ * button({ intent: 'primary', size: 'lg' }) // includes compound class
+ * ```
+ */
+declare function createComponent<V extends VariantDefinitions>(namespace: string, config: ComponentConfig<V>): ComponentFunction<V>;
+
+/**
+ * Apply styles to an arbitrary CSS selector.
+ *
+ * Use for CSS resets, body/root defaults, third-party elements, or any
+ * selector that isn't tied to a specific component class.
+ *
+ * @example
+ * ```ts
+ * global.style('body', { margin: 0, fontFamily: 'sans-serif' });
+ * global.style('a:hover', { textDecoration: 'underline' });
+ * global.style('*, *::before, *::after', { boxSizing: 'border-box' });
+ * ```
+ */
+declare function globalStyle(selector: string, properties: CSSProperties): void;
+/**
+ * Declare a `@font-face` rule to load a custom font.
+ *
+ * Multiple weights/styles of the same family can be registered by calling
+ * this function multiple times with different `src` values — each call is
+ * deduplicated by `family + src`.
+ *
+ * @example
+ * ```ts
+ * global.fontFace('Inter', {
+ *   src: "url('/fonts/Inter-Regular.woff2') format('woff2')",
+ *   fontWeight: 400,
+ *   fontStyle: 'normal',
+ *   fontDisplay: 'swap',
+ * });
+ *
+ * global.fontFace('Inter', {
+ *   src: "url('/fonts/Inter-Bold.woff2') format('woff2')",
+ *   fontWeight: 700,
+ *   fontStyle: 'normal',
+ *   fontDisplay: 'swap',
+ * });
+ * ```
+ */
+declare function globalFontFace(family: string, props: FontFaceProps): void;
+
+/**
+ * Style creation API.
+ *
+ * @example
+ * ```ts
+ * const button = styles.create('button', {
+ *   base: { padding: '8px 16px' },
+ *   primary: { backgroundColor: '#0066ff' },
+ * });
+ *
+ * <button className={button('base', 'primary')}>
+ * ```
+ */
+declare const styles: {
+    readonly create: typeof createStyles;
+    readonly component: typeof createComponent;
+};
+/**
+ * Global CSS API for arbitrary selectors and font-face declarations.
+ *
+ * @example
+ * ```ts
+ * global.style('body', { margin: 0 });
+ * global.fontFace('Inter', { src: "url('/Inter.woff2') format('woff2')", fontWeight: 400 });
+ * ```
+ */
+declare const global: {
+    readonly style: typeof globalStyle;
+    readonly fontFace: typeof globalFontFace;
+};
+/**
+ * Design token API using CSS custom properties.
+ *
+ * @example
+ * ```ts
+ * const color = tokens.create('color', {
+ *   primary: '#0066ff',
+ * });
+ *
+ * color.primary // "var(--color-primary)"
+ * ```
+ */
+declare const tokens: {
+    readonly create: typeof createTokens;
+    readonly use: typeof useTokens;
+    readonly createTheme: typeof createTheme;
+};
+/**
+ * Keyframe animation API.
+ *
+ * @example
+ * ```ts
+ * const fadeIn = keyframes.create('fadeIn', {
+ *   from: { opacity: 0 },
+ *   to: { opacity: 1 },
+ * });
+ *
+ * const card = styles.create('card', {
+ *   base: { animation: `${fadeIn} 300ms ease` },
+ * });
+ * ```
+ */
+declare const keyframes: {
+    readonly create: typeof createKeyframes;
+};
+/**
+ * Type-safe CSS color function helpers.
+ *
+ * Each function returns a plain CSS color string — no runtime color math.
+ * Composes naturally with token references.
+ *
+ * @example
+ * ```ts
+ * color.rgb(0, 102, 255)                    // "rgb(0 102 255)"
+ * color.oklch(0.7, 0.15, 250)               // "oklch(0.7 0.15 250)"
+ * color.mix(theme.primary, 'white', 20)      // "color-mix(in srgb, var(--theme-primary) 20%, white)"
+ * color.alpha(theme.primary, 0.5)            // "color-mix(in srgb, var(--theme-primary) 50%, transparent)"
+ * color.lightDark('#111', '#eee')            // "light-dark(#111, #eee)"
+ * ```
+ */
+declare const color: typeof colorFns;
+
+export { type CSSProperties, type CSSValue, type ColorMixSpace, type ComponentConfig, type ComponentFunction, type FontFaceProps, type KeyframeStops$1 as KeyframeStops, type SelectorFunction, type StyleDefinitions, type ThemeOverrides, type TokenRef, type TokenValues, type VariantDefinitions, color, global, keyframes, styles, tokens };