@boostdev/design-system-components 1.1.1 → 1.1.2

package/src/web-components/interaction/bds-skip-link.ts

@@ -0,0 +1,74 @@
+import { LitElement, css, html } from 'lit';
+
+/**
+ * `<bds-skip-link>` — framework-agnostic Skip Navigation Link custom element.
+ *
+ * Visually hidden until focused. Allows keyboard users to skip repetitive
+ * navigation and jump directly to main content.
+ *
+ * Attributes:
+ *   href — the target anchor (default: "#main")
+ *
+ * Slots:
+ *   (default) — link text (default: "Skip to main content")
+ *
+ * @example
+ * <bds-skip-link href="#main-content">Skip to main content</bds-skip-link>
+ */
+export class BdsSkipLink extends LitElement {
+  static styles = css`
+    :host {
+      display: block;
+    }
+
+    .skip-link {
+      position: absolute;
+      inset-block-start: var(--bds-space_s);
+      inset-inline-start: var(--bds-space_s);
+      z-index: 9999;
+      padding: var(--bds-space_xs) var(--bds-space_m);
+      background-color: var(--bds-color_bg);
+      color: var(--bds-color_on-bg);
+      border-radius: var(--bds-border_radius--s);
+      font-weight: var(--bds-font_weight--semibold);
+      font-size: var(--bds-font_size--body);
+      text-decoration: none;
+      box-shadow: var(--bds-shadow_m);
+      transform: translateY(calc(-100% - var(--bds-space_s)));
+      transition: transform var(--bds-animation_transition-duration) var(--bds-animation_easing);
+    }
+
+    .skip-link:focus-visible {
+      transform: translateY(0);
+      outline: var(--bds-outline_default);
+      outline-offset: var(--bds-outline_offset);
+    }
+  `;
+
+  static properties = {
+    href: { type: String },
+  };
+
+  declare href: string;
+
+  constructor() {
+    super();
+    this.href = '#main';
+  }
+
+  render() {
+    return html`
+      <a class="skip-link" href=${this.href}>
+        <slot>Skip to main content</slot>
+      </a>
+    `;
+  }
+}
+
+customElements.define('bds-skip-link', BdsSkipLink);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'bds-skip-link': BdsSkipLink;
+  }
+}

package/src/web-components/interaction/bds-tab-panel.spec.ts

@@ -0,0 +1,32 @@
+import { fixture, cleanup } from '../test/helpers';
+import { BdsTabPanel } from './bds-tab-panel';
+
+describe('bds-tab-panel', () => {
+  it('is registered as a custom element', () => {
+    expect(customElements.get('bds-tab-panel')).toBe(BdsTabPanel);
+  });
+
+  it('renders slotted content', async () => {
+    const el = await fixture('<bds-tab-panel>Panel content</bds-tab-panel>');
+    expect(el.textContent?.trim()).toBe('Panel content');
+    cleanup(el);
+  });
+
+  it('renders a slot in shadow DOM', async () => {
+    const el = await fixture('<bds-tab-panel>Content</bds-tab-panel>');
+    expect(el.shadowRoot!.querySelector('slot')).not.toBeNull();
+    cleanup(el);
+  });
+
+  it('is visible by default (no hidden attribute)', async () => {
+    const el = await fixture('<bds-tab-panel>Content</bds-tab-panel>');
+    expect(el.hasAttribute('hidden')).toBe(false);
+    cleanup(el);
+  });
+
+  it('applies hidden attribute when set externally', async () => {
+    const el = await fixture('<bds-tab-panel hidden>Content</bds-tab-panel>');
+    expect(el.hasAttribute('hidden')).toBe(true);
+    cleanup(el);
+  });
+});

package/src/web-components/interaction/bds-tab-panel.ts

@@ -0,0 +1,38 @@
+import { LitElement, css, html } from 'lit';
+
+/**
+ * `<bds-tab-panel>` — child element of `<bds-tabs>`.
+ *
+ * Contains the content displayed for the associated tab. The `hidden`
+ * state is managed by the parent `<bds-tabs>` element.
+ *
+ * Slots:
+ *   (default) — panel content
+ *
+ * @example
+ * <bds-tab-panel>Panel content here</bds-tab-panel>
+ */
+export class BdsTabPanel extends LitElement {
+  static styles = css`
+    :host {
+      display: block;
+      padding-block-start: var(--bds-space_m);
+    }
+
+    :host([hidden]) {
+      display: none;
+    }
+  `;
+
+  render() {
+    return html`<slot></slot>`;
+  }
+}
+
+customElements.define('bds-tab-panel', BdsTabPanel);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'bds-tab-panel': BdsTabPanel;
+  }
+}

package/src/web-components/interaction/bds-tab.spec.ts

@@ -0,0 +1,71 @@
+import { fixture, cleanup } from '../test/helpers';
+import { BdsTab } from './bds-tab';
+
+describe('bds-tab', () => {
+  it('is registered as a custom element', () => {
+    expect(customElements.get('bds-tab')).toBe(BdsTab);
+  });
+
+  it('renders a button with role="tab"', async () => {
+    const el = await fixture('<bds-tab>Label</bds-tab>');
+    const btn = el.shadowRoot!.querySelector('button');
+    expect(btn).not.toBeNull();
+    expect(btn!.getAttribute('role')).toBe('tab');
+    cleanup(el);
+  });
+
+  it('is not selected by default', async () => {
+    const el = await fixture('<bds-tab>Label</bds-tab>') as BdsTab;
+    expect(el.selected).toBe(false);
+    expect(el.shadowRoot!.querySelector('button')!.getAttribute('aria-selected')).toBe('false');
+    cleanup(el);
+  });
+
+  it('has tabindex="-1" when not selected', async () => {
+    const el = await fixture('<bds-tab>Label</bds-tab>');
+    const btn = el.shadowRoot!.querySelector('button')!;
+    expect(btn.getAttribute('tabindex')).toBe('-1');
+    cleanup(el);
+  });
+
+  it('has tabindex="0" when selected', async () => {
+    const el = await fixture('<bds-tab selected>Label</bds-tab>');
+    const btn = el.shadowRoot!.querySelector('button')!;
+    expect(btn.getAttribute('tabindex')).toBe('0');
+    cleanup(el);
+  });
+
+  it('sets aria-selected="true" when selected', async () => {
+    const el = await fixture('<bds-tab selected>Label</bds-tab>');
+    const btn = el.shadowRoot!.querySelector('button')!;
+    expect(btn.getAttribute('aria-selected')).toBe('true');
+    cleanup(el);
+  });
+
+  it('fires bds-tab-select when clicked', async () => {
+    const el = await fixture('<bds-tab>Label</bds-tab>');
+    const btn = el.shadowRoot!.querySelector('button')!;
+    const handler = vi.fn();
+    el.addEventListener('bds-tab-select', handler);
+    btn.click();
+    expect(handler).toHaveBeenCalledOnce();
+    cleanup(el);
+  });
+
+  it('does not fire bds-tab-select when disabled', async () => {
+    const el = await fixture('<bds-tab disabled>Label</bds-tab>');
+    const btn = el.shadowRoot!.querySelector('button')!;
+    const handler = vi.fn();
+    el.addEventListener('bds-tab-select', handler);
+    btn.dispatchEvent(new MouseEvent('click', { bubbles: true, composed: true }));
+    expect(handler).not.toHaveBeenCalled();
+    cleanup(el);
+  });
+
+  it('button is disabled when disabled attribute is set', async () => {
+    const el = await fixture('<bds-tab disabled>Label</bds-tab>');
+    const btn = el.shadowRoot!.querySelector('button')!;
+    expect(btn.hasAttribute('disabled')).toBe(true);
+    cleanup(el);
+  });
+});

package/src/web-components/interaction/bds-tab.ts

@@ -0,0 +1,110 @@
+import { LitElement, css, html } from 'lit';
+
+/**
+ * `<bds-tab>` — child element of `<bds-tabs>`.
+ *
+ * Represents a single tab button. State (`selected`, `tabIndex`, `disabled`)
+ * is managed by the parent `<bds-tabs>` element.
+ *
+ * Slots:
+ *   (default) — tab label
+ *
+ * Events:
+ *   bds-tab-select — fired (bubbles, composed) when the tab is clicked
+ *
+ * @example
+ * <bds-tab>Overview</bds-tab>
+ */
+export class BdsTab extends LitElement {
+  static styles = css`
+    :host {
+      display: inline-flex;
+    }
+
+    .tab {
+      all: unset;
+      display: inline-flex;
+      align-items: center;
+      padding: var(--bds-space_s) var(--bds-space_m);
+      font-family: var(--bds-font_family--body);
+      font-size: var(--bds-font_size--body);
+      font-weight: var(--bds-font_weight--semibold);
+      color: var(--tab_color, var(--bds-color_on-bg));
+      border-block-end: 2px solid var(--tab_border-color, transparent);
+      margin-block-end: -1px;
+      cursor: pointer;
+      transition: var(--bds-animation_transition);
+      white-space: nowrap;
+    }
+
+    :host([selected]) .tab {
+      --tab_color:        var(--bds-color_interactive_on-bg);
+      --tab_border-color: var(--bds-color_interactive);
+    }
+
+    .tab:disabled {
+      opacity: 0.4;
+      cursor: not-allowed;
+    }
+
+    .tab: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) {
+      .tab:not(:disabled, [aria-selected='true']):hover {
+        --tab_color: var(--bds-color_interactive_on-bg);
+      }
+    }
+  `;
+
+  static properties = {
+    selected: { type: Boolean, reflect: true },
+    disabled: { type: Boolean, reflect: true },
+  };
+
+  declare selected: boolean;
+  declare disabled: boolean;
+
+  constructor() {
+    super();
+    this.selected = false;
+    this.disabled = false;
+  }
+
+  /** Called by `bds-tabs` to focus the inner button for keyboard navigation. */
+  focusButton() {
+    this.shadowRoot?.querySelector<HTMLButtonElement>('button')?.focus();
+  }
+
+  private _handleClick() {
+    if (this.disabled) return;
+    this.dispatchEvent(new CustomEvent('bds-tab-select', { bubbles: true, composed: true }));
+  }
+
+  render() {
+    return html`
+      <button
+        type="button"
+        class="tab"
+        role="tab"
+        aria-selected=${this.selected}
+        tabindex=${this.selected ? 0 : -1}
+        ?disabled=${this.disabled}
+        @click=${this._handleClick}
+      >
+        <slot></slot>
+      </button>
+    `;
+  }
+}
+
+customElements.define('bds-tab', BdsTab);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'bds-tab': BdsTab;
+  }
+}

package/src/web-components/interaction/bds-tabs.spec.ts

@@ -0,0 +1,120 @@
+import { fixture, cleanup } from '../test/helpers';
+import { BdsTabs } from './bds-tabs';
+import { BdsTab } from './bds-tab';
+import { BdsTabPanel } from './bds-tab-panel';
+
+const html = `
+  <bds-tabs>
+    <bds-tab slot="tab">Tab 1</bds-tab>
+    <bds-tab slot="tab">Tab 2</bds-tab>
+    <bds-tab slot="tab" disabled>Tab 3</bds-tab>
+    <bds-tab-panel slot="panel">Panel 1</bds-tab-panel>
+    <bds-tab-panel slot="panel">Panel 2</bds-tab-panel>
+    <bds-tab-panel slot="panel">Panel 3</bds-tab-panel>
+  </bds-tabs>
+`;
+
+describe('bds-tabs', () => {
+  it('is registered as a custom element', () => {
+    expect(customElements.get('bds-tabs')).toBe(BdsTabs);
+  });
+
+  it('renders a tablist div with role="tablist"', async () => {
+    const el = await fixture(html);
+    const tablist = el.shadowRoot!.querySelector('[role="tablist"]');
+    expect(tablist).not.toBeNull();
+    cleanup(el);
+  });
+
+  it('selects the first tab by default', async () => {
+    const el = await fixture(html);
+    // Wait for deferred _applyState
+    await Promise.resolve();
+    const tabs = [...el.querySelectorAll<BdsTab>('bds-tab')];
+    expect(tabs[0].selected).toBe(true);
+    expect(tabs[1].selected).toBe(false);
+    cleanup(el);
+  });
+
+  it('first panel is visible, others are hidden by default', async () => {
+    const el = await fixture(html);
+    await Promise.resolve();
+    const panels = [...el.querySelectorAll<BdsTabPanel>('bds-tab-panel')];
+    expect(panels[0].hasAttribute('hidden')).toBe(false);
+    expect(panels[1].hasAttribute('hidden')).toBe(true);
+    cleanup(el);
+  });
+
+  it('switches to tab on bds-tab-select event', async () => {
+    const el = await fixture(html);
+    await Promise.resolve();
+    const tabs = [...el.querySelectorAll<BdsTab>('bds-tab')];
+    const panels = [...el.querySelectorAll<BdsTabPanel>('bds-tab-panel')];
+
+    tabs[1].dispatchEvent(new CustomEvent('bds-tab-select', { bubbles: true, composed: true }));
+
+    expect(tabs[0].selected).toBe(false);
+    expect(tabs[1].selected).toBe(true);
+    expect(panels[0].hasAttribute('hidden')).toBe(true);
+    expect(panels[1].hasAttribute('hidden')).toBe(false);
+    cleanup(el);
+  });
+
+  it('does not switch to a disabled tab on bds-tab-select', async () => {
+    const el = await fixture(html);
+    await Promise.resolve();
+    const tabs = [...el.querySelectorAll<BdsTab>('bds-tab')];
+    // Ensure the tab is marked disabled (Lit property may not reflect from HTML attribute in jsdom)
+    tabs[2].disabled = true;
+
+    tabs[2].dispatchEvent(new CustomEvent('bds-tab-select', { bubbles: true, composed: true }));
+
+    expect(tabs[0].selected).toBe(true);
+    expect(tabs[2].selected).toBe(false);
+    cleanup(el);
+  });
+
+  it('ArrowRight moves to next enabled tab', async () => {
+    const el = await fixture(html);
+    await Promise.resolve();
+    el.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowRight', bubbles: true }));
+    await Promise.resolve();
+    const tabs = [...el.querySelectorAll<BdsTab>('bds-tab')];
+    expect(tabs[1].selected).toBe(true);
+    cleanup(el);
+  });
+
+  it('ArrowLeft wraps around to last enabled tab', async () => {
+    const el = await fixture(html);
+    await Promise.resolve();
+    const tabs = [...el.querySelectorAll<BdsTab>('bds-tab')];
+    tabs[2].disabled = true; // ensure disabled is set (Lit property may not reflect from HTML attribute in jsdom)
+    el.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowLeft', bubbles: true }));
+    // disabled tab is skipped; enabled tabs are 0 and 1 → wraps to last enabled (index 1)
+    expect(tabs[1].selected).toBe(true);
+    cleanup(el);
+  });
+
+  it('Home moves to the first enabled tab', async () => {
+    const el = await fixture(html);
+    await Promise.resolve();
+    const tabs = [...el.querySelectorAll<BdsTab>('bds-tab')];
+    await Promise.all(tabs.map(t => t.updateComplete));
+    // Navigate to tab 1 first
+    tabs[1].dispatchEvent(new CustomEvent('bds-tab-select', { bubbles: true, composed: true }));
+    el.dispatchEvent(new KeyboardEvent('keydown', { key: 'Home', bubbles: true }));
+    expect(tabs[0].selected).toBe(true);
+    cleanup(el);
+  });
+
+  it('End moves to the last enabled tab', async () => {
+    const el = await fixture(html);
+    await Promise.resolve();
+    const tabs = [...el.querySelectorAll<BdsTab>('bds-tab')];
+    tabs[2].disabled = true; // ensure disabled is set
+    el.dispatchEvent(new KeyboardEvent('keydown', { key: 'End', bubbles: true }));
+    // Last enabled tab is index 1 (tab 3 is disabled)
+    expect(tabs[1].selected).toBe(true);
+    cleanup(el);
+  });
+});

package/src/web-components/interaction/bds-tabs.ts

@@ -0,0 +1,152 @@
+import { LitElement, css, html } from 'lit';
+import type { BdsTab } from './bds-tab';
+import type { BdsTabPanel } from './bds-tab-panel';
+
+/**
+ * `<bds-tabs>` — framework-agnostic Tabs custom element.
+ *
+ * Contains `<bds-tab>` and `<bds-tab-panel>` children. Tabs and panels are
+ * matched by DOM order: the first tab corresponds to the first panel, etc.
+ *
+ * Use `slot="tab"` on `<bds-tab>` elements and `slot="panel"` on
+ * `<bds-tab-panel>` elements.
+ *
+ * Keyboard navigation: ArrowLeft/Right moves between tabs, Home/End jumps to
+ * first/last enabled tab.
+ *
+ * @example
+ * <bds-tabs>
+ *   <bds-tab slot="tab">Overview</bds-tab>
+ *   <bds-tab slot="tab">Details</bds-tab>
+ *   <bds-tab slot="tab" disabled>Disabled</bds-tab>
+ *   <bds-tab-panel slot="panel">Overview content</bds-tab-panel>
+ *   <bds-tab-panel slot="panel">Details content</bds-tab-panel>
+ *   <bds-tab-panel slot="panel">Disabled content</bds-tab-panel>
+ * </bds-tabs>
+ */
+export class BdsTabs extends LitElement {
+  static styles = css`
+    :host {
+      display: flex;
+      flex-direction: column;
+    }
+
+    .tablist {
+      display: flex;
+      border-block-end: 1px solid var(--bds-color_bg--subtle);
+      gap: var(--bds-space_xxs);
+    }
+  `;
+
+  private _activeIndex = 0;
+  private _mo: MutationObserver | null = null;
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.addEventListener('bds-tab-select', this._handleTabSelect);
+    this.addEventListener('keydown', this._handleKeydown);
+    this._mo = new MutationObserver(() => { this._applyState(); });
+    this._mo.observe(this, { childList: true, subtree: false });
+    // Defer initial state so children have been upgraded
+    Promise.resolve().then(() => this._applyState());
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.removeEventListener('bds-tab-select', this._handleTabSelect);
+    this.removeEventListener('keydown', this._handleKeydown);
+    this._mo?.disconnect();
+    this._mo = null;
+  }
+
+  private get _tabs(): BdsTab[] {
+    return [...this.querySelectorAll<BdsTab>('bds-tab')];
+  }
+
+  private get _panels(): BdsTabPanel[] {
+    return [...this.querySelectorAll<BdsTabPanel>('bds-tab-panel')];
+  }
+
+  private get _enabledIndexes(): number[] {
+    return this._tabs
+      .map((tab, i) => ({ tab, i }))
+      .filter(({ tab }) => !tab.disabled)
+      .map(({ i }) => i);
+  }
+
+  private _applyState() {
+    const tabs = this._tabs;
+    const panels = this._panels;
+
+    // Clamp active index if tabs were removed
+    if (this._activeIndex >= tabs.length) {
+      this._activeIndex = Math.max(0, tabs.length - 1);
+    }
+
+    tabs.forEach((tab, i) => {
+      tab.selected = (i === this._activeIndex);
+    });
+
+    panels.forEach((panel, i) => {
+      if (i === this._activeIndex) {
+        panel.removeAttribute('hidden');
+      } else {
+        panel.setAttribute('hidden', '');
+      }
+    });
+  }
+
+  private _handleTabSelect = (e: Event) => {
+    const tab = e.target as BdsTab;
+    const index = this._tabs.indexOf(tab);
+    if (index !== -1 && !tab.disabled) {
+      this._activeIndex = index;
+      this._applyState();
+    }
+  };
+
+  private _handleKeydown = (e: KeyboardEvent) => {
+    const enabled = this._enabledIndexes;
+    if (!enabled.length) return;
+
+    const pos = enabled.indexOf(this._activeIndex);
+
+    let next = -1;
+    if (e.key === 'ArrowRight') {
+      e.preventDefault();
+      next = enabled[(pos + 1) % enabled.length];
+    } else if (e.key === 'ArrowLeft') {
+      e.preventDefault();
+      next = enabled[(pos - 1 + enabled.length) % enabled.length];
+    } else if (e.key === 'Home') {
+      e.preventDefault();
+      next = enabled[0];
+    } else if (e.key === 'End') {
+      e.preventDefault();
+      next = enabled[enabled.length - 1];
+    }
+
+    if (next !== -1) {
+      this._activeIndex = next;
+      this._applyState();
+      this._tabs[next]?.focusButton?.();
+    }
+  };
+
+  render() {
+    return html`
+      <div class="tablist" role="tablist">
+        <slot name="tab"></slot>
+      </div>
+      <slot name="panel"></slot>
+    `;
+  }
+}
+
+customElements.define('bds-tabs', BdsTabs);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'bds-tabs': BdsTabs;
+  }
+}

package/src/web-components/interaction/bds-tooltip.spec.ts

@@ -0,0 +1,49 @@
+import { fixture, cleanup } from '../test/helpers';
+import { BdsTooltip } from './bds-tooltip';
+
+describe('bds-tooltip', () => {
+  it('is registered as a custom element', () => {
+    expect(customElements.get('bds-tooltip')).toBe(BdsTooltip);
+  });
+
+  it('defaults to placement="top"', async () => {
+    const el = await fixture('<bds-tooltip content="Tip"><button>?</button></bds-tooltip>');
+    expect(el.getAttribute('placement')).toBe('top');
+    cleanup(el);
+  });
+
+  it('renders a tooltip span with role="tooltip"', async () => {
+    const el = await fixture('<bds-tooltip content="Helpful text"><button>?</button></bds-tooltip>');
+    const tooltip = el.shadowRoot!.querySelector('[role="tooltip"]');
+    expect(tooltip).not.toBeNull();
+    cleanup(el);
+  });
+
+  it('renders the content text in the tooltip', async () => {
+    const el = await fixture('<bds-tooltip content="Helpful text"><button>?</button></bds-tooltip>');
+    const tooltip = el.shadowRoot!.querySelector('[role="tooltip"]');
+    expect(tooltip!.textContent?.trim()).toBe('Helpful text');
+    cleanup(el);
+  });
+
+  it('applies placement class to the tooltip', async () => {
+    const el = await fixture('<bds-tooltip content="Tip" placement="bottom"><button>?</button></bds-tooltip>');
+    const tooltip = el.shadowRoot!.querySelector('.tooltip');
+    expect(tooltip!.classList.contains('--placement_bottom')).toBe(true);
+    cleanup(el);
+  });
+
+  it('reflects placement property updates', async () => {
+    const el = await fixture('<bds-tooltip content="Tip"><button>?</button></bds-tooltip>') as BdsTooltip;
+    el.placement = 'right';
+    await el.updateComplete;
+    expect(el.getAttribute('placement')).toBe('right');
+    cleanup(el);
+  });
+
+  it('renders slotted trigger content', async () => {
+    const el = await fixture('<bds-tooltip content="Tip"><button type="button">Help</button></bds-tooltip>');
+    expect(el.querySelector('button')!.textContent).toBe('Help');
+    cleanup(el);
+  });
+});