@commonpub/layer 0.23.0 → 0.23.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonpub/layer",
-  "version": "0.23.0",
+  "version": "0.23.1",
   "type": "module",
   "main": "./nuxt.config.ts",
   "files": [
@@ -13,6 +13,7 @@
     "middleware",
     "pages",
     "plugins",
+    "sections",
     "server",
     "theme",
     "types",
@@ -50,16 +51,16 @@
     "vue": "^3.4.0",
     "vue-router": "^4.3.0",
     "zod": "^4.3.6",
+    "@commonpub/auth": "0.6.0",
     "@commonpub/config": "0.15.0",
-    "@commonpub/explainer": "0.7.15",
     "@commonpub/editor": "0.7.11",
-    "@commonpub/auth": "0.6.0",
+    "@commonpub/explainer": "0.7.15",
+    "@commonpub/protocol": "0.12.0",
+    "@commonpub/server": "2.57.0",
+    "@commonpub/schema": "0.17.0",
     "@commonpub/learning": "0.5.2",
     "@commonpub/ui": "0.9.0",
-    "@commonpub/schema": "0.17.0",
-    "@commonpub/docs": "0.6.3",
-    "@commonpub/protocol": "0.12.0",
-    "@commonpub/server": "2.57.0"
+    "@commonpub/docs": "0.6.3"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",

package/sections/builtin/content-feed.ts

@@ -0,0 +1,52 @@
+/**
+ * Built-in section definition: content-feed.
+ *
+ * Phase 1c starter and the first DATA section. Fetches `/api/content`
+ * with config-driven filters and renders a responsive grid of
+ * `<ContentCard>`s.
+ *
+ * Config fields split into server-filter (forwarded to `/api/content`)
+ * and render-only (`heading`, `columns`). Keeping the contract explicit
+ * here matches the auto-form mapping in Phase 3e and stops accidental
+ * pass-through of admin-only filter values.
+ */
+import { z } from 'zod';
+import type { SectionDefinition } from '@commonpub/ui';
+import SectionContentFeed from '../../components/sections/SectionContentFeed.vue';
+
+const configSchema = z.object({
+  heading: z.string().max(120).default(''),
+  contentType: z.string().max(64).default(''),
+  sort: z.enum(['recent', 'popular', 'featured', 'editorial']).default('recent'),
+  limit: z.number().int().min(1).max(24).default(6),
+  columns: z.union([z.literal(1), z.literal(2), z.literal(3), z.literal(4)]).default(3),
+  tag: z.string().max(64).default(''),
+  featured: z.boolean().default(false),
+});
+
+export const contentFeedSection: SectionDefinition<z.infer<typeof configSchema>> = {
+  type: 'content-feed',
+  name: 'Content feed',
+  description: 'Grid of content cards filtered by type / tag / sort',
+  icon: 'fa-stream',
+  category: 'data',
+  status: 'stable',
+  configSchema,
+  defaultConfig: {
+    heading: '',
+    contentType: '',
+    sort: 'recent',
+    limit: 6,
+    columns: 3,
+    tag: '',
+    featured: false,
+  },
+  schemaVersion: 1,
+  component: SectionContentFeed,
+  // Multi-column grid collapses to less than half-width — readability + the
+  // card aspect ratio break down below 6
+  minColSpan: 6,
+  maxColSpan: 12,
+  defaultColSpan: 12,
+  resizable: true,
+};

package/sections/builtin/divider.ts

@@ -0,0 +1,37 @@
+/**
+ * Built-in section definition: divider.
+ *
+ * Phase 1 proof-of-life — the simplest possible registered section.
+ * Validates the registry → LayoutSlot → renderer chain without any
+ * Zod complexity, content fetches, or admin-only config.
+ *
+ * Phase 1c adds: hero, heading, paragraph, image, content-feed —
+ * each in its own `builtin/{type}.ts` file, registered in
+ * `../registry.ts` alongside this one.
+ */
+import { z } from 'zod';
+import type { SectionDefinition } from '@commonpub/ui';
+import SectionDivider from '../../components/sections/SectionDivider.vue';
+
+const configSchema = z.object({
+  variant: z.enum(['solid', 'dashed', 'dotted', 'accent']).default('solid'),
+  spacingY: z.enum(['sm', 'md', 'lg', 'xl']).default('md'),
+});
+
+export const dividerSection: SectionDefinition<z.infer<typeof configSchema>> = {
+  type: 'divider',
+  name: 'Divider',
+  description: 'Horizontal rule with style + spacing options',
+  icon: 'fa-minus',
+  category: 'layout',
+  status: 'stable',
+  configSchema,
+  defaultConfig: { variant: 'solid', spacingY: 'md' },
+  schemaVersion: 1,
+  component: SectionDivider,
+  // Dividers are always full-width; resize is meaningless for a 1px line
+  minColSpan: 12,
+  maxColSpan: 12,
+  defaultColSpan: 12,
+  resizable: false,
+};

package/sections/builtin/heading.ts

@@ -0,0 +1,36 @@
+/**
+ * Built-in section definition: heading.
+ *
+ * Phase 1c starter — single heading with optional eyebrow + subline.
+ * Drives the auto-form via the configSchema (Phase 3e maps Zod kinds to
+ * controls; level is a small enum → segmented control).
+ */
+import { z } from 'zod';
+import type { SectionDefinition } from '@commonpub/ui';
+import SectionHeading from '../../components/sections/SectionHeading.vue';
+
+const configSchema = z.object({
+  text: z.string().min(1).max(240).default('Section heading'),
+  level: z.union([z.literal(1), z.literal(2), z.literal(3), z.literal(4)]).default(2),
+  align: z.enum(['left', 'center']).default('left'),
+  eyebrow: z.string().max(120).default(''),
+  subline: z.string().max(480).default(''),
+});
+
+export const headingSection: SectionDefinition<z.infer<typeof configSchema>> = {
+  type: 'heading',
+  name: 'Heading',
+  description: 'Single h1–h4 heading with optional eyebrow + subline',
+  icon: 'fa-heading',
+  category: 'content',
+  status: 'stable',
+  configSchema,
+  defaultConfig: { text: 'Section heading', level: 2, align: 'left', eyebrow: '', subline: '' },
+  schemaVersion: 1,
+  component: SectionHeading,
+  // Heading reads fine narrow; allow as small as quarter-width
+  minColSpan: 3,
+  maxColSpan: 12,
+  defaultColSpan: 12,
+  resizable: true,
+};

package/sections/builtin/hero.ts

@@ -0,0 +1,67 @@
+/**
+ * Built-in section definition: hero.
+ *
+ * Phase 1c starter. Three variants — `default` (left-aligned with grid
+ * backdrop), `compact` (narrow with no backdrop), `centered` (centered
+ * content). Up to two CTAs each with their own variant.
+ *
+ * NOT contest-aware (the existing HomepageHeroSection has dispatch
+ * logic for the live-contest hero — that responsibility moves to a
+ * future `contest-feature` data section in Phase 6b).
+ */
+import { z } from 'zod';
+import type { SectionDefinition } from '@commonpub/ui';
+import SectionHero from '../../components/sections/SectionHero.vue';
+
+/**
+ * URL guard — accepts http(s), site-relative paths, hash links, mailto/tel.
+ * Rejects javascript:, data:, vbscript:, file:, etc. — admin-set fields
+ * render to ALL visitors, so a malicious admin (or DB corruption) could
+ * inject a clickable XSS via `<a href="javascript:...">` without this.
+ *
+ * Defense at the write boundary; the renderer doesn't re-validate
+ * (Vue's :href binding doesn't sanitize, so this IS the guard).
+ */
+const SAFE_LINK_URL = /^(https?:\/\/|\/|#|mailto:|tel:)/i;
+
+const ctaSchema = z.object({
+  label: z.string().min(1).max(80),
+  href: z.string().min(1).max(2048).regex(SAFE_LINK_URL, {
+    message: 'href must be http(s), relative (/), hash (#), mailto:, or tel:',
+  }),
+  variant: z.enum(['primary', 'secondary']).default('primary'),
+});
+
+const configSchema = z.object({
+  variant: z.enum(['default', 'compact', 'centered']).default('default'),
+  eyebrow: z.string().max(120).default(''),
+  title: z.string().min(1).max(240).default('Welcome'),
+  subtitle: z.string().max(800).default(''),
+  // Capped at 2 — visual + a11y guidance: more than two competing CTAs
+  // dilute the call-to-action and read as a button bar instead.
+  ctas: z.array(ctaSchema).max(2).default([]),
+});
+
+export const heroSection: SectionDefinition<z.infer<typeof configSchema>> = {
+  type: 'hero',
+  name: 'Hero',
+  description: 'Banner with title, subtitle, and up to two CTAs',
+  icon: 'fa-bullhorn',
+  category: 'layout',
+  status: 'stable',
+  configSchema,
+  defaultConfig: {
+    variant: 'default',
+    eyebrow: '',
+    title: 'Welcome',
+    subtitle: '',
+    ctas: [],
+  },
+  schemaVersion: 1,
+  component: SectionHero,
+  // Hero breaks at <6 cols (CTA wrap looks awful); 12 is the canonical use
+  minColSpan: 6,
+  maxColSpan: 12,
+  defaultColSpan: 12,
+  resizable: true,
+};

package/sections/builtin/image.ts

@@ -0,0 +1,67 @@
+/**
+ * Built-in section definition: image.
+ *
+ * Phase 1c starter. Stores raw URL + alt + optional caption + optional
+ * href. The Phase 3e auto-form will swap `src` for an ImageUpload picker
+ * via `.describe('image')` — current Zod is a plain URL string so the
+ * form generator still produces a usable text input today.
+ *
+ * Security note: `src` is rendered as-is via `<img>` — sanitisation is
+ * caller responsibility (the URL is never reflected into a script
+ * context). Custom-HTML / iframe sections are the XSS surface and gate
+ * differently (admin-only addRoles in Phase 6b).
+ */
+import { z } from 'zod';
+import type { SectionDefinition } from '@commonpub/ui';
+import SectionImage from '../../components/sections/SectionImage.vue';
+
+/**
+ * URL guards — separate for `src` (image fetch) vs `href` (click target).
+ *
+ * - `src`: http(s) or site-relative. data: rejected (large + tracking
+ *   surface; ImageUpload should be the path for inline data). javascript:
+ *   in <img src> doesn't execute in modern browsers, but disallow anyway
+ *   for consistency.
+ * - `href`: http(s), site-relative, hash, mailto:, tel:. javascript:
+ *   would execute on click — admin-set fields render to ALL visitors so
+ *   this is a stored XSS surface without the regex.
+ *
+ * Both allow EMPTY string (the section's "no image yet" / "no link"
+ * state). The `^(?:$|…)` shape matches empty-string only when the
+ * `$` end-of-string anchor immediately follows `^` — pinned by tests
+ * because the obvious `^(?:|…)` would have an empty alternation
+ * branch that matches ANY input (the empty match always succeeds at
+ * position 0).
+ */
+const SAFE_IMAGE_URL = /^(?:$|https?:\/\/|\/)/i;
+const SAFE_LINK_URL = /^(?:$|https?:\/\/|\/|#|mailto:|tel:)/i;
+
+const configSchema = z.object({
+  src: z.string().max(2048).regex(SAFE_IMAGE_URL, {
+    message: 'src must be http(s) or relative (/)',
+  }).default(''),
+  alt: z.string().max(240).default(''),
+  caption: z.string().max(480).default(''),
+  href: z.string().max(2048).regex(SAFE_LINK_URL, {
+    message: 'href must be http(s), relative (/), hash (#), mailto:, or tel:',
+  }).default(''),
+  fit: z.enum(['contain', 'cover']).default('contain'),
+  aspectRatio: z.enum(['16/9', '4/3', '1/1', 'auto']).default('auto'),
+});
+
+export const imageSection: SectionDefinition<z.infer<typeof configSchema>> = {
+  type: 'image',
+  name: 'Image',
+  description: 'Single image with optional caption + link',
+  icon: 'fa-image',
+  category: 'content',
+  status: 'stable',
+  configSchema,
+  defaultConfig: { src: '', alt: '', caption: '', href: '', fit: 'contain', aspectRatio: 'auto' },
+  schemaVersion: 1,
+  component: SectionImage,
+  minColSpan: 3,
+  maxColSpan: 12,
+  defaultColSpan: 12,
+  resizable: true,
+};

package/sections/builtin/paragraph.ts

@@ -0,0 +1,34 @@
+/**
+ * Built-in section definition: paragraph.
+ *
+ * Phase 1c starter — plain prose, blank-line split into `<p>` tags.
+ * Upgrade to TipTap-driven rich text in Phase 3e via `.describe('rich')`
+ * + a v2 migration; this v1 keeps the storage simple so the editor work
+ * doesn't block on TipTap integration.
+ */
+import { z } from 'zod';
+import type { SectionDefinition } from '@commonpub/ui';
+import SectionParagraph from '../../components/sections/SectionParagraph.vue';
+
+const configSchema = z.object({
+  text: z.string().max(8000).default(''),
+  align: z.enum(['left', 'center']).default('left'),
+});
+
+export const paragraphSection: SectionDefinition<z.infer<typeof configSchema>> = {
+  type: 'paragraph',
+  name: 'Paragraph',
+  description: 'Plain prose body with blank-line paragraph breaks',
+  icon: 'fa-align-left',
+  category: 'content',
+  status: 'stable',
+  configSchema,
+  defaultConfig: { text: '', align: 'left' },
+  schemaVersion: 1,
+  component: SectionParagraph,
+  // Prose reads best at ~6/12; allow narrower for sidebars + full-width on landing pages
+  minColSpan: 3,
+  maxColSpan: 12,
+  defaultColSpan: 6,
+  resizable: true,
+};

package/sections/registry.ts

@@ -0,0 +1,61 @@
+/**
+ * Layer-level section registry — the Vue runtime catalog that
+ * `<LayoutSlot>` consults to render a section by its `type` slug.
+ *
+ * `SectionRegistry` (the class) lives in `@commonpub/ui` as Vue-aware
+ * types. This file:
+ *   1. Creates ONE shared registry instance per app process
+ *   2. Calls `register()` for every built-in section type the layer ships
+ *   3. Exports `useSectionRegistry()` so consumers (LayoutSlot + the
+ *      admin editor's palette) can read it without circular imports
+ *
+ * **Same instance on server + client.** Vue plugins instantiate at
+ * setup time; section registration is synchronous + idempotent (the
+ * `register()` method throws on duplicate slugs — fail-fast).
+ *
+ * Adding a built-in section is THREE files (see any of `./builtin/*` for
+ * the template):
+ *   1. `./builtin/{type}.ts` — Zod schema + SectionDefinition export
+ *   2. `../components/sections/Section{PascalType}.vue` — renderer
+ *   3. One `registry.register(...)` line here
+ *
+ * To add a CUSTOM section from a thin layer app (Phase 9 — not yet
+ * shipped): same pattern, registered from your `commonpub.config.ts`.
+ */
+import { SectionRegistry } from '@commonpub/ui';
+import { dividerSection } from './builtin/divider';
+import { headingSection } from './builtin/heading';
+import { paragraphSection } from './builtin/paragraph';
+import { imageSection } from './builtin/image';
+import { heroSection } from './builtin/hero';
+import { contentFeedSection } from './builtin/content-feed';
+
+// 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 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.
+registry.register(dividerSection);
+registry.register(heroSection);
+registry.register(headingSection);
+registry.register(paragraphSection);
+registry.register(imageSection);
+registry.register(contentFeedSection);
+
+/**
+ * Read-only accessor — the layer's standard pattern for shared state.
+ * Use this everywhere instead of importing `registry` directly so we
+ * can swap to a Nuxt-provided instance in Phase 9 (when thin apps
+ * register their own sections via `commonpub.config.ts`).
+ */
+export function useSectionRegistry(): SectionRegistry {
+  return registry;
+}