@moneymap/ui 0.0.3-alpha.1 → 0.0.4

package/README.md

@@ -1,7 +1,443 @@
-# @moneymap/ui
-
-This library was generated with [Nx](https://nx.dev).
-
-## Running unit tests
-
-Run `nx test @moneymap/ui` to execute the unit tests via [Jest](https://jestjs.io).
+# @moneymap/ui
+
+> **⚠️ Tailwind CSS Required:** This library requires Tailwind CSS to be configured in your project. See [Setup](#setup-required) below.
+
+## Setup Required
+
+### Tailwind CSS v3 Setup
+
+1. **Install Tailwind CSS:**
+
+```bash
+npm install -D tailwindcss postcss autoprefixer
+npx tailwindcss init -p
+```
+
+2. **Configure Tailwind to scan the library** (`tailwind.config.js`):
+
+```javascript
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: [
+    './src/**/*.{js,jsx,ts,tsx}',
+    './node_modules/@moneymap/ui/**/*.{js,jsx,ts,tsx}', // Add this
+  ],
+  theme: {
+    extend: {
+      colors: {
+        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))',
+        },
+        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))',
+        },
+      },
+      borderRadius: {
+        lg: 'var(--radius)',
+        md: 'calc(var(--radius) - 2px)',
+        sm: 'calc(var(--radius) - 4px)',
+      },
+    },
+  },
+  plugins: [],
+};
+```
+
+3. **Add CSS variables to your global CSS** (e.g., `globals.css` or `index.css`):
+
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  :root {
+    --background: 0 0% 100%;
+    --foreground: 240 10% 3.9%;
+    --card: 0 0% 100%;
+    --card-foreground: 240 10% 3.9%;
+    --primary: 240 5.9% 10%;
+    --primary-foreground: 0 0% 98%;
+    --secondary: 240 4.8% 95.9%;
+    --secondary-foreground: 240 5.9% 10%;
+    --muted: 240 4.8% 95.9%;
+    --muted-foreground: 240 3.8% 46.1%;
+    --accent: 240 4.8% 95.9%;
+    --accent-foreground: 240 5.9% 10%;
+    --destructive: 0 84.2% 60.2%;
+    --destructive-foreground: 0 0% 98%;
+    --border: 240 5.9% 90%;
+    --input: 240 5.9% 90%;
+    --ring: 240 5.9% 10%;
+    --radius: 0.5rem;
+  }
+
+  .dark {
+    --background: 240 10% 3.9%;
+    --foreground: 0 0% 98%;
+    --card: 240 10% 3.9%;
+    --card-foreground: 0 0% 98%;
+    --primary: 0 0% 98%;
+    --primary-foreground: 240 5.9% 10%;
+    --secondary: 240 3.7% 15.9%;
+    --secondary-foreground: 0 0% 98%;
+    --muted: 240 3.7% 15.9%;
+    --muted-foreground: 240 5% 64.9%;
+    --accent: 240 3.7% 15.9%;
+    --accent-foreground: 0 0% 98%;
+    --destructive: 0 62.8% 30.6%;
+    --destructive-foreground: 0 0% 98%;
+    --border: 240 3.7% 15.9%;
+    --input: 240 3.7% 15.9%;
+    --ring: 240 4.9% 83.9%;
+  }
+}
+```
+
+### Tailwind CSS v4 Setup (Beta)
+
+1. **Install Tailwind CSS v4:**
+
+```bash
+npm install tailwindcss@next @tailwindcss/postcss@next
+```
+
+2. **Configure PostCSS** (`postcss.config.js`):
+
+```javascript
+module.exports = {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};
+```
+
+3. **Import Tailwind in your CSS:**
+
+```css
+@import 'tailwindcss';
+
+@theme {
+  --color-border: oklch(0.9 0 0);
+  --color-input: oklch(0.9 0 0);
+  --color-ring: oklch(0.2 0 0);
+  --color-background: oklch(1 0 0);
+  --color-foreground: oklch(0.15 0 0);
+  /* Add other custom colors */
+}
+```
+
+4. **Scan the library** - Tailwind v4 auto-detects imports, but you can configure it in your CSS:
+
+```css
+@source "../../node_modules/@moneymap/ui/**/*.{js,jsx,ts,tsx}";
+```
+
+---
+
+# Maintainers
+
+The sections below are for developers who need to build and publish the `@moneymap/ui` library to npm registry.
+
+## Prerequisites
+
+- Node.js and pnpm installed
+- npm account with access to publish to `@moneymap` scope
+- Access to the MoneyMap monorepo
+
+## Project Structure
+
+```
+libs/ui/
+├── src/                   # Source components
+├── dist/                  # Build output (generated)
+├── package.json           # Package configuration
+├── rollup.config.cjs      # Build configuration
+└── README.md              # This file
+```
+
+## Publishing Workflow
+
+### 1. Clean and Build
+
+Reset Nx cache and build the library:
+
+```bash
+# From workspace root
+nx reset
+nx build ui
+```
+
+This generates the build output in `libs/ui/dist/`:
+
+- `dist/index.esm.js` - Compiled JavaScript bundle
+- `dist/index.d.ts` - TypeScript declarations
+- `dist/src/` - Source files for `@moneymap/source` export
+
+### 2. Login to npm
+
+Ensure you're logged into npm with an account that has publish access:
+
+```bash
+npm login
+```
+
+Verify your login:
+
+```bash
+npm whoami
+```
+
+### 3. Test Package (Dry Run)
+
+Preview what will be published without actually publishing:
+
+```bash
+cd libs/ui
+npm pack --dry-run
+```
+
+**Expected output should include:**
+
+- ✅ `dist/index.esm.js`
+- ✅ `dist/index.d.ts`
+- ✅ `dist/src/` (source files)
+- ✅ `package.json`
+- ✅ `README.md`
+- ❌ No config files (`.babelrc`, `rollup.config.cjs`, `tsconfig.*`)
+
+### 4. Version Bump
+
+**Important:** You must increment the version before publishing.
+
+#### For Prerelease (Alpha/Beta)
+
+```bash
+# From libs/ui/
+npm version prerelease --preid=alpha
+# Example: 0.0.1-alpha.0 → 0.0.1-alpha.1
+# Example: 0.0.1-beta.0 → 0.0.1-beta.1
+```
+
+#### For Patch Release
+
+```bash
+npm version patch
+# Example: 0.0.1 → 0.0.2
+```
+
+#### For Minor Release
+
+```bash
+npm version minor
+# Example: 0.0.1 → 0.1.0
+```
+
+#### For Major Release
+
+```bash
+npm version major
+# Example: 0.0.1 → 1.0.0
+```
+
+#### Manual Version Update
+
+Alternatively, edit `libs/ui/package.json` directly:
+
+```json
+{
+  "version": "0.0.1"
+}
+```
+
+### 5. Publish to npm
+
+#### Publish Prerelease (Alpha/Beta)
+
+```bash
+# From libs/ui/
+npm publish --tag alpha --access public
+```
+
+This publishes with the `alpha` tag, so it won't become the default `latest` version.
+
+**Installing prerelease:**
+
+```bash
+npm install @moneymap/ui@alpha
+# or specific version
+npm install @moneymap/ui@0.0.1-alpha.1
+```
+
+#### Publish Stable Release
+
+```bash
+# From libs/ui/
+npm publish --access public
+```
+
+This publishes with the `latest` tag (default).
+
+**Installing stable:**
+
+```bash
+npm install @moneymap/ui
+```
+
+### 6. Verify Publication
+
+Check the published package:
+
+```bash
+npm view @moneymap/ui
+
+# Check all versions
+npm view @moneymap/ui versions
+
+# Check dist-tags
+npm view @moneymap/ui dist-tags
+```
+
+## Quick Reference Commands
+
+```bash
+# Full deployment workflow (stable release)
+nx reset
+nx build ui
+cd libs/ui
+npm pack --dry-run              # Verify package contents
+npm version patch               # Bump version
+npm publish --access public     # Publish
+
+# Full deployment workflow (prerelease)
+nx reset
+nx build ui
+cd libs/ui
+npm pack --dry-run
+npm version prerelease --preid=alpha
+npm publish --tag alpha --access public
+```
+
+## Troubleshooting
+
+### Cannot publish over previously published version
+
+You're trying to publish a version that already exists. Bump the version number:
+
+```bash
+npm version patch
+```
+
+### Package includes unwanted files
+
+Check the `files` field in `libs/ui/package.json`:
+
+```json
+{
+  "files": [
+    "dist",
+    "src/**/*.ts",
+    "src/**/*.tsx",
+    "!src/**/*.test.ts",
+    "!src/**/*.spec.ts"
+  ]
+}
+```
+
+Run `npm pack --dry-run` to preview before publishing.
+
+## Package Configuration
+
+### package.json
+
+The `libs/ui/package.json` controls what gets published:
+
+```json
+{
+  "name": "@moneymap/ui",
+  "version": "0.0.1",
+  "main": "./dist/index.esm.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "@moneymap/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.esm.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.ts",
+    "src/**/*.tsx",
+    "!src/**/*.test.ts",
+    "!src/**/*.spec.ts"
+  ]
+}
+```
+
+### rollup.config.cjs
+
+The build configuration uses Rollup with SWC for fast compilation:
+
+```javascript
+module.exports = withNx({
+  main: './src/index.ts',
+  outputPath: './dist',
+  compiler: 'swc',
+  format: ['esm'],
+  external: ['react', 'react-dom', 'react/jsx-runtime'],
+  assets: [
+    { input: '.', output: '.', glob: 'README.md' },
+    {
+      input: './src',
+      output: './src',
+      glob: '**/*.ts',
+      ignore: ['**/*.spec.ts', '**/*.test.ts'],
+    },
+    {
+      input: './src',
+      output: './src',
+      glob: '**/*.tsx',
+      ignore: ['**/*.spec.tsx', '**/*.test.tsx'],
+    },
+  ],
+});
+```
+
+## Version Strategy
+
+- **Prerelease (alpha/beta):** For testing new features
+  - Format: `0.0.1-alpha.0`, `0.0.1-beta.1`
+  - Publish with: `npm publish --tag alpha`
+
+- **Patch (0.0.x):** Bug fixes and minor changes
+  - Command: `npm version patch`
+
+- **Minor (0.x.0):** New features, backward compatible
+  - Command: `npm version minor`
+
+- **Major (x.0.0):** Breaking changes
+  - Command: `npm version major`
+
+## Support
+
+For questions or issues, contact the MoneyMap development team.