@nextsparkjs/theme-default 0.1.0-beta.1

package/config/features.config.ts

@@ -0,0 +1,203 @@
+/**
+ * Default Theme - Features Configuration
+ *
+ * Defines all features of the application for this theme.
+ * Each feature key becomes a tag: @feat-{key}
+ *
+ * Features are enriched at build-time with:
+ * - Entity metadata (from entity-registry)
+ * - Permission details (from permissions-registry)
+ * - Documentation links (from docs-registry)
+ * - Test coverage (from tags-registry + test files)
+ */
+
+import { defineFeatures } from '@nextsparkjs/core/lib/config/features-types'
+
+export default defineFeatures({
+
+
+  // ===========================================================================
+  // AI FEATURES
+  // AI-powered assistant and tools
+  // ===========================================================================
+
+  ai: {
+    name: 'AI Assistant',
+    description: 'AI-powered assistant with multi-agent orchestration, chat, and usage tracking',
+    category: 'core',
+    icon: 'bot',
+    entities: [],
+    permissions: ['ai.*'],
+    docs: ['03-ai/*'],
+  },
+
+  // ===========================================================================
+  // ENTITY FEATURES
+  // Business entity CRUD features
+  // ===========================================================================
+
+  customers: {
+    name: 'Customers',
+    description: 'Customer management with metadata support',
+    category: 'entities',
+    icon: 'user-circle',
+    entities: ['customers'],
+    permissions: ['customers.*'],
+    docs: [],
+  },
+
+  tasks: {
+    name: 'Tasks',
+    description: 'Task tracking and assignment',
+    category: 'entities',
+    icon: 'check-square',
+    entities: ['tasks'],
+    permissions: ['tasks.*'],
+    docs: [],
+  },
+
+  posts: {
+    name: 'Posts',
+    description: 'Blog posts and content publishing',
+    category: 'entities',
+    icon: 'file-text',
+    entities: ['posts', 'categories'],
+    permissions: ['posts.*', 'categories.*'],
+    docs: [],
+  },
+
+  pages: {
+    name: 'Pages',
+    description: 'Page management, publishing, and SEO settings',
+    category: 'entities',
+    icon: 'file',
+    entities: ['pages'],
+    permissions: ['pages.*'],
+    docs: [],
+  },
+
+  // ===========================================================================
+  // CONTENT FEATURES
+  // Content creation and editing tools
+  // ===========================================================================
+
+  'page-builder': {
+    name: 'Page Builder',
+    description: 'Visual block editor for page content',
+    category: 'content',
+    icon: 'layout',
+    entities: [],
+    permissions: ['blocks.*'],
+    docs: ['18-page-builder/*'],
+  },
+
+  // ===========================================================================
+  // CORE FEATURES
+  // Platform-level features that exist in all themes
+  // ===========================================================================
+
+  auth: {
+    name: 'Authentication',
+    description: 'User authentication, sessions, and account security',
+    category: 'core',
+    icon: 'shield',
+    entities: [],
+    permissions: ['auth.*'],
+    docs: ['06-authentication/*'],
+  },
+
+  teams: {
+    name: 'Teams',
+    description: 'Multi-tenant team management and membership',
+    category: 'core',
+    icon: 'users',
+    entities: [],
+    permissions: ['teams.*', 'members.*', 'invitations.*'],
+    docs: ['10-teams/*'],
+  },
+
+  // ===========================================================================
+  // BILLING FEATURES
+  // Plans, subscriptions, and payments
+  // ===========================================================================
+
+  plans: {
+    name: 'Plans',
+    description: 'Plan catalog, comparison, and selection',
+    category: 'settings',
+    icon: 'credit-card',
+    entities: [],
+    permissions: ['plans.*'],
+    docs: ['19-billing/02-configuration.md', '19-billing/07-pricing-strategies.md'],
+  },
+
+  billing: {
+    name: 'Billing',
+    description: 'Subscription management, payments, and invoices',
+    category: 'settings',
+    icon: 'receipt',
+    entities: [],
+    permissions: ['billing.*', 'subscriptions.*', 'invoices.*'],
+    docs: ['19-billing/*'],
+  },
+
+  // ===========================================================================
+  // SETTINGS FEATURES
+  // User and team settings
+  // ===========================================================================
+
+  users: {
+    name: 'User Profile',
+    description: 'User profile management and preferences',
+    category: 'settings',
+    icon: 'user',
+    entities: [],
+    permissions: ['profile.*'],
+    docs: [],
+  },
+
+  'api-keys': {
+    name: 'API Keys',
+    description: 'API key generation and management for integrations',
+    category: 'settings',
+    icon: 'key',
+    entities: [],
+    permissions: ['api-keys.*'],
+    docs: ['05-api/*'],
+  },
+
+  // ===========================================================================
+  // ADMIN FEATURES
+  // Superadmin and developer tools
+  // ===========================================================================
+
+  superadmin: {
+    name: 'Superadmin',
+    description: 'Superadmin dashboard and system management',
+    category: 'admin',
+    icon: 'shield-check',
+    entities: [],
+    permissions: ['superadmin.*'],
+    docs: ['19-restricted-zones/02-admin.md'],
+  },
+
+  devtools: {
+    name: 'Developer Tools',
+    description: 'Development tools, test viewers, and configuration inspectors',
+    category: 'admin',
+    icon: 'terminal',
+    entities: [],
+    permissions: ['developer.*'],
+    docs: ['19-restricted-zones/03-devtools.md'],
+  },
+
+  'scheduled-actions': {
+    name: 'Scheduled Actions',
+    description: 'Background task processing, webhooks, and recurring operations',
+    category: 'core',
+    icon: 'clock',
+    entities: [],
+    permissions: ['developer.*'],
+    docs: ['20-scheduled-actions/*'],
+  },
+})

package/config/flows.config.ts

@@ -0,0 +1,129 @@
+/**
+ * Default Theme - Flows Configuration
+ *
+ * Defines user journeys/flows that span multiple features.
+ * Each flow key becomes a tag: @flow-{key}
+ *
+ * Flows are enriched at build-time with:
+ * - Feature metadata (from features.config.ts)
+ * - Test coverage (from tags-registry + test files)
+ */
+
+import { defineFlows } from '@nextsparkjs/core/lib/config/features-types'
+
+export default defineFlows({
+  // ===========================================================================
+  // ACQUISITION FLOWS
+  // User acquisition and onboarding journeys
+  // ===========================================================================
+
+  onboarding: {
+    name: 'User Onboarding',
+    description: 'Complete journey from signup to first team creation',
+    category: 'acquisition',
+    icon: 'rocket',
+    criticalPath: true,
+
+    steps: [
+      {
+        feature: 'auth',
+        action: 'signup',
+        description: 'User creates account with email/password or OAuth',
+      },
+      {
+        feature: 'auth',
+        action: 'verify-email',
+        description: 'User verifies email address',
+      },
+      {
+        feature: 'teams',
+        action: 'create-team',
+        description: 'User creates their first team/workspace',
+      },
+      {
+        feature: 'teams',
+        action: 'invite-members',
+        description: 'User invites team members',
+        optional: true,
+      },
+    ],
+
+    features: ['auth', 'teams'],
+  },
+
+  // ===========================================================================
+  // NAVIGATION FLOWS
+  // Context switching and navigation journeys
+  // ===========================================================================
+
+  'team-switch': {
+    name: 'Team Switching',
+    description: 'Context switch between different teams/workspaces',
+    category: 'navigation',
+    icon: 'repeat',
+    criticalPath: true,
+
+    steps: [
+      {
+        feature: 'teams',
+        action: 'open-switcher',
+        description: 'User opens the team switcher dropdown',
+      },
+      {
+        feature: 'teams',
+        action: 'select-team',
+        description: 'User selects a different team',
+      },
+      {
+        feature: 'teams',
+        action: 'load-context',
+        description: 'System loads new team context and redirects',
+      },
+    ],
+
+    features: ['teams'],
+  },
+
+  // ===========================================================================
+  // BILLING FLOWS
+  // Subscription and payment journeys
+  // ===========================================================================
+
+  'upgrade-plan': {
+    name: 'Plan Upgrade',
+    description: 'Upgrade subscription to a higher tier plan',
+    category: 'settings',
+    icon: 'trending-up',
+    criticalPath: true,
+
+    steps: [
+      {
+        feature: 'plans',
+        action: 'view-plans',
+        description: 'User views available plans',
+      },
+      {
+        feature: 'plans',
+        action: 'compare-plans',
+        description: 'User compares features between plans',
+      },
+      {
+        feature: 'plans',
+        action: 'select-plan',
+        description: 'User selects a new plan',
+      },
+      {
+        feature: 'billing',
+        action: 'enter-payment',
+        description: 'User enters or confirms payment method',
+      },
+      {
+        feature: 'billing',
+        action: 'confirm-upgrade',
+        description: 'User confirms the upgrade',
+      },
+    ],
+
+    features: ['plans', 'billing'],
+  },
+})

package/config/permissions.config.ts

@@ -0,0 +1,245 @@
+/**
+ * Default Theme - Permissions Configuration
+ *
+ * SINGLE SOURCE OF TRUTH for all permissions and roles in this theme.
+ *
+ * This file defines:
+ * - roles: Custom roles beyond core (owner, admin, member, viewer)
+ * - teams: Team-level permissions (team.view, team.edit, etc.)
+ * - entities: Entity CRUD permissions (customers, tasks, etc.)
+ * - features: Theme-specific feature permissions (page-builder, blog, media)
+ *
+ * All sections use unified format: { action: '...', roles: [...] }
+ *
+ * Use PermissionService.canDoAction(role, action) to check any permission.
+ */
+
+import type { ThemePermissionsConfig } from '@nextsparkjs/core/lib/permissions/types'
+
+export const PERMISSIONS_CONFIG_OVERRIDES: ThemePermissionsConfig = {
+  // ==========================================
+  // CUSTOM ROLES
+  // ==========================================
+  // Roles beyond core (owner, admin, member, viewer)
+  roles: {
+    additionalRoles: ['editor'] as const,
+    hierarchy: {
+      editor: 5, // Between viewer (1) and member (10)
+    },
+    displayNames: {
+      editor: 'common.teamRoles.editor',
+    },
+    descriptions: {
+      editor: 'Can view team content but has limited editing capabilities',
+    },
+  },
+
+  // ==========================================
+  // TEAM PERMISSIONS
+  // ==========================================
+  // Unified format: { action, label, description, roles, dangerous? }
+  teams: [
+    // View permissions
+    { action: 'team.view', label: 'View Team', description: 'Can view team details', roles: ['owner', 'admin', 'member', 'viewer', 'editor'] },
+    { action: 'team.members.view', label: 'View Members', description: 'Can see team member list', roles: ['owner', 'admin', 'member', 'viewer', 'editor'] },
+    { action: 'team.settings.view', label: 'View Settings', description: 'Can view team settings', roles: ['owner', 'admin', 'member', 'editor'] },
+    { action: 'team.billing.view', label: 'View Billing', description: 'Can view billing information', roles: ['owner', 'admin'] },
+
+    // Edit permissions
+    { action: 'team.edit', label: 'Edit Team', description: 'Can modify team name and details', roles: ['owner', 'admin'] },
+    { action: 'team.settings.edit', label: 'Edit Settings', description: 'Can modify team settings', roles: ['owner', 'admin'] },
+    { action: 'team.billing.manage', label: 'Manage Billing', description: 'Can manage subscriptions and payments', roles: ['owner'] },
+
+    // Member management
+    { action: 'team.members.invite', label: 'Invite Members', description: 'Can invite new team members', roles: ['owner', 'admin'] },
+    { action: 'team.members.remove', label: 'Remove Members', description: 'Can remove team members', roles: ['owner', 'admin'] },
+    { action: 'team.members.update_role', label: 'Update Roles', description: 'Can change member roles', roles: ['owner', 'admin'] },
+
+    // Dangerous
+    { action: 'team.delete', label: 'Delete Team', description: 'Can permanently delete the team', roles: ['owner'], dangerous: true },
+  ],
+
+  // ==========================================
+  // ENTITY PERMISSIONS
+  // ==========================================
+  entities: {
+    // ------------------------------------------
+    // CUSTOMERS
+    // ------------------------------------------
+    customers: [
+      { action: 'create', label: 'Create customers', description: 'Can create new customers', roles: ['owner', 'admin'] },
+      { action: 'read', label: 'View customers', description: 'Can view customer details', roles: ['owner', 'admin', 'member', 'editor'] },
+      { action: 'list', label: 'List customers', description: 'Can see the customers list', roles: ['owner', 'admin', 'member', 'editor'] },
+      { action: 'update', label: 'Edit customers', description: 'Can modify customer information', roles: ['owner', 'admin'] },
+      { action: 'delete', label: 'Delete customers', description: 'Can delete customers', roles: ['owner'], dangerous: true },
+    ],
+
+    // ------------------------------------------
+    // TASKS
+    // Note: Editor does NOT have access to tasks (per business rules)
+    // ------------------------------------------
+    tasks: [
+      { 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 },
+      { action: 'assign', label: 'Assign tasks', description: 'Can assign tasks to team members', roles: ['owner', 'admin'] },
+    ],
+
+    // ------------------------------------------
+    // POSTS
+    // ------------------------------------------
+    posts: [
+      { action: 'create', label: 'Create Posts', description: 'Can create new blog posts', roles: ['owner', 'admin', 'member'] },
+      { action: 'read', label: 'View Posts', description: 'Can view post details', roles: ['owner', 'admin', 'member', 'viewer'] },
+      { action: 'list', label: 'List Posts', description: 'Can see the posts list', roles: ['owner', 'admin', 'member', 'viewer'] },
+      { action: 'update', label: 'Edit Posts', description: 'Can modify post content', roles: ['owner', 'admin', 'member'] },
+      { action: 'delete', label: 'Delete Posts', description: 'Can delete posts', roles: ['owner', 'admin'], dangerous: true },
+      { action: 'publish', label: 'Publish Posts', description: 'Can publish posts to make them public', roles: ['owner', 'admin'] },
+    ],
+
+    // ------------------------------------------
+    // PAGES
+    // ------------------------------------------
+    pages: [
+      { action: 'create', label: 'Create Pages', description: 'Can create new pages', roles: ['owner', 'admin'] },
+      { action: 'read', label: 'View Pages', description: 'Can view page details', roles: ['owner', 'admin', 'member', 'viewer'] },
+      { action: 'list', label: 'List Pages', description: 'Can see the pages list', roles: ['owner', 'admin', 'member', 'viewer'] },
+      { action: 'update', label: 'Edit Pages', description: 'Can modify page content', roles: ['owner', 'admin'] },
+      { action: 'delete', label: 'Delete Pages', description: 'Can delete pages', roles: ['owner', 'admin'], dangerous: true },
+      { action: 'publish', label: 'Publish Pages', description: 'Can publish pages to make them public', roles: ['owner', 'admin'] },
+    ],
+  },
+
+  // ==========================================
+  // FEATURE PERMISSIONS
+  // ==========================================
+  // Unified format: uses 'action' instead of 'id'
+  features: [
+    // AI ASSISTANT
+    {
+      action: 'ai.access',
+      label: 'Access AI Assistant',
+      description: 'Can access the AI chat assistant',
+      category: 'AI Assistant',
+      roles: ['owner', 'admin', 'member'],
+    },
+    {
+      action: 'ai.chat',
+      label: 'Send Messages',
+      description: 'Can send messages to the AI assistant',
+      category: 'AI Assistant',
+      roles: ['owner', 'admin', 'member'],
+    },
+    {
+      action: 'ai.history',
+      label: 'View Chat History',
+      description: 'Can view past conversations with AI assistant',
+      category: 'AI Assistant',
+      roles: ['owner', 'admin', 'member'],
+    },
+    {
+      action: 'ai.settings',
+      label: 'Manage AI Settings',
+      description: 'Can configure AI assistant settings and preferences',
+      category: 'AI Assistant',
+      roles: ['owner', 'admin'],
+    },
+
+    // PAGE BUILDER
+    {
+      action: 'page-builder.access',
+      label: 'Access Page Builder',
+      description: 'Can use the visual page builder to create and edit content',
+      category: 'Page Builder',
+      roles: ['owner', 'admin', 'editor', 'member'],
+    },
+    {
+      action: 'page-builder.manage-blocks',
+      label: 'Manage Blocks',
+      description: 'Can add, remove, and configure blocks in the page builder',
+      category: 'Page Builder',
+      roles: ['owner', 'admin'],
+    },
+    {
+      action: 'page-builder.custom-css',
+      label: 'Custom CSS',
+      description: 'Can add custom CSS styles to pages and blocks',
+      category: 'Page Builder',
+      roles: ['owner', 'admin'],
+      dangerous: true,
+    },
+
+    // BLOG PUBLISHING
+    {
+      action: 'blog.schedule',
+      label: 'Schedule Posts',
+      description: 'Can schedule posts for future publication',
+      category: 'Blog',
+      roles: ['owner', 'admin'],
+    },
+    {
+      action: 'blog.featured',
+      label: 'Feature Posts',
+      description: 'Can mark posts as featured for homepage display',
+      category: 'Blog',
+      roles: ['owner', 'admin'],
+    },
+
+    // MEDIA MANAGEMENT
+    {
+      action: 'media.upload',
+      label: 'Upload Media',
+      description: 'Can upload images, videos, and other media files',
+      category: 'Media',
+      roles: ['owner', 'admin', 'editor', 'member'],
+    },
+    {
+      action: 'media.delete',
+      label: 'Delete Media',
+      description: 'Can permanently delete media files',
+      category: 'Media',
+      roles: ['owner', 'admin'],
+      dangerous: true,
+    },
+  ],
+
+  // ==========================================
+  // UI SECTIONS
+  // ==========================================
+  uiSections: [
+    {
+      id: 'ai',
+      label: 'AI Assistant',
+      description: 'AI-powered assistant features',
+      categories: ['AI Assistant'],
+    },
+    {
+      id: 'teams',
+      label: 'Teams',
+      description: 'Team management permissions',
+      categories: ['Teams'],
+    },
+    {
+      id: 'page-builder',
+      label: 'Page Builder',
+      description: 'Visual content editing features',
+      categories: ['Page Builder'],
+    },
+    {
+      id: 'blog',
+      label: 'Blog',
+      description: 'Blog publishing and management features',
+      categories: ['Blog'],
+    },
+    {
+      id: 'media',
+      label: 'Media',
+      description: 'Media library management',
+      categories: ['Media'],
+    },
+  ],
+}
+
+export default PERMISSIONS_CONFIG_OVERRIDES

package/config/theme.config.ts

@@ -0,0 +1,74 @@
+/**
+ * Boilerplate Theme Configuration
+ *
+ */
+
+import type { ThemeConfig } from '@nextsparkjs/core/types/theme'
+
+export const boilerplateThemeConfig: ThemeConfig = {
+  name: 'default',
+  displayName: 'Default',
+  version: '1.0.0',
+  description: 'Default neutral theme - black and white',
+  author: 'NextSpark Team',
+
+  plugins: ['langchain'],
+
+  // Styles configuration - colors come from globals.css only
+  styles: {
+    globals: 'globals.css',
+    components: 'components.css',
+    variables: {
+      // Custom spacing
+      '--spacing-xs': '0.125rem',
+      '--spacing-sm': '0.25rem',
+      '--spacing-md': '0.5rem',
+      '--spacing-lg': '1rem',
+      '--spacing-xl': '1.5rem',
+      '--spacing-2xl': '2rem'
+    }
+  },
+
+  // Theme configuration - NO colors here, they come from globals.css
+  config: {
+    // Typography
+    fonts: {
+      sans: 'system-ui, -apple-system, sans-serif',
+      serif: 'Georgia, serif',
+      mono: 'ui-monospace, monospace'
+    },
+
+    // Border radius
+    spacing: {
+      radius: '0.5rem',
+      'radius-sm': 'calc(0.5rem - 4px)',
+      'radius-md': 'calc(0.5rem - 2px)',
+      'radius-lg': '0.5rem',
+      'radius-xl': 'calc(0.5rem + 4px)'
+    }
+  },
+  
+  // Component overrides and custom components
+  components: {
+    overrides: {
+      // Override core shadcn/ui components with theme-specific versions
+      // '@nextsparkjs/core/components/ui/button': () => import('../components/overrides/Button').then(m => m.Button),
+      // '@nextsparkjs/core/components/ui/card': () => import('../components/overrides/Card').then(m => ({
+      //   Card: m.Card,
+      //   CardHeader: m.CardHeader,
+      //   CardTitle: m.CardTitle,
+      //   CardDescription: m.CardDescription,
+      //   CardContent: m.CardContent,
+      //   CardFooter: m.CardFooter
+      // }))
+    },
+    custom: {
+      // Custom theme-specific components
+      // CustomHeader: () => import('../components/custom/CustomHeader').then(m => m.CustomHeader),
+      // CustomFooter: () => import('../components/custom/CustomFooter').then(m => m.CustomFooter),
+      // BrandLogo: () => import('../components/custom/BrandLogo').then(m => m.BrandLogo)
+    }
+  }
+}
+
+export default boilerplateThemeConfig