valtech-components 2.0.690 → 2.0.691

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

@@ -0,0 +1,201 @@
+import { Component, inject, Input, OnChanges, OnInit, Output, EventEmitter, SimpleChanges } from '@angular/core';
+import { IonIcon } from '@ionic/angular/standalone';
+import { CommonModule } from '@angular/common';
+import { PresetService } from '../../../services/presets';
+import { StepperMetadata, StepMetadata, StepChangeEvent, StepStatus } from './types';
+import { addIcons } from 'ionicons';
+import { checkmark, close, ellipse } from 'ionicons/icons';
+
+addIcons({ checkmark, close, ellipse });
+
+@Component({
+  selector: 'val-stepper',
+  standalone: true,
+  imports: [CommonModule, IonIcon],
+  template: `
+    <div
+      class="stepper-container"
+      [class.horizontal]="resolvedProps.orientation !== 'vertical'"
+      [class.vertical]="resolvedProps.orientation === 'vertical'"
+    >
+      @for (step of resolvedProps.steps; track step.value; let i = $index; let isLast = $last) {
+        <div
+          class="step"
+          [class.current]="getStepStatus(step, i) === 'current'"
+          [class.completed]="getStepStatus(step, i) === 'completed'"
+          [class.error]="getStepStatus(step, i) === 'error'"
+          [class.disabled]="step.disabled"
+          [class.clickable]="isStepClickable(step, i)"
+          (click)="onStepClick(step, i)"
+        >
+          <div class="step-indicator">
+            <div class="step-circle" [style.--step-color]="getStepColor(step, i)">
+              @if (getStepStatus(step, i) === 'completed') {
+                <ion-icon name="checkmark"></ion-icon>
+              } @else if (getStepStatus(step, i) === 'error') {
+                <ion-icon name="close"></ion-icon>
+              } @else if (step.icon) {
+                <ion-icon [name]="step.icon"></ion-icon>
+              } @else if (resolvedProps.showNumbers !== false) {
+                <span class="step-number">{{ i + 1 }}</span>
+              } @else {
+                <ion-icon name="ellipse"></ion-icon>
+              }
+            </div>
+            @if (!isLast && resolvedProps.connectorStyle !== 'none') {
+              <div
+                class="step-connector"
+                [class.dashed]="resolvedProps.connectorStyle === 'dashed'"
+                [class.completed]="getStepStatus(step, i) === 'completed'"
+              ></div>
+            }
+          </div>
+          <div class="step-content">
+            <div class="step-label">
+              {{ getStepLabel(step) }}
+              @if (step.optional) {
+                <span class="optional-text">(Optional)</span>
+              }
+            </div>
+            @if (step.description) {
+              <div class="step-description">{{ step.description }}</div>
+            }
+          </div>
+        </div>
+      }
+    </div>
+  `,
+  styleUrls: ['./stepper.component.scss'],
+})
+/**
+ * val-stepper
+ *
+ * A stepper component for multi-step processes.
+ * Supports horizontal and vertical orientations.
+ *
+ * @example Basic usage
+ * <val-stepper [props]="{
+ *   steps: [
+ *     { value: 'info', label: 'Personal Info' },
+ *     { value: 'address', label: 'Address' },
+ *     { value: 'payment', label: 'Payment' },
+ *     { value: 'confirm', label: 'Confirm' }
+ *   ],
+ *   currentIndex: 1
+ * }" (stepChange)="onStepChange($event)"></val-stepper>
+ *
+ * @example Vertical with descriptions
+ * <val-stepper [props]="{
+ *   steps: [
+ *     { value: 'step1', label: 'Step 1', description: 'Description here' },
+ *     { value: 'step2', label: 'Step 2', optional: true }
+ *   ],
+ *   orientation: 'vertical',
+ *   currentIndex: 0
+ * }"></val-stepper>
+ *
+ * @input props: StepperMetadata - Configuration for the stepper
+ * @output stepChange: StepChangeEvent - Emits when step changes
+ */
+export class StepperComponent implements OnInit, OnChanges {
+  private presets = inject(PresetService);
+
+  /**
+   * Preset name to apply. Presets define reusable stepper configurations
+   * that can be registered at app level via provideValtechPresets().
+   */
+  @Input() preset?: string;
+
+  /**
+   * Stepper configuration object. Values here override preset values.
+   */
+  @Input() props: Partial<StepperMetadata> = {};
+
+  /**
+   * Resolved props after merging preset + explicit props.
+   */
+  resolvedProps: StepperMetadata = {} as StepperMetadata;
+
+  @Output() stepChange = new EventEmitter<StepChangeEvent>();
+
+  ngOnInit() {
+    this.resolveProps();
+  }
+
+  ngOnChanges(changes: SimpleChanges) {
+    if (changes['preset'] || changes['props']) {
+      this.resolveProps();
+    }
+  }
+
+  private resolveProps(): void {
+    const presetProps = this.preset
+      ? (this.presets.get('stepper', this.preset) as Partial<StepperMetadata>)
+      : {};
+
+    this.resolvedProps = {
+      ...presetProps,
+      ...this.props,
+    } as StepperMetadata;
+  }
+
+  getCurrentIndex(): number {
+    if (this.resolvedProps.currentIndex !== undefined) {
+      return this.resolvedProps.currentIndex;
+    }
+    if (this.resolvedProps.currentStep) {
+      return this.resolvedProps.steps?.findIndex((s) => s.value === this.resolvedProps.currentStep) ?? 0;
+    }
+    return 0;
+  }
+
+  getStepStatus(step: StepMetadata, index: number): StepStatus {
+    if (step.status) return step.status;
+
+    const currentIndex = this.getCurrentIndex();
+    if (index < currentIndex) return 'completed';
+    if (index === currentIndex) return 'current';
+    return 'pending';
+  }
+
+  getStepColor(step: StepMetadata, index: number): string {
+    const status = this.getStepStatus(step, index);
+    const color = this.resolvedProps.color || 'primary';
+
+    switch (status) {
+      case 'completed':
+        return `var(--ion-color-${color})`;
+      case 'current':
+        return `var(--ion-color-${color})`;
+      case 'error':
+        return 'var(--ion-color-danger)';
+      default:
+        return 'var(--ion-color-medium)';
+    }
+  }
+
+  isStepClickable(step: StepMetadata, index: number): boolean {
+    if (step.disabled) return false;
+    if (!this.resolvedProps.linear) return true;
+
+    const currentIndex = this.getCurrentIndex();
+    return index <= currentIndex || (step.editable && index < currentIndex);
+  }
+
+  onStepClick(step: StepMetadata, index: number): void {
+    if (!this.isStepClickable(step, index)) return;
+
+    const currentIndex = this.getCurrentIndex();
+    if (index === currentIndex) return;
+
+    this.stepChange.emit({
+      step,
+      index,
+      previousIndex: currentIndex,
+    });
+  }
+
+  getStepLabel(step: StepMetadata): string {
+    return step.label || step.contentFallback || '';
+  }
+}

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

@@ -0,0 +1,308 @@
+import type { Meta, StoryObj } from '@storybook/angular';
+import { moduleMetadata } from '@storybook/angular';
+import { CommonModule } from '@angular/common';
+import { StepperComponent } from './stepper.component';
+import { StepperMetadata } from './types';
+
+const createStepperProps = (overrides: Partial<StepperMetadata> = {}): StepperMetadata => ({
+  steps: [
+    { value: 'step1', label: 'Step 1' },
+    { value: 'step2', label: 'Step 2' },
+    { value: 'step3', label: 'Step 3' },
+  ],
+  currentIndex: 0,
+  color: 'primary',
+  ...overrides,
+});
+
+// Pre-create all props at module level
+const defaultProps = createStepperProps();
+const secondStepProps = createStepperProps({
+  currentIndex: 1,
+});
+const checkoutStepsProps = createStepperProps({
+  steps: [
+    { value: 'cart', label: 'Cart', description: 'Review your items' },
+    { value: 'shipping', label: 'Shipping', description: 'Enter delivery address' },
+    { value: 'payment', label: 'Payment', description: 'Add payment method' },
+    { value: 'confirm', label: 'Confirm', description: 'Place your order' },
+  ],
+  currentIndex: 1,
+});
+const verticalProps = createStepperProps({
+  orientation: 'vertical',
+  steps: [
+    { value: 'info', label: 'Personal Info', description: 'Enter your details' },
+    { value: 'address', label: 'Address', description: 'Shipping information' },
+    { value: 'review', label: 'Review', description: 'Verify your order' },
+  ],
+  currentIndex: 1,
+});
+const withIconsProps = createStepperProps({
+  steps: [
+    { value: 'home', label: 'Start', icon: 'home' },
+    { value: 'search', label: 'Search', icon: 'search' },
+    { value: 'cart', label: 'Cart', icon: 'cart' },
+    { value: 'checkmark', label: 'Done', icon: 'checkmark' },
+  ],
+  currentIndex: 2,
+  showNumbers: false,
+});
+const withErrorProps = createStepperProps({
+  steps: [
+    { value: 'step1', label: 'Details', status: 'completed' },
+    { value: 'step2', label: 'Verification', status: 'error' },
+    { value: 'step3', label: 'Complete' },
+  ],
+  currentIndex: 1,
+});
+const linearProps = createStepperProps({
+  linear: true,
+  steps: [
+    { value: 'step1', label: 'Step 1' },
+    { value: 'step2', label: 'Step 2' },
+    { value: 'step3', label: 'Step 3' },
+  ],
+  currentIndex: 0,
+});
+const optionalStepProps = createStepperProps({
+  steps: [
+    { value: 'required1', label: 'Required Step' },
+    { value: 'optional', label: 'Optional Step', optional: true },
+    { value: 'required2', label: 'Final Step' },
+  ],
+  currentIndex: 0,
+});
+const dashedConnectorProps = createStepperProps({
+  connectorStyle: 'dashed',
+  currentIndex: 1,
+});
+const completedAllProps = createStepperProps({
+  steps: [
+    { value: 'step1', label: 'Step 1', status: 'completed' },
+    { value: 'step2', label: 'Step 2', status: 'completed' },
+    { value: 'step3', label: 'Step 3', status: 'completed' },
+  ],
+  currentIndex: 2,
+});
+
+// Showcase props
+const showcaseHorizontalProps = createStepperProps({
+  steps: [
+    { value: 'cart', label: 'Cart' },
+    { value: 'shipping', label: 'Shipping' },
+    { value: 'payment', label: 'Payment' },
+    { value: 'done', label: 'Done' },
+  ],
+  currentIndex: 2,
+});
+const showcaseVerticalProps = createStepperProps({
+  orientation: 'vertical',
+  steps: [
+    { value: 'start', label: 'Getting Started', description: 'Create your account' },
+    { value: 'profile', label: 'Complete Profile', description: 'Add your information' },
+    { value: 'verify', label: 'Verify Email', description: 'Confirm your identity' },
+    { value: 'ready', label: 'All Set!', description: 'Start using the app' },
+  ],
+  currentIndex: 1,
+});
+
+const meta: Meta<StepperComponent> = {
+  title: 'Molecules/Stepper',
+  component: StepperComponent,
+  decorators: [
+    moduleMetadata({
+      imports: [CommonModule, StepperComponent],
+    }),
+  ],
+  tags: ['autodocs'],
+  argTypes: {
+    props: {
+      description: 'Stepper configuration object',
+      control: 'object',
+      table: {
+        type: {
+          summary: 'StepperMetadata',
+          detail: `{
+  steps: StepMetadata[];
+  currentStep?: string;
+  currentIndex?: number;
+  orientation?: 'horizontal' | 'vertical';
+  linear?: boolean;
+  color?: Color;
+  showNumbers?: boolean;
+  connectorStyle?: 'solid' | 'dashed' | 'none';
+}`,
+        },
+      },
+    },
+  },
+  parameters: {
+    docs: {
+      description: {
+        component: `
+## val-stepper
+
+A stepper component for multi-step processes.
+
+### Features
+
+- **Horizontal/Vertical**: Different orientations
+- **Linear Mode**: Must complete steps in order
+- **Step Status**: Pending, current, completed, error
+- **Icons**: Custom icons per step
+- **Descriptions**: Optional step descriptions
+- **Optional Steps**: Mark steps as optional
+
+### Usage
+
+\`\`\`html
+<val-stepper
+  [props]="{
+    steps: [
+      { value: 'info', label: 'Personal Info' },
+      { value: 'address', label: 'Address' },
+      { value: 'payment', label: 'Payment' }
+    ],
+    currentIndex: 1
+  }"
+  (stepChange)="onStepChange($event)"
+></val-stepper>
+\`\`\`
+        `,
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<StepperComponent>;
+
+export const Default: Story = {
+  render: () => ({
+    template: `<div style="max-width: 500px;"><val-stepper [props]="stepperProps"></val-stepper></div>`,
+    props: { stepperProps: defaultProps },
+  }),
+};
+
+export const SecondStep: Story = {
+  render: () => ({
+    template: `<div style="max-width: 500px;"><val-stepper [props]="stepperProps"></val-stepper></div>`,
+    props: { stepperProps: secondStepProps },
+  }),
+};
+
+export const CheckoutFlow: Story = {
+  render: () => ({
+    template: `<div style="max-width: 700px;"><val-stepper [props]="stepperProps"></val-stepper></div>`,
+    props: { stepperProps: checkoutStepsProps },
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story: 'E-commerce checkout flow with descriptions.',
+      },
+    },
+  },
+};
+
+export const Vertical: Story = {
+  render: () => ({
+    template: `<div style="max-width: 350px;"><val-stepper [props]="stepperProps"></val-stepper></div>`,
+    props: { stepperProps: verticalProps },
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Vertical orientation for sidebar or detailed flows.',
+      },
+    },
+  },
+};
+
+export const WithIcons: Story = {
+  render: () => ({
+    template: `<div style="max-width: 600px;"><val-stepper [props]="stepperProps"></val-stepper></div>`,
+    props: { stepperProps: withIconsProps },
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Custom icons instead of step numbers.',
+      },
+    },
+  },
+};
+
+export const WithError: Story = {
+  render: () => ({
+    template: `<div style="max-width: 500px;"><val-stepper [props]="stepperProps"></val-stepper></div>`,
+    props: { stepperProps: withErrorProps },
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Step with error status.',
+      },
+    },
+  },
+};
+
+export const Linear: Story = {
+  render: () => ({
+    template: `<div style="max-width: 500px;"><val-stepper [props]="stepperProps"></val-stepper></div>`,
+    props: { stepperProps: linearProps },
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Linear mode - steps must be completed in order.',
+      },
+    },
+  },
+};
+
+export const OptionalStep: Story = {
+  render: () => ({
+    template: `<div style="max-width: 500px;"><val-stepper [props]="stepperProps"></val-stepper></div>`,
+    props: { stepperProps: optionalStepProps },
+  }),
+};
+
+export const DashedConnector: Story = {
+  render: () => ({
+    template: `<div style="max-width: 500px;"><val-stepper [props]="stepperProps"></val-stepper></div>`,
+    props: { stepperProps: dashedConnectorProps },
+  }),
+};
+
+export const AllCompleted: Story = {
+  render: () => ({
+    template: `<div style="max-width: 500px;"><val-stepper [props]="stepperProps"></val-stepper></div>`,
+    props: { stepperProps: completedAllProps },
+  }),
+};
+
+export const Showcase: Story = {
+  render: () => ({
+    template: `
+      <div style="display: flex; flex-direction: column; gap: 48px; max-width: 700px;">
+        <h3 style="margin: 0; font-family: system-ui;">Stepper Examples</h3>
+
+        <div>
+          <h4 style="margin: 0 0 16px; font-family: system-ui; font-size: 14px; color: #666;">Checkout Progress</h4>
+          <val-stepper [props]="horizontal"></val-stepper>
+        </div>
+
+        <div style="background: #f9f9f9; padding: 24px; border-radius: 12px;">
+          <h4 style="margin: 0 0 16px; font-family: system-ui; font-size: 14px; color: #666;">Onboarding Flow</h4>
+          <val-stepper [props]="vertical"></val-stepper>
+        </div>
+      </div>
+    `,
+    props: {
+      horizontal: showcaseHorizontalProps,
+      vertical: showcaseVerticalProps,
+    },
+  }),
+};

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

@@ -0,0 +1,70 @@
+import { Color } from '@ionic/core';
+
+/**
+ * Step status.
+ */
+export type StepStatus = 'pending' | 'current' | 'completed' | 'error';
+
+/**
+ * Single step configuration.
+ */
+export interface StepMetadata {
+  /** Unique step identifier */
+  value: string;
+  /** Step label */
+  label?: string;
+  /** Step description/subtitle */
+  description?: string;
+  /** Step icon (overrides number) */
+  icon?: string;
+  /** Step status */
+  status?: StepStatus;
+  /** Whether step is optional */
+  optional?: boolean;
+  /** Whether step is editable (can go back) */
+  editable?: boolean;
+  /** Whether step is disabled */
+  disabled?: boolean;
+  /** Reactive content key for label */
+  contentKey?: string;
+  /** Component class name for content lookup */
+  contentClass?: string;
+  /** Fallback for label */
+  contentFallback?: string;
+}
+
+/**
+ * Metadata for the stepper component.
+ */
+export interface StepperMetadata {
+  /** Step items */
+  steps: StepMetadata[];
+  /** Current step value */
+  currentStep?: string;
+  /** Current step index (alternative to currentStep) */
+  currentIndex?: number;
+  /** Stepper orientation */
+  orientation?: 'horizontal' | 'vertical';
+  /** Linear mode (must complete in order) */
+  linear?: boolean;
+  /** Stepper color */
+  color?: Color;
+  /** Show step numbers */
+  showNumbers?: boolean;
+  /** Connector line style */
+  connectorStyle?: 'solid' | 'dashed' | 'none';
+  /** Unique token identifier */
+  token?: string;
+}
+
+/**
+ * Event emitted when step changes.
+ */
+export interface StepChangeEvent {
+  /** New step */
+  step: StepMetadata;
+  /** New step index */
+  index: number;
+  /** Previous step index */
+  previousIndex: number;
+}