@flamingo-stack/openframe-frontend-core 0.0.736 → 0.0.738

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>
   );
 

package/src/components/ui/app-window-frame.tsx

@@ -1,5 +1,8 @@
+'use client';
+
 import type { ReactNode } from 'react';
 import { cn } from '../../utils/cn';
+import { useAgentTint } from '../agent-identity';
 
 export interface AppWindowFrameProps {
   /** Centered in the title bar. */
@@ -7,6 +10,12 @@ export interface AppWindowFrameProps {
   children: ReactNode;
   /** A bar pinned under the body (a status line, an action). */
   footer?: ReactNode;
+  /**
+   * The slug of the agent whose window this is. The window takes that agent's
+   * tint from its identity, like every card of the agent's. A window names its
+   * agent, never a colour.
+   */
+  agent?: string | null;
   className?: string;
   /** The scrolling body between the title bar and the footer. */
   bodyClassName?: string;
@@ -19,10 +28,17 @@ export interface AppWindowFrameProps {
  *
  * The frame is a column, so give it a height and the body fills what is left.
  */
-export function AppWindowFrame({ title, children, footer, className, bodyClassName }: AppWindowFrameProps) {
+export function AppWindowFrame({ title, children, footer, agent, className, bodyClassName }: AppWindowFrameProps) {
+  const tint = useAgentTint(agent);
   return (
     <div
-      className={cn('flex min-w-0 flex-col overflow-hidden rounded-xl border border-ods-border bg-ods-card', className)}
+      className={cn(
+        'flex min-w-0 flex-col overflow-hidden rounded-xl border border-ods-border',
+        // An agent's window sits on the page surface under that agent's tint.
+        tint ? 'bg-ods-bg' : 'bg-ods-card',
+        className,
+      )}
+      style={tint}
     >
       <div className="relative flex h-10 shrink-0 items-center gap-2 border-b border-ods-border px-4" aria-hidden>
         <span className="h-2.5 w-2.5 rounded-full bg-ods-border" />

package/src/components/ui/benefit-list.tsx

@@ -0,0 +1,97 @@
+import type { ReactNode } from 'react';
+import { cn } from '../../utils/cn';
+import { trialLabels } from '../../utils/trial';
+import { FileOffIcon } from '../icons-v2-generated/documents/file-off-icon';
+import { CreditCardXmarkIcon } from '../icons-v2-generated/finance/credit-card-xmark-icon';
+import { FlaskVialIcon } from '../icons-v2-generated/school/flask-vial-icon';
+import { XmarkAltIcon } from '../icons-v2-generated/signs-and-symbols/xmark-alt-icon';
+
+export interface BenefitItem {
+  /** Drawn at 16px in the quiet colour. */
+  icon?: ReactNode;
+  label: string;
+}
+
+/** The mark of each of the trial's terms, wherever a term is listed. */
+export const TRIAL_TERM_ICONS = {
+  noCard: <CreditCardXmarkIcon />,
+  cancel: <XmarkAltIcon />,
+  length: <FlaskVialIcon />,
+  noContract: <FileOffIcon />,
+} as const;
+export type TrialTerm = keyof typeof TRIAL_TERM_ICONS;
+
+/** The trial's terms a list shows when its host names none: cancel anytime, the trial's length, no contract. */
+export const DEFAULT_TRIAL_TERMS: readonly TrialTerm[] = ['cancel', 'length', 'noContract'];
+
+/** The named terms of the trial as benefits, in the order given. The length is left out when the host does not know it. */
+export function trialBenefits(
+  trialDays: number | string | null | undefined,
+  terms: readonly TrialTerm[] = DEFAULT_TRIAL_TERMS,
+): BenefitItem[] {
+  const labels = trialLabels(trialDays);
+  return terms.flatMap(term => {
+    const label = labels[term];
+    return label ? [{ icon: TRIAL_TERM_ICONS[term], label }] : [];
+  });
+}
+
+export interface BenefitListProps {
+  /**
+   * Which of the trial's terms to list, in order ("cancel", "length",
+   * "noContract", "noCard"). Omitted: none, the list is `items` alone.
+   */
+  terms?: readonly TrialTerm[];
+  /** The free trial's length in days, for the `length` term. Without it that term is left out. */
+  trialDays?: number | string | null;
+  /** The host's own benefits. With `terms`, `itemsFirst` says which come first. */
+  items?: BenefitItem[];
+  /** Draw `items` before the trial's terms. Default: after them. */
+  itemsFirst?: boolean;
+  /** `center` centres the row (under a centred hero). Default `start`. */
+  align?: 'start' | 'center';
+  className?: string;
+}
+
+/**
+ * THE row of short benefits beside a call to action ("Cancel Anytime", "No
+ * Contract"): a small mark and a few words each, wrapping as a row. The one
+ * such row everywhere: the sign-up panel, every hero, every closing call to
+ * action. A host chooses WHICH benefits (`terms`, `items`), never how they look.
+ */
+export function BenefitList({
+  terms,
+  trialDays,
+  items = [],
+  itemsFirst = false,
+  align = 'start',
+  className,
+}: BenefitListProps) {
+  const termItems = terms ? trialBenefits(trialDays, terms) : [];
+  const all = itemsFirst ? [...items, ...termItems] : [...termItems, ...items];
+  if (all.length === 0) return null;
+  return (
+    <ul
+      className={cn(
+        // A full step between benefits, a tighter one between wrapped rows: each reads as its own point.
+        'm-0 flex list-none flex-wrap content-center items-center gap-x-[var(--spacing-system-l)] gap-y-[var(--spacing-system-m)] p-0',
+        align === 'center' && 'justify-center',
+        className,
+      )}
+    >
+      {all.map(item => (
+        <li key={item.label} className="flex items-center gap-[var(--spacing-system-xs)]">
+          {item.icon && (
+            <span
+              className="flex size-4 shrink-0 items-center justify-center text-ods-text-secondary [&_svg]:size-4"
+              aria-hidden
+            >
+              {item.icon}
+            </span>
+          )}
+          <span className="whitespace-nowrap text-ods-text-primary text-h4">{item.label}</span>
+        </li>
+      ))}
+    </ul>
+  );
+}

package/src/components/ui/button/button.tsx

@@ -90,8 +90,19 @@ const buttonVariants = cva(
         true: 'px-0',
         false: '',
       },
+      // Two buttons drawn as ONE surface with a seam between them (a main action
+      // and a chevron that opens its alternatives: `DropdownButton` with an
+      // `action`). `start` is the leading half, `end` the trailing one: each
+      // gives up the corners and the border on its inner edge.
+      attach: {
+        none: '',
+        start: 'rounded-r-none',
+        end: 'rounded-l-none border-l-0',
+      },
     },
     compoundVariants: [
+      // The trailing half as an icon button is the design's 40px chevron cell, at every breakpoint.
+      { attach: 'end', size: 'icon', class: 'w-10 px-0 md:w-10' },
       { size: 'small', class: '[&_svg]:h-4 [&_svg]:w-4' },
       // Comes after the size classes, so cn()'s tailwind-merge resolves the
       // ods-typography group in favour of text-h4.
@@ -103,6 +114,7 @@ const buttonVariants = cva(
       font: 'bold',
       fullWidth: false,
       noPaddingX: false,
+      attach: 'none',
     },
   },
 );
@@ -267,6 +279,7 @@ const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(function ButtonI
     font,
     fullWidth,
     noPaddingX,
+    attach,
     asChild,
     href,
     openInNewTab,
@@ -389,7 +402,7 @@ const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(function ButtonI
     );
   }
 
-  const classes = cn(buttonVariants({ variant, size, font, fullWidth, noPaddingX }), className);
+  const classes = cn(buttonVariants({ variant, size, font, fullWidth, noPaddingX, attach }), className);
 
   // asChild: consumer fully controls the rendered element; we just stamp our classes.
   if (asChild) {

package/src/components/ui/dropdown-button.tsx

@@ -6,9 +6,26 @@ import { Chevron02DownIcon } from '../icons-v2-generated';
 import { ActionsMenuDropdown, type ActionsMenuGroup, type ActionsMenuItem } from './actions-menu';
 import { Button, type ButtonProps } from './button';
 
+/** The button's own action, when its label does something itself and the chevron holds the alternatives. */
+export interface DropdownButtonAction {
+  href?: string;
+  /** Fetch `href` as a file (an installer) instead of navigating to it. */
+  download?: boolean | string;
+  openInNewTab?: boolean;
+  onClick?: React.MouseEventHandler<HTMLButtonElement | HTMLAnchorElement>;
+}
+
 export interface DropdownButtonProps {
   /** Button label rendered next to the chevron. */
   label: React.ReactNode;
+  /**
+   * Makes the label a button of its own (Figma `button-action`): it runs this
+   * action, and the chevron beside it opens the menu of alternatives. Two click
+   * targets on one surface. Without it the whole button opens the menu.
+   */
+  action?: DropdownButtonAction;
+  /** The chevron's accessible name when `action` is set (it has no text of its own). Default: "More options". */
+  menuAriaLabel?: string;
   /** Optional leading icon rendered before the label. */
   icon?: React.ReactNode;
   /**
@@ -55,7 +72,9 @@ export interface DropdownButtonProps {
  * `ActionsMenu`. One component, so the trigger styling, chevron, and menu
  * chrome cannot drift between surfaces.
  *
- * Two trigger looks — BOTH render through the unified `Button`:
+ * With `action`, the label is a button of its own and the chevron alone opens
+ * the menu (two targets, one surface). Otherwise, two trigger looks — BOTH
+ * render through the unified `Button`:
  * - default (no `variant`): the card-colored seam trigger — `Button
  *   variant="outline"` with the chevron in its `splitIcon` slot, so the label
  *   and chevron are separated by a divider, the whole surface is one click
@@ -70,6 +89,8 @@ export interface DropdownButtonProps {
  */
 export function DropdownButton({
   label,
+  action,
+  menuAriaLabel = 'More options',
   icon,
   items,
   groups,
@@ -107,6 +128,57 @@ export function DropdownButton({
 
   const resolvedAriaLabel = ariaLabel || (typeof label === 'string' ? label : undefined);
 
+  // With its own action: two common `Button`s attached into one surface. The
+  // label runs the action, the chevron is the menu's trigger.
+  if (action) {
+    const skin = variant ?? 'outline';
+    return (
+      <div
+        role="group"
+        aria-label={resolvedAriaLabel}
+        className={cn('inline-flex items-stretch', fullWidth && 'w-full', className)}
+      >
+        <Button
+          variant={skin}
+          attach="start"
+          href={action.href}
+          download={action.download}
+          openInNewTab={action.openInNewTab}
+          onClick={action.onClick as React.MouseEventHandler<HTMLButtonElement> | undefined}
+          disabled={disabled}
+          loading={loading}
+          leftIcon={icon}
+          className={fullWidth ? 'flex-1' : undefined}
+        >
+          {label}
+        </Button>
+        <ActionsMenuDropdown
+          groups={groups ?? [{ items: items ?? [] }]}
+          open={open}
+          onOpenChange={handleOpenChange}
+          align={align}
+          side={side}
+          onCloseAutoFocus={onCloseAutoFocus}
+          triggerAriaLabel={menuAriaLabel}
+          customTrigger={
+            <Button
+              type="button"
+              variant={skin}
+              size="icon"
+              attach="end"
+              disabled={disabled || loading}
+              aria-label={menuAriaLabel}
+              className={cn(open && 'bg-ods-bg-hover')}
+              leftIcon={
+                <Chevron02DownIcon className={cn('transition-transform duration-fast', open && 'rotate-180')} />
+              }
+            />
+          }
+        />
+      </div>
+    );
+  }
+
   const trigger = variant ? (
     <Button
       variant={variant}

package/src/components/ui/index.ts

@@ -240,6 +240,9 @@ export * from './product-screen-frame';
 export * from './phone-frame';
 export * from './notification-stack';
 export * from './numbered-step';
+export * from './strip-card';
+export * from './benefit-list';
+export * from './leader-row';
 export * from './device-wallpaper';
 export * from './analyzing-state';
 export * from './incident-feed';

package/src/components/ui/leader-row.tsx

@@ -0,0 +1,28 @@
+import type { ReactNode } from 'react';
+import { cn } from '../../utils/cn';
+
+export interface LeaderRowProps {
+  label: ReactNode;
+  value: ReactNode;
+  /** After the value, at 16px (a check, a warning). */
+  status?: ReactNode;
+  /** The row's element. Default `div`; `li` inside a list. */
+  as?: 'div' | 'li';
+  className?: string;
+}
+
+/**
+ * A label and its value joined by a leader line (Figma `info-card` row): the
+ * quiet label, a hairline that takes the free space, the value, and a status
+ * mark at the end. One line, always: a long value clips.
+ */
+export function LeaderRow({ label, value, status, as: Row = 'div', className }: LeaderRowProps) {
+  return (
+    <Row className={cn('flex min-w-0 items-center gap-[var(--spacing-system-xsf)] text-h4', className)}>
+      <span className="shrink-0 whitespace-nowrap text-ods-text-secondary">{label}</span>
+      <span className="h-px min-w-4 flex-1 bg-ods-border" aria-hidden />
+      <span className="min-w-0 truncate text-ods-text-primary">{value}</span>
+      {status && <span className="flex shrink-0 items-center">{status}</span>}
+    </Row>
+  );
+}

package/src/components/ui/strip-card.tsx

@@ -0,0 +1,68 @@
+import type { ReactNode } from 'react';
+import { cn } from '../../utils/cn';
+
+export interface StripCardProps {
+  /** Before the title, at 24px (an icon, a step's number). */
+  lead?: ReactNode;
+  title: ReactNode;
+  /** One quieter line under the title. */
+  caption?: ReactNode;
+  /** The title's element. Default `h3`. */
+  titleAs?: 'h3' | 'h4' | 'p';
+  /** `roomy` gives the head and the body the larger inset (a card whose head carries a caption). */
+  density?: 'default' | 'roomy';
+  children?: ReactNode;
+  className?: string;
+  bodyClassName?: string;
+}
+
+/**
+ * THE card with a head strip (Figma "Info-card" with a `tag` head): a head on
+ * the card surface holding a mark, a title and an optional caption, a hairline,
+ * then the body on the page surface. One frame for every such card, so a row
+ * of them shares its radius, hairlines and insets.
+ */
+export function StripCard({
+  lead,
+  title,
+  caption,
+  titleAs: Title = 'h3',
+  density = 'default',
+  children,
+  className,
+  bodyClassName,
+}: StripCardProps) {
+  const roomy = density === 'roomy';
+  return (
+    <div
+      className={cn(
+        'flex h-full min-w-0 flex-col overflow-hidden rounded-md border border-ods-border bg-ods-card',
+        className,
+      )}
+    >
+      <div
+        className={cn(
+          'flex items-center gap-[var(--spacing-system-mf)] border-b border-ods-border',
+          roomy ? 'p-[var(--spacing-system-l)]' : 'p-[var(--spacing-system-m)]',
+        )}
+      >
+        {lead && <span className="flex shrink-0 items-center">{lead}</span>}
+        <div className="flex min-w-0 flex-1 flex-col">
+          <Title className="m-0 text-ods-text-primary text-h3">{title}</Title>
+          {caption && <span className="text-ods-text-secondary text-h6">{caption}</span>}
+        </div>
+      </div>
+      <div
+        className={cn(
+          'flex min-w-0 flex-1 flex-col bg-ods-bg',
+          roomy
+            ? 'gap-[var(--spacing-system-l)] p-[var(--spacing-system-l)]'
+            : 'gap-[var(--spacing-system-m)] px-[var(--spacing-system-m)] pb-[var(--spacing-system-l)] pt-[var(--spacing-system-m)]',
+          bodyClassName,
+        )}
+      >
+        {children}
+      </div>
+    </div>
+  );
+}

package/src/contexts/assistant-runtime-context.tsx

@@ -56,11 +56,11 @@ export interface AssistantRuntime {
   source?: string;
   /**
    * GET endpoint the questions are read from:
-   *   `<url>?count=<n>&section=<topic>&exclude=<id,id>` → `{ prompts: AskPrompt[] }`
-   * `section` is ANY string: the host decides what topics exist (the hub: the
-   * `section` attribute of a quick action, set in chat config), so a new topic
-   * needs no change here. Hub: '/api/quick-actions/questions'. Absent: an "ask"
-   * surface shows its launcher with no questions.
+   *   `<url>?count=<n>&topic=<topic>&exclude=<id,id>` → `{ prompts: AskPrompt[] }`
+   * `topic` is ANY string: the host decides what topics exist (the hub: the
+   * topics of its FAQs, set in the FAQ admin), so a new topic needs no change
+   * here. Hub: '/api/faqs/questions'. Absent: an "ask" surface shows its
+   * launcher with no questions.
    */
   askPromptsUrl?: string;
   /**

package/src/types/faq.ts

@@ -1,8 +1,26 @@
+/**
+ * The two kinds of FAQ. An `answer` is a question with its written answer (the
+ * accordion, FAQPage JSON-LD). An `ask` is a question the assistant answers: it
+ * has a `prompt` (what is sent to the chat) and no written answer, and is what
+ * every "ask the assistant" surface offers.
+ */
+export const FAQ_KINDS = ['answer', 'ask'] as const;
+export type FaqKind = (typeof FAQ_KINDS)[number];
+
 export interface Faq {
   id: number;
   question: string;
   answer: string;
   section?: string | null;
+  /** Absent on a host that predates kinds: an `answer`. */
+  kind?: FaqKind;
+  /** An `ask` FAQ's prompt for the chat; null on an `answer`. */
+  prompt?: string | null;
+  /**
+   * The places the FAQ is written for, shared by both kinds: a page's topic
+   * (`pricing`, `careers`, `home`) or a section's. Empty: written for no place.
+   */
+  topics?: string[];
   display_order: number;
   is_active: boolean;
   created_at: string;

package/src/utils/demo-clock.ts

@@ -0,0 +1,62 @@
+/**
+ * Times for a scripted conversation (a product demo, an example card): a
+ * believable time of day for each turn, chosen from a seed.
+ *
+ * The same seed always gives the same times, so a server render and the
+ * browser agree and a card keeps its time on every visit. Turns of one
+ * conversation follow each other: each is the one before it plus a short gap.
+ */
+
+/** A 32-bit hash of the seed (FNV-1a), the generator's starting state. */
+function hashSeed(seed: string): number {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < seed.length; i++) {
+    hash ^= seed.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return hash >>> 0;
+}
+
+/** A seeded generator of numbers in [0, 1) (mulberry32). */
+function seededRandom(seed: string): () => number {
+  let state = hashSeed(seed);
+  return () => {
+    state = (state + 0x6d2b79f5) >>> 0;
+    let t = state;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+export interface DemoClockOptions {
+  /** How many turns to time. Default 2. */
+  count?: number;
+  /** The first turn falls between these hours of the day (24h, end exclusive). Default 8 to 18. */
+  fromHour?: number;
+  toHour?: number;
+  /** The longest gap between two turns, in minutes. Default 3. A gap may be 0: an agent answers within the minute. */
+  maxGapMinutes?: number;
+}
+
+/** Minutes of the day as "2:47 PM". */
+export function formatDemoClock(minutesOfDay: number): string {
+  const minutes = ((Math.floor(minutesOfDay) % 1440) + 1440) % 1440;
+  const hour24 = Math.floor(minutes / 60);
+  const hour12 = hour24 % 12 === 0 ? 12 : hour24 % 12;
+  return `${hour12}:${String(minutes % 60).padStart(2, '0')} ${hour24 < 12 ? 'AM' : 'PM'}`;
+}
+
+/** The time of each turn of one scripted conversation, in order, for `seed`. */
+export function demoClockTimes(seed: string, options: DemoClockOptions = {}): string[] {
+  const { count = 2, fromHour = 8, toHour = 18, maxGapMinutes = 3 } = options;
+  const random = seededRandom(seed);
+  const span = Math.max(1, (toHour - fromHour) * 60);
+  let minutes = fromHour * 60 + Math.floor(random() * span);
+  const times: string[] = [];
+  for (let i = 0; i < Math.max(0, count); i++) {
+    if (i > 0) minutes += Math.floor(random() * (maxGapMinutes + 1));
+    times.push(formatDemoClock(minutes));
+  }
+  return times;
+}

package/src/utils/identity-tint.ts

@@ -0,0 +1,23 @@
+import type { CSSProperties } from 'react';
+
+/**
+ * A surface tinted by an identity colour (an agent's): its border mixed from
+ * the colour, a faint wash of it over the page surface and a glow of it in the
+ * far corner. THE tint of every card and window that belongs to one agent, so
+ * they read as that agent's at a glance and all read alike.
+ *
+ * `accent` is a CSS colour (the hex an agent's identity stores). The surface
+ * under it should be the page surface (`bg-ods-bg`). Undefined gives no style,
+ * so a surface with no agent keeps its own border and background.
+ */
+export function identityTint(accent: string | null | undefined): CSSProperties | undefined {
+  if (!accent) return undefined;
+  const wash = `color-mix(in srgb, ${accent} 2%, transparent)`;
+  return {
+    borderColor: `color-mix(in srgb, ${accent} 30%, transparent)`,
+    backgroundImage: [
+      `radial-gradient(120% 120% at 100% 100%, color-mix(in srgb, ${accent} 4%, transparent), transparent 70%)`,
+      `linear-gradient(${wash}, ${wash})`,
+    ].join(', '),
+  };
+}

package/src/utils/index.ts

@@ -473,3 +473,5 @@ export type { ProgramDateFields, ProgramInstant, ProgramMetaRenderers } from './
 export { copyrightLine } from './copyright-line';
 export * from './path-pattern';
 export * from './random-id';
+export * from './demo-clock';
+export * from './identity-tint';