@soloworks/smking-next 0.12.2 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @soloworks/smking-next
 
+## 0.13.0 — 2026-05-22
+
+**Dynamic CMS blocks — `nav-recent-posts`, `nav-taxonomy-list`, `nav-search` now render with real publish-time data.**
+
+Customer pages that include any nav-* block on the smking dashboard editor now receive the resolved snapshot baked into `block.props.snapshot` (or `block.props.index` for search). The SDK echoes it directly — zero round-trips back to smking at request time. If smking is down, the customer's page still renders the last published snapshot.
+
+### Added
+
+- **Server-side render of `nav-recent-posts` / `nav-taxonomy-list`** — `<SmkingCms>` now emits a real `<ul>` of cards (slug-linked title + excerpt + featured image + published date) instead of the prior `smk-nav-pending` placeholder. The wrapper carries `data-layout="list|grid|carousel"` so customer CSS can theme each variant.
+- **Server-side render of `nav-search`** — emits an `<input type="search">` plus a results `<ul>`, wired by an inline IIFE that does case-insensitive substring filter against the publish-time index (top 20 matches). Zero React client-component dependency on the customer side; the IIFE is `</`-escaped against `</script>` smuggling.
+- **`NavSnapshotEntry` + `NavSearchIndexEntry` types** added to the package's public type surface. Each nav block's `props` now exposes `snapshot?` (list/taxonomy) or `index?` (search) so customer code that introspects blocks gets full TS support.
+
+### Why this is a minor (0.13.0) not a patch
+
+Customer pages that previously rendered the empty `smk-nav-pending` placeholder will now show real content. If a customer's stylesheet relied on the placeholder being invisible / empty, this is a visible behavioural change — bumped to minor per semver hygiene. No API surface removals.
+
+### Pairs with
+
+- smking SaaS atomic publish — `publish-handler.ts` now resolves nav-* snapshots via `materializeBlocks` and cascade-refreshes sibling pages so a freshly published article appears in every other page's `nav-recent-posts` feed within the same webhook tick.
+
 ## 0.12.2 — 2026-05-21
 
 **Fix: `doctor` now auto-loads `.env.local` + `.env` matching Next.js convention.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soloworks/smking-next",
-  "version": "0.12.2",
+  "version": "0.13.0",
   "description": "AI-native SEO (AEO) for Next.js — auto-inject JSON-LD, FAQ, AI summary, and SEO metadata so AI crawlers (ChatGPT, Perplexity, Google AI) can cite your pages.",
   "license": "MIT",
   "homepage": "https://github.com/sillyleo/smking/tree/main/packages/smking-next",

package/src/components/smking-cms.tsx

@@ -1,5 +1,12 @@
 import { getCmsPage } from "../lib/cms-client";
-import type { Block, CmsParams } from "../types";
+import { SMKING_ELEMENTS_IIFE } from "../lib/smking-elements-iife";
+import type {
+  Block,
+  CmsParams,
+  ModuleHeader,
+  NavSearchIndexEntry,
+  NavSnapshotEntry,
+} from "../types";
 
 /**
  * Server Component that renders a published smking CMS page.
@@ -20,11 +27,13 @@ import type { Block, CmsParams } from "../types";
  *
  * v0.11+ substrate pivot: fetches a Block[] array and dispatches each
  * block by `component`. Article block carries pre-rendered HTML
- * (server-rendered at write time via tiptap-html, so the customer SDK
- * needs zero Tiptap dependencies). Hero / nav-* blocks render inline;
- * full server-side data fetch for nav-recent-posts / nav-taxonomy-list
- * / nav-search arrives in M2+ — they emit pending markers for now so
- * customer pages don't 500 if the page contains them.
+ * (server-rendered at write time via Plate's `serializeHtml`, so the
+ * customer SDK needs zero editor dependencies). Hero / carousel render
+ * inline. Dynamic nav-* blocks (`nav-recent-posts` /
+ * `nav-taxonomy-list` / `nav-search`) carry a publish-time materialized
+ * `snapshot` (or `index`) embedded in their props — SDK echoes that
+ * directly, zero round-trip back to smking. If smking is down, the
+ * customer's page still renders the last published snapshot.
  *
  * Returns null when the response isn't ready (pending / not_found /
  * unreachable / mis-configured) — fail-open by design.
@@ -42,8 +51,28 @@ export async function SmkingCms(props: CmsParams) {
   // also sets these still overrides ours where present.
   const seo = data.seo;
   const blocks = data.page.blocks ?? [];
+  // Emit the Web Component registration `<script>` once if any block
+  // needs `<smking-carousel>` / `<smking-slide>`. The IIFE is
+  // self-guarded so duplicate emits are harmless; gating here keeps
+  // zero-dep pages truly zero-byte.
+  // Web Component IIFE is needed only when the page actually contains
+  // a `<smking-carousel>`. nav-search emits its own self-contained
+  // inline IIFE (no Web Component registration needed) so we don't gate
+  // on it here.
+  const needsSmkingElements = blocks.some((b) => b.component === "carousel");
+  // IIFE source is a hand-authored package constant (not user data) —
+  // wrapping in __html here is the standard React server-side script
+  // emit pattern used elsewhere in this SDK for the article block.
+  const elementsScript: { __html: string } = { __html: SMKING_ELEMENTS_IIFE };
   return (
     <>
+      {needsSmkingElements && (
+        <script
+          data-smking="elements"
+          // eslint-disable-next-line react/no-danger -- IIFE source is a package constant.
+          dangerouslySetInnerHTML={elementsScript}
+        />
+      )}
       {seo?.title && <title data-smking="cms">{seo.title}</title>}
       {seo?.metaDescription && (
         <meta
@@ -134,21 +163,113 @@ function renderBlock(block: Block) {
           )}
         </section>
       );
-    case "nav-recent-posts":
-    case "nav-taxonomy-list":
-    case "nav-search":
-      // Server-side data fetch + render lands in M2+ alongside the
-      // public posts / taxonomy / search endpoints. Emit a marker so
-      // customer pages don't 500 if an editor publishes a page with
-      // one of these blocks before M2 ships.
+    case "carousel": {
+      // Canonical `<smking-carousel>` markup — the Web Component
+      // registered by `SMKING_ELEMENTS_IIFE` upgrades this into a
+      // swipe + nav + dots carousel on the client. Custom-element
+      // tags aren't in React's JSX intrinsic types by default; cast
+      // through a string ref so we don't need a global d.ts in the
+      // customer's package.
+      const CustomCarousel = "smking-carousel" as unknown as "section";
+      const CustomSlide = "smking-slide" as unknown as "div";
+      const aspect = block.props.aspectRatio ?? "16:9";
       return (
-        <section
+        <CustomCarousel
           key={block.id}
-          className={`smk-block smk-block--${block.component} smk-nav-pending`}
+          className="smk-block smk-block--carousel smk-carousel"
           data-block-id={block.id}
-          data-block-component={block.component}
-        />
+          data-aspect={aspect}
+        >
+          <div className="smk-carousel__viewport">
+            {block.props.slides.map((slide, i) => (
+              <CustomSlide key={i}>
+                <div className="smk-carousel__image-frame">
+                  {slide.imageUrl ? (
+                    <img
+                      src={slide.imageUrl}
+                      alt=""
+                      className="smk-carousel__image"
+                    />
+                  ) : (
+                    <div className="smk-carousel__image smk-carousel__image--placeholder" />
+                  )}
+                </div>
+                <div className="smk-carousel__caption-row">
+                  <div className="smk-carousel__caption">{slide.caption}</div>
+                  {slide.imageUrl ? (
+                    <a
+                      className="smk-carousel__download"
+                      href={slide.imageUrl}
+                      download
+                      aria-label="Download image"
+                    >
+                      <svg
+                        width="14"
+                        height="14"
+                        viewBox="0 0 24 24"
+                        fill="none"
+                        stroke="currentColor"
+                        strokeWidth={2.4}
+                        strokeLinecap="round"
+                        strokeLinejoin="round"
+                        aria-hidden
+                      >
+                        <path d="M12 5v14M5 12l7 7 7-7" />
+                      </svg>
+                    </a>
+                  ) : null}
+                </div>
+              </CustomSlide>
+            ))}
+          </div>
+          <button
+            type="button"
+            className="smk-carousel__nav-prev"
+            aria-label="Previous slide"
+          >
+            <svg
+              width="16"
+              height="16"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth={2.4}
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              aria-hidden
+            >
+              <path d="M15 18l-6-6 6-6" />
+            </svg>
+          </button>
+          <button
+            type="button"
+            className="smk-carousel__nav-next"
+            aria-label="Next slide"
+          >
+            <svg
+              width="16"
+              height="16"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth={2.4}
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              aria-hidden
+            >
+              <path d="M9 6l6 6-6 6" />
+            </svg>
+          </button>
+          <div className="smk-carousel__dots" />
+        </CustomCarousel>
       );
+    }
+    case "nav-recent-posts":
+      return renderNavList(block, "smk-nav-recent-posts");
+    case "nav-taxonomy-list":
+      return renderNavList(block, "smk-nav-taxonomy-list");
+    case "nav-search":
+      return renderNavSearch(block);
     default:
       // Forward-compat: unknown block component — emit empty marker
       // so the page renders. Better than throwing.
@@ -161,3 +282,157 @@ function renderBlock(block: Block) {
       );
   }
 }
+
+// ── nav-* render helpers ─────────────────────────────────────────────
+
+/**
+ * Card-list render for `nav-recent-posts` + `nav-taxonomy-list`. Both
+ * blocks expose the same `{heading, viewAll, layout, snapshot}` shape;
+ * only the source of the snapshot differs (resolver-side concern, not
+ * SDK-side). The `layout` prop drives the wrapper's `data-layout` attr
+ * so customer CSS can style list / grid / carousel variants. Default
+ * styling ships sufficient base CSS for the list variant to be usable
+ * without customer overrides.
+ *
+ * Slugs in the snapshot are stored without leading slash (matching the
+ * `productContent.slug` DB column); we prepend one when forming hrefs.
+ * Customer's catch-all route at `/[...slug]` resolves them.
+ */
+function renderNavList(
+  block: Extract<
+    Block,
+    { component: "nav-recent-posts" | "nav-taxonomy-list" }
+  >,
+  baseClass: string,
+) {
+  const snapshot: NavSnapshotEntry[] = block.props.snapshot ?? [];
+  const layout = block.props.layout ?? "list";
+  const heading = (block.props as ModuleHeader).heading;
+  const viewAll = (block.props as ModuleHeader).viewAll;
+
+  return (
+    <section
+      key={block.id}
+      className={`smk-block smk-block--${block.component} smk-nav ${baseClass}`}
+      data-block-id={block.id}
+      data-block-component={block.component}
+      data-layout={layout}
+    >
+      {heading && <h2 className="smk-nav__heading">{heading}</h2>}
+      {snapshot.length === 0 ? (
+        <p className="smk-nav__empty">No posts yet.</p>
+      ) : (
+        <ul className="smk-nav__list">
+          {snapshot.map((entry) => (
+            <li key={entry.slug} className="smk-nav__item">
+              <a href={`/${entry.slug}`} className="smk-nav__link">
+                {entry.featuredImageUrl && (
+                  <img
+                    src={entry.featuredImageUrl}
+                    alt=""
+                    className="smk-nav__thumb"
+                    loading="lazy"
+                  />
+                )}
+                <div className="smk-nav__meta">
+                  <h3 className="smk-nav__title">
+                    {entry.title || entry.slug}
+                  </h3>
+                  {entry.excerpt && (
+                    <p className="smk-nav__excerpt">{entry.excerpt}</p>
+                  )}
+                  {entry.publishedAt && (
+                    <time
+                      className="smk-nav__date"
+                      dateTime={entry.publishedAt}
+                    >
+                      {formatPublishedAt(entry.publishedAt)}
+                    </time>
+                  )}
+                </div>
+              </a>
+            </li>
+          ))}
+        </ul>
+      )}
+      {viewAll && (
+        <a className="smk-nav__view-all" href={viewAll.href}>
+          {viewAll.label}
+        </a>
+      )}
+    </section>
+  );
+}
+
+/**
+ * `nav-search` ships a server-rendered `<input>` + result `<ul>`, then
+ * an inline IIFE that wires keystroke → filter → list mutate. Zero
+ * client-component dependency on the customer side (no React hydration,
+ * no use client boundary). Index lives in DOM via `JSON.stringify` with
+ * `</` escape — prevents `</script>` smuggling.
+ *
+ * Match algorithm: case-insensitive substring against `title`, `excerpt`,
+ * and `slug`. Top 20 results shown. Customer can override the script by
+ * shipping their own `<SmkingSearch>` component if they want fancier
+ * matching (fuzzy, stemming, weighting).
+ */
+function renderNavSearch(
+  block: Extract<Block, { component: "nav-search" }>,
+) {
+  const index: NavSearchIndexEntry[] = block.props.index ?? [];
+  const placeholder = block.props.placeholder || "Search…";
+
+  // Escape `</` so the JSON payload can't terminate the surrounding
+  // <script> tag — standard React-docs-recommended JSON-in-script
+  // hardening, since we serialize titles / excerpts that came from
+  // arbitrary author input.
+  const indexJson = JSON.stringify(index).replace(/</g, "\\u003c");
+  const scriptSrc =
+    "(function(){var s=document.currentScript;var r=s&&s.previousElementSibling;if(!r)return;var i=r.querySelector('[data-smk-search-input]');var u=r.querySelector('[data-smk-search-results]');var e=r.querySelector('[data-smk-search-empty]');var idx=" +
+    indexJson +
+    ";function up(){var q=(i.value||'').trim().toLowerCase();u.textContent='';if(!q){u.hidden=true;e.hidden=true;return}var m=idx.filter(function(x){return((x.title||'')+' '+(x.excerpt||'')+' '+(x.slug||'')).toLowerCase().indexOf(q)>=0}).slice(0,20);if(m.length===0){u.hidden=true;e.hidden=false;return}e.hidden=true;u.hidden=false;m.forEach(function(x){var li=document.createElement('li');li.className='smk-nav-search__result';var a=document.createElement('a');a.href='/'+x.slug;a.textContent=x.title||x.slug;li.appendChild(a);u.appendChild(li)})}i.addEventListener('input',up)})();";
+
+  return (
+    <section
+      key={block.id}
+      className="smk-block smk-block--nav-search smk-nav-search"
+      data-block-id={block.id}
+    >
+      <div className="smk-nav-search__shell">
+        <input
+          type="search"
+          data-smk-search-input
+          placeholder={placeholder}
+          className="smk-nav-search__input"
+        />
+        <ul
+          data-smk-search-results
+          hidden
+          className="smk-nav-search__list"
+        />
+        <p
+          data-smk-search-empty
+          hidden
+          className="smk-nav-search__empty"
+        >
+          No matches.
+        </p>
+      </div>
+      {/* eslint-disable-next-line react/no-danger -- inline IIFE wires search filter; index is JSON-escaped against </script> smuggling. */}
+      <script dangerouslySetInnerHTML={{ __html: scriptSrc }} />
+    </section>
+  );
+}
+
+/**
+ * Best-effort locale-naive date render. SDK doesn't ship a date library;
+ * customer can override via CSS / their own `<SmkingCms>` wrapper if
+ * they need a specific format / timezone.
+ */
+function formatPublishedAt(iso: string): string {
+  try {
+    return new Date(iso).toLocaleDateString();
+  } catch {
+    return iso.slice(0, 10);
+  }
+}

package/src/lib/smking-elements-iife.ts

@@ -0,0 +1,46 @@
+/**
+ * IIFE source for `<smking-carousel>` + `<smking-slide>` Web Component
+ * registration. The Next.js SDK inlines this as a `<script>` tag once
+ * per page so customer sites get the carousel interactivity without
+ * adding a `<script src>` to their layout.
+ *
+ * Idempotent: the IIFE guards each `customElements.define` call with a
+ * `customElements.get(...)` check, so multiple emits per page are
+ * harmless.
+ *
+ * Keep this string in sync with
+ * `apps/web/src/features/cms/sdk/smking-elements.ts` — the SaaS-side
+ * Plate editor imports the TS module directly, so both paths register
+ * the same runtime.
+ */
+export const SMKING_ELEMENTS_IIFE = `(function(){if(typeof window==="undefined"||typeof customElements==="undefined")return;
+var C="smking-carousel",S="smking-slide";
+if(customElements.get(C))return;
+function nextFrame(cb){if(typeof requestAnimationFrame!=="undefined")return requestAnimationFrame(cb);return setTimeout(cb,16);}
+function cancelFrame(id){if(typeof cancelAnimationFrame!=="undefined")return cancelAnimationFrame(id);return clearTimeout(id);}
+function CarouselEl(){return Reflect.construct(HTMLElement,[],CarouselEl);}
+CarouselEl.prototype=Object.create(HTMLElement.prototype);
+CarouselEl.prototype.constructor=CarouselEl;
+CarouselEl.prototype.connectedCallback=function(){var self=this;
+var viewport=self.querySelector(".smk-carousel__viewport");
+if(!viewport)return;
+var dotsContainer=self.querySelector(".smk-carousel__dots");
+var prevBtn=self.querySelector(".smk-carousel__nav-prev");
+var nextBtn=self.querySelector(".smk-carousel__nav-next");
+var slides=Array.prototype.slice.call(viewport.querySelectorAll(":scope > "+S));
+if(dotsContainer){var dotEls=slides.map(function(_,i){var d=document.createElement("button");d.type="button";d.className="smk-carousel__dot";d.dataset.index=String(i);d.setAttribute("aria-label","Go to slide "+(i+1));if(i===0)d.setAttribute("aria-current","true");d.addEventListener("click",function(e){e.preventDefault();viewport.scrollTo({left:i*viewport.clientWidth,behavior:"smooth"});});return d;});dotsContainer.replaceChildren.apply(dotsContainer,dotEls);}
+function onPrev(e){e.preventDefault();viewport.scrollBy({left:-viewport.clientWidth,behavior:"smooth"});}
+function onNext(e){e.preventDefault();viewport.scrollBy({left:viewport.clientWidth,behavior:"smooth"});}
+if(prevBtn)prevBtn.addEventListener("click",onPrev);
+if(nextBtn)nextBtn.addEventListener("click",onNext);
+var raf=0;
+function onScroll(){if(raf)return;raf=nextFrame(function(){raf=0;var ai=Math.round(viewport.scrollLeft/Math.max(1,viewport.clientWidth));if(!dotsContainer)return;var dots=dotsContainer.querySelectorAll(".smk-carousel__dot");dots.forEach(function(d,i){if(i===ai)d.setAttribute("aria-current","true");else d.removeAttribute("aria-current");});});}
+viewport.addEventListener("scroll",onScroll,{passive:true});
+self._smkCleanup=function(){if(prevBtn)prevBtn.removeEventListener("click",onPrev);if(nextBtn)nextBtn.removeEventListener("click",onNext);viewport.removeEventListener("scroll",onScroll);if(raf)cancelFrame(raf);};};
+CarouselEl.prototype.disconnectedCallback=function(){if(this._smkCleanup)this._smkCleanup();};
+function SlideEl(){return Reflect.construct(HTMLElement,[],SlideEl);}
+SlideEl.prototype=Object.create(HTMLElement.prototype);
+SlideEl.prototype.constructor=SlideEl;
+customElements.define(C,CarouselEl);
+customElements.define(S,SlideEl);
+})();`;

package/src/types.ts

@@ -79,10 +79,30 @@ export interface ModuleHeader {
   viewAll?: { label: string; href: string };
 }
 export type NavLayout = "grid" | "list" | "carousel";
+
+/**
+ * Materialized snapshot entry — published pages on the smking SaaS
+ * pre-resolve their nav-* block data at publish time and bake it into
+ * `block.props.snapshot`. Customer SDK echoes this verbatim, never
+ * round-trips back to smking for nav rendering. If smking is down,
+ * customer pages still render whatever was last published.
+ */
+export interface NavSnapshotEntry {
+  slug: string;
+  title: string | null;
+  excerpt: string | null;
+  featuredImageUrl: string | null;
+  /** ISO string. */
+  publishedAt: string | null;
+  contentType: "article" | "landing" | "listing" | null;
+}
+
 export interface NavRecentPostsProps extends ModuleHeader {
   limit: number;
   layout: NavLayout;
   contentType?: "article" | "all";
+  /** Publish-time materialized — never fetched live. */
+  snapshot?: NavSnapshotEntry[];
 }
 export interface NavTaxonomyListProps extends ModuleHeader {
   /** category-by-path: slug prefix; tag: taxonomies.slug */
@@ -90,15 +110,49 @@ export interface NavTaxonomyListProps extends ModuleHeader {
   path: string;
   limit: number;
   layout: NavLayout;
+  /** Publish-time materialized — never fetched live. */
+  snapshot?: NavSnapshotEntry[];
+}
+
+/**
+ * Search index entry. Customer SDK does client-side fuzzy filter
+ * against this list; clicking a result navigates to the slug.
+ */
+export interface NavSearchIndexEntry {
+  slug: string;
+  title: string | null;
+  excerpt: string | null;
 }
+
 export interface NavSearchProps {
   placeholder: string;
   contentType?: "article" | "all";
+  /** Publish-time materialized full-site search index. */
+  index?: NavSearchIndexEntry[];
+}
+
+export interface CarouselSlideProps {
+  imageUrl: string;
+  caption: string;
+}
+
+export type CarouselAspectRatio =
+  | "16:9"
+  | "4:3"
+  | "1:1"
+  | "3:4"
+  | "9:16";
+
+export interface CarouselProps {
+  slides: CarouselSlideProps[];
+  /** Fixed aspect ratio for all slides — image fills via `object-fit: cover`. Default `16:9`. */
+  aspectRatio?: CarouselAspectRatio;
 }
 
 export type Block =
   | { component: "hero"; id: string; props: HeroProps }
   | { component: "article"; id: string; props: ArticleProps }
+  | { component: "carousel"; id: string; props: CarouselProps }
   | {
       component: "nav-recent-posts";
       id: string;