@flamingo-stack/openframe-frontend-core 0.0.449 → 0.0.450

package/src/hooks/ui/use-marquee-engine.ts

@@ -0,0 +1,158 @@
+'use client'
+
+import { useCallback, useEffect, useRef, type MutableRefObject } from 'react'
+
+/**
+ * THE marquee animation core (single source of truth) — extracted verbatim
+ * from <CardsStrip> so every endless-scroll surface (card strips, logo strips,
+ * quick-action walls, chip marquees) shares ONE rAF position engine ("unify
+ * means delete variations").
+ *
+ * The engine is axis- and driver-agnostic: it owns a FLOAT position ref, a
+ * velocity envelope, seam wrapping, and an optional chevron-style glide; the
+ * caller decides what a position "means" via `apply` — writing
+ * `scroller.scrollLeft` (CardsStrip: a real scroller the user can also drag)
+ * or a `translate` transform (MarqueeWall: decorative tracks, incl. vertical —
+ * mandatory inside surfaces that forbid inner scrollers, e.g. the deck's
+ * mobile single-fold panels).
+ *
+ * Engine semantics (do not "simplify"):
+ * - Position lives in a FLOAT ref, never read-modify-write from the DOM:
+ *   scrollLeft reads back rounded values, so sub-pixel increments
+ *   (speed/fps < 1px) get eaten by rounding — stutter + measurably slower
+ *   than the configured speed.
+ * - Velocity envelope (~250ms time constant) eases between 0 and `speed`
+ *   instead of binary stop/start — pause decelerates, resume accelerates from
+ *   the current position (GSAP-marquee behavior; hard cuts read as jank).
+ * - Glide consumes a signed remaining-distance, wrapping modulo the copy size
+ *   each frame, so seam warps are invisible to it (browser smooth-scroll
+ *   animates toward an ABSOLUTE target and lunges after a warp).
+ * - `isPaused` is evaluated every frame — the caller owns the pause-reason
+ *   set (hover, viewport, tab visibility, suppress windows); the engine only
+ *   turns it into a smooth velocity target.
+ */
+export interface MarqueeEngineOptions {
+  /** Master switch — the rAF runs only while true. On (re)activation the
+   *  position resyncs from `readBack` when provided. */
+  active: boolean
+  /** Cruise speed in px/s. */
+  speed: number
+  /** Per-frame pause verdict (caller-owned reason set). `now` is the rAF
+   *  timestamp, for suppress-until comparisons. */
+  isPaused: (now: number) => boolean
+  /** Single-copy size in px (the wrap modulus). Return <= 0 to disable
+   *  wrapping (position advances unwrapped — callers should size tracks so
+   *  this never happens while active). */
+  getWrapSize: () => number
+  /** Lower bound of the wrap range: positions stay in
+   *  [wrapMin, wrapMin + wrapSize). Default 0. Scroller drivers with USER
+   *  scrolling pass their seam-warp buffer here so engine-written positions
+   *  never enter the re-center zones — an exact-edge warp check is racy
+   *  against the rAF (the engine nudges the scroller off the edge before the
+   *  scroll handler samples it → "stuck at the left edge"). */
+  getWrapMin?: () => number
+  /** Write the position to the DOM (scrollLeft assignment or transform). */
+  apply: (pos: number) => void
+  /** Read the externally-mutated position back (real scrollers: user drag /
+   *  native smooth scroll move scrollLeft under the engine). Omit for
+   *  transform drivers — nothing external can move them. */
+  readBack?: () => number
+  /** Called at the end of every frame (e.g. hover re-resolution after the
+   *  track moved under a stationary pointer). */
+  onAfterFrame?: () => void
+}
+
+export interface MarqueeEngineHandle {
+  /** The engine's float position (px along the axis, 0 ≤ pos < wrap while
+   *  wrapping). Callers may write it together with their own DOM write (seam
+   *  warp on manual scroll). */
+  posRef: MutableRefObject<number>
+  /** Accumulate a signed glide distance (chevron navigation). Runs through
+   *  the engine's own tween — never native smooth scroll while wrapping. */
+  glideBy: (px: number) => void
+  /** Wrap an arbitrary position into [0, wrapSize). */
+  wrap: (pos: number) => number
+}
+
+// Resync threshold (px): external movement beyond this adopts the DOM value.
+const RESYNC_EPSILON = 1.5
+
+export function useMarqueeEngine(options: MarqueeEngineOptions): MarqueeEngineHandle {
+  const posRef = useRef(0)
+  const glideRemainingRef = useRef(0)
+  const speedEnvRef = useRef(0)
+
+  // Latest-options ref: the rAF loop always reads current values without the
+  // effect restarting on every render.
+  const optsRef = useRef(options)
+  optsRef.current = options
+
+  const wrap = useCallback((pos: number) => {
+    const half = optsRef.current.getWrapSize()
+    if (half <= 0) return pos
+    const min = optsRef.current.getWrapMin?.() ?? 0
+    while (pos >= min + half) pos -= half
+    while (pos < min) pos += half
+    return pos
+  }, [])
+
+  const glideBy = useCallback((px: number) => {
+    glideRemainingRef.current += px
+  }, [])
+
+  const active = options.active
+  useEffect(() => {
+    if (!active) return
+    let raf = 0
+    let last = performance.now()
+    const readBack = optsRef.current.readBack
+    if (readBack) posRef.current = readBack()
+
+    const tick = (now: number) => {
+      const opts = optsRef.current
+      const dt = Math.min(now - last, 100) / 1000 // clamp tab-wake jumps
+      last = now
+
+      const paused = opts.isPaused(now)
+      // Ease the velocity toward its target (0 when paused) — smooth decel on
+      // pause, smooth accel on resume, always from the CURRENT position.
+      const targetSpeed = paused ? 0 : opts.speed
+      speedEnvRef.current += (targetSpeed - speedEnvRef.current) * Math.min(1, dt / 0.25)
+      if (targetSpeed === 0 && speedEnvRef.current < 0.5) speedEnvRef.current = 0
+
+      const external = opts.readBack ? opts.readBack() : null
+      const resync = () => {
+        if (external !== null && Math.abs(external - posRef.current) > RESYNC_EPSILON) {
+          posRef.current = external
+        }
+      }
+
+      const glide = glideRemainingRef.current
+      if (glide !== 0) {
+        // Ease-out toward the glide target; runs even while "paused" (the
+        // interaction that queued it sets its own suppress window).
+        resync()
+        const speed = Math.max(Math.abs(glide) * 6, 240) // px/s, proportional
+        const step = Math.sign(glide) * Math.min(Math.abs(glide), speed * dt)
+        glideRemainingRef.current = Math.abs(glide - step) < 0.5 ? 0 : glide - step
+        posRef.current = wrap(posRef.current + step)
+        opts.apply(posRef.current)
+      } else if (speedEnvRef.current > 0) {
+        // Resync after external movement (user scroll, seam warp).
+        resync()
+        posRef.current = wrap(posRef.current + speedEnvRef.current * dt)
+        opts.apply(posRef.current)
+      } else if (external !== null) {
+        // Idle: follow external movement so resumes start from where the
+        // user left the scroller.
+        posRef.current = external
+      }
+      opts.onAfterFrame?.()
+      raf = requestAnimationFrame(tick)
+    }
+    raf = requestAnimationFrame(tick)
+    return () => cancelAnimationFrame(raf)
+  }, [active, wrap])
+
+  return { posRef, glideBy, wrap }
+}

package/src/hooks/ui/use-suppress-clone-focus.ts

@@ -0,0 +1,61 @@
+'use client'
+
+import { useEffect, useRef } from 'react'
+
+// Every focusable a clone might contain — matched so it can be pulled out of the
+// keyboard tab order (see useSuppressCloneFocus). `[contenteditable]:not(
+// [contenteditable="false"])` catches the empty/`"true"`/`"plaintext-only"`
+// editable forms; `summary` is focusable inside a <details>.
+const CLONE_FOCUSABLE_SELECTOR =
+  'a[href],button,input,select,textarea,iframe,summary,audio[controls],video[controls],[tabindex],[contenteditable]:not([contenteditable="false"])'
+
+/**
+ * Keep a marquee clone's content pointer-CLICKABLE while taking it out of the
+ * accessibility tree and the keyboard tab order. Shared by every endless-loop
+ * surface that renders a second track copy (<CardsStrip> managed cells,
+ * <MarqueeWall> clone copies).
+ *
+ * `inert` (the previous approach) does all three at once: a11y-hidden,
+ * un-focusable AND un-clickable. That third effect was the "news marquee stops
+ * being clickable after you scroll it for a while" bug — the 2-copy endless
+ * loop ALWAYS paints clone cards inside the viewport near the copy seam, so a
+ * user who manually scrolls and parks there is looking at real-looking cards
+ * that silently swallow every click. Clones must therefore stay clickable (a
+ * click on ANY visible card must open its link — mouse, ⌘-click, middle-click
+ * and context-menu all handled natively by the clone's own anchor).
+ *
+ * The a11y contract is still met without `inert`: the caller keeps
+ * `aria-hidden` on the clone wrapper (out of the a11y tree) and this hook
+ * forces every focusable descendant to `tabindex="-1"` (out of the tab order →
+ * no duplicate tab stops, no aria-hidden-focus violation). Re-applied on
+ * subtree mutation. This is the standard loop-clone treatment used by
+ * Swiper/Splide.
+ */
+export function useSuppressCloneFocus(active: boolean) {
+  const ref = useRef<HTMLDivElement | null>(null)
+  useEffect(() => {
+    const root = ref.current
+    if (!root || !active) return
+    const suppress = () => {
+      root.querySelectorAll<HTMLElement>(CLONE_FOCUSABLE_SELECTOR).forEach(el => {
+        // Only stamp the ones not already stamped — avoids touching the DOM (and
+        // clobbering an intentional tabindex) on every mutation.
+        if (el.getAttribute('tabindex') !== '-1') el.setAttribute('tabindex', '-1')
+      })
+    }
+    suppress()
+    // Watch structure AND the attributes that can turn a descendant tabbable
+    // (an anchor gaining `href`, React restoring `tabindex="0"`, an element
+    // becoming editable, media gaining `controls`). The `!== '-1'` guard above
+    // makes our own tabindex writes a no-op, so the observer never loops.
+    const mo = new MutationObserver(suppress)
+    mo.observe(root, {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeFilter: ['href', 'tabindex', 'contenteditable', 'controls'],
+    })
+    return () => mo.disconnect()
+  }, [active])
+  return ref
+}

package/src/stories/MarqueeWall.stories.tsx

@@ -0,0 +1,132 @@
+import type { Meta, StoryObj } from '@storybook/nextjs-vite'
+import { MarqueeWall, useMarqueeSync } from '../components/ui/marquee-wall'
+
+// Arbitrary-children demo content: simple lockup tiles (the wall is
+// content-agnostic — chips, logos, feed rows all ride the same engine).
+const TILES = [
+  'Datto RMM',
+  'ConnectWise',
+  'HaloPSA',
+  'SentinelOne',
+  'Proofpoint',
+  'Veeam',
+  'Auvik',
+  'IT Glue',
+]
+
+function Tile({ label }: { label: string }) {
+  return (
+    <div className="flex h-16 w-48 shrink-0 items-center justify-center rounded-md border border-ods-border bg-ods-card text-h6 text-ods-text-secondary">
+      {label}
+    </div>
+  )
+}
+
+const meta: Meta<typeof MarqueeWall> = {
+  title: 'UI/MarqueeWall',
+  component: MarqueeWall,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'THE endless-scroll wall container — a clipped area whose content loops as a marquee along either axis, fading where the clip cuts. Transform-driven on the shared `useMarqueeEngine` core (no inner scroller). Auto-static when the content fits or under `prefers-reduced-motion`. `useMarqueeSync` pins multiple walls to one position driver; `trackId` publishes live offsets for FLIP-morph coordination.',
+      },
+    },
+  },
+  decorators: [
+    (Story) => (
+      <div className="bg-ods-bg p-[var(--spacing-system-xl)]">
+        <Story />
+      </div>
+    ),
+  ],
+}
+
+export default meta
+type Story = StoryObj<typeof MarqueeWall>
+
+/** Horizontal loop of arbitrary children with the default right fade. */
+export const Horizontal: Story = {
+  render: () => (
+    <MarqueeWall fade="right" copyGap="var(--spacing-system-mf)" className="w-full" contentClassName="flex items-center gap-[var(--spacing-system-mf)]">
+      {TILES.map(t => (
+        <Tile key={t} label={t} />
+      ))}
+    </MarqueeWall>
+  ),
+}
+
+/** Vertical loop (bottom fade → bottom→top travel) inside a height cap. */
+export const Vertical: Story = {
+  render: () => (
+    <div className="w-64 rounded-md border border-ods-border bg-ods-card p-[var(--spacing-system-mf)]">
+      <MarqueeWall
+        fade="bottom"
+        fadeColor="var(--color-bg-card)"
+        copyGap="var(--spacing-system-mf)"
+        className="max-h-[240px]"
+        contentClassName="flex flex-col gap-[var(--spacing-system-mf)]"
+      >
+        {TILES.map(t => (
+          <Tile key={t} label={t} />
+        ))}
+      </MarqueeWall>
+    </div>
+  ),
+}
+
+/** Two walls pinned to ONE position driver via `useMarqueeSync` — scroll
+ *  stays pixel-locked (the FreeTrialCTA resolve-strip mechanism). */
+export const SyncedPair: Story = {
+  render: function SyncedPairStory() {
+    const sync = useMarqueeSync()
+    return (
+      <div className="flex flex-col gap-[var(--spacing-system-mf)]">
+        {[0, 1].map(row => (
+          <MarqueeWall
+            key={row}
+            sync={sync}
+            axis="x"
+            copyGap="var(--spacing-system-mf)"
+            className="w-full"
+            contentClassName="flex items-center gap-[var(--spacing-system-mf)]"
+          >
+            {TILES.map(t => (
+              <Tile key={t} label={t} />
+            ))}
+          </MarqueeWall>
+        ))}
+      </div>
+    )
+  },
+}
+
+/** Plain mode — the consumer's opt-out: same wall, no motion, no fades. */
+export const Plain: Story = {
+  render: () => (
+    <MarqueeWall mode="plain" className="w-full" contentClassName="flex items-center gap-[var(--spacing-system-mf)]">
+      {TILES.map(t => (
+        <Tile key={t} label={t} />
+      ))}
+    </MarqueeWall>
+  ),
+}
+
+/** Reverse travel (content moves right) with a custom-size leading fade. */
+export const Reversed: Story = {
+  render: () => (
+    <MarqueeWall
+      reverse
+      fade={['left', 'right']}
+      fadeSize={{ left: 48 }}
+      copyGap="var(--spacing-system-mf)"
+      className="w-full"
+      contentClassName="flex items-center gap-[var(--spacing-system-mf)]"
+    >
+      {TILES.map(t => (
+        <Tile key={t} label={t} />
+      ))}
+    </MarqueeWall>
+  ),
+}

package/src/stories/QuickActionMarquee.stories.tsx

@@ -32,14 +32,14 @@ const meta: Meta<typeof QuickActionMarquee> = {
     docs: {
       description: {
         component:
-          'Endless horizontally-scrolling strip of quick-action chips (Figma fae/mingo marquee rows). The item list is padded to ≥6 chips and rendered twice so the `qa-marquee` keyframe’s `translateX(-50%)` loops seamlessly; the duplicate half is `aria-hidden` and never focusable. Pauses on hover (`pauseOnHover`, default on) and always under `prefers-reduced-motion`. Pass `onSelect` to make chips interactive buttons; omit it for a purely decorative strip.',
+          'Endless horizontally-scrolling strip of quick-action chips (Figma fae/mingo marquee rows) — a single-row preset of the shared `<MarqueeWall>` engine (the same rAF core as the card strips). The item list is padded to ≥12 chips and the wall clones the track for the seamless loop; the clone copy is `aria-hidden` and never focusable. Speed is in px/s (constant on-screen speed regardless of item count). Pauses on hover (`pauseOnHover`, default on) and always under `prefers-reduced-motion`. Pass `onSelect` to make chips interactive buttons; omit it for a purely decorative strip.',
       },
     },
   },
   argTypes: {
     items: { control: false },
     direction: { control: 'inline-radio', options: ['left', 'right'] },
-    duration: { control: { type: 'number', min: 5, max: 120, step: 5 } },
+    speed: { control: { type: 'number', min: 10, max: 200, step: 10 } },
     pauseOnHover: { control: 'boolean' },
     onSelect: { control: false },
   },
@@ -66,7 +66,7 @@ export const Default: Story = {
 /** The two Figma rows: fae (left) over mingo (right, reversed). */
 export const TwoRows: Story = {
   render: () => (
-    <div className="flex flex-col gap-4">
+    <div className="flex flex-col gap-[var(--spacing-system-mf)]">
       <QuickActionMarquee items={FAE_ITEMS} direction="left" onSelect={(i) => console.log(i.id)} />
       <QuickActionMarquee items={MINGO_ITEMS} direction="right" onSelect={(i) => console.log(i.id)} />
     </div>
@@ -93,8 +93,9 @@ export const Decorative: Story = {
 }
 
 /**
- * Fewer than 6 items — the track is auto-repeated up to the `MIN_TRACK_ITEMS`
- * heuristic so the halved loop still fills the viewport with no visible gap.
+ * Fewer than 12 items — the track is auto-repeated up to the `minChips`
+ * padding target so one copy always overflows the container and the loop
+ * engages.
  */
 export const FewItems: Story = {
   args: {
@@ -103,11 +104,11 @@ export const FewItems: Story = {
   },
 }
 
-/** Faster loop (`duration={15}`) and hover-pause disabled. */
+/** Faster scroll (`speed={120}` px/s) and hover-pause disabled. */
 export const FastNoPause: Story = {
   args: {
     items: FAE_ITEMS,
-    duration: 15,
+    speed: 120,
     pauseOnHover: false,
     onSelect: (item) => console.log('select', item.id),
   },

package/src/stories/QuickActionWall.stories.tsx

@@ -0,0 +1,116 @@
+import type { Meta, StoryObj } from '@storybook/nextjs-vite'
+import { QuickActionWall, interleave } from '../components/chat/quick-action-wall'
+import type { QuickActionChip } from '../components/chat/chat-quick-action-row'
+
+// A mixed IT/SEC stream (per-chip themes + lozenges) and a fae wall — the two
+// wall registers: category-classified deck panels vs agent-themed hero walls.
+const IT_ACTIONS: ReadonlyArray<QuickActionChip> = [
+  { id: 'reset-password', label: 'Reset a password', icon: { name: 'key' }, theme: 'it' },
+  { id: 'new-laptop', label: 'Provision a new laptop', icon: { name: 'laptop' }, theme: 'it' },
+  { id: 'printer', label: 'Fix the printer', icon: { name: 'printer' }, theme: 'it' },
+  { id: 'vpn', label: 'VPN will not connect', icon: { name: 'globe' }, theme: 'it' },
+  { id: 'disk-full', label: 'Disk almost full', icon: { name: 'hard-drive' }, theme: 'it' },
+  { id: 'onboard', label: 'Onboard a new hire', icon: { name: 'user-plus' }, theme: 'it' },
+]
+
+const SEC_ACTIONS: ReadonlyArray<QuickActionChip> = [
+  { id: 'phishing', label: 'Phishing report triage', icon: { name: 'fish' }, theme: 'sec' },
+  { id: 'mfa', label: 'Enforce MFA', icon: { name: 'shield-check' }, theme: 'sec' },
+  { id: 'patch', label: 'Patch the CVE', icon: { name: 'bug' }, theme: 'sec' },
+  { id: 'offboard', label: 'Revoke access on exit', icon: { name: 'user-minus' }, theme: 'sec' },
+  { id: 'edr-alert', label: 'EDR alert review', icon: { name: 'radar' }, theme: 'sec' },
+]
+
+const FAE_ACTIONS: ReadonlyArray<QuickActionChip> = [
+  { id: 'how-to-start', label: 'How to start', icon: { name: 'fae' } },
+  { id: 'connect-device', label: 'Connect device', icon: { name: 'search' }, theme: 'fae' },
+  { id: 'find-device', label: 'Find device', icon: { name: 'compass' }, theme: 'fae' },
+  { id: 'remote-connection', label: 'Remote connection', icon: { name: 'rocket' }, theme: 'fae' },
+  { id: 'run-scripts', label: 'Run scripts', icon: { name: 'bracket-curly' }, theme: 'fae' },
+  { id: 'device-software', label: 'Device software', icon: { name: 'package' }, theme: 'fae' },
+]
+
+const meta: Meta<typeof QuickActionWall> = {
+  title: 'Chat/QuickActionWall',
+  component: QuickActionWall,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'THE quick-action chip wall: a themed pile of the shared chip on the shared `<MarqueeWall>` engine. Static-with-fade when content fits (or `prefers-reduced-motion`); an endless marquee when it overflows — the axis follows the fade (`bottom` fade → content travels bottom→top; `right` fade → right→left). Themes: `fae`/`mingo` (agent identities) and `it`/`sec` (classification pair, with lozenges). Interactive chips pause the track on hover; clone-copy chips stay clickable with wrapper-level a11y. `rows` renders the brick-wall mode (stacked independent row marquees).',
+      },
+    },
+  },
+  decorators: [
+    (Story) => (
+      <div className="bg-ods-bg p-[var(--spacing-system-xl)]">
+        <Story />
+      </div>
+    ),
+  ],
+}
+
+export default meta
+type Story = StoryObj<typeof QuickActionWall>
+
+/** Vertical wall (bottom fade → bottom→top marquee): the deck-panel register —
+ *  mixed IT/SEC stream with lozenges, decorative chips. */
+export const VerticalMixedStream: Story = {
+  render: () => (
+    <div className="rounded-md border border-ods-border bg-ods-card p-[var(--spacing-system-mf)]">
+      <QuickActionWall
+        chips={interleave(IT_ACTIONS, SEC_ACTIONS)}
+        lozenges
+        fade="bottom"
+        fadeColor="var(--color-bg-card)"
+        className="max-h-[180px]"
+      />
+    </div>
+  ),
+}
+
+/** Horizontal wall (right fade): the hero-tab register — a wide fae wall
+ *  drifting right→left, interactive chips (hover pauses the track). */
+export const HorizontalInteractive: Story = {
+  render: () => (
+    <QuickActionWall
+      chips={FAE_ACTIONS.map((c, i) => ({ ...c, selected: i === 0, selectedAccent: 'pink', onSelect: () => console.log(c.id) }))}
+      fade="right"
+      className="w-full"
+      contentClassName="w-[1400px]"
+    />
+  ),
+}
+
+/** Plain mode — the consumer's opt-out: same chips and layout, no marquee,
+ *  no blur. */
+export const Plain: Story = {
+  render: () => (
+    <div className="rounded-md border border-ods-border bg-ods-card p-[var(--spacing-system-mf)]">
+      <QuickActionWall
+        chips={interleave(IT_ACTIONS, SEC_ACTIONS)}
+        mode="plain"
+        lozenges
+        className="max-h-[180px]"
+      />
+    </div>
+  ),
+}
+
+/** Loading: skeleton chips (1:1 geometry, lozenge slots reserved) — static
+ *  until real chips land. */
+export const Loading: Story = {
+  render: () => (
+    <div className="rounded-md border border-ods-border bg-ods-card p-[var(--spacing-system-mf)]">
+      <QuickActionWall
+        chips={[]}
+        loading
+        lozenges
+        fade="bottom"
+        fadeColor="var(--color-bg-card)"
+        className="max-h-[180px]"
+      />
+    </div>
+  ),
+}

package/tailwind.config.ts

@@ -375,18 +375,11 @@ const config: Config = {
           from: { opacity: "0" },
           to: { opacity: "1" },
         },
-        // Endless chip strip (QuickActionMarquee): the track renders its items
-        // twice, so -50% lands exactly one copy over for a seamless loop.
-        "qa-marquee": {
-          from: { transform: "translateX(0)" },
-          to: { transform: "translateX(-50%)" },
-        },
       },
       animation: {
         "accordion-down": "accordion-down 0.2s ease-out",
         "accordion-up": "accordion-up 0.2s ease-out",
         "fade-in": "fade-in 0.3s ease-out",
-        "qa-marquee": "qa-marquee var(--qa-marquee-duration,40s) linear infinite",
       },
     },
   },