@stacksjs/components 0.2.111 → 0.2.112

package/src/ui/sidebar/themes.ts

@@ -0,0 +1,288 @@
+/**
+ * Sidebar theme registry
+ *
+ * Every visual decision the sidebar makes lives here, expressed as utility
+ * classes, so a theme can be read top-to-bottom like a spec sheet.
+ *
+ * The flagship theme is `macos` — a faithful recreation of the sidebar in
+ * the latest macOS (Tahoe, macOS 26/27 "Liquid Glass"). Its metrics were
+ * measured pixel-by-pixel from Mail.app's source list at @2x:
+ *
+ *   row pitch 32px, and the highlight fills the whole 32px — AppKit leaves
+ *     no gap between rows, so consecutive selected/hovered rows touch
+ *   highlight radius 8px
+ *   label 13px · count 13px secondary gray · section header 11px semibold,
+ *     Title Case (NOT uppercase — uppercasing section headers is the single
+ *     most common tell of a web sidebar imitating macOS)
+ *   icon 17px in a fixed 22px slot · disclosure gutter 18px · child indent 16px
+ *   pane 234px wide, #f1f2f3 in light appearance, ~90% opaque so the
+ *     backdrop bleeds through faintly rather than tinting the pane
+ *
+ * Selection follows AppKit's two-state model (`selection` below): in a key
+ * window the row takes the system accent with a white label, icon and count;
+ * when the window resigns key it falls back to a neutral fill with the label
+ * left dark. Icons desaturate to gray in the same non-key state.
+ *
+ * Legacy themes (`workspace`, `desktop`, `solid`, `transparent`, `vibrancy`)
+ * are preserved verbatim from the previous variant maps. `tahoe` now aliases
+ * `macos` — it always meant "look like macOS", and now it actually does.
+ */
+
+/** macOS system colors (light appearance) for tinting sidebar icons. */
+export const macosColors = {
+  blue: '#0088ff',
+  red: '#ff383c',
+  pink: '#ff2d55',
+  orange: '#ff8d28',
+  yellow: '#ffcc00',
+  green: '#34c759',
+  teal: '#00c3d0',
+  cyan: '#00c0e8',
+  indigo: '#6155f5',
+  purple: '#cb30e0',
+  brown: '#ac7f5e',
+  gray: '#8e8e93',
+} as const
+
+export type MacosColor = keyof typeof macosColors
+
+/**
+ * How a theme paints the selected row.
+ *
+ * `accent` reproduces AppKit: the pane owns CSS custom properties for the
+ * key/non-key fills, and scoped rules recolor the row's label, icon, count
+ * and chevron together. `classes` is the older utility-class model, where
+ * `item.active` is simply added to the row element and children are left
+ * alone. Legacy themes stay on `classes` so they render exactly as before.
+ */
+export type SidebarSelectionModel = 'accent' | 'classes'
+
+/** Class groups a sidebar theme provides. All values are utility classes. */
+export interface SidebarTheme {
+  /** The <aside> pane itself: material, text color, borders. */
+  pane: string
+  /** Which selection model the Sidebar controller and scoped CSS apply. */
+  selection: SidebarSelectionModel
+  /** Extra overlay layers rendered inside the pane (visual only). */
+  layers: {
+    /** Liquid Glass edge highlight — a bright rim that subtly shimmers. */
+    shimmerRim?: boolean
+    /** Frosted material behind the pane (a real `backdrop-filter`). */
+    frosted?: boolean
+    /** Soft tint gradient blended over the material. */
+    tint?: string
+  }
+  /** Scrollable content area between header and footer. */
+  scrollArea: string
+  /** Section header row (e.g. "Favorites", "iCloud"). */
+  sectionHeader: string
+  /** Chevron inside the section header (revealed on hover). */
+  sectionChevron: string
+  /** Wrapper around a section's items. */
+  sectionGroup: string
+  /** One navigation row, layout + typography. State styles live below. */
+  item: {
+    base: string
+    hover: string
+    active: string
+    pressed: string
+    disabled: string
+    /** Fixed-width leading slot the disclosure chevron sits in. */
+    disclosure: string
+    /** Chevron glyph itself (rotates 90° when expanded). */
+    chevron: string
+    /** Fixed-width slot that centers the 17px icon. */
+    iconSlot: string
+    icon: string
+    /** Thumbnail images (album art, avatars) rendered instead of an icon. */
+    image: string
+    label: string
+    /** Right-aligned unread/item count — plain gray text on macOS. */
+    count: string
+    /** Indentation added per nesting depth. */
+    indentPerLevel: number
+  }
+}
+
+const macos: SidebarTheme = {
+  pane: [
+    // Frosted sidebar material. In a Craft window with `webSidebarMaterial`
+    // the native vibrancy shows through; in a browser the backdrop blur
+    // approximates it over whatever sits behind the pane.
+    //
+    // The opacity is deliberately high. Sampling Mail.app over a saturated
+    // blue wallpaper, the pane moved by one or two 8-bit steps (#f1f2f2 to
+    // #f1f2f3) — AppKit's sidebar material is nearly opaque and only lets a
+    // hint of the backdrop through. A half-transparent pane reads as a web
+    // imitation, and over a dark page it inverts into a dark bar entirely.
+    'bg-[#f2f2f4]/90 dark:bg-[#1c1c1e]/88',
+    'text-black dark:text-white',
+    'select-none',
+  ].join(' '),
+  selection: 'accent',
+  layers: {
+    shimmerRim: true,
+    // The blur itself is real CSS in Sidebar.stx rather than a utility.
+    // Expressed as `backdrop-blur-[50px]` / `backdrop-saturate-[180%]` the
+    // arbitrary values did not survive the stx dev server's class
+    // extraction: the pane computed `backdrop-filter: none`, and an earlier
+    // `backdrop-saturate-[1.7]` reached the generator with its brackets
+    // stripped, so it was read as a percentage and compiled to
+    // `saturate(0.017)` — draining the colour out of the whole backdrop.
+    // Crosswind parses and generates both correctly on its own, so the
+    // material is written as plain CSS to stay out of that path entirely.
+    frosted: true,
+  },
+  scrollArea: 'flex-1 overflow-y-auto overflow-x-hidden px-[10px] pb-[10px]',
+  sectionHeader: [
+    'group/section flex w-full items-center',
+    'pl-[8px] pr-[6px] pt-[16px] pb-[5px]',
+    'text-[11px] font-semibold leading-[13px]',
+    'text-[#3c3c43]/60 dark:text-[#ebebf5]/60',
+  ].join(' '),
+  sectionChevron: [
+    'i-f7-chevron-down h-[11px] w-[11px] ml-auto',
+    'text-[#3c3c43]/45 dark:text-[#ebebf5]/45',
+    'opacity-0 group-hover/section:opacity-100 transition-opacity duration-150',
+    'transition-transform duration-200',
+  ].join(' '),
+  // No gap: AppKit rows are contiguous, the 32px pitch IS the row.
+  sectionGroup: 'flex flex-col',
+  item: {
+    base: [
+      'flex w-full items-center',
+      'h-[32px] rounded-[8px] pl-[4px] pr-[8px]',
+      'text-[13px] leading-[16px] font-normal',
+      'text-black dark:text-white',
+      'transition-colors duration-150 ease-out',
+      'cursor-default',
+    ].join(' '),
+    hover: 'hover:bg-black/4 dark:hover:bg-white/6',
+    // Selection is painted by the `accent` model in Sidebar.stx's scoped CSS,
+    // which has to recolor the label, icon and count together. Leaving this
+    // empty keeps the controller from also stacking a conflicting background.
+    active: '',
+    pressed: 'active:bg-black/10 dark:active:bg-white/18',
+    disabled: 'opacity-40 pointer-events-none',
+    disclosure: 'flex h-[16px] w-[18px] shrink-0 items-center justify-center',
+    chevron: [
+      'i-f7-chevron-right h-[11px] w-[11px]',
+      'text-[#3c3c43]/55 dark:text-[#ebebf5]/55',
+      'transition-transform duration-200 ease-out',
+    ].join(' '),
+    iconSlot: 'flex h-[20px] w-[22px] shrink-0 items-center justify-center mr-[7px]',
+    icon: 'h-[17px] w-[17px]',
+    image: 'h-[20px] w-[20px] rounded-[4px] object-cover shadow-sm',
+    label: 'flex-1 truncate text-left',
+    count: [
+      'ml-[8px] shrink-0 tabular-nums',
+      'text-[13px] leading-[16px]',
+      'text-[#3c3c43]/60 dark:text-[#ebebf5]/60',
+    ].join(' '),
+    indentPerLevel: 16,
+  },
+}
+
+/**
+ * Legacy themes carried over from the old per-component variant maps so
+ * existing apps keep rendering identically. New work should use `macos`.
+ */
+const workspace: SidebarTheme = {
+  selection: 'classes',
+  pane: 'bg-[#f4f4f3] dark:bg-neutral-950 text-zinc-950 dark:text-white select-none',
+  layers: {},
+  scrollArea: 'flex-1 overflow-y-auto overflow-x-hidden px-5 py-5',
+  sectionHeader: 'group/section flex w-full items-center gap-2.5 px-4 pb-2 pt-5 text-[13px] font-semibold uppercase tracking-[0.12em] text-zinc-400 dark:text-zinc-500',
+  sectionChevron: 'i-f7-chevron-down h-3 w-3 ml-auto opacity-0 group-hover/section:opacity-100 transition-opacity duration-150 transition-transform duration-200',
+  sectionGroup: 'flex flex-col space-y-1',
+  item: {
+    base: 'flex w-full items-center gap-3 rounded-[16px] px-3.5 py-2 text-[14px] leading-tight transition-colors duration-150',
+    hover: 'hover:bg-[#ececea] hover:text-zinc-950 dark:hover:bg-white/10',
+    active: 'bg-[#e7e7e5] text-zinc-950 dark:bg-white/12 dark:text-white',
+    pressed: 'active:bg-[#e2e2e0] dark:active:bg-white/15',
+    disabled: 'opacity-50 pointer-events-none',
+    disclosure: 'flex h-4 w-4 shrink-0 items-center justify-center',
+    chevron: 'i-f7-chevron-right h-3 w-3 opacity-50 transition-transform duration-200',
+    iconSlot: 'flex h-5 w-5 shrink-0 items-center justify-center',
+    icon: 'h-[18px] w-[18px] text-zinc-500 dark:text-zinc-500',
+    image: 'h-5 w-5 rounded object-cover',
+    label: 'flex-1 truncate text-left text-zinc-700 dark:text-zinc-300',
+    count: 'ml-auto grid h-5 min-w-5 place-items-center rounded-full bg-white/70 px-1.5 text-[11px] font-medium text-zinc-500 shadow-sm dark:bg-white/10 dark:text-zinc-400',
+    indentPerLevel: 12,
+  },
+}
+
+const desktop: SidebarTheme = {
+  selection: 'classes',
+  pane: 'bg-[#f3f3f1]/48 dark:bg-neutral-950/32 backdrop-blur-3xl backdrop-saturate-150 text-zinc-950 dark:text-white select-none',
+  layers: {
+    tint: 'bg-[linear-gradient(112deg,rgba(255,255,255,0.20)_0%,rgba(255,255,255,0.04)_45%,rgba(226,226,222,0.16)_100%)] dark:bg-[linear-gradient(112deg,rgba(255,255,255,0.08)_0%,rgba(255,255,255,0.02)_46%,rgba(255,255,255,0.06)_100%)]',
+  },
+  scrollArea: 'flex-1 overflow-y-auto overflow-x-hidden px-5 py-2',
+  sectionHeader: 'group/section flex w-full items-center gap-2.5 px-3 pb-1.5 pt-3 rounded-[14px] text-[12px] font-semibold uppercase tracking-[0.10em] text-zinc-500/80 dark:text-zinc-400/80',
+  sectionChevron: 'i-f7-chevron-down h-3 w-3 ml-auto opacity-0 group-hover/section:opacity-100 transition-opacity duration-150 transition-transform duration-200',
+  sectionGroup: 'flex flex-col space-y-1',
+  item: {
+    base: 'flex w-full items-center gap-3 rounded-[14px] px-3 py-1.5 text-[13.5px] leading-tight transition-colors duration-150',
+    hover: 'hover:bg-white/38 hover:text-zinc-950 dark:hover:bg-white/10',
+    active: 'bg-[#e8e8e6]/90 text-zinc-950 dark:bg-white/12 dark:text-white',
+    pressed: 'active:bg-white/50 dark:active:bg-white/15',
+    disabled: 'opacity-50 pointer-events-none',
+    disclosure: 'flex h-4 w-4 shrink-0 items-center justify-center',
+    chevron: 'i-f7-chevron-right h-3 w-3 opacity-50 transition-transform duration-200',
+    iconSlot: 'flex h-5 w-5 shrink-0 items-center justify-center',
+    icon: 'h-[18px] w-[18px] text-zinc-600 dark:text-zinc-400',
+    image: 'h-5 w-5 rounded object-cover',
+    label: 'flex-1 truncate text-left text-zinc-700 dark:text-zinc-300',
+    count: 'ml-auto grid h-5 min-w-5 place-items-center rounded-full bg-white/72 px-1.5 text-[11px] font-medium text-zinc-500 shadow-sm dark:bg-white/10 dark:text-zinc-400',
+    indentPerLevel: 12,
+  },
+}
+
+const solid: SidebarTheme = {
+  ...macos,
+  pane: 'bg-stone-100 dark:bg-neutral-900 text-black dark:text-white select-none',
+  layers: {},
+}
+
+const transparent: SidebarTheme = {
+  ...macos,
+  pane: 'bg-transparent text-black dark:text-white select-none',
+  layers: {},
+}
+
+const vibrancy: SidebarTheme = {
+  ...macos,
+  pane: 'bg-white/50 dark:bg-black/40 backdrop-blur-3xl backdrop-saturate-200 text-black dark:text-white select-none',
+  layers: {},
+}
+
+export const sidebarThemes: Record<string, SidebarTheme> = {
+  macos,
+  // Historical names people may still pass — all render the macOS look.
+  'tahoe': macos,
+  'macos-tahoe': macos,
+  'macos-latest': macos,
+  workspace,
+  desktop,
+  solid,
+  transparent,
+  vibrancy,
+}
+
+export type SidebarThemeName = keyof typeof sidebarThemes
+
+export function resolveSidebarTheme(name?: string): SidebarTheme {
+  return sidebarThemes[name || 'macos'] || sidebarThemes.macos
+}
+
+/**
+ * Resolve an item's icon tint. Accepts a macOS system color name
+ * (`"blue"`, `"red"`, …) or any CSS color, and falls back to the
+ * theme's default icon color when unset.
+ */
+export function resolveIconColor(color?: string): string | undefined {
+  if (!color)
+    return undefined
+  return macosColors[color as MacosColor] || color
+}

package/src/ui/skeleton/Skeleton.stx

@@ -0,0 +1,48 @@
+<script server>
+export const variant = $props.variant || 'text'
+export const count = $props.count || 1
+export const width = $props.width || ''
+export const height = $props.height || ''
+export const circle = $props.circle || false
+export const className = $props.className || ''
+export const animate = $props.animate ?? true
+
+// Variant classes
+const variantClasses = {
+  text: 'h-4 rounded',
+  title: 'h-8 rounded',
+  avatar: 'w-10 h-10 rounded-full',
+  thumbnail: 'w-24 h-24 rounded-md',
+  button: 'h-10 w-32 rounded-md',
+  card: 'h-64 rounded-lg',
+  rect: 'rounded-md',
+}
+
+// Animation classes
+const animationClasses = animate ? 'animate-pulse' : ''
+
+// Build base classes
+const baseClasses = circle ? 'rounded-full' : variantClasses[variant]
+
+// Build style object
+let styleString = ''
+if (width) {
+  styleString += `width: ${typeof width === 'number' ? width + 'px' : width};`
+}
+if (height) {
+  styleString += `height: ${typeof height === 'number' ? height + 'px' : height};`
+}
+
+export const skeletonClasses = `bg-gray-200 dark:bg-gray-700 ${baseClasses} ${animationClasses} ${className}`.trim()
+export const containerClasses = count > 1 ? 'space-y-3' : ''
+</script>
+
+@if(count > 1)
+  <div class="{{ containerClasses }}">
+    @for(i = 0; i < count; i++)
+      <div class="{{ skeletonClasses }}" style="{{ styleString }}" aria-busy="true" aria-live="polite"></div>
+    @endfor
+  </div>
+@else
+  <div class="{{ skeletonClasses }}" style="{{ styleString }}" aria-busy="true" aria-live="polite"></div>
+@endif

package/src/ui/skeleton/index.ts

@@ -0,0 +1,11 @@
+export { default as Skeleton } from './Skeleton.stx'
+
+export interface SkeletonProps {
+  variant?: 'text' | 'title' | 'avatar' | 'thumbnail' | 'button' | 'card' | 'rect'
+  count?: number
+  width?: string | number
+  height?: string | number
+  circle?: boolean
+  animate?: boolean
+  className?: string
+}

package/src/ui/spinner/Spinner.stx

@@ -0,0 +1,109 @@
+<script server>
+export const variant = $props.variant || 'circle'
+export const size = $props.size || 'md'
+export const color = $props.color || 'primary'
+export const label = $props.label || ''
+export const className = $props.className || ''
+
+// Size classes
+const sizeClasses = {
+  xs: 'w-3 h-3',
+  sm: 'w-4 h-4',
+  md: 'w-6 h-6',
+  lg: 'w-8 h-8',
+  xl: 'w-12 h-12',
+}
+
+// Color classes
+const colorClasses = {
+  primary: 'text-blue-600 dark:text-blue-500',
+  secondary: 'text-purple-600 dark:text-purple-500',
+  success: 'text-green-600 dark:text-green-500',
+  warning: 'text-yellow-600 dark:text-yellow-500',
+  danger: 'text-red-600 dark:text-red-500',
+  info: 'text-cyan-600 dark:text-cyan-500',
+  white: 'text-white',
+  gray: 'text-gray-600 dark:text-gray-400',
+}
+
+export const containerClasses = `inline-flex flex-col items-center gap-2 ${className}`.trim()
+export const spinnerClasses = `${sizeClasses[size]} ${colorClasses[color]} animate-spin`.trim()
+export const labelClasses = `text-sm font-medium text-gray-700 dark:text-gray-300`.trim()
+
+// Dots size classes
+const dotsSizeClasses = {
+  xs: 'w-1 h-1',
+  sm: 'w-1.5 h-1.5',
+  md: 'w-2 h-2',
+  lg: 'w-2.5 h-2.5',
+  xl: 'w-3 h-3',
+}
+
+const dotsColorClasses = {
+  primary: 'bg-blue-600 dark:bg-blue-500',
+  secondary: 'bg-purple-600 dark:bg-purple-500',
+  success: 'bg-green-600 dark:bg-green-500',
+  warning: 'bg-yellow-600 dark:bg-yellow-500',
+  danger: 'bg-red-600 dark:bg-red-500',
+  info: 'bg-cyan-600 dark:bg-cyan-500',
+  white: 'bg-white',
+  gray: 'bg-gray-600 dark:bg-gray-400',
+}
+
+export const dotClasses = `${dotsSizeClasses[size]} ${dotsColorClasses[color]} rounded-full`.trim()
+</script>
+
+<div class="{{ containerClasses }}" role="status" aria-live="polite" aria-busy="true">
+  @if(variant === 'circle')
+    <!-- Circle spinner (default) -->
+    <svg class="{{ spinnerClasses }}" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24">
+      <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
+      <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
+    </svg>
+  @elseif(variant === 'dots')
+    <!-- Dots spinner -->
+    <div class="flex items-center gap-1">
+      <div class="{{ dotClasses }}" style="animation: bounce 1.4s infinite ease-in-out both; animation-delay: -0.32s"></div>
+      <div class="{{ dotClasses }}" style="animation: bounce 1.4s infinite ease-in-out both; animation-delay: -0.16s"></div>
+      <div class="{{ dotClasses }}" style="animation: bounce 1.4s infinite ease-in-out both"></div>
+    </div>
+  @elseif(variant === 'bars')
+    <!-- Bars spinner -->
+    <div class="flex items-center gap-1">
+      <div class="w-1 bg-current rounded-full" style="height: {{ size === 'xs' ? '8px' : size === 'sm' ? '12px' : size === 'md' ? '16px' : size === 'lg' ? '20px' : '24px' }}; animation: bars 1.2s infinite ease-in-out; animation-delay: -0.24s"></div>
+      <div class="w-1 bg-current rounded-full" style="height: {{ size === 'xs' ? '8px' : size === 'sm' ? '12px' : size === 'md' ? '16px' : size === 'lg' ? '20px' : '24px' }}; animation: bars 1.2s infinite ease-in-out; animation-delay: -0.12s"></div>
+      <div class="w-1 bg-current rounded-full" style="height: {{ size === 'xs' ? '8px' : size === 'sm' ? '12px' : size === 'md' ? '16px' : size === 'lg' ? '20px' : '24px' }}; animation: bars 1.2s infinite ease-in-out"></div>
+    </div>
+  @elseif(variant === 'ring')
+    <!-- Ring spinner -->
+    <div class="{{ spinnerClasses }}" style="border: 2px solid currentColor; border-top-color: transparent; border-radius: 50%;"></div>
+  @endif
+
+  @if(label)
+    <span class="{{ labelClasses }}">{{ label }}</span>
+  @endif
+
+  <span class="sr-only">{{ label || 'Loading...' }}</span>
+</div>
+
+<style>
+@keyframes bounce {
+  0%, 80%, 100% {
+    transform: scale(0);
+    opacity: 0.5;
+  }
+  40% {
+    transform: scale(1);
+    opacity: 1;
+  }
+}
+
+@keyframes bars {
+  0%, 40%, 100% {
+    transform: scaleY(0.4);
+  }
+  20% {
+    transform: scaleY(1);
+  }
+}
+</style>

package/src/ui/spinner/index.ts

@@ -0,0 +1,9 @@
+export { default as Spinner } from './Spinner.stx'
+
+export interface SpinnerProps {
+  variant?: 'circle' | 'dots' | 'bars' | 'ring'
+  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+  color?: 'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info' | 'white' | 'gray'
+  label?: string
+  className?: string
+}

package/src/ui/stepper/README.md

@@ -0,0 +1,36 @@
+# Stepper Component
+
+A step-by-step progress indicator for multi-step processes.
+
+## Installation
+
+```bash
+bun add @stacksjs/components
+```
+
+## Usage
+
+```stx
+<script server>
+let currentStep = 0
+
+function handleStepClick(step) {
+  currentStep = step
+}
+</script>
+
+<Stepper :currentStep="currentStep">
+  <StepperStep :stepNumber="0" :currentStep="currentStep" label="Account" :onClick="handleStepClick" />
+  <StepperStep :stepNumber="1" :currentStep="currentStep" label="Profile" :onClick="handleStepClick" />
+  <StepperStep :stepNumber="2" :currentStep="currentStep" label="Confirmation" :onClick="handleStepClick" />
+</Stepper>
+```
+
+## Features
+
+- Horizontal and vertical orientation
+- Clickable steps
+- Complete/current/upcoming states
+- Dark mode support
+- Accessible
+- Customizable styling

package/src/ui/stepper/Stepper.stx

@@ -0,0 +1,17 @@
+<script server>
+export const currentStep = $props.currentStep || 0
+export const orientation = $props.orientation || 'horizontal'
+export const className = $props.className || ''
+export const as = $props.as || 'div'
+
+const orientationClasses = orientation === 'horizontal'
+  ? 'flex flex-row'
+  : 'flex flex-col'
+
+const baseClasses = 'w-full'
+const stepperClasses = `${baseClasses} ${orientationClasses} ${className}`.trim()
+</script>
+
+<component :is="{{ as }}" class="{{ stepperClasses }}">
+  <slot :currentStep="currentStep" />
+</component>

package/src/ui/stepper/StepperStep.stx

@@ -0,0 +1,57 @@
+<script server>
+export const stepNumber = $props.stepNumber
+export const currentStep = $props.currentStep || 0
+export const label = $props.label || ''
+export const description = $props.description || ''
+export const className = $props.className || ''
+export const as = $props.as || 'div'
+
+export const isComplete = stepNumber < currentStep
+export const isCurrent = stepNumber === currentStep
+export const isUpcoming = stepNumber > currentStep
+
+const baseClasses = 'flex items-center'
+export const stepClasses = `${baseClasses} ${className}`.trim()
+</script>
+
+<script client>
+const emit = defineEmits()
+const stepNumber = {{ stepNumber }}
+
+function onClick() {
+  emit('click', stepNumber)
+}
+</script>
+
+<component :is="{{ as }}" class="{{ stepClasses }}">
+  <button
+    type="button"
+    @click="onClick()"
+    class="flex items-center gap-3 focus:outline-none focus-visible:ring-2 focus-visible:ring-blue-500 rounded-lg p-2"
+  >
+    <div class="{{ isComplete ? 'bg-blue-600 dark:bg-blue-500' : isCurrent ? 'bg-blue-600 dark:bg-blue-500 ring-4 ring-blue-200 dark:ring-blue-800' : 'bg-neutral-300 dark:bg-neutral-600' }} w-10 h-10 rounded-full flex items-center justify-center text-white font-semibold transition-all">
+      @if(isComplete)
+        <svg class="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M5 13l4 4L19 7" />
+        </svg>
+      @else
+        {{ stepNumber + 1 }}
+      @endif
+    </div>
+
+    @if(label)
+      <div class="text-left">
+        <div class="text-sm font-medium {{ isCurrent ? 'text-blue-600 dark:text-blue-400' : 'text-neutral-900 dark:text-white' }}">
+          {{ label }}
+        </div>
+        @if(description)
+          <div class="text-xs text-neutral-500 dark:text-neutral-400">
+            {{ description }}
+          </div>
+        @endif
+      </div>
+    @endif
+  </button>
+
+  <slot :isComplete="isComplete" :isCurrent="isCurrent" :isUpcoming="isUpcoming" />
+</component>

package/src/ui/stepper/index.ts

@@ -0,0 +1,19 @@
+export { default as Stepper } from './Stepper.stx'
+export { default as StepperStep } from './StepperStep.stx'
+
+export interface StepperProps {
+  currentStep?: number
+  orientation?: 'horizontal' | 'vertical'
+  className?: string
+  as?: string
+}
+
+export interface StepperStepProps {
+  stepNumber: number
+  currentStep?: number
+  label?: string
+  description?: string
+  className?: string
+  as?: string
+  onClick?: (step: number) => void
+}