@nextsparkjs/core 0.1.0-beta.3 → 0.1.0-beta.5

package/templates/contents/themes/default/docs/02-features/01-components.md

@@ -1,155 +0,0 @@
----
-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/templates/contents/themes/default/docs/02-features/02-styling.md

@@ -1,139 +0,0 @@
----
-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/templates/contents/themes/default/docs/02-features/03-tasks-entity.md

@@ -1,407 +0,0 @@
-# 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