shru-design-system 0.1.5 → 0.1.8

package/README.md

@@ -1,184 +1,114 @@
 # shru-design-system
 
-A React component library with atoms and molecules built on Radix UI and Tailwind CSS.
+A React component library with atoms and molecules built on Radix UI and Tailwind CSS, featuring a dynamic theme system.
+
+## Project Structure
+
+### Root Files
+
+- **`package.json`** - Package configuration, dependencies, and scripts
+- **`tsconfig.json`** - TypeScript configuration
+- **`tsup.config.ts`** - Build configuration for bundling (ESM/CJS)
+- **`tailwind.config.js`** - Tailwind CSS configuration (for library development)
+- **`postcss.config.js`** - PostCSS configuration (for library development)
+- **`.gitignore`** - Git ignore rules
+
+### Source Code (`src/`)
+
+- **`src/index.ts`** - Main entry point, exports all components and utilities
+- **`src/utils.ts`** - Utility functions (cn helper for class merging)
+
+#### Atoms (`src/atoms/`)
+Basic UI building blocks:
+- **`Button.tsx`** - Button component with variants and sizes
+- **`Badge.tsx`** - Badge component for labels and tags
+- **`TextInput.tsx`** - Text input field component
+- **`Label.tsx`** - Form label component
+- **`Textarea.tsx`** - Multi-line text input component
+- **`Separator.tsx`** - Horizontal/vertical divider component
+- **`Checkbox.tsx`** - Checkbox input component
+
+#### Molecules (`src/molecules/`)
+Composite components:
+- **`Modal.tsx`** - Modal dialog component
+- **`Select.tsx`** - Dropdown select component
+- **`Tooltip.tsx`** - Tooltip component
+
+#### Theme System (`src/themes/`)
+- **`themeConfig.ts`** - Theme configuration and category definitions
+- **`themeUtils.ts`** - Theme utility functions (loading, merging, flattening)
+- **`applyThemeSync.ts`** - Synchronous theme application (prevents FOUC)
+- **`useTheme.tsx`** - React hook for theme management
+- **`ui/ThemeToggle/`** - Theme toggle UI component and related files
+  - **`ThemeToggle.tsx`** - Main theme toggle component
+  - **`useThemeToggle.ts`** - Hook for theme toggle UI state
+  - **`themeToggleConfig.ts`** - Theme toggle configuration
+  - **`themeToggleUtils.ts`** - Theme toggle utility functions
+  - **`index.ts`** - Theme toggle exports
+
+### Build Output (`dist/`)
+
+- **`index.js`** - CommonJS bundle
+- **`index.mjs`** - ESM bundle
+- **`index.d.ts`** - TypeScript declarations (CJS)
+- **`index.d.mts`** - TypeScript declarations (ESM)
+
+### Scripts (`scripts/`)
+
+Setup and runtime scripts:
+- **`init.js`** - Postinstall script that sets up Tailwind, PostCSS, and token files in consuming apps
+- **`apply-theme-sync.js`** - Standalone synchronous theme script (injected into HTML)
+- **`applyThemeSync.js`** - Synchronous theme application module
+- **`themeConfig.js`** - Theme configuration (JavaScript version)
+- **`themeUtils.js`** - Theme utilities (JavaScript version)
+- **`tokens/`** - Default token files (copied to consuming apps)
+  - **`base.json`** - Base design tokens
+  - **`palettes.json`** - Color palette definitions
+  - **`themes/`** - Theme category files
+    - **`color/`** - Color theme variants (white, dark)
+    - **`typography/`** - Typography themes (sans, serif)
+    - **`shape/`** - Shape themes (smooth, sharp)
+    - **`density/`** - Density themes (comfortable, compact)
+    - **`animation/`** - Animation themes (gentle, brisk)
+    - **`custom/`** - Custom theme examples (brand, minimal)
+
+### Test Application (`test/`)
+
+Local test environment for developing and testing the library:
+- **`package.json`** - Test app dependencies
+- **`vite.config.ts`** - Vite configuration for test app
+- **`index.html`** - Test app HTML entry point
+- **`src/App.tsx`** - Test app component showcasing all library components
+- **`src/main.tsx`** - Test app entry point
+- **`src/index.css`** - Test app global styles
+- **`tailwind.config.js`** - Tailwind config for test app
+- **`postcss.config.js`** - PostCSS config for test app
+- **`public/tokens/`** - Token files for testing (generated by init script)
+- **`dist/`** - Vite build output (ignored in git)
 
-## Installation
+## Usage
 
+Install the package:
 ```bash
 npm install shru-design-system
 ```
 
-## Quick Setup
-
-After installation, run the setup script to configure Tailwind CSS:
-
-```bash
-npx shru-design-system-init
-```
-
-Or it will run automatically after `npm install` (you can skip this step if it already ran).
-
-## Manual Setup
-
-If you prefer to set up manually or the automatic setup didn't work:
-
-### 1. Install Tailwind CSS
-
-```bash
-npm install -D tailwindcss postcss autoprefixer
-npx tailwindcss init -p
-```
-
-### 2. Configure Tailwind
-
-Update `tailwind.config.js`:
-
-```js
-export default {
-  content: [
-    "./index.html",
-    "./src/**/*.{js,ts,jsx,tsx}",
-    "./node_modules/shru-design-system/dist/**/*.{js,mjs}",
-  ],
-  theme: {
-    extend: {
-      colors: {
-        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))",
-        },
-        destructive: {
-          DEFAULT: "hsl(var(--destructive))",
-          foreground: "hsl(var(--destructive-foreground))",
-        },
-        muted: {
-          DEFAULT: "hsl(var(--muted))",
-          foreground: "hsl(var(--muted-foreground))",
-        },
-        accent: {
-          DEFAULT: "hsl(var(--accent))",
-          foreground: "hsl(var(--accent-foreground))",
-        },
-        popover: {
-          DEFAULT: "hsl(var(--popover))",
-          foreground: "hsl(var(--popover-foreground))",
-        },
-        border: "hsl(var(--border))",
-        input: "hsl(var(--input))",
-        ring: "hsl(var(--ring))",
-      },
-      borderRadius: {
-        lg: "var(--radius)",
-        md: "calc(var(--radius) - 2px)",
-        sm: "calc(var(--radius) - 4px)",
-      },
-    },
-  },
-  plugins: [],
-}
-```
-
-### 3. Add CSS Variables
-
-Create or update `src/index.css`:
-
-```css
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
-
-@layer base {
-  :root {
-    --background: 0 0% 100%;
-    --foreground: 222.2 84% 4.9%;
-    --primary: 222.2 47.4% 11.2%;
-    --primary-foreground: 210 40% 98%;
-    --secondary: 210 40% 96.1%;
-    --secondary-foreground: 222.2 47.4% 11.2%;
-    --destructive: 0 84.2% 60.2%;
-    --destructive-foreground: 210 40% 98%;
-    --muted: 210 40% 96.1%;
-    --muted-foreground: 215.4 16.3% 46.9%;
-    --accent: 210 40% 96.1%;
-    --accent-foreground: 222.2 47.4% 11.2%;
-    --popover: 0 0% 100%;
-    --popover-foreground: 222.2 84% 4.9%;
-    --border: 214.3 31.8% 91.4%;
-    --input: 214.3 31.8% 91.4%;
-    --ring: 222.2 84% 4.9%;
-    --radius: 0.5rem;
-  }
-  
-  * {
-    border-color: hsl(var(--border));
-  }
-  
-  body {
-    background-color: hsl(var(--background));
-    color: hsl(var(--foreground));
-  }
-}
-```
-
-### 4. Import CSS
-
-Import the CSS file in your entry point (e.g., `src/main.tsx`):
+The `postinstall` script automatically sets up Tailwind CSS, PostCSS, and token files in your project.
 
+Import components:
 ```tsx
-import './index.css'
+import { Button, Modal, ThemeToggle } from 'shru-design-system'
 ```
 
-## Usage
+## Development
 
-```tsx
-import { Button, Badge, Modal, Select } from 'shru-design-system'
-
-function App() {
-  return (
-    <div>
-      <Button variant="default">Click me</Button>
-      <Badge>New</Badge>
-      
-      <Modal>
-        <ModalTrigger asChild>
-          <Button>Open Modal</Button>
-        </ModalTrigger>
-        <ModalContent>
-          <ModalHeader>
-            <ModalTitle>Hello</ModalTitle>
-            <ModalDescription>This is a modal</ModalDescription>
-          </ModalHeader>
-        </ModalContent>
-      </Modal>
-    </div>
-  )
-}
+Build the library:
+```bash
+npm run build
 ```
 
-## Components
-
-### Atoms
-- **Button** - Versatile button with multiple variants and sizes
-- **Badge** - Small status indicators
-
-### Molecules
-- **Modal** - Dialog component with overlay
-- **Select** - Dropdown select component
-
-## Peer Dependencies
-
-Make sure to install these peer dependencies:
-
+Test locally:
 ```bash
-npm install @radix-ui/react-slot @radix-ui/react-dialog @radix-ui/react-select class-variance-authority clsx tailwind-merge lucide-react
+cd test && npm run dev
 ```
 
-## License
-
-MIT

package/dist/index.d.mts

@@ -1,6 +1,9 @@
 import * as class_variance_authority_types from 'class-variance-authority/types';
 import * as React from 'react';
 import { VariantProps } from 'class-variance-authority';
+import * as LabelPrimitive from '@radix-ui/react-label';
+import * as SeparatorPrimitive from '@radix-ui/react-separator';
+import * as CheckboxPrimitive from '@radix-ui/react-checkbox';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as DialogPrimitive from '@radix-ui/react-dialog';
 import * as SelectPrimitive from '@radix-ui/react-select';
@@ -26,6 +29,30 @@ declare const Badge: React.ForwardRefExoticComponent<Omit<React.ClassAttributes<
     asChild?: boolean;
 }, "ref"> & React.RefAttributes<HTMLSpanElement>>;
 
+declare const textInputTypes: readonly ["text", "email", "password", "number", "tel", "url", "search"];
+interface TextInputProps extends React.ComponentProps<"input"> {
+    type?: typeof textInputTypes[number];
+}
+declare const TextInput: React.ForwardRefExoticComponent<Omit<TextInputProps, "ref"> & React.RefAttributes<HTMLInputElement>>;
+
+interface LabelProps extends React.ComponentProps<typeof LabelPrimitive.Root> {
+}
+declare const Label: React.ForwardRefExoticComponent<Omit<LabelProps, "ref"> & React.RefAttributes<HTMLLabelElement>>;
+
+interface TextareaProps extends React.ComponentProps<"textarea"> {
+}
+declare const Textarea: React.ForwardRefExoticComponent<Omit<TextareaProps, "ref"> & React.RefAttributes<HTMLTextAreaElement>>;
+
+declare const separatorOrientations: readonly ["horizontal", "vertical"];
+interface SeparatorProps extends React.ComponentProps<typeof SeparatorPrimitive.Root> {
+    orientation?: typeof separatorOrientations[number];
+}
+declare const Separator: React.ForwardRefExoticComponent<Omit<SeparatorProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+
+interface CheckboxProps extends React.ComponentProps<typeof CheckboxPrimitive.Root> {
+}
+declare const Checkbox: React.ForwardRefExoticComponent<Omit<CheckboxProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;
+
 declare function Modal({ ...props }: React.ComponentProps<typeof DialogPrimitive.Root>): react_jsx_runtime.JSX.Element;
 declare function ModalTrigger({ ...props }: React.ComponentProps<typeof DialogPrimitive.Trigger>): react_jsx_runtime.JSX.Element;
 declare function ModalPortal({ ...props }: React.ComponentProps<typeof DialogPrimitive.Portal>): react_jsx_runtime.JSX.Element;
@@ -130,6 +157,16 @@ type ThemeCategory = {
     order: number;
     themes: Record<string, ThemeMetadata>;
 };
+/**
+ * Centralized theme category order
+ * Used everywhere to ensure consistency
+ * Custom category is included but handled specially (optional, user-created files)
+ *
+ * ⚠️ IF YOU UPDATE THIS, ALSO UPDATE:
+ * 1. scripts/themeConfig.js - THEME_CATEGORY_ORDER (JavaScript version)
+ * 2. scripts/apply-theme-sync.js - THEME_CATEGORY_ORDER constant (standalone script, can't import)
+ */
+declare const THEME_CATEGORY_ORDER: readonly ["color", "typography", "shape", "density", "animation", "custom"];
 /**
  * Register a custom theme dynamically
  * Allows users to add themes without modifying the base config
@@ -152,6 +189,22 @@ declare function getThemesForCategory(category: string): Promise<Record<string,
  */
 declare function getTheme(category: string, themeId: string): Promise<ThemeMetadata | null>;
 
+/**
+ * Theme Utilities
+ * Pure utility functions for theme management
+ * Note: generateAndApplyTheme has side effects (modifies DOM) but is the main theme application utility
+ */
+
+/**
+ * Debug helper: Enable debug mode to see all CSS variables in console
+ * Call this in browser console: window.__DESIGN_SYSTEM_DEBUG__ = true
+ */
+declare function enableDebugMode(): void;
+/**
+ * Debug helper: Get all current CSS variables
+ */
+declare function getCurrentCSSVariables(): Record<string, string>;
+
 /**
  * Synchronous theme application for blocking script execution
  * This runs before React hydrates to prevent theme flash
@@ -162,4 +215,4 @@ declare function getTheme(category: string, themeId: string): Promise<ThemeMetad
  */
 declare function applyThemeSync(): void;
 
-export { Badge, Button, Modal, ModalClose, ModalContent, ModalDescription, ModalFooter, ModalHeader, ModalOverlay, ModalPortal, ModalTitle, ModalTrigger, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, type ThemeMetadata$1 as ThemeMetadata, type ThemeSelection, ThemeToggle, type ThemeToggleProps, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, applyThemeSync, badgeVariants, buttonVariants, getTheme, getThemeCategories, getThemeFilePath, getThemesForCategory, registerTheme, useTheme, useThemeToggle };
+export { Badge, Button, Checkbox, Label, Modal, ModalClose, ModalContent, ModalDescription, ModalFooter, ModalHeader, ModalOverlay, ModalPortal, ModalTitle, ModalTrigger, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, THEME_CATEGORY_ORDER, TextInput, Textarea, type ThemeMetadata$1 as ThemeMetadata, type ThemeSelection, ThemeToggle, type ThemeToggleProps, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, applyThemeSync, badgeVariants, buttonVariants, enableDebugMode, getCurrentCSSVariables, getTheme, getThemeCategories, getThemeFilePath, getThemesForCategory, registerTheme, useTheme, useThemeToggle };

package/dist/index.d.ts

@@ -1,6 +1,9 @@
 import * as class_variance_authority_types from 'class-variance-authority/types';
 import * as React from 'react';
 import { VariantProps } from 'class-variance-authority';
+import * as LabelPrimitive from '@radix-ui/react-label';
+import * as SeparatorPrimitive from '@radix-ui/react-separator';
+import * as CheckboxPrimitive from '@radix-ui/react-checkbox';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as DialogPrimitive from '@radix-ui/react-dialog';
 import * as SelectPrimitive from '@radix-ui/react-select';
@@ -26,6 +29,30 @@ declare const Badge: React.ForwardRefExoticComponent<Omit<React.ClassAttributes<
     asChild?: boolean;
 }, "ref"> & React.RefAttributes<HTMLSpanElement>>;
 
+declare const textInputTypes: readonly ["text", "email", "password", "number", "tel", "url", "search"];
+interface TextInputProps extends React.ComponentProps<"input"> {
+    type?: typeof textInputTypes[number];
+}
+declare const TextInput: React.ForwardRefExoticComponent<Omit<TextInputProps, "ref"> & React.RefAttributes<HTMLInputElement>>;
+
+interface LabelProps extends React.ComponentProps<typeof LabelPrimitive.Root> {
+}
+declare const Label: React.ForwardRefExoticComponent<Omit<LabelProps, "ref"> & React.RefAttributes<HTMLLabelElement>>;
+
+interface TextareaProps extends React.ComponentProps<"textarea"> {
+}
+declare const Textarea: React.ForwardRefExoticComponent<Omit<TextareaProps, "ref"> & React.RefAttributes<HTMLTextAreaElement>>;
+
+declare const separatorOrientations: readonly ["horizontal", "vertical"];
+interface SeparatorProps extends React.ComponentProps<typeof SeparatorPrimitive.Root> {
+    orientation?: typeof separatorOrientations[number];
+}
+declare const Separator: React.ForwardRefExoticComponent<Omit<SeparatorProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+
+interface CheckboxProps extends React.ComponentProps<typeof CheckboxPrimitive.Root> {
+}
+declare const Checkbox: React.ForwardRefExoticComponent<Omit<CheckboxProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;
+
 declare function Modal({ ...props }: React.ComponentProps<typeof DialogPrimitive.Root>): react_jsx_runtime.JSX.Element;
 declare function ModalTrigger({ ...props }: React.ComponentProps<typeof DialogPrimitive.Trigger>): react_jsx_runtime.JSX.Element;
 declare function ModalPortal({ ...props }: React.ComponentProps<typeof DialogPrimitive.Portal>): react_jsx_runtime.JSX.Element;
@@ -130,6 +157,16 @@ type ThemeCategory = {
     order: number;
     themes: Record<string, ThemeMetadata>;
 };
+/**
+ * Centralized theme category order
+ * Used everywhere to ensure consistency
+ * Custom category is included but handled specially (optional, user-created files)
+ *
+ * ⚠️ IF YOU UPDATE THIS, ALSO UPDATE:
+ * 1. scripts/themeConfig.js - THEME_CATEGORY_ORDER (JavaScript version)
+ * 2. scripts/apply-theme-sync.js - THEME_CATEGORY_ORDER constant (standalone script, can't import)
+ */
+declare const THEME_CATEGORY_ORDER: readonly ["color", "typography", "shape", "density", "animation", "custom"];
 /**
  * Register a custom theme dynamically
  * Allows users to add themes without modifying the base config
@@ -152,6 +189,22 @@ declare function getThemesForCategory(category: string): Promise<Record<string,
  */
 declare function getTheme(category: string, themeId: string): Promise<ThemeMetadata | null>;
 
+/**
+ * Theme Utilities
+ * Pure utility functions for theme management
+ * Note: generateAndApplyTheme has side effects (modifies DOM) but is the main theme application utility
+ */
+
+/**
+ * Debug helper: Enable debug mode to see all CSS variables in console
+ * Call this in browser console: window.__DESIGN_SYSTEM_DEBUG__ = true
+ */
+declare function enableDebugMode(): void;
+/**
+ * Debug helper: Get all current CSS variables
+ */
+declare function getCurrentCSSVariables(): Record<string, string>;
+
 /**
  * Synchronous theme application for blocking script execution
  * This runs before React hydrates to prevent theme flash
@@ -162,4 +215,4 @@ declare function getTheme(category: string, themeId: string): Promise<ThemeMetad
  */
 declare function applyThemeSync(): void;
 
-export { Badge, Button, Modal, ModalClose, ModalContent, ModalDescription, ModalFooter, ModalHeader, ModalOverlay, ModalPortal, ModalTitle, ModalTrigger, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, type ThemeMetadata$1 as ThemeMetadata, type ThemeSelection, ThemeToggle, type ThemeToggleProps, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, applyThemeSync, badgeVariants, buttonVariants, getTheme, getThemeCategories, getThemeFilePath, getThemesForCategory, registerTheme, useTheme, useThemeToggle };
+export { Badge, Button, Checkbox, Label, Modal, ModalClose, ModalContent, ModalDescription, ModalFooter, ModalHeader, ModalOverlay, ModalPortal, ModalTitle, ModalTrigger, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, THEME_CATEGORY_ORDER, TextInput, Textarea, type ThemeMetadata$1 as ThemeMetadata, type ThemeSelection, ThemeToggle, type ThemeToggleProps, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, applyThemeSync, badgeVariants, buttonVariants, enableDebugMode, getCurrentCSSVariables, getTheme, getThemeCategories, getThemeFilePath, getThemesForCategory, registerTheme, useTheme, useThemeToggle };