@boostdev/design-system-components 1.1.1 → 1.1.2

package/src/web-components/ui/bds-progress-circle.ts

@@ -0,0 +1,142 @@
+import { LitElement, css, html, nothing } from 'lit';
+
+const SIZE_PX = { small: 40, medium: 64, large: 96 } as const;
+const STROKE_WIDTH = 4;
+
+/**
+ * `<bds-progress-circle>` — framework-agnostic circular Progress custom element.
+ *
+ * Attributes:
+ *   value      — current progress value (required)
+ *   max        — maximum value (default: 100)
+ *   label      — accessible label for the progress bar
+ *   show-value — boolean; when set, displays the percentage in the centre
+ *   size       — "small" | "medium" (default) | "large"
+ *
+ * @example
+ * <bds-progress-circle value="75" label="Loading" show-value></bds-progress-circle>
+ */
+export class BdsProgressCircle extends LitElement {
+  static styles = css`
+    :host {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      position: relative;
+    }
+
+    .svg {
+      display: block;
+    }
+
+    .track {
+      stroke: var(--bds-color_bg--subtle);
+    }
+
+    .fill {
+      stroke: var(--progressCircle_color-active, var(--bdc-color_active));
+      transition: stroke-dashoffset var(--bds-animation_transition-duration) var(--bds-animation_easing);
+    }
+
+    .value {
+      position: absolute;
+      font-size: var(--bds-font_size--body--s);
+      font-weight: var(--bds-font_weight--semibold);
+      font-variant-numeric: tabular-nums;
+      color: var(--bds-color_on-bg);
+      line-height: 1;
+    }
+
+    :host([size='small'])  .value { font-size: 0.5rem; }
+    :host([size='large'])  .value { font-size: var(--bds-font_size--body); }
+
+    @media (prefers-reduced-motion: reduce) {
+      .fill {
+        transition: none;
+      }
+    }
+  `;
+
+  static properties = {
+    value:     { type: Number },
+    max:       { type: Number },
+    label:     { type: String },
+    showValue: { type: Boolean, attribute: 'show-value', reflect: true },
+    size:      { type: String, reflect: true },
+  };
+
+  declare value: number;
+  declare max: number;
+  declare label: string;
+  declare showValue: boolean;
+  declare size: 'small' | 'medium' | 'large';
+
+  constructor() {
+    super();
+    this.value = 0;
+    this.max = 100;
+    this.label = '';
+    this.showValue = false;
+    this.size = 'medium';
+  }
+
+  render() {
+    const percentage = Math.min(100, Math.max(0, (this.value / this.max) * 100));
+    const px = SIZE_PX[this.size] ?? SIZE_PX.medium;
+    const radius = (px - STROKE_WIDTH * 2) / 2;
+    const circumference = 2 * Math.PI * radius;
+    const offset = circumference - (percentage / 100) * circumference;
+    const cx = px / 2;
+
+    return html`
+      <div
+        role="progressbar"
+        aria-label=${this.label}
+        aria-valuenow=${this.value}
+        aria-valuemin="0"
+        aria-valuemax=${this.max}
+        style="position: relative; display: inline-flex; align-items: center; justify-content: center;"
+      >
+        <svg
+          class="svg"
+          width=${px}
+          height=${px}
+          viewBox="0 0 ${px} ${px}"
+          aria-hidden="true"
+        >
+          <circle
+            class="track"
+            cx=${cx}
+            cy=${cx}
+            r=${radius}
+            stroke-width=${STROKE_WIDTH}
+            fill="none"
+          />
+          <circle
+            class="fill"
+            cx=${cx}
+            cy=${cx}
+            r=${radius}
+            stroke-width=${STROKE_WIDTH}
+            fill="none"
+            stroke-dasharray=${circumference}
+            stroke-dashoffset=${offset}
+            stroke-linecap="round"
+            transform="rotate(-90 ${cx} ${cx})"
+          />
+        </svg>
+        ${this.showValue
+          ? html`<span class="value" aria-hidden="true">${Math.round(percentage)}%</span>`
+          : nothing}
+      </div>
+    `;
+  }
+}
+
+customElements.define('bds-progress-circle', BdsProgressCircle);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'bds-progress-circle': BdsProgressCircle;
+  }
+}

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

@@ -0,0 +1,66 @@
+import { fixture, cleanup } from '../test/helpers';
+import { BdsProgress } from './bds-progress';
+
+describe('bds-progress', () => {
+  it('is registered as a custom element', () => {
+    expect(customElements.get('bds-progress')).toBe(BdsProgress);
+  });
+
+  it('defaults to max=100 and size="medium"', async () => {
+    const el = await fixture('<bds-progress value="50" label="Loading"></bds-progress>') as BdsProgress;
+    expect(el.max).toBe(100);
+    expect(el.getAttribute('size')).toBe('medium');
+    cleanup(el);
+  });
+
+  it('renders a progressbar track in shadow DOM', async () => {
+    const el = await fixture('<bds-progress value="50" label="Loading"></bds-progress>');
+    const track = el.shadowRoot!.querySelector('.track');
+    expect(track).not.toBeNull();
+    expect(track!.getAttribute('role')).toBe('progressbar');
+    cleanup(el);
+  });
+
+  it('sets aria-label, aria-valuenow, aria-valuemax on the track', async () => {
+    const el = await fixture('<bds-progress value="60" max="200" label="Upload"></bds-progress>');
+    const track = el.shadowRoot!.querySelector('.track');
+    expect(track!.getAttribute('aria-label')).toBe('Upload');
+    expect(track!.getAttribute('aria-valuenow')).toBe('60');
+    expect(track!.getAttribute('aria-valuemax')).toBe('200');
+    cleanup(el);
+  });
+
+  it('does not render the label row by default', async () => {
+    const el = await fixture('<bds-progress value="50" label="Loading"></bds-progress>');
+    expect(el.shadowRoot!.querySelector('.label-row')).toBeNull();
+    cleanup(el);
+  });
+
+  it('renders label row when show-label is set', async () => {
+    const el = await fixture('<bds-progress value="50" label="Upload" show-label></bds-progress>');
+    const labelRow = el.shadowRoot!.querySelector('.label-row');
+    expect(labelRow).not.toBeNull();
+    expect(labelRow!.querySelector('.label')!.textContent).toBe('Upload');
+    cleanup(el);
+  });
+
+  it('clamps percentage to 100 for value > max', async () => {
+    const el = await fixture('<bds-progress value="150" label="Done" show-label></bds-progress>');
+    const valueSpan = el.shadowRoot!.querySelector('.value');
+    expect(valueSpan!.textContent).toBe('100%');
+    cleanup(el);
+  });
+
+  it('clamps percentage to 0 for negative value', async () => {
+    const el = await fixture('<bds-progress value="-10" label="Done" show-label></bds-progress>');
+    const valueSpan = el.shadowRoot!.querySelector('.value');
+    expect(valueSpan!.textContent).toBe('0%');
+    cleanup(el);
+  });
+
+  it('reflects size attribute', async () => {
+    const el = await fixture('<bds-progress value="50" label="Loading" size="large"></bds-progress>') as BdsProgress;
+    expect(el.getAttribute('size')).toBe('large');
+    cleanup(el);
+  });
+});

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

@@ -0,0 +1,127 @@
+import { LitElement, css, html, nothing } from 'lit';
+
+/**
+ * `<bds-progress>` — framework-agnostic Progress bar custom element.
+ *
+ * Attributes:
+ *   value      — current progress value (required)
+ *   max        — maximum value (default: 100)
+ *   label      — accessible label for the progress bar
+ *   show-label — boolean; when set, displays the label and percentage above the bar
+ *   size       — "small" | "medium" (default) | "large"
+ *
+ * @example
+ * <bds-progress value="60" label="Upload progress" show-label></bds-progress>
+ */
+export class BdsProgress extends LitElement {
+  static styles = css`
+    :host {
+      display: block;
+    }
+
+    .container {
+      display: flex;
+      flex-direction: column;
+      gap: var(--bds-space_xxs);
+      inline-size: 100%;
+    }
+
+    .label-row {
+      display: flex;
+      justify-content: space-between;
+      align-items: baseline;
+      font-size: var(--bds-font_size--body--s);
+      color: var(--bds-color_on-bg);
+    }
+
+    .value {
+      font-variant-numeric: tabular-nums;
+    }
+
+    .track {
+      inline-size: 100%;
+      block-size: var(--progress_height, var(--bds-space_xs));
+      background-color: var(--bds-color_bg--subtle);
+      border-radius: 999px;
+      overflow: hidden;
+    }
+
+    :host([size='small'])  .track { --progress_height: var(--bds-space_xxs); }
+    :host([size='medium']) .track { --progress_height: var(--bds-space_xs); }
+    :host([size='large'])  .track { --progress_height: var(--bds-space_s); }
+
+    .fill {
+      block-size: 100%;
+      background-color: var(--progress_color-active, var(--bdc-color_active));
+      border-radius: 999px;
+      transition: inline-size var(--bds-animation_transition-duration) var(--bds-animation_easing);
+    }
+
+    @media (prefers-reduced-motion: reduce) {
+      .fill {
+        transition: none;
+      }
+    }
+  `;
+
+  static properties = {
+    value:     { type: Number },
+    max:       { type: Number },
+    label:     { type: String },
+    showLabel: { type: Boolean, attribute: 'show-label', reflect: true },
+    size:      { type: String, reflect: true },
+  };
+
+  declare value: number;
+  declare max: number;
+  declare label: string;
+  declare showLabel: boolean;
+  declare size: 'small' | 'medium' | 'large';
+
+  constructor() {
+    super();
+    this.value = 0;
+    this.max = 100;
+    this.label = '';
+    this.showLabel = false;
+    this.size = 'medium';
+  }
+
+  private get _percentage(): number {
+    return Math.min(100, Math.max(0, (this.value / this.max) * 100));
+  }
+
+  render() {
+    const pct = this._percentage;
+    return html`
+      <div class="container">
+        ${this.showLabel
+          ? html`
+              <div class="label-row">
+                <span class="label">${this.label}</span>
+                <span class="value">${Math.round(pct)}%</span>
+              </div>
+            `
+          : nothing}
+        <div
+          class="track"
+          role="progressbar"
+          aria-label=${this.label}
+          aria-valuenow=${this.value}
+          aria-valuemin="0"
+          aria-valuemax=${this.max}
+        >
+          <div class="fill" style="inline-size: ${pct}%"></div>
+        </div>
+      </div>
+    `;
+  }
+}
+
+customElements.define('bds-progress', BdsProgress);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'bds-progress': BdsProgress;
+  }
+}

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

@@ -0,0 +1,70 @@
+import { fixture, cleanup } from '../test/helpers';
+import { BdsRating } from './bds-rating';
+
+describe('bds-rating', () => {
+  it('is registered as a custom element', () => {
+    expect(customElements.get('bds-rating')).toBe(BdsRating);
+  });
+
+  it('defaults to max=5', async () => {
+    const el = await fixture('<bds-rating value="3"></bds-rating>') as BdsRating;
+    expect(el.max).toBe(5);
+    cleanup(el);
+  });
+
+  it('renders a container with role="img"', async () => {
+    const el = await fixture('<bds-rating value="3"></bds-rating>');
+    const container = el.shadowRoot!.querySelector('.rating');
+    expect(container!.getAttribute('role')).toBe('img');
+    cleanup(el);
+  });
+
+  it('sets aria-label with value and max', async () => {
+    const el = await fixture('<bds-rating value="3"></bds-rating>');
+    const container = el.shadowRoot!.querySelector('.rating');
+    expect(container!.getAttribute('aria-label')).toBe('3 out of 5 stars');
+    cleanup(el);
+  });
+
+  it('renders max number of star SVGs', async () => {
+    const el = await fixture('<bds-rating value="3"></bds-rating>');
+    const stars = el.shadowRoot!.querySelectorAll('.star');
+    expect(stars.length).toBe(5);
+    cleanup(el);
+  });
+
+  it('marks the correct stars as filled', async () => {
+    const el = await fixture('<bds-rating value="3"></bds-rating>');
+    const stars = el.shadowRoot!.querySelectorAll('.star');
+    const filledStars = [...stars].filter(s => s.classList.contains('--filled'));
+    expect(filledStars.length).toBe(3);
+    cleanup(el);
+  });
+
+  it('renders correct count with custom max', async () => {
+    const el = await fixture('<bds-rating value="2" max="10"></bds-rating>');
+    const stars = el.shadowRoot!.querySelectorAll('.star');
+    expect(stars.length).toBe(10);
+    const filledStars = [...stars].filter(s => s.classList.contains('--filled'));
+    expect(filledStars.length).toBe(2);
+    cleanup(el);
+  });
+
+  it('stars have aria-hidden="true"', async () => {
+    const el = await fixture('<bds-rating value="3"></bds-rating>');
+    const stars = el.shadowRoot!.querySelectorAll('.star');
+    [...stars].forEach(star => {
+      expect(star.getAttribute('aria-hidden')).toBe('true');
+    });
+    cleanup(el);
+  });
+
+  it('updates when value property changes', async () => {
+    const el = await fixture('<bds-rating value="1"></bds-rating>') as BdsRating;
+    el.value = 4;
+    await el.updateComplete;
+    const filledStars = [...el.shadowRoot!.querySelectorAll('.star')].filter(s => s.classList.contains('--filled'));
+    expect(filledStars.length).toBe(4);
+    cleanup(el);
+  });
+});

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

@@ -0,0 +1,80 @@
+import { LitElement, css, html } from 'lit';
+
+const STAR_PATH = 'M12 17.27L18.18 21l-1.64-7.03L22 9.24l-7.19-.61L12 2 9.19 8.63 2 9.24l5.46 4.73L5.82 21z';
+
+/**
+ * `<bds-rating>` — framework-agnostic read-only star Rating custom element.
+ *
+ * Attributes:
+ *   value — number of filled stars
+ *   max   — total number of stars (default: 5)
+ *
+ * @example
+ * <bds-rating value="3"></bds-rating>
+ * <bds-rating value="4" max="10"></bds-rating>
+ */
+export class BdsRating extends LitElement {
+  static styles = css`
+    :host {
+      display: inline-flex;
+    }
+
+    .rating {
+      display: inline-flex;
+      gap: var(--bds-space_xxxs);
+      color: var(--bds-color_bg);
+    }
+
+    .star {
+      inline-size: 1.5em;
+      block-size: 1.5em;
+    }
+
+    .star.--filled {
+      color: var(--bds-color_warning);
+    }
+  `;
+
+  static properties = {
+    value: { type: Number },
+    max:   { type: Number },
+  };
+
+  declare value: number;
+  declare max: number;
+
+  constructor() {
+    super();
+    this.value = 0;
+    this.max = 5;
+  }
+
+  render() {
+    return html`
+      <div
+        class="rating"
+        role="img"
+        aria-label="${this.value} out of ${this.max} stars"
+      >
+        ${Array.from({ length: this.max }, (_, i) => html`
+          <svg
+            class="star ${i < this.value ? '--filled' : ''}"
+            aria-hidden="true"
+            fill="currentColor"
+            viewBox="0 0 24 24"
+          >
+            <path d=${STAR_PATH} />
+          </svg>
+        `)}
+      </div>
+    `;
+  }
+}
+
+customElements.define('bds-rating', BdsRating);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'bds-rating': BdsRating;
+  }
+}

package/src/web-components/ui/bds-section-header.spec.ts

@@ -0,0 +1,57 @@
+import { fixture, cleanup } from '../test/helpers';
+import { BdsSectionHeader } from './bds-section-header';
+
+describe('bds-section-header', () => {
+  it('is registered as a custom element', () => {
+    expect(customElements.get('bds-section-header')).toBe(BdsSectionHeader);
+  });
+
+  it('renders an <h2> title by default', async () => {
+    const el = await fixture('<bds-section-header title="Hello"></bds-section-header>');
+    const h2 = el.shadowRoot!.querySelector('h2');
+    expect(h2).not.toBeNull();
+    expect(h2!.textContent).toBe('Hello');
+    cleanup(el);
+  });
+
+  it('renders the title text', async () => {
+    const el = await fixture('<bds-section-header title="Welcome"></bds-section-header>');
+    expect(el.shadowRoot!.querySelector('.title')!.textContent).toBe('Welcome');
+    cleanup(el);
+  });
+
+  it('does not render subtitle when not set', async () => {
+    const el = await fixture('<bds-section-header title="Hello"></bds-section-header>');
+    expect(el.shadowRoot!.querySelector('.subtitle')).toBeNull();
+    cleanup(el);
+  });
+
+  it('renders subtitle when set', async () => {
+    const el = await fixture('<bds-section-header title="Hello" subtitle="Subtitle text"></bds-section-header>');
+    const subtitle = el.shadowRoot!.querySelector('.subtitle');
+    expect(subtitle).not.toBeNull();
+    expect(subtitle!.textContent).toBe('Subtitle text');
+    cleanup(el);
+  });
+
+  it('uses title-as to override the title element', async () => {
+    const el = await fixture('<bds-section-header title="Hello" title-as="h1"></bds-section-header>');
+    expect(el.shadowRoot!.querySelector('h1')).not.toBeNull();
+    expect(el.shadowRoot!.querySelector('h2')).toBeNull();
+    cleanup(el);
+  });
+
+  it('applies alignment class', async () => {
+    const el = await fixture('<bds-section-header title="Hello" alignment="center"></bds-section-header>');
+    const header = el.shadowRoot!.querySelector('.header');
+    expect(header!.classList.contains('--center')).toBe(true);
+    cleanup(el);
+  });
+
+  it('applies size class', async () => {
+    const el = await fixture('<bds-section-header title="Hello" size="large"></bds-section-header>');
+    const header = el.shadowRoot!.querySelector('.header');
+    expect(header!.classList.contains('--large')).toBe(true);
+    cleanup(el);
+  });
+});

package/src/web-components/ui/bds-section-header.ts

@@ -0,0 +1,96 @@
+import { LitElement, css, html, nothing } from 'lit';
+import { html as staticHtml, unsafeStatic } from 'lit/static-html.js';
+
+/**
+ * `<bds-section-header>` — framework-agnostic Section Header custom element.
+ *
+ * Attributes:
+ *   title     — heading text (required)
+ *   subtitle  — optional subheading text
+ *   alignment — "start" (default) | "center" | "end"
+ *   size      — "small" | "medium" (default) | "large"
+ *   title-as  — tag name for the title element (default: "h2")
+ *
+ * @example
+ * <bds-section-header title="Our Products" subtitle="Browse the full range" size="large"></bds-section-header>
+ */
+export class BdsSectionHeader extends LitElement {
+  static styles = css`
+    :host {
+      display: block;
+    }
+
+    .header {
+      display: flex;
+      flex-direction: column;
+      gap: var(--bds-space_m);
+    }
+
+    .title {
+      color: var(--sectionHeader-title-color, var(--bds-color_on-bg));
+      margin: 0;
+      font-family: var(--bds-font_family--body);
+    }
+
+    .subtitle {
+      color: var(--sectionHeader_subtitle-color, var(--bds-color_grey--strong));
+      margin: 0;
+      font-family: var(--bds-font_family--body);
+      font-weight: var(--bds-font_weight--medium);
+    }
+
+    .header.--start  { align-items: flex-start; text-align: start; }
+    .header.--center { align-items: center;      text-align: center; }
+    .header.--end    { align-items: flex-end;    text-align: end; }
+
+    .header.--small  .title { font-size: var(--bds-font_size--heading-1); line-height: var(--bds-font_line-height--heading); font-weight: var(--bds-font_weight--bold); }
+    .header.--small  .subtitle { font-size: var(--bds-font_size--body); line-height: 1.4; }
+
+    .header.--medium .title { font-size: var(--bds-font_size--display); line-height: var(--bds-font_line-height--display); font-weight: var(--bds-font_weight--bold); }
+    .header.--medium .subtitle { font-size: var(--bds-font_size--heading-3); line-height: 1.3; }
+
+    .header.--large  .title { font-size: var(--bds-font_size--display); line-height: var(--bds-font_line-height--display); font-weight: var(--bds-font_weight--bold); letter-spacing: var(--bds-font_tracking--tight); }
+    .header.--large  .subtitle { font-size: var(--bds-font_size--heading-2); line-height: 1.3; font-weight: var(--bds-font_weight--medium); }
+  `;
+
+  static properties = {
+    title:     { type: String },
+    subtitle:  { type: String },
+    alignment: { type: String, reflect: true },
+    size:      { type: String, reflect: true },
+    titleAs:   { type: String, attribute: 'title-as' },
+  };
+
+  declare title: string;
+  declare subtitle: string;
+  declare alignment: 'start' | 'center' | 'end';
+  declare size: 'small' | 'medium' | 'large';
+  declare titleAs: string;
+
+  constructor() {
+    super();
+    this.title = '';
+    this.subtitle = '';
+    this.alignment = 'start';
+    this.size = 'medium';
+    this.titleAs = 'h2';
+  }
+
+  render() {
+    const tag = unsafeStatic(this.titleAs || 'h2');
+    return html`
+      <div class="header --${this.alignment} --${this.size}">
+        ${staticHtml`<${tag} class="title">${this.title}</${tag}>`}
+        ${this.subtitle ? html`<p class="subtitle">${this.subtitle}</p>` : nothing}
+      </div>
+    `;
+  }
+}
+
+customElements.define('bds-section-header', BdsSectionHeader);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'bds-section-header': BdsSectionHeader;
+  }
+}

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

@@ -0,0 +1,50 @@
+import { fixture, cleanup } from '../test/helpers';
+import { BdsSeparator } from './bds-separator';
+
+describe('bds-separator', () => {
+  it('is registered as a custom element', () => {
+    expect(customElements.get('bds-separator')).toBe(BdsSeparator);
+  });
+
+  it('defaults to orientation="horizontal"', async () => {
+    const el = await fixture('<bds-separator></bds-separator>');
+    expect(el.getAttribute('orientation')).toBe('horizontal');
+    cleanup(el);
+  });
+
+  it('renders a separator div in shadow DOM', async () => {
+    const el = await fixture('<bds-separator></bds-separator>');
+    const sep = el.shadowRoot!.querySelector('.separator');
+    expect(sep).not.toBeNull();
+    cleanup(el);
+  });
+
+  it('has role="separator"', async () => {
+    const el = await fixture('<bds-separator></bds-separator>');
+    const sep = el.shadowRoot!.querySelector('.separator');
+    expect(sep!.getAttribute('role')).toBe('separator');
+    cleanup(el);
+  });
+
+  it('sets aria-orientation="horizontal" by default', async () => {
+    const el = await fixture('<bds-separator></bds-separator>');
+    const sep = el.shadowRoot!.querySelector('.separator');
+    expect(sep!.getAttribute('aria-orientation')).toBe('horizontal');
+    cleanup(el);
+  });
+
+  it('sets aria-orientation="vertical" when orientation="vertical"', async () => {
+    const el = await fixture('<bds-separator orientation="vertical"></bds-separator>');
+    const sep = el.shadowRoot!.querySelector('.separator');
+    expect(sep!.getAttribute('aria-orientation')).toBe('vertical');
+    cleanup(el);
+  });
+
+  it('reflects orientation property to attribute', async () => {
+    const el = await fixture('<bds-separator></bds-separator>') as BdsSeparator;
+    el.orientation = 'vertical';
+    await el.updateComplete;
+    expect(el.getAttribute('orientation')).toBe('vertical');
+    cleanup(el);
+  });
+});