@boostdev/design-system-components 0.1.1

package/src/components/ui/Calendar/Calendar.tsx

@@ -0,0 +1,184 @@
+import { useState, useId, KeyboardEvent } from 'react';
+import css from './Calendar.module.css';
+import { cn } from '@boostdev/design-system-foundation';
+
+const DAYS = ['Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa'];
+const MONTHS = [
+  'January', 'February', 'March', 'April', 'May', 'June',
+  'July', 'August', 'September', 'October', 'November', 'December',
+];
+
+interface CalendarProps {
+  value?: Date;
+  defaultValue?: Date;
+  min?: Date;
+  max?: Date;
+  onChange?: (date: Date) => void;
+  className?: string;
+}
+
+function isSameDay(a: Date, b: Date): boolean {
+  return a.getFullYear() === b.getFullYear() &&
+    a.getMonth() === b.getMonth() &&
+    a.getDate() === b.getDate();
+}
+
+function isOutOfRange(date: Date, min?: Date, max?: Date): boolean {
+  if (min && date < min) return true;
+  if (max && date > max) return true;
+  return false;
+}
+
+function getDaysInMonth(year: number, month: number): number {
+  return new Date(year, month + 1, 0).getDate();
+}
+
+function getFirstDayOfMonth(year: number, month: number): number {
+  return new Date(year, month, 1).getDay();
+}
+
+export function Calendar({ value, defaultValue, min, max, onChange, className }: Readonly<CalendarProps>) {
+  const today = new Date();
+  const controlled = value !== undefined;
+  const [internal, setInternal] = useState<Date | undefined>(defaultValue);
+  const selected = controlled ? value : internal;
+
+  const [viewYear, setViewYear] = useState(selected?.getFullYear() ?? today.getFullYear());
+  const [viewMonth, setViewMonth] = useState(selected?.getMonth() ?? today.getMonth());
+  const [focusedDay, setFocusedDay] = useState<number | undefined>();
+
+  const titleId = useId();
+  const daysInMonth = getDaysInMonth(viewYear, viewMonth);
+  const firstDay = getFirstDayOfMonth(viewYear, viewMonth);
+
+  const navigate = (delta: number) => {
+    const d = new Date(viewYear, viewMonth + delta, 1);
+    setViewYear(d.getFullYear());
+    setViewMonth(d.getMonth());
+    setFocusedDay(undefined);
+  };
+
+  const selectDay = (day: number) => {
+    const date = new Date(viewYear, viewMonth, day);
+    if (isOutOfRange(date, min, max)) return;
+    if (!controlled) setInternal(date);
+    onChange?.(date);
+  };
+
+  const handleKeyDown = (e: KeyboardEvent<HTMLElement>, day: number) => {
+    const map: Record<string, number> = {
+      ArrowRight: 1, ArrowLeft: -1, ArrowDown: 7, ArrowUp: -7,
+    };
+    if (e.key in map) {
+      e.preventDefault();
+      const current = new Date(viewYear, viewMonth, day);
+      const next = new Date(current);
+      next.setDate(next.getDate() + map[e.key]);
+      setViewYear(next.getFullYear());
+      setViewMonth(next.getMonth());
+      setFocusedDay(next.getDate());
+    } else if (e.key === 'Home') {
+      e.preventDefault();
+      setFocusedDay(1);
+    } else if (e.key === 'End') {
+      e.preventDefault();
+      setFocusedDay(daysInMonth);
+    } else if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault();
+      selectDay(day);
+    }
+  };
+
+  // Build grid: leading empty cells, then day cells
+  const cells: Array<{ day: number } | null> = [
+    ...Array.from({ length: firstDay }, () => null),
+    ...Array.from({ length: daysInMonth }, (_, i) => ({ day: i + 1 })),
+  ];
+  // Pad to complete last row
+  while (cells.length % 7 !== 0) cells.push(null);
+
+  return (
+    <div className={cn(css.calendar, className)} role="group" aria-labelledby={titleId}>
+      <div className={css.header}>
+        <button
+          type="button"
+          className={css.navBtn}
+          aria-label="Previous month"
+          onClick={() => navigate(-1)}
+        >
+          <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5">
+            <path strokeLinecap="round" strokeLinejoin="round" d="M15 19l-7-7 7-7" />
+          </svg>
+        </button>
+        <span id={titleId} className={css.monthYear} aria-live="polite">
+          {MONTHS[viewMonth]} {viewYear}
+        </span>
+        <button
+          type="button"
+          className={css.navBtn}
+          aria-label="Next month"
+          onClick={() => navigate(1)}
+        >
+          <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5">
+            <path strokeLinecap="round" strokeLinejoin="round" d="M9 5l7 7-7 7" />
+          </svg>
+        </button>
+      </div>
+
+      <table
+        className={css.grid}
+        role="grid"
+        aria-labelledby={titleId}
+      >
+        <thead>
+          <tr>
+            {DAYS.map(d => (
+              <th key={d} scope="col" abbr={d} className={css.weekday}>
+                {d}
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {Array.from({ length: cells.length / 7 }, (_, row) => (
+            <tr key={row}>
+              {cells.slice(row * 7, row * 7 + 7).map((cell, col) => {
+                if (!cell) return <td key={col} className={css.empty} aria-hidden="true" />;
+
+                const date = new Date(viewYear, viewMonth, cell.day);
+                const isSelected = selected ? isSameDay(date, selected) : false;
+                const isToday = isSameDay(date, today);
+                const disabled = isOutOfRange(date, min, max);
+                const isFocused = focusedDay === cell.day;
+
+                return (
+                  <td key={col} role="gridcell">
+                    <button
+                      type="button"
+                      className={cn(
+                        css.day,
+                        isSelected && css.selected,
+                        isToday && !isSelected && css.today,
+                        disabled && css.disabled,
+                      )}
+                      aria-label={date.toLocaleDateString('en', { month: 'long', day: 'numeric', year: 'numeric' })}
+                      aria-pressed={isSelected}
+                      aria-current={isToday ? 'date' : undefined}
+                      aria-disabled={disabled}
+                      disabled={disabled}
+                      tabIndex={isFocused || (!focusedDay && isSelected) || (!focusedDay && !selected && isToday) ? 0 : -1}
+                      onClick={() => selectDay(cell.day)}
+                      onKeyDown={e => handleKeyDown(e, cell.day)}
+                    >
+                      {cell.day}
+                    </button>
+                  </td>
+                );
+              })}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}

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

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

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

@@ -0,0 +1,66 @@
+@layer component {
+  .carousel {
+    position: relative;
+    display: flex;
+    align-items: center;
+    gap: var(--space_xs);
+  }
+
+  .track {
+    display: flex;
+    gap: var(--space_m);
+    overflow-x: auto;
+    scroll-snap-type: x mandatory;
+    scrollbar-width: none;
+    flex: 1;
+    scroll-behavior: smooth;
+  }
+
+  .track::-webkit-scrollbar {
+    display: none;
+  }
+
+  .slide {
+    scroll-snap-align: start;
+    flex-shrink: 0;
+  }
+
+  .navBtn {
+    all: unset;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 2.5rem;
+    height: 2.5rem;
+    border-radius: 50%;
+    background-color: var(--color_bg);
+    border: 1px solid var(--color_on-bg);
+    color: var(--color_on-bg);
+    cursor: pointer;
+    flex-shrink: 0;
+    transition: var(--animation_transition);
+    box-shadow: var(--shadow_s);
+  }
+
+  .navBtn svg {
+    width: 1.25rem;
+    height: 1.25rem;
+  }
+
+  .navBtn:focus-visible {
+    outline: var(--outline_default);
+    outline-offset: var(--outline_offset);
+  }
+
+  @media (hover: hover) and (pointer: fine) {
+    .navBtn:hover {
+      background-color: var(--color_bg--subtle);
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .track {
+      scroll-behavior: auto;
+    }
+  }
+}

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

@@ -0,0 +1,29 @@
+import { render, screen } from '@testing-library/react';
+import { Carousel } from './Carousel';
+
+const items = [<div key="1">Slide 1</div>, <div key="2">Slide 2</div>, <div key="3">Slide 3</div>];
+
+describe('Carousel', () => {
+  it('renders a section with accessible label', () => {
+    render(<Carousel items={items} label="Featured items" />);
+    expect(screen.getByRole('region', { name: 'Featured items' })).toBeInTheDocument();
+  });
+
+  it('renders all slide items', () => {
+    render(<Carousel items={items} label="Slides" />);
+    expect(screen.getAllByRole('listitem')).toHaveLength(3);
+  });
+
+  it('renders prev and next navigation buttons', () => {
+    render(<Carousel items={items} label="Slides" />);
+    expect(screen.getByRole('button', { name: 'Previous' })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Next' })).toBeInTheDocument();
+  });
+
+  it('renders slide content', () => {
+    render(<Carousel items={items} label="Slides" />);
+    expect(screen.getByText('Slide 1')).toBeInTheDocument();
+    expect(screen.getByText('Slide 2')).toBeInTheDocument();
+    expect(screen.getByText('Slide 3')).toBeInTheDocument();
+  });
+});

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

@@ -0,0 +1,30 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Carousel } from './Carousel';
+
+const meta = {
+  title: 'UI/Carousel',
+  component: Carousel,
+  tags: ['autodocs'],
+} satisfies Meta<typeof Carousel>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const cardStyle: React.CSSProperties = {
+  width: '16rem',
+  height: '10rem',
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'center',
+  background: 'var(--color_bg--subtle)',
+  borderRadius: '0.5rem',
+  fontSize: '1.5rem',
+  fontWeight: 600,
+};
+
+export const Default: Story = {
+  args: {
+    label: 'Featured slides',
+    items: [1, 2, 3, 4, 5].map(n => <div key={n} style={cardStyle}>Slide {n}</div>),
+  },
+};

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

@@ -0,0 +1,64 @@
+import { ReactNode, useRef, useId } from 'react';
+import css from './Carousel.module.css';
+import { cn } from '@boostdev/design-system-foundation';
+
+interface CarouselProps {
+  items: ReactNode[];
+  label: string;
+  className?: string;
+}
+
+export function Carousel({ items, label, className }: 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',
+    });
+  };
+
+  return (
+    <section aria-label={label} className={cn(css.carousel, className)}>
+      <button
+        type="button"
+        className={cn(css.navBtn, css['--prev'])}
+        aria-label="Previous"
+        aria-controls={listId}
+        onClick={() => scroll('prev')}
+      >
+        <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5">
+          <path strokeLinecap="round" strokeLinejoin="round" d="M15 19l-7-7 7-7" />
+        </svg>
+      </button>
+
+      <div
+        ref={trackRef}
+        id={listId}
+        role="list"
+        className={css.track}
+      >
+        {items.map((item, i) => (
+          <div key={i} role="listitem" className={css.slide}>
+            {item}
+          </div>
+        ))}
+      </div>
+
+      <button
+        type="button"
+        className={cn(css.navBtn, css['--next'])}
+        aria-label="Next"
+        aria-controls={listId}
+        onClick={() => scroll('next')}
+      >
+        <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5">
+          <path strokeLinecap="round" strokeLinejoin="round" d="M9 5l7 7-7 7" />
+        </svg>
+      </button>
+    </section>
+  );
+}

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

@@ -0,0 +1 @@
+export { Carousel } from './Carousel';

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

@@ -0,0 +1,43 @@
+@layer component {
+  .list {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space_s);
+    margin: 0;
+    padding: 0;
+    font-size: var(--font_size--body);
+    color: var(--color_on-bg);
+  }
+
+  .group {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space_xxs);
+  }
+
+  .term {
+    font-weight: var(--font_weight--semibold);
+    color: var(--color_on-bg);
+  }
+
+  .details {
+    margin: 0;
+    color: var(--color_on-bg--muted);
+  }
+
+  /* Inline layout */
+  .--layout_inline .group {
+    display: grid;
+    grid-template-columns: minmax(8rem, 1fr) 2fr;
+    gap: var(--space_xs);
+    align-items: baseline;
+  }
+
+  .--layout_inline .term {
+    grid-column: 1;
+  }
+
+  .--layout_inline .details {
+    grid-column: 2;
+  }
+}

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

@@ -0,0 +1,31 @@
+import { render, screen } from '@testing-library/react';
+import { DescriptionList } from './DescriptionList';
+
+const items = [
+  { term: 'Name', details: 'Alice' },
+  { term: 'Role', details: 'Admin' },
+];
+
+describe('DescriptionList', () => {
+  it('renders a description list', () => {
+    render(<DescriptionList items={items} />);
+    expect(screen.getAllByRole('term')[0]).toHaveTextContent('Name');
+  });
+
+  it('renders all terms', () => {
+    render(<DescriptionList items={items} />);
+    expect(screen.getAllByRole('term')).toHaveLength(2);
+  });
+
+  it('renders all definitions', () => {
+    render(<DescriptionList items={items} />);
+    const definitions = screen.getAllByRole('definition');
+    expect(definitions[0]).toHaveTextContent('Alice');
+    expect(definitions[1]).toHaveTextContent('Admin');
+  });
+
+  it('renders multiple details for one term', () => {
+    render(<DescriptionList items={[{ term: 'Tags', details: ['React', 'TypeScript'] }]} />);
+    expect(screen.getAllByRole('definition')).toHaveLength(2);
+  });
+});

package/src/components/ui/DescriptionList/DescriptionList.stories.tsx

@@ -0,0 +1,21 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { DescriptionList } from './DescriptionList';
+
+const meta = {
+  title: 'UI/DescriptionList',
+  component: DescriptionList,
+  tags: ['autodocs'],
+} satisfies Meta<typeof DescriptionList>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const items = [
+  { term: 'Full name', details: 'Alice Johnson' },
+  { term: 'Email', details: 'alice@example.com' },
+  { term: 'Role', details: 'Administrator' },
+  { term: 'Tags', details: ['React', 'TypeScript', 'Design Systems'] },
+];
+
+export const Stacked: Story = { args: { items } };
+export const Inline: Story = { args: { items, layout: 'inline' } };

package/src/components/ui/DescriptionList/DescriptionList.tsx

@@ -0,0 +1,30 @@
+import { ReactNode } from 'react';
+import css from './DescriptionList.module.css';
+import { cn } from '@boostdev/design-system-foundation';
+
+interface DescriptionItem {
+  term: ReactNode;
+  details: ReactNode | ReactNode[];
+}
+
+interface DescriptionListProps {
+  items: DescriptionItem[];
+  layout?: 'stacked' | 'inline';
+  className?: string;
+}
+
+export function DescriptionList({ items, layout = 'stacked', className }: Readonly<DescriptionListProps>) {
+  return (
+    <dl className={cn(css.list, css[`--layout_${layout}`], className)}>
+      {items.map((item, i) => (
+        <div key={i} className={css.group}>
+          <dt className={css.term}>{item.term}</dt>
+          {Array.isArray(item.details)
+            ? item.details.map((d, j) => <dd key={j} className={css.details}>{d}</dd>)
+            : <dd className={css.details}>{item.details}</dd>
+          }
+        </div>
+      ))}
+    </dl>
+  );
+}

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

@@ -0,0 +1 @@
+export { DescriptionList } from './DescriptionList';

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

@@ -0,0 +1,64 @@
+@layer component {
+  .link {
+    --link_color:       var(--color_interactive);
+    --link_color-hover: var(--color_blue--strong);
+
+    color: var(--link_color);
+    text-decoration: underline;
+    text-underline-offset: 0.2em;
+    transition: var(--animation_transition);
+    cursor: pointer;
+  }
+
+  .link:focus-visible {
+    outline: var(--outline_default);
+    outline-offset: var(--outline_offset);
+    border-radius: var(--border_radius--xs);
+  }
+
+  @media (hover: hover) and (pointer: fine) {
+    .link:hover {
+      --link_color: var(--link_color-hover);
+    }
+  }
+
+  .--variant_default {
+    --link_color:       var(--color_interactive);
+    --link_color-hover: var(--color_blue--strong);
+  }
+
+  .--variant_subtle {
+    --link_color:       var(--color_on-bg);
+    --link_color-hover: var(--color_interactive);
+  }
+
+  .--variant_standalone {
+    --link_color:       var(--color_interactive);
+    --link_color-hover: var(--color_blue--strong);
+
+    display: inline-flex;
+    align-items: center;
+    gap: var(--space_xxs);
+    font-weight: var(--font_weight--semibold);
+    text-decoration: none;
+  }
+
+  @media (hover: hover) and (pointer: fine) {
+    .--variant_standalone:hover {
+      text-decoration: underline;
+      text-underline-offset: 0.2em;
+    }
+  }
+
+  .externalLabel {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border-width: 0;
+  }
+}

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

@@ -0,0 +1,43 @@
+import { render, screen } from '@testing-library/react';
+import { Link } from './Link';
+
+describe('Link', () => {
+  it('renders an anchor element', () => {
+    render(<Link href="/about">About</Link>);
+    expect(screen.getByRole('link', { name: 'About' })).toBeInTheDocument();
+  });
+
+  it('forwards the href', () => {
+    render(<Link href="/contact">Contact</Link>);
+    expect(screen.getByRole('link')).toHaveAttribute('href', '/contact');
+  });
+
+  it('renders children', () => {
+    render(<Link href="#">Click me</Link>);
+    expect(screen.getByText('Click me')).toBeInTheDocument();
+  });
+
+  it('adds target and rel for external links', () => {
+    render(<Link href="https://example.com" external>External</Link>);
+    const link = screen.getByRole('link');
+    expect(link).toHaveAttribute('target', '_blank');
+    expect(link).toHaveAttribute('rel', 'noreferrer noopener');
+  });
+
+  it('adds a visually hidden "(opens in new tab)" label for external links', () => {
+    render(<Link href="https://example.com" external>Visit us</Link>);
+    expect(screen.getByText('(opens in new tab)', { exact: false })).toBeInTheDocument();
+  });
+
+  it('does not add target or rel for internal links', () => {
+    render(<Link href="/internal">Internal</Link>);
+    const link = screen.getByRole('link');
+    expect(link).not.toHaveAttribute('target');
+    expect(link).not.toHaveAttribute('rel');
+  });
+
+  it('accepts a custom className', () => {
+    render(<Link href="#" className="custom">Link</Link>);
+    expect(screen.getByRole('link')).toHaveClass('custom');
+  });
+});

package/src/components/ui/Link/Link.stories.tsx

@@ -0,0 +1,55 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Link } from './Link';
+
+const meta = {
+  title: 'UI/Link',
+  component: Link,
+  tags: ['autodocs'],
+  argTypes: {
+    variant: { control: 'radio', options: ['default', 'subtle', 'standalone'] },
+  },
+} satisfies Meta<typeof Link>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = { args: { children: 'Read more', href: '#', variant: 'default' } };
+export const Subtle: Story = { args: { children: 'Learn more', href: '#', variant: 'subtle' } };
+export const Standalone: Story = { args: { children: 'View all products →', href: '#', variant: 'standalone' } };
+export const External: Story = { args: { children: 'Visit our website', href: 'https://example.com', external: true } };
+
+export const InlineUsage: Story = {
+  render: () => (
+    <p>
+      Read our <Link href="#">terms and conditions</Link> before signing up.
+      You can also visit our <Link href="https://example.com" external>partner site</Link>.
+    </p>
+  ),
+};
+
+export const AsButton: Story = {
+  render: () => (
+    <Link as="button" type="button" variant="default" onClick={() => alert('clicked')}>
+      Rendered as a button
+    </Link>
+  ),
+};
+
+export const AsSpan: Story = {
+  render: () => (
+    <Link as="span" variant="subtle">
+      Rendered as a span (no href)
+    </Link>
+  ),
+};
+
+export const AllVariants: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>
+      <Link href="#" variant="default">Default link</Link>
+      <Link href="#" variant="subtle">Subtle link</Link>
+      <Link href="#" variant="standalone">Standalone link →</Link>
+      <Link href="https://example.com" external>External link</Link>
+    </div>
+  ),
+};