cyberui-2045 2.1.0 → 2.2.0

package/bin/usage-content.js

@@ -1,120 +1,206 @@
-// 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 — use size prop (sm/md/lg/xl); fills container without it
+<SegmentedProgress progress={80} size="md">
+  <span className="text-accent font-bold text-xs">80%</span>
+</SegmentedProgress>
+
+// 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

@@ -52,7 +52,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

@@ -2,13 +2,15 @@ import { default as React } from 'react';
 /**
  * A circular progress indicator divided into segments.
  *
+ * Use the `size` prop to control dimensions — without it the component fills its container.
+ *
  * @example
- * // Basic segmented progress
- * <SegmentedProgress progress={30} />
+ * // Recommended: use size prop
+ * <SegmentedProgress progress={30} size="md" />
  *
  * @example
- * // Segmented progress with center content
- * <SegmentedProgress progress={80}>
+ * // With center content
+ * <SegmentedProgress progress={80} size="lg">
  *   <div className="text-center">
  *     <div className="text-2xl font-bold text-accent">80%</div>
  *     <div className="text-xs text-muted">LOADED</div>
@@ -20,6 +22,12 @@ export interface SegmentedProgressProps {
      * Progress value (0-100).
      */
     progress: number;
+    /**
+     * Preset container size. Sets width and height automatically.
+     * - sm: 64px, md: 96px, lg: 128px, xl: 160px
+     * @default 'md'
+     */
+    size?: 'sm' | 'md' | 'lg' | 'xl';
     /** Optional custom class name */
     className?: string;
     /** Optional content to render in the center of the segments */
@@ -29,7 +37,7 @@ export interface SegmentedProgressProps {
  * A highly technical, segmented radial progress indicator reminiscent of radar or power gauges.
  *
  * @example
- * <SegmentedProgress progress={45}>
+ * <SegmentedProgress progress={45} size="md">
  *   <div className="text-primary font-bold">LVL 4</div>
  * </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';