@boostdev/design-system-components 2.7.1 → 2.11.0

package/src/components/ui/Calendar/calendar-core.spec.ts

@@ -0,0 +1,176 @@
+import {
+  toISO, parseISO, addDays, addMonths, isSameDay, compareDay, clampToRange,
+  sortRange, isInRange, isDisabled, buildMonthGrid,
+  getMonthLabel, getDayLabel, getWeekdayNames, nextFocusDate,
+} from './calendar-core';
+
+describe('calendar-core', () => {
+  describe('toISO / parseISO', () => {
+    it('formats a date as YYYY-MM-DD in local time', () => {
+      expect(toISO(new Date(2024, 0, 5))).toBe('2024-01-05');
+      expect(toISO(new Date(2024, 11, 31))).toBe('2024-12-31');
+    });
+    it('round-trips through parseISO', () => {
+      const d = parseISO('2024-03-15')!;
+      expect(d.getFullYear()).toBe(2024);
+      expect(d.getMonth()).toBe(2);
+      expect(d.getDate()).toBe(15);
+    });
+    it('returns null for invalid input', () => {
+      expect(parseISO('')).toBeNull();
+      expect(parseISO('nope')).toBeNull();
+      expect(parseISO('2024-13-40')).toBeNull();
+    });
+    it('parses years below 100 without the Date two-digit-year remap', () => {
+      const d = parseISO('0099-01-15')!;
+      expect(d.getFullYear()).toBe(99);
+      expect(d.getMonth()).toBe(0);
+      expect(d.getDate()).toBe(15);
+    });
+  });
+
+  describe('addDays', () => {
+    it('crosses month and year boundaries', () => {
+      expect(toISO(addDays(new Date(2024, 0, 31), 1))).toBe('2024-02-01');
+      expect(toISO(addDays(new Date(2024, 11, 31), 1))).toBe('2025-01-01');
+      expect(toISO(addDays(new Date(2024, 0, 1), -1))).toBe('2023-12-31');
+    });
+  });
+
+  describe('addMonths', () => {
+    it('clamps the day to the target month length', () => {
+      expect(toISO(addMonths(new Date(2024, 0, 31), 1))).toBe('2024-02-29');  // leap Feb
+      expect(toISO(addMonths(new Date(2023, 2, 31), -1))).toBe('2023-02-28'); // non-leap Feb
+      expect(toISO(addMonths(new Date(2024, 0, 15), 13))).toBe('2025-02-15'); // spans >12 months
+      expect(toISO(addMonths(new Date(2024, 0, 15), -1))).toBe('2023-12-15'); // crosses year back
+    });
+  });
+
+  describe('isSameDay / compareDay', () => {
+    it('compares by calendar day only', () => {
+      expect(isSameDay(new Date(2024, 0, 1, 9), new Date(2024, 0, 1, 23))).toBe(true);
+      expect(compareDay(new Date(2024, 0, 1), new Date(2024, 0, 2))).toBe(-1);
+      expect(compareDay(new Date(2024, 0, 2), new Date(2024, 0, 1))).toBe(1);
+      expect(compareDay(new Date(2024, 0, 1, 8), new Date(2024, 0, 1, 20))).toBe(0);
+    });
+  });
+
+  describe('clampToRange', () => {
+    it('clamps below min and above max, passes through in-range', () => {
+      const min = new Date(2024, 0, 10);
+      const max = new Date(2024, 0, 20);
+      expect(toISO(clampToRange(new Date(2024, 0, 5), min, max))).toBe('2024-01-10');
+      expect(toISO(clampToRange(new Date(2024, 0, 25), min, max))).toBe('2024-01-20');
+      expect(toISO(clampToRange(new Date(2024, 0, 15), min, max))).toBe('2024-01-15');
+    });
+    it('always returns a fresh, midnight-normalized Date, even when in range', () => {
+      const input = new Date(2024, 0, 15, 9, 30);
+      const out = clampToRange(input, new Date(2024, 0, 10), new Date(2024, 0, 20));
+      expect(out).not.toBe(input);
+      expect(out.getHours()).toBe(0);
+      expect(toISO(out)).toBe('2024-01-15');
+    });
+  });
+
+  describe('sortRange / isInRange', () => {
+    it('sorts earliest first regardless of argument order', () => {
+      const [a, b] = sortRange(new Date(2024, 0, 20), new Date(2024, 0, 10));
+      expect(toISO(a)).toBe('2024-01-10');
+      expect(toISO(b)).toBe('2024-01-20');
+    });
+    it('is inclusive and order-independent', () => {
+      const s = new Date(2024, 0, 10);
+      const e = new Date(2024, 0, 20);
+      expect(isInRange(new Date(2024, 0, 10), s, e)).toBe(true);
+      expect(isInRange(new Date(2024, 0, 20), e, s)).toBe(true);
+      expect(isInRange(new Date(2024, 0, 15), s, e)).toBe(true);
+      expect(isInRange(new Date(2024, 0, 9), s, e)).toBe(false);
+      expect(isInRange(new Date(2024, 0, 21), s, e)).toBe(false);
+    });
+  });
+
+  describe('isDisabled', () => {
+    it('respects min, max, and the predicate', () => {
+      const min = new Date(2024, 0, 10);
+      const max = new Date(2024, 0, 20);
+      expect(isDisabled(new Date(2024, 0, 9), { min, max })).toBe(true);
+      expect(isDisabled(new Date(2024, 0, 21), { min, max })).toBe(true);
+      expect(isDisabled(new Date(2024, 0, 15), { min, max })).toBe(false);
+      const weekends = (d: Date) => d.getDay() === 0 || d.getDay() === 6;
+      expect(isDisabled(new Date(2024, 0, 13), { isDateDisallowed: weekends })).toBe(true); // Sat
+      expect(isDisabled(new Date(2024, 0, 15), { isDateDisallowed: weekends })).toBe(false); // Mon
+    });
+  });
+
+  describe('buildMonthGrid', () => {
+    it('always returns 42 cells', () => {
+      expect(buildMonthGrid(2024, 1, 1)).toHaveLength(42);
+    });
+    it('Monday-first January 2024 starts on the 1st (Jan 1 2024 is a Monday)', () => {
+      const cells = buildMonthGrid(2024, 0, 1);
+      expect(cells[0].iso).toBe('2024-01-01');
+      expect(cells[0].outside).toBe(false);
+    });
+    it('Sunday-first January 2024 leads with Dec 31 2023 (outside)', () => {
+      const cells = buildMonthGrid(2024, 0, 0);
+      expect(cells[0].iso).toBe('2023-12-31');
+      expect(cells[0].outside).toBe(true);
+      expect(cells[1].iso).toBe('2024-01-01');
+      expect(cells[1].outside).toBe(false);
+    });
+    it('marks in-month day count correctly for a leap February', () => {
+      const cells = buildMonthGrid(2024, 1, 1); // Feb 2024 = 29 days
+      expect(cells.filter(c => !c.outside)).toHaveLength(29);
+    });
+  });
+
+  describe('Intl helpers', () => {
+    it('getMonthLabel formats month + year (en)', () => {
+      expect(getMonthLabel(2024, 0, 'en-US')).toBe('January 2024');
+    });
+    it('getDayLabel formats a long date (en)', () => {
+      expect(getDayLabel(new Date(2024, 0, 15), 'en-US')).toBe('January 15, 2024');
+    });
+    it('getWeekdayNames returns 7 names starting from firstDayOfWeek (en, Monday)', () => {
+      const names = getWeekdayNames('en-US', 1);
+      expect(names).toHaveLength(7);
+      expect(names[0]).toBe('Mon');
+      expect(names[6]).toBe('Sun');
+    });
+    it('getWeekdayNames starts on Sunday when firstDayOfWeek=0', () => {
+      expect(getWeekdayNames('en-US', 0)[0]).toBe('Sun');
+    });
+  });
+
+  describe('nextFocusDate', () => {
+    const opts = { firstDayOfWeek: 1 };
+    it('moves by day and week with arrows', () => {
+      expect(toISO(nextFocusDate(new Date(2024, 0, 15), 'ArrowRight', opts)!)).toBe('2024-01-16');
+      expect(toISO(nextFocusDate(new Date(2024, 0, 15), 'ArrowLeft', opts)!)).toBe('2024-01-14');
+      expect(toISO(nextFocusDate(new Date(2024, 0, 15), 'ArrowDown', opts)!)).toBe('2024-01-22');
+      expect(toISO(nextFocusDate(new Date(2024, 0, 15), 'ArrowUp', opts)!)).toBe('2024-01-08');
+    });
+    it('moves to week bounds with Home/End honoring firstDayOfWeek', () => {
+      // 2024-01-17 is a Wednesday; Monday-first week → Home = Mon Jan 15, End = Sun Jan 21
+      expect(toISO(nextFocusDate(new Date(2024, 0, 17), 'Home', opts)!)).toBe('2024-01-15');
+      expect(toISO(nextFocusDate(new Date(2024, 0, 17), 'End', opts)!)).toBe('2024-01-21');
+      // Sunday-first week → Home = Sun Jan 14, End = Sat Jan 20
+      expect(toISO(nextFocusDate(new Date(2024, 0, 17), 'Home', { firstDayOfWeek: 0 })!)).toBe('2024-01-14');
+    });
+    it('pages by month and, with shift, by year', () => {
+      expect(toISO(nextFocusDate(new Date(2024, 0, 15), 'PageUp', opts)!)).toBe('2023-12-15');
+      expect(toISO(nextFocusDate(new Date(2024, 0, 15), 'PageDown', opts)!)).toBe('2024-02-15');
+      expect(toISO(nextFocusDate(new Date(2024, 0, 15), 'PageUp', { ...opts, shiftKey: true })!)).toBe('2023-01-15');
+      expect(toISO(nextFocusDate(new Date(2024, 0, 15), 'PageDown', { ...opts, shiftKey: true })!)).toBe('2025-01-15');
+    });
+    it('clamps the day when paging into a shorter month or year', () => {
+      expect(toISO(nextFocusDate(new Date(2024, 0, 31), 'PageDown', opts)!)).toBe('2024-02-29');
+      expect(toISO(nextFocusDate(new Date(2023, 2, 31), 'PageUp', opts)!)).toBe('2023-02-28');
+      expect(toISO(nextFocusDate(new Date(2024, 1, 29), 'PageUp', { ...opts, shiftKey: true })!)).toBe('2023-02-28');
+    });
+    it('returns null for non-navigation keys', () => {
+      expect(nextFocusDate(new Date(2024, 0, 15), 'Enter', opts)).toBeNull();
+      expect(nextFocusDate(new Date(2024, 0, 15), 'a', opts)).toBeNull();
+    });
+  });
+});

package/src/components/ui/Calendar/calendar-core.ts

@@ -0,0 +1,164 @@
+/**
+ * Framework-agnostic calendar logic shared by the React <Calendar>/<CalendarRange>
+ * components and the <bds-calendar>/<bds-calendar-range> web components.
+ * Pure functions only — no React, no Lit, no DOM.
+ */
+
+export type ISODate = string; // 'YYYY-MM-DD'
+
+/** Format a Date to ISO 8601 `YYYY-MM-DD` in local time. */
+export function toISO(date: Date): ISODate {
+  const y = date.getFullYear();
+  const m = String(date.getMonth() + 1).padStart(2, '0');
+  const d = String(date.getDate()).padStart(2, '0');
+  return `${y}-${m}-${d}`;
+}
+
+/** Parse `YYYY-MM-DD` to a local-time Date at midnight, or null if invalid. */
+export function parseISO(iso: string): Date | null {
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(iso);
+  if (!m) return null;
+  const year = Number(m[1]);
+  const month = Number(m[2]) - 1;
+  const day = Number(m[3]);
+  const date = new Date(year, month, day);
+  // The Date constructor remaps years 0–99 to 1900–1999; force the literal year.
+  date.setFullYear(year);
+  if (isNaN(date.getTime())) return null;
+  // Reject overflow (e.g. 2024-13-40 rolling into another month/day).
+  if (date.getFullYear() !== year || date.getMonth() !== month || date.getDate() !== day) return null;
+  return date;
+}
+
+/** A new midnight Date `n` days after `date` (n may be negative). */
+export function addDays(date: Date, n: number): Date {
+  return new Date(date.getFullYear(), date.getMonth(), date.getDate() + n);
+}
+
+/**
+ * A new midnight Date `n` months after `date` (n may be negative), with the
+ * day-of-month clamped to the target month's length so e.g. Jan 31 + 1 month
+ * lands on Feb 28/29, never rolling over into March.
+ */
+export function addMonths(date: Date, n: number): Date {
+  const firstOfTarget = new Date(date.getFullYear(), date.getMonth() + n, 1);
+  const daysInTarget = new Date(firstOfTarget.getFullYear(), firstOfTarget.getMonth() + 1, 0).getDate();
+  return new Date(firstOfTarget.getFullYear(), firstOfTarget.getMonth(), Math.min(date.getDate(), daysInTarget));
+}
+
+export function isSameDay(a: Date, b: Date): boolean {
+  return a.getFullYear() === b.getFullYear()
+    && a.getMonth() === b.getMonth()
+    && a.getDate() === b.getDate();
+}
+
+/** -1 if a is before b, 1 if after, 0 if same calendar day. */
+export function compareDay(a: Date, b: Date): number {
+  const am = new Date(a.getFullYear(), a.getMonth(), a.getDate()).getTime();
+  const bm = new Date(b.getFullYear(), b.getMonth(), b.getDate()).getTime();
+  return am < bm ? -1 : am > bm ? 1 : 0;
+}
+
+export function clampToRange(date: Date, min?: Date, max?: Date): Date {
+  if (min && compareDay(date, min) < 0) return new Date(min.getFullYear(), min.getMonth(), min.getDate());
+  if (max && compareDay(date, max) > 0) return new Date(max.getFullYear(), max.getMonth(), max.getDate());
+  // Always return a fresh midnight Date so the result is consistent whether or not
+  // clamping occurred (never leaks the caller's reference or its time component).
+  return new Date(date.getFullYear(), date.getMonth(), date.getDate());
+}
+
+/** Earliest date first. */
+export function sortRange(a: Date, b: Date): [Date, Date] {
+  return compareDay(a, b) <= 0 ? [a, b] : [b, a];
+}
+
+/** Inclusive, order-independent membership test. */
+export function isInRange(date: Date, start: Date, end: Date): boolean {
+  const [lo, hi] = sortRange(start, end);
+  return compareDay(date, lo) >= 0 && compareDay(date, hi) <= 0;
+}
+
+export interface DisabledOpts {
+  min?: Date;
+  max?: Date;
+  isDateDisallowed?: (date: Date) => boolean;
+}
+
+export function isDisabled(date: Date, opts: DisabledOpts): boolean {
+  if (opts.min && compareDay(date, opts.min) < 0) return true;
+  if (opts.max && compareDay(date, opts.max) > 0) return true;
+  return !!opts.isDateDisallowed?.(date);
+}
+
+export interface DayCell {
+  iso: ISODate;
+  date: Date;
+  day: number;      // 1–31
+  outside: boolean; // belongs to the previous/next month
+}
+
+/**
+ * Build a stable 6-row × 7-column month grid (42 cells) beginning on
+ * `firstDayOfWeek` (0=Sun … 6=Sat). Leading/trailing days from adjacent months
+ * are flagged `outside`. Always 42 cells so multi-month rows align and the grid
+ * height never jumps between months.
+ */
+export function buildMonthGrid(year: number, month: number, firstDayOfWeek: number): DayCell[] {
+  const firstOfMonth = new Date(year, month, 1);
+  const lead = (firstOfMonth.getDay() - firstDayOfWeek + 7) % 7;
+  const start = addDays(firstOfMonth, -lead);
+  return Array.from({ length: 42 }, (_, i) => {
+    const date = addDays(start, i);
+    return { iso: toISO(date), date, day: date.getDate(), outside: date.getMonth() !== month };
+  });
+}
+
+/** Localized month + year heading, e.g. "January 2024". */
+export function getMonthLabel(year: number, month: number, locale?: string): string {
+  return new Intl.DateTimeFormat(locale, { month: 'long', year: 'numeric' })
+    .format(new Date(year, month, 1));
+}
+
+/** Localized long date for a day cell's accessible label, e.g. "January 15, 2024". */
+export function getDayLabel(date: Date, locale?: string): string {
+  return new Intl.DateTimeFormat(locale, { year: 'numeric', month: 'long', day: 'numeric' })
+    .format(date);
+}
+
+/**
+ * Seven localized short weekday names ordered from `firstDayOfWeek`.
+ * e.g. firstDayOfWeek=1 → ['Mon','Tue',…,'Sun']. 2023-01-01 is a Sunday.
+ */
+export function getWeekdayNames(locale: string | undefined, firstDayOfWeek: number): string[] {
+  const fmt = new Intl.DateTimeFormat(locale, { weekday: 'short' });
+  return Array.from({ length: 7 }, (_, i) =>
+    fmt.format(new Date(2023, 0, 1 + ((firstDayOfWeek + i) % 7))));
+}
+
+export interface FocusKeyOpts {
+  shiftKey?: boolean;
+  firstDayOfWeek: number;
+}
+
+/**
+ * WAI-ARIA date-grid keyboard model: given the focused date and a keydown key,
+ * return the date focus should move to, or null if the key is not a navigation
+ * key. Arrow keys move by day/week; Home/End snap to the week bounds (honoring
+ * firstDayOfWeek); PageUp/PageDown move by month; Shift+PageUp/PageDown by year.
+ * Shared by both React components and both web components.
+ */
+export function nextFocusDate(current: Date, key: string, opts: FocusKeyOpts): Date | null {
+  const offsetInWeek = (current.getDay() - opts.firstDayOfWeek + 7) % 7;
+  switch (key) {
+    case 'ArrowRight': return addDays(current, 1);
+    case 'ArrowLeft': return addDays(current, -1);
+    case 'ArrowDown': return addDays(current, 7);
+    case 'ArrowUp': return addDays(current, -7);
+    case 'Home': return addDays(current, -offsetInWeek);
+    case 'End': return addDays(current, 6 - offsetInWeek);
+    case 'PageUp': return addMonths(current, opts.shiftKey ? -12 : -1);
+    case 'PageDown': return addMonths(current, opts.shiftKey ? 12 : 1);
+    default:
+      return null;
+  }
+}

package/src/components/ui/Calendar/index.ts

@@ -1 +1,2 @@
 export { Calendar } from './Calendar';
+export { CalendarRange } from './CalendarRange';

package/src/components/ui/Carousel/Carousel.mdx

@@ -22,6 +22,8 @@ Horizontally scrollable slide container with previous/next navigation.
 
 ## Props
 
+> **HTML attributes** — all standard HTML attributes for the root element are forwarded via `{...rest}` (`id`, `className`, `style`, `data-*`, `aria-*`, event handlers, etc.). Component-controlled attributes take precedence.
+
 <ArgTypes of={Stories} />
 
 ## CSS variables
@@ -32,14 +34,17 @@ Horizontally scrollable slide container with previous/next navigation.
 <tr><th>Variable</th><th>Default</th><th>Description</th></tr>
 </thead>
 <tbody>
-<tr><td>`--carousel_indicator-radius`</td><td>`var(--bds-border_radius--circle)`</td><td>Navigation button border radius</td></tr>
+<tr><td>`--carousel_navBtn-radius`</td><td>`var(--bds-border_radius--circle)`</td><td>Navigation button border radius</td></tr>
+<tr><td>`--carousel_navBtn-shadow`</td><td>`var(--bds-shadow_s)`</td><td>Navigation button elevation shadow</td></tr>
 <tr><td>`--carousel_navBtn-bg--hover`</td><td>`var(--bds-color_bg--subtle)`</td><td>Navigation button background on hover</td></tr>
 </tbody>
 </table>
 
+`--carousel_indicator-radius` is a deprecated alias for `--carousel_navBtn-radius` — it still works but `--carousel_navBtn-radius` is the documented, forward-compatible name.
 
 ## Accessibility
 
 - Prev/next buttons have `aria-label="Previous"` / `"Next"`
-- The slide container has `aria-live="polite"` to announce slide changes
-- Fully keyboard navigable: buttons receive focus, slides are accessible via arrow keys
+- Prev/next buttons carry `aria-controls` pointing at the slide list
+- Scrolling respects `prefers-reduced-motion` (both the CSS `scroll-behavior` and the JS-driven prev/next scroll fall back to an instant jump)
+- Prev/next scroll toward the logical end/start of content, so they work correctly in RTL layouts too

package/src/components/ui/Carousel/Carousel.module.css

@@ -10,7 +10,7 @@
     display: flex;
     gap: var(--bds-space_m);
     overflow-inline: auto;
-    scroll-snap-type: x mandatory;
+    scroll-snap-type: inline mandatory;
     scrollbar-width: none;
     flex: 1;
     scroll-behavior: smooth;
@@ -30,16 +30,18 @@
     display: flex;
     align-items: center;
     justify-content: center;
-    inline-size: 2.5rem;
-    block-size: 2.5rem;
-    border-radius: var(--carousel_indicator-radius, var(--bds-border_radius--circle));
+    inline-size: 2.75rem;
+    block-size: 2.75rem;
+
+    /* --carousel_indicator-radius is the deprecated name for this token; kept as a fallback */
+    border-radius: var(--carousel_navBtn-radius, var(--carousel_indicator-radius, var(--bds-border_radius--circle)));
     background-color: var(--bds-color_bg);
     color: var(--bds-color_on-bg);
 
     --bdc_color: var(--bds-color_on-bg);
 
     border: none;
-    box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color), var(--bds-shadow_s);
+    box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color), var(--carousel_navBtn-shadow, var(--bds-shadow_s));
     cursor: pointer;
     flex-shrink: 0;
     transition: var(--bds-animation_transition);

package/src/components/ui/Carousel/Carousel.spec.tsx

@@ -1,9 +1,28 @@
 import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import { Carousel } from './Carousel';
 
 const items = [<div key="1">Slide 1</div>, <div key="2">Slide 2</div>, <div key="3">Slide 3</div>];
 
+function setPrefersReducedMotion(matches: boolean) {
+  window.matchMedia = vi.fn().mockImplementation((query: string) => ({
+    matches,
+    media: query,
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+    addListener: vi.fn(),
+    removeListener: vi.fn(),
+    dispatchEvent: vi.fn(),
+  }));
+}
+
 describe('Carousel', () => {
+  beforeEach(() => {
+    // jsdom does not implement matchMedia; stub it so prefers-reduced-motion checks
+    // resolve deterministically ('no preference' by default) instead of throwing.
+    setPrefersReducedMotion(false);
+  });
+
   it('renders a section with accessible label', () => {
     render(<Carousel items={items} label="Featured items" />);
     expect(screen.getByRole('region', { name: 'Featured items' })).toBeInTheDocument();
@@ -26,4 +45,52 @@ describe('Carousel', () => {
     expect(screen.getByText('Slide 2')).toBeInTheDocument();
     expect(screen.getByText('Slide 3')).toBeInTheDocument();
   });
+
+  it('scrolls the track forward when Next is clicked', async () => {
+    render(<Carousel items={items} label="Slides" />);
+    const track = screen.getByRole('list');
+    Object.defineProperty(track, 'clientWidth', { configurable: true, value: 300 });
+    track.scrollBy = vi.fn();
+
+    await userEvent.click(screen.getByRole('button', { name: 'Next' }));
+
+    expect(track.scrollBy).toHaveBeenCalledWith({ left: 300, behavior: 'smooth' });
+  });
+
+  it('scrolls the track backward when Previous is clicked', async () => {
+    render(<Carousel items={items} label="Slides" />);
+    const track = screen.getByRole('list');
+    Object.defineProperty(track, 'clientWidth', { configurable: true, value: 300 });
+    track.scrollBy = vi.fn();
+
+    await userEvent.click(screen.getByRole('button', { name: 'Previous' }));
+
+    expect(track.scrollBy).toHaveBeenCalledWith({ left: -300, behavior: 'smooth' });
+  });
+
+  it('reverses the scroll direction in RTL layouts', async () => {
+    render(<Carousel items={items} label="Slides" />);
+    const track = screen.getByRole('list');
+    Object.defineProperty(track, 'clientWidth', { configurable: true, value: 300 });
+    track.style.direction = 'rtl';
+    track.scrollBy = vi.fn();
+
+    await userEvent.click(screen.getByRole('button', { name: 'Next' }));
+    expect(track.scrollBy).toHaveBeenCalledWith({ left: -300, behavior: 'smooth' });
+
+    await userEvent.click(screen.getByRole('button', { name: 'Previous' }));
+    expect(track.scrollBy).toHaveBeenCalledWith({ left: 300, behavior: 'smooth' });
+  });
+
+  it('scrolls instantly instead of smoothly when prefers-reduced-motion is set', async () => {
+    setPrefersReducedMotion(true);
+    render(<Carousel items={items} label="Slides" />);
+    const track = screen.getByRole('list');
+    Object.defineProperty(track, 'clientWidth', { configurable: true, value: 300 });
+    track.scrollBy = vi.fn();
+
+    await userEvent.click(screen.getByRole('button', { name: 'Next' }));
+
+    expect(track.scrollBy).toHaveBeenCalledWith({ left: 300, behavior: 'auto' });
+  });
 });

package/src/components/ui/Carousel/Carousel.tsx

@@ -8,16 +8,28 @@ interface CarouselProps extends WithClassName, HTMLAttributes<HTMLElement> {
   label: string;
 }
 
+function prefersReducedMotion(): boolean {
+  return (
+    typeof window !== 'undefined' &&
+    typeof window.matchMedia === 'function' &&
+    window.matchMedia('(prefers-reduced-motion: reduce)').matches
+  );
+}
+
 export function Carousel({ items, label, className, ...rest }: Readonly<CarouselProps>) {
   const trackRef = useRef<HTMLDivElement>(null);
   const listId = useId();
 
   const scroll = (direction: 'prev' | 'next') => {
-    if (!trackRef.current) return;
-    const { scrollLeft, clientWidth } = trackRef.current;
-    trackRef.current.scrollTo({
-      left: scrollLeft + (direction === 'next' ? clientWidth : -clientWidth),
-      behavior: 'smooth',
+    const track = trackRef.current;
+    if (!track) return;
+    // Determine the physical scroll sign from the computed writing direction so
+    // "next"/"prev" always move toward the logical end/start, in LTR and RTL alike.
+    const isRtl = window.getComputedStyle(track).direction === 'rtl';
+    const sign = direction === 'next' ? 1 : -1;
+    track.scrollBy({
+      left: (isRtl ? -sign : sign) * track.clientWidth,
+      behavior: prefersReducedMotion() ? 'auto' : 'smooth',
     });
   };
 
@@ -25,7 +37,7 @@ export function Carousel({ items, label, className, ...rest }: Readonly<Carousel
     <section {...rest} aria-label={label} className={cn(css.carousel, className)}>
       <button
         type="button"
-        className={cn(css.navBtn, css['--prev'])}
+        className={css.navBtn}
         aria-label="Previous"
         aria-controls={listId}
         onClick={() => scroll('prev')}
@@ -50,7 +62,7 @@ export function Carousel({ items, label, className, ...rest }: Readonly<Carousel
 
       <button
         type="button"
-        className={cn(css.navBtn, css['--next'])}
+        className={css.navBtn}
         aria-label="Next"
         aria-controls={listId}
         onClick={() => scroll('next')}

package/src/components/ui/Collapsible/Collapsible.mdx

@@ -30,8 +30,18 @@ Use the `name` prop to link multiple Collapsibles so only one can be open at a t
 ### Rich summary content
 <Canvas of={Stories.RichSummary} />
 
+## Controlled usage
+
+Pass `open` to take full control of the expanded state. The component intercepts the summary
+click/keyboard activation, cancels the native `<details>` toggle, and reports the intended next
+state via `onToggle` — update your own `open` state in that callback to actually expand or
+collapse the panel. Without `open` (i.e. `open === undefined`), the component is uncontrolled and
+the native `<details>` element drives its own state (seeded once from `defaultOpen`).
+
 ## Props
 
+> **HTML attributes** — all standard HTML attributes for the root element are forwarded via `{...rest}` (`id`, `className`, `style`, `data-*`, `aria-*`, event handlers, etc.). Component-controlled attributes take precedence.
+
 <ArgTypes of={Stories} />
 
 ## CSS variables
@@ -41,13 +51,14 @@ Use the `name` prop to link multiple Collapsibles so only one can be open at a t
 <tr><th>Variable</th><th>Default</th><th>Description</th></tr>
 </thead>
 <tbody>
-<tr><td>`--collapsible_border-color`</td><td>`var(--bds-bg--subtle)`</td><td>Border and separator colour</td></tr>
-<tr><td>`--collapsible_border-width`</td><td>`1px`</td><td>Border and separator width</td></tr>
+<tr><td>`--collapsible_border`</td><td>`none`</td><td>Optional additional CSS border drawn around the frame — the visible frame edge is drawn by the inset box-shadow border system below, so this stays `none` by default</td></tr>
+<tr><td>`--collapsible_border-color`</td><td>`var(--bds-color_bg--subtle)`</td><td>Frame outline and separator colour</td></tr>
+<tr><td>`--collapsible_border-width`</td><td>`1px`</td><td>Frame outline and separator width</td></tr>
 <tr><td>`--collapsible_border-radius`</td><td>`var(--bds-border_radius--m)`</td><td>Corner radius</td></tr>
-<tr><td>`--collapsible_bg`</td><td>`var(--bds-bg)`</td><td>Summary background</td></tr>
-<tr><td>`--collapsible_bg--hover`</td><td>`var(--bds-bg--subtle)`</td><td>Summary background on hover</td></tr>
-<tr><td>`--collapsible_color`</td><td>`var(--bds-on-bg)`</td><td>Summary text colour</td></tr>
-<tr><td>`--collapsible_on-color`</td><td>`var(--bds-on-bg)`</td><td>Content text colour</td></tr>
+<tr><td>`--collapsible_bg`</td><td>`var(--bds-color_bg)`</td><td>Summary background</td></tr>
+<tr><td>`--collapsible_bg--hover`</td><td>`var(--bds-color_bg--subtle)`</td><td>Summary background on hover</td></tr>
+<tr><td>`--collapsible_color`</td><td>`var(--bds-color_on-bg)`</td><td>Summary text colour</td></tr>
+<tr><td>`--collapsible_on-color`</td><td>`var(--bds-color_on-bg)`</td><td>Content text colour</td></tr>
 </tbody>
 </table>
 

package/src/components/ui/Collapsible/Collapsible.module.css

@@ -1,7 +1,12 @@
 @layer boostdev.component {
   .collapsible {
-    border: var(--collapsible_border-width, 1px) solid var(--collapsible_border-color, var(--bds-color_bg--subtle));
-    border-radius: var(--collapsible_border-radius, var(--bds-border_radius--m));
+    border: var(--collapsible_border, none);
+    --bdc_color: var(--collapsible_border-color, var(--bds-color_bg--subtle));
+    --bdc-outline_width: var(--collapsible_border-width, 1px);
+    --bdc-outline_radius: var(--collapsible_border-radius, var(--bds-border_radius--m));
+
+    border-radius: var(--bdc-outline_radius);
+    box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color);
     overflow: hidden;
   }
 

package/src/components/ui/Collapsible/Collapsible.spec.tsx

@@ -1,3 +1,4 @@
+import { useState } from 'react';
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { Collapsible } from './Collapsible';
@@ -56,6 +57,45 @@ describe('Collapsible', () => {
     expect(screen.getByRole('group')).toHaveAttribute('open');
   });
 
+  it('does not change the open attribute on click when open is controlled and onToggle does not update it', async () => {
+    const user = userEvent.setup();
+    const onToggle = vi.fn();
+    render(<Collapsible summary="Toggle" open={false} onToggle={onToggle}>Content</Collapsible>);
+    const details = screen.getByRole('group');
+    await user.click(screen.getByText('Toggle'));
+    expect(details).not.toHaveAttribute('open');
+    expect(onToggle).toHaveBeenCalledWith(true);
+  });
+
+  it('reports the current open state, not a stale toggle, when controlled and already open', async () => {
+    const user = userEvent.setup();
+    const onToggle = vi.fn();
+    render(<Collapsible summary="Toggle" open onToggle={onToggle}>Content</Collapsible>);
+    const details = screen.getByRole('group');
+    await user.click(screen.getByText('Toggle'));
+    expect(details).toHaveAttribute('open');
+    expect(onToggle).toHaveBeenCalledWith(false);
+  });
+
+  it('expands and collapses a fully controlled instance when the consumer updates open from onToggle', async () => {
+    const user = userEvent.setup();
+    function Controlled() {
+      const [open, setOpen] = useState(false);
+      return (
+        <Collapsible summary="Toggle" open={open} onToggle={setOpen}>
+          Content
+        </Collapsible>
+      );
+    }
+    render(<Controlled />);
+    const details = screen.getByRole('group');
+    expect(details).not.toHaveAttribute('open');
+    await user.click(screen.getByText('Toggle'));
+    expect(details).toHaveAttribute('open');
+    await user.click(screen.getByText('Toggle'));
+    expect(details).not.toHaveAttribute('open');
+  });
+
   it('renders with name attribute for grouping', () => {
     render(
       <>