# Interfaces

Import these from `@grafloria/renderer`.

## Interfaces

### `CascadeOptions`

```ts
interface CascadeOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `includeThemeBase?` | `boolean` |  | Include the theme base as layer 1. Programmatic/Canvas mode must (there is no stylesheet); CSS mode must NOT (the stylesheet paints it, and inlining it would defeat the theme fallback and the CSS-variable scoping). |
| `connection?` | `Partial<LinkStyle>` |  | LINKS ONLY — the `highlightConnected` layer for a line touching the selection. It sits over the link's own style and its hover, and UNDER a selected or highlighted link's state: a line the user selected keeps the selection's look. |

### `ColorPreferences`

The OS-level preferences that decide which theme wins.

```ts
interface ColorPreferences
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `prefersDark` | `boolean` |  | `prefers-color-scheme: dark` |
| `prefersContrast` | `boolean` |  | `prefers-contrast: more` |
| `forcedColors` | `boolean` |  | `forced-colors: active` — Windows High Contrast and friends. |

### `ContrastCheck`

One checked pair.

```ts
interface ContrastCheck
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  | `text.primary on node.fill` — human-readable, stable enough to assert on. |
| `kind` | `'text' \| 'selection' \| 'state' \| 'link' \| 'port' \| 'category'` |  | Broad bucket, so callers can enforce selectively. |
| `foreground` | `string` |  |  |
| `background` | `string` |  |  |
| `ratio?` | `number` |  | Undefined when a colour could not be parsed (system colour, gradient, …). |
| `required` | `number` |  | The WCAG minimum this pair is held to. |
| `passes` | `boolean` |  | `false` only when we could measure it AND it fell short. |
| `exempt?` | `boolean` |  | WCAG lets disabled/inactive controls off; reported, never enforced. |

### `ContrastReport`

```ts
interface ContrastReport
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `string` |  |  |
| `checks` | `ContrastCheck[]` |  |  |
| `failures` | `ContrastCheck[]` |  | Non-exempt checks that failed. |
| `passes` | `boolean` |  | True when nothing enforceable failed. |

### `DeriveThemeOptions`

```ts
interface DeriveThemeOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `from` | `Theme` |  | The theme to derive FROM (normally a hand-tuned light theme). |
| `mode` | `'dark' \| 'high-contrast'` |  | What to build: 'dark' — the dark counterpart (flip the surfaces, keep the hues) 'high-contrast' — same colour scheme, pushed to AAA text / strong strokes |
| `name?` | `string` |  | Name of the result. Defaults to `"<from> (Dark)"` / `"<from> (High Contrast)"`. |
| `textLevel?` | `number` |  | Text level the result is repaired to. Default AA; the HC themes use AAA. |

### `Hsl`

HSL — the space the light↔dark flip has to happen in (see below).

```ts
interface Hsl
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `h` | `number` |  | 0-360 |
| `s` | `number` |  | 0-1 |
| `l` | `number` |  | 0-1 |

### `Rgb`

sRGB channels, 0-255.

```ts
interface Rgb
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `r` | `number` |  |  |
| `g` | `number` |  |  |
| `b` | `number` |  |  |

### `StyleRule`

A single CSS rule in the shared stylesheet.

```ts
interface StyleRule
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `selector` | `string` |  | Selector WITHOUT the instance scope (added by {@link generateBaseStyleSheet}). |
| `decls` | `Record<string, string>` |  | Declarations, in CSS property form (`stroke-width`, not `strokeWidth`). |

### `ThemeRef`

A reference to a theme token, usable anywhere a literal style value is. Opaque on purpose: build it with {@link themeRef}, read it with
{@link resolveThemeRef}.

```ts
interface ThemeRef
```

**Members**

- `readonly [THEME_REF_MARKER]: string`
- `readonly [THEME_REF_MARKER]: string`

### `ThemeSet`

The themes a renderer can switch BETWEEN. `light`/`dark` are required (they
are what `colorMode` selects); the high-contrast pair is optional and only
consulted when the user has actually asked for contrast.

```ts
interface ThemeSet
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `light` | `Theme` |  |  |
| `dark` | `Theme` |  |  |
| `highContrastLight?` | `Theme` |  |  |
| `highContrastDark?` | `Theme` |  |  |

### `ThemeVarBinding`

One token's binding: the custom property + how to read its value from a Theme.

```ts
interface ThemeVarBinding
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `cssVar` | `string` |  | CSS custom property name, e.g. `--grafloria-node-fill`. |
| `read` | `(theme: Theme) => string \| number` |  | Pull the raw value out of a Theme. |
| `unit?` | `'px'` |  | Appended when serializing a numeric value into CSS. |