@kouji-ui/components 0.1.1

package/src/carousel/carousel.css

@@ -0,0 +1,181 @@
+@layer kj.component {
+  .kj-carousel {
+    --kj-carousel-gap:           var(--kj-space-md);
+    --kj-carousel-radius:        var(--kj-radius-box);
+    --kj-carousel-control-size:  44px;
+    --kj-carousel-control-bg:    var(--kj-bg-body);
+    --kj-carousel-control-fg:    var(--kj-fg-default);
+    --kj-carousel-indicator-size:    10px;
+    --kj-carousel-indicator-active:  var(--kj-bg-primary);
+    --kj-carousel-indicator-idle:    var(--kj-bg-field);
+
+    position: relative;
+    display: grid;
+    grid-template-columns: auto 1fr auto;
+    grid-template-rows: 1fr auto;
+    gap: var(--kj-carousel-gap);
+    align-items: center;
+  }
+
+  .kj-carousel[data-orientation="vertical"] {
+    grid-template-columns: 1fr auto;
+    grid-template-rows: auto 1fr auto auto;
+  }
+
+  .kj-carousel-viewport {
+    grid-column: 2;
+    grid-row: 1;
+    display: flex;
+    flex-direction: row;
+    overflow-x: auto;
+    overflow-y: hidden;
+    scroll-snap-type: x mandatory;
+    scrollbar-width: none;
+    border-radius: var(--kj-carousel-radius);
+    gap: var(--kj-carousel-gap);
+    scroll-behavior: smooth;
+  }
+  .kj-carousel-viewport::-webkit-scrollbar { display: none; }
+
+  .kj-carousel[data-orientation="vertical"] .kj-carousel-viewport {
+    flex-direction: column;
+    overflow-x: hidden;
+    overflow-y: auto;
+    scroll-snap-type: y mandatory;
+    grid-column: 1;
+    grid-row: 2;
+    /* Grid items default to `min-height: auto`, which lets the viewport
+       grow past its `1fr` row when slides are taller than the share —
+       defeating the scroll-snap container. Pin to 0 so the row's
+       fraction actually constrains the viewport height. */
+    min-height: 0;
+  }
+
+  .kj-carousel-slide {
+    flex: 0 0 calc(100% / var(--kj-carousel-slides-per-view, 1));
+    scroll-snap-align: start;
+    scroll-snap-stop: always;
+    border-radius: var(--kj-carousel-radius);
+    background: var(--kj-bg-body);
+    color: var(--kj-fg-default);
+    padding: var(--kj-space-lg);
+    min-height: 0;
+  }
+
+  .kj-carousel-slide[data-align="center"] { scroll-snap-align: center; }
+  .kj-carousel-slide[data-align="end"]    { scroll-snap-align: end; }
+
+  .kj-carousel-control {
+    grid-row: 1;
+    width: var(--kj-carousel-control-size);
+    height: var(--kj-carousel-control-size);
+    min-width: var(--kj-carousel-control-size);
+    min-height: var(--kj-carousel-control-size);
+    border-radius: 50%;
+    border: var(--kj-border) solid var(--kj-border-default);
+    background: var(--kj-carousel-control-bg);
+    color: var(--kj-carousel-control-fg);
+    cursor: pointer;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    font: 1rem var(--kj-font-sans);
+    transition: var(--kj-transition);
+  }
+  .kj-carousel-control:hover { background: var(--kj-bg-surface); }
+  .kj-carousel-control:focus-visible {
+    outline: 2px solid var(--kj-border-focus);
+    outline-offset: 2px;
+  }
+  .kj-carousel-control[aria-disabled="true"] {
+    opacity: 0.4;
+    cursor: not-allowed;
+  }
+
+  .kj-carousel-previous { grid-column: 1; }
+  .kj-carousel-next     { grid-column: 3; }
+
+  .kj-carousel[data-orientation="vertical"] .kj-carousel-previous { grid-column: 1; grid-row: 1; }
+  .kj-carousel[data-orientation="vertical"] .kj-carousel-next     { grid-column: 1; grid-row: 3; }
+
+  .kj-carousel-indicators {
+    grid-column: 2;
+    grid-row: 2;
+    display: inline-flex;
+    gap: var(--kj-space-sm);
+    align-items: center;
+    justify-content: center;
+    padding: var(--kj-space-sm) 0;
+  }
+  .kj-carousel[data-orientation="vertical"] .kj-carousel-indicators {
+    grid-column: 1;
+    grid-row: 4;
+    flex-direction: row;
+  }
+
+  .kj-carousel-indicator {
+    width:  var(--kj-carousel-indicator-size);
+    height: var(--kj-carousel-indicator-size);
+    min-width: 44px;
+    min-height: 44px;
+    padding: 0;
+    border: 0;
+    background: transparent;
+    cursor: pointer;
+    position: relative;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+  }
+  .kj-carousel-indicator::before {
+    content: '';
+    width:  var(--kj-carousel-indicator-size);
+    height: var(--kj-carousel-indicator-size);
+    border-radius: 50%;
+    background: var(--kj-carousel-indicator-idle);
+    transition: var(--kj-transition);
+  }
+  .kj-carousel-indicator[aria-current="true"]::before,
+  .kj-carousel-indicator[aria-selected="true"]::before {
+    background: var(--kj-carousel-indicator-active);
+    transform: scale(1.25);
+  }
+  .kj-carousel-indicator:focus-visible {
+    outline: 2px solid var(--kj-border-focus);
+    outline-offset: 2px;
+    border-radius: 50%;
+  }
+
+  .kj-carousel-pause {
+    grid-column: 3;
+    grid-row: 2;
+    width: var(--kj-carousel-control-size);
+    height: var(--kj-carousel-control-size);
+    border-radius: 50%;
+    border: var(--kj-border) solid var(--kj-border-default);
+    background: var(--kj-carousel-control-bg);
+    color: var(--kj-carousel-control-fg);
+    cursor: pointer;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    font: 1rem var(--kj-font-sans);
+  }
+  .kj-carousel-pause:focus-visible {
+    outline: 2px solid var(--kj-border-focus);
+    outline-offset: 2px;
+  }
+  .kj-carousel-pause[aria-pressed="true"] {
+    background: var(--kj-bg-primary);
+    color: var(--kj-fg-on-primary);
+  }
+  .kj-carousel-pause[disabled] {
+    opacity: 0.4;
+    cursor: not-allowed;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .kj-carousel-viewport { scroll-behavior: auto; }
+    .kj-carousel-indicator::before { transition: none; }
+  }
+}

package/src/carousel/carousel.playground.ts

@@ -0,0 +1,135 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import {
+  KjCarouselComponent,
+  KjCarouselIndicatorsComponent,
+  KjCarouselNextComponent,
+  KjCarouselPreviousComponent,
+  KjCarouselSlideComponent,
+  KjCarouselViewportComponent,
+} from './carousel';
+import type { PlaygroundFile } from '@kouji-ui/components/playground-types';
+
+/**
+ * Playground state — module-scope signals. Tunes the active slide, slide
+ * count, loop behaviour, orientation, and the indicator track so the
+ * navigation surface area is fully covered.
+ */
+const active = signal<'alps' | 'andes' | 'atlas' | 'rockies'>('alps');
+const slideCount = signal<3 | 4>(3);
+const loop = signal(false);
+const orientation = signal<'horizontal' | 'vertical'>('horizontal');
+const showIndicators = signal(true);
+
+const SLIDES: ReadonlyArray<{ value: string; label: string }> = [
+  { value: 'alps', label: 'The Alps' },
+  { value: 'andes', label: 'The Andes' },
+  { value: 'atlas', label: 'The Atlas' },
+  { value: 'rockies', label: 'The Rockies' },
+];
+
+@Component({
+  selector: 'kj-carousel-playground',
+  standalone: true,
+  imports: [
+    KjCarouselComponent,
+    KjCarouselViewportComponent,
+    KjCarouselSlideComponent,
+    KjCarouselPreviousComponent,
+    KjCarouselNextComponent,
+    KjCarouselIndicatorsComponent,
+  ],
+  styles: [`
+    :host { display: block; }
+    .slide { display: grid; place-items: center; min-height: 10rem; font-weight: 600; font-size: 1.125rem; }
+    /* Vertical orientation: the host carousel CSS uses
+       grid-template-rows: auto 1fr auto auto with the viewport in the
+       1fr row, so the parent needs an explicit height — otherwise 1fr
+       collapses to 0 and the viewport disappears. */
+    kj-carousel[data-orientation="vertical"] { height: 22rem; }
+    kj-carousel[data-orientation="vertical"] .slide { min-height: 8rem; }
+  `],
+  template: `
+    <kj-carousel
+      label="Featured destinations"
+      [(value)]="active"
+      [loop]="loop()"
+      [orientation]="orientation()"
+    >
+      <kj-carousel-previous aria-label="Previous slide" />
+      <kj-carousel-viewport>
+        @for (slide of visibleSlides(); track slide.value) {
+          <kj-carousel-slide [value]="slide.value" [label]="slide.label">
+            <div class="slide">{{ slide.label }}</div>
+          </kj-carousel-slide>
+        }
+      </kj-carousel-viewport>
+      <kj-carousel-next aria-label="Next slide" />
+      @if (showIndicators()) {
+        <kj-carousel-indicators />
+      }
+    </kj-carousel>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjCarouselPlaygroundDemo {
+  protected readonly active = active;
+  protected readonly slideCount = slideCount;
+  protected readonly loop = loop;
+  protected readonly orientation = orientation;
+  protected readonly showIndicators = showIndicators;
+
+  protected visibleSlides(): typeof SLIDES {
+    return SLIDES.slice(0, slideCount());
+  }
+}
+
+export const PLAYGROUND: PlaygroundFile = {
+  component: KjCarouselPlaygroundDemo,
+  state: {
+    active: active as unknown as ReturnType<typeof signal>,
+    slideCount: slideCount as unknown as ReturnType<typeof signal>,
+    loop: loop as unknown as ReturnType<typeof signal>,
+    orientation: orientation as unknown as ReturnType<typeof signal>,
+    showIndicators: showIndicators as unknown as ReturnType<typeof signal>,
+  },
+  controls: [
+    {
+      kind: 'chips',
+      name: 'active',
+      label: 'active',
+      options: ['alps', 'andes', 'atlas', 'rockies'],
+    },
+    { kind: 'chips', name: 'slideCount', label: 'slides', options: [3, 4] },
+    {
+      kind: 'chips',
+      name: 'orientation',
+      label: 'orientation',
+      options: ['horizontal', 'vertical'],
+    },
+    { kind: 'toggle', name: 'loop', label: 'loop' },
+    { kind: 'toggle', name: 'showIndicators', label: 'indicators' },
+  ],
+  snippet: (values) => {
+    const s = values as {
+      active: string;
+      slideCount: number;
+      loop: boolean;
+      orientation: string;
+      showIndicators: boolean;
+    };
+    const attrs: string[] = [
+      'label="Featured destinations"',
+      `value="${s.active}"`,
+      `orientation="${s.orientation}"`,
+    ];
+    if (s.loop) attrs.push('[loop]="true"');
+    const slides = SLIDES.slice(0, s.slideCount)
+      .map(
+        (slide) =>
+          `    <kj-carousel-slide value="${slide.value}" label="${slide.label}">\n      <div class="slide">${slide.label}</div>\n    </kj-carousel-slide>`,
+      )
+      .join('\n');
+    const indicators = s.showIndicators ? '\n  <kj-carousel-indicators />' : '';
+    return `<kj-carousel\n  ${attrs.join('\n  ')}\n>\n  <kj-carousel-previous aria-label="Previous slide" />\n  <kj-carousel-viewport>\n${slides}\n  </kj-carousel-viewport>\n  <kj-carousel-next aria-label="Next slide" />${indicators}\n</kj-carousel>`;
+  },
+};

package/src/carousel/carousel.spec.ts

@@ -0,0 +1,211 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { describe, expect, test, beforeEach } from 'vitest';
+import {
+  KjCarouselComponent,
+  KjCarouselViewportComponent,
+  KjCarouselSlideComponent,
+  KjCarouselPreviousComponent,
+  KjCarouselNextComponent,
+  KjCarouselIndicatorsComponent,
+  KjCarouselAutoplayComponent,
+  KjCarouselPauseComponent,
+} from './carousel';
+
+const imports = [
+  KjCarouselComponent,
+  KjCarouselViewportComponent,
+  KjCarouselSlideComponent,
+  KjCarouselPreviousComponent,
+  KjCarouselNextComponent,
+  KjCarouselIndicatorsComponent,
+  KjCarouselAutoplayComponent,
+  KjCarouselPauseComponent,
+];
+
+@Component({
+  standalone: true,
+  imports,
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-carousel [(value)]="active" [label]="label" [loop]="loop" [orientation]="orientation">
+      <kj-carousel-previous aria-label="Previous slide" />
+      <kj-carousel-viewport>
+        <kj-carousel-slide value="one" label="One"
+          ><div data-testid="content-one">One body</div></kj-carousel-slide
+        >
+        <kj-carousel-slide value="two" label="Two"
+          ><div data-testid="content-two">Two body</div></kj-carousel-slide
+        >
+        <kj-carousel-slide value="three" label="Three"
+          ><div data-testid="content-three">Three body</div></kj-carousel-slide
+        >
+      </kj-carousel-viewport>
+      <kj-carousel-next aria-label="Next slide" />
+      <kj-carousel-indicators ariaLabel="Slide controls" [controlPattern]="controlPattern" />
+    </kj-carousel>
+  `,
+})
+class HostComponent {
+  active = signal<string | null>(null);
+  label = 'Test wrapper';
+  loop = false;
+  orientation: 'horizontal' | 'vertical' = 'horizontal';
+  controlPattern: 'buttons' | 'tabs' = 'buttons';
+}
+
+@Component({
+  standalone: true,
+  imports,
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-carousel label="Auto">
+      <kj-carousel-autoplay [delay]="5000" />
+      <kj-carousel-viewport>
+        <kj-carousel-slide value="x">X</kj-carousel-slide>
+        <kj-carousel-slide value="y">Y</kj-carousel-slide>
+      </kj-carousel-viewport>
+      <kj-carousel-pause aria-label="Pause" />
+    </kj-carousel>
+  `,
+})
+class AutoplayHost {}
+
+async function flush() {
+  await Promise.resolve();
+  await Promise.resolve();
+  await new Promise<void>((r) => setTimeout(r, 0));
+}
+
+describe('KjCarouselComponent (wrapper)', () => {
+  beforeEach(() => {
+    TestBed.configureTestingModule({ imports: [HostComponent, AutoplayHost] });
+  });
+
+  test('renders the wrapper composition with correct ARIA shape', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const root: HTMLElement = fixture.nativeElement;
+
+    const carousel = root.querySelector('kj-carousel')!;
+    expect(carousel.getAttribute('role')).toBe('region');
+    expect(carousel.getAttribute('aria-roledescription')).toBe('carousel');
+    expect(carousel.getAttribute('aria-label')).toBe('Test wrapper');
+
+    const slides = root.querySelectorAll('kj-carousel-slide');
+    expect(slides.length).toBe(3);
+    slides.forEach((slide) => {
+      expect(slide.getAttribute('role')).toBe('group');
+      expect(slide.getAttribute('aria-roledescription')).toBe('slide');
+    });
+
+    const prev = root.querySelector('button.kj-carousel-previous')!;
+    const next = root.querySelector('button.kj-carousel-next')!;
+    expect(prev.getAttribute('aria-label')).toBe('Previous slide');
+    expect(next.getAttribute('aria-label')).toBe('Next slide');
+  });
+
+  test('aliased value model is two-way bound from the host signal', async () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    await flush();
+    fixture.detectChanges();
+
+    // Default reconciliation lands the first slide.
+    expect(fixture.componentInstance.active()).toBe('one');
+
+    fixture.componentInstance.active.set('two');
+    fixture.detectChanges();
+
+    const slides = fixture.nativeElement.querySelectorAll<HTMLElement>('kj-carousel-slide');
+    expect(slides[1].getAttribute('data-active')).toBe('');
+    expect(slides[0].getAttribute('data-active')).toBeNull();
+  });
+
+  test('auto-projects a dot indicator per slide with aria-current on the active', async () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    await flush();
+    fixture.detectChanges();
+
+    const dots = fixture.nativeElement.querySelectorAll<HTMLButtonElement>(
+      'button.kj-carousel-indicator',
+    );
+    expect(dots.length).toBe(3);
+    expect(dots[0].getAttribute('aria-current')).toBe('true');
+    expect(dots[1].getAttribute('aria-current')).toBeNull();
+
+    dots[2].click();
+    fixture.detectChanges();
+    expect(fixture.componentInstance.active()).toBe('three');
+    expect(dots[2].getAttribute('aria-current')).toBe('true');
+    expect(dots[0].getAttribute('aria-current')).toBeNull();
+  });
+
+  test('controlPattern="tabs" flips the indicator group to a tablist with role="tab"', async () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.controlPattern = 'tabs';
+    fixture.detectChanges();
+    await flush();
+    fixture.detectChanges();
+
+    const indicators = fixture.nativeElement.querySelector('kj-carousel-indicators')!;
+    expect(indicators.getAttribute('role')).toBe('tablist');
+    const dots = fixture.nativeElement.querySelectorAll<HTMLButtonElement>(
+      'button.kj-carousel-indicator',
+    );
+    dots.forEach((d) => expect(d.getAttribute('role')).toBe('tab'));
+    expect(dots[0].getAttribute('aria-selected')).toBe('true');
+    expect(dots[1].getAttribute('aria-selected')).toBe('false');
+  });
+
+  test('next button advances the model and is disabled at the boundary when not looping', async () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    await flush();
+    fixture.detectChanges();
+
+    const next: HTMLButtonElement = fixture.nativeElement.querySelector('button.kj-carousel-next');
+    next.click();
+    fixture.detectChanges();
+    expect(fixture.componentInstance.active()).toBe('two');
+    next.click();
+    fixture.detectChanges();
+    expect(fixture.componentInstance.active()).toBe('three');
+    expect(next.getAttribute('aria-disabled')).toBe('true');
+  });
+
+  test('vertical orientation propagates to the wrapper host', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.orientation = 'vertical';
+    fixture.detectChanges();
+    const carousel = fixture.nativeElement.querySelector('kj-carousel')!;
+    expect(carousel.getAttribute('aria-orientation')).toBe('vertical');
+    expect(carousel.getAttribute('data-orientation')).toBe('vertical');
+  });
+
+  test('autoplay pause toggle reflects paused state via aria-pressed', async () => {
+    const fixture = TestBed.createComponent(AutoplayHost);
+    fixture.detectChanges();
+    await flush();
+
+    const pause: HTMLButtonElement = fixture.nativeElement.querySelector(
+      'button.kj-carousel-pause',
+    );
+    expect(pause.getAttribute('aria-pressed')).toBe('false');
+    pause.click();
+    fixture.detectChanges();
+    expect(pause.getAttribute('aria-pressed')).toBe('true');
+  });
+
+  test('live region is rendered as a visually-hidden element with aria-live="polite"', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const region = fixture.nativeElement.querySelector('[aria-live]') as HTMLElement;
+    expect(region).not.toBeNull();
+    expect(region.getAttribute('aria-live')).toBe('polite');
+    expect(region.getAttribute('aria-atomic')).toBe('true');
+    // Visually hidden styles are inline (browsers / jsdom may add spaces; match liberally).
+    expect(region.getAttribute('style')).toMatch(/width:\s*1px/);
+  });
+});