torch-glare 2.1.1 → 2.1.2

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.

package/docs/components/timeline.md

@@ -0,0 +1,248 @@
+---
+title: Timeline
+description: Vertical or horizontal timeline for activity logs, audit trails, and history. Composed of indicator, separator, content, heading, and description parts with five semantic variants.
+component: true
+group: Data Display
+keywords: [timeline, activity, history, audit, log, events, vertical, horizontal]
+---
+
+# Timeline
+
+A composable timeline for activity logs, change history, audit trails, and event sequences. Each item has an indicator, a connecting separator, and a content block. The indicator supports five variants — `default`, `active`, `completed`, `error`, `warning` — each with built-in icons and color tokens.
+
+The component is composed of `Timeline`, `TimelineItem`, `TimelineIndicator`, `TimelineSeparator`, `TimelineConnector`, `TimelineContent`, `TimelineHeading`, and `TimelineDescription`. Unlike [`Stepper`](./stepper.md), Timeline doesn't track an `activeStep` — each item's variant is set explicitly.
+
+## Installation
+
+```bash
+npx torch-glare@latest add Timeline
+```
+
+## Imports
+
+```typescript
+import {
+  Timeline,
+  TimelineItem,
+  TimelineIndicator,
+  TimelineSeparator,
+  TimelineConnector,
+  TimelineContent,
+  TimelineHeading,
+  TimelineDescription,
+} from '@/components/Timeline'
+```
+
+## Basic Usage
+
+```tsx
+import {
+  Timeline,
+  TimelineItem,
+  TimelineIndicator,
+  TimelineSeparator,
+  TimelineConnector,
+  TimelineContent,
+  TimelineHeading,
+  TimelineDescription,
+} from '@/components/Timeline'
+
+export function BasicTimeline() {
+  return (
+    <Timeline>
+      <TimelineItem>
+        <TimelineConnector>
+          <TimelineIndicator variant="completed" />
+          <TimelineSeparator />
+        </TimelineConnector>
+        <TimelineContent>
+          <TimelineHeading>Account created</TimelineHeading>
+          <TimelineDescription>March 5, 2026 · 9:14 AM</TimelineDescription>
+        </TimelineContent>
+      </TimelineItem>
+
+      <TimelineItem>
+        <TimelineConnector>
+          <TimelineIndicator variant="active" />
+          <TimelineSeparator active />
+        </TimelineConnector>
+        <TimelineContent>
+          <TimelineHeading>Email verified</TimelineHeading>
+          <TimelineDescription>March 5, 2026 · 9:32 AM</TimelineDescription>
+        </TimelineContent>
+      </TimelineItem>
+
+      <TimelineItem>
+        <TimelineConnector>
+          <TimelineIndicator variant="default" />
+        </TimelineConnector>
+        <TimelineContent>
+          <TimelineHeading>Profile setup</TimelineHeading>
+          <TimelineDescription>Pending</TimelineDescription>
+        </TimelineContent>
+      </TimelineItem>
+    </Timeline>
+  )
+}
+```
+
+The last `TimelineItem` should typically omit `TimelineSeparator` so the line ends at the final indicator. `TimelineContent` auto-removes its bottom padding on the last item via `group-last/item:pb-0`.
+
+## Examples
+
+### Indicator variants
+
+`completed` renders a check icon, `error` renders a close icon, `warning` renders an alert icon. `default` and `active` render a `6×6` filled dot. Pass `icon` or `children` to override.
+
+```tsx
+<TimelineIndicator variant="default" />
+<TimelineIndicator variant="active" />
+<TimelineIndicator variant="completed" />
+<TimelineIndicator variant="error" />
+<TimelineIndicator variant="warning" />
+<TimelineIndicator variant="active" icon={<i className="ri-flashlight-line" />} />
+```
+
+### Sizes
+
+Indicators support `S` (`22px`), `M` (`28px`, default), and `L` (`34px`).
+
+```tsx
+<TimelineIndicator size="S" variant="completed" />
+<TimelineIndicator size="M" variant="completed" />
+<TimelineIndicator size="L" variant="completed" />
+```
+
+### Horizontal orientation
+
+```tsx
+<Timeline orientation="horizontal">
+  <TimelineItem>
+    <TimelineConnector orientation="horizontal">
+      <TimelineIndicator variant="completed" />
+      <TimelineSeparator orientation="horizontal" active />
+    </TimelineConnector>
+    <TimelineContent>
+      <TimelineHeading>Submitted</TimelineHeading>
+      <TimelineDescription>2:14 PM</TimelineDescription>
+    </TimelineContent>
+  </TimelineItem>
+
+  <TimelineItem>
+    <TimelineConnector orientation="horizontal">
+      <TimelineIndicator variant="active" />
+    </TimelineConnector>
+    <TimelineContent>
+      <TimelineHeading>Reviewing</TimelineHeading>
+      <TimelineDescription>Now</TimelineDescription>
+    </TimelineContent>
+  </TimelineItem>
+</Timeline>
+```
+
+Pass `orientation="horizontal"` on `Timeline`, `TimelineItem`, `TimelineConnector`, and `TimelineSeparator` — the orientation isn't propagated through context.
+
+### Activity log
+
+```tsx
+const events = [
+  { id: 1, variant: 'completed', heading: 'Order placed',    when: 'Mar 5 · 9:14 AM' },
+  { id: 2, variant: 'completed', heading: 'Payment received', when: 'Mar 5 · 9:15 AM' },
+  { id: 3, variant: 'active',    heading: 'Preparing order',  when: 'Mar 5 · 10:02 AM' },
+  { id: 4, variant: 'default',   heading: 'Shipped',          when: 'Pending' },
+  { id: 5, variant: 'default',   heading: 'Delivered',        when: 'Pending' },
+] as const
+
+export function OrderTimeline() {
+  return (
+    <Timeline>
+      {events.map((e, i) => (
+        <TimelineItem key={e.id}>
+          <TimelineConnector>
+            <TimelineIndicator variant={e.variant} />
+            {i < events.length - 1 && (
+              <TimelineSeparator active={e.variant === 'completed' || e.variant === 'active'} />
+            )}
+          </TimelineConnector>
+          <TimelineContent>
+            <TimelineHeading>{e.heading}</TimelineHeading>
+            <TimelineDescription>{e.when}</TimelineDescription>
+          </TimelineContent>
+        </TimelineItem>
+      ))}
+    </Timeline>
+  )
+}
+```
+
+## API Reference
+
+### Timeline
+
+| Prop          | Type                            | Default      | Description                              |
+| ------------- | ------------------------------- | ------------ | ---------------------------------------- |
+| `orientation` | `'vertical' \| 'horizontal'`    | `'vertical'` | Layout direction.                        |
+| `theme`       | `'dark' \| 'light' \| 'default'` | —            | Theme override applied via `data-theme`. |
+
+### TimelineItem
+
+| Prop          | Type                         | Default      | Description                                    |
+| ------------- | ---------------------------- | ------------ | ---------------------------------------------- |
+| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Should match the parent `Timeline`.            |
+
+### TimelineIndicator
+
+| Prop      | Type                                                            | Default     | Description                                                            |
+| --------- | --------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------- |
+| `variant` | `'default' \| 'active' \| 'completed' \| 'error' \| 'warning'` | `'default'` | Visual state. Drives both color tokens and the auto-rendered icon.     |
+| `size`    | `'S' \| 'M' \| 'L'`                                             | `'M'`       | Indicator diameter (`22 / 28 / 34px`).                                 |
+| `icon`    | `ReactNode`                                                     | —           | Custom icon — overrides the variant's default.                         |
+| `children`| `ReactNode`                                                     | —           | Custom content — used when `icon` is not set.                          |
+
+### TimelineSeparator
+
+| Prop          | Type                         | Default      | Description                                                |
+| ------------- | ---------------------------- | ------------ | ---------------------------------------------------------- |
+| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Line direction.                                            |
+| `active`      | `boolean`                    | `false`      | Render the line in focus blue (use after completed steps). |
+
+### TimelineConnector
+
+Wraps the indicator and separator. Pass `orientation` to switch between column (vertical) and row (horizontal) layout.
+
+### TimelineContent / TimelineHeading / TimelineDescription
+
+Forward `HTMLAttributes<HTMLDivElement>`. `TimelineContent` removes its bottom padding on the last item; `TimelineHeading` uses `typography-body-medium-medium`; `TimelineDescription` uses `typography-body-small-regular` with secondary text color.
+
+## Styling
+
+- Indicators use the standard state token set: `state-information-primary`, `state-success-primary`, `state-negative-primary`, `state-warning-primary`.
+- Separator: `1px` neutral line by default, focus-blue when `active`.
+- Vertical content: `pb-6 pt-[2px]` — gives breathing room between items.
+- Horizontal content: aligned under the indicator with `gap-3`.
+
+## TypeScript Types
+
+```typescript
+import type { VariantProps } from 'class-variance-authority'
+import type { timelineStyles, indicatorStyles, separatorStyles } from '@/components/Timeline'
+
+type TimelineVariants  = VariantProps<typeof timelineStyles>
+type IndicatorVariants = VariantProps<typeof indicatorStyles>
+// { variant?: 'default' | 'active' | 'completed' | 'error' | 'warning'; size?: 'S' | 'M' | 'L' }
+type SeparatorVariants = VariantProps<typeof separatorStyles>
+// { orientation?: 'vertical' | 'horizontal'; active?: boolean }
+```
+
+## Accessibility
+
+- Use `<ol>` semantics when the order matters (audit logs, order tracking) — wrap `Timeline` in `<ol>` and each `TimelineItem` in `<li>`.
+- Variants like `error` and `warning` should be paired with text in `TimelineDescription` — color is never the sole signal.
+- Decorative icons inside indicators don't need labels; the heading carries the meaning.
+
+## Best Practices
+
+1. Reach for Timeline when items are events at points in time. Reach for Stepper when items are tasks the user has to complete.
+2. Always omit `TimelineSeparator` on the last item so the line doesn't dangle.
+3. Use `active` on the separator after a `completed` indicator to color the connecting segment blue — it visually links progress.
+4. Cap visible items at 5–7 in vertical mode; collapse the rest behind a "show earlier" affordance for long histories.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "torch-glare",
-  "version": "2.1.1",
+  "version": "2.1.2",
   "type": "module",
   "license": "MIT",
   "files": [
@@ -15,6 +15,10 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "build": "tsc -b",
+    "deploy": "npx tsc --build --force && npm publish --access public"
+  },
   "dependencies": {
     "commander": "^13.1.0",
     "inquirer": "^9.2.15"
@@ -23,9 +27,5 @@
     "@types/inquirer": "^9.0.7",
     "@types/node": "^22.14.0",
     "typescript": "^5.0.0"
-  },
-  "scripts": {
-    "build": "tsc -b",
-    "deploy": "npx tsc --build --force && npm publish --access public"
   }
-}
+}