cyberui-2045 1.3.3 → 2.0.0

package/AGENT.md

@@ -1,79 +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. |
-
-## 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.
+# 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/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 Patrick Yang
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 Patrick Yang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,72 +1,160 @@
-# 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
-
-<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
-
-## 🚀 Quick Start
-
-```bash
-npm install cyberui-2045
-```
-
-Import the core stylesheet and components
-
-```tsx
-import React from "react";
-import "cyberui-2045/styles.css";
-import { CircularProgress, Notification } from "cyberui-2045";
-
-function App() {
-  return (
-    <div>
-      <CircularProgress progress={75} radius={20}>
-        <span>75%</span>
-      </CircularProgress>
-
-      <Notification
-        type="success"
-        title="System Online"
-        message="All systems are operational"
-      />
-    </div>
-  );
-}
-```
-
-## Changelog
-
-See the full history in [CHANGELOG.md](./CHANGELOG.md).
-
-## 🛠️ Development
-
-```bash
-git clone https://github.com/patrickkuei/CyberUI.git
-cd CyberUI
-npm install
-npm run dev          # Start development server
-npm run storybook    # Start Storybook
-```
-
-## 🤝 Contributing
-
-Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md).
-
-## 📄 License
-
-MIT License - see [LICENSE](LICENSE) file for details.
-
----
-
-Made with ⚡ by [Patrick Yang](https://github.com/patrickkuei)
+# 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
+
+<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 & Storybook](https://patrickkuei.github.io/CyberUI)** — interactive component docs and examples
+
+## Quick Start
+
+```bash
+npm install cyberui-2045
+```
+
+Import the stylesheet once in your app entry, then use any component:
+
+```tsx
+import 'cyberui-2045/styles.css';
+import { Button, Card, CircularProgress } from 'cyberui-2045';
+
+function App() {
+  return (
+    <Card>
+      <CircularProgress progress={75} radius={20}>
+        <span>75%</span>
+      </CircularProgress>
+      <Button variant="primary">Jack In</Button>
+    </Card>
+  );
+}
+```
+
+## Components
+
+| Component | Category | Docs |
+|-----------|----------|------|
+| Button | Forms | [→](https://patrickkuei.github.io/CyberUI/?path=/docs/button--docs) |
+| Input | Forms | [→](https://patrickkuei.github.io/CyberUI/?path=/docs/input--docs) |
+| Select | Forms | [→](https://patrickkuei.github.io/CyberUI/?path=/docs/select--docs) |
+| Toggle | Forms | [→](https://patrickkuei.github.io/CyberUI/?path=/docs/toggle--docs) |
+| Card | Layout | [→](https://patrickkuei.github.io/CyberUI/?path=/docs/card--docs) |
+| Modal | Layout | [→](https://patrickkuei.github.io/CyberUI/?path=/docs/modal--docs) |
+| Badge | Feedback | [→](https://patrickkuei.github.io/CyberUI/?path=/docs/badge--docs) |
+| Notification | Feedback | [→](https://patrickkuei.github.io/CyberUI/?path=/docs/notification--docs) |
+| Skeleton | Feedback | [→](https://patrickkuei.github.io/CyberUI/?path=/docs/skeleton--docs) |
+| CircularProgress | Progress | [→](https://patrickkuei.github.io/CyberUI/?path=/docs/circularprogress--docs) |
+| LinearProgress | Progress | [→](https://patrickkuei.github.io/CyberUI/?path=/docs/linearprogress--docs) |
+| SegmentedProgress | Progress | [→](https://patrickkuei.github.io/CyberUI/?path=/docs/segmentedprogress--docs) |
+| TabNavigation | Navigation | [→](https://patrickkuei.github.io/CyberUI/?path=/docs/tabnavigation--docs) |
+| Carousel | Navigation | [→](https://patrickkuei.github.io/CyberUI/?path=/docs/carousel--docs) |
+| Steps | Navigation | [→](https://patrickkuei.github.io/CyberUI/?path=/docs/steps--docs) |
+| Image | Media | [→](https://patrickkuei.github.io/CyberUI/?path=/docs/image--docs) |
+| Checkbox | Forms | [→](https://patrickkuei.github.io/CyberUI/?path=/docs/checkbox--docs) |
+| Divider | Layout | [→](https://patrickkuei.github.io/CyberUI/?path=/docs/divider--docs) |
+| GradientText | Typography | [→](https://patrickkuei.github.io/CyberUI/?path=/docs/gradienttext--docs) |
+| SectionTitle | Typography | [→](https://patrickkuei.github.io/CyberUI/?path=/docs/sectiontitle--docs) |
+| Timeline | Display | [→](https://patrickkuei.github.io/CyberUI/?path=/docs/timeline--docs) |
+
+Also includes hooks (`useCyberNotifications`, `useAnimatedProgress`, `useCyberScrollbar`) and `CyberNotificationProvider` context.
+
+## AI Coding Setup
+
+If you use an AI coding assistant (Claude Code, Cursor, GitHub Copilot), run this once after installing:
+
+```bash
+npx cyberui-2045 init
+```
+
+It writes a concise CyberUI usage guide — components, hooks, tokens, and patterns — directly into your AI config file (`CLAUDE.md`, `.cursorrules`, or `.github/copilot-instructions.md`). Idempotent: safe to re-run after upgrades.
+
+```bash
+npx cyberui-2045 init --claude    # Claude Code only
+npx cyberui-2045 init --cursor    # Cursor only
+npx cyberui-2045 init --copilot   # GitHub Copilot only
+npx cyberui-2045 init --all       # all three
+npx cyberui-2045 init --dry-run   # preview without writing
+```
+
+## Customization
+
+CyberUI is an opinionated design system. Layout, spacing, and motion are intentional and fixed. You own the **color palette**.
+
+### 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 */
+}
+```
+
+These tokens are **guaranteed stable** across minor versions. All other CSS variables (shadows, gradients, animation values, `--tw-*`) are internal and may change.
+
+### className prop
+
+All components accept a `className` prop, merged via [`tailwind-merge`](https://github.com/dcastil/tailwind-merge) — your classes win on conflict:
+
+```tsx
+<Button className="mt-8 w-full">Full width with margin</Button>
+```
+
+Use `className` for layout and spacing. Overriding color or variant classes is supported but visual coherence becomes your responsibility.
+
+### cn() utility
+
+CyberUI re-exports its `cn()` helper (clsx + tailwind-merge) for use in your own components:
+
+```tsx
+import { cn } from 'cyberui-2045';
+
+<div className={cn('base-classes', isActive && 'active', userClassName)} />
+```
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for the full history.
+
+## Development
+
+```bash
+git clone https://github.com/patrickkuei/CyberUI.git
+cd CyberUI
+npm install
+npm run dev          # demo app
+npm run storybook    # Storybook on :6006
+npm run test         # unit + Storybook tests
+npm run build        # typecheck + bundle → dist/
+```
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.
+
+---
+
+Made with ⚡ by [Patrick Yang](https://github.com/patrickkuei)

package/bin/init.js

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+
+import { createInterface } from 'node:readline';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { getUsageContent } from './usage-content.js';
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+const MARKER_START = '<!-- cyberui-2045:start -->';
+const MARKER_END = '<!-- cyberui-2045:end -->';
+
+const TARGETS = {
+  claude: {
+    label: 'Claude Code   → CLAUDE.md',
+    file: 'CLAUDE.md',
+  },
+  cursor: {
+    label: 'Cursor        → .cursorrules',
+    file: '.cursorrules',
+  },
+  copilot: {
+    label: 'GitHub Copilot → .github/copilot-instructions.md',
+    file: '.github/copilot-instructions.md',
+  },
+};
+
+// ─── Arg parsing ──────────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+const isDryRun = args.includes('--dry-run');
+
+let selectedKeys = [];
+if (args.includes('--all')) {
+  selectedKeys = Object.keys(TARGETS);
+} else {
+  if (args.includes('--claude')) selectedKeys.push('claude');
+  if (args.includes('--cursor')) selectedKeys.push('cursor');
+  if (args.includes('--copilot')) selectedKeys.push('copilot');
+}
+
+// ─── Main ─────────────────────────────────────────────────────────────────────
+
+async function main() {
+  console.log('\n  cyberui-2045 — AI assistant setup\n');
+
+  if (selectedKeys.length === 0) {
+    if (!process.stdin.isTTY) {
+      // Non-interactive (CI / piped input)
+      console.log('  Non-interactive environment detected. Run one of:\n');
+      console.log('    npx cyberui-2045 init --claude');
+      console.log('    npx cyberui-2045 init --cursor');
+      console.log('    npx cyberui-2045 init --copilot');
+      console.log('    npx cyberui-2045 init --all\n');
+      process.exit(0);
+    }
+    selectedKeys = await promptTargets();
+  }
+
+  if (selectedKeys.length === 0) {
+    console.log('\n  Nothing written. Exiting.\n');
+    process.exit(0);
+  }
+
+  console.log(isDryRun ? '\n  [dry-run] Would write:\n' : '');
+
+  for (const key of selectedKeys) {
+    writeTarget(key);
+  }
+
+  console.log('\n  Done! Your AI assistant now has CyberUI context.\n');
+}
+
+// ─── Interactive prompt ───────────────────────────────────────────────────────
+
+function promptTargets() {
+  return new Promise((resolve) => {
+    const keys = Object.keys(TARGETS);
+    const cwd = process.cwd();
+
+    console.log('  Which AI config file should the CyberUI usage guide be added to?\n');
+
+    keys.forEach((key, i) => {
+      const target = TARGETS[key];
+      const filePath = join(cwd, target.file);
+      const exists = existsSync(filePath);
+      const hasSection = exists && readFileSync(filePath, 'utf8').includes(MARKER_START);
+      const status = hasSection ? ' (update)' : exists ? ' (append)' : ' (create)';
+      console.log(`    ${i + 1}. ${target.label}${status}`);
+    });
+
+    console.log(`    ${keys.length + 1}. All of the above`);
+    console.log('\n  Enter number(s) separated by commas (e.g. 1,3), or press Enter to cancel:');
+
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+
+    rl.question('  > ', (answer) => {
+      rl.close();
+
+      const raw = answer.trim();
+      if (!raw) return resolve([]);
+
+      const chosen = [];
+      for (const part of raw.split(',')) {
+        const n = parseInt(part.trim(), 10);
+        if (n === keys.length + 1) return resolve([...keys]); // "All"
+        if (n >= 1 && n <= keys.length) {
+          const key = keys[n - 1];
+          if (!chosen.includes(key)) chosen.push(key);
+        }
+      }
+
+      resolve(chosen);
+    });
+  });
+}
+
+// ─── Write / update target file ───────────────────────────────────────────────
+
+function writeTarget(key) {
+  const target = TARGETS[key];
+  const cwd = process.cwd();
+  const filePath = join(cwd, target.file);
+
+  // Read current package version
+  let version = '1.3.2';
+  try {
+    const pkgPath = new URL('../package.json', import.meta.url).pathname;
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    version = pkg.version ?? version;
+  } catch {
+    // fallback to hardcoded version
+  }
+
+  const block = `${MARKER_START}\n${getUsageContent(version)}\n${MARKER_END}`;
+
+  if (isDryRun) {
+    console.log(`  ── ${target.file} ──\n${block}\n`);
+    return;
+  }
+
+  // Ensure parent directory exists (e.g. .github/)
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  let finalContent;
+
+  if (existsSync(filePath)) {
+    const existing = readFileSync(filePath, 'utf8');
+
+    if (existing.includes(MARKER_START) && existing.includes(MARKER_END)) {
+      // Replace existing section
+      const before = existing.slice(0, existing.indexOf(MARKER_START));
+      const after = existing.slice(existing.indexOf(MARKER_END) + MARKER_END.length);
+      finalContent = `${before}${block}${after}`;
+      console.log(`  ✓  Updated  ${target.file}`);
+    } else {
+      // Append new section
+      finalContent = `${existing.trimEnd()}\n\n${block}\n`;
+      console.log(`  ✓  Appended ${target.file}`);
+    }
+  } else {
+    // Create new file
+    finalContent = `${block}\n`;
+    console.log(`  ✓  Created  ${target.file}`);
+  }
+
+  writeFileSync(filePath, finalContent, 'utf8');
+}
+
+// ─── Run ──────────────────────────────────────────────────────────────────────
+
+main().catch((err) => {
+  console.error('\n  Error:', err.message, '\n');
+  process.exit(1);
+});