@kouji-ui/components 0.1.1

package/src/stepper/_examples/stepper.usage.example.ts

@@ -0,0 +1,73 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import {
+  KjStepperComponent,
+  KjStepComponent,
+  KjStepLabelComponent,
+  KjStepContentComponent,
+  KjStepperNextComponent,
+  KjStepperPreviousComponent,
+  KjStepperResetComponent,
+} from '../stepper';
+
+/**
+ * A walkthrough of the most common stepper usages — linear progression with
+ * completion gating, Next / Previous / Reset commands, and live readout of the
+ * active step index. Use this as the copy-paste starting point.
+ */
+@Component({
+  selector: 'kj-stepper-usage-example',
+  standalone: true,
+  imports: [
+    KjStepperComponent,
+    KjStepComponent,
+    KjStepLabelComponent,
+    KjStepContentComponent,
+    KjStepperNextComponent,
+    KjStepperPreviousComponent,
+    KjStepperResetComponent,
+  ],
+  styles: [
+    `
+      :host {
+        display: flex;
+        flex-direction: column;
+        gap: var(--kj-space-md);
+      }
+      .actions {
+        display: flex;
+        gap: var(--kj-space-sm);
+        margin-top: var(--kj-space-md);
+      }
+      .readout {
+        font: 0.875rem var(--kj-font-sans);
+        color: var(--kj-fg-muted);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <p class="readout">Active step: {{ active() + 1 }} of 3</p>
+    <kj-stepper [(kjActiveStep)]="active" [kjLinear]="true">
+      <kj-step [kjStepCompleted]="active() > 0">
+        <kj-step-label>Account</kj-step-label>
+        <kj-step-content>Pick an email and password.</kj-step-content>
+      </kj-step>
+      <kj-step [kjStepCompleted]="active() > 1">
+        <kj-step-label>Profile</kj-step-label>
+        <kj-step-content>Add your display name.</kj-step-content>
+      </kj-step>
+      <kj-step>
+        <kj-step-label>Confirm</kj-step-label>
+        <kj-step-content>Review and submit.</kj-step-content>
+      </kj-step>
+      <div class="actions">
+        <kj-stepper-previous>Back</kj-stepper-previous>
+        <kj-stepper-next>Continue</kj-stepper-next>
+        <kj-stepper-reset>Reset</kj-stepper-reset>
+      </div>
+    </kj-stepper>
+  `,
+})
+export class KjStepperUsageExample {
+  readonly active = signal(0);
+}

package/src/stepper/_examples/stepper.vertical.example.ts

@@ -0,0 +1,66 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import {
+  KjStepperComponent,
+  KjStepComponent,
+  KjStepLabelComponent,
+  KjStepContentComponent,
+  KjStepperNextComponent,
+  KjStepperPreviousComponent,
+} from '../stepper';
+
+/**
+ * Vertical stepper. ArrowUp / ArrowDown roves between headers; the layout
+ * stacks columns naturally for narrow viewports.
+ */
+@Component({
+  selector: 'kj-stepper-vertical-example',
+  standalone: true,
+  imports: [
+    KjStepperComponent,
+    KjStepComponent,
+    KjStepLabelComponent,
+    KjStepContentComponent,
+    KjStepperNextComponent,
+    KjStepperPreviousComponent,
+  ],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+      .actions {
+        display: flex;
+        gap: var(--kj-space-sm);
+        margin-top: var(--kj-space-lg);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-stepper [(kjActiveStep)]="active" kjOrientation="vertical">
+      <kj-step [kjStepCompleted]="active() > 0">
+        <kj-step-label>Address</kj-step-label>
+        <kj-step-content>Where to ship?</kj-step-content>
+      </kj-step>
+      <kj-step [kjStepCompleted]="active() > 1">
+        <kj-step-label>Shipping</kj-step-label>
+        <kj-step-content>Pick a carrier.</kj-step-content>
+      </kj-step>
+      <kj-step [kjStepCompleted]="active() > 2">
+        <kj-step-label>Payment</kj-step-label>
+        <kj-step-content>Enter card details.</kj-step-content>
+      </kj-step>
+      <kj-step>
+        <kj-step-label>Review</kj-step-label>
+        <kj-step-content>Confirm your order.</kj-step-content>
+      </kj-step>
+      <div class="actions">
+        <kj-stepper-previous>Back</kj-stepper-previous>
+        <kj-stepper-next>Next</kj-stepper-next>
+      </div>
+    </kj-stepper>
+  `,
+})
+export class KjStepperVerticalExample {
+  readonly active = signal(0);
+}

package/src/stepper/_examples/stepper.with-error.example.ts

@@ -0,0 +1,63 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import {
+  KjStepperComponent,
+  KjStepComponent,
+  KjStepLabelComponent,
+  KjStepContentComponent,
+  KjStepperNextComponent,
+  KjStepperPreviousComponent,
+} from '../stepper';
+
+/**
+ * Stepper with a step in error state. The middle step's `kjStepError` flag
+ * paints the error indicator on its header — re-entry is still permitted so
+ * the user can return and fix the issue.
+ */
+@Component({
+  selector: 'kj-stepper-with-error-example',
+  standalone: true,
+  imports: [
+    KjStepperComponent,
+    KjStepComponent,
+    KjStepLabelComponent,
+    KjStepContentComponent,
+    KjStepperNextComponent,
+    KjStepperPreviousComponent,
+  ],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+      .actions {
+        display: flex;
+        gap: var(--kj-space-sm);
+        margin-top: var(--kj-space-lg);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-stepper [(kjActiveStep)]="active">
+      <kj-step [kjStepCompleted]="true">
+        <kj-step-label>Diagnostic</kj-step-label>
+        <kj-step-content>System checks passed.</kj-step-content>
+      </kj-step>
+      <kj-step [kjStepError]="true">
+        <kj-step-label>Severity</kj-step-label>
+        <kj-step-content>Validation failed — please review the inputs.</kj-step-content>
+      </kj-step>
+      <kj-step>
+        <kj-step-label>Triage</kj-step-label>
+        <kj-step-content>Assign an owner.</kj-step-content>
+      </kj-step>
+      <div class="actions">
+        <kj-stepper-previous>Back</kj-stepper-previous>
+        <kj-stepper-next>Next</kj-stepper-next>
+      </div>
+    </kj-stepper>
+  `,
+})
+export class KjStepperWithErrorExample {
+  readonly active = signal(1);
+}

package/src/stepper/index.ts

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

package/src/stepper/stepper.css

@@ -0,0 +1,147 @@
+@layer kj.component {
+  .kj-stepper {
+    --kj-stepper-gap:           var(--kj-space-md);
+    --kj-stepper-indicator-size: 2rem;
+    --kj-stepper-bg:            var(--kj-bg-body);
+    --kj-stepper-border:        var(--kj-border-default);
+    --kj-stepper-active:        var(--kj-bg-primary);
+    --kj-stepper-active-fg:     var(--kj-fg-on-primary);
+    --kj-stepper-completed:     var(--kj-bg-success);
+    --kj-stepper-error:         var(--kj-bg-danger);
+    --kj-stepper-muted:         var(--kj-fg-muted);
+
+    display: flex;
+    flex-direction: column;
+    gap: var(--kj-space-lg);
+    list-style: none;
+    margin: 0;
+    padding: 0;
+  }
+
+  .kj-stepper[data-orientation="horizontal"] {
+    flex-direction: row;
+    flex-wrap: wrap;
+    align-items: flex-start;
+  }
+
+  .kj-step {
+    display: flex;
+    flex-direction: column;
+    gap: var(--kj-space-sm);
+    flex: 1 1 auto;
+  }
+
+  .kj-stepper[data-orientation="vertical"] .kj-step {
+    flex-direction: column;
+    align-items: stretch;
+  }
+
+  .kj-step__label {
+    appearance: none;
+    background: none;
+    border: 0;
+    padding: var(--kj-space-sm) var(--kj-space-md);
+    display: inline-flex;
+    align-items: center;
+    gap: var(--kj-space-sm);
+    color: var(--kj-stepper-muted);
+    font: 0.875rem / 1.4 var(--kj-font-sans);
+    font-weight: 600;
+    cursor: pointer;
+    border-radius: var(--kj-radius-field);
+    transition: var(--kj-transition);
+    text-align: left;
+  }
+
+  .kj-step__label::before {
+    content: counter(kj-step-counter);
+    counter-increment: kj-step-counter;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: var(--kj-stepper-indicator-size);
+    height: var(--kj-stepper-indicator-size);
+    border-radius: 50%;
+    border: var(--kj-border) solid var(--kj-stepper-border);
+    background: var(--kj-stepper-bg);
+    color: var(--kj-stepper-muted);
+    font-size: 0.75rem;
+    flex-shrink: 0;
+  }
+
+  .kj-stepper { counter-reset: kj-step-counter; }
+
+  .kj-step__label:hover { color: var(--kj-fg-default); }
+  .kj-step__label:focus-visible { outline: 2px solid var(--kj-stepper-active); outline-offset: 2px; }
+
+  .kj-step[data-active="true"] > .kj-step__label,
+  .kj-step[data-active="true"] .kj-step__label {
+    color: var(--kj-fg-default);
+  }
+  .kj-step[data-active="true"] > .kj-step__label::before,
+  .kj-step[data-active="true"] .kj-step__label::before {
+    background: var(--kj-stepper-active);
+    border-color: var(--kj-stepper-active);
+    color: var(--kj-stepper-active-fg);
+  }
+
+  .kj-step[data-completed="true"] > .kj-step__label::before,
+  .kj-step[data-completed="true"] .kj-step__label::before {
+    background: var(--kj-stepper-completed);
+    border-color: var(--kj-stepper-completed);
+    color: var(--kj-fg-on-success, #fff);
+    content: "\2713"; /* check mark */
+  }
+
+  .kj-step[data-error="true"] > .kj-step__label::before,
+  .kj-step[data-error="true"] .kj-step__label::before {
+    background: var(--kj-stepper-error);
+    border-color: var(--kj-stepper-error);
+    color: var(--kj-fg-on-danger, #fff);
+    content: "!";
+  }
+
+  .kj-step[data-disabled="true"] > .kj-step__label,
+  .kj-step[data-disabled="true"] .kj-step__label,
+  .kj-step__label[aria-disabled="true"],
+  .kj-step__label[disabled] {
+    opacity: 0.45;
+    cursor: not-allowed;
+  }
+
+  .kj-step__content {
+    display: block;
+    color: var(--kj-fg-default);
+    font: 0.875rem / 1.5 var(--kj-font-sans);
+    padding: var(--kj-space-md);
+    background: var(--kj-bg-body);
+    border: var(--kj-border) solid var(--kj-stepper-border);
+    border-radius: var(--kj-radius-box);
+  }
+  .kj-step__content[hidden] { display: none; }
+
+  .kj-stepper-action {
+    appearance: none;
+    border: var(--kj-border) solid var(--kj-stepper-border);
+    background: var(--kj-bg-body);
+    color: var(--kj-fg-default);
+    padding: var(--kj-space-sm) var(--kj-space-md);
+    border-radius: var(--kj-radius-field);
+    font: 0.875rem / 1 var(--kj-font-sans);
+    cursor: pointer;
+    transition: var(--kj-transition);
+  }
+  .kj-stepper-action:hover:not([disabled]):not([aria-disabled="true"]) {
+    border-color: var(--kj-stepper-active);
+    color: var(--kj-stepper-active);
+  }
+  .kj-stepper-action:focus-visible { outline: 2px solid var(--kj-stepper-active); outline-offset: 2px; }
+  .kj-stepper-action[disabled],
+  .kj-stepper-action[aria-disabled="true"] { opacity: 0.45; cursor: not-allowed; }
+
+  .kj-stepper-action--next {
+    background: var(--kj-stepper-active);
+    color: var(--kj-stepper-active-fg);
+    border-color: var(--kj-stepper-active);
+  }
+}

package/src/stepper/stepper.playground.ts

@@ -0,0 +1,88 @@
+import { ChangeDetectionStrategy, Component, computed, signal } from '@angular/core';
+import {
+  KjStepperComponent,
+  KjStepComponent,
+  KjStepLabelComponent,
+  KjStepContentComponent,
+} from './stepper';
+import type { PlaygroundFile } from '@kouji-ui/components/playground-types';
+
+/**
+ * Playground state — module-scope signals. Compound stepper exposes step
+ * count + active index + linear/orientation knobs.
+ */
+const stepCount = signal<2 | 3 | 4 | 5>(4);
+const active = signal<0 | 1 | 2 | 3 | 4>(2);
+const linear = signal(false);
+const orientation = signal<'horizontal' | 'vertical'>('horizontal');
+
+const STEP_LABELS = ['Account', 'Profile', 'Review', 'Confirm', 'Done'] as const;
+
+@Component({
+  selector: 'kj-stepper-playground',
+  standalone: true,
+  imports: [
+    KjStepperComponent,
+    KjStepComponent,
+    KjStepLabelComponent,
+    KjStepContentComponent,
+  ],
+  template: `
+    <kj-stepper
+      [(kjActiveStep)]="active"
+      [kjLinear]="linear()"
+      [kjOrientation]="orientation()"
+    >
+      @for (label of steps(); track label; let i = $index) {
+        <kj-step [kjStepCompleted]="active() > i">
+          <kj-step-label>{{ label }}</kj-step-label>
+          <kj-step-content>Step {{ i + 1 }} — {{ label }}.</kj-step-content>
+        </kj-step>
+      }
+    </kj-stepper>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjStepperPlaygroundDemo {
+  protected readonly active = active;
+  protected readonly linear = linear;
+  protected readonly orientation = orientation;
+  protected readonly steps = computed(() =>
+    STEP_LABELS.slice(0, stepCount()),
+  );
+}
+
+export const PLAYGROUND: PlaygroundFile = {
+  component: KjStepperPlaygroundDemo,
+  state: {
+    stepCount: stepCount as unknown as ReturnType<typeof signal>,
+    active: active as unknown as ReturnType<typeof signal>,
+    linear: linear as unknown as ReturnType<typeof signal>,
+    orientation: orientation as unknown as ReturnType<typeof signal>,
+  },
+  controls: [
+    { kind: 'chips', name: 'stepCount', label: 'steps', options: [2, 3, 4, 5] },
+    { kind: 'chips', name: 'active', label: 'active', options: [0, 1, 2, 3, 4] },
+    { kind: 'chips', name: 'orientation', label: 'orientation', options: ['horizontal', 'vertical'] },
+    { kind: 'toggle', name: 'linear', label: 'linear' },
+  ],
+  snippet: (values) => {
+    const s = values as {
+      stepCount: number;
+      active: number;
+      linear: boolean;
+      orientation: string;
+    };
+    const labels = STEP_LABELS.slice(0, s.stepCount);
+    const steps = labels
+      .map((label, i) => `  <kj-step [kjStepCompleted]="active() > ${i}">
+    <kj-step-label>${label}</kj-step-label>
+    <kj-step-content>Step ${i + 1} — ${label}.</kj-step-content>
+  </kj-step>`)
+      .join('\n');
+    const attrs: string[] = ['[(kjActiveStep)]="active"'];
+    if (s.linear) attrs.push('[kjLinear]="true"');
+    if (s.orientation !== 'horizontal') attrs.push(`kjOrientation="${s.orientation}"`);
+    return `<kj-stepper\n  ${attrs.join('\n  ')}\n>\n${steps}\n</kj-stepper>`;
+  },
+};

package/src/stepper/stepper.spec.ts

@@ -0,0 +1,200 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { describe, expect, test, beforeEach } from 'vitest';
+import {
+  KjStepperComponent,
+  KjStepComponent,
+  KjStepLabelComponent,
+  KjStepContentComponent,
+  KjStepperNextComponent,
+  KjStepperPreviousComponent,
+  KjStepperResetComponent,
+} from './stepper';
+
+@Component({
+  standalone: true,
+  imports: [
+    KjStepperComponent,
+    KjStepComponent,
+    KjStepLabelComponent,
+    KjStepContentComponent,
+    KjStepperNextComponent,
+    KjStepperPreviousComponent,
+    KjStepperResetComponent,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-stepper [(kjActiveStep)]="active" [kjLinear]="linear" [kjOrientation]="orientation">
+      <kj-step [kjStepCompleted]="step0Completed">
+        <kj-step-label>Account</kj-step-label>
+        <kj-step-content>Account body</kj-step-content>
+      </kj-step>
+      <kj-step [kjStepCompleted]="step1Completed" [kjStepOptional]="step1Optional">
+        <kj-step-label>Profile</kj-step-label>
+        <kj-step-content>Profile body</kj-step-content>
+      </kj-step>
+      <kj-step>
+        <kj-step-label>Confirm</kj-step-label>
+        <kj-step-content>Confirm body</kj-step-content>
+      </kj-step>
+      <div>
+        <kj-stepper-previous>Back</kj-stepper-previous>
+        <kj-stepper-next>Next</kj-stepper-next>
+        <kj-stepper-reset>Reset</kj-stepper-reset>
+      </div>
+    </kj-stepper>
+  `,
+})
+class HostComponent {
+  active = signal(0);
+  linear = false;
+  orientation: 'horizontal' | 'vertical' = 'horizontal';
+  step0Completed = false;
+  step1Completed = false;
+  step1Optional = false;
+}
+
+describe('KjStepperComponent', () => {
+  beforeEach(() => {
+    TestBed.configureTestingModule({ imports: [HostComponent] });
+  });
+
+  test('renders the wrapper with .kj-stepper class and a step per <kj-step>', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const root = fixture.nativeElement.querySelector('kj-stepper.kj-stepper');
+    expect(root).not.toBeNull();
+    const steps = fixture.nativeElement.querySelectorAll('kj-step');
+    expect(steps.length).toBe(3);
+  });
+
+  test('forwards kjOrientation to the directive (data-orientation host attr)', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.orientation = 'vertical';
+    fixture.detectChanges();
+    const root = fixture.nativeElement.querySelector('kj-stepper');
+    expect(root.getAttribute('data-orientation')).toBe('vertical');
+  });
+
+  test('forwards kjLinear to the directive (data-linear host attr)', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.linear = true;
+    fixture.detectChanges();
+    const root = fixture.nativeElement.querySelector('kj-stepper');
+    expect(root.getAttribute('data-linear')).toBe('true');
+  });
+
+  test('marks the active step with aria-current="step"', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const steps = fixture.nativeElement.querySelectorAll('kj-step');
+    expect(steps[0].getAttribute('aria-current')).toBe('step');
+    expect(steps[1].getAttribute('aria-current')).toBeNull();
+  });
+
+  test('two-way binding: programmatic write to kjActiveStep moves the active step', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    fixture.componentInstance.active.set(2);
+    fixture.detectChanges();
+    const steps = fixture.nativeElement.querySelectorAll('kj-step');
+    expect(steps[2].getAttribute('aria-current')).toBe('step');
+    expect(steps[2].getAttribute('data-active')).toBe('true');
+  });
+
+  test('clicking <kj-stepper-next> advances when canAdvance() is true (non-linear)', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const nextBtn = fixture.nativeElement.querySelector(
+      'kj-stepper-next button[kjStepperNext]',
+    ) as HTMLButtonElement;
+    nextBtn.click();
+    fixture.detectChanges();
+    expect(fixture.componentInstance.active()).toBe(1);
+  });
+
+  test('linear mode gates next: disabled when active step not completed', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.linear = true;
+    fixture.detectChanges();
+    const nextBtn = fixture.nativeElement.querySelector(
+      'kj-stepper-next button[kjStepperNext]',
+    ) as HTMLButtonElement;
+    expect(nextBtn.getAttribute('disabled')).toBe('');
+    expect(nextBtn.getAttribute('aria-disabled')).toBe('true');
+  });
+
+  test('linear mode advances once active step is marked completed', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.linear = true;
+    fixture.componentInstance.step0Completed = true;
+    fixture.detectChanges();
+    const nextBtn = fixture.nativeElement.querySelector(
+      'kj-stepper-next button[kjStepperNext]',
+    ) as HTMLButtonElement;
+    expect(nextBtn.getAttribute('disabled')).toBeNull();
+    nextBtn.click();
+    fixture.detectChanges();
+    expect(fixture.componentInstance.active()).toBe(1);
+  });
+
+  test('clicking <kj-stepper-previous> retreats one step', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    fixture.componentInstance.active.set(2);
+    fixture.detectChanges();
+    const prevBtn = fixture.nativeElement.querySelector(
+      'kj-stepper-previous button[kjStepperPrevious]',
+    ) as HTMLButtonElement;
+    prevBtn.click();
+    fixture.detectChanges();
+    expect(fixture.componentInstance.active()).toBe(1);
+  });
+
+  test('<kj-stepper-reset> returns to step 0 when clicked', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    fixture.componentInstance.active.set(2);
+    fixture.detectChanges();
+    const resetBtn = fixture.nativeElement.querySelector(
+      'kj-stepper-reset button[kjStepperReset]',
+    ) as HTMLButtonElement;
+    resetBtn.click();
+    fixture.detectChanges();
+    expect(fixture.componentInstance.active()).toBe(0);
+  });
+
+  test('kjStepOptional permits linear advancement without completion', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.linear = true;
+    fixture.componentInstance.step0Completed = true;
+    fixture.componentInstance.step1Optional = true;
+    fixture.detectChanges();
+    fixture.componentInstance.active.set(1);
+    fixture.detectChanges();
+    const nextBtn = fixture.nativeElement.querySelector(
+      'kj-stepper-next button[kjStepperNext]',
+    ) as HTMLButtonElement;
+    expect(nextBtn.getAttribute('disabled')).toBeNull();
+    nextBtn.click();
+    fixture.detectChanges();
+    expect(fixture.componentInstance.active()).toBe(2);
+  });
+
+  test('<kj-step-content> for inactive steps is hidden', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const contents = fixture.nativeElement.querySelectorAll('section[kjStepContent]');
+    expect(contents[0].hasAttribute('hidden')).toBe(false);
+    expect(contents[1].hasAttribute('hidden')).toBe(true);
+    expect(contents[2].hasAttribute('hidden')).toBe(true);
+  });
+
+  test('<kj-step-label> renders an inner <button kjStepLabel>', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const labels = fixture.nativeElement.querySelectorAll('kj-step-label button[kjStepLabel]');
+    expect(labels.length).toBe(3);
+    expect(labels[0].textContent.trim()).toBe('Account');
+  });
+});