@flamingo-stack/openframe-frontend-core 0.0.734 → 0.0.736

package/src/components/ui/fade-preview.tsx

@@ -56,7 +56,9 @@ export interface FadePreviewProps {
    * MEASURED to the bottom of item N (at every width). Implies `fixedHeight`, so
    * the block keeps that height loading or loaded, and "Show N more" counts the
    * items past N unless `hiddenCount` says otherwise. Until the list holds N
-   * items, `collapsedHeight` (or the height last measured) is kept.
+   * items, `collapsedHeight` (or the height last measured) is kept. The first
+   * paint (before any measure) is held for N up to 12; add rows to
+   * `UNMEASURED_ITEMS_CLASSES` for a longer preview.
    */
   visibleItems?: number;
   /**
@@ -80,6 +82,32 @@ const FILL_CLASSES: Record<string, string> = {
   lg: 'lg:absolute lg:inset-0',
 };
 
+/**
+ * Item mode before the first measure (the server's markup, and the page until it
+ * hydrates): the items past the first N are hidden by CSS, so the block is its
+ * collapsed height in the very first paint. Without it the whole list showed and
+ * the measure then cut it, which moved everything under it. Spelled out per N
+ * (Tailwind only emits classes it can read, and a `<style>` element is not
+ * allowed here: each rewrite relayouts the document), so it covers N up to
+ * `FADE_PREVIEW_MAX_UNMEASURED_ITEMS`; a larger N is clipped at the measure, as before.
+ */
+const UNMEASURED_ITEMS_CLASSES: Record<number, string> = {
+  1: '[&>*>*:nth-child(n+2)]:hidden',
+  2: '[&>*>*:nth-child(n+3)]:hidden',
+  3: '[&>*>*:nth-child(n+4)]:hidden',
+  4: '[&>*>*:nth-child(n+5)]:hidden',
+  5: '[&>*>*:nth-child(n+6)]:hidden',
+  6: '[&>*>*:nth-child(n+7)]:hidden',
+  7: '[&>*>*:nth-child(n+8)]:hidden',
+  8: '[&>*>*:nth-child(n+9)]:hidden',
+  9: '[&>*>*:nth-child(n+10)]:hidden',
+  10: '[&>*>*:nth-child(n+11)]:hidden',
+  11: '[&>*>*:nth-child(n+12)]:hidden',
+  12: '[&>*>*:nth-child(n+13)]:hidden',
+};
+/** The largest `visibleItems` the first paint is held for (the table above). */
+export const FADE_PREVIEW_MAX_UNMEASURED_ITEMS = 12;
+
 const cssLength = (value: number | string) => (typeof value === 'number' ? `${value}px` : value);
 
 export function FadePreview({
@@ -198,6 +226,7 @@ export function FadePreview({
         className={cn(
           'overflow-hidden transition-[max-height,height] duration-500',
           fill && FILL_CLASSES[String(fill)],
+          itemMode && itemsHeight == null && !expanded && UNMEASURED_ITEMS_CLASSES[visible],
         )}
         style={{
           transitionTimingFunction: 'cubic-bezier(0.33, 1, 0.68, 1)',

package/src/components/ui/index.ts

@@ -64,6 +64,7 @@ export * from './alert';
 export * from './badge';
 export * from './ai-generated-badge';
 export * from './fade-preview';
+export * from './layout-hold';
 export * from './progress';
 export * from './release-changelog-section';
 export * from './stacked-rows-panel';

package/src/components/ui/layout-hold.tsx

@@ -0,0 +1,55 @@
+import type { ReactNode } from 'react';
+import { cn } from '../../utils/cn';
+
+/**
+ * Holding a layout while its content is read, the two ways that are right at
+ * EVERY width. A placeholder of a guessed size (a `w-40` bar, a `h-[120px]`
+ * box) is only right at the widths it was tuned at: text wraps where the words
+ * make it wrap, so the placeholder has to be made of the words, or of the real
+ * layout, to wrap where the content will.
+ *
+ * - `TextHold`: an inline stand-in exactly as wide as the words it is given
+ *   (same font, same letter spacing, because it IS those words, not shown).
+ *   `bar` draws it as a pulsing grey bar; `blank` only keeps its space.
+ * - `LayoutHold`: a block as tall as the real layout rendered inside it, kept
+ *   invisible and inert: the layout's own height, at any width.
+ *
+ * Neither is shown or read out; both are removed for assistive technology.
+ */
+export interface TextHoldProps {
+  /** The words whose width is held (the content's own, or a stand-in of its length). */
+  children: ReactNode;
+  /** `bar`: a pulsing grey bar of that width. `blank`: the width only. */
+  variant?: 'bar' | 'blank';
+  className?: string;
+}
+
+export function TextHold({ children, variant = 'bar', className }: TextHoldProps) {
+  return (
+    <span
+      aria-hidden
+      className={cn(
+        variant === 'bar' ? 'animate-pulse rounded bg-ods-border text-transparent' : 'invisible',
+        // A hold is never selectable or clickable, whatever it wraps.
+        'pointer-events-none select-none',
+        className,
+      )}
+    >
+      {children}
+    </span>
+  );
+}
+
+export interface LayoutHoldProps {
+  /** The real layout, rendered with the data at hand. */
+  children: ReactNode;
+  className?: string;
+}
+
+export function LayoutHold({ children, className }: LayoutHoldProps) {
+  return (
+    <div aria-hidden inert className={cn('invisible', className)}>
+      {children}
+    </div>
+  );
+}

package/src/components/ui/snap-carousel.tsx

@@ -3,6 +3,7 @@
 import { type ReactNode, useCallback, useEffect, useRef, useState } from 'react';
 import { useAutoplay } from '../../hooks/ui/use-autoplay';
 import { useInView } from '../../hooks/ui/use-in-view';
+import { useResumableTimeout } from '../../hooks/ui/use-resumable-timeout';
 import { cn } from '../../utils/cn';
 import { Chevron02LeftIcon } from '../icons-v2-generated/arrows/chevron-02-left-icon';
 import { Chevron02RightIcon } from '../icons-v2-generated/arrows/chevron-02-right-icon';
@@ -39,20 +40,31 @@ export interface SnapCarouselProps<T> {
 const GAP_PX = 12;
 
 /**
- * The active dot filling up while the carousel waits to advance. A transition,
- * not a keyframe animation: it mounts empty and is told to be full one frame
- * later, taking the whole interval to get there.
+ * The active dot's fill: how much of the slide's wait has been run. It starts
+ * from where the wait stands (`ranMs`, nothing for a new slide) and runs to
+ * full over what is LEFT of it. While the carousel is not advancing it stands
+ * still at that point; it never empties because the carousel left the screen.
  */
-function DotFill({ durationMs }: { durationMs: number }) {
-  const [full, setFull] = useState(false);
+function DotFill({ durationMs, ranMs, running }: { durationMs: number; ranMs: number; running: boolean }) {
+  // One frame at the starting point, so the browser has it to run from.
+  const [going, setGoing] = useState(false);
   useEffect(() => {
-    const frame = requestAnimationFrame(() => setFull(true));
-    return () => cancelAnimationFrame(frame);
-  }, []);
+    if (!running) return undefined;
+    const frame = requestAnimationFrame(() => setGoing(true));
+    return () => {
+      cancelAnimationFrame(frame);
+      setGoing(false);
+    };
+  }, [running]);
+  const moving = running && going;
   return (
     <span
-      className="absolute inset-0 origin-left bg-ods-text-primary transition-transform ease-linear"
-      style={{ transform: full ? 'scaleX(1)' : 'scaleX(0)', transitionDuration: `${durationMs}ms` }}
+      className="absolute inset-0 origin-left bg-ods-text-primary ease-linear"
+      style={{
+        transform: `scaleX(${moving ? 1 : durationMs > 0 ? ranMs / durationMs : 0})`,
+        transitionProperty: moving ? 'transform' : 'none',
+        transitionDuration: `${Math.max(0, durationMs - ranMs)}ms`,
+      }}
     />
   );
 }
@@ -122,12 +134,15 @@ export function SnapCarousel<T>({
   const canAutoAdvance = autoAdvanceMs > 0 && count > 1;
   const playing = auto.playing && canAutoAdvance;
 
-  // Restarts on every slide change, so a swipe or an arrow is followed by a full interval.
-  useEffect(() => {
-    if (!playing) return undefined;
-    const timer = setTimeout(() => goTo(index >= count - 1 ? 0 : index + 1), autoAdvanceMs);
-    return () => clearTimeout(timer);
-  }, [playing, index, count, autoAdvanceMs, goTo]);
+  // A new slide starts a whole interval (a swipe or an arrow is followed by a
+  // full one); an interruption (off screen, a hold, another tab) only pauses it.
+  const ranMs = useResumableTimeout({
+    running: playing,
+    durationMs: autoAdvanceMs,
+    resetKey: index,
+    onElapsed: () => goTo(index >= count - 1 ? 0 : index + 1),
+  });
+  const showsWait = canAutoAdvance && !auto.reducedMotion;
 
   const setRefs = useCallback(
     (node: HTMLDivElement | null) => {
@@ -172,12 +187,13 @@ export function SnapCarousel<T>({
               className={cn(
                 'relative h-1.5 overflow-hidden rounded-full transition-[width] duration-200 motion-reduce:transition-none',
                 dotIndex === index ? 'w-6' : 'w-1.5',
-                dotIndex === index && !playing ? 'bg-ods-text-primary' : 'bg-ods-border',
+                // A carousel that never advances by itself marks its slide with a whole dot.
+                dotIndex === index && !showsWait ? 'bg-ods-text-primary' : 'bg-ods-border',
               )}
             >
-              {dotIndex === index && playing && (
-                // Re-keyed per slide so the fill restarts from empty.
-                <DotFill key={index} durationMs={autoAdvanceMs} />
+              {dotIndex === index && showsWait && (
+                // Re-keyed per slide so a NEW slide starts from empty; a pause keeps its place.
+                <DotFill key={index} durationMs={autoAdvanceMs} ranMs={ranMs} running={playing} />
               )}
             </span>
           ))}

package/src/components/unified-pagination.tsx

@@ -33,6 +33,17 @@ export function UnifiedPagination({
   const searchParams = useSearchParams();
   const pathname = usePathname();
 
+  /**
+   * The address of a page of this list: the current URL with `page` set. Page 1
+   * is the list's own address (no `page`), so the first page has one URL.
+   */
+  const pageHref = (page: number) => {
+    const params = new URLSearchParams(searchParams.toString());
+    if (page <= 1) params.delete('page');
+    else params.set('page', page.toString());
+    return withQuery(pathname, params.toString());
+  };
+
   const handlePageChange = (page: number) => {
     // Preserve current scroll position
     const currentScrollY = window.scrollY;
@@ -42,13 +53,12 @@ export function UnifiedPagination({
       onPageChange(page);
     }
 
-    // Update URL for bookmarking without navigation — unless the caller owns
-    // the URL (`syncUrl={false}`), in which case a second writer here would
-    // race the caller's own param write.
+    // Update the address bar in place (a bookmark, a shared link), unless the
+    // caller owns the URL (`syncUrl={false}`): a second writer here would race
+    // the caller's own param write. The address is the one the page's link
+    // carries (`pageHref`), so a click and a new-tab open land on the same URL.
     if (syncUrl) {
-      const params = new URLSearchParams(searchParams.toString());
-      params.set('page', page.toString());
-      window.history.replaceState(null, '', withQuery(pathname, params.toString()));
+      window.history.replaceState(null, '', pageHref(page));
     }
 
     // Restore scroll position after a brief delay to allow content to render
@@ -79,7 +89,13 @@ export function UnifiedPagination({
 
   return (
     <div className={className}>
-      <Pagination currentPage={currentPage} totalPages={totalPages} onPageChange={handlePageChange} />
+      {/* Real links only while this component owns `?page=`: a caller that owns the URL names its own parameter. */}
+      <Pagination
+        currentPage={currentPage}
+        totalPages={totalPages}
+        onPageChange={handlePageChange}
+        getPageHref={syncUrl ? pageHref : undefined}
+      />
     </div>
   );
 }

package/src/hooks/ui/index.ts

@@ -35,3 +35,4 @@ export * from './use-autoplay';
 export * from './use-active-section';
 export * from './use-nav-menus';
 export * from './use-visitor-os';
+export * from './use-resumable-timeout';

package/src/hooks/ui/use-resumable-timeout.ts

@@ -0,0 +1,55 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+
+export interface UseResumableTimeoutOptions {
+  /** The wait counts down only while this is true. */
+  running: boolean;
+  /** How long the whole wait is. */
+  durationMs: number;
+  /** A new value starts the wait over from nothing (the slide changed). */
+  resetKey: string | number;
+  /** Called once the whole wait has been run. */
+  onElapsed: () => void;
+}
+
+/**
+ * A wait that PAUSES instead of starting over: `durationMs` of time spent
+ * `running`, however many times it is interrupted. A carousel that scrolls off
+ * screen half-way through a slide comes back with half a slide left, not a
+ * whole one, and the bar that shows the wait picks up where it stopped.
+ *
+ * Returns how much of the wait had been run at the last stop (0 after a
+ * reset), which is what a progress bar draws while it is not running and
+ * where it resumes from.
+ */
+export function useResumableTimeout({ running, durationMs, resetKey, onElapsed }: UseResumableTimeoutOptions): number {
+  // What has been run so far, for the key it was run under. The ref is the
+  // clock's own memory (read when a stretch starts); the state is the same
+  // figure for whoever draws it.
+  const banked = useRef({ key: resetKey, ms: 0 });
+  const [shown, setShown] = useState({ key: resetKey, ms: 0 });
+
+  const onElapsedRef = useRef(onElapsed);
+  useEffect(() => {
+    onElapsedRef.current = onElapsed;
+  }, [onElapsed]);
+
+  useEffect(() => {
+    // A new key: the wait starts over.
+    if (banked.current.key !== resetKey) banked.current = { key: resetKey, ms: 0 };
+    if (!running) return undefined;
+    const startedAt = Date.now();
+    const timer = setTimeout(() => onElapsedRef.current(), Math.max(0, durationMs - banked.current.ms));
+    return () => {
+      clearTimeout(timer);
+      // Bank what this stretch ran.
+      const ms = Math.min(durationMs, banked.current.ms + (Date.now() - startedAt));
+      banked.current = { key: resetKey, ms };
+      setShown({ key: resetKey, ms });
+    };
+  }, [running, durationMs, resetKey]);
+
+  // Under another key (the slide changed) nothing has been run yet.
+  return shown.key === resetKey ? shown.ms : 0;
+}

package/src/hooks/use-scenario-player.ts

@@ -1,7 +1,8 @@
 'use client';
 
-import { useCallback, useEffect, useRef, useState } from 'react';
+import { useCallback, useState } from 'react';
 import { type AutoplayHoldProps, useAutoplay } from './ui/use-autoplay';
+import { useResumableTimeout } from './ui/use-resumable-timeout';
 
 /**
  * How soon the first step follows the moment the demo becomes playable (it
@@ -78,9 +79,10 @@ export interface UseScenarioPlayerResult {
  * not held by the visitor, motion allowed. Under reduced motion it parks on the last step
  * of the current scenario, and every scenario can still be read by choosing it.
  *
- * The moment it becomes playable, and at the top of every scenario (the
- * rotation moved on, or a tab was chosen), its first step follows within
- * `START_MS`, not a whole step later; from there every step takes `stepMs`.
+ * A step is `stepMs` of time spent playing: an interruption pauses it and it
+ * resumes with what was left (`useResumableTimeout`, the one clock every timed
+ * thing here runs on). At the top of a scenario whose first step is the empty
+ * stage, that step is left within `START_MS`.
  *
  * A visitor's own choice (`go`, `setStep`) moves the clock there and lets go of
  * any hold; the rotation carries on from that point.
@@ -110,34 +112,28 @@ export function useScenarioPlayer({
   const [started, setStarted] = useState(false);
   if (playing && !started) setStarted(true);
 
-  // True from the moment it becomes playable until its first tick has been scheduled.
-  const starting = useRef(false);
-  const wasPlaying = useRef(false);
-  useEffect(() => {
-    if (playing && !wasPlaying.current) starting.current = true;
-    wasPlaying.current = playing;
-    if (!playing) return undefined;
-    const atEnd = rawStep >= lastStep;
-    // The first step comes quickly, both after it becomes playable and at the
-    // top of every scenario whose step 0 is the empty stage (the rotation
-    // moved on, or the visitor chose a tab): a stage that sits empty for a
-    // whole step after a tap reads as not responding. A finished scenario still
-    // holds its full time: it is there to be read.
-    const quickStart = emptyFirstStep && (starting.current || rawStep === 0) && !atEnd;
-    starting.current = false;
-    const timer = setTimeout(
-      () => {
-        if (atEnd) {
-          setScenario(current => (current + 1) % scenarioCount);
-          setRawStep(0);
-        } else {
-          setRawStep(current => Math.min(current, lastStep) + 1);
-        }
-      },
-      atEnd ? holdMs : quickStart ? Math.min(START_MS, stepMs) : stepMs,
-    );
-    return () => clearTimeout(timer);
-  }, [playing, rawStep, lastStep, stepMs, holdMs, scenario, scenarioCount, emptyFirstStep]);
+  // ONE clock for everything that waits and moves on (`useResumableTimeout`,
+  // the carousel's too): a step is `stepMs` of time spent PLAYING. Interrupted
+  // (off screen, held, another tab), it comes back with what was left of the
+  // step, never a whole new one and never a skipped one.
+  const atEnd = rawStep >= lastStep;
+  // Step 0 of a scenario whose first step is the empty stage is left at once:
+  // a stage that sits empty for a whole step after a tap reads as not
+  // responding. A finished scenario holds its full time: it is there to be read.
+  const leavesAtOnce = emptyFirstStep && rawStep === 0 && !atEnd;
+  useResumableTimeout({
+    running: playing,
+    durationMs: atEnd ? holdMs : leavesAtOnce ? Math.min(START_MS, stepMs) : stepMs,
+    resetKey: `${scenario}:${Math.min(rawStep, lastStep)}`,
+    onElapsed: () => {
+      if (atEnd) {
+        setScenario(current => (current + 1) % scenarioCount);
+        setRawStep(0);
+      } else {
+        setRawStep(current => Math.min(current, lastStep) + 1);
+      }
+    },
+  });
 
   // A visitor's choice is an instruction to play from there: it lets go of any hold.
   const setStep = useCallback(