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

package/templates/contents/themes/starter/config/app.config.ts

@@ -0,0 +1,193 @@
+/**
+ * Starter Theme - Application Configuration
+ *
+ * This file allows the theme to override core application configuration values.
+ * Only include properties you want to override - missing properties will use core defaults.
+ *
+ * Related config files:
+ * - permissions.config.ts: Roles, team/entity/feature permissions (Single Source of Truth)
+ * - billing.config.ts: Plans, features, limits, subscriptions
+ * - dashboard.config.ts: UI configuration (topbar, sidebar, settings)
+ * - dev.config.ts: Development tools (devKeyring, debug settings)
+ * - theme.config.ts: Visual styling (colors, fonts, spacing)
+ */
+
+export const APP_CONFIG_OVERRIDES = {
+  // =============================================================================
+  // APPLICATION METADATA
+  // =============================================================================
+  app: {
+    name: 'Starter',
+    version: '1.0.0',
+  },
+
+  // =============================================================================
+  // TEAMS CONFIGURATION
+  // =============================================================================
+  /**
+   * Team modes available:
+   * - 'multi-tenant': Multiple teams, team switching enabled (e.g., CRM, Project Management)
+   * - 'single-tenant': One organization, no team switching (e.g., Internal tools)
+   * - 'single-user': Personal app, no teams (e.g., Blog, Personal dashboard)
+   */
+  teams: {
+    mode: 'multi-tenant' as const,
+    /**
+     * Available team roles for this theme
+     * Core roles: owner, admin, member, viewer
+     * Custom roles can be added here and configured in permissions.config.ts
+     */
+    availableTeamRoles: ['owner', 'admin', 'member', 'viewer'],
+    options: {
+      maxMembersPerTeam: 50,
+      allowLeaveTeam: true,
+      allowCreateTeams: true,
+    },
+  },
+
+  // =============================================================================
+  // INTERNATIONALIZATION
+  // =============================================================================
+  i18n: {
+    /**
+     * Supported locales for your theme
+     */
+    supportedLocales: ['en', 'es', 'fr', 'it', 'de', 'pt'],
+
+    /**
+     * Default locale
+     */
+    defaultLocale: 'en' as const,
+
+    /**
+     * Translation namespaces used by this theme
+     * Core namespaces are automatically included
+     */
+    namespaces: [
+      'common',
+      'dashboard',
+      'settings',
+      'auth',
+      'public',
+      'validation',
+      // Theme-specific namespaces:
+      'tasks',
+    ],
+  },
+
+  // =============================================================================
+  // API CONFIGURATION
+  // =============================================================================
+  api: {
+    cors: {
+      allowedOrigins: {
+        development: [
+          'http://localhost:3000',
+          'http://localhost:5173',
+          'http://127.0.0.1:3000',
+          'http://127.0.0.1:5173',
+        ],
+        production: [
+          // Add production domains:
+          // 'https://your-domain.com',
+        ],
+      },
+    },
+  },
+
+  // =============================================================================
+  // DOCUMENTATION
+  // =============================================================================
+  docs: {
+    enabled: true,
+    public: true,
+    searchEnabled: true,
+    breadcrumbs: true,
+    theme: {
+      enabled: true,
+      open: true,
+      label: 'Starter',
+    },
+    plugins: {
+      enabled: true,
+      open: false,
+      label: 'Plugins',
+    },
+    core: {
+      enabled: true,
+      open: true,
+      label: 'Core',
+    },
+  },
+
+  // =============================================================================
+  // MOBILE NAVIGATION
+  // =============================================================================
+  mobileNav: {
+    /**
+     * Bottom navigation bar items
+     * Icon names use lucide-react icons (https://lucide.dev)
+     */
+    items: [
+      {
+        id: 'home',
+        labelKey: 'common.mobileNav.home',
+        href: '/dashboard',
+        icon: 'Home',
+        enabled: true,
+      },
+      {
+        id: 'create',
+        labelKey: 'common.mobileNav.create',
+        icon: 'Plus',
+        isCentral: true,
+        action: 'quickCreate',
+        enabled: true,
+      },
+      {
+        id: 'settings',
+        labelKey: 'common.mobileNav.settings',
+        href: '/dashboard/settings',
+        icon: 'Settings',
+        enabled: true,
+      },
+      {
+        id: 'more',
+        labelKey: 'common.mobileNav.more',
+        icon: 'Menu',
+        action: 'moreSheet',
+        enabled: true,
+      },
+    ],
+
+    /**
+     * "More" sheet secondary navigation items
+     */
+    moreSheetItems: [
+      {
+        id: 'profile',
+        labelKey: 'common.navigation.profile',
+        href: '/dashboard/settings/profile',
+        icon: 'User',
+        enabled: true,
+      },
+      {
+        id: 'billing',
+        labelKey: 'common.navigation.billing',
+        href: '/dashboard/settings/billing',
+        icon: 'CreditCard',
+        enabled: true,
+      },
+      {
+        id: 'help',
+        labelKey: 'common.navigation.help',
+        href: '/support',
+        icon: 'HelpCircle',
+        enabled: false,
+        external: true,
+      },
+    ],
+  },
+}
+
+export default APP_CONFIG_OVERRIDES

package/templates/contents/themes/starter/config/billing.config.ts

@@ -0,0 +1,93 @@
+/**
+ * Starter Theme - Billing Configuration
+ *
+ * This is a free-only billing configuration for the starter theme.
+ * No paid plans are defined - all features are available for free.
+ *
+ * The three-layer model:
+ * RESULT = Permission (RBAC) AND Feature (Plan) AND Quota (Limits)
+ */
+
+import type { BillingConfig } from '@nextsparkjs/core/lib/billing/config-types'
+
+export const billingConfig: BillingConfig = {
+  provider: 'stripe',
+  currency: 'usd',
+  defaultPlan: 'free',
+
+  // ===========================================
+  // FEATURE DEFINITIONS
+  // ===========================================
+  // All features are available in the free plan for the starter theme
+  features: {
+    basic_analytics: {
+      name: 'billing.features.basic_analytics',
+      description: 'billing.features.basic_analytics_description',
+    },
+    api_access: {
+      name: 'billing.features.api_access',
+      description: 'billing.features.api_access_description',
+    },
+  },
+
+  // ===========================================
+  // LIMIT DEFINITIONS
+  // ===========================================
+  limits: {
+    team_members: {
+      name: 'billing.limits.team_members',
+      unit: 'count',
+      resetPeriod: 'never',
+    },
+    tasks: {
+      name: 'billing.limits.tasks',
+      unit: 'count',
+      resetPeriod: 'never',
+    },
+    api_calls: {
+      name: 'billing.limits.api_calls',
+      unit: 'calls',
+      resetPeriod: 'monthly',
+    },
+    storage_gb: {
+      name: 'billing.limits.storage',
+      unit: 'bytes',
+      resetPeriod: 'never',
+    },
+  },
+
+  // ===========================================
+  // PLAN DEFINITIONS
+  // ===========================================
+  // Free-only: No paid plans for the starter theme
+  plans: [],
+
+  // ===========================================
+  // ACTION MAPPINGS
+  // ===========================================
+  // Maps user actions to RBAC permissions, plan features, and limits.
+  // Three-layer model: RESULT = Permission AND Feature AND Quota
+  actionMappings: {
+    // RBAC permissions (integrates with permissions.config.ts)
+    permissions: {
+      'team.members.invite': 'team.members.invite',
+      'team.settings.edit': 'team.settings.edit',
+      'team.billing.manage': 'team.billing.manage',
+    },
+
+    // Feature requirements per action
+    features: {
+      'analytics.view': 'basic_analytics',
+      'api.generate_key': 'api_access',
+    },
+
+    // Limit consumption per action
+    limits: {
+      'team.members.invite': 'team_members',
+      'tasks.create': 'tasks',
+      'api.call': 'api_calls',
+    },
+  },
+}
+
+export default billingConfig

package/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