@commonpub/layer 0.22.1 → 0.23.0

package/components/LayoutSlot.vue

@@ -0,0 +1,266 @@
+<script setup lang="ts">
+/**
+ * &lt;LayoutSlot&gt; — renders one zone of a route's active layout.
+ *
+ * Page (e.g. `pages/index.vue`) is the FRAME; this component is the
+ * fillings for each zone the page exposes. Pages declare zones like:
+ *
+ * ```vue
+ * &lt;template&gt;
+ *   &lt;LayoutSlot route="/" zone="full-width" /&gt;
+ *   &lt;div class="cpub-content-grid"&gt;
+ *     &lt;LayoutSlot route="/" zone="main" /&gt;
+ *     &lt;aside&gt;&lt;LayoutSlot route="/" zone="sidebar" /&gt;&lt;/aside&gt;
+ *   &lt;/div&gt;
+ * &lt;/template&gt;
+ * ```
+ *
+ * For each row in the zone:
+ *   - Renders a 12-column CSS Grid container with the row's gap setting
+ *   - For each enabled + visible section: renders the registered section
+ *     component, scoped to its resolved colSpan
+ *
+ * Visibility filters (run client-side on every render so role/feature
+ * changes propagate without a re-fetch):
+ *   - section.enabled === false → skipped
+ *   - visibility.features intersected with active feature flags must
+ *     have ALL flags ON
+ *   - visibility.roles must include the current user's role (or
+ *     'anonymous' for unauthenticated)
+ *
+ * When the layout-engine feature is OFF (the default for v1), `useLayout`
+ * resolves to null and this component renders nothing — pages that
+ * adopt &lt;LayoutSlot&gt; need a v-if fallback to the legacy renderer
+ * during the migration window.
+ *
+ * Section rendering: the registry component map is populated by a Nuxt
+ * plugin at startup (Phase 1c). Until then, unknown types render
+ * an admin-only error placeholder.
+ */
+import { computed } from 'vue';
+import type { LayoutSection, LayoutPayload, LayoutZoneClient } from '../composables/useLayout';
+import { useSectionRegistry } from '../sections/registry';
+
+const props = defineProps<{
+  /** Route path this layout is for — e.g. '/', '/blog', '/hubs/foo'. */
+  route: string;
+  /** Zone slug — must match a zone declared in the layout's storage. */
+  zone: string;
+  /**
+   * Optional override — when set, this layout is rendered INSTEAD of
+   * fetching from /api/layouts/by-route. Used by the editor preview
+   * pane to render the in-progress draft without a save round-trip.
+   */
+  previewOverride?: LayoutPayload | null;
+}>();
+
+const { layout, pending } = useLayout(props.route);
+const features = useFeatures();
+const { isAuthenticated, user } = useAuth();
+const sectionRegistry = useSectionRegistry();
+
+const activeLayout = computed(() => props.previewOverride ?? layout.value);
+
+const zone = computed<LayoutZoneClient | null>(
+  () => activeLayout.value?.zones.find((z: LayoutZoneClient) => z.zone === props.zone) ?? null,
+);
+
+function isFeatureOn(featureGate: string | undefined): boolean {
+  if (!featureGate) return true;
+  return (features.features.value as unknown as Record<string, boolean>)?.[featureGate] ?? false;
+}
+
+function currentRole(): string {
+  if (!isAuthenticated.value) return 'anonymous';
+  return user.value?.role ?? 'member';
+}
+
+function sectionVisible(s: LayoutSection): boolean {
+  if (!s.enabled) return false;
+  const v = s.visibility;
+  if (!v) return true;
+  if (v.features && v.features.some((f: string) => !isFeatureOn(f))) return false;
+  if (v.roles && v.roles.length > 0 && !v.roles.includes(currentRole())) return false;
+  // hideAt is a viewport-level filter — applied via CSS, not here
+  return true;
+}
+
+/**
+ * Resolve colSpan honouring the responsive fallback chain. Defers the
+ * viewport choice to CSS — we use `--cpub-section-cols-{sm|md|lg}`
+ * custom properties on each section and let media queries pick which
+ * one becomes the active `grid-column: span N` via `attr()`-style
+ * values. For now, just use the base colSpan (12 = full width on mobile
+ * happens via the row's flex-wrap).
+ */
+function resolveColSpan(s: LayoutSection, viewport: 'lg' | 'md' | 'sm'): number {
+  if (viewport === 'lg') return s.responsive?.lg ?? s.colSpan;
+  if (viewport === 'md') return s.responsive?.md ?? s.responsive?.lg ?? s.colSpan;
+  // Mobile default 12 unless explicitly overridden
+  return s.responsive?.sm ?? 12;
+}
+</script>
+
+<template>
+  <!--
+    Renders nothing when:
+      - layout-engine feature is off (useLayout returns null)
+      - no layout exists for this route
+      - no zone of that slug in the layout
+      - zone has zero rows
+    All four are valid "absence" cases — fall back to legacy rendering
+    via the page's v-if structure.
+  -->
+  <template v-if="zone && zone.rows.length > 0">
+    <div
+      v-for="row in zone.rows"
+      :key="row.id"
+      class="cpub-layout-row"
+      :data-row-id="row.id"
+      :data-gap="row.config?.gap ?? 'md'"
+      :data-align="row.config?.align ?? 'stretch'"
+      :data-padding-y="row.config?.paddingY ?? 'none'"
+      :style="row.config?.background ? { background: row.config.background } : {}"
+    >
+      <div
+        v-for="section in row.sections.filter(sectionVisible)"
+        :key="section.id"
+        class="cpub-layout-section"
+        :data-section-id="section.id"
+        :data-section-type="section.type"
+        :data-hide-sm="section.visibility?.hideAt?.includes('sm') ? 'true' : 'false'"
+        :data-hide-md="section.visibility?.hideAt?.includes('md') ? 'true' : 'false'"
+        :data-hide-lg="section.visibility?.hideAt?.includes('lg') ? 'true' : 'false'"
+        :style="{
+          '--cpub-section-cols-sm': resolveColSpan(section, 'sm'),
+          '--cpub-section-cols-md': resolveColSpan(section, 'md'),
+          '--cpub-section-cols-lg': resolveColSpan(section, 'lg'),
+        }"
+      >
+        <!--
+          Section render path:
+            1. Look up the section's `type` in the registry (one shared
+               instance per app process, populated at module-load time in
+               sections/registry.ts).
+            2. If registered, render via <component :is> with the section's
+               `config` + computed `meta`. Vue's component-resolver handles
+               both functional + SFC renderers.
+            3. If NOT registered, fall back to the admin-only placeholder
+               so admins can see "this section type isn't installed" while
+               end users see nothing for the section (an unknown section
+               shouldn't leak rendering debug info to the public).
+        -->
+        <component
+          v-if="sectionRegistry.has(section.type)"
+          :is="sectionRegistry.get(section.type)!.component"
+          :config="section.config"
+          :meta="{
+            route,
+            zone,
+            isPreview: !!previewOverride,
+            effectiveColSpan: resolveColSpan(section, 'lg'),
+            sectionId: section.id,
+          }"
+        />
+        <div
+          v-else
+          class="cpub-layout-section-placeholder"
+          :aria-label="`Unregistered section type: ${section.type}`"
+        >
+          <code>{{ section.type }}</code>
+          <span class="cpub-layout-section-placeholder-hint">section type not registered</span>
+        </div>
+      </div>
+    </div>
+  </template>
+
+  <!-- Loading shimmer while initial fetch is in flight (no layout payload yet) -->
+  <div v-else-if="pending && !previewOverride" class="cpub-layout-skeleton" aria-hidden="true">
+    <div class="cpub-layout-skeleton-row" />
+    <div class="cpub-layout-skeleton-row" />
+  </div>
+</template>
+
+<style scoped>
+.cpub-layout-row {
+  display: grid;
+  grid-template-columns: repeat(12, 1fr);
+  gap: var(--space-4);
+  width: 100%;
+}
+.cpub-layout-row[data-gap='none'] { gap: 0; }
+.cpub-layout-row[data-gap='sm']   { gap: var(--space-2); }
+.cpub-layout-row[data-gap='md']   { gap: var(--space-4); }
+.cpub-layout-row[data-gap='lg']   { gap: var(--space-6); }
+
+.cpub-layout-row[data-align='center'] { align-items: center; }
+.cpub-layout-row[data-align='start']  { align-items: start; }
+.cpub-layout-row[data-align='stretch'] { align-items: stretch; }
+
+.cpub-layout-row[data-padding-y='sm'] { padding-block: var(--space-2); }
+.cpub-layout-row[data-padding-y='md'] { padding-block: var(--space-4); }
+.cpub-layout-row[data-padding-y='lg'] { padding-block: var(--space-6); }
+.cpub-layout-row[data-padding-y='xl'] { padding-block: var(--space-8); }
+
+/* Section span: default to lg (desktop). Media queries swap.
+   --cpub-section-cols-* are set per-section via inline style. */
+.cpub-layout-section {
+  grid-column: span var(--cpub-section-cols-lg, 12);
+  min-width: 0;
+}
+
+@media (max-width: 1024px) {
+  .cpub-layout-section { grid-column: span var(--cpub-section-cols-md, var(--cpub-section-cols-lg, 12)); }
+}
+@media (max-width: 640px) {
+  .cpub-layout-section { grid-column: span var(--cpub-section-cols-sm, 12); }
+}
+
+/* hideAt — orthogonal to colSpan. Use display:none so layout doesn't reserve space. */
+.cpub-layout-section[data-hide-sm='true'] { @media (max-width: 640px) { display: none; } }
+.cpub-layout-section[data-hide-md='true'] { @media (min-width: 641px) and (max-width: 1024px) { display: none; } }
+.cpub-layout-section[data-hide-lg='true'] { @media (min-width: 1025px) { display: none; } }
+
+/* Placeholder shown when no renderer is registered for the section type */
+.cpub-layout-section-placeholder {
+  padding: var(--space-4);
+  background: var(--surface2);
+  border: 1px dashed var(--border2);
+  font-family: var(--font-mono);
+  font-size: var(--text-sm);
+  color: var(--text-dim);
+  text-align: center;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  align-items: center;
+}
+.cpub-layout-section-placeholder code {
+  color: var(--accent);
+}
+.cpub-layout-section-placeholder-hint {
+  font-size: var(--text-xs);
+  color: var(--text-faint);
+}
+
+/* Skeleton loading state */
+.cpub-layout-skeleton {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-4);
+  padding: var(--space-4);
+}
+.cpub-layout-skeleton-row {
+  height: 60px;
+  background: linear-gradient(90deg, var(--surface2) 25%, var(--surface3) 50%, var(--surface2) 75%);
+  background-size: 200% 100%;
+  animation: cpub-layout-skel 1.4s ease-in-out infinite;
+}
+@keyframes cpub-layout-skel {
+  0% { background-position: 200% 0; }
+  100% { background-position: -200% 0; }
+}
+@media (prefers-reduced-motion: reduce) {
+  .cpub-layout-skeleton-row { animation: none; }
+}
+</style>

package/components/sections/SectionContentFeed.vue

@@ -0,0 +1,160 @@
+<script setup lang="ts">
+/**
+ * Built-in section: content-feed — a data-driven grid of content cards.
+ *
+ * Phase 1c starter and the first DATA section. Fetches `/api/content`
+ * with config-driven filter parameters; renders the existing
+ * `<ContentCard>` so the visual identity matches feeds elsewhere on the
+ * site.
+ *
+ * Each instance fetches independently (no global feed cache) — Nuxt's
+ * useFetch dedupes by `key`, which we derive from the config so two
+ * identically-configured feeds share a single request while two
+ * differently-configured feeds (e.g. main + sidebar with different
+ * `sort`) hit the endpoint separately.
+ *
+ * SSR-safe: useFetch fetches at setup() and includes the payload in the
+ * hydration snapshot.
+ *
+ * `var(--*)` only.
+ */
+import { computed } from 'vue';
+import type { PaginatedResponse, Serialized, ContentListItem } from '@commonpub/server';
+import type { SectionRenderProps } from '@commonpub/ui';
+
+interface ContentFeedConfig extends Record<string, unknown> {
+  heading: string;
+  contentType: string;
+  sort: 'recent' | 'popular' | 'featured' | 'editorial';
+  limit: number;
+  columns: 1 | 2 | 3 | 4;
+  tag: string;
+  featured: boolean;
+}
+
+const props = defineProps<SectionRenderProps<ContentFeedConfig>>();
+
+// Build the API query — server expects `type` (single value or absent),
+// `sort`, `limit`, `tag`, `featured`. Omit empty strings so the validator
+// treats them as absent (vs the empty-string=match-empty trap).
+const apiQuery = computed(() => {
+  const q: Record<string, unknown> = {
+    status: 'published',
+    sort: props.config.sort,
+    limit: Math.min(Math.max(props.config.limit, 1), 24),
+  };
+  if (props.config.contentType) q.type = props.config.contentType;
+  if (props.config.tag) q.tag = props.config.tag;
+  if (props.config.featured) q.featured = true;
+  return q;
+});
+
+// Stable key so two identical content-feed sections on the same page
+// share a single request, while different configurations don't collide.
+const fetchKey = computed(
+  () => `section-content-feed:${JSON.stringify(apiQuery.value)}`,
+);
+
+// NO await — section is rendered inside <LayoutSlot> deep in the tree;
+// awaiting top-level here would require Suspense on every parent, which
+// neither the production page-render path nor the editor preview pane
+// is set up for. The page (`/`, `/about`, etc.) already does its own
+// `await useFetch` for content via the legacy renderer, so initial
+// load is data-ready; this section's fetch is a fresh request per
+// instance + config. Pending state surfaces in the template instead.
+const { data: feed, pending } = useFetch<PaginatedResponse<Serialized<ContentListItem>>>(
+  '/api/content',
+  {
+    query: apiQuery,
+    key: fetchKey.value,
+    // Empty-result handler: surface a friendly empty state in the template
+    // rather than throwing. 404 wouldn't be a thing on /api/content anyway.
+  },
+);
+
+const items = computed(() => feed.value?.items ?? []);
+const isEmpty = computed(() => !pending.value && items.value.length === 0);
+</script>
+
+<template>
+  <section
+    class="cpub-section-content-feed"
+    :aria-labelledby="config.heading ? `section-feed-${meta.sectionId}` : undefined"
+  >
+    <h2
+      v-if="config.heading"
+      :id="`section-feed-${meta.sectionId}`"
+      class="cpub-section-content-feed-heading"
+    >
+      {{ config.heading }}
+    </h2>
+
+    <div v-if="pending" class="cpub-section-content-feed-loading">
+      <i class="fa-solid fa-circle-notch fa-spin" aria-hidden="true" />
+      <span>Loading…</span>
+    </div>
+
+    <div
+      v-else-if="!isEmpty"
+      class="cpub-section-content-feed-grid"
+      :data-columns="config.columns"
+    >
+      <ContentCard
+        v-for="item in items"
+        :key="item.id"
+        :item="item"
+      />
+    </div>
+
+    <p v-else class="cpub-section-content-feed-empty">
+      No content yet.
+    </p>
+  </section>
+</template>
+
+<style scoped>
+.cpub-section-content-feed {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-3);
+}
+.cpub-section-content-feed-heading {
+  font-family: var(--font-mono);
+  font-size: var(--text-xs);
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--text-faint);
+  margin: 0;
+  padding-bottom: var(--space-2);
+  border-bottom: var(--border-width-default) solid var(--border);
+}
+.cpub-section-content-feed-grid {
+  display: grid;
+  gap: var(--space-3);
+}
+.cpub-section-content-feed-grid[data-columns='1'] { grid-template-columns: 1fr; }
+.cpub-section-content-feed-grid[data-columns='2'] { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+.cpub-section-content-feed-grid[data-columns='3'] { grid-template-columns: repeat(3, minmax(0, 1fr)); }
+.cpub-section-content-feed-grid[data-columns='4'] { grid-template-columns: repeat(4, minmax(0, 1fr)); }
+
+/* Responsive collapse — multi-col grids stack on tablet/mobile */
+@media (max-width: 1024px) {
+  .cpub-section-content-feed-grid[data-columns='3'],
+  .cpub-section-content-feed-grid[data-columns='4'] { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+}
+@media (max-width: 640px) {
+  .cpub-section-content-feed-grid { grid-template-columns: 1fr; }
+}
+
+.cpub-section-content-feed-loading,
+.cpub-section-content-feed-empty {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--space-2);
+  padding: var(--space-6);
+  color: var(--text-faint);
+  font-size: var(--text-sm);
+}
+</style>

package/components/sections/SectionDivider.vue

@@ -0,0 +1,55 @@
+<script setup lang="ts">
+/**
+ * Built-in section: divider — a horizontal rule.
+ *
+ * Phase 1 proof-of-life — the simplest possible section, validating that:
+ *   - `SectionRegistry.register()` accepts a Vue component
+ *   - `<LayoutSlot>` resolves the section type slug to a renderer
+ *   - The renderer receives `config` + `meta` and produces DOM
+ *
+ * Phase 1c adds the real catalogue (hero / heading / paragraph / image /
+ * content-feed). Until then, dropping a divider into a layout is the
+ * end-to-end smoke test of the layout engine.
+ *
+ * Uses `var(--*)` only (rule #3); inherits all colors / spacing from
+ * the active theme.
+ */
+import type { SectionRenderProps } from '@commonpub/ui';
+
+interface DividerConfig extends Record<string, unknown> {
+  variant: 'solid' | 'dashed' | 'dotted' | 'accent';
+  spacingY: 'sm' | 'md' | 'lg' | 'xl';
+}
+
+defineProps<SectionRenderProps<DividerConfig>>();
+</script>
+
+<template>
+  <hr
+    class="cpub-section-divider"
+    :data-variant="config.variant"
+    :data-spacing-y="config.spacingY"
+    :aria-label="`section ${meta.sectionId}`"
+  />
+</template>
+
+<style scoped>
+.cpub-section-divider {
+  margin-block: var(--space-4);
+  border: 0;
+  border-top: var(--border-width-default) solid var(--border2);
+  width: 100%;
+}
+
+.cpub-section-divider[data-variant='dashed'] { border-top-style: dashed; }
+.cpub-section-divider[data-variant='dotted'] { border-top-style: dotted; }
+.cpub-section-divider[data-variant='accent']  {
+  border-top-color: var(--accent);
+  border-top-width: var(--border-width-thick);
+}
+
+.cpub-section-divider[data-spacing-y='sm']  { margin-block: var(--space-2); }
+.cpub-section-divider[data-spacing-y='md']  { margin-block: var(--space-4); }
+.cpub-section-divider[data-spacing-y='lg']  { margin-block: var(--space-6); }
+.cpub-section-divider[data-spacing-y='xl']  { margin-block: var(--space-8); }
+</style>

package/components/sections/SectionHeading.vue

@@ -0,0 +1,78 @@
+<script setup lang="ts">
+/**
+ * Built-in section: heading — a single configurable heading (h1–h4)
+ * with optional eyebrow + subline.
+ *
+ * Phase 1c starter. Semantic level is admin-chosen — the auto-form
+ * inspector (Phase 3e) will warn on multiple h1s per layout.
+ *
+ * `var(--*)` only.
+ */
+import { computed } from 'vue';
+import type { SectionRenderProps } from '@commonpub/ui';
+
+interface HeadingConfig extends Record<string, unknown> {
+  text: string;
+  level: 1 | 2 | 3 | 4;
+  align: 'left' | 'center';
+  eyebrow: string;
+  subline: string;
+}
+
+const props = defineProps<SectionRenderProps<HeadingConfig>>();
+
+// Vue's <component :is> with a tag string handles the level swap without
+// needing a v-if chain. Defensive clamp: an out-of-range level (shouldn't
+// happen — Zod gates it on write) falls back to h2.
+const headingTag = computed(() => {
+  const n = props.config.level;
+  return n >= 1 && n <= 4 ? `h${n}` : 'h2';
+});
+</script>
+
+<template>
+  <section
+    class="cpub-section-heading"
+    :data-align="config.align"
+    :aria-labelledby="`section-heading-${meta.sectionId}`"
+  >
+    <p v-if="config.eyebrow" class="cpub-section-heading-eyebrow">{{ config.eyebrow }}</p>
+    <component
+      :is="headingTag"
+      :id="`section-heading-${meta.sectionId}`"
+      class="cpub-section-heading-text"
+    >
+      {{ config.text }}
+    </component>
+    <p v-if="config.subline" class="cpub-section-heading-subline">{{ config.subline }}</p>
+  </section>
+</template>
+
+<style scoped>
+.cpub-section-heading {
+  margin-block: var(--space-4);
+}
+.cpub-section-heading[data-align='center'] {
+  text-align: center;
+}
+.cpub-section-heading-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-heading-text {
+  margin: 0;
+  font-weight: 700;
+  line-height: 1.25;
+  color: var(--text);
+}
+.cpub-section-heading-subline {
+  margin: var(--space-2) 0 0;
+  color: var(--text-dim);
+  font-size: var(--text-md);
+  line-height: 1.6;
+}
+</style>