zidanezidane-ui/
import { … } from 'zidane-ui/appearance/headless'ui/src/appearance/headless/index.ts
Functions#
activeThemeIdFunction#
The theme id to show: the dark slot when the mode (or the OS, under system) asks for dark, else the light slot.
function activeThemeId(state: AppearanceState, prefersDark: boolean): stringParameters
| Name | Type | Description |
|---|---|---|
| state | AppearanceState | The preferences. |
| prefersDark | boolean | Whether the OS prefers dark. |
Returns
stringavailableCuratedFontsFunction#
The curated fonts installed on this computer.
function availableCuratedFonts(): FontOption[]Returns
createStorageAppearancePrefsFunction#
Appearance preferences kept in a Storage under one key, read on first use and validated with parseAppearance.
Another window's change (the storage event) is adopted and announced.
function createStorageAppearancePrefs(
options: StorageAppearancePrefsOptions,
): AppearancePrefsParameters
| Name | Type | Description |
|---|---|---|
| options | StorageAppearancePrefsOptions | The storage, the key and how to check code theme ids. |
Returns
createStorageBootFunction#
The pre-paint snapshot kept in a Storage as a flat JSON blob ({ appearance, vars }), so the page's inline
script needs no logic beyond setProperty.
function createStorageBoot(storage: AppearanceStorage, key?: string): AppearanceBootParameters
| Name | Type | Default | Description |
|---|---|---|---|
| storage | AppearanceStorage | Where to keep it, such as | |
| key? | string | BOOT_SNAPSHOT_KEY | The key. Default: |
Returns
cssFamilyFunction#
Quotes a family name for CSS when it contains spaces or punctuation.
function cssFamily(family: string): stringParameters
| Name | Type | Description |
|---|---|---|
| family | string | The family name. |
Returns
stringfontStackFunction#
A font stack with the chosen family first, so a font that disappears degrades to the default stack.
function fontStack(choice: string | null, kind: 'ui' | 'mono'): stringParameters
| Name | Type | Description |
|---|---|---|
| choice | string | null | The chosen family, or |
| kind | 'ui' | 'mono' | Which default stack follows it. |
Returns
stringfontsToCssVarsFunction#
The font CSS variables for the picked families and sizes.
function fontsToCssVars(fonts: FontChoices, sizes: FontSizes): FontCssVarsParameters
| Name | Type | Description |
|---|---|---|
| fonts | FontChoices | The families per role. |
| sizes | FontSizes | The sizes per role. |
Returns
guessKindFunction#
Guesses a family's kind from its name (the Local Font Access API doesn't classify).
function guessKind(family: string): 'mono' | 'sans' | 'serif'Parameters
| Name | Type | Description |
|---|---|---|
| family | string | The family name. |
Returns
'mono' | 'sans' | 'serif'isFontAvailableFunction#
True when family renders differently from both generic fallbacks,
i.e. the OS resolved it to an actual installed face. Cheap (three
measureText calls), synchronous, no permission needed.
function isFontAvailable(family: string): booleanParameters
| Name | Type | Description |
|---|---|---|
| family | string | The family name. |
Returns
booleanparseAppearanceFunction#
Validates a stored blob field by field; anything unrecognised falls back to its default.
function parseAppearance(
raw: string,
options?: ParseAppearanceOptions,
): AppearanceState | undefinedParameters
| Name | Type | Default | Description |
|---|---|---|---|
| raw | string | The stored JSON. | |
| options? | ParseAppearanceOptions | {} | How to check code theme ids. |
Returns
AppearanceState | undefinedThe preferences, or undefined when raw is not a known blob.
queryInstalledFontsFunction#
Installed families via the Local Font Access API. Resolves to [] when
unsupported or denied. Families are de-duplicated and sorted; kind is
guessed from the name because the API doesn't classify.
function queryInstalledFonts(): Promise<FontOption[]>Returns
Promise<FontOption[]>resolveMotionFunction#
The motion level a preference resolves to: system follows the OS, an explicit choice wins.
function resolveMotion(
pref: MotionPreference,
osReducedMotion: boolean,
): 'off' | 'reduced' | 'full'Parameters
| Name | Type | Description |
|---|---|---|
| pref | MotionPreference | The stored preference. |
| osReducedMotion | boolean | Whether the OS asks for reduced motion. |
Returns
'off' | 'reduced' | 'full'stepInterfaceScaleFunction#
The preferences with the interface scale one step up or down, or back to 1, clamped to LIMITS.
function stepInterfaceScale(
prev: AppearanceState,
direction: -1 | 0 | 1,
): AppearanceStateParameters
| Name | Type | Description |
|---|---|---|
| prev | AppearanceState | The current preferences. |
| direction | -1 | 0 | 1 |
|
Returns
zoomKeyCommandsFunction#
The zoom key commands over a host's preferences.
function zoomKeyCommands(prefs: Pick<AppearancePrefs, 'set'>): KeyCommandsParameters
| Name | Type | Description |
|---|---|---|
| prefs | Pick<AppearancePrefs, 'set'> | The appearance host's preferences. |
Returns
Constants#
APPEARANCE_STORAGE_KEYConstant#
The key the preferences live under.
const APPEARANCE_STORAGE_KEY = 'zg:appearance:v1'BOOT_SNAPSHOT_KEYConstant#
The key the pre-paint snapshot lives under. A page's inline script replays it before any bundle loads.
const BOOT_SNAPSHOT_KEY = 'zg:appearance:boot:v1'CURATED_FONTSConstant#
Curated candidates. Order = display order within each kind. Availability is checked at runtime; missing ones are hidden from the picker.
const CURATED_FONTS: readonly FontOption[]DEFAULT_APPEARANCEConstant#
The preferences before the user changes anything.
const DEFAULT_APPEARANCE: AppearanceStateFONT_STACKSConstant#
The default font stacks: the platform UI stack and ui-monospace.
const FONT_STACKS: { readonly mono: 'ui-monospace, \'SF Mono\', SFMono-Regular, Menlo, Monaco, Consolas, \'Liberation Mono\', monospace'; readonly ui: '-apple-system, BlinkMacSystemFont, \'Segoe UI\', system-ui, Roboto, sans-serif' }LIMITSConstant#
The bounds (and slider steps) of the numeric preferences.
const LIMITS: { readonly contrast: { readonly max: 200; readonly min: 50; readonly step: 5 }; readonly fontSize: { readonly max: 22; readonly min: 10; readonly step: 1 }; readonly interfaceScale: { readonly max: 1.5; readonly min: 0.8; readonly step: 0.05 }; readonly panelMs: { readonly max: 400; readonly min: 0; readonly step: 20 }; readonly panelWidth: { readonly max: 900; readonly min: 300 }; readonly sidebarWidth: { readonly max: 480; readonly min: 220 } }Interfaces#
AppearanceBootInterface#
Where the pre-paint snapshot goes.
interface AppearanceBootProperties
| Name | Type | Description |
|---|---|---|
| write | (snapshot: BootSnapshot) => void | Stores the snapshot (after every apply that changed something). |
AppearanceHostInterface#
The appearance host. Only prefs is required.
interface AppearanceHostProperties
| Name | Type | Description |
|---|---|---|
| boot? | AppearanceBoot | Where the pre-paint snapshot goes. Absent: none is written. |
| prefs | AppearancePrefs | The stored preferences. |
| window? | AppearanceWindow | Native window effects. Absent: the window is left alone. |
| themes? | (folder: string) => Promise<readonly Theme[]> | Themes beyond the built-in ones for a folder (its extensions'). Absent: built-in themes only. |
AppearancePrefsInterface#
The stored preferences: read with get, follow with subscribe, change with set.
interface AppearancePrefs extends Readable<AppearanceState>Properties
| Name | Type | Description |
|---|---|---|
getfrom Readable | () => AppearanceState | Returns the current value. |
| isFirstRun | () => boolean | True until preferences were stored: the app's first run on this computer. |
| reset | () => void | Back to |
| set | (update: Partial<AppearanceState> | ((prev: AppearanceState) => AppearanceState)) => void | Merges |
subscribefrom Readable | (onChange: () => void) => () => void | Registers a listener called after the value changes. Returns a function that removes the listener. |
AppearanceStateInterface#
Every appearance preference, as stored.
interface AppearanceStateProperties
| Name | Type | Description |
|---|---|---|
| accentOverride | string | null |
|
| codeTheme | CodeThemeChoice | The code theme per appearance. |
| contrast | number | 50..200, 100 = as designed. |
| darkTheme | string | The theme id shown while dark (registry or extension). |
| filesTreeSide | FilesTreeSide | Which side of the Files tab the tree column sits on. |
| fonts | FontChoices | Font families per role. |
| fontSizes | FontSizes | Font sizes per role. |
| interfaceScale | number | The interface zoom factor, 0.8..1.5. |
| lightTheme | string | The theme id shown while light (registry or extension). |
| mode | AppearanceMode | System, light or dark. |
| motion | MotionPreference | The motion preference. |
| panelMs | number | Panel open/close duration in ms (sidebar, side panels), 0..400. |
| panelWidth | number | The side panel's drag-resized width in CSS px; persisted on drag end only. |
| sidebarWidth | number | The sidebar's drag-resized width in CSS px; persisted on drag end only. |
| springs | boolean | Spring animations: motion settles with physics (a hint of overshoot) instead of fixed ease-out curves. Only meaningful at the Full level. |
| version | 2 | The blob's version. |
AppearanceWindowInterface#
What the window does natively when the appearance changes. Each member is optional.
interface AppearanceWindowProperties
| Name | Type | Description |
|---|---|---|
| setBackground? | (color: string) => Promise<void> | Paints the window background shown during resize, before the page does. |
| setNativeTheme? | (mode: AppearanceMode) => Promise<void> | Mirrors the mode into the native chrome (title bar, menus). |
| setZoom? | (factor: number) => Promise<void> | Applies the interface scale (a zoom factor, 0.8..1.5). |
BootSnapshotInterface#
The pre-paint snapshot: the last applied CSS variables, replayed before any script loads.
interface BootSnapshotProperties
| Name | Type | Description |
|---|---|---|
| appearance | 'dark' | 'light' | The appearance class ( |
| vars | Record<string, string> |
|
CodeThemeChoiceInterface#
Syntax colours per appearance. Only the tokens come from the code theme; the code background is always the app's, so each slot holds a theme of its type.
interface CodeThemeChoiceProperties
| Name | Type | Description |
|---|---|---|
| dark | CodeThemePick | The pick while the app is dark. |
| light | CodeThemePick | The pick while the app is light. |
FontChoicesInterface#
The font families picked per role, as the OS names them. null: the stylesheet default.
interface FontChoicesProperties
| Name | Type | Description |
|---|---|---|
| chat | string | null | The transcript font (default: the interface font). |
| mono | string | null | The code font. |
| prompt | string | null | The prompt font (default: the transcript font). |
| ui | string | null | The interface font. |
FontOptionInterface#
A font the picker offers.
interface FontOptionProperties
| Name | Type | Description |
|---|---|---|
| family | string | Family name as passed to CSS. |
| kind | 'mono' | 'sans' | 'serif' | Its kind, for grouping. |
| label | string | Name shown in the picker. |
FontSizesInterface#
Font sizes in CSS px.
interface FontSizesProperties
| Name | Type | Description |
|---|---|---|
| chat | number | The transcript. |
| code | number | Code blocks and the editor. |
| prompt | number | The prompt. |
ParseAppearanceOptionsInterface#
Options of parseAppearance.
interface ParseAppearanceOptionsProperties
| Name | Type | Description |
|---|---|---|
| codeThemeType? | (id: string) => 'dark' | 'light' | undefined | The appearance a code theme id is made for, |
StorageAppearancePrefsOptionsInterface#
Options of createStorageAppearancePrefs.
interface StorageAppearancePrefsOptions extends ParseAppearanceOptionsProperties
| Name | Type | Description |
|---|---|---|
codeThemeType?from ParseAppearanceOptions | (id: string) => 'dark' | 'light' | undefined | The appearance a code theme id is made for, |
| key? | string | The key. Default: |
| storage | AppearanceStorage | Where the preferences live. |
| watch? | (key: string, onChange: () => void) => () => void | Calls |
Types#
AppearanceModeType#
Which appearance the app shows: the OS's, or always light or dark.
type AppearanceMode = 'system' | 'light' | 'dark'AppearanceStorageType#
The Storage calls the appearance stores make (localStorage or a double).
type AppearanceStorage = Pick<Storage, 'getItem' | 'setItem'>CodeThemePickType#
A bundled code theme id, or 'auto': the app theme's own mapping.
type CodeThemePick = 'auto' | (string & {})FilesTreeSideType#
Which side of the Files tab the tree column sits on.
type FilesTreeSide = 'left' | 'right'FontCssVarsType#
The font CSS variables fontsToCssVars writes.
type FontCssVars = Record<'--zg-font-ui' | '--zg-font-chat' | '--zg-font-prompt' | '--zg-font-mono' | '--zg-font-size-chat' | '--zg-font-size-prompt' | '--zg-font-size-code', string>MotionPreferenceType#
How much the UI animates. system follows the OS reduced-motion preference.
type MotionPreference = 'system' | 'off' | 'reduced' | 'full'Re-exports#
These names are documented on the entry point that owns them.