@deck.gl-community/infovis-layers 9.3.5 → 9.3.7

package/src/layers/time-delta-layer.ts

@@ -2,36 +2,47 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {CompositeLayer, type LayerProps} from '@deck.gl/core';
-import {LineLayer, TextLayer} from '@deck.gl/layers';
+import {CompositeLayer, type DefaultProps, type Layer, type LayerProps} from '@deck.gl/core';
+import {LineLayer, TextLayer, type TextLayerProps} from '@deck.gl/layers';
 
 // import {PathStyleExtension} from '@deck.gl/extensions';
 
 import {formatTimeMs} from '../utils/format-utils';
 
-export type TimeDeltaLayerProps = LayerProps & {
+/** Properties supported by {@link TimeDeltaLayer}. */
+export type TimeDeltaLayerProps = LayerProps & _TimeDeltaLayerProps;
+
+type _TimeDeltaLayerProps = Pick<TextLayerProps, 'fontFamily' | 'fontSettings' | 'fontWeight'> & {
+  /** Legacy time label unit retained for compatibility. @defaultValue 'timestamp' */
   unit: 'timestamp' | 'milliseconds';
+  /** Minimum trace time represented by the surrounding view. @defaultValue 0 */
   minTimeMs: number;
+  /** Maximum trace time represented by the surrounding view. @defaultValue 100 */
   maxTimeMs: number;
-  /** Start time in milliseconds since epoch */
+  /** Start time in milliseconds since epoch. @defaultValue 0 */
   startTimeMs: number;
-  /** End time in milliseconds since epoch */
+  /** End time in milliseconds since epoch. @defaultValue 100 */
   endTimeMs: number;
-  /** Optional: Y-coordinate for the axis line (default: 0) */
+  /** Y coordinate for the header interval guide. @defaultValue 0 */
   y?: number;
+  /** Whether to render the compact header label instead of full-height guide lines. @defaultValue false */
   header: boolean;
 
-  /** Optional: RGBA color for axis and ticks (default: [0, 0, 0, 255]) */
+  /** Header label text size. @defaultValue 12 */
+  fontSize?: number;
+
+  /** RGBA color for interval guides and labels. @defaultValue [0, 0, 0, 255] */
   color?: [number, number, number, number];
-  /** Minimum Y-coordinate for grid lines. @todo (ib) Remve and calculate from viewport? */
+  /** Minimum Y coordinate for full-height guide lines. @defaultValue -1e6 */
   yMin?: number;
-  /** Maximum Y-coordinate for grid lines. @todo (ib) Remve and calculate from viewport? */
+  /** Maximum Y coordinate for full-height guide lines. @defaultValue 1e6 */
   yMax?: number;
 };
 
-export class TimeDeltaLayer extends CompositeLayer<TimeDeltaLayerProps> {
+/** Renders a selected time interval as header or viewport guide lines. */
+export class TimeDeltaLayer extends CompositeLayer<Required<_TimeDeltaLayerProps>> {
   static override layerName = 'TimeDeltaLayer';
-  static override defaultProps: Required<Omit<TimeDeltaLayerProps, keyof LayerProps>> = {
+  static override defaultProps: DefaultProps<_TimeDeltaLayerProps> = {
     header: false,
     minTimeMs: 0,
     maxTimeMs: 100,
@@ -41,16 +52,16 @@ export class TimeDeltaLayer extends CompositeLayer<TimeDeltaLayerProps> {
     color: [0, 0, 0, 255],
     unit: 'timestamp',
     yMin: -1e6, // Should cover full viewport height in most cases
-    yMax: 1e6 // Should cover full viewport height in most cases
+    yMax: 1e6, // Should cover full viewport height in most cases
+    fontSize: 12,
+    fontFamily: TextLayer.defaultProps.fontFamily,
+    fontSettings: TextLayer.defaultProps.fontSettings,
+    fontWeight: TextLayer.defaultProps.fontWeight
   };
 
-  override renderLayers() {
+  override renderLayers(): Layer[] {
     const {startTimeMs, endTimeMs, color = [0, 0, 0, 255], yMin, yMax} = this.props;
 
-    const timeDeltaPosition = [(startTimeMs + endTimeMs) / 2, 10];
-    const timeDeltaMs = Math.abs(endTimeMs - startTimeMs);
-    const timeDeltaLabel = formatTimeMs(timeDeltaMs, false);
-
     if (!this.props.header) {
       const timeLines = [
         {
@@ -76,50 +87,20 @@ export class TimeDeltaLayer extends CompositeLayer<TimeDeltaLayerProps> {
       ];
     }
 
-    // // Tick marks
-    // new LineLayer({
-    //   id: 'time-delta-marks',
-    //   data: tickLines,
-    //   getSourcePosition: (d) => d.sourcePosition,
-    //   getTargetPosition: (d) => d.targetPosition,
-    //   getColor: color,
-    //   getWidth: 1,
-    // }),
-
-    // TODO - triggers broader root-level file updates
-    //   new PathLayer({
-    //     id: 'dotted-path',
-    //     data: route,
-    //     getPath: d => d.path,
-    //     getWidth: 4,
-    //     getColor: [255, 0, 0],
-
-    //     // Enable rounded caps on each dash
-    //     rounded: true,
-
-    //     // Add the dash extension
-    //     extensions: [
-    //       new PathStyleExtension({
-    //         dash: true,
-    //         // highPrecisionDash: true, // uncomment for finer control at low zoom
-    //         capRounded: true          // draw dash ends as semicircles
-    //       })
-    //     ],
-
-    //     // [dashLength, gapLength] in pixels
-    //     // small dash + equal or larger gap = dotted effect
-    //     getDashArray: () => [2, 6]
-    //   })
-    // ]
-    const HEADER_Y = 12;
+    const {y, fontSize, fontFamily, fontSettings, fontWeight} = this.props;
+
+    const timeDeltaPosition = [(startTimeMs + endTimeMs) / 2, y - 10];
+    const timeDeltaMs = Math.abs(endTimeMs - startTimeMs);
+    const timeDeltaLabel = formatTimeMs(timeDeltaMs, {space: false});
+
     const timeLines = [
       {
-        sourcePosition: [startTimeMs, -100],
-        targetPosition: [startTimeMs, HEADER_Y]
+        sourcePosition: [startTimeMs, y],
+        targetPosition: [startTimeMs, y - 7]
       },
       {
-        sourcePosition: [endTimeMs, -100],
-        targetPosition: [endTimeMs, HEADER_Y]
+        sourcePosition: [endTimeMs, y],
+        targetPosition: [endTimeMs, y - 7]
       }
     ];
 
@@ -140,8 +121,8 @@ export class TimeDeltaLayer extends CompositeLayer<TimeDeltaLayerProps> {
         id: 'header-time-delta-dotted-line',
         data: [
           {
-            sourcePosition: [startTimeMs, HEADER_Y - 7],
-            targetPosition: [endTimeMs, HEADER_Y - 7]
+            sourcePosition: [startTimeMs, y - 7],
+            targetPosition: [endTimeMs, y - 7]
           }
         ],
         getSourcePosition: d => d.sourcePosition,
@@ -157,12 +138,16 @@ export class TimeDeltaLayer extends CompositeLayer<TimeDeltaLayerProps> {
         data: [{position: timeDeltaPosition, text: timeDeltaLabel}],
         getPosition: d => d.position,
         getText: d => d.text,
-        getSize: 12,
+        characterSet: '-0123456789.dhmsµ',
+        getSize: fontSize,
+        fontFamily,
+        fontSettings,
+        fontWeight,
         getColor: color,
         getTextAnchor: 'middle',
-        getAlignmentBaseline: 'top',
+        getAlignmentBaseline: 'center',
         background: true,
-        getBackgroundColor: [255, 255, 255, 255], // Solid green background
+        getBackgroundColor: [255 - color[0], 255 - color[1], 255 - color[2], 255],
         backgroundPadding: [4, 2] // Horizontal and vertical padding
       })
     ];

package/src/synchronized-views/synchronized-views.ts

@@ -19,7 +19,7 @@ export const SYNCHRONIZED_VIEWS = [
     flipY: false,
     clear: true, // [1, 1, 1, 1],
     x: LEGEND_VIEW_WIDTH,
-    width: `calc(100% - ${LEGEND_VIEW_WIDTH}px`,
+    width: `calc(100% - ${LEGEND_VIEW_WIDTH}px)`,
     y: HEADER_VIEW_HEIGHT,
     height: `calc(100% - ${HEADER_VIEW_HEIGHT}px)`,
     controller: {

package/src/utils/format-utils.ts

@@ -3,78 +3,128 @@
 // Copyright (c) vis.gl contributors
 
 /**
- * Convert a time in microseconds to a human-readable string
- * @param us Time in microseconds
+ * Options for formatting millisecond duration labels.
  */
-export function formatTimeMs(timeMs: number, space: boolean = true): string {
+export type FormatTimeMsOptions = {
+  /** Whether to include a space between the value and unit. @defaultValue true */
+  space?: boolean;
+  /** Number of significant digits used for fractional values. @defaultValue 5 */
+  roundDigits?: number;
+};
+
+/**
+ * Convert a time in milliseconds to a human-readable string.
+ * @param timeMs Time in milliseconds.
+ * @param options Formatting options, or the legacy `space` boolean argument.
+ * @returns Human-readable duration label.
+ */
+export function formatTimeMs(timeMs: number, options: boolean | FormatTimeMsOptions = {}): string {
+  const normalizedOptions: FormatTimeMsOptions =
+    typeof options === 'boolean' ? {space: options} : options;
+  const {space = true, roundDigits = 5} = normalizedOptions;
   const sep = space ? ' ' : '';
   const us = timeMs * 1000;
   if (us === 0) {
     return '0s';
   }
   if (Math.abs(us) < 1000) {
-    return `${floatToStr(us)}${sep}µs`;
+    return `${floatToStr(us, roundDigits)}${sep}µs`;
   }
   const ms = us / 1000;
   if (Math.abs(ms) < 1000) {
-    return `${floatToStr(ms)}${sep} ms`;
+    return `${floatToStr(ms, roundDigits)}${sep}ms`;
   }
   const s = ms / 1000;
   if (Math.abs(s) < 60) {
-    return `${floatToStr(s)}${sep} s`;
+    return `${floatToStr(s, roundDigits)}${sep}s`;
   }
   const m = s / 60;
   if (Math.abs(m) < 60) {
-    return `${floatToStr(m)}${sep} min`;
+    return formatMinuteDuration(s);
   }
   const h = m / 60;
   if (Math.abs(h) < 24) {
-    return `${floatToStr(h)}${sep} hrs`;
+    return formatHourDuration(s);
   }
-  const d = h / 24;
-  return `${floatToStr(d)}${sep} days`;
+  return formatDayDuration(s);
 }
 
+/**
+ * Convert a millisecond time range to a human-readable string.
+ * @param startMs Range start in milliseconds.
+ * @param endMs Range end in milliseconds.
+ * @returns Human-readable start and end labels joined by a separator.
+ */
 export function formatTimeRangeMs(startMs: number, endMs: number): string {
   return `${formatTimeMs(startMs)} - ${formatTimeMs(endMs)}`;
 }
 
 /**
- * Convert a float to a string
+ * Convert a float to a string with a specified number of significant digits.
+ * @param f The float to convert.
+ * @param roundDigits The number of significant digits to round to (default is 5).
+ * @returns The float as a string, rounded to the specified precision.
  */
-function floatToStr(f: number, roundDigits: number = 5): string {
-  if (Number.isInteger(f)) {
+export function floatToStr(f: number, roundDigits: number = 5): string {
+  if (roundDigits < 1 || Number.isInteger(f)) {
     return f.toString();
   }
 
-  for (let i = 1; i < roundDigits - 1; i++) {
-    const rounded = parseFloat(f.toPrecision(i));
-    if (rounded === f) {
-      return rounded.toPrecision(i);
-    }
+  // Round the float to the specified precision
+  const precision = f.toPrecision(roundDigits);
+  return parseFloat(precision).toString();
+}
+
+/**
+ * Format a duration between one minute and one hour with whole seconds.
+ * @param seconds Duration in seconds.
+ * @returns A compact minutes-and-seconds duration label.
+ */
+function formatMinuteDuration(seconds: number): string {
+  const sign = seconds < 0 ? '-' : '';
+  const totalSeconds = Math.floor(Math.abs(seconds));
+  const minutes = Math.floor(totalSeconds / 60);
+  const remainingSeconds = totalSeconds % 60;
+
+  if (remainingSeconds === 0) {
+    return `${sign}${minutes}m`;
   }
 
-  return f.toPrecision(roundDigits);
+  return `${sign}${minutes}m${remainingSeconds}s`;
 }
 
-// export function formatTimesUs(ticks: number[]): string {
-//   // Try from 0 up to a reasonable max (e.g. 20)
-//   for (let d = 0; d <= 20; d++) {
-//     const seen = new Set<string>();
-//     let allDistinct = true;
-//     for (const t of ticks) {
-//       // Format each tick with d decimals
-//       const str = t.toFixed(d);
-//       if (seen.has(str)) {
-//         allDistinct = false;
-//         break;
-//       }
-//       seen.add(str);
-//     }
-//     if (allDistinct) {
-//       return d;
-//     }
-//   }
-//   // Fallback if somehow not distinct even at 20 decimals
-//   return 20;
-// }
+/**
+ * Format a duration between one hour and one day with whole minutes.
+ * @param seconds Duration in seconds.
+ * @returns A compact hours-and-minutes duration label.
+ */
+function formatHourDuration(seconds: number): string {
+  const sign = seconds < 0 ? '-' : '';
+  const totalMinutes = Math.floor(Math.abs(seconds) / 60);
+  const hours = Math.floor(totalMinutes / 60);
+  const remainingMinutes = totalMinutes % 60;
+
+  if (remainingMinutes === 0) {
+    return `${sign}${hours}h`;
+  }
+
+  return `${sign}${hours}h${remainingMinutes}m`;
+}
+
+/**
+ * Format a duration of at least one day with whole hours.
+ * @param seconds Duration in seconds.
+ * @returns A compact days-and-hours duration label.
+ */
+function formatDayDuration(seconds: number): string {
+  const sign = seconds < 0 ? '-' : '';
+  const totalHours = Math.floor(Math.abs(seconds) / 3600);
+  const days = Math.floor(totalHours / 24);
+  const remainingHours = totalHours % 24;
+
+  if (remainingHours === 0) {
+    return `${sign}${days}d`;
+  }
+
+  return `${sign}${days}d${remainingHours}h`;
+}

package/src/utils/utf8-string-view.test.ts

@@ -0,0 +1,119 @@
+import * as arrow from 'apache-arrow';
+import {describe, expect, it} from 'vitest';
+
+import {
+  arrowFindUtf8,
+  getArrowUtf8ColumnSource,
+  getArrowUtf8RowView,
+  getUtf8ColumnSourceRowView,
+  makeUtf8StringView
+} from './utf8-string-view';
+
+describe('utf8-string-view', () => {
+  it('finds matching Utf8 rows without materializing a lookup map', () => {
+    const column = arrow.vectorFromArray(['alpha', null, '6149800612493239450'], new arrow.Utf8());
+
+    expect(arrowFindUtf8(column, makeUtf8StringView('alpha'))).toBe(0);
+    expect(arrowFindUtf8(column, makeUtf8StringView('6149800612493239450'))).toBe(2);
+    expect(arrowFindUtf8(column, makeUtf8StringView('alpha'), 1)).toBe(-1);
+    expect(arrowFindUtf8(column, makeUtf8StringView('missing'))).toBe(-1);
+  });
+
+  it('finds exact UTF-8 strings in Arrow columns', () => {
+    const column = buildArrowUtf8Vector([
+      'span-a',
+      '6149800612493239450',
+      'span-b',
+      '6149800612493239450'
+    ]);
+    const view = makeUtf8StringView('6149800612493239450');
+
+    expect(arrowFindUtf8(column, view)).toBe(1);
+    expect(arrowFindUtf8(column, view, 2)).toBe(3);
+    expect(arrowFindUtf8(column, view, 4)).toBe(-1);
+  });
+
+  it('falls back safely for nullable Arrow string columns', () => {
+    const column = arrow.vectorFromArray(['span-a', null, 'span-c'], new arrow.Utf8());
+
+    expect(arrowFindUtf8(column, makeUtf8StringView('span-c'))).toBe(2);
+    expect(arrowFindUtf8(column, makeUtf8StringView('missing'))).toBe(-1);
+  });
+
+  it('fills a reusable row view for direct Utf8 values', () => {
+    const column = buildArrowUtf8Vector(['alpha', '', 'gamma']);
+    const out = makeEmptyUtf8View();
+
+    expect(getArrowUtf8RowView(column, 0, out)).toBe(true);
+    expect(readUtf8ViewBytes(out)).toEqual([97, 108, 112, 104, 97]);
+    expect(getArrowUtf8RowView(column, 1, out)).toBe(true);
+    expect(readUtf8ViewBytes(out)).toEqual([]);
+    expect(getArrowUtf8RowView(column, 3, out)).toBe(false);
+  });
+
+  it('fills a reusable row view for nullable Utf8 values', () => {
+    const column = arrow.vectorFromArray(['span-a', null, 'span-c'], new arrow.Utf8());
+    const out = makeEmptyUtf8View();
+
+    expect(getArrowUtf8RowView(column, 1, out)).toBe(false);
+    expect(getArrowUtf8RowView(column, 2, out)).toBe(true);
+    expect(readUtf8ViewBytes(out)).toEqual([115, 112, 97, 110, 45, 99]);
+  });
+
+  it('fills a reusable row view for sliced Utf8 values', () => {
+    const column = buildArrowUtf8Vector(['skip', 'first', 'second']).slice(
+      1,
+      3
+    ) as arrow.Vector<arrow.Utf8>;
+    const out = makeEmptyUtf8View();
+
+    expect(getArrowUtf8RowView(column, 0, out)).toBe(true);
+    expect(readUtf8ViewBytes(out)).toEqual([102, 105, 114, 115, 116]);
+    expect(getArrowUtf8RowView(column, 1, out)).toBe(true);
+    expect(readUtf8ViewBytes(out)).toEqual([115, 101, 99, 111, 110, 100]);
+    expect(arrowFindUtf8(column, makeUtf8StringView('second'))).toBe(1);
+  });
+
+  it('fills normalized column source row views for sliced Utf8 values', () => {
+    const column = buildArrowUtf8Vector(['skip', 'first', 'second']).slice(
+      1,
+      3
+    ) as arrow.Vector<arrow.Utf8>;
+    const source = getArrowUtf8ColumnSource(column);
+    const out = makeEmptyUtf8View();
+
+    expect(source).not.toBeNull();
+    expect(getUtf8ColumnSourceRowView(source!, 0, out)).toBe(true);
+    expect(readUtf8ViewBytes(out)).toEqual([102, 105, 114, 115, 116]);
+    expect(getUtf8ColumnSourceRowView(source!, 1, out)).toBe(true);
+    expect(readUtf8ViewBytes(out)).toEqual([115, 101, 99, 111, 110, 100]);
+  });
+
+  it('fills a reusable row view for chunked Utf8 values', () => {
+    const leftTable = new arrow.Table({
+      name: arrow.vectorFromArray(['left'], new arrow.Utf8())
+    });
+    const rightTable = new arrow.Table({
+      name: arrow.vectorFromArray(['right', 'last'], new arrow.Utf8())
+    });
+    const column = leftTable.concat(rightTable).getChild('name') as arrow.Vector<arrow.Utf8>;
+    const out = makeEmptyUtf8View();
+
+    expect(getArrowUtf8RowView(column, 0, out)).toBe(true);
+    expect(readUtf8ViewBytes(out)).toEqual([108, 101, 102, 116]);
+    expect(getArrowUtf8RowView(column, 2, out)).toBe(true);
+    expect(readUtf8ViewBytes(out)).toEqual([108, 97, 115, 116]);
+  });
+});
+
+function makeEmptyUtf8View() {
+  return {data: new Uint8Array(), start: 0, end: 0};
+}
+
+function readUtf8ViewBytes(view: ReturnType<typeof makeEmptyUtf8View>): number[] {
+  return Array.from(view.data.subarray(view.start, view.end));
+}
+
+function buildArrowUtf8Vector(values: readonly string[]): arrow.Vector<arrow.Utf8> {
+  return arrow.vectorFromArray(values, new arrow.Utf8()) as arrow.Vector<arrow.Utf8>;
+}