@postxl/ui-components 1.0.0

package/README.md

@@ -0,0 +1,172 @@
+# @postxl/ui-components
+
+A React UI component library built on Radix UI primitives with Tailwind CSS v4 styling.
+
+## Installation
+
+```bash
+npm install @postxl/ui-components
+# or
+pnpm add @postxl/ui-components
+# or
+yarn add @postxl/ui-components
+```
+
+## Requirements
+
+- React 18+
+- Tailwind CSS 4+
+
+## Setup
+
+### 1. Import the theme CSS
+
+In your main CSS file (e.g., `globals.css` or `index.css`), import the theme:
+
+```css
+@import 'tailwindcss';
+@import '@postxl/ui-components/theme.css';
+```
+
+Or if you're using a bundler that supports CSS imports in JS:
+
+```js
+import '@postxl/ui-components/theme.css'
+```
+
+### 2. Configure dark mode (optional)
+
+The components support dark mode via the `.dark` class on the HTML element. You can use the included `ThemeProvider`:
+
+```tsx
+import { ThemeProvider } from '@postxl/ui-components'
+
+function App() {
+  return (
+    <ThemeProvider defaultTheme="system">
+      {/* Your app */}
+    </ThemeProvider>
+  )
+}
+```
+
+## Usage
+
+```tsx
+import { Button, Card, Input } from '@postxl/ui-components'
+
+function MyComponent() {
+  return (
+    <Card>
+      <Input placeholder="Enter your name" />
+      <Button variant="primary">Submit</Button>
+    </Card>
+  )
+}
+```
+
+## Available Components
+
+### Basic Components
+- `Accordion` - Collapsible content sections
+- `Alert` - Notification messages
+- `AlertDialog` - Modal confirmation dialogs
+- `Avatar` - User profile images
+- `Badge` - Status indicators
+- `Breadcrumb` - Navigation breadcrumbs
+- `Button` - Interactive buttons with variants
+- `Card` / `CardHover` - Content containers
+- `Checkbox` / `ShadcnCheckbox` - Checkable inputs
+- `Label` - Form labels
+- `Separator` - Visual dividers
+- `Skeleton` - Loading placeholders
+- `Spinner` / `Loader` - Loading indicators
+- `Switch` - Toggle switches
+- `Toggle` - Toggle buttons
+- `ToggleGroup` - Grouped toggle buttons
+
+### Input Components
+- `Input` - Text inputs
+- `Textarea` - Multi-line text inputs
+- `Combobox` - Searchable select
+- `Select` - Dropdown selects
+- `Slider` - Range sliders
+- `RadioGroup` - Radio button groups
+- `DatePicker` - Date selection
+
+### Layout Components
+- `ContentFrame` - Content wrapper with header
+- `Resizable` - Resizable panels
+- `ScrollArea` - Scrollable containers
+- `Collapse` - Collapsible sections
+
+### Navigation Components
+- `NavigationMenu` - Site navigation
+- `Menubar` - Menu bars
+- `Pagination` - Page navigation
+- `CommandPalette` / `Command` - Command palette (⌘K)
+
+### Overlay Components
+- `Dialog` - Modal dialogs
+- `Drawer` - Slide-out panels
+- `Modal` - Modal containers
+- `Popover` - Floating content
+- `Sheet` - Side sheets
+- `Tooltip` - Hover tooltips
+- `DropdownMenu` - Dropdown menus
+- `ContextMenu` - Right-click menus
+
+### Data Display
+- `Calendar` - Calendar display
+- `Carousel` - Image carousels
+- `Progress` - Progress indicators
+- `MarkValueRenderer` - Value highlighting
+
+### Toast Notifications
+- `Toaster` / `toast` - Toast notifications (via Sonner)
+
+## Utilities
+
+### `cn()` - Class name merger
+Combines Tailwind classes intelligently:
+
+```tsx
+import { cn } from '@postxl/ui-components'
+
+const className = cn('p-4', isActive && 'bg-primary', className)
+```
+
+### `useTheme()` - Theme hook
+Access and modify the current theme:
+
+```tsx
+import { useTheme } from '@postxl/ui-components'
+
+function ThemeToggle() {
+  const { theme, setTheme } = useTheme()
+  return <button onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}>Toggle</button>
+}
+```
+
+## Customizing Theme Colors
+
+Override CSS variables in your stylesheet:
+
+```css
+:root {
+  --primary: #your-color;
+  --primary-foreground: #your-color;
+  /* ... other variables */
+}
+
+.dark {
+  --primary: #your-dark-color;
+  /* ... dark theme overrides */
+}
+```
+
+See `@postxl/ui-components/theme.css` for all available CSS variables.
+
+## License
+
+See LICENSE in the repository root.