@flamingo-stack/openframe-frontend-core 0.0.286 → 0.0.287

package/dist/utils/list-url.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"list-url.d.ts","sourceRoot":"","sources":["../../src/utils/list-url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAWH;;;;iEAIiE;AACjE,wBAAgB,uBAAuB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAEtE;AA4BD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,IAAI,SAAK,GAAG,MAAM,GAAG,IAAI,CAa5F"}
+{"version":3,"file":"list-url.d.ts","sourceRoot":"","sources":["../../src/utils/list-url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAWH;;;;iEAIiE;AACjE,wBAAgB,uBAAuB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAEtE;AA6BD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,IAAI,SAAK,GAAG,MAAM,GAAG,IAAI,CAa5F"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.286",
+  "version": "0.0.287",
   "description": "Shared design system and components for all Flamingo platforms",
   "type": "module",
   "main": "./dist/index.js",

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/types/marketing.ts

@@ -347,6 +347,7 @@ export type ContentSourceType =
   | 'investor_update'     // Investor updates
   | 'onboarding_guide'    // Onboarding guides (lives on openframe platform)
   | 'what_i_shipped'      // What I Shipped employee check-ins (lives on people-hub)
+  | 'faq'                 // FAQ Q&A pair (single-page /faqs index; deep-link by category anchor)
   | 'from_scratch';
 
 export type URLInjectionPreference = 'none' | 'in_post' | 'as_comment';

package/src/utils/faq-anchor.ts

@@ -0,0 +1,70 @@
+/**
+ * FAQ anchor SSOTs — TWO complementary deep-link kinds on the `/faqs` page,
+ * both rendered straight onto the DOM and recognised by ONE parser. Keeping
+ * the format helpers + parser in one file means the page, the chat RAG
+ * mapper, and any future consumer can't drift on what a hash means.
+ *
+ *   `/faqs#faq-pricing`     → category section header (jump-nav pills,
+ *                             scroll-spy)
+ *   `/faqs#faq-item-42`     → individual question (chat citation chips —
+ *                             auto-expands the row + scrolls to it)
+ *
+ * Reserved namespaces — `faq-item-<digits>` is the item shape; everything
+ * else starting with `faq-` is a section slug. `faqSectionSlug` lowercases
+ * + dash-collapses + dash-trims, so a section name would only collide with
+ * the item shape if it slugified to `faq-item-<digits-only>` (e.g. a
+ * category called "Item 42") — none of the 21 production sections do, and
+ * `parseFaqHash`'s regex is digits-only so future word-suffixed names like
+ * "Item Whatever" (slugifies to `faq-item-whatever`) are also safe.
+ */
+
+/** Stable, URL-safe anchor id for a category. Prefixed with `faq-` so it
+ *  can't collide with other in-page ids, and so a bare numeric/blank
+ *  section still yields a valid id. The helper assumes the caller has
+ *  already verified the section is a non-blank string (matches
+ *  `faq-section.tsx`'s `groupFaqsBySection` precondition). */
+export function faqSectionSlug(section: string): string {
+  return (
+    'faq-' +
+    section
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '')
+  )
+}
+
+/** Stable anchor for an individual FAQ row. Rendered as the row container's
+ *  `id` attribute by `FaqAccordion`; consumed by `FaqSection` (auto-open +
+ *  auto-scroll on mount) AND by the hub's RAG mapper so chat citations
+ *  deep-link to the specific question, not just its category. The id is
+ *  stringified verbatim — the FAQ schema uses integer PKs so `parseFaqHash`'s
+ *  digits-only regex always matches a real row. */
+export function faqItemAnchor(id: number | string): string {
+  return `faq-item-${id}`
+}
+
+/** Discriminated parse of a `/faqs#…` hash. Returns null for an empty,
+ *  missing, or unrecognised hash so callers can early-out without
+ *  scattering string parsing across the file.
+ *
+ *   parseFaqHash('#faq-item-42')   → { kind: 'item',    rawId: '42' }
+ *   parseFaqHash('#faq-pricing')   → { kind: 'section', slug: 'faq-pricing' }
+ *   parseFaqHash('#anything-else') → null
+ *
+ * `rawId` is the matched digit run as a string — the caller compares it
+ * to `String(item.id)` so coercion stays at the comparison site. */
+export type FaqHashTarget =
+  | { kind: 'item';    rawId: string }
+  | { kind: 'section'; slug:  string }
+
+const FAQ_ITEM_HASH_RE = /^faq-item-(\d+)$/
+
+export function parseFaqHash(hash: string | null | undefined): FaqHashTarget | null {
+  if (!hash) return null
+  const trimmed = hash.replace(/^#/, '')
+  if (!trimmed) return null
+  const itemMatch = FAQ_ITEM_HASH_RE.exec(trimmed)
+  if (itemMatch) return { kind: 'item', rawId: itemMatch[1] }
+  if (trimmed.startsWith('faq-')) return { kind: 'section', slug: trimmed }
+  return null
+}

package/src/utils/index.ts

@@ -253,6 +253,13 @@ export {
 // Pure + server-safe (the hub imports it server-side from this barrel).
 export { buildListUrl, canonicalContentRefType } from './list-url'
 
+// FAQ anchor SSOTs — section (`faq-<slug>`) AND item (`faq-item-<id>`)
+// formats plus the parser, all rendered by `FaqSection`/`FaqAccordion`
+// and recognised by the hub's RAG mapper. One algo per kind, one parser,
+// zero drift across page + chat + future consumers.
+export { faqSectionSlug, faqItemAnchor, parseFaqHash } from './faq-anchor'
+export type { FaqHashTarget } from './faq-anchor'
+
 // Content-ref group registry (labels/order/layout per rail type) + list-API
 // response normalizers + the shared suggestion-fetch URL composer — all
 // pure + server-safe; the hub re-exports these from its config/util shims.

package/src/utils/list-url.ts

@@ -70,6 +70,7 @@ const BUILDERS: Record<string, (ids: string[], base: string) => string> = {
   product_release: (ids, b) => `${b}/api/releases?ids=${ids.join(',')}&limit=${ids.length}`,
   customer_interview: (ids, b) => `${b}/api/customer-interviews?ids=${ids.join(',')}&limit=${ids.length}`,
   investor_update: (ids, b) => `${b}/api/investor-updates?ids=${ids.join(',')}&limit=${ids.length}`,
+  faq: (ids, b) => `${b}/api/faqs?ids=${ids.join(',')}&limit=${ids.length}`,
 }
 
 /**