@boostdev/design-system-components 1.1.1 → 1.2.0

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

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

@@ -0,0 +1,127 @@
+import { LitElement, css, html } from 'lit';
+
+export type TooltipPlacement = 'top' | 'bottom' | 'left' | 'right';
+
+/**
+ * `<bds-tooltip>` — framework-agnostic Tooltip custom element.
+ *
+ * Shows a tooltip panel on hover and keyboard focus using CSS-only visibility.
+ * The tooltip position is controlled via the `placement` attribute.
+ *
+ * Attributes:
+ *   content   — text to display in the tooltip
+ *   placement — "top" (default) | "bottom" | "left" | "right"
+ *
+ * Slots:
+ *   (default) — the trigger element (button, icon, etc.)
+ *
+ * Accessibility:
+ *   The `aria-describedby` relationship between trigger and tooltip panel
+ *   cannot cross shadow DOM boundaries; screen readers will announce the tooltip
+ *   via role="tooltip" proximity when it becomes visible.
+ *
+ * @example
+ * <bds-tooltip content="More information" placement="bottom">
+ *   <button type="button">?</button>
+ * </bds-tooltip>
+ */
+export class BdsTooltip extends LitElement {
+  static styles = css`
+    :host {
+      display: inline-flex;
+      align-items: center;
+      position: relative;
+    }
+
+    .tooltip {
+      position: absolute;
+      z-index: var(--bds-z-index_popover, 200);
+      padding: var(--bds-space_xxs) var(--bds-space_xs);
+      border-radius: var(--bds-border_radius--xs);
+      background-color: var(--tooltip_bg, var(--bds-color_on-bg));
+      color: var(--tooltip_text, var(--bds-color_bg));
+      font-size: var(--bds-font_size--body--s);
+      line-height: var(--bds-font_line-height--body);
+      white-space: nowrap;
+      pointer-events: none;
+
+      /* Hidden by default */
+      visibility: hidden;
+      opacity: 0;
+      transition: opacity var(--bds-animation_transition-duration) var(--bds-animation_easing);
+    }
+
+    /* Show on hover and keyboard focus */
+    :host(:hover) .tooltip,
+    :host(:focus-within) .tooltip {
+      visibility: visible;
+      opacity: 1;
+    }
+
+    /* Placement: top (default) */
+    .tooltip.--placement_top {
+      inset-block-end: calc(100% + var(--bds-space_xs));
+      inset-inline-start: 50%;
+      transform: translateX(-50%);
+    }
+
+    /* Placement: bottom */
+    .tooltip.--placement_bottom {
+      inset-block-start: calc(100% + var(--bds-space_xs));
+      inset-inline-start: 50%;
+      transform: translateX(-50%);
+    }
+
+    /* Placement: left */
+    .tooltip.--placement_left {
+      inset-inline-end: calc(100% + var(--bds-space_xs));
+      inset-block-start: 50%;
+      transform: translateY(-50%);
+    }
+
+    /* Placement: right */
+    .tooltip.--placement_right {
+      inset-inline-start: calc(100% + var(--bds-space_xs));
+      inset-block-start: 50%;
+      transform: translateY(-50%);
+    }
+
+    @media (prefers-reduced-motion: reduce) {
+      .tooltip {
+        transition: none;
+      }
+    }
+  `;
+
+  static properties = {
+    content:   { type: String },
+    placement: { type: String, reflect: true },
+  };
+
+  declare content: string;
+  declare placement: TooltipPlacement;
+
+  constructor() {
+    super();
+    this.content = '';
+    this.placement = 'top';
+  }
+
+  render() {
+    return html`
+      <slot></slot>
+      <span
+        class="tooltip --placement_${this.placement}"
+        role="tooltip"
+      >${this.content}</span>
+    `;
+  }
+}
+
+customElements.define('bds-tooltip', BdsTooltip);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'bds-tooltip': BdsTooltip;
+  }
+}

package/src/web-components/interaction/form/BdsCheckbox.mdx

@@ -0,0 +1,39 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsCheckbox.stories';
+
+<Meta of={Stories} />
+
+# Checkbox
+
+`<bds-checkbox>` is a form-associated custom element that participates in HTML forms via the Form-Associated Custom Elements API. Native browser validation (`required`) works without any wrapper.
+
+## Usage
+
+```html
+<bds-checkbox name="agree" value="yes" required>I agree to the terms</bds-checkbox>
+```
+
+## Attributes
+
+| Attribute  | Type      | Default | Description                         |
+|------------|-----------|---------|-------------------------------------|
+| `name`     | `string`  | `""`    | Form field name                     |
+| `value`    | `string`  | `"on"`  | Submitted value when checked        |
+| `checked`  | `boolean` | `false` | Whether the checkbox is checked     |
+| `required` | `boolean` | `false` | Marks the field as required         |
+| `disabled` | `boolean` | `false` | Disables interaction                |
+
+## Slots
+
+| Slot      | Description   |
+|-----------|---------------|
+| (default) | Label text    |
+
+## Stories
+
+<Canvas of={Stories.Default} />
+<Canvas of={Stories.AllVariants} />
+
+## Controls
+
+<ArgTypes of={Stories} />

package/src/web-components/interaction/form/BdsCheckbox.stories.tsx

@@ -0,0 +1,73 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../../index';
+
+function BdsCheckbox({
+  label = 'Check me',
+  checked,
+  disabled,
+  required,
+}: {
+  label?: string;
+  checked?: boolean;
+  disabled?: boolean;
+  required?: boolean;
+}) {
+  return React.createElement(
+    'bds-checkbox',
+    {
+      checked: checked || undefined,
+      disabled: disabled || undefined,
+      required: required || undefined,
+    },
+    label,
+  );
+}
+
+const meta = {
+  title: 'Web Components/Interaction/Form/Checkbox',
+  component: BdsCheckbox,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'padded' },
+  argTypes: {
+    checked: { control: 'boolean' },
+    disabled: { control: 'boolean' },
+    required: { control: 'boolean' },
+  },
+} satisfies Meta<typeof BdsCheckbox>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = { args: { label: 'Accept terms and conditions' } };
+export const Checked: Story = { args: { label: 'Already checked', checked: true } };
+export const Disabled: Story = { args: { label: 'Disabled option', disabled: true } };
+export const DisabledChecked: Story = { args: { label: 'Disabled and checked', checked: true, disabled: true } };
+
+export const AllVariants: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
+      {React.createElement('bds-checkbox', null, 'Unchecked')}
+      {React.createElement('bds-checkbox', { checked: true }, 'Checked')}
+      {React.createElement('bds-checkbox', { disabled: true }, 'Disabled')}
+      {React.createElement('bds-checkbox', { checked: true, disabled: true }, 'Disabled checked')}
+      {React.createElement('bds-checkbox', { required: true }, 'Required')}
+    </div>
+  ),
+};
+
+export const Interactive: Story = {
+  render: () => {
+    const [checked, setChecked] = React.useState(false);
+    return (
+      <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
+        <p style={{ margin: 0, fontSize: '0.875rem' }}>State: {checked ? 'checked' : 'unchecked'}</p>
+        {React.createElement(
+          'bds-checkbox',
+          { checked: checked || undefined, onChange: (e: Event) => setChecked((e.target as HTMLInputElement).checked) },
+          'Controlled checkbox',
+        )}
+      </div>
+    );
+  },
+};

package/src/web-components/interaction/form/BdsCombobox.mdx

@@ -0,0 +1,52 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsCombobox.stories';
+
+<Meta of={Stories} />
+
+# Combobox
+
+`<bds-combobox>` is a form-associated autocomplete input. The user types to filter options and selects with Enter or mouse click. Keyboard navigation: ArrowDown/ArrowUp to move focus, Enter to select, Escape to close.
+
+## Usage
+
+```html
+<bds-combobox
+  name="country"
+  placeholder="Search…"
+  options='[{"value":"nl","label":"Netherlands"},{"value":"be","label":"Belgium"}]'
+></bds-combobox>
+```
+
+## Attributes
+
+| Attribute     | Type      | Default | Description                                         |
+|---------------|-----------|---------|-----------------------------------------------------|
+| `name`        | `string`  | `""`    | Form field name                                     |
+| `value`       | `string`  | `""`    | Currently selected value                            |
+| `options`     | `string`  | `"[]"`  | JSON array of `{ value, label, disabled? }` objects |
+| `placeholder` | `string`  | `""`    | Input placeholder text                              |
+| `disabled`    | `boolean` | `false` | Disables the combobox                               |
+
+## Events
+
+| Event        | Detail                     | Description                      |
+|--------------|----------------------------|----------------------------------|
+| `bds-change` | `{ value, label }`         | Fired when an option is selected |
+
+## Keyboard Navigation
+
+| Key         | Action                  |
+|-------------|-------------------------|
+| `ArrowDown` | Move to next option     |
+| `ArrowUp`   | Move to previous option |
+| `Enter`     | Select focused option   |
+| `Escape`    | Close the listbox       |
+
+## Stories
+
+<Canvas of={Stories.Default} />
+<Canvas of={Stories.AllVariants} />
+
+## Controls
+
+<ArgTypes of={Stories} />