@boostdev/design-system-components 1.1.1 → 1.2.0

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

@@ -0,0 +1,50 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../index';
+
+function BdsSkeleton({ style }: { style?: React.CSSProperties }) {
+  return React.createElement('bds-skeleton', { style });
+}
+
+const meta = {
+  title: 'Web Components/UI/Skeleton',
+  component: BdsSkeleton,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+} satisfies Meta<typeof BdsSkeleton>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const TextLine: Story = {
+  render: () => <BdsSkeleton style={{ width: '200px', height: '1rem' }} />,
+};
+
+export const Heading: Story = {
+  render: () => <BdsSkeleton style={{ width: '300px', height: '1.75rem' }} />,
+};
+
+export const Avatar: Story = {
+  render: () => <BdsSkeleton style={{ width: '3rem', height: '3rem', borderRadius: '50%' }} />,
+};
+
+export const Card: Story = {
+  render: () => <BdsSkeleton style={{ width: '280px', height: '160px' }} />,
+};
+
+export const AllVariants: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '12px', width: '280px' }}>
+      <div style={{ display: 'flex', alignItems: 'center', gap: '12px' }}>
+        <BdsSkeleton style={{ width: '3rem', height: '3rem', borderRadius: '50%', flexShrink: 0 }} />
+        <div style={{ display: 'flex', flexDirection: 'column', gap: '8px', flex: 1 }}>
+          <BdsSkeleton style={{ width: '100%', height: '1rem' }} />
+          <BdsSkeleton style={{ width: '60%', height: '0.75rem' }} />
+        </div>
+      </div>
+      <BdsSkeleton style={{ width: '100%', height: '120px' }} />
+      <BdsSkeleton style={{ width: '80%', height: '0.875rem' }} />
+      <BdsSkeleton style={{ width: '60%', height: '0.875rem' }} />
+    </div>
+  ),
+};

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

@@ -0,0 +1,83 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsTypography.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-typography&gt;
+
+Framework-agnostic Typography custom element. Renders slotted content inside the appropriate semantic HTML element with the correct typographic styles.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## Examples
+
+### All variants
+<Canvas of={Stories.AllVariants} />
+
+### Heading 1
+<Canvas of={Stories.H1} />
+
+### Body
+<Canvas of={Stories.Body} />
+
+### Body small
+<Canvas of={Stories.BodySmall} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `variant` | `"h1" \| "h2" \| "h3" \| "body" \| "body_s"` | `"body"` | Typographic style and semantic element |
+| `component` | string | — | Override the rendered HTML tag (e.g. `"span"`, `"label"`) |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `(default)` | Text content |
+
+## Default tag mapping
+
+| Variant | Rendered tag |
+|---------|-------------|
+| `h1` | `<h1>` |
+| `h2` | `<h2>` |
+| `h3` | `<h3>` |
+| `body` | `<p>` |
+| `body_s` | `<p>` |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--typography_color` | Text colour (defaults to `--bds-color_on-bg`) |
+
+## Usage in plain HTML
+
+```html
+<bds-typography variant="h1">Page title</bds-typography>
+
+<bds-typography variant="body">
+  A paragraph of body text.
+</bds-typography>
+
+<!-- Override tag while keeping style -->
+<bds-typography variant="body_s" component="span">
+  Inline small text
+</bds-typography>
+```
+
+## Accessibility
+
+- Uses the correct semantic HTML element by default — always prefer semantic variants over overriding `component`
+- Use `component` only when the semantic element must differ from the visual style (e.g. a `<span>` styled as `body_s` inside a heading)

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

@@ -0,0 +1,51 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import type { TypographyVariant } from './bds-typography';
+import '../index';
+
+function BdsTypography({
+  variant,
+  component,
+  children,
+}: {
+  variant?: TypographyVariant;
+  component?: string;
+  children?: React.ReactNode;
+}) {
+  return React.createElement('bds-typography', { variant, component }, children);
+}
+
+const meta = {
+  title: 'Web Components/UI/Typography',
+  component: BdsTypography,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'padded' },
+  argTypes: {
+    variant: { control: 'select', options: ['h1', 'h2', 'h3', 'body', 'body_s'] },
+  },
+} satisfies Meta<typeof BdsTypography>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const H1: Story = { args: { variant: 'h1', children: 'Heading level 1' } };
+export const H2: Story = { args: { variant: 'h2', children: 'Heading level 2' } };
+export const H3: Story = { args: { variant: 'h3', children: 'Heading level 3' } };
+export const Body: Story = { args: { variant: 'body', children: 'Body text — the default paragraph style for reading comfort.' } };
+export const BodySmall: Story = { args: { variant: 'body_s', children: 'Small body text — useful for captions and helper text.' } };
+
+export const AllVariants: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
+      {(['h1', 'h2', 'h3', 'body', 'body_s'] as const).map(v => (
+        <BdsTypography key={v} variant={v}>
+          {v === 'h1' && 'Heading level 1'}
+          {v === 'h2' && 'Heading level 2'}
+          {v === 'h3' && 'Heading level 3'}
+          {v === 'body' && 'Body text — comfortable reading size for paragraphs.'}
+          {v === 'body_s' && 'Small body — captions, labels, and secondary text.'}
+        </BdsTypography>
+      ))}
+    </div>
+  ),
+};

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

@@ -110,8 +110,7 @@ export class BdsAlert extends LitElement {
       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);
+      box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color);
     }
 
     .dismiss svg {

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

@@ -0,0 +1,75 @@
+import { fixture, cleanup } from '../test/helpers';
+import { BdsAvatar } from './bds-avatar';
+
+describe('bds-avatar', () => {
+  it('is registered as a custom element', () => {
+    expect(customElements.get('bds-avatar')).toBe(BdsAvatar);
+  });
+
+  it('defaults to size="medium"', async () => {
+    const el = await fixture('<bds-avatar></bds-avatar>');
+    expect(el.getAttribute('size')).toBe('medium');
+    cleanup(el);
+  });
+
+  it('renders an <img> when src is set', async () => {
+    const el = await fixture('<bds-avatar src="/photo.jpg" name="Jane Doe"></bds-avatar>');
+    const img = el.shadowRoot!.querySelector('img');
+    expect(img).not.toBeNull();
+    expect(img!.getAttribute('src')).toBe('/photo.jpg');
+    cleanup(el);
+  });
+
+  it('img alt defaults to name when alt is not set', async () => {
+    const el = await fixture('<bds-avatar src="/photo.jpg" name="Jane Doe"></bds-avatar>');
+    const img = el.shadowRoot!.querySelector('img');
+    expect(img!.getAttribute('alt')).toBe('Jane Doe');
+    cleanup(el);
+  });
+
+  it('img uses explicit alt when set', async () => {
+    const el = await fixture('<bds-avatar src="/photo.jpg" alt="Custom alt" name="Jane Doe"></bds-avatar>');
+    const img = el.shadowRoot!.querySelector('img');
+    expect(img!.getAttribute('alt')).toBe('Custom alt');
+    cleanup(el);
+  });
+
+  it('renders fallback with initials when src is not set', async () => {
+    const el = await fixture('<bds-avatar name="Jane Doe"></bds-avatar>');
+    const fallback = el.shadowRoot!.querySelector('.fallback');
+    expect(fallback).not.toBeNull();
+    expect(fallback!.getAttribute('role')).toBe('img');
+    const initials = el.shadowRoot!.querySelector('.initials');
+    expect(initials!.textContent).toBe('JD');
+    cleanup(el);
+  });
+
+  it('computes initials from first two words', async () => {
+    const el = await fixture('<bds-avatar name="Alice Bob Charlie"></bds-avatar>');
+    const initials = el.shadowRoot!.querySelector('.initials');
+    expect(initials!.textContent).toBe('AB');
+    cleanup(el);
+  });
+
+  it('fallback aria-label is the name', async () => {
+    const el = await fixture('<bds-avatar name="Jane Doe"></bds-avatar>');
+    const fallback = el.shadowRoot!.querySelector('.fallback');
+    expect(fallback!.getAttribute('aria-label')).toBe('Jane Doe');
+    cleanup(el);
+  });
+
+  it('fallback aria-label defaults to "User avatar" when name is not set', async () => {
+    const el = await fixture('<bds-avatar></bds-avatar>');
+    const fallback = el.shadowRoot!.querySelector('.fallback');
+    expect(fallback!.getAttribute('aria-label')).toBe('User avatar');
+    cleanup(el);
+  });
+
+  it('reflects size property to attribute', async () => {
+    const el = await fixture('<bds-avatar></bds-avatar>') as BdsAvatar;
+    el.size = 'large';
+    await el.updateComplete;
+    expect(el.getAttribute('size')).toBe('large');
+    cleanup(el);
+  });
+});

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

@@ -0,0 +1,122 @@
+import { LitElement, css, html, nothing } from 'lit';
+
+/**
+ * `<bds-avatar>` — framework-agnostic Avatar custom element.
+ *
+ * Shows an image when `src` is set; falls back to initials derived from `name`.
+ *
+ * Attributes:
+ *   src  — image URL
+ *   alt  — image alt text (defaults to `name` or "User avatar")
+ *   name — full name; used to compute initials and as fallback aria-label
+ *   size — "small" | "medium" (default) | "large"
+ *
+ * @example
+ * <bds-avatar src="/photo.jpg" name="Jane Doe"></bds-avatar>
+ * <bds-avatar name="Jane Doe" size="large"></bds-avatar>
+ */
+export class BdsAvatar extends LitElement {
+  static styles = css`
+    :host {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      inline-size: var(--avatar_size, 3em);
+      block-size: var(--avatar_size, 3em);
+      border-radius: 50%;
+      overflow: hidden;
+      flex-shrink: 0;
+    }
+
+    :host([size='small'])  { --avatar_size: 2em; }
+    :host([size='medium']) { --avatar_size: 3em; }
+    :host([size='large'])  { --avatar_size: 4.5em; }
+
+    .fallback {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      inline-size: 100%;
+      block-size: 100%;
+      background-color: var(--avatar_bg, var(--bds-color_blue));
+      color: var(--avatar_text, var(--bds-color_on-blue));
+      font-weight: var(--bds-font_weight--semibold);
+    }
+
+    .initials {
+      line-height: 1;
+      user-select: none;
+      font-size: var(--bds-font_size--body);
+    }
+
+    :host([size='small'])  .initials { font-size: var(--bds-font_size--body--s); }
+    :host([size='large'])  .initials { font-size: var(--bds-font_size--heading-3); }
+
+    .image {
+      inline-size: 100%;
+      block-size: 100%;
+      object-fit: cover;
+      display: block;
+    }
+  `;
+
+  static properties = {
+    src:  { type: String },
+    alt:  { type: String },
+    name: { type: String },
+    size: { type: String, reflect: true },
+  };
+
+  declare src: string;
+  declare alt: string;
+  declare name: string;
+  declare size: 'small' | 'medium' | 'large';
+
+  constructor() {
+    super();
+    this.src = '';
+    this.alt = '';
+    this.name = '';
+    this.size = 'medium';
+  }
+
+  private get _initials(): string {
+    if (!this.name) return '';
+    return this.name
+      .split(' ')
+      .filter(Boolean)
+      .slice(0, 2)
+      .map(word => word[0].toUpperCase())
+      .join('');
+  }
+
+  render() {
+    if (this.src) {
+      return html`<img
+        class="image"
+        src=${this.src}
+        alt=${this.alt || this.name || 'User avatar'}
+      />`;
+    }
+
+    return html`
+      <span
+        class="fallback"
+        role="img"
+        aria-label=${this.name || 'User avatar'}
+      >
+        ${this._initials
+          ? html`<span class="initials" aria-hidden="true">${this._initials}</span>`
+          : nothing}
+      </span>
+    `;
+  }
+}
+
+customElements.define('bds-avatar', BdsAvatar);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'bds-avatar': BdsAvatar;
+  }
+}

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

@@ -0,0 +1,55 @@
+import { fixture, cleanup } from '../test/helpers';
+import { BdsBreadcrumb } from './bds-breadcrumb';
+
+describe('bds-breadcrumb', () => {
+  it('is registered as a custom element', () => {
+    expect(customElements.get('bds-breadcrumb')).toBe(BdsBreadcrumb);
+  });
+
+  it('renders a <nav> with aria-label="Breadcrumb"', async () => {
+    const el = await fixture('<bds-breadcrumb></bds-breadcrumb>');
+    const nav = el.shadowRoot!.querySelector('nav');
+    expect(nav).not.toBeNull();
+    expect(nav!.getAttribute('aria-label')).toBe('Breadcrumb');
+    cleanup(el);
+  });
+
+  it('renders items as list items', async () => {
+    const el = await fixture('<bds-breadcrumb></bds-breadcrumb>') as BdsBreadcrumb;
+    el.items = [{ label: 'Home', href: '/' }, { label: 'Products', href: '/products' }, { label: 'Item' }];
+    await el.updateComplete;
+    const items = el.shadowRoot!.querySelectorAll('.item');
+    expect(items.length).toBe(3);
+    cleanup(el);
+  });
+
+  it('renders links for non-last items', async () => {
+    const el = await fixture('<bds-breadcrumb></bds-breadcrumb>') as BdsBreadcrumb;
+    el.items = [{ label: 'Home', href: '/' }, { label: 'Current' }];
+    await el.updateComplete;
+    const link = el.shadowRoot!.querySelector('a.link');
+    expect(link).not.toBeNull();
+    expect(link!.getAttribute('href')).toBe('/');
+    cleanup(el);
+  });
+
+  it('renders current page as span with aria-current="page"', async () => {
+    const el = await fixture('<bds-breadcrumb></bds-breadcrumb>') as BdsBreadcrumb;
+    el.items = [{ label: 'Home', href: '/' }, { label: 'Current' }];
+    await el.updateComplete;
+    const current = el.shadowRoot!.querySelector('.current');
+    expect(current).not.toBeNull();
+    expect(current!.getAttribute('aria-current')).toBe('page');
+    expect(current!.textContent).toBe('Current');
+    cleanup(el);
+  });
+
+  it('renders separators between items', async () => {
+    const el = await fixture('<bds-breadcrumb></bds-breadcrumb>') as BdsBreadcrumb;
+    el.items = [{ label: 'Home', href: '/' }, { label: 'Products', href: '/p' }, { label: 'Item' }];
+    await el.updateComplete;
+    const separators = el.shadowRoot!.querySelectorAll('.separator');
+    expect(separators.length).toBe(2); // between each pair
+    cleanup(el);
+  });
+});

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

@@ -0,0 +1,114 @@
+import { LitElement, css, html } from 'lit';
+
+export interface BreadcrumbItem {
+  label: string;
+  href?: string;
+}
+
+/**
+ * `<bds-breadcrumb>` — framework-agnostic Breadcrumb custom element.
+ *
+ * Attributes:
+ *   items — JSON string array of `{ label: string, href?: string }` objects.
+ *           The last item is treated as the current page (no link).
+ *
+ * @example
+ * <bds-breadcrumb items='[{"label":"Home","href":"/"},{"label":"Products","href":"/products"},{"label":"Item"}]'></bds-breadcrumb>
+ */
+export class BdsBreadcrumb extends LitElement {
+  static styles = css`
+    :host {
+      display: block;
+    }
+
+    .breadcrumb {
+      font-size: var(--bds-font_size--body--s);
+    }
+
+    .list {
+      display: flex;
+      flex-wrap: wrap;
+      align-items: center;
+      gap: var(--bds-space_xxs);
+      list-style: none;
+      margin: 0;
+      padding: 0;
+    }
+
+    .item {
+      display: flex;
+      align-items: center;
+      gap: var(--bds-space_xxs);
+    }
+
+    .link {
+      color: var(--bds-color_interactive_on-bg);
+      text-decoration: none;
+      transition: var(--bds-animation_transition);
+    }
+
+    .link:focus-visible {
+      outline: var(--bds-outline_default);
+      outline-offset: var(--bds-outline_offset);
+      border-radius: var(--bds-border_radius--xs);
+    }
+
+    @media (hover: hover) and (pointer: fine) {
+      .link:hover {
+        text-decoration: underline;
+        text-underline-offset: 0.2em;
+      }
+    }
+
+    .separator {
+      color: var(--bds-color_on-bg--subtle);
+      user-select: none;
+    }
+
+    .current {
+      color: var(--bds-color_on-bg--subtle);
+      font-weight: var(--bds-font_weight--semibold);
+    }
+  `;
+
+  static properties = {
+    items: { type: Array },
+  };
+
+  declare items: BreadcrumbItem[];
+
+  constructor() {
+    super();
+    this.items = [];
+  }
+
+  render() {
+    return html`
+      <nav class="breadcrumb" aria-label="Breadcrumb">
+        <ol class="list">
+          ${this.items.map((item, index) => {
+            const isLast = index === this.items.length - 1;
+            return html`
+              <li class="item">
+                ${isLast
+                  ? html`<span class="current" aria-current="page">${item.label}</span>`
+                  : html`
+                      <a class="link" href=${item.href ?? '#'}>${item.label}</a>
+                      <span class="separator" aria-hidden="true">›</span>
+                    `}
+              </li>
+            `;
+          })}
+        </ol>
+      </nav>
+    `;
+  }
+}
+
+customElements.define('bds-breadcrumb', BdsBreadcrumb);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'bds-breadcrumb': BdsBreadcrumb;
+  }
+}

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

@@ -0,0 +1,70 @@
+import { fixture, cleanup } from '../test/helpers';
+import { BdsCard } from './bds-card';
+
+describe('bds-card', () => {
+  it('is registered as a custom element', () => {
+    expect(customElements.get('bds-card')).toBe(BdsCard);
+  });
+
+  it('defaults to variant="default", padding="medium", text-align="start"', async () => {
+    const el = await fixture('<bds-card>Content</bds-card>') as BdsCard;
+    expect(el.getAttribute('variant')).toBe('default');
+    expect(el.getAttribute('padding')).toBe('medium');
+    expect(el.getAttribute('text-align')).toBe('start');
+    cleanup(el);
+  });
+
+  it('renders a <div> when not clickable', async () => {
+    const el = await fixture('<bds-card>Content</bds-card>');
+    expect(el.shadowRoot!.querySelector('div.card')).not.toBeNull();
+    expect(el.shadowRoot!.querySelector('button')).toBeNull();
+    cleanup(el);
+  });
+
+  it('renders a <button> when clickable is set', async () => {
+    const el = await fixture('<bds-card clickable>Content</bds-card>');
+    expect(el.shadowRoot!.querySelector('button.card')).not.toBeNull();
+    expect(el.shadowRoot!.querySelector('div.card')).toBeNull();
+    cleanup(el);
+  });
+
+  it('button has type="button"', async () => {
+    const el = await fixture('<bds-card clickable>Content</bds-card>');
+    const btn = el.shadowRoot!.querySelector('button');
+    expect(btn!.getAttribute('type')).toBe('button');
+    cleanup(el);
+  });
+
+  it('fires bds-click event when clickable card is clicked', async () => {
+    const el = await fixture('<bds-card clickable>Content</bds-card>');
+    const btn = el.shadowRoot!.querySelector('button')!;
+    const handler = vi.fn();
+    el.addEventListener('bds-click', handler);
+    btn.dispatchEvent(new MouseEvent('click', { bubbles: true, composed: true }));
+    expect(handler).toHaveBeenCalledOnce();
+    cleanup(el);
+  });
+
+  it('applies variant, padding and text-align classes to the card element', async () => {
+    const el = await fixture('<bds-card variant="elevated" padding="large" text-align="center">Content</bds-card>');
+    const card = el.shadowRoot!.querySelector('.card')!;
+    expect(card.classList.contains('--elevated')).toBe(true);
+    expect(card.classList.contains('--padding-large')).toBe(true);
+    expect(card.classList.contains('--text-center')).toBe(true);
+    cleanup(el);
+  });
+
+  it('renders slotted content', async () => {
+    const el = await fixture('<bds-card>Hello card</bds-card>');
+    expect(el.textContent?.trim()).toBe('Hello card');
+    cleanup(el);
+  });
+
+  it('reflects variant property update', async () => {
+    const el = await fixture('<bds-card>Content</bds-card>') as BdsCard;
+    el.variant = 'outlined';
+    await el.updateComplete;
+    expect(el.getAttribute('variant')).toBe('outlined');
+    cleanup(el);
+  });
+});