@boostdev/design-system-components 1.0.2 → 1.1.0

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>
+  ),
+};

package/src/web-components/ui/bds-alert.spec.ts

@@ -0,0 +1,109 @@
+import { fixture, cleanup } from '../test/helpers';
+import { BdsAlert } from './bds-alert';
+
+describe('bds-alert', () => {
+  it('is registered as a custom element', () => {
+    expect(customElements.get('bds-alert')).toBe(BdsAlert);
+  });
+
+  it('renders the alert container in shadow DOM', async () => {
+    const el = await fixture('<bds-alert>Message</bds-alert>');
+    const div = el.shadowRoot!.querySelector('.alert');
+    expect(div).not.toBeNull();
+    cleanup(el);
+  });
+
+  it('defaults to variant="info"', async () => {
+    const el = await fixture('<bds-alert>Message</bds-alert>');
+    expect(el.getAttribute('variant')).toBe('info');
+    cleanup(el);
+  });
+
+  it('sets role="status" and aria-live="polite" for info variant', async () => {
+    const el = await fixture('<bds-alert variant="info">Info</bds-alert>');
+    const div = el.shadowRoot!.querySelector('.alert');
+    expect(div!.getAttribute('role')).toBe('status');
+    expect(div!.getAttribute('aria-live')).toBe('polite');
+    cleanup(el);
+  });
+
+  it('sets role="status" and aria-live="polite" for success variant', async () => {
+    const el = await fixture('<bds-alert variant="success">Done</bds-alert>');
+    const div = el.shadowRoot!.querySelector('.alert');
+    expect(div!.getAttribute('role')).toBe('status');
+    expect(div!.getAttribute('aria-live')).toBe('polite');
+    cleanup(el);
+  });
+
+  it('sets role="alert" and aria-live="assertive" for error variant', async () => {
+    const el = await fixture('<bds-alert variant="error">Error</bds-alert>');
+    const div = el.shadowRoot!.querySelector('.alert');
+    expect(div!.getAttribute('role')).toBe('alert');
+    expect(div!.getAttribute('aria-live')).toBe('assertive');
+    cleanup(el);
+  });
+
+  it('sets role="alert" and aria-live="assertive" for warning variant', async () => {
+    const el = await fixture('<bds-alert variant="warning">Warning</bds-alert>');
+    const div = el.shadowRoot!.querySelector('.alert');
+    expect(div!.getAttribute('role')).toBe('alert');
+    expect(div!.getAttribute('aria-live')).toBe('assertive');
+    cleanup(el);
+  });
+
+  it('renders title when title attribute is set', async () => {
+    const el = await fixture('<bds-alert title="Heads up">Message</bds-alert>');
+    const strong = el.shadowRoot!.querySelector('strong.title');
+    expect(strong).not.toBeNull();
+    expect(strong!.textContent).toBe('Heads up');
+    cleanup(el);
+  });
+
+  it('does not render title element when title is not set', async () => {
+    const el = await fixture('<bds-alert>Message</bds-alert>');
+    const strong = el.shadowRoot!.querySelector('strong.title');
+    expect(strong).toBeNull();
+    cleanup(el);
+  });
+
+  it('does not render dismiss button by default', async () => {
+    const el = await fixture('<bds-alert>Message</bds-alert>');
+    const btn = el.shadowRoot!.querySelector('button.dismiss');
+    expect(btn).toBeNull();
+    cleanup(el);
+  });
+
+  it('renders dismiss button when dismissible is set', async () => {
+    const el = await fixture('<bds-alert dismissible>Message</bds-alert>');
+    const btn = el.shadowRoot!.querySelector('button.dismiss');
+    expect(btn).not.toBeNull();
+    expect(btn!.getAttribute('aria-label')).toBe('Dismiss alert');
+    cleanup(el);
+  });
+
+  it('fires bds-dismiss event when dismiss button is clicked', async () => {
+    const el = await fixture('<bds-alert dismissible>Message</bds-alert>');
+    const btn = el.shadowRoot!.querySelector('button.dismiss')!;
+    const handler = vi.fn();
+    el.addEventListener('bds-dismiss', handler);
+    btn.dispatchEvent(new MouseEvent('click', { bubbles: true, composed: true }));
+    expect(handler).toHaveBeenCalledOnce();
+    cleanup(el);
+  });
+
+  it('renders slotted body content in light DOM', async () => {
+    const el = await fixture('<bds-alert>Something went wrong</bds-alert>');
+    expect(el.textContent?.trim()).toBe('Something went wrong');
+    cleanup(el);
+  });
+
+  it('reflects variant property updates', async () => {
+    const el = await fixture('<bds-alert>Message</bds-alert>') as BdsAlert;
+    el.variant = 'warning';
+    await el.updateComplete;
+    expect(el.getAttribute('variant')).toBe('warning');
+    const div = el.shadowRoot!.querySelector('.alert');
+    expect(div!.getAttribute('role')).toBe('alert');
+    cleanup(el);
+  });
+});