@ixfx/components 0.16.2 → 0.16.4

package/docs-user/infra-theming.md

@@ -0,0 +1,510 @@
+# CSS Variables Specification
+
+This document defines the semantic CSS variables for theming the application. Components should use these variables rather than hardcoded values to ensure consistent theming and easy customisation.
+
+All colour values use [OKLCH](https://oklch.com/) for consistent perceptual brightness across hues.
+
+---
+
+## Surfaces
+
+Surfaces represent UI depth. Higher numbers are more **elevated** — visually lighter in dark mode, following the standard elevation model (Material Design 3, Fluent UI 2).
+
+**Depth scale:**
+
+| Variable | Dark Theme | Light Theme | Semantic |
+|---|---|---|---|
+| `--surface-0` | `oklch(5% 0.02 240)` | `oklch(100% 0 0)` | True dark base (reserved, rarely used) |
+| `--surface-1` | `oklch(8% 0.02 240)` | `oklch(99% 0.01 240)` | Near-black base (reserved, rarely used) |
+| `--surface-2` | `oklch(12% 0.02 240)` | `oklch(95% 0.01 240)` | Deep wells, inset areas |
+| `--surface-3` | `oklch(15% 0.02 240)` | `oklch(98% 0.01 240)` | **Default UI plane** — panels, cards |
+| `--surface-4` | `oklch(22% 0.02 240)` | `oklch(92% 0.01 240)` | Interactive controls — buttons, inputs |
+| `--surface-5` | `oklch(28% 0.02 240)` | `oklch(85% 0.01 240)` | Hover states; **popup/menu backgrounds** |
+| `--surface-6` | `oklch(35% 0.02 240)` | `oklch(78% 0.01 240)` | Active/pressed states; hover within popups |
+
+### Text on surfaces
+
+Each surface level has a paired text colour for legible contrast.
+
+| Variable | Dark Theme | Light Theme | Usage |
+|---|---|---|---|
+| `--surface-2-text` | `#fff` | `oklch(15% 0.02 240)` | Text on `--surface-2` |
+| `--surface-3-text` | `oklch(75% 0.02 240)` | `oklch(25% 0.02 240)` | Text on `--surface-3` |
+| `--surface-4-text` | `#fff` | `oklch(15% 0.02 240)` | Text on `--surface-4` |
+| `--surface-5-text` | `#fff` | `oklch(10% 0.02 240)` | Text on `--surface-5` |
+| `--surface-6-text` | `#fff` | `oklch(10% 0.02 240)` | Text on `--surface-6` |
+| `--surface-muted-text` | `oklch(55% 0.02 240)` | `oklch(45% 0.02 240)` | Secondary/hint text (not depth-specific) |
+
+### Depth model guidance
+
+```
+surface-3  ← default panels (app chrome background)
+surface-4  ← buttons, inputs (raised above panel)
+surface-5  ← hover states; menus, popovers (floating above panel)
+surface-6  ← active/pressed states; hover within floating layers
+```
+
+A hover effect on an element at depth N should use depth N+1:
+```css
+.btn { background: var(--surface-4); }
+.btn:hover { background: var(--surface-5); }
+.menu-item:hover { background: var(--surface-6); }  /* menu is already at surface-5 */
+```
+
+---
+
+## Content
+
+Separate from surface (UI chrome), for user-generated content areas such as canvases, editors, or preview panes.
+
+| Variable | Dark Theme | Light Theme | Usage |
+|---|---|---|---|
+| `--content` | `oklch(10% 0.01 240)` | `oklch(100% 0 0)` | User content area background |
+| `--content-text` | `#fff` | `oklch(10% 0.02 240)` | Text on content backgrounds |
+
+---
+
+## Accent
+
+Accent colours for primary actions, active states, and focus indicators.
+
+| Variable | Dark Theme | Light Theme | Usage |
+|---|---|---|---|
+| `--accent` | `oklch(60% 0.15 140)` | `oklch(45% 0.15 140)` | Primary accent (active buttons, selected items) |
+| `--accent-text` | `#fff` | `#fff` | Text on accent-coloured backgrounds |
+
+There are also accent colours based on surface level, for example `--surface-2-accent` (used in `xy-pad.ts` as a convenience alias; not defined in `src/style.css`).
+---
+
+## Feedback / Status
+
+| Variable | Dark Theme | Light Theme | Usage |
+|---|---|---|---|
+| `--error` | `oklch(60% 0.15 20)` | `oklch(55% 0.15 20)` | Error states, destructive actions |
+| `--error-text` | `#fff` | `#fff` | Text on error backgrounds |
+
+---
+
+## Typography
+
+| Variable | Value | Usage |
+|---|---|---|
+| `--font-family` | `system-ui, sans-serif` | Primary UI font |
+| `--font-mono` | `ui-monospace, monospace` | Monospace for values, code |
+| `--font-weight` | `400` | Normal weight |
+| `--font-weight-bold` | `600` | Bold weight |
+| `--text-xs` | `10px` | Tiny — icons, badges |
+| `--text-s` | `11px` | Small — labels, captions |
+| `--text-m` | `12px` | Medium — body, inputs |
+| `--text-l` | `13px` | Large — titles |
+| `--text-xl` | `16px` | Extra large — headings |
+| `--text-2xl` | `20px` | Page headings |
+
+---
+
+## Spacing
+
+| Variable | Value | Usage |
+|---|---|---|
+| `--space-xs` | `3px` | Tight spacing, icon padding |
+| `--space-s` | `4px` | Default internal spacing |
+| `--space-m` | `8px` | Standard padding/margins |
+| `--space-l` | `12px` | Section spacing |
+| `--space-xl` | `16px` | Large gaps |
+| `--space-2xl` | `20px` | Section separation |
+
+---
+
+## Borders
+
+| Variable | Value | Usage |
+|---|---|---|
+| `--border` | `1px solid oklch(25% 0.02 240)` (dark) | Standard border on `--surface-2` through `--surface-4` |
+| `--border-subtle` | `1px solid oklch(18% 0.02 240)` (dark) | Subtle boundary |
+| `--radius-s` | `3px` | Small — inputs, compact buttons |
+| `--radius-m` | `4px` | Medium — buttons, cards |
+| `--radius-l` | `6px` | Large — menus, popovers |
+| `--radius-xl` | `8px` | Extra large — dialogs |
+
+**Note:** For borders on elevated surfaces (`--surface-5` and above), use `1px solid var(--surface-6)` rather than `var(--border)` to maintain visible contrast. This is handled automatically by the shared `popupSurfaceStyles` in `src/styles/popup.ts`.
+
+---
+
+## Shadows
+
+| Variable | Dark Theme | Light Theme | Usage |
+|---|---|---|---|
+| `--shadow-m` | `0 4px 12px rgba(0,0,0,0.3)` | `0 2px 8px rgba(0,0,0,0.1)` | Dropdowns, popovers |
+| `--shadow-l` | `0 4px 24px rgba(0,0,0,0.5)` | `0 4px 16px rgba(0,0,0,0.15)` | Dialogs, large floating panels |
+
+---
+
+## Interaction
+
+| Variable | Value | Usage |
+|---|---|---|
+| `--disabled-opacity` | `0.5` | Opacity for disabled elements |
+| `--transition` | `0.15s ease-out` | Default transition timing |
+
+---
+
+## Transparent Pattern
+
+| Variable | Dark Theme | Light Theme |
+|---|---|---|
+| `--transparent-bg` | `oklch(30% 0.02 240)` | `oklch(85% 0.01 240)` |
+
+---
+
+## Item States
+
+CSS variables for styling "items" — logical content elements like file list items, tree items, or crumb navigation items. Items are distinct from UI controls like buttons.
+
+### Design Approach
+- **Border-based states**: Uses border styling (colour, thickness, style) since background may not be visible for thumbnails.
+- **Independent of surface depth**: States work regardless of which surface level the item sits on.
+- **Combinable**: States can coexist (e.g., enabled + selected + tickled).
+
+### States
+
+| Variable | Dark Theme | Light Theme | Border Style |
+|---|---|---|---|
+| `--item-border` | `surface-5` | `surface-4` | 1px solid |
+| `--item-border-tickled` | accent 40% | accent 50% | 1px solid |
+| `--item-border-selected` | accent | accent | 1px dashed |
+| `--item-border-active` | accent | accent | 2px solid |
+| `--item-border-dragged` | accent 80% | accent | 2px dotted |
+| `--item-border-disabled` | `surface-4` | `surface-3` | 1px solid |
+
+### Background/Text Variants
+
+| Variable | Dark Theme | Light Theme | Usage |
+|---|---|---|---|
+| `--item-bg` | transparent | transparent | Default item background (no state) |
+| `--item-bg-tickled` | `surface-5` | `surface-4` | Hover/pointer state |
+| `--item-bg-selected` | accent | accent | Selected item background |
+| `--item-bg-selected-tickled` | accent 80% mixed with black | accent 80% mixed with black | Selected + hovered simultaneously |
+| `--item-text-tickled` | `surface-5-text` | `surface-4-text` | Text on tickled items |
+| `--item-text-selected` | accent-text | accent-text | Text on selected items |
+
+### Layout Variables
+
+| Variable | Value | Usage |
+|---|---|---|
+| `--item-padding` | `var(--space-s) var(--space-m)` | Padding applied to `.item` elements by `tickledItemStyles` |
+| `--item-border-radius` | `var(--radius-m)` | Border radius applied to `.item` elements |
+| `--item-icon-spacing` | `var(--space-s)` | Gap between icon and label text inside an item |
+
+These are layout defaults — override per-component if the geometry needs to differ (e.g. a compact list vs a card grid).
+
+### Item Label Styling
+
+Variables for styling item label text (e.g., font style, text decoration). These allow overriding label appearance per state without CSS selector cascading issues in shadow DOM.
+
+| Variable | Dark Theme | Light Theme | Usage |
+|---|---|---|---|
+| `--item-label-font-style-default` | `normal` | `normal` | Default font style |
+| `--item-label-font-style-selected` | `italic` | `italic` | Font style when selected |
+| `--item-label-font-style-tickled` | `normal` | `normal` | Font style when tickled/hovered |
+| `--item-label-text-decoration-default` | `none` | `none` | Default text decoration |
+| `--item-label-text-decoration-selected` | `none` | `none` | Text decoration when selected |
+| `--item-label-text-decoration-tickled` | `underline` | `underline` | Text decoration when tickled/hovered |
+| `--item-label-text-underline-offset-default` | `auto` | `auto` | Default underline offset |
+| `--item-label-text-underline-offset-tickled` | `3px` | `3px` | Underline offset when tickled/hovered |
+
+### Usage
+
+States are applied via CSS classes. Border variables use `color-mix()` for accent variations.
+
+```css
+/* Base item */
+.list-item {
+  background: var(--item-bg);
+  border: var(--item-border);
+  padding: var(--item-padding);
+  border-radius: var(--item-border-radius);
+}
+
+/* Hover/tickled state */
+.list-item.tickled {
+  border: var(--item-border-tickled);
+  background: var(--item-bg-tickled);
+  color: var(--item-text-tickled);
+}
+
+/* Selected state */
+.list-item.selected {
+  border: var(--item-border-selected);
+  background: var(--item-bg-selected);
+  color: var(--item-text-selected);
+}
+
+/* Selected + tickled simultaneously */
+.list-item.selected.tickled {
+  background: var(--item-bg-selected-tickled);
+}
+
+/* Active/pressed state */
+.list-item.active {
+  border: var(--item-border-active);
+}
+
+/* Dragged state */
+.list-item.dragged {
+  border: var(--item-border-dragged);
+}
+
+/* Disabled state */
+.list-item.disabled {
+  border: var(--item-border-disabled);
+  opacity: 0.5;
+}
+```
+
+In practice, most components should import `tickledItemStyles` from `src/interaction/index.js` rather than writing these rules manually — `tickledItemStyles` applies all of the above to `.item` class elements and is kept in sync with this variable contract.
+
+---
+
+## Prominence Styles
+
+Prominence styles provide filter-based interaction feedback for components. They use CSS `filter` (opacity + saturation) to convey interaction state, reducing visual noise for idle components while restoring full vibrancy on interaction.
+
+### States
+
+| State | Trigger | Effect |
+|-------|---------|--------|
+| **Idle** | No interaction | Reduced opacity + desaturated |
+| **Tickled** | `:hover` / `:focus-within` | Elevated opacity + saturation |
+| **Active** | `:active` / `[dragging]` | Full vibrancy (filter removed) |
+| **Disabled** | `[disabled]` / `:disabled` | Heavily muted + near-grayscale, `pointer-events: none` |
+
+### CSS Variables
+
+Defaults are defined on `:host` and can be overridden per-instance:
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `--prominence-disabled-opacity` | `0.3` | Opacity when disabled |
+| `--prominence-disabled-saturate` | `0.1` | Saturation when disabled |
+| `--prominence-idle-opacity` | `0.6` | Opacity when idle |
+| `--prominence-idle-saturate` | `0.4` | Saturation when idle |
+| `--prominence-tickled-opacity` | `0.85` | Opacity on hover/focus |
+| `--prominence-tickled-saturate` | `0.8` | Saturation on hover/focus |
+
+### When to Apply
+
+Use `prominenceStyles` for **interactive visual components** that benefit from reduced visual noise when idle — such as data visualization widgets (xy-pad, graphs), canvas-based components, or embedded media. Do not use for standard UI controls (buttons, inputs, menus) which already have their own interaction patterns via surface depth.
+
+### How to Apply
+
+```ts
+import { prominenceStyles } from '../styles/prominence.js';
+import { css } from 'lit';
+
+class MyComponent extends LitElement {
+  static styles = [prominenceStyles, css`...`];
+}
+```
+
+To disable prominence effects entirely, override the variables on the component instance:
+
+```html
+<my-component style="
+  --prominence-idle-opacity: 1;
+  --prominence-idle-saturate: 1;
+  --prominence-tickled-opacity: 1;
+  --prominence-tickled-saturate: 1;
+"></my-component>
+```
+
+### Notes
+
+- Uses CSS pseudo-classes only — no JavaScript tickled state management required.
+- `:host([dragging])` supplements `:active` for components that set that attribute during pointer drags.
+- Transition uses `--transition` from the theme.
+- When disabled, `pointer-events: none` is enforced and cannot be overridden.
+
+---
+
+## Scroll Fade
+
+Zero-JS edge-fade indicator for scrollable containers — signals "there's more content this way" by fading content out near an edge, only when that edge is actually scrollable.
+
+Implemented with a CSS alpha mask driven by a scroll-linked animation (`scroll-timeline` + `animation-timeline` + `@property`-registered custom properties), not a JS scroll/resize listener. Two consequences of that:
+
+- It can't go stale. A JS approach (recompute on `scroll`) misses cases where the scrollable range changes without the scroll position changing — e.g. widening a resizable container so content that used to overflow now fully fits. The fade only updates on the next `scroll` event, so it can be stuck showing a shadow with nothing left to scroll to. The CSS version reads live scroll-range state every frame for free.
+- It's a genuine mask, not a background layer. `background-image` paints behind an element's children, so it disappears wherever a child has an opaque background of its own. A mask fades the whole composited element — background and children together — so it works regardless of item styling.
+
+### CSS Variables
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `--scroll-fade-width` | `30px` | How far the fade extends in from each edge |
+| `--scroll-fade-strength` | `1` | How completely content fades at the edge, `0`–`1` (`1` = to transparent, `0` = no fade). Dense layouts usually want `0.7`–`0.8` |
+
+### When to Apply
+
+Any custom component with a scrolling region (`overflow-x`/`overflow-y`: `scroll`/`auto`) where content can overflow — breadcrumb trails, tab strips, horizontal chip/pill lists, scrollable menus. New scrollable components should use this by default rather than rolling a one-off shadow/fade.
+
+### How to Apply
+
+```ts
+import { scrollFadeStyles } from '../styles/scroll-fade.js';
+
+class MyComponent extends LitElement {
+  static styles = [scrollFadeStyles(`x`), css`
+    .scroller {
+      overflow-x: scroll;
+      /* ... */
+    }
+  `];
+}
+```
+
+Apply the matching class (`scroll-fade-x` for a horizontally-scrolling element, `scroll-fade-y` for vertical) to the actual `overflow`-scrolling element:
+
+```ts
+html`<div class="scroller scroll-fade-x">...</div>`
+```
+
+If a component can scroll on either axis depending on a runtime property (e.g. an `orientation` attribute), include both `scrollFadeStyles(`x`)` and `scrollFadeStyles(`y`)` in `static styles` and switch which class is applied in `render()` — each axis uses independently-named `@property`/`@keyframes`/`scroll-timeline` internals, so having both present is safe even though only one is ever applied at a time.
+
+Apply only one axis class per element — each sets `mask-image`, so a second axis class would overwrite the first rather than combine. For an element that scrolls on both axes at once (e.g. a grid viewport with `overflow: auto`), put the vertical fade on the viewport itself and handle the horizontal axis on a separate element (e.g. a synced header strip with its own `scroll-fade-x`). For a data grid, keep the mask on the row viewport below the header bar — not on a wrapper containing the headers — so the top fade never covers the column headers.
+
+### Notes
+
+- Used by `ixfx-crumb-navigation` and `ixfx-crumb-path` (`src/crumbs/`) — reference implementations for the pattern above. `ixfx-data-grid` uses `.scroll-fade-y` on the row viewport and `.scroll-fade-x` on the header strip, with dense-data defaults (`--scroll-fade-width: 20px; --scroll-fade-strength: 0.8`).
+- Depends on `scroll-timeline`, `animation-timeline`, and `@property`, all reasonably modern CSS features. Unsupported browsers simply get no fade (the mask fails to apply, not the scrolling) — verify this degrades acceptably for your target browser matrix before relying on it as anything more than a visual nicety.
+- Don't set the animated custom properties (or their `@property initial-value`/keyframe values/`var()` fallbacks) as unitless `0` — always `0px`. A bare `0` inside the generated `calc(100% - var(...))` is a percentage/number type mismatch that silently invalidates the whole `mask-image`, which is exactly what caused this to intermittently render as "always on" during development.
+
+---
+
+## Quick Reference
+
+### Common component patterns
+
+**Panel/Card** (surface-3 — default plane)
+```css
+background: var(--surface-3);
+color: var(--surface-3-text);
+border: var(--border);
+border-radius: var(--radius-l);
+padding: var(--space-l);
+```
+
+**Button** (surface-4 — raised above panel)
+```css
+background: var(--surface-4);
+color: var(--surface-4-text);
+border: var(--border);
+border-radius: var(--radius-m);
+padding: var(--space-s) var(--space-m);
+```
+
+**Button hover** (surface-5 — one level higher)
+```css
+background: var(--surface-5);
+```
+
+**Menu/Popover** (surface-5 — floating above panel)
+```css
+/* Use the shared popupSurfaceStyles from src/styles/popup.ts */
+background: var(--surface-5);
+border: 1px solid var(--surface-6);
+border-radius: var(--radius-l);
+box-shadow: var(--shadow-m);
+color: var(--surface-5-text);
+```
+
+**Menu item hover** (surface-6 — one level above menu background)
+```css
+background: var(--surface-6);
+```
+
+**Input field** (surface-4 — same level as buttons)
+```css
+background: var(--surface-4);
+color: var(--surface-4-text);
+border: var(--border);
+border-radius: var(--radius-s);
+```
+
+---
+
+## Implementation Notes
+
+1. **OKLCH format**: All colours use OKLCH for perceptual uniformity.
+2. **Semantic naming**: Variables describe *what* they represent and *where* in the depth hierarchy.
+3. **Theme Fallbacks**: Components must include the `themeFallbacks` style module from `src/styles/fallbacks.ts` in their `static styles` array. This registers `@property` rules for every theme variable with `inherits: true`, providing initial values in shadow DOM without shadowing inherited `:root` declarations.
+
+   ```ts
+   import { themeFallbacks } from '../styles/fallbacks.js';
+
+   class MyComponent extends LitElement {
+     static styles = [themeFallbacks, css`...`];
+   }
+   ```
+
+   Do **not** use per-usage CSS fallbacks like `var(--surface-3, #ccc)` — they would need updating if the theme changes and don't compose well. The `@property` approach is centralized, idempotent, and transparent to component authors.
+
+4. **Dark theme default**: The dark theme is the default. Light theme activates via `@media (prefers-color-scheme: light)`.
+5. **Theme source**: All variables are defined in `src/style.css`. Custom themes can be defined by overriding variables on a class (see `demo/shared/demo-themes.ts`).
+6. **Popup surface helper**: Floating components (menus, popovers, colour picker, crumb dropdown, tooltips) share `popupSurfaceStyles` from `src/styles/popup.ts` for consistent appearance.
+
+### Shadow DOM CSS Variable Bridging
+
+CSS custom properties set on a parent element do not automatically pierce into Shadow DOM children. To allow external customisation of internal component styling, use a **bridge variable** pattern:
+
+```css
+:host {
+  /* Internal alias: checks external var first, falls back to default */
+  --my-internal-var: var(--my-external-var, var(--surface-5));
+
+  /* Component's own internal defaults (can reference other :host vars) */
+  --my-other-var: var(--surface-3);
+}
+
+/* Use the internal alias in actual styles */
+.my-element {
+  background: var(--my-internal-var);
+  color: var(--my-other-var);
+}
+```
+
+**How it works:**
+- `--my-external-var` is the public API — consumers set this on the component element or parent
+- `--my-internal-var` is the internal bridge defined in `:host`, which resolves to `--my-external-var` if set, otherwise the fallback
+- The component's internal CSS rules use `--my-internal-var`
+
+**Example from `ixfx-tab-list-item` (all bridge variables):**
+```css
+:host {
+  /* Bridge variables: external ixfx-* var, fallback */
+  --selected-tab-color: var(--ixfx-selected-tab-color, var(--surface-2-text));
+  --selected-tab-border-width: var(--ixfx-selected-tab-border-width, 1px);
+  --selected-tab-weight: var(--ixfx-selected-tab-weight, bold);
+  --selected-background: var(--ixfx-tab-selected-background, var(--surface-5));
+}
+
+:host([selected]) > div {
+  color: var(--selected-tab-color);
+  border: var(--selected-tab-border-width) solid transparent;
+  background: var(--selected-background);
+  font-weight: var(--selected-tab-weight);
+}
+```
+
+**Usage:**
+```html
+<!-- Set on parent to affect all tabs -->
+<ixfx-tab-list style="
+  --ixfx-selected-tab-color: var(--accent-text);
+  --ixfx-selected-tab-weight: 600;
+  --ixfx-tab-selected-background: var(--accent);
+">
+
+<!-- Or on individual tab for per-item override -->
+<ixfx-tab-list-item style="--ixfx-tab-selected-background: var(--surface-2);">
+```
+
+**Key insight:** Without the bridge variable, `--ixfx-*` properties set on `ixfx-tab-list` would not be visible inside `ixfx-tab-list-item`'s shadow DOM. The bridge variables defined in `:host` live in the same scope as the component's internal CSS rules, so they can resolve external variables while still providing fallbacks.