cyberui-2045 1.3.2 → 1.4.0

package/AGENT.md

@@ -0,0 +1,85 @@
+# 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. |
+| `Checkbox` | Neon-styled checkbox with SVG icons. |
+| `Divider` | Gradient/solid/dashed content separator. |
+| `GradientText` | Text with cyberpunk gradient effects. |
+| `SectionTitle` | Title with decorative gradient line. |
+| `Steps` | Multi-step progress indicator. |
+| `Timeline` | Vertical event history display. |
+
+## 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/Checkbox.d.ts

@@ -0,0 +1,48 @@
+import { default as React } from 'react';
+import { ResponsiveValue } from '../utils/responsive';
+/**
+ * A cyberpunk-styled checkbox with neon glow effects.
+ *
+ * Features a custom SVG checkbox with a cut corner design, matching the cyberpunk aesthetic.
+ * Supports both controlled and uncontrolled modes.
+ *
+ * @example
+ * // Basic checkbox
+ * <Checkbox label="Accept terms" />
+ *
+ * @example
+ * // Controlled checkbox
+ * <Checkbox
+ *   label="Enable notifications"
+ *   checked={isEnabled}
+ *   onChange={(e) => setIsEnabled(e.target.checked)}
+ * />
+ *
+ * @example
+ * // With error message
+ * <Checkbox
+ *   label="Required field"
+ *   error="This field is required"
+ * />
+ */
+export interface CheckboxProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'type' | 'size'> {
+    /**
+     * Label text displayed next to the checkbox.
+     */
+    label?: string;
+    /**
+     * Error message to display below the checkbox.
+     */
+    error?: string;
+    /**
+     * Size of the checkbox. Supports responsive values.
+     * @default 'md'
+     */
+    size?: ResponsiveValue<'sm' | 'md' | 'lg'>;
+    /**
+     * Additional CSS classes.
+     */
+    className?: string;
+}
+declare const Checkbox: React.FC<CheckboxProps>;
+export default Checkbox;

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/Divider.d.ts

@@ -0,0 +1,43 @@
+import { default as React } from 'react';
+/**
+ * A decorative divider with cyberpunk styling.
+ *
+ * Supports multiple visual variants and both horizontal and vertical orientations.
+ *
+ * @example
+ * // Gradient divider (default)
+ * <Divider />
+ *
+ * @example
+ * // Solid divider
+ * <Divider variant="solid" />
+ *
+ * @example
+ * // Dashed divider
+ * <Divider variant="dashed" />
+ *
+ * @example
+ * // Vertical divider
+ * <Divider orientation="vertical" className="h-8" />
+ */
+export interface DividerProps {
+    /**
+     * Visual style of the divider.
+     * - `gradient`: Gradient fade from center (default).
+     * - `solid`: Solid semi-transparent line.
+     * - `dashed`: Dashed border style.
+     * @default 'gradient'
+     */
+    variant?: 'gradient' | 'solid' | 'dashed';
+    /**
+     * Orientation of the divider.
+     * @default 'horizontal'
+     */
+    orientation?: 'horizontal' | 'vertical';
+    /**
+     * Additional CSS classes.
+     */
+    className?: string;
+}
+declare const Divider: React.FC<DividerProps>;
+export default Divider;

package/dist/components/GradientText.d.ts

@@ -0,0 +1,47 @@
+import { default as React } from 'react';
+/**
+ * A component for rendering text with a neon gradient effect.
+ *
+ * @example
+ * // Default cyan-purple gradient
+ * <GradientText as="h1" className="text-4xl font-bold">
+ *   CyberUI 2045
+ * </GradientText>
+ *
+ * @example
+ * // Secondary pink-purple gradient
+ * <GradientText variant="secondary">
+ *   System Critical
+ * </GradientText>
+ *
+ * @example
+ * // Accent gradient for warnings
+ * <GradientText variant="accent" as="p">
+ *   Warning Level
+ * </GradientText>
+ */
+export interface GradientTextProps {
+    /**
+     * The text content to render.
+     */
+    children: React.ReactNode;
+    /**
+     * Visual style of the gradient.
+     * - `primary`: Cyan to pink gradient (secondary → primary).
+     * - `secondary`: Pink to yellow gradient (primary → accent).
+     * - `accent`: Yellow to cyan gradient (accent → secondary).
+     * @default 'primary'
+     */
+    variant?: 'primary' | 'secondary' | 'accent';
+    /**
+     * The HTML element to render as.
+     * @default 'span'
+     */
+    as?: 'span' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'div';
+    /**
+     * Additional CSS classes.
+     */
+    className?: string;
+}
+declare const GradientText: React.FC<GradientTextProps>;
+export default GradientText;

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/SectionTitle.d.ts

@@ -0,0 +1,41 @@
+import { default as React } from 'react';
+import { ResponsiveValue } from '../utils/responsive';
+/**
+ * A standardized section title with cyberpunk styling.
+ *
+ * Features uppercase text, wide letter spacing, and an optional decorative gradient line.
+ *
+ * @example
+ * // Standard title with gradient line
+ * <SectionTitle>System Status</SectionTitle>
+ *
+ * @example
+ * // Title without decorative line
+ * <SectionTitle showLine={false}>Heading Only</SectionTitle>
+ *
+ * @example
+ * // With custom styling
+ * <SectionTitle className="mb-8">Custom Spacing</SectionTitle>
+ */
+export interface SectionTitleProps {
+    /**
+     * The title text content.
+     */
+    children: React.ReactNode;
+    /**
+     * Whether to show a decorative gradient line after the title.
+     * @default true
+     */
+    showLine?: boolean;
+    /**
+     * Size of the section title. Supports responsive values.
+     * @default 'md'
+     */
+    size?: ResponsiveValue<'sm' | 'md' | 'lg'>;
+    /**
+     * Additional CSS classes.
+     */
+    className?: string;
+}
+declare const SectionTitle: React.FC<SectionTitleProps>;
+export default SectionTitle;

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;