@ixfx/components 0.5.0 → 0.5.2

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/button.md

@@ -66,6 +66,8 @@ btn.icon = '<svg viewBox="0 0 24 24" fill="currentColor"><path d="..."/></svg>';
 | `--disabled-opacity`| `0.5`    | Opacity when disabled   |
 | `--ixfx-button-hide-icon`  | `inline-flex` (icon shown) | Set to `none` to hide the icon. Overridden by the `hide-icon` attribute. |
 | `--ixfx-button-hide-label` | `inline` (label shown)     | Set to `none` to hide the label. Overridden by the `hide-label` attribute. |
+| `--ixfx-button-outline`    | `none`                     | Additional outline around the button (e.g. `2px solid var(--accent)`) |
+| `--ixfx-button-shade`      | `none`                     | Tinted overlay via box-shadow (e.g. `inset 0 0 8px 2px color-mix(in oklch, red 35%, transparent)`) |
 
 `--ixfx-button-hide-icon`/`--ixfx-button-hide-label` let you hide the icon/label conditionally from plain CSS — handy for a media or container query — without touching the `hide-icon`/`hide-label` attributes:
 

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`
@@ -167,6 +175,46 @@ A recommended `.tab-toolbar-btn` style for the page stylesheet:
 |----------|--------|----------------------------|
 | `close`  | —      | Fired when close button clicked; item removes itself from DOM |
 
+### Command activation
+
+Tabs can be programmatically activated via the `CommandRegistry` system. This is useful for keyboard shortcuts (e.g. `Alt+1` to switch to tab 1).
+
+1. Create a `CommandRegistry` and register commands for each tab:
+```js
+import { CommandRegistry } from '@clinth/ui-commands';
+
+const commands = new CommandRegistry();
+commands.register({ id: 'tab-home', label: 'Home', description: 'Switch to Home tab', execute: () => {} });
+commands.register({ id: 'tab-profile', label: 'Profile', description: 'Switch to Profile tab', execute: () => {} });
+```
+
+2. Bind keyboard shortcuts to the commands using `KeyboardManager`:
+```js
+import { KeyboardManager } from '@clinth/ui-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);
+```
+
+3. Set the `command-active` attribute and assign the registry to each tab item:
+```html
+<ixfx-tab-list>
+  <ixfx-tab-list-item command-active="tab-home">Home</ixfx-tab-list-item>
+  <ixfx-tab-list-item command-active="tab-profile">Profile</ixfx-tab-list-item>
+</ixfx-tab-list>
+```
+
+```js
+for (const item of document.querySelectorAll('ixfx-tab-list-item[command-active]')) {
+  item.registry = commands;
+}
+```
+
+When a command is invoked (via keyboard shortcut or `commands.invoke('tab-home')`), the associated tab will be activated as if clicked.
+
 ### CSS custom properties
 
 | Property                | Default          | Description                  |
@@ -212,4 +260,5 @@ 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 |

package/docs-user/vertical-list.md

@@ -116,7 +116,7 @@ To reflect selection state inside the custom element's shadow DOM, target the `:
 | `selectionMode` / `selection-mode` | `'none' \| 'single' \| 'multiple'` | `'single'` | Which items can be selected simultaneously |
 | `interactionMode` / `interaction-mode` | `ListInteractionMode` | `'standard'` | How gestures map to selection changes (see table below) |
 | `filterPredicate` | `((el: Element) => boolean) \| undefined` | `undefined` | External filter; only items returning `true` are shown |
-| `checkboxRenderer` | `((checked: boolean) => unknown) \| undefined` | `undefined` | Custom content for the checkbox in `checked` mode. See [Custom checkbox](#custom-checkbox) |
+| `checkboxRenderer` | `((checked: boolean) => unknown) \| CustomCheckboxOptions \| undefined` | `undefined` | Custom content for the checkbox in `checked` mode. See [Custom checkbox](#custom-checkbox) |
 
 Switching `interactionMode` always clears the current selection.
 
@@ -140,7 +140,7 @@ By default the column contains a native `<input type="checkbox">`. The visible s
 
 ### Subtle style — `checkboxRenderer`
 
-Set `checkboxRenderer` to a function that returns a Lit template. The function receives the row's current `checked` state. This is what enables the *subtle* style: render an empty template when unchecked and a translucent mark when checked.
+Set `checkboxRenderer` to a function that returns a Lit template, or pass an options object for additional control. The function receives the row's current `checked` state. This is what enables the *subtle* style: render an empty template when unchecked and a translucent mark when checked.
 
 ```typescript
 import { html } from 'lit';
@@ -160,6 +160,33 @@ list.checkboxRenderer = (checked) => checked
   : html``;
 ```
 
+#### Using `CustomCheckboxOptions`
+
+Pass an options object to also control the checkbox column's `margin` and `width`:
+
+```typescript
+import type { CustomCheckboxOptions } from '@ixfx/components';
+
+list.checkboxRenderer = {
+  renderer: (checked) => checked
+    ? html`<svg viewBox="0 0 16 16" width="14" height="14"
+          fill="none" stroke="currentColor" stroke-width="2"
+          stroke-linecap="round" stroke-linejoin="round"
+          style="opacity:0.5">
+        <polyline points="3,8 7,12 13,4" />
+      </svg>`
+    : html``,
+  margin: `0 6px 0 0`,  // left margin for the checkbox column (default: `0`)
+  width: `24px`,         // width of the checkbox column (default: `24px`)
+} satisfies CustomCheckboxOptions;
+```
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `renderer` | `(checked: boolean) => unknown` | — | Required. Returns the Lit template to render inside the checkbox cell |
+| `margin` | `string` | `0` | CSS margin for the checkbox column (e.g. `"0 6px 0 0"`) |
+| `width` | `string` | `24px` | Width of the checkbox column |
+
 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.
 
 ### How it works under the hood

package/package.json

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

package/dist/button-DxYee1ZH.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"button-DxYee1ZH.js","names":["customElement"],"sources":["../src/button/button-styles.ts","../src/button/button.ts"],"sourcesContent":["import { css } from 'lit';\n\nexport const buttonStyles = css`\n  :host {\n    display: inline-flex;\n    max-width: 100%;\n    vertical-align: middle;\n    user-select: none;\n    -webkit-user-select: none;\n  }\n\n  button {\n    cursor: pointer;\n    appearance: none;\n    background: var(--surface-4, #ccc);\n    color: var(--surface-3-text, #000);\n    border: var(--border, 1px solid #999);\n    border-radius: var(--radius-xl, 8px);\n    corner-shape: superellipse(1);\n    padding: var(--space-m, 8px) var(--space-l, 12px);\n    font-family: var(--font-family, inherit);\n    font-size: var(--text-m, 14px);\n    margin: 0;\n    display: inline-flex;\n    align-items: center;\n    justify-content: center;\n    gap: 0.5em;\n    width: 100%;\n    overflow: hidden;\n    white-space: nowrap;\n    box-shadow: \n      inset 1px 1px 1px 1px color-mix(in oklch, var(--surface-4) 30%, transparent), inset -1px -1px 1px 1px color-mix(in oklch, var(--surface-2) 20%, transparent),\n      2px 2px 1px 0px color-mix(in oklch, var(--surface-2) 30%, transparent);\n    transition: background var(--transition, 0.2s), border-color var(--transition, 0.2s);\n  }\n\n  button:disabled {\n    opacity: 0.5;\n    cursor: not-allowed;\n  }\n\n  button:hover:not(:disabled) {\n    background: color-mix(in oklch, var(--surface-4) 80%, transparent);\n    border-color: var(--accent, #666);\n    box-shadow: \n      inset 1px 1px 1px 1px color-mix(in oklch, var(--surface-5) 70%, transparent), \n      inset -1px -1px 1px 1px color-mix(in oklch, var(--surface-2) 60%, transparent),\n      2px 2px 1px 0px color-mix(in oklch, var(--surface-2) 90%, transparent);\n  }\n\n  button:active:not(:disabled) {\n    background: var(--surface-2, #aaa);\n    transform: translateY(1px);\n    box-shadow: inset 1px 1px 0px 0.5px color-mix(in oklch,var(--surface-1),transparent);\n  }\n\n  .button-icon {\n    display: var(--ixfx-button-hide-icon, inline-flex);\n    align-items: center;\n    flex-shrink: 0;\n  }\n\n  .button-label {\n    white-space: nowrap;\n    display: var(--ixfx-button-hide-label, inline);\n  }\n\n  :host([hide-label]) .button-label {\n    display: none;\n  }\n\n  :host([hide-icon]) .button-icon {\n    display: none;\n  }\n`;\n","import { html, LitElement, nothing } from \"lit\";\nimport { property } from \"lit/decorators.js\";\nimport { unsafeHTML } from \"lit/directives/unsafe-html.js\";\nimport { getIcon } from \"../icons/index.js\";\nimport { prominenceStyles } from \"../styles/prominence.js\";\nimport { safeCustomElement as customElement } from \"../util/custom-elements.js\";\nimport { buttonStyles } from \"./button-styles.js\";\n\n@customElement(`ixfx-button`)\nexport class ButtonElement extends LitElement {\n  @property({ type: Boolean })\n  disabled = false;\n\n  @property({ type: String })\n  icon?: string;\n\n  @property({ type: Boolean, attribute: `hide-icon`, reflect: true })\n  hideIcon = false;\n\n  @property({ type: Boolean, attribute: `hide-label`, reflect: true })\n  hideLabel = false;\n\n  protected _renderIcon() {\n    if (this.hideIcon || !this.icon)\n      return nothing;\n\n    if (this.icon.startsWith(`<svg`)) {\n      return html`<span class=\"button-icon\">${unsafeHTML(this.icon)}</span>`;\n    }\n\n    const svg = getIcon(this.icon);\n\n    if (!svg)\n      return nothing;\n\n    return html`<ixfx-icon class=\"button-icon\" name=\"${this.icon}\"></ixfx-icon>`;\n  }\n\n  protected render() {\n    const label = this.hideLabel\n      ? nothing\n      : html`<span class=\"button-label\"><slot></slot></span>`;\n    return html`<button ?disabled=${this.disabled}>${this._renderIcon()}${label}</button>`;\n  }\n\n  static styles = [\n    prominenceStyles,\n    buttonStyles,\n  ];\n}\n\ndeclare global {\n  interface HTMLElementTagNameMap {\n    \"ixfx-button\": ButtonElement;\n  }\n}\n"],"mappings":";;;;;;;;AAEA,MAAa,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACOxB,IAAM,gBAAN,MAAM,sBAAsB,WAAW;;;EAEjC,KAAA,WAAA;EAMA,KAAA,WAAA;EAGC,KAAA,YAAA;;CAEZ,cAAwB;EACtB,IAAI,KAAK,YAAY,CAAC,KAAK,MACzB,OAAO;EAET,IAAI,KAAK,KAAK,WAAW,MAAM,GAC7B,OAAO,IAAI,6BAA6B,WAAW,KAAK,IAAI,EAAE;EAKhE,IAAI,CAFQ,QAAQ,KAAK,IAElB,GACL,OAAO;EAET,OAAO,IAAI,wCAAwC,KAAK,KAAK;CAC/D;CAEA,SAAmB;EACjB,MAAM,QAAQ,KAAK,YACf,UACA,IAAI;EACR,OAAO,IAAI,qBAAqB,KAAK,SAAS,GAAG,KAAK,YAAY,IAAI,MAAM;CAC9E;;EAEgB,KAAA,SAAA,CACd,kBACA,YACF;;AACF;AAvCG,WAAA,CAAA,SAAS,EAAE,MAAM,QAAQ,CAAC,CAAA,GAAA,cAAA,WAAA,YAAA,KAAA,CAAA;AAG1B,WAAA,CAAA,SAAS,EAAE,MAAM,OAAO,CAAC,CAAA,GAAA,cAAA,WAAA,QAAA,KAAA,CAAA;AAGzB,WAAA,CAAA,SAAS;CAAE,MAAM;CAAS,WAAW;CAAa,SAAS;AAAK,CAAC,CAAA,GAAA,cAAA,WAAA,YAAA,KAAA,CAAA;AAGjE,WAAA,CAAA,SAAS;CAAE,MAAM;CAAS,WAAW;CAAc,SAAS;AAAK,CAAC,CAAA,GAAA,cAAA,WAAA,aAAA,KAAA,CAAA;AAXpEA,gBAAAA,WAAAA,CAAAA,kBAAc,aAAa,CAAA,GAAA,aAAA"}