@commonpub/layer 0.23.3 → 0.24.0

package/sections/builtin/hubs.ts

@@ -0,0 +1,45 @@
+/**
+ * Built-in section definition: hubs.
+ *
+ * Phase 1c addition (session 159) — trending hubs list. Server-fetches
+ * `/api/hubs?limit=N` and renders a sidebar-style card with icon, name,
+ * member count, and a Join CTA per hub.
+ *
+ * Renderer also dispatches join requests via `POST /api/hubs/:slug/join`
+ * for authenticated visitors (mirrors legacy `HubsSection.vue`); guests
+ * are redirected to `/auth/login?redirect=/`.
+ *
+ * Defaults to colSpan 4 (sidebar). Set colSpan 12 for a horizontal
+ * sweep on a community-discovery page.
+ */
+import { z } from 'zod';
+import type { SectionDefinition } from '@commonpub/ui';
+import SectionHubs from '../../components/sections/SectionHubs.vue';
+
+const configSchema = z.object({
+  heading: z.string().max(120).default('Trending Hubs'),
+  limit: z.number().int().min(1).max(20).default(4),
+});
+
+export const hubsSection: SectionDefinition<z.infer<typeof configSchema>> = {
+  type: 'hubs',
+  name: 'Hubs',
+  description: 'Trending hubs list with join action (feature-gated)',
+  icon: 'fa-users',
+  category: 'data',
+  status: 'stable',
+  // Palette gate — admins on a hubs-disabled instance shouldn't see this
+  // type in the section-picker. Runtime gating is separate: each placed
+  // instance's `visibility.features` array controls render visibility
+  // (LayoutSlot honors it). Setting both here AND in the migration script
+  // is the belt-and-braces.
+  featureGate: 'hubs',
+  configSchema,
+  defaultConfig: { heading: 'Trending Hubs', limit: 4 },
+  schemaVersion: 1,
+  component: SectionHubs,
+  minColSpan: 3,
+  maxColSpan: 12,
+  defaultColSpan: 4,
+  resizable: true,
+};

package/sections/builtin/learning.ts

@@ -0,0 +1,38 @@
+/**
+ * Built-in section definition: learning.
+ *
+ * Phase 1c addition (session 159) — learning paths grid. Server-fetches
+ * `/api/learn?limit=N` and renders a responsive grid of cards (title,
+ * description, difficulty + duration, enrollment count).
+ *
+ * Feature-gated on `features.learning`. Behaves like editorial /
+ * content-feed structurally — a discoverable feed of an entity type.
+ */
+import { z } from 'zod';
+import type { SectionDefinition } from '@commonpub/ui';
+import SectionLearning from '../../components/sections/SectionLearning.vue';
+
+const configSchema = z.object({
+  heading: z.string().max(120).default('Learning Paths'),
+  limit: z.number().int().min(1).max(12).default(6),
+  columns: z.union([z.literal(1), z.literal(2), z.literal(3), z.literal(4)]).default(3),
+});
+
+export const learningSection: SectionDefinition<z.infer<typeof configSchema>> = {
+  type: 'learning',
+  name: 'Learning paths',
+  description: 'Grid of learning paths with enrollment + difficulty (feature-gated)',
+  icon: 'fa-graduation-cap',
+  category: 'data',
+  status: 'stable',
+  // Palette gate — see hubs.ts for the rationale.
+  featureGate: 'learning',
+  configSchema,
+  defaultConfig: { heading: 'Learning Paths', limit: 6, columns: 3 },
+  schemaVersion: 1,
+  component: SectionLearning,
+  minColSpan: 6,
+  maxColSpan: 12,
+  defaultColSpan: 12,
+  resizable: true,
+};

package/sections/builtin/stats.ts

@@ -0,0 +1,36 @@
+/**
+ * Built-in section definition: stats.
+ *
+ * Phase 1c addition (session 159) — platform stats grid. Server-fetches
+ * `/api/stats` (PlatformStats) and renders a small numeric grid:
+ * Projects, Posts (blog + legacy article), Members, Hubs.
+ *
+ * Hubs metric is gated on `features.hubs` — when the flag is off, the
+ * cell hides + the grid collapses to 1×3. Sidebar-friendly by default
+ * (colSpan 4), but works as a narrow row at 12.
+ */
+import { z } from 'zod';
+import type { SectionDefinition } from '@commonpub/ui';
+import SectionStats from '../../components/sections/SectionStats.vue';
+
+const configSchema = z.object({
+  heading: z.string().max(120).default('Platform Stats'),
+});
+
+export const statsSection: SectionDefinition<z.infer<typeof configSchema>> = {
+  type: 'stats',
+  name: 'Platform stats',
+  description: 'Numeric grid of platform totals (projects, posts, members, hubs)',
+  icon: 'fa-chart-simple',
+  category: 'data',
+  status: 'stable',
+  configSchema,
+  defaultConfig: { heading: 'Platform Stats' },
+  schemaVersion: 1,
+  component: SectionStats,
+  // Stat blocks tile down to 2×2 in a quarter-width column comfortably
+  minColSpan: 3,
+  maxColSpan: 12,
+  defaultColSpan: 4,
+  resizable: true,
+};

package/sections/registry.ts

@@ -29,26 +29,46 @@ import { paragraphSection } from './builtin/paragraph';
 import { imageSection } from './builtin/image';
 import { heroSection } from './builtin/hero';
 import { contentFeedSection } from './builtin/content-feed';
+import { editorialSection } from './builtin/editorial';
+import { statsSection } from './builtin/stats';
+import { hubsSection } from './builtin/hubs';
+import { contestsSection } from './builtin/contests';
+import { learningSection } from './builtin/learning';
+import { customHtmlSection } from './builtin/custom-html';
 
 // Singleton — registered once at module load. Vue/Nuxt's setup() runs
 // per-component, but module load is once per app process. Safe.
 const registry = new SectionRegistry();
 
 // --- Built-in registrations -----------------------------------------------
-// Phase 1c starter catalog: divider (proof-of-life) + 5 sections covering
-// the four leading categories — layout (hero, divider), content (heading,
-// paragraph, image), and data (content-feed).
+// Phase 1c full catalog (session 159): divider (proof-of-life) + 11
+// sections covering the four leading categories — layout (hero,
+// divider), content (heading, paragraph, image, custom-html), and data
+// (content-feed, editorial, stats, hubs, contests, learning).
 //
-// Phase 6b adds the remaining 20 types (gallery, video, embed, spacer,
-// cta, featured-content, content-card, contest-list, hub-list, event-list,
-// member-list, stats-grid, contact-form, newsletter, announcement,
-// markdown, custom-html, iframe, editorial). See docs/plans/layout-and-pages.md §3.4.
+// With the addition of editorial / stats / hubs / contests / learning /
+// custom-html this session, every section type the legacy
+// `homepage.sections` JSON dispatches to (HomepageSectionRenderer.vue)
+// is now representable as a registered section — unblocking the real
+// legacy-homepage migration (Phase 1c step 3 in the session-158 handoff).
+//
+// Phase 6b will add the remaining 18 types (gallery, video, embed,
+// spacer, cta, featured-content, content-card, contest-list, hub-list,
+// event-list, member-list, stats-grid, contact-form, newsletter,
+// announcement, markdown, iframe, content-grid alias). See
+// docs/plans/layout-and-pages.md §3.4.
 registry.register(dividerSection);
 registry.register(heroSection);
 registry.register(headingSection);
 registry.register(paragraphSection);
 registry.register(imageSection);
 registry.register(contentFeedSection);
+registry.register(editorialSection);
+registry.register(statsSection);
+registry.register(hubsSection);
+registry.register(contestsSection);
+registry.register(learningSection);
+registry.register(customHtmlSection);
 
 /**
  * Read-only accessor — the layer's standard pattern for shared state.

package/server/api/admin/layouts/migrate-homepage.post.ts

@@ -0,0 +1,56 @@
+/**
+ * POST /api/admin/layouts/migrate-homepage
+ *
+ * Converts the operator's legacy `instance_settings.homepage.sections`
+ * JSON into a real `layouts` row at scope ('route', '/').
+ *
+ * Body (all optional):
+ *   { force?: boolean }
+ *
+ * Default: skip when a layout already exists at the route (returns
+ * `{migrated:false, reason:'layout-already-exists', layoutId}`). With
+ * `force: true`, the existing layout + its rows / sections / versions
+ * are deleted via FK cascade and replaced.
+ *
+ * Intended canary flow (replaces the older seed-homepage path for
+ * instances that have customised their homepage):
+ *   1. Operator runs migration 0005 (if not already applied)
+ *   2. Operator POSTs here → layouts row matching the live homepage
+ *      is created + published
+ *   3. Operator flips `features.layoutEngine` ON
+ *   4. Homepage SSR renders via LayoutSlot — visually identical, but
+ *      now sourced from the layouts table instead of homepage.sections
+ *   5. Once stable, the legacy `homepage.sections` setting can be
+ *      removed (separate operator action — this endpoint doesn't
+ *      delete legacy data)
+ *
+ * Admin + features.admin + features.layoutEngine. Invalidates the
+ * layouts-by-route cache on a successful migration (or force-replace).
+ */
+import { z } from 'zod';
+import { migrateHomepageSectionsToLayout } from '@commonpub/server';
+import { invalidateLayoutsByRouteCache } from '../../../utils/layoutCache';
+
+const bodySchema = z.object({
+  force: z.boolean().optional().default(false),
+});
+
+export default defineEventHandler(async (event) => {
+  requireFeature('admin');
+  requireFeature('layoutEngine');
+  const admin = requireAdmin(event);
+
+  const body = await readBody(event).catch(() => ({}));
+  const { force } = bodySchema.parse(body ?? {});
+
+  const db = useDB();
+  const result = await migrateHomepageSectionsToLayout(db, {
+    adminId: admin.id,
+    force,
+  });
+
+  if (result.migrated) {
+    invalidateLayoutsByRouteCache();
+  }
+  return result;
+});

package/server/plugins/feature-flags-prime.ts

@@ -0,0 +1,39 @@
+/**
+ * Nitro plugin — prime each SSR request with DB-merged feature flags.
+ *
+ * The Vue `useFeatures()` composable (layers/base/composables/useFeatures.ts)
+ * initialises its `useState('feature-flags')` from `useRuntimeConfig().public.features`,
+ * which is the BUILD-TIME config baked into the bundle. Admin-UI flag
+ * overrides land in `instance_settings.features.overrides` and are
+ * picked up by `useConfig()` (server-side, DB-merged with 60s cache),
+ * but the layer composable never queries that at SSR time — only AFTER
+ * client mount, via `$fetch('/api/features')`.
+ *
+ * Effect of the gap: SSR renders with stale (build-time) flag values.
+ * An admin flipping `layoutEngine: true` from off-by-default through the
+ * admin UI doesn't take effect for SSR; the first paint shows the
+ * v-else-if branch, then hydration replaces it with the v-if branch.
+ * Bad UX and breaks curl-based canary verification.
+ *
+ * Fix: read the merged config at request-start and attach it to
+ * `event.context.cpubFeatureFlags`. The Vue composable's `getInitialFlags`
+ * (modified alongside this plugin) reads from `useRequestEvent()` context
+ * on the server, falling back to the runtime config when context is
+ * absent (e.g. island components, error pages).
+ *
+ * Cost: one call to `useConfig()` per request. The merged config is
+ * itself cached (60s TTL on DB overrides), so this is a Map lookup,
+ * not a DB hit on the hot path.
+ */
+export default defineNitroPlugin((nitroApp) => {
+  nitroApp.hooks.hook('request', (event) => {
+    try {
+      const config = useConfig();
+      event.context.cpubFeatureFlags = config.features;
+    } catch {
+      // useConfig() throws at startup when the DB isn't ready yet.
+      // Leave context.cpubFeatureFlags unset → composable falls back to
+      // build-time runtime config (same behavior as before this plugin).
+    }
+  });
+});