@commonpub/layer 0.24.0 → 0.25.1

package/components/homepage/ContentGridSection.vue

@@ -123,7 +123,29 @@ const columns = computed(() => props.config.columns ?? 2);
 .cpub-tab:hover { color: var(--text); }
 .cpub-tab.active { color: var(--accent); border-bottom-color: var(--accent); }
 
-.cpub-content-grid { display: grid; grid-template-columns: repeat(var(--grid-cols, 2), 1fr); gap: 16px; }
+/*
+ * Session 164 polish: cap the grid's max width so cards don't stretch
+ * into a "giant cards in mobile layout" pattern at desktop widths.
+ *
+ * Was: `grid-template-columns: repeat(2, 1fr)` with NO width cap → at
+ * 1440px window, 2 columns of ~700px each. Cards stretched far past
+ * their natural design width and read as "single column of bigs".
+ *
+ * Now: same column behavior but bounded by --content-max-width (default
+ * 1280px) — matches the tabs-inner cap above (same theme token). At
+ * 1280px and below, behaves identically to before. Above, the grid
+ * stays at 1280 centered and cards stay at their design proportions.
+ *
+ * `var(--grid-cols)` config still drives column count. Mobile drops to
+ * 1-column at <=768px (unchanged).
+ */
+.cpub-content-grid {
+  display: grid;
+  grid-template-columns: repeat(var(--grid-cols, 2), 1fr);
+  gap: 16px;
+  max-width: var(--content-max-width, 1280px);
+  margin-inline: auto;
+}
 
 .cpub-load-more-row { text-align: center; padding: 24px 0; }
 .cpub-btn-load-more { font-family: var(--font-mono); font-size: 11px; padding: 8px 20px; border: var(--border-width-default) solid var(--border); background: var(--surface); color: var(--text-dim); cursor: pointer; display: inline-flex; align-items: center; gap: 6px; }

package/components/homepage/HeroSection.vue

@@ -1,7 +1,15 @@
 <script setup lang="ts">
+import { computed } from 'vue';
 import type { HomepageSectionConfig } from '@commonpub/server';
 
-defineProps<{ config: HomepageSectionConfig }>();
+interface HeroCta {
+  label: string;
+  href: string;
+  variant?: 'primary' | 'secondary';
+  icon?: string;  // Font Awesome class (e.g. 'fa-plus'); optional
+}
+
+const props = defineProps<{ config: HomepageSectionConfig }>();
 
 const { contests: contestsEnabled } = useFeatures();
 const { data: contests } = await useFetch('/api/contests', { query: { limit: 3 }, lazy: true });
@@ -11,6 +19,49 @@ const activeContest = computed(() => {
   return items?.find((c) => c.status === 'active') ?? null;
 });
 
+// Config-driven overrides (Stage E session 159 — finally wired). The
+// legacy admin form (/admin/homepage) has accepted `customTitle` +
+// `customSubtitle` for a long time, but the renderer ignored them —
+// admin would type a custom title and see no change. Now respected.
+//
+// Hardcoded fallbacks preserve the existing "Build. Document. Share."
+// + Open Source eyebrow + Start Building/Explore CTAs when admin
+// hasn't customised anything.
+//
+// Contest-aware swap still wins when there's an active contest +
+// `features.contests` is on — the contest hero is intentionally not
+// overridable because it pulls live data; admins who want fully-static
+// copy can either disable the contests flag or set customTitle which
+// applies in the non-contest branch.
+const heroTitle = computed(() => {
+  const cfg = props.config as { customTitle?: string };
+  return cfg.customTitle?.trim() || 'Build. Document. Share.';
+});
+const heroTitleIsCustom = computed(() => {
+  const cfg = props.config as { customTitle?: string };
+  return !!cfg.customTitle?.trim();
+});
+const heroSubtitle = computed(() => {
+  const cfg = props.config as { customSubtitle?: string };
+  return cfg.customSubtitle?.trim() ||
+    'CommonPub is an open platform for maker communities. Document your builds with rich editors, join hubs, learn with structured paths, and share with the world.';
+});
+const heroEyebrow = computed(() => {
+  const cfg = props.config as { eyebrow?: string };
+  return cfg.eyebrow?.trim() || 'Open Source';
+});
+const heroCtas = computed<HeroCta[]>(() => {
+  const cfg = props.config as { ctas?: HeroCta[] };
+  if (Array.isArray(cfg.ctas) && cfg.ctas.length > 0) return cfg.ctas;
+  // Hardcoded fallbacks keep the legacy hero's exact look: icons +
+  // canonical labels. Admin-set ctas (no icon field in the legacy
+  // admin form) render without icons by design.
+  return [
+    { label: 'Start Building', href: '/create', variant: 'primary', icon: 'fa-plus' },
+    { label: 'Explore', href: '/explore', variant: 'secondary', icon: 'fa-compass' },
+  ];
+});
+
 // Shared via useState so the dismiss sticks across component remounts.
 // HomepageSectionRenderer's v-if wrappers can remount HeroSection when the
 // `sections` useFetch revalidates on hydration or when feature flags flip
@@ -51,15 +102,25 @@ function dismissHero(): void {
         </template>
         <template v-else>
           <div class="cpub-hero-eyebrow">
-            <span class="cpub-hero-badge cpub-hero-badge-live"><span class="cpub-live-dot" /> Open Source</span>
+            <span class="cpub-hero-badge cpub-hero-badge-live"><span class="cpub-live-dot" /> {{ heroEyebrow }}</span>
           </div>
-          <h1 class="cpub-hero-title">Build. Document.<br><span>Share.</span></h1>
-          <p class="cpub-hero-excerpt">
-            CommonPub is an open platform for maker communities. Document your builds with rich editors, join hubs, learn with structured paths, and share with the world.
-          </p>
+          <!-- When admin supplied a customTitle, show as plain text. The
+               hardcoded fallback uses inline <br> + accent span for the
+               canonical "Build. Document. Share." typography. -->
+          <h1 v-if="heroTitleIsCustom" class="cpub-hero-title">{{ heroTitle }}</h1>
+          <h1 v-else class="cpub-hero-title">Build. Document.<br><span>Share.</span></h1>
+          <p class="cpub-hero-excerpt">{{ heroSubtitle }}</p>
           <div class="cpub-hero-actions">
-            <NuxtLink to="/create" class="cpub-btn cpub-btn-primary"><i class="fa-solid fa-plus"></i> Start Building</NuxtLink>
-            <NuxtLink to="/explore" class="cpub-btn"><i class="fa-solid fa-compass"></i> Explore</NuxtLink>
+            <NuxtLink
+              v-for="(cta, i) in heroCtas"
+              :key="i"
+              :to="cta.href"
+              class="cpub-btn"
+              :class="cta.variant === 'primary' ? 'cpub-btn-primary' : ''"
+            >
+              <i v-if="cta.icon" :class="['fa-solid', cta.icon]" aria-hidden="true" />
+              {{ cta.label }}
+            </NuxtLink>
           </div>
         </template>
       </div>

package/components/sections/SectionCta.vue

@@ -0,0 +1,175 @@
+<script setup lang="ts">
+/**
+ * Built-in section: cta — call-to-action panel.
+ *
+ * Heading + body + up to 3 buttons. Three variants:
+ *   default  → boxed panel with subtle border
+ *   contrast → accent-background inverse
+ *   minimal  → no panel, just text + buttons
+ *
+ * URL safety: href values are validated at WRITE time by the section's
+ * Zod schema (SAFE_LINK_URL regex). Renderer doesn't re-validate
+ * because Vue's :href binding doesn't sanitise — the regex IS the guard.
+ *
+ * `var(--*)` only.
+ */
+import type { SectionRenderProps } from '@commonpub/ui';
+
+interface CtaButton {
+  label: string;
+  href: string;
+  variant: 'primary' | 'secondary' | 'ghost';
+}
+
+interface CtaConfig extends Record<string, unknown> {
+  variant: 'default' | 'contrast' | 'minimal';
+  heading: string;
+  body: string;
+  buttons: CtaButton[];
+  align: 'left' | 'center';
+}
+
+const props = defineProps<SectionRenderProps<CtaConfig>>();
+void props;
+</script>
+
+<template>
+  <section
+    class="cpub-section-cta"
+    :data-variant="config.variant"
+    :data-align="config.align"
+    :aria-labelledby="`section-cta-${meta.sectionId}`"
+  >
+    <h2
+      :id="`section-cta-${meta.sectionId}`"
+      class="cpub-section-cta-heading"
+    >
+      {{ config.heading }}
+    </h2>
+
+    <p v-if="config.body" class="cpub-section-cta-body">
+      {{ config.body }}
+    </p>
+
+    <div v-if="config.buttons.length > 0" class="cpub-section-cta-actions">
+      <a
+        v-for="(btn, idx) in config.buttons"
+        :key="idx"
+        :href="btn.href"
+        :class="`cpub-section-cta-btn cpub-section-cta-btn-${btn.variant}`"
+      >
+        {{ btn.label }}
+      </a>
+    </div>
+  </section>
+</template>
+
+<style scoped>
+.cpub-section-cta {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-3);
+  padding: var(--space-5);
+}
+
+/* default — boxed */
+.cpub-section-cta[data-variant='default'] {
+  background: var(--surface);
+  border: var(--border-width-default) solid var(--border);
+}
+
+/* contrast — accent inverse */
+.cpub-section-cta[data-variant='contrast'] {
+  background: var(--accent);
+  color: var(--surface);
+  border: var(--border-width-default) solid var(--accent);
+}
+.cpub-section-cta[data-variant='contrast'] .cpub-section-cta-heading,
+.cpub-section-cta[data-variant='contrast'] .cpub-section-cta-body {
+  color: inherit;
+}
+
+/* minimal — no panel */
+.cpub-section-cta[data-variant='minimal'] {
+  background: transparent;
+  border: none;
+  padding: var(--space-3) 0;
+}
+
+/* align */
+.cpub-section-cta[data-align='center'] {
+  text-align: center;
+  align-items: center;
+}
+.cpub-section-cta[data-align='center'] .cpub-section-cta-actions {
+  justify-content: center;
+}
+
+.cpub-section-cta-heading {
+  font-size: var(--text-xl);
+  font-weight: 700;
+  color: var(--text);
+  margin: 0;
+}
+.cpub-section-cta-body {
+  font-size: var(--text-base);
+  line-height: 1.7;
+  color: var(--text-soft);
+  margin: 0;
+  max-width: 60ch;
+}
+.cpub-section-cta-actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-2);
+  margin-top: var(--space-2);
+}
+
+/* buttons — three variants */
+.cpub-section-cta-btn {
+  font-family: var(--font-mono);
+  font-size: var(--text-xs);
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  padding: var(--space-2) var(--space-4);
+  border: var(--border-width-default) solid var(--accent);
+  text-decoration: none;
+  display: inline-block;
+}
+.cpub-section-cta-btn-primary {
+  background: var(--accent);
+  color: var(--surface);
+}
+.cpub-section-cta-btn-primary:hover {
+  background: var(--accent-strong, var(--accent));
+}
+.cpub-section-cta-btn-secondary {
+  background: transparent;
+  color: var(--accent);
+}
+.cpub-section-cta-btn-secondary:hover {
+  background: var(--accent-bg);
+}
+.cpub-section-cta-btn-ghost {
+  border-color: transparent;
+  background: transparent;
+  color: var(--text);
+}
+.cpub-section-cta-btn-ghost:hover {
+  color: var(--accent);
+}
+/* Contrast variant — invert button colours so they read on accent bg */
+.cpub-section-cta[data-variant='contrast'] .cpub-section-cta-btn-primary {
+  background: var(--surface);
+  color: var(--accent);
+  border-color: var(--surface);
+}
+.cpub-section-cta[data-variant='contrast'] .cpub-section-cta-btn-secondary {
+  border-color: var(--surface);
+  color: var(--surface);
+}
+.cpub-section-cta[data-variant='contrast'] .cpub-section-cta-btn-ghost {
+  color: var(--surface);
+}
+</style>

package/composables/autoFormSchema.ts

@@ -0,0 +1,319 @@
+/**
+ * autoFormSchema — pure Zod → form-field descriptor engine (Phase 3e).
+ *
+ * Converts a section's `configSchema` (a `z.ZodType`) into a normalized
+ * `AutoFormField[]` that `<AdminLayoutsInspectorSection>` /
+ * `<AdminLayoutsInspectorRow>` render as native inputs reusing the
+ * `cpub-inspector-page-*` design language.
+ *
+ * ## Why hand-rolled, not FormKit (session 167 decision)
+ *
+ * The Phase 3 plan + `feedback-phase-3-hybrid-libraries` prescribed
+ * `@formkit/zod` for this. Verified against source at session 167:
+ *   1. `@formkit/zod`'s `createZodPlugin` adds VALIDATION ONLY to a form
+ *      whose inputs you hand-author — it does NOT generate fields from a
+ *      schema (formkit.com/plugins/zod). It delivers none of Phase 3e's
+ *      auto-gen goal.
+ *   2. `@formkit/zod@2.0.0` peer-deps `zod@^3`; the monorepo is on
+ *      `zod@4.3.6` everywhere. FormKit has not shipped Zod 4 support.
+ * The plan's risk register pre-authorized this exact fallback ("fall back
+ * to a hand-rolled <AutoForm> — Phase 3e decision"). See
+ * `project-session-167-formkit-pivot` memory.
+ *
+ * ## How it works
+ *
+ * Zod 4 ships a native `z.toJSONSchema()` that emits a complete, stable
+ * JSON Schema (type/enum/minLength/maxLength/pattern/minimum/maximum/
+ * minItems/maxItems/default/nested items+properties/required). We walk
+ * THAT (a well-specified format) rather than poking Zod internals, so the
+ * engine is resilient to Zod's internal churn. The §7.10 input-mapping
+ * table maps 1:1 onto JSON Schema node kinds.
+ *
+ * The engine is intentionally framework-free (no Vue imports) so it is
+ * unit-testable in isolation — per `feedback-css-cascade-unit-test-blind-spot`,
+ * keeping the LOGIC pure means the only place a CSS-cascade bug can hide
+ * is the `.vue` view, which gets the fresh-eyes pass.
+ */
+import { z, type ZodType } from 'zod';
+
+/** The native input control a field maps to. */
+export type AutoFormControl =
+  | 'text'
+  | 'textarea'
+  | 'number'
+  | 'select'
+  | 'toggle'
+  | 'array'
+  | 'group'
+  | 'unsupported';
+
+export interface AutoFormOption {
+  value: string | number;
+  label: string;
+}
+
+export interface AutoFormField {
+  /** Object key in the config blob (also the `name` for refs / labels). */
+  key: string;
+  /** Humanized label derived from `key` (e.g. `customTitle` → "Custom title"). */
+  label: string;
+  /** The control to render. */
+  control: AutoFormControl;
+  /**
+   * Whether the field is required IN FORM TERMS — i.e. present in the
+   * schema's `required` array AND has no `default`. A field with a default
+   * is pre-filled, so it never blocks the user; we don't asterisk it.
+   */
+  required: boolean;
+  /**
+   * True when the field can legitimately be ABSENT — not in `required` AND
+   * no `default` (e.g. the optional row-config enums). Selects use this to
+   * offer a leading "default/unset" option so a `undefined` value doesn't
+   * masquerade as the first real choice being selected.
+   */
+  optional: boolean;
+  /** JSON Schema `description` — reserved for the §7.10 `keyword:arg`
+   *  rich-field extension (rich/content-picker/image/color). Unused in v1. */
+  description?: string;
+  /** Schema default, if any. */
+  defaultValue?: unknown;
+  // --- string constraints ---
+  minLength?: number;
+  maxLength?: number;
+  /** Regex source string (e.g. URL guards). Carried for inline validation. */
+  pattern?: string;
+  // --- number constraints ---
+  min?: number;
+  max?: number;
+  /** Step granularity — 1 for integers, undefined (any) for floats. */
+  step?: number;
+  // --- select (enum + union-of-const) ---
+  options?: AutoFormOption[];
+  // --- array (repeater) ---
+  /** For `array<object>`: the per-item sub-fields. */
+  itemFields?: AutoFormField[];
+  /** A blank item to append when the user clicks "+ Add". */
+  itemDefault?: unknown;
+  minItems?: number;
+  maxItems?: number;
+  // --- group (nested object) ---
+  fields?: AutoFormField[];
+}
+
+export interface AutoFormModel {
+  fields: AutoFormField[];
+  /** True when the schema exposes no editable properties (e.g. `stats`). */
+  isEmpty: boolean;
+}
+
+/**
+ * maxLength at/above which a string renders as a multi-line textarea
+ * instead of a single-line input. Tuned against the real section schemas:
+ * caption(480)/subtitle(500)/body(800)/markdown(100k)/html(8k,50k) become
+ * textareas; title(240)/heading(240)/name(255)/alt(240) stay single-line.
+ * URL-pattern strings bypass this (see the `string` branch) — they're
+ * single-line regardless of their 2048 cap.
+ */
+const LONG_TEXT_THRESHOLD = 480;
+
+type JsonNode = Record<string, unknown>;
+
+/** `#/$defs/Foo` → root.$defs.Foo. Zod inlines single-use subschemas but
+ *  emits $ref/$defs when one is reused; resolve defensively either way. */
+function resolveRef(node: JsonNode | undefined, root: JsonNode): JsonNode {
+  if (!node) return {};
+  const ref = node['$ref'];
+  if (typeof ref !== 'string') return node;
+  // Only the local "#/$defs/Name" form is produced by z.toJSONSchema.
+  const m = /^#\/\$defs\/(.+)$/.exec(ref);
+  if (!m) return node;
+  const defs = root['$defs'] as Record<string, JsonNode> | undefined;
+  const target = defs?.[m[1]!];
+  // Merge so sibling keywords on the $ref node (rare) aren't lost.
+  return target ? { ...target, ...stripRef(node) } : node;
+}
+
+function stripRef(node: JsonNode): JsonNode {
+  const { ['$ref']: _ref, ...rest } = node;
+  return rest;
+}
+
+/** `customTitle` → "Custom title"; `paddingY` → "Padding y"; `categorySlug` → "Category slug". */
+export function humanizeKey(key: string): string {
+  const spaced = key
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/[_-]+/g, ' ')
+    .trim()
+    .toLowerCase();
+  return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+
+/** Enum value → display label. Keeps short slugs as-is (they're already
+ *  terse design tokens like "sm"/"primary"); just trims. Numbers stringify. */
+function optionLabel(value: string | number): string {
+  return String(value);
+}
+
+function isConstUnion(node: JsonNode): node is JsonNode & { anyOf: JsonNode[] } {
+  const anyOf = node['anyOf'];
+  return Array.isArray(anyOf) && anyOf.length > 0 && anyOf.every((o) => o && typeof o === 'object' && 'const' in o);
+}
+
+/** Walk one object node's `properties` into fields. */
+function objectToFields(node: JsonNode, root: JsonNode): AutoFormField[] {
+  const properties = (node['properties'] as Record<string, JsonNode> | undefined) ?? {};
+  const required = Array.isArray(node['required']) ? (node['required'] as string[]) : [];
+  return Object.entries(properties).map(([key, raw]) => nodeToField(key, raw, root, required.includes(key)));
+}
+
+function nodeToField(
+  key: string,
+  rawNode: JsonNode,
+  root: JsonNode,
+  inRequiredArray: boolean,
+): AutoFormField {
+  const node = resolveRef(rawNode, root);
+  const defaultValue = node['default'];
+  // Form-required: in the required list AND no default to pre-fill it.
+  const required = inRequiredArray && defaultValue === undefined;
+  // Optional: absent-allowed (not required) AND no default to fall back to.
+  const optional = !inRequiredArray && defaultValue === undefined;
+  const base: AutoFormField = {
+    key,
+    label: humanizeKey(key),
+    control: 'unsupported',
+    required,
+    optional,
+    defaultValue,
+  };
+  const description = node['description'];
+  if (typeof description === 'string') base.description = description;
+
+  // 1. Union of literal consts (heading.level, content-feed.columns,
+  //    learning.columns) — z.union([z.literal(1), …]) → anyOf:[{const}].
+  if (isConstUnion(node)) {
+    base.control = 'select';
+    base.options = node.anyOf.map((o) => {
+      const v = o['const'] as string | number;
+      return { value: v, label: optionLabel(v) };
+    });
+    return base;
+  }
+
+  // 2. String enum → select.
+  if (Array.isArray(node['enum'])) {
+    base.control = 'select';
+    base.options = (node['enum'] as Array<string | number>).map((v) => ({ value: v, label: optionLabel(v) }));
+    return base;
+  }
+
+  const type = node['type'];
+  switch (type) {
+    case 'boolean':
+      base.control = 'toggle';
+      return base;
+
+    case 'integer':
+    case 'number':
+      base.control = 'number';
+      if (typeof node['minimum'] === 'number') base.min = node['minimum'] as number;
+      if (typeof node['maximum'] === 'number') base.max = node['maximum'] as number;
+      base.step = type === 'integer' ? 1 : undefined;
+      return base;
+
+    case 'string': {
+      if (typeof node['maxLength'] === 'number') base.maxLength = node['maxLength'] as number;
+      if (typeof node['minLength'] === 'number') base.minLength = node['minLength'] as number;
+      // Pattern strings are URLs/paths in our schemas — single-line text,
+      // NOT <input type=url> (which would reject valid root-relative paths
+      // like `/about`). Carry the pattern for our own inline validation.
+      if (typeof node['pattern'] === 'string') {
+        base.control = 'text';
+        base.pattern = node['pattern'] as string;
+        return base;
+      }
+      base.control = base.maxLength !== undefined && base.maxLength >= LONG_TEXT_THRESHOLD ? 'textarea' : 'text';
+      return base;
+    }
+
+    case 'array': {
+      base.control = 'array';
+      if (typeof node['minItems'] === 'number') base.minItems = node['minItems'] as number;
+      if (typeof node['maxItems'] === 'number') base.maxItems = node['maxItems'] as number;
+      const items = resolveRef(node['items'] as JsonNode | undefined, root);
+      if (items['type'] === 'object' || items['properties']) {
+        base.itemFields = objectToFields(items, root);
+        base.itemDefault = buildDefaults(base.itemFields);
+      } else {
+        // Scalar array (none in v1 builtins, but handle generically).
+        const itemField = nodeToField('item', items, root, false);
+        base.itemFields = [itemField];
+        base.itemDefault = blankFor(itemField);
+      }
+      return base;
+    }
+
+    case 'object': {
+      base.control = 'group';
+      base.fields = objectToFields(node, root);
+      return base;
+    }
+
+    default:
+      // Unknown / unrepresentable — render read-only so the admin sees the
+      // field exists but can't corrupt it. R3 ops: forward-compat for new
+      // Zod kinds a future schema introduces.
+      base.control = 'unsupported';
+      return base;
+  }
+}
+
+/** A sensible blank value for a freshly-added array item / group. */
+function blankFor(field: AutoFormField): unknown {
+  if (field.defaultValue !== undefined) return field.defaultValue;
+  switch (field.control) {
+    case 'text':
+    case 'textarea':
+      return '';
+    case 'number':
+      return field.min ?? 0;
+    case 'toggle':
+      return false;
+    case 'select':
+      return field.options?.[0]?.value ?? '';
+    case 'array':
+      return [];
+    case 'group':
+      return field.fields ? buildDefaults(field.fields) : {};
+    default:
+      return undefined;
+  }
+}
+
+/** Build a default object from a field list (for new array items / groups). */
+export function buildDefaults(fields: AutoFormField[]): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const f of fields) out[f.key] = blankFor(f);
+  return out;
+}
+
+/**
+ * Convert a Zod schema to a normalized form model. Returns `{ fields: [],
+ * isEmpty: true }` if the schema is not an object or can't be represented
+ * (degrades gracefully — never throws into the render path).
+ */
+export function buildAutoForm(schema: ZodType): AutoFormModel {
+  let json: JsonNode;
+  try {
+    json = z.toJSONSchema(schema) as JsonNode;
+  } catch {
+    // Unrepresentable schema (z.toJSONSchema throws by default). Degrade to
+    // an empty model; the view shows the "no options" state.
+    return { fields: [], isEmpty: true };
+  }
+  if (json['type'] !== 'object' && !json['properties']) {
+    return { fields: [], isEmpty: true };
+  }
+  const fields = objectToFields(json, json);
+  return { fields, isEmpty: fields.length === 0 };
+}