cyberui-2045 1.3.2 → 1.3.3

package/AGENT.md

@@ -0,0 +1,79 @@
+# CyberUI 2045 - Agent Guide
+
+You are an expert frontend developer building a futuristic, cyberpunk-themed application using the `cyberui-2045` library.
+
+## 1. Setup & Installation
+
+**Install the package:**
+```bash
+npm install cyberui-2045
+```
+
+**Import the styles (CRITICAL):**
+Add this to your root entry file (e.g., `main.tsx`, `App.tsx`):
+```tsx
+import "cyberui-2045/styles.css";
+```
+
+## 2. Vibe Coding Principles (Consumer Edition)
+
+*   **Dark Mode Only**: CyberUI is designed for dark backgrounds. Always set your page background to a dark color (e.g., `bg-slate-900`, `#050505`).
+*   **Use the Library**: Do not build custom UI components if a CyberUI component exists.
+*   **Neon Pop**: Use the library's built-in glow effects. Don't override them with flat colors unless necessary.
+*   **Responsive**: Use the `ResponsiveValue` prop pattern for mobile-first designs.
+
+## 3. Component Reference
+
+| Component | Description |
+| :--- | :--- |
+| `Button` | Neon-styled button. Variants: `primary`, `secondary`, `danger`, `ghost`. |
+| `Card` | Glassmorphism container with borders. |
+| `Input` | Cyberpunk text input with focus glows. |
+| `Modal` | CRT-style modal dialog. |
+| `Notification` | Toast notifications. Use `useCyberNotifications` hook. |
+| `CircularProgress` | Dual-ring progress indicator. |
+| `TabNavigation` | Animated tab bar. |
+| `Badge` | Status indicator. Variants: `default`, `success`, `warning`, `danger`. |
+| `Toggle` | Cyberpunk switch. |
+| `Select` | Styled dropdown. |
+| `Skeleton` | Loading placeholder. |
+| `Image` | Image with cyberpunk frame/effects. |
+| `Carousel` | Image carousel. |
+
+## 4. Usage Patterns (Few-Shot)
+
+### Basic Card with Action
+```tsx
+import { Card, Button, Badge } from "cyberui-2045";
+
+export const UserProfile = () => (
+  <Card variant="default" className="max-w-md">
+    <div className="flex justify-between items-center mb-4">
+      <h2 className="text-xl text-cyan-400 font-bold">Operative Status</h2>
+      <Badge variant="success">ONLINE</Badge>
+    </div>
+    <p className="text-gray-300 mb-6">System synchronization at 98%.</p>
+    <Button variant="primary" onClick={() => console.log("Syncing...")}>
+      INITIATE SYNC
+    </Button>
+  </Card>
+);
+```
+
+### Responsive Layout
+```tsx
+import { Button } from "cyberui-2045";
+
+// Resize button based on screen width
+<Button
+  size={{ base: 'sm', md: 'md', lg: 'lg' }}
+  variant="secondary"
+>
+  Responsive Action
+</Button>
+```
+
+## 5. Troubleshooting
+
+*   **Missing Styles?** Ensure `import "cyberui-2045/styles.css"` is present.
+*   **Text Invisible?** Check if you are on a white background. Switch to dark mode.

package/README.md

@@ -6,6 +6,12 @@ A cyberpunk-themed React UI library with neon-styled components and futuristic a
 
 ## 🌐 Demo & Documentation
 
+<details>
+  <summary>Check out the Demo Video 🎬</summary>
+  <video src="https://github.com/user-attachments/assets/00d3de8d-d243-4ae0-80c4-e6b97b71c0f0">
+  </video>
+</details>
+
 - 🔗 **[Live Demo](https://patrickkuei.github.io/CyberUI)** - Experience the cyberpunk theme in action
 - 📚 **[Storybook Documentation](https://patrickkuei.github.io/CyberUI/storybook)** - Interactive component documentation
 

package/dist/components/Badge.d.ts

@@ -1,7 +1,33 @@
 import { default as React } from 'react';
 import { ResponsiveValue } from '../utils/responsive';
+/**
+ * A status indicator badge with various semantic variants.
+ *
+ * @example
+ * // Success badge
+ * <Badge variant="success">ONLINE</Badge>
+ *
+ * @example
+ * // Clickable badge with icon
+ * <Badge
+ *   variant="primary"
+ *   clickable
+ *   onClick={handleClick}
+ *   leftIcon={<Icon name="user" />}
+ * >
+ *   Profile
+ * </Badge>
+ */
 export interface BadgeProps {
+    /**
+     * Semantic style of the badge.
+     * @default 'primary'
+     */
     variant?: 'primary' | 'secondary' | 'accent' | 'success' | 'error' | 'warning';
+    /**
+     * Size of the badge.
+     * @default 'md'
+     */
     size?: ResponsiveValue<'sm' | 'md' | 'lg'>;
     children: React.ReactNode;
     className?: string;

package/dist/components/Button.d.ts

@@ -1,7 +1,42 @@
 import { default as React } from 'react';
 import { ResponsiveValue } from '../utils/responsive';
+/**
+ * A neon-styled cyberpunk button component.
+ *
+ * Supports multiple variants and responsive sizing.
+ *
+ * @example
+ * // Primary button
+ * <Button variant="primary" onClick={handleClick}>
+ *   INITIATE
+ * </Button>
+ *
+ * @example
+ * // Responsive size (Small on mobile, Large on desktop)
+ * <Button size={{ base: 'sm', lg: 'lg' }}>
+ *   RESPONSIVE
+ * </Button>
+ *
+ * @example
+ * // Ghost variant for secondary actions
+ * <Button variant="ghost">
+ *   CANCEL
+ * </Button>
+ */
 export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+    /**
+     * Visual style of the button.
+     * - `primary`: Main action, neon glow.
+     * - `secondary`: Alternative action, bordered.
+     * - `danger`: Destructive action, red glow.
+     * - `ghost`: Subtle action, transparent background.
+     * @default 'primary'
+     */
     variant?: 'primary' | 'secondary' | 'danger' | 'ghost';
+    /**
+     * Size of the button. Can be a static value or a responsive object.
+     * @default 'md'
+     */
     size?: ResponsiveValue<'sm' | 'md' | 'lg'>;
     children: React.ReactNode;
 }

package/dist/components/Card.d.ts

@@ -1,9 +1,39 @@
 import { default as React } from 'react';
 import { ResponsiveValue } from '../utils/responsive';
+/**
+ * A glassmorphism container for grouping content.
+ *
+ * @example
+ * // Basic card with title
+ * <Card title="System Status">
+ *   <p>All systems operational.</p>
+ * </Card>
+ *
+ * @example
+ * // Accent variant with hover effect
+ * <Card variant="accent" title="High Priority">
+ *   <Button>Action Required</Button>
+ * </Card>
+ */
 export interface CardProps {
+    /**
+     * Visual style of the card.
+     * - `default`: Standard glassmorphism.
+     * - `accent`: Glowing border and hover effects.
+     * - `small`: Compact padding for tight spaces.
+     * @default 'default'
+     */
     variant?: 'default' | 'accent' | 'small';
+    /**
+     * Padding size of the card content.
+     * @default 'md'
+     */
     size?: ResponsiveValue<'sm' | 'md' | 'lg'>;
     title?: string;
+    /**
+     * Whether to show a border under the title.
+     * @default true
+     */
     titleBorder?: boolean;
     children: React.ReactNode;
     className?: string;

package/dist/components/Carousel.d.ts

@@ -36,6 +36,29 @@ export interface CarouselCallbacks {
 }
 /**
  * Props for the CyberUI Carousel component
+ *
+ * @example
+ * // Basic carousel
+ * <Carousel
+ *   images={[
+ *     { src: 'img1.jpg', alt: 'Cyber City' },
+ *     { src: 'img2.jpg', alt: 'Neon Lights' }
+ *   ]}
+ *   currentIndex={index}
+ *   onChange={setIndex}
+ * />
+ *
+ * @example
+ * // Glitch effect carousel
+ * <Carousel
+ *   images={images}
+ *   currentIndex={index}
+ *   onChange={setIndex}
+ *   transition="signal-glitch"
+ *   glitchRate={0.5}
+ *   autoPlay
+ *   interval={5000}
+ * />
  */
 export interface CarouselProps extends CarouselCallbacks {
     /** Array of images to display */

package/dist/components/CircularProgress.d.ts

@@ -1,6 +1,25 @@
 import { default as React } from 'react';
+/**
+ * A circular progress indicator with neon glow effects.
+ *
+ * @example
+ * // Basic progress
+ * <CircularProgress progress={75} radius={40} />
+ *
+ * @example
+ * // Progress with label
+ * <CircularProgress progress={45} radius={60}>
+ *   <span className="text-accent font-bold">45%</span>
+ * </CircularProgress>
+ */
 export interface CircularProgressProps {
+    /**
+     * Progress value (0-100).
+     */
     progress: number;
+    /**
+     * Radius of the circle in pixels.
+     */
     radius: number;
     className?: string;
     children?: React.ReactNode;

package/dist/components/Image.d.ts

@@ -30,6 +30,23 @@ export interface ImageCallbacks {
 }
 /**
  * Props for the CyberUI Image component
+ *
+ * @example
+ * // Basic image with preview
+ * <Image
+ *   src="/cyber-city.jpg"
+ *   alt="Cyberpunk cityscape"
+ *   size="lg"
+ * />
+ *
+ * @example
+ * // Image with fallback and custom animation
+ * <Image
+ *   src={src}
+ *   alt="Avatar"
+ *   fallback="/default-avatar.png"
+ *   animation={{ cyberpunkEffects: false }}
+ * />
  */
 export interface ImageProps extends Omit<React.ImgHTMLAttributes<HTMLImageElement>, "size" | "onLoad" | "onError">, ImageCallbacks {
     /** Image source URL (required) */

package/dist/components/Input.d.ts

@@ -1,7 +1,31 @@
 import { default as React } from 'react';
 import { ResponsiveValue } from '../utils/responsive';
+/**
+ * A cyberpunk-styled text input field.
+ *
+ * @example
+ * // Basic input with label
+ * <Input label="Username" placeholder="Enter alias..." />
+ *
+ * @example
+ * // Input with error state and icon
+ * <Input
+ *   label="Password"
+ *   type="password"
+ *   error="Invalid credentials"
+ *   leftIcon={<LockIcon />}
+ * />
+ */
 export interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size'> {
+    /**
+     * Visual style of the input.
+     * @default 'primary'
+     */
     variant?: 'primary' | 'secondary' | 'danger' | 'ghost';
+    /**
+     * Size of the input (height and padding).
+     * @default 'md'
+     */
     size?: ResponsiveValue<'sm' | 'md' | 'lg'>;
     label?: string;
     helperText?: string;

package/dist/components/LinearProgress.d.ts

@@ -1,7 +1,29 @@
 import { default as React } from 'react';
 import { ResponsiveValue } from '../utils/responsive';
+/**
+ * A linear progress bar with gradient and glow effects.
+ *
+ * @example
+ * // Basic progress bar
+ * <LinearProgress progress={60} />
+ *
+ * @example
+ * // Large progress bar with custom class
+ * <LinearProgress
+ *   progress={85}
+ *   size="lg"
+ *   className="my-4"
+ * />
+ */
 export interface LinearProgressProps {
+    /**
+     * Progress value (0-100).
+     */
     progress: number;
+    /**
+     * Height of the progress bar.
+     * @default 'md'
+     */
     size?: ResponsiveValue<'sm' | 'md' | 'lg'>;
     className?: string;
 }

package/dist/components/Modal.d.ts

@@ -9,8 +9,36 @@ export interface ModalCallbacks {
     onClose?: () => void;
     onCRTBootComplete?: () => void;
 }
+/**
+ * A CRT-styled modal dialog with retro animation effects.
+ *
+ * @example
+ * // Basic modal
+ * <Modal isOpen={isOpen} onClose={close} title="System Alert">
+ *   <p>Breach detected in sector 7.</p>
+ * </Modal>
+ *
+ * @example
+ * // Confirmation modal with custom actions
+ * <Modal
+ *   isOpen={isOpen}
+ *   onClose={close}
+ *   title="Confirm Override"
+ *   onConfirm={handleConfirm}
+ *   confirmText="EXECUTE"
+ *   variant="danger"
+ * >
+ *   Are you sure you want to override safety protocols?
+ * </Modal>
+ */
 export interface ModalProps extends ModalCallbacks {
+    /**
+     * Whether the modal is visible.
+     */
     isOpen: boolean;
+    /**
+     * Callback when the modal requests to close.
+     */
     onClose: () => void;
     title?: string;
     children: React.ReactNode;
@@ -22,6 +50,10 @@ export interface ModalProps extends ModalCallbacks {
     confirmLoading?: boolean;
     showCancel?: boolean;
     showConfirm?: boolean;
+    /**
+     * Width of the modal.
+     * @default 'md'
+     */
     size?: "sm" | "md" | "lg" | "xl" | "fullscreen";
     closeOnOverlayClick?: boolean;
     closeOnEscape?: boolean;

package/dist/components/Notification.d.ts

@@ -1,9 +1,36 @@
 import { default as React } from 'react';
 import { ResponsiveValue } from '../utils/responsive';
+/**
+ * A toast notification component with status indicators.
+ *
+ * @example
+ * // Success notification
+ * <Notification
+ *   type="success"
+ *   title="Upload Complete"
+ *   message="Data transfer finished successfully."
+ * />
+ *
+ * @example
+ * // Error notification with close handler
+ * <Notification
+ *   type="error"
+ *   title="Connection Failed"
+ *   message="Unable to reach the mainframe."
+ *   onClose={handleClose}
+ * />
+ */
 export interface NotificationProps {
+    /**
+     * Semantic type of the notification.
+     */
     type: 'success' | 'warning' | 'error';
     title: string;
     message: string;
+    /**
+     * Size of the notification.
+     * @default 'md'
+     */
     size?: ResponsiveValue<'sm' | 'md' | 'lg'>;
     onClose?: () => void;
 }

package/dist/components/SegmentedProgress.d.ts

@@ -1,5 +1,24 @@
 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 {
+    /**
+     * Progress value (0-100).
+     */
     progress: number;
     className?: string;
     children?: React.ReactNode;

package/dist/components/Select.d.ts

@@ -5,9 +5,38 @@ export interface SelectOption {
     label: string;
     disabled?: boolean;
 }
+/**
+ * A styled dropdown selection component.
+ *
+ * @example
+ * // Basic select
+ * <Select
+ *   label="Choose Sector"
+ *   options={[
+ *     { value: 'sector-7', label: 'Sector 7' },
+ *     { value: 'sector-9', label: 'Sector 9' }
+ *   ]}
+ * />
+ *
+ * @example
+ * // Select with error
+ * <Select
+ *   label="Clearance Level"
+ *   error="Insufficient permissions"
+ *   options={levels}
+ * />
+ */
 export interface SelectProps extends Omit<React.SelectHTMLAttributes<HTMLSelectElement>, "size"> {
     label?: string;
+    /**
+     * Size of the select input.
+     * @default 'md'
+     */
     size?: ResponsiveValue<"sm" | "md" | "lg">;
+    /**
+     * Visual style variant.
+     * @default 'primary'
+     */
     variant?: "primary" | "secondary" | "danger" | "ghost";
     options: SelectOption[];
     placeholder?: string;

package/dist/components/Skeleton.d.ts

@@ -1,12 +1,48 @@
 import { default as React } from 'react';
 import { ResponsiveValue } from '../utils/responsive';
+/**
+ * A placeholder component for loading states.
+ *
+ * @example
+ * // Text skeleton
+ * <Skeleton variant="text" lines={3} />
+ *
+ * @example
+ * // Avatar and text combination
+ * <Skeleton variant="avatar-text" size="lg" />
+ *
+ * @example
+ * // Custom rectangular skeleton
+ * <Skeleton
+ *   variant="rectangular"
+ *   width={200}
+ *   height={150}
+ *   animate={false}
+ * />
+ */
 export interface SkeletonProps {
+    /**
+     * Shape variant of the skeleton.
+     * @default 'text'
+     */
     variant?: "text" | "circular" | "rectangular" | "card" | "avatar-text" | "button-group";
+    /**
+     * Size of the skeleton element.
+     * @default 'md'
+     */
     size?: ResponsiveValue<"sm" | "md" | "lg">;
     width?: string | number;
     height?: string | number;
     className?: string;
+    /**
+     * Number of lines for text variant.
+     * @default 3
+     */
     lines?: number;
+    /**
+     * Whether to show the pulse animation.
+     * @default true
+     */
     animate?: boolean;
 }
 declare const Skeleton: React.FC<SkeletonProps>;

package/dist/components/TabNavigation.d.ts

@@ -1,11 +1,52 @@
 import { default as React } from 'react';
 import { ResponsiveValue } from '../utils/responsive';
 export type TabNavigationMode = "scroll" | "wrap" | "dropdown" | "collapsible";
+/**
+ * A responsive tab navigation component.
+ *
+ * @example
+ * // Basic tabs
+ * <TabNavigation
+ *   tabs={['Home', 'Profile', 'Settings']}
+ *   activeTab={activeTab}
+ *   onTabChange={setActiveTab}
+ * />
+ *
+ * @example
+ * // Tabs with dropdown mode for mobile
+ * <TabNavigation
+ *   tabs={categories}
+ *   activeTab={category}
+ *   onTabChange={setCategory}
+ *   mode="dropdown"
+ *   dropdownLabel="Select Category"
+ * />
+ */
 export interface TabNavigationProps {
+    /**
+     * List of tab labels.
+     */
     tabs: readonly string[];
+    /**
+     * Currently active tab label.
+     */
     activeTab: string;
+    /**
+     * Callback when a tab is selected.
+     */
     onTabChange: (tab: string) => void;
+    /**
+     * Size of the tabs.
+     * @default 'md'
+     */
     size?: ResponsiveValue<"sm" | "md" | "lg">;
+    /**
+     * Responsive display mode.
+     * - `scroll`: Horizontal scrolling container.
+     * - `wrap`: Wraps to new lines.
+     * - `dropdown`: Collapses into a dropdown menu.
+     * @default 'scroll'
+     */
     mode?: ResponsiveValue<TabNavigationMode>;
     containerClassName?: string;
     tabsClassName?: string;

package/dist/components/Toggle.d.ts

@@ -1,8 +1,36 @@
 import { default as React } from 'react';
 import { ResponsiveValue } from '../utils/responsive';
+/**
+ * A toggle switch component.
+ *
+ * @example
+ * // Basic toggle
+ * <Toggle
+ *   label="Enable Notifications"
+ *   checked={enabled}
+ *   onChange={setEnabled}
+ * />
+ *
+ * @example
+ * // Large accent toggle
+ * <Toggle
+ *   checked={isActive}
+ *   onChange={toggle}
+ *   size="lg"
+ *   variant="accent"
+ * />
+ */
 export interface ToggleProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size' | 'onChange'> {
     label?: string;
+    /**
+     * Size of the toggle.
+     * @default 'md'
+     */
     size?: ResponsiveValue<'sm' | 'md' | 'lg'>;
+    /**
+     * Visual style variant.
+     * @default 'primary'
+     */
     variant?: 'primary' | 'secondary' | 'accent';
     className?: string;
     checked?: boolean;