@cratis/components 0.1.9 → 0.1.12

package/PivotViewer/components/pivot/visibility.ts

@@ -1,319 +0,0 @@
-// 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

@@ -1,9 +0,0 @@
-// 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

@@ -1,149 +0,0 @@
-// 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

@@ -1,86 +0,0 @@
-// 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 {};