@ixfx/components 0.5.5 → 0.5.7

package/docs-user/README.md

@@ -31,6 +31,7 @@ This directory contains documentation for each component and some architectural
 - [range-input](./range-input.md)
 - [selecthorizontal](./selecthorizontal.md)
 - [slider-input](./slider-input.md)
+- [snackbar](./snackbar.md)
 - [snap-container](./snap-container.md)
 - [split-layout](./split-layout.md)
 - [swipe](./swipe.md)

package/docs-user/button.md

@@ -15,6 +15,7 @@ Three related button components:
 <ixfx-button icon="check">Commit</ixfx-button>
 <ixfx-button icon="check" hide-label>Commit</ixfx-button>
 <ixfx-button disabled>Unavailable</ixfx-button>
+<ixfx-button subtle>Subtle</ixfx-button>
 ```
 
 ### Properties / attributes
@@ -25,6 +26,7 @@ Three related button components:
 | `icon`              | string  | —       | Registered icon name **or** raw `<svg>` string     |
 | `hide-icon`         | boolean | `false` | Hides the icon even when `icon` is set             |
 | `hide-label`        | boolean | `false` | Hides the text label (useful for icon-only buttons)|
+| `subtle`            | boolean | `false` | Renders the background at 40% opacity, raised to 70% on hover/focus |
 
 ### Slots
 

package/docs-user/snackbar.md

@@ -0,0 +1,94 @@
+# Snackbar
+
+A small floating toolbar anchored in visual proximity to another element on the page (the "target"), built on the native Popover and CSS Anchor Positioning APIs.
+
+```html
+<ixfx-snackbar for="something">
+  <button>Bold</button>
+</ixfx-snackbar>
+<div id="something">Hello</div>
+```
+
+The user sees "Hello". Clicking it shows the snackbar's toolbar anchored above it.
+
+---
+
+## `ixfx-snackbar`
+
+Unlike `ixfx-menu-trigger` / `ixfx-colour-picker-popup`, the trigger is not slotted content inside the component — it's an external element referenced by `for`. The host element itself is the popover (`popover="auto"`); there's no inner wrapper div, since the entire slotted content is the panel.
+
+### Properties / attributes
+
+| Attribute / Property | Type | Default | Description |
+|---|---|---|---|
+| `for` | string | `''` | `id` of the target element to anchor to and attach interaction listeners on |
+| `mode` | `'explicit'` \| `'manual'` \| `'implicit'` | `'explicit'` | How the snackbar is invoked (see below) |
+| `placement` | `'top'` \| `'bottom'` \| `'left'` \| `'right'` | `'top'` | Which side of the target the panel appears on; reflected attribute |
+| `dismiss` | `'auto'` \| `'manual'` | `'auto'` | Whether a click bubbling up from inside the snackbar closes it (see below) |
+| `show-delay` | number (ms) | `150` | `implicit` mode only — debounce before showing once the target/panel is tickled |
+| `hide-delay` | number (ms) | `500` | `implicit` mode only — delay before auto-hiding once the target/panel is no longer tickled |
+
+### Modes
+
+| Mode | Behavior |
+|---|---|
+| `explicit` | Clicking the target toggles the snackbar. If the target has no existing `tabindex`/focusability, `tabindex="0"` and `role="button"` are added so it's keyboard-operable too (removed again if `for` changes or the component disconnects). |
+| `implicit` | Hovering or focusing the target shows the snackbar after `show-delay` ms (cancelled if the pointer/focus leaves before then, so a quick pass-over doesn't open it); it auto-hides `hide-delay` ms after the pointer/focus leaves, unless the pointer enters or focus moves into the panel itself first. |
+| `manual` | No automatic listeners are attached to the target at all — only `.show()` / `.hide()` / `.toggle()` calls open or close it. |
+
+In all three modes, native popover light-dismiss still applies: Escape or clicking outside closes the snackbar.
+
+Only one `ixfx-snackbar` is ever open at a time on a page, regardless of how each was invoked — this comes for free from `popover="auto"` (every unrelated auto popover is closed as part of the platform's "show popover" algorithm whenever a new one shows), not from any bookkeeping in this component.
+
+### Dismiss
+
+| `dismiss` | Behavior |
+|---|---|
+| `auto` (default) | Any `click` event that bubbles up from inside the snackbar (e.g. clicking a toolbar button) closes it — the common "pick an action, panel closes" pattern. A control that needs to stay open after being clicked can call `event.stopPropagation()`. |
+| `manual` | Clicks inside the snackbar are ignored; it's only closed by calling `.hide()` (or native light-dismiss — Escape / click-outside). |
+
+This is independent of `mode` — it governs how the snackbar closes, not how it opens.
+
+### Methods
+
+- `show()`, `hide()`, `toggle()` — thin wrappers over the native `showPopover()`/`hidePopover()`/`togglePopover()`.
+
+Because the popover is `auto`, clicking outside (or pressing Escape) closes it *before* the click that triggered the dismissal dispatches. `toggle()` accounts for this: if a light-dismiss close happened in the same click, the toggle is a no-op rather than immediately re-opening the snackbar — so a target/button that calls `.toggle()` still works as an open/close switch even though the trigger lives outside the popover.
+
+### Getters
+
+- `isOpen: boolean`
+
+### Slots
+
+| Slot | Description |
+|---|---|
+| default | Toolbar content (buttons, etc.), laid out as a flex row |
+
+### Events
+
+No custom events. Because the host itself is the popover, the native `toggle` (`ToggleEvent`) fires directly on `ixfx-snackbar`:
+
+```js
+document.querySelector('ixfx-snackbar').addEventListener('toggle', e => {
+  console.log(e.newState); // 'open' | 'closed'
+});
+```
+
+### CSS custom properties
+
+Visual chrome comes from `popupSurfaceStyles` (shared with `ixfx-menu-trigger` / `ixfx-colour-picker-popup`):
+
+| Property | Description |
+|---|---|
+| `--surface-5` | Background |
+| `--surface-6` | Border color |
+| `--surface-5-text` | Text color |
+| `--shadow-m` | Drop shadow |
+| `--radius-l` | Corner radius |
+| `--space-s` | Padding / gap between slotted items and between panel and target |
+
+### Constraints
+
+- The target element referenced by `for` must exist in the DOM (by `id`, resolved against `getRootNode()`) whenever `for` is set or changes — there's no polling/observation for a target that appears later.
+- In `implicit` mode, the target must already be focusable for the focus-triggered (keyboard) path to work; `ixfx-snackbar` only auto-adds `tabindex`/`role` in `explicit` mode.

package/package.json

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

package/dist/button-CTE8crYn.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"button-CTE8crYn.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    outline: var(--ixfx-button-outline, none);\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      var(--ixfx-button-shade, none),\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"}

package/dist/icon-DpA9x2Ve.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"icon-DpA9x2Ve.d.ts","names":[],"sources":["../src/icons/icon.ts"],"mappings":";;;;;;;;;;;;;cAoBa,wBAAwB;;EACvB;EACgB;EAChB;EAC0C;EACU;EAQvD;EAKA;YAKU,iBAAM,wBAAA;YAgBN,QAAQ,SAAS;SAWpB,sBAAM;;QAsChB;YACI;IACR,aAAa"}

package/dist/popup-DiWMxsWj.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"popup-DiWMxsWj.js","names":[],"sources":["../src/styles/popup.ts"],"sourcesContent":["import { css } from \"lit\";\n\n/**\n * Canonical surface styles for floating popup elements (menus, dropdowns,\n * colour picker, tooltips). Apply by adding `popupSurfaceStyles` to a\n * component's `static styles` array and the class `popup-surface` to the\n * popup container element.\n *\n * Intentionally omitted (remain per-component): positioning, padding,\n * dimensions, z-index, and open/close animations.\n */\nexport const popupSurfaceStyles = css`\n  .popup-surface {\n    background: var(--surface-5);\n    border: 1px solid var(--surface-6);\n    border-radius: var(--radius-l);\n    box-shadow: var(--shadow-m);\n    color: var(--surface-5-text);\n  }\n`;\n"],"mappings":";;;;;;;;;;;AAWA,MAAa,qBAAqB,GAAG"}