@boostdev/design-system-components 1.0.2 → 1.1.0

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

@@ -0,0 +1,293 @@
+import { LitElement, css, html, nothing } from 'lit';
+
+export type ButtonVariant = 'default' | 'ghost';
+export type ButtonSize = 'small' | 'medium' | 'large';
+
+/**
+ * `<bds-button>` — framework-agnostic Button custom element.
+ *
+ * Attributes:
+ *   variant   — "default" (filled, default) | "ghost" (transparent + outlined)
+ *   size      — "small" | "medium" (default) | "large"
+ *   disabled  — boolean
+ *   href      — renders an <a> tag instead of <button>
+ *   target    — forwarded to <a> when href is set
+ *   rel       — forwarded to <a> when href is set
+ *   has-pulse — boolean, enables the pulse ring animation
+ *   type      — "button" (default) | "submit" | "reset"
+ *
+ * Slots:
+ *   (default)    — button label
+ *   icon-start   — icon placed before the label
+ *   icon-end     — icon placed after the label
+ *
+ * Events:
+ *   click — standard DOM click (disabled buttons suppress it and set aria-disabled)
+ *
+ * @example
+ * <bds-button variant="ghost" size="small">
+ *   <svg slot="icon-start">…</svg>
+ *   Save
+ * </bds-button>
+ */
+export class BdsButton extends LitElement {
+  static styles = css`
+    @keyframes fadeZoom {
+      0%, 100% { opacity: 1; transform: scale(1); }
+      50%       { opacity: 0.75; transform: scale(1.15); }
+    }
+
+    @keyframes pulse {
+      0%   { transform: scale(1);    box-shadow: 0 0 0 0    rgb(from var(--button_pulse-color, var(--button_color, var(--bds-color_green))) r g b / 50%); }
+      70%  { transform: scale(1.01); box-shadow: 0 0 0 var(--bds-space_m) rgb(from var(--button_pulse-color, var(--button_color, var(--bds-color_green))) r g b / 0%); }
+      100% { transform: scale(1);    box-shadow: 0 0 0 0    rgb(from var(--button_pulse-color, var(--button_color, var(--bds-color_green))) r g b / 0%); }
+    }
+
+    :host {
+      display: inline-flex;
+    }
+
+    .button,
+    .button[href] {
+      all: unset;
+      position: relative;
+      font: inherit;
+      padding-inline: var(--bds-space_l);
+      display: inline-flex;
+      gap: var(--bds-space_xs);
+      border-radius: var(--button_border_radius--s, var(--bds-border_radius--s));
+      align-items: center;
+      cursor: pointer;
+      justify-content: center;
+      height: var(--button_height, 3em);
+      font-size: var(--button_font-size, inherit);
+      white-space: nowrap;
+      line-height: 1;
+
+      --button_color:    var(--bds-color_green);
+      --button_on-color: var(--bds-color_on-green);
+
+      background-color: var(--button_bg, var(--button_color));
+      color: var(--button_text, var(--button_on-color));
+      border: var(--button_border, none);
+      --bdc_color: transparent;
+
+      outline: var(--bdc-outline_width) solid var(--bdc_color);
+      outline-offset: var(--bdc-outline_offset);
+      transition: var(--bds-animation_transition),
+                  --bdc_color var(--bds-animation_transition-duration) var(--bds-animation_easing);
+    }
+
+    .button[href] {
+      text-decoration: none;
+    }
+
+    /* Variants */
+    .button.ghost {
+      --button_bg:   transparent;
+      --button_text: var(--button_color);
+      --bdc_color:   var(--button_color);
+    }
+
+    /* Sizes */
+    .button.small {
+      --button_height:    2.25em;
+      --button_font-size: var(--bds-font_size--body--s);
+      --button_border_radius--s: var(--bds-border_radius--xs);
+      padding-inline: var(--bds-space_m);
+    }
+
+    .button.medium {
+      --button_height: 3em;
+      padding-inline: var(--bds-space_l);
+    }
+
+    .button.large {
+      --button_font-size: var(--bds-font_size--heading-3);
+      --button_border_radius--s: var(--bds-border_radius--m);
+      padding-inline: var(--bds-space_xl);
+    }
+
+    /* Pulse */
+    .button.has-pulse {
+      animation: pulse 3s infinite;
+    }
+
+    /* SVG icon colour */
+    .button svg {
+      --icon__stroke: currentcolor;
+      fill: currentcolor;
+      color: currentcolor;
+      flex-shrink: 0;
+    }
+
+    /* Icon slots — hidden by default, shown when slot has content */
+    .icon-start,
+    .icon-end {
+      display: none;
+      align-items: center;
+    }
+
+    .icon-start.has-content {
+      display: flex;
+      margin-inline-start: calc(var(--bds-space_s) * -1);
+      transition: var(--bds-animation_transition);
+    }
+
+    .icon-end.has-content {
+      display: flex;
+      margin-inline-end: calc(var(--bds-space_s) * -1);
+      transition: var(--bds-animation_transition);
+    }
+
+    /* Hover icon animation */
+    @media (hover: hover) and (pointer: fine) {
+      .button:hover .icon-start svg,
+      .button:hover .icon-end svg {
+        animation: fadeZoom 2s ease-out infinite;
+      }
+
+      /* Default hover */
+      .button.default:hover {
+        --button_bg:          var(--bds-color_bg);
+        --button_text:        var(--bds-color_interactive);
+        --button_pulse-color: var(--bds-color_interactive);
+        --bdc_color:          currentcolor;
+      }
+
+      /* Ghost hover */
+      .button.ghost:hover {
+        --button_bg:   var(--button_color);
+        --button_text: var(--button_on-color);
+        --bdc_color:   transparent;
+      }
+    }
+
+    /* Focus visible */
+    .button:focus-visible {
+      outline: var(--bds-outline_default);
+      outline-offset: var(--bds-outline_offset);
+      border-radius: var(--bds-border_radius--s);
+    }
+
+    /* Disabled */
+    .button:disabled,
+    .button[aria-disabled='true'] {
+      opacity: 0.5;
+      cursor: not-allowed;
+      pointer-events: none;
+    }
+  `;
+
+  static properties = {
+    variant:          { type: String, reflect: true },
+    size:             { type: String, reflect: true },
+    disabled:         { type: Boolean, reflect: true },
+    href:             { type: String },
+    target:           { type: String },
+    rel:              { type: String },
+    hasPulse:         { type: Boolean, attribute: 'has-pulse', reflect: true },
+    type:             { type: String },
+    ariaLabel:        { type: String, attribute: 'aria-label' },
+    // Internal state
+    _iconStartFilled: { state: true },
+    _iconEndFilled:   { state: true },
+  };
+
+  // `declare` annotates the type without emitting a class field initializer
+  // that would shadow Lit's reactive accessors on the prototype.
+  declare variant: ButtonVariant;
+  declare size: ButtonSize;
+  declare disabled: boolean;
+  declare href: string | undefined;
+  declare target: string | undefined;
+  declare rel: string | undefined;
+  declare hasPulse: boolean;
+  declare type: 'button' | 'submit' | 'reset';
+  declare ariaLabel: string | null;
+  declare private _iconStartFilled: boolean;
+  declare private _iconEndFilled: boolean;
+
+  constructor() {
+    super();
+    this.variant = 'default';
+    this.size = 'medium';
+    this.disabled = false;
+    this.hasPulse = false;
+    this.type = 'button';
+    this.ariaLabel = null;
+    this._iconStartFilled = false;
+    this._iconEndFilled = false;
+  }
+
+  private _onIconSlotChange(e: Event, position: 'start' | 'end') {
+    const slot = e.target as HTMLSlotElement;
+    const filled = slot.assignedNodes({ flatten: true }).length > 0;
+    if (position === 'start') {
+      this._iconStartFilled = filled;
+    } else {
+      this._iconEndFilled = filled;
+    }
+  }
+
+  private get _classes() {
+    return `button ${this.variant} ${this.size}${this.hasPulse ? ' has-pulse' : ''}`;
+  }
+
+  private _handleAnchorClick(e: MouseEvent) {
+    if (this.disabled) {
+      e.preventDefault();
+    }
+  }
+
+  private _iconSlot(position: 'start' | 'end') {
+    const filled = position === 'start' ? this._iconStartFilled : this._iconEndFilled;
+    return html`
+      <span class="icon-${position} ${filled ? 'has-content' : ''}">
+        <slot name="icon-${position}" @slotchange=${(e: Event) => this._onIconSlotChange(e, position)}></slot>
+      </span>
+    `;
+  }
+
+  render() {
+    if (this.href) {
+      return html`
+        <a
+          class=${this._classes}
+          href=${this.disabled ? nothing : this.href}
+          target=${this.target ?? nothing}
+          rel=${this.rel ?? nothing}
+          aria-disabled=${this.disabled ? 'true' : nothing}
+          tabindex=${this.disabled ? '-1' : nothing}
+          aria-label=${this.ariaLabel ?? nothing}
+          @click=${this._handleAnchorClick}
+        >
+          ${this._iconSlot('start')}
+          <slot></slot>
+          ${this._iconSlot('end')}
+        </a>
+      `;
+    }
+
+    return html`
+      <button
+        class=${this._classes}
+        type=${this.type}
+        ?disabled=${this.disabled}
+        aria-label=${this.ariaLabel ?? nothing}
+      >
+        ${this._iconSlot('start')}
+        <slot></slot>
+        ${this._iconSlot('end')}
+      </button>
+    `;
+  }
+}
+
+customElements.define('bds-button', BdsButton);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'bds-button': BdsButton;
+  }
+}

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

@@ -0,0 +1,126 @@
+import { fixture, cleanup } from '../test/helpers';
+import { BdsPopover } from './bds-popover';
+
+describe('bds-popover', () => {
+  it('is registered as a custom element', () => {
+    expect(customElements.get('bds-popover')).toBe(BdsPopover);
+  });
+
+  it('defaults to placement="bottom" and open=false', async () => {
+    const el = await fixture('<bds-popover><button slot="trigger">Open</button><p>Content</p></bds-popover>');
+    expect(el.getAttribute('placement')).toBe('bottom');
+    expect(el.hasAttribute('open')).toBe(false);
+    cleanup(el);
+  });
+
+  it('panel is hidden by default (no .open class)', async () => {
+    const el = await fixture('<bds-popover><button slot="trigger">Open</button><p>Content</p></bds-popover>');
+    const panel = el.shadowRoot!.querySelector('.panel');
+    expect(panel!.classList.contains('open')).toBe(false);
+    cleanup(el);
+  });
+
+  it('sets data-placement on the panel', async () => {
+    const el = await fixture('<bds-popover placement="right"><button slot="trigger">Open</button></bds-popover>');
+    const panel = el.shadowRoot!.querySelector('.panel');
+    expect(panel!.getAttribute('data-placement')).toBe('right');
+    cleanup(el);
+  });
+
+  it('opens when trigger slot is clicked', async () => {
+    const el = await fixture('<bds-popover><button slot="trigger">Open</button></bds-popover>') as BdsPopover;
+    const trigger = el.shadowRoot!.querySelector('slot[name="trigger"]')!;
+    trigger.dispatchEvent(new MouseEvent('click', { bubbles: true, composed: true }));
+    await el.updateComplete;
+    expect(el.open).toBe(true);
+    expect(el.hasAttribute('open')).toBe(true);
+    const panel = el.shadowRoot!.querySelector('.panel');
+    expect(panel!.classList.contains('open')).toBe(true);
+    cleanup(el);
+  });
+
+  it('closes when trigger is clicked again', async () => {
+    const el = await fixture('<bds-popover open><button slot="trigger">Open</button></bds-popover>') as BdsPopover;
+    await el.updateComplete;
+    const trigger = el.shadowRoot!.querySelector('slot[name="trigger"]')!;
+    trigger.dispatchEvent(new MouseEvent('click', { bubbles: true, composed: true }));
+    await el.updateComplete;
+    expect(el.open).toBe(false);
+    cleanup(el);
+  });
+
+  it('closes on Escape key', async () => {
+    const el = await fixture('<bds-popover open><button slot="trigger">Open</button></bds-popover>') as BdsPopover;
+    await el.updateComplete;
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+    await el.updateComplete;
+    expect(el.open).toBe(false);
+    cleanup(el);
+  });
+
+  it('closes on outside mousedown', async () => {
+    const el = await fixture('<bds-popover open><button slot="trigger">Open</button></bds-popover>') as BdsPopover;
+    await el.updateComplete;
+    document.body.dispatchEvent(new MouseEvent('mousedown', { bubbles: true }));
+    await el.updateComplete;
+    expect(el.open).toBe(false);
+    cleanup(el);
+  });
+
+  it('does not close on inside mousedown', async () => {
+    const el = await fixture('<bds-popover open><button slot="trigger">Open</button></bds-popover>') as BdsPopover;
+    await el.updateComplete;
+    el.dispatchEvent(new MouseEvent('mousedown', { bubbles: true }));
+    await el.updateComplete;
+    expect(el.open).toBe(true);
+    cleanup(el);
+  });
+
+  it('fires bds-open event when opened', async () => {
+    const el = await fixture('<bds-popover><button slot="trigger">Open</button></bds-popover>') as BdsPopover;
+    const handler = vi.fn();
+    el.addEventListener('bds-open', handler);
+    el.shadowRoot!.querySelector('slot[name="trigger"]')!
+      .dispatchEvent(new MouseEvent('click', { bubbles: true, composed: true }));
+    await el.updateComplete;
+    expect(handler).toHaveBeenCalledOnce();
+    cleanup(el);
+  });
+
+  it('fires bds-close event when closed', async () => {
+    const el = await fixture('<bds-popover open><button slot="trigger">Open</button></bds-popover>') as BdsPopover;
+    await el.updateComplete;
+    const handler = vi.fn();
+    el.addEventListener('bds-close', handler);
+    el.shadowRoot!.querySelector('slot[name="trigger"]')!
+      .dispatchEvent(new MouseEvent('click', { bubbles: true, composed: true }));
+    await el.updateComplete;
+    expect(handler).toHaveBeenCalledOnce();
+    cleanup(el);
+  });
+
+  it('injects a unique anchor-name CSS custom property on :host', async () => {
+    const el = await fixture('<bds-popover><button slot="trigger">Open</button></bds-popover>');
+    const anchorValue = el.style.getPropertyValue('--bds-popover-anchor');
+    expect(anchorValue).toMatch(/^--bds-popover-[a-z0-9]+$/);
+    cleanup(el);
+  });
+
+  it('panel has role="region" and aria-label="Popover"', async () => {
+    const el = await fixture('<bds-popover><button slot="trigger">Open</button></bds-popover>');
+    const panel = el.shadowRoot!.querySelector('.panel');
+    expect(panel!.getAttribute('role')).toBe('region');
+    expect(panel!.getAttribute('aria-label')).toBe('Popover');
+    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>');
+    const anchorA = a.style.getPropertyValue('--bds-popover-anchor');
+    const anchorB = b.style.getPropertyValue('--bds-popover-anchor');
+    expect(anchorA).not.toBe(anchorB);
+    cleanup(a);
+    cleanup(b);
+  });
+});

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

@@ -0,0 +1,217 @@
+import { LitElement, css, html } from 'lit';
+
+export type PopoverPlacement = 'bottom' | 'top' | 'left' | 'right';
+
+/**
+ * `<bds-popover>` — framework-agnostic Popover custom element.
+ *
+ * Uses CSS Anchor Positioning within the shadow DOM so the panel stays
+ * anchored to the trigger and automatically repositions when it would
+ * overflow the viewport (`@position-try` fallbacks).
+ *
+ * Attributes:
+ *   placement — "bottom" (default) | "top" | "left" | "right"
+ *   open      — boolean; reflects whether the panel is visible
+ *
+ * Slots:
+ *   trigger   — the element that opens/closes the panel on click
+ *   (default) — panel content
+ *
+ * Events:
+ *   bds-open  — fired (bubbles, composed) when the panel opens
+ *   bds-close — fired (bubbles, composed) when the panel closes
+ *
+ * @example
+ * <bds-popover placement="bottom">
+ *   <button slot="trigger">Open</button>
+ *   <p>Panel content here</p>
+ * </bds-popover>
+ */
+export class BdsPopover extends LitElement {
+  static styles = css`
+    :host {
+      display: inline-flex;
+      position: relative;
+    }
+
+    /* The wrapper IS the CSS anchor — anchor-name resolves via the custom
+       property injected on :host in connectedCallback(), so each instance
+       gets its own unique name without colliding with siblings. */
+    .wrapper {
+      display: inline-flex;
+      anchor-name: var(--bds-popover-anchor);
+    }
+
+    .panel {
+      display: none;
+      position: absolute;
+      position-anchor: var(--bds-popover-anchor);
+      margin: 0;
+      overflow-y: auto;
+      z-index: var(--popover_z-index, 100);
+      min-width: 12rem;
+      padding: var(--bds-space_m);
+      border-radius: var(--bds-border_radius--s);
+      background-color: var(--popover_color, var(--bds-color_bg));
+      box-shadow: var(--popover_shadow, var(--bds-shadow_m));
+      color: var(--popover_on-color, var(--bds-color_on-bg));
+      font-size: var(--bds-font_size--body);
+    }
+
+    .panel.open {
+      display: block;
+    }
+
+    /* Primary placements */
+
+    .panel[data-placement='bottom'] {
+      top: anchor(bottom);
+      left: anchor(left);
+      margin-top: var(--bds-space_xs, 8px);
+      position-try-fallbacks: --bds-popover-top, --bds-popover-right, --bds-popover-left;
+    }
+
+    .panel[data-placement='top'] {
+      bottom: anchor(top);
+      left: anchor(left);
+      margin-bottom: var(--bds-space_xs, 8px);
+      position-try-fallbacks: --bds-popover-bottom, --bds-popover-right, --bds-popover-left;
+    }
+
+    .panel[data-placement='right'] {
+      top: anchor(top);
+      left: anchor(right);
+      margin-left: var(--bds-space_xs, 8px);
+      position-try-fallbacks: --bds-popover-left, --bds-popover-bottom, --bds-popover-top;
+    }
+
+    .panel[data-placement='left'] {
+      top: anchor(top);
+      right: anchor(left);
+      margin-right: var(--bds-space_xs, 8px);
+      position-try-fallbacks: --bds-popover-right, --bds-popover-bottom, --bds-popover-top;
+    }
+
+    /* Fallback placements */
+
+    @position-try --bds-popover-bottom {
+      top: anchor(bottom);
+      right: unset;
+      bottom: unset;
+      left: anchor(left);
+      margin: 0;
+      margin-top: var(--bds-space_xs, 8px);
+    }
+
+    @position-try --bds-popover-top {
+      top: unset;
+      right: unset;
+      bottom: anchor(top);
+      left: anchor(left);
+      margin: 0;
+      margin-bottom: var(--bds-space_xs, 8px);
+    }
+
+    @position-try --bds-popover-right {
+      top: anchor(top);
+      right: unset;
+      bottom: unset;
+      left: anchor(right);
+      margin: 0;
+      margin-left: var(--bds-space_xs, 8px);
+    }
+
+    @position-try --bds-popover-left {
+      top: anchor(top);
+      right: anchor(left);
+      bottom: unset;
+      left: unset;
+      margin: 0;
+      margin-right: var(--bds-space_xs, 8px);
+    }
+  `;
+
+  static properties = {
+    placement: { type: String, reflect: true },
+    open:      { type: Boolean, reflect: true },
+  };
+
+  declare placement: PopoverPlacement;
+  declare open: boolean;
+
+  private _anchorName: string;
+
+  constructor() {
+    super();
+    this.placement = 'bottom';
+    this.open = false;
+    const uid = Math.random().toString(36).slice(2, 8);
+    this._anchorName = `--bds-popover-${uid}`;
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    // Inject the unique anchor-name as a CSS custom property so both
+    // `.wrapper` (anchor-name) and `.panel` (position-anchor) reference
+    // the same value without hard-coding it in the shared static styles.
+    this.style.setProperty('--bds-popover-anchor', this._anchorName);
+    document.addEventListener('keydown', this._onKeydown);
+    document.addEventListener('mousedown', this._onOutsideClick);
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    document.removeEventListener('keydown', this._onKeydown);
+    document.removeEventListener('mousedown', this._onOutsideClick);
+  }
+
+  private _onKeydown = (e: KeyboardEvent) => {
+    if (this.open && e.key === 'Escape') this._close();
+  };
+
+  private _onOutsideClick = (e: MouseEvent) => {
+    if (this.open && !this.contains(e.target as Node)) this._close();
+  };
+
+  private _toggle() {
+    if (this.open) {
+      this._close();
+    } else {
+      this._open();
+    }
+  }
+
+  private _open() {
+    this.open = true;
+    this.dispatchEvent(new CustomEvent('bds-open', { bubbles: true, composed: true }));
+  }
+
+  private _close() {
+    this.open = false;
+    this.dispatchEvent(new CustomEvent('bds-close', { bubbles: true, composed: true }));
+  }
+
+  render() {
+    return html`
+      <span class="wrapper">
+        <slot name="trigger" @click=${this._toggle}></slot>
+      </span>
+      <div
+        class="panel ${this.open ? 'open' : ''}"
+        data-placement=${this.placement}
+        role="region"
+        aria-label="Popover"
+      >
+        <slot></slot>
+      </div>
+    `;
+  }
+}
+
+customElements.define('bds-popover', BdsPopover);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'bds-popover': BdsPopover;
+  }
+}