@boostdev/design-system-components 1.2.0 → 1.2.1

package/src/web-components/interaction/form/bds-form-input.ts

@@ -0,0 +1,268 @@
+import { LitElement, css, html } from 'lit';
+
+/**
+ * `<bds-form-input>` — form-associated text input with label, hint, and error support.
+ *
+ * Participates in HTML forms via the Form-Associated Custom Elements API.
+ *
+ * Attributes:
+ *   name        — form field name
+ *   type        — input type: text | email | password | search | url | tel (default: "text")
+ *   value       — current value
+ *   placeholder — placeholder text
+ *   label       — visible label text
+ *   hint        — helper text shown below the input
+ *   error       — error message; when set the input enters error state
+ *   disabled    — disables the input
+ *   required    — marks the field as required
+ *
+ * Slots:
+ *   prefix — icon or text rendered before the input
+ *   suffix — icon or text rendered after the input
+ *
+ * Events:
+ *   bds-change — fired on value change; `detail: { value: string }`
+ *   bds-input  — fired on every keystroke; `detail: { value: string }`
+ *
+ * @example
+ * <bds-form-input name="email" type="email" label="Email address" required></bds-form-input>
+ */
+export class BdsFormInput extends LitElement {
+  static formAssociated = true;
+
+  static styles = css`
+    :host {
+      display: block;
+    }
+
+    :host([disabled]) {
+      opacity: 0.5;
+      pointer-events: none;
+    }
+
+    .label {
+      display: block;
+      font-size: var(--bds-font_size--body--s);
+      font-family: var(--bds-font_family--body);
+      font-weight: var(--bds-font_weight--semibold);
+      color: var(--bds-color_on-bg);
+      margin-block-end: var(--bds-space_xxs);
+    }
+
+    .required {
+      color: var(--bds-color_error);
+      margin-inline-start: var(--bds-space_xxxs);
+    }
+
+    .wrapper {
+      position: relative;
+      display: flex;
+      align-items: center;
+      --bdc_color: currentcolor;
+      --bdc-outline_radius: var(--bds-border_radius--xs);
+
+      border-radius: var(--formInput_radius, var(--bdc-outline_radius));
+      box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color), var(--formInput_shadow, var(--bdc-outline_shadow));
+      background-color: var(--bds-color_bg);
+      transition: --bdc_color var(--bds-animation_transition-duration) var(--bds-animation_easing);
+    }
+
+    :host([error]) .wrapper {
+      --bdc_color: var(--bds-color_error);
+    }
+
+    .wrapper:focus-within {
+      --bdc_color: var(--bdc_color--focus);
+    }
+
+    :host([error]) .wrapper:focus-within {
+      --bdc_color: var(--bds-color_error);
+    }
+
+    .input {
+      flex: 1;
+      min-inline-size: 0;
+      border: none;
+      background: transparent;
+      padding: var(--bds-space_s);
+      font-size: var(--bds-font_size--body);
+      font-family: var(--bds-font_family--body);
+      color: var(--bds-color_on-bg);
+      outline: none;
+    }
+
+    .input::placeholder {
+      color: var(--bds-color_on-bg--subtle);
+    }
+
+    .input:focus-visible {
+      outline: none;
+    }
+
+    .wrapper:focus-within {
+      outline: var(--bds-outline_default);
+      outline-offset: var(--bds-outline_offset);
+      border-radius: var(--formInput_radius, var(--bdc-outline_radius));
+    }
+
+    .prefix,
+    .suffix {
+      display: flex;
+      align-items: center;
+      color: var(--bds-color_on-bg--subtle);
+      flex-shrink: 0;
+    }
+
+    .prefix {
+      padding-inline-start: var(--bds-space_s);
+    }
+
+    .suffix {
+      padding-inline-end: var(--bds-space_s);
+    }
+
+    .prefix:empty,
+    .suffix:empty {
+      display: none;
+    }
+
+    .message {
+      margin-block-start: var(--bds-space_xxs);
+      font-size: var(--bds-font_size--body--s);
+      font-family: var(--bds-font_family--body);
+    }
+
+    .message--error {
+      color: var(--bds-color_error);
+    }
+
+    .message--hint {
+      color: var(--bds-color_on-bg--subtle);
+    }
+  `;
+
+  static properties = {
+    name:        { type: String, reflect: true },
+    type:        { type: String, reflect: true },
+    value:       { type: String },
+    placeholder: { type: String },
+    label:       { type: String },
+    hint:        { type: String },
+    error:       { type: String, reflect: true },
+    disabled:    { type: Boolean, reflect: true },
+    required:    { type: Boolean, reflect: true },
+  };
+
+  declare name: string;
+  declare type: string;
+  declare value: string;
+  declare placeholder: string;
+  declare label: string;
+  declare hint: string | undefined;
+  declare error: string | undefined;
+  declare disabled: boolean;
+  declare required: boolean;
+
+  private _internals!: ElementInternals;
+  private readonly _uid = Math.random().toString(36).slice(2, 8);
+
+  constructor() {
+    super();
+    this._internals = this.attachInternals();
+    this.name = '';
+    this.type = 'text';
+    this.value = '';
+    this.placeholder = '';
+    this.label = '';
+    this.disabled = false;
+    this.required = false;
+  }
+
+  updated(changed: Map<string, unknown>) {
+    super.updated(changed);
+    if (changed.has('value')) {
+      this._internals.setFormValue?.(this.value);
+    }
+    if (changed.has('required') || changed.has('value')) {
+      if (this.required && !this.value) {
+        this._internals.setValidity?.({ valueMissing: true }, 'Required');
+      } else {
+        this._internals.setValidity?.({});
+      }
+    }
+  }
+
+  formResetCallback() {
+    this.value = '';
+    this._internals.setFormValue?.('');
+  }
+
+  private _handleInput(e: Event) {
+    const input = e.target as HTMLInputElement;
+    this.value = input.value;
+    this.dispatchEvent(new CustomEvent('bds-input', {
+      detail: { value: this.value },
+      bubbles: true,
+      composed: true,
+    }));
+  }
+
+  private _handleChange(e: Event) {
+    const input = e.target as HTMLInputElement;
+    this.value = input.value;
+    this.dispatchEvent(new CustomEvent('bds-change', {
+      detail: { value: this.value },
+      bubbles: true,
+      composed: true,
+    }));
+  }
+
+  render() {
+    const id = `bds-form-input-${this._uid}`;
+    const hintId = `${id}-hint`;
+    const errorId = `${id}-error`;
+    const describedBy = [this.error && errorId, this.hint && hintId].filter(Boolean).join(' ') || undefined;
+
+    return html`
+      ${this.label
+        ? html`
+            <label class="label" for=${id}>
+              ${this.label}
+              ${this.required ? html`<span class="required" aria-hidden="true">*</span>` : ''}
+            </label>
+          `
+        : ''}
+      <div class="wrapper">
+        <span class="prefix"><slot name="prefix"></slot></span>
+        <input
+          id=${id}
+          class="input"
+          type=${this.type}
+          .value=${this.value}
+          placeholder=${this.placeholder}
+          ?disabled=${this.disabled}
+          ?required=${this.required}
+          aria-invalid=${this.error ? 'true' : 'false'}
+          aria-describedby=${describedBy ?? ''}
+          aria-required=${this.required ? 'true' : 'false'}
+          @input=${this._handleInput}
+          @change=${this._handleChange}
+        />
+        <span class="suffix"><slot name="suffix"></slot></span>
+      </div>
+      ${this.error
+        ? html`<p id=${errorId} class="message message--error" role="alert">${this.error}</p>`
+        : this.hint
+          ? html`<p id=${hintId} class="message message--hint">${this.hint}</p>`
+          : ''}
+    `;
+  }
+}
+
+customElements.define('bds-form-input', BdsFormInput);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'bds-form-input': BdsFormInput;
+  }
+}

package/src/web-components/interaction/form/bds-radio-group.spec.ts

@@ -0,0 +1,62 @@
+import { fixture, cleanup } from '../../test/helpers';
+import { BdsRadioGroup } from './bds-radio-group';
+
+describe('bds-radio-group', () => {
+  it('is registered as a custom element', () => {
+    expect(customElements.get('bds-radio-group')).toBe(BdsRadioGroup);
+  });
+
+  it('renders a fieldset', async () => {
+    const el = await fixture('<bds-radio-group label="Options"></bds-radio-group>');
+    expect(el.shadowRoot!.querySelector('fieldset')).not.toBeNull();
+    cleanup(el);
+  });
+
+  it('renders the label as a legend', async () => {
+    const el = await fixture('<bds-radio-group label="Select one"></bds-radio-group>');
+    const legend = el.shadowRoot!.querySelector('legend');
+    expect(legend?.textContent?.trim()).toContain('Select one');
+    cleanup(el);
+  });
+
+  it('disables the fieldset when disabled', async () => {
+    const el = await fixture('<bds-radio-group label="Test" disabled></bds-radio-group>');
+    const fieldset = el.shadowRoot!.querySelector('fieldset')!;
+    expect(fieldset.disabled).toBe(true);
+    cleanup(el);
+  });
+
+  it('renders a slot for radio children', async () => {
+    const el = await fixture('<bds-radio-group label="Test"></bds-radio-group>');
+    expect(el.shadowRoot!.querySelector('slot')).not.toBeNull();
+    cleanup(el);
+  });
+
+  it('renders error message when error attribute is set', async () => {
+    const el = await fixture('<bds-radio-group label="Test" error="Required field"></bds-radio-group>');
+    const message = el.shadowRoot!.querySelector('.message--error');
+    expect(message?.textContent?.trim()).toBe('Required field');
+    cleanup(el);
+  });
+
+  it('reflects name attribute', async () => {
+    const el = await fixture('<bds-radio-group label="Test" name="contact"></bds-radio-group>') as BdsRadioGroup;
+    expect(el.name).toBe('contact');
+    cleanup(el);
+  });
+
+  it('propagates name to slotted bds-radio elements', async () => {
+    // Define a minimal bds-radio stub so querySelectorAll finds it
+    if (!customElements.get('bds-radio-stub')) {
+      customElements.define('bds-radio-stub', class extends HTMLElement {});
+    }
+    const el = await fixture(
+      '<bds-radio-group label="Contact" name="contact"><bds-radio value="email">Email</bds-radio></bds-radio-group>',
+    ) as BdsRadioGroup;
+    // Wait for propagation promise
+    await Promise.resolve();
+    const radio = el.querySelector('bds-radio');
+    expect(radio?.getAttribute('name')).toBe('contact');
+    cleanup(el);
+  });
+});

package/src/web-components/interaction/form/bds-radio-group.ts

@@ -0,0 +1,142 @@
+import { LitElement, css, html } from 'lit';
+
+/**
+ * `<bds-radio-group>` — groups related radio buttons with a shared label and name.
+ *
+ * Renders a `<fieldset>` with a `<legend>`. Propagates the `name` attribute to
+ * all slotted `<bds-radio>` elements so radios form a mutually-exclusive set.
+ *
+ * Attributes:
+ *   label    — visible group label (rendered as `<legend>`)
+ *   name     — shared name forwarded to all slotted `<bds-radio>` elements
+ *   error    — error message shown below items
+ *   hint     — hint text shown below items
+ *   disabled — disables the entire fieldset
+ *   required — marks the group as required
+ *
+ * Slots:
+ *   (default) — `<bds-radio>` elements
+ *
+ * @example
+ * <bds-radio-group label="Preferred contact" name="contact">
+ *   <bds-radio value="email">Email</bds-radio>
+ *   <bds-radio value="phone">Phone</bds-radio>
+ * </bds-radio-group>
+ */
+export class BdsRadioGroup extends LitElement {
+  static styles = css`
+    :host {
+      display: block;
+    }
+
+    fieldset {
+      border: none;
+      margin: 0;
+      padding: 0;
+    }
+
+    .legend {
+      font-size: var(--bds-font_size--body--s);
+      font-family: var(--bds-font_family--body);
+      font-weight: var(--bds-font_weight--semibold);
+      color: var(--bds-color_on-bg);
+      margin-block-end: var(--bds-space_xs);
+    }
+
+    .required {
+      color: var(--bds-color_error);
+      margin-inline-start: var(--bds-space_xxxs);
+    }
+
+    .items {
+      display: flex;
+      flex-direction: column;
+      gap: var(--bds-space_xs);
+    }
+
+    .message {
+      margin-block-start: var(--bds-space_xs);
+      font-size: var(--bds-font_size--body--s);
+      font-family: var(--bds-font_family--body);
+    }
+
+    .message--error {
+      color: var(--bds-color_error);
+    }
+
+    .message--hint {
+      color: var(--bds-color_on-bg--subtle);
+    }
+  `;
+
+  static properties = {
+    label:    { type: String },
+    name:     { type: String, reflect: true },
+    error:    { type: String },
+    hint:     { type: String },
+    disabled: { type: Boolean, reflect: true },
+    required: { type: Boolean, reflect: true },
+  };
+
+  declare label: string;
+  declare name: string;
+  declare error: string | undefined;
+  declare hint: string | undefined;
+  declare disabled: boolean;
+  declare required: boolean;
+
+  constructor() {
+    super();
+    this.label = '';
+    this.name = '';
+    this.disabled = false;
+    this.required = false;
+  }
+
+  private _propagateName = () => {
+    if (!this.name) return;
+    this.querySelectorAll('bds-radio').forEach(radio => {
+      (radio as HTMLElement).setAttribute('name', this.name);
+    });
+  };
+
+  connectedCallback() {
+    super.connectedCallback();
+    // Propagate name after slot content has been parsed
+    Promise.resolve().then(this._propagateName);
+  }
+
+  updated(changed: Map<string, unknown>) {
+    super.updated(changed);
+    if (changed.has('name')) {
+      this._propagateName();
+    }
+  }
+
+  render() {
+    return html`
+      <fieldset ?disabled=${this.disabled}>
+        <legend class="legend">
+          ${this.label}
+          ${this.required ? html`<span class="required" aria-hidden="true"> *</span>` : ''}
+        </legend>
+        <div class="items">
+          <slot @slotchange=${this._propagateName}></slot>
+        </div>
+        ${this.error
+          ? html`<p class="message message--error" role="alert">${this.error}</p>`
+          : this.hint
+            ? html`<p class="message message--hint">${this.hint}</p>`
+            : ''}
+      </fieldset>
+    `;
+  }
+}
+
+customElements.define('bds-radio-group', BdsRadioGroup);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'bds-radio-group': BdsRadioGroup;
+  }
+}

package/src/web-components/interaction/form/bds-segmented-control.ts

@@ -131,8 +131,13 @@ export class BdsSegmentedControl extends LitElement {
       display: none;
     }
 
+    :host([variant='outline']) .item {
+      background-color: var(--segmented_item-bg, transparent);
+    }
+
     :host([variant='outline']) .item.--active {
       color: var(--segmented_color--active, var(--bds-color_interactive));
+      background-color: var(--segmented_item-bg--active, var(--bds-color_bg));
     }
 
     :host([variant='outline']) .indicator {

package/src/web-components/ui/BdsAvatar.mdx

@@ -5,7 +5,7 @@ import * as Stories from './BdsAvatar.stories';
 
 # <bds-avatar>
 
-Framework-agnostic Avatar custom element. Displays a profile image when `src` is set; falls back to initials derived from the `name` attribute.
+Framework-agnostic Avatar custom element. Displays a user photo when `src` is provided, or falls back to initials derived from the `name` attribute.
 
 > **Status: experimental** — API may change before stable release.
 
@@ -15,16 +15,27 @@ Framework-agnostic Avatar custom element. Displays a profile image when `src` is
 import '@boostdev/components/web-components';
 ```
 
+## When to use
+
+- As a user profile image in navigation bars, comment threads, and team lists
+- As an initials fallback when a photo is unavailable
+
 ## Examples
 
 ### All sizes
 <Canvas of={Stories.AllSizes} />
 
-### With initials
+### Default (initials)
 <Canvas of={Stories.Default} />
 
-### All variants
-<Canvas of={Stories.AllVariants} />
+### With image
+<Canvas of={Stories.WithImage} />
+
+### Small
+<Canvas of={Stories.Small} />
+
+### Large
+<Canvas of={Stories.Large} />
 
 ## Props
 
@@ -34,34 +45,32 @@ import '@boostdev/components/web-components';
 
 | Attribute | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `name` | string | — | Full name; used to compute initials and as `aria-label` fallback |
-| `src` | string | — | Image URL; when set, shows the image instead of initials |
-| `alt` | string | — | Alt text for the image (defaults to `name`) |
-| `size` | `"small" \| "medium" \| "large"` | `"medium"` | Avatar diameter (`2em` / `3em` / `4.5em`) |
+| `src` | string | — | Photo URL; when set the image is shown |
+| `alt` | string | `name` or `"User avatar"` | Alt text for the `<img>` element |
+| `name` | string | — | Full name; used to compute up to two initials and as `aria-label` |
+| `size` | `"small" \| "medium" \| "large"` | `"medium"` | Diameter scale |
 
 ## CSS Custom Properties
 
 | Property | Description |
 |----------|-------------|
-| `--avatar_size` | Override the diameter directly |
-| `--avatar_bg` | Fallback background colour (defaults to `--bds-color_blue`) |
-| `--avatar_text` | Initials text colour (defaults to `--bds-color_on-blue`) |
+| `--avatar_bg` | Background colour of the fallback initials circle |
+| `--avatar_text` | Text colour of the initials |
 
 ## Usage in plain HTML
 
 ```html
-<!-- Initials fallback -->
-<bds-avatar name="Jane Doe"></bds-avatar>
+<!-- With photo -->
+<bds-avatar src="/photo.jpg" name="Jane Doe"></bds-avatar>
 
-<!-- With image -->
-<bds-avatar src="/path/to/photo.jpg" name="Jane Doe" alt="Jane Doe's avatar"></bds-avatar>
+<!-- Initials only -->
+<bds-avatar name="Jane Doe" size="large"></bds-avatar>
 
-<!-- Large size -->
-<bds-avatar name="John Smith" size="large"></bds-avatar>
+<!-- Small -->
+<bds-avatar name="JD" size="small"></bds-avatar>
 ```
 
 ## Accessibility
 
-- When showing initials: renders `role="img"` with `aria-label` set to the `name` value
-- When showing an image: renders a standard `<img>` with `alt` text
-- Initials are hidden from assistive technology (`aria-hidden="true"`) — the label is on the container
+- Without `src`: renders `role="img"` with `aria-label` set to `name` (or "User avatar")
+- With `src`: renders `<img>` with `alt` set to `alt`, `name`, or "User avatar"

package/src/web-components/ui/BdsAvatar.stories.tsx

@@ -1,19 +1,19 @@
 import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
-import '../index';
+import '../index'; // auto-registers all custom elements
 
 function BdsAvatar({
-  name,
   src,
   alt,
-  size,
+  name,
+  size = 'medium',
 }: {
-  name?: string;
   src?: string;
   alt?: string;
+  name?: string;
   size?: 'small' | 'medium' | 'large';
 }) {
-  return React.createElement('bds-avatar', { name, src, alt, size });
+  return React.createElement('bds-avatar', { src, alt, name, size });
 }
 
 const meta = {
@@ -29,34 +29,20 @@ const meta = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-export const Default: Story = { args: { name: 'Jane Doe' } };
-export const SingleInitial: Story = { args: { name: 'Jane' } };
+export const Default: Story = { args: { name: 'Jane Doe', size: 'medium' } };
+export const WithImage: Story = {
+  args: { src: 'https://i.pravatar.cc/150?img=47', name: 'Jane Doe', size: 'medium' },
+};
 export const Small: Story = { args: { name: 'Jane Doe', size: 'small' } };
-export const Medium: Story = { args: { name: 'Jane Doe', size: 'medium' } };
 export const Large: Story = { args: { name: 'Jane Doe', size: 'large' } };
+export const InitialsOnly: Story = { args: { name: 'John Smith', size: 'medium' } };
 
 export const AllSizes: Story = {
   render: () => (
-    <div style={{ display: 'flex', alignItems: 'center', gap: '24px' }}>
-      {(['small', 'medium', 'large'] as const).map(s => (
-        <div key={s} style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: '8px' }}>
-          <BdsAvatar name="Jane Doe" size={s} />
-          <span style={{ fontSize: '0.75rem', color: '#888' }}>{s}</span>
-        </div>
-      ))}
-    </div>
-  ),
-};
-
-export const AllVariants: Story = {
-  render: () => (
-    <div style={{ display: 'flex', alignItems: 'center', gap: '16px', flexWrap: 'wrap' }}>
-      <BdsAvatar name="Jane Doe" />
-      <BdsAvatar name="John Smith" />
-      <BdsAvatar name="Alice" />
-      <BdsAvatar name="Bob" />
-      <BdsAvatar name="Jane Doe" size="small" />
-      <BdsAvatar name="Jane Doe" size="large" />
+    <div style={{ display: 'flex', gap: 16, alignItems: 'center' }}>
+      {React.createElement('bds-avatar', { name: 'Alice Brown', size: 'small' })}
+      {React.createElement('bds-avatar', { name: 'Alice Brown', size: 'medium' })}
+      {React.createElement('bds-avatar', { name: 'Alice Brown', size: 'large' })}
     </div>
   ),
 };