@nextsparkjs/theme-blog 0.1.0-beta.1

package/config/flows.config.ts

@@ -0,0 +1,333 @@
+/**
+ * Blog 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: 'Author Onboarding',
+    description: 'Complete journey from signup to first published post',
+    category: 'acquisition',
+    icon: 'rocket',
+    criticalPath: true,
+
+    steps: [
+      {
+        feature: 'auth',
+        action: 'signup',
+        description: 'Author creates account with email/password',
+      },
+      {
+        feature: 'auth',
+        action: 'verify-email',
+        description: 'Author verifies email address',
+      },
+      {
+        feature: 'users',
+        action: 'setup-profile',
+        description: 'Author sets up their profile (bio, avatar)',
+        optional: true,
+      },
+      {
+        feature: 'posts',
+        action: 'create-first-post',
+        description: 'Author creates their first blog post',
+      },
+    ],
+
+    features: ['auth', 'users', 'posts'],
+  },
+
+  // ===========================================================================
+  // CONTENT CREATION FLOWS
+  // Post creation and publishing journeys
+  // ===========================================================================
+
+  'create-post': {
+    name: 'Create Post',
+    description: 'Complete journey to create and publish a blog post',
+    category: 'content',
+    icon: 'edit',
+    criticalPath: true,
+
+    steps: [
+      {
+        feature: 'posts',
+        action: 'create-draft',
+        description: 'Author creates a new draft post',
+      },
+      {
+        feature: 'post-editor',
+        action: 'write-content',
+        description: 'Author writes post content using the editor',
+      },
+      {
+        feature: 'post-editor',
+        action: 'add-featured-image',
+        description: 'Author adds featured image',
+        optional: true,
+      },
+      {
+        feature: 'categories',
+        action: 'assign-category',
+        description: 'Author assigns categories to the post',
+        optional: true,
+      },
+      {
+        feature: 'publishing',
+        action: 'publish',
+        description: 'Author publishes the post',
+      },
+    ],
+
+    features: ['posts', 'post-editor', 'categories', 'publishing'],
+  },
+
+  'edit-post': {
+    name: 'Edit Post',
+    description: 'Edit and update an existing post',
+    category: 'content',
+    icon: 'pencil',
+    criticalPath: false,
+
+    steps: [
+      {
+        feature: 'posts',
+        action: 'select-post',
+        description: 'Author selects a post to edit',
+      },
+      {
+        feature: 'post-editor',
+        action: 'modify-content',
+        description: 'Author modifies post content',
+      },
+      {
+        feature: 'posts',
+        action: 'save-changes',
+        description: 'Author saves the updated post',
+      },
+    ],
+
+    features: ['posts', 'post-editor'],
+  },
+
+  // ===========================================================================
+  // PUBLISHING FLOWS
+  // Content publishing workflows
+  // ===========================================================================
+
+  'publish-workflow': {
+    name: 'Publishing Workflow',
+    description: 'Manage post status from draft to published',
+    category: 'content',
+    icon: 'send',
+    criticalPath: true,
+
+    steps: [
+      {
+        feature: 'posts',
+        action: 'review-draft',
+        description: 'Author reviews draft post',
+      },
+      {
+        feature: 'publishing',
+        action: 'set-publish-date',
+        description: 'Author sets publish date (optional)',
+        optional: true,
+      },
+      {
+        feature: 'publishing',
+        action: 'publish',
+        description: 'Author publishes the post',
+      },
+    ],
+
+    features: ['posts', 'publishing'],
+  },
+
+  unpublish: {
+    name: 'Unpublish Post',
+    description: 'Take a published post offline',
+    category: 'content',
+    icon: 'eye-off',
+    criticalPath: false,
+
+    steps: [
+      {
+        feature: 'posts',
+        action: 'select-published-post',
+        description: 'Author selects a published post',
+      },
+      {
+        feature: 'publishing',
+        action: 'unpublish',
+        description: 'Author unpublishes the post (reverts to draft)',
+      },
+    ],
+
+    features: ['posts', 'publishing'],
+  },
+
+  // ===========================================================================
+  // DATA MANAGEMENT FLOWS
+  // Import/export workflows
+  // ===========================================================================
+
+  'export-content': {
+    name: 'Export Content',
+    description: 'Export blog content for backup or migration',
+    category: 'settings',
+    icon: 'download',
+    criticalPath: false,
+
+    steps: [
+      {
+        feature: 'post-export',
+        action: 'select-content',
+        description: 'Author selects content to export',
+      },
+      {
+        feature: 'post-export',
+        action: 'export',
+        description: 'Author downloads the exported JSON file',
+      },
+    ],
+
+    features: ['post-export'],
+  },
+
+  'import-content': {
+    name: 'Import Content',
+    description: 'Import blog content from backup file',
+    category: 'settings',
+    icon: 'upload',
+    criticalPath: false,
+
+    steps: [
+      {
+        feature: 'post-import',
+        action: 'select-file',
+        description: 'Author selects JSON file to import',
+      },
+      {
+        feature: 'post-import',
+        action: 'review-content',
+        description: 'Author reviews content to be imported',
+      },
+      {
+        feature: 'post-import',
+        action: 'confirm-import',
+        description: 'Author confirms and executes import',
+      },
+    ],
+
+    features: ['post-import'],
+  },
+
+  // ===========================================================================
+  // PUBLIC READING FLOWS
+  // Reader-facing journeys
+  // ===========================================================================
+
+  'read-post': {
+    name: 'Read Post',
+    description: 'Public reader views a blog post',
+    category: 'public',
+    icon: 'book-open',
+    criticalPath: true,
+
+    steps: [
+      {
+        feature: 'public-blog',
+        action: 'browse-posts',
+        description: 'Reader browses blog homepage or category',
+      },
+      {
+        feature: 'public-blog',
+        action: 'select-post',
+        description: 'Reader clicks on a post to read',
+      },
+      {
+        feature: 'public-blog',
+        action: 'read-content',
+        description: 'Reader reads the full post content',
+      },
+    ],
+
+    features: ['public-blog'],
+  },
+
+  'view-author': {
+    name: 'View Author',
+    description: 'Reader views an author profile and their posts',
+    category: 'public',
+    icon: 'user',
+    criticalPath: false,
+
+    steps: [
+      {
+        feature: 'authors',
+        action: 'view-profile',
+        description: 'Reader views author profile page',
+      },
+      {
+        feature: 'authors',
+        action: 'browse-author-posts',
+        description: 'Reader browses posts by this author',
+      },
+    ],
+
+    features: ['authors', 'public-blog'],
+  },
+
+  // ===========================================================================
+  // BILLING FLOWS
+  // Subscription and payment journeys
+  // ===========================================================================
+
+  'upgrade-plan': {
+    name: 'Upgrade Plan',
+    description: 'Upgrade subscription to a higher tier plan',
+    category: 'settings',
+    icon: 'trending-up',
+    criticalPath: false,
+
+    steps: [
+      {
+        feature: 'plans',
+        action: 'view-plans',
+        description: 'Author views available plans',
+      },
+      {
+        feature: 'plans',
+        action: 'select-plan',
+        description: 'Author selects a new plan',
+      },
+      {
+        feature: 'billing',
+        action: 'enter-payment',
+        description: 'Author enters payment information',
+      },
+      {
+        feature: 'billing',
+        action: 'confirm-upgrade',
+        description: 'Author confirms the upgrade',
+      },
+    ],
+
+    features: ['plans', 'billing'],
+  },
+})

package/config/permissions.config.ts

@@ -0,0 +1,101 @@
+/**
+ * Blog Theme - Permissions Configuration
+ *
+ * SINGLE SOURCE OF TRUTH for all permissions and roles in this theme.
+ *
+ * This file defines:
+ * - entities: Entity CRUD permissions (posts, categories)
+ * - features: Theme-specific feature permissions (export, import)
+ *
+ * All sections use unified format: { action: '...', roles: [...] }
+ *
+ * Single-user blog permissions:
+ * - Owner has all permissions
+ * - Team collaboration features are disabled
+ * - Export/Import features enabled
+ *
+ * Use PermissionService.canDoAction(role, action) to check any permission.
+ */
+
+import type { ThemePermissionsConfig } from '@nextsparkjs/core/lib/permissions/types'
+
+export const PERMISSIONS_CONFIG_OVERRIDES: ThemePermissionsConfig = {
+  // ==========================================
+  // ENTITY PERMISSIONS
+  // ==========================================
+  // Single-user mode: only owner role
+  entities: {
+    // ------------------------------------------
+    // POSTS
+    // ------------------------------------------
+    posts: [
+      { action: 'create', label: 'Create posts', description: 'Can create new blog posts', roles: ['owner'] },
+      { action: 'read', label: 'View posts', description: 'Can view post details', roles: ['owner'] },
+      { action: 'list', label: 'List posts', description: 'Can see the posts list', roles: ['owner'] },
+      { action: 'update', label: 'Edit posts', description: 'Can modify post content', roles: ['owner'] },
+      { action: 'delete', label: 'Delete posts', description: 'Can delete posts', roles: ['owner'], dangerous: true },
+      { action: 'publish', label: 'Publish posts', description: 'Can publish posts to make them public', roles: ['owner'] },
+      { action: 'unpublish', label: 'Unpublish posts', description: 'Can unpublish posts to hide them', roles: ['owner'] },
+    ],
+
+    // ------------------------------------------
+    // CATEGORIES
+    // ------------------------------------------
+    categories: [
+      { action: 'create', label: 'Create categories', description: 'Can create new categories', roles: ['owner'] },
+      { action: 'read', label: 'View categories', description: 'Can view category details', roles: ['owner'] },
+      { action: 'list', label: 'List categories', description: 'Can see the categories list', roles: ['owner'] },
+      { action: 'update', label: 'Edit categories', description: 'Can modify category information', roles: ['owner'] },
+      { action: 'delete', label: 'Delete categories', description: 'Can delete categories', roles: ['owner'], dangerous: true },
+    ],
+  },
+
+  // ==========================================
+  // FEATURE PERMISSIONS
+  // ==========================================
+  // Unified format: uses 'action' instead of 'id'
+  features: [
+    {
+      action: 'blog.export',
+      label: 'Export posts',
+      description: 'Export all posts to JSON format for backup or migration',
+      category: 'Blog',
+      roles: ['owner'],
+    },
+    {
+      action: 'blog.import',
+      label: 'Import posts',
+      description: 'Import posts from JSON file',
+      category: 'Blog',
+      roles: ['owner'],
+      dangerous: true,
+    },
+  ],
+
+  // ==========================================
+  // DISABLED FEATURES
+  // ==========================================
+  // These don't apply in single-user mode
+  disabled: [
+    'teams.invite',
+    'teams.remove_member',
+    'teams.change_roles',
+    'teams.delete',
+    'settings.api_keys',
+    'settings.billing',
+  ],
+
+  // ==========================================
+  // UI SECTIONS
+  // ==========================================
+  uiSections: [
+    {
+      id: 'blog-features',
+      label: 'Blog Features',
+      description: 'Permissions for blog-specific functionality',
+      categories: ['Blog'],
+    },
+  ],
+}
+
+export default PERMISSIONS_CONFIG_OVERRIDES

package/config/theme.config.ts

@@ -0,0 +1,128 @@
+/**
+ * Blog Theme Configuration
+ *
+ * A simple personal blog theme with single-user mode.
+ * No collaboration, just a writer and their content.
+ */
+
+import type { ThemeConfig } from '@nextsparkjs/core/types/theme'
+
+export const blogThemeConfig: ThemeConfig = {
+  name: 'blog',
+  displayName: 'Personal Blog',
+  version: '2.0.0',
+  description: 'A multi-author blog platform with single-user mode',
+  author: 'NextSpark Team',
+
+  // Teams configuration for multi-author platform with single-user mode
+  teams: {
+    mode: 'single-user',
+    options: {
+      maxTeamsPerUser: 1,
+      maxMembersPerTeam: 1,
+      allowLeaveAllTeams: false
+    }
+  },
+
+  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'
+    }
+  },
+
+  // Google Fonts for editorial typography
+  fonts: [
+    { family: 'Oxanium', weights: ['400', '500', '600', '700'] },
+    { family: 'Merriweather', weights: ['400', '700'], styles: ['normal', 'italic'] },
+    { family: 'Fira Code', weights: ['400', '500'] }
+  ],
+
+  // Theme configuration - warm amber/orange editorial aesthetic
+  config: {
+    colors: {
+      // Warm cream background
+      background: 'oklch(0.9885 0.0057 84.5659)',
+      foreground: 'oklch(0.3660 0.0251 49.6085)',
+      card: 'oklch(0.9686 0.0091 78.2818)',
+      'card-foreground': 'oklch(0.3660 0.0251 49.6085)',
+      popover: 'oklch(0.9686 0.0091 78.2818)',
+      'popover-foreground': 'oklch(0.3660 0.0251 49.6085)',
+      // Warm amber primary
+      primary: 'oklch(0.5553 0.1455 48.9975)',
+      'primary-foreground': 'oklch(1.0000 0 0)',
+      secondary: 'oklch(0.8276 0.0752 74.4400)',
+      'secondary-foreground': 'oklch(0.4444 0.0096 73.6390)',
+      muted: 'oklch(0.9363 0.0218 83.2637)',
+      'muted-foreground': 'oklch(0.5534 0.0116 58.0708)',
+      accent: 'oklch(0.9000 0.0500 74.9889)',
+      'accent-foreground': 'oklch(0.4444 0.0096 73.6390)',
+      destructive: 'oklch(0.4437 0.1613 26.8994)',
+      'destructive-foreground': 'oklch(1.0000 0 0)',
+      border: 'oklch(0.8866 0.0404 89.6994)',
+      input: 'oklch(0.8866 0.0404 89.6994)',
+      ring: 'oklch(0.5553 0.1455 48.9975)',
+
+      // Chart colors
+      'chart-1': 'oklch(0.5553 0.1455 48.9975)',
+      'chart-2': 'oklch(0.5534 0.0116 58.0708)',
+      'chart-3': 'oklch(0.5538 0.1207 66.4416)',
+      'chart-4': 'oklch(0.5534 0.0116 58.0708)',
+      'chart-5': 'oklch(0.6806 0.1423 75.8340)',
+
+      // Sidebar
+      sidebar: 'oklch(0.9363 0.0218 83.2637)',
+      'sidebar-foreground': 'oklch(0.3660 0.0251 49.6085)',
+      'sidebar-primary': 'oklch(0.5553 0.1455 48.9975)',
+      'sidebar-primary-foreground': 'oklch(1.0000 0 0)',
+      'sidebar-accent': 'oklch(0.5538 0.1207 66.4416)',
+      'sidebar-accent-foreground': 'oklch(1.0000 0 0)',
+      'sidebar-border': 'oklch(0.8866 0.0404 89.6994)',
+      'sidebar-ring': 'oklch(0.5553 0.1455 48.9975)'
+    },
+
+    // Typography - Oxanium for UI, Merriweather for content
+    fonts: {
+      sans: 'Oxanium, sans-serif',
+      serif: 'Merriweather, serif',
+      mono: 'Fira Code, monospace'
+    },
+
+    // Small radius for clean look
+    spacing: {
+      radius: '0.3rem',
+      'radius-sm': 'calc(0.3rem - 4px)',
+      'radius-md': 'calc(0.3rem - 2px)',
+      'radius-lg': '0.3rem',
+      'radius-xl': 'calc(0.3rem + 4px)'
+    },
+
+    // Warm shadows
+    breakpoints: {
+      'shadow-2xs': '0px 2px 3px 0px hsl(28 18% 25% / 0.09)',
+      'shadow-xs': '0px 2px 3px 0px hsl(28 18% 25% / 0.09)',
+      'shadow-sm': '0px 2px 3px 0px hsl(28 18% 25% / 0.18), 0px 1px 2px -1px hsl(28 18% 25% / 0.18)',
+      shadow: '0px 2px 3px 0px hsl(28 18% 25% / 0.18), 0px 1px 2px -1px hsl(28 18% 25% / 0.18)',
+      'shadow-md': '0px 2px 3px 0px hsl(28 18% 25% / 0.18), 0px 2px 4px -1px hsl(28 18% 25% / 0.18)',
+      'shadow-lg': '0px 2px 3px 0px hsl(28 18% 25% / 0.18), 0px 4px 6px -1px hsl(28 18% 25% / 0.18)',
+      'shadow-xl': '0px 2px 3px 0px hsl(28 18% 25% / 0.18), 0px 8px 10px -1px hsl(28 18% 25% / 0.18)',
+      'shadow-2xl': '0px 2px 3px 0px hsl(28 18% 25% / 0.45)'
+    }
+  },
+
+  components: {
+    overrides: {},
+    custom: {}
+  }
+}
+
+export default blogThemeConfig

package/entities/categories/categories.config.ts

@@ -0,0 +1,60 @@
+/**
+ * Categories Entity Configuration
+ *
+ * Categories for blog posts in the multi-author platform.
+ */
+
+import { Tag } from 'lucide-react'
+import type { EntityConfig } from '@nextsparkjs/core/lib/entities/types'
+import { categoryFields } from './categories.fields'
+
+export const categoryEntityConfig: EntityConfig = {
+  // ==========================================
+  // 1. BASIC IDENTIFICATION
+  // ==========================================
+  slug: 'categories',
+  enabled: true,
+  names: {
+    singular: 'category',
+    plural: 'Categories'
+  },
+  icon: Tag,
+
+  // ==========================================
+  // 2. ACCESS AND SCOPE CONFIGURATION
+  // ==========================================
+  access: {
+    public: true,           // Categories are publicly accessible
+    api: true,              // API access enabled
+    metadata: false,        // No metadata needed
+    shared: false           // User-owned categories (each user manages their own)
+  },
+
+  // ==========================================
+  // 3. UI/UX FEATURES
+  // ==========================================
+  ui: {
+    dashboard: {
+      showInMenu: true,
+      showInTopbar: false
+    },
+    public: {
+      hasArchivePage: false,  // No dedicated archive page
+      hasSinglePage: true     // /category/[slug] - posts by category
+    },
+    features: {
+      searchable: true,
+      sortable: true,
+      filterable: false,
+      bulkOperations: true,
+      importExport: false
+    }
+  },
+
+  // ==========================================
+  // FIELDS
+  // ==========================================
+  fields: categoryFields,
+}
+
+export default categoryEntityConfig