@kouji-ui/components 0.1.1

package/src/carousel/carousel.ts

@@ -0,0 +1,399 @@
+import {
+  AfterViewInit,
+  ChangeDetectionStrategy,
+  Component,
+  ViewEncapsulation,
+  computed,
+  contentChildren,
+  inject,
+  input,
+  ViewChild,
+} from '@angular/core';
+import {
+  KJ_CAROUSEL,
+  KjCarousel,
+  KjCarouselAutoplay,
+  KjCarouselIndicator,
+  KjCarouselIndicators,
+  KjCarouselNext,
+  KjCarouselPauseToggle,
+  KjCarouselPrevious,
+  KjCarouselSlide,
+  KjCarouselViewport,
+  KjIconDirective,
+  KjLiveRegion,
+  KjVisuallyHidden,
+} from '@kouji-ui/core';
+import type {
+  KjCarouselAlign,
+  KjCarouselControlPattern,
+  KjCarouselOrientation,
+} from '@kouji-ui/core';
+
+/**
+ * Styled wrapper around the headless `KjCarousel` directive — the rotating
+ * region with previous / next controls, optional dot indicators, and an
+ * opt-in autoplay attached behaviour.
+ *
+ * Compose the wrappers — `<kj-carousel>`, `<kj-carousel-viewport>`,
+ * `<kj-carousel-slide>`, `<kj-carousel-previous>`, `<kj-carousel-next>`,
+ * `<kj-carousel-indicators>`, `<kj-carousel-pause>`, `<kj-carousel-autoplay>` —
+ * to mirror the directive family. The active slide is keyed by `value`,
+ * not by structural position, so consumers can two-way bind to a router
+ * param or analytics key.
+ *
+ * The wrapper also renders a visually hidden `kjLiveRegion` inside its
+ * template so user-initiated slide changes are announced politely without
+ * the consumer having to wire a live region of their own.
+ *
+ * @example
+ * ```html
+ * <kj-carousel [(value)]="active" label="Featured products">
+ *   <kj-carousel-previous aria-label="Previous slide">‹</kj-carousel-previous>
+ *   <kj-carousel-viewport>
+ *     <kj-carousel-slide value="a" label="Mountain meadow">
+ *       <article>…</article>
+ *     </kj-carousel-slide>
+ *   </kj-carousel-viewport>
+ *   <kj-carousel-next aria-label="Next slide">›</kj-carousel-next>
+ *   <kj-carousel-indicators />
+ * </kj-carousel>
+ * ```
+ *
+ * @doc-example Default
+ *   The default playground — four slides with manual prev / next controls.
+ *   @doc-file carousel.example.ts
+ * @doc-example Usage
+ *   The common shape — bound active slide, prev / next, and indicator dots.
+ *   Use this as the copy-paste starting point.
+ *   @doc-file carousel.usage.example.ts
+ * @doc-example With indicators
+ *   Add `<kj-carousel-indicators>` to expose a dot list under the viewport.
+ *   @doc-file carousel.indicators.example.ts
+ * @doc-example Autoplay with pause control
+ *   Pair `<kj-carousel-autoplay>` with `<kj-carousel-pause>` whenever delay > 5s (WCAG 2.2.2).
+ *   @doc-file carousel.autoplay.example.ts
+ * @doc-example Tabbed carousel
+ *   `kjControlPattern="tabs"` switches indicators to a tablist for editorial decks.
+ *   @doc-file carousel.tabs-pattern.example.ts
+ * @doc-example Lazy-loaded images
+ *   Render heavy media on-demand using the slide's visibility signal.
+ *   @doc-file carousel.lazy-load.example.ts
+ *
+ * @doc-keyboard
+ *   Tab           — Moves focus through prev / next / pause / indicators in DOM order
+ *   Enter|Space   — Activates the focused control
+ *   ArrowLeft|ArrowRight — On indicator tablist mode, moves between tabs (auto-activates the slide)
+ *
+ * @doc-aria
+ *   role               — `region` on the host; `aria-roledescription="carousel"`
+ *   aria-label         — Required; supply via `label` or `labelledby`
+ *   aria-live          — Politely announces slide changes via the wrapper's hidden live region
+ *   aria-current       — `"true"` on the active indicator
+ *   aria-controls      — Prev / next reference the viewport id
+ *
+ * @doc-touch
+ *   Prev / next / pause buttons default to a ≥ 44×44 control diameter
+ *   (`--kj-carousel-control-size`). Indicators are smaller dots — if they're
+ *   the primary nav on mobile, switch to `kjControlPattern="tabs"` for larger
+ *   targets.
+ *
+ * @doc-a11y
+ *   Follows the WAI-ARIA APG Carousel pattern. Autoplay > 5s requires a
+ *   pause control (WCAG 2.2.2 Pause, Stop, Hide) — pair `kj-carousel-autoplay`
+ *   with `kj-carousel-pause` whenever it's present. The wrapper's internal
+ *   `kjLiveRegion` announces user-initiated slide changes politely.
+ *
+ * @doc-related tabs,accordion,list
+ *
+ * @doc-css-var
+ *   --kj-carousel-gap                 — Gap between viewport and controls + between slides.
+ *   --kj-carousel-radius              — Corner radius for viewport and slides. Inherits --kj-radius-box.
+ *   --kj-carousel-control-size        — Diameter of prev/next/pause buttons. Defaults to 44px for WCAG touch.
+ *   --kj-carousel-control-bg          — Background of prev/next/pause buttons.
+ *   --kj-carousel-control-fg          — Foreground (icon) color of prev/next/pause buttons.
+ *   --kj-carousel-indicator-size      — Diameter of the indicator dots.
+ *   --kj-carousel-indicator-active    — Fill color of the active indicator dot.
+ *   --kj-carousel-indicator-idle      — Fill color of idle indicator dots.
+ *   --kj-carousel-slides-per-view     — Number of slides visible at once. Defaults to 1.
+ *
+ * @doc-category Library/Data display
+ * @doc
+ * @doc-name carousel
+ * @doc-description Themed rotating content region with prev/next controls, indicators, autoplay, and accessible announcements.
+ * @doc-is-main
+ */
+@Component({
+  selector: 'kj-carousel',
+  standalone: true,
+  imports: [KjLiveRegion, KjVisuallyHidden],
+  hostDirectives: [
+    {
+      directive: KjCarousel,
+      inputs: [
+        'kjValue: value',
+        'kjLoop: loop',
+        'kjOrientation: orientation',
+        'kjSlidesPerView: slidesPerView',
+        'kjSlidesPerAdvance: slidesPerAdvance',
+        'kjAlign: align',
+        'kjLabel: label',
+        'kjLabelledby: labelledby',
+        'kjDraggable: draggable',
+      ],
+      outputs: ['kjValueChange: valueChange'],
+    },
+  ],
+  template: `
+    <ng-content />
+    <div kjVisuallyHidden kjLiveRegion #liveRegion="kjLiveRegion"></div>
+  `,
+  styleUrl: './carousel.css',
+  encapsulation: ViewEncapsulation.None,
+  host: {
+    class: 'kj-carousel',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjCarouselComponent implements AfterViewInit {
+  protected readonly carousel = inject(KjCarousel);
+
+  @ViewChild('liveRegion', { static: true }) protected liveRegion!: KjLiveRegion;
+
+  ngAfterViewInit(): void {
+    this.carousel.registerLiveRegion(this.liveRegion);
+  }
+}
+
+/**
+ * Styled wrapper around `KjCarouselViewport`. Hosts the scroll container that
+ * the slides scroll-snap into, and forwards through to the underlying
+ * directive (no public inputs).
+ *
+ * @doc-category Library/Data display
+ * @doc
+ * @doc-name carousel
+ */
+@Component({
+  selector: 'kj-carousel-viewport',
+  standalone: true,
+  hostDirectives: [KjCarouselViewport],
+  template: `<ng-content />`,
+  encapsulation: ViewEncapsulation.None,
+  host: { class: 'kj-carousel-viewport' },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjCarouselViewportComponent {}
+
+/**
+ * Styled wrapper around `KjCarouselSlide`. Project a single slide; the
+ * directive's `aria-label="N of M[: label]"` is computed from its index in
+ * registration order plus the optional `[label]` shorthand.
+ *
+ * @doc-category Library/Data display
+ * @doc
+ * @doc-name carousel
+ */
+@Component({
+  selector: 'kj-carousel-slide',
+  standalone: true,
+  hostDirectives: [
+    {
+      directive: KjCarouselSlide,
+      inputs: ['kjSlideValue: value', 'kjSlideLabel: label', 'kjSlideAlign: align'],
+    },
+  ],
+  template: `<ng-content />`,
+  encapsulation: ViewEncapsulation.None,
+  host: {
+    class: 'kj-carousel-slide',
+    '[attr.data-align]': 'effectiveAlign()',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjCarouselSlideComponent {
+  protected readonly slide = inject(KjCarouselSlide);
+  protected readonly effectiveAlign = computed(() => this.slide.effectiveAlign());
+}
+
+/**
+ * Styled wrapper around `KjCarouselPrevious`. Renders a real `<button>` so
+ * Enter / Space activation, focus, and disabled semantics work for free; the
+ * `aria-label` input is required at runtime (dev-mode warn if omitted).
+ *
+ * @doc-category Library/Data display
+ * @doc
+ * @doc-name carousel
+ */
+@Component({
+  selector: 'kj-carousel-previous',
+  standalone: true,
+  imports: [KjCarouselPrevious],
+  template: `
+    <button
+      type="button"
+      kjCarouselPrevious
+      class="kj-carousel-control kj-carousel-previous"
+      [attr.aria-label]="ariaLabel()"
+    >
+      <ng-content>‹</ng-content>
+    </button>
+  `,
+  encapsulation: ViewEncapsulation.None,
+  host: { style: 'display: contents;' },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjCarouselPreviousComponent {
+  /** Accessible name for the control. Required by WCAG 4.1.2 — defaults to `"Previous slide"`. */
+  readonly ariaLabel = input<string>('Previous slide', { alias: 'aria-label' });
+}
+
+/**
+ * Styled wrapper around `KjCarouselNext`. Symmetric counterpart of
+ * `KjCarouselPreviousComponent`.
+ *
+ * @doc-category Library/Data display
+ * @doc
+ * @doc-name carousel
+ */
+@Component({
+  selector: 'kj-carousel-next',
+  standalone: true,
+  imports: [KjCarouselNext, KjIconDirective],
+  template: `
+    <button
+      type="button"
+      kjCarouselNext
+      class="kj-carousel-control kj-carousel-next"
+      [attr.aria-label]="ariaLabel()"
+    >
+      <ng-content><i kjIcon="chevron-right"></i></ng-content>
+    </button>
+  `,
+  encapsulation: ViewEncapsulation.None,
+  host: { style: 'display: contents;' },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjCarouselNextComponent {
+  /** Accessible name for the control. Required by WCAG 4.1.2 — defaults to `"Next slide"`. */
+  readonly ariaLabel = input<string>('Next slide', { alias: 'aria-label' });
+}
+
+/**
+ * Styled wrapper around `KjCarouselIndicators`. Auto-projects one
+ * `<button kjCarouselIndicator>` per registered slide (dot list) when no
+ * `<kj-carousel-indicator>` children are projected, otherwise leaves the
+ * projected children alone — letting consumers swap dots for thumbnails or
+ * numbered chips.
+ *
+ * @doc-category Library/Data display
+ * @doc
+ * @doc-name carousel
+ */
+@Component({
+  selector: 'kj-carousel-indicators',
+  standalone: true,
+  imports: [KjCarouselIndicator],
+  hostDirectives: [
+    {
+      directive: KjCarouselIndicators,
+      inputs: ['kjControlPattern: controlPattern', 'kjAriaLabel: ariaLabel'],
+    },
+  ],
+  template: `
+    <ng-content />
+    @if (autoProject()) {
+      @for (slide of carousel.slides(); track slide.kjSlideValue()) {
+        <button
+          type="button"
+          kjCarouselIndicator
+          class="kj-carousel-indicator"
+          [kjForValue]="slide.kjSlideValue()"
+          [attr.aria-label]="'Slide ' + ($index + 1)"
+          [attr.data-kj-indicator-value]="slide.kjSlideValue()"
+        ></button>
+      }
+    }
+  `,
+  encapsulation: ViewEncapsulation.None,
+  host: { class: 'kj-carousel-indicators' },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjCarouselIndicatorsComponent {
+  protected readonly carousel = inject(KJ_CAROUSEL) as KjCarousel;
+  private readonly projectedIndicators = contentChildren(KjCarouselIndicator);
+
+  /** Whether to render the auto-projected dot list (true when no indicator is projected). */
+  protected readonly autoProject = computed(() => this.projectedIndicators().length === 0);
+}
+
+/**
+ * Styled wrapper around `KjCarouselAutoplay`. Lifecycle-only directive — has
+ * no visible DOM. Drop next to the carousel content to attach the autoplay
+ * behaviour; pair with `<kj-carousel-pause>` whenever the delay exceeds
+ * 5000 ms (WCAG 2.2.2).
+ *
+ * @doc-category Library/Data display
+ * @doc
+ * @doc-name carousel
+ */
+@Component({
+  selector: 'kj-carousel-autoplay',
+  standalone: true,
+  hostDirectives: [
+    {
+      directive: KjCarouselAutoplay,
+      inputs: [
+        'kjAutoplayDelay: delay',
+        'kjPauseOnHover: pauseOnHover',
+        'kjPauseOnFocus: pauseOnFocus',
+      ],
+    },
+  ],
+  template: ``,
+  encapsulation: ViewEncapsulation.None,
+  host: { style: 'display: none;' },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjCarouselAutoplayComponent {}
+
+/**
+ * Styled wrapper around `KjCarouselPauseToggle`. Renders a real `<button>`
+ * with `aria-pressed` reflecting the carousel's `paused` signal. Required
+ * whenever an autoplay directive is present and its delay > 5000 ms.
+ *
+ * @doc-category Library/Data display
+ * @doc
+ * @doc-name carousel
+ */
+@Component({
+  selector: 'kj-carousel-pause',
+  standalone: true,
+  imports: [KjCarouselPauseToggle],
+  template: `
+    <button
+      type="button"
+      kjCarouselPauseToggle
+      class="kj-carousel-pause"
+      [attr.aria-label]="ariaLabel()"
+    >
+      <ng-content>{{ paused() ? '▶' : '❚❚' }}</ng-content>
+    </button>
+  `,
+  encapsulation: ViewEncapsulation.None,
+  host: { style: 'display: contents;' },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjCarouselPauseComponent {
+  protected readonly carousel = inject(KJ_CAROUSEL) as KjCarousel;
+  /** Accessible name for the toggle. Required by WCAG 4.1.2 — defaults to `"Pause carousel"`. */
+  readonly ariaLabel = input<string>('Pause carousel', { alias: 'aria-label' });
+  protected readonly paused = computed(() => this.carousel.paused());
+}
+
+// Re-export the input types for consumer convenience.
+export type {
+  KjCarouselOrientation,
+  KjCarouselAlign,
+  KjCarouselControlPattern,
+};

package/src/carousel/carousel.usage.example.ts

@@ -0,0 +1,46 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import {
+  KjCarouselComponent,
+  KjCarouselIndicatorsComponent,
+  KjCarouselNextComponent,
+  KjCarouselPreviousComponent,
+  KjCarouselSlideComponent,
+  KjCarouselViewportComponent,
+} from './carousel';
+
+/**
+ * Common carousel shape — bound active slide, prev / next controls, and a
+ * dot indicator row. Use this as the copy-paste starting point.
+ */
+@Component({
+  selector: 'kj-carousel-usage-example',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [
+    KjCarouselComponent,
+    KjCarouselViewportComponent,
+    KjCarouselSlideComponent,
+    KjCarouselPreviousComponent,
+    KjCarouselNextComponent,
+    KjCarouselIndicatorsComponent,
+  ],
+  styles: [`
+    :host { display: block; }
+    .slide { display: grid; place-items: center; min-height: 10rem; font-weight: 600; }
+  `],
+  template: `
+    <kj-carousel [(value)]="active" label="Featured posts">
+      <kj-carousel-previous aria-label="Previous slide" />
+      <kj-carousel-viewport>
+        <kj-carousel-slide value="a" label="Token system"><div class="slide">Token system</div></kj-carousel-slide>
+        <kj-carousel-slide value="b" label="Theming"><div class="slide">Theming</div></kj-carousel-slide>
+        <kj-carousel-slide value="c" label="A11y first"><div class="slide">A11y first</div></kj-carousel-slide>
+      </kj-carousel-viewport>
+      <kj-carousel-next aria-label="Next slide" />
+      <kj-carousel-indicators />
+    </kj-carousel>
+  `,
+})
+export class KjCarouselUsageExample {
+  readonly active = signal('a');
+}

package/src/carousel/index.ts

@@ -0,0 +1 @@
+export * from './carousel';

package/src/cascade-select/_examples/cascade-select.data-driven.example.ts

@@ -0,0 +1,119 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import {
+  KjCascadeSelectComponent,
+  KjCascadeOptionComponent,
+  KjCascadeSubPanelComponent,
+} from '../cascade-select';
+import type { KjCascadeNode } from '@kouji-ui/core';
+
+interface GeoNode extends KjCascadeNode<string> {
+  readonly value: string;
+  readonly label: string;
+  readonly children?: readonly GeoNode[];
+}
+
+const REGIONS: readonly GeoNode[] = [
+  {
+    value: 'na',
+    label: 'North America',
+    children: [
+      {
+        value: 'us',
+        label: 'United States',
+        children: [
+          { value: 'sf', label: 'San Francisco' },
+          { value: 'la', label: 'Los Angeles' },
+          { value: 'chi', label: 'Chicago' },
+          { value: 'nyc', label: 'New York City' },
+        ],
+      },
+      {
+        value: 'ca',
+        label: 'Canada',
+        children: [
+          { value: 'tor', label: 'Toronto' },
+          { value: 'van', label: 'Vancouver' },
+        ],
+      },
+    ],
+  },
+  {
+    value: 'eu',
+    label: 'Europe',
+    children: [
+      {
+        value: 'de',
+        label: 'Germany',
+        children: [
+          { value: 'ber', label: 'Berlin' },
+          { value: 'mun', label: 'Munich' },
+        ],
+      },
+      {
+        value: 'fr',
+        label: 'France',
+        children: [
+          { value: 'par', label: 'Paris' },
+          { value: 'lyo', label: 'Lyon' },
+        ],
+      },
+    ],
+  },
+  {
+    value: 'as',
+    label: 'Asia',
+    children: [
+      { value: 'tok', label: 'Tokyo' },
+      { value: 'bei', label: 'Beijing' },
+      { value: 'sin', label: 'Singapore' },
+    ],
+  },
+];
+
+/**
+ * Data-driven cascade-select example. Hierarchy is built from a data array
+ * rather than inline markup. Each node drives `<kj-cascade-option>`
+ * bindings including nested sub-panels.
+ */
+@Component({
+  selector: 'kj-cascade-select-data-driven-example',
+  standalone: true,
+  imports: [KjCascadeSelectComponent, KjCascadeOptionComponent, KjCascadeSubPanelComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-cascade-select [(kjValue)]="selected" placeholder="Select a location">
+      @for (region of regions; track region.value) {
+        <kj-cascade-option [kjValue]="region.value" [kjLabel]="region.label">
+          <kj-cascade-sub-panel [kjOwnerOptionId]="region.value">
+            @for (country of region.children; track country.value) {
+              <kj-cascade-option [kjValue]="country.value" [kjLabel]="country.label">
+                @if (country.children?.length) {
+                  <kj-cascade-sub-panel [kjOwnerOptionId]="country.value">
+                    @for (city of country.children; track city.value) {
+                      <kj-cascade-option [kjValue]="city.value" [kjLabel]="city.label" />
+                    }
+                  </kj-cascade-sub-panel>
+                }
+              </kj-cascade-option>
+            }
+          </kj-cascade-sub-panel>
+        </kj-cascade-option>
+      }
+    </kj-cascade-select>
+
+    <p style="margin-top: 1rem; font-size: 0.875rem; color: var(--kj-fg-default);">
+      Selected: <strong>{{ selected() ?? '—' }}</strong>
+    </p>
+  `,
+})
+export class KjCascadeSelectDataDrivenExample {
+  readonly regions = REGIONS;
+  readonly selected = signal<string | undefined>(undefined);
+}

package/src/cascade-select/_examples/cascade-select.disabled.example.ts

@@ -0,0 +1,74 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import {
+  KjCascadeSelectComponent,
+  KjCascadeOptionComponent,
+  KjCascadeSubPanelComponent,
+} from '../cascade-select';
+
+/**
+ * Demonstrates per-option `kjDisabled` and a whole-cascade `[disabled]` state.
+ * Disabled options are visible but non-interactive (ARIA-disabled, not native).
+ */
+@Component({
+  selector: 'kj-cascade-select-disabled-example',
+  standalone: true,
+  imports: [KjCascadeSelectComponent, KjCascadeOptionComponent, KjCascadeSubPanelComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <div style="display: flex; flex-direction: column; gap: 1rem; max-width: 20rem;">
+      <div>
+        <p style="margin-bottom: 0.5rem; font-size: 0.875rem; font-weight: 500;">
+          Per-option disabled (Antarctica is disabled)
+        </p>
+        <kj-cascade-select [(kjValue)]="continent" placeholder="Select a continent">
+          <kj-cascade-option [kjValue]="'af'" kjLabel="Africa">
+            <kj-cascade-sub-panel kjOwnerOptionId="dis-af">
+              <kj-cascade-option [kjValue]="'eg'" kjLabel="Egypt" />
+              <kj-cascade-option [kjValue]="'ng'" kjLabel="Nigeria" />
+            </kj-cascade-sub-panel>
+          </kj-cascade-option>
+          <kj-cascade-option [kjValue]="'eu'" kjLabel="Europe">
+            <kj-cascade-sub-panel kjOwnerOptionId="dis-eu">
+              <kj-cascade-option [kjValue]="'fr'" kjLabel="France" />
+              <kj-cascade-option [kjValue]="'de'" kjLabel="Germany" />
+            </kj-cascade-sub-panel>
+          </kj-cascade-option>
+          <kj-cascade-option [kjValue]="'an'" kjLabel="Antarctica" kjDisabled />
+        </kj-cascade-select>
+        <p style="margin-top: 0.5rem; font-size: 0.75rem;">
+          Continent: <strong>{{ continent() ?? '—' }}</strong>
+        </p>
+      </div>
+
+      <hr style="border: none; border-top: 1px solid var(--kj-border-default);" />
+
+      <div>
+        <p style="margin-bottom: 0.5rem; font-size: 0.875rem; font-weight: 500;">
+          Whole cascade disabled
+        </p>
+        <kj-cascade-select
+          [(kjValue)]="disabledValue"
+          placeholder="Disabled cascade"
+          [disabled]="true"
+        >
+          <kj-cascade-option [kjValue]="'us'" kjLabel="USA">
+            <kj-cascade-sub-panel kjOwnerOptionId="dis-all-us">
+              <kj-cascade-option [kjValue]="'sf'" kjLabel="San Francisco" />
+            </kj-cascade-sub-panel>
+          </kj-cascade-option>
+        </kj-cascade-select>
+      </div>
+    </div>
+  `,
+})
+export class KjCascadeSelectDisabledExample {
+  readonly continent = signal<string | undefined>(undefined);
+  readonly disabledValue = signal<string | undefined>(undefined);
+}