@flamingo-stack/openframe-frontend-core 0.0.718 → 0.0.720

package/src/components/chat/hooks/index.ts

@@ -39,3 +39,15 @@ export * from './use-embedded-chat';
 // `ChatRuntime.endpoints`, so hub vs. embedders share one image-proxy
 // resolver.
 export * from './use-proxied-image-url';
+export {
+  ASK_PROMPTS_DEFAULT_COUNT,
+  assistantAvailable,
+  buildAskPromptsUrl,
+  useAskPrompts,
+  useAssistantOpen,
+  useShownAskPromptIds,
+  useShownAskPrompts,
+  type AskPromptsResponse,
+  type UseAskPromptsOptions,
+  type UseAskPromptsResult,
+} from './use-ask-prompts';

package/src/components/chat/hooks/use-ask-prompts.ts

@@ -0,0 +1,188 @@
+'use client';
+
+import { useCallback, useId, useLayoutEffect, useSyncExternalStore } from 'react';
+import {
+  useAssistantRuntime,
+  type AssistantOpenRequest,
+  type AssistantRuntime,
+} from '../../../contexts/assistant-runtime-context';
+import { useSelfFetch } from '../../../hooks/use-self-fetch';
+import { openAskAi } from '../../navigation/mingo-ai-button';
+import type { AskPrompt } from '../ask-prompts';
+
+/** The answer of a host's questions endpoint (`AssistantRuntime.askPromptsUrl`). */
+export interface AskPromptsResponse {
+  prompts: AskPrompt[];
+}
+
+/** How many questions an "ask" surface offers when nothing states a number. */
+export const ASK_PROMPTS_DEFAULT_COUNT = 3;
+
+/** The questions URL: the host's endpoint with the surface's count, topic and exclusions. */
+export function buildAskPromptsUrl(
+  base: string,
+  { count, topic, exclude = [] }: { count: number; topic?: string; exclude?: readonly string[] },
+): string {
+  const params = new URLSearchParams({ count: String(count) });
+  if (topic) params.set('section', topic);
+  if (exclude.length > 0) params.set('exclude', exclude.join(','));
+  return `${base}${base.includes('?') ? '&' : '?'}${params.toString()}`;
+}
+
+/** An "ask" surface has something to open: a runtime is mounted and its chat is there. */
+export function assistantAvailable(assistant: AssistantRuntime | null): assistant is AssistantRuntime {
+  return !!assistant?.available;
+}
+
+export interface UseAskPromptsOptions {
+  /**
+   * What the surface is about: ANY string the host's endpoint knows (sent as
+   * `section`). Questions written for it are picked first. Absent: general ones.
+   */
+  topic?: string;
+  count?: number;
+  /** Ids of questions never to pick (the ones the page already shows). */
+  exclude?: readonly string[];
+  /** False: nothing is fetched yet (the surface is not ready to pick). Default true. */
+  enabled?: boolean;
+}
+
+export interface UseAskPromptsResult {
+  prompts: AskPrompt[];
+  /** True until the pick has landed (or failed). False where nothing is fetched. */
+  isLoading: boolean;
+  /** The host has a questions endpoint and a chat to ask: questions can exist here. */
+  supported: boolean;
+}
+
+/**
+ * The questions an "ask" surface offers, picked by the HOST for this visit
+ * (`AssistantRuntime.askPromptsUrl`). One pick per mount: read once, never
+ * cached, so a visitor keeps the same questions while the page is open and
+ * gets a new pick next time. A failed read leaves the list empty. No chat, or
+ * no endpoint: nothing is fetched and the list is empty.
+ */
+export function useAskPrompts({
+  topic,
+  count = ASK_PROMPTS_DEFAULT_COUNT,
+  exclude,
+  enabled = true,
+}: UseAskPromptsOptions = {}): UseAskPromptsResult {
+  const assistant = useAssistantRuntime();
+  const base = assistantAvailable(assistant) ? assistant.askPromptsUrl : undefined;
+  const url = base && enabled ? buildAskPromptsUrl(base, { count, topic, exclude }) : null;
+  const { data, isLoading } = useSelfFetch<AskPromptsResponse>(url);
+  return { prompts: data?.prompts ?? [], isLoading: !!base && (!enabled || isLoading), supported: !!base };
+}
+
+/**
+ * How an "ask" surface opens the chat and asks it: its own `onOpen`, else the
+ * nearest assistant runtime's `open`, else the `ask-ai:open` event of the
+ * runtime's source (the mounted `EmbeddableChat`). The surface's topic rides
+ * every request, so a host with several chats can tell them apart.
+ */
+export function useAssistantOpen(
+  topic?: string,
+  onOpen?: (request: AssistantOpenRequest) => void,
+): (request: { prompt?: string }) => void {
+  const assistant = useAssistantRuntime();
+  const runtimeOpen = assistant?.open;
+  const source = assistant?.source;
+  return useCallback(
+    (request: { prompt?: string }) => {
+      const full: AssistantOpenRequest = { ...request, topic };
+      if (onOpen) onOpen(full);
+      else if (runtimeOpen) runtimeOpen(full);
+      else openAskAi(source, request);
+    },
+    [onOpen, runtimeOpen, source, topic],
+  );
+}
+
+// ─── The questions the page already shows ────────────────────────────────────
+// Every surface that shows questions says which ones (`useShownAskPrompts`), so
+// a later surface (the FAQ's card) never repeats one, with no wiring by the
+// host. One list per QUESTIONS ENDPOINT (the runtime's `askPromptsUrl`): two
+// assistants on one page read different questions, and never leave out each
+// other's ids. A module store, read through React's external-store hook.
+// `null` for a surface = it is still picking.
+
+const NO_IDS: readonly string[] = [];
+
+/** One endpoint's list: which questions each surface shows, and who is listening. */
+interface ShownList {
+  set(surface: string, ids: readonly string[] | null): void;
+  remove(surface: string): void;
+  subscribe(listener: () => void): () => void;
+  read(): readonly string[] | null;
+}
+
+function createShownList(): ShownList {
+  const bySurface = new Map<string, readonly string[] | null>();
+  const listeners = new Set<() => void>();
+  let snapshot: readonly string[] | null = NO_IDS;
+  const publish = (): void => {
+    const lists = [...bySurface.values()];
+    const next = lists.some(list => list === null) ? null : lists.flatMap(list => list ?? []);
+    const same = next === null ? snapshot === null : snapshot !== null && next.join(',') === snapshot.join(',');
+    if (same) return;
+    snapshot = next === null ? null : next.length > 0 ? next : NO_IDS;
+    for (const listener of listeners) listener();
+  };
+  return {
+    set(surface, ids) {
+      bySurface.set(surface, ids);
+      publish();
+    },
+    remove(surface) {
+      bySurface.delete(surface);
+      publish();
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    read: () => snapshot,
+  };
+}
+
+const shownLists = new Map<string, ShownList>();
+
+/** The list a surface belongs to: the questions endpoint of its assistant runtime. */
+function useShownList(): ShownList {
+  const scope = useAssistantRuntime()?.askPromptsUrl ?? '';
+  let list = shownLists.get(scope);
+  if (!list) {
+    list = createShownList();
+    shownLists.set(scope, list);
+  }
+  return list;
+}
+
+/**
+ * Say which questions this surface shows. `null`: it is still picking, so a
+ * surface that must not repeat them waits. Pass `undefined` to say nothing
+ * (the surface shows no questions here).
+ */
+export function useShownAskPrompts(ids: readonly string[] | null | undefined): void {
+  const surface = useId();
+  const list = useShownList();
+  const key = ids === undefined ? undefined : ids === null ? null : ids.join(',');
+  // A layout effect: the list holds this surface before any reader's own effects run.
+  useLayoutEffect(() => {
+    if (key === undefined) return undefined;
+    list.set(surface, key === null ? null : key ? key.split(',') : NO_IDS);
+    return () => list.remove(surface);
+  }, [list, surface, key]);
+}
+
+/** The ids of the questions the page's other surfaces of the same assistant show; `null` while one is still picking. */
+export function useShownAskPromptIds(): readonly string[] | null {
+  const list = useShownList();
+  return useSyncExternalStore(list.subscribe, list.read, () => NO_IDS);
+}
+
+/** Tests only: forget every surface. */
+export function resetShownAskPrompts(): void {
+  shownLists.clear();
+}

package/src/components/chat/index.ts

@@ -24,6 +24,7 @@ export * from './chat-message-skeleton';
 
 export * from './quick-action-chip';
 export * from './ask-prompts';
+export * from './assistant-ask-prompts';
 export * from './quick-action-marquee';
 export * from './quick-action-wall';
 export * from './chat-ticket-list';

package/src/components/chat/utils/icon-library.tsx

@@ -91,6 +91,11 @@ const OpenmspLogoIcon: IconComponent = ({ size = 16, className }) => (
   />
 );
 const FlamingoLogoIcon = sizedLogo(FlamingoLogo);
+// The same mark as a GLYPH: it takes the colour of the slot it sits in, like every icon beside it (a source
+// chip, a command row, a card), where the brand pink would be the one coloured icon in the list.
+const FlamingoLogoGreyIcon: IconComponent = ({ size = 16, className, color }) => (
+  <FlamingoLogo className={className} fill={color ?? 'currentColor'} style={{ width: size, height: size }} />
+);
 // The two community marks size themselves through a `size` prop, the resolver's own contract.
 // Major League GitHub draws its mark in the theme's text colour on its own site
 // (its header, hero and footer), never in an accent: so does every glyph of it.
@@ -174,6 +179,7 @@ export const ICON_ALIASES: Record<string, IconComponent> = {
   'tmcg-logo': TmcgLogoIcon,
   flamingo: FlamingoLogoIcon,
   'flamingo-logo': FlamingoLogoIcon,
+  'flamingo-logo-grey': FlamingoLogoGreyIcon,
   megaphone: Megaphone,
   bell: Bell,
   info: Info,

package/src/components/faq/faq-ask-card.tsx

@@ -0,0 +1,115 @@
+'use client';
+
+import { useMemo, useState } from 'react';
+import {
+  AssistantRuntimeContext,
+  useAssistantRuntime,
+  type AssistantOpenRequest,
+  type AssistantRuntime,
+} from '../../contexts/assistant-runtime-context';
+import { useInView } from '../../hooks/ui/use-in-view';
+import { AskCard } from '../chat/ask-prompts';
+import {
+  assistantAvailable,
+  ASK_PROMPTS_DEFAULT_COUNT,
+  useAskPrompts,
+  useAssistantOpen,
+  useShownAskPromptIds,
+} from '../chat/hooks/use-ask-prompts';
+
+/** The card beside a FAQ, as a host may shape it. Every field is optional. */
+export interface FaqAskOptions {
+  /**
+   * What this FAQ is about: ANY string the host's questions endpoint knows (it
+   * is sent as `section`, and reported with every click). Questions written
+   * for the topic are picked first. Whoever renders the FAQ passes it. Absent:
+   * the entity the FAQ is attached to (`FaqSection`'s `entityType`). With
+   * neither, the FAQ has no card: the lib names no topic of its own.
+   */
+  topic?: string;
+  /**
+   * Ids of questions never to offer. Absent: the ones the page's other "ask"
+   * surfaces show (`AssistantAskPrompts` rows say so themselves), which the
+   * card waits for. `null`: wait.
+   */
+  exclude?: readonly string[] | null;
+  /** How many questions the card offers. Absent: the runtime's, else three. */
+  count?: number;
+  /** The card's wording. `{assistant}` is replaced by the assistant's name. Absent: the runtime's, else the lib's. */
+  title?: string;
+  description?: string;
+  /**
+   * How the chat is opened and asked from THIS card. Absent: the assistant
+   * runtime's `open`, else the `ask-ai:open` event of its source. A FAQ that
+   * sits beside its own chat (an embedded one) passes that chat's opener.
+   */
+  onOpen?: (request: AssistantOpenRequest) => void;
+}
+
+/** The lib's own wording, when neither the host nor the runtime states it. */
+const DEFAULT_ASK_CARD = {
+  title: 'Still deciding?',
+  description: '{assistant} answers from our docs and customer stories.',
+} as const;
+
+/** How far below the viewport the card is when it picks its questions. */
+const PICK_ROOT_MARGIN = '600px';
+
+const fillAssistant = (text: string, name: string) => text.split('{assistant}').join(name);
+
+/** True when a FAQ under this runtime shows the card: a chat to open, and a name for the card's words. */
+export function faqAskCardShown(assistant: AssistantRuntime | null): assistant is AssistantRuntime {
+  return assistantAvailable(assistant) && !!assistant.name;
+}
+
+/**
+ * The "ask the assistant" card of a FAQ: the assistant's identity and the
+ * chat's opener from the nearest assistant runtime, its questions from the
+ * host's endpoint. It picks ONCE, when the card first comes near the viewport:
+ * by then the page above has said which questions it shows itself, and a
+ * visitor who never reaches the FAQ costs no request. The card is the same
+ * height before and after the questions arrive. A host with no questions
+ * endpoint gets the launcher with no questions.
+ */
+export function FaqAskCard({ topic, exclude, count, title, description, onOpen }: FaqAskOptions & { topic: string }) {
+  const assistant = useAssistantRuntime();
+  const { ref, inView } = useInView<HTMLDivElement>({ rootMargin: PICK_ROOT_MARGIN });
+  const [reached, setReached] = useState(false);
+  if (inView && !reached) setReached(true);
+
+  const shownElsewhere = useShownAskPromptIds();
+  const excluded = exclude === undefined ? shownElsewhere : exclude;
+  const slots = count ?? assistant?.askCard?.count ?? ASK_PROMPTS_DEFAULT_COUNT;
+  const { prompts, isLoading, supported } = useAskPrompts({
+    topic,
+    count: slots,
+    exclude: excluded ?? undefined,
+    enabled: reached && excluded !== null,
+  });
+  const open = useAssistantOpen(topic, onOpen);
+  // The card's launcher opens the same chat as its questions, with the card's topic: it reads the runtime.
+  const scoped = useMemo(() => (assistant ? { ...assistant, open } : null), [assistant, open]);
+
+  if (!faqAskCardShown(assistant) || !assistant.name) return null;
+  const name = assistant.name;
+  const cardDescription = description ?? assistant.askCard?.description ?? DEFAULT_ASK_CARD.description;
+  return (
+    <AssistantRuntimeContext.Provider value={scoped}>
+      <div ref={ref}>
+        <AskCard
+          title={fillAssistant(title ?? assistant.askCard?.title ?? DEFAULT_ASK_CARD.title, name)}
+          description={cardDescription ? fillAssistant(cardDescription, name) : undefined}
+          prompts={prompts}
+          // Fixed slots, one question per row: chip skeletons until the pick lands, the same box after.
+          count={supported ? slots : 0}
+          loading={isLoading}
+          source={assistant.source}
+          label={name}
+          icon={assistant.icon}
+          onOpen={open}
+          onAsk={prompt => assistant.onAsk?.({ promptId: prompt.id, topic })}
+        />
+      </div>
+    </AssistantRuntimeContext.Provider>
+  );
+}

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

@@ -23,7 +23,7 @@
 import { useRouter } from '../../embed-shims/next-navigation';
 import type { Faq } from '../../types/faq';
 import { PageShell, PageLayout } from '../ui';
-import { FaqSection } from './faq-section';
+import { FaqSection, type FaqSectionProps } from './faq-section';
 import type { FaqSchemaOptions } from './json-ld';
 
 export interface FaqDocumentPageProps {
@@ -54,6 +54,9 @@ export interface FaqDocumentPageProps {
   entityId?: number | string;
   /** Minimum FAQ count before the section renders (forwarded to `FaqSection`). */
   minResults?: number;
+  /** The "ask the assistant" card beside the questions (forwarded to `FaqSection`): `false` switches it off, an
+   *  object states its topic, wording and the chat it opens. */
+  ask?: FaqSectionProps['ask'];
 }
 
 export function FaqDocumentPage({
@@ -67,6 +70,7 @@ export function FaqDocumentPage({
   entityType,
   entityId,
   minResults,
+  ask,
   shell = true,
 }: FaqDocumentPageProps) {
   const router = useRouter();
@@ -93,6 +97,7 @@ export function FaqDocumentPage({
         entityType={entityType}
         entityId={entityId}
         minResults={minResults}
+        ask={ask}
       />
     </PageLayout>
   );

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

@@ -2,6 +2,7 @@
 
 import type React from 'react';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useAssistantRuntime } from '../../contexts/assistant-runtime-context';
 import Link from '../../embed-shims/next-link';
 import { useScrollToHash } from '../../hooks/use-scroll-to-hash';
 import { useSelfFetch } from '../../hooks/use-self-fetch';
@@ -13,6 +14,7 @@ import { navigateSamePageHash, STICKY_HEADER_OFFSET_PX } from '../../utils/same-
 import { buildSuggestionUrl } from '../../utils/suggestion-url';
 import { FaqAccordion, type FaqItem } from '../faq-accordion';
 import { SECTION_HEADING_CLASS } from '../layout/page-heading';
+import { FaqAskCard, faqAskCardShown, type FaqAskOptions } from './faq-ask-card';
 import { buildFaqJsonLdFromFaqs, type FaqSchemaOptions } from './json-ld';
 
 export interface FaqSectionProps {
@@ -48,12 +50,24 @@ export interface FaqSectionProps {
    *  ('' = same-origin relative). */
   apiBaseUrl?: string;
   /**
-   * A block beside the questions (an "ask the assistant" card). From the
-   * content `lg` step the heading, the category nav and this block form a left
-   * column and the questions the right one; below it the block follows the
-   * questions. Absent: the single-column layout, unchanged.
+   * A block beside the questions, in place of the "ask the assistant" card.
+   * From the content `lg` step the heading, the category nav and this block
+   * form a left column and the questions the right one; below it the block
+   * follows the questions.
    */
   aside?: React.ReactNode;
+  /**
+   * 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
+   * also states the questions to leave out, the wording and the chat it opens
+   * (`onOpen`). An `aside` takes the card's place.
+   */
+  ask?: false | FaqAskOptions;
 }
 
 const DEFAULT_HEADING_TEXT = 'Frequently Asked Questions';
@@ -392,8 +406,16 @@ export function FaqSection({
   className,
   minResults,
   apiBaseUrl = '',
-  aside,
+  aside: asideProp,
+  ask,
 }: FaqSectionProps) {
+  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 aside =
+    asideProp ??
+    (ask !== false && askTopic && faqAskCardShown(assistant) ? <FaqAskCard {...ask} topic={askTopic} /> : undefined);
   const url = buildFaqsUrl(entityType, entityId, minResults, apiBaseUrl);
   // Memoized — useSelfFetch re-syncs on [initialData]; a fresh per-render
   // wrapper object would setState-loop under re-rendering parents.

package/src/components/faq/index.ts

@@ -11,3 +11,4 @@
 // block and exposed via "./components/faq/json-ld" in package.json#exports.)
 export { FaqSection, type FaqSectionProps } from './faq-section';
 export { FaqDocumentPage, type FaqDocumentPageProps } from './faq-document-page';
+export { FaqAskCard, type FaqAskOptions } from './faq-ask-card';

package/src/components/features/auth/auth-benefits-panel.tsx

@@ -2,6 +2,7 @@
 
 import type { ReactNode } from 'react';
 import { cn } from '../../../utils/cn';
+import { TRIAL_LABELS } from '../../../utils/trial';
 import { OpenFrameLogo } from '../../icons';
 import { FileOffIcon } from '../../icons-v2-generated/documents/file-off-icon';
 import { CreditCardXmarkIcon } from '../../icons-v2-generated/finance/credit-card-xmark-icon';
@@ -29,10 +30,10 @@ const DEFAULT_DESCRIPTION =
   'All your core ops in one place - built for MSPs who are done duct-taping tools together. Unified stack, AI-ready, no vendor tax. Just solid software that lets you run lean and fast.';
 
 const DEFAULT_BENEFITS: AuthBenefit[] = [
-  { icon: <CreditCardXmarkIcon />, label: 'No card required' },
-  { icon: <XmarkAltIcon />, label: 'Cancel Anytime' },
-  { icon: <FlaskVialIcon />, label: '14 day free trial' },
-  { icon: <FileOffIcon />, label: 'No Contract' },
+  { icon: <CreditCardXmarkIcon />, label: TRIAL_LABELS.noCard },
+  { icon: <XmarkAltIcon />, label: TRIAL_LABELS.cancel },
+  { icon: <FlaskVialIcon />, label: TRIAL_LABELS.length },
+  { icon: <FileOffIcon />, label: TRIAL_LABELS.noContract },
 ];
 
 /**