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

package/dist/templates/contents/themes/starter/config/dashboard.config.ts

@@ -0,0 +1,419 @@
+/**
+ * Starter Theme - Dashboard Configuration
+ *
+ * Controls dashboard UI behavior: topbar, sidebar, settings pages, entity views.
+ * Customize the dashboard experience for your theme.
+ */
+
+export const DASHBOARD_CONFIG = {
+  // =============================================================================
+  // TOPBAR CONFIGURATION
+  // =============================================================================
+  topbar: {
+    /**
+     * Global search
+     */
+    search: {
+      enabled: true,
+      placeholder: 'dashboard.search.placeholder',
+      maxResults: 8,
+    },
+
+    /**
+     * Notifications
+     */
+    notifications: {
+      enabled: true,
+    },
+
+    /**
+     * Theme mode toggle (light/dark)
+     */
+    themeToggle: {
+      enabled: true,
+    },
+
+    /**
+     * Help/Support dropdown
+     */
+    support: {
+      enabled: true,
+      type: 'dropdown', // 'dropdown' | 'link' | 'modal'
+      links: [
+        {
+          label: 'common.help.documentation',
+          url: '/docs',
+          icon: 'book-open',
+          external: false,
+        },
+        {
+          label: 'common.help.support',
+          url: '/support',
+          icon: 'help-circle',
+          external: false,
+        },
+        {
+          label: 'common.help.keyboard',
+          action: 'showKeyboardShortcuts',
+          icon: 'keyboard',
+        },
+      ],
+    },
+
+    /**
+     * Quick create button
+     */
+    quickCreate: {
+      enabled: true,
+    },
+
+    /**
+     * Admin access button (Super Admin area)
+     */
+    adminAccess: {
+      enabled: true,
+      showToDevelopers: true,
+    },
+
+    /**
+     * Dev Zone access button (Developer area)
+     */
+    devtoolsAccess: {
+      enabled: true,
+    },
+
+    /**
+     * User menu
+     */
+    userMenu: {
+      enabled: true,
+      showAvatar: true,
+      showEmail: true,
+      showRole: false,
+      items: [
+        {
+          type: 'link',
+          label: 'navigation.profile',
+          href: '/dashboard/settings/profile',
+          icon: 'user',
+        },
+        {
+          type: 'link',
+          label: 'navigation.settings',
+          href: '/dashboard/settings',
+          icon: 'settings',
+        },
+        { type: 'divider' },
+        {
+          type: 'action',
+          label: 'buttons.signOut',
+          action: 'signOut',
+          icon: 'log-out',
+        },
+      ],
+    },
+  },
+
+  // =============================================================================
+  // SIDEBAR CONFIGURATION
+  // =============================================================================
+  sidebar: {
+    defaultCollapsed: false,
+    rememberState: true,
+    collapsedWidth: '60px',
+    expandedWidth: '240px',
+
+    toggle: {
+      enabled: true,
+      showInTopbar: true,
+      hideOnMobile: false,
+    },
+
+    navigation: {
+      showEntityCounts: true,
+      groupEntities: true,
+      showRecents: true,
+      maxRecents: 5,
+
+      /**
+       * Custom navigation sections
+       * These are added to the sidebar in addition to entity navigation
+       */
+      sections: [
+        {
+          id: 'analytics',
+          label: 'common.navigation.analytics',
+          icon: 'BarChart3',
+          href: '/analytics',
+          enabled: true,
+        },
+      ],
+    },
+  },
+
+  // =============================================================================
+  // SETTINGS PAGES
+  // =============================================================================
+  settings: {
+    pages: {
+      profile: {
+        enabled: true,
+        label: 'settings.pages.profile',
+        description: 'settings.pages.profileDescription',
+        icon: 'user',
+        order: 1,
+        features: {
+          avatarUpload: true,
+          nameChange: true,
+          emailChange: true,
+          localeChange: true,
+          timezoneChange: false,
+        },
+      },
+
+      password: {
+        enabled: true,
+        label: 'settings.pages.password',
+        description: 'settings.pages.passwordDescription',
+        icon: 'key',
+        order: 2,
+        features: {
+          passwordChange: true,
+          passwordStrength: true,
+          passwordHistory: false,
+        },
+      },
+
+      'api-keys': {
+        enabled: true,
+        label: 'settings.pages.apiKeys',
+        description: 'settings.pages.apiKeysDescription',
+        icon: 'key',
+        order: 3,
+        features: {
+          createKeys: true,
+          revokeKeys: true,
+          scopeManagement: true,
+          usageAnalytics: true,
+        },
+      },
+
+      billing: {
+        enabled: true,
+        label: 'settings.pages.billing',
+        description: 'settings.pages.billingDescription',
+        icon: 'credit-card',
+        order: 4,
+        features: {
+          subscriptionManagement: true,
+          paymentMethods: true,
+          invoiceHistory: true,
+          usageMetrics: true,
+        },
+        requiredRole: 'admin',
+      },
+
+      teams: {
+        enabled: true,
+        label: 'settings.pages.teams',
+        description: 'settings.pages.teamsDescription',
+        icon: 'users',
+        order: 5,
+        features: {
+          createTeams: true,
+          manageMembers: true,
+          inviteMembers: true,
+          teamSettings: true,
+        },
+      },
+    },
+
+    layout: {
+      showDescription: true,
+      showIcons: true,
+      groupByCategory: false,
+      enableSearch: true,
+    },
+  },
+
+  // =============================================================================
+  // ENTITY PAGES DEFAULTS
+  // =============================================================================
+  entities: {
+    defaultListView: {
+      pagination: {
+        defaultPageSize: 20,
+        allowedPageSizes: [10, 20, 50, 100],
+        showSizeSelector: true,
+      },
+      sorting: {
+        enabled: true,
+        defaultSort: { field: 'createdAt', direction: 'desc' },
+        rememberSort: true,
+      },
+      filtering: {
+        enabled: true,
+        quickFilters: true,
+        advancedFilters: true,
+        rememberFilters: false,
+      },
+      search: {
+        enabled: true,
+        placeholder: 'dashboard.entities.searchPlaceholder',
+        searchableFields: ['name', 'title', 'description', 'email'],
+        instantSearch: true,
+        debounceMs: 300,
+      },
+    },
+
+    defaultFormView: {
+      validation: {
+        validateOnBlur: true,
+        validateOnChange: false,
+        showFieldErrors: true,
+        showFormErrors: true,
+      },
+      autosave: {
+        enabled: false,
+        intervalMs: 30000,
+        showIndicator: true,
+      },
+      confirmation: {
+        showOnCreate: false,
+        showOnUpdate: true,
+        showOnDelete: true,
+      },
+    },
+
+    /**
+     * Per-entity customizations
+     * Override defaults for specific entities
+     */
+    customizations: {
+      tasks: {
+        listView: {
+          defaultSort: { field: 'priority', direction: 'desc' },
+          quickFilters: ['status', 'priority', 'assignee'],
+        },
+      },
+    },
+  },
+
+  // =============================================================================
+  // HOMEPAGE WIDGETS
+  // =============================================================================
+  homepage: {
+    widgets: {
+      welcome: {
+        enabled: true,
+        showUserName: true,
+        showLastLogin: true,
+        showQuickActions: true,
+      },
+
+      stats: {
+        enabled: true,
+        entities: ['tasks'],
+        timeframe: '30days',
+        showTrends: true,
+      },
+
+      recentActivity: {
+        enabled: true,
+        maxItems: 10,
+        entities: ['tasks'],
+        showTimestamps: true,
+      },
+
+      quickActions: {
+        enabled: true,
+        actions: [
+          { entity: 'tasks', action: 'create', label: 'dashboard.quickActions.createTask' },
+        ],
+      },
+    },
+
+    layout: {
+      columns: 3,
+      gutter: 'medium',
+      responsive: true,
+    },
+  },
+
+  // =============================================================================
+  // PERFORMANCE & BEHAVIOR
+  // =============================================================================
+  performance: {
+    cache: {
+      entityConfigs: { enabled: true, duration: 5 * 60 * 1000 },
+      entityData: { enabled: true, duration: 2 * 60 * 1000 },
+    },
+    loading: {
+      showSkeletons: true,
+      showProgressBars: true,
+      minimumLoadingTime: 300,
+    },
+    errors: {
+      showErrorBoundaries: true,
+      logErrors: true,
+      enableRetry: true,
+      maxRetries: 3,
+    },
+  },
+
+  // =============================================================================
+  // ACCESSIBILITY
+  // =============================================================================
+  accessibility: {
+    keyboard: {
+      enabled: true,
+      showShortcuts: true,
+      customShortcuts: {
+        'Ctrl+K': 'openSearch',
+        'Ctrl+Shift+N': 'quickCreate',
+        'Ctrl+B': 'toggleSidebar',
+        Esc: 'closeModals',
+      },
+    },
+    screenReader: {
+      announceNavigation: true,
+      announceActions: true,
+      announceErrors: true,
+    },
+    visual: {
+      showFocusOutlines: true,
+      highContrastMode: false,
+      reducedMotion: false,
+    },
+  },
+} as const
+
+// =============================================================================
+// CONVENIENCE EXPORTS
+// =============================================================================
+export const TOPBAR_CONFIG = DASHBOARD_CONFIG.topbar
+export const SIDEBAR_CONFIG = DASHBOARD_CONFIG.sidebar
+export const SETTINGS_CONFIG = DASHBOARD_CONFIG.settings
+export const ENTITIES_CONFIG = DASHBOARD_CONFIG.entities
+export const HOMEPAGE_CONFIG = DASHBOARD_CONFIG.homepage
+
+export const isSettingsPageEnabled = (
+  pageKey: keyof typeof DASHBOARD_CONFIG.settings.pages
+): boolean => {
+  return DASHBOARD_CONFIG.settings.pages[pageKey]?.enabled ?? false
+}
+
+export const getEnabledSettingsPages = () => {
+  return Object.entries(DASHBOARD_CONFIG.settings.pages)
+    .filter(([_, config]) => config.enabled)
+    .sort((a, b) => a[1].order - b[1].order)
+    .map(([key, config]) => ({ key, ...config }))
+}
+
+export const isTopbarFeatureEnabled = (
+  feature: keyof typeof DASHBOARD_CONFIG.topbar
+): boolean => {
+  return DASHBOARD_CONFIG.topbar[feature]?.enabled ?? false
+}
+
+export default DASHBOARD_CONFIG

package/dist/templates/contents/themes/starter/config/dev.config.ts

@@ -0,0 +1,74 @@
+/**
+ * Starter Theme - Development Configuration
+ *
+ * This file contains development-only settings that should never affect production.
+ * Settings like DevKeyring are only rendered in non-production environments.
+ *
+ * @see core/lib/config/types.ts for DevConfig interface
+ */
+
+import type { DevConfig } from '@nextsparkjs/core/lib/config/types'
+
+export const DEV_CONFIG_OVERRIDES: DevConfig = {
+  // =============================================================================
+  // DEV KEYRING (Development/QA Only)
+  // =============================================================================
+  /**
+   * DevKeyring - Quick login users for development and testing
+   *
+   * These users should match entries in your sample data migrations.
+   * The component is only rendered in non-production environments.
+   *
+   * User structure:
+   * - id: Unique identifier for the user button
+   * - email: User's email address (must exist in database)
+   * - name: Display name shown in the keyring
+   * - password: Password for auto-fill
+   * - teamRoles: Description of team memberships (for reference)
+   */
+  devKeyring: {
+    enabled: true,
+    users: [
+      // ========================================
+      // STARTER THEME TEST USERS
+      // ========================================
+      {
+        id: 'superadmin',
+        email: 'superadmin@starter.dev',
+        name: 'Super Admin',
+        password: 'Test1234',
+        teamRoles: 'Starter Team (owner) - SUPERADMIN ROLE',
+      },
+      {
+        id: 'developer',
+        email: 'developer@starter.dev',
+        name: 'Developer',
+        password: 'Test1234',
+        teamRoles: 'Starter Team (admin) - DEVELOPER ROLE',
+      },
+      {
+        id: 'owner',
+        email: 'owner@starter.dev',
+        name: 'Team Owner',
+        password: 'Test1234',
+        teamRoles: 'Starter Team (owner)',
+      },
+      {
+        id: 'admin',
+        email: 'admin@starter.dev',
+        name: 'Team Admin',
+        password: 'Test1234',
+        teamRoles: 'Starter Team (admin)',
+      },
+      {
+        id: 'member',
+        email: 'member@starter.dev',
+        name: 'Team Member',
+        password: 'Test1234',
+        teamRoles: 'Starter Team (member)',
+      },
+    ],
+  },
+}
+
+export default DEV_CONFIG_OVERRIDES

package/dist/templates/contents/themes/starter/config/permissions.config.ts

@@ -0,0 +1,64 @@
+/**
+ * Starter 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 (tasks)
+ * - features: Theme-specific feature permissions
+ *
+ * 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 = {
+  // ==========================================
+  // 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'] },
+    { action: 'team.members.view', label: 'View Members', description: 'Can see team member list', roles: ['owner', 'admin', 'member', 'viewer'] },
+    { action: 'team.settings.view', label: 'View Settings', description: 'Can view team settings', roles: ['owner', 'admin', 'member'] },
+    { 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
+  // ==========================================
+  // Define CRUD permissions for each entity in your theme
+  entities: {
+    // ------------------------------------------
+    // TASKS ENTITY
+    // ------------------------------------------
+    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', 'viewer'] },
+      { action: 'list', label: 'List tasks', description: 'Can see the tasks list', roles: ['owner', 'admin', 'member', 'viewer'] },
+      { 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'] },
+    ],
+  },
+}
+
+export default PERMISSIONS_CONFIG_OVERRIDES

package/dist/templates/contents/themes/starter/config/theme.config.ts

@@ -0,0 +1,83 @@
+/**
+ * Starter Theme Configuration
+ *
+ * Theme visual configuration: colors, typography, spacing, and component overrides.
+ * This file defines the look and feel of your theme.
+ */
+
+import type { ThemeConfig } from '@nextsparkjs/core/types/theme'
+
+export const starterThemeConfig: ThemeConfig = {
+  // ==========================================
+  // BASIC IDENTIFICATION
+  // ==========================================
+  name: 'starter',
+  displayName: 'Starter',
+  version: '1.0.0',
+  description: 'Minimal starter theme for NextSpark',
+  author: 'NextSpark Team',
+
+  // ==========================================
+  // PLUGINS (Optional)
+  // ==========================================
+  plugins: [],
+
+  // ==========================================
+  // STYLES CONFIGURATION
+  // ==========================================
+  styles: {
+    globals: 'globals.css',
+    components: 'components.css',
+    variables: {
+      '--spacing-xs': '0.125rem',
+      '--spacing-sm': '0.25rem',
+      '--spacing-md': '0.5rem',
+      '--spacing-lg': '1rem',
+      '--spacing-xl': '1.5rem',
+      '--spacing-2xl': '2rem',
+    },
+  },
+
+  // ==========================================
+  // THEME CONFIGURATION
+  // ==========================================
+  // Colors come from globals.css - no need to define here
+  // This section is for typography and spacing overrides
+  config: {
+    // ------------------------------------------
+    // TYPOGRAPHY
+    // ------------------------------------------
+    fonts: {
+      sans: 'system-ui, -apple-system, sans-serif',
+      serif: 'Georgia, serif',
+      mono: 'ui-monospace, monospace',
+    },
+
+    // ------------------------------------------
+    // SPACING (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 (Optional)
+  // ==========================================
+  components: {
+    overrides: {
+      // Override core shadcn/ui components with theme-specific versions:
+      // '@nextsparkjs/core/components/ui/button': () => import('../components/overrides/Button').then(m => m.Button),
+    },
+    custom: {
+      // Custom theme-specific components:
+      // CustomHeader: () => import('../components/custom/CustomHeader').then(m => m.CustomHeader),
+    },
+  },
+}
+
+export default starterThemeConfig

package/dist/templates/contents/themes/starter/docs/01-overview/01-introduction.md

@@ -0,0 +1,33 @@
+# Starter Theme Introduction
+
+Welcome to the Starter theme for NextSpark. This minimal theme provides everything you need to begin building your application.
+
+## Features
+
+- **Tasks Entity**: A complete example entity with CRUD operations
+- **Analytics Dashboard**: Custom dashboard page example
+- **Hero Block**: Page builder block example
+- **Multi-language Support**: Translations in 6 languages (en, es, fr, it, de, pt)
+- **Cypress Tests**: Complete test infrastructure
+
+## Getting Started
+
+1. Install dependencies: `pnpm install`
+2. Configure environment: `cp .env.example .env.local`
+3. Run migrations: `pnpm db:migrate`
+4. Start development: `pnpm dev`
+
+## Project Structure
+
+```
+starter/
+├── config/         # Theme configuration files
+├── entities/       # Entity definitions (tasks)
+├── blocks/         # Page builder blocks (hero)
+├── templates/      # Page templates (public, dashboard)
+├── messages/       # i18n translations
+├── lib/            # Utilities and hooks
+├── tests/          # Cypress test suite
+├── styles/         # CSS files
+└── docs/           # Documentation
+```