@tpzdsp/next-toolkit 1.0.1

package/README.md

@@ -0,0 +1,594 @@
+# Next.js Component Library
+
+A modern, reusable React component library designed specifically for Next.js applications. This library provides a collection of client and server components, hooks, contexts, and utilities with full TypeScript support.
+
+## 📋 Prerequisites
+
+- **Node.js**: 22.17.1 (managed with `asdf`)
+- **Package Manager**: Yarn (preferred) or npm
+- **Next.js**: 13+ (peer dependency)
+- **React**: 18+ (peer dependency)
+
+## Features
+
+- 🚀 **Next.js Optimized**: Built specifically for Next.js with support for both client and server components
+- 🎨 **Tailwind CSS v3**: Styled with Tailwind CSS and includes `tailwind-merge` for efficient class merging
+- 📦 **Multiple Export Patterns**: Separate exports for client, server, and shared utilities
+- 🧪 **Fully Tested**: Comprehensive test coverage with Vitest and React Testing Library
+- 📝 **TypeScript First**: Full TypeScript support with proper type definitions
+- ⚡ **Fast Development**: Built with Vite for lightning-fast development and builds
+- 🎯 **Tree Shakeable**: Optimized for tree-shaking to reduce bundle size
+- 🔄 **Source Distribution**: Distributes raw TypeScript files for optimal bundling
+
+## Installation
+
+```bash
+yarn add @your-org/nextjs-library
+# or
+npm install @your-org/nextjs-library
+# or
+pnpm add @your-org/nextjs-library
+```
+
+## Usage
+
+### Basic Import
+
+```typescript
+// Import everything
+import { Button, Card, useLocalStorage } from '@your-org/nextjs-library';
+
+// Import styles (choose one method)
+import '@your-org/nextjs-library/styles';
+// OR if the above doesn't work:
+// import '@your-org/nextjs-library/src/assets/styles/globals.css';
+```
+
+### Selective Imports (Recommended)
+
+```typescript
+// Import only client components
+import { Button, NextLinkWrapper } from '@your-org/nextjs-library/client';
+
+// Import only server components
+import { Card, Container } from '@your-org/nextjs-library/server';
+
+// Import only types
+import type { ButtonProps, ApiResponse, FormFieldProps } from '@your-org/nextjs-library/types';
+```
+
+### Example Usage
+
+```tsx
+import { Button } from '@your-org/nextjs-library/client';
+import { Card } from '@your-org/nextjs-library/server';
+import '@your-org/nextjs-library/styles'; // or the src path if this doesn't work
+
+export default function MyPage() {
+  return (
+    <Card title="Welcome" description="Get started with our components">
+      <Button variant="primary" size="lg">
+        Get Started
+      </Button>
+    </Card>
+  );
+}
+```
+
+### Using Exported Types
+
+```tsx
+import type {
+  ButtonProps,
+  ButtonVariant,
+  CardProps,
+  BaseProps,
+  ThemeContextValue,
+} from '@your-org/nextjs-library';
+
+// Use library types in your own components
+interface MyCustomButtonProps extends ButtonProps {
+  icon?: React.ReactNode;
+}
+
+// Use type unions for consistency
+const handleVariantChange = (variant: ButtonVariant) => {
+  console.log('Variant changed to:', variant);
+};
+
+// Extend base props for your own components
+interface MyComponentProps extends BaseProps {
+  customProp: string;
+}
+```
+
+## Available Components
+
+### Client Components
+
+- **Button**: Interactive button with multiple variants and loading states
+- **NextLinkWrapper**: Enhanced Next.js Link wrapper with external link handling
+- **ThemeProvider**: Theme context provider for dark/light mode
+
+### Server Components
+
+- **Card**: Flexible card component with title and description
+- **Container**: Responsive container with multiple size options
+
+### Hooks
+
+- **useLocalStorage**: localStorage hook with SSR support
+- **useDebounce**: Debounce values and functions
+
+### Utilities
+
+- **cn()**: Tailwind class merging utility using tailwind-merge
+- **debounce()**: Function debouncing utility
+- **formatBytes()**: Human-readable byte formatting
+
+### Types & Interfaces
+
+- **Component Props**: `ButtonProps`, `CardProps`, `ContainerProps`, etc.
+- **Common Types**: `BaseProps`, `Variant`, `Size`, `Status`, `Theme`
+- **Form Types**: `FormFieldProps`, `ChangeHandler`, `SubmitHandler`
+- **API Types**: `ApiResponse<T>`, `PaginatedResponse<T>`, `PaginationMeta`
+- **Utility Types**: `PropsWithRequired<T, K>`, `PropsWithOptional<T, K>`
+
+## 🏗️ Project Structure
+
+```
+src/
+├── components/
+│   ├── client/          # Client components ('use client' directive)
+│   │   ├── Button/
+│   │   │   ├── Button.tsx
+│   │   │   └── Button.test.tsx
+│   │   ├── NextLinkWrapper/
+│   │   └── ThemeProvider/
+│   └── server/          # Server components (SSR compatible)
+│       ├── Card/
+│       │   ├── Card.tsx
+│       │   └── Card.test.tsx (when created)
+│       └── Container/
+├── hooks/               # React hooks (client-side only)
+│   ├── useLocalStorage.ts
+│   └── useDebounce.ts
+├── contexts/            # React contexts (client-side only)
+│   └── ThemeContext.tsx
+├── utils/               # Utilities (client & server compatible)
+│   └── index.ts
+├── assets/              # CSS, images, and static assets
+│   ├── styles/
+│   └── images/
+├── types.ts             # TypeScript type definitions
+└── index.ts             # Main library exports
+
+vitest.setup.ts          # Test configuration (top-level)
+```
+
+## 🧭 Architecture Decisions
+
+### Client vs Server Components
+
+- **Client Components** (`src/components/client/`): Include `'use client';` directive, used for interactive features, hooks, and state management
+- **Server Components** (`src/components/server/`): No directive needed, can be server-side rendered, used for static content and layouts
+
+### Source Distribution Strategy
+
+This library distributes **raw TypeScript/TSX files** instead of compiled bundles:
+
+- ✅ Better tree-shaking in consuming applications
+- ✅ Consuming apps control the build process and browser targets
+- ✅ Smaller final bundle sizes
+- ✅ No build step needed during development
+
+### Styling Approach
+
+- **Tailwind CSS v3** for utility-first styling
+- **tailwind-merge** (`cn()` utility) for intelligent class merging
+- Component-specific CSS classes in `assets/styles/globals.css`
+
+## Development
+
+```bash
+# Install dependencies
+yarn install
+
+# Start development server
+yarn dev
+
+# Run tests
+yarn test
+
+# Run tests with UI
+yarn test:ui
+
+# Build the library (TypeScript check only)
+yarn build
+
+# Build distribution files (if needed)
+yarn build:dist
+
+# Preview the built library
+yarn preview
+```
+
+## Local Development with Yalc
+
+This library works perfectly with `yalc` for local testing before publishing to npm. Since we distribute source files, changes are reflected immediately.
+
+### Setup Yalc (one-time)
+
+```bash
+# Install yalc globally
+npm install -g yalc
+```
+
+### Publishing to Yalc Store
+
+```bash
+# In this library directory
+yarn yalc:publish
+# or
+yalc publish
+```
+
+### Using in Your Next.js App
+
+```bash
+# In your Next.js app directory
+yalc add @your-org/nextjs-library
+
+# Install dependencies (yalc creates a symlink-like structure)
+yarn install
+```
+
+### Your Next.js App Configuration
+
+Add to your `next.config.js`:
+
+```js
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  transpilePackages: ['@your-org/nextjs-library'],
+  // Enable if you want faster refresh during development
+  experimental: {
+    externalDir: true,
+  },
+};
+
+module.exports = nextConfig;
+```
+
+### Development Workflow
+
+```bash
+# 1. Make changes to the library
+# 2. Push changes to apps using the library
+yarn yalc:push
+# or
+yalc push
+
+# 3. Your Next.js app will automatically pick up the changes!
+```
+
+### Removing from Test App
+
+```bash
+# In your Next.js app directory
+yalc remove @your-org/nextjs-library
+yarn install
+```
+
+### Benefits with Source Distribution
+
+- ✅ **Instant Changes**: Since we distribute source files, changes appear immediately
+- ✅ **Full TypeScript**: Complete type checking and IntelliSense
+- ✅ **Tree Shaking**: Your app's bundler handles optimization
+- ✅ **Hot Reload**: Works with Next.js development server
+- ✅ **No Build Step**: No need to rebuild the library for every change
+
+## 🚀 Quick Yalc Workflow
+
+### Library Development (this repo):
+
+```bash
+# First time setup
+yalc publish
+
+# After making changes
+yalc push  # Pushes to all connected apps
+```
+
+### In Your Next.js Test App:
+
+```bash
+# Add the library
+yalc add @your-org/nextjs-library
+yarn install
+
+# Configure next.config.js (transpilePackages: ['@your-org/nextjs-library'])
+
+# Remove when done testing
+yalc remove @your-org/nextjs-library
+yarn install
+```
+
+## 🛠️ Adding New Components
+
+### Client Component Template
+
+```tsx
+// src/components/client/MyComponent/MyComponent.tsx
+'use client';
+
+import React from 'react';
+import { cn } from '../../../utils';
+
+export interface MyComponentProps {
+  children: React.ReactNode;
+  className?: string;
+  // Add your props here
+}
+
+export const MyComponent: React.FC<MyComponentProps> = ({ children, className, ...props }) => {
+  return (
+    <div className={cn('base-classes', className)} {...props}>
+      {children}
+    </div>
+  );
+};
+```
+
+### Server Component Template
+
+```tsx
+// src/components/server/MyComponent/MyComponent.tsx
+import React from 'react';
+import { cn } from '../../../utils';
+
+export interface MyComponentProps {
+  children: React.ReactNode;
+  className?: string;
+  // Add your props here
+}
+
+export const MyComponent: React.FC<MyComponentProps> = ({ children, className, ...props }) => {
+  return (
+    <div className={cn('base-classes', className)} {...props}>
+      {children}
+    </div>
+  );
+};
+```
+
+### Don't Forget To:
+
+1. Add exports to the appropriate `index.ts` file
+2. Create tests co-located with your component (e.g., `MyComponent.test.tsx`)
+3. Update TypeScript types if needed
+4. Test with `yalc` in a real Next.js app
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+**"Cannot resolve module" errors:**
+
+```bash
+# Make sure transpilePackages is configured in next.config.js
+transpilePackages: ['@your-org/nextjs-library']
+```
+
+**TypeScript errors in consuming app:**
+
+```bash
+# Ensure your tsconfig.json includes:
+{
+  "compilerOptions": {
+    "moduleResolution": "bundler", // or "node16"
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true
+  }
+}
+```
+
+**Tailwind styles not working:**
+
+```bash
+# Import the library styles in your app:
+import '@your-org/nextjs-library/styles';
+
+# Or alternatively, import the CSS file directly:
+import '@your-org/nextjs-library/src/assets/styles/globals.css';
+
+# And include the library in your tailwind.config.js content:
+content: [
+  // your paths...
+  './node_modules/@your-org/nextjs-library/src/**/*.{js,ts,jsx,tsx}',
+]
+```
+
+**yalc issues:**
+
+```bash
+# Reset yalc completely
+yalc remove --all
+yalc publish
+yalc add @your-org/nextjs-library
+```
+
+## Testing
+
+This library uses Vitest and React Testing Library for testing:
+
+```bash
+# Run all tests
+yarn test
+
+# Run tests in watch mode
+yarn test:watch
+
+# Run tests with coverage
+yarn test:coverage
+```
+
+## Build Configuration
+
+The library distributes **raw TypeScript/TSX source files** rather than pre-built bundles. This approach offers several benefits:
+
+- **Better Tree-Shaking**: Your bundler can eliminate unused code more effectively
+- **Optimal Bundling**: Your build process optimizes the code for your specific use case
+- **Smaller Bundle Size**: No duplicate dependencies or unnecessary polyfills
+- **Modern Output**: Your bundler can target your specific browser requirements
+
+### Requirements for Consuming Apps
+
+Your Next.js application needs to be configured to transpile the library:
+
+```js
+// next.config.js
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  transpilePackages: ['@your-org/nextjs-library'],
+};
+
+module.exports = nextConfig;
+```
+
+## Tailwind CSS Integration
+
+To use the library's Tailwind styles in your Next.js project:
+
+1. Import the library's Tailwind config:
+
+```js
+// tailwind.config.js
+import libraryConfig from '@your-org/nextjs-library/tailwind';
+
+export default {
+  ...libraryConfig,
+  content: [
+    ...libraryConfig.content,
+    './pages/**/*.{js,ts,jsx,tsx,mdx}',
+    './components/**/*.{js,ts,jsx,tsx,mdx}',
+    './app/**/*.{js,ts,jsx,tsx,mdx}',
+  ],
+};
+```
+
+2. Import the library styles:
+
+```js
+// pages/_app.js or app/layout.js or globals.css
+import '@your-org/nextjs-library/styles';
+
+// Alternative method (if the above doesn't work):
+import '@your-org/nextjs-library/src/assets/styles/globals.css';
+```
+
+## Contributing
+
+### Getting Started
+
+1. **Install asdf and set Node.js version:**
+
+   ```bash
+   # Install asdf if you haven't already
+   # Then install the required Node.js version
+   asdf install nodejs 22.17.1
+   asdf local nodejs 22.17.1
+   ```
+
+2. **Install dependencies:**
+
+   ```bash
+   yarn install
+   ```
+
+3. **Run tests to ensure everything works:**
+   ```bash
+   yarn test
+   ```
+
+### Development Workflow
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes following our component templates above
+4. Add tests for your changes (`src/test/YourComponent.test.tsx`)
+5. Run the test suite (`yarn test`)
+6. Test with yalc in a real Next.js app
+7. Commit your changes (`git commit -m 'Add some amazing feature'`)
+8. Push to the branch (`git push origin feature/amazing-feature`)
+9. Open a Pull Request
+
+### Code Style
+
+- Use TypeScript for all files
+- Follow the existing component patterns
+- Use `cn()` utility for className merging
+- Include proper TypeScript interfaces
+- Add tests for new components/functions
+- Document props and functions with JSDoc comments
+
+## License
+
+MIT License - see the [LICENSE](LICENSE) file for details.
+
+```js
+export default tseslint.config([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+
+      // Remove tseslint.configs.recommended and replace with this
+      ...tseslint.configs.recommendedTypeChecked,
+      // Alternatively, use this for stricter rules
+      ...tseslint.configs.strictTypeChecked,
+      // Optionally, add this for stylistic rules
+      ...tseslint.configs.stylisticTypeChecked,
+
+      // Other configs...
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+]);
+```
+
+You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+
+```js
+// eslint.config.js
+import reactX from 'eslint-plugin-react-x';
+import reactDom from 'eslint-plugin-react-dom';
+
+export default tseslint.config([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+      // Enable lint rules for React
+      reactX.configs['recommended-typescript'],
+      // Enable lint rules for React DOM
+      reactDom.configs.recommended,
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+]);
+```