@marimo-team/islands 0.23.16-dev4 → 0.23.16-dev6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marimo-team/islands",
-  "version": "0.23.16-dev4",
+  "version": "0.23.16-dev6",
   "main": "dist/main.js",
   "types": "dist/index.d.ts",
   "type": "module",

package/src/components/slides/__tests__/slide-scroll-hint.test.tsx

@@ -0,0 +1,198 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { act, render, screen } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  shouldShowScrollHint,
+  SlideScrollContainer,
+} from "../slide-scroll-hint";
+
+describe("shouldShowScrollHint", () => {
+  it("shows when content overflows and scroll is at the top", () => {
+    expect(
+      shouldShowScrollHint({
+        scrollHeight: 800,
+        clientHeight: 400,
+        scrollTop: 0,
+      }),
+    ).toBe(true);
+  });
+
+  it("hides when content fits", () => {
+    expect(
+      shouldShowScrollHint({
+        scrollHeight: 300,
+        clientHeight: 400,
+        scrollTop: 0,
+      }),
+    ).toBe(false);
+  });
+
+  it("hides after the user scrolls down", () => {
+    expect(
+      shouldShowScrollHint({
+        scrollHeight: 800,
+        clientHeight: 400,
+        scrollTop: 40,
+      }),
+    ).toBe(false);
+  });
+
+  it("ignores sub-pixel overflow", () => {
+    expect(
+      shouldShowScrollHint({
+        scrollHeight: 401,
+        clientHeight: 400,
+        scrollTop: 0,
+      }),
+    ).toBe(false);
+  });
+
+  it("still shows within the top threshold", () => {
+    expect(
+      shouldShowScrollHint({
+        scrollHeight: 800,
+        clientHeight: 400,
+        scrollTop: 8,
+      }),
+    ).toBe(true);
+  });
+});
+
+describe("SlideScrollContainer", () => {
+  const resizeObservers: Array<{
+    callback: ResizeObserverCallback;
+    observe: ReturnType<typeof vi.fn>;
+    disconnect: ReturnType<typeof vi.fn>;
+  }> = [];
+
+  beforeEach(() => {
+    resizeObservers.length = 0;
+    vi.stubGlobal("requestAnimationFrame", (cb: FrameRequestCallback) => {
+      cb(0);
+      return 0;
+    });
+    vi.stubGlobal("cancelAnimationFrame", vi.fn());
+    vi.stubGlobal(
+      "ResizeObserver",
+      class MockResizeObserver {
+        callback: ResizeObserverCallback;
+        observe = vi.fn();
+        unobserve = vi.fn();
+        disconnect = vi.fn();
+
+        constructor(callback: ResizeObserverCallback) {
+          this.callback = callback;
+          resizeObservers.push(this);
+        }
+      },
+    );
+    vi.stubGlobal(
+      "MutationObserver",
+      class MockMutationObserver {
+        observe = vi.fn();
+        disconnect = vi.fn();
+        takeRecords = vi.fn(() => []);
+      },
+    );
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  function stubOverflow(
+    el: HTMLElement,
+    metrics: {
+      scrollHeight: number;
+      clientHeight: number;
+      scrollTop?: number;
+    },
+  ) {
+    Object.defineProperty(el, "scrollHeight", {
+      configurable: true,
+      get: () => metrics.scrollHeight,
+    });
+    Object.defineProperty(el, "clientHeight", {
+      configurable: true,
+      get: () => metrics.clientHeight,
+    });
+    Object.defineProperty(el, "scrollTop", {
+      configurable: true,
+      get: () => metrics.scrollTop ?? 0,
+      set: (value: number) => {
+        metrics.scrollTop = value;
+      },
+    });
+  }
+
+  it("renders a scroll hint when content overflows", () => {
+    render(
+      <SlideScrollContainer>
+        <div>tall content</div>
+      </SlideScrollContainer>,
+    );
+
+    const container = screen.getByTestId("slide-scroll-container");
+    stubOverflow(container, { scrollHeight: 900, clientHeight: 400 });
+
+    act(() => {
+      for (const observer of resizeObservers) {
+        observer.callback([], observer as unknown as ResizeObserver);
+      }
+    });
+
+    expect(screen.getByTestId("slide-scroll-hint")).toBeTruthy();
+    expect(screen.getByText("Scroll for more")).toBeTruthy();
+  });
+
+  it("hides the hint after scrolling", () => {
+    const metrics = {
+      scrollHeight: 900,
+      clientHeight: 400,
+      scrollTop: 0,
+    };
+
+    render(
+      <SlideScrollContainer>
+        <div>tall content</div>
+      </SlideScrollContainer>,
+    );
+
+    const container = screen.getByTestId("slide-scroll-container");
+    stubOverflow(container, metrics);
+
+    act(() => {
+      for (const observer of resizeObservers) {
+        observer.callback([], observer as unknown as ResizeObserver);
+      }
+    });
+    expect(screen.getByTestId("slide-scroll-hint")).toBeTruthy();
+
+    act(() => {
+      metrics.scrollTop = 50;
+      container.dispatchEvent(new Event("scroll"));
+    });
+
+    expect(screen.queryByTestId("slide-scroll-hint")).toBeNull();
+  });
+
+  it("does not show a hint when content fits", () => {
+    render(
+      <SlideScrollContainer>
+        <div>short content</div>
+      </SlideScrollContainer>,
+    );
+
+    const container = screen.getByTestId("slide-scroll-container");
+    stubOverflow(container, { scrollHeight: 200, clientHeight: 400 });
+
+    act(() => {
+      for (const observer of resizeObservers) {
+        observer.callback([], observer as unknown as ResizeObserver);
+      }
+    });
+
+    expect(screen.queryByTestId("slide-scroll-hint")).toBeNull();
+  });
+});

package/src/components/slides/reveal-component.tsx

@@ -14,6 +14,7 @@ import { CodeIcon, ExpandIcon, EyeOffIcon } from "lucide-react";
 import { Deck, Fragment, Slide, Stack } from "@revealjs/react";
 import { Panel, PanelGroup, PanelResizeHandle } from "react-resizable-panels";
 import { Slide as CellOutputSlide } from "@/components/slides/slide";
+import { SlideScrollContainer } from "@/components/slides/slide-scroll-hint";
 import { Button } from "@/components/ui/button";
 import { useFullScreenElement } from "@/components/ui/fullscreen";
 import { Tooltip } from "@/components/ui/tooltip";
@@ -327,7 +328,7 @@ const SubslideView = ({
 
   return (
     <Slide>
-      <div className="h-full w-full overflow-auto flex">
+      <SlideScrollContainer>
         <div
           className={
             anyCodeShown
@@ -367,7 +368,7 @@ const SubslideView = ({
             return <ReactFragment key={i}>{rendered}</ReactFragment>;
           })}
         </div>
-      </div>
+      </SlideScrollContainer>
       {/* Outside any `.fragment`: shown only before any fragment is revealed. */}
       {slideLevel && <NotesAside text={slideLevel} />}
     </Slide>

package/src/components/slides/slide-scroll-hint.tsx

@@ -0,0 +1,161 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { ChevronDownIcon } from "lucide-react";
+import {
+  type ReactNode,
+  type RefObject,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
+import { cn } from "@/utils/cn";
+
+/** Pixels of scroll before the hint is considered dismissed. */
+const TOP_THRESHOLD_PX = 8;
+/** Ignore sub-pixel overflow from rounding / borders. */
+const OVERFLOW_TOLERANCE_PX = 1;
+
+/**
+ * Whether a scroll container should show a "more content below" affordance.
+ * Visible only when content overflows and the viewport is still near the top.
+ */
+export function shouldShowScrollHint(options: {
+  scrollHeight: number;
+  clientHeight: number;
+  scrollTop: number;
+}): boolean {
+  const { scrollHeight, clientHeight, scrollTop } = options;
+  const overflowing = scrollHeight > clientHeight + OVERFLOW_TOLERANCE_PX;
+  const atTop = scrollTop <= TOP_THRESHOLD_PX;
+  return overflowing && atTop;
+}
+
+/**
+ * Measure only up to the first unrevealed fragment so
+ * the hint reflects currently revealed content, not future fragment steps.
+ */
+function measureRevealedHeight(el: HTMLElement): number {
+  const firstUnrevealed = el.querySelector<HTMLElement>(
+    ".fragment:not(.visible)",
+  );
+  if (!firstUnrevealed) {
+    return el.scrollHeight;
+  }
+  const fragmentTop = firstUnrevealed.getBoundingClientRect().top;
+  return fragmentTop - el.getBoundingClientRect().top + el.scrollTop;
+}
+
+/**
+ * Tracks whether a scroll container is overflowing at the top, so we can
+ * surface a scroll affordance.
+ */
+function useScrollHint(
+  scrollRef: RefObject<HTMLElement | null>,
+  contentRef: RefObject<HTMLElement | null>,
+): boolean {
+  const [showHint, setShowHint] = useState(false);
+
+  useEffect(() => {
+    const el = scrollRef.current;
+    const content = contentRef.current;
+    if (!el || !content) {
+      return;
+    }
+
+    let frame = 0;
+    const update = () => {
+      cancelAnimationFrame(frame);
+      frame = requestAnimationFrame(() => {
+        setShowHint(
+          shouldShowScrollHint({
+            scrollHeight: measureRevealedHeight(el),
+            clientHeight: el.clientHeight,
+            scrollTop: el.scrollTop,
+          }),
+        );
+      });
+    };
+
+    update();
+
+    const resizeObserver = new ResizeObserver(update);
+    resizeObserver.observe(el);
+    resizeObserver.observe(content);
+
+    // Fragments reveal via class changes (opacity/visibility, no layout shift),
+    // which the ResizeObserver can't see, so re-check on class mutations. Only
+    // attach on slides that have fragments to avoid reacting to unrelated class
+    // churn (e.g. animating widgets) on the common non-fragment slide.
+    const fragmentObserver = content.querySelector(".fragment")
+      ? new MutationObserver(update)
+      : null;
+    fragmentObserver?.observe(content, {
+      subtree: true,
+      attributes: true,
+      attributeFilter: ["class"],
+    });
+
+    el.addEventListener("scroll", update, { passive: true });
+
+    return () => {
+      cancelAnimationFrame(frame);
+      resizeObserver.disconnect();
+      fragmentObserver?.disconnect();
+      el.removeEventListener("scroll", update);
+    };
+  }, [scrollRef, contentRef]);
+
+  return showHint;
+}
+
+const ScrollHintOverlay = ({ className }: { className?: string }) => {
+  return (
+    <div
+      className={cn(
+        "pointer-events-none absolute inset-x-0 bottom-0 z-10 flex flex-col items-center",
+        "animate-in fade-in-0 duration-200",
+        className,
+      )}
+      data-testid="slide-scroll-hint"
+      aria-hidden={true}
+    >
+      <div className="h-16 w-full bg-linear-to-t from-background via-background/80 to-transparent" />
+      <div className="absolute bottom-3 flex items-center gap-1 rounded-full border border-border/60 bg-background/90 px-2.5 py-1 text-xs text-muted-foreground shadow-sm backdrop-blur-sm">
+        <ChevronDownIcon className="h-3.5 w-3.5" />
+        <span>Scroll for more</span>
+      </div>
+    </div>
+  );
+};
+
+/**
+ * Full-height scroll container for a slide. Shows a dismissible "Scroll for
+ * more" cue when content overflows the frame (easy to miss in fullscreen when
+ * OS overlay scrollbars are hidden).
+ */
+export const SlideScrollContainer = ({
+  children,
+  className,
+}: {
+  children: ReactNode;
+  className?: string;
+}) => {
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const contentRef = useRef<HTMLDivElement>(null);
+  const showHint = useScrollHint(scrollRef, contentRef);
+
+  return (
+    <div className={cn("relative h-full w-full", className)}>
+      <div
+        ref={scrollRef}
+        className="h-full w-full overflow-auto"
+        data-testid="slide-scroll-container"
+      >
+        <div ref={contentRef} className="flex w-full min-h-full">
+          {children}
+        </div>
+      </div>
+      {showHint && <ScrollHintOverlay />}
+    </div>
+  );
+};