@cratis/components 0.1.9

package/PivotViewer/components/pivot/visibility.ts

@@ -0,0 +1,319 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import * as PIXI from 'pixi.js';
+import type { CardSprite } from './constants';
+import { CARD_GAP } from './constants';
+import type { LayoutResult } from '../../engine/types';
+import { destroySprite } from './sprites';
+
+export interface SyncParams<TItem> {
+  root: PIXI.Container | null;
+  container: HTMLDivElement | null;
+  sprites: Map<string | number, CardSprite>;
+  layout: LayoutResult;
+  visibleIds: Uint32Array;
+  items: TItem[];
+  cardWidth: number;
+  cardHeight: number;
+  panX: number;
+  panY: number;
+  panDeltaX?: number;
+  panDeltaY?: number;
+  viewportWidth: number;
+  viewportHeight: number;
+  zoomLevel: number;
+  createCardSprite: (id: string | number, x: number, y: number) => CardSprite;
+  updateCardContent: (sprite: CardSprite, item: TItem) => void;
+  isViewTransition?: boolean;
+  prevLayout?: LayoutResult | null;
+}
+
+export function syncSpritesToViewport<TItem>(params: SyncParams<TItem>) {
+  const { root, container, sprites, layout, visibleIds, items, cardWidth, cardHeight, panX, panY, panDeltaX, panDeltaY, viewportWidth, viewportHeight, createCardSprite, updateCardContent, zoomLevel, isViewTransition, prevLayout } = params;
+  if (!root || !container) return;
+
+  // `visibleIds` comes from callers but this module iterates `layout.positions`.
+  // Keep a reference to avoid unused variable lint errors when callers include it.
+  void visibleIds;
+
+  // Apply pan delta to animating sprites to keep them visually stable during camera jumps
+  if (isViewTransition && (panDeltaX || panDeltaY)) {
+    const dx = (panDeltaX || 0) / (zoomLevel || 1);
+    const dy = (panDeltaY || 0) / (zoomLevel || 1);
+
+    for (const sprite of sprites.values()) {
+      if (sprite.animationStartTime !== undefined) {
+        if (sprite.startX !== undefined) sprite.startX += dx;
+        if (sprite.startY !== undefined) sprite.startY += dy;
+        sprite.currentX += dx;
+        sprite.currentY += dy;
+        sprite.container.position.set(sprite.currentX, sprite.currentY);
+      }
+    }
+  }
+
+  const visibleSet = new Set<string | number>();
+
+  // Increase buffer (in world units) to reduce edge cases where rapid
+  // scrolling skips sprite creation. Keep buffer in world units and convert
+  // DOM pixel measurements into world coordinates below to avoid mixing
+  // coordinate spaces which can cause precision drift at browser zooms.
+  const baseBufferWorld = Math.max(cardWidth, cardHeight) * 4;
+  // Ensure buffer scales with viewport size (in world units) so that when
+  // zoomed out we still pre-create enough sprites ahead of the viewport.
+  const invScale = zoomLevel && zoomLevel !== 0 ? 1 / zoomLevel : 1;
+  // The layout positions are in world units; when the root container is scaled
+  // (zoomed) the rendered pixel position = position * zoomLevel. The DOM
+  // scroll positions (`container.scrollLeft/Top`) are the authoritative pixel
+  // camera offsets; prefer them over the passed `panX/panY` to avoid stale
+  // values or race conditions between React state and direct DOM updates.
+  const effectivePanX = typeof container.scrollLeft === 'number' ? container.scrollLeft : (panX || 0);
+  const effectivePanY = typeof container.scrollTop === 'number' ? container.scrollTop : (panY || 0);
+
+  // Convert pixel-based DOM measurements into world units so we compare like
+  // with like. root.position is set using -pixels, so the mapping
+  // from DOM scroll (pixels) to world units is: world = pixels / zoomLevel.
+  const panWorldX = effectivePanX * invScale;
+  const panWorldY = effectivePanY * invScale;
+
+  // Use the container's measured client size for the viewport dimensions
+  // (in pixels). The passed `viewportWidth`/`viewportHeight` can be stale
+  // when the browser/device zoom changes; `clientWidth/clientHeight` are
+  // authoritative for the actual visible pixel area.
+  const viewportPxWidth = container.clientWidth || viewportWidth;
+  const viewportPxHeight = container.clientHeight || viewportHeight;
+
+  const viewportWorldWidth = viewportPxWidth * invScale;
+  const viewportWorldHeight = viewportPxHeight * invScale;
+
+  // Ensure bufferWorld is calculated from the actual measured viewport
+  // in world units (after converting client pixel dims using invScale).
+  // Make buffer adaptive to zoom: when zoomed out (invScale > 1) a small
+  // pixel scroll maps to a larger world delta, so increase the buffer.
+  // Use the larger of width/height to ensure we buffer enough in both directions.
+  const bufferWorld = Math.max(baseBufferWorld * invScale, Math.max(viewportWorldWidth, viewportWorldHeight) * 2.0, baseBufferWorld);
+
+  // Do not clamp viewport edges to 0 — allow negative top/left values so the
+  // visible window correctly follows the scroll even when the buffer is
+  // larger than the current scroll offset.
+  const viewportLeftWorld = panWorldX - bufferWorld;
+  const viewportRightWorld = panWorldX + viewportWorldWidth + bufferWorld;
+  const viewportTopWorld = panWorldY - bufferWorld;
+  const viewportBottomWorld = panWorldY + viewportWorldHeight + bufferWorld;
+
+  const inViewportIds: (string | number)[] = [];
+  // Small tolerance in world units to avoid floating-point edge cases when
+  // browser/device zoom or high scroll values produce tiny rounding errors.
+  // Scale epsilon with invScale so tolerance grows when zoomed out.
+  const worldEpsilon = Math.max(0.5, 0.5 * invScale);
+
+  // Iterate layout positions directly to avoid depending on `visibleIds`
+  // which may be calculated in a different coordinate space or with
+  // different assumptions about zoom. Looping the positions map is
+  // deterministic and uses world coordinates directly.
+  for (const [id, position] of layout.positions) {
+    if (!position) continue;
+    const worldX = position.x;
+    const worldY = position.y;
+    const worldCardW = cardWidth;
+    const worldCardH = cardHeight;
+
+    if (
+      worldX + worldCardW >= viewportLeftWorld - worldEpsilon &&
+      worldX <= viewportRightWorld + worldEpsilon &&
+      worldY + worldCardH >= viewportTopWorld - worldEpsilon &&
+      worldY <= viewportBottomWorld + worldEpsilon
+    ) {
+      inViewportIds.push(id);
+      visibleSet.add(id);
+    }
+  }
+
+  // Ensure last rows are present when the user scrolls near the bottom.
+  // Compute slot/row information and force-insert IDs from the last few
+  // rows to avoid missing tiles due to rounding/precision at zoom levels.
+  try {
+    const slotHeight = cardHeight + (CARD_GAP || 8);
+    const totalRows = Math.ceil((layout.totalHeight || 0) / slotHeight) || 0;
+    // Determine how many rows are visible in the viewport (world units),
+    // then prefetch a fraction of that adjusted by zoom (invScale).
+    const rowsVisible = Math.max(1, Math.ceil(viewportWorldHeight / slotHeight));
+    const prefetchMultiplier = 0.75; // fraction of viewport to prefetch
+    const prefetchRows = Math.max(2, Math.ceil(rowsVisible * prefetchMultiplier * Math.max(1, invScale)));
+    const lastRowThresholdY = Math.max(0, (totalRows - prefetchRows) * slotHeight);
+    for (const [id, position] of layout.positions) {
+      if (position.y >= lastRowThresholdY) {
+        if (!visibleSet.has(id)) {
+          inViewportIds.push(id);
+          visibleSet.add(id);
+        }
+      }
+    }
+  } catch (e) {
+    void e;
+  }
+
+  // If we detect a very large discrepancy between created sprites and the
+  // computed in-viewport count, that's a signal our culling math may be
+  // unstable (especially at non-100% zoom). In that case, skip hiding this
+  // frame as a conservative safeguard to avoid mass disappearing tiles.
+  // However, disable this safeguard during view transitions to ensure old sprites are cleaned up.
+  const aggressiveCull = !isViewTransition && sprites.size > Math.max(120, Math.ceil(inViewportIds.length * 1.5));
+
+  for (const [id, sprite] of sprites) {
+    if (!visibleSet.has(id)) {
+      // If view transition is active, check if this sprite has a valid target in the new layout
+      // If so, keep it visible and animate it to the new position (even if off-screen)
+      if (isViewTransition && layout.positions.has(id)) {
+        const newPos = layout.positions.get(id);
+        if (newPos) {
+          sprite.targetX = newPos.x;
+          sprite.targetY = newPos.y;
+
+          // Trigger animation if not already animating
+          if (sprite.animationStartTime === undefined) {
+             sprite.startX = sprite.currentX;
+             sprite.startY = sprite.currentY;
+             sprite.animationStartTime = Date.now();
+             sprite.animationDelay = Math.random() * 300;
+          }
+
+          try { if (sprite.container) sprite.container.visible = true; } catch (e) { void e; }
+          // Don't mark as hidden, so it won't be swept
+          if ((sprite as any).__lastHiddenAt) delete (sprite as any).__lastHiddenAt;
+          continue;
+        }
+      }
+
+      if (aggressiveCull) {
+        // Keep sprite visible this frame to avoid visual holes
+        try { if (sprite.container) sprite.container.visible = true; } catch (e) { void e; }
+        continue;
+      }
+
+      try {
+        if (sprite.container) {
+          sprite.container.visible = false;
+        }
+        (sprite as any).__lastHiddenAt = Date.now();
+      } catch (e) {
+        void e;
+      }
+    } else {
+      try {
+        if (sprite.container) {
+          sprite.container.visible = true;
+        }
+        if ((sprite as any).__lastHiddenAt) delete (sprite as any).__lastHiddenAt;
+      } catch (e) { void e; }
+    }
+  }
+
+  // Sweep: actually destroy sprites that have been hidden longer than threshold
+  try {
+    const SWEEP_MS = 500; // keep hidden sprites for 500ms before destruction
+    const now = Date.now();
+    for (const [id, sprite] of sprites) {
+      const lastHidden = (sprite as any).__lastHiddenAt as number | undefined;
+      if (lastHidden && now - lastHidden > SWEEP_MS) {
+        try {
+          // remove from parent if present
+          if (sprite.container && sprite.container.parent) sprite.container.parent.removeChild(sprite.container);
+        } catch (e) {
+          void e;
+        }
+        try {
+          destroySprite(sprite);
+        } catch (e) {
+          void e;
+        }
+        sprites.delete(id);
+      }
+    }
+  } catch (e) {
+    void e;
+  }
+
+  // Limit the number of sprites created per frame to avoid choking the GPU/CPU
+  // when scrolling rapidly or zooming out significantly.
+  const MAX_SPRITES_PER_FRAME = 50;
+  let createdCount = 0;
+
+  for (const id of inViewportIds) {
+    const position = layout.positions.get(id);
+    if (!position) continue;
+
+    let sprite = sprites.get(id);
+    if (!sprite) {
+      if (createdCount >= MAX_SPRITES_PER_FRAME) continue;
+      createdCount++;
+
+      let startX = position.x;
+      let startY = position.y;
+      let shouldAnimate = false;
+
+      // If view transition, try to find old position to fly in from
+      if (isViewTransition && prevLayout && prevLayout.positions.has(id)) {
+        const oldPos = prevLayout.positions.get(id);
+        if (oldPos) {
+          startX = oldPos.x;
+          startY = oldPos.y;
+
+          // If we have a pan delta (camera jump), we need to adjust the start position
+          // so that the sprite appears at the same visual location relative to the NEW camera.
+          // StartWorld = OldWorld + PanDelta
+          if (panDeltaX || panDeltaY) {
+             const dx = (panDeltaX || 0) / (zoomLevel || 1);
+             const dy = (panDeltaY || 0) / (zoomLevel || 1);
+             startX += dx;
+             startY += dy;
+          }
+
+          shouldAnimate = true;
+        }
+      }
+
+      sprite = createCardSprite(id, startX, startY);
+      sprites.set(id, sprite);
+      root.addChild(sprite.container);
+      sprite.currentX = startX;
+      sprite.currentY = startY;
+      // Keep sprite.container positioned in world units; animation/update
+      // loop will apply root.scale/position to convert to pixels.
+      sprite.container.position.set(startX, startY);
+
+      if (shouldAnimate) {
+        sprite.targetX = position.x;
+        sprite.targetY = position.y;
+        sprite.startX = startX;
+        sprite.startY = startY;
+        sprite.animationStartTime = Date.now();
+        sprite.animationDelay = Math.random() * 300;
+      }
+    }
+
+    // Check if target changed to trigger animation
+    if (sprite.targetX !== position.x || sprite.targetY !== position.y) {
+      if (isViewTransition) {
+        sprite.startX = sprite.currentX;
+        sprite.startY = sprite.currentY;
+        sprite.targetX = position.x;
+        sprite.targetY = position.y;
+        sprite.animationStartTime = Date.now();
+        // Add random delay for "organic" fly effect
+        sprite.animationDelay = Math.random() * 300;
+      } else {
+        sprite.targetX = position.x;
+        sprite.targetY = position.y;
+        delete sprite.animationStartTime;
+        delete sprite.animationDelay;
+      }
+    }
+
+    const item = (items as any)[String(id)];
+    if (item) {
+      updateCardContent(sprite, item);
+    }
+  }
+}

package/PivotViewer/constants.ts

@@ -0,0 +1,9 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export const BASE_CARD_WIDTH = 200;
+export const BASE_CARD_HEIGHT = 176;
+export const CARDS_PER_COLUMN = 5;
+export const GROUP_SPACING = 20;
+export const CARD_GAP = 10;
+export const CANVAS_PADDING = 20;

package/PivotViewer/engine/layout.ts

@@ -0,0 +1,149 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type {
+  LayoutSpec,
+  LayoutResult,
+  ItemPosition,
+  GroupingResult,
+  ItemId,
+} from './types';
+import { CARD_GAP, CANVAS_PADDING } from '../constants';
+
+export function computeLayout(
+  grouping: GroupingResult,
+  spec: LayoutSpec
+): LayoutResult {
+  const positions = new Map<ItemId, ItemPosition>();
+
+  if (spec.viewMode === 'collection') {
+    return computeCollectionLayout(grouping, spec, positions);
+  } else {
+    return computeGroupedLayout(grouping, spec, positions);
+  }
+}
+
+function computeCollectionLayout(
+  grouping: GroupingResult,
+  spec: LayoutSpec,
+  positions: Map<ItemId, ItemPosition>
+): LayoutResult {
+  const { cardWidth, cardHeight, containerWidth } = spec;
+  const slotWidth = cardWidth + CARD_GAP;
+  const slotHeight = cardHeight + CARD_GAP;
+
+  // Calculate how many cards fit per row based on container width (include gap)
+  const cardsPerRow = Math.max(1, Math.floor((containerWidth + CARD_GAP - (CANVAS_PADDING * 2)) / slotWidth));
+
+  let x = CANVAS_PADDING;
+  let y = CANVAS_PADDING;
+  let column = 0;
+  let itemCount = 0;
+
+  for (const group of grouping.groups) {
+    for (let i = 0; i < group.ids.length; i++) {
+      const id = group.ids[i];
+
+      positions.set(id, {
+        x,
+        y,
+        groupIndex: 0,
+      });
+
+      // Move to next position horizontally (left to right)
+      column++;
+      x += slotWidth;
+
+      // Wrap to next row when we've filled the width
+      if (column >= cardsPerRow) {
+        column = 0;
+        x = CANVAS_PADDING;
+        y += slotHeight;
+      }
+
+      itemCount++;
+    }
+  }
+
+  const rows = Math.ceil(itemCount / cardsPerRow);
+  const contentWidth = Math.min(itemCount, cardsPerRow) * slotWidth;
+
+  return {
+    positions,
+    totalWidth: Math.max(containerWidth, contentWidth + (CANVAS_PADDING * 2)),
+    totalHeight: (rows * slotHeight) + (CANVAS_PADDING * 2),
+  };
+}
+
+function computeGroupedLayout(
+  grouping: GroupingResult,
+  spec: LayoutSpec,
+  positions: Map<ItemId, ItemPosition>
+): LayoutResult {
+  const { cardWidth, cardHeight, cardsPerColumn, groupSpacing } = spec;
+  const slotWidth = cardWidth + CARD_GAP;
+  const slotHeight = cardHeight + CARD_GAP;
+
+  // Fixed bucket width: 2 columns of cards per bucket (always)
+  const COLUMNS_PER_BUCKET = 2;
+  const bucketWidth = COLUMNS_PER_BUCKET * slotWidth;
+
+  let groupX = CANVAS_PADDING;
+  // Use container height for layout, or fallback to cardsPerColumn height
+  const layoutHeight = spec.containerHeight || (cardsPerColumn * slotHeight);
+  const bucketWidths: number[] = [];
+  let maxRows = 0;
+
+  // First pass: calculate max rows to determine total height
+  for (const group of grouping.groups) {
+    const itemsInGroup = group.ids.length;
+    const rowsInGroup = Math.ceil(itemsInGroup / COLUMNS_PER_BUCKET);
+    maxRows = Math.max(maxRows, rowsInGroup);
+  }
+
+  // Calculate actual content height needed (ensure it's at least as tall as the container)
+  const contentHeight = Math.max(layoutHeight, maxRows * slotHeight);
+
+  for (let groupIndex = 0; groupIndex < grouping.groups.length; groupIndex++) {
+    const group = grouping.groups[groupIndex];
+
+    const itemsInGroup = group.ids.length;
+
+    for (let i = 0; i < itemsInGroup; i++) {
+      const id = group.ids[i];
+
+      // Cards fill from left to right, bottom to top
+      // For a 2-column bucket: i=0,1 in row 0; i=2,3 in row 1; etc.
+      const col = i % COLUMNS_PER_BUCKET;
+      const row = Math.floor(i / COLUMNS_PER_BUCKET);
+
+      const x = groupX + col * slotWidth;
+      // Stack from bottom of total content upward:
+      // row 0 (first card) at bottom: contentHeight - slotHeight
+      // row 1 above it: contentHeight - 2*slotHeight, etc.
+      const y = contentHeight - (row + 1) * slotHeight + CANVAS_PADDING;
+
+      positions.set(id, {
+        x,
+        y,
+        groupIndex,
+      });
+    }
+
+    // Always use fixed bucket width
+    bucketWidths.push(bucketWidth);
+
+    // Advance position by fixed bucket width + spacing
+    groupX += bucketWidth;
+    if (groupIndex < grouping.groups.length - 1) {
+      groupX += groupSpacing;
+    }
+  }
+
+  return {
+    positions,
+    totalWidth: groupX + CANVAS_PADDING,
+    totalHeight: contentHeight + (CANVAS_PADDING * 2),
+    bucketWidths,
+  };
+}

package/PivotViewer/engine/pivot.worker.ts

@@ -0,0 +1,86 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type {
+  PivotStore,
+  PivotIndexes,
+  WorkerInMessage,
+  WorkerOutMessage,
+} from './types';
+import { buildIndexes, applyFilters, computeGrouping, sortIds } from './store';
+
+let store: PivotStore | null = null;
+let indexes: PivotIndexes | null = null;
+
+self.onmessage = (e: MessageEvent<WorkerInMessage>) => {
+  const message = e.data;
+
+  switch (message.type) {
+    case 'buildIndexes': {
+      store = message.store;
+      indexes = buildIndexes(store, message.fields);
+
+      const response: WorkerOutMessage = {
+        type: 'indexesReady',
+        indexes,
+      };
+      self.postMessage(response);
+      break;
+    }
+
+    case 'applyFilters': {
+      if (!store || !indexes) {
+        console.error('Store or indexes not initialized');
+        return;
+      }
+
+      const result = applyFilters(store, indexes, message.filters);
+
+      const response: WorkerOutMessage = {
+        type: 'filterResult',
+        result,
+      };
+      self.postMessage(response);
+      break;
+    }
+
+    case 'computeGrouping': {
+      if (!store || !indexes) {
+        console.error('Store or indexes not initialized');
+        return;
+      }
+
+      const result = computeGrouping(
+        store,
+        indexes,
+        message.visibleIds,
+        message.groupBy
+      );
+
+      const response: WorkerOutMessage = {
+        type: 'groupingResult',
+        result,
+      };
+      self.postMessage(response);
+      break;
+    }
+
+    case 'sort': {
+      if (!store) {
+        console.error('Store not initialized');
+        return;
+      }
+
+      const result = sortIds(store, message.ids, message.sortBy);
+
+      const response: WorkerOutMessage = {
+        type: 'sortResult',
+        result,
+      };
+      self.postMessage(response);
+      break;
+    }
+  }
+};
+
+export {};