@ankhorage/zora 25.4.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/registry/ZORA_COMPONENT_REGISTRY.ts

@@ -77,6 +77,7 @@ import {
 } from '../tabletop/public';
 import { Tab, TabList, TabPanel, Tabs } from '../tabs/public';
 import { ThemeModeToggle } from '../theme/adapters/inbound/ThemeModeToggle';
+import { TimeGrid } from '../time-grid/public';
 import { TimePicker } from '../time-picker/public';
 import { Timeline } from '../timeline/public';
 import { Toast } from '../toast/public';
@@ -200,6 +201,7 @@ const _ZORA_COMPONENT_REGISTRY = {
   GridRuler,
   GridView,
   TileGrid,
+  TimeGrid,
   MediaExplorer,
   Hero,
   List,

package/src/features/registry/componentMeta.ts

@@ -99,6 +99,7 @@ import { tabMeta } from '../tabs/tabMeta';
 import { tabPanelMeta } from '../tabs/tabPanelMeta';
 import { tabsMeta } from '../tabs/tabsMeta';
 import { themeModeToggleMeta } from '../theme/ThemeModeToggle.meta';
+import { timeGridMeta } from '../time-grid/meta';
 import { timePickerMeta } from '../time-picker/timePickerMeta';
 import { timelineMeta } from '../timeline/meta';
 import { toastMeta } from '../toast/toastMeta';
@@ -204,6 +205,7 @@ export const ZORA_COMPONENT_META: ZoraComponentMetaRegistry = finalizeFeatureMet
   GridRuler: gridRulerMeta,
   GridView: gridViewMeta,
   TileGrid: tileGridMeta,
+  TimeGrid: timeGridMeta,
   Hero: heroMeta,
   List: listMeta,
   ListItem: listItemMeta,

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

@@ -0,0 +1,158 @@
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import React, { act } from 'react';
+import { createRoot } from 'react-dom/client';
+
+import type { TimeGridProps } from '../../../../types/time-grid';
+
+const webDistRoot = join(import.meta.dir, '../../../../../web-dist');
+
+function load(path: string) {
+  return import(pathToFileURL(join(webDistRoot, path)).href);
+}
+
+function installBrowserGlobals(browser: Window): () => void {
+  const keys = [
+    'window',
+    'document',
+    'Node',
+    'navigator',
+    'ShadowRoot',
+    'IS_REACT_ACT_ENVIRONMENT',
+  ] as const;
+  const previous = keys.map(
+    (key) => [key, Object.getOwnPropertyDescriptor(globalThis, key)] as const,
+  );
+  Object.assign(globalThis, {
+    IS_REACT_ACT_ENVIRONMENT: true,
+    Node: browser.Node,
+    ShadowRoot: browser.ShadowRoot,
+    document: browser.document,
+    navigator: browser.navigator,
+    window: browser,
+  });
+  return () => {
+    for (const [key, descriptor] of previous) {
+      if (descriptor) Object.defineProperty(globalThis, key, descriptor);
+      else Reflect.deleteProperty(globalThis, key);
+    }
+  };
+}
+
+test('keeps mounted interval and virtualized variable-height lane labels synchronized with GridView scrolling', async () => {
+  const browser = new Window();
+  const restore = installBrowserGlobals(browser);
+  const host = document.createElement('div');
+  document.body.append(host);
+  const root = createRoot(host);
+  const { TimeGrid } = (await load('components/time-grid/TimeGrid.js')) as {
+    TimeGrid: React.ComponentType<TimeGridProps>;
+  };
+  const focusedIds: string[] = [];
+  const viewportOffsets: number[] = [];
+
+  try {
+    act(() => {
+      root.render(
+        <TimeGrid
+          contentWidth={100}
+          focusedIntervalId="drums"
+          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={['drums']}
+          testID="time-grid"
+          width={100}
+          zoom={2}
+        />,
+      );
+    });
+
+    expect(host.querySelector('[data-testid="time-grid-interval-drums"]')?.textContent).toBe(
+      'drums',
+    );
+    expect(host.querySelector('[data-testid="time-grid-interval-strings"]')).toBeNull();
+    expect(
+      host.querySelector('[data-testid="time-grid-lane-label-drums"]')?.getAttribute('style'),
+    ).toContain('height: 40px');
+    expect(host.querySelector('[data-testid="time-grid-lane-label-bass"]')).toBeNull();
+
+    const interval = host.querySelector<HTMLElement>('[data-testid="time-grid-interval-drums"]');
+    if (!interval) throw new Error('Missing mounted interval');
+    const arrowDown = new browser.KeyboardEvent('keydown', {
+      bubbles: true,
+      cancelable: true,
+      key: 'ArrowDown',
+    });
+    void act(() => interval.dispatchEvent(arrowDown));
+    expect(arrowDown.defaultPrevented).toBe(true);
+    expect(focusedIds).toEqual(['strings']);
+
+    const verticalScroller = host.querySelector<HTMLElement>(
+      '[data-testid="time-grid-viewport-vertical-scroll"]',
+    );
+    if (!verticalScroller) throw new Error('Missing GridView vertical scroller');
+    verticalScroller.scrollTop = 60;
+    void act(() => verticalScroller.dispatchEvent(new browser.Event('scroll', { bubbles: true })));
+
+    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());
+    host.remove();
+    browser.close();
+    restore();
+  }
+});

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

@@ -0,0 +1,197 @@
+import { getLaneIntervalPlacement, type GridViewport } from '@ankhorage/grid-view';
+import React from 'react';
+import { Pressable, View } from 'react-native';
+
+import type { TimeGridProps } from '../../../../types/time-grid';
+import { GridView } from '../../../grid-view/public';
+import { resolveTimeGridNextFocusId } from '../../application/resolveTimeGridNextFocusId';
+import { resolveTimeGridVisibleIntervals } from '../../application/resolveTimeGridVisibleIntervals';
+import { TimeGridKeyboardProxy } from './TimeGridKeyboardProxy';
+
+/*** Presents virtualized variable-height interval lanes through ZORA's shared GridView renderer. */
+export function TimeGrid({
+  contentWidth,
+  focusedIntervalId,
+  height,
+  interactionPolicy,
+  intervals,
+  lanes,
+  onFocusedIntervalIdChange,
+  onIntervalPress,
+  onViewportChange,
+  onVisibleIntervalIdsChange,
+  overscanPixels,
+  renderInterval,
+  renderLaneLabel,
+  revealPaddingPixels,
+  selectedIntervalIds = [],
+  testID,
+  width,
+  zoom,
+}: TimeGridProps) {
+  const scale = Math.max(0.01, zoom ?? 1);
+  const [scrollOffsets, setScrollOffsets] = React.useState(() => ({
+    offsetX: 0,
+    offsetY: 0,
+  }));
+  const viewport = React.useMemo<GridViewport>(
+    () => ({
+      ...scrollOffsets,
+      height,
+      pixelsPerUnitX: scale,
+      pixelsPerUnitY: scale,
+      width,
+    }),
+    [height, scale, scrollOffsets, width],
+  );
+  const intervalById = React.useMemo(
+    () => new Map(intervals.map((interval) => [interval.id, interval])),
+    [intervals],
+  );
+  const selectedIds = React.useMemo(() => new Set(selectedIntervalIds), [selectedIntervalIds]);
+  const contentHeight = React.useMemo(
+    () => lanes.reduce((total, lane) => total + lane.height, 0),
+    [lanes],
+  );
+  const visibleIntervals = React.useMemo(
+    () => resolveTimeGridVisibleIntervals(lanes, intervals, viewport, overscanPixels),
+    [intervals, lanes, overscanPixels, viewport],
+  );
+  const focusedPlacement = React.useMemo(() => {
+    const focusedInterval = intervals.find((interval) => interval.id === focusedIntervalId);
+    return focusedInterval ? getLaneIntervalPlacement(lanes, focusedInterval) : undefined;
+  }, [focusedIntervalId, intervals, lanes]);
+  const gridItems = React.useMemo(
+    () =>
+      focusedPlacement && !visibleIntervals.some((interval) => interval.id === focusedPlacement.id)
+        ? [...visibleIntervals, focusedPlacement]
+        : visibleIntervals,
+    [focusedPlacement, visibleIntervals],
+  );
+  const labelIntervals = React.useMemo(
+    () =>
+      lanes.map((lane) => ({
+        extent: contentWidth,
+        id: `lane-label-${lane.id}`,
+        laneId: lane.id,
+        start: 0,
+      })),
+    [contentWidth, lanes],
+  );
+  const visibleLabels = React.useMemo(
+    () => resolveTimeGridVisibleIntervals(lanes, labelIntervals, viewport, overscanPixels),
+    [labelIntervals, lanes, overscanPixels, viewport],
+  );
+
+  const handleViewportChange = React.useCallback(
+    (nextViewport: GridViewport) => {
+      setScrollOffsets((current) =>
+        current.offsetX === nextViewport.offsetX && current.offsetY === nextViewport.offsetY
+          ? current
+          : { offsetX: nextViewport.offsetX, offsetY: nextViewport.offsetY },
+      );
+      onViewportChange?.(nextViewport);
+    },
+    [onViewportChange],
+  );
+
+  const resolveNextFocusId = React.useCallback(
+    (intervalId: string, direction: 'down' | 'left' | 'right' | 'up') => {
+      const allIntervals = resolveTimeGridVisibleIntervals(lanes, intervals, {
+        height: contentHeight,
+        offsetX: 0,
+        offsetY: 0,
+        pixelsPerUnitX: 1,
+        pixelsPerUnitY: 1,
+        width: contentWidth,
+      });
+      return resolveTimeGridNextFocusId(allIntervals, intervalId, direction);
+    },
+    [contentHeight, contentWidth, intervals, lanes],
+  );
+
+  return (
+    <View style={{ flexDirection: 'row', height, width }} testID={testID}>
+      {renderLaneLabel ? (
+        <View
+          accessibilityElementsHidden
+          pointerEvents="none"
+          style={{ height, overflow: 'hidden' }}
+        >
+          {visibleLabels.map((placement) => {
+            const lane = lanes[placement.laneIndex];
+            if (!lane) return null;
+            return (
+              <View
+                key={lane.id}
+                style={{
+                  height: placement.height * scale,
+                  position: 'absolute',
+                  top: (placement.y - viewport.offsetY) * scale,
+                }}
+                testID={testID === undefined ? undefined : `${testID}-lane-label-${lane.id}`}
+              >
+                {renderLaneLabel(lane)}
+              </View>
+            );
+          })}
+        </View>
+      ) : null}
+      <GridView
+        contentHeight={contentHeight}
+        contentWidth={contentWidth}
+        focusedItemId={focusedIntervalId}
+        height={height}
+        interactionPolicy={interactionPolicy}
+        items={gridItems}
+        onViewportChange={handleViewportChange}
+        onVisibleItemIdsChange={onVisibleIntervalIdsChange}
+        overscanPixels={overscanPixels}
+        renderItem={(placement) => {
+          const interval = intervalById.get(placement.id);
+          if (!interval) return null;
+          const selected = selectedIds.has(interval.id);
+          return (
+            <TimeGridKeyboardProxy
+              onKeyDown={(key) => {
+                const direction = resolveKeyboardDirection(key);
+                const nextId =
+                  direction === undefined ? undefined : resolveNextFocusId(interval.id, direction);
+                if (!nextId) return false;
+                onFocusedIntervalIdChange?.(nextId);
+                return true;
+              }}
+            >
+              <Pressable
+                accessibilityLabel={`Interval ${interval.id}`}
+                accessibilityRole="button"
+                disabled={interactionPolicy === 'passive'}
+                onPress={() => {
+                  onFocusedIntervalIdChange?.(interval.id);
+                  onIntervalPress?.(interval);
+                }}
+                style={{ flex: 1 }}
+                testID={testID === undefined ? undefined : `${testID}-interval-${interval.id}`}
+              >
+                {renderInterval(interval, selected)}
+              </Pressable>
+            </TimeGridKeyboardProxy>
+          );
+        }}
+        revealPaddingPixels={revealPaddingPixels}
+        testID={testID === undefined ? undefined : `${testID}-viewport`}
+        width={width}
+        zoom={zoom}
+      />
+    </View>
+  );
+}
+
+/*** Maps desktop arrow keys to the platform-neutral interval navigation directions. */
+function resolveKeyboardDirection(key: string): 'down' | 'left' | 'right' | 'up' | undefined {
+  if (key === 'ArrowDown') return 'down';
+  if (key === 'ArrowLeft') return 'left';
+  if (key === 'ArrowRight') return 'right';
+  if (key === 'ArrowUp') return 'up';
+  return undefined;
+}

package/src/features/time-grid/adapters/inbound/TimeGridKeyboardProxy.native.tsx

@@ -0,0 +1,11 @@
+import type React from 'react';
+
+/*** Preserves native activation and touch interaction where DOM arrow-key events do not exist. */
+export function TimeGridKeyboardProxy({ children }: TimeGridKeyboardProxyProps) {
+  return <>{children}</>;
+}
+
+interface TimeGridKeyboardProxyProps {
+  readonly children: React.ReactNode;
+  readonly onKeyDown: (key: string) => boolean;
+}

package/src/features/time-grid/adapters/inbound/TimeGridKeyboardProxy.tsx

@@ -0,0 +1,11 @@
+import type React from 'react';
+
+/*** Provides the native fallback type surface; React Native Web resolves the DOM adapter at runtime. */
+export function TimeGridKeyboardProxy({ children }: TimeGridKeyboardProxyProps) {
+  return <>{children}</>;
+}
+
+interface TimeGridKeyboardProxyProps {
+  readonly children: React.ReactNode;
+  readonly onKeyDown: (key: string) => boolean;
+}

package/src/features/time-grid/adapters/inbound/TimeGridKeyboardProxy.web.tsx

@@ -0,0 +1,20 @@
+import type React from 'react';
+
+/*** Bridges DOM arrow keys into portable interval focus navigation on React Native Web. */
+export function TimeGridKeyboardProxy({ children, onKeyDown }: TimeGridKeyboardProxyProps) {
+  return (
+    <div
+      onKeyDown={(event) => {
+        if (onKeyDown(event.key)) event.preventDefault();
+      }}
+      style={{ display: 'flex', flex: 1 }}
+    >
+      {children}
+    </div>
+  );
+}
+
+interface TimeGridKeyboardProxyProps {
+  readonly children: React.ReactNode;
+  readonly onKeyDown: (key: string) => boolean;
+}

package/src/features/time-grid/application/resolveTimeGridNextFocusId.test.ts

@@ -0,0 +1,46 @@
+import { expect, test } from 'bun:test';
+
+import { resolveTimeGridNextFocusId } from './resolveTimeGridNextFocusId';
+
+const placements = [
+  {
+    extent: 4,
+    height: 20,
+    id: 'drums-a',
+    laneId: 'drums',
+    laneIndex: 0,
+    start: 2,
+    width: 4,
+    x: 2,
+    y: 0,
+  },
+  {
+    extent: 4,
+    height: 20,
+    id: 'drums-b',
+    laneId: 'drums',
+    laneIndex: 0,
+    start: 12,
+    width: 4,
+    x: 12,
+    y: 0,
+  },
+  {
+    extent: 4,
+    height: 20,
+    id: 'bass-a',
+    laneId: 'bass',
+    laneIndex: 1,
+    start: 3,
+    width: 4,
+    x: 3,
+    y: 20,
+  },
+] as const;
+
+test('moves keyboard focus by interval geometry without calendar or music semantics', () => {
+  expect(resolveTimeGridNextFocusId(placements, 'drums-a', 'right')).toBe('drums-b');
+  expect(resolveTimeGridNextFocusId(placements, 'drums-b', 'left')).toBe('drums-a');
+  expect(resolveTimeGridNextFocusId(placements, 'drums-a', 'down')).toBe('bass-a');
+  expect(resolveTimeGridNextFocusId(placements, 'bass-a', 'up')).toBe('drums-a');
+});

package/src/features/time-grid/application/resolveTimeGridNextFocusId.ts

@@ -0,0 +1,41 @@
+import type { GridLaneIntervalPlacement } from '@ankhorage/grid-view';
+
+/*** Resolves a neighboring interval for keyboard movement without attaching domain meaning to lanes. */
+export function resolveTimeGridNextFocusId(
+  placements: readonly GridLaneIntervalPlacement[],
+  focusedId: string,
+  direction: 'down' | 'left' | 'right' | 'up',
+): string | undefined {
+  const focused = placements.find((placement) => placement.id === focusedId);
+  if (!focused) return undefined;
+  const candidates = placements.filter((placement) => {
+    if (direction === 'left') return placement.laneId === focused.laneId && placement.x < focused.x;
+    if (direction === 'right')
+      return placement.laneId === focused.laneId && placement.x > focused.x;
+    if (direction === 'up') return placement.laneIndex < focused.laneIndex;
+    return placement.laneIndex > focused.laneIndex;
+  });
+  return candidates
+    .sort(
+      (first, second) =>
+        resolveFocusDistance(first, focused, direction) -
+        resolveFocusDistance(second, focused, direction),
+    )
+    .at(0)?.id;
+}
+
+/*** Measures nearby candidates by axis first and timeline/lane offset second. */
+function resolveFocusDistance(
+  candidate: GridLaneIntervalPlacement,
+  focused: GridLaneIntervalPlacement,
+  direction: 'down' | 'left' | 'right' | 'up',
+): number {
+  const horizontal = direction === 'left' || direction === 'right';
+  const primary = horizontal
+    ? Math.abs(candidate.x - focused.x)
+    : Math.abs(candidate.laneIndex - focused.laneIndex);
+  const secondary = horizontal
+    ? Math.abs(candidate.laneIndex - focused.laneIndex)
+    : Math.abs(candidate.x - focused.x);
+  return primary * 1_000_000 + secondary;
+}

package/src/features/time-grid/application/resolveTimeGridVisibleIntervals.test.ts

@@ -0,0 +1,33 @@
+import { expect, test } from 'bun:test';
+
+import { resolveTimeGridVisibleIntervals } from './resolveTimeGridVisibleIntervals';
+
+test('culls sparse intervals across both time and lane axes', () => {
+  expect(
+    resolveTimeGridVisibleIntervals(
+      [
+        { height: 20, id: 'drums' },
+        { height: 40, id: 'bass' },
+        { height: 30, id: 'strings' },
+      ],
+      [
+        { extent: 4, id: 'intro', laneId: 'drums', start: 2 },
+        { extent: 4, id: 'verse', laneId: 'bass', start: 20 },
+        { extent: 4, id: 'outro', laneId: 'strings', start: 2 },
+      ],
+      { height: 45, offsetX: 0, offsetY: 0, pixelsPerUnitX: 1, pixelsPerUnitY: 1, width: 12 },
+    ),
+  ).toEqual([
+    {
+      extent: 4,
+      height: 20,
+      id: 'intro',
+      laneId: 'drums',
+      laneIndex: 0,
+      start: 2,
+      width: 4,
+      x: 2,
+      y: 0,
+    },
+  ]);
+});

package/src/features/time-grid/application/resolveTimeGridVisibleIntervals.ts

@@ -0,0 +1,13 @@
+import { getVisibleLaneIntervals, type GridViewport } from '@ankhorage/grid-view';
+
+import type { TimeGridInterval, TimeGridLane } from '../../../types/time-grid';
+
+/*** Resolves the ordered interval placements visible in both world-space axes. */
+export function resolveTimeGridVisibleIntervals(
+  lanes: readonly TimeGridLane[],
+  intervals: readonly TimeGridInterval[],
+  viewport: GridViewport,
+  overscanPixels?: number,
+) {
+  return getVisibleLaneIntervals(lanes, intervals, viewport, overscanPixels);
+}

package/src/features/time-grid/meta.ts

@@ -0,0 +1,12 @@
+import type { ZoraComponentMeta } from '../../types/authoring';
+
+/** TimeGrid remains code-only because interval and lane presentation require executable renderers. */
+export const timeGridMeta = {
+  name: 'TimeGrid',
+  category: 'foundation',
+  description: 'Virtualized variable-height world-space interval lanes for code-defined timelines.',
+  directManifestNode: false,
+  note: 'Requires executable interval and optional lane-label renderers; available through code APIs, not a serializable manifest node.',
+  allowedChildren: [],
+  props: {},
+} as const satisfies ZoraComponentMeta;

package/src/features/time-grid/public.ts

@@ -0,0 +1,4 @@
+export type { TimeGridInterval, TimeGridLane, TimeGridProps } from '../../types/time-grid';
+export { TimeGrid } from './adapters/inbound/TimeGrid';
+export { resolveTimeGridNextFocusId } from './application/resolveTimeGridNextFocusId';
+export { resolveTimeGridVisibleIntervals } from './application/resolveTimeGridVisibleIntervals';

package/src/index.ts

@@ -484,6 +484,8 @@ export {
 } from './features/theme/colorModel';
 export * from './features/theme/public';
 export * from './features/theme/runtime';
+export type { TimeGridInterval, TimeGridLane, TimeGridProps } from './features/time-grid/public';
+export { resolveTimeGridVisibleIntervals, TimeGrid } from './features/time-grid/public';
 export {
   TimePicker,
   type TimePickerProps,