@boostdev/design-system-components 1.0.3 → 1.1.1

package/src/web-components/interaction/bds-popover.ts

@@ -0,0 +1,229 @@
+import { LitElement, css, html } from 'lit';
+
+export type PopoverPlacement = 'bottom' | 'top' | 'left' | 'right';
+
+/**
+ * `<bds-popover>` — framework-agnostic Popover custom element.
+ *
+ * Uses CSS Anchor Positioning within the shadow DOM so the panel stays
+ * anchored to the trigger and automatically repositions when it would
+ * overflow the viewport (`@position-try` fallbacks).
+ *
+ * Attributes:
+ *   placement — "bottom" (default) | "top" | "left" | "right"
+ *   open      — boolean; reflects whether the panel is visible
+ *
+ * Slots:
+ *   trigger   — the element that opens/closes the panel on click
+ *   (default) — panel content
+ *
+ * Events:
+ *   bds-open  — fired (bubbles, composed) when the panel opens
+ *   bds-close — fired (bubbles, composed) when the panel closes
+ *
+ * @example
+ * <bds-popover placement="bottom">
+ *   <button slot="trigger">Open</button>
+ *   <p>Panel content here</p>
+ * </bds-popover>
+ */
+export class BdsPopover extends LitElement {
+  static styles = css`
+    :host {
+      display: inline-flex;
+      position: relative;
+    }
+
+    /* The wrapper IS the CSS anchor — anchor-name resolves via the custom
+       property injected on :host in connectedCallback(), so each instance
+       gets its own unique name without colliding with siblings. */
+    .wrapper {
+      display: inline-flex;
+      anchor-name: var(--bds-popover-anchor);
+    }
+
+    .panel {
+      display: none;
+      position: absolute;
+      position-anchor: var(--bds-popover-anchor);
+      margin: 0;
+      overflow-y: auto;
+      z-index: var(--popover_z-index, 100);
+      min-width: 12rem;
+      padding: var(--bds-space_m);
+      border-radius: var(--bds-border_radius--s);
+      background-color: var(--popover_color, var(--bds-color_bg));
+      box-shadow: var(--popover_shadow, var(--bds-shadow_m));
+      color: var(--popover_on-color, var(--bds-color_on-bg));
+      font-size: var(--bds-font_size--body);
+    }
+
+    .panel.open {
+      display: block;
+    }
+
+    /* Primary placements */
+
+    .panel[data-placement='bottom'] {
+      top: anchor(bottom);
+      left: anchor(left);
+      margin-top: var(--bds-space_xs, 8px);
+      position-try-fallbacks: --bds-popover-top, --bds-popover-right, --bds-popover-left;
+    }
+
+    .panel[data-placement='top'] {
+      bottom: anchor(top);
+      left: anchor(left);
+      margin-bottom: var(--bds-space_xs, 8px);
+      position-try-fallbacks: --bds-popover-bottom, --bds-popover-right, --bds-popover-left;
+    }
+
+    .panel[data-placement='right'] {
+      top: anchor(top);
+      left: anchor(right);
+      margin-left: var(--bds-space_xs, 8px);
+      position-try-fallbacks: --bds-popover-left, --bds-popover-bottom, --bds-popover-top;
+    }
+
+    .panel[data-placement='left'] {
+      top: anchor(top);
+      right: anchor(left);
+      margin-right: var(--bds-space_xs, 8px);
+      position-try-fallbacks: --bds-popover-right, --bds-popover-bottom, --bds-popover-top;
+    }
+
+    /* Fallback placements */
+
+    @position-try --bds-popover-bottom {
+      top: anchor(bottom);
+      right: unset;
+      bottom: unset;
+      left: anchor(left);
+      margin: 0;
+      margin-top: var(--bds-space_xs, 8px);
+    }
+
+    @position-try --bds-popover-top {
+      top: unset;
+      right: unset;
+      bottom: anchor(top);
+      left: anchor(left);
+      margin: 0;
+      margin-bottom: var(--bds-space_xs, 8px);
+    }
+
+    @position-try --bds-popover-right {
+      top: anchor(top);
+      right: unset;
+      bottom: unset;
+      left: anchor(right);
+      margin: 0;
+      margin-left: var(--bds-space_xs, 8px);
+    }
+
+    @position-try --bds-popover-left {
+      top: anchor(top);
+      right: anchor(left);
+      bottom: unset;
+      left: unset;
+      margin: 0;
+      margin-right: var(--bds-space_xs, 8px);
+    }
+  `;
+
+  static properties = {
+    placement: { type: String, reflect: true },
+    open:      { type: Boolean, reflect: true },
+  };
+
+  declare placement: PopoverPlacement;
+  declare open: boolean;
+
+  private _anchorName: string;
+
+  constructor() {
+    super();
+    this.placement = 'bottom';
+    this.open = false;
+    const uid = Math.random().toString(36).slice(2, 8);
+    this._anchorName = `--bds-popover-${uid}`;
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    // Inject the unique anchor-name as a CSS custom property so both
+    // `.wrapper` (anchor-name) and `.panel` (position-anchor) reference
+    // the same value without hard-coding it in the shared static styles.
+    this.style.setProperty('--bds-popover-anchor', this._anchorName);
+    document.addEventListener('keydown', this._onKeydown);
+    document.addEventListener('mousedown', this._onOutsideClick);
+    // Invoker Commands API — host is in light DOM so commandfor can reference its id.
+    this.addEventListener('command', this._onCommand);
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    document.removeEventListener('keydown', this._onKeydown);
+    document.removeEventListener('mousedown', this._onOutsideClick);
+    this.removeEventListener('command', this._onCommand);
+  }
+
+  private _onKeydown = (e: KeyboardEvent) => {
+    if (this.open && e.key === 'Escape') this._close();
+  };
+
+  private _onCommand = (e: Event) => {
+    const command = (e as CommandEvent).command;
+    if (command === '--toggle') this._toggle();
+    else if (command === '--open') this._open();
+    else if (command === '--close') this._close();
+  };
+
+  private _onOutsideClick = (e: MouseEvent) => {
+    if (this.open && !this.contains(e.target as Node)) this._close();
+  };
+
+  private _toggle() {
+    if (this.open) {
+      this._close();
+    } else {
+      this._open();
+    }
+  }
+
+  private _open() {
+    if (this.open) return;
+    this.open = true;
+    this.dispatchEvent(new CustomEvent('bds-open', { bubbles: true, composed: true }));
+  }
+
+  private _close() {
+    if (!this.open) return;
+    this.open = false;
+    this.dispatchEvent(new CustomEvent('bds-close', { bubbles: true, composed: true }));
+  }
+
+  render() {
+    return html`
+      <span class="wrapper">
+        <slot name="trigger" @click=${this._toggle}></slot>
+      </span>
+      <div
+        class="panel ${this.open ? 'open' : ''}"
+        data-placement=${this.placement}
+        role="region"
+        aria-label="Popover"
+      >
+        <slot></slot>
+      </div>
+    `;
+  }
+}
+
+customElements.define('bds-popover', BdsPopover);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'bds-popover': BdsPopover;
+  }
+}

package/src/web-components/interaction/bds-toast-provider.spec.ts

@@ -0,0 +1,122 @@
+import { fixture, cleanup } from '../test/helpers';
+import { BdsToastProvider } from './bds-toast-provider';
+
+describe('bds-toast-provider', () => {
+  it('is registered as a custom element', () => {
+    expect(customElements.get('bds-toast-provider')).toBe(BdsToastProvider);
+  });
+
+  it('renders a popover="manual" container in shadow DOM', async () => {
+    const el = await fixture('<bds-toast-provider></bds-toast-provider>');
+    const container = el.shadowRoot!.querySelector('[popover]');
+    expect(container).not.toBeNull();
+    expect(container!.getAttribute('popover')).toBe('manual');
+    cleanup(el);
+  });
+
+  it('container has role="region" and aria-label="Notifications"', async () => {
+    const el = await fixture('<bds-toast-provider></bds-toast-provider>');
+    const container = el.shadowRoot!.querySelector('[popover="manual"]');
+    expect(container!.getAttribute('role')).toBe('region');
+    expect(container!.getAttribute('aria-label')).toBe('Notifications');
+    cleanup(el);
+  });
+
+  it('shows no toasts initially', async () => {
+    const el = await fixture('<bds-toast-provider></bds-toast-provider>');
+    const toasts = el.shadowRoot!.querySelectorAll('.toast');
+    expect(toasts.length).toBe(0);
+    cleanup(el);
+  });
+
+  it('showToast adds a toast to the shadow DOM', async () => {
+    const el = await fixture('<bds-toast-provider></bds-toast-provider>') as BdsToastProvider;
+    el.showToast('Hello toast', 'info');
+    await el.updateComplete;
+    const toasts = el.shadowRoot!.querySelectorAll('.toast');
+    expect(toasts.length).toBe(1);
+    expect(toasts[0].querySelector('.message')!.textContent).toBe('Hello toast');
+    cleanup(el);
+  });
+
+  it('applies the correct variant class', async () => {
+    const el = await fixture('<bds-toast-provider></bds-toast-provider>') as BdsToastProvider;
+    el.showToast('Success!', 'success');
+    await el.updateComplete;
+    const toast = el.shadowRoot!.querySelector('.toast');
+    expect(toast!.classList.contains('--variant_success')).toBe(true);
+    cleanup(el);
+  });
+
+  it('dismiss button click removes the toast', async () => {
+    const el = await fixture('<bds-toast-provider></bds-toast-provider>') as BdsToastProvider;
+    el.showToast('Dismiss me', 'info');
+    await el.updateComplete;
+    const btn = el.shadowRoot!.querySelector<HTMLButtonElement>('.close')!;
+    btn.dispatchEvent(new MouseEvent('click', { bubbles: true, composed: true }));
+    await el.updateComplete;
+    expect(el.shadowRoot!.querySelectorAll('.toast').length).toBe(0);
+    cleanup(el);
+  });
+
+  it('auto-removes the toast after 5 seconds', async () => {
+    vi.useFakeTimers();
+    const el = await fixture('<bds-toast-provider></bds-toast-provider>') as BdsToastProvider;
+    el.showToast('Timed out', 'warning');
+    await el.updateComplete;
+    expect(el.shadowRoot!.querySelectorAll('.toast').length).toBe(1);
+    vi.advanceTimersByTime(5100);
+    await el.updateComplete;
+    expect(el.shadowRoot!.querySelectorAll('.toast').length).toBe(0);
+    vi.useRealTimers();
+    cleanup(el);
+  });
+
+  it('static BdsToastProvider.show() adds a toast via the first provider', async () => {
+    const el = await fixture('<bds-toast-provider></bds-toast-provider>') as BdsToastProvider;
+    BdsToastProvider.show('Static show', 'error');
+    await el.updateComplete;
+    const toast = el.shadowRoot!.querySelector('.toast');
+    expect(toast).not.toBeNull();
+    expect(toast!.querySelector('.message')!.textContent).toBe('Static show');
+    cleanup(el);
+  });
+
+  it('bds-show-toast document event adds a toast', async () => {
+    const el = await fixture('<bds-toast-provider></bds-toast-provider>') as BdsToastProvider;
+    document.dispatchEvent(
+      new CustomEvent('bds-show-toast', { detail: { message: 'Event toast', variant: 'success' } }),
+    );
+    await el.updateComplete;
+    const toast = el.shadowRoot!.querySelector('.toast');
+    expect(toast).not.toBeNull();
+    expect(toast!.querySelector('.message')!.textContent).toBe('Event toast');
+    cleanup(el);
+  });
+
+  it('showToast defaults variant to info when not specified', async () => {
+    const el = await fixture('<bds-toast-provider></bds-toast-provider>') as BdsToastProvider;
+    el.showToast('No variant');
+    await el.updateComplete;
+    const toast = el.shadowRoot!.querySelector('.toast');
+    expect(toast!.classList.contains('--variant_info')).toBe(true);
+    cleanup(el);
+  });
+
+  it('bds-show-toast event with no message is a no-op', async () => {
+    const el = await fixture('<bds-toast-provider></bds-toast-provider>') as BdsToastProvider;
+    document.dispatchEvent(new CustomEvent('bds-show-toast', { detail: {} }));
+    await el.updateComplete;
+    expect(el.shadowRoot!.querySelectorAll('.toast').length).toBe(0);
+    cleanup(el);
+  });
+
+  it('multiple toasts stack in the container', async () => {
+    const el = await fixture('<bds-toast-provider></bds-toast-provider>') as BdsToastProvider;
+    el.showToast('First', 'info');
+    el.showToast('Second', 'success');
+    await el.updateComplete;
+    expect(el.shadowRoot!.querySelectorAll('.toast').length).toBe(2);
+    cleanup(el);
+  });
+});

package/src/web-components/interaction/bds-toast-provider.ts

@@ -0,0 +1,211 @@
+import { LitElement, css, html } from 'lit';
+
+export type ToastVariant = 'success' | 'error' | 'info' | 'warning';
+
+interface ToastEntry {
+  id: string;
+  message: string;
+  variant: ToastVariant;
+}
+
+/**
+ * `<bds-toast-provider>` — framework-agnostic Toast provider custom element.
+ *
+ * Wraps page content and manages a `popover="manual"` toast container that
+ * renders in the browser top layer — above all fixed/sticky elements without
+ * needing a z-index.
+ *
+ * Usage:
+ *   // Instance method (direct reference)
+ *   provider.showToast('Saved!', 'success');
+ *
+ *   // Static convenience (finds the first provider in the DOM)
+ *   BdsToastProvider.show('Something went wrong', 'error');
+ *
+ *   // Event-driven (no import required)
+ *   document.dispatchEvent(new CustomEvent('bds-show-toast', {
+ *     detail: { message: 'Hello', variant: 'info' }
+ *   }));
+ *
+ * Slots:
+ *   (default) — page content; the host uses display:contents so layout
+ *               is unaffected
+ *
+ * @example
+ * <bds-toast-provider>
+ *   <main>…</main>
+ * </bds-toast-provider>
+ */
+export class BdsToastProvider extends LitElement {
+  static styles = css`
+    :host {
+      display: contents;
+    }
+
+    .container {
+      /* Reset UA popover defaults */
+      position: fixed;
+      inset: unset;
+      bottom: var(--bds-space_xl, 2rem);
+      right: var(--bds-space_xl, 2rem);
+      display: flex;
+      flex-direction: column;
+      gap: var(--bds-space_m, 1rem);
+      border: none;
+      padding: 0;
+      background: transparent;
+    }
+
+    .toast {
+      padding: var(--bds-space_m) var(--bds-space_l);
+      background-color: var(--toast_color, var(--bds-color_bg));
+      color: var(--toast_on-color, var(--bds-color_on-bg));
+      border-radius: var(--bds-border_radius--s);
+      box-shadow: var(--bds-shadow_s);
+      display: flex;
+      align-items: center;
+      gap: var(--bds-space_m);
+      min-width: 300px;
+    }
+
+    .toast.--variant_success {
+      --toast_color:    var(--bds-color_success);
+      --toast_on-color: var(--bds-color_on-success);
+    }
+
+    .toast.--variant_warning {
+      --toast_color:    var(--bds-color_warning);
+      --toast_on-color: var(--bds-color_on-warning);
+    }
+
+    .toast.--variant_info {
+      --toast_color:    var(--bds-color_bg--subtle);
+      --toast_on-color: var(--bds-color_on-bg--subtle);
+    }
+
+    .toast.--variant_error {
+      --toast_color:    var(--bds-color_error);
+      --toast_on-color: var(--bds-color_on-error);
+    }
+
+    .message {
+      flex: 1;
+    }
+
+    .close {
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      flex-shrink: 0;
+      width: 1.25rem;
+      height: 1.25rem;
+      padding: 0;
+      background: none;
+      border: none;
+      cursor: pointer;
+      color: var(--toast_on-color);
+    }
+
+    .close svg {
+      width: 1rem;
+      height: 1rem;
+    }
+  `;
+
+  static properties = {
+    _toasts: { state: true },
+  };
+
+  declare private _toasts: ToastEntry[];
+
+  constructor() {
+    super();
+    this._toasts = [];
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    document.addEventListener('bds-show-toast', this._onShowToastEvent);
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    document.removeEventListener('bds-show-toast', this._onShowToastEvent);
+  }
+
+  // Sync the popover's top-layer visibility with the toast queue —
+  // mirrors Toast.tsx's useEffect([toasts.length]).
+  updated() {
+    const container = this.shadowRoot?.querySelector<HTMLElement & {
+      showPopover?: () => void;
+      hidePopover?: () => void;
+    }>('[popover]');
+    if (!container) return;
+    if (this._toasts.length > 0) {
+      container.showPopover?.();
+    } else {
+      try { container.hidePopover?.(); } catch { /* already hidden on initial mount */ }
+    }
+  }
+
+  showToast(message: string, variant: ToastVariant = 'info') {
+    const id = Math.random().toString(36).slice(2, 9);
+    this._toasts = [...this._toasts, { id, message, variant }];
+    setTimeout(() => this._removeToast(id), 5000);
+  }
+
+  private _removeToast(id: string) {
+    this._toasts = this._toasts.filter(t => t.id !== id);
+  }
+
+  private _onShowToastEvent = (e: Event) => {
+    const { message, variant } = (e as CustomEvent<{ message: string; variant?: ToastVariant }>).detail ?? {};
+    if (message) this.showToast(message, variant);
+  };
+
+  static show(message: string, variant?: ToastVariant) {
+    const provider = document.querySelector<BdsToastProvider>('bds-toast-provider');
+    provider?.showToast(message, variant ?? 'info');
+  }
+
+  render() {
+    return html`
+      <slot></slot>
+      <div
+        popover="manual"
+        role="region"
+        aria-label="Notifications"
+        class="container"
+      >
+        ${this._toasts.map(t => html`
+          <div
+            class="toast --variant_${t.variant}"
+            role="status"
+            aria-live="polite"
+            aria-atomic="true"
+          >
+            <span class="message">${t.message}</span>
+            <button
+              type="button"
+              class="close"
+              @click=${() => this._removeToast(t.id)}
+              aria-label="Dismiss"
+            >
+              <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                <path stroke-linecap="round" stroke-linejoin="round" d="M18 6L6 18M6 6l12 12" />
+              </svg>
+            </button>
+          </div>
+        `)}
+      </div>
+    `;
+  }
+}
+
+customElements.define('bds-toast-provider', BdsToastProvider);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'bds-toast-provider': BdsToastProvider;
+  }
+}

package/src/web-components/test/helpers.ts

@@ -0,0 +1,22 @@
+/** Render an HTML string, upgrade the custom element, and await first paint. */
+export async function fixture(html: string): Promise<HTMLElement> {
+  const template = document.createElement('template');
+  template.innerHTML = html;
+  const el = template.content.firstElementChild as HTMLElement;
+  document.body.appendChild(el);
+  await (el as unknown as { updateComplete: Promise<void> }).updateComplete;
+  return el;
+}
+
+/** Remove an element from the document after a test. */
+export function cleanup(el: HTMLElement) {
+  el.remove();
+}
+
+/** Create a synthetic Invoker Commands API `command` event for testing. */
+export function makeCommandEvent(command: string): Event {
+  const event = new Event('command', { bubbles: false, cancelable: true });
+  Object.defineProperty(event, 'command', { value: command, configurable: true });
+  Object.defineProperty(event, 'source', { value: null, configurable: true });
+  return event;
+}

package/src/web-components/ui/BdsAlert.mdx

@@ -0,0 +1,90 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsAlert.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-alert&gt;
+
+Framework-agnostic alert custom element for inline status messages. Supports four semantic variants, an optional title, and a dismissible mode.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## Examples
+
+### All variants
+<Canvas of={Stories.AllVariants} />
+
+### Info
+<Canvas of={Stories.Info} />
+
+### Success
+<Canvas of={Stories.Success} />
+
+### Warning
+<Canvas of={Stories.Warning} />
+
+### Error
+<Canvas of={Stories.Error} />
+
+### With title
+<Canvas of={Stories.WithTitle} />
+
+### Dismissible
+<Canvas of={Stories.Dismissible} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `variant` | `"info" \| "success" \| "warning" \| "error"` | `"info"` | Semantic colour and icon |
+| `title` | string | — | Optional heading displayed above body content |
+| `dismissible` | boolean | `false` | Shows a dismiss (×) button |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `(default)` | Alert body text or content |
+| `icon` | Custom icon, placed left of the content area |
+
+## Events
+
+| Event | Detail | Bubbles | Composed | Description |
+|-------|--------|---------|----------|-------------|
+| `bds-dismiss` | — | Yes | Yes | Fired when the dismiss button is clicked |
+
+## Usage in plain HTML
+
+```html
+<bds-alert variant="success" title="Saved">
+  Your changes have been saved successfully.
+</bds-alert>
+
+<bds-alert variant="error" dismissible>
+  Something went wrong. Please try again.
+</bds-alert>
+```
+
+Listen for dismiss:
+
+```js
+document.querySelector('bds-alert').addEventListener('bds-dismiss', () => {
+  // remove or hide the element
+});
+```
+
+## Accessibility
+
+- `error` and `warning` use `role="alert"` + `aria-live="assertive"` — content is announced immediately
+- `info` and `success` use `role="status"` + `aria-live="polite"` — content is announced at the next opportunity
+- The dismiss button has an accessible label; do not rely solely on its icon