@smicolon/fasla-ui 0.3.0 → 0.4.1

package/README.md

@@ -19,12 +19,25 @@ A professional React UI component library built on **shadcn/ui** primitives. Pro
 
 ## Installation
 
+Components are copied into your project with the CLI, as with shadcn/ui:
+
+```bash
+npx @smicolon/cli init              # once per project: writes components.json and lib/utils.ts,
+                                    # and installs clsx and tailwind-merge, which lib/utils.ts imports
+npx @smicolon/cli add button card shimmer-button
+```
+
+`add` ends by printing the install command for the packages the components
+need, in your project's package manager. For `button card shimmer-button` with npm it is:
+
 ```bash
-# Using the CLI (recommended)
-npx @smicolon/cli init
-npx @smicolon/cli add button
+npm install @radix-ui/react-slot class-variance-authority lucide-react framer-motion
+```
 
-# Or install the package directly
+This package holds the design tokens, the Tailwind preset and the motion
+presets, not the components. Install it when you want those:
+
+```bash
 npm install @smicolon/fasla-ui
 # or
 yarn add @smicolon/fasla-ui
@@ -83,9 +96,9 @@ Animated components for visual flair (powered by Framer Motion):
 ## 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"
+import { Button } from "@/components/ui/button"
+import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card"
+import { ShimmerButton } from "@/components/ui/shimmer-button"
 
 export function MyComponent() {
   return (
@@ -106,26 +119,45 @@ export function MyComponent() {
 
 ```json
 {
-  "react": "^18.0.0",
-  "react-dom": "^18.0.0",
-  "tailwindcss": "^3.4.0",
-  "framer-motion": "^11.0.0"  // optional, required for effects
+  "react": "^18.0.0 || ^19.0.0",
+  "react-dom": "^18.0.0 || ^19.0.0",
+  "tailwindcss": "^3.4.0 || ^4.1.4",
+  "framer-motion": "^11.0.0 || ^12.0.0 || ^13.0.0 || ^14.0.0"  // optional, required for effects
 }
 ```
 
-## Tailwind Configuration
+## Theme
 
-Add fasla-ui to your `tailwind.config.js`:
+Components take every colour from your theme. `init` asks which of two layers
+you want and installs it; both include the base layer. The shadcn commands below
+install one too, or switch a project to the other one later.
 
-```js
-module.exports = {
-  content: [
-    // ... your content paths
-    "./node_modules/@smicolon/fasla-ui/**/*.{js,ts,jsx,tsx}",
-  ],
-}
+They need a project that is already set up, with a `components.json`: in a new
+project, run `npx @smicolon/cli init` first, or `npx shadcn@latest init`. Without
+one, the shadcn CLI sets the project up itself, and its preset's colours replace
+Fasla's. On Next.js 14, use `npx @smicolon/cli init`: `shadcn init` writes
+Tailwind 4 styles and loads Geist from `next/font`, which Next.js 14 has neither of.
+
+```bash
+# Starting from scratch: use Fasla's colours (palette, radius, Geist).
+npx shadcn@latest add https://ui.smicolon.com/r/theme.json https://ui.smicolon.com/r/font-geist.json
+
+# The same on Next.js 14, without Geist: its template already loads it.
+npx shadcn@latest add https://ui.smicolon.com/r/theme.json
+
+# I have a brand: keep my colours (base layer only)
+npx shadcn@latest add https://ui.smicolon.com/r/theme-base.json
 ```
 
+The base layer adds only what shadcn doesn't have: the success, warning and
+info tokens and the soft tints, the type scale with Arabic line heights, the
+Arabic setting, and the Cairo font. It never changes a colour you already
+have. Arabic text uses `--font-arabic`; point it at another font to swap Cairo.
+
+Fasla's base components replace shadcn's components of the same name in
+`components/ui`; `add` asks before replacing a file that isn't Fasla's. Blocks
+install to `components/blocks`.
+
 ## Documentation
 
 Visit [ui.smicolon.com](https://ui.smicolon.com) for full documentation, examples, and API reference.

package/dist/index.cjs

@@ -0,0 +1,319 @@
+'use strict';
+
+var clsx = require('clsx');
+var tailwindMerge = require('tailwind-merge');
+var framerMotion = require('framer-motion');
+
+// src/lib/utils.ts
+function cn(...inputs) {
+  return tailwindMerge.twMerge(clsx.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 } },
+  // Brand V2.5 §14 — Geist is the LTR face. Arabic is set in Cairo, which the
+  // Tailwind preset selects per direction; this scaffold carries only the base.
+  // 16/24 is the `Base` rung, identical in both Figma ramps.
+  typography: { fontFamily: "Geist", baseFontSizePx: 16, lineHeight: 1.5 },
+  motion: { durationsMs: { fast: 120, base: 180, slow: 260 } }
+};
+
+// src/tokens/tailwind.ts
+var semanticColor = (name) => `color-mix(in oklch, var(--${name}) calc(<alpha-value> * 100%), transparent)`;
+var c = semanticColor;
+var tailwindSemanticColors = {
+  // Surfaces
+  background: c("background"),
+  foreground: c("foreground"),
+  card: { DEFAULT: c("card"), foreground: c("card-foreground") },
+  popover: { DEFAULT: c("popover"), foreground: c("popover-foreground") },
+  // Actions. `primary` is Figma's strong neutral (#0a0a0a light, #fafafa dark),
+  // identical to `foreground` in both modes. It is NOT a brand accent — an app
+  // that wants its brand colour should define its own token for it.
+  primary: { DEFAULT: c("primary"), foreground: c("primary-foreground") },
+  secondary: { DEFAULT: c("secondary"), foreground: c("secondary-foreground") },
+  muted: { DEFAULT: c("muted"), foreground: c("muted-foreground") },
+  accent: { DEFAULT: c("accent"), foreground: c("accent-foreground") },
+  destructive: {
+    DEFAULT: c("destructive"),
+    foreground: c("destructive-foreground")
+  },
+  // Lines and focus
+  border: c("border"),
+  input: c("input"),
+  ring: c("ring"),
+  // Status
+  success: { DEFAULT: c("success"), foreground: c("success-foreground") },
+  warning: { DEFAULT: c("warning"), foreground: c("warning-foreground") },
+  info: { DEFAULT: c("info"), foreground: c("info-foreground") },
+  // Soft tints — Figma's `opacity/*` variables, already translucent. The Badge
+  // Soft type lays one over `card`, exactly as Figma stacks the two fills, so
+  // the chip reads the same on any surface. Only `primary` changes in Dark.
+  soft: {
+    primary: c("soft-primary"),
+    secondary: c("soft-secondary"),
+    info: c("soft-info"),
+    success: c("soft-success"),
+    warning: c("soft-warning"),
+    destructive: c("soft-destructive")
+  },
+  // Inverse — a fixed contrast band, not a mode-reactive surface.
+  "background-inverse": c("background-inverse"),
+  "foreground-inverse": c("foreground-inverse"),
+  "muted-foreground-inverse": c("muted-foreground-inverse"),
+  // Charts
+  "chart-1": c("chart-1"),
+  "chart-2": c("chart-2"),
+  "chart-3": c("chart-3"),
+  "chart-4": c("chart-4"),
+  "chart-5": c("chart-5"),
+  sidebar: {
+    DEFAULT: c("sidebar"),
+    foreground: c("sidebar-foreground"),
+    primary: c("sidebar-primary"),
+    "primary-foreground": c("sidebar-primary-foreground"),
+    accent: c("sidebar-accent"),
+    "accent-foreground": c("sidebar-accent-foreground"),
+    border: c("sidebar-border"),
+    ring: c("sidebar-ring")
+  }
+};
+function useMotionPresets() {
+  const prefersReduced = framerMotion.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", "lucide-react"],
+    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 compact inline label for status, category or metadata: solid, soft and outline types in six semantic tones, with an optional icon, avatar and close button.",
+    sourcePath: "registry/ui/badge",
+    dependencies: ["class-variance-authority", "lucide-react"],
+    categories: ["primitives", "data-display"]
+  },
+  {
+    name: "avatar",
+    type: "ui",
+    title: "Avatar",
+    description: "A user's photo, initials or icon, in three sizes and two radii, with an optional border and presence dot. Falls back from photo to initials to icon on its own.",
+    sourcePath: "registry/ui/avatar",
+    dependencies: ["class-variance-authority", "lucide-react"],
+    registryDependencies: ["status-indicator"],
+    categories: ["primitives", "data-display"]
+  },
+  {
+    name: "status-indicator",
+    type: "ui",
+    title: "Status Indicator",
+    description: "A presence dot \u2014 online, away, busy or offline \u2014 with an accessible name in the page's language, so colour never carries the status alone.",
+    sourcePath: "registry/ui/status-indicator",
+    dependencies: ["class-variance-authority"],
+    categories: ["primitives", "data-display"]
+  },
+  {
+    name: "skeleton",
+    type: "ui",
+    title: "Skeleton",
+    description: "Loading placeholders that replace shadcn's Skeleton: a plain block plus text, avatar, list item and card shapes that stay still under reduced motion.",
+    sourcePath: "registry/ui/skeleton",
+    categories: ["primitives", "feedback"]
+  },
+  {
+    name: "radio",
+    type: "ui",
+    title: "Radio",
+    description: "An accessible radio for choosing one option from a set, with a plain and a bordered layout variant.",
+    sourcePath: "registry/ui/radio",
+    dependencies: ["class-variance-authority"],
+    categories: ["primitives", "forms"]
+  },
+  // 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",
+    dependencies: ["lucide-react"],
+    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));
+}
+
+exports.baseTokens = baseTokens;
+exports.cn = cn;
+exports.getRegistryItem = getRegistryItem;
+exports.getRegistryItemsByCategory = getRegistryItemsByCategory;
+exports.getRegistryItemsByType = getRegistryItemsByType;
+exports.registry = registry;
+exports.semanticColor = semanticColor;
+exports.tailwindSemanticColors = tailwindSemanticColors;
+exports.useMotionPresets = useMotionPresets;

package/dist/index.d.cts

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

package/dist/index.js

@@ -194,7 +194,7 @@ var registry = [
     name: "skeleton",
     type: "ui",
     title: "Skeleton",
-    description: "Loading skeleton placeholders with pre-built variants for text, avatars, and cards.",
+    description: "Loading placeholders that replace shadcn's Skeleton: a plain block plus text, avatar, list item and card shapes that stay still under reduced motion.",
     sourcePath: "registry/ui/skeleton",
     categories: ["primitives", "feedback"]
   },

package/dist/lib/utils.cjs

@@ -0,0 +1,11 @@
+'use strict';
+
+var clsx = require('clsx');
+var tailwindMerge = require('tailwind-merge');
+
+// src/lib/utils.ts
+function cn(...inputs) {
+  return tailwindMerge.twMerge(clsx.clsx(inputs));
+}
+
+exports.cn = cn;

package/dist/lib/utils.d.cts

@@ -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/motion/index.cjs

@@ -0,0 +1,61 @@
+'use strict';
+
+var framerMotion = require('framer-motion');
+
+// src/motion/presets.ts
+function useMotionPresets() {
+  const prefersReduced = framerMotion.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 }
+  };
+}
+
+exports.useMotionPresets = useMotionPresets;

package/dist/motion/index.d.cts

@@ -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 };