@octans/ui 1.0.0 → 1.3.0

package/dist/utils/color.d.ts

@@ -106,7 +106,18 @@ 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.
+ *
+ * A lightness rule of thumb, not a measurement — use `contrastRatio` when the
+ * answer has to hold up as a WCAG number rather than just look right.
  */
 export declare function prefersDarkText(c: Rgba): boolean;
+/**
+ * WCAG contrast ratio between two colours, 1–21. Symmetric: the lighter of the
+ * pair goes on top whichever order they arrive in.
+ *
+ * Alpha is ignored, as in `relativeLuminance` — `flatten` a translucent colour
+ * over its backdrop first if you want the composited answer.
+ */
+export declare function contrastRatio(a: Rgba, b: Rgba): number;
 /** 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/contrastPairs.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The token pairs whose contrast actually matters, with the ratio each owes.
+ *
+ * One list, two consumers: `scripts/check-contrast.mjs` audits the built-in
+ * palette with it at build time, and the Theme Builder measures a theme being
+ * edited against it live. Keeping them on the same table is the point — a pair
+ * the script guards but the Builder never shows is a rule a custom theme can
+ * break in silence.
+ *
+ * The script is plain `.mjs` and imports this `.ts` directly: Node strips the
+ * types on the way in (the engines field already requires Node 24, where that
+ * is on by default). So keep this file to types the stripper can simply
+ * delete — no enums, no namespaces, no `const enum`.
+ *
+ * On the thresholds:
+ *
+ *   4.5  body text (WCAG 1.4.3).
+ *   3.0  UI components and graphical objects needed to understand the
+ *        interface (WCAG 1.4.11) — input outlines, focus rings.
+ *
+ * A plain divider is decorative and carries NO WCAG requirement, so `border`
+ * gets a loose sanity floor instead: enough to be visible, not so much that
+ * every table row grows a heavy rule. Don't "fix" a border failure by
+ * darkening it past what the design wants — check which of the two cases it
+ * actually is first.
+ */
+export interface ContrastPair {
+    /** Token read as the foreground. */
+    fg: string;
+    /** Token it sits on. */
+    bg: string;
+    /** What the pair is, for messages. */
+    label: string;
+    /** The ratio it has to clear. */
+    min: number;
+}
+export declare const CONTRAST_PAIRS: ContrastPair[];
+/** Every pair a given token is the foreground of. */
+export declare function pairsForToken(name: string): ContrastPair[];

package/dist/utils/createTheme.d.ts

@@ -3,6 +3,19 @@ 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];
+/** The roles that have a fill, and therefore a `text-on-<role>` label. */
+export declare const THEME_FILL_ROLES: ThemeFillRoleType[];
+export type ThemeFillRoleType = Exclude<ThemeSeedRoleType, 'neutral'>;
+/**
+ * The ramp step each role's semantic FILL token points at (see tokens.scss).
+ * `createTheme` measures the generated colour at this step to pick a legible
+ * `text-on-<role>`.
+ *
+ * Exported because the Theme Builder needs the same mapping: a fill edited by
+ * hand has to re-derive its label the way a seeded one does, and it can only
+ * know which step to read from here.
+ */
+export declare const ROLE_FILL_STEP: Record<ThemeFillRoleType, number>;
 export type ThemeRadiusPresetType = 'none' | 'small' | 'medium' | 'large';
 export interface CreateThemeOptions {
     /** Human-readable name, shown in the Theme Builder. */
@@ -50,3 +63,19 @@ export interface CreateThemeOptions {
  * palette only; check generated themes with the Theme Builder's preview.
  */
 export declare function createTheme(options: CreateThemeOptions): CustomTheme;
+/** What `darkText` falls back to when a theme seeds no neutral of its own. */
+export declare const DEFAULT_DARK_TEXT = "#11151a";
+/**
+ * The label a fill wants: white if it clears WCAG's 4.5:1 there — the house
+ * style for labels on fills — otherwise whichever of white and the theme's
+ * near-black measures stronger. Measured, not guessed by lightness: on a
+ * mid-tone fill the two can sit either side of the threshold by a whisker.
+ *
+ * Returns null when the fill cannot be parsed, so a caller can leave whatever
+ * is already there alone rather than write a guess over it.
+ *
+ * Exported for the Theme Builder, which re-derives labels as fills are edited
+ * by hand. Both paths must agree — a fill that arrives via a seed and the same
+ * fill typed into the token list should end up with the same label.
+ */
+export declare function labelForFill(fill: string, darkText?: string): string | null;

package/dist/utils/customTheme.d.ts

@@ -57,7 +57,7 @@ export declare function restoreCustomTheme(): CustomTheme | undefined;
  * 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 getResolvedTokenValue(name: string, from?: Element): string;
 export declare function exportCustomTheme(theme: CustomTheme): string;
 export declare class ThemeImportError extends Error {
 }

package/dist/utils/date.d.ts

@@ -1,4 +1,15 @@
 import { default as dayjs } from 'dayjs';
 declare function setLocale(locale: string): void;
+declare function setTimezone(timezone?: string | null): void;
+declare function getTimezone(): string | undefined;
+/**
+ * Reads a value in the display time zone, or the viewer's clock when there
+ * isn't one. `timezone` overrides the global for this one call.
+ *
+ * A zone the runtime rejects falls back rather than throwing: a date that
+ * renders in the wrong zone is a bug, and a component that throws while
+ * rendering is an outage.
+ */
+declare function inTimezone(value?: dayjs.ConfigType, timezone?: string): dayjs.Dayjs;
 declare const mysqlFormat = "YYYY-MM-DD HH:mm:ss";
-export { dayjs, setLocale, mysqlFormat };
+export { dayjs, setLocale, setTimezone, getTimezone, inTimezone, mysqlFormat };

package/dist/utils/format.d.ts

@@ -1,6 +1,14 @@
 export interface FormatContextInterface {
     locale?: string;
     currency?: string;
+    /**
+     * IANA time zone the date formatters render in (`'America/Los_Angeles'`).
+     *
+     * Defaults to the library-wide display zone set with `setTimezone`, and
+     * failing that the viewer's own clock — which is what every date here used
+     * to be, unconditionally.
+     */
+    timezone?: string;
 }
 export declare const emptyValuePlaceholder = "\u2014";
 export declare const formatters: Record<string, any>;

package/dist/utils/positionPanel.d.ts

@@ -23,10 +23,10 @@ export interface PanelPosition {
  * 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
+ * This is the only imperative positioning in the library. `<Popover>` — 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>`.
+ * for `Select`, whose dropdown is hand-rolled rather than a `<Popover>`.
  */
 export declare function positionPanel(reference: HTMLElement, panel: HTMLElement, options?: PositionPanelOptions): PanelPosition;
 export default positionPanel;

package/dist/utils/radix.d.ts

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

package/dist/utils/tokens.d.ts

@@ -8,7 +8,7 @@
  * Keep it in sync when adding a token. `tokens.test.ts` fails if the stylesheet
  * and this registry drift apart, so it cannot rot silently.
  */
-export type TokenKind = 'color' | 'shadow' | 'radius' | 'font';
+export type TokenKind = 'color' | 'shadow' | 'radius' | 'font' | 'length';
 export interface TokenDefinition {
     /** Token name without the `--octans-` prefix. */
     name: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@octans/ui",
-  "version": "1.0.0",
-  "description": "A Vue 3 component library — accessible, themeable UI primitives and application shell components.",
+  "version": "1.3.0",
+  "description": "A Vue 3 component library \u2014 accessible, themeable UI primitives and application shell components.",
   "keywords": [
     "vue",
     "vue3",
@@ -29,7 +29,8 @@
   },
   "files": [
     "dist",
-    "bin"
+    "bin",
+    "skills"
   ],
   "exports": {
     ".": {
@@ -38,12 +39,35 @@
       "default": "./dist/ui.js"
     },
     "./style.css": "./dist/style.css",
+    "./reset.css": "./dist/reset.css",
     "./dist/*": "./dist/*",
     "./package.json": "./package.json"
   },
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "dev": "pnpm storybook",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build",
+    "build-site": "storybook build --output-dir site-dist/storybook && node scripts/build-site.mjs",
+    "type-check": "vue-tsc --noEmit -p tsconfig.app.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "check:contrast": "node scripts/check-contrast.mjs",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write src/ .storybook/ scripts/ *.ts *.js",
+    "format:check": "prettier --check src/ .storybook/ scripts/ *.ts *.js",
+    "icons:bundle": "node scripts/build-icon-bundle.mjs",
+    "check:icons": "node scripts/check-icon-bundle.mjs",
+    "build": "pnpm run build-lib",
+    "build-lib": "vp build --config vite.config-lib.ts && vp build --config vite.config-umd.ts",
+    "verify": "pnpm run lint && pnpm run type-check && pnpm run test && pnpm run check:contrast && pnpm run check:icons && pnpm run build-lib",
+    "prepublishOnly": "pnpm run verify",
+    "tag": "package-version-git-tag --push"
+  },
   "dependencies": {
     "@floating-ui/dom": "^1.8.0",
     "@iconify/vue": "^5.0.1",
@@ -97,24 +121,5 @@
   "engines": {
     "node": ">=24"
   },
-  "scripts": {
-    "dev": "pnpm storybook",
-    "storybook": "storybook dev -p 6006",
-    "build-storybook": "storybook build",
-    "type-check": "vue-tsc --noEmit -p tsconfig.app.json",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "check:contrast": "node scripts/check-contrast.mjs",
-    "lint": "eslint .",
-    "lint:fix": "eslint . --fix",
-    "format": "prettier --write src/ .storybook/ scripts/ *.ts *.js",
-    "format:check": "prettier --check src/ .storybook/ scripts/ *.ts *.js",
-    "icons:bundle": "node scripts/build-icon-bundle.mjs",
-    "check:icons": "node scripts/check-icon-bundle.mjs",
-    "build": "pnpm run build-lib",
-    "build-lib": "vp build --config vite.config-lib.ts && vp build --config vite.config-umd.ts",
-    "verify": "pnpm run lint && pnpm run type-check && pnpm run test && pnpm run check:contrast && pnpm run check:icons && pnpm run build-lib",
-    "tag": "package-version-git-tag --push"
-  }
-}
+  "packageManager": "pnpm@11.6.0"
+}

package/skills/octans-ui/SKILL.md

@@ -0,0 +1,303 @@
+---
+name: octans-ui
+description: Build interfaces with the @octans/ui Vue 3 component library — setup, the design-token system, theming, the $ui global helpers, and the inheritance traps that make components look broken in dark mode. Use when writing or reviewing Vue code that imports from @octans/ui, when styling against --octans-* tokens, or when building a custom theme.
+license: MIT
+compatibility: Any agent supporting the Agent Skills standard. Requires a Vue 3.5+ project with @octans/ui installed. Optional peer, vue-router, only for MaybeRouterLink and Navigation.
+---
+
+# Octans UI
+
+An opinionated Vue 3 component library: ~77 accessible, themeable components
+plus the application shell pieces (nav, frame, sheets, toasts). Docs live at
+<https://octans.dev>, source at <https://github.com/tarwin/octans-ui>.
+
+## Setup
+
+Two things are required — the stylesheet, and a `UiProvider` at the app root.
+A full-page app needs a third: the reset.
+
+```ts
+// main.ts
+import { createApp } from 'vue'
+import UI from '@octans/ui'
+import '@octans/ui/style.css'
+// Only when Octans owns the whole page — see below.
+import '@octans/ui/reset.css'
+import App from './App.vue'
+
+createApp(App).use(UI).mount('#app')
+```
+
+```vue
+<!-- App.vue -->
+<script setup lang="ts">
+import { UiProvider } from '@octans/ui'
+</script>
+
+<template>
+  <UiProvider>
+    <!-- your app -->
+  </UiProvider>
+</template>
+```
+
+`UiProvider` supplies the context tooltips, popovers and the global overlays
+rely on. Without it, anything using `Tooltip` throws on mount.
+
+`.use(UI)` is optional — it registers every component globally, which pulls
+them all into the bundle. Prefer named imports and skip the plugin:
+
+```vue
+<script setup lang="ts">
+import { Button, Card, CardSection } from '@octans/ui'
+</script>
+```
+
+The stylesheet and `UiProvider` are needed either way. The plugin also installs
+the `$ui` global; without it, import `toast`, `confirmModal`, `promptModal`,
+`loader`, `saveBar` and `progress` by name instead.
+
+### `reset.css` — when Octans owns the page
+
+`style.css` deliberately resets nothing outside `.UIElement`. That keeps the
+library safe to drop into a page it doesn't own, and it is the wrong default
+for an app where Octans IS the UI: everything the app renders itself — the
+shell, the layout wrappers, the nav — falls back to browser defaults. Serif
+text, the user agent's 8px body margin, `content-box` sizing, and a body with
+no height that grows past the viewport into a second scrollbar.
+
+`@octans/ui/reset.css` is that missing layer, and nothing more. Import it after
+`style.css` — it reads the tokens. **Symptoms it fixes**: app-authored markup
+in a serif face, a gap around the whole shell, a second scrollbar, and
+app-authored text at 16px beside 14px Octans components.
+
+Skip it when Octans is one widget on someone else's page.
+
+## Design tokens
+
+Three tiers, described in full in `docs/color-system.md`:
+
+1. **Seeds** — `createTheme({ primary: '#…' })` generates everything below.
+2. **Primitives** — `--octans-primary-500`, `--octans-neutral-800`, the raw
+   ramps. **Components must never use these directly.**
+3. **Semantic** — `--octans-surface`, `--octans-text-subdued`,
+   `--octans-border`. This is the public, themeable API.
+
+**When styling anything, reach for a semantic token.** Every non-neutral role
+(primary, secondary, tertiary, info, success, warning, error) exposes the same
+four:
+
+| Token                     | Meaning                                       |
+| ------------------------- | --------------------------------------------- |
+| `--octans-<role>`         | the solid fill                                |
+| `--octans-text-on-<role>` | content sitting on that fill                  |
+| `--octans-<role>-surface` | soft tinted background                        |
+| `--octans-text-<role>`    | readable text in that hue, on a plain surface |
+
+Never hard-code a colour. A literal like `rgba(0, 0, 0, 0.54)` looks fine in
+light mode and is invisible in dark.
+
+Two rules that are easy to get wrong:
+
+- Use `--octans-text-<role>` for coloured **text**, and `--octans-<role>` only
+  as a **fill**. Fills are chosen to sit behind white text, so they are too
+  dark to read as text on a dark surface.
+- A colour must never be defined only inside a media query or a
+  `[data-octans-theme]` block, or it disappears in the other theme.
+
+Fills do **not** flip between light and dark — only surfaces, borders and the
+`text-<role>` tokens do. That is why `--octans-text-on-<role>` is defined once.
+
+## Theming
+
+```ts
+import { setTheme, persistTheme } from '@octans/ui'
+
+setTheme('dark') // 'light' | 'dark' | 'system'
+persistTheme() // remember the choice in localStorage
+```
+
+To rebrand from a seed colour — every ramp and semantic token follows, dark
+mode included:
+
+```ts
+import { createTheme, applyCustomTheme } from '@octans/ui'
+
+applyCustomTheme(createTheme({ name: 'Violet', primary: '#7b5cff' }))
+```
+
+`createTheme` measures each generated fill and picks a legible
+`text-on-<role>` automatically. If you set a fill **by hand**, set its label to
+match — white on a dark fill, near-black on a pale one.
+
+Or override tokens in CSS, which survives library updates better than
+rewriting semantic tokens one by one:
+
+```css
+:root {
+  --octans-primary-500: #7b5cff;
+  --octans-primary-600: #6a48f0;
+}
+```
+
+Three knobs that are not colours:
+
+```css
+:root {
+  /* The font for everything, components and app markup alike. */
+  --octans-font: 'Inter', system-ui, sans-serif;
+  --octans-font-mono: 'JetBrains Mono', monospace;
+
+  /* Every `Icon`'s vertical alignment. `0` is the default. Set it to
+     `-0.125em` for icons that sit inline with running text. */
+  --octans-icon-valign: -0.125em;
+}
+```
+
+`--octans-font` is the one to set. `--ui-font` still exists and still works —
+`--octans-font` resolves through it — but every token in the public API is
+spelled `--octans-*`, and that is the name the baseline reads.
+
+## Traps
+
+These are the mistakes that actually happen. Most produce black text on a dark
+surface, which passes review in light mode and fails in dark.
+
+**Form controls inherit neither `color` nor `font`.** A `<button>`, `<input>`,
+`<select>` or `<textarea>` starts from the user agent's `buttontext` and Arial,
+whatever the surrounding theme says. Any control you style needs both stated:
+
+```scss
+.MyButton {
+  font: inherit; // put it first, so a later font-size still wins
+  color: var(--octans-text);
+
+  // An authored `color` also opts out of the UA's dimming of a disabled
+  // control, so a control that can be disabled needs this too.
+  &:disabled {
+    color: var(--octans-text-disabled);
+  }
+}
+```
+
+**Teleported content inherits nothing.** Anything portalled to `<body>` — a
+popover, a modal, a sheet — lands outside the tree it was written in and picks
+up the host page's defaults. Put `UIElement` on the root of teleported content;
+that class carries the text colour, font and box-sizing baseline.
+
+**`color-scheme` covers what CSS cannot reach.** The native `<option>` list a
+`<select>` opens, scrollbars, and the internals of `input[type=date|time]` take
+their palette from `color-scheme`, which the token layer sets per theme. Don't
+fight it with per-control CSS.
+
+**Icons are SVG via Iconify**, drawn in `currentColor`, so they follow whatever
+`color` resolves to — which is why a black icon usually means a control that
+never got told its colour.
+
+**Reaching through a wrapper a component rendered itself.** Neither `vue-tsc`
+nor the build catches this: the CSS just silently stops applying. Some
+components put an element of their own around your slot content — `Tooltip`
+wraps its trigger in a `<span>`, `Popover` (and so `ActionList`, `DatePicker`,
+`TimePicker`, `ColorSelector`) wraps everything in a `<div>`. That element
+belongs to the LIBRARY's template, so Vue never stamps your component's
+scoped-style attribute on it, and any selector that reached through it stops
+matching:
+
+```scss
+/* in your component, <style scoped> */
+.Nav {
+  & > span:first-of-type {
+    margin-right: 16px;
+  } /* never matches once that span is Tooltip's */
+  &.sDisabled > span {
+    display: none;
+  } /* same — the control stays visible */
+}
+```
+
+Style an element you render yourself. Put `gap` on the flex container rather
+than margins on its children, and reach for `:deep()` only deliberately.
+
+## Global helpers
+
+Available as `$ui.*` in templates when the plugin is installed, or as named
+imports:
+
+```ts
+import { toast, confirmModal, promptModal, loader, saveBar } from '@octans/ui'
+
+toast.success('Saved')
+if (await confirmModal({ title: 'Delete this?' })) {
+  /* … */
+}
+loader.show()
+```
+
+## Internationalisation
+
+Components translate through `$t`. Register dictionaries at install time or
+later:
+
+```ts
+import { addTranslations, setTranslationLocale } from '@octans/ui'
+```
+
+Dates have two knobs, both set once at start-up and both global:
+
+```ts
+import { setLocale, setTimezone } from '@octans/ui'
+
+setLocale('fr') // formats, month names, and the day the week starts on
+setTimezone('America/Los_Angeles') // what "now" is, and what zone dates render in
+```
+
+`setTimezone` is for an app that must show ONE zone to everybody — an
+operations console pinned to head-office time — rather than each viewer's own
+clock, which is the default. It affects display only; it never reinterprets a
+stored value. `Formatter`, `Calendar` and `DatePicker` each take a `timezone`
+prop to override it for one instance.
+
+## Components
+
+Layout and shell: `AppFrame` `Page` `Layout` `Card` `Stack` `Divider`
+`FormLayout` `ScrollPane` `Splitter` `Sticky` `TextContainer` `FooterHelp`
+`PageActions`
+
+Navigation: `GlobalNav` `Navigation` `Tabs` `Link` `Pagination`
+`MaybeRouterLink` `UnstyledLink`
+
+Actions: `Button` `ButtonGroup` `ActionList`
+
+Forms: `TextField` `Select` `Checkbox` `RadioButton` `ChoiceList` `Choice`
+`ToggleSwitch` `SegmentedControl` `RangeSlider` `Rating` `OtpInput` `FileInput`
+`DatePicker` `TimePicker` `TimezonePicker` `Calendar` `ColorPicker`
+`ColorSelector` `GradientPicker` `Labelled` `InlineError` `NavField` `Filters`
+`PreventAutoComplete`
+
+Data display: `DataTable` `ResourceList` `List` `Badge` `Tag` `Thumbnail`
+`StatGroup` `CalendarHeatmap` `Formatter` `SyntaxHighlighter`
+
+Typography: `Heading` `TextStyle` `Caption` `LineClamper` `KeyboardKey`
+
+Feedback: `Banner` `Spinner` `ProgressBar` `LoadingBar` `LoaderOverlay`
+`SkeletonBodyText` `SkeletonCard` `SkeletonDisplayText` `SkeletonPage`
+`SaveBar` `ToastManager`
+
+Overlays: `Modal` `ModalSection` `Sheet` `Popover` `Tooltip`
+
+`Popover` was called `Popper` until 1.2. The old name still works as a
+deprecated alias — it wraps reka-ui's Popover primitives and never had
+anything to do with popper.js.
+
+Utilities: `Icon` `EventDelegator` `MaybeMountingPortal` `UiProvider`
+`SaveBarController`
+
+## Looking things up
+
+- Props and live examples: <https://octans.dev/storybook/> — every component
+  has its own page, and the Kitchen Sink shows one example of each.
+- Plain-markdown docs an agent can fetch: <https://octans.dev/llms.txt>
+- Token reference: `docs/color-system.md` in the repo.
+
+Storybook is a single-page app, so fetching a `?path=…` URL returns the shell
+rather than the page content. Use `llms.txt` when you need the text.

package/dist/components/Popper/index.d.ts

@@ -1,2 +0,0 @@
-export { default as Popper } from './Popper.vue';
-export * from './types';