torch-glare 2.1.0 → 2.1.2

package/docs/components/form-stepper.md

@@ -0,0 +1,244 @@
+---
+title: FormStepper
+description: Pill-shaped multi-step indicator for forms and wizards. Three semantic step types (default, success, negative) with resting, hover, selected, and selected-hover states. Full LTR and RTL support.
+component: true
+group: Forms
+keywords: [form-stepper, stepper, wizard, steps, pill, multi-step, form, indicator, RTL]
+---
+
+# FormStepper
+
+A pill-shaped multi-step indicator for forms and wizards. Each step renders a circular indicator and a label inside a pill. Selection swaps the pill background to black with a white label; hover deepens the shadow on selected pills and grows the label gap on non-selected ones. The status badge on the indicator switches the visual to `success` (green check) or `negative` (red info).
+
+The component is composed of `FormStepper`, `FormStep`, `FormStepIndicator`, and `FormStepLabel`.
+
+## Installation
+
+```bash
+npx torch-glare@latest add FormStepper
+```
+
+## Imports
+
+```typescript
+import {
+  FormStepper,
+  FormStep,
+  FormStepIndicator,
+  FormStepLabel,
+} from '@/components/FormStepper'
+```
+
+## Basic Usage
+
+```tsx
+import { useState } from 'react'
+import {
+  FormStepper,
+  FormStep,
+  FormStepIndicator,
+  FormStepLabel,
+} from '@/components/FormStepper'
+
+export function BasicFormStepper() {
+  const [activeStep, setActiveStep] = useState(0)
+
+  return (
+    <FormStepper activeStep={activeStep}>
+      <FormStep index={0} type="success" onClick={() => setActiveStep(0)}>
+        <FormStepIndicator />
+        <FormStepLabel>Account</FormStepLabel>
+      </FormStep>
+      <FormStep index={1} type="default" onClick={() => setActiveStep(1)}>
+        <FormStepIndicator />
+        <FormStepLabel>Profile</FormStepLabel>
+      </FormStep>
+      <FormStep index={2} type="negative" onClick={() => setActiveStep(2)}>
+        <FormStepIndicator />
+        <FormStepLabel>Payment</FormStepLabel>
+      </FormStep>
+      <FormStep index={3} type="default" onClick={() => setActiveStep(3)}>
+        <FormStepIndicator />
+        <FormStepLabel>Confirm</FormStepLabel>
+      </FormStep>
+    </FormStepper>
+  )
+}
+```
+
+`FormStepper.activeStep` drives which pill renders selected — each `FormStep` auto-selects when its `index` matches. Pass `selected` on a step to override the match.
+
+## Examples
+
+### Step Types
+
+Three semantic types. `success` and `negative` add a small status badge on the indicator (check / info icon) and use filled colors when selected. `default` uses a gray ring at rest, blue ring on hover, and a solid blue fill when selected.
+
+```tsx
+export function StepTypes() {
+  return (
+    <FormStepper>
+      <FormStep index={0} type="default" selected={false}>
+        <FormStepIndicator />
+        <FormStepLabel>Default</FormStepLabel>
+      </FormStep>
+      <FormStep index={1} type="success" selected={false}>
+        <FormStepIndicator />
+        <FormStepLabel>Success</FormStepLabel>
+      </FormStep>
+      <FormStep index={2} type="negative" selected={false}>
+        <FormStepIndicator />
+        <FormStepLabel>Negative</FormStepLabel>
+      </FormStep>
+    </FormStepper>
+  )
+}
+```
+
+### Selected state
+
+```tsx
+export function SelectedSteps() {
+  return (
+    <FormStepper>
+      <FormStep index={0} type="default" selected>
+        <FormStepIndicator />
+        <FormStepLabel>Default</FormStepLabel>
+      </FormStep>
+      <FormStep index={1} type="success" selected>
+        <FormStepIndicator />
+        <FormStepLabel>Success</FormStepLabel>
+      </FormStep>
+      <FormStep index={2} type="negative" selected>
+        <FormStepIndicator />
+        <FormStepLabel>Negative</FormStepLabel>
+      </FormStep>
+    </FormStepper>
+  )
+}
+```
+
+### RTL direction
+
+The pill, label spacing, and indicator badge all flip under `dir="rtl"`.
+
+```tsx
+export function RTLFormStepper() {
+  return (
+    <div dir="rtl">
+      <FormStepper>
+        <FormStep index={0} type="default" selected>
+          <FormStepIndicator />
+          <FormStepLabel>افتراضي</FormStepLabel>
+        </FormStep>
+        <FormStep index={1} type="success">
+          <FormStepIndicator />
+          <FormStepLabel>نجاح</FormStepLabel>
+        </FormStep>
+        <FormStep index={2} type="negative">
+          <FormStepIndicator />
+          <FormStepLabel>خطأ</FormStepLabel>
+        </FormStep>
+      </FormStepper>
+    </div>
+  )
+}
+```
+
+### Custom badge icon
+
+`FormStepIndicator.badgeIcon` overrides the default check / info icon for `success` / `negative` types.
+
+```tsx
+<FormStep index={0} type="success" selected>
+  <FormStepIndicator badgeIcon={<i className="ri-shield-check-line" />} />
+  <FormStepLabel>Verified</FormStepLabel>
+</FormStep>
+```
+
+### Custom indicator content
+
+Children of `FormStepIndicator` replace the auto-rendered step number.
+
+```tsx
+<FormStep index={0} type="default" selected>
+  <FormStepIndicator>
+    <i className="ri-user-line" />
+  </FormStepIndicator>
+  <FormStepLabel>Account</FormStepLabel>
+</FormStep>
+```
+
+## API Reference
+
+### FormStepper
+
+| Prop         | Type                            | Default | Description                                                       |
+| ------------ | ------------------------------- | ------- | ----------------------------------------------------------------- |
+| `activeStep` | `number`                        | `0`     | Zero-based index of the currently selected step.                  |
+| `theme`      | `'dark' \| 'light' \| 'default'` | —       | Theme override applied via `data-theme`.                          |
+| `className`  | `string`                        | —       | Extra classes merged onto the root `<div>`.                       |
+
+Standard `HTMLAttributes<HTMLDivElement>` are forwarded.
+
+### FormStep
+
+| Prop        | Type                                    | Default     | Description                                                                |
+| ----------- | --------------------------------------- | ----------- | -------------------------------------------------------------------------- |
+| `index`     | `number`                                | `0`         | Zero-based step index. Matched against `FormStepper.activeStep`.           |
+| `type`      | `'default' \| 'success' \| 'negative'` | `'default'` | Visual type. `success` and `negative` add a status badge on the indicator. |
+| `selected`  | `boolean`                               | —           | Force the selected state, overriding the index/`activeStep` match.         |
+| `className` | `string`                                | —           | Extra classes merged onto the pill root.                                   |
+
+Standard `HTMLAttributes<HTMLDivElement>` (minus `type`) are forwarded — typical use is `onClick` for navigation.
+
+### FormStepIndicator
+
+| Prop        | Type        | Default | Description                                                                   |
+| ----------- | ----------- | ------- | ----------------------------------------------------------------------------- |
+| `badgeIcon` | `ReactNode` | —       | Override the default badge icon (check for `success`, info for `negative`).   |
+| `children`  | `ReactNode` | —       | Replaces the auto-rendered step number.                                       |
+| `className` | `string`    | —       | Extra classes merged onto the indicator `<div>`.                              |
+
+### FormStepLabel
+
+Forwards `HTMLAttributes<HTMLDivElement>`. Color and label spacing follow the parent `FormStep` selection state.
+
+## Styling
+
+- Pill height: `28px`, fully rounded, `2px` inner padding.
+- Indicator: `24×24px` circle, `border-[3px]` for `default`, solid fill for `success`/`negative`.
+- Status badge: `15×15px` circle pinned to the top-right of the indicator (top-left under RTL), with `border` matching the page background.
+- Selection: `bg-[#000000]` pill with `text-[#FFFFFF]` label and a `0 0 32px 2px rgba(0,0,0,0.05)` shadow that deepens on hover.
+- Non-selected hover: `bg-[#FFFFFF]` pill, label gap grows from `6px` to `9px`, ring color flips to `#004699`.
+
+## TypeScript Types
+
+```typescript
+type FormStepperType = 'default' | 'success' | 'negative'
+
+interface FormStepperProps extends React.HTMLAttributes<HTMLDivElement> {
+  activeStep?: number
+  theme?: 'dark' | 'light' | 'default'
+}
+
+interface FormStepProps
+  extends Omit<React.HTMLAttributes<HTMLDivElement>, 'type'> {
+  index?: number
+  type?: FormStepperType
+  selected?: boolean
+}
+```
+
+## Accessibility
+
+- Each `FormStep` is a focusable interactive surface — attach `onClick` and (if needed) `role="button"` plus `tabIndex={0}` for keyboard navigation.
+- The status badge is `aria-hidden`; the meaning should be carried by the label text (e.g. `"Payment — error"`).
+- Color is never the sole signal for `success`/`negative` — pair with text or an off-screen description.
+
+## Best Practices
+
+1. Drive selection with `activeStep` from the parent form state — avoid setting `selected` per step manually.
+2. Use `success` only for *completed and validated* steps, `negative` only for *failed* steps. Default = pending or current.
+3. Keep labels short — the pill grows by `~3px` on hover, and long labels make that animation jittery.
+4. Wire `onClick` for non-linear navigation (jump-to-step). For strict wizards, omit `onClick` on future steps.

package/docs/components/stepper.md

@@ -0,0 +1,215 @@
+---
+title: Stepper
+description: Generic horizontal/vertical stepper with pending, active, completed, and error states. Composed of Stepper, Step, StepIndicator, StepConnector, StepLabel, and StepDescription.
+component: true
+group: Forms
+keywords: [stepper, steps, wizard, progress, multi-step, vertical, horizontal]
+---
+
+# Stepper
+
+A generic step-progress component for wizards, onboarding flows, and multi-section forms. Each step has four states — `pending`, `active`, `completed`, `error` — derived automatically from `activeStep` or set explicitly per `Step`.
+
+The component is composed of `Stepper`, `Step`, `StepIndicator`, `StepConnector`, `StepLabel`, and `StepDescription`. Compare to [`FormStepper`](./form-stepper.md), which is a pill-shaped variant with no connector line.
+
+## Installation
+
+```bash
+npx torch-glare@latest add Stepper
+```
+
+## Imports
+
+```typescript
+import {
+  Stepper,
+  Step,
+  StepIndicator,
+  StepConnector,
+  StepLabel,
+  StepDescription,
+} from '@/components/Stepper'
+```
+
+## Basic Usage
+
+```tsx
+import { useState } from 'react'
+import {
+  Stepper,
+  Step,
+  StepIndicator,
+  StepConnector,
+  StepLabel,
+} from '@/components/Stepper'
+
+export function BasicStepper() {
+  const [activeStep, setActiveStep] = useState(1)
+
+  return (
+    <Stepper activeStep={activeStep}>
+      <Step index={0}>
+        <StepIndicator />
+        <StepLabel>Account</StepLabel>
+      </Step>
+      <StepConnector />
+      <Step index={1}>
+        <StepIndicator />
+        <StepLabel>Profile</StepLabel>
+      </Step>
+      <StepConnector />
+      <Step index={2}>
+        <StepIndicator />
+        <StepLabel>Confirm</StepLabel>
+      </Step>
+    </Stepper>
+  )
+}
+```
+
+State derivation: `index < activeStep` → `completed`, `index === activeStep` → `active`, otherwise `pending`. Pass `isCompleted`, `isActive`, or `isError` on a `Step` to override.
+
+## Examples
+
+### Vertical orientation with descriptions
+
+```tsx
+<Stepper orientation="vertical" activeStep={1}>
+  <Step index={0}>
+    <StepIndicator />
+    <div>
+      <StepLabel>Create account</StepLabel>
+      <StepDescription>Email and password.</StepDescription>
+    </div>
+  </Step>
+  <StepConnector />
+  <Step index={1}>
+    <StepIndicator />
+    <div>
+      <StepLabel>Verify email</StepLabel>
+      <StepDescription>Check your inbox for a code.</StepDescription>
+    </div>
+  </Step>
+  <StepConnector />
+  <Step index={2}>
+    <StepIndicator />
+    <div>
+      <StepLabel>Done</StepLabel>
+      <StepDescription>You're all set.</StepDescription>
+    </div>
+  </Step>
+</Stepper>
+```
+
+### Error state
+
+```tsx
+<Stepper activeStep={2}>
+  <Step index={0}>
+    <StepIndicator />
+    <StepLabel>Account</StepLabel>
+  </Step>
+  <StepConnector />
+  <Step index={1} isError>
+    <StepIndicator />
+    <StepLabel>Payment</StepLabel>
+  </Step>
+  <StepConnector />
+  <Step index={2}>
+    <StepIndicator />
+    <StepLabel>Confirm</StepLabel>
+  </Step>
+</Stepper>
+```
+
+`StepIndicator` auto-renders a check icon for `completed`, a close icon for `error`, and the step number otherwise. Override via `icon`, `completedIcon`, or `errorIcon`.
+
+### Custom indicators
+
+```tsx
+<Step index={0} isCompleted>
+  <StepIndicator
+    completedIcon={<i className="ri-shield-check-line" />}
+    errorIcon={<i className="ri-shield-cross-line" />}
+  />
+  <StepLabel>Verified</StepLabel>
+</Step>
+```
+
+### Sizes
+
+```tsx
+<Stepper size="S" activeStep={1}> {/* 22px indicators */} </Stepper>
+<Stepper size="M" activeStep={1}> {/* 28px — default */} </Stepper>
+<Stepper size="L" activeStep={1}> {/* 34px */} </Stepper>
+```
+
+## API Reference
+
+### Stepper
+
+| Prop          | Type                              | Default        | Description                                          |
+| ------------- | --------------------------------- | -------------- | ---------------------------------------------------- |
+| `activeStep`  | `number`                          | `0`            | Zero-based index of the active step.                 |
+| `orientation` | `'horizontal' \| 'vertical'`      | `'horizontal'` | Layout direction.                                    |
+| `size`        | `'S' \| 'M' \| 'L'`               | `'M'`          | Indicator size for all children.                     |
+| `theme`       | `'dark' \| 'light' \| 'default'`  | —              | Theme override applied via `data-theme`.             |
+
+### Step
+
+| Prop          | Type      | Default | Description                                                  |
+| ------------- | --------- | ------- | ------------------------------------------------------------ |
+| `index`       | `number`  | `0`     | Zero-based step index. Compared with `Stepper.activeStep`.   |
+| `isActive`    | `boolean` | —       | Force the active state.                                      |
+| `isCompleted` | `boolean` | —       | Force the completed state.                                   |
+| `isError`     | `boolean` | —       | Force the error state. Overrides active and completed.       |
+
+### StepIndicator
+
+| Prop            | Type        | Default | Description                                       |
+| --------------- | ----------- | ------- | ------------------------------------------------- |
+| `icon`          | `ReactNode` | —       | Replaces the step number for the pending state.   |
+| `completedIcon` | `ReactNode` | —       | Replaces the default check icon when completed.   |
+| `errorIcon`     | `ReactNode` | —       | Replaces the default close icon on error.         |
+
+### StepConnector
+
+The line between steps. No props beyond standard HTML attributes — orientation comes from the parent `Stepper`.
+
+### StepLabel / StepDescription
+
+Forward `HTMLAttributes<HTMLDivElement>`. Their colors follow the parent `Step` state automatically.
+
+## Styling
+
+- Default state: `bg-background-presentation-action-disabled`, gray border, disabled foreground.
+- Active: blue informational background + focus ring.
+- Completed: green success background and ring; check icon.
+- Error: red negative background and ring; close icon.
+- Connectors: `2px` line, gray when pending, focus-blue when the preceding step is completed.
+
+## TypeScript Types
+
+```typescript
+import type { VariantProps } from 'class-variance-authority'
+import type { stepperStyles, stepIndicatorStyles } from '@/components/Stepper'
+
+type StepperVariants  = VariantProps<typeof stepperStyles>
+// { orientation?: 'horizontal' | 'vertical' }
+
+type IndicatorVariants = VariantProps<typeof stepIndicatorStyles>
+// { state?: 'pending' | 'active' | 'completed' | 'error'; size?: 'S' | 'M' | 'L' }
+```
+
+## Accessibility
+
+- Wrap the stepper in a `<nav aria-label="Progress">` when it represents real navigation.
+- Use `aria-current="step"` on the active step's container when steps are interactive.
+- Don't rely on color alone for error — pair with `StepDescription` or an off-screen message.
+
+## Best Practices
+
+1. Use `Stepper` when you need a connector line + numbered/iconified steps. Use `FormStepper` when you want pill-shaped buttons without a line.
+2. Keep `Step` count to 3–5 horizontal, 3–7 vertical. Beyond that, switch to a checklist or summary.
+3. Drive state from `activeStep` in the parent — only fall back to `isActive`/`isCompleted` for non-linear flows.
+4. Provide a `StepDescription` only on vertical steppers — descriptions wrap horizontal layouts awkwardly.