@boostdev/design-system-components 1.1.2 → 1.2.0

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,39 @@ 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.--active {
+      color: var(--segmented_color--active, var(--bds-color_interactive));
+    }
+
+    :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 +153,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 +172,7 @@ export class BdsSegmentedControl extends LitElement {
     this.value = '';
     this.options = '[]';
     this.disabled = false;
+    this.variant = 'outline';
   }
 
   private get _options(): SegmentedOption[] {
@@ -140,22 +187,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 +234,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,67 @@
+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 profile image when `src` is set; falls back to initials derived from the `name` attribute.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## Examples
+
+### All sizes
+<Canvas of={Stories.AllSizes} />
+
+### With initials
+<Canvas of={Stories.Default} />
+
+### All variants
+<Canvas of={Stories.AllVariants} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| 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`) |
+
+## 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`) |
+
+## Usage in plain HTML
+
+```html
+<!-- Initials fallback -->
+<bds-avatar name="Jane Doe"></bds-avatar>
+
+<!-- With image -->
+<bds-avatar src="/path/to/photo.jpg" name="Jane Doe" alt="Jane Doe's avatar"></bds-avatar>
+
+<!-- Large size -->
+<bds-avatar name="John Smith" size="large"></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

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

@@ -0,0 +1,62 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../index';
+
+function BdsAvatar({
+  name,
+  src,
+  alt,
+  size,
+}: {
+  name?: string;
+  src?: string;
+  alt?: string;
+  size?: 'small' | 'medium' | 'large';
+}) {
+  return React.createElement('bds-avatar', { name, src, alt, 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' } };
+export const SingleInitial: Story = { args: { name: 'Jane' } };
+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 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>
+  ),
+};

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

@@ -0,0 +1,63 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsBreadcrumb.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-breadcrumb&gt;
+
+Framework-agnostic Breadcrumb navigation custom element. Renders an ordered list of links showing the user's location in the site hierarchy.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## Examples
+
+### Default (3 levels)
+<Canvas of={Stories.Default} />
+
+### Deep nested
+<Canvas of={Stories.DeepNested} />
+
+### All variants
+<Canvas of={Stories.AllVariants} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `items` | JSON string | `"[]"` | Array of `{ label: string, href?: string }` objects. The last item is the current page (no link). |
+
+## Usage in plain HTML
+
+```html
+<bds-breadcrumb items='[
+  {"label":"Home","href":"/"},
+  {"label":"Products","href":"/products"},
+  {"label":"Detail"}
+]'></bds-breadcrumb>
+```
+
+In JavaScript:
+```js
+const crumb = document.querySelector('bds-breadcrumb');
+crumb.items = [
+  { label: 'Home', href: '/' },
+  { label: 'Products', href: '/products' },
+  { label: 'Detail' },
+];
+```
+
+## Accessibility
+
+- Renders as `<nav aria-label="Breadcrumb">` with an `<ol>` list
+- The last item gets `aria-current="page"` — it is not a link
+- Separators (`›`) are hidden from screen readers with `aria-hidden="true"`

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

@@ -0,0 +1,59 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import type { BreadcrumbItem } from './bds-breadcrumb';
+import '../index';
+
+function BdsBreadcrumb({ items = [] }: { items?: BreadcrumbItem[] }) {
+  return React.createElement('bds-breadcrumb', { items: JSON.stringify(items) });
+}
+
+const meta = {
+  title: 'Web Components/UI/Breadcrumb',
+  component: BdsBreadcrumb,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'padded' },
+} satisfies Meta<typeof BdsBreadcrumb>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    items: [
+      { label: 'Home', href: '/' },
+      { label: 'Products', href: '/products' },
+      { label: 'Current page' },
+    ],
+  },
+};
+
+export const TwoLevels: Story = {
+  args: {
+    items: [
+      { label: 'Home', href: '/' },
+      { label: 'Current page' },
+    ],
+  },
+};
+
+export const DeepNested: Story = {
+  args: {
+    items: [
+      { label: 'Home', href: '/' },
+      { label: 'Category', href: '/category' },
+      { label: 'Subcategory', href: '/category/sub' },
+      { label: 'Section', href: '/category/sub/section' },
+      { label: 'Current page' },
+    ],
+  },
+};
+
+export const AllVariants: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
+      <BdsBreadcrumb items={[{ label: 'Home', href: '/' }, { label: 'Current' }]} />
+      <BdsBreadcrumb items={[{ label: 'Home', href: '/' }, { label: 'Products', href: '/products' }, { label: 'Detail' }]} />
+      <BdsBreadcrumb items={[{ label: 'Home', href: '/' }, { label: 'A', href: '/a' }, { label: 'B', href: '/a/b' }, { label: 'C', href: '/a/b/c' }, { label: 'Current' }]} />
+    </div>
+  ),
+};

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

@@ -0,0 +1,83 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsCard.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-card&gt;
+
+Framework-agnostic Card layout element. Groups related content in a contained surface with optional elevation or outline. Can be made clickable.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## Examples
+
+### All variants
+<Canvas of={Stories.AllVariants} />
+
+### Clickable
+<Canvas of={Stories.Interactive} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `variant` | `"default" \| "elevated" \| "outlined"` | `"default"` | Visual style |
+| `padding` | `"none" \| "small" \| "medium" \| "large"` | `"medium"` | Internal spacing |
+| `text-align` | `"start" \| "center" \| "end"` | `"start"` | Content alignment |
+| `clickable` | boolean | `false` | Renders as `<button>`, adds hover/active effects |
+| `aria-label` | string | — | Accessible label (required when `clickable` and the card content is not descriptive enough) |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `(default)` | Card content |
+
+## Events
+
+| Event | Detail | Bubbles | Composed | Description |
+|-------|--------|---------|----------|-------------|
+| `bds-click` | — | Yes | Yes | Fired when a clickable card is activated |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--card_color` | Card background colour |
+| `--card_on-color` | Card text colour |
+
+## Usage in plain HTML
+
+```html
+<bds-card variant="elevated" padding="large">
+  <h3>Card title</h3>
+  <p>Card body text.</p>
+</bds-card>
+
+<bds-card clickable aria-label="View product details">
+  <strong>Clickable card</strong>
+</bds-card>
+```
+
+Listen for click:
+```js
+document.querySelector('bds-card[clickable]').addEventListener('bds-click', () => {
+  console.log('card clicked');
+});
+```
+
+## Accessibility
+
+- Non-clickable cards are `<div>` elements — they have no interactive role
+- Clickable cards render as `<button>` with keyboard and pointer support
+- Always provide `aria-label` on clickable cards when the text content alone is not descriptive