@flamingo-stack/openframe-frontend-core 0.0.735 → 0.0.737

package/src/components/faq/faq-section.tsx

@@ -27,6 +27,15 @@ export interface FaqSectionProps {
   /** Both required together for entity-attached FAQs; partial → bare /api/faqs. */
   entityType?: string;
   entityId?: number | string;
+  /**
+   * What the page this FAQ sits on is about: ANY string the host's FAQ
+   * endpoint knows. ONE topic for the whole block: the questions are the FAQs
+   * written for it (`/api/faqs?topic=`; `initialFaqs` are then the host's read
+   * of the same topic) and the "ask the assistant" card offers the questions
+   * written for it. Whoever renders the FAQ states it; the lib names none.
+   * Ignored for the questions when the FAQ is attached to an entity.
+   */
+  topic?: string;
   /**
    * Heading node above the grouped list. `undefined` → default
    * `<h2>`"Frequently Asked Questions". `null` → no heading (the host page
@@ -43,6 +52,14 @@ export interface FaqSectionProps {
   /** Overrides for the JSON-LD's name/description/url. */
   jsonLd?: FaqSchemaOptions;
   className?: string;
+  /** The `id` of the rendered section: what an in-page link to the FAQ points at (`PAGE_FAQ_SECTION_ID` for a page's own block). */
+  id?: string;
+  /**
+   * Print the topic's bare name in small muted text under the heading
+   * (`pricing`), so whoever edits the FAQs can see which topic a page asks
+   * for. Default off. The section always carries it as `data-faq-topic` too.
+   */
+  showTopic?: boolean;
   /** Maps to /api/faqs `?count=` (the 5-tier fill target). Absent → param
    *  not sent (server default applies). */
   minResults?: number;
@@ -60,10 +77,10 @@ export interface FaqSectionProps {
    * The "ask the assistant" card beside the questions. Shown wherever the
    * host's assistant runtime says a chat is there to open
    * (`AssistantRuntimeContext`: its name, glyph, questions endpoint and
-   * opener) AND the FAQ has a topic: `ask.topic` (any string the host's
-   * questions endpoint knows), else the `entityType` the FAQ is attached to.
-   * No runtime or no topic: the FAQ is the single column it always was; the
-   * lib names no topic of its own. `false` switches the card off; the object
+   * opener) AND the FAQ has a topic: the block's `topic`, else the
+   * `entityType` the FAQ is attached to (`ask.topic` states another one for
+   * the card alone). No runtime or no topic: the FAQ is the single column it
+   * always was; the lib names no topic of its own. `false` switches the card off; the object
    * also states the questions to leave out, the wording and the chat it opens
    * (`onOpen`). An `aside` takes the card's place.
    */
@@ -72,11 +89,47 @@ export interface FaqSectionProps {
 
 const DEFAULT_HEADING_TEXT = 'Frequently Asked Questions';
 
+/** The id of a page's own FAQ block: what a page's "FAQ" link or section nav points at. */
+export const PAGE_FAQ_SECTION_ID = 'faq';
+
+/** A page's own FAQ block inside a page that already provides the container: vertical rhythm only. */
+const PAGE_FAQ_IN_PAGE_CLASS = 'space-y-10 pt-12 md:pt-20';
+
+/**
+ * What a shared page of the lib takes as its `faq` prop: the topic the page is
+ * about (REQUIRED, stated by the host, never read from the page's address) and
+ * where the host serves the FAQs. The page renders `FaqSection` with it, inside
+ * its own container, after its content (`pageFaqProps`).
+ */
+export type PageFaqSlot = Pick<
+  FaqSectionProps,
+  'apiBaseUrl' | 'initialFaqs' | 'heading' | 'ask' | 'emitJsonLd' | 'jsonLd' | 'showTopic'
+> & { topic: string };
+
+/** The `FaqSection` props of a shared page's own FAQ block: the host's slot, as the page's `#faq` section. */
+export function pageFaqProps(faq: PageFaqSlot): FaqSectionProps {
+  return { ...faq, id: PAGE_FAQ_SECTION_ID, className: PAGE_FAQ_IN_PAGE_CLASS };
+}
+
 /** URL composition shared with RelatedContentSection (`buildSuggestionUrl`)
  *  — byte-identical to the historical `buildFaqsUrl` output when
  *  `minResults`/`apiBaseUrl` are absent. */
-function buildFaqsUrl(entityType?: string, entityId?: number | string, minResults?: number, apiBaseUrl = ''): string {
-  return buildSuggestionUrl('/api/faqs', { apiBaseUrl, entityType, entityId, count: minResults });
+function buildFaqsUrl(
+  entityType?: string,
+  entityId?: number | string,
+  minResults?: number,
+  apiBaseUrl = '',
+  topic?: string,
+): string {
+  // An entity's FAQs are the entity's: a topic narrows only the platform's own list.
+  const entityScoped = !!entityType && entityId !== undefined && entityId !== null && entityId !== '';
+  return buildSuggestionUrl('/api/faqs', {
+    apiBaseUrl,
+    entityType,
+    entityId,
+    count: minResults,
+    extraParams: entityScoped ? undefined : { topic },
+  });
 }
 
 interface FaqGroup {
@@ -390,6 +443,8 @@ interface FaqsResponse {
  *   page owns the <h1>) + `emitJsonLd` with `jsonLd` overrides for SEO.
  * - Per-entity embed: pass `entityType` + `entityId` (no `initialFaqs`); the
  *   hook self-fetches `GET /api/faqs`, and `heading` is this block's own <h2>.
+ * - A page's own FAQ: pass `topic` (what the page is about); the hook
+ *   self-fetches `GET /api/faqs?topic=`, and the ask card takes the same topic.
  *
  * CONTRACT: the consuming app MUST implement `GET /api/faqs`. On a fetch error
  * (or zero FAQs) the component renders nothing so the host page isn't
@@ -400,10 +455,13 @@ export function FaqSection({
   initialFaqs,
   entityType,
   entityId,
+  topic,
   heading,
   emitJsonLd = false,
   jsonLd,
   className,
+  id,
+  showTopic = false,
   minResults,
   apiBaseUrl = '',
   aside: asideProp,
@@ -412,30 +470,41 @@ export function FaqSection({
   const assistant = useAssistantRuntime();
   // The host's own block wins; else the card, where a chat is there to open and the FAQ has a topic
   // (an empty topic is no topic, as the questions request reads it).
-  const askTopic = ask === false ? undefined : ask?.topic || entityType;
+  const askTopic = ask === false ? undefined : ask?.topic || topic || entityType;
   const aside =
     asideProp ??
     (ask !== false && askTopic && faqAskCardShown(assistant) ? <FaqAskCard {...ask} topic={askTopic} /> : undefined);
-  const url = buildFaqsUrl(entityType, entityId, minResults, apiBaseUrl);
+  const url = buildFaqsUrl(entityType, entityId, minResults, apiBaseUrl, topic);
   // Memoized — useSelfFetch re-syncs on [initialData]; a fresh per-render
   // wrapper object would setState-loop under re-rendering parents.
   const initialData = useMemo<FaqsResponse | undefined>(
     () => (initialFaqs ? { faqs: initialFaqs } : undefined),
     [initialFaqs],
   );
-  const { data, isLoading, error } = useSelfFetch<FaqsResponse>(url, { initialData });
+  const { data, dataUrl, isLoading, error } = useSelfFetch<FaqsResponse>(url, { initialData });
 
-  // Memoised because the `??` fallback minted a NEW array on every
-  // render, which made the memo below re-run every time — i.e. do nothing.
-  const faqs = useMemo(() => data?.faqs ?? [], [data?.faqs]);
+  // Only the answer for THIS url: while another topic's questions load, the
+  // previous topic's are not this page's. Memoised because the `??` fallback
+  // minted a NEW array on every render, which made the memo below re-run
+  // every time — i.e. do nothing.
+  const held = dataUrl === url ? data?.faqs : undefined;
+  const faqs = useMemo(() => held ?? [], [held]);
   // Grouped before the early returns so the hook order stays stable.
   const groups = useMemo(() => (faqs.length > 0 ? groupFaqsBySection(faqs) : []), [faqs]);
 
   // `undefined` → default <h2> title; `null` → the host page owns the <h1>, so
   // no title renders here. `heading === null` also makes the category headings
   // <h2> (directly under the page <h1>); otherwise they nest as <h3>.
+  const titleNode = heading === undefined ? <h2 className={SECTION_HEADING_CLASS}>{DEFAULT_HEADING_TEXT}</h2> : heading;
   const headingNode =
-    heading === undefined ? <h2 className={SECTION_HEADING_CLASS}>{DEFAULT_HEADING_TEXT}</h2> : heading;
+    showTopic && topic ? (
+      <div className="space-y-1">
+        {titleNode}
+        <p className="text-ods-text-muted text-h6">{topic}</p>
+      </div>
+    ) : (
+      titleNode
+    );
 
   // Degrade silently — never show an error banner or an empty section shell
   // where FAQs would be (host pages and the standalone surface both rely on it).
@@ -453,7 +522,7 @@ export function FaqSection({
 
   return (
     <>
-      <section className={className ?? 'space-y-10'}>
+      <section id={id} data-faq-topic={topic} className={className ?? 'space-y-10'}>
         {!aside && headingNode}
         <GroupedFaqList
           groups={groups}

package/src/components/faq/index.ts

@@ -9,6 +9,6 @@
 //
 // (Server-safe subpath is wired in tsup.config.ts under the server/universal
 // block and exposed via "./components/faq/json-ld" in package.json#exports.)
-export { FaqSection, type FaqSectionProps } from './faq-section';
+export { FaqSection, PAGE_FAQ_SECTION_ID, pageFaqProps, type FaqSectionProps, type PageFaqSlot } from './faq-section';
 export { FaqDocumentPage, type FaqDocumentPageProps } from './faq-document-page';
 export { FaqAskCard, type FaqAskOptions } from './faq-ask-card';

package/src/components/help-center-pages/delivery-page.tsx

@@ -8,6 +8,7 @@
  */
 
 import type { ReactNode } from 'react';
+import type { PageFaqSlot } from '../faq/faq-section';
 import { DeliveryLists } from '../shared/delivery';
 import { DevSectionPage } from '../shared/dev-section';
 
@@ -22,6 +23,12 @@ export interface DeliveryPageProps {
   subtitle?: string;
   /** Optional slot rendered below the lists, inside the page chrome. */
   belowContent?: ReactNode;
+  /**
+   * The page's own FAQ block: the topic the page is about (stated by the host,
+   * never read from its address) and where the host serves the FAQs. Rendered
+   * after the page's content, inside its container. Absent: no FAQ block.
+   */
+  faq?: PageFaqSlot;
   /** Render the standalone `<PageShell>`. Default true. Pass false when the host
    *  layout already provides the page container (forwarded to `DevSectionPage`). */
   shell?: boolean;
@@ -34,10 +41,18 @@ export function DeliveryPage({
   title,
   subtitle,
   belowContent,
+  faq,
   shell,
 }: DeliveryPageProps) {
   return (
-    <DevSectionPage sectionKey="delivery" backButton={backButton} title={title} subtitle={subtitle} shell={shell}>
+    <DevSectionPage
+      sectionKey="delivery"
+      backButton={backButton}
+      title={title}
+      subtitle={subtitle}
+      faq={faq}
+      shell={shell}
+    >
       <DeliveryLists completedApiEndpoint={completedEndpoint} inProgressApiEndpoint={inProgressEndpoint} />
       {belowContent}
     </DevSectionPage>

package/src/components/help-center-pages/download-apps-page.tsx

@@ -52,6 +52,7 @@ import {
 import { cn } from '../../utils/cn';
 import { formatUrlForDisplay } from '../../utils/format';
 import { DESKTOP_OSES, type DesktopOs } from '../../utils/visitor-os';
+import { FaqSection, pageFaqProps, type PageFaqSlot } from '../faq/faq-section';
 import { CommandBox } from '../features/command-box';
 import { AppleLogoIcon } from '../icons-v2-generated/brand-logos/apple-logo-icon';
 import { WindowsLogoGreyIcon } from '../icons-v2-generated/brand-logos/windows-logo-grey-icon';
@@ -86,6 +87,12 @@ export interface DownloadAppsPageProps {
   onDownloadAction?: (event: DownloadActionEvent) => void;
   /** The closing card, under the mobile app: using OpenFrame without installing anything. Default: none. */
   web?: DownloadAppsWebOption;
+  /**
+   * The page's own FAQ block: the topic the page is about (stated by the host,
+   * never read from its address) and where the host serves the FAQs. Rendered
+   * after the page's content, inside its container. Absent: no FAQ block.
+   */
+  faq?: PageFaqSlot;
 }
 
 /** The "no install" card: the host's words and its own button (the page holds no signup link). */
@@ -281,6 +288,7 @@ export function DownloadAppsPage({
   openStoresInNewTab = true,
   onDownloadAction,
   web,
+  faq,
 }: DownloadAppsPageProps) {
   const { data, isLoading, error, reload } = useDownloads({ endpoint, initialData });
   // The page adapts to the server's answer: a section exists only for what it names.
@@ -362,6 +370,7 @@ export function DownloadAppsPage({
         {body}
         {web && <WebCard web={web} />}
       </div>
+      {faq && <FaqSection {...pageFaqProps(faq)} />}
     </DownloadAppsChrome>
   );
 }

package/src/components/help-center-pages/onboarding-guides-catalog-page.tsx

@@ -10,6 +10,7 @@
 
 import type { ReactNode } from 'react';
 import type { OnboardingGuide } from '../chat/types/entities/onboarding-guide';
+import type { PageFaqSlot } from '../faq/faq-section';
 import { OnboardingGuidesCatalogView } from '../onboarding-guides';
 import { DevSectionPage } from '../shared/dev-section';
 
@@ -32,6 +33,12 @@ export interface OnboardingGuidesCatalogPageProps {
   subtitle?: string;
   /** Optional slot rendered below the catalog, inside the page chrome. */
   belowContent?: ReactNode;
+  /**
+   * The page's own FAQ block: the topic the page is about (stated by the host,
+   * never read from its address) and where the host serves the FAQs. Rendered
+   * after the page's content, inside its container. Absent: no FAQ block.
+   */
+  faq?: PageFaqSlot;
   /** Render the standalone `<PageShell>`. Default true. Pass false when the host
    *  layout already provides the page container (forwarded to `DevSectionPage`). */
   shell?: boolean;
@@ -48,10 +55,18 @@ export function OnboardingGuidesCatalogPage({
   title,
   subtitle,
   belowContent,
+  faq,
   shell,
 }: OnboardingGuidesCatalogPageProps) {
   return (
-    <DevSectionPage sectionKey="onboarding" backButton={backButton} title={title} subtitle={subtitle} shell={shell}>
+    <DevSectionPage
+      sectionKey="onboarding"
+      backButton={backButton}
+      title={title}
+      subtitle={subtitle}
+      faq={faq}
+      shell={shell}
+    >
       <OnboardingGuidesCatalogView
         guidesEndpoint={guidesEndpoint}
         sectionsEndpoint={sectionsEndpoint}

package/src/components/help-center-pages/product-releases-list-page.tsx

@@ -10,6 +10,7 @@
 
 import type { ReactNode } from 'react';
 import type { ProductRelease, ProductReleaseListResponse } from '../../types/product-release';
+import type { PageFaqSlot } from '../faq/faq-section';
 import { DevSectionPage } from '../shared/dev-section';
 import { ProductReleasesView, type ProductReleaseCardExtras } from '../shared/product-release';
 
@@ -28,6 +29,12 @@ export interface ProductReleasesListPageProps {
   subtitle?: string;
   /** Optional slot rendered below the list, inside the page chrome. */
   belowContent?: ReactNode;
+  /**
+   * The page's own FAQ block: the topic the page is about (stated by the host,
+   * never read from its address) and where the host serves the FAQs. Rendered
+   * after the page's content, inside its container. Absent: no FAQ block.
+   */
+  faq?: PageFaqSlot;
   /** Render the standalone `<PageShell>`. Default true. Pass false when the host
    *  layout already provides the page container (forwarded to `DevSectionPage`). */
   shell?: boolean;
@@ -42,10 +49,18 @@ export function ProductReleasesListPage({
   title,
   subtitle,
   belowContent,
+  faq,
   shell,
 }: ProductReleasesListPageProps) {
   return (
-    <DevSectionPage sectionKey="releases" backButton={backButton} title={title} subtitle={subtitle} shell={shell}>
+    <DevSectionPage
+      sectionKey="releases"
+      backButton={backButton}
+      title={title}
+      subtitle={subtitle}
+      faq={faq}
+      shell={shell}
+    >
       <ProductReleasesView
         endpoint={releasesEndpoint}
         basePath={basePath}

package/src/components/help-center-pages/roadmap-page.tsx

@@ -10,6 +10,7 @@
 
 import type { ReactNode } from 'react';
 import type { RoadmapItem } from '../chat/types/entities/roadmap-item';
+import type { PageFaqSlot } from '../faq/faq-section';
 import { DevSectionPage } from '../shared/dev-section';
 import { RoadmapView } from '../shared/roadmap';
 import type { UseRoadmapVotingOptions } from '../shared/roadmap';
@@ -35,6 +36,12 @@ export interface RoadmapPageProps {
   /** Optional slot rendered below the list, inside the page chrome — e.g. the
    *  hub's related-content rail. */
   belowContent?: ReactNode;
+  /**
+   * The page's own FAQ block: the topic the page is about (stated by the host,
+   * never read from its address) and where the host serves the FAQs. Rendered
+   * after the page's content, inside its container. Absent: no FAQ block.
+   */
+  faq?: PageFaqSlot;
   /** Render the standalone `<PageShell>`. Default true. Pass false when the host
    *  layout already provides the page container (forwarded to `DevSectionPage`). */
   shell?: boolean;
@@ -51,10 +58,18 @@ export function RoadmapPage({
   title,
   subtitle,
   belowContent,
+  faq,
   shell,
 }: RoadmapPageProps) {
   return (
-    <DevSectionPage sectionKey="roadmap" backButton={backButton} title={title} subtitle={subtitle} shell={shell}>
+    <DevSectionPage
+      sectionKey="roadmap"
+      backButton={backButton}
+      title={title}
+      subtitle={subtitle}
+      faq={faq}
+      shell={shell}
+    >
       <RoadmapView
         endpoint={roadmapEndpoint}
         initialItems={initialItems}

package/src/components/pagination.tsx

@@ -1,8 +1,10 @@
 'use client';
 
 import { ChevronLeft, ChevronRight, MoreHorizontal } from 'lucide-react';
-import { type ButtonHTMLAttributes, type HTMLAttributes, forwardRef } from 'react';
+import { type ButtonHTMLAttributes, type HTMLAttributes, type MouseEvent, type ReactNode, forwardRef } from 'react';
+import Link from '../embed-shims/next-link';
 import { cn } from '../utils/cn';
+import { isModifierClick } from './chat/utils/chat-nav-resolution';
 import { Button } from './ui/button';
 
 interface PaginationProps {
@@ -10,9 +12,98 @@ interface PaginationProps {
   totalPages: number;
   onPageChange: (page: number) => void;
   className?: string;
+  /**
+   * The address of a page of this list. With it every enabled control is a real
+   * link (`<a href>`), so a crawler that runs no script can reach every page of
+   * the list, and a person can open a page in a new tab. A plain click still
+   * changes the page in place through `onPageChange`. Without it the controls
+   * are buttons.
+   */
+  getPageHref?: (page: number) => string;
 }
 
-const Pagination = ({ currentPage, totalPages, onPageChange, className }: PaginationProps) => {
+interface PaginationControlProps {
+  /** The page this control goes to. */
+  page: number;
+  /** The control's accessible name ("Page 3", "Go to next page"). */
+  label: string;
+  variant: 'accent' | 'outline';
+  className: string;
+  /** The control marks the page being shown. */
+  current?: boolean;
+  /** There is no such page (previous on the first page, next on the last). */
+  disabled?: boolean;
+  /** Which neighbour the control leads to, stated to crawlers and assistive technology as `rel`. */
+  rel?: 'prev' | 'next';
+  onPageChange: (page: number) => void;
+  getPageHref?: (page: number) => string;
+  children: ReactNode;
+}
+
+/**
+ * One control of the pager. With a page address it is a link: the href is the
+ * page's real URL, so it works with no script, in a new tab and for a crawler,
+ * and a plain click is taken over to change the page in place (the progressive
+ * enhancement every in-page link in this library uses). With no address, or
+ * when there is no such page, it is a button: a link must always lead somewhere.
+ */
+function PaginationControl({
+  page,
+  label,
+  variant,
+  className,
+  current,
+  disabled,
+  rel,
+  onPageChange,
+  getPageHref,
+  children,
+}: PaginationControlProps) {
+  const ariaCurrent = current ? ('page' as const) : undefined;
+
+  if (!getPageHref || disabled) {
+    return (
+      <Button
+        variant={variant}
+        size="icon"
+        className={className}
+        disabled={disabled}
+        aria-label={label}
+        aria-current={ariaCurrent}
+        onClick={() => onPageChange(page)}
+      >
+        {children}
+      </Button>
+    );
+  }
+
+  const handleClick = (event: MouseEvent<HTMLAnchorElement>) => {
+    // A new tab or window is the browser's to open, at the link's own address.
+    if (isModifierClick(event)) return;
+    event.preventDefault();
+    onPageChange(page);
+  };
+
+  return (
+    <Button variant={variant} size="icon" className={className} asChild>
+      <Link
+        href={getPageHref(page)}
+        prefetch={false}
+        rel={rel}
+        aria-label={label}
+        aria-current={ariaCurrent}
+        onClick={handleClick}
+      >
+        {children}
+      </Link>
+    </Button>
+  );
+}
+
+const NEIGHBOUR_CLASS = '!h-10 !w-10 content-md:!h-10 content-md:!w-10';
+const PAGE_CLASS = '!h-9 !w-9 content-md:!h-9 content-md:!w-9';
+
+const Pagination = ({ currentPage, totalPages, onPageChange, className, getPageHref }: PaginationProps) => {
   // Generate page numbers to display
   const getPageNumbers = () => {
     const pages = [];
@@ -68,16 +159,18 @@ const Pagination = ({ currentPage, totalPages, onPageChange, className }: Pagina
     <nav role="navigation" aria-label="pagination" className={cn('mx-auto flex w-full justify-center', className)}>
       <ul className="flex flex-row items-center gap-1">
         <li>
-          <Button
+          <PaginationControl
+            page={currentPage - 1}
+            label="Go to previous page"
             variant="outline"
-            size="icon"
-            onClick={() => onPageChange(currentPage - 1)}
+            className={NEIGHBOUR_CLASS}
             disabled={currentPage === 1}
-            aria-label="Go to previous page"
-            className="!h-10 !w-10 content-md:!h-10 content-md:!w-10"
+            rel="prev"
+            onPageChange={onPageChange}
+            getPageHref={getPageHref}
           >
             <ChevronLeft className="h-4 w-4" />
-          </Button>
+          </PaginationControl>
         </li>
 
         {pageNumbers.map((page, index) => {
@@ -95,32 +188,35 @@ const Pagination = ({ currentPage, totalPages, onPageChange, className }: Pagina
 
           return (
             <li key={page}>
-              <Button
+              <PaginationControl
+                page={page}
+                label={`Page ${page}`}
                 variant={currentPage === page ? 'accent' : 'outline'}
-                size="icon"
-                onClick={() => onPageChange(page)}
-                className="!h-9 !w-9 content-md:!h-9 content-md:!w-9"
-                aria-label={`Page ${page}`}
-                aria-current={currentPage === page ? 'page' : undefined}
+                className={PAGE_CLASS}
+                current={currentPage === page}
+                onPageChange={onPageChange}
+                getPageHref={getPageHref}
               >
                 {page}
-              </Button>
+              </PaginationControl>
             </li>
           );
         })}
 
         <li>
-          <Button
+          <PaginationControl
+            page={currentPage + 1}
+            label="Go to next page"
             variant="outline"
-            size="icon"
-            onClick={() => onPageChange(currentPage + 1)}
+            className={NEIGHBOUR_CLASS}
             disabled={currentPage === totalPages}
-            aria-label="Go to next page"
-            className="!h-10 !w-10 content-md:!h-10 content-md:!w-10"
+            rel="next"
+            onPageChange={onPageChange}
+            getPageHref={getPageHref}
           >
             <ChevronRight className="h-4 w-4" />
             <span className="sr-only">Next page</span>
-          </Button>
+          </PaginationControl>
         </li>
       </ul>
     </nav>

package/src/components/shared/dev-section/dev-section-page.tsx

@@ -22,6 +22,7 @@ import {
   OPENFRAME_DEV_SECTIONS,
   type OpenframeDevSectionKey,
 } from '../../../utils/dev-sections/openframe-dev-sections';
+import { FaqSection, pageFaqProps, type PageFaqSlot } from '../../faq/faq-section';
 import { PageShell, PageLayout } from '../../ui';
 import { DevSectionView } from './dev-section-view';
 
@@ -51,6 +52,12 @@ export interface DevSectionPageProps {
    *  `false` when the host layout already provides the page container (e.g.
    *  openframe-frontend's `AppLayout` `<main>`): then only the
    *  `page-shell-content` padding box is rendered, avoiding a nested `<main>`. */
+  /**
+   * The page's own FAQ block: the topic the page is about (stated by the host,
+   * never read from its address) and where the host serves the FAQs. Rendered
+   * after the page's content, inside its container. Absent: no FAQ block.
+   */
+  faq?: PageFaqSlot;
   shell?: boolean;
 }
 
@@ -61,6 +68,7 @@ export function DevSectionPage({
   backButton,
   title,
   subtitle,
+  faq,
   shell = true,
 }: DevSectionPageProps) {
   const router = useRouter();
@@ -95,6 +103,7 @@ export function DevSectionPage({
       <DevSectionView sectionKey={sectionKey} showHeading={false} preControls={preControls}>
         {children}
       </DevSectionView>
+      {faq && <FaqSection {...pageFaqProps(faq)} />}
     </PageLayout>
   );
 

package/src/components/shared/legal-document/legal-document-page.tsx

@@ -21,6 +21,7 @@ import type { ComponentType } from 'react';
 import Link from '../../../embed-shims/next-link';
 import { useRouter } from '../../../embed-shims/next-navigation';
 import { formatLegalDate } from '../../../utils/format';
+import { FaqSection, pageFaqProps, type PageFaqSlot } from '../../faq/faq-section';
 import { PageShell, PageLayout } from '../../ui';
 import { RichMarkdownRenderer } from '../../ui/markdown';
 import { useLegalDocs, type LegalDocument } from './use-legal-docs';
@@ -64,6 +65,12 @@ export interface LegalDocumentPageProps {
   /** Back-button config — same pattern as `DevSectionPage`. Pass `false`
    *  to hide. Default `{ label: 'Back to home', href: '/' }`. */
   backButton?: { label?: string; href?: string } | false;
+  /**
+   * The page's own FAQ block: the topic the page is about (stated by the host,
+   * never read from its address) and where the host serves the FAQs. Rendered
+   * after the page's content, inside its container. Absent: no FAQ block.
+   */
+  faq?: PageFaqSlot;
   /** Render the standalone `<PageShell>`. Default true. Pass false when the host
    *  layout already provides the page container — only the padding box renders,
    *  avoiding a nested `<main>`. */
@@ -83,6 +90,7 @@ export function LegalDocumentPage({
   apiEndpoint,
   MarkdownRenderer = RichMarkdownRenderer,
   backButton,
+  faq,
   shell = true,
 }: LegalDocumentPageProps) {
   const router = useRouter();
@@ -161,6 +169,7 @@ export function LegalDocumentPage({
           </div>
         </div>
       </div>
+      {faq && <FaqSection {...pageFaqProps(faq)} />}
     </PageLayout>
   );