@boostdev/design-system-components 1.1.0 → 1.1.2

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

@@ -0,0 +1,266 @@
+import { LitElement, css, html } from 'lit';
+
+const FOCUSABLE = 'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])';
+
+export type DrawerSide = 'left' | 'right';
+
+/**
+ * `<bds-drawer>` — framework-agnostic Drawer (slide-in panel) custom element.
+ *
+ * Same modal infrastructure as `<bds-dialog>` but positioned as a side panel.
+ * Uses a native `<dialog>` element with a slide-in inner panel.
+ *
+ * Attributes:
+ *   open — boolean; controlled open state
+ *   side — "left" | "right" (default: "right")
+ *
+ * Slots:
+ *   title   — drawer title text
+ *   (default) — drawer body content
+ *
+ * Events:
+ *   bds-open  — fired (bubbles, composed) when the drawer opens
+ *   bds-close — fired (bubbles, composed) when the drawer closes
+ *
+ * @example
+ * <bds-drawer id="my-drawer" side="right">
+ *   <span slot="title">Settings</span>
+ *   <p>Drawer content</p>
+ * </bds-drawer>
+ * <button commandfor="my-drawer" command="show-modal">Open</button>
+ */
+export class BdsDrawer extends LitElement {
+  static styles = css`
+    :host {
+      display: contents;
+    }
+
+    .drawer {
+      position: fixed;
+      inset: 0;
+      margin: 0;
+      padding: 0;
+      inline-size: 100%;
+      max-inline-size: 100%;
+      block-size: 100%;
+      max-block-size: 100%;
+      border: none;
+      background: transparent;
+      overflow: hidden;
+    }
+
+    .drawer::backdrop {
+      background-color: var(--color_backdrop, rgb(0 0 0 / 50%));
+      backdrop-filter: blur(3px);
+    }
+
+    .panel {
+      position: absolute;
+      inset-block: 0;
+      display: flex;
+      flex-direction: column;
+      inline-size: min(28rem, 90vw);
+      block-size: 100%;
+      background-color: var(--drawer_color, var(--bds-color_bg));
+      color: var(--drawer_on-color, var(--bds-color_on-bg));
+      box-shadow: var(--bds-shadow_xl);
+      overflow: hidden;
+      transition: var(--bds-animation_transition);
+    }
+
+    :host([side='right']) .panel {
+      inset-inline-end: 0;
+    }
+
+    :host([side='left']) .panel,
+    :host(:not([side])) .panel {
+      inset-inline-start: 0;
+    }
+
+    .header {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      padding: var(--bds-space_m) var(--bds-space_l);
+      border-block-end: 1px solid currentcolor;
+      flex-shrink: 0;
+    }
+
+    .title {
+      font-weight: var(--bds-font_weight--semibold);
+      font-size: var(--bds-font_size--body);
+    }
+
+    .close-button {
+      all: unset;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      inline-size: 2rem;
+      block-size: 2rem;
+      border-radius: 50%;
+      cursor: pointer;
+      transition: var(--bds-animation_transition);
+    }
+
+    .close-button svg {
+      inline-size: 1.25rem;
+      block-size: 1.25rem;
+    }
+
+    .close-button:focus-visible {
+      outline: var(--bds-outline_default);
+      outline-offset: var(--bds-outline_offset);
+    }
+
+    @media (hover: hover) and (pointer: fine) {
+      .close-button:hover {
+        background-color: var(--bds-color_bg--subtle);
+      }
+    }
+
+    .body {
+      flex: 1;
+      overflow-block: auto;
+      padding: var(--bds-space_l);
+      display: flex;
+      flex-direction: column;
+    }
+
+    @media (prefers-reduced-motion: reduce) {
+      .panel {
+        transition: none;
+      }
+    }
+  `;
+
+  static properties = {
+    open: { type: Boolean, reflect: true },
+    side: { type: String, reflect: true },
+  };
+
+  declare open: boolean;
+  declare side: DrawerSide;
+
+  private _triggerEl: Element | null = null;
+
+  constructor() {
+    super();
+    this.open = false;
+    this.side = 'right';
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.addEventListener('command', this._onCommand);
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.removeEventListener('command', this._onCommand);
+  }
+
+  updated(changed: Map<string, unknown>) {
+    super.updated(changed);
+    if (changed.has('open')) {
+      const dialog = this._dialog;
+      if (!dialog) return;
+      if (this.open && !dialog.open) {
+        this._triggerEl = document.activeElement;
+        dialog.showModal();
+        document.body.style.overflow = 'hidden';
+      } else if (!this.open && dialog.open) {
+        dialog.close();
+        document.body.style.overflow = '';
+        (this._triggerEl as HTMLElement | null)?.focus();
+        this._triggerEl = null;
+      }
+    }
+  }
+
+  private get _dialog(): HTMLDialogElement | null {
+    return this.shadowRoot?.querySelector('dialog') ?? null;
+  }
+
+  private _onCommand = (e: Event) => {
+    const command = (e as CommandEvent).command;
+    if (command === 'show-modal') this._openDrawer();
+    else if (command === 'close') this._closeDrawer();
+  };
+
+  private _openDrawer() {
+    if (this.open) return;
+    this._triggerEl = document.activeElement;
+    this.open = true;
+    this.dispatchEvent(new CustomEvent('bds-open', { bubbles: true, composed: true }));
+  }
+
+  private _closeDrawer() {
+    if (!this.open) return;
+    this.open = false;
+    this.dispatchEvent(new CustomEvent('bds-close', { bubbles: true, composed: true }));
+  }
+
+  private _handleBackdropClick(e: MouseEvent) {
+    if (e.target === this._dialog) this._closeDrawer();
+  }
+
+  private _handleCancel(e: Event) {
+    e.preventDefault();
+    this._closeDrawer();
+  }
+
+  private _handleKeydown(e: KeyboardEvent) {
+    if (e.key !== 'Tab') return;
+    const dialog = this._dialog;
+    if (!dialog) return;
+    const focusable = Array.from(dialog.querySelectorAll<HTMLElement>(FOCUSABLE));
+    if (focusable.length === 0) return;
+    const first = focusable[0];
+    const last = focusable[focusable.length - 1];
+    if (e.shiftKey) {
+      if (document.activeElement === first) { e.preventDefault(); last.focus(); }
+    } else {
+      if (document.activeElement === last) { e.preventDefault(); first.focus(); }
+    }
+  }
+
+  render() {
+    return html`
+      <dialog
+        class="drawer"
+        aria-modal="true"
+        @click=${this._handleBackdropClick}
+        @cancel=${this._handleCancel}
+        @keydown=${this._handleKeydown}
+      >
+        <div class="panel">
+          <div class="header">
+            <span class="title"><slot name="title"></slot></span>
+            <button
+              type="button"
+              class="close-button"
+              aria-label="Close drawer"
+              @click=${this._closeDrawer}
+            >
+              <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                <path stroke-linecap="round" stroke-linejoin="round" d="M18 6L6 18M6 6l12 12" />
+              </svg>
+            </button>
+          </div>
+          <div class="body">
+            <slot></slot>
+          </div>
+        </div>
+      </dialog>
+    `;
+  }
+}
+
+customElements.define('bds-drawer', BdsDrawer);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'bds-drawer': BdsDrawer;
+  }
+}

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

@@ -1,4 +1,4 @@
-import { fixture, cleanup } from '../test/helpers';
+import { fixture, cleanup, makeCommandEvent } from '../test/helpers';
 import { BdsPopover } from './bds-popover';
 
 describe('bds-popover', () => {
@@ -114,6 +114,54 @@ describe('bds-popover', () => {
     cleanup(el);
   });
 
+  describe('Invoker Commands API (command event on host)', () => {
+    it('opens on --open command', async () => {
+      const el = await fixture('<bds-popover id="p1"><button slot="trigger">T</button></bds-popover>') as BdsPopover;
+      el.dispatchEvent(makeCommandEvent('--open'));
+      await el.updateComplete;
+      expect(el.open).toBe(true);
+      cleanup(el);
+    });
+
+    it('closes on --close command', async () => {
+      const el = await fixture('<bds-popover id="p2" open><button slot="trigger">T</button></bds-popover>') as BdsPopover;
+      await el.updateComplete;
+      el.dispatchEvent(makeCommandEvent('--close'));
+      await el.updateComplete;
+      expect(el.open).toBe(false);
+      cleanup(el);
+    });
+
+    it('toggles on --toggle command', async () => {
+      const el = await fixture('<bds-popover id="p3"><button slot="trigger">T</button></bds-popover>') as BdsPopover;
+      el.dispatchEvent(makeCommandEvent('--toggle'));
+      await el.updateComplete;
+      expect(el.open).toBe(true);
+      el.dispatchEvent(makeCommandEvent('--toggle'));
+      await el.updateComplete;
+      expect(el.open).toBe(false);
+      cleanup(el);
+    });
+
+    it('fires bds-open event on --open command', async () => {
+      const el = await fixture('<bds-popover id="p4"><button slot="trigger">T</button></bds-popover>') as BdsPopover;
+      const handler = vi.fn();
+      el.addEventListener('bds-open', handler);
+      el.dispatchEvent(makeCommandEvent('--open'));
+      await el.updateComplete;
+      expect(handler).toHaveBeenCalledOnce();
+      cleanup(el);
+    });
+
+    it('ignores unknown commands', async () => {
+      const el = await fixture('<bds-popover id="p5"><button slot="trigger">T</button></bds-popover>') as BdsPopover;
+      el.dispatchEvent(makeCommandEvent('--unknown'));
+      await el.updateComplete;
+      expect(el.open).toBe(false);
+      cleanup(el);
+    });
+  });
+
   it('two instances get different anchor names', async () => {
     const a = await fixture('<bds-popover><button slot="trigger">A</button></bds-popover>');
     const b = await fixture('<bds-popover><button slot="trigger">B</button></bds-popover>');

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

@@ -157,18 +157,28 @@ export class BdsPopover extends LitElement {
     this.style.setProperty('--bds-popover-anchor', this._anchorName);
     document.addEventListener('keydown', this._onKeydown);
     document.addEventListener('mousedown', this._onOutsideClick);
+    // Invoker Commands API — host is in light DOM so commandfor can reference its id.
+    this.addEventListener('command', this._onCommand);
   }
 
   disconnectedCallback() {
     super.disconnectedCallback();
     document.removeEventListener('keydown', this._onKeydown);
     document.removeEventListener('mousedown', this._onOutsideClick);
+    this.removeEventListener('command', this._onCommand);
   }
 
   private _onKeydown = (e: KeyboardEvent) => {
     if (this.open && e.key === 'Escape') this._close();
   };
 
+  private _onCommand = (e: Event) => {
+    const command = (e as CommandEvent).command;
+    if (command === '--toggle') this._toggle();
+    else if (command === '--open') this._open();
+    else if (command === '--close') this._close();
+  };
+
   private _onOutsideClick = (e: MouseEvent) => {
     if (this.open && !this.contains(e.target as Node)) this._close();
   };
@@ -182,11 +192,13 @@ export class BdsPopover extends LitElement {
   }
 
   private _open() {
+    if (this.open) return;
     this.open = true;
     this.dispatchEvent(new CustomEvent('bds-open', { bubbles: true, composed: true }));
   }
 
   private _close() {
+    if (!this.open) return;
     this.open = false;
     this.dispatchEvent(new CustomEvent('bds-close', { bubbles: true, composed: true }));
   }

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

@@ -0,0 +1,42 @@
+import { fixture, cleanup } from '../test/helpers';
+import { BdsSkipLink } from './bds-skip-link';
+
+describe('bds-skip-link', () => {
+  it('is registered as a custom element', () => {
+    expect(customElements.get('bds-skip-link')).toBe(BdsSkipLink);
+  });
+
+  it('defaults to href="#main"', async () => {
+    const el = await fixture('<bds-skip-link></bds-skip-link>') as BdsSkipLink;
+    expect(el.href).toBe('#main');
+    cleanup(el);
+  });
+
+  it('renders an <a> element in shadow DOM', async () => {
+    const el = await fixture('<bds-skip-link></bds-skip-link>');
+    const a = el.shadowRoot!.querySelector('a.skip-link');
+    expect(a).not.toBeNull();
+    cleanup(el);
+  });
+
+  it('uses the href attribute on the anchor', async () => {
+    const el = await fixture('<bds-skip-link href="#content"></bds-skip-link>');
+    const a = el.shadowRoot!.querySelector('a');
+    expect(a!.getAttribute('href')).toBe('#content');
+    cleanup(el);
+  });
+
+  it('renders default slot text "Skip to main content"', async () => {
+    const el = await fixture('<bds-skip-link></bds-skip-link>');
+    // The slot default content is not visible in textContent from light DOM.
+    // Verify the anchor exists and the slot is present.
+    expect(el.shadowRoot!.querySelector('slot')).not.toBeNull();
+    cleanup(el);
+  });
+
+  it('renders slotted link text', async () => {
+    const el = await fixture('<bds-skip-link href="#main">Go to main</bds-skip-link>');
+    expect(el.textContent?.trim()).toBe('Go to main');
+    cleanup(el);
+  });
+});

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