@ixfx/components 0.5.2 → 0.5.4

package/docs-user/tabs.md

@@ -261,4 +261,98 @@ Manages multiple `ixfx-tab-panel` children, selecting one at a time.
 | `getSelectedElement()` | —      | `TabPanelElement \| undefined` | Get currently selected panel |
 | `selectPanel(id)`  | `string` | `boolean` | Select panel by ID; returns true if found |
 | `selectTab(nameOrTitle)` | `string` | `boolean` | Select a tab as if it was clicked: activates the matching header (via the list associated with `syncWithList`) and shows its panel. `nameOrTitle` can be a tab's label text (case-insensitive) or the panel id its `for` attribute points at. Returns true if a panel was found |
-| `syncWithList(el)`  | `TabListElement` | `void` | Associates this panels element with a tab list, syncing panel selection to it. Must be called before `selectTab()` if the tab header should be activated |
+| `syncWithList(el)`  | `TabListElement` | `void` | Associates this panels element with a tab list, syncing panel selection to it. Must be called before `selectTab()` if the tab header should be activated |
+
+---
+
+## `TabController`
+
+A class that wires an `ixfx-tab-list` to an `ixfx-tab-panels` container. It keeps track of the tabs, mirrors the selected header into the panels, and offers an API to select, add, remove, rename and reorder tabs.
+
+### Setup
+
+```js
+import { TabController } from '@ixfx/components';
+
+const controller = new TabController(
+  document.querySelector('ixfx-tab-list'),
+  document.querySelector('ixfx-tab-panels'),
+  {
+    onSelect: (tab, previous) => console.log(`selected ${tab.id}`),
+  },
+);
+controller.connect();
+```
+
+Call `connect()` to start wiring; `disconnect()` removes listeners, observers and commands.
+
+### Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `commands` | `CommandRegistry \| undefined` | When provided, a command is registered per tab (id = tab id). Invoking `commands.invoke(id)` selects the tab |
+| `onSelect` | `(tab, previous) => void` | Fired after a tab is selected (click or programmatic) |
+| `onAdd` | `(tab) => void` | Fired after a tab is added |
+| `onRemove` | `(tab) => void` | Fired after a tab is removed |
+| `onReorder` | `(tabs) => void` | Fired after tabs are reordered |
+
+### Methods
+
+| Method | Argument | Returns | Description |
+|--------|----------|---------|-------------|
+| `connect()` | — | `void` | Wire the list and panels, register commands |
+| `disconnect()` | — | `void` | Remove listeners, observers and commands |
+| `selectTab(sel)` | `string \| TabListItemElement` | `boolean` | Select a tab as if it was clicked. `sel` may be a tab id, the panel id its `for` points at, its label text (case-insensitive), or the item element |
+| `selectNext()` | — | `boolean` | Select the next tab (wraps) |
+| `selectPrevious()` | — | `boolean` | Select the previous tab (wraps) |
+| `getSelected()` | — | `Tab \| undefined` | Currently selected tab |
+| `getTabs()` | — | `Tab[]` | All managed tabs |
+| `getTab(id)` | `string` | `Tab \| undefined` | Tab by id |
+| `addTab(opts)` | `TabAddOptions` | `Tab` | Add a tab (item + panel) |
+| `removeTab(sel)` | `string \| TabListItemElement` | `boolean` | Remove a tab; selects an adjacent tab if the removed one was selected |
+| `renameTab(sel, label)` | `string \| TabListItemElement, string` | `boolean` | Change a tab's label |
+| `setTabIcon(sel, iconName?)` | `string \| TabListItemElement, string \| undefined` | `boolean` | Set or clear a tab's icon |
+
+A `Tab` is `{ id, forId, item, panel, label, iconName? }` where `item` is the `ixfx-tab-list-item` and `panel` the `ixfx-tab-panel`.
+
+### `TabAddOptions`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `label` | `string` | *(required)* | Tab label |
+| `id` | `string` | derived from label | id for the tab item |
+| `forId` | `string` | derived from label | id for the panel (and the item's `for`) |
+| `iconName` | `string` | — | Icon to display |
+| `description` | `string` | — | Tooltip description |
+| `closeable` | `boolean` | `true` | Show the close button |
+| `toolbar` | `HTMLElement[]` | — | Elements to slot into `slot="toolbar"` |
+| `content` | `Node \| string \| (panel) => void` | — | Panel content |
+| `select` | `boolean` | `true` | Select the new tab immediately |
+| `index` | `number` | append | Insertion index among existing tabs |
+
+```js
+controller.addTab({
+  label: 'Console',
+  iconName: 'debug',
+  content: (panel) => { panel.append('Console output'); },
+});
+```
+
+### Keyboard shortcuts via commands
+
+Pass a `CommandRegistry` to the options and bind shortcuts with `KeyboardManager`. Command ids equal the tab ids:
+
+```js
+import { CommandRegistry, KeyboardManager } from '@clinth/ui-commands';
+
+const commands = new CommandRegistry();
+const controller = new TabController(list, panels, { commands });
+
+const keyboard = new KeyboardManager();
+keyboard.bind({ key: '1', modifiers: new Set(['alt']), commandId: 'tab-home' });
+keyboard.bind({ key: '2', modifiers: new Set(['alt']), commandId: 'tab-profile' });
+keyboard.onKeyEvent((commandId) => commands.invoke(commandId));
+keyboard.attach(document.body);
+```
+
+Commands are unregistered when their tab is removed or the controller disconnects.

package/docs-user/vertical-list.md

@@ -127,14 +127,14 @@ Switching `interactionMode` always clears the current selection.
 | `'implicit'` | Click always replaces selection. No modifier support. |
 | `'standard'` | Plain click replaces selection; Ctrl/Cmd+click toggles; Shift+click range-selects (multiple mode only); Cmd+A selects all |
 | `'vscode'` | Like `standard` for clicks; Shift+Arrow extends the range from the keyboard anchor |
-| `'checked'` | Checkbox column on the left of every row; only that column is clickable and it spans the full row height so a tall card can still be toggled with a single click on the left; Space toggles the focused row. See [Custom checkbox](#custom-checkbox) for styling |
+| `'checked'` | Checkbox column on the left of every row; only that column is clickable and it spans the full row height so a tall card can still be toggled with a single click on the left; Space toggles the focused row. Rows marked `not-checked` get no checkbox and can't be checked (see [Non-checkable rows](#non-checkable-rows)). See [Custom checkbox](#custom-checkbox) for styling |
 | `'manual'` | No automatic selection; drive state entirely via `select()` / `deselect()` / `clearSelection()` |
 
 ---
 
 ## Custom checkbox
 
-In `checked` mode every row gets a checkbox column on the left. The column is always a **full-height click target** (the wrapper uses `align-self: stretch`), so a single click anywhere on the left side of a tall card toggles it — you never have to precisely hit a small checkbox. Clicks on the row body (the text or custom card content) do **not** toggle, and the cursor is `default` there so the affordance is clear.
+In `checked` mode every row gets a checkbox column on the left — except rows marked [`not-checked`](#non-checkable-rows), which get no checkbox and can't be checked. The column is always a **full-height click target** (the wrapper uses `align-self: stretch`), so a single click anywhere on the left side of a tall card toggles it — you never have to precisely hit a small checkbox. Clicks on the row body (the text or custom card content) do **not** toggle, and the cursor is `default` there so the affordance is clear.
 
 By default the column contains a native `<input type="checkbox">`. The visible square is small, but the entire column (~20–24px wide, full row height) is clickable.
 
@@ -189,9 +189,44 @@ list.checkboxRenderer = {
 
 Because the wrapper still spans the full row height and owns the click handler, the empty unchecked area is just as clickable as the visible tick — even though there is no border, background, or other visual indicator of where the column is.
 
+### Non-checkable rows (`not-checked`)
+
+Sometimes a list needs rows that are informational rather than selectable — headers, separators, "new document" placeholders. Mark an item with the `not-checked` attribute to opt it out in `checked` mode:
+
+```html
+<ixfx-vertical-list interaction-mode="checked">
+  <li not-checked>Recent files</li>
+  <li>Document A</li>
+  <li>Image 01.png</li>
+</ixfx-vertical-list>
+```
+
+A `not-checked` row:
+
+- shows **no checkbox column** (nothing is rendered on its left),
+- can **not be selected, toggled, or range-selected** — click, Space, `select()`, `selectMany()`, and `Cmd/Ctrl+A` all skip it,
+- is still **visible and navigable** — the cursor moves onto it, and it still fires `list-item-click` and `list-activate` (e.g. Enter).
+
+Outside `checked` mode the attribute has no effect, so the same item remains fully selectable in other interaction modes.
+
+The attribute works on both plain `<li>` items and `data-list-item` custom elements (on the custom element itself, before it is wrapped).
+
+When adding items programmatically, pass `notChecked: true` to `addItem()` instead of setting the attribute yourself:
+
+```typescript
+list.addItem('Header', { notChecked: true });
+list.addItem('Document A');
+
+// Or set the attribute directly on an element
+const header = document.createElement('li');
+header.textContent = 'Header';
+header.setAttribute('not-checked', '');
+list.addItem(header);
+```
+
 ### How it works under the hood
 
-In `checked` mode each row has a `<span class="ixfx-list-checkbox" role="checkbox" part="checkbox">` prepended as the first child:
+In `checked` mode each checkable row has a `<span class="ixfx-list-checkbox" role="checkbox" part="checkbox">` prepended as the first child:
 
 - When `checkboxRenderer` is set, your template is rendered into the span (via lit's `render()`) and re-rendered on every state change.
 - When `checkboxRenderer` is **not** set, the span contains a real `<input type="checkbox">` with `pointer-events: none` — the span owns the click so there is exactly one toggle per click.
@@ -239,6 +274,9 @@ list.selectAll();
 list.addItem('New item');
 list.addItem(myElement);
 
+// In checked mode, add a row that shows no checkbox and can't be checked
+list.addItem('Header', { notChecked: true });
+
 // Remove a specific element
 list.removeItem(element);
 
@@ -277,6 +315,8 @@ The component reflects state onto list items as data attributes. Use these in CS
 | `data-selected` | The item is in the current selection |
 | `data-checked` | Set in `checked` mode; mirrors `data-selected` |
 
+The `not-checked` attribute is user-set, not reflected: it opts a row out of `checked` mode (see [Non-checkable rows](#non-checkable-rows)).
+
 ---
 
 ## Events
@@ -431,7 +471,7 @@ ixfx-vertical-list {
 |---|---|
 | `list` | The `<ul>` scroll container |
 | `search-overlay` | The floating search input overlay |
-| `checkbox` | The per-row checkbox column wrapper in `checked` mode (always present; hosts the native `<input>` or the user-rendered content) |
+| `checkbox` | The per-row checkbox column wrapper in `checked` mode (present on checkable rows; hosts the native `<input>` or the user-rendered content) |
 
 Use `::part()` to style these from outside the component's shadow DOM:
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ixfx/components",
   "type": "module",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "",
   "author": "",
   "license": "ISC",