@marimo-team/islands 0.23.3-dev9 → 0.23.3

package/src/components/slides/compose-slides.ts

@@ -0,0 +1,337 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import type { SlideType } from "../editor/renderers/slides-layout/types";
+
+/**
+ * A contiguous run of cells that render together on a single subslide.
+ *
+ * - `isFragment=false`: cells are emitted inline in the <Slide>.
+ * - `isFragment=true`:  cells are wrapped in a single <Fragment> so they reveal
+ *   as one step.
+ */
+export interface ComposedBlock<T> {
+  isFragment: boolean;
+  cells: T[];
+}
+
+/**
+ * One <Slide>. Vertical stacking is expressed at the Stack level.
+ */
+export interface ComposedSubslide<T> {
+  blocks: ComposedBlock<T>[];
+}
+
+/**
+ * One horizontal position in the deck.
+ *
+ * - `subslides.length === 1` -> render as a single <Slide>.
+ * - `subslides.length > 1`  -> render as <Stack><Slide/>...</Stack>.
+ */
+export interface ComposedStack<T> {
+  subslides: ComposedSubslide<T>[];
+}
+
+export interface Composition<T> {
+  stacks: ComposedStack<T>[];
+}
+
+/**
+ * Groups a flat list of cells into a tree of stacks / subslides / blocks based
+ * on each cell's {@link SlideType}.
+ *
+ * Inspired by the RISE JupyterLab extension's `markupSlides`, but adapted for a
+ * declarative React renderer: instead of mutating DOM during the walk, we
+ * produce a tree the caller can render however they like.
+ *
+ * Callers are responsible for normalizing "no type set" to a concrete
+ * {@link SlideType} before getting here — the convention in this codebase is
+ * that a cell with no configured type is a `"slide"`.
+ *
+ * Rules (per cell):
+ * - `"slide"`     -> open a new stack + subslide, cell goes in a plain block.
+ * - `"sub-slide"` -> open a new subslide inside the current stack.
+ * - `"fragment"`  -> open a new fragment block inside the current subslide.
+ * - `"skip"`      -> dropped entirely. If a caller wants to preserve these,
+ *                    they can remap the type in `getType`.
+ *
+ * If the very first cell is a `fragment` or `sub-slide`, a containing stack /
+ * subslide is created implicitly.
+ */
+export function composeSlides<T>({
+  cells,
+  getType,
+}: {
+  cells: readonly T[];
+  getType: (cell: T) => SlideType;
+}): Composition<T> {
+  const stacks: ComposedStack<T>[] = [];
+  let stack: ComposedStack<T> | null = null;
+  let subslide: ComposedSubslide<T> | null = null;
+
+  const openStack = (): ComposedStack<T> => {
+    const next: ComposedStack<T> = { subslides: [] };
+    stacks.push(next);
+    stack = next;
+    subslide = null;
+    return next;
+  };
+  const openSubslide = (): ComposedSubslide<T> => {
+    const parent = stack ?? openStack();
+    const next: ComposedSubslide<T> = { blocks: [] };
+    parent.subslides.push(next);
+    subslide = next;
+    return next;
+  };
+  const openBlock = (isFragment: boolean): ComposedBlock<T> => {
+    const parent = subslide ?? openSubslide();
+    const next: ComposedBlock<T> = { isFragment, cells: [] };
+    parent.blocks.push(next);
+    return next;
+  };
+
+  for (const cell of cells) {
+    const type = getType(cell);
+
+    switch (type) {
+      case "skip":
+        break;
+      case "slide":
+        openStack();
+        openSubslide();
+        openBlock(false).cells.push(cell);
+        break;
+      case "sub-slide":
+        openSubslide();
+        openBlock(false).cells.push(cell);
+        break;
+      case "fragment":
+        openBlock(true).cells.push(cell);
+        break;
+    }
+  }
+
+  return { stacks };
+}
+
+/**
+ * A location within the composed tree. Mirrors reveal.js's `{h, v, f}` indices
+ * so callers can feed it directly to `Reveal.slide(h, v, f?)`.
+ *
+ * - `h`: stack index
+ * - `v`: subslide index within that stack
+ * - `f`: fragment block index within the subslide, or `-1` for non-fragment
+ *   cells (i.e. content that's visible before any fragment is revealed).
+ */
+export interface SlideTarget {
+  h: number;
+  v: number;
+  f: number;
+}
+
+export interface SlideIndices<Id> {
+  /** Where each cell lives in the deck. */
+  cellToTarget: Map<Id, SlideTarget>;
+  /**
+   * `"h,v,f"` -> flat index into the original cell list. The value is the
+   * "active" cell for that position — i.e. the last cell currently visible
+   * on screen, so the active cell advances as the user steps through
+   * fragments.
+   *
+   * `f === -1` represents "nothing revealed yet" and is always populated when
+   * a subslide exists, so it doubles as a fallback for subslides that have
+   * no fragments at all (reveal reports `f === 0` in that case).
+   */
+  targetToCellIndex: Map<string, number>;
+}
+
+/**
+ * Build {@link SlideIndices} for a composition so callers can translate
+ * between a flat cell list and reveal.js's `{h, v, f}` indices.
+ */
+export function buildSlideIndices<T, Id>({
+  composition,
+  cells,
+  getId,
+}: {
+  composition: Composition<T>;
+  cells: readonly T[];
+  getId: (cell: T) => Id;
+}): SlideIndices<Id> {
+  const cellToTarget = new Map<Id, SlideTarget>();
+  const targetToCellIndex = new Map<string, number>();
+  const cellIndexById = new Map<Id, number>();
+  for (const [i, cell] of cells.entries()) {
+    cellIndexById.set(getId(cell), i);
+  }
+
+  composition.stacks.forEach((stack, h) => {
+    stack.subslides.forEach((sub, v) => {
+      // f = -1: "nothing revealed yet" state. Active cell = last cell that
+      // appears before the first fragment block. If the subslide starts with
+      // a fragment block, fall back to its first cell so we still have an
+      // anchor when nothing is visible yet.
+      let preFragmentActiveId: Id | undefined;
+      for (const block of sub.blocks) {
+        if (block.isFragment) {
+          break;
+        }
+        const last = block.cells.at(-1);
+        if (last) {
+          preFragmentActiveId = getId(last);
+        }
+      }
+      if (preFragmentActiveId === undefined) {
+        const fallback = sub.blocks[0]?.cells[0];
+        if (fallback) {
+          preFragmentActiveId = getId(fallback);
+        }
+      }
+      if (preFragmentActiveId !== undefined) {
+        const idx = cellIndexById.get(preFragmentActiveId);
+        if (idx != null) {
+          targetToCellIndex.set(`${h},${v},-1`, idx);
+        }
+      }
+
+      let fragmentCounter = -1;
+      for (const block of sub.blocks) {
+        if (block.isFragment) {
+          fragmentCounter++;
+          for (const cell of block.cells) {
+            cellToTarget.set(getId(cell), { h, v, f: fragmentCounter });
+          }
+          const last = block.cells.at(-1);
+          if (last) {
+            const idx = cellIndexById.get(getId(last));
+            if (idx != null) {
+              targetToCellIndex.set(`${h},${v},${fragmentCounter}`, idx);
+            }
+          }
+        } else {
+          for (const cell of block.cells) {
+            cellToTarget.set(getId(cell), { h, v, f: -1 });
+          }
+        }
+      }
+    });
+  });
+  return { cellToTarget, targetToCellIndex };
+}
+
+/**
+ * Resolve the flat cell index for the current reveal indices. For slides
+ * without fragments reveal may report `f = 0`, so we fall back to the `-1`
+ * entry (which is always populated when a subslide exists).
+ */
+export function resolveActiveCellIndex(
+  targetToCellIndex: ReadonlyMap<string, number>,
+  indices: { h: number; v: number; f: number },
+): number | undefined {
+  const { h, v, f } = indices;
+  return (
+    targetToCellIndex.get(`${h},${v},${f}`) ??
+    targetToCellIndex.get(`${h},${v},-1`)
+  );
+}
+
+function findDeckTarget<T, Id>({
+  start,
+  stop,
+  step,
+  cells,
+  cellToTarget,
+  getId,
+}: {
+  start: number;
+  stop: number;
+  step: 1 | -1;
+  cells: readonly T[];
+  cellToTarget: ReadonlyMap<Id, SlideTarget>;
+  getId: (cell: T) => Id;
+}): SlideTarget | undefined {
+  for (let i = start; i !== stop; i += step) {
+    const target = cellToTarget.get(getId(cells[i]));
+    if (target) {
+      return target;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Resolve the deck location that should back the currently selected minimap
+ * entry.
+ *
+ * Cells marked `"skip"` are not part of the composed deck; for those we
+ * "park" on the closest real slide in notebook order (preferring the
+ * predecessor). Handling the UI consequences of parking — ignoring reveal.js
+ * echo events and intercepting keyboard nav — is the caller's job.
+ */
+export function resolveDeckNavigationTarget<T, Id>({
+  activeIndex,
+  cells,
+  cellToTarget,
+  getId,
+}: {
+  activeIndex: number | undefined;
+  cells: readonly T[];
+  cellToTarget: ReadonlyMap<Id, SlideTarget>;
+  getId: (cell: T) => Id;
+}): SlideTarget | undefined {
+  if (activeIndex == null) {
+    return undefined;
+  }
+
+  const activeCell = cells[activeIndex];
+  if (!activeCell) {
+    return undefined;
+  }
+
+  const directTarget = cellToTarget.get(getId(activeCell));
+  if (directTarget) {
+    return directTarget;
+  }
+
+  return (
+    findDeckTarget({
+      start: activeIndex - 1,
+      stop: -1,
+      step: -1,
+      cells,
+      cellToTarget,
+      getId,
+    }) ??
+    findDeckTarget({
+      start: activeIndex + 1,
+      stop: cells.length,
+      step: 1,
+      cells,
+      cellToTarget,
+      getId,
+    })
+  );
+}
+
+/**
+ * Decide where the deck should navigate to given the user's target cell, or
+ * `null` if the deck is already there (so the caller can skip the imperative
+ * `deck.slide()` call).
+ *
+ * Each minimap entry is a distinct navigation target, so the fragment index
+ * is always pinned:
+ *   - fragment cells (`target.f >= 0`) advance to that fragment
+ *   - non-fragment cells reset to `f = -1` so any revealed fragments on the
+ *     destination slide collapse — otherwise jumping to the parent slide
+ *     from elsewhere in the deck leaves fragments looking "completed"
+ *     instead of clean.
+ */
+export function computeDeckNavigation(
+  current: { h: number; v: number; f: number },
+  target: SlideTarget,
+): SlideTarget | null {
+  const next = { h: target.h, v: target.v, f: target.f >= 0 ? target.f : -1 };
+  if (current.h === next.h && current.v === next.v && current.f === next.f) {
+    return null;
+  }
+  return next;
+}

package/src/components/slides/minimap.tsx

@@ -5,7 +5,10 @@ import type { CellId } from "@/core/cells/ids";
 import type { CellColumnId } from "@/utils/id-tree";
 import { useEffect, useRef, useState } from "react";
 import type { ICellRendererProps } from "../editor/renderers/types";
-import type { SlidesLayout } from "../editor/renderers/slides-layout/types";
+import type {
+  SlideType,
+  SlidesLayout,
+} from "../editor/renderers/slides-layout/types";
 import {
   DndContext,
   DragOverlay,
@@ -29,8 +32,10 @@ import {
 import { restrictToVerticalAxis } from "@dnd-kit/modifiers";
 import { cn } from "@/utils/cn";
 import { Slide } from "./slide";
-import { InfoIcon } from "lucide-react";
+import { InfoIcon, type LucideIcon } from "lucide-react";
+import { Tooltip } from "@/components/ui/tooltip";
 import { Logger } from "@/utils/Logger";
+import { SLIDE_TYPE_OPTIONS_BY_VALUE } from "./slide-form";
 
 type Props = ICellRendererProps<SlidesLayout>;
 type SlideCell = Props["cells"][number];
@@ -48,34 +53,65 @@ interface ResolvedDropTarget {
   index: number;
 }
 
+interface ThumbnailDimensions {
+  width: number;
+  height: number;
+  scale: number;
+}
+
 interface SlideThumbnailCardProps extends React.HTMLAttributes<HTMLDivElement> {
   cell: SlideCell;
+  dimensions: ThumbnailDimensions;
   isActiveSlide?: boolean;
   isActiveDragSource?: boolean;
   isOverlay?: boolean;
   isVisible?: boolean;
+  slideType?: SlideType;
   ref?: React.Ref<HTMLDivElement>;
 }
 
 interface SlideThumbnailRowProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
   cell: SlideCell;
+  dimensions: ThumbnailDimensions;
   isActiveSlide?: boolean;
   dropIndicator?: DropPosition | null;
   isActiveDragSource?: boolean;
   isVisible?: boolean;
+  slideType?: SlideType;
   ref?: React.Ref<HTMLButtonElement>;
 }
 
 interface SlidesMinimapProps {
   cells: SlideCell[];
+  thumbnailWidth: number;
   canReorder: boolean;
   activeCellId: CellId | null;
+  // Set of cell ids that are marked `skip` in the slides layout.
+  skippedIds?: ReadonlySet<CellId>;
+  slideTypes?: ReadonlyMap<CellId, SlideType>;
   onSlideClick: (index: number) => void;
 }
 
-const THUMBNAIL_WIDTH = 256;
-const THUMBNAIL_HEIGHT = 144;
-const THUMBNAIL_SCALE = 0.3;
+function getSlideTypeVisual(
+  slideType: SlideType | undefined,
+): { label: string; description: string; Icon: LucideIcon } | null {
+  if (!slideType || slideType === "slide") {
+    return null;
+  }
+  const { label, description, Icon } = SLIDE_TYPE_OPTIONS_BY_VALUE[slideType];
+  return { label, description, Icon };
+}
+
+const SLIDE_ASPECT_RATIO = 16 / 9;
+const SLIDE_BASE_WIDTH = 960;
+
+function computeThumbnailDimensions(width: number): ThumbnailDimensions {
+  return {
+    width,
+    height: width / SLIDE_ASPECT_RATIO,
+    scale: width / SLIDE_BASE_WIDTH,
+  };
+}
 const MINIMAP_AUTO_SCROLL = {
   threshold: { x: 0, y: 0.1 },
 };
@@ -156,8 +192,11 @@ function useVisibleCellIds(
 
 export const SlidesMinimap = ({
   cells,
+  thumbnailWidth,
   canReorder,
   activeCellId,
+  skippedIds,
+  slideTypes,
   onSlideClick,
 }: SlidesMinimapProps) => {
   const cellIds = useCellIds();
@@ -168,6 +207,7 @@ export const SlidesMinimap = ({
   const [dropTarget, setDropTarget] = useState<ProjectedDropTarget | null>(
     null,
   );
+  const dimensions = computeThumbnailDimensions(thumbnailWidth);
 
   useEffect(() => {
     if (!activeCellId || !containerRef.current) {
@@ -245,8 +285,14 @@ export const SlidesMinimap = ({
           <SlideThumbnailRow
             key={cell.id}
             cell={cell}
+            dimensions={dimensions}
             isActiveSlide={cell.id === activeCellId}
             isVisible={visibleIds.has(cell.id)}
+            slideType={resolveSlideType({
+              cellId: cell.id,
+              slideTypes,
+              skippedIds,
+            })}
             onClick={() => onSlideClick(index)}
           />
         ))}
@@ -275,9 +321,15 @@ export const SlidesMinimap = ({
             <SortableSlideThumbnail
               key={cell.id}
               cell={cell}
+              dimensions={dimensions}
               isActive={activeId === cell.id}
               isActiveSlide={cell.id === activeCellId}
               isVisible={visibleIds.has(cell.id)}
+              slideType={resolveSlideType({
+                cellId: cell.id,
+                slideTypes,
+                skippedIds,
+              })}
               dropIndicator={
                 dropTarget?.overId === cell.id && activeId !== cell.id
                   ? dropTarget.position
@@ -292,6 +344,7 @@ export const SlidesMinimap = ({
         {activeCell && (
           <SlideThumbnailCard
             cell={activeCell}
+            dimensions={dimensions}
             isOverlay={true}
             isActiveDragSource={true}
           />
@@ -320,19 +373,23 @@ const SlideThumbnailsContainer = ({
 
 interface SortableSlideThumbnailProps {
   cell: SlideCell;
+  dimensions: ThumbnailDimensions;
   dropIndicator?: DropPosition | null;
   isActive: boolean;
   isActiveSlide?: boolean;
   isVisible?: boolean;
+  slideType?: SlideType;
   onClick?: () => void;
 }
 
 const SortableSlideThumbnail = ({
   cell,
+  dimensions,
   dropIndicator,
   isActive,
   isActiveSlide,
   isVisible,
+  slideType,
   onClick,
 }: SortableSlideThumbnailProps) => {
   const { attributes, listeners, setNodeRef } = useSortable({
@@ -343,10 +400,12 @@ const SortableSlideThumbnail = ({
     <SlideThumbnailRow
       ref={setNodeRef}
       cell={cell}
+      dimensions={dimensions}
       dropIndicator={dropIndicator}
       isActiveDragSource={isActive}
       isActiveSlide={isActiveSlide}
       isVisible={isVisible}
+      slideType={slideType}
       onClick={onClick}
       {...attributes}
       {...listeners}
@@ -356,12 +415,14 @@ const SortableSlideThumbnail = ({
 
 const SlideThumbnailRow = ({
   cell,
+  dimensions,
   className,
   style,
   dropIndicator,
   isActiveSlide = false,
   isActiveDragSource = false,
   isVisible,
+  slideType,
   onClick,
   ref,
   ...props
@@ -397,9 +458,11 @@ const SlideThumbnailRow = ({
       )}
       <SlideThumbnailCard
         cell={cell}
+        dimensions={dimensions}
         isActiveSlide={isActiveSlide}
         isActiveDragSource={isActiveDragSource}
         isVisible={isVisible}
+        slideType={slideType}
       />
     </button>
   );
@@ -407,24 +470,30 @@ const SlideThumbnailRow = ({
 
 const SlideThumbnailCard = ({
   cell,
+  dimensions,
   className,
   style,
   isActiveSlide = false,
   isActiveDragSource = false,
   isOverlay = false,
   isVisible = false,
+  slideType,
   ref,
   ...props
 }: SlideThumbnailCardProps) => {
+  const { width, height, scale } = dimensions;
+  const visual = getSlideTypeVisual(slideType);
+  const isSkipped = slideType === "skip";
+
   const outerStyle: React.CSSProperties = {
-    width: THUMBNAIL_WIDTH,
-    height: THUMBNAIL_HEIGHT,
+    width,
+    height,
     contain: "strict",
     ...(isOverlay
       ? null
       : {
           contentVisibility: "auto",
-          containIntrinsicSize: `${THUMBNAIL_WIDTH}px ${THUMBNAIL_HEIGHT}px`,
+          containIntrinsicSize: `${width}px ${height}px`,
         }),
     ...style,
   };
@@ -435,7 +504,7 @@ const SlideThumbnailCard = ({
     <div
       ref={ref}
       className={cn(
-        "border-2 shrink-0 rounded-md relative select-none bg-background cursor-pointer active:cursor-grabbing",
+        "border-2 shrink-0 rounded-md relative select-none bg-background cursor-pointer active:cursor-grabbing overflow-hidden",
         isActiveSlide || isActiveDragSource || isOverlay
           ? "border-blue-500"
           : "border-border",
@@ -450,15 +519,41 @@ const SlideThumbnailCard = ({
         <div
           className="flex p-6 box-border pointer-events-none mo-slide-content overflow-hidden"
           style={{
-            transform: `scale(${THUMBNAIL_SCALE})`,
+            transform: `scale(${scale})`,
             transformOrigin: "top left",
-            width: THUMBNAIL_WIDTH / THUMBNAIL_SCALE,
-            height: THUMBNAIL_HEIGHT / THUMBNAIL_SCALE,
+            width: width / scale,
+            height: height / scale,
           }}
         >
           <Slide cellId={cell.id} status={cell.status} output={cell.output} />
         </div>
       )}
+      {isSkipped && (
+        <div
+          className="absolute inset-0 bg-muted/60 pointer-events-none"
+          aria-hidden={true}
+        />
+      )}
+      {visual && (
+        <Tooltip
+          content={
+            <span className="text-xs opacity-80">{visual.description}</span>
+          }
+        >
+          <span
+            className={cn(
+              "absolute top-1 right-1 flex items-center gap-1 rounded-full border p-0.5 font-medium leading-none shadow-xs cursor-help",
+              isSkipped
+                ? "bg-background/90 border-border text-muted-foreground"
+                : "bg-background/95 border-border text-foreground/80",
+            )}
+            aria-label={visual.label}
+          >
+            <visual.Icon className="h-3.5 w-3.5" />
+            {/* <span>{visual.label}</span> */}
+          </span>
+        </Tooltip>
+      )}
     </div>
   );
 };
@@ -527,6 +622,32 @@ function asCellId(id: UniqueIdentifier): CellId | null {
   return typeof id === "string" ? (id as CellId) : null;
 }
 
+/**
+ * Resolves the effective slide type for a cell. Falls back to `"skip"` if the
+ * caller-supplied `skippedIds` set marks the cell as skipped, which keeps this
+ * component working when only the legacy `skippedIds` prop is provided.
+ * Returns `undefined` for the default `"slide"` type so callers can skip
+ * rendering any badge.
+ */
+function resolveSlideType({
+  cellId,
+  slideTypes,
+  skippedIds,
+}: {
+  cellId: CellId;
+  slideTypes: ReadonlyMap<CellId, SlideType> | undefined;
+  skippedIds: ReadonlySet<CellId> | undefined;
+}): SlideType | undefined {
+  const type = slideTypes?.get(cellId);
+  if (type && type !== "slide") {
+    return type;
+  }
+  if (skippedIds?.has(cellId)) {
+    return "skip";
+  }
+  return undefined;
+}
+
 export const exportedForTesting = {
   useVisibleCellIds,
   projectDropTarget,