@smicolon/fasla-ui 0.2.2

package/README.md

@@ -0,0 +1,141 @@
+# @smicolon/fasla-ui
+
+[![npm version](https://img.shields.io/npm/v/@smicolon/fasla-ui.svg)](https://www.npmjs.com/package/@smicolon/fasla-ui)
+[![npm downloads](https://img.shields.io/npm/dm/@smicolon/fasla-ui.svg)](https://www.npmjs.com/package/@smicolon/fasla-ui)
+[![license](https://img.shields.io/npm/l/@smicolon/fasla-ui.svg)](https://github.com/smicolon/fasla-ui/blob/main/LICENSE)
+
+A professional React UI component library built on **shadcn/ui** primitives. Provides animated effects components (like Magic UI), app building blocks, and design tokens - all distributed via a shadcn-compatible registry.
+
+## Features
+
+- **30+ Components** - UI primitives, app blocks, and animated effects
+- **shadcn Compatible** - Works seamlessly with existing shadcn/ui projects
+- **Tailwind CSS** - Utility-first styling with full customization
+- **Framer Motion** - Smooth animations with `prefers-reduced-motion` support
+- **TypeScript** - Full type safety and IntelliSense
+- **Design Tokens** - Consistent spacing, colors, and density profiles
+- **Accessible** - WCAG compliant with keyboard navigation support
+- **Tree Shakeable** - Import only what you need
+
+## Installation
+
+```bash
+# Using the CLI (recommended)
+npx @smicolon/cli init
+npx @smicolon/cli add button
+
+# Or install the package directly
+npm install @smicolon/fasla-ui
+# or
+yarn add @smicolon/fasla-ui
+# or
+pnpm add @smicolon/fasla-ui
+```
+
+## Components
+
+### UI Primitives
+Core building blocks with CVA variants for consistent styling:
+
+| Component | Description |
+|-----------|-------------|
+| **Button** | Multiple variants (default, destructive, outline, secondary, ghost, link) with loading state |
+| **Input** | Text input with validation states and icon support |
+| **Textarea** | Multi-line text input with auto-resize |
+| **Select** | Dropdown selection with search |
+| **Checkbox** | Checkbox with label and description |
+| **Switch** | Toggle switch with multiple sizes |
+| **Tabs** | Tabbed navigation with animations |
+| **Badge** | Status indicators and labels |
+| **Avatar** | User avatars with fallback initials |
+| **Card** | Flexible content containers |
+| **Skeleton** | Loading placeholders |
+| **Combobox** | Searchable select with autocomplete |
+
+### App Blocks
+Pre-built page compositions for rapid development:
+
+| Component | Description |
+|-----------|-------------|
+| **AppShell** | Application layout with sidebar and header |
+| **PageHeader** | Title, breadcrumbs, and action buttons |
+| **DataTable** | Sortable, filterable tables with pagination |
+| **FormSection** | Grouped form fields with validation |
+| **EmptyState** | Empty content placeholders with CTAs |
+| **Sidebar** | Collapsible navigation sidebar |
+| **Navbar** | Top navigation bar |
+| **StatsCard** | Metric display cards |
+
+### Effects
+Animated components for visual flair (powered by Framer Motion):
+
+| Component | Description |
+|-----------|-------------|
+| **ShimmerButton** | Button with animated shimmer effect |
+| **AnimatedGradient** | Smooth gradient background animations |
+| **BorderBeam** | Animated border glow effect |
+| **Spotlight** | Cursor-following spotlight |
+| **TextReveal** | Text reveal on scroll |
+| **GlowCard** | Card with hover glow effect |
+| **TypewriterText** | Typewriter text animation |
+
+## Quick Start
+
+```tsx
+import { Button } from "@smicolon/fasla-ui/registry/ui/button"
+import { Card, CardHeader, CardTitle, CardContent } from "@smicolon/fasla-ui/registry/ui/card"
+import { ShimmerButton } from "@smicolon/fasla-ui/registry/effects/shimmer-button"
+
+export function MyComponent() {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Welcome</CardTitle>
+      </CardHeader>
+      <CardContent className="space-x-4">
+        <Button variant="default">Get Started</Button>
+        <ShimmerButton>Learn More</ShimmerButton>
+      </CardContent>
+    </Card>
+  )
+}
+```
+
+## Peer Dependencies
+
+```json
+{
+  "react": "^18.0.0",
+  "react-dom": "^18.0.0",
+  "tailwindcss": "^3.4.0",
+  "framer-motion": "^11.0.0"  // optional, required for effects
+}
+```
+
+## Tailwind Configuration
+
+Add fasla-ui to your `tailwind.config.js`:
+
+```js
+module.exports = {
+  content: [
+    // ... your content paths
+    "./node_modules/@smicolon/fasla-ui/**/*.{js,ts,jsx,tsx}",
+  ],
+}
+```
+
+## Documentation
+
+Visit [ui.smicolon.com](https://ui.smicolon.com) for full documentation, examples, and API reference.
+
+## Related
+
+- [@smicolon/cli](https://www.npmjs.com/package/@smicolon/cli) - CLI for adding components
+- [shadcn/ui](https://ui.shadcn.com) - The foundation this library builds on
+- [Tailwind CSS](https://tailwindcss.com) - Utility-first CSS framework
+- [Framer Motion](https://www.framer.com/motion/) - Animation library for React
+
+## License
+
+MIT - See [LICENSE](https://github.com/smicolon/fasla-ui/blob/main/LICENSE) for details.

package/bin/fasla-ui.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+
+function usage() {
+  console.log(`fasla-ui (scaffold)
+Usage:
+  fasla-ui add <registry-path> --to <target-dir>
+
+Example:
+  fasla-ui add blocks/app-shell --to ../client/src/components/blocks
+`);
+}
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) copyDir(srcPath, destPath);
+    else fs.copyFileSync(srcPath, destPath);
+  }
+}
+
+const args = process.argv.slice(2);
+if (args.length === 0 || args.includes("-h") || args.includes("--help")) {
+  usage();
+  process.exit(0);
+}
+
+const cmd = args[0];
+if (cmd !== "add") {
+  usage();
+  process.exit(1);
+}
+
+const item = args[1];
+const toIdx = args.findIndex((a) => a === "--to");
+const targetDir = toIdx >= 0 ? args[toIdx + 1] : null;
+if (!item || !targetDir) {
+  usage();
+  process.exit(1);
+}
+
+const registryRoot = path.resolve(process.cwd(), "packages/fasla-ui/registry");
+const srcDir = path.join(registryRoot, item);
+if (!fs.existsSync(srcDir)) {
+  console.error(`Registry path not found: ${srcDir}`);
+  process.exit(1);
+}
+
+const destDir = path.resolve(process.cwd(), targetDir, path.basename(item));
+copyDir(srcDir, destDir);
+console.log(`Added ${item} -> ${destDir}`);

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { cn } from './lib/utils.js';
+export { Density, TokenSet, baseTokens, tailwindSemanticColors } from './tokens/index.js';
+export { MotionPreset, useMotionPresets } from './motion/index.js';
+export { RegistryItem, RegistryItemType, getRegistryItem, getRegistryItemsByCategory, getRegistryItemsByType, registry } from './registry/index.js';
+import 'clsx';

package/dist/index.js

@@ -0,0 +1,241 @@
+import { clsx } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+import { useReducedMotion } from 'framer-motion';
+
+// src/lib/utils.ts
+function cn(...inputs) {
+  return twMerge(clsx(inputs));
+}
+
+// src/tokens/model.ts
+var baseTokens = {
+  radius: { sm: "0.5rem", md: "0.75rem", lg: "1rem" },
+  spacing: { densityMultiplier: { compact: 0.9, comfortable: 1, spacious: 1.1 } },
+  typography: { fontFamily: "Inter", baseFontSizePx: 16, lineHeight: 1.5 },
+  motion: { durationsMs: { fast: 120, base: 180, slow: 260 } }
+};
+
+// src/tokens/tailwind.ts
+var tailwindSemanticColors = {
+  border: "hsl(var(--border))",
+  input: "hsl(var(--input))",
+  ring: "hsl(var(--ring))",
+  background: "hsl(var(--background))",
+  foreground: "hsl(var(--foreground))",
+  primary: {
+    DEFAULT: "hsl(var(--primary))",
+    foreground: "hsl(var(--primary-foreground))"
+  },
+  secondary: {
+    DEFAULT: "hsl(var(--secondary))",
+    foreground: "hsl(var(--secondary-foreground))"
+  },
+  muted: {
+    DEFAULT: "hsl(var(--muted))",
+    foreground: "hsl(var(--muted-foreground))"
+  },
+  destructive: {
+    DEFAULT: "hsl(var(--destructive))",
+    foreground: "hsl(var(--destructive-foreground))"
+  }
+};
+function useMotionPresets() {
+  const prefersReduced = useReducedMotion();
+  const durations = {
+    fast: 0.12,
+    base: 0.18,
+    slow: 0.26
+  };
+  const easing = {
+    standard: [0.2, 0, 0, 1],
+    emphasized: [0.2, 0.8, 0.2, 1]
+  };
+  const safe = (preset) => {
+    if (!prefersReduced) return preset;
+    return {
+      initial: { opacity: 0 },
+      animate: { opacity: 1 },
+      exit: { opacity: 0 },
+      transition: { duration: durations.fast }
+    };
+  };
+  return {
+    fadeIn: safe({
+      initial: { opacity: 0 },
+      animate: { opacity: 1 },
+      exit: { opacity: 0 },
+      transition: { duration: durations.base, ease: easing.standard }
+    }),
+    slideUp: safe({
+      initial: { opacity: 0, y: 10 },
+      animate: { opacity: 1, y: 0 },
+      exit: { opacity: 0, y: 6 },
+      transition: { duration: durations.base, ease: easing.standard }
+    }),
+    modalScale: safe({
+      initial: { opacity: 0, scale: 0.98 },
+      animate: { opacity: 1, scale: 1 },
+      exit: { opacity: 0, scale: 0.98 },
+      transition: { duration: durations.base, ease: easing.emphasized }
+    }),
+    stagger: {
+      container: safe({
+        initial: { opacity: 0 },
+        animate: { opacity: 1 },
+        transition: { staggerChildren: 0.06, delayChildren: 0.02 }
+      }),
+      item: safe({
+        initial: { opacity: 0, y: 8 },
+        animate: { opacity: 1, y: 0 },
+        transition: { duration: durations.base, ease: easing.standard }
+      })
+    },
+    meta: { prefersReduced, durations, easing }
+  };
+}
+
+// src/registry/index.ts
+var registry = [
+  // UI Primitives
+  {
+    name: "button",
+    type: "ui",
+    title: "Button",
+    description: "A button component with multiple variants, sizes, and loading state.",
+    sourcePath: "registry/ui/button",
+    dependencies: ["@radix-ui/react-slot", "class-variance-authority"],
+    categories: ["primitives", "forms"]
+  },
+  {
+    name: "input",
+    type: "ui",
+    title: "Input",
+    description: "An input component with variants for validation states and icon support.",
+    sourcePath: "registry/ui/input",
+    dependencies: ["class-variance-authority"],
+    categories: ["primitives", "forms"]
+  },
+  {
+    name: "card",
+    type: "ui",
+    title: "Card",
+    description: "A card component with header, content, and footer sections.",
+    sourcePath: "registry/ui/card",
+    categories: ["primitives", "layout"]
+  },
+  {
+    name: "badge",
+    type: "ui",
+    title: "Badge",
+    description: "A badge component for status indicators with multiple variants.",
+    sourcePath: "registry/ui/badge",
+    dependencies: ["class-variance-authority"],
+    categories: ["primitives", "data-display"]
+  },
+  {
+    name: "skeleton",
+    type: "ui",
+    title: "Skeleton",
+    description: "Loading skeleton placeholders with pre-built variants for text, avatars, and cards.",
+    sourcePath: "registry/ui/skeleton",
+    categories: ["primitives", "feedback"]
+  },
+  // Blocks
+  {
+    name: "app-shell",
+    type: "block",
+    title: "App Shell",
+    description: "Application shell with sidebar, header, and content area.",
+    sourcePath: "registry/blocks/app-shell",
+    categories: ["layout", "application"]
+  },
+  {
+    name: "page-header",
+    type: "block",
+    title: "Page Header",
+    description: "Page header with title, breadcrumb, description, and actions.",
+    sourcePath: "registry/blocks/page-header",
+    categories: ["layout", "navigation"]
+  },
+  {
+    name: "empty-state",
+    type: "block",
+    title: "Empty State",
+    description: "Empty state component with icon, title, description, and actions.",
+    sourcePath: "registry/blocks/empty-state",
+    categories: ["feedback", "data-display"]
+  },
+  {
+    name: "form-section",
+    type: "block",
+    title: "Form Section",
+    description: "Form section with title, description, fields, and actions.",
+    sourcePath: "registry/blocks/form-section",
+    categories: ["forms", "layout"]
+  },
+  {
+    name: "data-table",
+    type: "block",
+    title: "Data Table",
+    description: "Data table with sorting, pagination, and custom cell rendering.",
+    sourcePath: "registry/blocks/data-table",
+    categories: ["data-display", "tables"]
+  },
+  // Effects
+  {
+    name: "shimmer-button",
+    type: "effect",
+    title: "Shimmer Button",
+    description: "A button with animated shimmer effect.",
+    sourcePath: "registry/effects/shimmer-button",
+    dependencies: ["framer-motion"],
+    categories: ["effects", "buttons"]
+  },
+  {
+    name: "animated-gradient",
+    type: "effect",
+    title: "Animated Gradient",
+    description: "Animated gradient background and text effects.",
+    sourcePath: "registry/effects/animated-gradient",
+    dependencies: ["framer-motion"],
+    categories: ["effects", "backgrounds"]
+  },
+  {
+    name: "text-reveal",
+    type: "effect",
+    title: "Text Reveal",
+    description: "Character and word reveal animations.",
+    sourcePath: "registry/effects/text-reveal",
+    dependencies: ["framer-motion"],
+    categories: ["effects", "text"]
+  },
+  {
+    name: "border-beam",
+    type: "effect",
+    title: "Border Beam",
+    description: "Animated border beam and glowing border effects.",
+    sourcePath: "registry/effects/border-beam",
+    dependencies: ["framer-motion"],
+    categories: ["effects", "borders"]
+  },
+  {
+    name: "spotlight",
+    type: "effect",
+    title: "Spotlight",
+    description: "Cursor-following spotlight effect.",
+    sourcePath: "registry/effects/spotlight",
+    dependencies: ["framer-motion"],
+    categories: ["effects", "interactive"]
+  }
+];
+function getRegistryItem(name) {
+  return registry.find((item) => item.name === name);
+}
+function getRegistryItemsByType(type) {
+  return registry.filter((item) => item.type === type);
+}
+function getRegistryItemsByCategory(category) {
+  return registry.filter((item) => item.categories?.includes(category));
+}
+
+export { baseTokens, cn, getRegistryItem, getRegistryItemsByCategory, getRegistryItemsByType, registry, tailwindSemanticColors, useMotionPresets };

package/dist/lib/utils.d.ts

@@ -0,0 +1,9 @@
+import { ClassValue } from 'clsx';
+
+/**
+ * Merge Tailwind CSS classes with clsx and tailwind-merge.
+ * This ensures proper class merging and deduplication.
+ */
+declare function cn(...inputs: ClassValue[]): string;
+
+export { cn };

package/dist/lib/utils.js

@@ -0,0 +1,9 @@
+import { clsx } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+// src/lib/utils.ts
+function cn(...inputs) {
+  return twMerge(clsx(inputs));
+}
+
+export { cn };

package/dist/motion/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Motion presets: use these across the app to keep motion consistent.
+ * Rule: do not hardcode durations/easing elsewhere.
+ */
+type MotionPreset = {
+    initial?: Record<string, unknown>;
+    animate?: Record<string, unknown>;
+    exit?: Record<string, unknown>;
+    transition?: Record<string, unknown>;
+};
+declare function useMotionPresets(): {
+    fadeIn: MotionPreset;
+    slideUp: MotionPreset;
+    modalScale: MotionPreset;
+    stagger: {
+        container: MotionPreset;
+        item: MotionPreset;
+    };
+    meta: {
+        prefersReduced: boolean | null;
+        durations: {
+            fast: number;
+            base: number;
+            slow: number;
+        };
+        easing: {
+            standard: number[];
+            emphasized: number[];
+        };
+    };
+};
+
+export { type MotionPreset, useMotionPresets };

package/dist/motion/index.js

@@ -0,0 +1,59 @@
+import { useReducedMotion } from 'framer-motion';
+
+// src/motion/presets.ts
+function useMotionPresets() {
+  const prefersReduced = useReducedMotion();
+  const durations = {
+    fast: 0.12,
+    base: 0.18,
+    slow: 0.26
+  };
+  const easing = {
+    standard: [0.2, 0, 0, 1],
+    emphasized: [0.2, 0.8, 0.2, 1]
+  };
+  const safe = (preset) => {
+    if (!prefersReduced) return preset;
+    return {
+      initial: { opacity: 0 },
+      animate: { opacity: 1 },
+      exit: { opacity: 0 },
+      transition: { duration: durations.fast }
+    };
+  };
+  return {
+    fadeIn: safe({
+      initial: { opacity: 0 },
+      animate: { opacity: 1 },
+      exit: { opacity: 0 },
+      transition: { duration: durations.base, ease: easing.standard }
+    }),
+    slideUp: safe({
+      initial: { opacity: 0, y: 10 },
+      animate: { opacity: 1, y: 0 },
+      exit: { opacity: 0, y: 6 },
+      transition: { duration: durations.base, ease: easing.standard }
+    }),
+    modalScale: safe({
+      initial: { opacity: 0, scale: 0.98 },
+      animate: { opacity: 1, scale: 1 },
+      exit: { opacity: 0, scale: 0.98 },
+      transition: { duration: durations.base, ease: easing.emphasized }
+    }),
+    stagger: {
+      container: safe({
+        initial: { opacity: 0 },
+        animate: { opacity: 1 },
+        transition: { staggerChildren: 0.06, delayChildren: 0.02 }
+      }),
+      item: safe({
+        initial: { opacity: 0, y: 8 },
+        animate: { opacity: 1, y: 0 },
+        transition: { duration: durations.base, ease: easing.standard }
+      })
+    },
+    meta: { prefersReduced, durations, easing }
+  };
+}
+
+export { useMotionPresets };

package/dist/registry/index.d.ts

@@ -0,0 +1,17 @@
+type RegistryItemType = "ui" | "block" | "effect" | "hook";
+type RegistryItem = {
+    name: string;
+    type: RegistryItemType;
+    title: string;
+    description: string;
+    sourcePath: string;
+    dependencies?: string[];
+    registryDependencies?: string[];
+    categories?: string[];
+};
+declare const registry: RegistryItem[];
+declare function getRegistryItem(name: string): RegistryItem | undefined;
+declare function getRegistryItemsByType(type: RegistryItemType): RegistryItem[];
+declare function getRegistryItemsByCategory(category: string): RegistryItem[];
+
+export { type RegistryItem, type RegistryItemType, getRegistryItem, getRegistryItemsByCategory, getRegistryItemsByType, registry };