@flamingo-stack/openframe-frontend-core 0.0.314 → 0.0.315-snapshot.20260624135932

package/src/components/faq/faq-document-page.tsx

@@ -2,19 +2,17 @@
 
 /**
  * FaqDocumentPage — the full `/faqs` page with chrome, so embedders drop in
- * ONE component instead of hand-assembling `PageShell` + `PageLayout` + the
- * FAQ hero around the bare `<FaqSection>`. Mirrors `LegalDocumentPage` /
- * `DevSectionPage`: the page-level layout lives in the lib, the host page is a
- * thin wrapper that passes only config + the SSR-resolved data.
+ * ONE component instead of hand-assembling `PageShell` + `PageLayout` around
+ * the bare `<FaqSection>`. Mirrors `LegalDocumentPage` / `DevSectionPage`: the
+ * page-level layout lives in the lib, the host page is a thin wrapper that
+ * passes only config + the SSR-resolved data.
  *
- * HERO: renders the canonical FAQ hero (`<h1 class="text-h1">` + accent dot +
- * icon + clamped subtitle) — byte-identical to the multi-platform hub's local
- * `PageWithHeader` chrome the standalone `/faqs` page historically used. It
- * does NOT route through `PageLayout`'s `title`/`subtitle` (the FROZEN
- * `text-h2` `TitleBlock` is a different, smaller header used by OpenFrame
- * detail surfaces). The page owns the `<h1>`, so `<FaqSection heading={null}>`
- * nests its category headings as `<h2>` and the questions as `<h3>` (the
- * SEO-recommended FAQ document outline).
+ * HERO: the title + subtitle route through the canonical (frozen) `PageLayout`
+ * `TitleBlock` with `titleSize="h1"` — the unified Help Center header (the
+ * `TitleBlock` element is always an `<h1>`; `titleSize` only sets its typography,
+ * here `text-h1`). The page owns that `<h1>`, so `<FaqSection heading={null}>`
+ * nests its category headings as `<h2>`/`<h3>` (the SEO-recommended FAQ document
+ * outline).
  *
  * DATA: pass `initialFaqs` (SSR-resolved, platform-scoped) so `FaqSection`
  * skips its client self-fetch — the standalone page's static platform-only
@@ -22,27 +20,25 @@
  * suggestion-fill instead.
  */
 
-import React from 'react';
-import { HelpCircle } from 'lucide-react';
 import type { Faq } from '../../types/faq';
 import { PageShell, PageLayout } from '../ui';
 import { useRouter } from '../../embed-shims/next-navigation';
-import { SECTION_HERO_ICON_CLASS } from '../../utils/page-header-constants';
 import { FaqSection } from './faq-section';
 import type { FaqSchemaOptions } from './json-ld';
 
 export interface FaqDocumentPageProps {
-  /** Hero `<h1>`. Default "Frequently Asked Questions". */
+  /** Page title (frozen `PageLayout` `TitleBlock`). Default "Frequently Asked Questions". */
   title?: string;
-  /** Subtitle under the title (auto-clamped to 2 lines). */
+  /** Subtitle under the title. */
   subtitle?: string;
-  /** Icon rendered before the title. Default `<HelpCircle>` (the FAQ glyph). */
-  titleIcon?: React.ReactNode;
-  /** Render the yellow accent dot after the title (default true). */
-  accentDot?: boolean;
   /** Back-button config — same pattern as `DevSectionPage` / `LegalDocumentPage`.
    *  Pass `false` to hide. Default `{ label: 'Back to home', href: '/' }`. */
   backButton?: { label?: string; href?: string } | false;
+  /** Render the standalone `<PageShell>` (own `<main>` + bg + max-width). Default
+   *  true. Pass false when the host layout already provides the page container
+   *  (e.g. openframe-frontend's `AppLayout` `<main>`) — only the padding box
+   *  renders, avoiding a nested `<main>`. */
+  shell?: boolean;
   /** SSR-hydrate `FaqSection` (skips the client fetch — the platform-only
    *  contract for the standalone page). Omit for self-fetching embeds. */
   initialFaqs?: Faq[];
@@ -63,8 +59,6 @@ export interface FaqDocumentPageProps {
 export function FaqDocumentPage({
   title = 'Frequently Asked Questions',
   subtitle,
-  titleIcon = <HelpCircle className={SECTION_HERO_ICON_CLASS} />,
-  accentDot = true,
   backButton,
   initialFaqs,
   emitJsonLd,
@@ -73,6 +67,7 @@ export function FaqDocumentPage({
   entityType,
   entityId,
   minResults,
+  shell = true,
 }: FaqDocumentPageProps) {
   const router = useRouter();
 
@@ -87,42 +82,20 @@ export function FaqDocumentPage({
           onClick: () => router.push(backButton?.href ?? '/'),
         };
 
-  return (
-    <PageShell>
-      <PageLayout backButton={backCfg}>
-        <div className="w-full flex flex-col gap-10">
-          {/* Canonical FAQ hero — the exact DOM/CSS the hub's local
-              `PageWithHeader` rendered (text-h1 + accent dot + icon + clamped
-              subtitle), inlined here so the standalone `/faqs` look is owned by
-              the lib. Intentionally NOT the frozen `text-h2` `TitleBlock`. */}
-          <div className="flex items-end justify-between gap-[var(--spacing-system-m)] md:flex-col md:items-start md:justify-start lg:flex-row lg:items-end lg:justify-between">
-            <div className="flex flex-col gap-[var(--spacing-system-xs)] flex-1 min-w-0">
-              <div className="space-y-4">
-                <h1 className="text-h1 tracking-[-1.12px] text-ods-text-primary flex items-center gap-3">
-                  {titleIcon}
-                  <span>
-                    {title}
-                    {accentDot && <span className="text-ods-accent">.</span>}
-                  </span>
-                </h1>
-                <p className="font-['DM_Sans'] font-medium text-[18px] leading-[28px] text-ods-text-secondary max-w-3xl line-clamp-2 min-h-[56px]">
-                  {subtitle || ' '}
-                </p>
-              </div>
-            </div>
-          </div>
-          <FaqSection
-            initialFaqs={initialFaqs}
-            heading={null}
-            emitJsonLd={emitJsonLd}
-            jsonLd={jsonLd}
-            apiBaseUrl={apiBaseUrl}
-            entityType={entityType}
-            entityId={entityId}
-            minResults={minResults}
-          />
-        </div>
-      </PageLayout>
-    </PageShell>
+  const inner = (
+    <PageLayout title={title} subtitle={subtitle} backButton={backCfg} titleSize="h1">
+      <FaqSection
+        initialFaqs={initialFaqs}
+        heading={null}
+        emitJsonLd={emitJsonLd}
+        jsonLd={jsonLd}
+        apiBaseUrl={apiBaseUrl}
+        entityType={entityType}
+        entityId={entityId}
+        minResults={minResults}
+      />
+    </PageLayout>
   );
+
+  return shell ? <PageShell>{inner}</PageShell> : <div className="page-shell-content">{inner}</div>;
 }

package/src/components/features/push-button-selector.tsx

@@ -1,6 +1,7 @@
 "use client";
 
 import { Button, Badge } from "../ui";
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "../ui/tooltip";
 import { Check } from 'lucide-react';
 import React from 'react';
 
@@ -15,6 +16,7 @@ export interface SelectableOption {
   icon?: React.ReactNode;
   color?: string;
   disabled?: boolean;      // If true, option is shown grayed out and not selectable
+  disabledReason?: string; // Tooltip shown on hover when disabled — explains WHY it's unavailable
   section?: string;        // Optional section ID to group options
 }
 
@@ -151,19 +153,21 @@ export function PushButtonSelector({
   const renderOption = (option: SelectableOption) => {
     const isSelected = validSelectedIds.includes(option.id);
 
-    return (
+    const optionEl = (
       <div
         key={option.id}
         className={`
           p-4 rounded-lg border transition-all duration-200 group
           ${option.disabled
-            ? 'cursor-not-allowed opacity-40 bg-ods-card border-ods-border'
+            ? `${isSelected ? 'cursor-pointer' : 'cursor-not-allowed'} opacity-40 bg-ods-card border-ods-border`
             : isSelected
               ? 'cursor-pointer bg-ods-bg-secondary border-ods-accent shadow-sm'
               : 'cursor-pointer bg-ods-bg-primary border-ods-border hover:border-ods-border-hover hover:bg-ods-bg-hover'
           }
         `}
-        onClick={() => !option.disabled && toggleSelection(option.id)}
+        // Disabled options can't be newly SELECTED, but an already-selected one
+        // (e.g. it later became unavailable) must still be removable.
+        onClick={() => (!option.disabled || isSelected) && toggleSelection(option.id)}
       >
         <div className="flex items-center justify-between gap-4">
           <div className="flex items-center gap-3 flex-1 min-w-0">
@@ -199,6 +203,18 @@ export function PushButtonSelector({
         </div>
       </div>
     );
+
+    // Disabled options explain WHY on hover via the unified Tooltip.
+    if (option.disabled && option.disabledReason) {
+      return (
+        <Tooltip key={option.id}>
+          <TooltipTrigger asChild>{optionEl}</TooltipTrigger>
+          <TooltipContent className="max-w-xs">{option.disabledReason}</TooltipContent>
+        </Tooltip>
+      );
+    }
+
+    return optionEl;
   };
 
   // Group options by section if sections are provided
@@ -271,6 +287,7 @@ export function PushButtonSelector({
   };
 
   return (
+    <TooltipProvider delayDuration={150}>
     <div className={`space-y-4 ${className}`}>
       {title && (
         <h3 className="text-h5 text-ods-text-primary">
@@ -319,5 +336,6 @@ export function PushButtonSelector({
         </div>
       )}
     </div>
+    </TooltipProvider>
   );
 }

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

@@ -0,0 +1,45 @@
+'use client'
+
+/**
+ * `<DeliveryPage>` — the full bug-fixes & enhancements (`delivery`) page:
+ * `DevSectionPage sectionKey="delivery"` chrome wrapping the self-contained
+ * `<DeliveryLists>` (Recently Completed + Active Tasks tables). Hosts configure
+ * only the two bucket api routes.
+ */
+
+import type { ReactNode } from 'react'
+import { DevSectionPage } from '../shared/dev-section'
+import { DeliveryLists } from '../shared/delivery'
+
+export interface DeliveryPageProps {
+  /** GET endpoint for the "Recently Completed" bucket. Default `/api/delivery/completed`. */
+  completedEndpoint?: string
+  /** GET endpoint for the "Active Tasks" bucket. Default `/api/delivery/in-progress`. */
+  inProgressEndpoint?: string
+  /** Back-button config. Pass `false` to hide. Default `{ href: '/' }`. */
+  backButton?: { label?: string; href?: string } | false
+  title?: string
+  subtitle?: string
+  /** Optional slot rendered below the lists, inside the page chrome. */
+  belowContent?: ReactNode
+  /** Render the standalone `<PageShell>`. Default true. Pass false when the host
+   *  layout already provides the page container (forwarded to `DevSectionPage`). */
+  shell?: boolean
+}
+
+export function DeliveryPage({
+  completedEndpoint,
+  inProgressEndpoint,
+  backButton,
+  title,
+  subtitle,
+  belowContent,
+  shell,
+}: DeliveryPageProps) {
+  return (
+    <DevSectionPage sectionKey="delivery" backButton={backButton} title={title} subtitle={subtitle} shell={shell}>
+      <DeliveryLists completedApiEndpoint={completedEndpoint} inProgressApiEndpoint={inProgressEndpoint} />
+      {belowContent}
+    </DevSectionPage>
+  )
+}

package/src/components/help-center-pages/index.ts

@@ -0,0 +1,41 @@
+'use client'
+
+/**
+ * Help Center pages — ready-made, full-page components (each owns the canonical
+ * `PageShell` + `PageLayout` chrome) so a host route is a one-line mount with NO
+ * local wrapper. Shared by openframe-frontend (self-fetch via the `/content`
+ * proxy, mounted under `/help-center/*`) and multi-platform-hub (SSR with
+ * server-fetched `initialData` + `generateMetadata`/JSON-LD kept in the server
+ * route). Endpoint config + SSR data + optional slots are passed as props.
+ *
+ * This barrel ALSO re-exports the already-existing full-pages (FAQ / Legal /
+ * Release detail / Onboarding detail / Docs / Tickets) so consumers have ONE
+ * import site for "help center pages". Re-exports are NAMED (not `export *`) to
+ * avoid TS2308 ambiguous-re-export collisions, and this barrel is intentionally
+ * NOT merged into the top-level `components/index.ts`.
+ */
+
+// New combined pages. (The Help Center *index* landing is intentionally NOT
+// here — it stays a host-local page; its links + icons are app-specific.)
+export { RoadmapPage, type RoadmapPageProps } from './roadmap-page'
+export { ProductReleasesListPage, type ProductReleasesListPageProps } from './product-releases-list-page'
+export { DeliveryPage, type DeliveryPageProps } from './delivery-page'
+export {
+  OnboardingGuidesCatalogPage,
+  type OnboardingGuidesCatalogPageProps,
+} from './onboarding-guides-catalog-page'
+
+// Existing full-pages re-exported for a single Help Center import site.
+export { FaqDocumentPage, type FaqDocumentPageProps } from '../faq'
+export { LegalDocumentPage, type LegalDocumentPageProps } from '../shared/legal-document'
+export {
+  ReleaseDetailPage,
+  type ReleaseDetailPageProps,
+  type VideoDisplaySectionProps,
+} from '../shared/product-release'
+export {
+  OnboardingGuideDetailView,
+  type OnboardingGuideDetailViewProps,
+} from '../onboarding-guides'
+export { DocsHubPage } from '../docs'
+export { HelpCenterList } from '../tickets'

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

@@ -0,0 +1,66 @@
+'use client'
+
+/**
+ * `<OnboardingGuidesCatalogPage>` — the full `/onboarding-guides` catalog page:
+ * `DevSectionPage sectionKey="onboarding"` chrome wrapping the self-contained
+ * `<OnboardingGuidesCatalogView>` (RAG search + section pills + guide grid).
+ * Supports both SSR (`initialGuides`/`initialSections`) and self-fetch
+ * (`guidesEndpoint`/`sectionsEndpoint`) modes — forwarded to the view verbatim.
+ */
+
+import type { ReactNode } from 'react'
+import type { OnboardingGuide } from '../chat/types/entities/onboarding-guide'
+import { DevSectionPage } from '../shared/dev-section'
+import { OnboardingGuidesCatalogView } from '../onboarding-guides'
+
+type SectionSummary = { section: string; section_order: number; count: number }
+
+export interface OnboardingGuidesCatalogPageProps {
+  /** Self-fetch: GET list endpoint (the api route). Appends `?section=`. */
+  guidesEndpoint?: string
+  /** Self-fetch: GET section-summary endpoint (the api route). */
+  sectionsEndpoint?: string
+  /** Controlled / SSR: server-fetched guides + sections + active section. */
+  initialGuides?: OnboardingGuide[]
+  initialSections?: SectionSummary[]
+  initialSection?: string
+  /** Base path the catalog is mounted under (card href prefix + `?section=` push). */
+  basePath?: string
+  /** Back-button config. Pass `false` to hide. Default `{ href: '/' }`. */
+  backButton?: { label?: string; href?: string } | false
+  title?: string
+  subtitle?: string
+  /** Optional slot rendered below the catalog, inside the page chrome. */
+  belowContent?: ReactNode
+  /** Render the standalone `<PageShell>`. Default true. Pass false when the host
+   *  layout already provides the page container (forwarded to `DevSectionPage`). */
+  shell?: boolean
+}
+
+export function OnboardingGuidesCatalogPage({
+  guidesEndpoint,
+  sectionsEndpoint,
+  initialGuides,
+  initialSections,
+  initialSection,
+  basePath,
+  backButton,
+  title,
+  subtitle,
+  belowContent,
+  shell,
+}: OnboardingGuidesCatalogPageProps) {
+  return (
+    <DevSectionPage sectionKey="onboarding" backButton={backButton} title={title} subtitle={subtitle} shell={shell}>
+      <OnboardingGuidesCatalogView
+        guidesEndpoint={guidesEndpoint}
+        sectionsEndpoint={sectionsEndpoint}
+        initialGuides={initialGuides}
+        initialSections={initialSections}
+        initialSection={initialSection}
+        basePath={basePath}
+      />
+      {belowContent}
+    </DevSectionPage>
+  )
+}

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

@@ -0,0 +1,58 @@
+'use client'
+
+/**
+ * `<ProductReleasesListPage>` — the full `/releases` list page: `DevSectionPage
+ * sectionKey="releases"` chrome wrapping the self-contained `<ProductReleasesView>`.
+ * Hosts configure the api route + detail `basePath` (+ optional SSR `initialData`
+ * and a custom card-prop builder). Card → detail nav flows through
+ * `runtime.composeContentUrl`.
+ */
+
+import type { ReactNode } from 'react'
+import type { ProductRelease, ProductReleaseListResponse } from '../../types/product-release'
+import { DevSectionPage } from '../shared/dev-section'
+import { ProductReleasesView, type ProductReleaseCardExtras } from '../shared/product-release'
+
+export interface ProductReleasesListPageProps {
+  /** GET list endpoint (the api route). Default `/api/releases`. */
+  releasesEndpoint?: string
+  /** Fallback detail-href prefix when `composeContentUrl` is not wired. Default `/releases`. */
+  basePath?: string
+  /** Derive the per-card prop bundle (defaults to the lib's rich builder). */
+  buildCardProps?: (release: ProductRelease) => ProductReleaseCardExtras
+  /** Optional SSR hydrate for the first page (hub server-fetch). */
+  initialData?: ProductReleaseListResponse
+  /** Back-button config. Pass `false` to hide. Default `{ href: '/' }`. */
+  backButton?: { label?: string; href?: string } | false
+  title?: string
+  subtitle?: string
+  /** Optional slot rendered below the list, inside the page chrome. */
+  belowContent?: ReactNode
+  /** Render the standalone `<PageShell>`. Default true. Pass false when the host
+   *  layout already provides the page container (forwarded to `DevSectionPage`). */
+  shell?: boolean
+}
+
+export function ProductReleasesListPage({
+  releasesEndpoint,
+  basePath,
+  buildCardProps,
+  initialData,
+  backButton,
+  title,
+  subtitle,
+  belowContent,
+  shell,
+}: ProductReleasesListPageProps) {
+  return (
+    <DevSectionPage sectionKey="releases" backButton={backButton} title={title} subtitle={subtitle} shell={shell}>
+      <ProductReleasesView
+        endpoint={releasesEndpoint}
+        basePath={basePath}
+        buildCardProps={buildCardProps}
+        initialData={initialData}
+      />
+      {belowContent}
+    </DevSectionPage>
+  )
+}

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

@@ -0,0 +1,68 @@
+'use client'
+
+/**
+ * `<RoadmapPage>` — the full `/roadmap` page: `DevSectionPage sectionKey="roadmap"`
+ * (PageShell + PageLayout + hero + search/status chrome) wrapping the
+ * self-contained `<RoadmapView>` list. Hosts configure only the api routes
+ * (+ optional SSR `initialItems`); both openframe-frontend and the hub mount
+ * this instead of hand-composing `DevSectionPage` + `RoadmapView`.
+ */
+
+import type { ReactNode } from 'react'
+import type { RoadmapItem } from '../chat/types/entities/roadmap-item'
+import { DevSectionPage } from '../shared/dev-section'
+import { RoadmapView } from '../shared/roadmap'
+import type { UseRoadmapVotingOptions } from '../shared/roadmap'
+
+export interface RoadmapPageProps {
+  /** GET list endpoint (the api route). Default `/api/roadmap`. */
+  roadmapEndpoint?: string
+  /** Per-task refresh URL builder (after a vote). Default `/api/roadmap/<id>`. */
+  buildRefreshUrl?: (taskId: string) => string
+  /** Vote POST endpoint, forwarded to `RoadmapView` via `votingOptions`. */
+  voteApiEndpoint?: string
+  /** Full voting options override — takes precedence over `voteApiEndpoint`. */
+  votingOptions?: UseRoadmapVotingOptions
+  /** Optional SSR hydrate (hub server-fetch) — skips the initial client fetch. */
+  initialItems?: RoadmapItem[]
+  /** Indent the grid (the hub's full-page roadmap look). Default off. */
+  showLeftMargin?: boolean
+  /** Back-button config. Pass `false` to hide. Default `{ href: '/' }`. */
+  backButton?: { label?: string; href?: string } | false
+  /** Override the hero title/subtitle (defaults from `OPENFRAME_DEV_SECTIONS`). */
+  title?: string
+  subtitle?: string
+  /** Optional slot rendered below the list, inside the page chrome — e.g. the
+   *  hub's related-content rail. */
+  belowContent?: ReactNode
+  /** Render the standalone `<PageShell>`. Default true. Pass false when the host
+   *  layout already provides the page container (forwarded to `DevSectionPage`). */
+  shell?: boolean
+}
+
+export function RoadmapPage({
+  roadmapEndpoint,
+  buildRefreshUrl,
+  voteApiEndpoint,
+  votingOptions,
+  initialItems,
+  showLeftMargin,
+  backButton,
+  title,
+  subtitle,
+  belowContent,
+  shell,
+}: RoadmapPageProps) {
+  return (
+    <DevSectionPage sectionKey="roadmap" backButton={backButton} title={title} subtitle={subtitle} shell={shell}>
+      <RoadmapView
+        endpoint={roadmapEndpoint}
+        initialItems={initialItems}
+        showLeftMargin={showLeftMargin}
+        buildRefreshUrl={buildRefreshUrl}
+        votingOptions={votingOptions ?? (voteApiEndpoint ? { voteApiEndpoint } : undefined)}
+      />
+      {belowContent}
+    </DevSectionPage>
+  )
+}

package/src/components/layout/page-layout.tsx

@@ -25,6 +25,12 @@
  * If a new design genuinely needs different chrome: build a SEPARATE new
  * component for it. Never mutate this one. If you believe an edit here is
  * unavoidable, STOP and get explicit human sign-off first.
+ *
+ * SANCTIONED EXCEPTION (2026-06, explicit human sign-off): the OPTIONAL
+ * `titleSize` prop, forwarded to `TitleBlock`. Defaults to `'h2'` — the frozen
+ * baseline is unchanged for every existing caller. `titleSize="h1"` opts the
+ * title up to `text-h1` (the unified Help Center pages). Additive + default-
+ * preserving; do NOT change the default or anything else here.
  * ========================================================================== */
 
 import React from 'react'
@@ -49,6 +55,9 @@ export interface PageLayoutProps {
   className?: string
   contentClassName?: string
   showHeader?: boolean
+  /** Title typography size, forwarded to `TitleBlock`. Default `'h2'` (frozen
+   *  baseline). Pass `'h1'` for the unified Help Center pages. */
+  titleSize?: 'h1' | 'h2'
 }
 
 /**
@@ -70,6 +79,7 @@ export function PageLayout({
   className,
   contentClassName,
   showHeader = true,
+  titleSize,
 }: PageLayoutProps) {
   const hasActions = actions && actions.length > 0
   const needsBottomPadding = hasActions && actionsVariant === 'primary-buttons'
@@ -88,6 +98,7 @@ export function PageLayout({
           menuActions={menuActions}
           selector={selector}
           variant={headerVariant}
+          titleSize={titleSize}
         />
       )}
 

package/src/components/layout/title-block.tsx

@@ -22,6 +22,13 @@
  * current output. If a new design needs different chrome, build a SEPARATE new
  * component — never mutate this one. If an edit here seems unavoidable, STOP
  * and get explicit human sign-off first.
+ *
+ * SANCTIONED EXCEPTION (2026-06, explicit human sign-off): the OPTIONAL
+ * `titleSize` prop. It defaults to `'h2'` — i.e. the frozen baseline above is
+ * unchanged for EVERY existing caller. A caller may pass `titleSize="h1"` to
+ * opt the title typography up to `text-h1` (used by the unified Help Center
+ * pages). This is additive and default-preserving; do NOT change the default or
+ * touch anything else here.
  * ========================================================================== */
 
 import React from 'react'
@@ -59,6 +66,10 @@ export interface TitleBlockProps {
    */
   variant?: 'plain' | 'card'
   className?: string
+  /** Title typography size. Default `'h2'` (the frozen baseline). Pass `'h1'` to
+   *  opt the title up to `text-h1` (the unified Help Center pages). Subtitle stays
+   *  `text-h6` either way. */
+  titleSize?: 'h1' | 'h2'
 }
 
 export function TitleBlock({
@@ -72,9 +83,11 @@ export function TitleBlock({
   selector,
   variant = 'plain',
   className,
+  titleSize = 'h2',
 }: TitleBlockProps) {
   const hasActions = actions && actions.length > 0
   const hasMenuActions = !!menuActions && menuActions.some(g => g.items.length > 0)
+  const titleClass = titleSize === 'h1' ? 'text-h1' : 'text-h2'
 
   return (
     <div
@@ -113,7 +126,7 @@ export function TitleBlock({
             )}
             <div className="flex flex-col justify-center min-w-0 flex-1">
               {title && (
-                <h1 className="text-h2 text-ods-text-primary truncate" title={title}>{title}</h1>
+                <h1 className={cn(titleClass, 'text-ods-text-primary truncate')} title={title}>{title}</h1>
               )}
               {subtitle && (
                 <p className="text-h6 text-ods-text-secondary truncate" title={subtitle}>{subtitle}</p>
@@ -121,7 +134,7 @@ export function TitleBlock({
             </div>
           </div>
         ) : (
-          title && <h1 className="text-h2 text-ods-text-primary">{title}</h1>
+          title && <h1 className={cn(titleClass, 'text-ods-text-primary')}>{title}</h1>
         )}
       </div>