torch-glare 2.5.2 → 2.5.4

package/apps/lib/components/FormStepper.tsx

@@ -1,272 +0,0 @@
-"use client";
-
-import React, { forwardRef, HTMLAttributes, ReactNode, createContext, useContext } from "react";
-import { cva } from "class-variance-authority";
-import { cn } from "../utils/cn";
-import { Themes } from "../utils/types";
-
-// ─── Types ───────────────────────────────────────────────────────────────────
-
-type FormStepperType = "default" | "success" | "negative";
-
-// ─── Context ─────────────────────────────────────────────────────────────────
-
-interface FormStepperContextValue {
-  activeStep: number;
-}
-
-const FormStepperContext = createContext<FormStepperContextValue>({
-  activeStep: 0,
-});
-
-const useFormStepperContext = () => useContext(FormStepperContext);
-
-// ─── FormStepper Root ────────────────────────────────────────────────────────
-
-interface FormStepperProps extends HTMLAttributes<HTMLDivElement> {
-  theme?: Themes;
-  activeStep?: number;
-}
-
-const FormStepper = forwardRef<HTMLDivElement, FormStepperProps>(
-  ({ className, theme, activeStep = 0, ...props }, ref) => (
-    <FormStepperContext.Provider value={{ activeStep }}>
-      <div
-        ref={ref}
-        data-theme={theme}
-        className={cn("flex items-center gap-3", className)}
-        {...props}
-      />
-    </FormStepperContext.Provider>
-  ),
-);
-FormStepper.displayName = "FormStepper";
-
-// ─── FormStep (the pill wrapper) ─────────────────────────────────────────────
-
-const formStepStyles = cva(
-  [
-    "group/form-step inline-flex items-center shrink-0",
-    "h-[28px] rounded-full p-[2px]",
-    "transition-all duration-200 ease-in-out",
-    "cursor-pointer select-none outline-none",
-  ],
-  {
-    variants: {
-      // Selection drives the pill background. Hover drives a white bg + soft
-      // shadow for non-selected pills, and a stronger shadow for selected pills.
-      selected: {
-        true: [
-          "bg-[#000000]",
-          "shadow-[0_0_32px_2px_rgba(0,0,0,0.05)]",
-          "hover:shadow-[0_0_32px_2px_rgba(0,0,0,0.2)]",
-        ],
-        false: [
-          "bg-transparent",
-          "hover:bg-[#FFFFFF]",
-          "hover:shadow-[0_0_32px_2px_rgba(0,0,0,0.05)]",
-        ],
-      },
-    },
-    defaultVariants: {
-      selected: false,
-    },
-  },
-);
-
-interface FormStepProps extends Omit<HTMLAttributes<HTMLDivElement>, "type"> {
-  index?: number;
-  type?: FormStepperType;
-  selected?: boolean;
-}
-
-const FormStep = forwardRef<HTMLDivElement, FormStepProps>(
-  ({ className, index = 0, type = "default", selected, children, ...props }, ref) => {
-    const { activeStep } = useFormStepperContext();
-    const isSelected = selected ?? index === activeStep;
-
-    return (
-      <div
-        ref={ref}
-        data-selected={isSelected || undefined}
-        data-type={type}
-        className={cn(formStepStyles({ selected: isSelected }), className)}
-        {...props}
-      >
-        {React.Children.map(children, (child) => {
-          if (!React.isValidElement(child)) return child;
-          return React.cloneElement(child as React.ReactElement<Record<string, unknown>>, {
-            _selected: isSelected,
-            _type: type,
-            _index: index,
-          });
-        })}
-      </div>
-    );
-  },
-);
-FormStep.displayName = "FormStep";
-
-// ─── FormStepIndicator (circle badge) ───────────────────────────────────────
-
-const formStepIndicatorStyles = cva(
-  [
-    "relative inline-flex items-center justify-center shrink-0",
-    "w-[24px] h-[24px] text-[14px]",
-    "rounded-full",
-    "transition-colors duration-200 ease-in-out",
-    "typography-body-medium-medium",
-  ],
-  {
-    variants: {
-      type: {
-        default: ["border-[3px]"],
-        success: ["bg-[#047854] text-[#FFFFFF]", "border border-transparent"],
-        negative: ["bg-[#E30C30] text-[#FFFFFF]", "border border-transparent"],
-      },
-      // Only meaningful for type=default. Selected = filled blue, otherwise
-      // ring color comes from the resting/hover compound variants below.
-      selected: {
-        true: "",
-        false: "",
-      },
-    },
-    defaultVariants: {
-      type: "default",
-      selected: false,
-    },
-    compoundVariants: [
-      // Default type, not selected: gray ring + gray number at rest;
-      // hover (driven by parent .group/form-step) flips ring blue, number black.
-      {
-        type: "default",
-        selected: false,
-        className: [
-          "bg-transparent border-[#A0A0A0] text-[#626467]",
-          "group-hover/form-step:border-[#004699]",
-          "group-hover/form-step:text-[#000000]",
-        ],
-      },
-      // Default type, selected: solid blue fill, white number, no ring color.
-      {
-        type: "default",
-        selected: true,
-        className: ["bg-[#005ECC] border-transparent text-[#FFFFFF]"],
-      },
-    ],
-  },
-);
-
-const formStepIndicatorBadgeStyles = cva(
-  [
-    "absolute -top-[7px]",
-    "w-[15px] h-[15px]",
-    "rounded-full",
-    "inline-flex items-center justify-center",
-    "border border-[#F0F0F0]",
-    "[&_i]:leading-none [&_i]:flex [&_i]:text-[11px]",
-    // LTR: badge top-right; RTL: badge top-left
-    "ltr:right-[-4px] rtl:left-[-4px]",
-  ],
-  {
-    variants: {
-      type: {
-        success: "bg-[#047854] text-[#FFFFFF]",
-        negative: "bg-[#E30C30] text-[#FFFFFF]",
-      },
-    },
-  },
-);
-
-interface FormStepIndicatorProps extends HTMLAttributes<HTMLDivElement> {
-  badgeIcon?: ReactNode;
-  _selected?: boolean;
-  _type?: FormStepperType;
-  _index?: number;
-}
-
-const FormStepIndicator = forwardRef<HTMLDivElement, FormStepIndicatorProps>(
-  ({ className, badgeIcon, _selected, _type = "default", _index = 0, children, ...props }, ref) => {
-    const showBadge = _type === "success" || _type === "negative";
-    const defaultBadgeIcon =
-      _type === "success" ? <i className="ri-check-line" /> : <i className="ri-information-fill" />;
-
-    return (
-      <div
-        ref={ref}
-        className={cn(formStepIndicatorStyles({ type: _type, selected: !!_selected }), className)}
-        {...props}
-      >
-        {children ?? _index + 1}
-        {showBadge && (
-          <span
-            className={cn(
-              formStepIndicatorBadgeStyles({
-                type: _type as "success" | "negative",
-              }),
-            )}
-            aria-hidden
-          >
-            {badgeIcon ?? defaultBadgeIcon}
-          </span>
-        )}
-      </div>
-    );
-  },
-);
-FormStepIndicator.displayName = "FormStepIndicator";
-
-// ─── FormStepLabel ──────────────────────────────────────────────────────────
-
-const formStepLabelStyles = cva(
-  [
-    "typography-body-small-medium whitespace-nowrap",
-    "transition-[padding,color] duration-200 ease-in-out",
-    // At rest the label sits 6px from the circle. On hover (parent pill
-    // hovered) the gap grows to 9px — matches figma onHover/onSelect-Hoverd.
-    // The outer edge keeps a constant 12px.
-    "ltr:pl-[6px] ltr:pr-[12px] rtl:pr-[6px] rtl:pl-[12px]",
-    "group-hover/form-step:ltr:pl-[9px] group-hover/form-step:rtl:pr-[9px]",
-  ],
-  {
-    variants: {
-      selected: {
-        true: "text-[#FFFFFF]",
-        false: "text-[#000000]",
-      },
-    },
-    defaultVariants: {
-      selected: false,
-    },
-  },
-);
-
-interface FormStepLabelProps extends HTMLAttributes<HTMLDivElement> {
-  _selected?: boolean;
-  _type?: FormStepperType;
-  _index?: number;
-}
-
-const FormStepLabel = forwardRef<HTMLDivElement, FormStepLabelProps>(
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars -- excluded from {...props} spread
-  ({ className, _selected, _type: _t, _index: _i, ...props }, ref) => (
-    <div
-      ref={ref}
-      className={cn(formStepLabelStyles({ selected: !!_selected }), className)}
-      {...props}
-    />
-  ),
-);
-FormStepLabel.displayName = "FormStepLabel";
-
-// ─── Exports ─────────────────────────────────────────────────────────────────
-
-export {
-  FormStepper,
-  FormStep,
-  FormStepIndicator,
-  FormStepLabel,
-  formStepStyles,
-  formStepIndicatorStyles,
-  formStepLabelStyles,
-};

package/docs/components/form-stepper.md

@@ -1,250 +0,0 @@
----
-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
-
-TORCH Glare is a copy-in library: the CLI copies this component's source into your project
-(you do **not** install it from the npm package). Run `init` once, then `add`:
-
-```bash
-npx torch-glare@latest init
-npx torch-glare@latest add FormStepper
-```
-
-`add` also copies any components, hooks, and utilities that `FormStepper` depends on.
-
-## 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.