@nestledjs/data-browser 0.1.0

package/.babelrc

@@ -0,0 +1,12 @@
+{
+  "presets": [
+    [
+      "@nx/react/babel",
+      {
+        "runtime": "automatic",
+        "useBuiltIns": "usage"
+      }
+    ]
+  ],
+  "plugins": []
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nestled Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,320 @@
+# @nestledjs/data-browser
+
+Universal admin data browser for Nestled framework projects with full CRUD operations, advanced filtering, and customizable views.
+
+## Features
+
+- 🔍 **Auto-generated CRUD Interface** - Automatically generates admin UI for all Prisma models
+- 📊 **Advanced Data Table** - Sorting, filtering, pagination, column selection
+- 🔎 **Smart Search** - Multi-field text search with debouncing
+- 📝 **Dynamic Forms** - Auto-generated create/edit forms from model schema
+- 🎨 **Dark Mode Support** - Full dark mode theming
+- 💾 **Persistent Preferences** - Saves column visibility, sort order, and search preferences per model
+- 🔐 **Type-Safe** - Full TypeScript support with GraphQL code generation
+- 📱 **Responsive** - Mobile-friendly with fullscreen mode
+
+## Installation
+
+```bash
+npm install @nestledjs/data-browser
+# or
+pnpm add @nestledjs/data-browser
+# or
+yarn add @nestledjs/data-browser
+```
+
+## Prerequisites
+
+This package requires a Nestled framework project with:
+
+- **Apollo Client v4+** for GraphQL operations
+- **React Router v7+** for routing
+- **@nestledjs/forms** for form generation
+- **@nestledjs/helpers** for utility functions
+- **Prisma** for database models
+- **Generated GraphQL SDK** with admin CRUD operations
+
+### Peer Dependencies
+
+```json
+{
+  "@apollo/client": "^4.0.0",
+  "@nestledjs/forms": "^0.5.0",
+  "@nestledjs/helpers": "^0.1.0",
+  "react": "^19.0.0",
+  "react-router": "^7.0.0"
+}
+```
+
+### Required Project Components
+
+Your Nestled project must also export:
+
+1. **Web UI Components** from `@your-project/web-ui`:
+   - `WebUiDataTable`
+   - `WebUiErrorBoundary`
+
+2. **Form Theme** from `@your-project/shared/styles`:
+   - `formTheme`
+
+3. **GraphQL SDK** from `@your-project/shared/sdk`:
+   - `DATABASE_MODELS` (auto-generated model metadata)
+   - GraphQL documents with `__Admin*Document` naming
+
+## Quick Start
+
+### Step 1: Install
+
+```bash
+pnpm add @nestledjs/data-browser
+```
+
+### Step 2: Update Import Paths
+
+Since this package imports from your project's namespaced packages, find and replace in the source:
+
+```
+@nestled-template → @your-project-name
+```
+
+This affects 3 files in `libs/admin-data/src/lib/pages/`.
+
+### Step 3: Create Route Wrapper
+
+Create `apps/web/app/routes/admin/data/_layout.tsx`:
+
+```typescript
+import * as Sdk from '@your-project/shared/sdk'
+import { DATABASE_MODELS } from '@your-project/shared/sdk'
+import { AdminDataProvider, AdminDataLayout } from '@nestledjs/data-browser'
+
+export default function DataLayoutRoute() {
+  return (
+    <AdminDataProvider
+      sdk={Sdk}
+      databaseModels={DATABASE_MODELS}
+      basePath="/admin/data"
+    >
+      <AdminDataLayout />
+    </AdminDataProvider>
+  )
+}
+```
+
+### Step 4: Create Page Routes
+
+Create these minimal route files:
+
+**`apps/web/app/routes/admin/data/index.tsx`**:
+```typescript
+import { AdminDataIndexPage } from '@nestledjs/data-browser'
+export default AdminDataIndexPage
+```
+
+**`apps/web/app/routes/admin/data/$dataTypePlural.tsx`**:
+```typescript
+import { AdminDataListPage, AdminDataErrorBoundary } from '@nestledjs/data-browser'
+
+export default function DataListRoute() {
+  return <AdminDataListPage />
+}
+
+export function ErrorBoundary({ error }: Readonly<{ error: Error }>) {
+  return <AdminDataErrorBoundary error={error} />
+}
+```
+
+**`apps/web/app/routes/admin/data/$dataType.create.tsx`**:
+```typescript
+import { AdminDataCreatePage, AdminDataCreateErrorBoundary } from '@nestledjs/data-browser'
+
+export default function CreateDataRoute() {
+  return <AdminDataCreatePage />
+}
+
+export function ErrorBoundary({ error }: Readonly<{ error: Error }>) {
+  return <AdminDataCreateErrorBoundary error={error} />
+}
+```
+
+**`apps/web/app/routes/admin/data/$dataType.$id.tsx`**:
+```typescript
+import { AdminDataEditPage, AdminDataEditErrorBoundary } from '@nestledjs/data-browser'
+
+export default function EditDataRoute() {
+  return <AdminDataEditPage />
+}
+
+export function ErrorBoundary({ error }: Readonly<{ error: Error }>) {
+  return <AdminDataEditErrorBoundary error={error} />
+}
+```
+
+### Step 5: Register Routes
+
+In `apps/web/app/routes.tsx`:
+
+```typescript
+import { index, route, type RouteConfig } from '@react-router/dev/routes'
+
+export default [
+  route('admin', './routes/admin/_layout.tsx', [
+    route('data', './routes/admin/data/_layout.tsx', [
+      index('./routes/admin/data/index.tsx'),
+      route(':dataTypePlural', './routes/admin/data/$dataTypePlural.tsx'),
+      route(':dataType/create', './routes/admin/data/$dataType.create.tsx'),
+      route(':dataType/:id', './routes/admin/data/$dataType.$id.tsx'),
+    ]),
+  ]),
+] satisfies RouteConfig
+```
+
+### Step 6: Access the Data Browser
+
+Navigate to `/admin/data` in your application!
+
+## Usage
+
+### Landing Page (`/admin/data`)
+
+Shows all available database models with a searchable list.
+
+### List View (`/admin/data/users`)
+
+- **Search**: Multi-field text search across string fields
+- **Filter**: Advanced filters for dates, numbers, enums, and relations
+- **Sort**: Click column headers to sort
+- **Columns**: Show/hide columns via column selector
+- **Pagination**: Navigate through large datasets
+
+### Create (`/admin/data/user/create`)
+
+Auto-generated form based on your Prisma model schema with:
+- Type-aware inputs (text, number, date, enum, relation dropdowns)
+- Validation based on model requirements
+- Real-time error handling
+
+### Edit (`/admin/data/user/123`)
+
+Pre-filled form with current values, plus delete functionality.
+
+## API
+
+### AdminDataProvider
+
+The context provider that makes SDK and models available to all components.
+
+```typescript
+<AdminDataProvider
+  sdk={Sdk}                    // Your GraphQL SDK namespace
+  databaseModels={DATABASE_MODELS}  // Array of model metadata
+  basePath="/admin/data"       // Optional: Custom route prefix
+>
+  {children}
+</AdminDataProvider>
+```
+
+### useAdminDataContext
+
+Hook to access the admin data context:
+
+```typescript
+const { sdk, databaseModels, basePath } = useAdminDataContext()
+```
+
+## GraphQL Schema Requirements
+
+The data browser expects these operations for each model:
+
+```graphql
+# Queries
+query __AdminUser($input: AdminUserInput!)
+query __AdminUsers($input: AdminUsersInput!)
+
+# Mutations
+mutation __AdminCreateUser($input: CreateUserInput!)
+mutation __AdminUpdateUser($input: UpdateUserInput!)
+mutation __AdminDeleteUser($input: DeleteUserInput!)
+```
+
+These are auto-generated by the Nestled CRUD generator when you run:
+
+```bash
+pnpm db-update
+```
+
+## Preferences Storage
+
+User preferences are saved to `localStorage` with key `mi-admin-config`:
+
+- Column visibility per model
+- Sort preference per model
+- Search fields per model
+
+**Export/Import**: Use the header buttons to backup and restore preferences across devices.
+
+## Customization
+
+### Custom Base Path
+
+```typescript
+<AdminDataProvider basePath="/admin/database">
+```
+
+Changes all routes to use `/admin/database/*` instead of `/admin/data/*`.
+
+### Custom Styling
+
+The data browser uses Tailwind CSS classes. Customize via your project's Tailwind config and the `formTheme` export.
+
+## Troubleshooting
+
+### "Missing GraphQL documents for model X"
+
+**Solution**: Run GraphQL code generation:
+```bash
+pnpm sdk
+```
+
+### "useAdminDataContext must be used within AdminDataProvider"
+
+**Solution**: Ensure all data browser components are children of `<AdminDataProvider>` in `_layout.tsx`.
+
+### Import errors for WebUiDataTable or formTheme
+
+**Solution**: Ensure your project exports these from:
+- `@your-project/web-ui`
+- `@your-project/shared/styles`
+
+### DATABASE_MODELS is undefined
+
+**Solution**: Run the model generator:
+```bash
+pnpm generate:models
+```
+
+This creates the `DATABASE_MODELS` export from your Prisma schema.
+
+## Development
+
+### Build
+
+```bash
+nx build admin-data
+```
+
+Output: `dist/libs/admin-data/`
+
+### Publish
+
+```bash
+nx publish admin-data
+```
+
+## License
+
+MIT
+
+## Support
+
+For issues and questions, please visit the [Nestled framework repository](https://github.com/nestledjs/nestled).

package/eslint.config.mjs

@@ -0,0 +1,12 @@
+import nx from '@nx/eslint-plugin'
+import baseConfig from '../../eslint.config.mjs'
+
+export default [
+  ...baseConfig,
+  ...nx.configs['flat/react'],
+  {
+    files: ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx'],
+    // Override or add rules here
+    rules: {},
+  },
+]

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@nestledjs/data-browser",
+  "version": "0.1.0",
+  "description": "Universal admin data browser for Nestled framework projects with full CRUD operations",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "keywords": [
+    "nestled",
+    "admin",
+    "data-browser",
+    "crud",
+    "react",
+    "graphql",
+    "apollo"
+  ],
+  "author": "Nestled Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nestledjs/nestled_template.git",
+    "directory": "libs/admin-data"
+  },
+  "peerDependencies": {
+    "@apollo/client": "^4.0.0",
+    "@heroicons/react": "^2.0.0",
+    "@nestledjs/forms": "^0.5.0",
+    "@nestledjs/helpers": "^0.1.0",
+    "@nestledjs/shared-components": "^0.1.0",
+    "react": "^19.0.0",
+    "react-router": "^7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@heroicons/react": {
+      "optional": false
+    }
+  },
+  "dependencies": {},
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "module": "./src/index.js",
+  "type": "module"
+}

package/project.json

@@ -0,0 +1,39 @@
+{
+  "name": "admin-data",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "libs/admin-data/src",
+  "projectType": "library",
+  "tags": ["publishable"],
+  "targets": {
+    "build": {
+      "executor": "@nx/js:tsc",
+      "outputs": ["{options.outputPath}"],
+      "options": {
+        "outputPath": "dist/libs/admin-data",
+        "main": "libs/admin-data/src/index.ts",
+        "tsConfig": "libs/admin-data/tsconfig.lib.json",
+        "assets": [
+          "libs/admin-data/*.md",
+          {
+            "input": "libs/admin-data",
+            "glob": "package.json",
+            "output": "."
+          }
+        ]
+      }
+    },
+    "publish": {
+      "executor": "nx:run-commands",
+      "dependsOn": ["build"],
+      "options": {
+        "command": "npm publish dist/libs/admin-data --access public"
+      }
+    },
+    "version": {
+      "executor": "@jscutlery/semver:version",
+      "options": {
+        "preset": "conventional"
+      }
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+// Context
+export * from './lib/context/AdminDataContext'
+
+// Main components
+export * from './lib/pages/AdminDataCreatePage'
+export * from './lib/pages/AdminDataEditPage'
+export * from './lib/pages/AdminDataListPage'
+export * from './lib/pages/AdminDataIndexPage'
+
+// Layouts
+export * from './lib/layouts/AdminDataLayout'
+
+// Types
+export * from './lib/types'
+
+// Hooks
+export * from './lib/hooks/useAdminList'
+export * from './lib/hooks/useClickOutside'
+export * from './lib/hooks/useDebounce'
+export * from './lib/hooks/useRelationData'
+
+// Components
+export * from './lib/components'
+
+// Utilities
+export * from './lib/utils/graphql-utils'
+export * from './lib/utils/secure-storage'
+export * from './lib/utils/string-utils'

package/src/lib/admin-data.spec.tsx

@@ -0,0 +1,10 @@
+import { render } from '@testing-library/react'
+
+import AdminData from './admin-data'
+
+describe('AdminData', () => {
+  it('should render successfully', () => {
+    const { baseElement } = render(<AdminData />)
+    expect(baseElement).toBeTruthy()
+  })
+})

package/src/lib/admin-data.tsx

@@ -0,0 +1,9 @@
+export function AdminData() {
+  return (
+    <div>
+      <h1>Welcome to AdminData!</h1>
+    </div>
+  )
+}
+
+export default AdminData

package/src/lib/components/filters/DateRangeFilter.tsx

@@ -0,0 +1,88 @@
+import { formatFieldName } from '../../utils/string-utils'
+
+interface DateRangeFilterProps {
+  fieldName: string
+  currentValue: any
+  onChange: (value: any) => void
+}
+
+// Component for date range filtering
+export function DateRangeFilter({ 
+  fieldName, 
+  currentValue, 
+  onChange 
+}: DateRangeFilterProps) {
+  // Parse current value if it's a range object
+  const fromDate = currentValue?.gte ? new Date(currentValue.gte).toISOString().split('T')[0] : ''
+  const toDate = currentValue?.lte ? new Date(currentValue.lte).toISOString().split('T')[0] : ''
+  
+  const handleFromChange = (date: string) => {
+    const newValue = { ...currentValue }
+    if (date) {
+      newValue.gte = new Date(date).toISOString()
+    } else {
+      delete newValue.gte
+    }
+    
+    // If no from or to date, clear the filter entirely
+    if (!newValue.gte && !newValue.lte) {
+      onChange(undefined)
+    } else {
+      onChange(newValue)
+    }
+  }
+  
+  const handleToChange = (date: string) => {
+    const newValue = { ...currentValue }
+    if (date) {
+      // Set to end of day for "to" date
+      const endOfDay = new Date(date)
+      endOfDay.setHours(23, 59, 59, 999)
+      newValue.lte = endOfDay.toISOString()
+    } else {
+      delete newValue.lte
+    }
+    
+    // If no from or to date, clear the filter entirely
+    if (!newValue.gte && !newValue.lte) {
+      onChange(undefined)
+    } else {
+      onChange(newValue)
+    }
+  }
+  
+  return (
+    <div className="space-y-1">
+      <label className="block text-sm font-medium text-gray-700">
+        {formatFieldName(fieldName)}
+      </label>
+      <div className="grid grid-cols-2 gap-2">
+        <div>
+          <label className="block text-xs text-gray-500 mb-1">From</label>
+          <input
+            type="date"
+            value={fromDate}
+            onChange={(e) => handleFromChange(e.target.value)}
+            className="w-full px-2 py-1 text-sm border border-gray-300 rounded-md focus:outline-none focus:ring-1 focus:ring-green-web focus:border-green-web"
+          />
+        </div>
+        <div>
+          <label className="block text-xs text-gray-500 mb-1">To</label>
+          <input
+            type="date"
+            value={toDate}
+            onChange={(e) => handleToChange(e.target.value)}
+            className="w-full px-2 py-1 text-sm border border-gray-300 rounded-md focus:outline-none focus:ring-1 focus:ring-green-web focus:border-green-web"
+          />
+        </div>
+      </div>
+      {(fromDate || toDate) && (
+        <div className="text-xs text-gray-500">
+          {fromDate && toDate && `${fromDate} to ${toDate}`}
+          {fromDate && !toDate && `From ${fromDate}`}
+          {!fromDate && toDate && `Until ${toDate}`}
+        </div>
+      )}
+    </div>
+  )
+}