@boostdev/design-system-components 1.1.1 → 1.2.0

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

@@ -0,0 +1,154 @@
+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;
+      box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color), 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);
+  });
+});

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

@@ -0,0 +1,138 @@
+import { LitElement, css, html, nothing } from 'lit';
+
+export type LinkVariant = 'default' | 'subtle' | 'standalone';
+
+/**
+ * `<bds-link>` — framework-agnostic Link custom element.
+ *
+ * Attributes:
+ *   href           — URL for the anchor
+ *   target         — link target (e.g. "_blank")
+ *   variant        — "default" (default) | "subtle" | "standalone"
+ *   external       — boolean; when set, adds rel="noreferrer noopener" and a
+ *                    visually-hidden label for screen readers
+ *   external-label — the screen reader text appended for external links
+ *                    (default: "(opens in new tab)")
+ *
+ * Slots:
+ *   (default) — link text / content
+ *
+ * @example
+ * <bds-link href="https://example.com" external>Visit site</bds-link>
+ */
+export class BdsLink extends LitElement {
+  static styles = css`
+    :host {
+      display: inline;
+    }
+
+    .link {
+      color: var(--link_color, var(--bds-color_interactive_on-bg));
+      text-decoration: underline;
+      text-underline-offset: 0.2em;
+      transition: var(--bds-animation_transition);
+      cursor: pointer;
+    }
+
+    .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 {
+        --link_color: var(--link_color-hover, var(--bds-color_blue--strong));
+      }
+    }
+
+    .link.--variant_default {
+      --link_color:       var(--bds-color_interactive_on-bg);
+      --link_color-hover: var(--bds-color_blue--strong);
+    }
+
+    .link.--variant_subtle {
+      --link_color:       var(--bds-color_on-bg);
+      --link_color-hover: var(--bds-color_interactive_on-bg);
+    }
+
+    .link.--variant_standalone {
+      --link_color:       var(--bds-color_interactive_on-bg);
+      --link_color-hover: var(--bds-color_blue--strong);
+      display: inline-flex;
+      align-items: center;
+      gap: var(--bds-space_xxs);
+      font-weight: var(--bds-font_weight--semibold);
+      text-decoration: none;
+    }
+
+    @media (hover: hover) and (pointer: fine) {
+      .link.--variant_standalone:hover {
+        text-decoration: underline;
+        text-underline-offset: 0.2em;
+      }
+    }
+
+    .external-label {
+      position: absolute;
+      inline-size: 1px;
+      block-size: 1px;
+      padding: 0;
+      margin: -1px;
+      overflow: hidden;
+      clip: rect(0, 0, 0, 0);
+      white-space: nowrap;
+      border-width: 0;
+    }
+  `;
+
+  static properties = {
+    href:          { type: String },
+    target:        { type: String },
+    variant:       { type: String, reflect: true },
+    external:      { type: Boolean, reflect: true },
+    externalLabel: { type: String, attribute: 'external-label' },
+  };
+
+  declare href: string;
+  declare target: string;
+  declare variant: LinkVariant;
+  declare external: boolean;
+  declare externalLabel: string;
+
+  constructor() {
+    super();
+    this.href = '';
+    this.target = '';
+    this.variant = 'default';
+    this.external = false;
+    this.externalLabel = '(opens in new tab)';
+  }
+
+  render() {
+    const rel = this.external ? 'noreferrer noopener' : nothing;
+    const target = this.external ? '_blank' : (this.target || nothing);
+
+    return html`
+      <a
+        class="link --variant_${this.variant}"
+        href=${this.href || nothing}
+        target=${target}
+        rel=${rel}
+      >
+        <slot></slot>
+        ${this.external
+          ? html`<span class="external-label">${this.externalLabel}</span>`
+          : nothing}
+      </a>
+    `;
+  }
+}
+
+customElements.define('bds-link', BdsLink);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'bds-link': BdsLink;
+  }
+}

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

@@ -0,0 +1,38 @@
+import { fixture, cleanup } from '../test/helpers';
+import { BdsLoading } from './bds-loading';
+
+describe('bds-loading', () => {
+  it('is registered as a custom element', () => {
+    expect(customElements.get('bds-loading')).toBe(BdsLoading);
+  });
+
+  it('defaults to size="medium"', async () => {
+    const el = await fixture('<bds-loading></bds-loading>');
+    expect(el.getAttribute('size')).toBe('medium');
+    cleanup(el);
+  });
+
+  it('renders a spinner in shadow DOM', async () => {
+    const el = await fixture('<bds-loading></bds-loading>');
+    const spinner = el.shadowRoot!.querySelector('.spinner');
+    expect(spinner).not.toBeNull();
+    cleanup(el);
+  });
+
+  it('spinner has role="status" and aria-label="Loading"', async () => {
+    const el = await fixture('<bds-loading></bds-loading>');
+    const spinner = el.shadowRoot!.querySelector('.spinner');
+    expect(spinner!.getAttribute('role')).toBe('status');
+    expect(spinner!.getAttribute('aria-label')).toBe('Loading');
+    cleanup(el);
+  });
+
+  it('reflects size attribute', async () => {
+    const el = await fixture('<bds-loading size="large"></bds-loading>') as BdsLoading;
+    expect(el.size).toBe('large');
+    el.size = 'small';
+    await el.updateComplete;
+    expect(el.getAttribute('size')).toBe('small');
+    cleanup(el);
+  });
+});

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

@@ -0,0 +1,76 @@
+import { LitElement, css, html } from 'lit';
+
+/**
+ * `<bds-loading>` — framework-agnostic Loading spinner custom element.
+ *
+ * Attributes:
+ *   size — "small" | "medium" (default) | "large"
+ *
+ * @example
+ * <bds-loading></bds-loading>
+ * <bds-loading size="large"></bds-loading>
+ */
+export class BdsLoading extends LitElement {
+  static styles = css`
+    :host {
+      display: flex;
+      justify-content: center;
+      align-items: center;
+    }
+
+    .spinner {
+      inline-size: 2.5em;
+      block-size: 2.5em;
+      border: 4px solid var(--bds-color_bg);
+      border-block-start: 4px solid var(--bds-color_interactive);
+      border-radius: 50%;
+      animation: spin 1s linear infinite;
+    }
+
+    :host([size='small']) .spinner {
+      inline-size: 1.5em;
+      block-size: 1.5em;
+      border-width: 2px;
+    }
+
+    :host([size='large']) .spinner {
+      inline-size: 4em;
+      block-size: 4em;
+      border-width: 6px;
+    }
+
+    @keyframes spin {
+      0% { transform: rotate(0deg); }
+      100% { transform: rotate(360deg); }
+    }
+
+    @media (prefers-reduced-motion: reduce) {
+      .spinner {
+        animation: none;
+      }
+    }
+  `;
+
+  static properties = {
+    size: { type: String, reflect: true },
+  };
+
+  declare size: 'small' | 'medium' | 'large';
+
+  constructor() {
+    super();
+    this.size = 'medium';
+  }
+
+  render() {
+    return html`<div class="spinner" role="status" aria-label="Loading"></div>`;
+  }
+}
+
+customElements.define('bds-loading', BdsLoading);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'bds-loading': BdsLoading;
+  }
+}