fernwell 0.3.0 → 0.5.0

package/dist/table.d.cts

@@ -0,0 +1,40 @@
+/**
+ * Table — client-side column sorting and row selection for `.fw-table`.
+ *
+ *   <table class="fw-table" data-fw-table>
+ *     <thead><tr>
+ *       <th class="fw-table-select"><label class="fw-checkbox"><input type="checkbox" data-fw-select-all>…</label></th>
+ *       <th scope="col" aria-sort="none" data-fw-sort><button type="button" class="fw-table-sort">Client</button></th>
+ *     </tr></thead>
+ *     <tbody><tr>
+ *       <td class="fw-table-select"><label class="fw-checkbox"><input type="checkbox" data-fw-select-row>…</label></td>
+ *       <td data-fw-sort-value="1250">$1,250.00</td>
+ *     </tr></tbody>
+ *   </table>
+ *
+ * Clicking a `th[data-fw-sort]` cycles aria-sort (none → ascending → descending → …)
+ * and reorders the first <tbody>. `data-fw-sort-value` on a cell overrides its
+ * text for comparison (numbers, ISO dates). Rows without a cell in the sorted
+ * column (e.g. a colspan empty row) stay at the bottom.
+ *
+ * Row checkboxes toggle `.is-selected` / aria-selected on their row and keep the
+ * select-all checkbox in sync (checked / indeterminate).
+ *
+ * Events (bubbling, on the <table>): `fw:sort` { column, direction, th } and
+ * `fw:select` { rows, all }.
+ */
+export type SortDirection = 'ascending' | 'descending';
+export interface SortDetail {
+    column: number;
+    direction: SortDirection;
+    th: HTMLTableCellElement;
+}
+export interface SelectDetail {
+    rows: HTMLTableRowElement[];
+    all: boolean;
+}
+export declare function sort(table: HTMLTableElement, column: number, direction: SortDirection): void;
+export declare function getSelected(table: HTMLTableElement): HTMLTableRowElement[];
+export declare function setRowSelected(row: HTMLTableRowElement, on: boolean): void;
+export declare function selectAll(table: HTMLTableElement, on: boolean): void;
+export declare function init(root?: ParentNode): void;

package/dist/tabs.d.cts

@@ -0,0 +1,43 @@
+/**
+ * Tabs — a single-selection tablist that switches between panels.
+ *
+ *   <div class="fw-tablist" role="tablist" aria-label="Account settings" data-fw-tabs>
+ *     <button type="button" class="fw-tab" id="tab-profile" role="tab" aria-selected="true" aria-controls="panel-profile">Profile</button>
+ *     <button type="button" class="fw-tab" id="tab-billing" role="tab" aria-selected="false" aria-controls="panel-billing">Billing</button>
+ *   </div>
+ *   <div class="fw-tabpanel" id="panel-profile" role="tabpanel" aria-labelledby="tab-profile" tabindex="0">…</div>
+ *   <div class="fw-tabpanel" id="panel-billing" role="tabpanel" aria-labelledby="tab-billing" tabindex="0" hidden>…</div>
+ *
+ * Author `aria-selected="true"` on the tab that should start selected (the
+ * rest `"false"`); `init()` derives roving `tabIndex` (0 on the selected tab,
+ * -1 on the rest) and each panel's `hidden` from that. Falls back to the
+ * first non-disabled tab if none is marked selected. A tab may carry
+ * `aria-disabled="true"` to make it non-interactive — it is skipped by
+ * click, arrow-key, and Home/End navigation.
+ *
+ * `data-fw-tabs-activation="manual"` on the tablist switches from the
+ * default "automatic" activation (arrow keys move focus AND select) to
+ * "manual" (arrow keys only move focus; Space/Enter selects the focused
+ * tab) — use manual when selecting a tab is expensive (e.g. triggers a
+ * fetch).
+ *
+ * `aria-orientation="vertical"` on the tablist swaps the primary arrow keys
+ * from Left/Right to Up/Down, per WAI-ARIA APG. Left/Right invert under RTL.
+ *
+ * Events (bubbling, from the tablist): `fw:tabs-change` { tab, panel }.
+ */
+export type TabsActivation = 'automatic' | 'manual';
+export interface TabsOptions {
+    activation?: TabsActivation;
+}
+export interface TabsInstance {
+    activate(tab: HTMLElement, focus?: boolean): void;
+    destroy(): void;
+}
+export interface TabsChangeDetail {
+    tab: HTMLElement;
+    panel: HTMLElement;
+}
+export declare function tabs(tablist: HTMLElement, opts?: TabsOptions): TabsInstance;
+/** Wire every `[role="tablist"][data-fw-tabs]` under `root`. */
+export declare function init(root?: ParentNode): void;

package/dist/tabs.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Tabs — a single-selection tablist that switches between panels.
+ *
+ *   <div class="fw-tablist" role="tablist" aria-label="Account settings" data-fw-tabs>
+ *     <button type="button" class="fw-tab" id="tab-profile" role="tab" aria-selected="true" aria-controls="panel-profile">Profile</button>
+ *     <button type="button" class="fw-tab" id="tab-billing" role="tab" aria-selected="false" aria-controls="panel-billing">Billing</button>
+ *   </div>
+ *   <div class="fw-tabpanel" id="panel-profile" role="tabpanel" aria-labelledby="tab-profile" tabindex="0">…</div>
+ *   <div class="fw-tabpanel" id="panel-billing" role="tabpanel" aria-labelledby="tab-billing" tabindex="0" hidden>…</div>
+ *
+ * Author `aria-selected="true"` on the tab that should start selected (the
+ * rest `"false"`); `init()` derives roving `tabIndex` (0 on the selected tab,
+ * -1 on the rest) and each panel's `hidden` from that. Falls back to the
+ * first non-disabled tab if none is marked selected. A tab may carry
+ * `aria-disabled="true"` to make it non-interactive — it is skipped by
+ * click, arrow-key, and Home/End navigation.
+ *
+ * `data-fw-tabs-activation="manual"` on the tablist switches from the
+ * default "automatic" activation (arrow keys move focus AND select) to
+ * "manual" (arrow keys only move focus; Space/Enter selects the focused
+ * tab) — use manual when selecting a tab is expensive (e.g. triggers a
+ * fetch).
+ *
+ * `aria-orientation="vertical"` on the tablist swaps the primary arrow keys
+ * from Left/Right to Up/Down, per WAI-ARIA APG. Left/Right invert under RTL.
+ *
+ * Events (bubbling, from the tablist): `fw:tabs-change` { tab, panel }.
+ */
+export type TabsActivation = 'automatic' | 'manual';
+export interface TabsOptions {
+    activation?: TabsActivation;
+}
+export interface TabsInstance {
+    activate(tab: HTMLElement, focus?: boolean): void;
+    destroy(): void;
+}
+export interface TabsChangeDetail {
+    tab: HTMLElement;
+    panel: HTMLElement;
+}
+export declare function tabs(tablist: HTMLElement, opts?: TabsOptions): TabsInstance;
+/** Wire every `[role="tablist"][data-fw-tabs]` under `root`. */
+export declare function init(root?: ParentNode): void;

package/dist/theme.d.cts

@@ -0,0 +1,12 @@
+export type Theme = 'light' | 'dark';
+/** The theme currently applied to <html>, or the system preference if none is set. */
+export declare function get(): Theme;
+/** Apply a theme, persist it, and update every toggle button on the page. */
+export declare function set(theme: Theme, { persist }?: {
+    persist?: boolean;
+}): void;
+export declare function toggle(): Theme;
+/** Apply the stored / system theme and wire every `[data-fw-theme-toggle]` under `root`. */
+export declare function init(root?: ParentNode): void;
+export { setTokens, resetTokens, getToken } from './tokens.cjs';
+export type { TokenOverrides, TokenThemeOverrides, SetTokensOptions } from './tokens.cjs';

package/dist/theme.d.ts

@@ -1,16 +1,3 @@
-/**
- * Theme — toggles `data-theme="dark"` on <html>, remembers the choice, and
- * falls back to the OS preference. Also carries the runtime token API
- * (`setTokens` / `resetTokens` / `getToken`) for retheming Fernwell's colour
- * tokens on the fly — per-tenant branding, a user-picked accent, a live
- * preview — without touching a stylesheet.
- *
- *   <button class="fw-btn fw-btn-ghost" data-fw-theme-toggle
- *           data-fw-theme-label-dark="☀️ Light" data-fw-theme-label-light="🌙 Dark">🌙 Dark</button>
- *
- * To avoid a flash of the wrong theme on load, inline this before your CSS:
- *   <script>document.documentElement.dataset.theme=localStorage.getItem('fw-theme')||(matchMedia('(prefers-color-scheme: dark)').matches?'dark':'light')</script>
- */
 export type Theme = 'light' | 'dark';
 /** The theme currently applied to <html>, or the system preference if none is set. */
 export declare function get(): Theme;
@@ -21,32 +8,5 @@ export declare function set(theme: Theme, { persist }?: {
 export declare function toggle(): Theme;
 /** Apply the stored / system theme and wire every `[data-fw-theme-toggle]` under `root`. */
 export declare function init(root?: ParentNode): void;
-/** Token name → CSS value. Bare names (`primary`) and full names (`--fw-primary`) both work. */
-export type TokenOverrides = Record<string, string>;
-/** Split form: set different values per theme instead of both at once. */
-export interface TokenThemeOverrides {
-    light?: TokenOverrides;
-    dark?: TokenOverrides;
-}
-/**
- * Override Fernwell design tokens at runtime — every derived token (hovers,
- * tints, focus ring, glows) follows automatically, in both themes:
- *
- *   theme.setTokens({ primary: '#2266ff' });
- *
- * Pass `{ light, dark }` to set different values per theme, and `scope` to
- * theme a subtree instead of the whole page:
- *
- *   theme.setTokens({ light: { primary: '#2266ff' }, dark: { primary: '#5c9dff' } });
- *   theme.setTokens({ secondary: '#a33' }, { scope: '.tenant-acme' });
- *
- * Calls accumulate (merge into whatever overrides are already set for that
- * scope) — call `resetTokens()` to clear them.
- */
-export declare function setTokens(tokens: TokenOverrides | TokenThemeOverrides, opts?: {
-    scope?: string;
-}): void;
-/** Clear runtime token overrides — for one `scope`, or every scope if omitted. */
-export declare function resetTokens(scope?: string): void;
-/** The live, resolved value of a token (e.g. `getToken('primary')` → `'#ffc145'`), including runtime overrides. */
-export declare function getToken(name: string, el?: Element): string;
+export { setTokens, resetTokens, getToken } from './tokens.js';
+export type { TokenOverrides, TokenThemeOverrides, SetTokensOptions } from './tokens.js';

package/dist/toast.d.cts

@@ -0,0 +1,14 @@
+/**
+ * Toast — a single, reused, bottom-right notice.
+ *
+ *   toast.show('Invoice sent');
+ *   toast.show('That card was declined', { variant: 'error', duration: 6000 });
+ */
+export type ToastVariant = 'success' | 'error' | 'info' | 'pending';
+export interface ToastOptions {
+    variant?: ToastVariant;
+    /** ms before it hides; 0 keeps it until `hide()` or the next `show()`. */
+    duration?: number;
+}
+export declare function show(message: string, { variant, duration }?: ToastOptions): HTMLElement;
+export declare function hide(): void;

package/dist/tokens.d.cts

@@ -0,0 +1,105 @@
+/**
+ * Tokens — override any `--fw-*` design token from JS, for the whole app or
+ * for one page or subtree, in both themes or per-theme. Every derived token
+ * (hovers, tints, focus ring, glows) follows the seed it is built from.
+ *
+ *   tokens.setTokens({ primary: '#2266ff' });                                  // both themes
+ *   tokens.setTokens({ light: { primary: '#2266ff' }, dark: { primary: '#5c9dff' } });
+ *   tokens.setTokens({ secondary: '#a33' }, { scope: '.tenant-acme' });       // one subtree
+ *   const undo = tokens.setTokens({ primary: '#a33' });  undo();               // route-scoped
+ *   tokens.setTokens({ primary: '#2266ff' }, { persist: true });               // app-wide
+ *
+ * Overrides render into one `<style data-fw-tokens>` appended to `<head>`:
+ * being unlayered and last, it wins over Fernwell's own `@layer fw-tokens`
+ * *and* any earlier static override in the consumer's stylesheet.
+ *
+ * Persistence — `persist: true` saves the scope to localStorage so every page
+ * of the app (and every reload) gets it. Without it an override lives only
+ * for the current page load, which is what "this page only" means in a
+ * multi-page app. Persisted overrides sit *below* page-level ones, so a page
+ * can still tweak an app-wide value. To apply them before first paint, inline
+ * this ahead of your CSS (next to the theme snippet — see theme.ts):
+ *   <script>try{var c=localStorage.getItem('fw-tokens-css');if(c){var s=document.createElement('style');s.setAttribute('data-fw-tokens','');s.textContent=c;document.head.appendChild(s)}}catch(e){}</script>
+ *
+ * Declarative hooks (wired by `init()`):
+ *
+ *   <script type="application/json" data-fw-theme-tokens>{"primary":"#2266ff"}</script>
+ *   <script type="application/json" data-fw-theme-tokens data-fw-scope=".tenant-acme" data-fw-persist>{…}</script>
+ *   <section data-fw-theme-scope='{"secondary":"#a33"}'>…</section>
+ *
+ * The `<script>` form takes the same shapes as `setTokens()` (flat map or
+ * `{ light, dark }`); `data-fw-scope` and `data-fw-persist` are optional. The
+ * element form themes that element's subtree only, and is never persisted.
+ * Both are undone on the next `init()` after their element is removed from
+ * the page; call the function `setTokens()` returns, or `resetTokens(scope)`,
+ * to undo one sooner.
+ *
+ * Events (on `document`): `fw:tokenschange` { scope } — `scope` is absent
+ * when every scope changed (a reset or a restore).
+ */
+import { type TokenName } from './_tokenData.cjs';
+/** A token to override: a known name (autocompletes), a bare custom name, or a full `--fw-*` / `--custom` property. */
+export type TokenKey = TokenName | (string & {});
+/** Token name → CSS value. Bare names (`primary`) and full names (`--fw-primary`) both work. */
+export type TokenOverrides = Partial<Record<TokenName, string>> & Record<string, string>;
+/** Split form: set different values per theme instead of both at once. */
+export interface TokenThemeOverrides {
+    light?: TokenOverrides;
+    dark?: TokenOverrides;
+}
+export interface SetTokensOptions {
+    /** A CSS selector to theme a subtree instead of the whole page. Default `:root`. */
+    scope?: string;
+    /** Save this scope to localStorage so it applies on every page and reload. Default `false`. */
+    persist?: boolean;
+}
+export interface TokensChangeDetail {
+    scope?: string;
+}
+/**
+ * Override Fernwell design tokens at runtime — every derived token (hovers,
+ * tints, focus ring, glows) follows automatically, in both themes:
+ *
+ *   tokens.setTokens({ primary: '#2266ff' });
+ *
+ * Pass `{ light, dark }` to set different values per theme, `scope` to theme
+ * a subtree instead of the whole page, and `persist` to keep the scope for
+ * every page of the app:
+ *
+ *   tokens.setTokens({ light: { primary: '#2266ff' }, dark: { primary: '#5c9dff' } });
+ *   tokens.setTokens({ secondary: '#a33' }, { scope: '.tenant-acme' });
+ *   tokens.setTokens({ primary: '#2266ff' }, { persist: true });
+ *
+ * Calls accumulate (merge into whatever overrides are already set for that
+ * scope) — call `resetTokens()` to clear them. The returned function undoes
+ * just this call, e.g. when a route unmounts; call it in reverse order if
+ * several calls touched the same token.
+ */
+export declare function setTokens(tokens: TokenOverrides | TokenThemeOverrides, opts?: SetTokensOptions): () => void;
+/**
+ * Clear runtime token overrides — for one `scope`, or every scope if
+ * omitted. Persisted overrides are removed from localStorage too.
+ */
+export declare function resetTokens(scope?: string): void;
+/**
+ * Reload persisted overrides from localStorage, replacing whatever persisted
+ * scopes are in memory. `init()` does this once for you; call it yourself
+ * only if something else rewrote storage.
+ */
+export declare function restoreTokens(): void;
+/** The live, resolved value of a token (e.g. `getToken('primary')` → `'#ffc145'`), including runtime overrides. */
+export declare function getToken(name: TokenKey, el?: Element): string;
+/**
+ * Restore persisted overrides (once), then apply every declarative hook
+ * under `root` — `<script type="application/json" data-fw-theme-tokens>` and
+ * `data-fw-theme-scope="{…}"`. Safe to call again after injecting markup.
+ *
+ * Bound elements are marked `data-fw-tokens-bound`, not the shared `fwBound`
+ * the other enhancers use — a themed element is often also a table, modal or
+ * menu root, and must still be picked up by that component's own `init()`.
+ *
+ * A hook that isn't persisted is undone on the next `init()` after its element
+ * has been removed from the page, so route-scoped markup doesn't accumulate
+ * rules. (`data-fw-persist` hooks are app-wide and stay until `resetTokens()`.)
+ */
+export declare function init(root?: ParentNode): void;

package/dist/tokens.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Tokens — override any `--fw-*` design token from JS, for the whole app or
+ * for one page or subtree, in both themes or per-theme. Every derived token
+ * (hovers, tints, focus ring, glows) follows the seed it is built from.
+ *
+ *   tokens.setTokens({ primary: '#2266ff' });                                  // both themes
+ *   tokens.setTokens({ light: { primary: '#2266ff' }, dark: { primary: '#5c9dff' } });
+ *   tokens.setTokens({ secondary: '#a33' }, { scope: '.tenant-acme' });       // one subtree
+ *   const undo = tokens.setTokens({ primary: '#a33' });  undo();               // route-scoped
+ *   tokens.setTokens({ primary: '#2266ff' }, { persist: true });               // app-wide
+ *
+ * Overrides render into one `<style data-fw-tokens>` appended to `<head>`:
+ * being unlayered and last, it wins over Fernwell's own `@layer fw-tokens`
+ * *and* any earlier static override in the consumer's stylesheet.
+ *
+ * Persistence — `persist: true` saves the scope to localStorage so every page
+ * of the app (and every reload) gets it. Without it an override lives only
+ * for the current page load, which is what "this page only" means in a
+ * multi-page app. Persisted overrides sit *below* page-level ones, so a page
+ * can still tweak an app-wide value. To apply them before first paint, inline
+ * this ahead of your CSS (next to the theme snippet — see theme.ts):
+ *   <script>try{var c=localStorage.getItem('fw-tokens-css');if(c){var s=document.createElement('style');s.setAttribute('data-fw-tokens','');s.textContent=c;document.head.appendChild(s)}}catch(e){}</script>
+ *
+ * Declarative hooks (wired by `init()`):
+ *
+ *   <script type="application/json" data-fw-theme-tokens>{"primary":"#2266ff"}</script>
+ *   <script type="application/json" data-fw-theme-tokens data-fw-scope=".tenant-acme" data-fw-persist>{…}</script>
+ *   <section data-fw-theme-scope='{"secondary":"#a33"}'>…</section>
+ *
+ * The `<script>` form takes the same shapes as `setTokens()` (flat map or
+ * `{ light, dark }`); `data-fw-scope` and `data-fw-persist` are optional. The
+ * element form themes that element's subtree only, and is never persisted.
+ * Both are undone on the next `init()` after their element is removed from
+ * the page; call the function `setTokens()` returns, or `resetTokens(scope)`,
+ * to undo one sooner.
+ *
+ * Events (on `document`): `fw:tokenschange` { scope } — `scope` is absent
+ * when every scope changed (a reset or a restore).
+ */
+import { type TokenName } from './_tokenData.js';
+/** A token to override: a known name (autocompletes), a bare custom name, or a full `--fw-*` / `--custom` property. */
+export type TokenKey = TokenName | (string & {});
+/** Token name → CSS value. Bare names (`primary`) and full names (`--fw-primary`) both work. */
+export type TokenOverrides = Partial<Record<TokenName, string>> & Record<string, string>;
+/** Split form: set different values per theme instead of both at once. */
+export interface TokenThemeOverrides {
+    light?: TokenOverrides;
+    dark?: TokenOverrides;
+}
+export interface SetTokensOptions {
+    /** A CSS selector to theme a subtree instead of the whole page. Default `:root`. */
+    scope?: string;
+    /** Save this scope to localStorage so it applies on every page and reload. Default `false`. */
+    persist?: boolean;
+}
+export interface TokensChangeDetail {
+    scope?: string;
+}
+/**
+ * Override Fernwell design tokens at runtime — every derived token (hovers,
+ * tints, focus ring, glows) follows automatically, in both themes:
+ *
+ *   tokens.setTokens({ primary: '#2266ff' });
+ *
+ * Pass `{ light, dark }` to set different values per theme, `scope` to theme
+ * a subtree instead of the whole page, and `persist` to keep the scope for
+ * every page of the app:
+ *
+ *   tokens.setTokens({ light: { primary: '#2266ff' }, dark: { primary: '#5c9dff' } });
+ *   tokens.setTokens({ secondary: '#a33' }, { scope: '.tenant-acme' });
+ *   tokens.setTokens({ primary: '#2266ff' }, { persist: true });
+ *
+ * Calls accumulate (merge into whatever overrides are already set for that
+ * scope) — call `resetTokens()` to clear them. The returned function undoes
+ * just this call, e.g. when a route unmounts; call it in reverse order if
+ * several calls touched the same token.
+ */
+export declare function setTokens(tokens: TokenOverrides | TokenThemeOverrides, opts?: SetTokensOptions): () => void;
+/**
+ * Clear runtime token overrides — for one `scope`, or every scope if
+ * omitted. Persisted overrides are removed from localStorage too.
+ */
+export declare function resetTokens(scope?: string): void;
+/**
+ * Reload persisted overrides from localStorage, replacing whatever persisted
+ * scopes are in memory. `init()` does this once for you; call it yourself
+ * only if something else rewrote storage.
+ */
+export declare function restoreTokens(): void;
+/** The live, resolved value of a token (e.g. `getToken('primary')` → `'#ffc145'`), including runtime overrides. */
+export declare function getToken(name: TokenKey, el?: Element): string;
+/**
+ * Restore persisted overrides (once), then apply every declarative hook
+ * under `root` — `<script type="application/json" data-fw-theme-tokens>` and
+ * `data-fw-theme-scope="{…}"`. Safe to call again after injecting markup.
+ *
+ * Bound elements are marked `data-fw-tokens-bound`, not the shared `fwBound`
+ * the other enhancers use — a themed element is often also a table, modal or
+ * menu root, and must still be picked up by that component's own `init()`.
+ *
+ * A hook that isn't persisted is undone on the next `init()` after its element
+ * has been removed from the page, so route-scoped markup doesn't accumulate
+ * rules. (`data-fw-persist` hooks are app-wide and stay until `resetTokens()`.)
+ */
+export declare function init(root?: ParentNode): void;

package/dist/tokens.json

@@ -130,6 +130,18 @@
     "focus-ring": {
       "value": "0 0 0 4px color-mix(in srgb, {primary} 25%, transparent)",
       "comment": "derived: box-shadow focus ring, primary wash"
+    },
+    "scrollbar-thumb": {
+      "value": "{text-soft}",
+      "comment": "scrollbar thumb — reuses secondary-text so it recedes against content"
+    },
+    "scrollbar-thumb-hover": {
+      "value": "color-mix(in srgb, {text-soft}, {text} 15%)",
+      "comment": "derived: darkens toward full-strength text on hover, same recipe as secondary-hover"
+    },
+    "scrollbar-track": {
+      "value": "transparent",
+      "comment": "default track; Table overrides to bg-dim so its scrollbar reads as clearly present"
     }
   },
   "font": {

package/dist/tooltip.d.cts

@@ -0,0 +1,51 @@
+/**
+ * Tooltip — a short hover/focus annotation, anchored to its trigger.
+ *
+ *   <button type="button" class="fw-icon-btn" title="Copy to clipboard" data-fw-tooltip>
+ *     <span data-fw-icon="copy" aria-hidden="true"></span>
+ *   </button>
+ *
+ * The `title` attribute is the content source — it's moved into
+ * `dataset.fwTooltipText` and removed on init (same detach-and-mirror trick
+ * combobox.ts uses for the `list` attribute), which gives a real no-JS
+ * fallback (the native OS tooltip) and stops the two tooltips firing at once.
+ *
+ * Optional trigger attributes: `data-fw-tooltip-placement` (default "top";
+ * also accepts "bottom" | "left" | "right", or a corner variant —
+ * "top-left" | "top-right" | "bottom-left" | "bottom-right" — that leans the
+ * bubble toward that corner instead of centering it, for triggers near a
+ * layout edge), `data-fw-tooltip-offset` (px, default 6),
+ * `data-fw-tooltip-delay` (ms, default 400).
+ *
+ * The bubble is centered on the trigger by default so the arrow (drawn at
+ * `computePosition`'s returned `arrowOffset`) always points at the trigger's
+ * midpoint — including when a corner placement or a viewport-edge clamp
+ * shifts the bubble off-center.
+ *
+ * Only one tooltip bubble exists for the whole page (a lazily-created
+ * singleton, same pattern as toast.ts) — a second trigger's hover pre-empts
+ * the first. Acceptable for a short annotation; not meant for concurrent
+ * multi-tooltip UIs.
+ *
+ * WCAG 2.1 SC 1.4.13 requires hover/focus-revealed content to be dismissible,
+ * *hoverable* (the pointer can move onto it without it disappearing) and
+ * persistent. `pointer-events: none` on the bubble would fail "hoverable"
+ * outright — the bubble couldn't receive a hover at all — so this
+ * deliberately does NOT set it while open. Instead the bubble gets its own
+ * mouseenter/mouseleave, and a short cancelable hide-grace timer covers the
+ * gap while the pointer travels from trigger to bubble.
+ */
+import { type Placement } from './_position.cjs';
+export interface TooltipOptions {
+    placement?: Placement;
+    offset?: number;
+    delay?: number;
+}
+export interface TooltipInstance {
+    show(): void;
+    hide(): void;
+    destroy(): void;
+}
+export declare function tooltip(trigger: HTMLElement, opts?: TooltipOptions): TooltipInstance;
+/** Wire every `[data-fw-tooltip]` under `root`. */
+export declare function init(root?: ParentNode): void;

package/dist/tooltip.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Tooltip — a short hover/focus annotation, anchored to its trigger.
+ *
+ *   <button type="button" class="fw-icon-btn" title="Copy to clipboard" data-fw-tooltip>
+ *     <span data-fw-icon="copy" aria-hidden="true"></span>
+ *   </button>
+ *
+ * The `title` attribute is the content source — it's moved into
+ * `dataset.fwTooltipText` and removed on init (same detach-and-mirror trick
+ * combobox.ts uses for the `list` attribute), which gives a real no-JS
+ * fallback (the native OS tooltip) and stops the two tooltips firing at once.
+ *
+ * Optional trigger attributes: `data-fw-tooltip-placement` (default "top";
+ * also accepts "bottom" | "left" | "right", or a corner variant —
+ * "top-left" | "top-right" | "bottom-left" | "bottom-right" — that leans the
+ * bubble toward that corner instead of centering it, for triggers near a
+ * layout edge), `data-fw-tooltip-offset` (px, default 6),
+ * `data-fw-tooltip-delay` (ms, default 400).
+ *
+ * The bubble is centered on the trigger by default so the arrow (drawn at
+ * `computePosition`'s returned `arrowOffset`) always points at the trigger's
+ * midpoint — including when a corner placement or a viewport-edge clamp
+ * shifts the bubble off-center.
+ *
+ * Only one tooltip bubble exists for the whole page (a lazily-created
+ * singleton, same pattern as toast.ts) — a second trigger's hover pre-empts
+ * the first. Acceptable for a short annotation; not meant for concurrent
+ * multi-tooltip UIs.
+ *
+ * WCAG 2.1 SC 1.4.13 requires hover/focus-revealed content to be dismissible,
+ * *hoverable* (the pointer can move onto it without it disappearing) and
+ * persistent. `pointer-events: none` on the bubble would fail "hoverable"
+ * outright — the bubble couldn't receive a hover at all — so this
+ * deliberately does NOT set it while open. Instead the bubble gets its own
+ * mouseenter/mouseleave, and a short cancelable hide-grace timer covers the
+ * gap while the pointer travels from trigger to bubble.
+ */
+import { type Placement } from './_position.js';
+export interface TooltipOptions {
+    placement?: Placement;
+    offset?: number;
+    delay?: number;
+}
+export interface TooltipInstance {
+    show(): void;
+    hide(): void;
+    destroy(): void;
+}
+export declare function tooltip(trigger: HTMLElement, opts?: TooltipOptions): TooltipInstance;
+/** Wire every `[data-fw-tooltip]` under `root`. */
+export declare function init(root?: ParentNode): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fernwell",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Fernwell — the HunnyDo design system. Design tokens, CSS components, and small vanilla JS enhancers that work in any web app, with or without a build step.",
   "type": "module",
   "license": "MIT",
@@ -33,23 +33,45 @@
   "jsdelivr": "./dist/fernwell.iife.js",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/fernwell.esm.js",
-      "require": "./dist/fernwell.cjs"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/fernwell.esm.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/fernwell.cjs"
+      }
+    },
+    "./css": {
+      "types": "./dist/css.d.ts",
+      "default": "./dist/fernwell.css"
+    },
+    "./css/min": {
+      "types": "./dist/css.d.ts",
+      "default": "./dist/fernwell.min.css"
+    },
+    "./tokens.css": {
+      "types": "./dist/css.d.ts",
+      "default": "./dist/fernwell.tokens.css"
     },
-    "./css": "./dist/fernwell.css",
-    "./css/min": "./dist/fernwell.min.css",
-    "./tokens.css": "./dist/fernwell.tokens.css",
     "./tokens.json": "./dist/tokens.json",
     "./package.json": "./package.json"
   },
+  "typesVersions": {
+    "*": {
+      "css": ["./dist/css.d.ts"],
+      "css/min": ["./dist/css.d.ts"],
+      "tokens.css": ["./dist/css.d.ts"]
+    }
+  },
   "scripts": {
-    "dev": "npm run build && npm run docs",
+    "dev": "node scripts/dev.mjs",
     "tokens": "node scripts/gen-tokens.mjs",
     "lint": "node scripts/lint-tokens.mjs",
-    "test": "vitest run",
+    "test": "vitest run && npm run test:types",
     "test:watch": "vitest",
-    "build": "npm run tokens && npm run lint && node scripts/build.mjs && tsc -p tsconfig.build.json",
+    "test:types": "npm run build && vitest run --config __tests__/config/vitest.types.config.ts",
+    "build": "npm run tokens && npm run lint && node scripts/build.mjs && tsc -p tsconfig.build.json && node scripts/cjs-types.mjs",
     "docs": "serve docs/",
     "prepublishOnly": "npm run build"
   },