@scalably/ui 0.1.0

package/README.md

@@ -0,0 +1,326 @@
+# Scalably UI Component Library
+
+A modern, accessible, and fully isolated React component library built with TypeScript and Tailwind CSS. Designed to work seamlessly across multiple projects without style conflicts.
+
+## 🚀 Features
+
+- **Style Isolation**: All components use prefixed Tailwind classes (`sui-*`) to prevent conflicts
+- **TypeScript First**: Full type safety with comprehensive prop interfaces
+- **Accessible**: Built with accessibility best practices and WCAG compliance
+- **Modern**: Uses latest React patterns and modern build tools (tsup, Vite, Storybook)
+- **Customizable**: Flexible variant system with class-variance-authority
+- **Comprehensive**: 20+ production-ready components with full documentation
+- **Production Ready**: Complete build pipeline with CommonJS and ES modules
+
+## 📦 Installation
+
+```bash
+npm install @scalably/ui
+```
+
+## 🎨 Usage
+
+### 1. Import the CSS
+
+Add the component library styles to your main entry point:
+
+```tsx
+// In your main.tsx, App.tsx, or index.tsx
+import "@scalably/ui/styles";
+```
+
+### 2. Use Components
+
+```tsx
+import "@scalably/ui/styles";
+import { ScalablyUIProvider, Form, FormField, Input, Button, ToastContainer, Toast } from "@scalably/ui";
+
+export default function App() {
+  return (
+    <ScalablyUIProvider>
+      <main>
+        <Form onSubmit={(e) => e.preventDefault()}>
+          <FormField label="Email" htmlFor="email">
+            <Input id="email" type="email" placeholder="Enter your email" />
+          </FormField>
+          <Button className="sui-mt-4" type="submit">Submit</Button>
+        </Form>
+
+        {/* Toasts */}
+        <ToastContainer />
+        <Toast status="success" title="Welcome" description="You're all set." />
+      </main>
+    </ScalablyUIProvider>
+  );
+}
+```
+
+### 3. Add the provider once (recommended)
+
+Instead of adding the `sui-scope` class manually, wrap your app with the provider:
+
+```tsx
+import "@scalably/ui/styles";
+import { ScalablyUIProvider } from "@scalably/ui";
+
+export default function App() {
+  return <ScalablyUIProvider>{/* your app */}</ScalablyUIProvider>;
+}
+```
+
+Optional no extra DOM element:
+
+```tsx
+<ScalablyUIProvider asChild>
+  <main>{/* your app */}</main>
+  {/* merges the scope onto <main> */}
+</ScalablyUIProvider>
+```
+
+### 4. React import guidance
+
+If you reference the React namespace (e.g., `React.useState`, `React.forwardRef`, `React.SVGProps`) add an explicit import to avoid UMD global errors:
+
+```ts
+import * as React from "react";
+```
+
+Alternatively, import only what you use with the automatic JSX runtime:
+
+```ts
+import { useState, forwardRef } from "react";
+import type { SVGProps } from "react";
+```
+
+### Helper Functions
+- Date helpers: `addMonths`, `clampDate`, `daysGrid`, `endOfMonth`, `formatDateLocalized`, `isSameDay`, `monthsForLocale`, `startOfMonth`, `toDateKey`, `weekdaysForLocale`
+- Form helpers: `fieldErrorToProps`, `zodErrorsToSummary` and `type FieldErrorLike`
+
+### Example Usage
+
+```tsx
+import { 
+  Button, 
+  Input, 
+  Select, 
+  CheckboxGroup,
+  DatePicker,
+  Toast,
+  Pagination 
+} from '@scalably/ui'
+
+// Button with variants
+<Button variant="destructive">Delete</Button>
+<Button variant="outline">Cancel</Button>
+<Button loading>Loading...</Button>
+
+// Input with validation
+<Input
+  label="Email Address"
+  type="email"
+  placeholder="Enter your email"
+  error="Please enter a valid email"
+/>
+
+// Date picker
+<DatePicker
+  mode="single"
+  placeholder="Select a date"
+  onChange={(date) => console.log(date)}
+/>
+
+// Toast notifications
+<Toast
+  status="success"
+  title="Success!"
+  description="Your changes have been saved."
+/>
+```
+
+## 🎨 Styling
+
+### Style Isolation
+
+All components use prefixed Tailwind classes (`sui-*`) to ensure complete style isolation:
+
+```tsx
+// ✅ Correct - components are properly isolated
+<div className="sui-scope">
+  <Button>Isolated Button</Button>
+</div>
+
+// ❌ Avoid - mixing prefixed and non-prefixed classes
+<div className="p-4"> {/* This won't conflict */}
+  <Button>Button with ui-* classes</Button>
+</div>
+```
+
+### Custom Styling
+
+You can still customize components using the `className` prop:
+
+```tsx
+<Button className="sui-w-full sui-mt-4">Full Width Button</Button>
+<Card className="sui-max-w-md sui-mx-auto">Centered Card</Card>
+```
+
+## 🛠 Development
+
+### Prerequisites
+
+- Node.js 18+
+- npm or pnpm
+
+### Setup
+
+```bash
+# Clone the repository
+git clone git@github.com:quangnle/scalably-components.git
+cd scalably-components
+
+# Install dependencies
+npm install
+
+# Start Storybook for development
+npm run storybook
+
+# Build the library
+npm run build
+
+# Run tests
+npm test
+```
+
+### Available Scripts
+
+- `npm run dev` - Start development build with watch mode
+- `npm run build` - Build the library for production
+- `npm run build:css` - Build CSS styles separately
+- `npm run storybook` - Start Storybook development server
+- `npm run build-storybook` - Build Storybook for production
+- `npm run lint` - Run ESLint
+- `npm run lint:fix` - Run ESLint with auto-fix
+- `npm run type-check` - Run TypeScript type checking
+- `npm test` - Run tests
+- `npm run test:watch` - Run tests in watch mode
+- `npm run test:ci` - Run tests with coverage
+- `npm run verify` - Run verification script
+- `npm run clean` - Clean build artifacts
+
+## 📚 Documentation
+
+Visit our Storybook documentation for:
+
+- Interactive component playground
+- Comprehensive prop documentation
+- Usage examples and best practices
+- Design system guidelines
+- Accessibility testing with axe-core
+- Design tokens and theming
+
+## 🎨 Design System
+
+### Colors
+
+- **Primary**: `#36499B` - Main brand color for primary actions
+- **Secondary**: `#F2F6FC` - Light background colors with multiple levels
+- **Success**: `#22BC4D` - Green for positive actions and success states
+- **Warning**: `#FF7A00` - Orange for caution and in-progress states
+- **Info**: `#2772F0` - Blue for informational content
+- **Error**: `#EA3540` - Red for destructive actions and errors
+- **Inactive**: `#777E90` - Gray for inactive or completed states
+- **Disabled**: `#B2BBC7` - Light gray for disabled elements
+
+### Typography
+
+- **Font Family**: Poppins (primary), Inter (fallback), system-ui
+- **Font Sizes**: 12px, 14px, 16px, 20px, 24px with 150% line-height and -2% letter-spacing
+- **Font Weights**: 400 (normal), 500 (medium), 600 (semibold), 700 (bold)
+
+## 🔧 Configuration
+
+### Tailwind Config
+
+The library uses a custom Tailwind configuration with:
+
+- **Prefix**: `sui-` for all utility classes
+- **Important**: `.sui-scope` for style isolation
+- **Custom Colors**: Brand-specific color palette
+- **Custom Shadows**: Soft, medium, and strong shadow variants
+
+### Build Configuration
+
+- **Bundler**: tsup for fast, modern builds
+- **Formats**: CommonJS and ES modules with proper exports
+- **TypeScript**: Full type definitions included
+- **Tree Shaking**: Optimized for minimal bundle size
+- **CSS**: Separate CSS build with Tailwind compilation
+- **Source Maps**: Generated for debugging
+- **Minification**: Production builds are minified
+
+## 📦 Publishing
+
+### Version Management
+
+We use semantic versioning (semver):
+
+- **Major** (1.0.0): Breaking changes
+- **Minor** (0.1.0): New features, backward compatible
+- **Patch** (0.0.1): Bug fixes, backward compatible
+
+### Publishing Process
+
+```bash
+# Build the library
+npm run build
+
+# Run tests
+npm test
+
+# Publish to registry
+npm publish
+```
+
+### Development Guidelines
+
+- Follow TypeScript best practices
+- Write comprehensive Storybook stories
+- Ensure accessibility compliance
+- Add tests for new components
+- Update documentation
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🆘 Support
+
+- **Documentation**: Storybook (run `npm run storybook`)
+- **Issues**: GitHub Issues
+- **Discussions**: GitHub Discussions
+
+## 🧪 Testing
+
+The library includes comprehensive testing setup:
+
+- **Unit Tests**: Vitest with React Testing Library
+- **Accessibility**: jest-axe for a11y testing
+- **Coverage**: Built-in coverage reporting
+- **CI/CD**: Automated testing pipeline
+
+## 🔧 Dependencies
+
+### Peer Dependencies
+- React 18+
+- React DOM 18+
+
+### Key Dependencies
+- `@floating-ui/react` - Positioning for tooltips and popovers
+- `class-variance-authority` - Component variant management
+- `date-fns` - Date manipulation utilities
+- `clsx` - Conditional class names
+- `tailwind-merge` - Tailwind class merging
+
+---
+
+Built with ❤️ by the Scalably team