@nextsparkjs/theme-default 0.1.0-beta.1

package/docs/02-features/01-components.md

@@ -0,0 +1,155 @@
+---
+title: Theme Components
+description: Overview of theme-specific components and patterns
+---
+
+# Theme Components
+
+The default theme includes several pre-built components that extend the core component library.
+
+## Navigation Components
+
+### MainNavigation
+
+The primary navigation component with responsive behavior:
+
+```typescript
+import { MainNavigation } from '@/contents/themes/default/components/navigation'
+
+<MainNavigation />
+```
+
+Features:
+- Mobile hamburger menu
+- Desktop horizontal navigation
+- Active link highlighting
+- Authentication-aware menu items
+
+### UserMenu
+
+User account dropdown with profile and settings:
+
+```typescript
+import { UserMenu } from '@/contents/themes/default/components/user-menu'
+
+<UserMenu />
+```
+
+## Layout Components
+
+### DashboardLayout
+
+Standard dashboard layout with sidebar and header:
+
+```typescript
+import { DashboardLayout } from '@/contents/themes/default/components/layouts'
+
+export default function DashboardPage() {
+  return (
+    <DashboardLayout>
+      <h1>Dashboard Content</h1>
+    </DashboardLayout>
+  )
+}
+```
+
+### AuthLayout
+
+Centered layout for authentication pages:
+
+```typescript
+import { AuthLayout } from '@/contents/themes/default/components/layouts'
+
+export default function LoginPage() {
+  return (
+    <AuthLayout>
+      <LoginForm />
+    </AuthLayout>
+  )
+}
+```
+
+## Component Guidelines
+
+### Composition Over Modification
+
+Always compose upward from core components. Never modify shadcn/ui components directly.
+
+```typescript
+// ✅ CORRECT
+import { Button } from '@/core/components/ui/button'
+
+export function ThemeButton({ children, ...props }) {
+  return (
+    <Button {...props} className="theme-specific-styles">
+      {children}
+    </Button>
+  )
+}
+
+// ❌ WRONG - Don't edit core/components/ui/button.tsx
+```
+
+### Accessibility First
+
+All theme components must include:
+- Proper ARIA labels
+- Keyboard navigation support
+- Screen reader compatibility
+- Focus indicators
+
+### Responsive Design
+
+Use Tailwind's responsive prefixes:
+
+```typescript
+<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3">
+  {/* Responsive grid */}
+</div>
+```
+
+## Layout Examples
+
+### Desktop Layout
+
+The theme provides a responsive desktop layout with a fixed sidebar and scrollable content area:
+
+![Desktop Layout Example](/theme/docs/desktop-layout-example.png)
+
+The layout adapts automatically to different screen sizes:
+- **Desktop (≥1024px)**: Fixed sidebar navigation with expanded content area
+- **Tablet (768px-1023px)**: Collapsible sidebar with full-width content
+- **Mobile (<768px)**: Hidden sidebar with hamburger menu toggle
+
+### Adding Images to Documentation
+
+Images can be added to documentation by placing them in the appropriate directory:
+
+**For theme documentation:**
+```bash
+# 1. Place image in theme's public/docs/ directory
+contents/themes/default/public/docs/your-image.png
+
+# 2. Run theme build (or automatic in dev mode)
+npm run theme:build
+
+# 3. Image is automatically copied to public/theme/docs/
+```
+
+**For core documentation:**
+```bash
+# Place directly in public directory (no build step needed)
+public/docs/core/assets/your-image.png
+```
+
+Then reference them in markdown using absolute paths:
+
+```markdown
+# Theme docs
+![Alt text description](/theme/docs/your-image.png)
+
+# Core docs
+![Alt text description](/docs/core/assets/your-image.png)
+```
+
+**Important:** All theme public assets (including documentation images) must stay within `contents/themes/[THEME]/public/`. The build system automatically copies the entire `public/` directory to `/theme/`. This ensures all assets are theme-specific and change when switching themes.

package/docs/02-features/02-styling.md

@@ -0,0 +1,139 @@
+---
+title: Theme Styling
+description: Comprehensive guide to styling in the default theme
+---
+
+# Theme Styling
+
+The default theme uses a combination of Tailwind CSS v4, CSS variables, and custom styles to provide a flexible and maintainable styling system.
+
+## Design Tokens
+
+All design tokens are defined as CSS variables in `styles/globals.css`:
+
+### Color System
+
+```css
+:root {
+  /* Background colors */
+  --background: 0 0% 100%;
+  --foreground: 222.2 84% 4.9%;
+
+  /* Brand colors */
+  --primary: 222.2 47.4% 11.2%;
+  --primary-foreground: 210 40% 98%;
+
+  /* Semantic colors */
+  --destructive: 0 84.2% 60.2%;
+  --success: 142 76% 36%;
+  --warning: 38 92% 50%;
+}
+```
+
+### Spacing Scale
+
+Follow Tailwind's default spacing scale:
+- `xs`: 0.5rem (8px)
+- `sm`: 0.75rem (12px)
+- `md`: 1rem (16px)
+- `lg`: 1.5rem (24px)
+- `xl`: 2rem (32px)
+
+### Typography
+
+```css
+.text-xs { font-size: 0.75rem; }
+.text-sm { font-size: 0.875rem; }
+.text-base { font-size: 1rem; }
+.text-lg { font-size: 1.125rem; }
+.text-xl { font-size: 1.25rem; }
+```
+
+## Dark Mode
+
+Dark mode is automatically applied using CSS variables:
+
+```css
+.dark {
+  --background: 222.2 84% 4.9%;
+  --foreground: 210 40% 98%;
+}
+```
+
+Components automatically adapt to dark mode without additional code.
+
+## Custom Styles
+
+### Component-Specific Styles
+
+Create scoped styles in the component directory:
+
+```typescript
+// components/custom-card/styles.css
+.custom-card {
+  @apply rounded-lg border bg-card p-6 shadow-sm;
+}
+
+.custom-card-header {
+  @apply mb-4 border-b pb-4;
+}
+```
+
+### Global Theme Styles
+
+Add global styles in `styles/theme.css`:
+
+```css
+/* Custom scrollbar */
+::-webkit-scrollbar {
+  width: 8px;
+}
+
+::-webkit-scrollbar-thumb {
+  background: hsl(var(--muted-foreground));
+  border-radius: 4px;
+}
+```
+
+## Animation
+
+### Built-in Animations
+
+The theme includes several utility animations:
+
+```typescript
+<div className="animate-fade-in">Fades in</div>
+<div className="animate-slide-up">Slides up</div>
+<div className="animate-pulse">Pulses</div>
+```
+
+### Custom Animations
+
+Define custom animations in `tailwind.config.ts`:
+
+```typescript
+export default {
+  theme: {
+    extend: {
+      animation: {
+        'bounce-slow': 'bounce 3s infinite',
+      },
+    },
+  },
+}
+```
+
+## Performance
+
+### CSS Optimization
+
+- Use Tailwind's JIT mode for minimal bundle size
+- Avoid inline styles when possible
+- Leverage CSS variables for theme switching
+
+### Best Practices
+
+- Prefer Tailwind utilities over custom CSS
+- Use `@apply` for repeated utility combinations
+- Keep custom CSS to a minimum
+- Always scope styles to avoid conflicts

package/docs/02-features/03-tasks-entity.md

@@ -0,0 +1,407 @@
+# Tasks Entity
+
+## Introduction
+
+The **Tasks** entity is the primary example entity included in the default theme. It demonstrates a complete entity implementation with full CRUD operations, metadata support, API access, and internationalization.
+
+## Entity Configuration
+
+### Basic Setup
+
+```typescript
+{
+  slug: 'tasks',
+  enabled: true,
+  names: {
+    singular: 'task',
+    plural: 'Tasks'
+  },
+  icon: CheckSquare
+}
+```
+
+### Access Configuration
+
+```typescript
+access: {
+  public: false,      // Not accessible without authentication
+  api: true,          // External API access enabled
+  metadata: true,     // Metadata system supported
+  shared: false       // User-scoped (not shared between users)
+}
+```
+
+**Implications:**
+- Users must be authenticated to access tasks
+- Tasks are available via API key
+- Each task can have custom metadata
+- Users only see their own tasks
+
+### UI Features
+
+```typescript
+ui: {
+  dashboard: {
+    showInMenu: true,       // Appears in sidebar
+    showInTopbar: true      // Quick access in topbar
+  },
+  public: {
+    hasArchivePage: false,  // No public archive
+    hasSinglePage: false    // No public detail page
+  },
+  features: {
+    searchable: true,       // Full-text search enabled
+    sortable: true,         // Column sorting
+    filterable: true,       // Advanced filters
+    bulkOperations: true,   // Select multiple tasks
+    importExport: false     // No CSV import/export
+  }
+}
+```
+
+### Permissions
+
+```typescript
+permissions: {
+  read: ['admin', 'colaborator', 'member'],
+  create: ['admin', 'colaborator', 'member'],
+  update: ['admin', 'colaborator', 'member'],
+  delete: ['admin', 'colaborator', 'member']
+}
+```
+
+**All roles** can perform all operations on tasks.
+
+## Fields
+
+### Standard Fields
+
+**Title:**
+```typescript
+{
+  name: 'title',
+  type: 'text',
+  label: 'Title',
+  required: true,
+  searchable: true,
+  sortable: true
+}
+```
+
+**Description:**
+```typescript
+{
+  name: 'description',
+  type: 'textarea',
+  label: 'Description',
+  required: false
+}
+```
+
+**Status:**
+```typescript
+{
+  name: 'status',
+  type: 'select',
+  label: 'Status',
+  options: [
+    { value: 'pending', label: 'Pending' },
+    { value: 'in_progress', label: 'In Progress' },
+    { value: 'completed', label: 'Completed' }
+  ]
+}
+```
+
+**Priority:**
+```typescript
+{
+  name: 'priority',
+  type: 'select',
+  label: 'Priority',
+  options: [
+    { value: 'low', label: 'Low' },
+    { value: 'medium', label: 'Medium' },
+    { value: 'high', label: 'High' }
+  ]
+}
+```
+
+## Database Schema
+
+### Tasks Table
+
+```sql
+CREATE TABLE tasks (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  title VARCHAR(255) NOT NULL,
+  description TEXT,
+  status VARCHAR(50) DEFAULT 'pending',
+  priority VARCHAR(50) DEFAULT 'medium',
+  user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE,
+  created_at TIMESTAMP DEFAULT NOW(),
+  updated_at TIMESTAMP DEFAULT NOW()
+);
+```
+
+### Tasks Metadata Table
+
+```sql
+CREATE TABLE tasks_metas (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  entity_id UUID REFERENCES tasks(id) ON DELETE CASCADE,
+  meta_key VARCHAR(255) NOT NULL,
+  meta_value TEXT,
+  created_at TIMESTAMP DEFAULT NOW()
+);
+```
+
+## API Endpoints
+
+### List Tasks
+
+```bash
+GET /api/v1/tasks
+Authorization: Bearer {API_KEY}
+```
+
+**Query Parameters:**
+- `search` - Full-text search
+- `status` - Filter by status
+- `priority` - Filter by priority
+- `sort` - Sort by field (e.g., `sort=created_at:desc`)
+- `limit` - Results per page
+- `offset` - Pagination offset
+
+### Get Single Task
+
+```bash
+GET /api/v1/tasks/{id}
+Authorization: Bearer {API_KEY}
+```
+
+### Create Task
+
+```bash
+POST /api/v1/tasks
+Authorization: Bearer {API_KEY}
+Content-Type: application/json
+
+{
+  "title": "New Task",
+  "description": "Task description",
+  "status": "pending",
+  "priority": "high"
+}
+```
+
+### Update Task
+
+```bash
+PUT /api/v1/tasks/{id}
+Authorization: Bearer {API_KEY}
+Content-Type: application/json
+
+{
+  "title": "Updated Title",
+  "status": "completed"
+}
+```
+
+### Delete Task
+
+```bash
+DELETE /api/v1/tasks/{id}
+Authorization: Bearer {API_KEY}
+```
+
+## Translations
+
+### English (`messages/en.json`)
+
+```json
+{
+  "tasks": {
+    "title": "Tasks",
+    "singular": "Task",
+    "fields": {
+      "title": "Title",
+      "description": "Description",
+      "status": "Status",
+      "priority": "Priority"
+    },
+    "status": {
+      "pending": "Pending",
+      "in_progress": "In Progress",
+      "completed": "Completed"
+    },
+    "priority": {
+      "low": "Low",
+      "medium": "Medium",
+      "high": "High"
+    }
+  }
+}
+```
+
+### Spanish (`messages/es.json`)
+
+```json
+{
+  "tasks": {
+    "title": "Tareas",
+    "singular": "Tarea",
+    "fields": {
+      "title": "Título",
+      "description": "Descripción",
+      "status": "Estado",
+      "priority": "Prioridad"
+    },
+    "status": {
+      "pending": "Pendiente",
+      "in_progress": "En Progreso",
+      "completed": "Completada"
+    },
+    "priority": {
+      "low": "Baja",
+      "medium": "Media",
+      "high": "Alta"
+    }
+  }
+}
+```
+
+## Usage Examples
+
+### In Components
+
+```typescript
+import { useTranslations } from 'next-intl'
+import { useEntityData } from '@/core/hooks/use-entity-data'
+
+export function TasksList() {
+  const t = useTranslations('tasks')
+  const { data: tasks, isLoading } = useEntityData('tasks')
+
+  if (isLoading) return <div>Loading...</div>
+
+  return (
+    <div>
+      <h1>{t('title')}</h1>
+      {tasks.map(task => (
+        <div key={task.id}>
+          <h3>{task.title}</h3>
+          <p>{t(`status.${task.status}`)}</p>
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+### With Metadata
+
+```typescript
+// Add metadata to task
+await addMetadata('tasks', taskId, 'custom_field', 'custom_value')
+
+// Get metadata
+const metadata = await getMetadata('tasks', taskId, 'custom_field')
+
+// Update metadata
+await updateMetadata('tasks', taskId, 'custom_field', 'new_value')
+
+// Delete metadata
+await deleteMetadata('tasks', taskId, 'custom_field')
+```
+
+## Row Level Security (RLS)
+
+### Policy: Users see only their tasks
+
+```sql
+CREATE POLICY "Users can only see their own tasks"
+ON tasks FOR SELECT
+USING (auth.uid() = user_id);
+
+CREATE POLICY "Users can only create their own tasks"
+ON tasks FOR INSERT
+WITH CHECK (auth.uid() = user_id);
+
+CREATE POLICY "Users can only update their own tasks"
+ON tasks FOR UPDATE
+USING (auth.uid() = user_id);
+
+CREATE POLICY "Users can only delete their own tasks"
+ON tasks FOR DELETE
+USING (auth.uid() = user_id);
+```
+
+## Dashboard Integration
+
+### Navigation Menu
+
+Tasks automatically appear in:
+- **Sidebar** - Full navigation entry
+- **Topbar** - Quick access button
+
+### Mobile Navigation
+
+Configured in `app.config.ts`:
+
+```typescript
+mobileNav: {
+  items: [
+    {
+      id: 'tasks',
+      labelKey: 'common.mobileNav.tasks',
+      href: '/dashboard/tasks',
+      icon: 'CheckSquare',
+      enabled: true,
+    }
+  ]
+}
+```
+
+## Customization
+
+### Add Custom Fields
+
+```typescript
+// entities/tasks/tasks.fields.ts
+{
+  name: 'due_date',
+  type: 'date',
+  label: 'Due Date',
+  required: false,
+  sortable: true
+}
+```
+
+### Change Permissions
+
+```typescript
+// entities/tasks/tasks.config.ts
+permissions: {
+  read: ['admin', 'colaborator', 'member'],
+  create: ['admin', 'colaborator'],        // Only admin and colaborator
+  update: ['admin', 'colaborator'],
+  delete: ['admin']                        // Only admin
+}
+```
+
+### Disable API Access
+
+```typescript
+access: {
+  public: false,
+  api: false,       // Disable API access
+  metadata: true,
+  shared: false
+}
+```
+
+## Next Steps
+
+- **[Entity System](/docs/core/entities/introduction)** - Complete entity documentation
+- **[API System](/docs/core/api/introduction)** - API reference
+- **[Permissions](/docs/core/authentication/permissions-and-roles)** - Permission system