@ixfx/components 0.5.1 → 0.5.3

package/dist/style.css

@@ -141,3 +141,83 @@
 ixfx-grouped-item-lister {
   display: block;
 }
+ixfx-form {
+  display: block;
+}
+
+ixfx-form-group {
+  display: block;
+  container-type: inline-size;
+}
+
+ixfx-form-group fieldset {
+  gap: var(--space-m) var(--space-l);
+  margin: 0;
+  border: 0;
+  grid-template-columns: 1fr;
+  min-inline-size: 0;
+  margin-block-start: var(--space-m);
+  margin-block-end: var(--space-m);
+  padding: 0;
+  display: grid;
+}
+
+ixfx-form-group fieldset > legend:empty {
+  display: none;
+}
+
+ixfx-form-group fieldset > legend {
+  font-weight: var(--font-weight-bold);
+  grid-column: 1 / -1;
+  margin-block-start: var(--space-m);
+  margin-block-end: var(--space-s);
+  padding: 0;
+}
+
+ixfx-form-group fieldset > :not(ixfx-form-part) {
+  grid-column: 1 / -1;
+}
+
+ixfx-form-part {
+  grid-column: 1 / -1;
+  grid-template-columns: 1fr;
+  align-items: start;
+  display: grid;
+}
+
+ixfx-form-part > label {
+  font-size: var(--ixfx-form-label-font-size, var(--text-s));
+  font-weight: var(--ixfx-form-label-font-weight, inherit);
+  font-family: var(--ixfx-form-label-font-family, inherit);
+  color: var(--ixfx-form-label-color, inherit);
+  text-transform: var(--ixfx-form-label-text-transform, uppercase);
+  padding-bottom: var(--space-xs);
+  grid-area: 1 / 1;
+}
+
+ixfx-form-part > input, ixfx-form-part > select, ixfx-form-part > textarea {
+  grid-area: 2 / 1;
+}
+
+@container (width >= 30rem) {
+  ixfx-form-group fieldset {
+    grid-template-columns: max-content 1fr;
+  }
+
+  ixfx-form-part {
+    grid-column: 1 / -1;
+    grid-template-columns: subgrid;
+    align-items: baseline;
+    display: grid;
+  }
+
+  ixfx-form-part > label {
+    padding-right: var(--space-xs);
+    grid-area: 1 / 1;
+    padding-bottom: 0;
+  }
+
+  ixfx-form-part > input, ixfx-form-part > select, ixfx-form-part > textarea {
+    grid-area: 1 / 2;
+  }
+}

package/docs-user/README.md

@@ -12,6 +12,7 @@ This directory contains documentation for each component and some architectural
 - [crumbs](./crumbs.md)
 - [data-display](./data-display.md)
 - [editable-label](./editable-label.md)
+- [form](./form.md)
 - [grouped-item-lister](./grouped-item-lister.md)
 - [icons](./icons.md)
 - [incr-search](./incr-search.md)

package/docs-user/form.md

@@ -0,0 +1,108 @@
+# Form layout components
+
+Primitives for typical form layout with responsive label positioning and data binding.
+
+---
+
+## `ixfx-form`
+
+Main container for form sections. Provides `getValues()` and `setValues()` methods for data binding.
+
+```html
+<ixfx-form>
+  <ixfx-form-group label="Section A">
+    <p>Preamble text for section A...</p>
+    <ixfx-form-part label="Some text">
+      <input type="text" name="input1" />
+    </ixfx-form-part>
+    <ixfx-form-part label="Some other text">
+      <input type="text" name="input2" />
+    </ixfx-form-part>
+  </ixfx-form-group>
+</ixfx-form>
+```
+
+### Properties / attributes
+
+`ixfx-form` has no attributes — it is a pure layout and data-binding container.
+
+### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `getValues()` | `Record<string, unknown>` | Collects values from all named inputs within the form |
+| `setValues(data)` | `void` | Applies values to named inputs. Keys absent from `data` are left untouched. |
+
+### Value collection rules
+
+- Native `<input type=radio>` sharing a `name` → value of the checked one
+- Native/checked-bearing checkbox → boolean
+- `<select multiple>` → array of selected values
+- Everything else with a `.value` property → used as-is
+
+---
+
+## `ixfx-form-group`
+
+A section within the form, backed by a `<fieldset>`/`<legend>` for proper accessibility semantics.
+
+```html
+<ixfx-form-group label="Personal Information">
+  <ixfx-form-part label="Full Name">
+    <input type="text" name="name" />
+  </ixfx-form-part>
+  <ixfx-form-part label="Email">
+    <input type="email" name="email" />
+  </ixfx-form-part>
+</ixfx-form-group>
+```
+
+### Properties / attributes
+
+| Attribute / Property | Type   | Default | Description |
+|---------------------|--------|---------|-------------|
+| `label`            | string | `''`    | Section heading text |
+
+---
+
+## `ixfx-form-part`
+
+Wraps a form control with a label. Uses light DOM so the `<label for>` natively associates with the slotted input.
+
+```html
+<ixfx-form-part label="Username">
+  <input type="text" name="username" />
+</ixfx-form-part>
+```
+
+### Properties / attributes
+
+| Attribute / Property | Type   | Default | Description |
+|---------------------|--------|---------|-------------|
+| `label`            | string | `''`    | Label text displayed for the control |
+
+### How it works
+
+`ixfx-form-part` generates an `<label for="...">` element that is associated with the first control-like child (`<input>`, `<select>`, `<textarea>`, or element with a `name` attribute). The association works natively because both elements live in the same light DOM tree — no shadow boundary to work around.
+
+An `id` is generated for the control if it doesn't already have one.
+
+---
+
+## Responsive behaviour
+
+The layout switches between two modes based on available width (via CSS container queries):
+
+**Narrow (< 30rem):** Label appears above the input, single-column stacked layout.
+
+**Wide (≥ 30rem):** Label appears to the left of the input, two-column grid. All labels in a group share the width of the widest label (right-justified).
+
+Resize the container to see the transition.
+
+---
+
+## TypeScript types
+
+```ts
+import type { FormElement, FormGroupElement, FormPartElement } from 'ixfxfun-components';
+```

package/docs-user/tabs.md

@@ -27,10 +27,18 @@ Wire them together:
 const tabList = document.querySelector('ixfx-tab-list');
 const tabPanels = document.querySelector('ixfx-tab-panels');
 tabList.addEventListener('change', e => {
-  tabPanels.selectPanel(e.detail.selected);
+  tabPanels.selectPanel(e.detail.for);
 });
 ```
 
+Select a tab programmatically — same effect as clicking it (header + content):
+
+```js
+tabPanels.syncWithList(tabList);
+tabPanels.selectTab('Home');        // by label text
+tabPanels.selectTab('panel-home');  // by the panel id a tab's `for` points at
+```
+
 ---
 
 ## `ixfx-tab-list`
@@ -252,4 +260,99 @@ 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 |
-| `syncWithList(el)`  | `TabListElement` | `void` | Sync panel selection to tab list |
+| `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 |
+
+---
+
+## `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/package.json

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