# zidane-ui/appearance

Import: `import { … } from 'zidane-ui/appearance'`. Source: [ui/src/appearance/index.ts](https://github.com/Tahul/zidane/blob/main/ui/src/appearance/index.ts).

## Components

### `AppearanceProvider`

Component.

Applies the host's appearance to the document and provides it to the hooks below: the active theme and palette,
contrast, accent, fonts, the code theme and the motion policy.

```ts
function AppearanceProvider(props: AppearanceProviderProps): Element
```

**Parameters**

- `props` (`AppearanceProviderProps`): See [`AppearanceProviderProps`](https://zidane.si/docs/reference/ui-appearance.md#AppearanceProviderProps).

**Returns** `Element`

**Props**

- `children` (`ReactNode`): The app.
- `extensions?` (`ExtensionsHost`): The extensions host: its `Theme` items are offered too, after the host's own extra themes. One
  theme id shows once (the appearance host's copy wins: zidane's registry serves extension themes through
  `host.themes` as well). `AppHostProvider` passes `AppHost.extensions`.
- `folder?` (`string | null`): The folder whose extra themes are offered (`host.themes`). Without one, the last folder's stay.
- `host` (`AppearanceHost`): Where the preferences live, the extra themes, the snapshot and the window effects.
- `legacyThemeId?` (`string`): A theme id from elsewhere (zidane's shared `Settings.theme`), read once on the first run to seed the pairing.
- `motion?` (`boolean`): Puts the tree under the motion preferences (`MotionProvider`, which writes `html[data-motion]`). Default: true.
- `root?` (`HTMLElement`): Where the theme vars go. Default: `<html>`. Elsewhere, no snapshot is written and the window is left alone.
- `themesKey?` (`string`): Changes when the folder's themes may have changed (its enabled extensions): they are read again.

Source: [ui/src/appearance/AppearanceProvider.tsx:117](https://github.com/Tahul/zidane/blob/main/ui/src/appearance/AppearanceProvider.tsx#L117)

## Functions

### `applyPalette`

Function.

Applies palette and contrast to the document. Toggles `.light` / `.dark` on the root (UnoCSS `dark:` and
`color-scheme` key off them); a root other than `<html>` also gets `.zg-theme-scope`, so the derived tokens
(`--zg-text`, `--zg-tray`…) resolve against its own vars instead of the page's. Suppresses transitions for one frame, so a theme swap snaps instead of
cross-fading every surface at a different speed. Values equal to the last ones written are a no-op.

```ts
function applyPalette(options: ApplyPaletteOptions): void
```

**Parameters**

- `options` (`ApplyPaletteOptions`): The palette, contrast, extra vars, root and snapshot sink.

Source: [ui/src/appearance/apply.ts:35](https://github.com/Tahul/zidane/blob/main/ui/src/appearance/apply.ts#L35)

### `codeThemesOf`

Function.

The bundled code themes of one appearance, sorted by display name.

```ts
function codeThemesOf(type: Appearance): { id: CodeThemeId; name: string }[]
```

**Parameters**

- `type` (`Appearance`): `'light'` or `'dark'`.

**Returns** `{ id: CodeThemeId; name: string }[]`

Source: [ui/src/code/code-themes.ts:183](https://github.com/Tahul/zidane/blob/main/ui/src/code/code-themes.ts#L183)

### `codeThemeTypeOf`

Function.

The appearance a bundled code theme is made for.

```ts
function codeThemeTypeOf(id: string): Appearance | undefined
```

**Parameters**

- `id` (`string`): A code theme id, such as `nord`.

**Returns** `Appearance | undefined`: `'light'` or `'dark'`, or `undefined` when `id` is not a bundled theme.

Source: [ui/src/code/code-themes.ts:174](https://github.com/Tahul/zidane/blob/main/ui/src/code/code-themes.ts#L174)

### `resolveCodeTheme`

Function.

The code theme code renders with: the pick for the current appearance, else (`'auto'`, or a pick that is not a
bundled theme of that appearance) the app theme's mapping.

```ts
function resolveCodeTheme(
  choice: CodeThemeChoice,
  themeId: string,
  appearance: Appearance,
): CodeThemeId
```

**Parameters**

- `choice` (`CodeThemeChoice`): The code theme per appearance.
- `themeId` (`string`): The active app theme.
- `appearance` (`Appearance`): The active appearance.

**Returns** `CodeThemeId`

Source: [ui/src/appearance/AppearanceProvider.tsx:52](https://github.com/Tahul/zidane/blob/main/ui/src/appearance/AppearanceProvider.tsx#L52)

### `useAppearance`

Function.

The appearance state and its setters. Outside an [`AppearanceProvider`](https://zidane.si/docs/reference/ui-appearance.md#AppearanceProvider) the setters do nothing.

```ts
function useAppearance(): AppearanceApi
```

**Returns** `AppearanceApi`

Source: [ui/src/appearance/AppearanceProvider.tsx:258](https://github.com/Tahul/zidane/blob/main/ui/src/appearance/AppearanceProvider.tsx#L258)

### `useAppearanceHost`

Function.

The host from the nearest [`AppearanceProvider`](https://zidane.si/docs/reference/ui-appearance.md#AppearanceProvider), or `null` outside one.

```ts
function useAppearanceHost(): AppearanceHost | null
```

**Returns** `AppearanceHost | null`

Source: [ui/src/appearance/AppearanceProvider.tsx:218](https://github.com/Tahul/zidane/blob/main/ui/src/appearance/AppearanceProvider.tsx#L218)

### `useAppearanceMotion`

Function.

The motion level the preferences resolve to (`system` follows the OS).

```ts
function useAppearanceMotion(): 'off' | 'reduced' | 'full'
```

**Returns** `'off' | 'reduced' | 'full'`

Source: [ui/src/appearance/AppearanceProvider.tsx:228](https://github.com/Tahul/zidane/blob/main/ui/src/appearance/AppearanceProvider.tsx#L228)

### `useAppearanceReducedMotion`

Function.

True for `off` and `reduced`: skip decorative JS-driven animation.

```ts
function useAppearanceReducedMotion(): boolean
```

**Returns** `boolean`

Source: [ui/src/appearance/AppearanceProvider.tsx:233](https://github.com/Tahul/zidane/blob/main/ui/src/appearance/AppearanceProvider.tsx#L233)

### `useAppearanceState`

Function.

The stored preferences (`DEFAULT_APPEARANCE` outside an [`AppearanceProvider`](https://zidane.si/docs/reference/ui-appearance.md#AppearanceProvider)).

```ts
function useAppearanceState(): AppearanceState
```

**Returns** `AppearanceState`

Source: [ui/src/appearance/AppearanceProvider.tsx:223](https://github.com/Tahul/zidane/blob/main/ui/src/appearance/AppearanceProvider.tsx#L223)

### `useColors`

Function.

The active theme's colors.

```ts
function useColors(): ThemeColors
```

**Returns** `ThemeColors`

Source: [ui/src/appearance/AppearanceProvider.tsx:203](https://github.com/Tahul/zidane/blob/main/ui/src/appearance/AppearanceProvider.tsx#L203)

### `useOsReducedMotion`

Function.

Whether the OS asks for reduced motion, followed live. False on the server.

```ts
function useOsReducedMotion(): boolean
```

**Returns** `boolean`

Source: [ui/src/appearance/AppearanceProvider.tsx:299](https://github.com/Tahul/zidane/blob/main/ui/src/appearance/AppearanceProvider.tsx#L299)

### `usePalette`

Function.

The active derived palette.

```ts
function usePalette(): ResolvedPalette
```

**Returns** `ResolvedPalette`

Source: [ui/src/appearance/AppearanceProvider.tsx:208](https://github.com/Tahul/zidane/blob/main/ui/src/appearance/AppearanceProvider.tsx#L208)

### `useShikiTheme`

Function.

The theme for code right now: the code theme pick for the current appearance, else the app theme's.

```ts
function useShikiTheme(): CodeThemeId
```

**Returns** `CodeThemeId`

Source: [ui/src/appearance/AppearanceProvider.tsx:213](https://github.com/Tahul/zidane/blob/main/ui/src/appearance/AppearanceProvider.tsx#L213)

### `useTheme`

Function.

The active theme (the default theme outside an [`AppearanceProvider`](https://zidane.si/docs/reference/ui-appearance.md#AppearanceProvider)).

```ts
function useTheme(): Theme
```

**Returns** `Theme`

Source: [ui/src/appearance/AppearanceProvider.tsx:198](https://github.com/Tahul/zidane/blob/main/ui/src/appearance/AppearanceProvider.tsx#L198)

## Interfaces

### `AppearanceApi`

Interface.

The appearance state and its setters, for a settings panel.

```ts
interface AppearanceApi
```

**Properties**

- `activeThemeId` (`string`): The active theme's id.
- `appearance` (`Appearance`): The active appearance.
- `availableThemes` (`readonly Theme[]`): Every theme selectable right now (built-in and the host's extra ones).
- `pickTheme` (`(theme: Theme) => void`): Assigns a theme to the slot its own appearance implies (light theme → light slot).
- `reset` (`() => void`): Back to the defaults.
- `set` (`(update: Partial<AppearanceState>) => void`): Merges a change into the preferences.
- `setMode` (`(mode: AppearanceMode) => void`): Sets the mode.
- `state` (`AppearanceState`): The stored preferences.

Source: [ui/src/appearance/AppearanceProvider.tsx:238](https://github.com/Tahul/zidane/blob/main/ui/src/appearance/AppearanceProvider.tsx#L238)

### `AppearanceProviderProps`

Interface.

Props for [`AppearanceProvider`](https://zidane.si/docs/reference/ui-appearance.md#AppearanceProvider).

```ts
interface AppearanceProviderProps
```

**Properties**

- `children` (`ReactNode`): The app.
- `extensions?` (`ExtensionsHost`): The extensions host: its `Theme` items are offered too, after the host's own extra themes. One
  theme id shows once (the appearance host's copy wins: zidane's registry serves extension themes through
  `host.themes` as well). `AppHostProvider` passes `AppHost.extensions`.
- `folder?` (`string | null`): The folder whose extra themes are offered (`host.themes`). Without one, the last folder's stay.
- `host` (`AppearanceHost`): Where the preferences live, the extra themes, the snapshot and the window effects.
- `legacyThemeId?` (`string`): A theme id from elsewhere (zidane's shared `Settings.theme`), read once on the first run to seed the pairing.
- `motion?` (`boolean`): Puts the tree under the motion preferences (`MotionProvider`, which writes `html[data-motion]`). Default: true.
- `root?` (`HTMLElement`): Where the theme vars go. Default: `<html>`. Elsewhere, no snapshot is written and the window is left alone.
- `themesKey?` (`string`): Changes when the folder's themes may have changed (its enabled extensions): they are read again.

Source: [ui/src/appearance/AppearanceProvider.tsx:88](https://github.com/Tahul/zidane/blob/main/ui/src/appearance/AppearanceProvider.tsx#L88)

### `ApplyPaletteOptions`

Interface.

Options of [`applyPalette`](https://zidane.si/docs/reference/ui-appearance.md#applyPalette).

```ts
interface ApplyPaletteOptions
```

**Properties**

- `boot?` (`(snapshot: BootSnapshot) => void`): Stores the pre-paint snapshot after a write (`AppearanceHost.boot.write`).
- `contrast?` (`number`): 50..200, default 100.
- `extraVars?` (`Record<string, string>`): Extra vars applied in the same frame (fonts) and included in the snapshot.
- `palette` (`ResolvedPalette`): The derived palette.
- `root?` (`HTMLElement`): Where the vars go. Default: `<html>`.

Source: [ui/src/appearance/apply.ts:11](https://github.com/Tahul/zidane/blob/main/ui/src/appearance/apply.ts#L11)

## Types

### `CodeTheme`

Type.

A bundled code theme id, what the highlighters take.

```ts
type CodeTheme = ReturnType<typeof shikiThemeFor>
```

Source: [ui/src/appearance/AppearanceProvider.tsx:42](https://github.com/Tahul/zidane/blob/main/ui/src/appearance/AppearanceProvider.tsx#L42)