@flamingo-stack/openframe-frontend-core 0.0.285 → 0.0.286-snapshot.20260618154650

package/src/components/embeds/figma-embed.tsx

@@ -0,0 +1,147 @@
+'use client'
+
+import { useState } from 'react'
+import { Button, ToggleGroup, ToggleGroupItem } from '../ui'
+import { FigmaIcon } from '../icons-v2-generated'
+import { ExternalLink, Play, LayoutGrid } from 'lucide-react'
+import { toFigmaEmbedUrl, toFigmaOriginalUrl, isFigmaSlidesUrl } from '../../utils/embed-url-converters'
+import { EmbedIframe } from './embed-iframe'
+
+export interface FigmaEmbedProps {
+  /** Any Figma URL (design/file/proto/board/slides/deck) or an already-resolved embed URL. */
+  url: string
+  /** Heading shown above the embed. Defaults to "Figma Design". */
+  title?: string
+  /**
+   * iframe height (CSS value). The data-room document viewer omits it (full
+   * height, `calc(100vh - 250px)`); inline markdown passes e.g. `"70vh"` so the
+   * embed sits naturally inside article content.
+   */
+  height?: string
+  /** iframe loading strategy. Defaults to `"lazy"`; the data-room viewer passes `"eager"`. */
+  loading?: 'eager' | 'lazy'
+}
+
+type SlidesView = 'present' | 'browse'
+
+/**
+ * Two-state present/browse toggle for Figma Slides. `present` (default) uses
+ * Figma's deck viewer (full-bleed slide + `‹ n/N ›` nav bar + keyboard nav);
+ * `browse` uses the thumbnail-rail + zoom viewer.
+ */
+function SlidesViewToggle({
+  view,
+  onChange,
+}: {
+  view: SlidesView
+  onChange: (v: SlidesView) => void
+}) {
+  const options: { key: SlidesView; label: string; Icon: typeof Play }[] = [
+    { key: 'present', label: 'Present', Icon: Play },
+    { key: 'browse', label: 'Browse', Icon: LayoutGrid },
+  ]
+  return (
+    <ToggleGroup
+      type="single"
+      value={view}
+      onValueChange={(v: string) => {
+        if (v && v !== view) onChange(v as SlidesView)
+      }}
+      aria-label="Figma slides view mode"
+      className="flex shrink-0 items-center gap-0.5 rounded-lg border border-ods-border bg-ods-card p-0.5"
+    >
+      {options.map(({ key, label, Icon }) => {
+        const active = view === key
+        return (
+          <ToggleGroupItem
+            key={key}
+            value={key}
+            aria-label={label}
+            className={`flex items-center gap-1.5 rounded-md px-2.5 py-1 text-sm font-medium transition-colors ${
+              active
+                ? 'bg-ods-accent text-ods-text-on-accent'
+                : 'text-ods-text-secondary hover:text-ods-text-primary hover:bg-ods-bg-hover'
+            }`}
+          >
+            <Icon className="h-4 w-4 shrink-0" />
+            {label}
+          </ToggleGroupItem>
+        )
+      })}
+    </ToggleGroup>
+  )
+}
+
+/**
+ * Single source of truth for every Figma surface — the data-room document viewer
+ * and in-article markdown both render this. A header (icon + title + "Open in
+ * Figma") over an interactive Figma iframe, built from the canonical
+ * `toFigmaEmbedUrl` / `toFigmaOriginalUrl` converters + the shared `<EmbedIframe>`.
+ * Only height/loading differ per surface.
+ *
+ * For Slides decks, a present/browse toggle (default = present) lets viewers flip
+ * slides with Figma's native nav bar + keyboard, or switch to the thumbnail-rail
+ * browse view.
+ */
+export function FigmaEmbed({ url, title, height, loading = 'lazy' }: FigmaEmbedProps) {
+  const [view, setView] = useState<SlidesView>('present')
+  const isSlides = url ? isFigmaSlidesUrl(url) : false
+  const embedSrc = url ? toFigmaEmbedUrl(url, { slidesView: view }) : null
+  const originalUrl = (() => {
+    if (!url) return null
+    try {
+      const parsed = new URL(toFigmaOriginalUrl(url))
+      const host = parsed.hostname.toLowerCase()
+      const okHost = host === 'figma.com' || host.endsWith('.figma.com')
+      const okProtocol = parsed.protocol === 'https:' || parsed.protocol === 'http:'
+      return okHost && okProtocol ? parsed.toString() : null
+    } catch {
+      return null
+    }
+  })()
+  const heading = title || 'Figma Design'
+
+  return (
+    <div className="my-6 space-y-3">
+      <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+        <div className="flex items-center gap-2 min-w-0">
+          <FigmaIcon className="w-5 h-5 shrink-0" />
+          <span className="font-sans text-base font-semibold text-ods-text-primary truncate">
+            {heading}
+          </span>
+        </div>
+        <div className="flex flex-col gap-2 sm:flex-row sm:items-center">
+          {isSlides && embedSrc && <SlidesViewToggle view={view} onChange={setView} />}
+          {originalUrl && (
+            <Button
+              variant="outline"
+              size="small-legacy"
+              href={originalUrl}
+              openInNewTab
+              leftIcon={<FigmaIcon className="w-4 h-4" />}
+              rightIcon={<ExternalLink className="w-4 h-4" />}
+              className="w-full sm:w-auto"
+            >
+              Open in Figma
+            </Button>
+          )}
+        </div>
+      </div>
+      {embedSrc ? (
+        <EmbedIframe
+          src={embedSrc}
+          title={heading}
+          allow="clipboard-write; clipboard-read; fullscreen"
+          loading={loading}
+          height={height}
+          allowFullScreen
+        />
+      ) : (
+        <div className="flex flex-col items-center justify-center py-16 text-center">
+          <FigmaIcon className="w-16 h-16 text-ods-text-secondary mb-4" />
+          <p className="text-ods-text-secondary">Figma URL not configured</p>
+        </div>
+      )}
+    </div>
+  )
+}

package/src/components/embeds/google-sheets-viewer.tsx

@@ -0,0 +1,54 @@
+"use client"
+
+import React from 'react'
+import { Button } from '../ui'
+import { ExternalLink } from 'lucide-react'
+import { GoogleSheetsIcon } from '../icons-v2-generated'
+import { EmbedIframe } from './embed-iframe'
+import { toGoogleSheetsEmbedUrl, toGoogleSheetsOriginalUrl } from '../../utils/embed-url-converters'
+
+export interface GoogleSheetsViewerProps {
+  externalUrl: string
+  fileName?: string
+  height?: string
+}
+
+export function GoogleSheetsViewer({ externalUrl, fileName, height }: GoogleSheetsViewerProps) {
+  const displayName = fileName || 'Google Sheet'
+
+  if (!externalUrl) {
+    return (
+      <div className="flex flex-col items-center justify-center py-16 text-center">
+        <GoogleSheetsIcon className="w-16 h-16 text-ods-text-secondary mb-4" />
+        <p className="text-ods-text-secondary">Google Sheet URL not configured</p>
+      </div>
+    )
+  }
+
+  return (
+    <div className="space-y-4">
+      <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+        <div className="flex items-center gap-2 min-w-0">
+          <GoogleSheetsIcon className="w-5 h-5 shrink-0" />
+          <h2 className="text-xl font-semibold text-ods-text-primary truncate">{displayName}</h2>
+        </div>
+        <Button
+          variant="outline"
+          size="small-legacy"
+          href={toGoogleSheetsOriginalUrl(externalUrl)}
+          openInNewTab
+          leftIcon={<GoogleSheetsIcon className="w-4 h-4" />}
+          rightIcon={<ExternalLink className="w-4 h-4" />}
+          className="w-full sm:w-auto"
+        >
+          Open in Google Sheets
+        </Button>
+      </div>
+      <EmbedIframe
+        src={toGoogleSheetsEmbedUrl(externalUrl)}
+        title={displayName}
+        height={height}
+      />
+    </div>
+  )
+}

package/src/components/embeds/index.ts

@@ -0,0 +1,11 @@
+export { EmbedIframe } from './embed-iframe'
+export type { EmbedIframeProps } from './embed-iframe'
+
+export { PdfViewer } from './pdf-viewer'
+export type { PdfViewerProps } from './pdf-viewer'
+
+export { GoogleSheetsViewer } from './google-sheets-viewer'
+export type { GoogleSheetsViewerProps } from './google-sheets-viewer'
+
+export { FigmaEmbed } from './figma-embed'
+export type { FigmaEmbedProps } from './figma-embed'

package/src/components/embeds/pdf-viewer.tsx

@@ -0,0 +1,64 @@
+"use client"
+
+import React from 'react'
+import { Button } from '../ui'
+import { Download, Eye } from 'lucide-react'
+import { AdobePdfIcon } from '../icons-v2-generated'
+import { EmbedIframe } from './embed-iframe'
+
+export interface PdfViewerProps {
+  src: string
+  fileName?: string
+  onPreview?: () => void
+  onDownload?: () => void
+  height?: string
+}
+
+export function PdfViewer({ src, fileName, onPreview, onDownload, height }: PdfViewerProps) {
+  const displayName = fileName || 'PDF Document'
+
+  if (!src) {
+    return (
+      <div className="flex flex-col items-center justify-center py-16 text-center">
+        <AdobePdfIcon className="w-16 h-16 text-ods-text-secondary mb-4" />
+        <p className="text-ods-text-secondary">PDF file not available</p>
+      </div>
+    )
+  }
+
+  return (
+    <div className="space-y-4">
+      <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+        <div className="flex items-center gap-2 min-w-0">
+          <AdobePdfIcon className="w-5 h-5 shrink-0" />
+          <h2 className="text-xl font-semibold text-ods-text-primary truncate">{displayName}</h2>
+        </div>
+        <div className="flex items-center gap-2 w-full sm:w-auto">
+          <Button
+            variant="outline"
+            size="small-legacy"
+            href={onPreview ? undefined : src}
+            openInNewTab={!onPreview}
+            onClick={onPreview}
+            leftIcon={<Eye className="w-4 h-4" />}
+            className="flex-1 sm:flex-initial"
+          >
+            Preview
+          </Button>
+          <Button
+            variant="outline"
+            size="small-legacy"
+            href={onDownload ? undefined : src}
+            openInNewTab={!onDownload}
+            onClick={onDownload}
+            leftIcon={<Download className="w-4 h-4" />}
+            className="flex-1 sm:flex-initial"
+          >
+            Download
+          </Button>
+        </div>
+      </div>
+      <EmbedIframe src={src} title={displayName} height={height} />
+    </div>
+  )
+}

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

@@ -7,6 +7,7 @@ import { useSelfFetch } from '../../hooks/use-self-fetch'
 import { buildSuggestionUrl } from '../../utils/suggestion-url'
 import { serializeJsonLd } from '../../utils/common'
 import { scrollElementIntoView } from '../../utils/scroll-into-view'
+import { faqSectionSlug, faqItemAnchor, parseFaqHash, type FaqHashTarget } from '../../utils/faq-anchor'
 import { cn } from '../../utils/cn'
 import { buildFaqJsonLdFromFaqs, type FaqSchemaOptions } from './json-ld'
 import { SECTION_HEADING_CLASS } from '../layout/page-heading'
@@ -59,19 +60,6 @@ function buildFaqsUrl(
   return buildSuggestionUrl('/api/faqs', { apiBaseUrl, entityType, entityId, count: minResults })
 }
 
-/** Stable, URL-safe anchor id for a category. Prefixed so it can't collide
- *  with other in-page ids, and so a bare numeric/blank section still yields a
- *  valid id. */
-function sectionSlug(section: string): string {
-  return (
-    'faq-' +
-    section
-      .toLowerCase()
-      .replace(/[^a-z0-9]+/g, '-')
-      .replace(/^-+|-+$/g, '')
-  )
-}
-
 interface FaqGroup {
   /** null → the uncategorized bucket: no heading, no jump pill, rendered last. */
   section: string | null
@@ -98,7 +86,7 @@ function groupFaqsBySection(faqs: Faq[]): FaqGroup[] {
     }
     let group = byName.get(name)
     if (!group) {
-      group = { section: name, slug: sectionSlug(name), items: [] }
+      group = { section: name, slug: faqSectionSlug(name), items: [] }
       byName.set(name, group)
       order.push(name)
     }
@@ -113,6 +101,12 @@ function groupFaqsBySection(faqs: Faq[]): FaqGroup[] {
  *  scroll uses, so a category jump lands below the header, not under it. */
 const FAQ_NAV_HEADER_OFFSET = 96
 
+/** Map key for the uncategorized bucket — `group.slug` is null for it, so
+ *  every per-group map (default-open ids, accordion keys) uses this sentinel
+ *  to keep the lookup typed. */
+const UNCATEGORIZED_KEY = '__uncategorized__'
+const groupKey = (g: FaqGroup): string => g.slug ?? UNCATEGORIZED_KEY
+
 /**
  * Grouped FAQ layout: a category jump-nav above stacked `<h2>` category
  * sections (each its own accordion). Isolated into its own component so the
@@ -177,6 +171,54 @@ function GroupedFaqList({
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [slugKey])
 
+  // ─── Hash dispatch — `/faqs#faq-item-<id>` or `/faqs#faq-<section-slug>` ──
+  // Tracks the current hash so:
+  //   1. an item-kind hash seeds `defaultOpenIds` on the matching accordion
+  //      (auto-expands the cited question);
+  //   2. either kind triggers the cancellation-proof tween scroll with the
+  //      sticky-header offset (native browser hash scroll runs once, ignores
+  //      our offset — re-running the tween puts the target in the right spot).
+  // Listens to `hashchange` so back/forward replays the same behavior. SSR-
+  // safe: initial null state matches the server render; the first effect
+  // tick on the client updates it.
+  const [hashTarget, setHashTarget] = useState<FaqHashTarget | null>(null)
+  useEffect(() => {
+    const refresh = () => setHashTarget(parseFaqHash(window.location.hash))
+    refresh()
+    window.addEventListener('hashchange', refresh)
+    return () => window.removeEventListener('hashchange', refresh)
+  }, [])
+
+  // Per-group default-open set when the hash points at an item. The map key
+  // matches `groupKey(group)` so the render-time lookup is O(1) per group.
+  const defaultOpenByGroupKey = useMemo(() => {
+    if (hashTarget?.kind !== 'item') return null
+    const targetId = hashTarget.rawId
+    const result = new Map<string, (string | number)[]>()
+    for (const group of groups) {
+      const hit = group.items.find((i) => String(i.id) === targetId)
+      if (hit) result.set(groupKey(group), [hit.id])
+    }
+    return result.size > 0 ? result : null
+  }, [groups, hashTarget])
+
+  // Accordion is uncontrolled — `defaultOpenIds` is only consumed at mount,
+  // so a new item hash needs a remount to honor it. Keying off the item-id
+  // suffix triggers exactly the remount we need (and stays stable when the
+  // hash points at a section, so category navigation never disturbs the
+  // accordion's open state).
+  const accordionKeySuffix =
+    hashTarget?.kind === 'item' ? `item:${hashTarget.rawId}` : 'default'
+
+  useEffect(() => {
+    if (!hashTarget) return
+    const elId =
+      hashTarget.kind === 'item' ? faqItemAnchor(hashTarget.rawId) : hashTarget.slug
+    const el = document.getElementById(elId)
+    if (el) scrollElementIntoView(el, { headerOffset: FAQ_NAV_HEADER_OFFSET })
+    if (hashTarget.kind === 'section') setActiveSlug(hashTarget.slug)
+  }, [hashTarget])
+
   const handleJump = useCallback(
     (e: React.MouseEvent<HTMLAnchorElement>, slug: string) => {
       e.preventDefault()
@@ -215,18 +257,28 @@ function GroupedFaqList({
         </nav>
       )}
       <div className="space-y-10">
-        {groups.map((group) => (
-          <section
-            key={group.slug ?? 'faq-uncategorized'}
-            id={group.slug ?? undefined}
-            className="scroll-mt-24 space-y-4"
-          >
-            {group.section && (
-              <CategoryHeading className={SECTION_HEADING_CLASS}>{group.section}</CategoryHeading>
-            )}
-            <FaqAccordion items={group.items} />
-          </section>
-        ))}
+        {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>
     </div>
   )

package/src/components/faq-accordion.tsx

@@ -3,6 +3,7 @@
 import React, { useRef, useState, useEffect, useCallback } from 'react'
 import { ChevronButton } from './ui/chevron-button'
 import { cn } from "../utils/cn"
+import { faqItemAnchor } from "../utils/faq-anchor"
 
 export interface FaqItem {
   id: number | string
@@ -60,7 +61,13 @@ export function FaqAccordion({ items, defaultOpenIds = [] }: FaqAccordionProps)
         return (
           <div
             key={item.id}
-            className={cn('group transition-colors hover:bg-[#1E1E1E]', isOpen ? 'bg-ods-bg' : 'bg-transparent')}
+            // Per-row anchor — chat citation chips (`/faqs#faq-item-<id>`) land
+            // here via native browser hash scroll AND via `FaqSection`'s tween
+            // dispatch. `scroll-mt-24` keeps the row header below the 96px
+            // sticky nav offset (matches `<section>`'s scroll-margin for
+            // category anchors).
+            id={faqItemAnchor(item.id)}
+            className={cn('group scroll-mt-24 transition-colors hover:bg-[#1E1E1E]', isOpen ? 'bg-ods-bg' : 'bg-transparent')}
           >
             {/* Header */}
             <div

package/src/components/index.ts

@@ -2,6 +2,8 @@
 
 // Components exports
 export * from './chat'
+export * from './docs'
+export * from './embeds'
 export * from './features'
 export * from './icons'
 export * from './navigation'

package/src/components/navigation/index.ts

@@ -56,6 +56,11 @@ export type { HeaderGlobalSearchProps } from './header-global-search'
 export { HeaderOrganizationFilter } from './header-organization-filter'
 export type { HeaderOrganizationFilterOrganization, HeaderOrganizationFilterProps } from './header-organization-filter'
 
+// Multi-level navigation — sidebar + mobile dropdown for the doc-viewer
+// (DocViewer / DocSourceViewer) and any other tree-shaped navigation surface.
+export { MultiLevelNavigation, MobileNavigationDropdown } from './multi-level-navigation'
+export type { NavigationNode } from './multi-level-navigation'
+
 // Re-export types from navigation types
 export type {
   MobileNavConfig, NavigationItem, NavigationSidebarConfig,