@boostdev/design-system-components 1.1.2 → 1.2.1

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-radio.ts

@@ -50,10 +50,8 @@ export class BdsRadio extends LitElement {
       --bdc_color: currentcolor;
       --bdc-outline_radius: 50%;
 
-      outline: var(--bdc-outline_width) solid var(--bdc_color);
-      outline-offset: var(--bdc-outline_offset);
       border-radius: 50%;
-      box-shadow: var(--radio_shadow, var(--bdc-outline_shadow));
+      box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color), var(--radio_shadow, var(--bdc-outline_shadow));
       border: none;
       appearance: none;
       background-color: var(--radio_color_bg, var(--bds-color_bg));
@@ -63,18 +61,14 @@ export class BdsRadio extends LitElement {
     }
 
     .input:checked {
-      background-color: var(--radio_color-active, var(--bdc-color_active));
+      background: radial-gradient(
+        circle,
+        var(--radio_color-active, var(--bdc-color_active)) 35%,
+        var(--radio_color_bg, var(--bds-color_bg)) 42%
+      );
       --bdc_color: var(--radio_color-active, var(--bdc-color_active));
     }
 
-    .input:checked::after {
-      content: '';
-      position: absolute;
-      inset: 25%;
-      border-radius: 50%;
-      background-color: var(--radio_color-on-active, var(--bdc-color_on-active));
-    }
-
     .input:focus-visible {
       outline: var(--bds-outline_default);
       outline-offset: var(--bds-outline_offset);

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

@@ -1,26 +1,29 @@
-import { LitElement, css, html } from 'lit';
+import { LitElement, css, html, nothing } from 'lit';
 
 export interface SegmentedOption {
   value: string;
   label: string;
   disabled?: boolean;
+  /** When set, renders the option as an <a> link instead of a radio button */
+  href?: string;
 }
 
 /**
  * `<bds-segmented-control>` — form-associated Segmented Control custom element.
  *
- * Renders a group of radio buttons styled as a unified segmented control.
+ * Renders a group of radio buttons (or links) styled as a unified segmented control.
  * Passes a JSON `options` attribute because reactive slot content can't be
  * easily converted to radio groups.
  *
  * Attributes:
  *   name     — form field name (also used for the internal radio group)
  *   value    — currently selected value
- *   options  — JSON array of `{ value, label, disabled? }` option objects
+ *   options  — JSON array of `{ value, label, disabled?, href? }` option objects
  *   disabled — boolean; disables all options
+ *   variant  — "outline" (inset border on active item, default) | "filled" (sliding thumb)
  *
  * Events:
- *   change — fired when a new segment is selected
+ *   change — fired when a new segment is selected (radio mode only)
  *
  * @example
  * <bds-segmented-control
@@ -28,6 +31,13 @@ export interface SegmentedOption {
  *   value="list"
  *   options='[{"value":"list","label":"List"},{"value":"grid","label":"Grid"}]'
  * ></bds-segmented-control>
+ *
+ * @example Outline variant with links
+ * <bds-segmented-control
+ *   variant="outline"
+ *   value="home"
+ *   options='[{"value":"home","label":"Home","href":"/"},{"value":"about","label":"About","href":"/about"}]'
+ * ></bds-segmented-control>
  */
 export class BdsSegmentedControl extends LitElement {
   static formAssociated = true;
@@ -56,7 +66,7 @@ export class BdsSegmentedControl extends LitElement {
       position: absolute;
       inset-block: 0.25rem;
       border-radius: calc(var(--bds-border_radius--s) - 2px);
-      background-color: var(--segmented_thumb-color, var(--bds-color_bg));
+      background-color: var(--segmented_thumb-color, var(--bds-color_interactive));
       box-shadow: var(--bds-shadow_m);
       transition: inset-inline-start var(--bds-animation_transition-duration) var(--bds-animation_easing),
                   inline-size var(--bds-animation_transition-duration) var(--bds-animation_easing);
@@ -87,10 +97,11 @@ export class BdsSegmentedControl extends LitElement {
       transition: color var(--bds-animation_transition-duration) var(--bds-animation_easing);
       user-select: none;
       white-space: nowrap;
+      text-decoration: none;
     }
 
     .item.--active {
-      color: var(--segmented_color--active, var(--bds-color_interactive_on-bg));
+      color: var(--segmented_color--active, var(--bds-color_on-interactive));
     }
 
     .item.--disabled {
@@ -102,6 +113,44 @@ export class BdsSegmentedControl extends LitElement {
       outline: var(--bds-outline_default);
       outline-offset: var(--bds-outline_offset);
     }
+
+    /* Outline variant: sliding inset-border indicator (positioned via JS like .thumb) */
+    .indicator {
+      position: absolute;
+      inset-block: 0.25rem;
+      border-radius: calc(var(--bds-border_radius--s) - 2px);
+      pointer-events: none;
+      z-index: 2;
+      display: none;
+      transition: inset-inline-start var(--bds-animation_transition-duration) var(--bds-animation_easing),
+                  inline-size var(--bds-animation_transition-duration) var(--bds-animation_easing);
+    }
+
+    /* Outline variant — no thumb, sliding inset-border indicator, interactive active color */
+    :host([variant='outline']) .thumb {
+      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 {
+      display: block;
+      box-shadow: inset 0 0 0 2px var(--bds-color_interactive);
+    }
+
+    @media (prefers-reduced-motion: reduce) {
+      .thumb,
+      .indicator {
+        transition: none;
+      }
+    }
   `;
 
   static properties = {
@@ -109,12 +158,14 @@ export class BdsSegmentedControl extends LitElement {
     value:    { type: String },
     options:  { type: String },
     disabled: { type: Boolean, reflect: true },
+    variant:  { type: String, reflect: true },
   };
 
   declare name: string;
   declare value: string;
   declare options: string;
   declare disabled: boolean;
+  declare variant: 'outline' | 'filled';
 
   private _internals!: ElementInternals;
   private readonly _uid = Math.random().toString(36).slice(2, 8);
@@ -126,6 +177,7 @@ export class BdsSegmentedControl extends LitElement {
     this.value = '';
     this.options = '[]';
     this.disabled = false;
+    this.variant = 'outline';
   }
 
   private get _options(): SegmentedOption[] {
@@ -140,22 +192,35 @@ export class BdsSegmentedControl extends LitElement {
     super.updated(changed);
     if (changed.has('value') || changed.has('options')) {
       this._internals.setFormValue?.(this.value || null);
-      this._updateThumb();
+      if (this.variant === 'filled') this._updateThumb();
+      if (this.variant === 'outline') this._updateIndicator();
+    }
+    if (changed.has('variant')) {
+      if (this.variant === 'filled') this._updateThumb();
+      if (this.variant === 'outline') this._updateIndicator();
     }
   }
 
-  private _updateThumb() {
-    const opts = this._options;
-    const selectedIndex = Math.max(0, opts.findIndex(o => o.value === this.value));
-    const items = this.shadowRoot?.querySelectorAll<HTMLElement>('.item');
-    const thumb = this.shadowRoot?.querySelector<HTMLElement>('.thumb');
-    if (!items || !thumb || items.length === 0) return;
+  private _positionSlider(el: HTMLElement | null | undefined, items: NodeListOf<HTMLElement>, selectedIndex: number) {
+    if (!el || items.length === 0) return;
     const item = items[selectedIndex];
     if (!item) return;
     const controlRect = (item.parentElement as HTMLElement).getBoundingClientRect();
     const itemRect = item.getBoundingClientRect();
-    thumb.style.insetInlineStart = `${itemRect.left - controlRect.left}px`;
-    thumb.style.inlineSize = `${itemRect.width}px`;
+    el.style.insetInlineStart = `${itemRect.left - controlRect.left}px`;
+    el.style.inlineSize = `${itemRect.width}px`;
+  }
+
+  private _updateThumb() {
+    const selectedIndex = Math.max(0, this._options.findIndex(o => o.value === this.value));
+    const items = this.shadowRoot?.querySelectorAll<HTMLElement>('.item');
+    this._positionSlider(this.shadowRoot?.querySelector<HTMLElement>('.thumb'), items!, selectedIndex);
+  }
+
+  private _updateIndicator() {
+    const selectedIndex = Math.max(0, this._options.findIndex(o => o.value === this.value));
+    const items = this.shadowRoot?.querySelectorAll<HTMLElement>('.item');
+    this._positionSlider(this.shadowRoot?.querySelector<HTMLElement>('.indicator'), items!, selectedIndex);
   }
 
   formResetCallback() {
@@ -174,15 +239,26 @@ export class BdsSegmentedControl extends LitElement {
     return html`
       <div class="control" role="group">
         <span class="thumb" aria-hidden="true"></span>
+        <span class="indicator" aria-hidden="true"></span>
         ${opts.map((opt, i) => {
-          const id = `bds-seg-${this._uid}-${i}`;
           const isActive = opt.value === this.value;
           const isDisabled = this.disabled || opt.disabled;
+          const itemClass = `item ${isActive ? '--active' : ''} ${isDisabled ? '--disabled' : ''}`.trim();
+
+          if (opt.href) {
+            return html`
+              <a
+                class=${itemClass}
+                href=${isDisabled ? nothing : opt.href}
+                aria-current=${isActive ? 'page' : nothing}
+                ?aria-disabled=${isDisabled}
+              >${opt.label}</a>
+            `;
+          }
+
+          const id = `bds-seg-${this._uid}-${i}`;
           return html`
-            <label
-              class="item ${isActive ? '--active' : ''} ${isDisabled ? '--disabled' : ''}"
-              for=${id}
-            >
+            <label class=${itemClass} for=${id}>
               <input
                 id=${id}
                 type="radio"

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

@@ -58,10 +58,8 @@ export class BdsSelect extends LitElement {
       --bdc_color: currentcolor;
       --bdc-outline_radius: var(--bds-border_radius--xs);
 
-      outline: var(--bdc-outline_width) solid var(--bdc_color);
-      outline-offset: var(--bdc-outline_offset);
       border-radius: var(--select_radius, var(--bdc-outline_radius));
-      box-shadow: var(--select_shadow, var(--bdc-outline_shadow));
+      box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color), var(--select_shadow, var(--bdc-outline_shadow));
       background-color: var(--select_color_bg, var(--bds-color_bg));
       color: var(--select_color, var(--bds-color_on-bg));
       appearance: none;
@@ -86,7 +84,7 @@ export class BdsSelect extends LitElement {
       pointer-events: none;
       inline-size: 1rem;
       block-size: 1rem;
-      color: currentcolor;
+      color: var(--select_chevron-color, var(--bds-color_interactive));
     }
 
     .chevron svg {

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

@@ -48,8 +48,7 @@ export class BdsSwitch extends LitElement {
       background-color: var(--switch_color_bg, var(--bds-color_bg--subtle));
       --bdc_color: currentcolor;
 
-      outline: var(--bdc-outline_width) solid var(--bdc_color);
-      outline-offset: var(--bdc-outline_offset);
+      box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color);
       transition: background-color 0.2s ease;
       flex-shrink: 0;
     }
@@ -61,7 +60,7 @@ export class BdsSwitch extends LitElement {
       inline-size: 1.1rem;
       block-size: 1.1rem;
       border-radius: 50%;
-      background-color: var(--switch_thumb_color, var(--bds-color_bg));
+      background-color: var(--switch_thumb_color, var(--bds-color_interactive));
       transition: inset-inline-start 0.2s ease;
     }
 
@@ -74,7 +73,7 @@ export class BdsSwitch extends LitElement {
     }
 
     .input:checked + .track {
-      background-color: var(--switch_color-active, var(--bdc-color_active));
+      background-color: var(--switch_color-active, var(--bdc-color_active--subtle));
     }
 
     .input:checked + .track .thumb {

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

@@ -44,10 +44,8 @@ export class BdsTextarea extends LitElement {
       --bdc_color: currentcolor;
       --bdc-outline_radius: var(--bds-border_radius--xs);
 
-      outline: var(--bdc-outline_width) solid var(--bdc_color);
-      outline-offset: var(--bdc-outline_offset);
       border-radius: var(--textarea_radius, var(--bdc-outline_radius));
-      box-shadow: var(--textarea_shadow, var(--bdc-outline_shadow));
+      box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color), var(--textarea_shadow, var(--bdc-outline_shadow));
       background-color: var(--textarea_color_bg, var(--bds-color_bg));
       color: var(--textarea_color, var(--bds-color_on-bg));
       resize: vertical;

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

@@ -0,0 +1,76 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsAvatar.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-avatar&gt;
+
+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.
+
+## Installation
+
+```js
+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} />
+
+### Default (initials)
+<Canvas of={Stories.Default} />
+
+### With image
+<Canvas of={Stories.WithImage} />
+
+### Small
+<Canvas of={Stories.Small} />
+
+### Large
+<Canvas of={Stories.Large} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `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_bg` | Background colour of the fallback initials circle |
+| `--avatar_text` | Text colour of the initials |
+
+## Usage in plain HTML
+
+```html
+<!-- With photo -->
+<bds-avatar src="/photo.jpg" name="Jane Doe"></bds-avatar>
+
+<!-- Initials only -->
+<bds-avatar name="Jane Doe" size="large"></bds-avatar>
+
+<!-- Small -->
+<bds-avatar name="JD" size="small"></bds-avatar>
+```
+
+## Accessibility
+
+- 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

@@ -0,0 +1,48 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../index'; // auto-registers all custom elements
+
+function BdsAvatar({
+  src,
+  alt,
+  name,
+  size = 'medium',
+}: {
+  src?: string;
+  alt?: string;
+  name?: string;
+  size?: 'small' | 'medium' | 'large';
+}) {
+  return React.createElement('bds-avatar', { src, alt, name, size });
+}
+
+const meta = {
+  title: 'Web Components/UI/Avatar',
+  component: BdsAvatar,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+  argTypes: {
+    size: { control: 'select', options: ['small', 'medium', 'large'] },
+  },
+} satisfies Meta<typeof BdsAvatar>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+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 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', 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>
+  ),
+};

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

@@ -0,0 +1,66 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsBreadcrumb.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-breadcrumb&gt;
+
+Framework-agnostic Breadcrumb custom element. Renders a horizontal navigation trail from a JSON array of `{ label, href? }` items. The last item is treated as the current page and rendered without a link.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## When to use
+
+- On pages more than one level deep in a hierarchy to help users understand their location
+- Always include a link back to the root/home as the first item
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### Short (two levels)
+<Canvas of={Stories.Short} />
+
+### Long (five levels)
+<Canvas of={Stories.Long} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `items` | `Array<{ label: string; href?: string }>` | `[]` | Breadcrumb items as a JSON-serialisable array. The last item is always the current page. |
+
+## Usage in plain HTML
+
+```html
+<bds-breadcrumb
+  items='[{"label":"Home","href":"/"},{"label":"Products","href":"/products"},{"label":"Item"}]'>
+</bds-breadcrumb>
+```
+
+Or set the property in JavaScript:
+
+```js
+document.querySelector('bds-breadcrumb').items = [
+  { label: 'Home', href: '/' },
+  { label: 'Products', href: '/products' },
+  { label: 'Item' },
+];
+```
+
+## Accessibility
+
+- Wrapped in `<nav aria-label="Breadcrumb">` with an `<ol>` list structure
+- The current page item carries `aria-current="page"`
+- Separator characters are `aria-hidden="true"` to avoid screen reader noise