@commonpub/layer 0.22.0 → 0.23.0

package/components/sections/SectionHero.vue

@@ -0,0 +1,164 @@
+<script setup lang="ts">
+/**
+ * Built-in section: hero — banner with title, optional eyebrow + subtitle,
+ * up to two CTAs.
+ *
+ * Phase 1c starter. Variants: `default` (left-aligned, grid backdrop),
+ * `compact` (smaller padding, no backdrop), `centered` (centered text
+ * + CTAs, grid backdrop).
+ *
+ * Intentionally does NOT replicate the existing `HomepageHeroSection`'s
+ * contest-dispatch logic — that becomes its own data-aware section in
+ * Phase 6b (`contest-feature` or similar). This hero is pure
+ * config-driven so the editor preview is deterministic.
+ *
+ * `var(--*)` only.
+ */
+import type { SectionRenderProps } from '@commonpub/ui';
+
+interface HeroCta {
+  label: string;
+  href: string;
+  variant: 'primary' | 'secondary';
+}
+
+interface HeroConfig extends Record<string, unknown> {
+  variant: 'default' | 'compact' | 'centered';
+  eyebrow: string;
+  title: string;
+  subtitle: string;
+  ctas: HeroCta[];
+}
+
+defineProps<SectionRenderProps<HeroConfig>>();
+</script>
+
+<template>
+  <section
+    class="cpub-section-hero"
+    :data-variant="config.variant"
+    :aria-labelledby="`section-hero-${meta.sectionId}`"
+  >
+    <div v-if="config.variant !== 'compact'" class="cpub-section-hero-grid-bg" aria-hidden="true" />
+    <div class="cpub-section-hero-inner">
+      <div class="cpub-section-hero-content">
+        <p v-if="config.eyebrow" class="cpub-section-hero-eyebrow">{{ config.eyebrow }}</p>
+        <h1
+          :id="`section-hero-${meta.sectionId}`"
+          class="cpub-section-hero-title"
+        >
+          {{ config.title }}
+        </h1>
+        <p v-if="config.subtitle" class="cpub-section-hero-subtitle">{{ config.subtitle }}</p>
+        <div v-if="config.ctas.length > 0" class="cpub-section-hero-actions">
+          <NuxtLink
+            v-for="(cta, i) in config.ctas"
+            :key="i"
+            :to="cta.href"
+            class="cpub-btn"
+            :class="cta.variant === 'primary' ? 'cpub-btn-primary' : ''"
+          >
+            {{ cta.label }}
+          </NuxtLink>
+        </div>
+      </div>
+    </div>
+  </section>
+</template>
+
+<style scoped>
+.cpub-section-hero {
+  position: relative;
+  background: var(--surface);
+  border-bottom: var(--border-width-default) solid var(--border);
+  overflow: hidden;
+  min-height: 180px;
+  display: flex;
+  align-items: stretch;
+}
+.cpub-section-hero[data-variant='compact'] {
+  min-height: 120px;
+  border-bottom: none;
+}
+
+.cpub-section-hero-grid-bg {
+  position: absolute;
+  inset: 0;
+  background-image:
+    linear-gradient(var(--border2) 1px, transparent 1px),
+    linear-gradient(90deg, var(--border2) 1px, transparent 1px);
+  background-size: 32px 32px;
+  opacity: 0.25;
+  pointer-events: none;
+}
+
+.cpub-section-hero-inner {
+  position: relative;
+  z-index: 1;
+  max-width: 1280px;
+  margin: 0 auto;
+  padding: var(--space-6) var(--space-6);
+  width: 100%;
+  display: flex;
+  align-items: center;
+}
+.cpub-section-hero[data-variant='compact'] .cpub-section-hero-inner {
+  padding: var(--space-4) var(--space-6);
+}
+
+.cpub-section-hero-content { flex: 1; min-width: 0; }
+
+.cpub-section-hero[data-variant='centered'] .cpub-section-hero-inner {
+  justify-content: center;
+}
+.cpub-section-hero[data-variant='centered'] .cpub-section-hero-content {
+  text-align: center;
+  max-width: 720px;
+}
+
+.cpub-section-hero-eyebrow {
+  font-family: var(--font-mono);
+  font-size: var(--text-xs);
+  text-transform: uppercase;
+  letter-spacing: 0.1em;
+  color: var(--text-faint);
+  margin: 0 0 var(--space-2);
+}
+
+.cpub-section-hero-title {
+  font-size: var(--text-3xl);
+  font-weight: 700;
+  line-height: 1.2;
+  margin: 0 0 var(--space-2);
+  color: var(--text);
+}
+.cpub-section-hero[data-variant='compact'] .cpub-section-hero-title {
+  font-size: var(--text-2xl);
+}
+
+.cpub-section-hero-subtitle {
+  font-size: var(--text-md);
+  color: var(--text-dim);
+  line-height: 1.6;
+  margin: 0 0 var(--space-4);
+  max-width: 560px;
+}
+.cpub-section-hero[data-variant='centered'] .cpub-section-hero-subtitle {
+  margin-inline: auto;
+}
+
+.cpub-section-hero-actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-2);
+}
+.cpub-section-hero[data-variant='centered'] .cpub-section-hero-actions {
+  justify-content: center;
+}
+
+@media (max-width: 640px) {
+  .cpub-section-hero-inner { padding: var(--space-4); }
+  .cpub-section-hero-title { font-size: var(--text-2xl); }
+  .cpub-section-hero-actions { width: 100%; }
+}
+</style>

package/components/sections/SectionImage.vue

@@ -0,0 +1,104 @@
+<script setup lang="ts">
+/**
+ * Built-in section: image — single image with optional caption + link.
+ *
+ * Phase 1c starter. Author-provided `src` is rendered as-is; aspect-ratio
+ * keeps cards uniform. Lazy-loaded by default for below-fold sections.
+ *
+ * Phase 3e inspector will swap the `src` text input for an ImageUpload
+ * picker via `.describe('image')` Zod metadata.
+ *
+ * `var(--*)` only.
+ */
+import type { SectionRenderProps } from '@commonpub/ui';
+
+interface ImageConfig extends Record<string, unknown> {
+  src: string;
+  alt: string;
+  caption: string;
+  href: string;
+  fit: 'contain' | 'cover';
+  aspectRatio: '16/9' | '4/3' | '1/1' | 'auto';
+}
+
+defineProps<SectionRenderProps<ImageConfig>>();
+</script>
+
+<template>
+  <figure
+    class="cpub-section-image"
+    :data-aspect="config.aspectRatio"
+    :data-fit="config.fit"
+  >
+    <!-- The `href` field is optional — link only when truthy so screen
+         readers don't announce a non-interactive image as a link. -->
+    <component
+      :is="config.href ? 'a' : 'div'"
+      :href="config.href || undefined"
+      class="cpub-section-image-frame"
+    >
+      <img
+        v-if="config.src"
+        :src="config.src"
+        :alt="config.alt"
+        loading="lazy"
+        decoding="async"
+        class="cpub-section-image-img"
+      />
+      <div v-else class="cpub-section-image-placeholder" aria-hidden="true">
+        <i class="fa-regular fa-image" />
+      </div>
+    </component>
+    <figcaption v-if="config.caption" class="cpub-section-image-caption">
+      {{ config.caption }}
+    </figcaption>
+  </figure>
+</template>
+
+<style scoped>
+.cpub-section-image {
+  margin: 0;
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2);
+}
+.cpub-section-image-frame {
+  display: block;
+  width: 100%;
+  background: var(--surface2);
+  border: var(--border-width-default) solid var(--border);
+  overflow: hidden;
+  text-decoration: none;
+  color: inherit;
+}
+.cpub-section-image[data-aspect='16/9'] .cpub-section-image-frame { aspect-ratio: 16 / 9; }
+.cpub-section-image[data-aspect='4/3']  .cpub-section-image-frame { aspect-ratio: 4 / 3; }
+.cpub-section-image[data-aspect='1/1']  .cpub-section-image-frame { aspect-ratio: 1 / 1; }
+
+.cpub-section-image-img {
+  width: 100%;
+  height: 100%;
+  display: block;
+}
+.cpub-section-image[data-fit='cover']   .cpub-section-image-img { object-fit: cover; }
+.cpub-section-image[data-fit='contain'] .cpub-section-image-img { object-fit: contain; }
+/* Aspect=auto + no explicit ratio: let the image dictate height */
+.cpub-section-image[data-aspect='auto'] .cpub-section-image-img {
+  height: auto;
+}
+
+.cpub-section-image-placeholder {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  height: 100%;
+  min-height: 120px;
+  color: var(--text-faint);
+  font-size: var(--text-xl);
+}
+.cpub-section-image-caption {
+  font-size: var(--text-sm);
+  color: var(--text-dim);
+  line-height: 1.5;
+}
+</style>

package/components/sections/SectionParagraph.vue

@@ -0,0 +1,55 @@
+<script setup lang="ts">
+/**
+ * Built-in section: paragraph — plain prose body.
+ *
+ * Phase 1c starter. Stores `text: string` and splits on blank lines into
+ * paragraphs at render time. The auto-form inspector (Phase 3e) will
+ * upgrade this to a TipTap subset via the `.describe('rich')` Zod
+ * metadata — at which point `schemaVersion` bumps to 2 with a migration
+ * that converts plain text → block tuples.
+ *
+ * `var(--*)` only.
+ */
+import { computed } from 'vue';
+import type { SectionRenderProps } from '@commonpub/ui';
+
+interface ParagraphConfig extends Record<string, unknown> {
+  text: string;
+  align: 'left' | 'center';
+}
+
+const props = defineProps<SectionRenderProps<ParagraphConfig>>();
+
+// Blank-line split — preserves authored paragraph breaks without needing
+// a rich-text editor. Empty paragraphs are dropped (defensive).
+const paragraphs = computed<string[]>(() =>
+  (props.config.text ?? '')
+    .split(/\n{2,}/)
+    .map((p) => p.trim())
+    .filter((p) => p.length > 0),
+);
+</script>
+
+<template>
+  <div class="cpub-section-paragraph" :data-align="config.align">
+    <p v-for="(p, i) in paragraphs" :key="i">{{ p }}</p>
+  </div>
+</template>
+
+<style scoped>
+.cpub-section-paragraph {
+  margin-block: var(--space-3);
+  color: var(--text);
+  font-size: var(--text-md);
+  line-height: 1.7;
+}
+.cpub-section-paragraph[data-align='center'] {
+  text-align: center;
+}
+.cpub-section-paragraph p {
+  margin: 0 0 var(--space-3);
+}
+.cpub-section-paragraph p:last-child {
+  margin-bottom: 0;
+}
+</style>

package/composables/useFeatures.ts

@@ -26,6 +26,14 @@ export interface FeatureFlags {
   emailNotifications: boolean;
   publicApi: boolean;
   contentImport: boolean;
+  /**
+   * DB-backed page layout engine. Default OFF — when ON, the homepage
+   * (and future layout-bearing pages) render via `<LayoutSlot>` zones
+   * resolved from the `layouts` table. Operator MUST run
+   * POST /api/admin/layouts/seed-homepage before flipping this on so
+   * a default layout exists at scope ('route', '/'). Added session 158.
+   */
+  layoutEngine: boolean;
   /**
    * Cross-instance delegated authorization. All sub-flags default false.
    * Mirrors `@commonpub/config`'s `IdentityFeatures`. Phase 1b+ — see
@@ -46,6 +54,7 @@ export const DEFAULT_FLAGS: FeatureFlags = {
   contests: false, events: false, learning: true, explainers: true,
   editorial: true, federation: false, admin: false, emailNotifications: false,
   publicApi: false, contentImport: true,
+  layoutEngine: false,
   identity: {
     linkRemoteAccounts: false,
     signInWithRemote: false,
@@ -120,6 +129,7 @@ export function useFeatures() {
     emailNotifications: computed(() => flags.value.emailNotifications),
     publicApi: computed(() => flags.value.publicApi),
     contentImport: computed(() => flags.value.contentImport),
+    layoutEngine: computed(() => flags.value.layoutEngine),
     identity: computed(() => flags.value.identity),
   };
 }

package/composables/useLayout.ts

@@ -0,0 +1,132 @@
+/**
+ * Client-side composable for resolving a route's active layout.
+ *
+ * Wraps `useFetch('/api/layouts/by-route?path=…')` with SSR-safe caching:
+ *   - Server-side: fetched during SSR, payload is included in the
+ *     hydration snapshot (Nuxt's `useFetch` default) — same data is
+ *     re-used on client mount with zero extra requests
+ *   - Client-side: subsequent navigations to the same path return the
+ *     cached value (Nuxt's request cache, keyed by `key`)
+ *
+ * Returns `null` when:
+ *   - The layout-engine feature is OFF (`/api/layouts/by-route` 404s,
+ *     which we surface as null so consumers fall back to legacy renderers
+ *     gracefully)
+ *   - No layout exists for the route
+ *
+ * The `<LayoutSlot>` component is the only intended caller in v1; other
+ * consumers should use that instead.
+ */
+import type { Ref } from 'vue';
+
+export interface LayoutSection {
+  id: string;
+  order: number;
+  type: string;
+  config: Record<string, unknown>;
+  colSpan: number;
+  responsive: { sm?: number; md?: number; lg?: number } | null;
+  enabled: boolean;
+  visibility: { roles?: string[]; features?: string[]; hideAt?: ('sm' | 'md' | 'lg')[] } | null;
+  schemaVersion: number;
+}
+
+export interface LayoutRow {
+  id: string;
+  order: number;
+  config: {
+    gap?: 'none' | 'sm' | 'md' | 'lg';
+    align?: 'start' | 'center' | 'stretch';
+    background?: string;
+    paddingY?: 'none' | 'sm' | 'md' | 'lg' | 'xl';
+  } | null;
+  sections: LayoutSection[];
+}
+
+export interface LayoutZoneClient {
+  zone: string;
+  rows: LayoutRow[];
+}
+
+export interface LayoutPayload {
+  zones: LayoutZoneClient[];
+  pageMeta: {
+    title: string;
+    description?: string;
+    ogImage?: string;
+    noindex?: boolean;
+    ogType?: 'website' | 'article' | 'profile';
+    access?: 'public' | 'members' | 'admin';
+    frame?: 'narrow' | 'wide' | 'two-column' | 'three-column' | 'sidebar-left' | 'sidebar-right';
+  } | null;
+  state: 'draft' | 'published';
+}
+
+export interface UseLayoutResult {
+  /** The layout payload, or null if none exists / feature off. */
+  layout: Ref<LayoutPayload | null>;
+  /** True while the initial fetch is in flight. */
+  pending: Ref<boolean>;
+  /** Truthy if the fetch errored (incl. 404 for feature off). */
+  error: Ref<unknown>;
+  /** Re-fetch the layout (after a save / publish). */
+  refresh: () => Promise<void>;
+}
+
+/**
+ * Resolve the layout for a given route path. SSR-safe; caches per path
+ * for the request lifetime + survives hydration.
+ *
+ * Returns a layout=null Ref when the feature is off so consumers can
+ * `v-if="layout"` and fall through to a legacy renderer.
+ *
+ * **Reactivity**: pass a string for the typical case (literal route on
+ * a page) — useFetch fires once at setup. For the rare case where the
+ * route changes without remount (e.g. a parent component swapping the
+ * prop dynamically), pass a Ref or getter — useFetch will refire on
+ * change. Without this, a path-prop change on `<LayoutSlot>` would
+ * silently leave the stale fetch result in place.
+ */
+export function useLayout(path: string | Ref<string> | (() => string)): UseLayoutResult {
+  const pathGetter = (): string => (
+    typeof path === 'string'
+      ? path
+      : typeof path === 'function'
+        ? path()
+        : path.value
+  );
+
+  const { data, pending, error, refresh } = useFetch<LayoutPayload | null>(
+    '/api/layouts/by-route',
+    {
+      // Static key for the literal-string case (so Nuxt's request cache
+      // can dedupe across components on the same nav). For the reactive
+      // case, omit key so useFetch derives one from the query Ref.
+      key: typeof path === 'string' ? `layout:${path}` : undefined,
+      // Functional query — useFetch re-evaluates on watched deps change.
+      query: { path: pathGetter },
+      // Watch the path getter so reactive callers refetch on change.
+      // For string callers this is empty array → no extra reactivity.
+      watch: typeof path === 'string' ? [] : [pathGetter],
+      // 404 from the API (feature off OR route has no layout) is NOT an
+      // exceptional case — surface as null. Don't treat as error.
+      onResponseError({ response }) {
+        if (response.status === 404) {
+          // Don't throw; data stays null
+          return;
+        }
+      },
+      // Falsy data on 404 maps to null
+      transform: (input: LayoutPayload | null | undefined) => input ?? null,
+      server: true,
+      lazy: false,
+    },
+  );
+
+  return {
+    layout: data as Ref<LayoutPayload | null>,
+    pending,
+    error,
+    refresh: async () => { await refresh(); },
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonpub/layer",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "type": "module",
   "main": "./nuxt.config.ts",
   "files": [
@@ -50,16 +50,16 @@
     "vue": "^3.4.0",
     "vue-router": "^4.3.0",
     "zod": "^4.3.6",
+    "@commonpub/config": "0.15.0",
+    "@commonpub/explainer": "0.7.15",
     "@commonpub/editor": "0.7.11",
-    "@commonpub/docs": "0.6.3",
-    "@commonpub/learning": "0.5.2",
-    "@commonpub/config": "0.14.0",
-    "@commonpub/server": "2.56.0",
     "@commonpub/auth": "0.6.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/ui": "0.9.0",
-    "@commonpub/explainer": "0.7.15"
+    "@commonpub/server": "2.57.0"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",

package/pages/admin/theme/edit/[id].vue

@@ -149,7 +149,13 @@ const pairCandidates = computed(() =>
 
 // --- Save / cancel / export -----------------------------------------
 
-async function save(): Promise<void> {
+/**
+ * Save the draft. If `apply` is true, ALSO set this theme as the
+ * instance default in the same await chain — must happen BEFORE the
+ * create-mode router.replace, otherwise the navigation could unmount
+ * the component mid-PUT and lose the apply.
+ */
+async function save({ apply = false }: { apply?: boolean } = {}): Promise<void> {
   saving.value = true;
   error.value = null;
   try {
@@ -163,15 +169,14 @@ async function save(): Promise<void> {
       parentTheme: draft.value.parentTheme,
       tokens: draft.value.tokens,
     };
+
+    let savedId: string;
     if (isCreating) {
       const created = await $fetch('/api/admin/themes', {
         method: 'POST',
         body: payload,
       });
-      notify('Theme created', 'success');
-      dirty.value = false;
-      await themesApi.refresh();
-      router.replace(`/admin/theme/edit/${(created as { id: string }).id}`);
+      savedId = (created as { id: string }).id;
     } else {
       // Cast: Nuxt's typed-route inference for dynamic URLs picks the
       // narrowest method overload (GET) — same workaround used in
@@ -180,9 +185,25 @@ async function save(): Promise<void> {
         `/api/admin/themes/${draft.value.id}`,
         { method: 'PUT', body: payload },
       );
-      notify('Saved', 'success');
-      dirty.value = false;
-      await themesApi.refresh();
+      savedId = draft.value.id;
+    }
+
+    // Apply BEFORE refresh/navigation so the navigate doesn't unmount us
+    // mid-PUT (would lose the apply + the success toast).
+    if (apply) {
+      await $fetch('/api/admin/settings', {
+        method: 'PUT',
+        body: { key: 'theme.default', value: `cpub-custom-${savedId}` },
+      });
+    }
+
+    notify(apply ? 'Saved & applied' : (isCreating ? 'Theme created' : 'Saved'), 'success');
+    dirty.value = false;
+    await themesApi.refresh();
+
+    // Navigate LAST so all the awaits above have observable effects.
+    if (isCreating) {
+      router.replace(`/admin/theme/edit/${savedId}`);
     }
   } catch (err) {
     const msg = err instanceof Error ? err.message : 'Save failed';
@@ -194,13 +215,7 @@ async function save(): Promise<void> {
 }
 
 async function applyAndSave(): Promise<void> {
-  await save();
-  if (error.value) return;
-  await $fetch('/api/admin/settings', {
-    method: 'PUT',
-    body: { key: 'theme.default', value: `cpub-custom-${draft.value.id}` },
-  });
-  notify('Saved and applied instance-wide', 'success');
+  await save({ apply: true });
 }
 
 function exportTheme(): void {
@@ -248,9 +263,14 @@ onBeforeUnmount(() => {
 <template>
   <div class="theme-editor">
     <header class="theme-editor-toolbar">
-      <button class="cpub-btn cpub-btn-sm theme-editor-back" @click="cancel">
+      <button
+        class="cpub-btn cpub-btn-sm theme-editor-back"
+        :title="dirty ? 'You have unsaved changes' : 'Back to themes list'"
+        @click="cancel"
+      >
         <i class="fa-solid fa-arrow-left" aria-hidden="true" />
         <span>Themes</span>
+        <span v-if="dirty" class="theme-editor-dirty-dot" aria-label="unsaved changes"></span>
       </button>
 
       <div class="theme-editor-meta">
@@ -329,11 +349,13 @@ onBeforeUnmount(() => {
         <button class="cpub-btn cpub-btn-sm" @click="exportTheme" title="Download .cpub-theme.json">
           <i class="fa-solid fa-file-export" aria-hidden="true" /> Export
         </button>
-        <button class="cpub-btn cpub-btn-sm" :disabled="saving || !dirty" @click="save">
-          <i class="fa-solid fa-floppy-disk" aria-hidden="true" /> Save
+        <button class="cpub-btn cpub-btn-sm" :disabled="saving || !dirty" @click="() => save()">
+          <i :class="['fa-solid', saving ? 'fa-circle-notch fa-spin' : 'fa-floppy-disk']" aria-hidden="true" />
+          {{ saving ? 'Saving…' : 'Save' }}
         </button>
         <button class="cpub-btn cpub-btn-sm cpub-btn-primary" :disabled="saving" @click="applyAndSave">
-          <i class="fa-solid fa-rocket" aria-hidden="true" /> Save &amp; apply
+          <i :class="['fa-solid', saving ? 'fa-circle-notch fa-spin' : 'fa-rocket']" aria-hidden="true" />
+          {{ saving ? 'Applying…' : 'Save & apply' }}
         </button>
       </div>
     </header>
@@ -406,7 +428,33 @@ onBeforeUnmount(() => {
   flex-wrap: wrap;
 }
 
-.theme-editor-back { flex-shrink: 0; }
+.theme-editor-back {
+  flex-shrink: 0;
+  position: relative;
+}
+
+.theme-editor-dirty-dot {
+  display: inline-block;
+  width: 6px;
+  height: 6px;
+  background: var(--accent);
+  border-radius: var(--radius-full);
+  margin-left: 4px;
+  /* Subtle pulse so it draws the eye without being noisy */
+  animation: theme-editor-dirty-pulse 2s ease-in-out infinite;
+}
+
+@keyframes theme-editor-dirty-pulse {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.4; }
+}
+@media (prefers-reduced-motion: reduce) {
+  .theme-editor-dirty-dot { animation: none; }
+}
+
+.theme-editor-input-name {
+  font-weight: var(--font-weight-semibold);
+}
 
 .theme-editor-meta {
   display: flex;