cyberui-2045 1.3.1 → 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

@@ -1,10 +1,16 @@
-# CyberUI 🚀
+# CyberUI
 
 A cyberpunk-themed React UI library with neon-styled components and futuristic aesthetics.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## � Demo & Documentation
+## 🌐 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
@@ -15,9 +21,12 @@ A cyberpunk-themed React UI library with neon-styled components and futuristic a
 npm install cyberui-2045
 ```
 
+Import the core stylesheet and components
+
 ```tsx
-import React from 'react';
-import { CircularProgress, Notification } from 'cyberui-2045';
+import React from "react";
+import "cyberui-2045/styles.css";
+import { CircularProgress, Notification } from "cyberui-2045";
 
 function App() {
   return (
@@ -36,6 +45,10 @@ function App() {
 }
 ```
 
+## Changelog
+
+See the full history in [CHANGELOG.md](./CHANGELOG.md).
+
 ## 🛠️ Development
 
 ```bash

package/dist/components/Badge.d.ts

@@ -0,0 +1,40 @@
+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;
+    leftIcon?: React.ReactNode;
+    rightIcon?: React.ReactNode;
+    clickable?: boolean;
+    onClick?: () => void;
+}
+declare const Badge: React.FC<BadgeProps>;
+export default Badge;

package/dist/components/Button.d.ts

@@ -0,0 +1,44 @@
+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;
+}
+declare const Button: React.FC<ButtonProps>;
+export default Button;

package/dist/components/Card.d.ts

@@ -0,0 +1,42 @@
+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;
+}
+declare const Card: React.FC<CardProps>;
+export default Card;

package/dist/components/Carousel.d.ts

@@ -0,0 +1,94 @@
+import { default as React } from 'react';
+import { ResponsiveValue } from '../utils/responsive';
+/**
+ * Size options for the Carousel component
+ */
+export type CarouselSize = "sm" | "md" | "lg";
+/**
+ * Transition effects for the Carousel
+ */
+export type CarouselTransition = "slide" | "fade" | "matrix" | "signal-glitch";
+/**
+ * Object fit options for images
+ */
+export type CarouselObjectFit = "cover" | "contain";
+/**
+ * Image data structure for Carousel
+ */
+export interface CarouselImageData {
+    /** Image source URL */
+    src: string;
+    /** Alt text for accessibility */
+    alt: string;
+    /** Optional fallback image URL */
+    fallbackSrc?: string;
+    /** Optional caption */
+    caption?: string;
+}
+/**
+ * Lifecycle callback functions for Carousel events
+ */
+export interface CarouselCallbacks {
+    /** Fired before slide change (fromIndex, toIndex) */
+    onBeforeChange?: (fromIndex: number, toIndex: number) => void;
+    /** Fired after slide change */
+    onAfterChange?: (index: number) => void;
+}
+/**
+ * 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 */
+    images: CarouselImageData[];
+    /** Current slide index (controlled) */
+    currentIndex: number;
+    /** Callback when slide changes */
+    onChange: (index: number) => void;
+    /** Size variant with responsive support */
+    size?: ResponsiveValue<CarouselSize>;
+    /** Enable auto-play functionality */
+    autoPlay?: boolean;
+    /** Auto-play interval in milliseconds */
+    interval?: number;
+    /** Enable infinite loop */
+    infinite?: boolean;
+    /** Transition effect */
+    transition?: CarouselTransition;
+    /** Image object fit behavior */
+    objectFit?: CarouselObjectFit;
+    /** Show navigation arrows */
+    showArrows?: boolean;
+    /** Show slide indicators */
+    showIndicators?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+    /** Disable click-to-expand on images */
+    disableImagePreview?: boolean;
+    /** Control signal-glitch effect frequency. Float (0.0-1.0) for probability, boolean for on/off */
+    glitchRate?: number | boolean;
+}
+declare const _default: React.NamedExoticComponent<CarouselProps>;
+export default _default;

package/dist/components/CircularProgress.d.ts

@@ -0,0 +1,29 @@
+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;
+    ariaLabel?: string;
+}
+declare const CircularProgress: React.FC<CircularProgressProps>;
+export default CircularProgress;

package/dist/components/Image.d.ts

@@ -0,0 +1,90 @@
+import { default as React } from 'react';
+import { ResponsiveValue } from '../utils/responsive';
+/**
+ * Size options for the Image component
+ */
+export type ImageSize = "sm" | "md" | "lg";
+/**
+ * Animation configuration for preview transitions
+ */
+export interface ImageAnimationConfig {
+    /** Duration of opening animation in milliseconds */
+    openDuration?: number;
+    /** Duration of closing animation in milliseconds */
+    closeDuration?: number;
+    /** Enable/disable cyberpunk effects */
+    cyberpunkEffects?: boolean;
+}
+/**
+ * Callback functions for Image component events
+ */
+export interface ImageCallbacks {
+    /** Fired when preview opens */
+    onPreviewOpen?: () => void;
+    /** Fired when preview closes */
+    onPreviewClose?: () => void;
+    /** Fired when image loads successfully */
+    onLoad?: (event: React.SyntheticEvent<HTMLImageElement>) => void;
+    /** Fired when image fails to load */
+    onError?: (event: React.SyntheticEvent<HTMLImageElement>) => void;
+}
+/**
+ * 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) */
+    src: string;
+    /** Alternative text for accessibility (required) */
+    alt: string;
+    /** Size of the image container */
+    size?: ResponsiveValue<ImageSize>;
+    /** Enable click-to-expand preview functionality */
+    preview?: boolean;
+    /** Fallback image URL when main image fails to load */
+    fallback?: string;
+    /** Custom loading placeholder component */
+    placeholder?: React.ReactNode;
+    /** Additional CSS classes */
+    className?: string;
+    /** Animation configuration */
+    animation?: ImageAnimationConfig;
+    /** Disable lazy loading (images load immediately) */
+    eager?: boolean;
+    /** Custom preview container styles */
+    previewClassName?: string;
+}
+/**
+ * CyberUI Image Component
+ *
+ * A cyberpunk-themed image component with click-to-expand preview functionality,
+ * loading states, error handling, and smooth animations.
+ *
+ * @example
+ * ```tsx
+ * <Image
+ *   src="/cyber-city.jpg"
+ *   alt="Cyberpunk cityscape"
+ *   size="lg"
+ *   onPreviewOpen={() => console.log('Preview opened')}
+ * />
+ * ```
+ */
+declare const Image: React.FC<ImageProps>;
+export default Image;

package/dist/components/Input.d.ts

@@ -0,0 +1,37 @@
+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;
+    error?: string;
+    leftIcon?: React.ReactNode;
+    rightIcon?: React.ReactNode;
+}
+declare const Input: React.FC<InputProps>;
+export default Input;

package/dist/components/LinearProgress.d.ts

@@ -0,0 +1,31 @@
+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;
+}
+declare const LinearProgress: React.FC<LinearProgressProps>;
+export default LinearProgress;

package/dist/components/Modal.d.ts

@@ -0,0 +1,66 @@
+import { default as React } from 'react';
+export interface ModalAnimationConfig {
+    openDuration?: number;
+    closeDuration?: number;
+    crtEffects?: boolean;
+}
+export interface ModalCallbacks {
+    onOpen?: () => void;
+    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;
+    footer?: React.ReactNode;
+    onCancel?: () => void;
+    onConfirm?: () => void;
+    cancelText?: string;
+    confirmText?: string;
+    confirmLoading?: boolean;
+    showCancel?: boolean;
+    showConfirm?: boolean;
+    /**
+     * Width of the modal.
+     * @default 'md'
+     */
+    size?: "sm" | "md" | "lg" | "xl" | "fullscreen";
+    closeOnOverlayClick?: boolean;
+    closeOnEscape?: boolean;
+    animation?: ModalAnimationConfig;
+    className?: string;
+    overlayClassName?: string;
+    showCloseButton?: boolean;
+}
+declare const Modal: React.FC<ModalProps>;
+export default Modal;

package/dist/components/Notification.d.ts

@@ -0,0 +1,38 @@
+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;
+}
+declare const Notification: React.FC<NotificationProps>;
+export default Notification;

package/dist/components/SegmentedProgress.d.ts

@@ -0,0 +1,27 @@
+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;
+}
+declare const SegmentedProgress: React.FC<SegmentedProgressProps>;
+export default SegmentedProgress;