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

package/templates/contents/themes/starter/entities/tasks/tasks.config.ts

@@ -0,0 +1,131 @@
+/**
+ * Task Entity Configuration - Starter Theme
+ *
+ * 5-section structure for entity configuration.
+ * All table names, API paths, and metadata are derived automatically from slug.
+ */
+
+import { CheckSquare } from 'lucide-react'
+import type { EntityConfig } from '@nextsparkjs/core/lib/entities/types'
+import { taskFields } from './tasks.fields'
+
+export const taskEntityConfig: EntityConfig = {
+  // ==========================================
+  // 1. BASIC IDENTIFICATION
+  // ==========================================
+  slug: 'tasks', // Single source of truth - derives tableName, apiPath, metaTableName, i18nNamespace
+  enabled: true,
+  names: {
+    singular: 'task',
+    plural: 'Tasks',
+  },
+  icon: CheckSquare,
+
+  // ==========================================
+  // 2. ACCESS AND SCOPE CONFIGURATION
+  // ==========================================
+  access: {
+    public: false, // If accessible without authentication, requires RLS (anon can select)
+    api: true, // If has external API via API key
+    metadata: true, // If supports metadata system
+    shared: false, // CASE 2: Any authenticated user can access all records (no userId filter)
+  },
+
+  // ==========================================
+  // 3. UI/UX FEATURES
+  // ==========================================
+  ui: {
+    dashboard: {
+      showInMenu: true,
+      showInTopbar: true,
+    },
+    public: {
+      hasArchivePage: false,
+      hasSinglePage: false,
+    },
+    features: {
+      searchable: true,
+      sortable: true,
+      filterable: true,
+      bulkOperations: true,
+      importExport: false,
+    },
+  },
+
+  // ==========================================
+  // 4. PERMISSIONS SYSTEM
+  // ==========================================
+  permissions: {
+    actions: [
+      {
+        action: 'create',
+        label: 'Create tasks',
+        description: 'Can create new tasks',
+        roles: ['owner', 'admin', 'member'],
+      },
+      {
+        action: 'read',
+        label: 'View tasks',
+        description: 'Can view task details',
+        roles: ['owner', 'admin', 'member'],
+      },
+      {
+        action: 'list',
+        label: 'List tasks',
+        description: 'Can see the tasks list',
+        roles: ['owner', 'admin', 'member'],
+      },
+      {
+        action: 'update',
+        label: 'Edit tasks',
+        description: 'Can modify task information',
+        roles: ['owner', 'admin', 'member'],
+      },
+      {
+        action: 'delete',
+        label: 'Delete tasks',
+        description: 'Can delete tasks',
+        roles: ['owner', 'admin'],
+        dangerous: true,
+      },
+    ],
+    customActions: [
+      {
+        action: 'assign',
+        label: 'Assign tasks',
+        description: 'Can assign tasks to team members',
+        roles: ['owner', 'admin'],
+      },
+    ],
+  },
+
+  // ==========================================
+  // 5. INTERNATIONALIZATION
+  // ==========================================
+  i18n: {
+    fallbackLocale: 'en',
+    loaders: {
+      en: () => import('./messages/en.json'),
+      es: () => import('./messages/es.json'),
+      fr: () => import('./messages/fr.json'),
+      it: () => import('./messages/it.json'),
+      de: () => import('./messages/de.json'),
+      pt: () => import('./messages/pt.json'),
+    },
+  },
+
+  // ==========================================
+  // FIELDS (imported from separate file)
+  // ==========================================
+  fields: taskFields,
+
+  // ==========================================
+  // AUTOMATIC SYSTEM DERIVATIONS
+  // ==========================================
+  // The following properties are automatically derived from the slug:
+  // - tableName: 'tasks' (slug)
+  // - metaTableName: 'tasks_metas' (slug + '_metas')
+  // - apiPath: '/api/v1/tasks' (slug API Route)
+  // - i18nNamespace: 'tasks' (slug as namespace)
+  // - foreignKey in metadata: 'entityId' (generic for all entities)
+}

package/templates/contents/themes/starter/entities/tasks/tasks.fields.ts

@@ -0,0 +1,188 @@
+/**
+ * Task Entity Fields Configuration - Starter Theme
+ *
+ * Contains all field definitions for the tasks entity.
+ */
+
+import type { EntityField } from '@nextsparkjs/core/lib/entities/types'
+
+export const taskFields: EntityField[] = [
+  {
+    name: 'title',
+    type: 'text',
+    required: true,
+    display: {
+      label: 'Title',
+      description: 'Task title or name',
+      placeholder: 'Enter task title...',
+      showInList: true,
+      showInDetail: true,
+      showInForm: true,
+      order: 1,
+      columnWidth: 12,
+    },
+    api: {
+      readOnly: false,
+      searchable: true,
+      sortable: true,
+    },
+  },
+  {
+    name: 'description',
+    type: 'textarea',
+    required: false,
+    display: {
+      label: 'Description',
+      description: 'Detailed task description',
+      placeholder: 'Enter task description...',
+      showInList: false,
+      showInDetail: true,
+      showInForm: true,
+      order: 2,
+      columnWidth: 12,
+    },
+    api: {
+      readOnly: false,
+      searchable: true,
+      sortable: false,
+    },
+  },
+  {
+    name: 'status',
+    type: 'select',
+    required: false,
+    defaultValue: 'todo',
+    options: [
+      { value: 'todo', label: 'To Do' },
+      { value: 'in-progress', label: 'In Progress' },
+      { value: 'review', label: 'In Review' },
+      { value: 'done', label: 'Done' },
+      { value: 'blocked', label: 'Blocked' },
+    ],
+    display: {
+      label: 'Status',
+      description: 'Current task status',
+      placeholder: 'Select status...',
+      showInList: true,
+      showInDetail: true,
+      showInForm: true,
+      order: 3,
+      columnWidth: 4,
+    },
+    api: {
+      readOnly: false,
+      searchable: false,
+      sortable: true,
+    },
+  },
+  {
+    name: 'priority',
+    type: 'select',
+    required: false,
+    defaultValue: 'medium',
+    options: [
+      { value: 'low', label: 'Low' },
+      { value: 'medium', label: 'Medium' },
+      { value: 'high', label: 'High' },
+      { value: 'urgent', label: 'Urgent' },
+    ],
+    display: {
+      label: 'Priority',
+      description: 'Task priority level',
+      placeholder: 'Select priority...',
+      showInList: true,
+      showInDetail: true,
+      showInForm: true,
+      order: 4,
+      columnWidth: 4,
+    },
+    api: {
+      readOnly: false,
+      searchable: false,
+      sortable: true,
+    },
+  },
+  {
+    name: 'tags',
+    type: 'tags',
+    required: false,
+    display: {
+      label: 'Tags',
+      description: 'Task tags for categorization',
+      placeholder: 'Add tags...',
+      showInList: false,
+      showInDetail: true,
+      showInForm: true,
+      order: 5,
+      columnWidth: 6,
+    },
+    api: {
+      readOnly: false,
+      searchable: true,
+      sortable: false,
+    },
+  },
+  {
+    name: 'dueDate',
+    type: 'date',
+    required: false,
+    display: {
+      label: 'Due Date',
+      description: 'Task deadline',
+      placeholder: 'Select due date...',
+      showInList: true,
+      showInDetail: true,
+      showInForm: true,
+      order: 6,
+      columnWidth: 4,
+    },
+    api: {
+      readOnly: false,
+      searchable: false,
+      sortable: true,
+    },
+  },
+  {
+    name: 'estimatedHours',
+    type: 'number',
+    required: false,
+    display: {
+      label: 'Estimated Hours',
+      description: 'Estimated time to complete (in hours)',
+      placeholder: '0',
+      showInList: false,
+      showInDetail: true,
+      showInForm: true,
+      order: 7,
+      columnWidth: 4,
+    },
+    api: {
+      readOnly: false,
+      searchable: false,
+      sortable: true,
+    },
+  },
+  {
+    name: 'completed',
+    type: 'boolean',
+    required: false,
+    defaultValue: false,
+    display: {
+      label: 'Completed',
+      description: 'Mark as completed (legacy field, use status instead)',
+      showInList: false,
+      showInDetail: true,
+      showInForm: false,
+      order: 8,
+      columnWidth: 4,
+    },
+    api: {
+      readOnly: false,
+      searchable: false,
+      sortable: true,
+    },
+  },
+  // NOTE: createdAt and updatedAt are implicit system fields
+  // They are automatically included by the API and frontend components
+  // Do NOT declare them here - see core/lib/entities/system-fields.ts
+]

package/templates/contents/themes/starter/entities/tasks/tasks.service.ts

@@ -0,0 +1,390 @@
+/**
+ * Tasks Service - Starter Theme
+ *
+ * Provides data access methods for tasks.
+ * Tasks is a private entity with shared: false - users only see their own tasks.
+ *
+ * All methods require authentication (use RLS with userId filter).
+ *
+ * @module TasksService
+ */
+
+import { queryOneWithRLS, queryWithRLS } from '@nextsparkjs/core/lib/db'
+import type {
+  Task,
+  TaskListOptions,
+  TaskListResult,
+  TaskStatus,
+} from './tasks.types'
+
+// Database row type for task
+interface DbTask {
+  id: string
+  title: string
+  description: string | null
+  status: TaskStatus
+  priority: string
+  tags: string[] | null
+  dueDate: string | null
+  estimatedHours: number | null
+  completed: boolean | null
+  createdAt: string
+  updatedAt: string
+}
+
+export class TasksService {
+  // ============================================
+  // AUTHENTICATED METHODS (with RLS)
+  // ============================================
+
+  /**
+   * Get a task by ID
+   *
+   * Respects RLS policies. Since tasks has shared: false,
+   * only the task owner can access it.
+   *
+   * @param id - Task ID
+   * @param userId - Current user ID for RLS
+   * @returns Task data or null if not found/not authorized
+   *
+   * @example
+   * const task = await TasksService.getById('task-uuid', currentUserId)
+   */
+  static async getById(id: string, userId: string): Promise<Task | null> {
+    try {
+      if (!id || id.trim() === '') {
+        throw new Error('Task ID is required')
+      }
+
+      if (!userId || userId.trim() === '') {
+        throw new Error('User ID is required for authentication')
+      }
+
+      const task = await queryOneWithRLS<DbTask>(
+        `
+        SELECT
+          id,
+          title,
+          description,
+          status,
+          priority,
+          tags,
+          "dueDate",
+          "estimatedHours",
+          completed,
+          "createdAt",
+          "updatedAt"
+        FROM tasks
+        WHERE id = $1
+        `,
+        [id],
+        userId
+      )
+
+      if (!task) {
+        return null
+      }
+
+      return {
+        id: task.id,
+        title: task.title,
+        description: task.description ?? undefined,
+        status: task.status,
+        priority: task.priority as Task['priority'],
+        tags: task.tags ?? undefined,
+        dueDate: task.dueDate ?? undefined,
+        estimatedHours: task.estimatedHours ?? undefined,
+        completed: task.completed ?? undefined,
+        createdAt: task.createdAt,
+        updatedAt: task.updatedAt,
+      }
+    } catch (error) {
+      console.error('TasksService.getById error:', error)
+      throw new Error(
+        error instanceof Error ? error.message : 'Failed to fetch task'
+      )
+    }
+  }
+
+  /**
+   * List tasks with pagination and filtering
+   *
+   * @param userId - Current user ID for RLS
+   * @param options - List options (limit, offset, status, priority, orderBy, orderDir)
+   * @returns Object with tasks array and total count
+   *
+   * @example
+   * const { tasks, total } = await TasksService.list(currentUserId, {
+   *   status: 'todo',
+   *   limit: 10
+   * })
+   */
+  static async list(
+    userId: string,
+    options: TaskListOptions = {}
+  ): Promise<TaskListResult> {
+    try {
+      if (!userId || userId.trim() === '') {
+        throw new Error('User ID is required for authentication')
+      }
+
+      const {
+        limit = 10,
+        offset = 0,
+        status,
+        priority,
+        orderBy = 'createdAt',
+        orderDir = 'desc',
+      } = options
+
+      // Build WHERE clause
+      const conditions: string[] = []
+      const params: unknown[] = []
+      let paramIndex = 1
+
+      if (status) {
+        conditions.push(`status = $${paramIndex}`)
+        params.push(status)
+        paramIndex++
+      }
+
+      if (priority) {
+        conditions.push(`priority = $${paramIndex}`)
+        params.push(priority)
+        paramIndex++
+      }
+
+      const whereClause =
+        conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : ''
+
+      // Validate orderBy to prevent SQL injection
+      const validOrderBy = [
+        'title',
+        'status',
+        'priority',
+        'dueDate',
+        'createdAt',
+      ].includes(orderBy)
+        ? orderBy
+        : 'createdAt'
+      const validOrderDir = orderDir === 'asc' ? 'ASC' : 'DESC'
+
+      // Map field names to database columns
+      const orderColumnMap: Record<string, string> = {
+        title: 'title',
+        status: 'status',
+        priority: 'priority',
+        dueDate: '"dueDate"',
+        createdAt: '"createdAt"',
+      }
+      const orderColumn = orderColumnMap[validOrderBy] || '"createdAt"'
+
+      // Get total count
+      const countResult = await queryWithRLS<{ count: string }>(
+        `SELECT COUNT(*)::text as count FROM tasks ${whereClause}`,
+        params,
+        userId
+      )
+      const total = parseInt(countResult[0]?.count || '0', 10)
+
+      // Get tasks
+      params.push(limit, offset)
+      const tasks = await queryWithRLS<DbTask>(
+        `
+        SELECT
+          id,
+          title,
+          description,
+          status,
+          priority,
+          tags,
+          "dueDate",
+          "estimatedHours",
+          completed,
+          "createdAt",
+          "updatedAt"
+        FROM tasks
+        ${whereClause}
+        ORDER BY ${orderColumn} ${validOrderDir}
+        LIMIT $${paramIndex} OFFSET $${paramIndex + 1}
+        `,
+        params,
+        userId
+      )
+
+      return {
+        tasks: tasks.map((task) => ({
+          id: task.id,
+          title: task.title,
+          description: task.description ?? undefined,
+          status: task.status,
+          priority: task.priority as Task['priority'],
+          tags: task.tags ?? undefined,
+          dueDate: task.dueDate ?? undefined,
+          estimatedHours: task.estimatedHours ?? undefined,
+          completed: task.completed ?? undefined,
+          createdAt: task.createdAt,
+          updatedAt: task.updatedAt,
+        })),
+        total,
+      }
+    } catch (error) {
+      console.error('TasksService.list error:', error)
+      throw new Error(
+        error instanceof Error ? error.message : 'Failed to list tasks'
+      )
+    }
+  }
+
+  /**
+   * Get tasks by status
+   *
+   * Convenience method to fetch all tasks with a specific status.
+   *
+   * @param userId - Current user ID for RLS
+   * @param status - Task status to filter by
+   * @returns Array of tasks with the given status
+   *
+   * @example
+   * const todoTasks = await TasksService.getByStatus(currentUserId, 'todo')
+   */
+  static async getByStatus(userId: string, status: TaskStatus): Promise<Task[]> {
+    try {
+      const { tasks } = await this.list(userId, {
+        status,
+        limit: 1000, // Large limit to get all matching tasks
+        orderBy: 'priority',
+        orderDir: 'desc',
+      })
+
+      return tasks
+    } catch (error) {
+      console.error('TasksService.getByStatus error:', error)
+      throw new Error(
+        error instanceof Error
+          ? error.message
+          : 'Failed to fetch tasks by status'
+      )
+    }
+  }
+
+  /**
+   * Get overdue tasks
+   *
+   * Fetches tasks that are past their due date and not completed.
+   *
+   * @param userId - Current user ID for RLS
+   * @returns Array of overdue tasks
+   *
+   * @example
+   * const overdueTasks = await TasksService.getOverdue(currentUserId)
+   */
+  static async getOverdue(userId: string): Promise<Task[]> {
+    try {
+      if (!userId || userId.trim() === '') {
+        throw new Error('User ID is required for authentication')
+      }
+
+      const tasks = await queryWithRLS<DbTask>(
+        `
+        SELECT
+          id,
+          title,
+          description,
+          status,
+          priority,
+          tags,
+          "dueDate",
+          "estimatedHours",
+          completed,
+          "createdAt",
+          "updatedAt"
+        FROM tasks
+        WHERE "dueDate" < CURRENT_DATE
+          AND status != 'done'
+          AND (completed IS NULL OR completed = false)
+        ORDER BY "dueDate" ASC
+        `,
+        [],
+        userId
+      )
+
+      return tasks.map((task) => ({
+        id: task.id,
+        title: task.title,
+        description: task.description ?? undefined,
+        status: task.status,
+        priority: task.priority as Task['priority'],
+        tags: task.tags ?? undefined,
+        dueDate: task.dueDate ?? undefined,
+        estimatedHours: task.estimatedHours ?? undefined,
+        completed: task.completed ?? undefined,
+        createdAt: task.createdAt,
+        updatedAt: task.updatedAt,
+      }))
+    } catch (error) {
+      console.error('TasksService.getOverdue error:', error)
+      throw new Error(
+        error instanceof Error ? error.message : 'Failed to fetch overdue tasks'
+      )
+    }
+  }
+
+  /**
+   * Get tasks due today
+   *
+   * @param userId - Current user ID for RLS
+   * @returns Array of tasks due today
+   */
+  static async getDueToday(userId: string): Promise<Task[]> {
+    try {
+      if (!userId || userId.trim() === '') {
+        throw new Error('User ID is required for authentication')
+      }
+
+      const tasks = await queryWithRLS<DbTask>(
+        `
+        SELECT
+          id,
+          title,
+          description,
+          status,
+          priority,
+          tags,
+          "dueDate",
+          "estimatedHours",
+          completed,
+          "createdAt",
+          "updatedAt"
+        FROM tasks
+        WHERE "dueDate" = CURRENT_DATE
+          AND status != 'done'
+        ORDER BY priority DESC, "createdAt" ASC
+        `,
+        [],
+        userId
+      )
+
+      return tasks.map((task) => ({
+        id: task.id,
+        title: task.title,
+        description: task.description ?? undefined,
+        status: task.status,
+        priority: task.priority as Task['priority'],
+        tags: task.tags ?? undefined,
+        dueDate: task.dueDate ?? undefined,
+        estimatedHours: task.estimatedHours ?? undefined,
+        completed: task.completed ?? undefined,
+        createdAt: task.createdAt,
+        updatedAt: task.updatedAt,
+      }))
+    } catch (error) {
+      console.error('TasksService.getDueToday error:', error)
+      throw new Error(
+        error instanceof Error
+          ? error.message
+          : 'Failed to fetch tasks due today'
+      )
+    }
+  }
+}