@popgrids/ui 0.0.2 → 0.0.5

package/README.md

@@ -1,79 +1,259 @@
 # @popgrids/ui
 
-A modern, reusable UI component library built with Lit for Popgrids applications.
+A modern, production-ready React UI component library based on shadcn/ui principles, built with Base UI primitives and optimized for tree-shaking.
 
 ## Installation
 
+```bash
+pnpm add @popgrids/ui
+```
+
+Or with npm:
+
 ```bash
 npm install @popgrids/ui
 ```
 
+## Peer Dependencies
+
+This library requires the following peer dependencies:
+
+- `react` ^19.0.0
+- `react-dom` ^19.0.0
+- `@base-ui/react` ^1.0.0
+- `tailwindcss` ^4.0.0
+
+## Requirements
+
+- React 19+
+- Tailwind CSS v4 configured in your project
+- TypeScript (recommended)
+
 ## Usage
 
-Import the package to register all components:
+### Step 1: Import the Theme CSS
+
+**Import the library's theme CSS file in your main CSS file** (not in JavaScript). This file includes theme variables and tells Tailwind to scan the library's component files.
+
+```css
+/* Your main CSS file (e.g., app.css, index.css, globals.css) */
+@import "tailwindcss";
+/* Import the library's theme and source definitions */
+@import "@popgrids/ui/theme.css";
+```
+
+### Step 2: Import and Use Components
+
+```tsx
+import { Button } from "@popgrids/ui";
+
+function App() {
+  return <Button>Click me</Button>;
+}
+```
+
+That's it! The `@import "@popgrids/ui/theme.css"` line:
+- Defines the library's theme variables
+- Tells Tailwind to scan `@popgrids/ui/dist/**/*.{js,cjs}` for class names
+- Automatically generates CSS for all classes used in the components
+
+### Variants
+
+```tsx
+import { Button } from "@popgrids/ui";
+
+function App() {
+  return (
+    <>
+      <Button variant="default">Default</Button>
+      <Button variant="outline">Outline</Button>
+      <Button variant="secondary">Secondary</Button>
+      <Button variant="ghost">Ghost</Button>
+      <Button variant="destructive">Destructive</Button>
+      <Button variant="link">Link</Button>
+    </>
+  );
+}
+```
+
+### Sizes
+
+```tsx
+import { Button } from "@popgrids/ui";
+
+function App() {
+  return (
+    <>
+      <Button size="xs">Extra Small</Button>
+      <Button size="sm">Small</Button>
+      <Button size="default">Default</Button>
+      <Button size="lg">Large</Button>
+      <Button size="icon">Icon</Button>
+    </>
+  );
+}
+```
+
+### Using buttonVariants
+
+You can also use the `buttonVariants` function directly for custom styling:
+
+```tsx
+import { buttonVariants } from "@popgrids/ui";
+import { cn } from "./lib/utils";
+
+function CustomButton({ className, ...props }) {
+  return (
+    <button
+      className={cn(buttonVariants({ variant: "outline", size: "lg" }), className)}
+      {...props}
+    />
+  );
+}
+```
+
+## Theming
+
+The library's theme is included when you import `@popgrids/ui/theme.css`. This file defines:
+
+1. **Theme variables** using Tailwind v4's `@theme` directive
+2. **CSS variables** for backward compatibility
+3. **Source directives** that tell Tailwind to scan the library's component files
 
-```typescript
-import "@popgrids/ui";
+### Default Theme
+
+The theme CSS file includes default design tokens. You can customize them by overriding the variables in your own CSS:
+
+```css
+:root {
+  --background: 0 0% 100%;
+  --foreground: 222.2 84% 4.9%;
+  --card: 0 0% 100%;
+  --card-foreground: 222.2 84% 4.9%;
+  --popover: 0 0% 100%;
+  --popover-foreground: 222.2 84% 4.9%;
+  --primary: 221.2 83.2% 53.3%;
+  --primary-foreground: 210 40% 98%;
+  --secondary: 210 40% 96.1%;
+  --secondary-foreground: 222.2 47.4% 11.2%;
+  --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%;
+  --destructive: 0 84.2% 60.2%;
+  --destructive-foreground: 210 40% 98%;
+  --border: 214.3 31.8% 91.4%;
+  --input: 214.3 31.8% 91.4%;
+  --ring: 221.2 83.2% 53.3%;
+  --radius: 0.5rem;
+}
+
+.dark {
+  --background: 222.2 84% 4.9%;
+  --foreground: 210 40% 98%;
+  --card: 222.2 84% 4.9%;
+  --card-foreground: 210 40% 98%;
+  --popover: 222.2 84% 4.9%;
+  --popover-foreground: 210 40% 98%;
+  --primary: 217.2 91.2% 59.8%;
+  --primary-foreground: 222.2 47.4% 11.2%;
+  --secondary: 217.2 32.6% 17.5%;
+  --secondary-foreground: 210 40% 98%;
+  --muted: 217.2 32.6% 17.5%;
+  --muted-foreground: 215 20.2% 65.1%;
+  --accent: 217.2 32.6% 17.5%;
+  --accent-foreground: 210 40% 98%;
+  --destructive: 0 62.8% 30.6%;
+  --destructive-foreground: 210 40% 98%;
+  --border: 217.2 32.6% 17.5%;
+  --input: 217.2 32.6% 17.5%;
+  --ring: 224.3 76.3% 48%;
+}
 ```
 
-Then use the components in your HTML:
+### Customizing Theme Variables
+
+You can customize any variable to match your design system. Simply override the values in your CSS:
 
-```html
-<pop-button>Click me</pop-button>
-<pop-icon name="star"></pop-icon>
-<pop-toast message="Hello!"></pop-toast>
+```css
+:root {
+  --primary: 221.2 83.2% 53.3%; /* Your primary color */
+  --radius: 0.5rem; /* Your border radius */
+  /* Customize other variables as needed */
+}
 ```
 
-## Available Components
+### Dark Mode
+
+Apply the `.dark` class to your root element to enable dark mode:
+
+```tsx
+<html className="dark">
+  {/* Your app */}
+</html>
+```
+
+## Tree-Shaking
+
+This library is fully tree-shakeable. When you import only the components you need:
+
+```tsx
+import { Button } from "@popgrids/ui";
+```
 
-The library includes the following components:
+Your bundler will only include the Button component and its dependencies, not unused exports.
 
-- `<pop-button>` - Standard button component
-- `<pop-button-vertical>` - Vertical button variant
-- `<pop-button-link>` - Button that acts as a link
-- `<pop-code-input-field>` - Input field for code entry
-- `<pop-comment-avatar>` - Avatar component for comments
-- `<pop-comment-icon>` - Icon component for comments
-- `<pop-element>` - Base element component
-- `<pop-focus-indicator>` - Focus indicator component
-- `<pop-form-input-simple>` - Simple form input component
-- `<pop-icon>` - Icon component
-- `<pop-loader>` - Loading indicator component
-- `<pop-logo>` - Logo component
-- `<pop-sum>` - Sum display component
-- `<pop-timestamp-countdown>` - Countdown timer component
-- `<pop-toast>` - Toast notification component
+## How It Works
 
-## Development
+When you import `@popgrids/ui/theme.css` in your main CSS file:
 
-### Prerequisites
+1. **Theme variables are defined** using Tailwind v4's `@theme` directive
+2. **CSS variables are set** for backward compatibility (used in component classes like `hsl(var(--primary))`)
+3. **`@source` directive tells Tailwind** to scan `@popgrids/ui/dist/**/*.{js,cjs}` for class names
+4. **Tailwind generates CSS** for all classes found in the library's components
+5. **No manual configuration needed** - the `@source` directive handles everything!
 
-- Node.js
-- npm
+### Requirements
 
-### Scripts
+- **Tailwind CSS v4** (required for `@theme` and `@source` directives)
+- Import `@popgrids/ui/theme.css` in your main CSS file (not in JavaScript)
 
-- `npm run build` - Build the package
-- `npm run dev` - Watch mode for development
-- `npm run clean` - Clean build artifacts
-- `npm run lint` - Run ESLint
-- `npm run test` - Run tests
-- `npm run generate:component` - Generate a new component
-- `npm run check-types` - Check TypeScript types
+## TypeScript
 
-### Adding New Components
+Full TypeScript support is included. All components are typed and exported with their proper types.
 
-To add a new component, use the generator:
+## Changesets
+
+This library uses Changesets to manage versions. To create a new version, run:
+
+```bash
+pnpm changeset
+```
+
+This will open an interactive prompt to help you create a changeset.
+
+Once you've created a changeset, run:
+
+```bash
+pnpm changeset version
+```
+
+This will update the version in the package.json file and create a new git tag.
+
+Then push the changes to the repository:
 
 ```bash
-npm run generate:component
+git push origin main
 ```
 
-## Dependencies
+And finally, publish the package:
+
+```bash
+pnpm changeset publish
+```
 
-- [Lit](https://lit.dev/) - Web Components library
-- [@popgrids/theme](https://github.com/popgrids/popgrids-turborepo) - Theme package
+This will publish the package to the npm registry.
 
 ## License
 
-Private - All rights reserved
+MIT