@ixfx/components 0.16.3 → 0.16.4

package/docs-user/infra-handle.md

@@ -0,0 +1,122 @@
+# Drag / resize handles
+
+A **handle** is the grab affordance for moving or resizing an object — a
+splitter grip, a resize edge, a reorder handle. `handleStyles`
+(`src/styles/handle.js`) is the one shared look, so every draggable component
+reads the same and themes through the same variables.
+
+Before this module the library had six unrelated handle idioms (two of them
+near-duplicate 3-dot implementations, two hard-coded Unicode glyphs). Don't add a
+seventh.
+
+---
+
+## Usage
+
+```ts
+import { themeFallbacks } from '../styles/fallbacks.js';
+import { handleStyles } from '../styles/handle.js';
+
+class MyComponent extends LitElement {
+  static styles = [themeFallbacks, handleStyles, css`
+    .hit-zone { /* your resize / drag target */ }
+  `];
+
+  render() {
+    return html`
+      <div class="hit-zone" @pointerdown=${this.#onDown}>
+        <span class="ixfx-handle" data-handle="flat" data-shape="horizontal" part="handle"></span>
+      </div>`;
+  }
+}
+```
+
+Bind pointer handlers to the **hit-zone**, not the handle — the handle is
+`pointer-events: none`.
+
+---
+
+## Two independent axes
+
+| Attribute | Values | Meaning |
+|---|---|---|
+| `data-handle` | `flat` (default) · `dotted` · `dimpled` · `grated` | **texture** — how the mark looks |
+| `data-shape`  | `horizontal` (default) · `vertical` · `spot` | **topology** — a wide bar, a tall bar, or a small centred point handle |
+
+Any texture combines with any shape.
+
+- **flat** — a solid rounded capsule (a bar) or dot (`spot`), filled with
+  `--ixfx-handle-color`. The `ixfx-bottom-drawer` resize handle.
+- **dotted** — marks in the [Lucide *grip*](https://lucide.dev/icons/grip)
+  arrangement: **three in a row** (`horizontal`), **three in a column**
+  (`vertical`), or a **3×3 block** (`spot`). Drawn as one `::before` mark plus
+  `box-shadow` copies, so each mark's corner rounding is `--ixfx-handle-radius`
+  (→ the theme `--radius-l`): **round** normally, **square** under a flat theme
+  (`--radius-l: 0`, e.g. `theme-cyberpunk`). Tinted by `--ixfx-handle-color`. The
+  `ixfx-data-grid` column reorder handle, `ixfx-timeline-track-tab` reorder
+  handle, `ixfx-dock-host` junction handles.
+- **dimpled** — that same layout, but each **bar** mark is pressed in: a lighter
+  copy peeking out above-left and a darker copy below-right (`spot` stays plain —
+  the 3D is imperceptible at that size). Splitter grips (`ixfx-split-layout`,
+  `ixfx-twosplit-layout`).
+- **grated** — fine 45° knurling: parallel ridges, each a **lit edge, the base
+  colour, then a shaded edge**. `spot` is the same hatch cropped square.
+
+`dotted`, `dimpled` and `grated` are texture only — no plate, box or border; the
+gaps are transparent, so the surface behind shows through. The base is
+`--ixfx-handle-color` (`currentColor`); `--ixfx-handle-highlight` /
+`--ixfx-handle-shadow` default to that colour lightened / darkened, so `dimpled`
+stays as prominent as `dotted` and re-tones with the theme.
+
+---
+
+## Active state
+
+The handle goes to `--ixfx-handle-opacity-active` (and, for `flat` / `dotted`,
+`--ixfx-handle-color-active`) when:
+
+- its **immediate parent** (the hit-zone) is `:hover` or `:focus-visible`, or
+- the hit-zone or the handle carries `[data-active]`.
+
+While a drag is live the pointer may leave the hit-zone, so set `[data-active]`
+on the hit-zone yourself for the duration and the handle stays lit.
+
+To suppress the reveal entirely, set `--ixfx-handle-opacity-active` equal to
+`--ixfx-handle-opacity`.
+
+---
+
+## CSS variables
+
+Defaults resolve through `themeFallbacks`. Override on the handle element or any
+ancestor (`:host`, the hit-zone, …).
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `--ixfx-handle-color` | `var(--surface-muted-text)` | `flat` / `dotted` fill |
+| `--ixfx-handle-color-active` | `var(--accent)` | `flat` / `dotted` hover / focus / `[data-active]` |
+| `--ixfx-handle-thickness` | `6px` | cross-axis size of a bar |
+| `--ixfx-handle-length` | `44px` | long-axis size of a bar (`100%` fills) |
+| `--ixfx-handle-spot-size` | `14px` | width = height of a `spot` |
+| `--ixfx-handle-radius` | `var(--radius-l)` | `flat` capsule + `dotted` / `dimpled` mark rounding (0 ⇒ squares) |
+| `--ixfx-handle-opacity` | `0.55` | rest opacity |
+| `--ixfx-handle-opacity-active` | `1` | active opacity |
+| `--ixfx-handle-dot-size` | `4px` | mark size (dotted / dimpled) |
+| `--ixfx-handle-dot-gap` | `length / 6` (bar) · `spot / 3` | mark centre-to-centre step |
+| `--ixfx-handle-tile` | `5px` | knurl period (grated) |
+| `--ixfx-handle-highlight` | `color-mix(currentColor 35%, #fff)` | lit deboss edge (dimpled / grated) |
+| `--ixfx-handle-shadow` | `color-mix(currentColor 60%, #000)` | shaded deboss edge (dimpled / grated) |
+
+---
+
+## Notes & limits
+
+- **Host-as-handle** (`:host(.ixfx-handle)`) is not supported yet — always wrap
+  the class on a child element inside the hit-zone.
+- The handle exposes `part="handle"` (rename per component where a more specific
+  part name already exists, e.g. `part="grip"` / `part="reorder-handle"`).
+- No motion beyond the colour / opacity transition; nothing to gate for reduced
+  motion (the module still drops the transition under
+  `prefers-reduced-motion: reduce`).
+
+See it live: `demo/handle.html` (4 textures × 3 shapes + variable knobs).

package/docs-user/infra-incremental.md

@@ -0,0 +1,154 @@
+# Incremental search
+
+Type-ahead search shared by the list and tree components. One popover, one
+`ReactiveController`, three behaviours ("modes"), triggered by
+`@clinth/ui-commands` commands. Built on the fuzzy engine in
+`src/incr-search/incr-search.ts` (fzf).
+
+Supported today: `ixfx-grid-list`, `ixfx-vertical-list`, `ixfx-detail-list`,
+`ixfx-data-grid`, `ixfx-tree-list`, `ixfx-miller-list`.
+
+---
+
+## The three modes
+
+| Mode | As you type… | Enter | On close |
+|---|---|---|---|
+| **navigate** | the cursor moves to the best match; ↑/↓ cycle between matches | activates the current match, closes | cursor stays |
+| **select** | the selection becomes the set of matching items, live | closes | selection stays |
+| **filter** | items that don't match are hidden | closes (keeps the filter with `stickyFilter`) | filter is removed |
+
+All modes highlight the matched characters (CSS Custom Highlights) where the
+component supports it.
+
+### Conversions
+
+The popover is interactive. While it's open you can, without retyping:
+
+- **switch mode** — buttons for each other enabled mode, or **Tab** /
+  **Shift+Tab** in the input to cycle forward / back (`cycleMode(±1)`). The old
+  mode's effect is undone first (e.g. leaving *filter* un-hides), then the new
+  mode is applied to the current query. Example: start in *filter*, hit
+  **navigate** to stop hiding and just move the cursor.
+- **re-open** — running a search command while the popover is open keeps the
+  query: it switches to that command's mode and refocuses the input with the
+  text selected. `focus()` refocuses without changing mode.
+- **Select matches** — a one-shot button (shown in *navigate* / *filter* when
+  *select* is enabled) that turns the current match set into the selection while
+  staying in the current mode.
+
+### Sticky filter
+
+By default a filter lasts only while the popover is open. Set
+`list.search.stickyFilter = true` (or the `stickyFilter` controller option) so
+that Enter in *filter* mode closes the popover but keeps the filter. A
+"Filtered: …" chip (part `search-kept`) stays in the popover's place, and the
+filter re-applies as items change. Clear it with the chip's ×, Escape on the
+list, or `search.clearFilter()`. Clicking the chip, or running any search
+command, reopens the popover with the kept query. `search.keptFilter` is the
+kept query (or `undefined`).
+
+### Which modes are offered
+
+The effective set is **component capability ∩ the `search-modes` attribute**:
+
+- **capability** — most components offer all three. A component with no
+  selection concept would omit `select`, etc.
+- **`search-modes`** attribute — a space-separated subset of
+  `navigate select filter`. Unset ⇒ the component default. Empty (`search-modes=""`)
+  ⇒ search disabled: no commands registered, no popover.
+
+```html
+<ixfx-grid-list search-modes="navigate filter"></ixfx-grid-list>
+```
+
+---
+
+## Commands
+
+Each component owns a `@clinth/ui-commands` `CommandRegistry` (exposed as
+`el.registry`) and registers one command per enabled mode:
+
+| id | opens |
+|---|---|
+| `list.search.navigate` | popover in navigate mode |
+| `list.search.select` | popover in select mode |
+| `list.search.filter` | popover in filter mode |
+
+There is **no default keybinding** — a consumer binds a key or button:
+
+```ts
+el.registry.invoke('list.search.filter');
+// or via @clinth/ui-commands' InputManager / a data-command button
+```
+
+`ixfx-grouped-item-lister.dispatch('list.search.filter')` fans the command out to
+every sub-list.
+
+---
+
+## Adding search to a new component
+
+1. **Adapter.** Implement `ListSearchAdapter<TItem>` (`src/incr-search/list-search-controller.ts`):
+   `getItems` / `getLabel` / `getKey`, then `focusItem` (navigate),
+   `selectItems` (select), `applyFilter` (filter; `undefined` clears).
+   Optional: `activateItem`, the `highlight*` hooks, `container` (an element
+   whose child-list mutations should re-`refresh()` the item set).
+   - Element-based lists: `createElementListSearchAdapter(this, { itemSelector })`.
+   - Tree-based: `createTreeListSearchAdapter(this, { labelSelector })`.
+
+2. **Controller.** One field:
+
+   ```ts
+   readonly search = new ListSearchController<TItem>(this, {
+     adapter: /* from step 1 */,
+   });
+   ```
+
+3. **Styles + field.** Add `listSearchStyles` to `static styles` and
+   `${this.search.renderField()}` to `render()`, inside a `position: relative`
+   ancestor that is **not** the scroll container (so the popover doesn't scroll
+   away — put `overflow:auto` on an inner element, `position:relative` on `:host`).
+
+4. **Modes + commands.** Keep a `search-modes` reflected property; on connect and
+   whenever it changes:
+
+   ```ts
+   this.search.setModes(/* capability ∩ search-modes */);
+   this.#unregister?.();
+   this.#unregister = registerListSearchCommands(this.registry, this.search);
+   ```
+
+   Own the registry (`createCommandRegistry()`), expose it as `registry`,
+   unregister on disconnect. Route any `dispatch(commandId, args)` to
+   `registry.invoke(commandId, args)`.
+
+5. **Keyboard.** `if (this.search.isOpen) return;` at the top of the host's
+   keydown handler so list navigation doesn't fight the field.
+
+---
+
+## Notes
+
+- **Virtualised lists** (`ixfx-grid-list`, `ixfx-data-grid`) — filter genuinely
+  drops items from layout/virtualisation. Character highlights are best-effort:
+  applied to whatever is in the rendered window (data-grid does no highlighting —
+  a match position indexes into the whole-row text, which spans cells).
+- **Trees** snapshot the whole node set when the popover opens (`getNodes()`
+  returns every node regardless of expansion or an active filter), so refining a
+  query can always re-surface a node. `navigate` expands the match's ancestors;
+  `filter` prunes via `filterPredicate` but does **not** auto-expand collapsed
+  ancestors of a deep match.
+- **Highlights** painted inside a host's shadow root are styled by
+  `listSearchStyles` (keys `incr-search-highlight`, `grid-list-search`,
+  `data-grid-search`; tokens `--search-highlight-bg` / `--search-highlight-color`).
+  A host using another key must add its own rule. Text in the light DOM (the
+  element lists paint onto the item elements) needs a page-level
+  `::highlight(<key>)` rule:
+  `::highlight(vertical-list-search) { background: var(--accent); color: var(--accent-text); }`.
+- Everything is inert when the effective mode set is empty.
+
+## Deprecated
+
+`createElementIncrSearch` and `IncrSearchTreeController` (the external-`<input>`
+filter-only controllers) still work but are superseded by the built-in popover.