npm - @boostdev/design-system-components - Versions diffs - 1.1.2 → 1.2.1 - Mend

@boostdev/design-system-components 1.1.2 → 1.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (213) hide show

package/src/web-components/interaction/BdsSkipLink.mdx ADDED Viewed

@@ -0,0 +1,90 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsSkipLink.stories';
+<Meta of={Stories} />
+# &lt;bds-skip-link&gt;
+Framework-agnostic Skip Navigation Link custom element. Visually hidden until focused, allowing keyboard users to jump directly to the main content area and bypass repeated navigation.
+> **Status: experimental** — API may change before stable release.
+## Installation
+```js
+import '@boostdev/components/web-components';
+```
+Or in HTML without a bundler:
+```html
+<script type="module">
+  import '@boostdev/components/web-components';
+</script>
+```
+## When to use
+- Place as the very first focusable element on every page that has a navigation region before the main content
+- Required on all pages to comply with WCAG 2.4.1 (Bypass Blocks, Level A)
+## When not to use
+- Do not place it anywhere other than the start of the document flow
+- Do not use it as a general-purpose navigation shortcut — it is specifically for skipping repetitive blocks
+## Examples
+### Default
+<Canvas of={Stories.Default} />
+### With custom label
+<Canvas of={Stories.WithCustomLabel} />
+## Props
+<ArgTypes of={Stories} />
+## Attributes
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `href` | string | `"#main"` | The target anchor ID to jump to (e.g. `"#main-content"`) |
+## Slots
+| Slot | Description |
+|------|-------------|
+| `(default)` | Link text; defaults to `"Skip to main content"` when no content is provided |
+## Usage in plain HTML
+Place `<bds-skip-link>` as the very first element inside `<body>`:
+```html
+<body>
+  <bds-skip-link href="#main-content"></bds-skip-link>
+  <header>
+    <nav>...</nav>
+  </header>
+  <main id="main-content">
+    Page content
+  </main>
+</body>
+```
+With custom label text:
+```html
+<bds-skip-link href="#main-content">Skip to main content</bds-skip-link>
+```
+## Accessibility
+- Visually hidden via `transform: translateY(...)` until focused — avoids `display: none` and `visibility: hidden` which remove the element from the accessibility tree
+- Becomes visible on `:focus-visible`, ensuring it is discoverable by keyboard and switch-access users
+- Uses an `<a>` element so it is announced as a link by screen readers
+- `z-index: 9999` ensures it appears above all other content when focused
+- Satisfies WCAG 2.4.1 Bypass Blocks (Level A)

package/src/web-components/interaction/BdsSkipLink.stories.tsx ADDED Viewed

@@ -0,0 +1,68 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../index'; // auto-registers all custom elements
+// Thin React wrapper so Storybook controls work with the custom element's props
+function BdsSkipLink({
+  href = '#main',
+  children,
+}: {
+  href?: string;
+  children?: React.ReactNode;
+}) {
+  return React.createElement(
+    'bds-skip-link',
+    { href },
+    children,
+  );
+}
+const meta = {
+  title: 'Web Components/Interaction/SkipLink',
+  component: BdsSkipLink,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'padded' },
+  argTypes: {
+    href: { control: 'text' },
+  },
+} satisfies Meta<typeof BdsSkipLink>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+export const Default: Story = {
+  args: { href: '#main' },
+  // Hint to the viewer that the link is visually hidden until focused
+  decorators: [
+    (Story) => (
+      <div>
+        <p style={{ marginBottom: '0.5rem', fontSize: '0.875rem', color: 'var(--bds-color_on-bg, #333)' }}>
+          Tab into the preview to see the skip link appear.
+        </p>
+        <Story />
+        <main id="main" style={{ marginTop: '1rem', padding: '1rem', border: '1px dashed currentcolor' }}>
+          Main content area
+        </main>
+      </div>
+    ),
+  ],
+};
+export const WithCustomLabel: Story = {
+  args: { href: '#content' },
+  render: (args) => (
+    <div>
+      <p style={{ marginBottom: '0.5rem', fontSize: '0.875rem', color: 'var(--bds-color_on-bg, #333)' }}>
+        Tab into the preview to see the skip link appear.
+      </p>
+      {React.createElement(
+        'bds-skip-link',
+        { href: args.href },
+        'Skip to main content',
+      )}
+      <main id="content" style={{ marginTop: '1rem', padding: '1rem', border: '1px dashed currentcolor' }}>
+        Main content area
+      </main>
+    </div>
+  ),
+};

package/src/web-components/interaction/BdsTabs.mdx ADDED Viewed

@@ -0,0 +1,117 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsTabs.stories';
+<Meta of={Stories} />
+# &lt;bds-tabs&gt;
+Framework-agnostic Tabs custom element. Coordinates `<bds-tab>` and `<bds-tab-panel>` children by DOM order, with full keyboard navigation.
+> **Status: experimental** — API may change before stable release.
+## Installation
+```js
+import '@boostdev/components/web-components';
+```
+Or in HTML without a bundler:
+```html
+<script type="module">
+  import '@boostdev/components/web-components';
+</script>
+```
+## When to use
+- Organising related content into sections when only one section is shown at a time
+- Switching between views at the same level of hierarchy
+## When not to use
+- For navigation between pages — use `<a>` links or a router
+- When all sections should be visible at once — use an accordion or separate sections
+## Examples
+### Default
+<Canvas of={Stories.Default} />
+### With disabled tab
+<Canvas of={Stories.WithDisabledTab} />
+### Many tabs
+<Canvas of={Stories.ManyTabs} />
+## Props
+<ArgTypes of={Stories} />
+## Attributes — `<bds-tabs>`
+`<bds-tabs>` has no configurable attributes. Tab state and active index are managed internally.
+## Attributes — `<bds-tab>`
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `disabled` | boolean | `false` | Prevents the tab from being selected; tab is skipped during keyboard navigation |
+| `selected` | boolean | `false` | Set by the parent `<bds-tabs>`; do not set manually |
+## Slots
+### `<bds-tabs>`
+| Slot | Description |
+|------|-------------|
+| `tab` | `<bds-tab>` elements — rendered in the tab list |
+| `panel` | `<bds-tab-panel>` elements — rendered below the tab list |
+### `<bds-tab>`
+| Slot | Description |
+|------|-------------|
+| `(default)` | Tab label text |
+### `<bds-tab-panel>`
+| Slot | Description |
+|------|-------------|
+| `(default)` | Panel content displayed when the corresponding tab is selected |
+## Events
+| Event | Fired by | Bubbles | Description |
+|-------|----------|---------|-------------|
+| `bds-tab-select` | `<bds-tab>` | Yes | Fired when a tab is clicked; handled internally by `<bds-tabs>` |
+## Usage in plain HTML
+Tabs and panels are matched by DOM order (first tab → first panel, etc.):
+```html
+<bds-tabs>
+  <bds-tab slot="tab">Overview</bds-tab>
+  <bds-tab slot="tab">Details</bds-tab>
+  <bds-tab slot="tab" disabled>Disabled</bds-tab>
+  <bds-tab-panel slot="panel">
+    <p>Overview content</p>
+  </bds-tab-panel>
+  <bds-tab-panel slot="panel">
+    <p>Details content</p>
+  </bds-tab-panel>
+  <bds-tab-panel slot="panel">
+    <p>Disabled tab content (unreachable)</p>
+  </bds-tab-panel>
+</bds-tabs>
+```
+## Accessibility
+- The tab list container has `role="tablist"`
+- Each `<bds-tab>` renders a `<button role="tab">` with `aria-selected` and the correct `tabindex` (0 for active, -1 for others)
+- Each `<bds-tab-panel>` receives `hidden` when not active
+- Keyboard navigation: ArrowRight / ArrowLeft cycles through enabled tabs; Home / End jumps to first / last enabled tab
+- Disabled tabs are excluded from keyboard navigation

package/src/web-components/interaction/BdsTabs.stories.tsx ADDED Viewed

@@ -0,0 +1,94 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../index'; // auto-registers all custom elements
+// Thin React wrapper so Storybook controls work with the custom element's props
+function BdsTabs({
+  tabs = ['Overview', 'Details', 'Settings'],
+  panels = ['Overview content.', 'Details content.', 'Settings content.'],
+}: {
+  tabs?: string[];
+  panels?: string[];
+}) {
+  return React.createElement(
+    'bds-tabs',
+    null,
+    ...tabs.map(label =>
+      React.createElement('bds-tab', { key: label, slot: 'tab' }, label),
+    ),
+    ...panels.map((content, i) =>
+      React.createElement(
+        'bds-tab-panel',
+        { key: i, slot: 'panel' },
+        React.createElement('p', { style: { margin: 0 } }, content),
+      ),
+    ),
+  );
+}
+const meta = {
+  title: 'Web Components/Interaction/Tabs',
+  component: BdsTabs,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'padded' },
+} satisfies Meta<typeof BdsTabs>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+export const Default: Story = {
+  args: {
+    tabs: ['Overview', 'Details', 'Settings'],
+    panels: [
+      'Overview content. Use tabs to divide related content into sections.',
+      'Details content. Each tab maps to a panel by DOM order.',
+      'Settings content. Navigate with ArrowLeft / ArrowRight keys.',
+    ],
+  },
+};
+export const WithDisabledTab: Story = {
+  render: () =>
+    React.createElement(
+      'bds-tabs',
+      null,
+      React.createElement('bds-tab', { slot: 'tab' }, 'Active'),
+      React.createElement('bds-tab', { slot: 'tab', disabled: '' }, 'Disabled'),
+      React.createElement('bds-tab', { slot: 'tab' }, 'Another'),
+      React.createElement(
+        'bds-tab-panel',
+        { slot: 'panel' },
+        React.createElement('p', { style: { margin: 0 } }, 'Content for the first tab.'),
+      ),
+      React.createElement(
+        'bds-tab-panel',
+        { slot: 'panel' },
+        React.createElement('p', { style: { margin: 0 } }, 'This panel is paired with the disabled tab.'),
+      ),
+      React.createElement(
+        'bds-tab-panel',
+        { slot: 'panel' },
+        React.createElement('p', { style: { margin: 0 } }, 'Content for the third tab.'),
+      ),
+    ),
+};
+export const ManyTabs: Story = {
+  render: () => {
+    const labels = ['Dashboard', 'Reports', 'Users', 'Billing', 'Integrations'];
+    return React.createElement(
+      'bds-tabs',
+      null,
+      ...labels.map(label =>
+        React.createElement('bds-tab', { key: label, slot: 'tab' }, label),
+      ),
+      ...labels.map((label, i) =>
+        React.createElement(
+          'bds-tab-panel',
+          { key: i, slot: 'panel' },
+          React.createElement('p', { style: { margin: 0 } }, `${label} content area.`),
+        ),
+      ),
+    );
+  },
+};

package/src/web-components/interaction/BdsTooltip.mdx ADDED Viewed

@@ -0,0 +1,104 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsTooltip.stories';
+<Meta of={Stories} />
+# &lt;bds-tooltip&gt;
+Framework-agnostic Tooltip custom element. Displays a small informational label on hover and keyboard focus using CSS-only visibility — no JavaScript positioning required.
+> **Status: experimental** — API may change before stable release.
+## Installation
+```js
+import '@boostdev/components/web-components';
+```
+Or in HTML without a bundler:
+```html
+<script type="module">
+  import '@boostdev/components/web-components';
+</script>
+```
+## When to use
+- Labelling icon-only buttons that have no visible text
+- Providing supplementary information for a UI element without cluttering the layout
+- Short, non-interactive hints (a single sentence or less)
+## When not to use
+- For interactive content (links, buttons inside the tooltip) — use `<bds-popover>` instead
+- For error messages or validation feedback — use an inline message
+- For content longer than a short phrase — use `<bds-popover>` or a disclosure pattern
+## Examples
+### Default
+<Canvas of={Stories.Default} />
+### On a button
+<Canvas of={Stories.OnButton} />
+### Bottom placement
+<Canvas of={Stories.Bottom} />
+### Left placement
+<Canvas of={Stories.Left} />
+### Right placement
+<Canvas of={Stories.Right} />
+### All placements
+<Canvas of={Stories.AllPlacements} />
+## Props
+<ArgTypes of={Stories} />
+## Attributes
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `content` | string | `""` | Text to display inside the tooltip |
+| `placement` | `"top" \| "bottom" \| "left" \| "right"` | `"top"` | Where the tooltip appears relative to the trigger |
+## Slots
+| Slot | Description |
+|------|-------------|
+| `(default)` | The trigger element (button, icon, etc.) that the tooltip is anchored to |
+## CSS Custom Properties
+| Property | Description |
+|----------|-------------|
+| `--tooltip_bg` | Tooltip background colour (default: `var(--bds-color_on-bg)`) |
+| `--tooltip_text` | Tooltip text colour (default: `var(--bds-color_bg)`) |
+## Usage in plain HTML
+```html
+<bds-tooltip content="Save your changes" placement="top">
+  <button type="button">Save</button>
+</bds-tooltip>
+<!-- Icon-only button with tooltip label -->
+<bds-tooltip content="Delete item" placement="bottom">
+  <button type="button" aria-label="Delete item">
+    <!-- icon SVG -->
+  </button>
+</bds-tooltip>
+```
+## Accessibility
+- The tooltip panel has `role="tooltip"`
+- Visibility is controlled by `:hover` and `:focus-within` — no JavaScript required
+- The tooltip is rendered adjacent to the trigger inside the same shadow root, so screen readers can read it via proximity
+- Note: `aria-describedby` cannot cross shadow DOM boundaries; if your project requires explicit ARIA association, use `<bds-popover>` instead
+- `pointer-events: none` on the tooltip prevents it from interfering with mouse events
+- Fade transition respects `prefers-reduced-motion`

package/src/web-components/interaction/BdsTooltip.stories.tsx ADDED Viewed

@@ -0,0 +1,87 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import type { TooltipPlacement } from './bds-tooltip';
+import '../index'; // auto-registers all custom elements
+// Thin React wrapper so Storybook controls work with the custom element's props
+function BdsTooltip({
+  content = 'Tooltip text',
+  placement = 'top',
+  children,
+}: {
+  content?: string;
+  placement?: TooltipPlacement;
+  children?: React.ReactNode;
+}) {
+  return React.createElement(
+    'bds-tooltip',
+    { content, placement },
+    children ?? React.createElement('button', { type: 'button' }, 'Hover me'),
+  );
+}
+const meta = {
+  title: 'Web Components/Interaction/Tooltip',
+  component: BdsTooltip,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+  argTypes: {
+    content: { control: 'text' },
+    placement: { control: 'select', options: ['top', 'bottom', 'left', 'right'] },
+  },
+} satisfies Meta<typeof BdsTooltip>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+export const Default: Story = {
+  args: { content: 'Tooltip text', placement: 'top' },
+};
+export const OnButton: Story = {
+  args: { content: 'Save your changes', placement: 'top' },
+  render: (args) =>
+    React.createElement(
+      'bds-tooltip',
+      { content: args.content, placement: args.placement },
+      React.createElement(
+        'button',
+        { type: 'button', style: { padding: '0.5rem 1rem', cursor: 'pointer' } },
+        'Save',
+      ),
+    ),
+};
+export const Bottom: Story = {
+  args: { content: 'Appears below', placement: 'bottom' },
+};
+export const Left: Story = {
+  args: { content: 'Appears to the left', placement: 'left' },
+};
+export const Right: Story = {
+  args: { content: 'Appears to the right', placement: 'right' },
+};
+export const AllPlacements: Story = {
+  render: () => (
+    <div style={{ display: 'grid', gridTemplateColumns: 'repeat(2, auto)', gap: '4rem', padding: '3rem' }}>
+      {(['top', 'bottom', 'left', 'right'] as const).map(placement =>
+        React.createElement(
+          'div',
+          { key: placement, style: { display: 'flex', justifyContent: 'center', alignItems: 'center' } },
+          React.createElement(
+            'bds-tooltip',
+            { content: `Placement: ${placement}`, placement },
+            React.createElement(
+              'button',
+              { type: 'button', style: { padding: '0.5rem 1rem', cursor: 'pointer' } },
+              placement,
+            ),
+          ),
+        ),
+      )}
+    </div>
+  ),
+};

package/src/web-components/interaction/bds-accordion.ts CHANGED Viewed

@@ -28,9 +28,8 @@ export class BdsAccordion extends LitElement {
       display: block;
       --bdc_color: var(--bds-color_bg--subtle);
       --bdc-outline_radius: var(--bds-border_radius--s);
-      outline: var(--bdc-outline_width) solid var(--bdc_color);
-      outline-offset: var(--bdc-outline_offset);
       border-radius: var(--accordion_radius, var(--bdc-outline_radius));
+      box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color);
       overflow: hidden;
     }
   `;

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

@@ -1,13 +1,13 @@
 import { LitElement, css, html, nothing } from 'lit';
-export type ButtonVariant = 'default' | 'ghost';
+export type ButtonVariant = 'default' | 'outline' | 'ghost'; // 'ghost' is deprecated, use 'outline'
 export type ButtonSize = 'small' | 'medium' | 'large';
 /**
  * `<bds-button>` — framework-agnostic Button custom element.
  *
  * Attributes:
- *   variant   — "default" (filled, default) | "ghost" (transparent + outlined)
+ *   variant   — "default" (filled, default) | "outline" (transparent + outlined) | "ghost" (deprecated alias for "outline")
  *   size      — "small" | "medium" (default) | "large"
  *   disabled  — boolean
  *   href      — renders an <a> tag instead of <button>
@@ -38,9 +38,9 @@ export class BdsButton extends LitElement {
     }
     @keyframes pulse {
-      0%   { transform: scale(1);    box-shadow: 0 0 0 0    rgb(from var(--button_pulse-color, var(--button_color, var(--bds-color_green))) r g b / 50%); }
-      70%  { transform: scale(1.01); box-shadow: 0 0 0 var(--bds-space_m) rgb(from var(--button_pulse-color, var(--button_color, var(--bds-color_green))) r g b / 0%); }
-      100% { transform: scale(1);    box-shadow: 0 0 0 0    rgb(from var(--button_pulse-color, var(--button_color, var(--bds-color_green))) r g b / 0%); }
+      0%   { transform: scale(1);    box-shadow: 0 0 0 0    rgb(from var(--button_pulse-color, var(--button_color, var(--bds-color_interactive))) r g b / 50%); }
+      70%  { transform: scale(1.01); box-shadow: 0 0 0 var(--bds-space_m) rgb(from var(--button_pulse-color, var(--button_color, var(--bds-color_interactive))) r g b / 0%); }
+      100% { transform: scale(1);    box-shadow: 0 0 0 0    rgb(from var(--button_pulse-color, var(--button_color, var(--bds-color_interactive))) r g b / 0%); }
     }
     :host {
@@ -64,16 +64,16 @@ export class BdsButton extends LitElement {
       white-space: nowrap;
       line-height: 1;
-      --button_color:    var(--bds-color_green);
-      --button_on-color: var(--bds-color_on-green);
+      --button_color:        var(--bds-color_interactive);
+      --button_on-color:     var(--bds-color_on-interactive);
+      --button_color--on-bg: var(--bds-color_interactive_on-bg);
       background-color: var(--button_bg, var(--button_color));
       color: var(--button_text, var(--button_on-color));
       border: var(--button_border, none);
       --bdc_color: transparent;
-      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: var(--bds-animation_transition),
                   --bdc_color var(--bds-animation_transition-duration) var(--bds-animation_easing);
     }
@@ -83,10 +83,11 @@ export class BdsButton extends LitElement {
     }
     /* Variants */
-    .button.ghost {
+    .button.outline,
+    .button.ghost /* deprecated — use variant="outline" */ {
       --button_bg:   transparent;
-      --button_text: var(--button_color);
-      --bdc_color:   var(--button_color);
+      --button_text: var(--button_color--on-bg);
+      --bdc_color:   var(--button_color--on-bg);
     }
     /* Sizes */
@@ -155,7 +156,8 @@ export class BdsButton extends LitElement {
         --bdc_color:          currentcolor;
       }
-      /* Ghost hover */
+      /* Outline hover */
+      .button.outline:hover,
       .button.ghost:hover {
         --button_bg:   var(--button_color);
         --button_text: var(--button_on-color);

package/src/web-components/interaction/bds-collapsible.ts CHANGED Viewed

@@ -91,6 +91,7 @@ export class BdsCollapsible extends LitElement {
     .content {
       padding: var(--bds-space_m);
+      background-color: var(--collapsible_content-bg, var(--bds-color_bg));
       color: var(--collapsible_on-color, var(--bds-color_on-bg));
       font-size: var(--bds-font_size--body);
       line-height: var(--bds-font_line-height--body);

package/src/web-components/interaction/bds-dialog.ts CHANGED Viewed

@@ -37,10 +37,8 @@ export class BdsDialog extends LitElement {
       --bdc_color: currentcolor;
       --bdc-outline_radius: var(--bds-border_radius--m);
-      outline: var(--bdc-outline_width) solid var(--bdc_color);
-      outline-offset: var(--bdc-outline_offset);
       border-radius: var(--dialog_radius, var(--bdc-outline_radius));
-      box-shadow: var(--dialog_shadow, var(--bdc-outline_shadow));
+      box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color), var(--dialog_shadow, var(--bdc-outline_shadow));
       background-color: var(--dialog_color, var(--bds-color_grey--subtle));
       color: var(--dialog_on-color, var(--bds-color_on-grey--subtle));
       padding: var(--bds-space_l);
@@ -74,8 +72,7 @@ export class BdsDialog extends LitElement {
       border: var(--dialog_close-border, none);
       --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);
       cursor: pointer;
     }