cyberui-2045 2.1.1 → 2.3.0

package/AGENT.md

@@ -31,9 +31,11 @@ import "cyberui-2045/styles.css";
 | `Input` | Cyberpunk text input with focus glows. |
 | `Modal` | CRT-style modal dialog. |
 | `Notification` | Toast notifications. Use `useCyberNotifications` hook. |
-| `CircularProgress` | Dual-ring progress indicator. |
+| `CircularProgress` | Dual-ring circular progress indicator. |
+| `LinearProgress` | Smooth horizontal progress bar. |
+| `SegmentedProgress` | Segmented progress: `variant="radial"` (circular arc gauge, default) or `variant="block"` (discrete filled blocks ▮▮▮▯▯). |
 | `TabNavigation` | Animated tab bar. |
-| `Badge` | Status indicator. Variants: `default`, `success`, `warning`, `danger`. |
+| `Badge` | Status indicator. Variants: `primary`, `secondary`, `accent`, `success`, `error`, `warning`. |
 | `Toggle` | Cyberpunk switch. |
 | `Select` | Styled dropdown. |
 | `Skeleton` | Loading placeholder. |

package/bin/usage-content.js

@@ -1,120 +1,210 @@
-// Consumer-facing AI usage guide for cyberui-2045.
-// Injected into CLAUDE.md / .cursorrules / copilot-instructions.md by `init`.
-
-export function getUsageContent(version = '1.4.0') {
-  return `## CyberUI (cyberui-2045 v${version})
-
-Cyberpunk-themed React UI library. Docs & live examples: https://patrickkuei.github.io/CyberUI
-
-### Setup
-
-\`\`\`bash
-npm install cyberui-2045
-\`\`\`
-
-\`\`\`tsx
-// Import styles once in your app entry (e.g. main.tsx)
-import 'cyberui-2045/styles.css';
-
-// Import components
-import { Button, Card, Modal } from 'cyberui-2045';
-\`\`\`
-
-### Component Reference
-
-| Component | Category | Storybook |
-|-----------|----------|-----------|
-| Button | Forms | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-button--docs |
-| Input | Forms | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-input--docs |
-| Select | Forms | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-select--docs |
-| Toggle | Forms | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-toggle--docs |
-| Card | Layout | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-card--docs |
-| Modal | Layout | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-modal--docs |
-| Badge | Feedback | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-badge--docs |
-| Notification | Feedback | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-notification--docs |
-| Skeleton | Feedback | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-skeleton--docs |
-| CircularProgress | Progress | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-circularprogress--docs |
-| LinearProgress | Progress | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-linearprogress--docs |
-| SegmentedProgress | Progress | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-segmentedprogress--docs |
-| TabNavigation | Navigation | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-tabnavigation--docs |
-| Carousel | Navigation | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-carousel--docs |
-| Image | Media | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-image--docs |
-| Checkbox | Forms | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-checkbox--docs |
-| Divider | Layout | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-divider--docs |
-| GradientText | Typography | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-gradienttext--docs |
-| SectionTitle | Typography | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-sectiontitle--docs |
-| Steps | Navigation | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-steps--docs |
-| Timeline | Display | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-timeline--docs |
-
-### Hooks
-
-\`\`\`tsx
-import { useCyberNotifications, useAnimatedProgress, useCyberScrollbar } from 'cyberui-2045';
-
-// Trigger toast notifications
-const { notify } = useCyberNotifications();
-notify({ message: 'Hack complete', variant: 'success' });
-
-// Animated numeric counter for progress displays
-const value = useAnimatedProgress(targetValue, { duration: 800 });
-
-// Apply cyberpunk scrollbar styles to an element
-const ref = useCyberScrollbar<HTMLDivElement>();
-\`\`\`
-
-### Notifications (requires provider)
-
-\`\`\`tsx
-import { CyberNotificationProvider, useCyberNotifications } from 'cyberui-2045';
-
-// Wrap your app
-<CyberNotificationProvider>
-  <App />
-</CyberNotificationProvider>
-
-// Then anywhere inside:
-const { notify } = useCyberNotifications();
-notify({ message: 'Access granted', variant: 'success', duration: 3000 });
-// variants: 'primary' | 'secondary' | 'accent' | 'success' | 'error' | 'warning'
-\`\`\`
-
-### Theming — CSS token overrides
-
-Override in your global CSS (after importing cyberui-2045/styles.css):
-
-\`\`\`css
-:root {
-  --color-primary: #ff0055;      /* neon pink  */
-  --color-secondary: #00fff9;    /* cyan       */
-  --color-accent: #fbff00;       /* yellow     */
-  --color-success: #00ff88;      /* green      */
-  --color-error: #ff4444;        /* red        */
-  --color-warning: #ff8800;      /* orange     */
-  --color-background: #0a0a0f;   /* dark bg    */
-  --color-surface: #12121a;      /* card bg    */
-  --color-border: #2a2a3a;       /* borders    */
-  --color-text: #e0e0ff;         /* body text  */
-  --color-text-muted: #6b6b8a;   /* muted text */
-}
-\`\`\`
-
-### className overrides
-
-All components accept a \`className\` prop. Classes are merged via \`twMerge\` — your classes win on conflict.
-
-\`\`\`tsx
-// Layout overrides (safe — doesn't break variant identity)
-<Button className="w-full mt-4">Submit</Button>
-
-// Color/variant overrides (you own visual coherence)
-<Button variant="primary" className="bg-purple-600">Custom</Button>
-\`\`\`
-
-### cn() utility (re-exported)
-
-\`\`\`tsx
-import { cn } from 'cyberui-2045';
-// clsx + tailwind-merge — use for composing className strings in your own components
-const cls = cn('base-class', isActive && 'active', className);
-\`\`\``;
-}
+// Consumer-facing AI usage guide for cyberui-2045.
+// Injected into CLAUDE.md / .cursorrules / copilot-instructions.md by `init`.
+
+export function getUsageContent(version = '2.2.0') {
+  return `## CyberUI (cyberui-2045 v${version})
+
+Cyberpunk-themed React UI library. Docs & live examples: https://patrickkuei.github.io/CyberUI/storybook/
+
+### Setup
+
+\`\`\`bash
+npm install cyberui-2045
+\`\`\`
+
+\`\`\`tsx
+// ⚠️ REQUIRED: import styles once in your app entry (e.g. main.tsx / index.tsx)
+// Without this ALL components lose colors, backgrounds, and animations.
+import 'cyberui-2045/styles.css';
+
+// Import components — always from the root, never from subpaths
+import { Button, Card, Modal } from 'cyberui-2045';
+\`\`\`
+
+⚠️ Do NOT import from \`cyberui-2045/components/Button\` or similar subpaths — root only.
+⚠️ If styles look broken or text is invisible, \`cyberui-2045/styles.css\` is missing from the app entry.
+
+### Component Reference
+
+| Component | Category | Storybook |
+|-----------|----------|-----------|
+| Button | Forms | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-button--docs |
+| Input | Forms | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-input--docs |
+| Select | Forms | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-select--docs |
+| Toggle | Forms | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-toggle--docs |
+| Checkbox | Forms | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-checkbox--docs |
+| Card | Layout | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-card--docs |
+| Modal | Layout | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-modal--docs |
+| Divider | Layout | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-divider--docs |
+| Badge | Feedback | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-badge--docs |
+| Notification | Feedback | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-notification--docs |
+| Skeleton | Feedback | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-skeleton--docs |
+| CircularProgress | Progress | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-circularprogress--docs |
+| LinearProgress | Progress | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-linearprogress--docs |
+| SegmentedProgress | Progress | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-segmentedprogress--docs |
+| TabNavigation | Navigation | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-tabnavigation--docs |
+| Carousel | Navigation | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-carousel--docs |
+| Steps | Navigation | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-steps--docs |
+| GradientText | Typography | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-gradienttext--docs |
+| SectionTitle | Typography | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-sectiontitle--docs |
+| Timeline | Display | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-timeline--docs |
+| Image | Media | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-image--docs |
+
+### Critical API notes (read before coding)
+
+\`\`\`tsx
+// Button — variants: 'primary' | 'secondary' | 'danger' | 'ghost'  (NO 'accent')
+<Button variant="primary">Jack In</Button>
+<Button variant="danger">Purge</Button>
+
+// Badge — uses children, NOT a label prop
+<Badge variant="success">Online</Badge>
+<Badge variant="error">Offline</Badge>
+// variants: 'primary' | 'secondary' | 'accent' | 'success' | 'error' | 'warning'
+
+// CircularProgress — use size prop (sm/md/lg/xl); prop is 'progress' not 'value'
+// center content goes as children; do NOT pass a large radius — default 20 is correct
+<CircularProgress progress={75} size="md">
+  <span className="text-xs font-mono text-accent">75%</span>
+</CircularProgress>
+
+// LinearProgress — prop is 'progress' (not 'value'); fills container width (w-full) by default
+// wrap in a constrained div to control width
+<LinearProgress progress={60} />
+<div className="w-64"><LinearProgress progress={60} /></div>
+
+// SegmentedProgress — two variants:
+//   variant="radial" (default): circular arc-segment gauge; children render in the center
+//   variant="block": linear discrete-block bar (▮▮▮▯▯); use segments prop (default 10)
+// Both support size prop (sm/md/lg/xl)
+<SegmentedProgress progress={80} size="md">
+  <span className="text-accent font-bold text-xs">80%</span>
+</SegmentedProgress>
+<SegmentedProgress variant="block" progress={60} segments={10} size="md" />
+
+// TabNavigation — tabs is a plain string array (NOT {id, label}[])
+<TabNavigation
+  tabs={['Overview', 'Stats', 'History']}
+  activeTab="Overview"
+  onTabChange={setTab}
+/>
+
+// SectionTitle — NO subtitle prop; use children for the heading text
+<SectionTitle>System Status</SectionTitle>
+
+// Select — use onValueChange for a simple string callback (like Toggle/Checkbox pattern)
+// or use standard HTML onChange for the raw event
+<Select
+  options={[{ value: 'a', label: 'Option A' }]}
+  onValueChange={(val) => setSelected(val)}
+/>
+
+// Toggle — onChange receives boolean directly
+<Toggle checked={on} onChange={setOn} />
+
+// Checkbox — use onCheckedChange for a simple boolean callback
+<Checkbox checked={val} onCheckedChange={setVal} />
+
+// Modal — default size is 'lg' (672px); use 'xl' for forms/tables, 'sm' only for simple alerts
+// variant="danger" for destructive confirmations
+<Modal title="Settings" size="lg" isOpen={open} onClose={close}>
+  content here
+</Modal>
+<Modal variant="danger" title="Delete?" size="md" onConfirm={handleDelete} onCancel={close}>
+  This cannot be undone.
+</Modal>
+
+// Card — supports onClick and all standard div HTML attributes
+<Card onClick={() => select(item)}>content</Card>
+
+// Image — preview={true} must be explicit to enable click-to-expand fullscreen (disabled by default)
+<Image src="/photo.jpg" alt="Description" size="md" preview={true} />
+
+// Carousel — images takes CarouselImageData[]: { src, alt, fallbackSrc?, caption? }
+<Carousel
+  images={[
+    { src: 'img1.jpg', alt: 'Cyber City', caption: 'Night District' },
+    { src: 'img2.jpg', alt: 'Neon Lights', fallbackSrc: 'fallback.jpg' }
+  ]}
+  currentIndex={idx}
+  onIndexChange={setIdx}
+/>
+
+// Steps — current is 0-BASED. First step = current={0}, second = current={1}.
+// Passing 1-based values is a common mistake that skips the first step.
+<Steps
+  current={0}
+  items={[{ title: 'Login' }, { title: 'Verify' }, { title: 'Complete' }]}
+/>
+\`\`\`
+
+### Hooks
+
+\`\`\`tsx
+import { useCyberNotifications, useAnimatedProgress, useCyberScrollbar } from 'cyberui-2045';
+
+// Toast notifications — showNotification(type, title, message, options?)
+// type: 'success' | 'warning' | 'error'
+const { showNotification } = useCyberNotifications();
+showNotification('success', 'Access Granted', 'Welcome back, runner.');
+showNotification('error', 'Breach Detected', 'Sector 7 compromised.', { duration: 5000 });
+
+// Oscillating value for loading/pulse animations (min → max → min loop)
+const value = useAnimatedProgress({ min: 5, max: 95, speed: 30 });
+
+// Apply cyberpunk scrollbar styles to a scrollable element
+const ref = useCyberScrollbar<HTMLDivElement>();
+\`\`\`
+
+### Notifications (requires provider)
+
+\`\`\`tsx
+import { CyberNotificationProvider, useCyberNotifications } from 'cyberui-2045';
+
+// Wrap your app once
+<CyberNotificationProvider>
+  <App />
+</CyberNotificationProvider>
+
+// Then anywhere inside:
+const { showNotification } = useCyberNotifications();
+showNotification('success', 'Upload Complete', 'Neural data synced.');
+\`\`\`
+
+### Theming — CSS token overrides
+
+Override in your global CSS (after importing cyberui-2045/styles.css):
+
+\`\`\`css
+:root {
+  --color-primary: #ff005d;        /* neon pink  */
+  --color-secondary: #00fff9;      /* cyan       */
+  --color-accent: #fffb00;         /* yellow     */
+  --color-success: #00ff9e;        /* green      */
+  --color-error: #ff4f4f;          /* red        */
+  --color-warning: #ffaa00;        /* orange     */
+  --color-base: #1a1a2e;           /* page background */
+  --color-surface: #2d2d44;        /* card / component surface */
+  --color-border-default: #3c3c5e; /* borders    */
+  --color-default: #e0e0e0;        /* primary text */
+  --color-muted: #8888aa;          /* secondary text */
+  --color-inverse: #1a1a2e;        /* inverted text */
+}
+\`\`\`
+
+### className overrides
+
+All components accept a \`className\` prop merged via \`tailwind-merge\` — your classes win on conflict.
+
+\`\`\`tsx
+<Button className="w-full mt-4">Full width</Button>
+\`\`\`
+
+### cn() utility (re-exported)
+
+\`\`\`tsx
+import { cn } from 'cyberui-2045';
+// clsx + tailwind-merge — compose className strings in your own components
+const cls = cn('base-class', isActive && 'active', className);
+\`\`\``;
+}

package/dist/components/Carousel.d.ts

@@ -38,11 +38,11 @@ export interface CarouselCallbacks {
  * Props for the CyberUI Carousel component
  *
  * @example
- * // Basic carousel
+ * // Basic carousel — images is CarouselImageData[]: { src, alt, fallbackSrc?, caption? }
  * <Carousel
  *   images={[
- *     { src: 'img1.jpg', alt: 'Cyber City' },
- *     { src: 'img2.jpg', alt: 'Neon Lights' }
+ *     { src: 'img1.jpg', alt: 'Cyber City', caption: 'Night District' },
+ *     { src: 'img2.jpg', alt: 'Neon Lights', fallbackSrc: 'fallback.jpg' }
  *   ]}
  *   currentIndex={index}
  *   onChange={setIndex}

package/dist/components/CircularProgress.d.ts

@@ -2,13 +2,18 @@ import { default as React } from 'react';
 /**
  * A circular progress indicator with neon glow effects.
  *
+ * Use the `size` prop for common cases — it constrains the container automatically.
+ * Only use `radius` if you need a custom size (radius is in SVG units, viewBox is 50×50).
+ *
  * @example
- * // Basic progress
- * <CircularProgress progress={75} radius={40} />
+ * // Recommended: use size prop
+ * <CircularProgress progress={75} size="md">
+ *   <span className="text-xs font-mono text-accent">75%</span>
+ * </CircularProgress>
  *
  * @example
- * // Progress with label
- * <CircularProgress progress={45} radius={60}>
+ * // Custom size via className
+ * <CircularProgress progress={45} className="w-32 h-32">
  *   <span className="text-accent font-bold">45%</span>
  * </CircularProgress>
  */
@@ -18,9 +23,17 @@ export interface CircularProgressProps {
      */
     progress: number;
     /**
-     * Radius of the circle in pixels.
+     * Preset container size. Sets width and height of the component automatically.
+     * - sm: 64px, md: 96px, lg: 128px, xl: 160px
+     * @default 'md'
+     */
+    size?: 'sm' | 'md' | 'lg' | 'xl';
+    /**
+     * Radius of the SVG circle in SVG units (viewBox is 50×50, center at 25,25).
+     * Default 20 fits cleanly within the viewBox. Only override for custom layouts.
+     * @default 20
      */
-    radius: number;
+    radius?: number;
     /** Optional custom class name */
     className?: string;
     /** Optional content to render in the center of the circle */
@@ -32,7 +45,7 @@ export interface CircularProgressProps {
  * A beautiful circular progress indicator with neon glow and dual-tone stroke.
  *
  * @example
- * <CircularProgress progress={60} radius={20}>
+ * <CircularProgress progress={60} size="md">
  *   <span className="text-xs font-mono">60%</span>
  * </CircularProgress>
  */

package/dist/components/Image.d.ts

@@ -55,7 +55,11 @@ export interface ImageProps extends Omit<React.ImgHTMLAttributes<HTMLImageElemen
     alt: string;
     /** Size of the image container */
     size?: ResponsiveValue<ImageSize>;
-    /** Enable click-to-expand preview functionality */
+    /**
+     * Enable click-to-expand fullscreen preview on click.
+     * Must be explicitly set to `true` — disabled by default.
+     * @default false
+     */
     preview?: boolean;
     /** Fallback image URL when main image fails to load */
     fallback?: string;

package/dist/components/LinearProgress.d.ts

@@ -31,14 +31,18 @@ export interface LinearProgressProps {
 /**
  * A sleek, animated linear progress bar with cyberpunk aesthetic.
  *
+ * The bar is `w-full` by default — it fills its container width.
+ * Wrap it in a constrained element to control its width.
+ *
  * @example
- * <LinearProgress progress={75} variant="primary" />
+ * // Full-width bar (fills parent)
+ * <LinearProgress progress={75} />
  *
  * @example
- * <LinearProgress
- *   progress={kbytesLoaded}
- *   size={{ base: 'sm', lg: 'md' }}
- * />
+ * // Width-constrained
+ * <div className="w-64">
+ *   <LinearProgress progress={kbytesLoaded} size={{ base: 'sm', lg: 'md' }} />
+ * </div>
  */
 declare const LinearProgress: React.FC<LinearProgressProps>;
 export default LinearProgress;

package/dist/components/Modal.d.ts

@@ -1,12 +1,32 @@
 import { default as React } from 'react';
+/**
+ * Controls CRT animation timing and effects.
+ * Pass this as the `animation` prop on `<Modal>`:
+ * ```tsx
+ * <Modal animation={{ openDuration: 300, crtEffects: false }} ... />
+ * ```
+ */
 export interface ModalAnimationConfig {
+    /** Duration of the open (CRT boot) animation in ms. @default 600 */
     openDuration?: number;
+    /** Duration of the close (CRT off) animation in ms. @default 400 */
     closeDuration?: number;
+    /** Enable CRT scanline power-on/off effects. @default true */
     crtEffects?: boolean;
 }
+/**
+ * Lifecycle event handlers for the modal.
+ * These are flat props on `<Modal>` — not nested under `animation`:
+ * ```tsx
+ * <Modal onOpen={track} onClose={cleanup} ... />
+ * ```
+ */
 export interface ModalCallbacks {
+    /** Fired when the modal begins opening (before animation completes). */
     onOpen?: () => void;
+    /** Fired when the modal has fully closed. Alias of `onClose` for clarity. */
     onClose?: () => void;
+    /** Fired when the CRT boot animation finishes and the modal is fully visible. */
     onCRTBootComplete?: () => void;
 }
 /**
@@ -52,7 +72,9 @@ export interface ModalProps extends ModalCallbacks {
     showConfirm?: boolean;
     /**
      * Width of the modal.
-     * @default 'md'
+     * - sm: 448px, md: 512px, lg: 672px, xl: 896px
+     * Use `lg` or `xl` for content-heavy modals (forms, tables, multi-step flows).
+     * @default 'lg'
      */
     size?: "sm" | "md" | "lg" | "xl" | "fullscreen";
     /**

package/dist/components/SegmentedProgress.d.ts

@@ -1,37 +1,45 @@
 import { default as React } from 'react';
-/**
- * A circular progress indicator divided into segments.
- *
- * @example
- * // Basic segmented progress
- * <SegmentedProgress progress={30} />
- *
- * @example
- * // Segmented progress with center content
- * <SegmentedProgress progress={80}>
- *   <div className="text-center">
- *     <div className="text-2xl font-bold text-accent">80%</div>
- *     <div className="text-xs text-muted">LOADED</div>
- *   </div>
- * </SegmentedProgress>
- */
-export interface SegmentedProgressProps {
+type Size = 'sm' | 'md' | 'lg' | 'xl';
+interface RadialProps {
     /**
-     * Progress value (0-100).
+     * Renders a **radial/circular** gauge — discrete arc segments arranged in a ring.
+     * This is the original behaviour and the default.
      */
+    variant?: 'radial';
+    /** Size of the circular gauge. Sets width and height automatically.
+     * - sm: 64px, md: 96px, lg: 128px, xl: 160px
+     * @default 'md'
+     */
+    size?: Size;
+    /** Optional content to render in the center of the gauge. */
+    children?: React.ReactNode;
+    /** Progress value (0–100). */
     progress: number;
-    /** Optional custom class name */
+    /** Optional custom class name. */
     className?: string;
-    /** Optional content to render in the center of the segments */
-    children?: React.ReactNode;
 }
-/**
- * A highly technical, segmented radial progress indicator reminiscent of radar or power gauges.
- *
- * @example
- * <SegmentedProgress progress={45}>
- *   <div className="text-primary font-bold">LVL 4</div>
- * </SegmentedProgress>
- */
+interface BlockProps {
+    /**
+     * Renders a **linear block bar** — discrete filled rectangles in a row
+     * (think health bar or loading indicator divided into blocks: ▮▮▮▮▯▯).
+     */
+    variant: 'block';
+    /**
+     * Number of discrete blocks.
+     * @default 10
+     */
+    segments?: number;
+    /** Size controls block height.
+     * - sm: h-3, md: h-5, lg: h-7, xl: h-9
+     * @default 'md'
+     */
+    size?: Size;
+    /** Progress value (0–100). */
+    progress: number;
+    /** Optional custom class name. */
+    className?: string;
+    children?: never;
+}
+export type SegmentedProgressProps = RadialProps | BlockProps;
 declare const SegmentedProgress: React.FC<SegmentedProgressProps>;
 export default SegmentedProgress;

package/dist/components/Select.d.ts

@@ -55,6 +55,11 @@ export interface SelectProps extends Omit<React.SelectHTMLAttributes<HTMLSelectE
     error?: string;
     /** Optional custom class name */
     className?: string;
+    /**
+     * Convenience callback that receives the selected string value directly.
+     * Use instead of onChange when you only need the value (not the raw event).
+     */
+    onValueChange?: (value: string) => void;
 }
 /**
  * A futuristic Cyberpunk-themed dropdown select component with support for labels and error states.

package/dist/components/Steps.d.ts

@@ -57,7 +57,8 @@ export interface StepsProps {
      */
     items: StepItem[];
     /**
-     * Current active step index (0-based). Used to derive status when individual step status is not set.
+     * Current active step index. **0-based** — first step is `current={0}`, second is `current={1}`.
+     * A common mistake is passing a 1-based value which skips the first step.
      * @default 0
      */
     current?: number;

package/dist/components/index.d.ts

@@ -47,5 +47,7 @@ export { useCyberScrollbar } from '../hooks/useCyberScrollbar';
 export type { UseCyberScrollbarOptions } from '../hooks/useCyberScrollbar';
 export { useCyberNotifications } from '../hooks/useCyberNotifications';
 export type { CyberNotification, NotificationOptions } from '../hooks/useCyberNotifications';
+export { useAnimatedProgress } from '../hooks/useAnimatedProgress';
+export type { UseAnimatedProgressOptions } from '../hooks/useAnimatedProgress';
 export { CyberNotificationProvider } from '../contexts/NotificationContext';
 export type { CyberNotificationProviderProps } from '../contexts/NotificationContext';