@flamingo-stack/openframe-frontend-core 0.0.711 → 0.0.712

package/src/components/docs/use-scroll-spy.ts

@@ -1,7 +1,14 @@
 'use client';
 
 import { useState, useRef, useCallback, useEffect, useMemo } from 'react';
-import { getScrollableAncestor, scrollElementIntoView } from '../../utils/scroll-into-view';
+import {
+  ACTIVE_ANCHOR_ATTRIBUTE,
+  getHashTargetElement,
+  isScrollSyncedHash,
+  normalizeHashFragment,
+  replaceLocationHash,
+} from '../../utils/same-page-hash-nav';
+import { declaredScrollMarginTop, getScrollableAncestor, scrollElementIntoView } from '../../utils/scroll-into-view';
 
 // Default sticky-chrome height. Used for BOTH the scroll target offset (where a
 // clicked section lands) AND the active-section detection threshold (where the
@@ -15,6 +22,11 @@ const SCROLL_OFFSET = 100;
 // so the join is unambiguous and the key can be split back apart.
 const ID_SEPARATOR = '\n';
 
+// A section that a link just landed on sits ON the line, give or take a
+// sub-pixel of layout rounding: without this it reads as "not reached yet" and
+// the section above stays active (and, with `syncHash`, takes the URL back).
+const LINE_TOLERANCE_PX = 1;
+
 interface ScrollSpySection {
   id: string;
   title?: string;
@@ -23,13 +35,35 @@ interface ScrollSpySection {
 
 export interface UseScrollSpyOptions {
   /**
-   * Keep the URL's `#hash` on the section being read (`replaceState`: no
+   * Keep the URL's `#hash` on where the reader IS (`replaceLocationHash`: no
    * history entry, and no `hashchange`, so `useScrollToHash` never re-scrolls
    * to it) — as the user SCROLLS, and when a rail click scrolls for them.
    * Above the first section the hash is cleared. Only a scroll or a click
    * writes it — mounting a page never adds a hash.
+   *
+   * TWO LEVELS. The hash names the section being read, or an anchor INSIDE it:
+   *   - a section that marks one of its descendants with
+   *     `ACTIVE_ANCHOR_ATTRIBUTE` (and an `id`) is named by that child: a tab
+   *     group whose open tab has its own anchor. The section remembers its
+   *     child while the reader is elsewhere, so coming back restores it;
+   *   - otherwise a hash that already names something inside the section (a
+   *     card, a question a link landed on) is finer than the section's own and
+   *     is kept until the reader leaves the section.
+   *
+   * RELOAD. The browser restores the exact scroll position and the hash only
+   * mirrors it, so nothing scrolls (`useScrollToHash` stands down for a synced
+   * hash). When the two disagree (the position was not restored: a scroll
+   * container, a layout that changed), the hash wins and the spy scrolls to
+   * it, once, without a tween.
    */
   syncHash?: boolean;
+  /**
+   * What is active above the first section. `'first'` (default): the first
+   * section, a table of contents that always has a current entry. `'none'`:
+   * nothing (`activeSection` is `''`), for a page with a hero above its
+   * sections, so the nav and the URL (no hash there) say the same thing.
+   */
+  aboveFirst?: 'first' | 'none';
   /**
    * Sticky-chrome height in px: where a clicked section lands AND the line a
    * section's top must pass to become the active one. One number for both, so
@@ -38,12 +72,29 @@ export interface UseScrollSpyOptions {
   headerOffset?: number;
 }
 
-/** Point the URL's hash at `sectionId` (or clear it) without a history entry or a `hashchange`. */
-function replaceHash(sectionId: string | null): void {
-  const { pathname, search, hash } = window.location;
-  const next = sectionId ? `#${sectionId}` : '';
-  if (hash === next) return;
-  window.history.replaceState(window.history.state, '', `${pathname}${search}${next}`);
+/** The id the URL's hash names, or `''`. */
+function currentHashId(): string {
+  return normalizeHashFragment(window.location.hash).slice(1);
+}
+
+/** The child anchor a section declares as its active one, if any (`ACTIVE_ANCHOR_ATTRIBUTE`). */
+function activeChildAnchor(section: HTMLElement): string | null {
+  return section.querySelector<HTMLElement>(`[${ACTIVE_ANCHOR_ATTRIBUTE}][id]`)?.id ?? null;
+}
+
+/** Whether the URL's hash names `section` or something inside it. */
+function hashIsWithin(section: HTMLElement): boolean {
+  return section.contains(getHashTargetElement(currentHashId()));
+}
+
+/**
+ * The hash for a section being READ: its active child, else the hash already
+ * in the URL when it names something inside the section, else the section.
+ */
+function hashForSection(sectionId: string): string {
+  const section = document.getElementById(sectionId);
+  if (!section) return sectionId;
+  return activeChildAnchor(section) ?? (hashIsWithin(section) ? currentHashId() : sectionId);
 }
 
 /**
@@ -108,9 +159,11 @@ export function useScrollSpy(
   sections: ScrollSpySection[] | undefined,
   options: UseScrollSpyOptions = {},
 ): UseScrollSpyReturn {
-  const { syncHash = false, headerOffset = SCROLL_OFFSET } = options;
+  const { syncHash = false, headerOffset = SCROLL_OFFSET, aboveFirst = 'first' } = options;
   const [activeSection, setActiveSection] = useState('');
   const isScrollingFromClick = useRef(false);
+  // The restored-position check (see `syncHash`) runs once per page, not on every re-subscription.
+  const restoredChecked = useRef(false);
 
   // The scroll listener only ever needs the section IDS, and callers rebuild
   // the `sections` array on every render — so the value-stable joined key IS
@@ -128,7 +181,9 @@ export function useScrollSpy(
       setActiveSection(sectionId);
       // The click IS the reader's position now: say so in the URL right away
       // rather than waiting for a scroll event the click guard below swallows.
-      if (syncHash) replaceHash(sectionId);
+      // A click on a section's own entry goes to its head: its active child
+      // still names it, a finer hash from an earlier link does not.
+      if (syncHash) replaceLocationHash(activeChildAnchor(targetElement) ?? sectionId);
 
       scrollElementIntoView(targetElement, { headerOffset });
 
@@ -154,12 +209,17 @@ export function useScrollSpy(
 
       const scrollTop = scroller.scrollTop();
       const viewportTop = scroller.viewportTop();
-      const scrollPosition = scrollTop + headerOffset;
       // A section's top in the scroller's coordinates. `offsetTop` is relative
       // to the nearest POSITIONED ancestor, which is neither the document nor
       // the scroll container inside most layouts — measure from the viewport
       // and translate.
       const sectionTop = (element: HTMLElement) => element.getBoundingClientRect().top - viewportTop + scrollTop;
+      // The line a section's top must reach is where a link LANDS it: the
+      // offset, or the section's own larger `scroll-margin-top` (the rule
+      // `scrollElementIntoView` lands by). One number for both, per section.
+      const reached = (element: HTMLElement) =>
+        scrollTop + Math.max(headerOffset, declaredScrollMarginTop(element)) + LINE_TOLERANCE_PX >= sectionTop(element);
+      const first = document.getElementById(sectionIds[0] ?? '');
       let currentSection = sectionIds[0] ?? '';
 
       // At the bottom of the page the last sections can never reach the offset
@@ -175,20 +235,35 @@ export function useScrollSpy(
       } else {
         for (let i = sectionIds.length - 1; i >= 0; i--) {
           const element = document.getElementById(sectionIds[i]);
-          if (element && scrollPosition >= sectionTop(element)) {
+          if (element && reached(element)) {
             currentSection = sectionIds[i];
             break;
           }
         }
       }
 
-      setActiveSection(prev => (prev !== currentSection ? currentSection : prev));
+      const isAboveFirst = !atBottom && first !== null && !reached(first);
+      const active = isAboveFirst && aboveFirst === 'none' ? '' : currentSection;
+      setActiveSection(prev => (prev !== active ? active : prev));
 
-      if (syncHash && fromScroll) {
-        const first = document.getElementById(sectionIds[0] ?? '');
-        const aboveFirst = !atBottom && first !== null && scrollPosition < sectionTop(first);
-        replaceHash(aboveFirst ? null : currentSection);
+      if (!syncHash) return;
+      if (fromScroll) {
+        replaceLocationHash(isAboveFirst ? null : hashForSection(currentSection));
+        return;
       }
+      // First pass with the sections on the page: a hash the reader's scrolling
+      // left behind (a reload) must agree with where the browser restored the
+      // page. It agrees when it names the section at the line or something
+      // inside it; otherwise the hash wins, in one instant write. A hash that
+      // names nothing in the sections known so far waits for the next set (a
+      // section that joins the nav after hydration).
+      if (restoredChecked.current || !isScrollSyncedHash()) return;
+      const target = getHashTargetElement(currentHashId());
+      const tracked = sectionIds.some(id => document.getElementById(id)?.contains(target) ?? false);
+      if (!target || !tracked) return;
+      restoredChecked.current = true;
+      const section = isAboveFirst ? null : document.getElementById(currentSection);
+      if (!section?.contains(target)) scrollElementIntoView(target, { headerOffset, behavior: 'instant' });
     };
 
     let scrollTimer: ReturnType<typeof setTimeout>;
@@ -204,7 +279,7 @@ export function useScrollSpy(
       scroller.target.removeEventListener('scroll', throttledScroll);
       clearTimeout(scrollTimer);
     };
-  }, [sectionIdsKey, syncHash, headerOffset]);
+  }, [sectionIdsKey, syncHash, headerOffset, aboveFirst]);
 
   return { activeSection, handleSectionClick };
 }

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 Link from '../../embed-shims/next-link';
 import { useScrollToHash } from '../../hooks/use-scroll-to-hash';
 import { useSelfFetch } from '../../hooks/use-self-fetch';
 import type { Faq } from '../../types/faq';
@@ -46,6 +47,13 @@ export interface FaqSectionProps {
   /** Fetch-URL prefix for third-party embeds / reverse proxies
    *  ('' = 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.
+   */
+  aside?: React.ReactNode;
 }
 
 const DEFAULT_HEADING_TEXT = 'Frequently Asked Questions';
@@ -114,7 +122,12 @@ const groupKey = (g: FaqGroup): string => g.slug ?? UNCATEGORIZED_KEY;
 function GroupedFaqList({
   groups,
   categoryHeadingAs,
+  heading,
+  aside,
 }: {
+  /** With `aside`, the section heading: it sits in the left column above the category nav. */
+  heading?: React.ReactNode;
+  aside?: React.ReactNode;
   groups: FaqGroup[];
   /** Heading tag for each category, so the document outline nests correctly
    *  under whatever owns the heading above this block: `h2` on the standalone
@@ -265,49 +278,69 @@ function GroupedFaqList({
     });
   }, []);
 
+  const categoryNav = navGroups.length > 1 && (
+    <nav aria-label="FAQ categories" className="flex flex-wrap gap-2">
+      {navGroups.map(group => {
+        const isActive = group.slug === activeSlug;
+        return (
+          <Link
+            key={group.slug}
+            href={`#${group.slug}`}
+            aria-current={isActive ? 'true' : undefined}
+            onClick={e => handleJump(e, group.slug as string)}
+            className={cn(
+              'rounded-full border px-4 py-2 transition-colors text-h6',
+              isActive
+                ? 'border-ods-text-primary bg-ods-card text-ods-text-primary'
+                : 'border-ods-border bg-ods-card text-ods-text-secondary hover:border-ods-text-secondary hover:text-ods-text-primary',
+            )}
+          >
+            {group.section}
+          </Link>
+        );
+      })}
+    </nav>
+  );
+  const questions = (
+    <div className="space-y-10">
+      {groups.map(group => {
+        const key = groupKey(group);
+        return (
+          <section key={key} id={group.slug ?? undefined} className="scroll-mt-24 space-y-4">
+            {group.section && <CategoryHeading className={SECTION_HEADING_CLASS}>{group.section}</CategoryHeading>}
+            <FaqAccordion
+              // Re-key on item-hash changes so the remount picks up the new
+              // `defaultOpenIds` (the accordion is uncontrolled). Stable for
+              // section hashes — category navigation doesn't disturb state.
+              key={`${key}:${accordionKeySuffix}`}
+              items={group.items}
+              defaultOpenIds={defaultOpenByGroupKey?.get(key)}
+            />
+          </section>
+        );
+      })}
+    </div>
+  );
+
+  if (!aside) {
+    return (
+      <div className="space-y-8">
+        {categoryNav}
+        {questions}
+      </div>
+    );
+  }
+
+  // One instance of each block, placed by the grid: questions second in the
+  // document (and on a narrow area), in the right column from `lg`.
   return (
-    <div className="space-y-8">
-      {navGroups.length > 1 && (
-        <nav aria-label="FAQ categories" className="flex flex-wrap gap-2">
-          {navGroups.map(group => {
-            const isActive = group.slug === activeSlug;
-            return (
-              <a
-                key={group.slug}
-                href={`#${group.slug}`}
-                aria-current={isActive ? 'true' : undefined}
-                onClick={e => handleJump(e, group.slug as string)}
-                className={cn(
-                  'rounded-full border px-4 py-2 transition-colors text-h6',
-                  isActive
-                    ? 'border-ods-text-primary bg-ods-card text-ods-text-primary'
-                    : 'border-ods-border bg-ods-card text-ods-text-secondary hover:border-ods-text-secondary hover:text-ods-text-primary',
-                )}
-              >
-                {group.section}
-              </a>
-            );
-          })}
-        </nav>
-      )}
-      <div className="space-y-10">
-        {groups.map(group => {
-          const key = groupKey(group);
-          return (
-            <section key={key} id={group.slug ?? undefined} className="scroll-mt-24 space-y-4">
-              {group.section && <CategoryHeading className={SECTION_HEADING_CLASS}>{group.section}</CategoryHeading>}
-              <FaqAccordion
-                // Re-key on item-hash changes so the remount picks up the new
-                // `defaultOpenIds` (the accordion is uncontrolled). Stable for
-                // section hashes — category navigation doesn't disturb state.
-                key={`${key}:${accordionKeySuffix}`}
-                items={group.items}
-                defaultOpenIds={defaultOpenByGroupKey?.get(key)}
-              />
-            </section>
-          );
-        })}
+    <div className="grid gap-10 content-lg:grid-cols-[minmax(0,1fr)_minmax(0,2fr)] content-lg:grid-rows-[auto_1fr] content-lg:gap-x-16">
+      <div className="space-y-8">
+        {heading}
+        {categoryNav}
       </div>
+      <div className="content-lg:col-start-2 content-lg:row-span-2 content-lg:row-start-1">{questions}</div>
+      <div className="content-lg:col-start-1 content-lg:row-start-2">{aside}</div>
     </div>
   );
 }
@@ -359,6 +392,7 @@ export function FaqSection({
   className,
   minResults,
   apiBaseUrl = '',
+  aside,
 }: FaqSectionProps) {
   const url = buildFaqsUrl(entityType, entityId, minResults, apiBaseUrl);
   // Memoized — useSelfFetch re-syncs on [initialData]; a fresh per-render
@@ -398,8 +432,13 @@ export function FaqSection({
   return (
     <>
       <section className={className ?? 'space-y-10'}>
-        {headingNode}
-        <GroupedFaqList groups={groups} categoryHeadingAs={heading === null ? 'h2' : 'h3'} />
+        {!aside && headingNode}
+        <GroupedFaqList
+          groups={groups}
+          categoryHeadingAs={heading === null ? 'h2' : 'h3'}
+          heading={aside ? headingNode : undefined}
+          aside={aside}
+        />
       </section>
       {schema && (
         <script

package/src/components/features/array-entry-manager.tsx

@@ -38,6 +38,10 @@ interface ArrayEntryManagerProps<T extends object> {
   titleFieldKey?: keyof T;
   titlePlaceholder?: string;
   isSaving?: boolean; // Loading state for save button
+  /** The most entries the list holds; at the cap the add button is disabled. Omitted: no cap. */
+  maxItems?: number;
+  /** Where a new entry lands. Default `start` (the newest on top); `end` for a list whose ORDER is its meaning. */
+  addPosition?: 'start' | 'end';
 }
 
 export function ArrayEntryManager<T extends object>({
@@ -57,6 +61,8 @@ export function ArrayEntryManager<T extends object>({
   titleFieldKey,
   titlePlaceholder,
   isSaving = false,
+  maxItems,
+  addPosition = 'start',
 }: ArrayEntryManagerProps<T>) {
   // Local state for draft changes (when requireSave=true)
   const [draftItems, setDraftItems] = useState<T[]>(items);
@@ -100,7 +106,9 @@ export function ArrayEntryManager<T extends object>({
 
   const addItem = () => {
     const newItem = { [fieldKey]: '' } as T;
-    setWorkingItems([newItem, ...workingItems]); // Add at top for better UX
+    if (maxItems !== undefined && workingItems.length >= maxItems) return;
+    // On top by default (the newest is what is being typed); at the end for an ordered list.
+    setWorkingItems(addPosition === 'end' ? [...workingItems, newItem] : [newItem, ...workingItems]);
   };
 
   const removeItem = (index: number) => {
@@ -180,6 +188,7 @@ export function ArrayEntryManager<T extends object>({
             variant="outline"
             size="small-legacy"
             onClick={addItem}
+            disabled={maxItems !== undefined && workingItems.length >= maxItems}
             leftIcon={<Plus className="h-4 w-4" />}
             className="text-h6"
           >

package/src/components/features/board/board.tsx

@@ -83,6 +83,8 @@ export interface BoardProps {
   onApprove?: (ticketId: string, requestId?: string) => void | Promise<void>;
   onReject?: (ticketId: string, requestId?: string) => void | Promise<void>;
   collapseStorageKey?: string;
+  /** The lanes folded when the board mounts, by column id. Read only without `collapseStorageKey`. */
+  initialCollapsed?: Record<string, boolean>;
   loadMoreRootMargin?: string;
   className?: string;
 }
@@ -138,10 +140,11 @@ function DragBoard({
   onApprove,
   onReject,
   collapseStorageKey,
+  initialCollapsed,
   loadMoreRootMargin,
   className,
 }: BoardProps) {
-  const { collapsed, toggle } = useBoardCollapse(collapseStorageKey);
+  const { collapsed, toggle } = useBoardCollapse(collapseStorageKey, initialCollapsed);
 
   const {
     scrollRef,

package/src/components/features/board/ticket-card.tsx

@@ -22,6 +22,7 @@ import { cn } from '../../../utils/cn';
 import { formatTicketRelativeTime, formatTicketFullTimestamp } from '../../../utils/date-utils';
 import { holdMoveDragEffect } from '../../../utils/drag-effect';
 import { getReadableTextColor } from '../../../utils/ods-color-utils';
+import { AgentMark } from '../../agent-mark';
 import {
   ClockIcon,
   DotsLoaderIcon,
@@ -110,7 +111,7 @@ export function TicketCardBody({
   const showDeviceRow = !!(ticket.deviceHostnames?.length || ticket.organizationName);
   const deviceText = [ticket.deviceHostnames?.join(', '), ticket.organizationName].filter(Boolean).join(', ');
 
-  const hasRightSection = !!(ticket.priority || ticket.assignees?.length || renderAssignSlot);
+  const hasRightSection = !!(ticket.priority || ticket.agent || ticket.assignees?.length || renderAssignSlot);
   const rightSection = hasRightSection ? (
     <div className="pointer-events-auto flex shrink-0 items-center gap-[var(--spacing-system-xsf)]">
       {ticket.priority && (
@@ -119,6 +120,15 @@ export function TicketCardBody({
           aria-label={`Priority: ${ticket.priority}`}
         />
       )}
+      {ticket.agent && (
+        <span
+          role="img"
+          aria-label={`Owned by ${ticket.agent === 'fae' ? 'Fae' : 'Mingo'}`}
+          className="flex size-8 shrink-0 items-center justify-center overflow-hidden rounded-full border border-ods-border bg-ods-bg"
+        >
+          <AgentMark agent={ticket.agent} className={ticket.agent === 'fae' ? 'size-full' : 'size-5'} />
+        </span>
+      )}
       {renderAssignSlot ? (
         renderAssignSlot(ticket)
       ) : ticket.assignees?.length ? (

package/src/components/features/board/touch-board.tsx

@@ -33,10 +33,11 @@ export function TouchBoard({
   onApprove,
   onReject,
   collapseStorageKey,
+  initialCollapsed,
   loadMoreRootMargin,
   className,
 }: BoardProps) {
-  const { collapsed, toggle } = useBoardCollapse(collapseStorageKey);
+  const { collapsed, toggle } = useBoardCollapse(collapseStorageKey, initialCollapsed);
 
   return (
     <div className={cn('flex h-full min-h-0 flex-col', className)}>

package/src/components/features/board/types.ts

@@ -1,3 +1,4 @@
+import type { AgentName } from '../../agent-mark';
 import type { PendingToolCallData } from '../../chat/types';
 import type { TicketStatus } from '../../ui/ticket-status-tag';
 
@@ -68,6 +69,8 @@ export interface BoardTicket {
   escalatedByUser?: boolean;
   /** Single live-activity indicator rendered as the card's footer row. */
   activity?: BoardTicketActivity;
+  /** The AI agent that owns the ticket: its mark is shown with the assignees. */
+  agent?: AgentName;
 }
 
 export interface BoardColumnDef {

package/src/components/features/board/use-board-collapse.ts

@@ -11,9 +11,14 @@ export interface UseBoardCollapseReturn {
   setCollapsed: (columnId: string, value: boolean) => void;
 }
 
-export function useBoardCollapse(storageKey?: string): UseBoardCollapseReturn {
+/**
+ * Which lanes are collapsed. With a `storageKey` the map is the user's, kept in
+ * local storage; without one it lives in memory and starts from `initial` (a
+ * host that shows a board with some lanes already folded).
+ */
+export function useBoardCollapse(storageKey?: string, initial?: BoardCollapseMap): UseBoardCollapseReturn {
   const [persisted, setPersisted] = useLocalStorage<BoardCollapseMap>(storageKey ?? '__board_collapse_unused__', {});
-  const [memory, setMemory] = useState<BoardCollapseMap>({});
+  const [memory, setMemory] = useState<BoardCollapseMap>(initial ?? {});
 
   const collapsed = storageKey ? persisted : memory;
   const setMap = storageKey ? setPersisted : setMemory;