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

package/dist/templates/contents/themes/starter/README.md

@@ -0,0 +1,35 @@
+# Starter Theme
+
+A minimal NextSpark theme to kickstart your project.
+
+## Features
+
+- **Tasks Entity** - Complete example with CRUD
+- **Analytics Dashboard** - Custom dashboard page
+- **Hero Block** - Page builder block example
+- **6 Languages** - en, es, fr, it, de, pt
+- **Cypress Tests** - Full test infrastructure
+
+## Quick Start
+
+```bash
+# Install dependencies
+pnpm install
+
+# Configure environment
+cp .env.example .env.local
+
+# Run migrations
+pnpm db:migrate
+
+# Start development
+pnpm dev
+```
+
+## Documentation
+
+See `docs/` folder for detailed documentation.
+
+## License
+
+MIT

package/dist/templates/contents/themes/starter/about/business.md

@@ -0,0 +1,16 @@
+# Starter Theme
+
+A minimal NextSpark theme designed to help you get started quickly.
+
+## Use Cases
+
+- Internal tools
+- SaaS applications
+- Project management
+- Team collaboration
+
+## Target Audience
+
+- Developers building new applications
+- Teams needing a quick start template
+- Projects requiring multi-language support

package/dist/templates/contents/themes/starter/about/features.json

@@ -0,0 +1,28 @@
+{
+  "features": [
+    {
+      "id": "tasks",
+      "title": "Task Management",
+      "description": "Complete task management with status tracking, priorities, and due dates",
+      "icon": "CheckSquare"
+    },
+    {
+      "id": "analytics",
+      "title": "Analytics Dashboard",
+      "description": "Visual analytics to track team productivity and task completion",
+      "icon": "BarChart3"
+    },
+    {
+      "id": "teams",
+      "title": "Team Collaboration",
+      "description": "Multi-tenant support with role-based access control",
+      "icon": "Users"
+    },
+    {
+      "id": "i18n",
+      "title": "Multi-language",
+      "description": "Built-in support for 6 languages with easy extensibility",
+      "icon": "Globe"
+    }
+  ]
+}

package/dist/templates/contents/themes/starter/blocks/hero/component.tsx

@@ -0,0 +1,112 @@
+import React from 'react'
+import { Button } from '@nextsparkjs/core/components/ui/button'
+import { cn } from '@nextsparkjs/core/lib/utils'
+import { buildSectionClasses } from '@nextsparkjs/core/types/blocks'
+import { sel } from '../../lib/selectors'
+import type { HeroBlockProps } from './schema'
+
+/**
+ * Hero Block Component
+ *
+ * Props from 3-tab structure:
+ * - Content: title, content, cta
+ * - Design: backgroundColor, backgroundImage, textColor, alignment
+ * - Advanced: className, id
+ */
+export function HeroBlock({
+  // Base content props
+  title,
+  content,
+  cta,
+  // Base design props
+  backgroundColor,
+  // Hero-specific design
+  backgroundImage,
+  textColor = 'light',
+  alignment = 'center',
+  // Base advanced props
+  className,
+  id,
+  // Legacy props for backward compatibility
+  ...legacyProps
+}: HeroBlockProps & {
+  ctaText?: string
+  ctaLink?: string
+  subtitle?: string
+  description?: string
+}) {
+  // Handle legacy CTA format (ctaText, ctaLink) for backward compatibility
+  const ctaConfig = cta || (legacyProps.ctaText ? {
+    text: legacyProps.ctaText,
+    link: legacyProps.ctaLink || '#',
+    target: '_self' as const,
+  } : undefined)
+
+  // Handle legacy subtitle/description props for backward compatibility
+  const displayContent = content || legacyProps.subtitle || legacyProps.description
+
+  // Alignment classes mapping
+  const alignmentClasses = {
+    left: 'text-left items-start',
+    center: 'text-center items-center',
+    right: 'text-right items-end',
+  }
+
+  // Build section classes with background and custom className
+  const sectionClasses = buildSectionClasses(
+    cn(
+      'relative flex min-h-[600px] items-center justify-center overflow-hidden px-4 py-20',
+      textColor === 'light' ? 'text-white dark:text-white' : 'text-gray-900 dark:text-gray-100'
+    ),
+    { backgroundColor, className }
+  )
+
+  return (
+    <section id={id} className={sectionClasses} data-cy={sel('blocks.hero.container')}>
+      {/* Background Image */}
+      {backgroundImage && (
+        <div
+          className="absolute inset-0 z-0"
+          style={{
+            backgroundImage: `url(${backgroundImage})`,
+            backgroundSize: 'cover',
+            backgroundPosition: 'center',
+          }}
+        >
+          <div className="absolute inset-0 bg-black/40 dark:bg-black/60" />
+        </div>
+      )}
+
+      {/* Content */}
+      <div className={cn(
+        'container relative z-10 mx-auto max-w-4xl flex flex-col',
+        alignmentClasses[alignment]
+      )}>
+        {title && (
+          <h1 className="mb-6 text-5xl font-bold leading-tight md:text-6xl lg:text-7xl">
+            {title}
+          </h1>
+        )}
+
+        {displayContent && (
+          <p className="mb-8 text-xl md:text-2xl opacity-90 max-w-2xl">
+            {displayContent}
+          </p>
+        )}
+
+        {ctaConfig && (
+          <Button asChild size="lg" className="text-lg px-8 py-6">
+            <a
+              href={ctaConfig.link}
+              target={ctaConfig.target}
+              rel={ctaConfig.target === '_blank' ? 'noopener noreferrer' : undefined}
+              data-cy={sel('blocks.hero.cta')}
+            >
+              {ctaConfig.text}
+            </a>
+          </Button>
+        )}
+      </div>
+    </section>
+  )
+}

package/dist/templates/contents/themes/starter/blocks/hero/config.ts

@@ -0,0 +1,11 @@
+import type { BlockConfig } from '@nextsparkjs/core/types/blocks'
+
+export const config: Omit<BlockConfig, 'schema' | 'fieldDefinitions' | 'Component' | 'examples'> = {
+  slug: 'hero',
+  name: 'Hero Section',
+  description: 'Full-width hero section with title, subtitle, CTA button, and background image',
+  category: 'hero',
+  icon: 'Rocket',
+  thumbnail: '/theme/blocks/hero/thumbnail.png',
+  scope: ['pages', 'posts']
+}

package/dist/templates/contents/themes/starter/blocks/hero/fields.ts

@@ -0,0 +1,74 @@
+import type { FieldDefinition } from '@nextsparkjs/core/types/blocks'
+import {
+  baseContentFields,
+  baseDesignFields,
+  baseAdvancedFields,
+} from '@nextsparkjs/core/types/blocks'
+
+/**
+ * Hero Block Field Definitions
+ *
+ * Organized into 3 tabs:
+ * - Content: title, content, cta (from base)
+ * - Design: backgroundColor (from base) + backgroundImage, textColor, alignment
+ * - Advanced: className, id (from base)
+ *
+ * Note: The `content` field from base serves as the hero subtitle/description
+ */
+
+// Hero-specific design fields
+const heroDesignFields: FieldDefinition[] = [
+  {
+    name: 'backgroundImage',
+    label: 'Background Image',
+    type: 'image',
+    tab: 'design',
+    required: false,
+    helpText: 'Optional background image (recommended: 1920x1080px minimum)',
+  },
+  {
+    name: 'textColor',
+    label: 'Text Color',
+    type: 'select',
+    tab: 'design',
+    required: false,
+    default: 'light',
+    helpText: 'Choose text color based on background',
+    options: [
+      { label: 'Light (for dark backgrounds)', value: 'light' },
+      { label: 'Dark (for light backgrounds)', value: 'dark' },
+    ],
+  },
+  {
+    name: 'alignment',
+    label: 'Text Alignment',
+    type: 'select',
+    tab: 'design',
+    required: false,
+    default: 'center',
+    helpText: 'Horizontal alignment of the hero content',
+    options: [
+      { label: 'Left', value: 'left' },
+      { label: 'Center', value: 'center' },
+      { label: 'Right', value: 'right' },
+    ],
+  },
+]
+
+/**
+ * Complete field definitions organized by tab
+ */
+export const fieldDefinitions: FieldDefinition[] = [
+  // Content tab: base fields only (title, content, cta)
+  ...baseContentFields,
+
+  // Design tab: base fields + hero-specific
+  ...baseDesignFields,
+  ...heroDesignFields,
+
+  // Advanced tab: base fields only
+  ...baseAdvancedFields,
+]
+
+// Alias for compatibility
+export const fields = fieldDefinitions

package/dist/templates/contents/themes/starter/blocks/hero/index.ts

@@ -0,0 +1,6 @@
+export { config } from './config'
+export { schema } from './schema'
+export { fields } from './fields'
+export { HeroBlock as Component } from './component'
+
+export type { HeroBlockProps } from './schema'

package/dist/templates/contents/themes/starter/blocks/hero/schema.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod'
+import {
+  baseBlockSchema,
+  type BaseBlockProps,
+} from '@nextsparkjs/core/types/blocks'
+
+/**
+ * Hero Block Schema
+ *
+ * Extends base schema with hero-specific fields:
+ * - backgroundImage: Optional hero background
+ * - textColor: Light/dark for contrast
+ * - alignment: Text alignment (left, center, right)
+ *
+ * Note: Uses base schema title, content, cta, backgroundColor, className, id
+ * The `content` field serves as the hero subtitle/description
+ */
+export const heroSpecificSchema = z.object({
+  // Hero-specific design fields
+  backgroundImage: z.string().url('Must be a valid URL').optional(),
+  textColor: z.enum(['light', 'dark']).default('light'),
+  alignment: z.enum(['left', 'center', 'right']).default('center'),
+})
+
+/**
+ * Complete Hero Block Schema
+ * Combines base fields + hero-specific fields
+ */
+export const schema = baseBlockSchema.merge(heroSpecificSchema)
+
+export type HeroBlockProps = z.infer<typeof schema>
+
+// Also export for type-only imports
+export type { BaseBlockProps }

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