◆ KOVO
GitHub
Menu

API Reference

@kovojs/style

Generated from 1 public subpath — 39 exports, 39 documented. Do not edit by hand.

@kovojs/style#

StyleX-inspired typed styling: atomic style objects, attrs/props merging, CSS variables, and theme classes.

Source: packages/style/src/index.ts

Functions#

create#

Compiles static Kovo style objects into opaque atomic style records. This is the TS-native fork point for StyleX-style authoring: authored TSX stays source-like, while the compiler can inspect __rules and lower to ordinary class attributes for SPEC.md §5.2 fixpoint output.

ts
function create<const Styles extends Record<string, StyleObject>>(
  styles: Styles,
): StyleNamespaces<Styles>;
function create<const Styles extends Record<string, StyleObject>>(
  styles: Styles,
  identity: StyleIdentityOptions,
): StyleNamespaces<Styles>;

attrs#

Merge compiled style records into Kovo JSX-shaped attributes: class plus a serialized inline style escape. Kovo examples should prefer this shape outside React because the emitted HTML remains plain and inspectable (SPEC.md §4.2).

ts
function attrs(...styles: readonly StyleInput[]): AttrsResult;

defineVars#

Define CSS custom-property tokens with deterministic --kovo-* names. The returned values are ordinary var(...) strings so themes remain document CSS and do not need shadow boundaries (SPEC.md §13.1).

ts
function defineVars<const Tokens extends Record<string, CssValue>>(
  tokens: Tokens,
): Vars<Tokens>;
function defineVars<const Tokens extends Record<string, CssValue>>(
  tokens: Tokens,
  identity: StyleIdentityOptions,
): Vars<Tokens>;

createTheme#

Create a theme class that overrides a defineVars group. Apps apply the class at document scope, and components keep referencing the original typed tokens.

ts
function createTheme<Tokens extends Record<string, CssValue>>(
  baseTokens: Vars<Tokens>,
  overrides: Partial<Record<keyof Tokens, CssValue>>,
): Theme;
function createTheme<Tokens extends Record<string, CssValue>>(
  baseTokens: Vars<Tokens>,
  overrides: Partial<Record<keyof Tokens, CssValue>>,
  identity: StyleIdentityOptions,
): Theme;

keyframes#

Deterministic keyframes name placeholder for the compiler's later extraction pass.

ts
function keyframes(frames: Keyframes): string;
function keyframes(frames: Keyframes, identity: StyleIdentityOptions): string;

emitAtomicCss#

Emit atomic CSS in priority layers so split files do not depend on link order.

ts
function emitAtomicCss(rules: readonly AtomicRule[], options: CssEmitOptions = {}): string;

defineTheme#

Define the app theme from one seed color. The v1 public surface is the seed form (SPEC.md §13.1); deriving from a generated base theme is a repo-internal capability exposed through defineThemeFromBase.

ts
function defineTheme(options: DefineThemeOptions): KovoTheme;

Types & interfaces#

AtomicRule#

A single extracted atomic CSS rule plus source/provenance metadata for compiler manifests.

ts
interface AtomicRule {
  readonly className: string;
  readonly property: string;
  readonly cssProperty: string;
  readonly value: StylePrimitive;
  readonly priority: number;
  readonly selectorSuffix: string;
  readonly atRules: readonly string[];
  readonly rule: string;
  readonly source: string;
}

AttrsResult#

Kovo JSX-shaped merge result returned by style.attrs.

ts
interface AttrsResult {
  readonly class?: string;
  readonly [STYLE_SRC]?: string;
  readonly style?: string;
}

CompiledStyle#

Compiler-produced atomic style record keyed by CSS-property conflict group.

ts
interface CompiledStyle {
  readonly [CSS_MARKER]: true | string;
  readonly [STYLE_SRC]?: string;
  readonly __rules?: readonly AtomicRule[];
  readonly __styleKey?: string;
  readonly [property: string]: string | true | readonly AtomicRule[] | undefined;
}

CssEmitOptions#

Options for serializing extracted atom rules into CSS text.

ts
interface CssEmitOptions {
  readonly layerName?: string;
}

CssValue#

Values accepted in a Kovo static style object.

ts
type CssValue = StylePrimitive | null | undefined;

InlineStyle#

Explicit raw inline style payload used only through the internal raw(...) escape hatch.

ts
type InlineStyle = Readonly<Record<string, StylePrimitive>>;

Keyframes#

Keyframes object accepted by the deterministic keyframes name helper.

ts
interface Keyframes {
  readonly [step: string]: StyleObject;
}

Style#

Opaque compiled style object that may be passed to style.attrs.

ts
type Style = CompiledStyle | null | false | undefined;

StyleInput#

A style argument accepted by attrs, including arrays and raw inline tuples.

ts
type StyleInput = Style | ReadonlyArray<StyleInput> | readonly [Style, InlineStyle];

StyleNamespaces#

Result shape of style.create: one compiled style record per named namespace key.

ts
type StyleNamespaces<Styles extends Record<string, StyleObject>> = {
  readonly [Key in keyof Styles]: CompiledStyle;
};

StyleObject#

Static style object accepted by style.create, including nested pseudos and at-rules.

ts
interface StyleObject {
  readonly [property: string]: CssValue | StyleObject;
}

StylePrimitive#

CSS scalar values Kovo's static atomic compiler can emit without runtime CSS parsing.

ts
type StylePrimitive = string | number;

Theme#

Theme class returned by createTheme, with extracted custom-property override rules.

ts
interface Theme {
  readonly [CSS_MARKER]: true | string;
  readonly [STYLE_SRC]?: string;
  readonly __rules?: readonly AtomicRule[];
  readonly __theme: true;
  readonly className: string;
}

Vars#

Typed CSS variable group returned by defineVars; token values are var(--kovo-*) strings.

ts
type Vars<Tokens extends Record<string, CssValue>> = {
  readonly [Key in keyof Tokens]: string;
} & {
  readonly [CSS_MARKER]: true | string;
  readonly __vars: true;
  readonly __rules?: readonly AtomicRule[];
};

DefineThemeOptions#

App-facing theme definition. The v1 public surface is the seed form (SPEC.md §13.1).

ts
type DefineThemeOptions = { readonly seed: ThemeSeed } & ThemeFromSeedOptions;

KovoTheme#

Generated Kovo theme object. Values are concrete CSS values; tokens exports var(...) refs.

ts
interface KovoTheme {
  readonly css: string;
  readonly custom: Readonly<Record<string, ThemeCustomColorGroup>>;
  readonly dark: ThemeSchemeValues;
  readonly light: ThemeSchemeValues;
  readonly ref: ThemeReferencePalettes;
  readonly seed: string;
  readonly sys: {
    readonly color: ThemeSystemColorValues;
    readonly shape: ThemeShapeValues;
  };
  readonly variant: ThemeVariant;
}

ThemeCustomColorGroup#

Four-role Material custom color group generated from one semantic color.

ts
interface ThemeCustomColorGroup {
  readonly color: string;
  readonly colorContainer: string;
  readonly onColor: string;
  readonly onColorContainer: string;
}

ThemeCustomColorInput#

Named semantic color to harmonize with the seed color.

ts
interface ThemeCustomColorInput {
  readonly blend?: boolean;
  readonly value: ThemeSeed;
}

ThemeCustomColorsInput#

Custom semantic color map, such as { success: '#16a34a' }.

ts
type ThemeCustomColorsInput = Readonly<Record<string, ThemeSeed | ThemeCustomColorInput>>;

ThemeFromSeedOptions#

Theme options for seed-generated Kovo themes.

ts
interface ThemeFromSeedOptions {
  /** Additional semantic colors generated through Material custom-color groups. */
  readonly colors?: ThemeCustomColorsInput;
  /** Material contrast level from -1 to 1. Defaults to 0. */
  readonly contrast?: number;
  /** Selector that receives dark system-token overrides. Defaults to `:root[data-theme="dark"]`. */
  readonly darkSelector?: string;
  /** Emit reference palette tone variables. Defaults to true. */
  readonly emitRef?: boolean;
  /** Shape token overrides. */
  readonly shape?: ThemeShapeInput;
  /** Selector that receives light/default variables. Defaults to `:root`. */
  readonly selector?: string;
  /** Material dynamic scheme variant. Defaults to `tonal-spot`. */
  readonly variant?: ThemeVariant;
}

ThemeReferencePaletteName#

Material reference palette groups exposed by Kovo themes.

ts
type ThemeReferencePaletteName =
  | 'error'
  | 'neutral'
  | 'neutralVariant'
  | 'primary'
  | 'secondary'
  | 'tertiary';

ThemeReferencePalettes#

Concrete Material reference palette values by tone.

ts
type ThemeReferencePalettes = Readonly<
  Record<ThemeReferencePaletteName, Readonly<Record<number, string>>>
>;

ThemeSchemeValues#

Actual generated values for one light or dark scheme.

ts
interface ThemeSchemeValues {
  readonly custom: Readonly<Record<string, ThemeCustomColorGroup>>;
  readonly sys: {
    readonly color: ThemeSystemColorValues;
    readonly shape: ThemeShapeValues;
  };
}

ThemeSeed#

Seed color accepted by Kovo's build-time theme generator.

ts
type ThemeSeed = string | number;

ThemeShapeInput#

Shape tokens emitted beside color tokens for copied UI components.

ts
interface ThemeShapeInput {
  readonly cornerFull?: string;
  readonly cornerLarge?: string;
  readonly cornerMedium?: string;
  readonly cornerSmall?: string;
}

ThemeShapeTokenName#

System shape token names for Kovo UI components.

ts
type ThemeShapeTokenName = 'cornerFull' | 'cornerLarge' | 'cornerMedium' | 'cornerSmall';

ThemeShapeValues#

Concrete Kovo shape token values.

ts
type ThemeShapeValues = Readonly<Record<ThemeShapeTokenName, string>>;

ThemeSystemColorName#

Material system color role names exposed as Kovo's semantic color contract.

ts
type ThemeSystemColorName =
  | 'background'
  | 'error'
  | 'errorContainer'
  | 'inverseOnSurface'
  | 'inversePrimary'
  | 'inverseSurface'
  | 'onBackground'
  | 'onError'
  | 'onErrorContainer'
  | 'onPrimary'
  | 'onPrimaryContainer'
  | 'onPrimaryFixed'
  | 'onPrimaryFixedVariant'
  | 'onSecondary'
  | 'onSecondaryContainer'
  | 'onSecondaryFixed'
  | 'onSecondaryFixedVariant'
  | 'onSurface'
  | 'onSurfaceVariant'
  | 'onTertiary'
  | 'onTertiaryContainer'
  | 'onTertiaryFixed'
  | 'onTertiaryFixedVariant'
  | 'outline'
  | 'outlineVariant'
  | 'primary'
  | 'primaryContainer'
  | 'primaryFixed'
  | 'primaryFixedDim'
  | 'scrim'
  | 'secondary'
  | 'secondaryContainer'
  | 'secondaryFixed'
  | 'secondaryFixedDim'
  | 'shadow'
  | 'surface'
  | 'surfaceBright'
  | 'surfaceContainer'
  | 'surfaceContainerHigh'
// … truncated (10 more lines); see the package source for the full declaration.

ThemeSystemColorValues#

Concrete Material system color role values.

ts
type ThemeSystemColorValues = Readonly<Record<ThemeSystemColorName, string>>;

ThemeTokens#

Typed var(...) references for Kovo theme tokens used inside style.create(...).

ts
interface ThemeTokens {
  readonly component: (name: string) => string;
  readonly customColor: (name: string) => ThemeCustomColorGroup;
  readonly ref: {
    readonly palette: ThemeReferencePalettes;
  };
  readonly sys: {
    readonly color: ThemeSystemColorValues;
    readonly shape: ThemeShapeValues;
  };
}

ThemeVariant#

Material dynamic-color scheme variants supported by Kovo's public adapter.

ts
type ThemeVariant =
  | 'content'
  | 'expressive'
  | 'fidelity'
  | 'fruit-salad'
  | 'monochrome'
  | 'neutral'
  | 'rainbow'
  | 'tonal-spot'
  | 'vibrant';

Constants#

tokens#

Theme token references for authored styles; generated CSS supplies the values.

ts
const tokens = Object.freeze({
  component: (name: string) => `var(${themeVar('component', name)})`,
  customColor: (name: string) =>
    ({
      color: `var(${themeVar('custom', name, 'color')})`,
      colorContainer: `var(${themeVar('custom', name, 'color-container')})`,
      onColor: `var(${themeVar('custom', name, 'on-color')})`,
      onColorContainer: `var(${themeVar('custom', name, 'on-color-container')})`,
    }) satisfies ThemeCustomColorGroup,
  ref: {
    palette: referenceTokenVars(),
  },
  sys: {
    color: systemColorTokenVars(),
    shape: shapeTokenVars(),
  },
}) satisfies ThemeTokens;