@boostdev/design-system-components 1.1.1 → 1.1.2

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

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

@@ -0,0 +1,156 @@
+import { LitElement, css, html, nothing } from 'lit';
+
+export type CardVariant = 'default' | 'elevated' | 'outlined';
+export type CardPadding = 'none' | 'small' | 'medium' | 'large';
+export type CardTextAlign = 'start' | 'center' | 'end';
+
+/**
+ * `<bds-card>` — framework-agnostic Card layout custom element.
+ *
+ * Attributes:
+ *   variant    — "default" (default) | "elevated" | "outlined"
+ *   padding    — "none" | "small" | "medium" (default) | "large"
+ *   text-align — "start" (default) | "center" | "end"
+ *   clickable  — boolean; renders as a <button> with hover/active effects
+ *   aria-label — accessible label (useful when clickable)
+ *
+ * Slots:
+ *   (default) — card content
+ *
+ * Events:
+ *   bds-click — fired (bubbles, composed) when the card button is clicked
+ *
+ * @example
+ * <bds-card variant="elevated" padding="large">
+ *   <p>Card content</p>
+ * </bds-card>
+ *
+ * <bds-card clickable aria-label="Open details">
+ *   <p>Clickable card</p>
+ * </bds-card>
+ */
+export class BdsCard extends LitElement {
+  static styles = css`
+    :host {
+      display: block;
+    }
+
+    .card {
+      background-color: var(--card_color, var(--bds-color_bg));
+      color: var(--card_on-color, var(--bds-color_on-bg));
+      border-radius: var(--bds-border_radius--m);
+      transition: all 0.3s ease;
+      position: relative;
+      box-sizing: border-box;
+      inline-size: 100%;
+      text-align: inherit;
+      font: inherit;
+      border: none;
+    }
+
+    .card.--default  { box-shadow: var(--bds-shadow_s); }
+    .card.--elevated { box-shadow: var(--bds-shadow_m); }
+
+    .card.--outlined {
+      --bdc_color: currentcolor;
+      outline: var(--bdc-outline_width) solid var(--bdc_color);
+      outline-offset: var(--bdc-outline_offset);
+      box-shadow: var(--bds-shadow_s);
+    }
+
+    .card.--padding-none   { padding: 0; }
+    .card.--padding-small  { padding: var(--bds-space_s); }
+    .card.--padding-medium { padding: var(--bds-space_m); }
+    .card.--padding-large  { padding: var(--bds-space_l); }
+
+    .card.--text-start  { text-align: start; }
+    .card.--text-center { text-align: center; }
+    .card.--text-end    { text-align: end; }
+
+    .card.--clickable {
+      cursor: pointer;
+      display: block;
+    }
+
+    .card.--clickable:focus-visible {
+      outline: 2px solid var(--color_focus, currentcolor);
+      outline-offset: 2px;
+    }
+
+    .card.--clickable:active {
+      transform: translateY(0);
+      box-shadow: var(--bds-shadow_s);
+    }
+
+    @media (hover: hover) and (pointer: fine) {
+      .card.--clickable:hover {
+        transform: translateY(-2px);
+        box-shadow: var(--bds-shadow_xl);
+      }
+
+      .card.--default:hover  { box-shadow: var(--bds-shadow_m); }
+      .card.--elevated:hover { box-shadow: var(--bds-shadow_2xl); }
+      .card.--outlined:hover { box-shadow: var(--bds-shadow_s); }
+    }
+  `;
+
+  static properties = {
+    variant:   { type: String, reflect: true },
+    padding:   { type: String, reflect: true },
+    textAlign: { type: String, attribute: 'text-align', reflect: true },
+    clickable: { type: Boolean, reflect: true },
+    ariaLabel: { type: String, attribute: 'aria-label' },
+  };
+
+  declare variant: CardVariant;
+  declare padding: CardPadding;
+  declare textAlign: CardTextAlign;
+  declare clickable: boolean;
+  declare ariaLabel: string;
+
+  constructor() {
+    super();
+    this.variant = 'default';
+    this.padding = 'medium';
+    this.textAlign = 'start';
+    this.clickable = false;
+    this.ariaLabel = '';
+  }
+
+  private _handleClick() {
+    this.dispatchEvent(new CustomEvent('bds-click', { bubbles: true, composed: true }));
+  }
+
+  render() {
+    const classes = [
+      'card',
+      `--${this.variant}`,
+      `--padding-${this.padding}`,
+      `--text-${this.textAlign}`,
+      this.clickable ? '--clickable' : '',
+    ].filter(Boolean).join(' ');
+
+    if (this.clickable) {
+      return html`
+        <button
+          type="button"
+          class=${classes}
+          @click=${this._handleClick}
+          aria-label=${this.ariaLabel || nothing}
+        >
+          <slot></slot>
+        </button>
+      `;
+    }
+
+    return html`<div class=${classes}><slot></slot></div>`;
+  }
+}
+
+customElements.define('bds-card', BdsCard);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'bds-card': BdsCard;
+  }
+}

package/src/web-components/ui/bds-description-list.spec.ts

@@ -0,0 +1,36 @@
+import { fixture, cleanup } from '../test/helpers';
+import { BdsDescriptionList } from './bds-description-list';
+
+describe('bds-description-list', () => {
+  it('is registered as a custom element', () => {
+    expect(customElements.get('bds-description-list')).toBe(BdsDescriptionList);
+  });
+
+  it('defaults to layout="stacked"', async () => {
+    const el = await fixture('<bds-description-list></bds-description-list>');
+    expect(el.getAttribute('layout')).toBe('stacked');
+    cleanup(el);
+  });
+
+  it('renders a <dl> in shadow DOM', async () => {
+    const el = await fixture('<bds-description-list></bds-description-list>');
+    expect(el.shadowRoot!.querySelector('dl')).not.toBeNull();
+    cleanup(el);
+  });
+
+  it('accepts slotted <dt> and <dd> elements', async () => {
+    const el = await fixture('<bds-description-list><dt>Name</dt><dd>Jane</dd></bds-description-list>');
+    expect(el.querySelector('dt')!.textContent).toBe('Name');
+    expect(el.querySelector('dd')!.textContent).toBe('Jane');
+    cleanup(el);
+  });
+
+  it('reflects layout attribute', async () => {
+    const el = await fixture('<bds-description-list layout="inline"></bds-description-list>') as BdsDescriptionList;
+    expect(el.getAttribute('layout')).toBe('inline');
+    el.layout = 'stacked';
+    await el.updateComplete;
+    expect(el.getAttribute('layout')).toBe('stacked');
+    cleanup(el);
+  });
+});

package/src/web-components/ui/bds-description-list.ts

@@ -0,0 +1,79 @@
+import { LitElement, css, html } from 'lit';
+
+/**
+ * `<bds-description-list>` — framework-agnostic Description List custom element.
+ *
+ * Renders a `<dl>` styled list. Consumers provide `<dt>` and `<dd>` elements
+ * as slotted children; this component handles layout and styling.
+ *
+ * Attributes:
+ *   layout — "stacked" (default) | "inline"
+ *
+ * Slots:
+ *   (default) — `<dt>` and `<dd>` pairs
+ *
+ * @example
+ * <bds-description-list layout="inline">
+ *   <dt>Name</dt>
+ *   <dd>Jane Doe</dd>
+ *   <dt>Email</dt>
+ *   <dd>jane@example.com</dd>
+ * </bds-description-list>
+ */
+export class BdsDescriptionList extends LitElement {
+  static styles = css`
+    :host {
+      display: block;
+    }
+
+    .list {
+      display: flex;
+      flex-direction: column;
+      gap: var(--bds-space_s);
+      margin: 0;
+      padding: 0;
+      font-size: var(--bds-font_size--body);
+      color: var(--bds-color_on-bg);
+    }
+
+    /* Style slotted dt/dd elements */
+    ::slotted(dt) {
+      font-weight: var(--bds-font_weight--semibold);
+      color: var(--bds-color_on-bg);
+      margin: 0;
+    }
+
+    ::slotted(dd) {
+      margin: 0;
+      color: var(--bds-color_on-bg);
+    }
+
+    /* Inline layout: pair each dt/dd side by side */
+    :host([layout='inline']) .list {
+      gap: var(--bds-space_xs);
+    }
+  `;
+
+  static properties = {
+    layout: { type: String, reflect: true },
+  };
+
+  declare layout: 'stacked' | 'inline';
+
+  constructor() {
+    super();
+    this.layout = 'stacked';
+  }
+
+  render() {
+    return html`<dl class="list"><slot></slot></dl>`;
+  }
+}
+
+customElements.define('bds-description-list', BdsDescriptionList);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'bds-description-list': BdsDescriptionList;
+  }
+}

package/src/web-components/ui/bds-icon-wrapper.spec.ts

@@ -0,0 +1,21 @@
+import { fixture, cleanup } from '../test/helpers';
+import { BdsIconWrapper } from './bds-icon-wrapper';
+
+describe('bds-icon-wrapper', () => {
+  it('is registered as a custom element', () => {
+    expect(customElements.get('bds-icon-wrapper')).toBe(BdsIconWrapper);
+  });
+
+  it('renders a wrapper div in shadow DOM', async () => {
+    const el = await fixture('<bds-icon-wrapper></bds-icon-wrapper>');
+    expect(el.shadowRoot!.querySelector('.wrapper')).not.toBeNull();
+    cleanup(el);
+  });
+
+  it('renders slotted content', async () => {
+    const el = await fixture('<bds-icon-wrapper><svg aria-hidden="true"></svg></bds-icon-wrapper>');
+    const svg = el.querySelector('svg');
+    expect(svg).not.toBeNull();
+    cleanup(el);
+  });
+});

package/src/web-components/ui/bds-icon-wrapper.ts

@@ -0,0 +1,68 @@
+import { LitElement, css, html } from 'lit';
+
+/**
+ * `<bds-icon-wrapper>` — framework-agnostic Icon Wrapper custom element.
+ *
+ * Displays an icon inside a circular container with background and foreground theming.
+ *
+ * Attributes:
+ *   aria-hidden — boolean attribute; set to "true" for decorative icons
+ *
+ * Slots:
+ *   (default) — icon content (SVG or img)
+ *
+ * @example
+ * <bds-icon-wrapper aria-hidden="true">
+ *   <svg>…</svg>
+ * </bds-icon-wrapper>
+ */
+export class BdsIconWrapper extends LitElement {
+  static styles = css`
+    :host {
+      display: inline-flex;
+    }
+
+    .wrapper {
+      inline-size: 2em;
+      block-size: 2em;
+      font-size: 3em;
+      border-radius: 50%;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      margin: var(--bds-space_l) auto var(--bds-space_m);
+      background: var(--icon-wrapper-color, var(--bds-color_bg));
+      color: var(--bds-on-icon-wrapper-color, var(--bds-color_on-bg));
+      fill: var(--bds-on-icon-wrapper-color, var(--bds-color_on-bg));
+      position: relative;
+      transition: var(--bds-animation_transition);
+    }
+
+    .wrapper svg {
+      fill: currentcolor;
+    }
+  `;
+
+  static properties = {
+    ariaHidden: { type: String, attribute: 'aria-hidden', reflect: true },
+  };
+
+  declare ariaHidden: string;
+
+  constructor() {
+    super();
+    this.ariaHidden = '';
+  }
+
+  render() {
+    return html`<div class="wrapper"><slot></slot></div>`;
+  }
+}
+
+customElements.define('bds-icon-wrapper', BdsIconWrapper);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'bds-icon-wrapper': BdsIconWrapper;
+  }
+}

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

@@ -0,0 +1,72 @@
+import { fixture, cleanup } from '../test/helpers';
+import { BdsLink } from './bds-link';
+
+describe('bds-link', () => {
+  it('is registered as a custom element', () => {
+    expect(customElements.get('bds-link')).toBe(BdsLink);
+  });
+
+  it('defaults to variant="default"', async () => {
+    const el = await fixture('<bds-link href="/test">Link</bds-link>');
+    expect(el.getAttribute('variant')).toBe('default');
+    cleanup(el);
+  });
+
+  it('renders an <a> with the given href', async () => {
+    const el = await fixture('<bds-link href="/about">About</bds-link>');
+    const a = el.shadowRoot!.querySelector('a');
+    expect(a).not.toBeNull();
+    expect(a!.getAttribute('href')).toBe('/about');
+    cleanup(el);
+  });
+
+  it('renders slotted content', async () => {
+    const el = await fixture('<bds-link href="/">Home</bds-link>');
+    expect(el.textContent?.trim()).toBe('Home');
+    cleanup(el);
+  });
+
+  it('adds target="_blank" and rel="noreferrer noopener" when external is set', async () => {
+    const el = await fixture('<bds-link href="https://example.com" external>Visit</bds-link>');
+    const a = el.shadowRoot!.querySelector('a');
+    expect(a!.getAttribute('target')).toBe('_blank');
+    expect(a!.getAttribute('rel')).toBe('noreferrer noopener');
+    cleanup(el);
+  });
+
+  it('renders visually hidden external label when external is set', async () => {
+    const el = await fixture('<bds-link href="https://example.com" external>Visit</bds-link>');
+    const label = el.shadowRoot!.querySelector('.external-label');
+    expect(label).not.toBeNull();
+    expect(label!.textContent).toBe('(opens in new tab)');
+    cleanup(el);
+  });
+
+  it('uses custom external-label when provided', async () => {
+    const el = await fixture('<bds-link href="https://example.com" external external-label="(new window)">Visit</bds-link>');
+    const label = el.shadowRoot!.querySelector('.external-label');
+    expect(label!.textContent).toBe('(new window)');
+    cleanup(el);
+  });
+
+  it('does not render external label when external is not set', async () => {
+    const el = await fixture('<bds-link href="/about">About</bds-link>');
+    expect(el.shadowRoot!.querySelector('.external-label')).toBeNull();
+    cleanup(el);
+  });
+
+  it('applies variant class to the anchor', async () => {
+    const el = await fixture('<bds-link href="/test" variant="subtle">Link</bds-link>');
+    const a = el.shadowRoot!.querySelector('a');
+    expect(a!.classList.contains('--variant_subtle')).toBe(true);
+    cleanup(el);
+  });
+
+  it('reflects variant property updates', async () => {
+    const el = await fixture('<bds-link href="/test">Link</bds-link>') as BdsLink;
+    el.variant = 'standalone';
+    await el.updateComplete;
+    expect(el.getAttribute('variant')).toBe('standalone');
+    cleanup(el);
+  });
+});