@owlmeans/web-panel 0.1.2 → 0.1.3

package/README.md

@@ -1,1195 +1,123 @@
 # @owlmeans/web-panel
 
-Web-based panel components and infrastructure for OwlMeans Common Libraries. This package extends the `@owlmeans/client-panel` functionality with React web components, Material-UI integration, and web-specific implementations for building comprehensive administrative interfaces and user panels.
+shadcn UI + Tailwind v4 implementation of the OwlMeans web panel layer.
+Wraps the headless `@owlmeans/client-panel` logic with shadcn primitives
+instead of Material UI.
 
-## Overview
+## When to use this package
 
-The `@owlmeans/web-panel` package serves as the web-specific implementation of the OwlMeans panel system, designed for fullstack applications with focus on security and modern web user interfaces. It provides:
+- New OwlMeans web apps where the consumer owns its shadcn primitives and
+  Tailwind v4 theme.
+- Drop-in replacement for the previous Material-UI based `@owlmeans/web-panel`
+  (which has been renamed to [`@owlmeans/mui-panel`](../mui-panel) for
+  backwards-compatibility consumers).
 
-- **Material-UI Integration**: Complete Material Design component system with theming
-- **Web Panel Components**: Comprehensive React components for building web admin panels
-- **Authentication Integration**: Built-in authentication components and flows
-- **Form Management**: Advanced form components with validation and error handling
-- **File Upload**: File and media upload components with progress tracking
-- **Layout System**: Flexible layout components for organizing panel content
-- **Theme Customization**: Material-UI theme integration with customizable styling
-- **Internationalization**: Built-in i18n support with browser language detection
+## Install
 
-This package follows the OwlMeans "quadra" pattern as the **web** implementation, complementing:
-- **@owlmeans/client-panel**: Common panel declarations and base functionality *(base package)*
-- **@owlmeans/native-panel**: React Native panel implementation
-- **@owlmeans/web-panel**: Web browser panel implementation *(this package)*
-
-## Installation
-
-```bash
-npm install @owlmeans/web-panel
-```
-
-### Peer Dependencies
-
-This package requires several peer dependencies for web development:
-
-```bash
-npm install react react-dom @mui/material @emotion/react @emotion/styled react-hook-form @hookform/resolvers ajv
-```
-
-## Dependencies
-
-This package builds upon the OwlMeans ecosystem and web technologies:
-- `@owlmeans/client-panel`: Base panel functionality and context
-- `@owlmeans/web-client`: Web client framework and rendering
-- `@owlmeans/client-auth`: Authentication components and services
-- `@owlmeans/client-flow`: Flow management integration
-- `@owlmeans/web-flow`: Web-specific flow implementations
-- Material-UI: React component library for Material Design
-- React Hook Form: Form management and validation
-
-## Key Concepts
-
-### Material-UI Integration
-Built on Material-UI (MUI) providing:
-- **Material Design**: Modern Material Design 3 component system
-- **Theme System**: Comprehensive theming with custom color schemes
-- **Responsive Design**: Mobile-first responsive components
-- **Accessibility**: Built-in accessibility support and ARIA compliance
-
-### Panel Architecture
-Structured panel system with:
-- **Panel Context**: Shared context for panel-wide settings and state
-- **Authentication Guards**: Built-in authentication and authorization
-- **Layout Management**: Flexible layout system for complex interfaces
-- **Navigation Integration**: Integration with React Router and client routing
-
-### Form Management
-Advanced form capabilities with:
-- **React Hook Form**: Performance-optimized form management
-- **AJV Validation**: Schema-based validation using JSON Schema
-- **Error Handling**: Comprehensive error display and user feedback
-- **File Uploads**: Integrated file and media upload components
-
-## API Reference
-
-### Main Functions
-
-#### `render<C, T>(context, theme?, opts?): void`
-
-Main rendering function for web panel applications.
-
-```typescript
-function render<C extends ClientConfig, T extends ClientContext<C>>(
-  context: T,
-  theme?: Theme,
-  opts?: RenderOptions
-): void
-```
-
-**Parameters:**
-- `context`: Client context with configuration and services
-- `theme`: Optional Material-UI theme customization
-- `opts`: Optional rendering options
-
-**Usage:**
-```typescript
-import { render } from '@owlmeans/web-panel'
-import { makeWebContext } from '@owlmeans/web-client'
-import { createTheme } from '@mui/material/styles'
-
-const context = makeWebContext(config)
-const theme = createTheme({
-  palette: {
-    primary: { main: '#1976d2' },
-    secondary: { main: '#dc004e' }
-  }
-})
-
-render(context, theme, { rootId: 'app' })
-```
-
-### Core Components
-
-#### `PanelApp`
-
-Main panel application wrapper with Material-UI theming and context integration.
-
-```typescript
-interface PanelAppProps {
-  context: AppContext<any>           // Application context
-  provide?: ProvideFunction          // Custom provider function
-  children?: React.ReactNode         // Panel content
-  theme?: Theme                      // Material-UI theme
-}
-
-const PanelApp: FC<PanelAppProps> = (props) => { /* ... */ }
-```
-
-**Features:**
-- Material-UI theme provider integration
-- CSS baseline normalization
-- I18n context with browser language detection
-- OwlMeans client app wrapper
-
-**Usage:**
-```typescript
-import { PanelApp } from '@owlmeans/web-panel'
-
-<PanelApp context={context} theme={customTheme}>
-  <AdminInterface />
-</PanelApp>
-```
-
-### Layout Components
-
-#### Panel Layout System
-
-Flexible layout components for organizing panel content.
-
-```typescript
-import { 
-  PanelLayout, 
-  PanelHeader, 
-  PanelSidebar, 
-  PanelContent,
-  PanelFooter 
-} from '@owlmeans/web-panel'
-
-<PanelLayout>
-  <PanelHeader title="Administration Panel">
-    <UserMenu />
-  </PanelHeader>
-  
-  <PanelSidebar>
-    <NavigationMenu />
-  </PanelSidebar>
-  
-  <PanelContent>
-    <MainContent />
-  </PanelContent>
-  
-  <PanelFooter>
-    <StatusBar />
-  </PanelFooter>
-</PanelLayout>
+```sh
+bun add @owlmeans/web-panel
 ```
 
-### Form Components
+Peer requirements (the consuming app provides these): `react`, `react-dom`,
+`react-hook-form`, `ajv`, `tailwindcss@^4`, `lucide-react`, `clsx`,
+`tailwind-merge`, `class-variance-authority`, plus the radix primitives
+listed in `peerDependencies`.
 
-#### Advanced Form System
+## Consumer setup — the `@` contract
 
-React Hook Form integration with Material-UI components and AJV validation.
-
-```typescript
-import { 
-  PanelForm, 
-  FormField, 
-  FormButton, 
-  FormSelect,
-  FormCheckbox,
-  FormValidation 
-} from '@owlmeans/web-panel'
+This package imports its shadcn primitives as `@/components/ui/<name>` and
+its utility as `@/lib/utils`. Build emits these specifiers verbatim
+(TypeScript `moduleResolution: Bundler`). The consumer's bundler must
+resolve `@/*` to its own shadcn primitive copy.
 
-interface UserFormData {
-  name: string
-  email: string
-  role: string
-  active: boolean
-}
+### 1. Add the package's primitives to your app
 
-const userSchema = {
-  type: 'object',
-  properties: {
-    name: { type: 'string', minLength: 2 },
-    email: { type: 'string', format: 'email' },
-    role: { type: 'string', enum: ['admin', 'user'] },
-    active: { type: 'boolean' }
-  },
-  required: ['name', 'email', 'role']
-}
+Generate the matching primitives in your app once. You can either copy them
+from this package's `src/@/components/ui/` or use the shadcn CLI:
 
-<PanelForm<UserFormData>
-  schema={userSchema}
-  onSubmit={handleSubmit}
-  defaultValues={defaultValues}
->
-  <FormField
-    name="name"
-    label="Full Name"
-    type="text"
-    required
-  />
-  
-  <FormField
-    name="email"
-    label="Email Address"
-    type="email"
-    required
-  />
-  
-  <FormSelect
-    name="role"
-    label="User Role"
-    options={[
-      { value: 'admin', label: 'Administrator' },
-      { value: 'user', label: 'Regular User' }
-    ]}
-    required
-  />
-  
-  <FormCheckbox
-    name="active"
-    label="Active User"
-  />
-  
-  <FormButton type="submit" variant="contained">
-    Save User
-  </FormButton>
-</PanelForm>
+```sh
+npx shadcn add button card input label progress alert separator
 ```
 
-### Button Components
+This package was authored against the shadcn `new-york` style with
+`baseColor: neutral`. See `components.json` for the exact config.
 
-Enhanced button components with loading states and Material-UI integration.
+### 2. Add Tailwind v4 theme tokens
 
-```typescript
-import { PanelButton, IconButton, FloatingActionButton } from '@owlmeans/web-panel'
+The components rely on the following CSS variables (defined inside
+`@theme` in your app's globals.css):
 
-<PanelButton
-  variant="contained"
-  color="primary"
-  startIcon={<SaveIcon />}
-  loading={isSaving}
-  onClick={handleSave}
->
-  Save Changes
-</PanelButton>
+- `--color-background`, `--color-foreground`
+- `--color-card`, `--color-card-foreground`
+- `--color-primary`, `--color-primary-foreground`
+- `--color-secondary`, `--color-secondary-foreground`
+- `--color-muted`, `--color-muted-foreground`
+- `--color-accent`, `--color-accent-foreground`
+- `--color-destructive`
+- `--color-success` (custom; only needed if you use `<Status ok />`)
+- `--color-border`, `--color-input`, `--color-ring`
+- `--radius`
+- `--animate-progress-indeterminate` + the `@keyframes progress-indeterminate`
+  rule for the `Progress` component's indeterminate mode
 
-<IconButton
-  color="secondary"
-  onClick={handleEdit}
-  tooltip="Edit Item"
->
-  <EditIcon />
-</IconButton>
+A working set is shipped at `src/@/globals.css` (for dev/test only).
 
-<FloatingActionButton
-  color="primary"
-  onClick={handleAdd}
-  position="bottom-right"
->
-  <AddIcon />
-</FloatingActionButton>
-```
-
-### File Upload Components
-
-Comprehensive file upload system with progress tracking and validation.
-
-```typescript
-import { 
-  FileUploader, 
-  ImageUploader, 
-  MultiFileUploader,
-  DropZone 
-} from '@owlmeans/web-panel'
+### 3. Bundler alias
 
-<FileUploader
-  accept=".pdf,.doc,.docx"
-  maxSize={10 * 1024 * 1024} // 10MB
-  onUpload={handleFileUpload}
-  onProgress={handleProgress}
-  onError={handleError}
-/>
-
-<ImageUploader
-  accept="image/*"
-  maxSize={5 * 1024 * 1024} // 5MB
-  cropAspectRatio={16/9}
-  onUpload={handleImageUpload}
-  preview={true}
-/>
-
-<MultiFileUploader
-  maxFiles={5}
-  accept="*/*"
-  onUploadAll={handleMultipleUpload}
-  showProgress={true}
-/>
-
-<DropZone
-  onDrop={handleFileDrop}
-  accept=".zip,.tar.gz"
-  multiple={false}
->
-  Drop files here or click to browse
-</DropZone>
+```ts
+// vite.config.ts
+resolve: { alias: { '@': fileURLToPath(new URL('./src/@', import.meta.url)) } }
 ```
 
-### Text and Display Components
+## Breaking changes vs `@owlmeans/mui-panel`
 
-Typography and content display components.
-
-```typescript
-import { 
-  PanelText, 
-  PanelLink, 
-  StatusIndicator, 
-  InfoBlock 
-} from '@owlmeans/web-panel'
+This package keeps the same public name and re-export surface as the
+previous MUI implementation, but the following props/types have changed:
 
-<PanelText variant="h4" color="primary" gutterBottom>
-  Panel Title
-</PanelText>
-
-<PanelLink href="/admin/users" external={false}>
-  Manage Users
-</PanelLink>
-
-<StatusIndicator 
-  status="success" 
-  message="Operation completed successfully"
-/>
-
-<InfoBlock 
-  title="Important Notice"
-  severity="warning"
-  actions={[
-    { label: 'Dismiss', onClick: handleDismiss },
-    { label: 'Learn More', onClick: openDetails }
-  ]}
->
-  This action cannot be undone.
-</InfoBlock>
-```
+- **`styles?: SxProps` is removed.** Use the new `className?: string` and
+  `style?: React.CSSProperties` props instead. Affected: `BlockProps`,
+  `TextProps`, `LinkProps`, `WebFormProps`, `LayoutProps`.
+- **`variant` on `Text` / `Link` is now `TextVariant`**, a string-literal
+  union: `'h1' | 'h2' | 'h3' | 'h4' | 'p' | 'lead' | 'large' | 'small' |
+  'muted' | 'blockquote'`. The previous MUI `TypographyOwnProps['variant']`
+  union no longer applies.
+- **`PanelAppProps.theme?: Theme` is replaced with
+  `PanelAppProps.rootClassName?: string`.** Apply your theme via Tailwind
+  classes / CSS variables instead of MUI's `Theme` object.
+- **`render(context, theme?, opts?)` signature → `render(context, opts?)`**
+  where `opts` includes the new `rootClassName?: string`.
+- **`scalingToStyles()`** now returns a class-name string (composable with
+  `cn()`), not an `SxProps` object. The `theme?: Theme` parameter is
+  removed (Tailwind handles breakpoints declaratively).
+- **`useBreakPoint` / `useMapBreakpoint`** now use Tailwind's static
+  default breakpoints (`xs/sm/md/lg/xl`) instead of MUI's `Theme.breakpoints`.
+  Customise via Tailwind config in the consuming app.
+- **Component prop API for buttons** stays compatible (`'small' | 'medium'
+  | 'large'`, `variant` strings `contained`/`outlined`/`text`/shadcn names).
+  Internally they map to shadcn variants.
 
-### Authentication Components
+Consumers that need the previous MUI behaviour should swap to
+[`@owlmeans/mui-panel`](../mui-panel) — same exports, MUI-rendered.
 
-Built-in authentication UI components and flows.
+## Public exports
 
-```typescript
-import { 
-  LoginForm, 
-  LogoutButton, 
-  UserProfile, 
-  AuthGuard,
-  PermissionGuard 
-} from '@owlmeans/web-panel/auth'
-
-<AuthGuard fallback={<LoginForm />}>
-  <PanelApp context={context}>
-    <PermissionGuard permissions={['admin']}>
-      <AdminPanel />
-    </PermissionGuard>
-  </PanelApp>
-</AuthGuard>
-
-<LoginForm
-  onSuccess={handleLoginSuccess}
-  onError={handleLoginError}
-  showRegister={true}
-  showForgotPassword={true}
-/>
-
-<UserProfile
-  showAvatar={true}
-  showMenu={true}
-  menuActions={[
-    { label: 'Settings', onClick: openSettings },
-    { label: 'Logout', onClick: handleLogout }
-  ]}
-/>
-```
-
-## Usage Examples
-
-### Complete Panel Application
-
-```typescript
-import React from 'react'
-import { render } from '@owlmeans/web-panel'
-import { makeWebContext } from '@owlmeans/web-client'
-import { createTheme } from '@mui/material/styles'
-import {
-  PanelApp,
-  PanelLayout,
-  PanelHeader,
-  PanelSidebar,
-  PanelContent,
-  AuthGuard
-} from '@owlmeans/web-panel'
-
-const config = {
-  service: 'admin-panel',
-  type: AppType.Frontend,
-  layer: Layer.Service
-}
-
-const theme = createTheme({
-  palette: {
-    mode: 'light',
-    primary: {
-      main: '#1976d2',
-      contrastText: '#ffffff'
-    },
-    secondary: {
-      main: '#dc004e'
-    },
-    background: {
-      default: '#f5f5f5',
-      paper: '#ffffff'
-    }
-  },
-  typography: {
-    fontFamily: 'Roboto, Arial, sans-serif',
-    h1: {
-      fontSize: '2.5rem',
-      fontWeight: 500
-    }
-  },
-  shape: {
-    borderRadius: 8
-  }
-})
-
-const AdminPanelApp: React.FC = () => {
-  const context = makeWebContext(config)
-
-  return (
-    <PanelApp context={context} theme={theme}>
-      <AuthGuard>
-        <PanelLayout>
-          <PanelHeader title="Administration Panel">
-            <UserProfile />
-          </PanelHeader>
-          
-          <PanelSidebar>
-            <AdminNavigation />
-          </PanelSidebar>
-          
-          <PanelContent>
-            <AdminRouter />
-          </PanelContent>
-        </PanelLayout>
-      </AuthGuard>
-    </PanelApp>
-  )
-}
-
-// Render the application
-render(makeWebContext(config), theme)
-```
-
-### User Management Interface
-
-```typescript
-import React, { useState, useEffect } from 'react'
+```ts
 import {
-  PanelForm,
-  FormField,
-  FormSelect,
-  FormButton,
-  PanelButton,
-  StatusIndicator,
-  InfoBlock
+  PanelApp, Layout, Form, TextInput, SubmitButton, Button, ButtonSelector,
+  Block, Text, Link, Status, ImageUploader,
+  scalingToStyles, useBreakPoint, useMapBreakpoint,
+  render,
 } from '@owlmeans/web-panel'
-import { Grid, Card, CardContent, Typography } from '@mui/material'
-
-interface User {
-  id: string
-  name: string
-  email: string
-  role: string
-  active: boolean
-  createdAt: Date
-}
 
-const UserManagement: React.FC = () => {
-  const [users, setUsers] = useState<User[]>([])
-  const [loading, setLoading] = useState(true)
-  const [editing, setEditing] = useState<User | null>(null)
-  const [error, setError] = useState<string | null>(null)
-
-  useEffect(() => {
-    loadUsers()
-  }, [])
-
-  const loadUsers = async () => {
-    try {
-      setLoading(true)
-      const response = await fetch('/api/users')
-      const userData = await response.json()
-      setUsers(userData)
-    } catch (err) {
-      setError('Failed to load users')
-    } finally {
-      setLoading(false)
-    }
-  }
-
-  const handleUserSave = async (userData: Partial<User>) => {
-    try {
-      const url = editing ? `/api/users/${editing.id}` : '/api/users'
-      const method = editing ? 'PUT' : 'POST'
-      
-      const response = await fetch(url, {
-        method,
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(userData)
-      })
-      
-      if (response.ok) {
-        await loadUsers()
-        setEditing(null)
-      } else {
-        setError('Failed to save user')
-      }
-    } catch (err) {
-      setError('Network error')
-    }
-  }
-
-  const handleUserDelete = async (userId: string) => {
-    if (!confirm('Are you sure you want to delete this user?')) return
-    
-    try {
-      const response = await fetch(`/api/users/${userId}`, { method: 'DELETE' })
-      if (response.ok) {
-        await loadUsers()
-      } else {
-        setError('Failed to delete user')
-      }
-    } catch (err) {
-      setError('Network error')
-    }
-  }
-
-  const userSchema = {
-    type: 'object',
-    properties: {
-      name: { type: 'string', minLength: 2, maxLength: 100 },
-      email: { type: 'string', format: 'email' },
-      role: { type: 'string', enum: ['admin', 'user', 'moderator'] },
-      active: { type: 'boolean' }
-    },
-    required: ['name', 'email', 'role']
-  }
-
-  if (loading) {
-    return <StatusIndicator status="loading" message="Loading users..." />
-  }
-
-  return (
-    <Grid container spacing={3}>
-      <Grid item xs={12}>
-        <Typography variant="h4" gutterBottom>
-          User Management
-        </Typography>
-        
-        {error && (
-          <InfoBlock severity="error" onClose={() => setError(null)}>
-            {error}
-          </InfoBlock>
-        )}
-      </Grid>
-
-      <Grid item xs={12} md={8}>
-        <Card>
-          <CardContent>
-            <Typography variant="h6" gutterBottom>
-              Users
-            </Typography>
-            
-            <PanelButton
-              variant="contained"
-              color="primary"
-              onClick={() => setEditing({} as User)}
-              sx={{ mb: 2 }}
-            >
-              Add New User
-            </PanelButton>
-
-            {users.map(user => (
-              <Card key={user.id} variant="outlined" sx={{ mb: 1 }}>
-                <CardContent>
-                  <Grid container alignItems="center" spacing={2}>
-                    <Grid item xs>
-                      <Typography variant="subtitle1">{user.name}</Typography>
-                      <Typography variant="body2" color="textSecondary">
-                        {user.email} • {user.role}
-                      </Typography>
-                    </Grid>
-                    <Grid item>
-                      <StatusIndicator 
-                        status={user.active ? 'success' : 'warning'}
-                        message={user.active ? 'Active' : 'Inactive'}
-                      />
-                    </Grid>
-                    <Grid item>
-                      <PanelButton
-                        size="small"
-                        onClick={() => setEditing(user)}
-                      >
-                        Edit
-                      </PanelButton>
-                      <PanelButton
-                        size="small"
-                        color="error"
-                        onClick={() => handleUserDelete(user.id)}
-                        sx={{ ml: 1 }}
-                      >
-                        Delete
-                      </PanelButton>
-                    </Grid>
-                  </Grid>
-                </CardContent>
-              </Card>
-            ))}
-          </CardContent>
-        </Card>
-      </Grid>
-
-      <Grid item xs={12} md={4}>
-        {editing && (
-          <Card>
-            <CardContent>
-              <Typography variant="h6" gutterBottom>
-                {editing.id ? 'Edit User' : 'Add User'}
-              </Typography>
-              
-              <PanelForm
-                schema={userSchema}
-                defaultValues={editing}
-                onSubmit={handleUserSave}
-              >
-                <FormField
-                  name="name"
-                  label="Full Name"
-                  required
-                  fullWidth
-                  margin="normal"
-                />
-                
-                <FormField
-                  name="email"
-                  label="Email Address"
-                  type="email"
-                  required
-                  fullWidth
-                  margin="normal"
-                />
-                
-                <FormSelect
-                  name="role"
-                  label="Role"
-                  required
-                  fullWidth
-                  margin="normal"
-                  options={[
-                    { value: 'user', label: 'Regular User' },
-                    { value: 'moderator', label: 'Moderator' },
-                    { value: 'admin', label: 'Administrator' }
-                  ]}
-                />
-                
-                <FormField
-                  name="active"
-                  label="Active User"
-                  type="checkbox"
-                  margin="normal"
-                />
-                
-                <Grid container spacing={2} sx={{ mt: 2 }}>
-                  <Grid item>
-                    <FormButton
-                      type="submit"
-                      variant="contained"
-                      color="primary"
-                    >
-                      {editing.id ? 'Update' : 'Create'}
-                    </FormButton>
-                  </Grid>
-                  <Grid item>
-                    <PanelButton
-                      variant="outlined"
-                      onClick={() => setEditing(null)}
-                    >
-                      Cancel
-                    </PanelButton>
-                  </Grid>
-                </Grid>
-              </PanelForm>
-            </CardContent>
-          </Card>
-        )}
-      </Grid>
-    </Grid>
-  )
-}
-
-export default UserManagement
-```
-
-### File Upload Interface
-
-```typescript
-import React, { useState } from 'react'
-import {
-  FileUploader,
-  ImageUploader,
-  MultiFileUploader,
-  StatusIndicator,
-  PanelButton
-} from '@owlmeans/web-panel'
-import { Grid, Card, CardContent, Typography, LinearProgress } from '@mui/material'
-
-const FileManagement: React.FC = () => {
-  const [uploadProgress, setUploadProgress] = useState<Record<string, number>>({})
-  const [uploadedFiles, setUploadedFiles] = useState<string[]>([])
-
-  const handleFileUpload = async (file: File, progressCallback: (progress: number) => void) => {
-    const formData = new FormData()
-    formData.append('file', file)
-
-    try {
-      const xhr = new XMLHttpRequest()
-      
-      xhr.upload.addEventListener('progress', (e) => {
-        if (e.lengthComputable) {
-          const progress = (e.loaded / e.total) * 100
-          progressCallback(progress)
-          setUploadProgress(prev => ({ ...prev, [file.name]: progress }))
-        }
-      })
-
-      xhr.addEventListener('load', () => {
-        if (xhr.status === 200) {
-          setUploadedFiles(prev => [...prev, file.name])
-          setUploadProgress(prev => {
-            const updated = { ...prev }
-            delete updated[file.name]
-            return updated
-          })
-        }
-      })
-
-      xhr.open('POST', '/api/upload')
-      xhr.send(formData)
-    } catch (error) {
-      console.error('Upload failed:', error)
-    }
-  }
-
-  const handleImageUpload = async (file: File, cropData?: any) => {
-    console.log('Uploading image:', file.name, 'Crop data:', cropData)
-    // Implement image upload with crop data
-  }
-
-  const handleMultipleUpload = async (files: File[]) => {
-    for (const file of files) {
-      await handleFileUpload(file, () => {})
-    }
-  }
-
-  return (
-    <Grid container spacing={3}>
-      <Grid item xs={12}>
-        <Typography variant="h4" gutterBottom>
-          File Management
-        </Typography>
-      </Grid>
-
-      <Grid item xs={12} md={6}>
-        <Card>
-          <CardContent>
-            <Typography variant="h6" gutterBottom>
-              Document Upload
-            </Typography>
-            
-            <FileUploader
-              accept=".pdf,.doc,.docx,.txt"
-              maxSize={10 * 1024 * 1024} // 10MB
-              onUpload={handleFileUpload}
-              multiple={false}
-            />
-          </CardContent>
-        </Card>
-      </Grid>
-
-      <Grid item xs={12} md={6}>
-        <Card>
-          <CardContent>
-            <Typography variant="h6" gutterBottom>
-              Image Upload
-            </Typography>
-            
-            <ImageUploader
-              accept="image/*"
-              maxSize={5 * 1024 * 1024} // 5MB
-              cropAspectRatio={16/9}
-              onUpload={handleImageUpload}
-              preview={true}
-              cropperOptions={{
-                guides: false,
-                center: false,
-                highlight: false,
-                background: false,
-                autoCropArea: 1,
-                checkOrientation: false
-              }}
-            />
-          </CardContent>
-        </Card>
-      </Grid>
-
-      <Grid item xs={12}>
-        <Card>
-          <CardContent>
-            <Typography variant="h6" gutterBottom>
-              Multiple File Upload
-            </Typography>
-            
-            <MultiFileUploader
-              maxFiles={5}
-              accept="*/*"
-              onUploadAll={handleMultipleUpload}
-              showProgress={true}
-            />
-            
-            {Object.entries(uploadProgress).map(([fileName, progress]) => (
-              <div key={fileName}>
-                <Typography variant="body2" gutterBottom>
-                  {fileName}
-                </Typography>
-                <LinearProgress 
-                  variant="determinate" 
-                  value={progress} 
-                  sx={{ mb: 1 }}
-                />
-              </div>
-            ))}
-          </CardContent>
-        </Card>
-      </Grid>
-
-      {uploadedFiles.length > 0 && (
-        <Grid item xs={12}>
-          <Card>
-            <CardContent>
-              <Typography variant="h6" gutterBottom>
-                Uploaded Files
-              </Typography>
-              
-              {uploadedFiles.map(fileName => (
-                <StatusIndicator
-                  key={fileName}
-                  status="success"
-                  message={`${fileName} uploaded successfully`}
-                />
-              ))}
-            </CardContent>
-          </Card>
-        </Grid>
-      )}
-    </Grid>
-  )
-}
-
-export default FileManagement
-```
-
-## Authentication Integration
-
-### Protected Routes and Components
-
-```typescript
-import { AuthGuard, PermissionGuard } from '@owlmeans/web-panel/auth'
-import { Navigate } from 'react-router-dom'
-
-// Protect entire application
-<AuthGuard fallback={<Navigate to="/login" />}>
-  <PanelApp context={context}>
-    <Router>
-      <Routes>
-        <Route path="/admin" element={
-          <PermissionGuard permissions={['admin']}>
-            <AdminPanel />
-          </PermissionGuard>
-        } />
-        <Route path="/users" element={
-          <PermissionGuard permissions={['user-management']}>
-            <UserManagement />
-          </PermissionGuard>
-        } />
-      </Routes>
-    </Router>
-  </PanelApp>
-</AuthGuard>
-
-// Conditional rendering based on permissions
-const AdminActions: React.FC = () => (
-  <PermissionGuard permissions={['admin', 'moderator']}>
-    {(hasPermission) => (
-      <PanelButton 
-        disabled={!hasPermission}
-        onClick={handleAdminAction}
-      >
-        Admin Action
-      </PanelButton>
-    )}
-  </PermissionGuard>
-)
-```
-
-## Theme Customization
-
-### Custom Material-UI Theme
-
-```typescript
-import { createTheme, ThemeProvider } from '@mui/material/styles'
-
-const customTheme = createTheme({
-  palette: {
-    mode: 'light',
-    primary: {
-      main: '#1976d2',
-      light: '#42a5f5',
-      dark: '#1565c0',
-      contrastText: '#ffffff'
-    },
-    secondary: {
-      main: '#dc004e',
-      light: '#f06292',
-      dark: '#c2185b',
-      contrastText: '#ffffff'
-    },
-    background: {
-      default: '#f5f5f5',
-      paper: '#ffffff'
-    },
-    text: {
-      primary: '#212121',
-      secondary: '#757575'
-    }
-  },
-  typography: {
-    fontFamily: '"Roboto", "Helvetica", "Arial", sans-serif',
-    h1: {
-      fontSize: '2.5rem',
-      fontWeight: 500,
-      lineHeight: 1.2
-    },
-    h2: {
-      fontSize: '2rem',
-      fontWeight: 500,
-      lineHeight: 1.3
-    },
-    body1: {
-      fontSize: '1rem',
-      lineHeight: 1.5
-    }
-  },
-  shape: {
-    borderRadius: 8
-  },
-  spacing: 8,
-  components: {
-    MuiCard: {
-      styleOverrides: {
-        root: {
-          boxShadow: '0 2px 8px rgba(0,0,0,0.1)',
-          '&:hover': {
-            boxShadow: '0 4px 16px rgba(0,0,0,0.15)'
-          }
-        }
-      }
-    },
-    MuiButton: {
-      styleOverrides: {
-        root: {
-          borderRadius: 8,
-          textTransform: 'none',
-          fontWeight: 500
-        }
-      }
-    }
-  }
-})
-
-// Apply theme to panel app
-<PanelApp context={context} theme={customTheme}>
-  <AdminInterface />
-</PanelApp>
-```
-
-## Internationalization
-
-### Multi-language Support
-
-```typescript
-import { addI18nApp } from '@owlmeans/i18n'
-
-// Add translations for panel
-addI18nApp('en', 'panel', {
-  'panel.title': 'Administration Panel',
-  'users.title': 'User Management',
-  'users.add': 'Add New User',
-  'users.edit': 'Edit User',
-  'users.delete': 'Delete User',
-  'form.save': 'Save',
-  'form.cancel': 'Cancel',
-  'status.loading': 'Loading...',
-  'status.error': 'An error occurred',
-  'status.success': 'Operation completed successfully'
-})
-
-addI18nApp('es', 'panel', {
-  'panel.title': 'Panel de Administración',
-  'users.title': 'Gestión de Usuarios',
-  'users.add': 'Agregar Nuevo Usuario',
-  'users.edit': 'Editar Usuario',
-  'users.delete': 'Eliminar Usuario',
-  'form.save': 'Guardar',
-  'form.cancel': 'Cancelar',
-  'status.loading': 'Cargando...',
-  'status.error': 'Ocurrió un error',
-  'status.success': 'Operación completada exitosamente'
-})
-
-// Use translations in components
-import { useTranslation } from '@owlmeans/client-i18n'
-
-const UserPanel: React.FC = () => {
-  const { t } = useTranslation()
-  
-  return (
-    <Typography variant="h4">
-      {t('users.title')}
-    </Typography>
-  )
-}
-```
-
-## Performance Optimization
-
-### Code Splitting and Lazy Loading
-
-```typescript
-import React, { lazy, Suspense } from 'react'
-import { StatusIndicator } from '@owlmeans/web-panel'
-
-// Lazy load panel sections
-const UserManagement = lazy(() => import('./UserManagement'))
-const SystemSettings = lazy(() => import('./SystemSettings'))
-const Reports = lazy(() => import('./Reports'))
-
-const AdminRouter: React.FC = () => (
-  <Routes>
-    <Route path="/users" element={
-      <Suspense fallback={<StatusIndicator status="loading" message="Loading users..." />}>
-        <UserManagement />
-      </Suspense>
-    } />
-    <Route path="/settings" element={
-      <Suspense fallback={<StatusIndicator status="loading" message="Loading settings..." />}>
-        <SystemSettings />
-      </Suspense>
-    } />
-    <Route path="/reports" element={
-      <Suspense fallback={<StatusIndicator status="loading" message="Loading reports..." />}>
-        <Reports />
-      </Suspense>
-    } />
-  </Routes>
-)
-```
-
-### Memoization and Optimization
-
-```typescript
-import React, { memo, useMemo, useCallback } from 'react'
-
-const OptimizedUserList = memo<{ users: User[]; onUserSelect: (user: User) => void }>(({ 
-  users, 
-  onUserSelect 
-}) => {
-  const sortedUsers = useMemo(() => 
-    users.sort((a, b) => a.name.localeCompare(b.name)),
-    [users]
-  )
-  
-  const handleUserClick = useCallback((user: User) => {
-    onUserSelect(user)
-  }, [onUserSelect])
-
-  return (
-    <div>
-      {sortedUsers.map(user => (
-        <UserCard 
-          key={user.id} 
-          user={user} 
-          onClick={handleUserClick}
-        />
-      ))}
-    </div>
-  )
-})
-```
-
-## Best Practices
-
-1. **Component Structure**: Use consistent component hierarchy and naming conventions
-2. **Theme Management**: Leverage Material-UI theme system for consistent styling
-3. **Form Validation**: Use AJV schemas for robust form validation
-4. **Error Handling**: Provide comprehensive error feedback and recovery options
-5. **Performance**: Implement code splitting and memoization for large applications
-6. **Accessibility**: Ensure all components meet WCAG accessibility standards
-7. **Internationalization**: Always use i18n for user-facing text
-8. **Testing**: Write comprehensive tests for form validation and user interactions
-
-## Authentication Modules
-
-The package provides authentication-specific modules and components:
-
-```typescript
+import { setupExternalAuthentication } from '@owlmeans/web-panel/auth'
 import { modules } from '@owlmeans/web-panel/auth/modules'
-import { AuthProvider, LoginForm } from '@owlmeans/web-panel/auth'
-
-// Register authentication modules
-context.registerModules(modules)
-
-// Use authentication components
-<AuthProvider context={context}>
-  <LoginForm 
-    onSuccess={handleLogin}
-    features={{
-      showRegister: true,
-      showForgotPassword: true,
-      showRememberMe: true
-    }}
-  />
-</AuthProvider>
 ```
 
-## Related Packages
-
-- **@owlmeans/client-panel**: Base panel functionality and context
-- **@owlmeans/native-panel**: React Native panel implementation
-- **@owlmeans/web-client**: Web client framework and rendering
-- **@owlmeans/client-auth**: Authentication components and services
-- **@owlmeans/client-flow**: Flow management integration
-- **@owlmeans/web-flow**: Web-specific flow implementations
-
-## TypeScript Support
-
-This package is written in TypeScript and provides full type safety:
-
-```typescript
-import type { 
-  PanelAppProps,
-  FormFieldProps,
-  FileUploaderProps,
-  AuthGuardProps 
-} from '@owlmeans/web-panel'
+## Related packages
 
-const MyPanel: FC<PanelAppProps> = (props) => { /* ... */ }
-const MyForm: FC<{ onSubmit: (data: FormData) => void }> = ({ onSubmit }) => { /* ... */ }
-```
+- [`@owlmeans/mui-panel`](../mui-panel) — Material UI implementation of the
+  same surface.
+- [`@owlmeans/web-oidc-rp`](../web-oidc-rp) — companion OIDC/OAuth UI for
+  this package; uses the same Tailwind theme.
+- [`@owlmeans/client-panel`](../client-panel) — framework-agnostic headless
+  form/layout logic this package wraps.