diff --git a/.changeset/fix-select-component-export.md b/.changeset/fix-select-component-export.md new file mode 100644 index 0000000..c1532ad --- /dev/null +++ b/.changeset/fix-select-component-export.md @@ -0,0 +1,9 @@ +--- +"@etherisc/ui-kit": patch +--- + +fix: ensure Select component is properly exported with TypeScript declarations + +The Select component was implemented but not being exported due to a build configuration issue where TypeScript declarations weren't being generated properly. This fix updates the build script to ensure all component declarations are generated and exported correctly. + +Fixes #39 diff --git a/docs/AI-SETUP.md b/docs/AI-SETUP.md new file mode 100644 index 0000000..ef75f31 --- /dev/null +++ b/docs/AI-SETUP.md @@ -0,0 +1,524 @@ +# **Complete Setup Guide: Radix UI + shadcn + DaisyUI Design System** + +This guide provides comprehensive instructions for consuming applications to properly integrate the `@etherisc/ui-kit` design system. + +## **📐 Architecture Overview** + +The design system uses a **layered approach** combining three powerful libraries: + +1. **Radix UI** - Provides headless, accessible component primitives +2. **shadcn/ui** - Provides styled component patterns and utilities +3. **DaisyUI** - Provides semantic CSS classes and design tokens + +The system bridges these through a **custom CSS variable mapping** that allows DaisyUI themes to power shadcn components. + +```mermaid +graph TD + A["DaisyUI Themes
(Design Tokens)"] --> B["CSS Variables Mapping
(theme.css)"] + B --> C["shadcn Components
(Styled Primitives)"] + D["Radix UI
(Headless Primitives)"] --> C + C --> E["@etherisc/ui-kit
(Component Library)"] + E --> F["Consumer Application"] + + G["Tailwind CSS
(Utility Classes)"] --> C + H["Custom Styles
(globals.css)"] --> F + + style A fill:#e1f5fe + style B fill:#fff3e0 + style C fill:#f3e5f5 + style D fill:#e8f5e8 + style E fill:#fff8e1 + style F fill:#fce4ec +``` + +## **🚀 Step-by-Step Setup for Consuming Applications** + +### **Step 1: Install Required Dependencies** + +```bash +# Core dependencies +npm install @etherisc/ui-kit + +# Peer dependencies (required) +npm install react@>=18.0.0 react-dom@>=18.0.0 + +# Additional dependencies for forms (optional) +npm install react-hook-form@^7.56.4 @hookform/resolvers@^3.6.1 zod@^3.25.7 +``` + +### **Step 2: Install and Configure Tailwind CSS + DaisyUI** + +```bash +# Install styling dependencies +npm install -D tailwindcss@^3.4.17 postcss@^8.5.3 autoprefixer@^10.4.21 +npm install -D daisyui@^5.0.35 tailwindcss-animate@^1.0.7 + +# Initialize Tailwind (if not already done) +npx tailwindcss init -p +``` + +### **Step 3: Configure Tailwind CSS** + +Create or update your `tailwind.config.js`: + +```javascript +import daisyui from "daisyui"; +import tailwindcssAnimate from "tailwindcss-animate"; + +/** @type {import('tailwindcss').Config} */ +export default { + content: [ + "./index.html", + "./src/**/*.{js,ts,jsx,tsx}", + // Include the ui-kit components for proper class detection + "./node_modules/@etherisc/ui-kit/dist/**/*.{js,jsx}", + ], + darkMode: ["class"], + theme: { + extend: { + colors: { + // Essential shadcn color mappings + 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))", + }, + accent: { + DEFAULT: "hsl(var(--accent))", + foreground: "hsl(var(--accent-foreground))", + }, + destructive: { + DEFAULT: "hsl(var(--destructive))", + foreground: "hsl(var(--destructive-foreground))", + }, + card: { + DEFAULT: "hsl(var(--card))", + foreground: "hsl(var(--card-foreground))", + }, + popover: { + DEFAULT: "hsl(var(--popover))", + foreground: "hsl(var(--popover-foreground))", + }, + success: { + DEFAULT: "hsl(var(--success))", + foreground: "hsl(var(--success-foreground))", + }, + warning: { + DEFAULT: "hsl(var(--warning))", + foreground: "hsl(var(--warning-foreground))", + }, + info: { + DEFAULT: "hsl(var(--info))", + foreground: "hsl(var(--info-foreground))", + }, + muted: { + DEFAULT: "hsl(var(--muted))", + foreground: "hsl(var(--muted-foreground))", + }, + }, + borderRadius: { + lg: "var(--radius)", + md: "calc(var(--radius) - 2px)", + sm: "calc(var(--radius) - 4px)", + }, + boxShadow: { + sm: "var(--shadow-sm)", + DEFAULT: "var(--shadow)", + md: "var(--shadow-md)", + lg: "var(--shadow-lg)", + }, + }, + }, + plugins: [daisyui, tailwindcssAnimate], + daisyui: { + themes: ["light", "dark"], + base: true, + styled: true, + utils: true, + prefix: "", + logs: false, + themeRoot: ":root", + }, +}; +``` + +### **Step 4: Import Required Styles** + +In your main CSS file (e.g., `src/index.css` or `src/main.css`): + +```css +/* Import the complete design system styles */ +@import "@etherisc/ui-kit/dist/style.css"; + +/* Include Tailwind utilities */ +@tailwind base; +@tailwind components; +@tailwind utilities; + +/* Optional: Add your custom base styles */ +@layer base { + body { + @apply bg-background text-foreground; + } +} +``` + +### **Step 5: Set Up React Providers** + +In your main app entry point (e.g., `src/main.tsx` or `src/App.tsx`): + +```tsx +import React from "react"; +import { createRoot } from "react-dom/client"; +import { + ThemeProvider, + ToastProvider, + ErrorBoundary, + I18nProvider, +} from "@etherisc/ui-kit"; +import "./index.css"; // Your CSS file with the imports above + +function App() { + return ( + + + + + {/* Your app content goes here */} + + + + + + ); +} + +// Root setup +const container = document.getElementById("root"); +if (!container) throw new Error("Failed to find the root element"); + +const root = createRoot(container); +root.render( + + + , +); +``` + +### **Step 6: Configure Theme for DaisyUI (Optional)** + +To ensure DaisyUI components render correctly, you may need to set the theme attribute: + +```tsx +// In your main app or index.html +useEffect(() => { + // Set DaisyUI theme on HTML element + document.documentElement.setAttribute("data-theme", "light"); +}, []); +``` + +Or in your `index.html`: + +```html + + + +``` + +## **🔧 Essential Configuration Details** + +### **Provider Configuration Options** + +#### **ThemeProvider** + +```tsx + +``` + +#### **ToastProvider** + +```tsx + +``` + +#### **I18nProvider** + +```tsx + +``` + +### **Key CSS Variables Available** + +The design system provides these CSS variables that you can customize: + +```css +:root { + /* Core colors (mapped from DaisyUI) */ + --primary: hsl(var(--p)); + --primary-foreground: hsl(var(--pc)); + --secondary: hsl(var(--s)); + --background: hsl(var(--b1)); + --foreground: hsl(var(--bc)); + --border: hsl(var(--b2)); + + /* Status colors */ + --success: hsl(var(--su)); + --warning: hsl(var(--wa)); + --error: hsl(var(--er)); + --info: hsl(var(--in)); + + /* UI elements */ + --radius: 0.5rem; + --shadow-sm: /* ... */; + --shadow: /* ... */; + --shadow-md: /* ... */; + --shadow-lg: /* ... */; +} +``` + +## **📝 Usage Examples** + +### **Basic Component Usage** + +```tsx +import { + Button, + TextInput, + Select, + AppShell, + StatusBadge, +} from "@etherisc/ui-kit"; + +function MyApp() { + return ( + My App} + sideNavItems={[ + { label: "Dashboard", href: "/" }, + { label: "Settings", href: "/settings" }, + ]} + > +
+

Welcome

+ + + +