@boostdev/design-system-components 1.0.3 → 1.1.1

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.mdx

@@ -0,0 +1,74 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsBadge.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-badge&gt;
+
+Framework-agnostic badge custom element for short status labels and counts. Five semantic variants covering the common status palette.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## Examples
+
+### All variants
+<Canvas of={Stories.AllVariants} />
+
+### Primary
+<Canvas of={Stories.Primary} />
+
+### Secondary
+<Canvas of={Stories.Secondary} />
+
+### Success
+<Canvas of={Stories.Success} />
+
+### Error
+<Canvas of={Stories.Error} />
+
+### Warning
+<Canvas of={Stories.Warning} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `variant` | `"primary" \| "secondary" \| "success" \| "error" \| "warning"` | `"primary"` | Semantic colour |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `(default)` | Badge label text |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--badge_bg` | Badge background colour |
+| `--badge_text` | Badge text colour |
+| `--badge_font-size` | Font size |
+| `--badge_radius` | Border radius |
+
+## Usage in plain HTML
+
+```html
+<bds-badge variant="success">Active</bds-badge>
+<bds-badge variant="error">3</bds-badge>
+<bds-badge variant="warning">Pending</bds-badge>
+```
+
+## Accessibility
+
+- Badge is a purely visual element — wrap in an element with `aria-label` when the colour alone conveys meaning (e.g. status indicators)
+- For count badges next to icon buttons, use `aria-label` on the parent: `aria-label="3 notifications"`

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

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

@@ -0,0 +1,209 @@
+import { LitElement, css, html, nothing } from 'lit';
+
+export type AlertVariant = 'info' | 'success' | 'warning' | 'error';
+
+/**
+ * `<bds-alert>` — framework-agnostic Alert custom element.
+ *
+ * Attributes:
+ *   variant     — "info" (default) | "success" | "warning" | "error"
+ *   title       — optional heading above the body text
+ *   dismissible — boolean; shows a dismiss button when present
+ *
+ * Slots:
+ *   (default) — alert body content
+ *   icon      — optional icon displayed to the left of the content
+ *
+ * Events:
+ *   bds-dismiss — fired (bubbles, composed) when the dismiss button is clicked
+ *
+ * Accessibility:
+ *   role="alert" + aria-live="assertive" for error/warning variants,
+ *   role="status" + aria-live="polite" for info/success variants.
+ *
+ * @example
+ * <bds-alert variant="success" title="Saved!">Your changes have been saved.</bds-alert>
+ *
+ * <bds-alert variant="error" dismissible>
+ *   <svg slot="icon">…</svg>
+ *   Something went wrong.
+ * </bds-alert>
+ */
+export class BdsAlert extends LitElement {
+  static styles = css`
+    :host {
+      display: block;
+    }
+
+    .alert {
+      display: flex;
+      align-items: flex-start;
+      gap: var(--bds-space_s);
+      padding: var(--bds-space_m);
+      border-radius: var(--bds-border_radius--s);
+      border-inline-start: var(--bds-space_s) solid var(--alert_border, var(--bds-color_blue));
+      background-color: var(--alert_bg, var(--bds-color_blue--subtle));
+      color: var(--alert_text, var(--bds-color_on-blue--subtle));
+      font-size: var(--bds-font_size--body);
+      line-height: var(--bds-font_line-height--body);
+    }
+
+    /* Variant colours */
+    :host([variant='info']) .alert {
+      --alert_bg:     var(--bds-color_blue--subtle);
+      --alert_text:   var(--bds-color_on-blue--subtle);
+      --alert_border: var(--bds-color_blue);
+    }
+
+    :host([variant='success']) .alert {
+      --alert_bg:     var(--bds-color_success--subtle);
+      --alert_text:   var(--bds-color_on-success--subtle);
+      --alert_border: var(--bds-color_success);
+    }
+
+    :host([variant='warning']) .alert {
+      --alert_bg:     var(--bds-color_orange--subtle);
+      --alert_text:   var(--bds-color_on-orange--subtle);
+      --alert_border: var(--bds-color_warning);
+    }
+
+    :host([variant='error']) .alert {
+      --alert_bg:     rgb(from var(--bds-color_error) r g b / 12%);
+      --alert_text:   var(--bds-color_on-bg);
+      --alert_border: var(--bds-color_error);
+    }
+
+    /* Icon slot wrapper — hidden unless slot has content */
+    .icon {
+      display: none;
+      align-items: center;
+      flex-shrink: 0;
+      margin-block-start: 0.1em;
+    }
+
+    .icon.has-content {
+      display: flex;
+    }
+
+    /* Content area */
+    .content {
+      flex: 1;
+      display: flex;
+      flex-direction: column;
+      gap: var(--bds-space_xxs);
+    }
+
+    .title {
+      font-weight: var(--bds-font_weight--semibold);
+      font-size: var(--bds-font_size--body);
+    }
+
+    /* Dismiss button */
+    .dismiss {
+      all: unset;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      flex-shrink: 0;
+      cursor: pointer;
+      color: currentcolor;
+      transition: var(--bds-animation_transition);
+      border-radius: 50%;
+      --bdc_color: currentcolor;
+      outline: var(--bdc-outline_width) solid var(--bdc_color);
+      outline-offset: var(--bdc-outline_offset);
+    }
+
+    .dismiss svg {
+      width: 1rem;
+      height: 1rem;
+    }
+
+    .dismiss:focus-visible {
+      outline: var(--bds-outline_default);
+      outline-offset: var(--bds-outline_offset);
+    }
+
+    @media (hover: hover) and (pointer: fine) {
+      .dismiss:hover {
+        opacity: 0.7;
+      }
+    }
+  `;
+
+  static properties = {
+    variant:     { type: String, reflect: true },
+    title:       { type: String },
+    dismissible: { type: Boolean, reflect: true },
+    _iconFilled: { state: true },
+  };
+
+  // `declare` annotates the type without emitting a class field initializer
+  // that would shadow Lit's reactive accessors on the prototype.
+  declare variant: AlertVariant;
+  declare title: string;
+  declare dismissible: boolean;
+  declare private _iconFilled: boolean;
+
+  constructor() {
+    super();
+    this.variant = 'info';
+    this.title = '';
+    this.dismissible = false;
+    this._iconFilled = false;
+  }
+
+  private _onIconSlotChange(e: Event) {
+    const slot = e.target as HTMLSlotElement;
+    this._iconFilled = slot.assignedNodes({ flatten: true }).length > 0;
+  }
+
+  private get _isUrgent() {
+    return this.variant === 'error' || this.variant === 'warning';
+  }
+
+  private _handleDismiss() {
+    this.dispatchEvent(new CustomEvent('bds-dismiss', { bubbles: true, composed: true }));
+  }
+
+  render() {
+    return html`
+      <div
+        class="alert"
+        role=${this._isUrgent ? 'alert' : 'status'}
+        aria-live=${this._isUrgent ? 'assertive' : 'polite'}
+        aria-atomic="true"
+      >
+        <span class="icon ${this._iconFilled ? 'has-content' : ''}" aria-hidden="true">
+          <slot name="icon" @slotchange=${this._onIconSlotChange}></slot>
+        </span>
+        <div class="content">
+          ${this.title ? html`<strong class="title">${this.title}</strong>` : nothing}
+          <div><slot></slot></div>
+        </div>
+        ${this.dismissible
+          ? html`
+              <button
+                type="button"
+                class="dismiss"
+                @click=${this._handleDismiss}
+                aria-label="Dismiss alert"
+              >
+                <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>
+            `
+          : nothing}
+      </div>
+    `;
+  }
+}
+
+customElements.define('bds-alert', BdsAlert);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'bds-alert': BdsAlert;
+  }
+}

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

@@ -0,0 +1,51 @@
+import { fixture, cleanup } from '../test/helpers';
+import { BdsBadge } from './bds-badge';
+
+describe('bds-badge', () => {
+  it('is registered as a custom element', () => {
+    expect(customElements.get('bds-badge')).toBe(BdsBadge);
+  });
+
+  it('renders a span.badge in shadow DOM', async () => {
+    const el = await fixture('<bds-badge>New</bds-badge>');
+    const span = el.shadowRoot!.querySelector('.badge');
+    expect(span).not.toBeNull();
+    cleanup(el);
+  });
+
+  it('defaults to variant="primary"', async () => {
+    const el = await fixture('<bds-badge>New</bds-badge>');
+    expect(el.getAttribute('variant')).toBe('primary');
+    cleanup(el);
+  });
+
+  it('reflects variant attribute', async () => {
+    const el = await fixture('<bds-badge variant="success">OK</bds-badge>');
+    expect(el.getAttribute('variant')).toBe('success');
+    cleanup(el);
+  });
+
+  it('updates variant property', async () => {
+    const el = await fixture('<bds-badge>Label</bds-badge>') as BdsBadge;
+    el.variant = 'error';
+    await el.updateComplete;
+    expect(el.getAttribute('variant')).toBe('error');
+    cleanup(el);
+  });
+
+  it('renders slotted text content', async () => {
+    const el = await fixture('<bds-badge>Hello</bds-badge>');
+    // Slotted content lives in light DOM
+    expect(el.textContent?.trim()).toBe('Hello');
+    cleanup(el);
+  });
+
+  it('accepts all valid variant values', async () => {
+    const variants = ['primary', 'secondary', 'success', 'error', 'warning'] as const;
+    for (const variant of variants) {
+      const el = await fixture(`<bds-badge variant="${variant}">Label</bds-badge>`);
+      expect(el.getAttribute('variant')).toBe(variant);
+      cleanup(el);
+    }
+  });
+});

package/src/web-components/ui/bds-badge.ts

@@ -0,0 +1,88 @@
+import { LitElement, css, html } from 'lit';
+
+export type BadgeVariant = 'primary' | 'secondary' | 'success' | 'error' | 'warning';
+
+/**
+ * `<bds-badge>` — framework-agnostic Badge custom element.
+ *
+ * Attributes:
+ *   variant  — "primary" (default) | "secondary" | "success" | "error" | "warning"
+ *
+ * Slots:
+ *   (default) — badge label text / content
+ *
+ * @example
+ * <bds-badge variant="success">New</bds-badge>
+ */
+export class BdsBadge extends LitElement {
+  static styles = css`
+    :host {
+      display: inline-flex;
+    }
+
+    .badge {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      padding: var(--bds-space_xxs) var(--bds-space_xs);
+      border-radius: var(--badge_radius, 2em);
+      font-size: var(--badge_font-size, var(--bds-font_size--body--s));
+      font-weight: var(--bds-font_weight--semibold);
+      line-height: 1;
+      white-space: nowrap;
+      background-color: var(--badge_bg, var(--bds-color_blue));
+      color: var(--badge_text, var(--bds-color_on-blue));
+    }
+
+    /* Variant overrides */
+    :host([variant='primary']) .badge {
+      --badge_bg:   var(--bds-color_interactive);
+      --badge_text: var(--bds-color_on-interactive);
+    }
+
+    :host([variant='secondary']) .badge {
+      --badge_bg:   var(--bds-color_bg);
+      --badge_text: var(--bds-color_on-bg);
+    }
+
+    :host([variant='success']) .badge {
+      --badge_bg:   var(--bds-color_success);
+      --badge_text: var(--bds-color_on-success);
+    }
+
+    :host([variant='error']) .badge {
+      --badge_bg:   var(--bds-color_error);
+      --badge_text: var(--bds-color_on-error);
+    }
+
+    :host([variant='warning']) .badge {
+      --badge_bg:   var(--bds-color_warning);
+      --badge_text: var(--bds-color_on-warning);
+    }
+  `;
+
+  static properties = {
+    variant: { type: String, reflect: true },
+  };
+
+  // `declare` gives TypeScript the type without emitting a class field initializer
+  // that would shadow Lit's reactive accessor on the prototype.
+  declare variant: BadgeVariant;
+
+  constructor() {
+    super();
+    this.variant = 'primary';
+  }
+
+  render() {
+    return html`<span class="badge"><slot></slot></span>`;
+  }
+}
+
+customElements.define('bds-badge', BdsBadge);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'bds-badge': BdsBadge;
+  }
+}