@flamingo-stack/openframe-frontend-core 0.0.315 → 0.0.316

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

@@ -25,8 +25,6 @@ import {
   type OpenframeDevSectionKey,
 } from '../../../utils/dev-sections/openframe-dev-sections';
 
-const SECTION_HERO_ICON_CLASS = 'h-10 w-10 text-ods-accent';
-
 export interface DevSectionPageProps {
   sectionKey: OpenframeDevSectionKey;
   /** The page-specific list body (e.g. `<RoadmapList />`). */
@@ -48,6 +46,12 @@ export interface DevSectionPageProps {
   /** Override the hero subtitle/description. Defaults to
    *  `OPENFRAME_DEV_SECTIONS[sectionKey].hero.description`. */
   subtitle?: string;
+  /** Render the standalone `<PageShell>` (own `<main>` + bg + max-width). Default
+   *  `true` — the contract for marketing/hub surfaces with no app shell. Pass
+   *  `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>`. */
+  shell?: boolean;
 }
 
 export function DevSectionPage({
@@ -57,10 +61,10 @@ export function DevSectionPage({
   backButton,
   title,
   subtitle,
+  shell = true,
 }: DevSectionPageProps) {
   const router = useRouter();
   const section = OPENFRAME_DEV_SECTIONS[sectionKey];
-  const Icon = section.icon;
 
   // Back-button config — mirrors LegalDocumentPage / ReleaseDetailPage.
   // Default: { label: 'Back to home', href: '/' }. Pass `false` to hide.
@@ -74,21 +78,27 @@ export function DevSectionPage({
           onClick: () => router.push((backButton ? backButton.href : undefined) ?? '/'),
         };
 
-  return (
-    <PageShell>
-      <PageLayout backButton={backCfg}>
-        <DevSectionView
-          sectionKey={sectionKey}
-          hero={{
-            icon: <Icon className={SECTION_HERO_ICON_CLASS} />,
-            title,
-            description: subtitle ?? section.hero.description,
-          }}
-          preControls={preControls}
-        >
-          {children}
-        </DevSectionView>
-      </PageLayout>
-    </PageShell>
+  const inner = (
+    // Unified header: title/description route through the canonical (frozen)
+    // `PageLayout` `TitleBlock` (text-h2) — same as FAQ / Legal / detail pages —
+    // so every help-center surface shares one header. `DevSectionView` then
+    // renders ONLY its search + filter controls (`showHeading={false}`), no
+    // duplicate title. (The hero icon is intentionally dropped: TitleBlock is
+    // frozen and renders title-only.)
+    <PageLayout
+      title={title ?? section.hero.title}
+      subtitle={subtitle ?? section.hero.description}
+      titleSize="h1"
+      backButton={backCfg}
+    >
+      <DevSectionView sectionKey={sectionKey} showHeading={false} preControls={preControls}>
+        {children}
+      </DevSectionView>
+    </PageLayout>
   );
+
+  // `shell` true → standalone `<PageShell>` (own <main> + bg + max-width).
+  // false → padding-only box (no nested <main>) for hosts whose layout already
+  // provides the container; both consume the host's `--page-shell-*` vars.
+  return shell ? <PageShell>{inner}</PageShell> : <div className="page-shell-content">{inner}</div>;
 }

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

@@ -51,9 +51,15 @@ export interface DevSectionViewProps {
   /** The page-specific list body. Reads URL params written by this
    *  component (search input + filter pills). */
   children: ReactNode;
+  /** Render this component's own title heading (hero or compact `h2`). Default
+   *  `true` — the tab context renders the compact heading itself. Pass `false`
+   *  when the host already renders the title elsewhere (e.g. `DevSectionPage`
+   *  routes it through the unified `PageLayout` `TitleBlock`): then only the
+   *  search + filter controls + list render, with no duplicate heading. */
+  showHeading?: boolean;
 }
 
-export function DevSectionView({ sectionKey, hero, preControls, children }: DevSectionViewProps) {
+export function DevSectionView({ sectionKey, hero, preControls, children, showHeading = true }: DevSectionViewProps) {
   const section = OPENFRAME_DEV_SECTIONS[sectionKey];
   const router = useRouter();
   const pathname = usePathname();
@@ -94,24 +100,25 @@ export function DevSectionView({ sectionKey, hero, preControls, children }: DevS
 
   return (
     <div className="w-full flex flex-col gap-10">
-      {hero ? (
-        <div className="space-y-4">
-          <h1 className="text-h1 tracking-[-1.12px] text-ods-text-primary flex items-center gap-3">
-            {hero.icon}
-            {hero.title ?? section.hero.title}
-          </h1>
-          <p className="font-['DM_Sans'] font-medium text-[18px] leading-[28px] text-ods-text-secondary max-w-3xl">
-            {hero.description}
-          </p>
-        </div>
-      ) : (
-        <div className="flex items-center justify-between w-full">
-          <h2 className="font-['Azeret_Mono'] font-semibold text-[32px] md:text-[40px] lg:text-[48px] leading-[40px] md:leading-[48px] lg:leading-[56px] text-ods-text-primary tracking-[-0.64px] md:tracking-[-0.8px] lg:tracking-[-0.96px]">
-            {section.hero.title}
-            <span className="text-ods-accent">:</span>
-          </h2>
-        </div>
-      )}
+      {showHeading &&
+        (hero ? (
+          <div className="space-y-4">
+            <h1 className="text-h1 tracking-[-1.12px] text-ods-text-primary flex items-center gap-3">
+              {hero.icon}
+              {hero.title ?? section.hero.title}
+            </h1>
+            <p className="font-['DM_Sans'] font-medium text-[18px] leading-[28px] text-ods-text-secondary max-w-3xl">
+              {hero.description}
+            </p>
+          </div>
+        ) : (
+          <div className="flex items-center justify-between w-full">
+            <h2 className="font-['Azeret_Mono'] font-semibold text-[32px] md:text-[40px] lg:text-[48px] leading-[40px] md:leading-[48px] lg:leading-[56px] text-ods-text-primary tracking-[-0.64px] md:tracking-[-0.8px] lg:tracking-[-0.96px]">
+              {section.hero.title}
+              <span className="text-ods-accent">:</span>
+            </h2>
+          </div>
+        ))}
 
       {preControls}
 

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

@@ -18,7 +18,7 @@
  */
 
 import type { ComponentType } from 'react';
-import { PageShell, PageLayout, PageHeading } from '../../ui';
+import { PageShell, PageLayout } from '../../ui';
 import { RichMarkdownRenderer } from '../../ui/rich-markdown-renderer';
 import { useRouter } from '../../../embed-shims/next-navigation';
 import { useLegalDocs, type LegalDocument } from './use-legal-docs';
@@ -63,6 +63,10 @@ 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;
+  /** 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>`. */
+  shell?: boolean;
 }
 
 export function LegalDocumentPage({
@@ -78,6 +82,7 @@ export function LegalDocumentPage({
   apiEndpoint,
   MarkdownRenderer = RichMarkdownRenderer,
   backButton,
+  shell = true,
 }: LegalDocumentPageProps) {
   const router = useRouter();
   const { data, isLoading, error } = useLegalDocs(docType, { initialData, apiEndpoint });
@@ -97,28 +102,18 @@ export function LegalDocumentPage({
     data?.lastSynced != null ? formatLegalDate(data.lastSynced) : null;
   const effectiveLastUpdatedLabel = initialLastUpdatedLabel ?? fallbackLastUpdatedLabel;
 
-  // Title with accent-colon trailing dot — matches knowledge-hub typography
-  const customTitle = (
-    <div className="flex flex-col gap-4">
-      <PageHeading>
-        <span>{title}</span>
-        <span className="text-ods-accent">.</span>
-      </PageHeading>
-      <p className="font-['DM_Sans'] text-base md:text-lg text-ods-text-secondary max-w-2xl">
-        {effectiveLastUpdatedLabel ? `Last Updated: ${effectiveLastUpdatedLabel}` : fallbackDescription}
-        {data?.sourceFile && (
-          <span className="block text-sm mt-1 opacity-75">Source: {data.sourceFile}</span>
-        )}
-      </p>
-    </div>
-  );
+  // Subtitle routes through the frozen `PageLayout` `TitleBlock` (text-h2 title
+  // + subtitle) — unified header across all help-center pages. Shows the
+  // last-updated date when known, else the fallback description.
+  const subtitle = effectiveLastUpdatedLabel ? `Last Updated: ${effectiveLastUpdatedLabel}` : fallbackDescription;
 
-  return (
-    <PageShell>
-      <PageLayout backButton={backCfg}>
-        <div className="flex flex-col gap-4">{customTitle}</div>
+  const inner = (
+    <PageLayout title={title} subtitle={subtitle} backButton={backCfg} titleSize="h1">
+      {data?.sourceFile && (
+        <p className="font-['DM_Sans'] text-sm text-ods-text-secondary opacity-75">Source: {data.sourceFile}</p>
+      )}
 
-        <div className="flex flex-col lg:flex-row gap-6 lg:gap-10 items-start flex-1">
+      <div className="flex flex-col lg:flex-row gap-6 lg:gap-10 items-start flex-1">
           <div className="flex-1">
             <div className="w-full">
               <article className="space-y-2">
@@ -172,7 +167,8 @@ export function LegalDocumentPage({
             </div>
           </div>
         </div>
-      </PageLayout>
-    </PageShell>
+    </PageLayout>
   );
+
+  return shell ? <PageShell>{inner}</PageShell> : <div className="page-shell-content">{inner}</div>;
 }

package/src/components/shared/product-release/release-detail-page.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useState, useEffect, ComponentType } from 'react';
+import { useState, useEffect, ComponentType, type ReactNode } from 'react';
 import Link from '../../../embed-shims/next-link';
 import { useRouter } from '../../../embed-shims/next-navigation';
 import { Card, CardContent } from '../../ui/card';
@@ -108,6 +108,15 @@ export interface ReleaseDetailPageProps {
   /** Link target for the author name in the metadata grid — the host
    *  computes it (public author page; absent ⇒ plain text). */
   authorHref?: string;
+  /** Optional slot rendered inside the page chrome, BELOW the article body —
+   *  e.g. the hub's end-of-article author byline + related-content / FAQ rail.
+   *  Lets the hub mount this page directly (no local wrapper component) while
+   *  embedders that don't have those extras simply omit it. */
+  relatedContent?: ReactNode;
+  /** 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>`. */
+  shell?: boolean;
 }
 
 // Default renderer = the lib's `RichMarkdownRenderer` so out-of-the-box
@@ -128,9 +137,15 @@ export function ReleaseDetailPage({
   VideoDisplaySection,
   roadmapApiEndpoint = '/api/roadmap',
   deliveryApiEndpoint = '/api/delivery',
-  backButton
+  backButton,
+  relatedContent,
+  shell = true
 }: ReleaseDetailPageProps) {
   const router = useRouter();
+  // `shell` true → standalone `<PageShell>`; false → padding-only box (no nested
+  // <main>) for hosts whose layout already provides the container.
+  const renderShell = (node: ReactNode) =>
+    shell ? <PageShell>{node}</PageShell> : <div className="page-shell-content">{node}</div>;
   // Use pre-fetched data if provided (admin preview), otherwise fetch via hook (public)
   const { data: fetchedRelease, error, isLoading } = useRelease(initialData ? undefined : slug);
   const release = (initialData || fetchedRelease) as Record<string, unknown> | undefined;
@@ -191,25 +206,21 @@ export function ReleaseDetailPage({
   if (!initialData && isLoading) {
     // `bare` + `PageShell` so the loading state matches the loaded page's full
     // width / padding / min-height (the wrapper supplies the page chrome).
-    return (
-      <PageShell>
-        {/* Match the loaded page's top offset (TitleBlock's
-            `pt-[var(--spacing-system-l)]`) so content doesn't jump on load. */}
-        <div className="pt-[var(--spacing-system-l)]">
-          <DetailPageSkeleton bare metadataColumns={4} showImageGallery={true} />
-        </div>
-      </PageShell>
+    return renderShell(
+      // Match the loaded page's top offset (TitleBlock's
+      // `pt-[var(--spacing-system-l)]`) so content doesn't jump on load.
+      <div className="pt-[var(--spacing-system-l)]">
+        <DetailPageSkeleton bare metadataColumns={4} showImageGallery={true} />
+      </div>
     );
   }
 
   if (error || !release) {
-    return (
-      <PageShell>
-        <div className="text-center py-16">
-          <h1 className="text-4xl font-bold text-ods-text-primary mb-4">Release Not Found</h1>
-          <p className="text-xl text-ods-text-secondary">The release you&apos;re looking for doesn&apos;t exist.</p>
-        </div>
-      </PageShell>
+    return renderShell(
+      <div className="text-center py-16">
+        <h1 className="text-4xl font-bold text-ods-text-primary mb-4">Release Not Found</h1>
+        <p className="text-xl text-ods-text-secondary">The release you&apos;re looking for doesn&apos;t exist.</p>
+      </div>
     );
   }
 
@@ -241,29 +252,16 @@ export function ReleaseDetailPage({
   const bugFixed = release.bugs_fixed as ChangelogEntry[] | undefined;
   const improvements = release.improvements as ChangelogEntry[] | undefined;
 
-  return (
-    <PageShell>
-      <PageLayout
+  return renderShell(
+    <PageLayout
+        title={releaseTitle}
+        subtitle={`Version: ${releaseVersion}`}
+        titleSize="h1"
         backButton={
           showBackButton ? { label: backLabel, onClick: () => router.push(backHref) } : undefined
         }
       >
       <div className="space-y-6 md:space-y-8">
-        {/* Title Block */}
-        <div className="flex flex-col md:flex-row md:items-end gap-4 w-full">
-          <div className="flex-1 flex flex-col gap-2">
-            {/* Title */}
-            <h1 className="text-h1 tracking-[-1.12px] text-ods-text-primary">
-              {releaseTitle}
-            </h1>
-
-            {/* Version */}
-            <p className="text-h4 text-ods-text-secondary">
-              Version: {releaseVersion}
-            </p>
-          </div>
-        </div>
-
         {/* Tags — flat product_release_tags[] from entity_tags */}
         <EntityTagBadges tags={release.product_release_tags as TagAssoc[] | undefined} />
 
@@ -568,7 +566,9 @@ export function ReleaseDetailPage({
           </div>
         )}
       </div>
+
+      {/* Host slot — end-of-article byline + related-content / FAQ rail. */}
+      {relatedContent}
       </PageLayout>
-    </PageShell>
   );
 }

package/src/components/tickets/help-center-list.tsx

@@ -59,9 +59,13 @@ export interface HelpCenterListProps {
    *  the `tickets` section copy ("Help Center"). Set this to brand the surface
    *  for an embed that wants its own label (e.g. "Support Tickets"). */
   title?: string
+  /** Render the standalone `<PageShell>` (forwarded to the internal
+   *  `DevSectionPage`). Default true. Pass false when the host layout already
+   *  provides the page container (avoids a nested `<main>`). */
+  shell?: boolean
 }
 
-export function HelpCenterList({ toast = defaultToast, backButton, title }: HelpCenterListProps = {}) {
+export function HelpCenterList({ toast = defaultToast, backButton, title, shell }: HelpCenterListProps = {}) {
   const identity = useChatIdentity()
   const searchParams = useSearchParams()
   const router = useRouter()
@@ -93,6 +97,7 @@ export function HelpCenterList({ toast = defaultToast, backButton, title }: Help
         sectionKey="tickets"
         backButton={backButton}
         title={title}
+        shell={shell}
         preControls={<HelpCenterCreateFormSkeleton />}
       >
         <DevCardRowSkeletonList />
@@ -101,7 +106,7 @@ export function HelpCenterList({ toast = defaultToast, backButton, title }: Help
   }
   if (identity.authTier === 'anon' || !identity.user?.email) {
     return (
-      <DevSectionPage sectionKey="tickets" backButton={backButton} title={title}>
+      <DevSectionPage sectionKey="tickets" backButton={backButton} title={title} shell={shell}>
         <EmptyState
           type="generic"
           title="Sign in to manage tickets"
@@ -138,6 +143,7 @@ export function HelpCenterList({ toast = defaultToast, backButton, title }: Help
       sessionEmail={sessionEmail}
       backButton={backButton}
       title={title}
+      shell={shell}
     />
   )
 }
@@ -156,6 +162,7 @@ interface AuthedProps {
   sessionEmail: string
   backButton?: { label?: string; href?: string } | false
   title?: string
+  shell?: boolean
 }
 
 function HelpCenterListAuthed({
@@ -171,6 +178,7 @@ function HelpCenterListAuthed({
   sessionEmail,
   backButton,
   title,
+  shell,
 }: AuthedProps) {
   const queryClient = useQueryClient()
   const [optimisticTickets, setOptimisticTickets] = useState<OptimisticTicket[]>([])
@@ -398,7 +406,7 @@ function HelpCenterListAuthed({
   )
 
   return (
-    <DevSectionPage sectionKey="tickets" backButton={backButton} title={title} preControls={form}>
+    <DevSectionPage sectionKey="tickets" backButton={backButton} title={title} shell={shell} preControls={form}>
       {body}
     </DevSectionPage>
   )