@flamingo-stack/openframe-frontend-core 0.0.777 → 0.0.781

package/src/components/chat/msp-organization-card.tsx

@@ -4,7 +4,9 @@ import type { ReactNode } from 'react';
 import Link from '../../embed-shims/next-link';
 import { cn } from '../../utils/cn';
 import { ExternalLinkIcon } from '../icons-v2-generated';
+import { TextLineSkeleton } from '../loading/unified-skeleton';
 import { Button } from '../ui/button';
+import { InertWhileLoading, useLoadingScope } from '../ui/loading-scope';
 import { SquareAvatar } from '../ui/square-avatar';
 
 export interface MspOrganizationCardProps {
@@ -29,10 +31,24 @@ export interface MspOrganizationCardProps {
    * "Your IT is managed by" over the name, no website line, no card chrome.
    */
   variant?: 'card' | 'footer';
+  /** The organization is still loading: the card draws its own skeleton (either variant). Inside a `LoadingScope` it
+   *  does so whatever this says. */
+  loading?: boolean;
   /** Appended to the root element. */
   className?: string;
 }
 
+/** The card's layout per variant, loaded and loading. */
+// Inset ring (box-shadow) instead of `border` so the 1px stroke does not add to the box height — matches Figma's
+// 80px frame (16 + 48 + 16) with its inside-aligned stroke. A real border would render 82px.
+const CARD_FRAME_CLASS =
+  'flex items-start gap-[var(--spacing-system-m)] rounded-md bg-ods-bg p-[var(--spacing-system-m)] ring-1 ring-inset ring-ods-border';
+const FOOTER_FRAME_CLASS =
+  'flex items-center gap-[var(--spacing-system-s)] px-[var(--spacing-system-m)] py-[var(--spacing-system-s)]';
+const TEXT_STACK_CLASS = 'flex min-w-0 flex-1 flex-col';
+const FOOTER_CAPTION = 'Your IT is managed by';
+const FOOTER_CAPTION_CLASS = 'truncate text-ods-text-secondary text-h6';
+
 /**
  * MSP Organization card for the AI Assistant welcome screen.
  *
@@ -43,6 +59,10 @@ export interface MspOrganizationCardProps {
  *
  * The trailing button renders only when `href` or `onOpenWebsite` is provided:
  * `href` becomes an anchor (new tab), otherwise `onOpenWebsite` fires on click.
+ *
+ * ONE switch (`useLoadingScope() || loading`): while the organization is read the SAME card (either variant) draws
+ * the logo in its loading form and its read text as bars (the footer's static caption stays real), and its link button
+ * real and inert.
  */
 export function MspOrganizationCard({
   name,
@@ -52,66 +72,64 @@ export function MspOrganizationCard({
   href,
   onOpenWebsite,
   variant = 'card',
+  loading: loadingProp = false,
   className,
 }: MspOrganizationCardProps) {
+  const loading = useLoadingScope() || loadingProp;
   const actionLabel = website ? `Open ${website}` : 'Open organization website';
+  const footer = variant === 'footer';
+  const buttonSize = footer ? 'icon-sm' : 'icon';
+
+  const action = href ? (
+    <Button asChild variant="outline" size={buttonSize} aria-label={actionLabel}>
+      <Link href={href} target="_blank" rel="noreferrer noopener">
+        <ExternalLinkIcon />
+      </Link>
+    </Button>
+  ) : onOpenWebsite ? (
+    <Button variant="outline" size={buttonSize} aria-label={actionLabel} onClick={onOpenWebsite}>
+      <ExternalLinkIcon />
+    </Button>
+  ) : null;
+  // The link button is static: drawn real while loading, inert.
+  const trailing = action && loading ? <InertWhileLoading>{action}</InertWhileLoading> : action;
 
-  if (variant === 'footer') {
+  if (footer) {
     return (
-      <div
-        className={cn(
-          'flex items-center gap-[var(--spacing-system-s)] px-[var(--spacing-system-m)] py-[var(--spacing-system-s)]',
-          className,
-        )}
-      >
-        <SquareAvatar src={logoUrl} alt={name} fallback={name} size="sm" variant="square" />
-        <div className="flex min-w-0 flex-1 flex-col">
-          <span className="truncate text-ods-text-secondary text-h6">Your IT is managed by</span>
-          <span className="truncate text-ods-text-primary text-h4">{title ?? name}</span>
+      <div className={cn(FOOTER_FRAME_CLASS, className)}>
+        <SquareAvatar loading={loading} src={logoUrl} alt={name} fallback={name} size="sm" variant="square" />
+        <div className={TEXT_STACK_CLASS}>
+          <span className={FOOTER_CAPTION_CLASS}>{FOOTER_CAPTION}</span>
+          {loading ? (
+            <TextLineSkeleton type="h4" className="w-3/5" />
+          ) : (
+            <span className="truncate text-ods-text-primary text-h4">{title ?? name}</span>
+          )}
         </div>
-        {href ? (
-          <Button asChild variant="outline" size="icon-sm" aria-label={actionLabel}>
-            <Link href={href} target="_blank" rel="noreferrer noopener">
-              <ExternalLinkIcon />
-            </Link>
-          </Button>
-        ) : onOpenWebsite ? (
-          <Button variant="outline" size="icon-sm" aria-label={actionLabel} onClick={onOpenWebsite}>
-            <ExternalLinkIcon />
-          </Button>
-        ) : null}
+        {trailing}
       </div>
     );
   }
 
   return (
-    <div
-      className={cn(
-        // Inset ring (box-shadow) instead of `border` so the 1px stroke does not
-        // add to the box height — matches Figma's 80px frame (16 + 48 + 16) with
-        // its inside-aligned stroke. A real border would render 82px.
-        'flex items-start gap-[var(--spacing-system-m)] rounded-md bg-ods-bg p-[var(--spacing-system-m)] ring-1 ring-inset ring-ods-border',
-        className,
-      )}
-    >
-      <SquareAvatar src={logoUrl} alt={name} fallback={name} size="lg" variant="square" />
+    <div className={cn(CARD_FRAME_CLASS, className)}>
+      <SquareAvatar loading={loading} src={logoUrl} alt={name} fallback={name} size="lg" variant="square" />
 
-      <div className="flex min-w-0 flex-1 flex-col">
-        <span className="truncate text-ods-text-primary text-h3">{title ?? `Your IT is managed by ${name}`}</span>
-        {website ? <span className="truncate text-ods-text-secondary text-h4">{website}</span> : null}
+      <div className={TEXT_STACK_CLASS}>
+        {loading ? (
+          <>
+            <TextLineSkeleton type="h3" className="w-3/5" />
+            <TextLineSkeleton type="h4" className="w-2/5" />
+          </>
+        ) : (
+          <>
+            <span className="truncate text-ods-text-primary text-h3">{title ?? `Your IT is managed by ${name}`}</span>
+            {website ? <span className="truncate text-ods-text-secondary text-h4">{website}</span> : null}
+          </>
+        )}
       </div>
 
-      {href ? (
-        <Button asChild variant="outline" size="icon" aria-label={actionLabel}>
-          <Link href={href} target="_blank" rel="noreferrer noopener">
-            <ExternalLinkIcon />
-          </Link>
-        </Button>
-      ) : onOpenWebsite ? (
-        <Button variant="outline" size="icon" aria-label={actionLabel} onClick={onOpenWebsite}>
-          <ExternalLinkIcon />
-        </Button>
-      ) : null}
+      {trailing}
     </div>
   );
 }

package/src/components/chat/quick-action-chip.tsx

@@ -4,6 +4,8 @@ import { type ReactNode, isValidElement } from 'react';
 import { cn } from '../../utils/cn';
 import { EntityIcon, type EntityIconValue } from '../icon-display';
 import { UnifiedSkeleton } from '../loading/unified-skeleton';
+import { Button } from '../ui/button';
+import { loadingItemProps, useLoadingScope } from '../ui/loading-scope';
 import { Tag } from '../ui/tag';
 
 // =============================================================================
@@ -181,13 +183,20 @@ export interface QuickActionChipButtonProps {
    *  strips, table cells). Default `true`. */
   interactive?: boolean;
   className?: string;
+  /** The chip's label is still being read: the chip draws its {@link QuickActionChipSkeleton} (same box). In a loading
+   *  scope it does the same. */
+  loading?: boolean;
+  /** While loading, the label placeholder's width in `ch` (see {@link QuickActionChipSkeletonProps.labelCh}). */
+  labelCh?: number;
+  /** The list's markers (`data-loading-item`), forwarded in both forms. */
+  [marker: `data-${string}`]: unknown;
 }
 
 // =============================================================================
 // Skeleton
 // =============================================================================
 
-export interface QuickActionChipSkeletonProps {
+interface QuickActionChipSkeletonProps {
   /** Label placeholder width in `ch` of the chip's own font — vary per item
    *  for a realistic spread. Default 16. */
   labelCh?: number;
@@ -200,6 +209,8 @@ export interface QuickActionChipSkeletonProps {
   /** `'question'`: the placeholder of a `variant="question"` chip (its height and padding). */
   variant?: 'outline' | 'question';
   className?: string;
+  /** The list's markers (`data-loading-item`), forwarded like the loaded chip's. */
+  [marker: `data-${string}`]: unknown;
 }
 
 /**
@@ -210,17 +221,19 @@ export interface QuickActionChipSkeletonProps {
  * construction. Use anywhere quick actions stream in (chat empty states,
  * marketing walls, deck panels).
  */
-export function QuickActionChipSkeleton({
+function QuickActionChipSkeleton({
   labelCh = 16,
   icon = true,
   lozenge = false,
   size = 'default',
   variant = 'outline',
   className,
+  ...props
 }: QuickActionChipSkeletonProps) {
   const question = variant === 'question';
   return (
     <Tag
+      {...loadingItemProps(props)}
       variant="outline"
       size={question ? 'sentence' : size}
       className={cn(question && 'max-w-full', className)}
@@ -272,7 +285,25 @@ export function QuickActionChipButton({
   onHoverEnd,
   interactive = true,
   className,
+  loading: loadingProp = false,
+  labelCh,
+  ...props
 }: QuickActionChipButtonProps) {
+  // ONE switch: in a page's loading state, or while the host reads the label, the chip is its skeleton (same box).
+  const loading = useLoadingScope() || loadingProp;
+  const markers = loadingItemProps(props);
+  if (loading)
+    return (
+      <QuickActionChipSkeleton
+        {...markers}
+        labelCh={labelCh}
+        icon={icon != null}
+        lozenge={!!lozenge}
+        size={size}
+        variant={variant === 'question' ? 'question' : 'outline'}
+        className={className}
+      />
+    );
   // The theme's accent only fills the gap — an icon spec's own accent
   // (admin-configured per-action color) always wins.
   const themedIcon = theme && isQuickActionIconSpec(icon) && !icon.accent ? { ...icon, accent: theme.accent } : icon;
@@ -289,10 +320,21 @@ export function QuickActionChipButton({
       : variant;
   const tagSize = question ? 'sentence' : size;
   if (!interactive) {
-    return <Tag variant={tagVariant} size={tagSize} icon={resolvedIcon} label={resolvedLabel} className={className} />;
+    return (
+      <Tag
+        {...markers}
+        variant={tagVariant}
+        size={tagSize}
+        icon={resolvedIcon}
+        label={resolvedLabel}
+        className={className}
+      />
+    );
   }
   return (
-    <button
+    <Button
+      variant="card"
+      {...markers}
       type="button"
       onClick={onSelect}
       onMouseEnter={onHoverStart}
@@ -301,9 +343,8 @@ export function QuickActionChipButton({
       onBlur={onHoverEnd}
       aria-pressed={selected || undefined}
       className={cn(
-        'rounded-md focus:outline-none focus-visible:ring-2 focus-visible:ring-ods-accent',
         // A question may be longer than a narrow column: it shrinks and clips there, read from its start.
-        question ? 'min-w-0 max-w-full text-left' : 'shrink-0',
+        question ? 'w-auto min-w-0 max-w-full' : 'w-auto shrink-0',
         className,
       )}
     >
@@ -314,7 +355,7 @@ export function QuickActionChipButton({
         label={resolvedLabel}
         className={question ? 'max-w-full' : undefined}
       />
-    </button>
+    </Button>
   );
 }
 
@@ -370,15 +411,19 @@ export function QuickActionChipFromData({
   defaultLozenge,
   interactive = true,
   className,
+  ...props
 }: {
   chip: QuickActionChip;
   defaultTheme?: QuickActionThemeSpec;
   defaultLozenge?: boolean;
   interactive?: boolean;
   className?: string;
+  /** The list's markers (`data-loading-item`), forwarded to the chip. */
+  [marker: `data-${string}`]: unknown;
 }) {
   return (
     <QuickActionChipButton
+      {...loadingItemProps(props)}
       label={chip.label}
       icon={chip.icon}
       theme={chip.theme ?? defaultTheme}

package/src/components/chat/quick-action-wall.tsx

@@ -2,6 +2,7 @@
 
 import { useRef, useState, useEffect, useMemo } from 'react';
 import { cn } from '../../utils/cn';
+import { LoadingItems, useLoadingScope } from '../ui/loading-scope';
 import {
   MarqueeWall,
   MarqueeWallFades,
@@ -10,7 +11,7 @@ import {
   type MarqueeWallProps,
 } from '../ui/marquee-wall';
 import {
-  QuickActionChipSkeleton,
+  QuickActionChipButton,
   QuickActionChipFromData,
   type QuickActionThemeSpec,
   type QuickActionChip,
@@ -26,6 +27,10 @@ import {
  *  the loaded state — zero height jump when data lands). */
 export const WALL_SKELETON_LABEL_CH = [17, 24, 14, 20, 15, 25, 12, 21, 16, 19, 13, 23];
 
+/** Skeleton chips a loading wall draws when its host names none: a wall has no page size, and 24 overflow the
+ *  typical caps at any width (the loaded wall's fill and fade). */
+const QUICK_ACTION_WALL_SKELETON_CHIPS = 24;
+
 /** Deterministic index-alternating merge — the mixed "one stream" pile
  *  (deck slide 3's IT+SEC blend and its Storybook mirror). Input order
  *  stable → the blend never reshuffles across renders or consumers. */
@@ -135,8 +140,8 @@ export interface QuickActionWallProps {
    * the cap at `rows`. Optional — decorative/marketing walls omit it.
    */
   agentSlug?: string;
-  /** Draw skeleton chips instead of `chips` (the shared
-   *  {@link QuickActionChipSkeleton} — 1:1 geometry with loaded chips).
+  /** Draw the chips' own loading form instead of `chips` (`QuickActionChipButton loading`, 1:1 geometry with loaded
+   *  chips), `skeletonCount` of them.
    *  Callers own the policy (`loading` flag vs skeleton-when-empty). */
   loading?: boolean;
   skeletonCount?: number;
@@ -186,12 +191,14 @@ export function QuickActionWall({
   minChips,
   rows,
   agentSlug,
-  loading = false,
-  skeletonCount = 24,
+  loading: loadingProp = false,
+  skeletonCount = QUICK_ACTION_WALL_SKELETON_CHIPS,
   className,
   contentClassName,
   sync,
 }: QuickActionWallProps) {
+  // ONE switch: in a page's loading state (or while the host reads the chips) the wall draws skeleton chips.
+  const loading = useLoadingScope() || loadingProp;
   // Adapt the per-row pad target to the actual geometry (brick mode only): a
   // narrow chat composer needs only a handful of repeats to overflow, a wide
   // wall needs many, and a tiny chip needs more repeats than a wide one. We
@@ -240,14 +247,22 @@ export function QuickActionWall({
     ).flat();
   }, [chips, padTarget]);
 
-  const renderSkeletons = (count: number, offset = 0) =>
-    Array.from({ length: count }, (_, i) => (
-      <QuickActionChipSkeleton
-        key={i}
-        lozenge={lozenges}
-        labelCh={WALL_SKELETON_LABEL_CH[(offset + i) % WALL_SKELETON_LABEL_CH.length]}
-      />
-    ));
+  // The chips while the wall is read: each chip's own loading form (it switches itself), `icon` reserving its slot
+  // because most wall chips carry one, labels cycled through the declared width spread.
+  const renderSkeletons = (count: number, offset = 0) => (
+    <LoadingItems count={count}>
+      {i => (
+        <QuickActionChipButton
+          loading
+          label=""
+          icon
+          lozenge={lozenges}
+          labelCh={WALL_SKELETON_LABEL_CH[(offset + i) % WALL_SKELETON_LABEL_CH.length]}
+          data-loading-item
+        />
+      )}
+    </LoadingItems>
+  );
 
   const renderChipNodes = (list: ReadonlyArray<QuickActionChip>) =>
     list.map(chip => (
@@ -258,6 +273,7 @@ export function QuickActionWall({
         defaultLozenge={lozenges}
         interactive={!!chip.onSelect}
         className="max-w-full"
+        data-loading-item
       />
     ));
 

package/src/components/chat/tool-execution-display.tsx

@@ -6,6 +6,7 @@ import { cn } from '../../utils/cn';
 import { CheckCircleIcon, DotsLoaderIcon, XmarkCircleIcon } from '../icons-v2-generated';
 import type { ToolType } from '../platform';
 import { ToolIcon } from '../tool-icon';
+import { Button } from '../ui/button';
 import { StatusLine, type StatusLineTone } from '../ui/status-line';
 import { CHAT_BLOCK_FRAME_CLASS } from './chat-block-frame';
 import { ExpandChevron } from './expand-chevron';
@@ -141,13 +142,9 @@ const ToolExecutionDisplay = forwardRef<HTMLDivElement, ToolExecutionDisplayProp
         ) : (
           <>
             {hasBody ? (
-              <button
-                type="button"
-                className="flex w-full cursor-pointer items-start gap-[var(--spacing-system-xs)] p-[var(--spacing-system-s)] text-left"
-                onClick={() => setExpanded(prev => !prev)}
-              >
+              <Button variant="row" type="button" aria-expanded={expanded} onClick={() => setExpanded(prev => !prev)}>
                 {headerContent}
-              </button>
+              </Button>
             ) : (
               <div className="flex w-full items-start gap-[var(--spacing-system-xs)] p-[var(--spacing-system-s)] text-left">
                 {headerContent}

package/src/components/chat/types/component.types.ts

@@ -142,6 +142,9 @@ export interface ChatMessageEnhancedProps extends Omit<HTMLAttributes<HTMLDivEle
    *  write (`ChatMessageList.selfAuthorType`). Omit and every `user` turn is
    *  the viewer's own. */
   selfAuthorType?: AuthorType;
+  /** Write the speaker's name on the agent's turn and the viewer's own bubble
+   *  too (`ChatMessageList.nameEveryTurn`). Default false. */
+  nameEveryTurn?: boolean;
   /** Viewer variant for approval blocks in this message's segments.
    *  `'admin'` (default) = full command block; `'client'` = end-client
    *  (Fae desktop app) title-only card. Forwarded to
@@ -257,7 +260,15 @@ export interface ChatMessageEnhancedProps extends Omit<HTMLAttributes<HTMLDivEle
 export interface ChatMessageListProps extends HTMLAttributes<HTMLDivElement> {
   messages: Message[];
   dialogId?: string;
+  /** The thread is still loading: the list draws its own loading state. Inside a `LoadingScope` it does so whatever
+   *  this says. */
   isLoading?: boolean;
+  /** The reader's limit: how many messages the host reads for the thread, so the loading state draws exactly that
+   *  many rows. Default `CHAT_MESSAGE_LIST_SKELETON_MESSAGES` (a typical thread, for a host that reads with no limit). */
+  pageSize?: number;
+  /** The loading state top-anchors its rows and clips them, so a fixed-height host box reads as "the whole panel is
+   *  loading" and never grows a scrollbar. Default `false` (rows bottom-anchored like the loaded thread). */
+  fill?: boolean;
   isTyping?: boolean;
   /** The line shown beside the pending-turn loader: what the turn is doing right
    *  now ("Searching 28 sources"). Omitted, the loader cycles its generic phrases. */
@@ -305,6 +316,12 @@ export interface ChatMessageListProps extends HTMLAttributes<HTMLDivElement> {
    *  is the viewer's (Mingo: the admin's own turns arrive as `admin`); the Fae
    *  client passes `'user'`, so a technician (`admin`) answers from the left. */
   selfAuthorType?: AuthorType;
+  /** Write the speaker's name on every turn: the agent's and the viewer's own
+   *  bubbles too, not only another person's. For a thread of several parties
+   *  — a ticket, where the end user, the agent and any number of technicians
+   *  (all `admin`) write — so who said what is information. Default false: a
+   *  two-party thread (Mingo, the Fae client) is told apart by its faces. */
+  nameEveryTurn?: boolean;
   /** Visual generation of the whole thread, blocks included. Default
    *  `classic`; the Fae client passes `v2`. See `ChatAppearance`. */
   appearance?: ChatAppearance;
@@ -661,6 +678,9 @@ export interface AskDisplayProps extends Omit<HTMLAttributes<HTMLDivElement>, 'o
 // ========== Model Display Props ==========
 
 export interface ModelDisplayProps extends HTMLAttributes<HTMLDivElement> {
+  /** The model metadata is still loading: the row draws its own skeleton (with the "tokens used" tail when
+   *  `contextWindow` is known). Inside a `LoadingScope` it does so whatever this says. */
+  loading?: boolean;
   provider?: string;
   modelName?: string;
   displayName?: string;
@@ -744,6 +764,9 @@ export interface ChatSidebarProps extends HTMLAttributes<HTMLDivElement> {
   hasNextPage?: boolean;
   isFetchingNextPage?: boolean;
   onLoadMore?: () => void;
+  /** The host's page size: how many skeleton rows the first load (and the next page) draws. Default
+   *  `CHAT_HISTORY_PAGE_SIZE`. */
+  pageSize?: number;
 }
 
 // ========== Dialog List Item Props ==========
@@ -752,4 +775,7 @@ export interface DialogListItemProps extends HTMLAttributes<HTMLDivElement> {
   dialog: DialogItem;
   isActive?: boolean;
   onDialogSelect?: (dialogId: string) => void;
+  /** The dialog is still being read: the row draws its skeleton (as it does in a loading scope), carrying the row's
+   *  `data-*` markers. */
+  loading?: boolean;
 }

package/src/components/chat/types/entities/program-types.ts

@@ -289,6 +289,9 @@ export interface ProgramConfig<T extends BaseProgramItem = BaseProgramItem> {
   heroCoverAspect?: 'landscape' | 'square'; // Hero cover image aspect ratio (default: 'landscape')
   /** A card of this type shows its hosts (a webinar presents its speakers): the card's skeleton draws the hosts row. */
   cardShowsHosts?: boolean;
+  /** A card of this type shows its photo gallery (an event's list API serves its photos): the card's skeleton draws
+   *  the gallery row (`PROGRAM_CARD_SKELETON_MEDIA` thumbnails); elsewhere the loaded row is a record's optional part. */
+  cardShowsGallery?: boolean;
 }
 
 // ============================================================================

package/src/components/chat/utils/compact-card-skeleton.tsx

@@ -2,7 +2,7 @@ import { ExternalLink } from 'lucide-react';
 import type React from 'react';
 import { cn } from '../../../utils/cn';
 import { TextLineSkeleton, UnifiedSkeleton } from '../../loading/unified-skeleton';
-import { StatusBadgeSkeleton } from '../../ui/status-badge';
+import { StatusBadge } from '../../ui/status-badge';
 import {
   COMPACT_CARD_META_ROW_BOX,
   COMPACT_CARD_SKELETON_IMAGE_SLOT,
@@ -46,7 +46,7 @@ export function CompactCardSkeleton({
   /** A card whose slot is not the standard image slot (the roadmap's bordered logo box). */
   slotClassName?: string;
   titleWidth?: string;
-  /** Width classes of the status stamps after the title (`StatusBadgeSkeleton variant="button"`); the title row then wraps like the card's. */
+  /** Width classes of the status stamps after the title (`StatusBadge loading variant="button"`); the title row then wraps like the card's. */
   titleBadges?: string[];
   rows?: CompactCardSkeletonRow[];
   /** The card shows the trailing external-link icon. */
@@ -61,7 +61,7 @@ export function CompactCardSkeleton({
           <TextLineSkeleton as="span" type="inherit" className={cn(COMPACT_CARD_TITLE_TYPE, titleWidth)} />
           {titleBadges.map((width, i) => (
             // The compact cards' title badges are `StatusBadge variant="button"` stamps: their own skeleton.
-            <StatusBadgeSkeleton key={i} variant="button" className={cn('shrink-0', width)} />
+            <StatusBadge loading text="" key={i} variant="button" className={cn('shrink-0', width)} />
           ))}
         </span>
         {rows.map((row, i) =>