@ceed/ads 1.23.3 → 1.23.4

package/dist/components/navigation/Stepper.md

@@ -1,6 +1,10 @@
 # Stepper
 
-Stepper 컴포넌트는 여러 단계로 구성된 프로세스를 시각적으로 보여주는 컴포넌트입니다. 사용자가 현재 어느 단계에 있는지 표시하고, 완료된 단계와 남은 단계를 쉽게 확인할 수 있습니다.
+## Introduction
+
+The Stepper component visually represents a multi-step process, guiding users through sequential tasks such as forms, onboarding flows, or checkout procedures. It clearly indicates the current step, completed steps, and remaining steps, giving users a sense of progress and orientation within a workflow.
+
+Stepper supports both horizontal and vertical layouts, customizable colors, and flexible step content including labels, extra descriptions, and indicator numbers or icons. It is well suited for wizards, registration flows, order tracking, and any process that benefits from a clear step-by-step breakdown.
 
 ```text
 // Unable to derive source for Default
@@ -10,99 +14,227 @@ Stepper 컴포넌트는 여러 단계로 구성된 프로세스를 시각적으
 | ---------------------------- | ----------- | ------- |
 | Controls resolved at runtime | —           | —       |
 
-## 사용법
+## Usage
 
 ```tsx
 import { Stepper } from '@ceed/ads';
+
+function OnboardingFlow() {
+  const [activeStep, setActiveStep] = useState(1);
+
+  return (
+    <Stepper
+      steps={[
+        { indicatorContent: 1, label: 'Account', extraContent: 'Create your account' },
+        { indicatorContent: 2, label: 'Profile', extraContent: 'Set up your profile' },
+        { indicatorContent: 3, label: 'Complete', extraContent: 'Review and finish' },
+      ]}
+      activeStep={activeStep}
+    />
+  );
+}
 ```
 
-## 기본형
+## Default
 
-Stepper의 기본 형태입니다. 필수 속성 값으로 `steps`와 `activeStep`을 받으며, 각 단계는 `indicatorContent`, `label`, `extraContent`를 포함할 수 있습니다.
+The default form of Stepper. It requires `steps` and `activeStep` as mandatory props. Each step can include `indicatorContent`, `label`, and `extraContent`.
 
 ```text
 // Unable to derive source for Default
 ```
 
-## 인디케이터만 사용
+## Indicator Only
 
-`label`과 `extraContent` 없이 인디케이터만 표시할 수도 있습니다.
+Steps can be rendered with only the indicator, omitting `label` and `extraContent`. This is useful for compact layouts where full labels are not needed.
 
 ```text
 // Unable to derive source for OnlyIndicator
 ```
 
-## 방향 설정
+## Orientation
 
-### 수평 방향 (Horizontal)
+### Horizontal
 
-`orientation` 속성을 'horizontal'로 설정하면 Stepper가 수평 방향으로 표시됩니다.
+Set the `orientation` prop to `'horizontal'` to display the Stepper in a horizontal layout.
 
 ```text
 // Unable to derive source for HorizontalOrientation
 ```
 
-### 수직 방향 (Vertical)
+### Vertical
 
-`orientation` 속성을 'vertical'로 설정하면 Stepper가 수직 방향으로 표시됩니다. 이것이 기본 설정입니다.
+Set the `orientation` prop to `'vertical'` to display the Stepper vertically. This is the default orientation.
 
 ```text
 // Unable to derive source for VerticalOrientation
 ```
 
-## 단계 방향 설정
+## Step Orientation
 
-### 수평 단계 방향 (Horizontal Step Orientation)
+### Horizontal Step Orientation
 
-`stepOrientation` 속성을 'horizontal'로 설정하면 각 단계의 내용이 인디케이터 옆에 수평으로 배치됩니다. 이것이 기본 설정입니다.
+Set `stepOrientation` to `'horizontal'` to place each step's content beside the indicator. This is the default step orientation.
 
 ```text
 // Unable to derive source for HorizontalStepOrientation
 ```
 
-### 수직 단계 방향 (Vertical Step Orientation)
+### Vertical Step Orientation
 
-`stepOrientation` 속성을 'vertical'로 설정하면 각 단계의 내용이 인디케이터 아래에 수직으로 배치됩니다.
-**주의**: `orientation`이 'vertical'로 설정된 경우, `stepOrientation`은 항상 'horizontal'로 강제 설정됩니다.
+Set `stepOrientation` to `'vertical'` to place each step's content below the indicator. When `orientation` is `'horizontal'` and `stepOrientation` is `'vertical'`, content is automatically center-aligned.
 
-`orientation`이 'horizontal'이고 `stepOrientation`이 'vertical'인 경우, 단계 내용이 자동으로 중앙 정렬됩니다.
+> **Note:** When `orientation` is set to `'vertical'`, the `stepOrientation` is always forced to `'horizontal'` regardless of the value provided.
 
 ```text
 // Unable to derive source for VerticalStepOrientation
 ```
 
-## 색상 커스터마이징
+## Color Customization
 
-### 활성 색상 설정
+### Active Color
 
-`activeColor`와 `activeLineColor` 속성을 사용하여 활성 상태와 완료된 상태의 색상을 변경할 수 있습니다.
+Use `activeColor` and `activeLineColor` to change the color of active and completed steps and their connecting lines.
 
 ```text
 // Unable to derive source for WithActiveColor
 ```
 
-### 비활성 색상 설정
+### Inactive Color
 
-`inactiveColor`와 `inactiveLineColor` 속성을 사용하여 비활성 상태의 색상을 변경할 수 있습니다.
+Use `inactiveColor` and `inactiveLineColor` to change the color of steps that have not yet been reached.
 
 ```text
 // Unable to derive source for WithInactiveColor
 ```
 
-## 단계 상태
+## Step State
 
-### 모든 단계 완료
+### All Steps Complete
 
-`activeStep` 값이 단계 수보다 크면 모든 단계가 완료된 것으로 표시됩니다.
+When the `activeStep` value exceeds the total number of steps, all steps are displayed as completed.
 
 ```text
 // Unable to derive source for WithAllComplete
 ```
 
-### 모든 단계 비활성
+### All Steps Inactive
 
-`activeStep` 값이 0이면 모든 단계가 비활성 상태로 표시됩니다.
+When `activeStep` is set to `0`, all steps are displayed in the inactive state.
 
 ```text
 // Unable to derive source for WithAllInactive
 ```
+
+## Common Use Cases
+
+### Form Wizard
+
+```tsx
+function FormWizard() {
+  const [activeStep, setActiveStep] = useState(1);
+
+  const steps = [
+    { indicatorContent: 1, label: 'Personal Info', extraContent: 'Name and contact' },
+    { indicatorContent: 2, label: 'Address', extraContent: 'Shipping details' },
+    { indicatorContent: 3, label: 'Payment', extraContent: 'Billing information' },
+    { indicatorContent: 4, label: 'Confirm', extraContent: 'Review your order' },
+  ];
+
+  return (
+    <Box>
+      <Stepper steps={steps} activeStep={activeStep} orientation="horizontal" />
+      <Box sx={{ mt: 3 }}>
+        {/* Step content rendered here based on activeStep */}
+        <Stack direction="row" gap={1} sx={{ mt: 2 }}>
+          <Button
+            disabled={activeStep <= 1}
+            onClick={() => setActiveStep((prev) => prev - 1)}
+          >
+            Back
+          </Button>
+          <Button onClick={() => setActiveStep((prev) => prev + 1)}>
+            {activeStep >= steps.length ? 'Finish' : 'Next'}
+          </Button>
+        </Stack>
+      </Box>
+    </Box>
+  );
+}
+```
+
+### Order Tracking
+
+```tsx
+function OrderTracking({ currentStatus }) {
+  const statusToStep = { placed: 1, processing: 2, shipped: 3, delivered: 4 };
+
+  return (
+    <Stepper
+      orientation="vertical"
+      activeStep={statusToStep[currentStatus]}
+      activeColor="success.500"
+      activeLineColor="success.500"
+      steps={[
+        { indicatorContent: 1, label: 'Order Placed', extraContent: 'Jan 15, 2025' },
+        { indicatorContent: 2, label: 'Processing', extraContent: 'Jan 16, 2025' },
+        { indicatorContent: 3, label: 'Shipped', extraContent: 'In transit' },
+        { indicatorContent: 4, label: 'Delivered', extraContent: 'Estimated Jan 20' },
+      ]}
+    />
+  );
+}
+```
+
+### Compact Progress Indicator
+
+```tsx
+function CompactProgress({ currentStep, totalSteps }) {
+  const steps = Array.from({ length: totalSteps }, (_, i) => ({
+    indicatorContent: i + 1,
+  }));
+
+  return (
+    <Stepper
+      steps={steps}
+      activeStep={currentStep}
+      orientation="horizontal"
+      stepOrientation="vertical"
+    />
+  );
+}
+```
+
+## Best Practices
+
+1. **Keep step count manageable**: Limit the number of steps to 3-7 for optimal user comprehension. If more steps are needed, consider grouping them.
+
+```tsx
+// ✅ Good: Concise steps
+<Stepper steps={[step1, step2, step3, step4]} activeStep={2} />
+
+// ❌ Bad: Too many steps overwhelm users
+<Stepper steps={[s1, s2, s3, s4, s5, s6, s7, s8, s9, s10]} activeStep={3} />
+```
+
+2. **Use descriptive labels**: Provide clear, concise labels that tell users what each step involves.
+
+```tsx
+// ✅ Good: Descriptive labels
+{ label: 'Shipping Address', extraContent: 'Where should we deliver?' }
+
+// ❌ Bad: Vague labels
+{ label: 'Step 2', extraContent: 'Continue' }
+```
+
+3. **Choose the right orientation**: Use horizontal for wide layouts with few steps, and vertical for narrow layouts or many steps.
+
+4. **Indicate completion clearly**: Use `activeStep` values accurately. Setting `activeStep` higher than the step count signals completion of the entire flow.
+
+5. **Use color meaningfully**: Apply `activeColor` to match your application's semantic palette (e.g., success green for completed tasks, primary blue for in-progress).
+
+## Accessibility
+
+- The Stepper uses semantic list markup, making the step sequence understandable by screen readers.
+- Each step indicator and label is accessible to assistive technology, conveying both position and state.
+- Use descriptive `label` and `extraContent` values so that users relying on screen readers can understand what each step represents.
+- Avoid relying solely on color to communicate step status. The structural difference between active, completed, and inactive steps is also conveyed through visual indicators.