@boostdev/design-system-components 2.0.0 → 2.2.0

package/src/web-components/interaction/BdsButton.stories.tsx

@@ -1,56 +1,188 @@
-import React from 'react';
+import React, { type ReactNode } from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
 import type { ButtonVariant, ButtonSize } from './bds-button';
 import '../index'; // auto-registers all custom elements
 
-// Thin React wrapper so Storybook controls work with the custom element's props
+const CheckIcon = (
+  <svg
+    slot="icon-start"
+    xmlns="http://www.w3.org/2000/svg"
+    viewBox="0 0 24 24"
+    width="1em"
+    height="1em"
+    aria-hidden
+    fill="currentColor"
+  >
+    <path d="M12 0a12 12 0 1 0 12 12A12 12 0 0 0 12 0Zm6.93 8.2-6.85 9.29a1 1 0 0 1-1.43.19l-4.89-3.91a1 1 0 0 1-.15-1.41A1 1 0 0 1 7 12.21l4.08 3.26L17.32 7a1 1 0 0 1 1.39-.21 1 1 0 0 1 .22 1.41Z" />
+  </svg>
+);
+
+const ArrowRightStart = <span slot="icon-start" aria-hidden>→</span>;
+const ArrowRightEnd = <span slot="icon-end" aria-hidden>→</span>;
+const ArrowLeftStart = <span slot="icon-start" aria-hidden>←</span>;
+
+// Icon for icon-only buttons — goes into the default slot (no slot attribute)
+const CheckIconDefault = (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    viewBox="0 0 24 24"
+    width="1em"
+    height="1em"
+    aria-hidden
+    fill="currentColor"
+  >
+    <path d="M12 0a12 12 0 1 0 12 12A12 12 0 0 0 12 0Zm6.93 8.2-6.85 9.29a1 1 0 0 1-1.43.19l-4.89-3.91a1 1 0 0 1-.15-1.41A1 1 0 0 1 7 12.21l4.08 3.26L17.32 7a1 1 0 0 1 1.39-.21 1 1 0 0 1 .22 1.41Z" />
+  </svg>
+);
+
+const iconStartMap = {
+  none: undefined,
+  check: CheckIcon,
+  arrowRight: ArrowRightStart,
+  arrowLeft: ArrowLeftStart,
+};
+
+const iconEndMap = {
+  none: undefined,
+  arrowRight: ArrowRightEnd,
+};
+
+type IconStartKey = keyof typeof iconStartMap;
+type IconEndKey = keyof typeof iconEndMap;
+
+// React wrapper translating typed props into the custom element's attributes/slots
+interface BdsButtonProps {
+  variant?: ButtonVariant;
+  size?: ButtonSize;
+  disabled?: boolean;
+  href?: string;
+  hasPulse?: boolean;
+  isIconOnly?: boolean;
+  'aria-label'?: string;
+  iconStart?: ReactNode;
+  iconEnd?: ReactNode;
+  children?: ReactNode;
+}
+
 function BdsButton({
   variant = 'default',
   size = 'medium',
   disabled,
   href,
   hasPulse,
+  isIconOnly,
+  'aria-label': ariaLabel,
+  iconStart,
+  iconEnd,
   children,
-}: {
-  variant?: ButtonVariant;
-  size?: ButtonSize;
-  disabled?: boolean;
-  href?: string;
-  hasPulse?: boolean;
-  children?: React.ReactNode;
-}) {
+}: BdsButtonProps) {
   return React.createElement(
     'bds-button',
-    { variant, size, disabled: disabled || undefined, href, 'has-pulse': hasPulse || undefined },
+    {
+      variant,
+      size,
+      disabled: disabled || undefined,
+      href,
+      'has-pulse': hasPulse || undefined,
+      'is-icon-only': isIconOnly || undefined,
+      'aria-label': ariaLabel,
+    },
+    iconStart,
     children,
+    iconEnd,
   );
 }
 
-const meta = {
+type BdsButtonStoryArgs = Omit<BdsButtonProps, 'iconStart' | 'iconEnd'> & {
+  iconStart?: IconStartKey;
+  iconEnd?: IconEndKey;
+};
+
+const meta: Meta<BdsButtonStoryArgs> = {
   title: 'Web Components/Interaction/Button',
   component: BdsButton,
   tags: ['!stable', 'experimental'],
   parameters: { layout: 'centered' },
   argTypes: {
-    variant: { control: 'select', options: ['default', 'ghost'] },
-    size: { control: 'select', options: ['small', 'medium', 'large'] },
+    variant: {
+      control: 'select',
+      options: ['default', 'outline'],
+      description: '`default` is filled; `outline` is transparent with a border.',
+      table: { defaultValue: { summary: 'default' } },
+    },
+    size: {
+      control: 'select',
+      options: ['small', 'medium', 'large'],
+      description: 'Height + horizontal padding.',
+      table: { defaultValue: { summary: 'medium' } },
+    },
+    iconStart: {
+      control: 'select',
+      options: Object.keys(iconStartMap) as IconStartKey[],
+      mapping: iconStartMap,
+      description: 'Icon rendered in the `icon-start` slot.',
+    },
+    iconEnd: {
+      control: 'select',
+      options: Object.keys(iconEndMap) as IconEndKey[],
+      mapping: iconEndMap,
+      description: 'Icon rendered in the `icon-end` slot.',
+    },
+    isIconOnly: {
+      control: 'boolean',
+      description: 'Forces 1:1 aspect ratio with minimal xs padding. Composable with any `variant`. Requires `aria-label`.',
+      table: { defaultValue: { summary: 'false' } },
+    },
+    hasPulse: {
+      control: 'boolean',
+      description: 'Adds a pulsing animation for CTA emphasis.',
+      table: { defaultValue: { summary: 'false' } },
+    },
+    disabled: { control: 'boolean' },
+    href: { control: 'text', description: 'When set, renders as `<a>` with button styling.' },
+    'aria-label': { control: 'text', description: 'Required for icon-only buttons.' },
   },
-} satisfies Meta<typeof BdsButton>;
+  args: { variant: 'default', size: 'medium' },
+};
 
 export default meta;
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<BdsButtonStoryArgs>;
 
-export const Default: Story = { args: { children: 'Default', variant: 'default' } };
-export const Ghost: Story = { args: { children: 'Ghost', variant: 'ghost' } };
+export const Playground: Story = {
+  args: { children: 'Button', iconStart: 'none', iconEnd: 'none' },
+};
+
+export const Default: Story = { args: { children: 'Default' } };
+export const Outline: Story = { args: { children: 'Outline', variant: 'outline' } };
 export const Small: Story = { args: { children: 'Small', size: 'small' } };
 export const Medium: Story = { args: { children: 'Medium', size: 'medium' } };
 export const Large: Story = { args: { children: 'Large', size: 'large' } };
 export const WithPulse: Story = { args: { children: 'Pulsing', hasPulse: true } };
 export const Disabled: Story = { args: { children: 'Disabled', disabled: true } };
+export const WithIconStart: Story = { args: { children: 'Confirm', iconStart: 'check' } };
+export const WithIconEnd: Story = { args: { children: 'Continue', iconEnd: 'arrowRight' } };
+
+export const IconOnly: Story = {
+  args: {
+    isIconOnly: true,
+    'aria-label': 'Confirm',
+    children: CheckIconDefault,
+  },
+};
+
+export const IconOnlyOutline: Story = {
+  args: {
+    variant: 'outline',
+    isIconOnly: true,
+    'aria-label': 'Confirm',
+    children: CheckIconDefault,
+  },
+};
+
 export const AllVariants: Story = {
   render: () => (
     <div style={{ display: 'flex', gap: '12px', flexWrap: 'wrap', alignItems: 'center' }}>
-      {(['default', 'ghost'] as const).flatMap(v =>
+      {(['default', 'outline'] as const).flatMap(v =>
         (['small', 'medium', 'large'] as const).map(s => (
           <BdsButton key={`${v}-${s}`} variant={v} size={s}>{v} {s}</BdsButton>
         )),
@@ -58,3 +190,23 @@ export const AllVariants: Story = {
     </div>
   ),
 };
+
+export const AllIconOnly: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: '12px', flexWrap: 'wrap', alignItems: 'center' }}>
+      {(['default', 'outline'] as const).flatMap(v =>
+        (['small', 'medium', 'large'] as const).map(s => (
+          <BdsButton
+            key={`${v}-${s}`}
+            variant={v}
+            size={s}
+            isIconOnly
+            aria-label={`${v} ${s}`}
+          >
+            {CheckIconDefault}
+          </BdsButton>
+        )),
+      )}
+    </div>
+  ),
+};

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

@@ -92,4 +92,39 @@ describe('bds-button', () => {
     expect(a!.getAttribute('rel')).toBe('noopener');
     cleanup(el);
   });
+
+  it('applies is-icon-only class when is-icon-only is set', async () => {
+    const el = await fixture('<bds-button is-icon-only aria-label="Confirm"><svg></svg></bds-button>');
+    const btn = el.shadowRoot!.querySelector('button');
+    expect(btn!.className).toContain('is-icon-only');
+    cleanup(el);
+  });
+
+  it('does not apply is-icon-only class by default', async () => {
+    const el = await fixture('<bds-button>Click</bds-button>');
+    const btn = el.shadowRoot!.querySelector('button');
+    expect(btn!.className).not.toContain('is-icon-only');
+    cleanup(el);
+  });
+
+  it('reflects the is-icon-only attribute on the host', async () => {
+    const el = await fixture('<bds-button is-icon-only aria-label="Confirm"></bds-button>');
+    expect(el.hasAttribute('is-icon-only')).toBe(true);
+    cleanup(el);
+  });
+
+  it('composes is-icon-only with outline variant', async () => {
+    const el = await fixture('<bds-button variant="outline" is-icon-only aria-label="Confirm"></bds-button>');
+    const btn = el.shadowRoot!.querySelector('button');
+    expect(btn!.className).toContain('outline');
+    expect(btn!.className).toContain('is-icon-only');
+    cleanup(el);
+  });
+
+  it('forwards aria-label to the inner button', async () => {
+    const el = await fixture('<bds-button is-icon-only aria-label="Close"></bds-button>');
+    const btn = el.shadowRoot!.querySelector('button');
+    expect(btn!.getAttribute('aria-label')).toBe('Close');
+    cleanup(el);
+  });
 });

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

@@ -14,6 +14,7 @@ export type ButtonSize = 'small' | 'medium' | 'large';
  *   target    — forwarded to <a> when href is set
  *   rel       — forwarded to <a> when href is set
  *   has-pulse — boolean, enables the pulse ring animation
+ *   is-icon-only — boolean, forces a 1:1 aspect ratio with minimal xs padding (requires aria-label)
  *   type      — "button" (default) | "submit" | "reset"
  *
  * Slots:
@@ -114,6 +115,23 @@ export class BdsButton extends LitElement {
       animation: pulse 3s infinite;
     }
 
+    /* Icon-only: square (1:1), equal xs padding on both axes — composes with
+       any variant/size. box-sizing: border-box keeps the outer box at
+       --button_height; without it, all: unset reverts to content-box and
+       padding-block would stretch the button past its declared height.
+       Slotted child fills the content area (button height minus the two
+       padding sides) so SVG icons scale with button size. */
+    .button.is-icon-only {
+      aspect-ratio: 1;
+      box-sizing: border-box;
+      padding: var(--bds-space_xs);
+    }
+
+    :host([is-icon-only]) ::slotted(*) {
+      inline-size: 100%;
+      block-size: 100%;
+    }
+
     /* SVG icon colour */
     .button svg {
       --icon__stroke: currentcolor;
@@ -141,6 +159,12 @@ export class BdsButton extends LitElement {
       transition: var(--bds-animation_transition);
     }
 
+    /* Icon-only: zero out icon slot margins so icon centres */
+    .button.is-icon-only .icon-start.has-content,
+    .button.is-icon-only .icon-end.has-content {
+      margin-inline: 0;
+    }
+
     /* Hover icon animation */
     @media (hover: hover) and (pointer: fine) {
       .button:hover .icon-start svg,
@@ -189,6 +213,7 @@ export class BdsButton extends LitElement {
     target:           { type: String },
     rel:              { type: String },
     hasPulse:         { type: Boolean, attribute: 'has-pulse', reflect: true },
+    isIconOnly:       { type: Boolean, attribute: 'is-icon-only', reflect: true },
     type:             { type: String },
     ariaLabel:        { type: String, attribute: 'aria-label' },
     // Internal state
@@ -205,6 +230,7 @@ export class BdsButton extends LitElement {
   declare target: string | undefined;
   declare rel: string | undefined;
   declare hasPulse: boolean;
+  declare isIconOnly: boolean;
   declare type: 'button' | 'submit' | 'reset';
   declare ariaLabel: string | null;
   declare private _iconStartFilled: boolean;
@@ -216,6 +242,7 @@ export class BdsButton extends LitElement {
     this.size = 'medium';
     this.disabled = false;
     this.hasPulse = false;
+    this.isIconOnly = false;
     this.type = 'button';
     this.ariaLabel = null;
     this._iconStartFilled = false;
@@ -233,7 +260,7 @@ export class BdsButton extends LitElement {
   }
 
   private get _classes() {
-    return `button ${this.variant} ${this.size}${this.hasPulse ? ' has-pulse' : ''}`;
+    return `button ${this.variant} ${this.size}${this.hasPulse ? ' has-pulse' : ''}${this.isIconOnly ? ' is-icon-only' : ''}`;
   }
 
   private _handleAnchorClick(e: MouseEvent) {

package/src/web-components/layout/BdsGrid.mdx

@@ -0,0 +1,210 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsGrid.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-grid&gt;
+
+Framework-agnostic Grid layout custom element. Built on the `@boostdev/design-system-foundation` grid tokens.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/design-system-components/web-components';
+```
+
+## Variants
+
+| Variant  | Use case                                                                                 |
+| -------- | ---------------------------------------------------------------------------------------- |
+| `main`   | Default. Responsive content-block grid matching the Figma main grid.                     |
+| `page`   | Single-column full-width grid. Use at page root.                                          |
+| `funnel` | Narrow variant of `main`; capped at `--bds-container_max-width--narrow` (48rem).          |
+| `custom` | Explicit column count via the `columns` attribute. Not responsive — use sparingly.        |
+
+## Responsive behavior
+
+`main` and `funnel` inherit the foundation's column ladder automatically. Named `column-span` values adapt across breakpoints so no media queries are required in consumer code:
+
+| Viewport          | Total columns | `one-quarter` | `one-third` | `half` | `two-thirds` | `three-quarters` | `full` |
+| ----------------- | ------------- | ------------- | ----------- | ------ | ------------ | ---------------- | ------ |
+| mobile (< 48rem)  | 4             | 4             | 4           | 4      | 4            | 4                | 4      |
+| tablet (≥ 48rem)  | 8             | 4             | 4           | 4      | 4            | 8                | 8      |
+| desktop (≥ 60rem) | 12            | 3             | 4           | 6      | 8            | 9                | 12     |
+
+Numeric `column-span="n"` is literal — it does not adapt. Use named values for responsive behavior.
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute         | Type                                           | Default  | Description                                        |
+| ----------------- | ---------------------------------------------- | -------- | -------------------------------------------------- |
+| `variant`         | `"main" \| "page" \| "funnel" \| "custom"`     | `"main"` | Grid type                                          |
+| `columns`         | number                                         | —        | Column count (only for `variant="custom"`)         |
+| `is-centered`     | boolean                                        | `false`  | Caps max-width via `--bds-container_max-width`     |
+| `is-masonry`      | boolean                                        | `false`  | Enables masonry layout (CSS Grid Level 3 "grid-lanes"). Uses native CSS when supported, otherwise runs a JS polyfill. |
+| `auto-span-media` | boolean                                        | `false`  | Child `<bds-grid-item>`s without an explicit `column-span` resolve their span from the intrinsic aspect ratio of their first `<img>`/`<video>` descendant. See [Aspect-ratio auto-span](#aspect-ratio-auto-span). |
+
+## Slots
+
+| Slot        | Description                                  |
+| ----------- | -------------------------------------------- |
+| `(default)` | Grid content; typically `<bds-grid-item>` children |
+
+## CSS custom properties
+
+| Property          | Default                   | Description                                |
+| ----------------- | ------------------------- | ------------------------------------------ |
+| `--grid_gap`      | `var(--bds-grid_gap)`     | Gap between grid items                     |
+| `--grid_columns`  | `4`                       | Column count for `variant="custom"`        |
+
+## Usage in plain HTML
+
+```html
+<bds-grid variant="main">
+  <bds-grid-item column-span="half">A</bds-grid-item>
+  <bds-grid-item column-span="half">B</bds-grid-item>
+</bds-grid>
+```
+
+## Nesting
+
+Grids can nest. A `variant="page"` inside another grid uses `grid-column: 1 / -1` so nested page grids always occupy the full width of their container.
+
+```html
+<bds-grid variant="main">
+  <bds-grid-item column-span="full">
+    <bds-grid variant="page">…</bds-grid>
+  </bds-grid-item>
+</bds-grid>
+```
+
+## Accessibility
+
+`<bds-grid>` is purely presentational — no implicit ARIA role. Wrap in a landmark (`<main>`, `<section>`) if one applies. The grid does not manage focus order; source order drives reading order and should match the visual flow.
+
+## Masonry layout
+
+Set `is-masonry` on any `<bds-grid>` to enable masonry (a.k.a. Pinterest-style) layout. Items flow into whichever track currently has the most room, removing the ragged gaps a standard grid leaves when items have uneven heights.
+
+```html
+<bds-grid is-masonry>
+  <bds-grid-item column-span="one-quarter">…</bds-grid-item>
+  <bds-grid-item column-span="one-quarter">…</bds-grid-item>
+</bds-grid>
+```
+
+### When to use
+
+- Image/card galleries with heterogenous heights.
+- Feeds/moodboards where uniform-height tiles would look wrong.
+
+### When NOT to use
+
+- Layouts where the visual order must match reading/tab order. `grid-auto-flow: dense` can backfill an item into an earlier visual slot than its DOM position suggests. Keep DOM order meaningful.
+- Fixed-height cards — a standard grid is simpler and has no JS dependency.
+- Row-aligned layouts (comparison tables).
+
+### How it works
+
+Targets [CSS Grid Layout Module Level 3](https://www.w3.org/TR/css-grid-3/) ("grid lanes"):
+
+- **Native path** — when the browser supports `display: grid-lanes` or `grid-template-rows: masonry`, CSS handles everything and the polyfill short-circuits.
+- **Polyfill path** — row-span packing: the container collapses to a 1 px row track with `grid-auto-flow: dense`, and each item is given `grid-row-end: span ceil(height + gap)`. Items stay in **normal flow** (no absolute positioning), so surrounding content lays out correctly around the grid.
+
+Re-runs on child size changes (`ResizeObserver` on each child) and child addition/removal (`MutationObserver` on the host). The container itself is not observed to avoid a feedback loop — setting row-spans changes the container's block-size.
+
+### Span behavior in masonry
+
+- `column-span` works normally — wider items span more columns. Use this to make a hero or panorama stand out.
+- `row-span` is **ignored**. The stacking axis has no rows to span.
+- `start-column` / `end-column` still apply for definite placement.
+
+### Performance
+
+- Initial layout is one measure pass + one write pass (heights are batched to avoid per-item reflows).
+- Re-layout is scheduled via `requestAnimationFrame` so bursts of observer callbacks coalesce into a single run per frame.
+- Row-gap is baked into each item's span, so ceil-rounding only introduces sub-pixel overshoot per item — not visible in practice.
+
+### Accessibility
+
+Masonry does not change semantics — DOM order is preserved. Because visual order can differ from DOM order, **do not rely on visual order for screen-reader reading order**. Structure content so it makes sense top-to-bottom in the DOM.
+
+## Aspect-ratio auto-span
+
+For galleries mixing portrait, landscape, and panoramic media, set `auto-span-media` on `<bds-grid>` and each `<bds-grid-item>` without a `column-span` attribute will derive its span from the intrinsic aspect ratio of its first `<img>` or `<video>` descendant.
+
+```html
+<bds-grid is-masonry auto-span-media>
+  <bds-grid-item><img src="/portrait.jpg" alt=""></bds-grid-item>
+  <bds-grid-item><img src="/landscape.jpg" alt=""></bds-grid-item>
+  <bds-grid-item><img src="/panorama.jpg" alt=""></bds-grid-item>
+</bds-grid>
+```
+
+Individual items can opt out with an explicit `column-span` (e.g. `column-span="full"` for a hero that shouldn't be auto-sized) or opt in explicitly with `column-span="auto"` when the parent grid doesn't set `auto-span-media`.
+
+### Thresholds
+
+| Aspect ratio (w ÷ h) | Resolved span       | Typical source                    |
+| -------------------- | ------------------- | --------------------------------- |
+| ≤ 1.5                | `'one-quarter'`     | Portrait, square, 3:2 portrait    |
+| > 1.5 and ≤ 2.2      | `'half'`            | 16:9, 3:2 landscape, 2:1          |
+| > 2.2 and ≤ 3.5      | `'three-quarters'`  | 21:9, 2.35:1, 2.5:1 (cinematic)   |
+| > 3.5                | `'full'`            | 32:9, hard panoramic              |
+| invalid / unresolved | `'one-quarter'`     | No media / metadata not yet ready |
+
+Named-span responsive behavior still applies — on mobile every item collapses to full-width regardless of its resolved span.
+
+### Loading behavior
+
+Dimensions are read from `img.naturalWidth/naturalHeight` and `video.videoWidth/videoHeight` — no layout is triggered. If metadata is not yet available when the element upgrades, the item starts at `'one-quarter'` and re-resolves when the `load` (image) or `loadedmetadata` (video) event fires. Subsequent slot mutations re-run the resolver.
+
+### When NOT to use auto-span
+
+- Items whose span reflects **content importance** rather than media shape — set `column-span` explicitly.
+- Non-media grids — every item falls back to `'one-quarter'` because there's no aspect to read.
+- Galleries where all images share the same aspect — the thresholds won't differentiate them; a uniform explicit span is simpler.
+
+## Framework equivalents
+
+| React                   | Web component              |
+| ----------------------- | -------------------------- |
+| `<Grid>` / `<GridItem>` | `<bds-grid>` / `<bds-grid-item>` |
+
+## Examples
+
+### Main grid
+<Canvas of={Stories.Main} />
+
+### Page grid
+<Canvas of={Stories.Page} />
+
+### Funnel
+<Canvas of={Stories.Funnel} />
+
+### Custom
+<Canvas of={Stories.Custom} />
+
+### Centered
+<Canvas of={Stories.Centered} />
+
+### Spans
+<Canvas of={Stories.Spans} />
+
+### Start / end (escape hatch)
+<Canvas of={Stories.StartEnd} />
+
+### Complex layout
+<Canvas of={Stories.ComplexLayout} />
+
+### Masonry
+<Canvas of={Stories.Masonry} />
+
+### Masonry with spans
+<Canvas of={Stories.MasonryWithSpans} />