@boostdev/design-system-components 1.1.1 → 1.1.2

package/src/web-components/interaction/form/bds-switch.spec.ts

@@ -0,0 +1,62 @@
+import { fixture, cleanup } from '../../test/helpers';
+import { BdsSwitch } from './bds-switch';
+
+describe('bds-switch', () => {
+  it('is registered as a custom element', () => {
+    expect(customElements.get('bds-switch')).toBe(BdsSwitch);
+  });
+
+  it('renders a checkbox input with role="switch"', async () => {
+    const el = await fixture('<bds-switch name="notify">Notifications</bds-switch>');
+    const input = el.shadowRoot!.querySelector<HTMLInputElement>('input')!;
+    expect(input.type).toBe('checkbox');
+    expect(input.getAttribute('role')).toBe('switch');
+    cleanup(el);
+  });
+
+  it('is off by default', async () => {
+    const el = await fixture('<bds-switch name="notify">Notifications</bds-switch>');
+    const input = el.shadowRoot!.querySelector<HTMLInputElement>('input')!;
+    expect(input.checked).toBe(false);
+    cleanup(el);
+  });
+
+  it('is on when checked attribute is set', async () => {
+    const el = await fixture('<bds-switch name="notify" checked>Notifications</bds-switch>');
+    const input = el.shadowRoot!.querySelector<HTMLInputElement>('input')!;
+    expect(input.checked).toBe(true);
+    cleanup(el);
+  });
+
+  it('input is disabled when disabled attribute is set', async () => {
+    const el = await fixture('<bds-switch name="notify" disabled>Notifications</bds-switch>');
+    const input = el.shadowRoot!.querySelector<HTMLInputElement>('input')!;
+    expect(input.disabled).toBe(true);
+    cleanup(el);
+  });
+
+  it('renders a visual track element', async () => {
+    const el = await fixture('<bds-switch name="notify">Notifications</bds-switch>');
+    expect(el.shadowRoot!.querySelector('.track')).not.toBeNull();
+    cleanup(el);
+  });
+
+  it('renders slotted label text', async () => {
+    const el = await fixture('<bds-switch name="notify">Turn on alerts</bds-switch>');
+    expect(el.textContent?.trim()).toBe('Turn on alerts');
+    cleanup(el);
+  });
+
+  it('updates checked property on change', async () => {
+    const el = await fixture('<bds-switch name="notify">Notifications</bds-switch>') as BdsSwitch;
+    const input = el.shadowRoot!.querySelector<HTMLInputElement>('input')!;
+    input.checked = true;
+    input.dispatchEvent(new Event('change', { bubbles: true }));
+    expect(el.checked).toBe(true);
+    cleanup(el);
+  });
+
+  it('is form-associated', () => {
+    expect(BdsSwitch.formAssociated).toBe(true);
+  });
+});

package/src/web-components/interaction/form/bds-switch.ts

@@ -0,0 +1,166 @@
+import { LitElement, css, html } from 'lit';
+
+/**
+ * `<bds-switch>` — form-associated Toggle Switch custom element.
+ *
+ * Visually a toggle switch but semantically equivalent to a checkbox
+ * (`role="switch"`). Participates in HTML forms via the Form-Associated
+ * Custom Elements API.
+ *
+ * Attributes:
+ *   name     — form field name
+ *   value    — submitted value when on (default: "on")
+ *   checked  — boolean; whether the switch is on
+ *   required — boolean
+ *   disabled — boolean
+ *
+ * Slots:
+ *   (default) — label text
+ *
+ * @example
+ * <bds-switch name="notifications" value="enabled">Enable notifications</bds-switch>
+ */
+export class BdsSwitch extends LitElement {
+  static formAssociated = true;
+
+  static styles = css`
+    :host {
+      display: inline-flex;
+      align-items: center;
+      gap: var(--bds-space_xs);
+      cursor: pointer;
+      font-size: var(--bds-font_size--body);
+      font-family: var(--bds-font_family--body);
+      color: var(--bds-color_on-bg);
+    }
+
+    :host([disabled]) {
+      opacity: 0.5;
+      cursor: not-allowed;
+      pointer-events: none;
+    }
+
+    .track {
+      position: relative;
+      inline-size: 2.75rem;
+      block-size: 1.5rem;
+      border-radius: 999px;
+      background-color: var(--switch_color_bg, var(--bds-color_bg--subtle));
+      --bdc_color: currentcolor;
+
+      outline: var(--bdc-outline_width) solid var(--bdc_color);
+      outline-offset: var(--bdc-outline_offset);
+      transition: background-color 0.2s ease;
+      flex-shrink: 0;
+    }
+
+    .thumb {
+      position: absolute;
+      inset-block-start: 0.2rem;
+      inset-inline-start: 0.2rem;
+      inline-size: 1.1rem;
+      block-size: 1.1rem;
+      border-radius: 50%;
+      background-color: var(--switch_thumb_color, var(--bds-color_bg));
+      transition: inset-inline-start 0.2s ease;
+    }
+
+    .input {
+      position: absolute;
+      opacity: 0;
+      inline-size: 0;
+      block-size: 0;
+      margin: 0;
+    }
+
+    .input:checked + .track {
+      background-color: var(--switch_color-active, var(--bdc-color_active));
+    }
+
+    .input:checked + .track .thumb {
+      inset-inline-start: calc(100% - 1.3rem);
+    }
+
+    .input:focus-visible + .track {
+      outline: var(--bds-outline_default);
+      outline-offset: var(--bds-outline_offset);
+    }
+
+    label {
+      cursor: pointer;
+    }
+  `;
+
+  static properties = {
+    name:     { type: String, reflect: true },
+    value:    { type: String },
+    checked:  { type: Boolean, reflect: true },
+    required: { type: Boolean, reflect: true },
+    disabled: { type: Boolean, reflect: true },
+  };
+
+  declare name: string;
+  declare value: string;
+  declare checked: boolean;
+  declare required: boolean;
+  declare disabled: boolean;
+
+  private _internals!: ElementInternals;
+  private readonly _uid = Math.random().toString(36).slice(2, 8);
+
+  constructor() {
+    super();
+    this._internals = this.attachInternals();
+    this.name = '';
+    this.value = 'on';
+    this.checked = false;
+    this.required = false;
+    this.disabled = false;
+  }
+
+  updated(changed: Map<string, unknown>) {
+    super.updated(changed);
+    if (changed.has('checked') || changed.has('value')) {
+      this._internals.setFormValue?.(this.checked ? this.value : null);
+    }
+  }
+
+  formResetCallback() {
+    this.checked = false;
+    this._internals.setFormValue?.(null);
+  }
+
+  private _handleChange(e: Event) {
+    this.checked = (e.target as HTMLInputElement).checked;
+  }
+
+  render() {
+    const id = `bds-switch-${this._uid}`;
+    return html`
+      <input
+        id=${id}
+        type="checkbox"
+        role="switch"
+        class="input"
+        .checked=${this.checked}
+        ?required=${this.required}
+        ?disabled=${this.disabled}
+        @change=${this._handleChange}
+      />
+      <label for=${id}>
+        <span class="track">
+          <span class="thumb"></span>
+        </span>
+        <slot></slot>
+      </label>
+    `;
+  }
+}
+
+customElements.define('bds-switch', BdsSwitch);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'bds-switch': BdsSwitch;
+  }
+}

package/src/web-components/interaction/form/bds-textarea.spec.ts

@@ -0,0 +1,55 @@
+import { fixture, cleanup } from '../../test/helpers';
+import { BdsTextarea } from './bds-textarea';
+
+describe('bds-textarea', () => {
+  it('is registered as a custom element', () => {
+    expect(customElements.get('bds-textarea')).toBe(BdsTextarea);
+  });
+
+  it('renders a <textarea> element in shadow DOM', async () => {
+    const el = await fixture('<bds-textarea name="message"></bds-textarea>');
+    expect(el.shadowRoot!.querySelector('textarea')).not.toBeNull();
+    cleanup(el);
+  });
+
+  it('forwards placeholder attribute to inner textarea', async () => {
+    const el = await fixture('<bds-textarea name="message" placeholder="Type here…"></bds-textarea>');
+    const textarea = el.shadowRoot!.querySelector<HTMLTextAreaElement>('textarea')!;
+    expect(textarea.placeholder).toBe('Type here…');
+    cleanup(el);
+  });
+
+  it('forwards rows attribute to inner textarea', async () => {
+    const el = await fixture('<bds-textarea name="message" rows="8"></bds-textarea>');
+    const textarea = el.shadowRoot!.querySelector<HTMLTextAreaElement>('textarea')!;
+    expect(textarea.rows).toBe(8);
+    cleanup(el);
+  });
+
+  it('is disabled when disabled attribute is set', async () => {
+    const el = await fixture('<bds-textarea name="message" disabled></bds-textarea>');
+    const textarea = el.shadowRoot!.querySelector<HTMLTextAreaElement>('textarea')!;
+    expect(textarea.disabled).toBe(true);
+    cleanup(el);
+  });
+
+  it('is required when required attribute is set', async () => {
+    const el = await fixture('<bds-textarea name="message" required></bds-textarea>');
+    const textarea = el.shadowRoot!.querySelector<HTMLTextAreaElement>('textarea')!;
+    expect(textarea.required).toBe(true);
+    cleanup(el);
+  });
+
+  it('updates value property on input', async () => {
+    const el = await fixture('<bds-textarea name="message"></bds-textarea>') as BdsTextarea;
+    const textarea = el.shadowRoot!.querySelector<HTMLTextAreaElement>('textarea')!;
+    textarea.value = 'Hello world';
+    textarea.dispatchEvent(new Event('input', { bubbles: true }));
+    expect(el.value).toBe('Hello world');
+    cleanup(el);
+  });
+
+  it('is form-associated', () => {
+    expect(BdsTextarea.formAssociated).toBe(true);
+  });
+});

package/src/web-components/interaction/form/bds-textarea.ts

@@ -0,0 +1,143 @@
+import { LitElement, css, html } from 'lit';
+
+/**
+ * `<bds-textarea>` — form-associated Textarea custom element.
+ *
+ * Wraps a native `<textarea>` for consistent styling while participating
+ * in HTML forms via the Form-Associated Custom Elements API.
+ *
+ * Attributes:
+ *   name        — form field name
+ *   value       — text value
+ *   placeholder — placeholder text
+ *   rows        — number of visible rows (default: 4)
+ *   required    — boolean
+ *   disabled    — boolean
+ *
+ * Events:
+ *   input  — native input event
+ *   change — native change event
+ *
+ * @example
+ * <bds-textarea name="message" placeholder="Enter message…" rows="6"></bds-textarea>
+ */
+export class BdsTextarea extends LitElement {
+  static formAssociated = true;
+
+  static styles = css`
+    :host {
+      display: block;
+    }
+
+    :host([disabled]) {
+      opacity: 0.5;
+      pointer-events: none;
+    }
+
+    .textarea {
+      inline-size: 100%;
+      font-family: var(--bds-font_family--body);
+      font-size: var(--bds-font_size--body);
+      line-height: var(--bds-font_line-height--body);
+      padding: var(--bds-space_s);
+      border: none;
+      --bdc_color: currentcolor;
+      --bdc-outline_radius: var(--bds-border_radius--xs);
+
+      outline: var(--bdc-outline_width) solid var(--bdc_color);
+      outline-offset: var(--bdc-outline_offset);
+      border-radius: var(--textarea_radius, var(--bdc-outline_radius));
+      box-shadow: var(--textarea_shadow, var(--bdc-outline_shadow));
+      background-color: var(--textarea_color_bg, var(--bds-color_bg));
+      color: var(--textarea_color, var(--bds-color_on-bg));
+      resize: vertical;
+      min-block-size: calc(var(--bds-space_m) * 5);
+      box-sizing: border-box;
+      transition: --bdc_color var(--bds-animation_transition-duration) var(--bds-animation_easing),
+                  background-color var(--bds-animation_transition-duration) var(--bds-animation_easing);
+    }
+
+    .textarea:focus {
+      --bdc_color: var(--bdc_color--focus);
+    }
+
+    .textarea:focus-visible {
+      outline: var(--bds-outline_default);
+      outline-offset: var(--bds-outline_offset);
+    }
+
+    .textarea:disabled {
+      opacity: 0.5;
+      cursor: not-allowed;
+      resize: none;
+    }
+  `;
+
+  static properties = {
+    name:        { type: String, reflect: true },
+    value:       { type: String },
+    placeholder: { type: String },
+    rows:        { type: Number },
+    required:    { type: Boolean, reflect: true },
+    disabled:    { type: Boolean, reflect: true },
+  };
+
+  declare name: string;
+  declare value: string;
+  declare placeholder: string;
+  declare rows: number;
+  declare required: boolean;
+  declare disabled: boolean;
+
+  private _internals!: ElementInternals;
+
+  constructor() {
+    super();
+    this._internals = this.attachInternals();
+    this.name = '';
+    this.value = '';
+    this.placeholder = '';
+    this.rows = 4;
+    this.required = false;
+    this.disabled = false;
+  }
+
+  updated(changed: Map<string, unknown>) {
+    super.updated(changed);
+    if (changed.has('value')) {
+      this._internals.setFormValue?.(this.value || null);
+    }
+  }
+
+  formResetCallback() {
+    this.value = '';
+    this._internals.setFormValue?.(null);
+  }
+
+  private _handleInput(e: Event) {
+    this.value = (e.target as HTMLTextAreaElement).value;
+  }
+
+  render() {
+    return html`
+      <textarea
+        class="textarea"
+        name=${this.name}
+        .value=${this.value}
+        placeholder=${this.placeholder}
+        rows=${this.rows}
+        ?required=${this.required}
+        ?disabled=${this.disabled}
+        @input=${this._handleInput}
+      ></textarea>
+    `;
+  }
+}
+
+customElements.define('bds-textarea', BdsTextarea);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'bds-textarea': BdsTextarea;
+  }
+}

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