@omnifyjp/ui 0.4.4 → 0.5.0

package/README.md

@@ -1,218 +1,464 @@
 # @omnifyjp/ui
 
-A comprehensive React UI component library built on [Shadcn UI](https://ui.shadcn.com/) + [Radix UI](https://www.radix-ui.com/) + [Tailwind CSS v4](https://tailwindcss.com/). Provides 53 accessible primitives and 14 domain-specific components — all tree-shakeable with per-component entry points.
+A production-ready application shell framework for multi-tenant React apps. Provides a complete layout system with collapsible sidebar, header with organization switching, theme management, internationalization (vi/en/ja), and flexible page containers.
+
+Built on top of [`@omnifyjp/ui-components`](https://www.npmjs.com/package/@omnifyjp/ui-components) components.
 
 ## Installation
 
 ```bash
 npm install @omnifyjp/ui
-# or
-pnpm add @omnifyjp/ui
+# This automatically installs @omnifyjp/ui-components as a dependency
 ```
 
 ### Peer Dependencies
 
 ```bash
-npm install react react-dom
+npm install react react-dom react-router
 ```
 
-Optional peers (only needed if you use specific components):
+---
+
+## Quick Start
 
-| Peer | Required By |
-|------|-------------|
-| `date-fns` (>=3) | `calendar`, `date-picker` |
-| `recharts` (>=2) | `chart` |
-| `react-hook-form` (>=7) | `form` |
+```tsx
+import { createBrowserRouter, RouterProvider } from 'react-router';
+import { AppShell, initOmnifyI18n } from '@omnifyjp/ui';
+import type { ShellConfig } from '@omnifyjp/ui';
+import { LayoutDashboard, Users, Settings } from 'lucide-react';
+
+// 1. Initialize i18n with your service translations
+import enLocale from './locales/en.json';
+import viLocale from './locales/vi.json';
+
+initOmnifyI18n({
+  namespaces: {
+    myapp: { en: enLocale, vi: viLocale },
+  },
+});
+
+// 2. Define shell configuration
+const config: ShellConfig = {
+  app: {
+    name: 'My App',
+    key: 'myapp',
+    logo: { icon: LayoutDashboard, text: 'My App', color: 'text-blue-600' },
+  },
+  sidebar: {
+    menuItems: [
+      { icon: LayoutDashboard, label: 'Dashboard', path: '/' },
+      { icon: Users, label: 'Users', path: '/users' },
+      { icon: Settings, label: 'Settings', path: '/settings' },
+    ],
+  },
+  header: {
+    user: {
+      name: 'John Doe',
+      email: 'john@example.com',
+      onLogout: () => console.log('logout'),
+    },
+  },
+  organization: {
+    organizations: [
+      { id: '1', name: 'Acme Corp', shortName: 'AC' },
+    ],
+    branches: [
+      { id: '1', name: 'Tokyo Office', organizationId: '1', location: 'Tokyo' },
+      { id: '2', name: 'Hanoi Office', organizationId: '1', location: 'Hanoi' },
+    ],
+  },
+};
+
+// 3. Set up routes with AppShell as the layout
+const router = createBrowserRouter([
+  {
+    path: '/',
+    element: <AppShell config={config} />,
+    children: [
+      { index: true, element: <Dashboard /> },
+      { path: 'users', element: <Users /> },
+      { path: 'settings', element: <Settings /> },
+    ],
+  },
+]);
+
+function App() {
+  return <RouterProvider router={router} />;
+}
+```
 
 ---
 
-## Usage
+## Core Components
+
+### AppShell
 
-### Import individual components (recommended)
+The main application wrapper. Combines `ThemeProvider` + `I18nextProvider` + `OrganizationProvider`, then renders the sidebar, header, and a React Router `<Outlet />`.
 
 ```tsx
-import { Button } from '@omnifyjp/ui/components/button';
-import { Card, CardContent, CardHeader, CardTitle } from '@omnifyjp/ui/components/card';
-import { Input } from '@omnifyjp/ui/components/input';
+import { AppShell } from '@omnifyjp/ui';
+
+<AppShell config={config} extra={<ChatWidget />} />
 ```
 
-### Import from barrel (convenience)
+| Prop | Type | Description |
+|------|------|-------------|
+| `config` | `ShellConfig` | Full shell configuration (see below) |
+| `extra` | `ReactNode` | Optional floating elements (e.g., chat widget) |
 
-```tsx
-import { Button, Card, Input } from '@omnifyjp/ui';
-```
+### Sidebar
+
+Collapsible left navigation with context switching, expandable groups, and tooltips when collapsed.
+
+Features:
+- Logo area with app icon
+- Main menu items with nested groups
+- Context switching popover (e.g., project switcher with search)
+- Recent items section
+- Collapse/expand toggle
+- Organization selector badge
+
+### Header
 
-### Import utilities
+Top navigation bar with:
+- Organization/branch selector
+- Service menu (grid of available apps)
+- Global search input
+- Notification dropdown with count badge
+- Custom action buttons
+- User menu (profile, settings, logout)
+
+### PageContainer
+
+Flexible page layout wrapper with three variants:
 
 ```tsx
-import { cn } from '@omnifyjp/ui/lib/utils';
+import {
+  StandardPageContainer,
+  SplitPageContainer,
+  FullWidthPageContainer,
+} from '@omnifyjp/ui';
+
+// Standard — padded page with title bar
+<StandardPageContainer title="Users" subtitle="Manage team members" extra={<Button>Add User</Button>}>
+  <UserTable />
+</StandardPageContainer>
+
+// Split — two-column layout with sidebar
+<SplitPageContainer title="Settings" sidebar={<SettingsNav />} sidebarPosition="left">
+  <SettingsForm />
+</SplitPageContainer>
+
+// Full width — no padding (for Kanban boards, Gantt charts)
+<FullWidthPageContainer>
+  <KanbanBoard />
+</FullWidthPageContainer>
 ```
 
-### Import hooks
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `string` | — | Page heading |
+| `subtitle` | `string` | — | Description text below title |
+| `extra` | `ReactNode` | — | Header actions (buttons, etc.) |
+| `children` | `ReactNode` | — | Main content |
+| `footer` | `ReactNode` | — | Footer content |
+| `variant` | `'standard' \| 'split' \| 'full'` | `'standard'` | Layout mode |
+| `sidebar` | `ReactNode` | — | Sidebar content (split mode) |
+| `sidebarPosition` | `'left' \| 'right'` | `'right'` | Sidebar placement |
+| `sidebarWidth` | `string` | `'w-80'` | Sidebar Tailwind width class |
+
+### OrganizationSelector
+
+Two-step modal for switching organizations and branches:
+
+1. **Step 1**: Select organization (shows description + branch count)
+2. **Step 2**: Select branch (searchable, shows location)
 
 ```tsx
-import { useIsMobile } from '@omnifyjp/ui/hooks/use-mobile';
+import { OrganizationSelector } from '@omnifyjp/ui';
+
+<OrganizationSelector variant="header" />  // in header
+<OrganizationSelector variant="sidebar" /> // in sidebar
 ```
 
-### Import theme CSS
+### ServiceMenu
 
-```css
-@import '@omnifyjp/ui/styles';
+Searchable dropdown grid listing all available services/apps:
+
+```tsx
+const config: ShellConfig = {
+  services: [
+    {
+      category: 'HR',
+      items: [
+        { icon: Users, label: 'Attendance', url: '/attendance', color: 'bg-blue-600' },
+        { icon: Calendar, label: 'Leave', url: '/leave', color: 'bg-green-600' },
+      ],
+    },
+  ],
+};
 ```
 
 ---
 
-## Components
-
-### Shadcn UI Primitives (53)
+## Configuration: `ShellConfig`
+
+```typescript
+interface ShellConfig {
+  app: {
+    name: string;                    // App display name
+    key: string;                     // App identifier
+    logo: {
+      icon: LucideIcon;             // Logo icon
+      text: string;                  // Logo text
+      color?: string;                // Icon color class
+    };
+  };
+
+  sidebar: {
+    menuItems: SidebarMenuItem[];    // Navigation items
+    contextMenu?: {                  // Context switcher (e.g., project selector)
+      paramName: string;             // URL param name
+      getItems: () => ContextItem[];
+      getHeader?: () => ReactNode;
+      getFooterItems?: () => ContextItem[];
+    };
+    recentItems?: {                  // Recent items section
+      title: string;
+      items: { label: string; path: string; badge?: string; color?: string }[];
+    };
+    footer?: ReactNode;              // Custom sidebar footer
+  };
+
+  services?: ServiceCategory[];      // Service menu grid
+
+  header?: {
+    searchPlaceholder?: string;
+    showSearch?: boolean;            // Default: true
+    actions?: ReactNode;             // Custom header buttons
+    notifications?: {
+      count: number;
+      content: ReactNode;
+    };
+    user?: {
+      name: string;
+      email?: string;
+      avatar?: string;
+      onLogout?: () => void;
+    };
+  };
+
+  organization?: {
+    organizations: Organization[];
+    branches: Branch[];
+    onOrganizationChange?: (org: Organization) => void;
+    onBranchChange?: (branch: Branch) => void;
+  };
+}
+```
 
-All Shadcn primitives are included, fully accessible via Radix UI, with dark mode support.
+### SidebarMenuItem
 
-| Category | Components |
-|----------|-----------|
-| **Layout** | `aspect-ratio`, `card`, `resizable`, `scroll-area`, `separator`, `skeleton` |
-| **Navigation** | `breadcrumb`, `menubar`, `navigation-menu`, `pagination`, `tabs` |
-| **Data Display** | `avatar`, `badge`, `calendar`, `carousel`, `chart`, `hover-card`, `progress`, `table`, `tooltip` |
-| **Data Entry** | `button`, `checkbox`, `color-picker`, `combobox`, `date-picker`, `file-upload`, `form`, `input`, `input-otp`, `label`, `radio-group`, `rating`, `select`, `slider`, `switch`, `tag-input`, `textarea`, `time-picker`, `toggle`, `toggle-group` |
-| **Feedback** | `alert`, `alert-dialog`, `sonner` (toast) |
-| **Overlay** | `command`, `context-menu`, `dialog`, `drawer`, `dropdown-menu`, `popover`, `sheet` |
-| **Composition** | `accordion`, `collapsible`, `sidebar` |
+```typescript
+interface SidebarMenuItem {
+  icon: LucideIcon;
+  label: string;
+  path?: string;                     // Omit for collapsible groups
+  badge?: number;                    // Notification count
+  children?: SidebarMenuItem[];      // Nested items
+}
+```
 
-### Domain Components (14)
+---
 
-Shared business-logic components, locale-agnostic (accept `labels` prop with English defaults).
+## Context Providers
 
-#### Calendar
+### ThemeProvider
 
-| Component | Description |
-|-----------|-------------|
-| `CalendarMini` | Compact month calendar with event dots |
-| `CalendarEventChip` | Colored event bar for calendar grids |
-| `CalendarEventSheet` | Side panel for event details |
-| `CalendarToolbar` | Date navigation with view switcher (month/week/day) |
-| `CalendarCategoryBadge` | Colored category label |
+Dark mode management with system preference detection:
 
-#### Workflow
+```tsx
+import { useTheme } from '@omnifyjp/ui';
+
+function ThemeToggle() {
+  const { theme, setTheme } = useTheme();
+  // theme: 'light' | 'dark' | 'system'
+
+  return (
+    <select value={theme} onChange={(e) => setTheme(e.target.value)}>
+      <option value="light">Light</option>
+      <option value="dark">Dark</option>
+      <option value="system">System</option>
+    </select>
+  );
+}
+```
 
-| Component | Description |
-|-----------|-------------|
-| `WorkflowStepper` | Multi-step progress indicator |
-| `WorkflowDiagram` | Visual flow diagram with stages |
-| `WorkflowStatusBadge` | Status indicator (active/draft/archived) |
-| `WorkflowCategoryBadge` | Category badge for workflows |
-| `StageTypeBadge` | Stage type indicator (approval/action/notification) |
+Persists selection to `localStorage.omnify_theme`.
 
-#### RBAC
+### OrganizationProvider
 
-| Component | Description |
-|-----------|-------------|
-| `PermissionGrid` | Module x Action permission matrix with checkboxes |
-| `ScopeTree` | Hierarchical scope selector with inheritance |
-| `ScopeTypeBadge` | Scope level indicator (global/org/branch/team) |
+Multi-tenant organization/branch management:
 
-#### Forms
+```tsx
+import { useOrganization } from '@omnifyjp/ui';
+
+function OrgInfo() {
+  const {
+    selectedOrganization,   // Organization | null
+    selectedBranch,         // Branch | null
+    setSelectedOrganization,
+    setSelectedBranch,
+    getBranchesByOrg,       // (orgId: string) => Branch[]
+    isSetupComplete,        // true when both selected
+  } = useOrganization();
+
+  return <p>{selectedOrganization?.name} — {selectedBranch?.name}</p>;
+}
+```
 
-| Component | Description |
-|-----------|-------------|
-| `SlugInput` | URL-friendly slug input with auto-generation |
+Persists selections to `localStorage.selectedOrganizationId` and `localStorage.selectedBranchId`.
 
 ---
 
-## Theme & Styling
-
-### CSS Design Tokens
+## i18n (Internationalization)
 
-The package ships a `theme.css` with a complete token system. Import it in your app:
+### Supported Languages
 
-```css
-/* In your global CSS */
-@import '@omnifyjp/ui/styles';
-```
+| Code | Language |
+|------|----------|
+| `vi` | Tieng Viet (default, fallback) |
+| `en` | English |
+| `ja` | Japanese |
 
-### Density Tokens
+### Shell Namespace
 
-All spacing and sizing is controlled via CSS custom properties:
+The shell comes pre-loaded with translations for common UI strings: sidebar labels, header actions, status/priority names, settings pages, login forms, organization selection, date picker, etc.
 
-| Token | Value | Tailwind Class | Use For |
-|-------|-------|----------------|---------|
-| `--density-page` | 16px | `p-page` | Page padding |
-| `--density-section` | 16px | `gap-section` | Section gaps |
-| `--density-element` | 32px | `h-element` | Button/Input height |
-| `--density-element-sm` | 28px | `h-element-sm` | Small inputs |
-| `--density-element-lg` | 36px | `h-element-lg` | Large buttons |
-| `--density-card` | 16px | `px-card`, `pt-card` | Card padding |
-| `--density-dialog` | 20px | `p-dialog` | Dialog padding |
-| `--header-height` | 48px | `h-header` | App header height |
-| `--density-page-title` | 20px | `text-page-title` | Page title font size |
+### Adding Service Translations
 
-### Dark Mode
+```tsx
+import { initOmnifyI18n } from '@omnifyjp/ui';
+
+// Add your service namespace
+initOmnifyI18n({
+  namespaces: {
+    myapp: {
+      en: { dashboard: { title: 'Dashboard' } },
+      vi: { dashboard: { title: 'Bang dieu khien' } },
+      ja: { dashboard: { title: 'dasshubodo' } },
+    },
+  },
+});
+
+// Use in components
+import { useTranslation } from 'react-i18next';
+
+function Dashboard() {
+  const { t } = useTranslation(['myapp', 'shell']);
+  return <h1>{t('dashboard.title')}</h1>;
+  // Falls back to 'shell' namespace for common keys
+}
+```
 
-All components support dark mode via the `dark` class on `<html>`. Color tokens auto-switch:
+### Changing Language
 
 ```tsx
-// Semantic tokens (auto dark mode)
-<div className="bg-background text-foreground border-border">
-  <p className="text-muted-foreground">Secondary text</p>
-</div>
+import { changeLanguage } from '@omnifyjp/ui';
 
-// Accent colors with dark variants
-<Badge className="bg-red-50 dark:bg-red-500/15 text-red-600 dark:text-red-400">
-  Urgent
-</Badge>
+await changeLanguage('en'); // Persists to localStorage
 ```
 
 ---
 
-## Utility: `cn()`
+## Hooks
 
-Class merging utility combining `clsx` + `tailwind-merge`:
+### useDateFormat
 
-```tsx
-import { cn } from '@omnifyjp/ui/lib/utils';
+Locale-aware date formatting with timezone support:
 
-<div className={cn('p-4 bg-card', isActive && 'ring-2 ring-primary', className)} />
+```tsx
+import { useDateFormat } from '@omnifyjp/ui';
+
+function EventDate({ date }: { date: Date }) {
+  const {
+    formatDate,           // '01/15/2026' (locale-dependent)
+    formatDateTime,       // '01/15/2026 14:30'
+    formatRelativeTime,   // '5 minutes ago'
+    formatShortDate,      // '01/15'
+    formatMonthYear,      // 'January 2026'
+    formatDayOfWeek,      // 'Mon'
+    formatDateLong,       // 'January 15, 2026'
+    timezone,             // 'Asia/Ho_Chi_Minh'
+    setTimezone,          // Change timezone
+    dateFnsLocale,        // date-fns Locale object
+  } = useDateFormat();
+
+  return <time>{formatDateTime(date)}</time>;
+}
 ```
 
----
+Supported timezones: `Asia/Ho_Chi_Minh`, `Asia/Tokyo`, `America/New_York`, `America/Los_Angeles`, `Europe/London`, `UTC`.
 
-## Tree Shaking
+---
 
-The package is fully tree-shakeable:
+## Package Exports
 
-- **Per-component entry points**: `@omnifyjp/ui/components/button` only loads `button.js`
-- **`sideEffects: false`**: Bundlers can safely eliminate unused code
-- **ESM only**: Modern `import`/`export` for optimal bundling
+```
+@omnifyjp/ui                             → all exports (barrel)
+@omnifyjp/ui/components/AppShell      → AppShell
+@omnifyjp/ui/components/Sidebar       → Sidebar
+@omnifyjp/ui/components/Header        → Header
+@omnifyjp/ui/components/PageContainer → PageContainer, Standard/Split/FullWidth variants
+@omnifyjp/ui/components/ServiceMenu   → ServiceMenu
+@omnifyjp/ui/components/OrganizationSelector → OrganizationSelector
+@omnifyjp/ui/contexts/ThemeContext    → ThemeProvider, useTheme
+@omnifyjp/ui/contexts/OrganizationContext → OrganizationProvider, useOrganization
+@omnifyjp/ui/hooks/useDateFormat      → useDateFormat, timezoneLabels
+@omnifyjp/ui/i18n                     → i18n, initOmnifyI18n, changeLanguage
+@omnifyjp/ui/types                    → ShellConfig, Organization, Branch, etc.
+```
 
 ---
 
-## Package Exports
+## TypeScript
 
-```
-@omnifyjp/ui                    → all components (barrel)
-@omnifyjp/ui/components/button  → Button, buttonVariants
-@omnifyjp/ui/components/card    → Card, CardHeader, CardContent, ...
-@omnifyjp/ui/components/*       → any component by name
-@omnifyjp/ui/lib/utils          → cn()
-@omnifyjp/ui/hooks/use-mobile   → useIsMobile()
-@omnifyjp/ui/styles             → theme.css
+Full type definitions are included. Key types:
+
+```typescript
+import type {
+  ShellConfig,
+  SidebarMenuItem,
+  ServiceCategory,
+  ServiceItem,
+  Organization,
+  Branch,
+  PageContainerProps,
+} from '@omnifyjp/ui';
 ```
 
 ---
 
-## Tech Stack
-
-- **React** 18+ with new JSX transform
-- **TypeScript** (strict mode, full type definitions)
-- **Tailwind CSS v4** with design tokens
-- **Radix UI** for accessible primitives
-- **class-variance-authority** for component variants
-- **cmdk** for command palette
-- **embla-carousel-react** for carousel
-- **react-day-picker** for calendar/date-picker
-- **react-resizable-panels** for resizable layouts
-- **vaul** for drawer component
-- **sonner** for toast notifications
-- **lucide-react** for icons
+## Dependencies
+
+This package depends on:
+
+| Package | Purpose |
+|---------|---------|
+|  `@omnifyjp/ui-components` | UI component primitives (auto-installed) |
+| `i18next` | Internationalization core |
+| `react-i18next` | React i18n bindings |
+| `date-fns` | Date formatting |
+| `lucide-react` | Icons |
+| `sonner` | Toast notifications |
+
+Peer dependencies (you provide):
+
+| Package | Version |
+|---------|---------|
+| `react` | >=18 |
+| `react-dom` | >=18 |
+| `react-router` | >=7 |
 
 ---
 
@@ -220,7 +466,7 @@ The package is fully tree-shakeable:
 
 | Package | Description |
 |---------|-------------|
-| [`@omnifyjp/shell`](https://www.npmjs.com/package/@omnifyjp/shell) | App shell framework (sidebar, header, i18n, theming) — depends on this package |
+| [`@omnifyjp/ui-components`](https://www.npmjs.com/package/@omnifyjp/ui-components) | 53 Shadcn primitives + 14 domain components |
 | [`@omnifyjp/editor`](https://www.npmjs.com/package/@omnifyjp/editor) | Rich text editors (Tiptap + BlockNote) |
 
 ---