@octans/ui 1.0.0

package/dist/utils/autoHost.d.ts

@@ -0,0 +1,27 @@
+import { Component } from 'vue';
+/**
+ * The bookkeeping behind "works with nothing mounted": counts how many outlet
+ * components are currently rendering a piece of global UI, so the auto-mounted
+ * fallback host knows when it is needed and when to stand down. The pattern
+ * comes from `ToastManager` — see the comments in its `host.ts`.
+ */
+export interface HostRegistryType {
+    readonly count: number;
+    add(): void;
+    remove(): void;
+    /** Notified whenever an outlet mounts. Returns an unsubscribe function. */
+    watch(fn: () => void): () => void;
+}
+export declare function createHostRegistry(): HostRegistryType;
+/**
+ * An auto-mounted host for one outlet component. `ensure()` mounts it on first
+ * use so the imperative API works with nothing placed in the page; an outlet
+ * the consumer mounts themselves takes over, and the auto host retires.
+ *
+ * `app.unmount()` is a real teardown — every `onUnmounted` runs — so nothing
+ * is left behind on the page or in memory.
+ */
+export declare function createAutoHost(registry: HostRegistryType, id: string, component: Component, props?: Record<string, unknown>): {
+    ensure: () => void;
+    teardown: () => void;
+};

package/dist/utils/color.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Colour values: parsing, formatting and conversion.
+ *
+ * Everything here works on one shape — `Rgba`, with channels in 0–255 and
+ * alpha in 0–1 — and converts in and out of it. That keeps the conversions to
+ * a hub-and-spoke set rather than a mesh, and means a colour picker only ever
+ * holds one representation.
+ *
+ * Channels are kept as floats internally and only rounded when formatted.
+ * Rounding on every conversion is what makes a picker drift: drag the hue
+ * slider back and forth and the colour slowly changes under you.
+ *
+ * Deliberately NOT supported: named colours (`rebeccapurple`), `var()`,
+ * `color-mix()` and `color()`. Resolving those needs either a large table or a
+ * live document, and guessing is worse than refusing — a silently wrong colour
+ * is much harder to notice than a colour that plainly did not apply. Callers
+ * get `null` and can fall back to a text field.
+ */
+export interface Rgba {
+    /** 0–255. */
+    r: number;
+    /** 0–255. */
+    g: number;
+    /** 0–255. */
+    b: number;
+    /** 0–1. */
+    a: number;
+}
+/** How a colour is written out. Parsing accepts all of these regardless. */
+export type ColorFormat = 'hex' | 'rgb' | 'hsl' | 'oklch';
+export interface ColorFormatOption {
+    value: ColorFormat;
+    label: string;
+    /** One line, for a tooltip or helper text. */
+    description: string;
+}
+export declare const COLOR_FORMATS: ColorFormatOption[];
+/**
+ * Parses any colour form this module understands into `Rgba`.
+ *
+ * Accepts `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, `rgb()`, `rgba()`, `hsl()`,
+ * `hsla()`, `oklab()`, `oklch()` and the keyword `transparent`. Returns `null`
+ * for anything else — see the note at the top of the file.
+ *
+ * Colours outside sRGB (which `oklch()` can easily express) are clamped into
+ * gamut on the way in, since the whole module works in sRGB.
+ */
+export declare function parseColor(value: string): Rgba | null;
+/** `{ r: 255, g: 0, b: 128 }` → `#ff0080`. Alpha is ignored. */
+export declare function formatHex(c: Rgba): string;
+/**
+ * Writes a colour out in the given format.
+ *
+ * `alpha` controls whether transparency may be expressed at all: with it off
+ * the colour is written opaque, which is what a picker in "no alpha" mode
+ * needs so that a stray transparent value cannot leak into the output.
+ * Otherwise alpha is only included when it is actually below 1 — nobody wants
+ * `#5f63e8ff` back when they typed `#5f63e8`.
+ */
+export declare function formatColor(c: Rgba, format?: ColorFormat, alpha?: boolean): string;
+/**
+ * The format a string was written in, so an editor can keep using it rather
+ * than rewriting the user's value into its own preferred form. Returns `null`
+ * for anything unparseable.
+ */
+export declare function detectFormat(value: string): ColorFormat | null;
+/** Returns `[hue 0–360, saturation 0–1, lightness 0–1]`. */
+export declare function rgbToHsl({ r, g, b }: Rgba): [number, number, number];
+/** `h` in degrees, `s` and `l` in 0–1. Alpha is left to the caller. */
+export declare function hslToRgb(h: number, s: number, l: number): Omit<Rgba, 'a'>;
+/**
+ * Returns `[hue 0–360, saturation 0–1, value 0–1]`.
+ *
+ * HSV rather than HSL because it is what a picker's square is: x is saturation
+ * and y is value, so the top-right corner is the pure hue. The same square in
+ * HSL would put the pure hue in the middle of the right edge and waste half the
+ * area on colours the user rarely wants.
+ */
+export declare function rgbToHsv({ r, g, b }: Rgba): [number, number, number];
+/** `h` in degrees, `s` and `v` in 0–1. */
+export declare function hsvToRgb(h: number, s: number, v: number): Omit<Rgba, 'a'>;
+export declare function toLinear(c: number): number;
+export declare function fromLinear(c: number): number;
+/** Returns `[L 0–1, a, b]`. */
+export declare function rgbToOklab({ r, g, b }: Rgba): [number, number, number];
+/**
+ * OKLab back to sRGB, clamped into gamut.
+ *
+ * OKLab describes far more colours than sRGB holds, so an out-of-gamut result
+ * has to go somewhere. Clamping each channel is what a browser effectively does
+ * when it has to produce a legacy `rgb()` output, so a colour generated here
+ * matches what CSS would have shown. Proper gamut mapping (reducing chroma
+ * until the colour fits) would be more faithful but would no longer agree with
+ * the browser.
+ */
+export declare function oklabToRgb(L: number, A: number, B: number): Omit<Rgba, 'a'>;
+/** Returns `[L 0–1, chroma, hue in degrees]`. */
+export declare function rgbToOklch(c: Rgba): [number, number, number];
+/** Below this a colour is grey, and its hue is meaningless noise. */
+export declare const ACHROMATIC = 0.0001;
+/**
+ * WCAG relative luminance, 0–1. Alpha is ignored — a colour has to be composited
+ * against something before its contrast means anything.
+ */
+export declare function relativeLuminance({ r, g, b }: Rgba): number;
+/**
+ * Whether black text reads better than white on this colour. Used to keep a
+ * swatch's own label legible whatever colour it is showing.
+ */
+export declare function prefersDarkText(c: Rgba): boolean;
+/** Composites a colour over an opaque backdrop, so its alpha can be seen. */
+export declare function flatten(c: Rgba, backdrop: Rgba): Rgba;

package/dist/utils/colorRamp.d.ts

@@ -0,0 +1,51 @@
+import { ColorFormat, Rgba } from './color';
+import { Gradient } from './gradient';
+export interface RampStepPosition {
+    /** The step's number, e.g. `200`. */
+    step: number;
+    /** Where it samples the gradient, 0–1. */
+    t: number;
+}
+/**
+ * Maps step numbers onto positions along a gradient.
+ *
+ * The numbers are spread across 0–1 by VALUE, not by index: on a `[0, 50, 100,
+ * 200, … 950]` ramp the gap from 500 to 600 is a tenth of the gap from 100 to
+ * 300, and the generated colours honour that. That is what makes a generated
+ * ramp line up with a hand-authored one, where the number has always meant "how
+ * far along". A generator that spaced these evenly would put `500` at 6/11 and
+ * quietly stop matching the ramp it replaced.
+ *
+ * Exported because a caller may want the mapping without the colours — to label
+ * a step with where it sits, or to check a ramp lines up with an existing one.
+ */
+export declare function stepPositions(steps: number[]): RampStepPosition[];
+/**
+ * Samples a gradient at each step, returning `{ [step]: '#rrggbb' }`.
+ *
+ * The lowest and highest steps land exactly on whatever the gradient holds at
+ * its two ends. Returns `null` if any stop is not a colour that can be parsed,
+ * or if there are no steps — a caller should treat that as "not a ramp" rather
+ * than substituting black, since a silently wrong ramp is much harder to notice
+ * than one that plainly did not generate.
+ */
+export declare function rampColors(gradient: Gradient, steps: number[], format?: ColorFormat): Record<number, string> | null;
+/**
+ * Builds the three-stop gradient a seed colour implies.
+ *
+ * The seed always sits at the domain's midpoint — step 500 — exactly as Ant
+ * Design's generator pins the seed to its palette slot. The colour you picked
+ * IS `<role>-500`, whatever its lightness; a pastel seed simply yields a pale
+ * upper half. Predictability beats cleverness here: "your colour is 500" is a
+ * rule a theme author can hold in their head.
+ *
+ * Returns `null` for an unparseable seed.
+ */
+export declare function seedGradient(seed: string | Rgba): Gradient | null;
+/**
+ * The whole derivation in one call: seed in, `{ step: '#rrggbb' }` out.
+ *
+ * Steps sample the gradient at `step / 1000` — see `RAMP_DOMAIN`. Returns
+ * `null` if the seed cannot be parsed.
+ */
+export declare function seedRampColors(seed: string | Rgba, steps: number[], format?: ColorFormat): Record<number, string> | null;

package/dist/utils/createTheme.d.ts

@@ -0,0 +1,52 @@
+import { CustomTheme } from './customTheme';
+import { ThemeType } from './theme';
+/** The ramp prefixes a seed can be given for, in display order. */
+export declare const THEME_SEED_ROLES: readonly ["neutral", "primary", "secondary", "tertiary", "info", "success", "warning", "error"];
+export type ThemeSeedRoleType = (typeof THEME_SEED_ROLES)[number];
+export type ThemeRadiusPresetType = 'none' | 'small' | 'medium' | 'large';
+export interface CreateThemeOptions {
+    /** Human-readable name, shown in the Theme Builder. */
+    name: string;
+    /** Storage id. Generated from the name when omitted. */
+    id?: string;
+    /**
+     * Which built-in theme to layer on. `'light'` unless stated — but note the
+     * ramps generated here feed BOTH themes; `base` only picks the starting
+     * point for anything you did not seed.
+     */
+    base?: ThemeType;
+    /** Tints every grey — surfaces, text and borders follow. */
+    neutral?: string;
+    /** The brand colour. The single highest-leverage seed. */
+    primary?: string;
+    secondary?: string;
+    tertiary?: string;
+    info?: string;
+    success?: string;
+    warning?: string;
+    error?: string;
+    /**
+     * Corner rounding, as a preset or explicit `{ field, box }` lengths.
+     * `medium` is the built-in default (4px controls / 8px containers).
+     */
+    radius?: ThemeRadiusPresetType | {
+        field: string;
+        box: string;
+    };
+}
+/**
+ * Generates a sparse `CustomTheme` from seed colours.
+ *
+ * Each seed becomes a full ramp via `seedGradient` — the seed itself lands
+ * exactly on step 500. `text-on-<role>` is chosen by measuring the generated
+ * fill: white unless the fill is light enough to want dark text.
+ *
+ * Throws on an unparseable seed rather than skipping it — a silently missing
+ * ramp looks like the theme applied and did nothing.
+ *
+ * One honest limitation: a very light seed (a pastel) generates a light upper
+ * half, and the `text-<role>` tokens that point at steps 600–700 can land
+ * under WCAG's 4.5:1 for text. `pnpm run check:contrast` guards the built-in
+ * palette only; check generated themes with the Theme Builder's preview.
+ */
+export declare function createTheme(options: CreateThemeOptions): CustomTheme;

package/dist/utils/customTheme.d.ts

@@ -0,0 +1,73 @@
+import { ThemeType } from './theme';
+import { Gradient } from './gradient';
+export interface CustomTheme {
+    /** Unique identifier, also used as the storage key suffix. */
+    id: string;
+    /** Human-readable name. */
+    name: string;
+    /** Which built-in theme this is layered on top of. */
+    base: ThemeType;
+    /** Sparse map of token name (no `--octans-` prefix) → value. */
+    tokens: Record<string, string>;
+    /**
+     * The gradient each ramp was generated from, keyed by ramp prefix
+     * (`neutral`, `primary`, …).
+     *
+     * Purely editor state: `tokens` already holds every colour, so anything
+     * applying a theme can ignore this entirely. It is stored because a gradient
+     * is NOT recoverable from the steps it produced — a five-stop gradient and a
+     * two-stop one can pass through the same dozen samples — so without it,
+     * reopening a theme would offer you a ramp you could no longer edit as the
+     * thing you built.
+     */
+    ramps?: Record<string, Gradient>;
+}
+/** Every saved theme, newest last. */
+export declare function listCustomThemes(): CustomTheme[];
+export declare function getCustomTheme(id: string): CustomTheme | undefined;
+/** Creates or replaces a saved theme, matched by `id`. */
+export declare function saveCustomTheme(theme: CustomTheme): CustomTheme[];
+export declare function deleteCustomTheme(id: string): CustomTheme[];
+export declare function getActiveCustomThemeId(): string | null;
+/**
+ * Applies a theme's overrides to the document, switching to its base theme
+ * first so unset tokens resolve correctly.
+ *
+ * Pass `target` to scope the overrides to one subtree instead. The base theme
+ * still switches document-wide — it is an attribute on `<html>`, not a set of
+ * properties — so the rest of the page follows light/dark but keeps its
+ * untouched token values.
+ *
+ * Scoped application is deliberately not remembered: `restoreCustomTheme()`
+ * would have nowhere to put it on the next page load.
+ */
+export declare function applyCustomTheme(theme: CustomTheme, target?: HTMLElement): void;
+/**
+ * Removes any custom overrides, returning to the plain base theme. Pass the
+ * same `target` that was given to `applyCustomTheme` to clear a scoped theme.
+ */
+export declare function clearCustomTheme(target?: HTMLElement): void;
+/**
+ * Re-applies whichever custom theme was last active. Call once at startup, the
+ * same way you'd call `persistTheme()`.
+ */
+export declare function restoreCustomTheme(): CustomTheme | undefined;
+/**
+ * The value a token currently resolves to, as the browser computes it —
+ * including inherited and overridden values. Used to seed the editor with real
+ * starting values rather than blanks.
+ */
+export declare function getResolvedTokenValue(name: string): string;
+export declare function exportCustomTheme(theme: CustomTheme): string;
+export declare class ThemeImportError extends Error {
+}
+/**
+ * Parses and validates a theme JSON string.
+ *
+ * Deliberately strict: unknown token names are rejected rather than silently
+ * dropped, because a typo would otherwise look like it applied and simply do
+ * nothing.
+ */
+export declare function importCustomTheme(json: string): CustomTheme;
+/** Slug + short suffix, so two themes named the same don't collide. */
+export declare function createThemeId(name: string): string;

package/dist/utils/date.d.ts

@@ -0,0 +1,4 @@
+import { default as dayjs } from 'dayjs';
+declare function setLocale(locale: string): void;
+declare const mysqlFormat = "YYYY-MM-DD HH:mm:ss";
+export { dayjs, setLocale, mysqlFormat };

package/dist/utils/debounce.d.ts

@@ -0,0 +1,3 @@
+import { default as debounce, DebouncedFunc } from 'lodash-es/debounce';
+export type { DebouncedFunc };
+export default debounce;

package/dist/utils/deferredPromise.d.ts

@@ -0,0 +1,6 @@
+declare const deferredPromise: <T>() => {
+    resolve: (value: T | PromiseLike<T>) => void;
+    reject: (reason?: any) => void;
+    promise: Promise<T>;
+};
+export default deferredPromise;

package/dist/utils/format.d.ts

@@ -0,0 +1,9 @@
+export interface FormatContextInterface {
+    locale?: string;
+    currency?: string;
+}
+export declare const emptyValuePlaceholder = "\u2014";
+export declare const formatters: Record<string, any>;
+export declare function format(value: string | number, format: string, context?: FormatContextInterface): any;
+export declare function isNumericType(type: string): boolean;
+export declare function isSummableNumericType(type: string): type is "decimal" | "currency" | "integer";

package/dist/utils/fuzzy.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Fuzzy (subsequence) matching, used by `Select`'s `fuzzy` prop and exported so
+ * applications can use the same behaviour in their own filters.
+ *
+ * The rule is simply that every character of the query appears in the text, in
+ * order, but not necessarily together — so `gwp` finds "Girl **w**ith a
+ * **P**earl Earring" and `strnght` finds "The Starry Night".
+ *
+ * Scoring exists so the good matches float to the top. Without it, fuzzy
+ * matching is worse than a plain substring filter: it returns far more rows and
+ * puts them in an arbitrary order.
+ */
+/**
+ * Scores `query` against `text`. Higher is better; `null` means no match.
+ *
+ * An empty query matches everything with a score of `0`, which keeps
+ * "no filter typed yet" from being a special case at every call site.
+ *
+ * Greedy left-to-right rather than optimal: finding the genuinely best
+ * alignment is quadratic, and for option-list lengths the difference in
+ * ordering is not worth the cost.
+ */
+export declare function fuzzyScore(query: string, text: string): number | null;
+/** Whether `query` fuzzy-matches `text` at all, ignoring how well. */
+export declare function fuzzyMatch(query: string, text: string): boolean;
+/**
+ * Filters and re-orders `items` by how well they match `query`.
+ *
+ * `getText` may return several strings — a label and a description, say — and
+ * the item scores as its best one. Ties keep their original order, so a list
+ * that was already meaningfully sorted stays that way.
+ */
+export declare function fuzzyFilter<T>(query: string, items: T[], getText: (item: T) => string | (string | undefined | null)[]): T[];

package/dist/utils/gradient.d.ts

@@ -0,0 +1,83 @@
+import { Rgba } from './color';
+export type InterpolationSpace = 'oklch' | 'oklab' | 'srgb' | 'hsl';
+export interface InterpolationSpaceOption {
+    value: InterpolationSpace;
+    label: string;
+    /** One line, for a tooltip or helper text. */
+    description: string;
+}
+/** The offered interpolation spaces, best-first. */
+export declare const INTERPOLATION_SPACES: InterpolationSpaceOption[];
+/**
+ * One colour `t` of the way from `a` to `b`, interpolated in `space`.
+ *
+ * `t` is clamped, so callers do not have to guard against a gradient whose
+ * samples run outside its endpoints.
+ */
+export declare function mixColors(a: Rgba, b: Rgba, t: number, space?: InterpolationSpace): Rgba;
+export type GradientType = 'linear' | 'radial' | 'conic';
+export interface GradientTypeOption {
+    value: GradientType;
+    label: string;
+    description: string;
+}
+export declare const GRADIENT_TYPES: GradientTypeOption[];
+export interface GradientStop {
+    /** Any colour `parseColor` understands. */
+    color: string;
+    /** Where along the gradient it sits, 0–100. */
+    position: number;
+}
+export interface Gradient {
+    type: GradientType;
+    /** Degrees. Used by `linear` and `conic`; ignored by `radial`. */
+    angle: number;
+    /** At least two, in any order — sampling and CSS output sort them. */
+    stops: GradientStop[];
+    space: InterpolationSpace;
+}
+/** A sensible two-stop gradient, as a starting point for an editor. */
+export declare function createGradient(partial?: Partial<Gradient>): Gradient;
+interface ResolvedStop {
+    color: Rgba;
+    position: number;
+}
+/**
+ * Parses and sorts the stops, or returns `null` if any colour is unusable.
+ *
+ * All-or-nothing on purpose: dropping the one stop that failed would silently
+ * produce a different gradient from the one that was asked for.
+ */
+export declare function resolveStops(stops: GradientStop[]): ResolvedStop[] | null;
+/**
+ * The colour at `t` (0–1) along the gradient, or `null` if a stop is unusable.
+ *
+ * Only the stops and the interpolation space matter here — `type` and `angle`
+ * describe how the gradient is *painted*, which is a separate question from
+ * what colour sits at a given fraction of the way along it. That is why a ramp
+ * can be generated from a conic gradient and still make sense.
+ */
+export declare function sampleGradient(gradient: Gradient, t: number): Rgba | null;
+/**
+ * The gradient as a CSS `*-gradient()` value.
+ *
+ * The stops are baked out as our own samples rather than handed to the browser
+ * as two endpoints and an `in oklch` hint. Two reasons: the result is then
+ * identical to what `sampleGradient` produces, so a preview cannot disagree
+ * with the values it is previewing; and it renders the same in browsers that do
+ * not support interpolation hints, instead of silently falling back to sRGB and
+ * looking muddy.
+ *
+ * Real stop positions are always emitted exactly, so a hard stop (two stops at
+ * the same position) stays hard rather than being blurred across a sample.
+ */
+export declare function gradientCss(gradient: Gradient, resolution?: number): string;
+/**
+ * Validates an unknown value as a `Gradient`.
+ *
+ * Used when importing a saved theme, where the JSON is whatever someone pasted
+ * in. Strict rather than forgiving: a gradient that is half-understood would
+ * regenerate a ramp into colours nobody chose.
+ */
+export declare function isGradient(value: unknown): value is Gradient;
+export {};

package/dist/utils/index.d.ts

@@ -0,0 +1,31 @@
+import { VNode, Slot } from 'vue';
+import { default as isEqual } from 'lodash-es/isEqual';
+import { default as orderBy } from 'lodash-es/orderBy';
+import { default as memoize } from 'lodash-es/memoize';
+export { isEqual, orderBy, memoize };
+export * from './deferredPromise';
+export * from './date';
+export * from './loader';
+export declare function capitalize(str: string): string;
+export declare function flattenSlotChildren(children: VNode[]): VNode[];
+export declare function isEmptyValue(value: any): boolean;
+export declare function nonEmptyChildren(vnodes: VNode[]): VNode[];
+export declare function clamp(value: number, min: number, max: number): number;
+export declare function pad(value: number): string;
+export declare function inputToNumber(value: any): any;
+export declare function scrollIntoViewIfNeeded(el?: HTMLElement & {
+    scrollIntoViewIfNeeded?: () => void;
+}): void;
+export declare function cloneDeep(value: any): any;
+export declare function escapeRegExp(string: string): string;
+export declare function createWildcardRegExp(string: string): RegExp;
+export declare function isEqualUnordered(array1: any[] | any, array2: any[] | any): boolean;
+export declare function isVNode(value: any): value is VNode;
+/**
+ * Check if a VNode has meaningful content (not just comments, whitespace, or empty fragments)
+ */
+export declare function vnodeHasContent(vnode: VNode): boolean;
+/**
+ * Check if a slot has meaningful content (not just comments, empty templates, or whitespace)
+ */
+export declare function hasSlotContent(slot: Slot | undefined, props?: Record<string, unknown>): boolean;

package/dist/utils/loader.d.ts

@@ -0,0 +1 @@
+export declare function load(urls: string[]): Promise<void[]>;

package/dist/utils/positionPanel.d.ts

@@ -0,0 +1,32 @@
+import { Placement } from '@floating-ui/dom';
+export type { Placement };
+export interface PositionPanelOptions {
+    /** Preferred placement. Flips to the opposite side when it does not fit. */
+    placement?: Placement;
+    /** Gap between the reference and the panel, in pixels. */
+    offset?: number;
+    /**
+     * Called with the placement actually used, and again whenever it changes —
+     * a panel that flips to `top-start` usually needs different styling.
+     */
+    onPlacement?: (placement: Placement) => void;
+    /** Called once, after the first position lands. */
+    onFirstUpdate?: () => void;
+}
+export interface PanelPosition {
+    /** Reposition now. `autoUpdate` covers scroll and resize on its own. */
+    update: () => void;
+    /** Stops tracking and releases the observers. */
+    destroy: () => void;
+}
+/**
+ * Positions a floating panel against a reference element and keeps it there
+ * while the page scrolls or either element resizes.
+ *
+ * This is the only imperative positioning in the library. `<Popper>` — and so
+ * `ActionList`, `DatePicker`, `TimePicker` and `ColorSelector` — goes through
+ * reka-ui, which does its own on the same floating-ui underneath. This exists
+ * for `Select`, whose dropdown is hand-rolled rather than a `<Popper>`.
+ */
+export declare function positionPanel(reference: HTMLElement, panel: HTMLElement, options?: PositionPanelOptions): PanelPosition;
+export default positionPanel;

package/dist/utils/radix.d.ts

@@ -0,0 +1,6 @@
+import { PopperPlacementType } from '../components/Popper';
+import { PopoverContentProps } from 'reka-ui';
+export declare function getRadixPopperPlacement(placement: PopperPlacementType | ''): {
+    side: PopoverContentProps['side'];
+    align: PopoverContentProps['align'];
+};

package/dist/utils/theme.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Light/dark theme control.
+ *
+ * Themes are driven by a `data-octans-theme` attribute on `<html>`:
+ *
+ *   - `'light'` / `'dark'` — an explicit choice, which always wins.
+ *   - `'system'` — remove the attribute and let `prefers-color-scheme` decide.
+ *
+ * The token stylesheet is written so that all three work without JavaScript;
+ * these helpers only set the attribute.
+ */
+export type ThemeType = 'light' | 'dark';
+export type ThemePreferenceType = ThemeType | 'system';
+/** The preference as set — may be `'system'`. */
+export declare function getThemePreference(): ThemePreferenceType;
+/**
+ * The theme actually in effect. Resolves `'system'` against
+ * `prefers-color-scheme`, defaulting to light where that can't be determined.
+ */
+export declare function getResolvedTheme(): ThemeType;
+/**
+ * Sets the theme. Pass `'system'` to follow the operating system.
+ *
+ * ```ts
+ * setTheme('dark')
+ * setTheme('system')
+ * ```
+ */
+export declare function setTheme(next: ThemePreferenceType): void;
+/** Flips between light and dark, resolving `'system'` first. */
+export declare function toggleTheme(): ThemeType;
+/**
+ * Subscribes to theme changes — including system changes while the preference
+ * is `'system'`. Returns an unsubscribe function.
+ */
+export declare function onThemeChange(fn: (theme: ThemeType) => void): () => boolean;
+/**
+ * Restores a previously persisted preference and starts saving future changes
+ * to `localStorage`. Entirely optional — call it once at startup if you want
+ * the choice to survive a reload.
+ */
+export declare function persistTheme(storageKey?: string): void;

package/dist/utils/timezone.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Timezone helpers built on the platform's `Intl` APIs.
+ *
+ * The library ships no timezone database. Zone ids, display names and country
+ * names all come from `Intl`, which means they are always current with the
+ * host's tzdata and localised for free.
+ *
+ * The one thing `Intl` has no API for is mapping a zone to a country, so that
+ * map is generated into `TimezonePicker/zoneCountries.ts` (~10 kB) and imported
+ * *dynamically* — apps that don't group by country never download it.
+ */
+export interface TimezoneOptionType {
+    /** IANA id, e.g. `Australia/Sydney`. */
+    value: string;
+    /** e.g. `Sydney, Australia`. */
+    label: string;
+    /** e.g. `Australian Eastern Time (GMT+10)`. */
+    description: string;
+    /** Region prefix of the id, e.g. `Australia`. Used for grouping. */
+    region: string;
+}
+/**
+ * Every zone the runtime knows about.
+ *
+ * `Intl.supportedValuesOf` is ES2022. Older engines get a small fallback list
+ * rather than an empty picker — enough to be usable, and `guessTimezone()`
+ * still resolves the user's actual zone either way.
+ */
+export declare function listTimezones(): string[];
+/** The user's current zone, or `UTC` if it can't be determined. */
+export declare function guessTimezone(): string;
+export declare function isValidTimezone(zone: string): boolean;
+/**
+ * A human name for the zone, localised — `Australian Eastern Time`,
+ * `India Standard Time`.
+ */
+export declare function getTimezoneName(zone: string, locale?: string): string;
+/** Current UTC offset as a short label — `GMT+10`, `GMT-4`, `GMT+5:30`. */
+export declare function getTimezoneOffset(zone: string, locale?: string): string;
+/**
+ * Turns an IANA id into something readable: `Australia/Sydney` →
+ * `Sydney, Australia`. Underscores become spaces and the path is reversed, so
+ * the city — the part people search for — leads.
+ */
+export declare function formatTimezoneId(zone: string): string;
+/** The leading region of an id: `Australia/Sydney` → `Australia`. */
+export declare function getTimezoneRegion(zone: string): string;
+/** Builds the option list the picker renders. */
+export declare function getTimezoneOptions(locale?: string): TimezoneOptionType[];
+export interface TimezoneCountryType {
+    /** ISO 3166-1 alpha-2 code. */
+    value: string;
+    /** Localised country name. */
+    label: string;
+    /** Zones belonging to this country, sorted by label. */
+    zones: string[];
+}
+/**
+ * Loads the zone → country map and inverts it into a country list.
+ *
+ * Dynamically imported on purpose: it is the only bundled timezone data, and
+ * only country grouping needs it.
+ */
+export declare function loadTimezoneCountries(locale?: string): Promise<TimezoneCountryType[]>;
+/** Looks up the country code for a zone, without loading the whole list. */
+export declare function getTimezoneCountry(zone: string): Promise<string | undefined>;