@umituz/web-design-system 3.1.21 → 4.0.0

package/README.md

@@ -1,503 +1,171 @@
 # @umituz/web-design-system
 
-> Web Design System - Atomic Design components (Atoms, Molecules, Organisms) for React applications
+Atomic Design component library for React: atoms, molecules, overlay/data
+organisms, templates and hooks. **Authored in Tailwind v4, shipped as both
+source and a precompiled stylesheet** — it works in any React host, with or
+without Tailwind.
 
-## 📦 Installation
+The package is **source-distributed** (raw TypeScript in `src/`); your
+bundler compiles the components. Styling is available two ways:
 
-```bash
-npm install @umituz/web-design-system
-# or
-yarn add @umituz/web-design-system
-# or
-pnpm add @umituz/web-design-system
-```
-
-## 🚀 Quick Start
-
-```tsx
-// ✅ Use subpath imports (RECOMMENDED)
-import { Button } from '@umituz/web-design-system/atoms';
-import { Card } from '@umituz/web-design-system/organisms';
-
-function App() {
-  return (
-    <Card>
-      <Button variant="primary">Click me</Button>
-    </Card>
-  );
-}
-```
-
-## 📚 Available Subpaths
-
-### Atoms (Smallest UI Elements)
-```tsx
-import {
-  Button,
-  Badge,
-  Input,
-  Text,
-  Icon,
-  Spinner
-} from '@umituz/web-design-system/atoms';
-```
-
-### Molecules (Simple Combinations)
-```tsx
-import {
-  FormField,
-  SearchBox,
-  Avatar,
-  Chip,
-  Toggle
-} from '@umituz/web-design-system/molecules';
-```
-
-### Organisms (Complex UI Components)
-```tsx
-import {
-  Card,
-  Alert,
-  Modal,
-  Navbar
-} from '@umituz/web-design-system/organisms';
-```
-
-### Templates (Page Structures)
-```tsx
-import {
-  Form,
-  List,
-  Section,
-  PageLayout,
-  PageHeader,
-  ResponsiveContainer,
-  ProjectSkeleton
-} from '@umituz/web-design-system/templates';
-```
-
-### Hooks (React Hooks)
-```tsx
-import {
-  useTheme,
-  useMediaQuery,
-  useBreakpoint,
-  useLocalStorage,
-  useLanguage,
-  useClickOutside,
-  useKeyboard,
-  useEscape,
-  useDebounce,
-  useClipboard,
-  useToggle,
-  useScrollLock
-} from '@umituz/web-design-system/hooks';
-```
-
-### Tokens (Design Tokens)
-```tsx
-import {
-  lightColorTokens,
-  darkColorTokens,
-  spacing,
-  fontSizes,
-  radii,
-  shadows
-} from '@umituz/web-design-system/tokens';
-```
-
-### Types (TypeScript Types)
-```tsx
-import type {
-  SizeVariant,
-  ColorVariant,
-  BaseProps
-} from '@umituz/web-design-system/types';
-```
+- `@umituz/web-design-system/styles.css` — precompiled (`dist/styles.css`),
+  Tailwind included. For vanilla-CSS hosts.
+- `@umituz/web-design-system/theme.css` — the `@theme` layer alone. For
+  Tailwind v4 hosts that compile the component classes themselves.
 
-### Security (Security & Validation)
-```tsx
-import {
-  validateInput,
-  validateEmail,
-  validateUrl,
-  sanitizeInput,
-  validateFileName,
-  CSP_CONFIG,
-  SECURITY_HEADERS,
-  VALIDATION_CONFIGS
-} from '@umituz/web-design-system/security';
-
-import { useFormValidation, COMMON_RULES } from '@umituz/web-design-system/security';
-```
+**Never use both** — a Tailwind host that adds the package source to its own
+`@source` scan must not also import the precompiled stylesheet (duplicate
+rules).
 
-### Performance (Performance Optimization)
-```tsx
-import {
-  usePerformanceMonitor,
-  useLazyLoading,
-  useMemoryOptimization,
-  useLazyImage,
-  useLazyComponent,
-  useVirtualList
-} from '@umituz/web-design-system/performance';
-```
+## Installation
 
-### Error (Error Handling & Boundaries)
-```tsx
-import {
-  ErrorBoundary,
-  ErrorDisplay,
-  SuspenseWrapper,
-  NetworkError,
-  NotFoundError,
-  ApiError
-} from '@umituz/web-design-system/error';
+```bash
+npm install @umituz/web-design-system
 ```
 
-## 🎨 Component Examples
+`clsx`, `class-variance-authority` and `tailwind-merge` are real runtime
+dependencies (installed automatically). Peers: `react`, `react-dom`,
+`lucide-react`, `react-syntax-highlighter` (CodeBlock only) and the 14
+Radix primitives actually imported (dialog, dropdown-menu, select, …).
 
-### Button
+### Vanilla host (no Tailwind)
 
 ```tsx
+// main.tsx — one import, includes preflight
+import '@umituz/web-design-system/styles.css';
 import { Button } from '@umituz/web-design-system/atoms';
 
-<Button variant="primary" size="md">Primary Button</Button>
-<Button variant="secondary" size="lg">Secondary Button</Button>
-<Button variant="success" size="sm">Success Button</Button>
-```
-
-### Card
-
-```tsx
-import { Card, CardHeader, CardTitle, CardDescription, CardContent } from '@umituz/web-design-system/organisms';
-
-<Card>
-  <CardHeader>
-    <CardTitle>Card Title</CardTitle>
-    <CardDescription>Card description goes here</CardDescription>
-  </CardHeader>
-  <CardContent>
-    <p>Card content</p>
-  </CardContent>
-</Card>
-```
-
-### Alert
-
-```tsx
-import { Alert } from '@umituz/web-design-system/organisms';
-
-<Alert variant="success">Success message!</Alert>
-<Alert variant="warning">Warning message!</Alert>
-<Alert variant="destructive">Error message!</Alert>
+<Button>Save</Button>
 ```
 
-### Theme Hook
+Restyle by overriding the CSS variables — no rebuild needed:
 
-```tsx
-import { useTheme } from '@umituz/web-design-system/hooks';
-
-function ThemeToggle() {
-  const { theme, toggleTheme } = useTheme();
-  return (
-    <Button onClick={toggleTheme}>
-      Current: {theme}
-    </Button>
-  );
-}
-```
-
-### Language Hook
-
-```tsx
-import { useLanguage } from '@umituz/web-design-system/hooks';
-
-function LanguageSelector() {
-  const { currentLanguage, changeLanguage, t, supportedLanguages } = useLanguage({
-    defaultLanguage: 'en-US',
-    supportedLanguages: {
-      'en-US': { name: 'English', flag: '🇺🇸' },
-      'tr-TR': { name: 'Türkçe', flag: '🇹🇷' },
-      'de-DE': { name: 'Deutsch', flag: '🇩🇪' },
-    }
-  });
-
-  return (
-    <select value={currentLanguage} onChange={(e) => changeLanguage(e.target.value)}>
-      {Object.entries(supportedLanguages).map(([code, { name, flag }]) => (
-        <option key={code} value={code}>{flag} {name}</option>
-      ))}
-    </select>
-  );
-}
-```
-
-### Breakpoint Hook
-
-```tsx
-import { useBreakpoint, useMediaQuery } from '@umituz/web-design-system/hooks';
-
-function ResponsiveComponent() {
-  const breakpoint = useBreakpoint();
-  const isDesktop = useMediaQuery('lg');
-  const isTablet = useMediaQuery('md');
-
-  return (
-    <div>
-      Current breakpoint: {breakpoint || 'mobile'}
-      {isDesktop && <DesktopNavigation />}
-      {isTablet && !isDesktop && <TabletNavigation />}
-    </div>
-  );
+```css
+:root {
+  --color-primary: #2e8b5f;        /* brand color, e.g. herb green */
+  --color-primary-foreground: #ffffff;
+  --color-ring: rgba(46, 139, 95, 0.45);
 }
 ```
 
-## 📱 Responsive Templates
-
-### ResponsiveContainer
-
-```tsx
-import { ResponsiveContainer } from '@umituz/web-design-system/templates';
-
-// Auto-responsive container with different max widths per device
-<ResponsiveContainer
-  mobileMaxWidth="full"
-  tabletMaxWidth="lg"
-  desktopMaxWidth="xl"
-  gradient
-  minHeight="screen"
->
-  <h1>Auto-responsive content</h1>
-  <p>This container automatically adjusts based on screen size</p>
-</ResponsiveContainer>
-
-// Custom responsive container
-<ResponsiveContainer
-  mobilePadding={false}
-  tabletPadding={true}
-  desktopPadding={true}
-  centered={false}
->
-  <div>Custom responsive layout</div>
-</ResponsiveContainer>
-```
-
-## 🎯 Design Tokens
-
-### Colors
-
-```tsx
-import { lightColorTokens, darkColorTokens } from '@umituz/web-design-system/tokens';
-
-// Light mode
-const colors = lightColorTokens;
-// {
-//   primary: 'hsl(187 75% 38%)',
-//   background: 'hsl(210 20% 98%)',
-//   ...
-// }
-
-// Dark mode
-const darkColors = darkColorTokens;
-```
-
-### Spacing
-
-```tsx
-import { spacing } from '@umituz/web-design-system/tokens';
-
-const gap = spacing['4']; // '1rem'
-```
-
-### Typography
+Dark mode: add `data-theme="dark"` or `class="dark"` on any ancestor
+(typically `<html>`). The package never switches themes on its own.
 
-```tsx
-import { fontSizes, fontWeights } from '@umituz/web-design-system/tokens';
-
-const fontSize = fontSizes['lg']; // '1.125rem'
-const fontWeight = fontWeights['semibold']; // '600'
-```
+### Tailwind v4 host
 
-## 🔒 Security Features
+Compile the component classes as part of your own build — then utilities
+you pass via `className` merge naturally with the package's:
 
-### Input Validation
-```tsx
-import { validateEmail, sanitizeInput, validateFileName } from '@umituz/web-design-system/security';
+```css
+/* app.css */
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "@umituz/web-design-system/theme.css";
+@source "../node_modules/@umituz/web-design-system/src";
+```
+
+You control the palette the same way (override `--color-*` in your theme),
+and your `@theme` extensions apply everywhere.
+
+## Theming
+
+Every component binds to semantic variables defined in `src/styles/theme.css`:
+
+| Variable | Light default | Purpose |
+| --- | --- | --- |
+| `--color-background` / `--color-foreground` | `#f8fafc` / `#0f172a` | app surface & text |
+| `--color-card` / `--color-popover` (+ `-foreground`) | `#ffffff` | elevated surfaces |
+| `--color-primary` / `--color-primary-foreground` | `#2563eb` / `#fff` | brand actions |
+| `--color-secondary` / `--color-secondary-foreground` | `#8b5cf6` / `#fff` | secondary actions |
+| `--color-muted` / `--color-muted-foreground` | `#f1f5f9` / `#64748b` | quiet surfaces & text |
+| `--color-accent` / `--color-accent-foreground` | `#f1f5f9` / `#0f172a` | hover accents |
+| `--color-destructive` / `--color-destructive-foreground` | `#dc2626` / `#fff` | danger actions |
+| `--color-success` / `--color-warning` / `--color-info` | `#16a34a` / `#d97706` / `#2563eb` | status (Badge variants) |
+| `--color-border` / `--color-input` | `#e2e8f0` | borders & inputs |
+| `--color-ring` | `rgba(37,99,235,.45)` | focus rings |
+| `--radius-sm` / `--radius-md` / `--radius-lg` / `--radius-xl` | 6/8/12/16px | radii scale |
+| `--shadow-sm` / `--shadow-md` / `--shadow-lg` | dashboard scale | elevation |
+| `--font-sans` / `--font-mono` | system stacks | typography |
+
+The defaults mirror `@umituz/web-dashboard`'s tokens, so dashboard adoption
+is visually regression-free. A brand override (e.g. foodora's herb green)
+is three variables:
 
-// Validate email
-const result = validateEmail('user@example.com');
-if (result.isValid) {
-  // Email is valid
+```css
+:root {
+  --color-primary: #2e8b5f;
+  --color-primary-foreground: #ffffff;
+  --color-info: #2e8b5f;
+}
+.dark {
+  --color-primary: #3aa76d;
 }
-
-// Sanitize user input
-const clean = sanitizeInput(userInput);
-
-// Validate file names
-const fileResult = validateFileName(fileName);
-```
-
-### Form Validation Hook
-```tsx
-import { useFormValidation, COMMON_RULES } from '@umituz/web-design-system/security';
-
-const MyForm = () => {
-  const { formData, errors, updateField, validateAllFields, isFormValid } = useFormValidation(
-    { name: '', email: '' },
-    {
-      name: COMMON_RULES.name,
-      email: COMMON_RULES.email
-    }
-  );
-
-  return (
-    <form onSubmit={handleSubmit}>
-      <input
-        value={formData.name}
-        onChange={(e) => updateField('name', e.target.value)}
-      />
-      {errors.name && <span className="error">{errors.name}</span>}
-    </form>
-  );
-};
-```
-
-## ⚡ Performance Features
-
-### Performance Monitoring
-```tsx
-import { usePerformanceMonitor } from '@umituz/web-design-system/performance';
-
-const MyComponent = () => {
-  const { metrics, getPerformanceReport } = usePerformanceMonitor({
-    componentName: 'MyComponent',
-    trackRenders: true,
-    trackMemory: true
-  });
-
-  return <div>Render time: {metrics.renderTime}ms</div>;
-};
-```
-
-### Lazy Loading
-```tsx
-import { useLazyLoading, useLazyImage } from '@umituz/web-design-system/performance';
-
-const LazyImage = () => {
-  const { targetRef, imageSrc, isLoaded } = useLazyImage('/large-image.jpg');
-
-  return (
-    <div ref={targetRef}>
-      {isLoaded ? <img src={imageSrc} alt="Lazy loaded" /> : <div>Loading...</div>}
-    </div>
-  );
-};
-```
-
-### Memory Optimization
-```tsx
-import { useMemoryOptimization } from '@umituz/web-design-system/performance';
-
-const MyComponent = () => {
-  const { addEventListener, setTimeout, addCleanup, getMemoryStats } = useMemoryOptimization();
-
-  useEffect(() => {
-    const cleanup = addEventListener(window, 'resize', handleResize);
-    const timerId = setTimeout(() => {}, 1000);
-
-    return () => {
-      cleanup();
-      // Automatic cleanup on unmount
-    };
-  }, []);
-
-  return <div>Memory stats: {getMemoryStats().totalTrackedItems} items</div>;
-};
-```
-
-## 🚨 Error Handling
-
-### Error Boundary
-```tsx
-import { ErrorBoundary } from '@umituz/web-design-system/error';
-
-<ErrorBoundary
-  level="page"
-  showDetails={true}
-  onError={(error, errorInfo) => console.error(error)}
->
-  <MyComponent />
-</ErrorBoundary>
-```
-
-### Error Display
-```tsx
-import { ErrorDisplay, NetworkError, ApiError } from '@umituz/web-design-system/error';
-
-<ErrorDisplay
-  error={error}
-  title="Something went wrong"
-  severity="error"
-  showRetry={true}
-  onRetry={retryFunction}
-/>
-
-<NetworkError onRetry={retry} />
-<ApiError error={apiError} onRetry={retry} />
 ```
 
-### Suspense Wrapper
-```tsx
-import { SuspenseWrapper, PageSuspense } from '@umituz/web-design-system/error';
+## Entry points
 
-<PageSuspense loadingText="Loading page...">
-  <MyLazyComponent />
-</PageSuspense>
+```bash
+@umituz/web-design-system/styles.css   # precompiled stylesheet (vanilla hosts)
+@umituz/web-design-system/theme.css     # @theme layer (Tailwind v4 hosts)
+@umituz/web-design-system/atoms         # Button, Input, Badge, Spinner, …
+@umituz/web-design-system/molecules     # FormField, Select, Avatar, …
+@umituz/web-design-system/organisms     # Card, Dialog, Sheet, Table, DataTable, …
+@umituz/web-design-system/templates     # page-level layouts
+@umituz/web-design-system/hooks         # useMediaQuery, useDebounce, useTheme, …
+@umituz/web-design-system/utils         # cn, responsive helpers, clamp/pagination math
+@umituz/web-design-system/utils/cn      # cn alone
+@umituz/web-design-system/constants     # size/type maps
+@umituz/web-design-system/tokens        # RESPONSIVE_* scale maps
+@umituz/web-design-system/types         # shared type contracts
+```
+
+Subpath imports are recommended; the root barrel exists but pulls
+everything.
+
+## What changed in v4 (major)
+
+- **Authored in Tailwind v4, precompiled CSS shipped.** v3 required the
+  host to run Tailwind with matching config; v4 compiles itself and binds
+  semantic classes to `--color-*` variables (`dist/styles.css` is a
+  published artifact with contract tests).
+- **Dead towers removed**: `infrastructure/security`, `performance`,
+  `calculation`, `error` (~2.5k lines, zero consumers). The four live
+  calculation helpers live in `utils` (`clampToRange`, `percentOfMax`,
+  `formatTrendMagnitude`, `computePageBounds`).
+- **App-specific organisms removed**: Navbar, MainNavbar, Footer,
+  NewsletterSignup, Comments, ImageLightbox, Calendar, FilterBar,
+  FilterSidebar, QuickActionCard, Grid, Modal, FormModal, ConfirmDialog,
+  AlertDialog (use Dialog), Breadcrumb molecule (organism stays).
+- **JS theme tokens removed** — theming is CSS-native now
+  (`src/styles/theme.css`). The `./tokens` subpath keeps the
+  `RESPONSIVE_*` scale maps only.
+- **`useLanguage` removed** — i18n runtime belongs to the host (same
+  principle as dashboard v4). `react-i18next` is no longer a peer.
+- **Peer list tightened to real imports** (14 Radix primitives;
+  `react-day-picker`, `react-alert-dialog`, `react-tabs`,
+  `react-tooltip` dropped). `clsx`/`class-variance-authority`/
+  `tailwind-merge` moved from peers to dependencies.
+- **Package ships tests** (contract + unit + smoke) and a `build` step;
+  `prepublishOnly` runs the full gate.
+
+## Platform compatibility
+
+React 18 and 19. Rendering targets the DOM; React Native is not supported.
+
+## Development
 
-<SuspenseWrapper variant="card" errorBoundaryLevel="feature">
-  <AsyncComponent />
-</SuspenseWrapper>
+```bash
+npm install
+npm run lint        # eslint
+npm run typecheck   # tsc --noEmit
+npm run build       # tailwindcss → dist/styles.css (minified)
+npm test            # build + vitest (contract, unit, smoke)
 ```
 
-## 📐 Atomic Design Principles
-
-This package follows Atomic Design methodology:
-
-- **Atoms**: Basic building blocks (Button, Input, Icon)
-- **Molecules**: Simple combinations (FormField, SearchBox, Chip)
-- **Organisms**: Complex components (Card, Modal, Navbar)
-- **Templates**: Page structures (Form, List, Section)
-
-## 🌐 Tailwind CSS Integration
+Component classes must stay literal in the source: `@source` scans
+`src/`, so classes passed in from outside (props) are not compiled into
+the precompiled stylesheet.
 
-This design system works seamlessly with Tailwind CSS. Make sure your Tailwind config includes the CSS variables:
-
-```css
-/* Your global CSS */
-@layer base {
-  :root {
-    --background: 210 20% 98%;
-    --foreground: 220 20% 12%;
-    --primary: 187 75% 38%;
-    --primary-foreground: 0 0% 100%;
-    /* ... more tokens */
-  }
-
-  .dark {
-    --background: 220 20% 7%;
-    --foreground: 210 20% 92%;
-    --primary: 187 85% 53%;
-    --primary-foreground: 220 20% 7%;
-    /* ... more tokens */
-  }
-}
-```
-
-## 📄 License
+## License
 
 MIT
-
-## 🤝 Contributing
-
-This package is part of the @umituz organization. For issues and feature requests, please visit the GitHub repository.