obs-admin-dashboard 1.0.0

package/README.md

@@ -0,0 +1,146 @@
+# obs-admin-dashboard
+
+A ready-to-use admin dashboard base package for React apps. It provides the core infrastructure — API layer, layouts, sidebar navigation, shared components, and a `DashboardProvider` — that you can drop into any React application as a starting point.
+
+## Installation
+
+```bash
+npm install obs-admin-dashboard
+```
+
+> `react` and `react-dom` are peer dependencies — make sure they're installed in your app.
+
+## Quick Start
+
+The package ships with two usage styles:
+
+### 1. Use the `DashboardProvider` (all-in-one)
+
+Wrap your app with `DashboardProvider` to get a configured QueryClient, theme, tooltips, and toasts:
+
+```tsx
+import { DashboardProvider, AppLayout } from "obs-admin-dashboard"
+import "obs-admin-dashboard/styles.css"
+
+function App() {
+  return (
+    <DashboardProvider
+      config={{
+        apiUrl: "https://your-api.example.com",
+        theme: "system",
+        toastPosition: "top-center",
+      }}
+    >
+      <AppLayout navItems={myNavItems} brandName="My Company" logoUrl="/logo.png">
+        {/* your routed content */}
+      </AppLayout>
+    </DashboardProvider>
+  )
+}
+```
+
+### 2. Use individual exports
+
+Import only what you need for tree-shaking:
+
+```tsx
+import { DataTable, DataPagination, SearchBar, ConfirmDialog } from "obs-admin-dashboard"
+import { useGetItems } from "./my-feature/hooks" // your feature logic
+```
+
+## Exports
+
+### Provider
+
+| Export | Description |
+|--------|-------------|
+| `DashboardProvider` | Sets up QueryClient, ThemeProvider, TooltipProvider, and Toaster |
+| `DashboardConfig` | Config type (`apiUrl`, `theme`, `toastPosition`, `navItems`) |
+
+### API Layer
+
+| Export | Description |
+|--------|-------------|
+| `apiClient` | Axios instance with Bearer token + refresh queue |
+| `authClient` | Axios instance for unauthenticated requests (login/register) |
+| `CrudService<T>` | Base class with typed `getAll`, `getById`, `create`, `update`, `delete` |
+| `BASE_URL` | The configured API base URL |
+| `ApiResponse<T>`, `PaginatedApiResponse<T>`, `PaginatedMeta` | API response types |
+
+### Layout
+
+| Export | Description |
+|--------|-------------|
+| `AppLayout` | Authenticated shell with sidebar + outlet (`navItems`, `brandName`, `logoUrl`, `sidebarFooter`, `redirectPath`) |
+| `AuthLayout` | Centered card layout for login/OTP/password flows |
+| `AppHeader` | Page header with title/total/action button or dropdown |
+| `AppSidebar` | Collapsible sidebar with search, nav, and user footer |
+
+### Sidebar
+
+| Export | Description |
+|--------|-------------|
+| `SidebarNav` | Navigation menu (`items` prop overrides defaults) |
+| `SidebarUserFooter` | User profile + logout footer |
+| `NavItem`, `NavChild` | Nav item types |
+
+### Shared Components
+
+| Export | Description |
+|--------|-------------|
+| `DataTable` | TanStack Table v8 wrapper |
+| `DataPagination` | Server-side pagination with page-size selector |
+| `SearchBar` | Debounced search input synced to URL params |
+| `ConfirmDialog` | Delete/confirm alert dialog |
+| `ErrorBoundary` | React error boundary |
+| `ThemeProvider`, `useTheme` | Theme context |
+
+### UI Components (shadcn/ui)
+
+Re-exported shadcn primitives: `Button`, `Input`, `Label`, `Dialog`, `AlertDialog`, `Card`, `Select`, `Table`, `Form`, `DropdownMenu`, `Sidebar` (+ `useSidebar`).
+
+### Utilities & Hooks
+
+- `cn` — `clsx` + `tailwind-merge` utility
+- `useIsMobile` — responsive breakpoint hook
+
+## Styles
+
+Import the package styles in your app's CSS entry (requires Tailwind v4 with the `@tailwindcss/vite` plugin):
+
+```css
+@import "obs-admin-dashboard/styles.css";
+```
+
+## API Configuration
+
+Set the API base URL via an environment variable:
+
+```
+VITE_API_URL=https://your-api.example.com
+```
+
+`apiClient` automatically attaches `Bearer` tokens from `localStorage.accessToken` and handles token refresh on `401`.
+
+## Feature Modules
+
+Business logic lives in `src/feature/[name]/` — each feature is self-contained with `types.ts`, `services/`, `hooks/`, `components/`, `page/`, and `routes/routes.tsx`. See `src/feature/CLAUDE.md` for the two supported patterns (dialog-based and page-based).
+
+## Commands
+
+```bash
+npm run dev          # Start dev server
+npm run build        # Type-check + Vite app build
+npm run build:lib    # Build ESM + UMD + type declarations for publishing
+npm run typecheck    # tsc --noEmit
+npm run lint         # ESLint
+npm run format       # Prettier
+npm pack             # Dry-run check of publishable files
+```
+
+## Publishing
+
+```bash
+npm run build:lib
+npm publish
+```