@boostdev/design-system-components 1.0.3 → 1.1.0

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

@@ -0,0 +1,217 @@
+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);
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    document.removeEventListener('keydown', this._onKeydown);
+    document.removeEventListener('mousedown', this._onOutsideClick);
+  }
+
+  private _onKeydown = (e: KeyboardEvent) => {
+    if (this.open && e.key === 'Escape') 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() {
+    this.open = true;
+    this.dispatchEvent(new CustomEvent('bds-open', { bubbles: true, composed: true }));
+  }
+
+  private _close() {
+    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,14 @@
+/** 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();
+}

package/src/web-components/ui/BdsAlert.stories.tsx

@@ -0,0 +1,60 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import type { AlertVariant } from './bds-alert';
+import '../index'; // auto-registers all custom elements
+
+// Thin React wrapper so Storybook controls work with the custom element's props
+function BdsAlert({
+  variant = 'info',
+  title,
+  dismissible,
+  children,
+  onDismiss,
+}: {
+  variant?: AlertVariant;
+  title?: string;
+  dismissible?: boolean;
+  children?: React.ReactNode;
+  onDismiss?: () => void;
+}) {
+  return React.createElement(
+    'bds-alert',
+    { variant, title, dismissible: dismissible || undefined, onbdsdismiss: onDismiss },
+    children,
+  );
+}
+
+const meta = {
+  title: 'Web Components/UI/Alert',
+  component: BdsAlert,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'padded' },
+  argTypes: {
+    variant: { control: 'select', options: ['info', 'success', 'warning', 'error'] },
+  },
+} satisfies Meta<typeof BdsAlert>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Info: Story = { args: { children: 'This is an informational message.', variant: 'info' } };
+export const Success: Story = { args: { children: 'Your changes have been saved.', variant: 'success' } };
+export const Warning: Story = { args: { children: 'Please review before continuing.', variant: 'warning' } };
+export const Error: Story = { args: { children: 'Something went wrong.', variant: 'error' } };
+export const WithTitle: Story = {
+  args: { children: 'More details about the alert.', variant: 'info', title: 'Heads up' },
+};
+export const Dismissible: Story = {
+  args: { children: 'You can dismiss this alert.', variant: 'success', dismissible: true },
+};
+export const AllVariants: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '12px', maxWidth: 500 }}>
+      {(['info', 'success', 'warning', 'error'] as const).map(v => (
+        <BdsAlert key={v} variant={v} title={v.charAt(0).toUpperCase() + v.slice(1)}>
+          This is a {v} alert.
+        </BdsAlert>
+      ))}
+    </div>
+  ),
+};

package/src/web-components/ui/BdsBadge.stories.tsx

@@ -0,0 +1,37 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import type { BadgeVariant } from './bds-badge';
+import '../index'; // auto-registers all custom elements
+
+// Thin React wrapper so Storybook controls work with the custom element's props
+function BdsBadge({ variant = 'primary', children }: { variant?: BadgeVariant; children?: React.ReactNode }) {
+  return React.createElement('bds-badge', { variant }, children);
+}
+
+const meta = {
+  title: 'Web Components/UI/Badge',
+  component: BdsBadge,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+  argTypes: {
+    variant: { control: 'select', options: ['primary', 'secondary', 'success', 'error', 'warning'] },
+  },
+} satisfies Meta<typeof BdsBadge>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Primary: Story = { args: { children: 'Primary', variant: 'primary' } };
+export const Secondary: Story = { args: { children: 'Secondary', variant: 'secondary' } };
+export const Success: Story = { args: { children: 'Success', variant: 'success' } };
+export const Error: Story = { args: { children: 'Error', variant: 'error' } };
+export const Warning: Story = { args: { children: 'Warning', variant: 'warning' } };
+export const AllVariants: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: '8px', flexWrap: 'wrap' }}>
+      {(['primary', 'secondary', 'success', 'error', 'warning'] as const).map(v => (
+        <BdsBadge key={v} variant={v}>{v}</BdsBadge>
+      ))}
+    </div>
+  ),
+};