@ankhorage/zora 25.5.0 → 25.6.0

package/src/features/grid-view/adapters/inbound/TileGrid.tsx

@@ -1,3 +1,4 @@
+import type { GridViewport } from '@ankhorage/grid-view';
 import React from 'react';
 import { View as NativeView } from 'react-native';
 
@@ -13,20 +14,29 @@ export function TileGrid({
   tileSize = 120,
   gap = 12,
   zoom = 1,
+  viewport,
+  defaultViewport,
+  viewportConstraints,
+  zoomLimits,
   overscanPixels,
   focusedItemId,
   revealPaddingPixels,
   onColumnsChange,
+  onViewportChange,
   onVisibleItemIdsChange,
   renderItem,
   interactionPolicy,
   testID,
 }: TileGridProps) {
   const [measuredWidth, setMeasuredWidth] = React.useState(0);
+  const [uncontrolledPixelsPerUnitX, setUncontrolledPixelsPerUnitX] = React.useState(
+    () => defaultViewport?.pixelsPerUnitX ?? zoom,
+  );
   const resolvedWidth = width ?? measuredWidth;
+  const pixelsPerUnitX = viewport?.pixelsPerUnitX ?? uncontrolledPixelsPerUnitX;
   const layout = React.useMemo(
-    () => layoutTileGrid(items, resolvedWidth, tileSize, gap, zoom),
-    [items, resolvedWidth, tileSize, gap, zoom],
+    () => layoutTileGrid(items, resolvedWidth, tileSize, gap, pixelsPerUnitX),
+    [gap, items, pixelsPerUnitX, resolvedWidth, tileSize],
   );
   const itemLookup = React.useMemo(() => new Map(items.map((item) => [item.id, item])), [items]);
 
@@ -34,6 +44,14 @@ export function TileGrid({
     if (resolvedWidth > 0) onColumnsChange?.(layout.columns);
   }, [layout.columns, onColumnsChange, resolvedWidth]);
 
+  const handleViewportChange = React.useCallback(
+    (nextViewport: GridViewport) => {
+      if (viewport === undefined) setUncontrolledPixelsPerUnitX(nextViewport.pixelsPerUnitX);
+      onViewportChange?.(nextViewport);
+    },
+    [onViewportChange, viewport],
+  );
+
   return (
     <NativeView
       onLayout={(event) => setMeasuredWidth(event.nativeEvent.layout.width)}
@@ -43,12 +61,14 @@ export function TileGrid({
       {resolvedWidth > 0 ? (
         <GridView
           contentHeight={layout.height}
-          contentWidth={Math.max(resolvedWidth / zoom, layout.width)}
+          contentWidth={Math.max(resolvedWidth / pixelsPerUnitX, layout.width)}
+          defaultViewport={defaultViewport}
           height={height}
           focusedItemId={focusedItemId}
           interactionPolicy={interactionPolicy}
           items={layout.items}
           onVisibleItemIdsChange={onVisibleItemIdsChange}
+          onViewportChange={handleViewportChange}
           overscanPixels={overscanPixels}
           renderItem={(item) => {
             const source = itemLookup.get(item.id);
@@ -56,6 +76,9 @@ export function TileGrid({
           }}
           revealPaddingPixels={revealPaddingPixels}
           width={resolvedWidth}
+          viewport={viewport}
+          viewportConstraints={viewportConstraints}
+          zoomLimits={zoomLimits}
           zoom={zoom}
         />
       ) : null}

package/src/features/time-grid/adapters/inbound/TimeGrid.test.tsx

@@ -105,22 +105,49 @@ test('keeps mounted interval and virtualized variable-height lane labels synchro
     expect(arrowDown.defaultPrevented).toBe(true);
     expect(focusedIds).toEqual(['strings']);
 
-    const verticalScroller = Array.from(host.querySelectorAll<HTMLElement>('div')).find(
-      (element) =>
-        element.getAttribute('style') === 'width: 200px; height: 30px;' &&
-        Array.from(element.querySelectorAll('div')).some(
-          (child) => child.getAttribute('style') === 'width: 200px; height: 180px;',
-        ),
+    const verticalScroller = host.querySelector<HTMLElement>(
+      '[data-testid="time-grid-viewport-vertical-scroll"]',
     );
     if (!verticalScroller) throw new Error('Missing GridView vertical scroller');
-    Object.defineProperty(verticalScroller, 'scrollTop', { configurable: true, value: 60 });
+    verticalScroller.scrollTop = 60;
     void act(() => verticalScroller.dispatchEvent(new browser.Event('scroll', { bubbles: true })));
 
-    expect(viewportOffsets).toContain(30);
+    expect(viewportOffsets).toEqual([30]);
     expect(host.querySelector('[data-testid="time-grid-lane-label-drums"]')).toBeNull();
     expect(
       host.querySelector('[data-testid="time-grid-lane-label-bass"]')?.getAttribute('style'),
     ).toContain('top: -20px');
+
+    act(() => {
+      root.render(
+        <TimeGrid
+          contentWidth={100}
+          focusedIntervalId="strings"
+          height={30}
+          intervals={[
+            { extent: 10, id: 'drums', laneId: 'drums', start: 0 },
+            { extent: 10, id: 'strings', laneId: 'strings', start: 0 },
+          ]}
+          lanes={[
+            { height: 20, id: 'drums' },
+            { height: 40, id: 'bass' },
+            { height: 30, id: 'strings' },
+          ]}
+          onFocusedIntervalIdChange={(id) => focusedIds.push(id)}
+          onViewportChange={(viewport) => viewportOffsets.push(viewport.offsetY)}
+          overscanPixels={0}
+          renderInterval={(interval, selected) => (
+            <span data-selected={selected}>{interval.id}</span>
+          )}
+          renderLaneLabel={(lane) => <span>{lane.id}</span>}
+          selectedIntervalIds={['strings']}
+          testID="time-grid"
+          width={100}
+          zoom={2}
+        />,
+      );
+    });
+    expect(viewportOffsets).toEqual([30, 56]);
     await new Promise((resolve) => setTimeout(resolve, 100));
   } finally {
     act(() => root.unmount());

package/src/types/grid-view.ts

@@ -1,4 +1,9 @@
-import type { GridRectItem, GridViewport } from '@ankhorage/grid-view';
+import type {
+  GridRectItem,
+  GridViewport,
+  GridViewportConstraints,
+  GridZoomLimits,
+} from '@ankhorage/grid-view';
 import type React from 'react';
 
 import type { ZoraBaseProps } from './base';
@@ -10,6 +15,20 @@ export interface GridViewProps extends ZoraBaseProps {
   contentHeight: number;
   width: number;
   height: number;
+  /**
+   * Canonical controlled world viewport. Supplying this value makes `onViewportChange`
+   * report interaction proposals without mutating renderer-owned state.
+   */
+  viewport?: GridViewport;
+  /** Initial world position and independent axis scales for uncontrolled rendering. */
+  defaultViewport?: Partial<
+    Pick<GridViewport, 'offsetX' | 'offsetY' | 'pixelsPerUnitX' | 'pixelsPerUnitY'>
+  >;
+  /** Finite world bounds and optional overscroll for panning and focused-item reveal. */
+  viewportConstraints?: GridViewportConstraints;
+  /** Independent X/Y scale limits applied to focal-point zoom interactions. */
+  zoomLimits?: GridZoomLimits;
+  /** @deprecated Use `defaultViewport` for new code. */
   zoom?: number;
   overscanPixels?: number;
   /** Stable item identity that must be scrolled into view without duplicating viewport geometry. */
@@ -34,11 +53,18 @@ export interface TileGridProps extends ZoraBaseProps {
   tileSize?: number;
   gap?: number;
   zoom?: number;
+  viewport?: GridViewport;
+  defaultViewport?: Partial<
+    Pick<GridViewport, 'offsetX' | 'offsetY' | 'pixelsPerUnitX' | 'pixelsPerUnitY'>
+  >;
+  viewportConstraints?: GridViewportConstraints;
+  zoomLimits?: GridZoomLimits;
   overscanPixels?: number;
   focusedItemId?: string;
   revealPaddingPixels?: number;
   /** Reports the same measured column count used to position tiles. */
   onColumnsChange?: (columns: number) => void;
+  onViewportChange?: (viewport: GridViewport) => void;
   onVisibleItemIdsChange?: (ids: readonly string[]) => void;
   renderItem: (item: TileGridItem) => React.ReactNode;
 }

package/web-dist/chunks/{Accordion-0my2z6qe.js → Accordion-ebghcyzj.js}

@@ -143,6 +143,18 @@ function isAlignment(value) {
   return value === "start" || value === "center" || value === "end";
 }
 
+// node_modules/@ankhorage/grid-view/dist/features/viewport/panViewport.js
+function panViewport(viewport, displacement, constraints) {
+  if (![displacement.x, displacement.y].every(Number.isFinite)) {
+    throw new RangeError("Pan displacement must be finite.");
+  }
+  return constrainViewport({
+    ...viewport,
+    offsetX: viewport.offsetX - displacement.x / viewport.pixelsPerUnitX,
+    offsetY: viewport.offsetY - displacement.y / viewport.pixelsPerUnitY
+  }, constraints);
+}
+
 // node_modules/@ankhorage/grid-view/dist/features/viewport/revealWorldRect.js
 function revealWorldRect(viewport, rect, paddingPixels = 0, constraints) {
   validateRevealInput(viewport, rect, paddingPixels);
@@ -192,6 +204,34 @@ function worldToViewport(point, viewport) {
   };
 }
 
+// node_modules/@ankhorage/grid-view/dist/features/viewport/zoomViewportAt.js
+function zoomViewportAt(viewport, focalPoint, nextScale, limits = {}, constraints) {
+  if (![focalPoint.x, focalPoint.y, nextScale.pixelsPerUnitX, nextScale.pixelsPerUnitY].every(Number.isFinite)) {
+    throw new RangeError("Focal points and scales must be finite.");
+  }
+  const focalWorld = viewportToWorld(focalPoint, viewport);
+  const x = constrainScale(nextScale.pixelsPerUnitX, limits.minX, limits.maxX);
+  const y = constrainScale(nextScale.pixelsPerUnitY, limits.minY, limits.maxY);
+  return constrainViewport({
+    ...viewport,
+    pixelsPerUnitX: x,
+    pixelsPerUnitY: y,
+    offsetX: focalWorld.x - focalPoint.x / x,
+    offsetY: focalWorld.y - focalPoint.y / y
+  }, constraints);
+}
+function constrainScale(scale, minimum, maximum) {
+  const min = minimum ?? Number.EPSILON;
+  const max = maximum ?? Infinity;
+  if (!Number.isFinite(min) || min <= 0 || maximum !== undefined && (!Number.isFinite(max) || max <= 0 || min > max)) {
+    throw new RangeError("Zoom limits must be finite positive ranges.");
+  }
+  if (scale <= 0) {
+    throw new RangeError("Viewport scales must be positive.");
+  }
+  return Math.max(min, Math.min(max, scale));
+}
+
 // node_modules/@ankhorage/grid-view/dist/features/axes/getAxisCategoryTicks.js
 function getAxisCategoryTicks(viewport, axis, categories) {
   const bounds = getVisibleWorldBounds(viewport);
@@ -290,4 +330,4 @@ function validateUniqueIds(intervals) {
 function intersects(firstStart, firstExtent, secondStart, secondExtent) {
   return firstStart <= secondStart + secondExtent && firstStart + firstExtent >= secondStart;
 }
-export { getAxisCategoryTicks, getAxisTicks, getVisibleGridItems, getLaneIntervalPlacement, getVisibleLaneIntervals, revealWorldRect, worldToViewport };
+export { getAxisCategoryTicks, getAxisTicks, getVisibleGridItems, getLaneIntervalPlacement, getVisibleLaneIntervals, constrainViewport, panViewport, revealWorldRect, worldToViewport, zoomViewportAt };

package/web-dist/chunks/{Accordion-d6azgz09.js → Accordion-f43jba23.js}

@@ -1,7 +1,7 @@
 'use client';
 import {
   TileGrid2
-} from "./Accordion-gxj5qbpr.js";
+} from "./Accordion-q8exgc3h.js";
 import {
   withZoraThemeScope
 } from "./Accordion-42jfy1a1.js";