@soloworks/smking-next 0.21.1 → 0.21.2

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @soloworks/smking-next
 
+## 0.21.2 — 2026-07-02
+
+**CMS taxonomy page types caught up with the SaaS catalog (types only — no runtime change).**
+
+The CMS page model now includes the `taxonomy` content type used by protected
+category and tag index pages. This keeps the published SDK type surface aligned
+with the SaaS block contract after the taxonomy-page normalization work.
+
 ## 0.21.1 — 2026-06-12
 
 **Webhook replay protection (security review M6).**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soloworks/smking-next",
-  "version": "0.21.1",
+  "version": "0.21.2",
   "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/cms-blocks.ts

@@ -29,15 +29,27 @@
 
 export interface HeroProps {
   title: string;
+  /** Generic visible meta lines. Legacy drafts may still also carry subtitle. */
+  line1?: string;
+  line2?: string;
+  /** When true, render the backend page publish date. */
+  showPublishedAt?: boolean;
+  /** ISO or display date injected from page metadata at publish time. */
+  publishedAt?: string;
+  /** Legacy single-line fallback for SDK Mode B consumers. */
   subtitle?: string;
   image?: { url: string; alt: string };
   cta?: { label: string; href: string };
   /** Header layout — omitted = the original centred hero; "start" = the
-   * Apple-newsroom-style left-aligned header; "cover" = title-only banner
-   * over a full-bleed background image (Apple services index). Visuals ship
-   * via bodyHtml; this mirrors the node attr for SDK Mode B (per-block)
-   * consumers. */
-  align?: "center" | "start" | "cover";
+   * Apple-newsroom-style left-aligned header; "cover" = title-only banner over
+   * a full-bleed background image with a dark scrim (Apple services index);
+   * "cover-plain" = the same banner WITHOUT the scrim (image shown untouched).
+   * Visuals ship via bodyHtml; this mirrors the node attr for SDK Mode B
+   * (per-block) consumers. */
+  align?: "center" | "start" | "cover" | "cover-plain";
+  /** Crop ratio for cover heroes and the optional hero image.
+   * Omitted = auto, preserving the original image ratio. */
+  aspectRatio?: "auto" | "16:9" | "4:3";
 }
 
 export interface ArticleProps {
@@ -72,7 +84,26 @@ export interface NavSnapshotEntry {
   featuredImageUrl: string | null;
   /** ISO string. */
   publishedAt: string | null;
-  contentType: "article" | "landing" | "listing" | null;
+  /** ISO string. Present when the article is manually pinned in CMS feeds. */
+  pinnedAt?: string | null;
+  contentType: "article" | "landing" | "listing" | "taxonomy" | null;
+}
+
+export type SearchQuickLinkSource = "category-by-path" | "tag" | "url";
+
+/**
+ * Optional links shown beside the search trigger on desktop and inside the
+ * search panel on small screens. Category/tag links keep their semantic source
+ * + path so publish-time materialization can bake the customer's CMS mount
+ * prefix into `href`; URL links carry the author's literal `href`.
+ */
+export interface SearchQuickLink {
+  label: string;
+  source: SearchQuickLinkSource;
+  /** Category slug path or flat tag slug. Not used for arbitrary URLs. */
+  path?: string;
+  /** Materialized href for category/tag links, or the author-entered URL. */
+  href?: string;
 }
 
 /**
@@ -88,6 +119,11 @@ export interface SearchProps {
   placeholder?: string;
   /** Optional heading above the search input. */
   heading?: string;
+  /** Content column vs wide breakout (default wide). Mirrors the media
+   * blocks (image/embed). */
+  widthMode?: "content" | "wide";
+  /** Optional quick links adjacent to search. */
+  links?: SearchQuickLink[];
   /** Publish-time materialized snapshot — every published page on the site. */
   snapshot?: NavSnapshotEntry[];
 }
@@ -95,23 +131,74 @@ export interface SearchProps {
 export interface RecentPostsProps extends ModuleHeader {
   /** Author-set number of latest posts to show (1..50). */
   limit: number;
+  /** Content column vs wide breakout (default content). Mirrors the media
+   * blocks. */
+  widthMode?: "content" | "wide";
   /** Publish-time materialized snapshot — whole-site newest-first. */
   snapshot?: NavSnapshotEntry[];
 }
 
+/** One author-picked source for nav-related-posts. Same shape as
+ * `CategoryIndexItem` (a category path OR a tag), reused so the source picker
+ * UI stays identical across blocks. */
+export interface RelatedPostsSource {
+  /** Slug prefix (category-by-path) or taxonomy slug (tag), per `source`. */
+  path: string;
+  /** Display name (only used by the editor chip; resolver ignores it). */
+  label: string;
+  /** Omitted = `category-by-path` (back-compat, mirrors CategoryIndexItem). */
+  source?: "category-by-path" | "tag";
+}
+
 export interface RelatedPostsProps extends ModuleHeader {
+  /** Authoring mode before materialization. Published blocks carry resolved
+   * `heading`; SDK consumers can ignore this field. */
+  headingMode?: "global" | "custom";
   /** Author-set number of related posts to show (1..50). */
   limit: number;
-  /** Publish-time materialized snapshot — same-tag, ranked by overlap. */
+  /** Content column vs wide breakout (default content). Mirrors the media
+   * blocks. */
+  widthMode?: "content" | "wide";
+  /** Author-picked sources. Empty/omitted → auto-fill from the CURRENT page's
+   * category, derived from its slug at publish time. When set, related posts
+   * are the latest across ALL picked sources (OR), newest-first, excluding the
+   * current page. */
+  sources?: RelatedPostsSource[];
+  /** Publish-time materialized snapshot. */
   snapshot?: NavSnapshotEntry[];
 }
 
-/** One author-selected category in a nav-category-index block. */
+/** One tag attached to the current article, materialized at publish time. */
+export interface ArticleTagSnapshot {
+  slug: string;
+  name: string;
+  /** Virtual tag archive href, e.g. `/blog/tag/tofu-life`. */
+  href: string;
+}
+
+/**
+ * `article-tags` block — renders the current article's CMS tags as chips.
+ * The tags are page metadata, not authored inside the block, so `snapshot`
+ * is filled at publish time from `content_taxonomies`.
+ */
+export interface ArticleTagsProps {
+  /** Optional section heading. Omitted / empty means no heading. */
+  heading?: string;
+  /** Publish-time materialized current-article tags. */
+  snapshot?: ArticleTagSnapshot[];
+}
+
+/** One author-selected category OR tag in a nav-category-index block. */
 export interface CategoryIndexItem {
-  /** Slug prefix identifying the category (e.g. `blog/seo`). */
+  /** Slug prefix (category-by-path) or taxonomy slug (tag), per `source`.
+   * e.g. category `blog/seo`, tag `announcements`. */
   path: string;
-  /** Display name on the card (slug leaf by default; author-editable). */
+  /** Display name on the card (slug leaf / tag name by default; author-editable). */
   label: string;
+  /** Source discriminator (mirrors nav-taxonomy-list). Omitted =
+   * `category-by-path` — back-compat: pre-tag nodes carry no source. A `tag`
+   * card shows that tag's latest post + links to its archive. */
+  source?: "category-by-path" | "tag";
 }
 
 /**
@@ -126,15 +213,30 @@ export interface CategoryCardSnapshot {
 }
 
 export interface CategoryIndexProps extends ModuleHeader {
+  /** `auto` = listing categories directly under `autoBasePath` at publish
+   * time; `manual` = exactly the picked items below. Omitted = back-compat:
+   * items present means manual, otherwise auto. */
+  mode?: "auto" | "manual";
+  /** Auto mode source. Omitted = category hierarchy, for back-compat. */
+  autoSource?: "category-by-path" | "tag";
+  /** Auto mode source hierarchy. Empty string means root-level listing
+   * categories; any other value is a listing slug whose direct child listing
+   * pages should be shown. Omitted falls back to root for new materialization. */
+  autoBasePath?: string;
   items: CategoryIndexItem[];
   /** Card layout — omitted/"cards" = category cards (archive links);
    * "featured" = Apple-newsroom services-index tiles where each card IS the
    * category's latest article. Visuals ship via bodyHtml; this mirrors the
    * node attr for SDK Mode B (per-block) consumers. */
   layout?: "cards" | "featured";
+  /** Content column vs wide breakout. Omitted = layout-derived default
+   * (cards → content, featured → wide); set explicitly to override. */
+  widthMode?: "content" | "wide";
   snapshot?: CategoryCardSnapshot[];
 }
 
+export type MediaAspectRatio = "auto" | "16:9" | "4:3" | "square";
+
 /**
  * `image` block — a single figure (image + optional caption). `widthMode`
  * controls the breakout (content = text column, wide = up to 1024px centred
@@ -146,6 +248,10 @@ export interface ImageProps {
   alt?: string;
   caption?: string;
   widthMode?: "content" | "wide";
+  /** Plain image vs soft neutral tonal surface. */
+  styleVariant?: "plain" | "tonal";
+  /** Omitted / auto preserves the original image ratio. Fixed values crop. */
+  aspectRatio?: MediaAspectRatio;
 }
 
 /** One slide in a `slideshow` block. */
@@ -168,17 +274,51 @@ export interface SlideshowProps {
   aspectRatio?: "16:9" | "4:3";
 }
 
+/** One image in a `collage` block. Width/height are optional natural
+ * dimensions saved at authoring time so the auto layout can keep row
+ * proportions stable without loading images first. */
+export interface CollageImageProps {
+  url: string;
+  alt?: string;
+  width?: number;
+  height?: number;
+}
+
+/**
+ * `collage` block — a 1–6 image composition. `auto` uses natural image
+ * ratios and the wide breakout; `row-grid` keeps each row at one height while
+ * allowing different rows to have different proportions. Content width forces
+ * `row-grid` at render time.
+ */
+export interface CollageProps {
+  images?: CollageImageProps[];
+  widthMode?: "content" | "wide";
+  mode?: "auto" | "row-grid";
+}
+
+export type SocialSharePlatform =
+  | "threads"
+  | "instagram"
+  | "facebook"
+  | "line"
+  | "copy";
+
 /**
- * `social-share` block — X / Facebook / LinkedIn share links + copy-link. The
- * platforms are fixed; `shareUrl` is the optional no-JS fallback target (the
- * `<smking-share>` web component overrides every link from window.location at
- * runtime, so the live share always points at the real current page).
+ * `social-share` block — Threads / Instagram / Facebook / LINE share links +
+ * copy-link.
+ * Platform visibility is site-wide; `shareUrl` is the optional no-JS fallback
+ * target (the `<smking-share>` web component overrides every link from
+ * window.location at runtime, so the live share always points at the real
+ * current page).
  */
 export interface SocialShareProps {
   shareUrl?: string;
-  /** Heading above the row. Omitted = "Share article" default at render
-   * time; empty string = bare icon row (Apple-newsroom header style). */
+  /** Global mode reads the site-wide share title. Custom mode reads `label`.
+   * Omitted = global; empty resolved title = bare icon row. */
+  headingMode?: "global" | "custom";
   label?: string;
+  /** Site-wide platform visibility snapshot baked into published output. */
+  platforms?: SocialSharePlatform[];
 }
 
 export interface NavTaxonomyListProps extends ModuleHeader {
@@ -196,10 +336,115 @@ export interface NavTaxonomyListProps extends ModuleHeader {
    * safety cap. Omitted (not false) when off — back-compat shape. */
   showAll?: boolean;
   layout: NavLayout;
+  /** Content column vs wide breakout (default content). Mirrors the media
+   * blocks. */
+  widthMode?: "content" | "wide";
   /** Publish-time materialized snapshot. */
   snapshot?: NavSnapshotEntry[];
 }
 
+/** One button in a `button-group` block. */
+export interface ButtonItemProps {
+  label: string;
+  href: string;
+  /** Apple-style looks: `filled` = primary capsule, `tinted` = soft primary
+   * wash, `outline` = bordered. Omitted = filled. */
+  variant?: "filled" | "tinted" | "outline";
+}
+
+/**
+ * `button-group` block — a row of Apple-style capsule CTAs. Buttons wrap on
+ * narrow screens; `align` positions the row. Empty `buttons` is valid (an
+ * unconfigured block renders nothing on the customer side).
+ */
+export interface ButtonGroupProps {
+  buttons?: ButtonItemProps[];
+  align?: "start" | "center";
+}
+
+/**
+ * `embed` block — a privacy-friendly YouTube embed (youtube-nocookie
+ * iframe). `url` accepts any YouTube form (watch / youtu.be / shorts /
+ * embed); the video id is resolved at render time. No url / unrecognised
+ * url = renders nothing on the customer side. `widthMode` matches the other
+ * media blocks (content column vs wide breakout).
+ */
+export interface EmbedProps {
+  url?: string;
+  caption?: string;
+  widthMode?: "content" | "wide";
+}
+
+/**
+ * `media-text` block — Apple-style feature row: image on one side, RICH
+ * EDITABLE text on the other. Unlike the attr-panel blocks, the text is
+ * real Plate content (the node's children — headings/paragraphs edited
+ * inline); `html` carries its serialized form for Mode B consumers, while
+ * Mode A ships the full markup inside bodyHtml as usual.
+ */
+export interface MediaTextProps {
+  imageUrl?: string;
+  imageAlt?: string;
+  /** Which side the IMAGE sits on (md+ screens; stacks on mobile). */
+  side?: "left" | "right";
+  /** Content column vs wide breakout (default wide). Mirrors the media
+   * blocks. */
+  widthMode?: "content" | "wide";
+  /** Plain row vs soft neutral tonal surface. */
+  styleVariant?: "plain" | "tonal";
+  /** Omitted / auto preserves the original image ratio. Fixed values crop. */
+  aspectRatio?: MediaAspectRatio;
+  /** Serialized text-column HTML (class-stripped, same treatment as
+   * `article`). */
+  html: string;
+}
+
+/**
+ * One slot in a `latest-news` block — sourced independently from EITHER a
+ * specific article (by slug) or a category (shows that category's latest
+ * post). The discriminator mirrors `nav-taxonomy-list`'s source pattern.
+ */
+export type LatestNewsSlot =
+  | { kind: "article"; slug: string }
+  | {
+      kind: "category";
+      path: string;
+      label: string;
+      /** Source discriminator (mirrors nav-taxonomy-list). Omitted =
+       * `category-by-path` — back-compat. A `tag` slot shows the latest post
+       * carrying that tag. */
+      source?: "category-by-path" | "tag";
+    };
+
+/**
+ * One materialized `latest-news` card: the resolved article entry (the
+ * article itself for an `article` slot, or the category's latest post for a
+ * `category` slot) plus an optional eyebrow (the category label for category
+ * slots; null for article slots). A null `entry` = the slot's source
+ * resolved to nothing and is skipped at render.
+ */
+export interface LatestNewsCardSnapshot {
+  eyebrow: string | null;
+  entry: NavSnapshotEntry | null;
+}
+
+/**
+ * `latest-news` block — the Apple-newsroom "Latest News" magazine grid.
+ * 3–6 author-curated slots; the first is the large feature card, the rest
+ * scale down to medium / small tiles (6 = 1 feature + 2 medium + 3 small,
+ * down to 3 = 1 feature + 2 medium). Materialized at publish like the nav-*
+ * feeds; reuses `NavSnapshotEntry` for each resolved card.
+ */
+export interface LatestNewsProps extends ModuleHeader {
+  /** Author-curated slots, 3–6, in display order (first = feature card). */
+  slots: LatestNewsSlot[];
+  /** Content column vs wide breakout (default wide). Mirrors the media
+   * blocks. */
+  widthMode?: "content" | "wide";
+  /** Publish-time materialized snapshot — one card per slot, same order. */
+  snapshot?: LatestNewsCardSnapshot[];
+}
+
 export type Block =
   | { component: "hero"; id: string; props: HeroProps }
   | { component: "article"; id: string; props: ArticleProps }
@@ -211,9 +456,15 @@ export type Block =
   | { component: "search"; id: string; props: SearchProps }
   | { component: "nav-recent-posts"; id: string; props: RecentPostsProps }
   | { component: "nav-related-posts"; id: string; props: RelatedPostsProps }
+  | { component: "article-tags"; id: string; props: ArticleTagsProps }
   | { component: "nav-category-index"; id: string; props: CategoryIndexProps }
   | { component: "image"; id: string; props: ImageProps }
   | { component: "slideshow"; id: string; props: SlideshowProps }
-  | { component: "social-share"; id: string; props: SocialShareProps };
+  | { component: "collage"; id: string; props: CollageProps }
+  | { component: "social-share"; id: string; props: SocialShareProps }
+  | { component: "button-group"; id: string; props: ButtonGroupProps }
+  | { component: "embed"; id: string; props: EmbedProps }
+  | { component: "media-text"; id: string; props: MediaTextProps }
+  | { component: "latest-news"; id: string; props: LatestNewsProps };
 
 export type BlockComponent = Block["component"];

package/src/index.ts

@@ -27,9 +27,12 @@ export type {
   NavTaxonomyListProps,
   RecentPostsProps,
   RelatedPostsProps,
+  SearchQuickLink,
+  SearchQuickLinkSource,
   SearchProps,
   SeoMeta,
   SlideshowProps,
   SlideshowSlideProps,
+  SocialSharePlatform,
   SocialShareProps,
 } from "./types";

package/src/types.ts

@@ -56,7 +56,7 @@ export interface AeoResponse {
 
 export type CmsStatus = "ready" | "preview" | "pending" | "not_found";
 
-export type CmsContentType = "article" | "landing" | "listing";
+export type CmsContentType = "article" | "landing" | "listing" | "taxonomy";
 
 // `CmsThemeMode` removed in v0.15.0 — Mode B (`tailwind-prose`) dropped
 // in favour of the canonical Plate-serialized HTML render (Mode A only).
@@ -87,9 +87,12 @@ export type {
   NavTaxonomyListProps,
   RecentPostsProps,
   RelatedPostsProps,
+  SearchQuickLink,
+  SearchQuickLinkSource,
   SearchProps,
   SlideshowProps,
   SlideshowSlideProps,
+  SocialSharePlatform,
   SocialShareProps,
 } from "./cms-blocks";