fernwell 0.4.0 → 0.5.0

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/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

@@ -35,7 +35,7 @@
  * 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';
+import { type Placement } from './_position.js';
 export interface TooltipOptions {
     placement?: Placement;
     offset?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fernwell",
-  "version": "0.4.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": "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"
   },