@bloomneo/uikit 1.5.0

package/bin/commands/serve.js

@@ -0,0 +1,216 @@
+/**
+ * @fileoverview UIKit Serve Command - Development server management
+ * @description Smart Vite server with port management and process cleanup
+ * @package @bloomneo/uikit
+ */
+
+import { spawn, exec } from 'child_process';
+import { promisify } from 'util';
+import fs from 'fs';
+import path from 'path';
+
+const execAsync = promisify(exec);
+
+/**
+ * Start development server with smart port management
+ */
+export async function startServer(options) {
+  console.log('🚀 UIKit Development Server\n');
+
+  try {
+    // Check if we're in a valid project
+    await validateProject();
+
+    // Handle port management
+    const port = parseInt(options.port) || 5173;
+    
+    if (options.restart) {
+      console.log('🔄 Cleaning up existing processes...');
+      await killProcessOnPort(port);
+    }
+
+    const availablePort = await findAvailablePort(port);
+    
+    if (availablePort !== port) {
+      console.log(`⚡ Port ${port} in use, using port ${availablePort}`);
+    }
+
+    // Bundle themes first
+    console.log('🎨 Bundling themes...');
+    await bundleThemesIfNeeded();
+
+    // Start Vite server
+    console.log(`✅ Starting server on http://localhost:${availablePort}\n`);
+    
+    const viteArgs = [
+      'vite',
+      '--port', availablePort.toString(),
+      '--host', '0.0.0.0'
+    ];
+
+    if (options.open) {
+      viteArgs.push('--open');
+    }
+
+    const viteProcess = spawn('npx', viteArgs, {
+      stdio: 'inherit',
+      cwd: process.cwd(),
+      env: { ...process.env, FORCE_COLOR: '1' }
+    });
+
+    // Handle process termination
+    process.on('SIGINT', () => {
+      console.log('\n🛑 Shutting down server...');
+      viteProcess.kill();
+      process.exit(0);
+    });
+
+    process.on('SIGTERM', () => {
+      viteProcess.kill();
+      process.exit(0);
+    });
+
+    viteProcess.on('close', (code) => {
+      if (code !== 0) {
+        console.error(`❌ Server exited with code ${code}`);
+        process.exit(code);
+      }
+    });
+
+    viteProcess.on('error', (error) => {
+      console.error('❌ Failed to start server:', error.message);
+      process.exit(1);
+    });
+
+  } catch (error) {
+    console.error('❌ Serve command failed:', error.message);
+    process.exit(1);
+  }
+}
+
+/**
+ * Validate that we're in a valid UIKit project
+ */
+async function validateProject() {
+  const packageJsonPath = path.join(process.cwd(), 'package.json');
+  const indexHtmlPath = path.join(process.cwd(), 'index.html');
+  const fbcaIndexHtmlPath = path.join(process.cwd(), 'src/web/index.html');
+
+  if (!fs.existsSync(packageJsonPath)) {
+    throw new Error('No package.json found. Run this command in a project directory.');
+  }
+
+  // Check for index.html in standard location or FBCA location
+  if (!fs.existsSync(indexHtmlPath) && !fs.existsSync(fbcaIndexHtmlPath)) {
+    throw new Error('No index.html found. This doesn\'t appear to be a Vite project.');
+  }
+
+  // Check if it's a UIKit project
+  try {
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+    const hasUIKit = packageJson.dependencies?.['@bloomneo/uikit'] || 
+                     packageJson.devDependencies?.['@bloomneo/uikit'];
+    
+    if (!hasUIKit) {
+      console.log('💡 This project doesn\'t use @bloomneo/uikit. Server will start anyway.');
+    }
+  } catch (error) {
+    // Invalid package.json, but let Vite handle it
+  }
+}
+
+/**
+ * Kill process running on specific port
+ */
+async function killProcessOnPort(port) {
+  try {
+    // For Unix/Linux/macOS
+    if (process.platform !== 'win32') {
+      await execAsync(`lsof -ti:${port} | xargs kill -9`).catch(() => {
+        // No process found, which is fine
+      });
+    } else {
+      // For Windows
+      await execAsync(`netstat -ano | findstr :${port}`).then(async (result) => {
+        const lines = result.stdout.split('\\n');
+        for (const line of lines) {
+          const match = line.match(/\\s+(\\d+)$/);
+          if (match) {
+            const pid = match[1];
+            await execAsync(`taskkill /F /PID ${pid}`).catch(() => {
+              // Process might already be dead
+            });
+          }
+        }
+      }).catch(() => {
+        // No process found
+      });
+    }
+  } catch (error) {
+    // Ignore errors in process cleanup
+  }
+}
+
+/**
+ * Find available port starting from the given port
+ */
+async function findAvailablePort(startPort) {
+  for (let port = startPort; port <= startPort + 10; port++) {
+    if (await isPortAvailable(port)) {
+      return port;
+    }
+  }
+  throw new Error(`No available ports found starting from ${startPort}`);
+}
+
+/**
+ * Check if port is available
+ */
+async function isPortAvailable(port) {
+  try {
+    if (process.platform !== 'win32') {
+      const result = await execAsync(`lsof -i:${port}`);
+      return false; // Port is in use
+    } else {
+      const result = await execAsync(`netstat -an | findstr :${port}`);
+      return false; // Port is in use
+    }
+  } catch (error) {
+    return true; // Port is available (command failed = no process using it)
+  }
+}
+
+/**
+ * Bundle themes if theme files exist
+ */
+async function bundleThemesIfNeeded() {
+  const themeDirs = [
+    'src/themes/presets',
+    'src/web/assets/themes/presets',
+    'themes/presets'
+  ];
+
+  let hasThemes = false;
+  for (const dir of themeDirs) {
+    if (fs.existsSync(dir)) {
+      const files = fs.readdirSync(dir).filter(f => 
+        f.endsWith('.js') || f.endsWith('.ts')
+      );
+      if (files.length > 0) {
+        hasThemes = true;
+        break;
+      }
+    }
+  }
+
+  if (hasThemes) {
+    try {
+      // Import and run bundle command
+      const { bundleThemes } = await import('./bundle.js');
+      await bundleThemes({ output: 'src/styles/globals.css' });
+      console.log('✅ Themes bundled successfully');
+    } catch (error) {
+      console.log('⚠️  Theme bundling failed, continuing without themes:', error.message);
+    }
+  }
+}

package/bin/templates/fbca/README.md.template

@@ -0,0 +1,130 @@
+# {{PROJECT_NAME}}
+
+**A modern React FBCA Application built with @bloomneo/uikit**
+
+## 🚀 Quick Start
+
+```bash
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+
+# Build for production
+npm run build
+
+# Preview production build
+npm run preview
+```
+
+## 🎨 UIKit FBCA Features
+
+This Feature-Based Component Architecture application is built with [@bloomneo/uikit](https://github.com/bloomneo/uikit) featuring:
+
+- **37 UI Components** - Forms, tables, navigation, overlays, and more
+- **5 Professional Themes** - Base, Elegant, Metro, Studio, Vivid
+- **5 Layout Systems** - Admin, Auth, Page, Popup, Blank layouts
+- **FBCA Architecture** - Scalable feature-based organization
+- **Theme System** - Light/dark mode with semantic OKLCH colors
+- **TypeScript Support** - Full type safety out of the box
+- **SEO Optimization** - Built-in SEO components and hooks
+
+## 🏗️ Project Structure (FBCA)
+
+```
+{{PROJECT_NAME}}/
+├── src/web/
+│   ├── App.tsx             # Main application component
+│   ├── main.tsx            # Application entry point
+│   ├── index.html          # HTML entry point
+│   ├── styles/
+│   │   └── index.css       # Tailwind CSS v4+ and UIKit styles
+│   ├── lib/
+│   │   └── page-router.tsx # Custom router implementation
+│   ├── features/           # Feature-based organization
+│   │   ├── main/           # Main feature
+│   │   │   ├── pages/      # Feature pages
+│   │   │   └── components/ # Feature components
+│   │   ├── auth/           # Authentication feature
+│   │   ├── gallery/        # Gallery feature
+│   │   └── docs/           # Documentation feature
+│   ├── shared/             # Shared components and utilities
+│   │   ├── components/     # Shared components
+│   │   │   ├── Header.tsx  # Navigation header
+│   │   │   ├── Footer.tsx  # Footer component
+│   │   │   ├── SEO.tsx     # SEO component
+│   │   │   └── index.ts    # Component exports
+│   │   └── hooks/          # Shared hooks
+│   │       └── useSEO.ts   # SEO hook
+│   └── utils/
+│       └── asset.ts        # Asset utility for deployment paths
+├── public/                 # Static assets
+├── docs/                   # Documentation guides
+├── package.json            # Dependencies and scripts
+└── README.md              # This file
+```
+
+## 🎯 Development Commands
+
+```bash
+npm run dev         # Start development server (localhost:5173)
+npm run build       # Build for production
+npm run preview     # Preview production build
+npm run deploy:gh   # Deploy to GitHub Pages
+```
+
+## 🎨 Theme Customization
+
+Change your theme by updating the ThemeProvider in `src/web/main.tsx`:
+
+```jsx
+<ThemeProvider theme="elegant" mode="light">
+  <App />
+</ThemeProvider>
+```
+
+Available themes: `base` | `elegant` | `metro` | `studio` | `vivid`
+Available modes: `light` | `dark`
+
+## 📦 Built With
+
+- **[React 19](https://react.dev)** - UI library
+- **[TypeScript](https://typescriptlang.org)** - Type safety
+- **[Vite](https://vitejs.dev)** - Build tool and dev server
+- **[Tailwind CSS v4+](https://tailwindcss.com)** - Utility-first CSS framework
+- **[@bloomneo/uikit](https://github.com/bloomneo/uikit)** - UI components and layouts
+- **[Lucide React](https://lucide.dev)** - Icon library
+
+## 🏗️ FBCA Architecture
+
+The Feature-Based Component Architecture (FBCA) organizes code by features rather than technical layers:
+
+- **Features** - Self-contained feature modules
+- **Shared** - Reusable components and utilities
+- **Lib** - Custom libraries and utilities
+- **Scalable** - Easy to add new features and maintain
+
+## 🌐 Asset Management
+
+Use the included asset utility for deployment-friendly paths:
+
+```jsx
+import { asset } from '../utils/asset';
+
+// Works in both development and production deployments
+<img src={asset('/images/hero.jpg')} alt="Hero" />
+<link rel="icon" href={asset('/favicon.ico')} />
+```
+
+## 📚 Resources
+
+- **[UIKit Documentation](https://docs.anthropic.com/en/docs/claude-code/claude_code_docs_map.md)** - Complete component reference
+- **[UIKit LLM Guide](./docs/UIKIT_LLM_GUIDE.md)** - Comprehensive usage guide
+- **[React Documentation](https://react.dev)** - React framework guide
+- **[Vite Documentation](https://vitejs.dev)** - Build tool documentation
+- **[FBCA Guide](./docs/QUICKSTART_FBCA.md)** - Feature-based architecture guide
+
+---
+
+**Built with ❤️ using [@bloomneo/uikit](https://github.com/bloomneo/uikit)** ✨

package/bin/templates/fbca/docs/QUICKSTART_FBCA.md

@@ -0,0 +1,368 @@
+# Quick Start: FBCA Template
+
+**Feature-Based Component Architecture with auto-discovery routing - perfect for scalable enterprise applications.**
+
+## 🎯 What is FBCA Template?
+
+FBCA (Feature-Based Component Architecture) organizes code by business features instead of file types. Each feature is self-contained with its own pages, components, and hooks. Routes are automatically discovered from your file structure - no manual route configuration needed.
+
+**Perfect for:**
+- Enterprise applications with multiple features
+- Large teams working on different features
+- Long-term projects that need to scale
+- Applications with 10+ distinct feature areas
+- Projects requiring feature isolation and modularity
+
+## ⚡ 30-Second Setup
+
+### Step 1: Install UIKit CLI Globally
+```bash
+npm install -g @bloomneo/uikit
+```
+
+### Step 2: Create FBCA Project
+```bash
+uikit create my-fbca-app --fbca --theme elegant
+cd my-fbca-app && npm run dev
+```
+
+### Step 3: Project Structure
+```
+src/
+└── web/
+    ├── App.tsx                          # Root app with theme provider
+    ├── main.tsx                         # Entry point
+    ├── index.html                       # HTML template
+    ├── lib/
+    │   └── page-router.tsx              # Auto-discovery routing engine
+    ├── features/
+    │   ├── main/
+    │   │   ├── pages/
+    │   │   │   ├── index.tsx            # Route: / (homepage)
+    │   │   │   └── About.tsx            # Route: /about
+    │   │   └── components/
+    │   │       └── CTASection.tsx       # Feature-specific components
+    │   ├── auth/
+    │   │   └── pages/
+    │   │       └── index.tsx            # Route: /auth (login)
+    │   ├── gallery/
+    │   │   ├── pages/
+    │   │   │   └── index.tsx            # Route: /gallery
+    │   │   └── hooks/
+    │   │       └── useGallery.ts        # Feature-specific logic
+    │   └── docs/
+    │       └── pages/
+    │           └── [...slug].tsx        # Route: /docs/* (catch-all)
+    ├── shared/
+    │   ├── components/                  # Reusable across features
+    │   │   ├── Header.tsx               # Site header
+    │   │   ├── Footer.tsx               # Site footer
+    │   │   └── SEO.tsx                  # SEO component
+    │   └── hooks/
+    │       └── useSEO.ts                # Shared logic
+    └── styles/
+        └── index.css                    # Global styles
+```
+
+## 🧭 How FBCA Works
+
+### Auto-Discovery Routing
+**Why:** Zero configuration routing based on file structure
+**When:** Want file-system based routing like Next.js
+**How:** PageRouter scans features/*/pages/ and creates routes automatically
+
+```jsx
+// File structure determines URL routes:
+/features/main/pages/index.tsx          → / (homepage)
+/features/main/pages/About.tsx          → /about
+/features/auth/pages/index.tsx          → /auth
+/features/gallery/pages/index.tsx       → /gallery
+/features/docs/pages/[...slug].tsx      → /docs/* (catch-all)
+```
+
+### App.tsx - Root Configuration
+**Why:** Simple root app with theme provider and router
+**When:** Global app setup
+**How:** Delegates routing to PageRouter
+
+```jsx
+function App() {
+  return (
+    <ThemeProvider theme="base" mode="light" forceConfig={true}>
+      <Router>
+        <PageRouter />
+      </Router>
+    </ThemeProvider>
+  );
+}
+```
+
+### PageRouter - Auto-Discovery Engine
+**Why:** Automatically discovers and configures routes
+**When:** Adding new pages without manual route config
+**How:** Uses Vite glob imports to scan feature pages
+
+```jsx
+// Auto-discovers all page files
+const pageFiles = import.meta.glob('../features/*/pages/**/*.{tsx,jsx}', { eager: true });
+
+// Converts file paths to routes:
+// features/main/pages/index.tsx → /
+// features/gallery/pages/index.tsx → /gallery
+// features/auth/pages/login.tsx → /auth/login
+```
+
+## 📁 Feature Structure
+
+### Feature Organization
+**Why:** Each feature is completely self-contained
+**When:** Building distinct business features
+**How:** Organize by feature, not by file type
+
+```jsx
+// ✅ FBCA Way - Organize by feature
+/features/blog/
+  ├── pages/           # Blog pages
+  ├── components/      # Blog-specific components
+  ├── hooks/           # Blog business logic
+  └── types/           # Blog type definitions
+
+// ❌ Traditional Way - Organize by file type
+/pages/              # All pages mixed together
+/components/         # All components mixed together
+/hooks/              # All hooks mixed together
+```
+
+### Page Component Example
+**Why:** Each page handles its own layout and content
+**When:** Creating feature pages
+**How:** Use PageLayout with shared Header/Footer
+
+```jsx
+// features/gallery/pages/index.tsx
+import { PageLayout } from '@bloomneo/uikit/page';
+import { Header, Footer, SEO } from '../../../shared/components';
+import { useGallery } from '../hooks/useGallery';
+
+export default function GalleryPage() {
+  const { images, loading } = useGallery();
+
+  return (
+    <PageLayout>
+      <SEO
+        title="Gallery - UIKit FBCA Demo"
+        description="Browse our image gallery built with Feature-Based Component Architecture and UIKit components"
+        keywords="gallery, images, fbca, uikit, react"
+        ogTitle="Gallery Feature - UIKit FBCA"
+        ogDescription="Explore the gallery feature in our FBCA demo application"
+      />
+      <Header />
+
+      <PageLayout.Content>
+        <h1 className="voila-heading text-4xl mb-8">Gallery</h1>
+        {loading ? (
+          <div>Loading images...</div>
+        ) : (
+          <div className="grid grid-cols-3 gap-4">
+            {images.map(image => (
+              <img key={image.id} src={image.url} alt={image.title} />
+            ))}
+          </div>
+        )}
+      </PageLayout.Content>
+
+      <Footer />
+    </PageLayout>
+  );
+}
+```
+
+### Shared Components
+**Why:** Reusable components across all features
+**When:** Common UI elements like headers, footers, SEO
+**How:** Place in /shared/components/
+
+```jsx
+// shared/components/Header.tsx
+export const Header = () => {
+  return (
+    <PageLayout.Header
+      navigation={[
+        { key: 'home', label: 'Home', href: '/' },
+        { key: 'gallery', label: 'Gallery', href: '/gallery' },
+        { key: 'auth', label: 'Login', href: '/auth' },
+        { key: 'docs', label: 'Docs', href: '/docs' },
+      ]}
+      logo={<div className="font-bold">FBCA Demo</div>}
+    />
+  );
+};
+
+// shared/components/SEO.tsx
+export const SEO = (props) => {
+  useSEO(props);
+  return null; // Component doesn't render anything
+};
+```
+
+### SEO Management
+**Why:** Each page needs proper SEO meta tags
+**When:** Want search engine optimization and social sharing
+**How:** Use SEO component with useSEO hook
+
+```jsx
+// shared/hooks/useSEO.ts - Manages document head
+export const useSEO = ({
+  title = 'UIKit FBCA Demo',
+  description = 'Feature-Based Component Architecture with UIKit components',
+  keywords = 'react, fbca, uikit, components, typescript',
+  ogTitle,
+  ogDescription,
+  ogImage = '/favicon.ico',
+  canonical
+}) => {
+  useEffect(() => {
+    document.title = title;
+    // Sets meta description, keywords, Open Graph, Twitter Cards
+  }, [title, description, keywords, ogTitle, ogDescription, ogImage, canonical]);
+};
+```
+
+## 🎯 When to Use FBCA Template
+
+**Perfect for:**
+- Enterprise applications with multiple business domains
+- Large teams (5+ developers) working on different features
+- Long-term projects that need to scale over time
+- Applications with distinct feature areas (auth, billing, analytics, etc.)
+- Projects requiring feature isolation for testing/deployment
+
+**Key Benefits:**
+- **Feature isolation** - Features don't depend on each other
+- **Team scalability** - Different teams can work on different features
+- **Zero-config routing** - File structure determines URLs
+- **Maintainability** - Easy to find and modify feature code
+- **Testability** - Test features in complete isolation
+
+**Not ideal for:**
+- Simple websites (use SPA template)
+- Small teams (use Multi template)
+- Quick prototypes (use Single template)
+- Applications with heavy feature interdependency
+
+## ⚡ Adding New Features
+
+### Step 1: Create Feature Structure
+**Why:** Follow FBCA conventions for consistency
+**When:** Adding new business functionality
+**How:** Create feature folder with pages, components, hooks
+
+```bash
+# Create new feature structure
+mkdir -p src/web/features/blog/pages
+mkdir -p src/web/features/blog/components
+mkdir -p src/web/features/blog/hooks
+```
+
+### Step 2: Add Feature Pages
+**Why:** Pages automatically become routes
+**When:** Need URLs for your feature
+**How:** Create .tsx files in pages/ folder
+
+```jsx
+// features/blog/pages/index.tsx - Route: /blog
+export default function BlogPage() {
+  return (
+    <PageLayout>
+      <Header />
+      <PageLayout.Content>
+        <h1>Blog Posts</h1>
+        {/* Blog list */}
+      </PageLayout.Content>
+      <Footer />
+    </PageLayout>
+  );
+}
+
+// features/blog/pages/[id].tsx - Route: /blog/:id
+export default function BlogPostPage() {
+  return (
+    <PageLayout>
+      <Header />
+      <PageLayout.Content>
+        <h1>Blog Post</h1>
+        {/* Individual blog post */}
+      </PageLayout.Content>
+      <Footer />
+    </PageLayout>
+  );
+}
+```
+
+### Step 3: Add Feature Logic
+**Why:** Keep business logic isolated in feature
+**When:** Need feature-specific functionality
+**How:** Create hooks and components in feature folder
+
+```jsx
+// features/blog/hooks/useBlog.ts
+export const useBlog = () => {
+  const [posts, setPosts] = useState([]);
+
+  const fetchPosts = async () => {
+    // Blog-specific logic
+  };
+
+  return { posts, fetchPosts };
+};
+
+// features/blog/components/BlogCard.tsx
+export const BlogCard = ({ post }) => {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>{post.title}</CardTitle>
+      </CardHeader>
+      <CardContent>
+        {post.excerpt}
+      </CardContent>
+    </Card>
+  );
+};
+```
+
+## 🔧 Advanced Routing
+
+### Dynamic Routes
+**Why:** Handle variable URL segments
+**When:** Need routes like /blog/post-123
+**How:** Use [param].tsx file naming
+
+```jsx
+// features/blog/pages/[slug].tsx → /blog/:slug
+// features/user/pages/[id]/settings.tsx → /user/:id/settings
+```
+
+### Catch-All Routes
+**Why:** Handle multiple URL segments
+**When:** Need routes like /docs/guide/getting-started
+**How:** Use [...param].tsx file naming
+
+```jsx
+// features/docs/pages/[...slug].tsx → /docs/*
+```
+
+### Nested Routes
+**Why:** Organize related pages hierarchically
+**When:** Complex feature with sub-sections
+**How:** Create nested folder structure
+
+```jsx
+// features/admin/pages/users/index.tsx → /admin/users
+// features/admin/pages/users/[id].tsx → /admin/users/:id
+// features/admin/pages/settings/billing.tsx → /admin/settings/billing
+```
+
+---
+
+**Built with @bloomneo/uikit** ✨