@semantic-components/ui-lab 0.62.0 → 0.63.0

package/src/lib/components/stepper/README.md

@@ -0,0 +1,250 @@
+# Stepper
+
+A multi-step wizard component for guiding users through a process.
+
+## Usage
+
+```html
+<div sc-stepper [(activeStep)]="currentStep">
+  <div sc-stepper-list>
+    <div sc-stepper-item [step]="0">
+      <button sc-stepper-trigger></button>
+      <span sc-stepper-title>Step 1</span>
+    </div>
+    <div sc-stepper-separator></div>
+    <div sc-stepper-item [step]="1">
+      <button sc-stepper-trigger></button>
+      <span sc-stepper-title>Step 2</span>
+    </div>
+  </div>
+
+  <div sc-stepper-content [step]="0">Step 1 content</div>
+  <div sc-stepper-content [step]="1">Step 2 content</div>
+
+  <button sc-stepper-previous>Previous</button>
+  <button sc-stepper-next>Next</button>
+</div>
+```
+
+## Components
+
+### ScStepper
+
+Root container that manages step state.
+
+**Selector:** `[sc-stepper]`
+
+**Inputs:**
+
+| Input         | Type                         | Default        | Description            |
+| ------------- | ---------------------------- | -------------- | ---------------------- |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout orientation     |
+| `class`       | `string`                     | `''`           | Additional CSS classes |
+
+**Two-way Bindings:**
+
+| Binding      | Type     | Default | Description         |
+| ------------ | -------- | ------- | ------------------- |
+| `activeStep` | `number` | `0`     | Current active step |
+
+**Methods:**
+
+| Method                   | Description                 |
+| ------------------------ | --------------------------- |
+| `goToStep(step: number)` | Navigate to a specific step |
+| `nextStep()`             | Go to next step             |
+| `prevStep()`             | Go to previous step         |
+| `isStepComplete(step)`   | Check if step is complete   |
+| `isStepActive(step)`     | Check if step is active     |
+
+### ScStepperList
+
+Container for step indicators.
+
+**Selector:** `[sc-stepper-list]`
+
+### ScStepperItem
+
+Individual step indicator.
+
+**Selector:** `[sc-stepper-item]`
+
+**Inputs:**
+
+| Input   | Type     | Required | Description          |
+| ------- | -------- | -------- | -------------------- |
+| `step`  | `number` | Yes      | Step index (0-based) |
+| `class` | `string` | No       | Additional CSS       |
+
+**Data Attributes:**
+
+| Attribute    | Values                                 |
+| ------------ | -------------------------------------- |
+| `data-state` | `'complete' \| 'active' \| 'inactive'` |
+
+### ScStepperTrigger
+
+Clickable step button with number or check icon.
+
+**Selector:** `button[sc-stepper-trigger]`
+
+### ScStepperSeparator
+
+Visual line between steps.
+
+**Selector:** `[sc-stepper-separator]`
+
+**Data Attributes:**
+
+| Attribute    | Values                     |
+| ------------ | -------------------------- |
+| `data-state` | `'complete' \| 'inactive'` |
+
+### ScStepperContent
+
+Content panel for a step.
+
+**Selector:** `[sc-stepper-content]`
+
+**Inputs:**
+
+| Input   | Type     | Required | Description          |
+| ------- | -------- | -------- | -------------------- |
+| `step`  | `number` | Yes      | Step index (0-based) |
+| `class` | `string` | No       | Additional CSS       |
+
+### ScStepperTitle
+
+Title text for a step.
+
+**Selector:** `[sc-stepper-title]`
+
+### ScStepperDescription
+
+Description text for a step.
+
+**Selector:** `[sc-stepper-description]`
+
+### ScStepperPrevious
+
+Button to go to previous step.
+
+**Selector:** `button[sc-stepper-previous]`
+
+Auto-disables on first step.
+
+### ScStepperNext
+
+Button to go to next step.
+
+**Selector:** `button[sc-stepper-next]`
+
+## Examples
+
+### Horizontal Stepper
+
+```html
+<div sc-stepper [(activeStep)]="step">
+  <div sc-stepper-list>
+    <div sc-stepper-item [step]="0">
+      <button sc-stepper-trigger></button>
+      <div class="flex flex-col">
+        <span sc-stepper-title>Account</span>
+        <span sc-stepper-description>Create your account</span>
+      </div>
+    </div>
+    <div sc-stepper-separator></div>
+    <div sc-stepper-item [step]="1">
+      <button sc-stepper-trigger></button>
+      <div class="flex flex-col">
+        <span sc-stepper-title>Profile</span>
+        <span sc-stepper-description>Set up your profile</span>
+      </div>
+    </div>
+    <div sc-stepper-separator></div>
+    <div sc-stepper-item [step]="2">
+      <button sc-stepper-trigger></button>
+      <div class="flex flex-col">
+        <span sc-stepper-title>Complete</span>
+        <span sc-stepper-description>Review and submit</span>
+      </div>
+    </div>
+  </div>
+
+  <div sc-stepper-content [step]="0">Account form...</div>
+  <div sc-stepper-content [step]="1">Profile form...</div>
+  <div sc-stepper-content [step]="2">Review...</div>
+
+  <div class="flex justify-between">
+    <button sc-stepper-previous>Previous</button>
+    <button sc-stepper-next>Next</button>
+  </div>
+</div>
+```
+
+### Vertical Stepper
+
+```html
+<div sc-stepper orientation="vertical" [(activeStep)]="step">
+  <div sc-stepper-list>
+    <div sc-stepper-item [step]="0">
+      <button sc-stepper-trigger></button>
+      <div class="flex flex-col">
+        <span sc-stepper-title>Step 1</span>
+        <span sc-stepper-description>First step</span>
+        @if (step === 0) {
+        <div class="mt-4">Step 1 content here</div>
+        }
+      </div>
+      <div sc-stepper-separator></div>
+    </div>
+    <div sc-stepper-item [step]="1">
+      <button sc-stepper-trigger></button>
+      <div class="flex flex-col">
+        <span sc-stepper-title>Step 2</span>
+        <span sc-stepper-description>Second step</span>
+      </div>
+    </div>
+  </div>
+</div>
+```
+
+### Simple Number Steps
+
+```html
+<div sc-stepper [(activeStep)]="step">
+  <div sc-stepper-list>
+    <div sc-stepper-item [step]="0">
+      <button sc-stepper-trigger></button>
+    </div>
+    <div sc-stepper-separator></div>
+    <div sc-stepper-item [step]="1">
+      <button sc-stepper-trigger></button>
+    </div>
+    <div sc-stepper-separator></div>
+    <div sc-stepper-item [step]="2">
+      <button sc-stepper-trigger></button>
+    </div>
+  </div>
+
+  <button sc-stepper-previous>Back</button>
+  <button sc-stepper-next>Continue</button>
+</div>
+```
+
+## Features
+
+- **Horizontal/Vertical**: Supports both orientations
+- **Click Navigation**: Click any step to navigate directly
+- **Step States**: Complete, active, and inactive visual states
+- **Auto-disable**: Previous button disabled on first step
+- **Check Icons**: Completed steps show a checkmark
+- **Two-way Binding**: Sync step state with `[(activeStep)]`
+
+## Accessibility
+
+- Uses `role="tablist"` for step list
+- Uses `role="tab"` for step triggers
+- Uses `role="tabpanel"` for step content
+- `aria-selected` indicates active step
+- Keyboard navigation via Tab key

package/src/lib/components/stepper/index.ts

@@ -0,0 +1,12 @@
+export { SC_STEPPER, SC_STEPPER_ITEM } from './stepper-types';
+export type { StepperOrientation } from './stepper-types';
+export { ScStepper } from './stepper';
+export { ScStepperList } from './stepper-list';
+export { ScStepperItem } from './stepper-item';
+export { ScStepperTrigger } from './stepper-trigger';
+export { ScStepperSeparator } from './stepper-separator';
+export { ScStepperContent } from './stepper-content';
+export { ScStepperTitle } from './stepper-title';
+export { ScStepperDescription } from './stepper-description';
+export { ScStepperPrevious } from './stepper-previous';
+export { ScStepperNext } from './stepper-next';

package/src/lib/components/stepper/stepper-content.ts

@@ -0,0 +1,25 @@
+import { computed, Directive, inject, input } from '@angular/core';
+import { cn } from '@semantic-components/ui';
+import { SC_STEPPER } from './stepper-types';
+
+@Directive({
+  selector: '[sc-stepper-content]',
+  host: {
+    'data-slot': 'stepper-content',
+    role: 'tabpanel',
+    '[class]': 'class()',
+    '[hidden]': '!isActive()',
+  },
+})
+export class ScStepperContent {
+  private readonly stepper = inject(SC_STEPPER);
+
+  readonly classInput = input<string>('', { alias: 'class' });
+  readonly step = input.required<number>();
+
+  protected readonly isActive = computed(() =>
+    this.stepper.isStepActive(this.step()),
+  );
+
+  protected readonly class = computed(() => cn('mt-4', this.classInput()));
+}

package/src/lib/components/stepper/stepper-description.ts

@@ -0,0 +1,17 @@
+import { computed, Directive, input } from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+@Directive({
+  selector: '[sc-stepper-description]',
+  host: {
+    'data-slot': 'stepper-description',
+    '[class]': 'class()',
+  },
+})
+export class ScStepperDescription {
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly class = computed(() =>
+    cn('text-xs text-muted-foreground', this.classInput()),
+  );
+}

package/src/lib/components/stepper/stepper-item.ts

@@ -0,0 +1,35 @@
+import { computed, Directive, inject, input } from '@angular/core';
+import { cn } from '@semantic-components/ui';
+import { SC_STEPPER, SC_STEPPER_ITEM } from './stepper-types';
+
+@Directive({
+  selector: '[sc-stepper-item]',
+  providers: [{ provide: SC_STEPPER_ITEM, useExisting: ScStepperItem }],
+  host: {
+    'data-slot': 'stepper-item',
+    '[class]': 'class()',
+    '[attr.data-state]': 'state()',
+  },
+})
+export class ScStepperItem {
+  private readonly stepper = inject(SC_STEPPER);
+
+  readonly classInput = input<string>('', { alias: 'class' });
+  readonly step = input.required<number>();
+
+  readonly state = computed(() => {
+    const stepNum = this.step();
+    if (this.stepper.isStepComplete(stepNum)) return 'complete';
+    if (this.stepper.isStepActive(stepNum)) return 'active';
+    return 'inactive';
+  });
+
+  protected readonly class = computed(() => {
+    const isVertical = this.stepper.orientation() === 'vertical';
+    return cn(
+      'flex gap-2',
+      isVertical ? 'flex-row' : 'flex-col items-center',
+      this.classInput(),
+    );
+  });
+}

package/src/lib/components/stepper/stepper-list.ts

@@ -0,0 +1,26 @@
+import { computed, Directive, inject, input } from '@angular/core';
+import { cn } from '@semantic-components/ui';
+import { SC_STEPPER } from './stepper-types';
+
+@Directive({
+  selector: '[sc-stepper-list]',
+  host: {
+    'data-slot': 'stepper-list',
+    role: 'tablist',
+    '[class]': 'class()',
+  },
+})
+export class ScStepperList {
+  private readonly stepper = inject(SC_STEPPER);
+
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly class = computed(() => {
+    const isVertical = this.stepper.orientation() === 'vertical';
+    return cn(
+      'flex gap-2',
+      isVertical ? 'flex-col' : 'flex-row items-center',
+      this.classInput(),
+    );
+  });
+}

package/src/lib/components/stepper/stepper-next.ts

@@ -0,0 +1,41 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  inject,
+  input,
+  ViewEncapsulation,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+import { SC_STEPPER } from './stepper-types';
+
+@Component({
+  selector: 'button[sc-stepper-next]',
+  template: `
+    <ng-content />
+  `,
+  host: {
+    'data-slot': 'stepper-next',
+    type: 'button',
+    '[class]': 'class()',
+    '(click)': 'stepper.nextStep()',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScStepperNext {
+  readonly stepper = inject(SC_STEPPER);
+
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly class = computed(() =>
+    cn(
+      'inline-flex h-10 items-center justify-center gap-2 rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground',
+      'ring-offset-background transition-colors',
+      'hover:bg-primary/90',
+      'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',
+      'disabled:pointer-events-none disabled:opacity-50',
+      this.classInput(),
+    ),
+  );
+}

package/src/lib/components/stepper/stepper-previous.ts

@@ -0,0 +1,42 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  inject,
+  input,
+  ViewEncapsulation,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+import { SC_STEPPER } from './stepper-types';
+
+@Component({
+  selector: 'button[sc-stepper-previous]',
+  template: `
+    <ng-content />
+  `,
+  host: {
+    'data-slot': 'stepper-previous',
+    type: 'button',
+    '[class]': 'class()',
+    '[disabled]': 'stepper.activeStep() === 0',
+    '(click)': 'stepper.prevStep()',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScStepperPrevious {
+  readonly stepper = inject(SC_STEPPER);
+
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly class = computed(() =>
+    cn(
+      'inline-flex h-10 items-center justify-center gap-2 rounded-md border border-input bg-background px-4 py-2 text-sm font-medium',
+      'ring-offset-background transition-colors',
+      'hover:bg-accent hover:text-accent-foreground',
+      'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',
+      'disabled:pointer-events-none disabled:opacity-50',
+      this.classInput(),
+    ),
+  );
+}

package/src/lib/components/stepper/stepper-separator.ts

@@ -0,0 +1,35 @@
+import { computed, Directive, inject, input } from '@angular/core';
+import { cn } from '@semantic-components/ui';
+import { SC_STEPPER, SC_STEPPER_ITEM } from './stepper-types';
+
+@Directive({
+  selector: '[sc-stepper-separator]',
+  host: {
+    'data-slot': 'stepper-separator',
+    '[class]': 'class()',
+    '[attr.data-state]': 'state()',
+  },
+})
+export class ScStepperSeparator {
+  private readonly stepper = inject(SC_STEPPER);
+  private readonly stepperItem = inject(SC_STEPPER_ITEM, { optional: true });
+
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly state = computed(() => {
+    if (!this.stepperItem) return 'inactive';
+    return this.stepper.isStepComplete(this.stepperItem.step())
+      ? 'complete'
+      : 'inactive';
+  });
+
+  protected readonly class = computed(() => {
+    const isVertical = this.stepper.orientation() === 'vertical';
+    return cn(
+      'transition-colors',
+      isVertical ? 'ml-5 h-8 w-0.5' : 'h-0.5 flex-1',
+      'data-[state=complete]:bg-primary data-[state=inactive]:bg-muted',
+      this.classInput(),
+    );
+  });
+}

package/src/lib/components/stepper/stepper-title.ts

@@ -0,0 +1,17 @@
+import { computed, Directive, input } from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+@Directive({
+  selector: '[sc-stepper-title]',
+  host: {
+    'data-slot': 'stepper-title',
+    '[class]': 'class()',
+  },
+})
+export class ScStepperTitle {
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly class = computed(() =>
+    cn('text-sm font-medium', this.classInput()),
+  );
+}

package/src/lib/components/stepper/stepper-trigger.ts

@@ -0,0 +1,67 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  inject,
+  input,
+  ViewEncapsulation,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+import { SC_STEPPER, SC_STEPPER_ITEM } from './stepper-types';
+
+@Component({
+  selector: 'button[sc-stepper-trigger]',
+  template: `
+    @if (stepperItem.state() === 'complete') {
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        width="24"
+        height="24"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="2"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+        class="size-4"
+      >
+        <path d="M20 6 9 17l-5-5" />
+      </svg>
+    } @else {
+      <span>{{ stepperItem.step() + 1 }}</span>
+    }
+  `,
+  host: {
+    'data-slot': 'stepper-trigger',
+    type: 'button',
+    role: 'tab',
+    '[class]': 'class()',
+    '[attr.aria-selected]': 'stepperItem.state() === "active"',
+    '[attr.data-state]': 'stepperItem.state()',
+    '(click)': 'onClick()',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScStepperTrigger {
+  private readonly stepper = inject(SC_STEPPER);
+  readonly stepperItem = inject(SC_STEPPER_ITEM);
+
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly class = computed(() =>
+    cn(
+      'inline-flex size-10 items-center justify-center rounded-full border-2 text-sm font-medium',
+      'transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',
+      'disabled:pointer-events-none disabled:opacity-50',
+      'data-[state=complete]:border-primary data-[state=complete]:bg-primary data-[state=complete]:text-primary-foreground',
+      'data-[state=active]:border-primary data-[state=active]:text-primary',
+      'data-[state=inactive]:border-muted data-[state=inactive]:text-muted-foreground',
+      this.classInput(),
+    ),
+  );
+
+  onClick(): void {
+    this.stepper.goToStep(this.stepperItem.step());
+  }
+}

package/src/lib/components/stepper/stepper-types.ts

@@ -0,0 +1,10 @@
+import { InjectionToken } from '@angular/core';
+import type { ScStepper } from './stepper';
+import type { ScStepperItem } from './stepper-item';
+
+export type StepperOrientation = 'horizontal' | 'vertical';
+
+export const SC_STEPPER = new InjectionToken<ScStepper>('SC_STEPPER');
+export const SC_STEPPER_ITEM = new InjectionToken<ScStepperItem>(
+  'SC_STEPPER_ITEM',
+);

package/src/lib/components/stepper/stepper.ts

@@ -0,0 +1,46 @@
+import { computed, Directive, input, model } from '@angular/core';
+import { cn } from '@semantic-components/ui';
+import { SC_STEPPER, StepperOrientation } from './stepper-types';
+
+@Directive({
+  selector: '[sc-stepper]',
+  providers: [{ provide: SC_STEPPER, useExisting: ScStepper }],
+  host: {
+    'data-slot': 'stepper',
+    '[class]': 'class()',
+    '[attr.data-orientation]': 'orientation()',
+  },
+})
+export class ScStepper {
+  readonly classInput = input<string>('', { alias: 'class' });
+  readonly orientation = input<StepperOrientation>('horizontal');
+  readonly activeStep = model<number>(0);
+
+  protected readonly class = computed(() =>
+    cn(
+      'flex gap-4',
+      this.orientation() === 'vertical' ? 'flex-col' : 'flex-row',
+      this.classInput(),
+    ),
+  );
+
+  goToStep(step: number): void {
+    this.activeStep.set(step);
+  }
+
+  nextStep(): void {
+    this.activeStep.update((s) => s + 1);
+  }
+
+  prevStep(): void {
+    this.activeStep.update((s) => Math.max(0, s - 1));
+  }
+
+  isStepComplete(step: number): boolean {
+    return step < this.activeStep();
+  }
+
+  isStepActive(step: number): boolean {
+    return step === this.activeStep();
+  }
+}