◆ KOVO
Star
Menu

API Reference

View as Markdown

@kovojs/style

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

@kovojs/style#

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

Source: packages/style/src/index.ts

Values#

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 consumes a separate internal extraction result and lowers to ordinary class attributes for SPEC.md §5.2 fixpoint output.

Signature

ts
function create<const Styles extends Record<string, StyleObject>>(
  styles: Styles,
): { readonly [Key in keyof Styles]: StyleHandle };

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).

Signature

ts
function attrs(...styles: readonly StyleInput[]): {
  readonly class?: string;
  readonly style?: string;
};

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).

Signature

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

keyframes#

Define a CSS @keyframes animation, returning its deterministic (kv-<slug>-<hash>) animation-name for use in animationName. The compiler's StyleX extraction recognizes the style.keyframes(...) const, resolves this name, and emits the matching @keyframes block into the served CSS asset (SPEC.md §13.1); see createKeyframes for the engine's structured result.

Signature

ts
function keyframes(frames: Readonly<Record<string, StyleObject>>): 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.

Signature

ts
function defineTheme(options: DefineThemeOptions): KovoTheme;

tokens#

Typed public token refs for app-authored source (SPEC.md §13.1).

Signature

ts
const tokens: ThemeTokens = publicThemeTokens;

Supporting types#

CssValue#

Values accepted in a Kovo static style object.

Signature

ts
type CssValue = string | number | null | undefined;

StyleHandle#

Framework-created style capability accepted by style.attrs.

The runtime representation has no public fields. Type assertions can bypass TypeScript, but attrs still requires module-private WeakMap provenance.

Signature

ts
interface StyleHandle {
  readonly [styleHandleIdentity]: true;
}

StyleInput#

A style argument accepted by attrs, including nested arrays of opaque handles.

Signature

ts
type StyleInput = StyleHandle | null | false | undefined | ReadonlyArray<StyleInput>;

StyleObject#

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

Signature

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

Vars#

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

Signature

ts
type Vars<Tokens extends Record<string, CssValue>> = {
  readonly [Key in keyof Tokens]: string;
} & {
  readonly [varsIdentity]: true;
};

DefineThemeOptions#

App-facing options for generating one Kovo theme from a seed color.

Signature

ts
interface DefineThemeOptions {
  /** Additional semantic colors harmonized with the seed. */
  readonly colors?: Readonly<
    Record<
      string,
      | string
      | number
      | {
          readonly blend?: boolean;
          readonly value: string | number;
        }
    >
  >;
  /** 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;
  /** Seed color accepted as a CSS color string or finite ARGB number. */
  readonly seed: string | number;
  /** Shape token overrides. */
  readonly shape?: {
    readonly cornerFull?: string;
    readonly cornerLarge?: string;
    readonly cornerMedium?: string;
    readonly cornerSmall?: string;
  };
  /** Selector that receives light/default variables. Defaults to `:root`. */
  readonly selector?: string;
  /** Material dynamic scheme variant. Defaults to `tonal-spot`. */
  readonly variant?:
    | 'content'
    | 'expressive'
    | 'fidelity'
    | 'fruit-salad'
    | 'monochrome'
    | 'neutral'
    | 'rainbow'
    | 'tonal-spot'
    | 'vibrant';
}

KovoTheme#

Generated theme values and CSS produced by defineTheme.

Signature

ts
interface KovoTheme {
  readonly css: string;
  readonly custom: Readonly<Record<string, ReturnType<ThemeTokens['customColor']>>>;
  readonly dark: {
    readonly custom: Readonly<Record<string, ReturnType<ThemeTokens['customColor']>>>;
    readonly sys: ThemeTokens['sys'];
  };
  readonly light: {
    readonly custom: Readonly<Record<string, ReturnType<ThemeTokens['customColor']>>>;
    readonly sys: ThemeTokens['sys'];
  };
  readonly ref: ThemeTokens['ref']['palette'];
  readonly seed: string;
  readonly sys: ThemeTokens['sys'];
  readonly variant: NonNullable<DefineThemeOptions['variant']>;
}

ThemeTokens#

Typed public var(...) references for app-authored style.create(...) objects (SPEC.md §13.1).

Signature

ts
interface ThemeTokens {
  readonly customColor: (name: string) => {
    readonly color: string;
    readonly colorContainer: string;
    readonly onColor: string;
    readonly onColorContainer: string;
  };
  readonly ref: {
    readonly palette: Readonly<
      Record<
        'error' | 'neutral' | 'neutralVariant' | 'primary' | 'secondary' | 'tertiary',
        Readonly<Record<number, string>>
      >
    >;
  };
  readonly sys: {
    readonly color: Readonly<
      Record<
        | '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'
        | 'surfaceContainerHighest'
        | 'surfaceContainerLow'
        | 'surfaceContainerLowest'
        | 'surfaceDim'
        | 'surfaceTint'
        | 'surfaceVariant'
        | 'tertiary'
        | 'tertiaryContainer'
        | 'tertiaryFixed'
        | 'tertiaryFixedDim',
        string
      >
    >;
    readonly shape: Readonly<
      Record<'cornerFull' | 'cornerLarge' | 'cornerMedium' | 'cornerSmall', string>
    >;
  };
}