@deck.gl-community/graph-layers 9.1.0-beta.8 → 9.2.0-beta.2

package/src/style/style-property.ts

@@ -3,7 +3,23 @@
 // Copyright (c) vis.gl contributors
 
 import Color from 'color';
-import {log} from '../utils/log';
+import {
+  scaleLinear,
+  scaleLog,
+  scaleOrdinal,
+  scalePow,
+  scaleQuantile,
+  scaleQuantize,
+  scaleSqrt
+} from 'd3-scale';
+
+import {warn} from '../utils/log';
+import type {
+  GraphStyleAttributeReference,
+  GraphStyleLeafValue,
+  GraphStyleScale,
+  GraphStyleScaleType
+} from './graph-style-engine';
 
 /* Utils for type check */
 function getColor(value) {
@@ -133,29 +149,292 @@ const DEFAULT_STYLES = {
   scaleWithZoom: true
 };
 
-// code generation: generate a function as a layer accessor
-function generateAccessor(key, value) {
+/** Union of supported D3 scale implementations. */
+type SupportedScale =
+  | ReturnType<typeof scaleLinear>
+  | ReturnType<typeof scaleLog>
+  | ReturnType<typeof scalePow>
+   
+  | ReturnType<typeof scaleQuantize>
+  | ReturnType<typeof scaleQuantile>
+  | ReturnType<typeof scaleOrdinal>;
+
+const SCALE_FACTORIES: Record<GraphStyleScaleType, () => SupportedScale> = {
+  linear: () => scaleLinear(),
+  log: () => scaleLog(),
+  pow: () => scalePow(),
+  sqrt: () => scaleSqrt(),
+  quantize: () => scaleQuantize(),
+  quantile: () => scaleQuantile(),
+  ordinal: () => scaleOrdinal()
+};
+
+/** Resolved attribute reference with guaranteed defaults. */
+type NormalizedAttributeReference = {
+  attribute: string;
+  fallback: unknown;
+  scale?: (value: unknown) => unknown;
+  scaleConfig?: GraphStyleScale | ((value: unknown) => unknown);
+};
+
+/** Create a D3 scale instance based on a declarative configuration. */
+/* eslint-disable-next-line complexity */
+function createScaleFromConfig(config: GraphStyleScale): SupportedScale {
+  const type = config.type ?? 'linear';
+  const factory = SCALE_FACTORIES[type];
+  if (!factory) {
+    warn(`Invalid scale type: ${type}`);
+    throw new Error(`Invalid scale type: ${type}`);
+  }
+  const scale = (factory as () => SupportedScale)();
+  const anyScale = scale as any;
+  if (config.domain && 'domain' in scale) {
+    anyScale.domain(config.domain as never);
+  }
+  if (config.range && 'range' in scale) {
+    anyScale.range(config.range as never);
+  }
+  if (typeof config.clamp === 'boolean' && 'clamp' in scale && typeof anyScale.clamp === 'function') {
+    anyScale.clamp(config.clamp);
+  }
+  if (typeof config.nice !== 'undefined' && 'nice' in scale && typeof anyScale.nice === 'function') {
+    anyScale.nice(config.nice as never);
+  }
+  if (
+    type === 'pow' &&
+    typeof config.exponent === 'number' &&
+    'exponent' in scale &&
+    typeof anyScale.exponent === 'function'
+  ) {
+    anyScale.exponent(config.exponent);
+  }
+  if (
+    type === 'log' &&
+    typeof config.base === 'number' &&
+    'base' in scale &&
+    typeof anyScale.base === 'function'
+  ) {
+    anyScale.base(config.base);
+  }
+  if (
+    typeof config.unknown !== 'undefined' &&
+    'unknown' in scale &&
+    typeof (scale as {unknown?: (value: unknown) => unknown}).unknown === 'function'
+  ) {
+    (scale as {unknown: (value: unknown) => unknown}).unknown(config.unknown);
+  }
+  return scale;
+}
+
+/** Normalize attribute reference definitions into a consistent structure. */
+function normalizeAttributeReference(
+  key: string,
+  reference: GraphStyleAttributeReference
+): NormalizedAttributeReference {
+  if (typeof reference === 'string') {
+    const attribute = reference.startsWith('@') ? reference.slice(1) : reference;
+    if (!attribute) {
+      throw new Error(`Invalid attribute reference for ${key}: ${reference}`);
+    }
+    return {
+      attribute,
+      fallback: DEFAULT_STYLES[key]
+    };
+  }
+
+  const {attribute, fallback = DEFAULT_STYLES[key], scale} = reference;
+  if (!attribute) {
+    throw new Error(`Invalid attribute reference for ${key}: ${JSON.stringify(reference)}`);
+  }
+
+  let scaleFn: ((value: unknown) => unknown) | undefined;
+  let scaleConfig: GraphStyleScale | ((value: unknown) => unknown) | undefined;
+
+  if (scale) {
+    if (typeof scale === 'function') {
+      scaleFn = scale;
+      scaleConfig = scale;
+    } else {
+      scaleFn = createScaleFromConfig(scale);
+      scaleConfig = scale;
+    }
+  }
+
+  return {
+    attribute,
+    fallback,
+    scale: scaleFn,
+    scaleConfig
+  };
+}
+
+/** Determine whether a value points to a graph attribute reference. */
+function isAttributeReference(value: unknown): value is GraphStyleAttributeReference {
+  if (typeof value === 'string') {
+    return value.startsWith('@');
+  }
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value) && 'attribute' in (value as Record<string, unknown>);
+}
+
+/** Determine whether a style value maps interaction states. */
+function isStatefulValue(value: unknown): value is Record<string, GraphStyleLeafValue> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value) && !isAttributeReference(value);
+}
+
+/** Resolve an attribute from a datum or `Graph` entity. */
+function getAttributeValue(datum: any, attribute: string) {
+  if (datum && typeof datum.getPropertyValue === 'function') {
+    return datum.getPropertyValue(attribute);
+  }
+  if (datum && typeof datum === 'object' && attribute in datum) {
+    return datum[attribute];
+  }
+  return undefined;
+}
+
+/** Combine Deck.gl update triggers while filtering falsey entries. */
+function mergeUpdateTriggers(...triggers: unknown[]): unknown {
+  const filtered = triggers.filter(
+    (trigger) => !(trigger === false || trigger === undefined || trigger === null)
+  );
+  if (!filtered.length) {
+    return false;
+  }
+  if (filtered.length === 1) {
+    return filtered[0];
+  }
+  return filtered;
+}
+
+/** Build an accessor that reads and optionally scales an attribute. */
+function createAttributeAccessor(
+  key: string,
+  attributeRef: NormalizedAttributeReference,
+  formatter: (value: unknown) => unknown
+) {
+  const accessor = (datum: any) => {
+    let raw = getAttributeValue(datum, attributeRef.attribute);
+    if (raw === undefined || raw === null) {
+      raw = attributeRef.fallback;
+    }
+    if (attributeRef.scale) {
+      raw = attributeRef.scale(raw);
+    }
+    const formatted = formatter(raw);
+    if (formatted === null) {
+      warn(`Invalid ${key} value: ${raw}`);
+      throw new Error(`Invalid ${key} value: ${raw}`);
+    }
+    return formatted;
+  };
+
+  const updateTrigger = {
+    attribute: attributeRef.attribute,
+    scale: attributeRef.scaleConfig ?? null
+  };
+
+  return {accessor, updateTrigger};
+}
+
+/** Result of parsing a leaf style value. */
+type LeafParseResult = {
+  value: any;
+  isAccessor: boolean;
+  updateTrigger: unknown;
+};
+
+function describeStyleValue(value: unknown): string {
+  if (typeof value === 'string') {
+    return value;
+  }
+  if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'undefined') {
+    return String(value);
+  }
+  if (value === null) {
+    return 'null';
+  }
+  if (typeof value === 'function') {
+    return value.name ? `[Function ${value.name}]` : '[Function]';
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => describeStyleValue(item)).join(', ')}]`;
+  }
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+
+/** Parse a non-stateful style value into deck.gl compatible form. */
+function parseLeafValue(key: string, value: GraphStyleLeafValue | undefined): LeafParseResult {
   const formatter = PROPERTY_FORMATTERS[key] || IDENTITY;
-  // ex: key = 'fill', value = {defaut: 'red', hover: 'blue'}
-  // valueMap => {defaut: [255, 0, 0], hover: [0, 0, 255]}
-  const valueMap = Object.keys(value).reduce((res, key0) => {
-    res[key0] = value[key0];
-    return res;
-  }, {}) as any;
-
-  return (node) => {
-    const statefulValue = valueMap[node.state];
-    if (!node.state || typeof statefulValue === 'undefined') {
-      return valueMap.default || DEFAULT_STYLES[key];
+
+  if (typeof value === 'undefined') {
+    const formatted = formatter(DEFAULT_STYLES[key]);
+    if (formatted === null) {
+      const description = describeStyleValue(value);
+      warn(`Invalid ${key} value: ${description}`);
+      throw new Error(`Invalid ${key} value: ${description}`);
     }
-    // else has stateful value
-    // check if the value is a function
-    if (typeof statefulValue === 'function') {
-      return formatter(statefulValue(node));
+    return {value: formatted, isAccessor: false, updateTrigger: false};
+  }
+
+  if (isAttributeReference(value)) {
+    const normalized = normalizeAttributeReference(key, value);
+    const {accessor, updateTrigger} = createAttributeAccessor(key, normalized, formatter);
+    return {value: accessor, isAccessor: true, updateTrigger};
+  }
+
+  if (typeof value === 'function') {
+    return {
+      value: (datum) => formatter(value(datum)),
+      isAccessor: true,
+      updateTrigger: value
+    };
+  }
+
+  const formatted = formatter(value);
+  if (formatted === null) {
+    const description = describeStyleValue(value);
+    warn(`Invalid ${key} value: ${description}`);
+    throw new Error(`Invalid ${key} value: ${description}`);
+  }
+
+  return {value: formatted, isAccessor: false, updateTrigger: false};
+}
+
+/**
+ * Create an accessor capable of handling interaction state overrides for a style property.
+ */
+function createStatefulAccessor(
+  key: string,
+  value: Record<string, GraphStyleLeafValue>,
+  stateUpdateTrigger: unknown
+) {
+  const valueMap: Record<string, any> = {};
+  const attributeTriggers: unknown[] = [];
+
+  for (const state of Object.keys(value)) {
+    const parsed = parseLeafValue(key, value[state]);
+    valueMap[state] = parsed.value;
+    if (parsed.updateTrigger) {
+      attributeTriggers.push(parsed.updateTrigger);
     }
-    // or just a plain value
-    return formatter(statefulValue);
+  }
+
+  const defaultValue =
+    typeof valueMap.default !== 'undefined' ? valueMap.default : parseLeafValue(key, undefined).value;
+
+  const accessor = (datum: any) => {
+    const stateValue = datum?.state ? valueMap[datum.state] : undefined;
+    const candidate = typeof stateValue !== 'undefined' ? stateValue : defaultValue;
+    return typeof candidate === 'function' ? candidate(datum) : candidate;
   };
+
+  const updateTrigger = mergeUpdateTriggers(stateUpdateTrigger, ...attributeTriggers);
+
+  return {accessor, updateTrigger};
 }
 
 const VALUE_TYPE = {
@@ -165,7 +444,7 @@ const VALUE_TYPE = {
 
 export class StyleProperty {
   key: any;
-  _updateTrigger: boolean;
+  _updateTrigger: unknown;
   _value: any;
   _valueType: any;
 
@@ -180,40 +459,24 @@ export class StyleProperty {
     this.key = key;
     this._updateTrigger = false;
 
-    // statefule property, ex:
-    // fill: {default: 'red', hover: 'blue'}
-    // note that offset: [0, 1], the type of array is object, too.
-    if (typeof value === 'object' && !Array.isArray(value)) {
-      // generate accessor function
-      this._value = generateAccessor(key, value);
+    if (isStatefulValue(value)) {
+      const {accessor, updateTrigger: triggers} = createStatefulAccessor(
+        key,
+        value,
+        updateTrigger
+      );
+      this._value = accessor;
       this._valueType = VALUE_TYPE.ACCESSOR;
-      this._updateTrigger = updateTrigger;
-    }
-    // default state property, but value = accessor
-    // fill: () => 'red'
-    else if (typeof value === 'function') {
-      const formatter = PROPERTY_FORMATTERS[key] || IDENTITY;
-      // the output of the function should be formated by
-      // the corresponding formatter again.
-      // Ex: colorAccessor might return '#f00', which needs to
-      // be formated as [255, 0, 0];
-      this._value = (d) => formatter(value(d));
-      this._valueType = VALUE_TYPE.ACCESSOR;
-      this._updateTrigger = value;
-    }
-    // default state property with plain value:
-    // fill: 'red'
-    else {
-      // format the value properly
-      const formatter = PROPERTY_FORMATTERS[key] || IDENTITY;
-      this._value = formatter(value);
-      this._valueType = VALUE_TYPE.PLAIN_VALUE;
-      this._updateTrigger = false;
+      this._updateTrigger = triggers;
+    } else {
+      const parsed = parseLeafValue(key, value as GraphStyleLeafValue | undefined);
+      this._value = parsed.value;
+      this._valueType = parsed.isAccessor ? VALUE_TYPE.ACCESSOR : VALUE_TYPE.PLAIN_VALUE;
+      this._updateTrigger = mergeUpdateTriggers(parsed.updateTrigger);
     }
 
-    // sanity check
     if (this._value === null) {
-      log.warn(`Invalid ${key} value: ${value}`)();
+      warn(`Invalid ${key} value: ${value}`);
       throw new Error(`Invalid ${key} value: ${value}`);
     }
   }

package/src/utils/collapsed-chains.ts

@@ -0,0 +1,261 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {GraphEngine} from '../core/graph-engine';
+import type {Node} from '../graph/node';
+
+const OUTLINE_PADDING = 24;
+const OUTLINE_CORNER_RADIUS = 16;
+const OUTLINE_CORNER_SEGMENTS = 6;
+
+export type ChainInteractionSource =
+  | 'node'
+  | 'collapsed-marker'
+  | 'expanded-marker'
+  | 'collapsed-outline'
+  | 'expanded-outline';
+
+function resolveLayerId(layer: any): string {
+  if (!layer) {
+    return '';
+  }
+  if (typeof layer.id === 'string') {
+    return layer.id;
+  }
+  if (typeof layer.props?.id === 'string') {
+    return layer.props.id;
+  }
+  return '';
+}
+
+function classifyChainLayer(layer: any): ChainInteractionSource | null {
+  let current = layer ?? null;
+  while (current) {
+    const layerId = resolveLayerId(current);
+    if (layerId.includes('collapsed-chain-markers')) {
+      return 'collapsed-marker';
+    }
+    if (layerId.includes('expanded-chain-markers')) {
+      return 'expanded-marker';
+    }
+    if (layerId.includes('collapsed-chain-outlines')) {
+      return 'collapsed-outline';
+    }
+    if (layerId.includes('expanded-chain-outlines')) {
+      return 'expanded-outline';
+    }
+    current = current.parent ?? null;
+  }
+  return null;
+}
+
+export function resolveChainInteractionSource(info: any): ChainInteractionSource {
+  if (!info) {
+    return 'node';
+  }
+
+  const layersToCheck = [] as any[];
+  if (info.layer || info.sourceLayer) {
+    if (info.layer) {
+      layersToCheck.push(info.layer);
+    }
+    if (info.sourceLayer && info.sourceLayer !== info.layer) {
+      layersToCheck.push(info.sourceLayer);
+    }
+  } else {
+    layersToCheck.push(info);
+  }
+
+  for (const layer of layersToCheck) {
+    const classification = classifyChainLayer(layer);
+    if (classification) {
+      return classification;
+    }
+  }
+
+  return 'node';
+}
+
+function isChainRepresentative(node: Node): boolean {
+  const chainId = node.getPropertyValue('collapsedChainId');
+  const nodeIds = node.getPropertyValue('collapsedNodeIds');
+  const representativeId = node.getPropertyValue('collapsedChainRepresentativeId');
+
+  return (
+    Boolean(chainId) &&
+    Array.isArray(nodeIds) &&
+    nodeIds.length > 1 &&
+    representativeId === node.getId()
+  );
+}
+
+export function getRepresentativeNodes(engine: GraphEngine | null | undefined): Node[] {
+  if (!engine) {
+    return [];
+  }
+
+  return engine.getNodes().filter((node) => isChainRepresentative(node));
+}
+
+export type ChainOutlineGetter = (node: Node) => [number, number][] | null;
+
+export function createChainOutlineGetter(engine: GraphEngine | null | undefined): ChainOutlineGetter {
+  if (!engine) {
+    return () => null;
+  }
+
+  const graph = engine.props.graph;
+  const cache = new Map<string, [number, number][] | null>();
+
+  // eslint-disable-next-line max-statements, complexity
+  return (node: Node): [number, number][] | null => {
+    const chainId = node.getPropertyValue('collapsedChainId');
+    if (!chainId) {
+      return null;
+    }
+
+    const cacheKey = String(chainId);
+    if (cache.has(cacheKey)) {
+      return cache.get(cacheKey) ?? null;
+    }
+
+    if (!graph) {
+      cache.set(cacheKey, null);
+      return null;
+    }
+
+    const collapsedNodeIds = node.getPropertyValue('collapsedNodeIds');
+    if (!Array.isArray(collapsedNodeIds) || collapsedNodeIds.length === 0) {
+      cache.set(cacheKey, null);
+      return null;
+    }
+
+    let minX = Number.POSITIVE_INFINITY;
+    let maxX = Number.NEGATIVE_INFINITY;
+    let minY = Number.POSITIVE_INFINITY;
+    let maxY = Number.NEGATIVE_INFINITY;
+
+    for (const nodeId of collapsedNodeIds) {
+      const chainNode = graph.findNode(nodeId);
+      if (chainNode) {
+        const position = engine.getNodePosition(chainNode);
+        if (position) {
+          const [x, y] = position;
+          minX = Math.min(minX, x);
+          maxX = Math.max(maxX, x);
+          minY = Math.min(minY, y);
+          maxY = Math.max(maxY, y);
+        }
+      }
+    }
+
+    if (
+      !Number.isFinite(minX) ||
+      !Number.isFinite(maxX) ||
+      !Number.isFinite(minY) ||
+      !Number.isFinite(maxY)
+    ) {
+      cache.set(cacheKey, null);
+      return null;
+    }
+
+    const paddedMinX = minX - OUTLINE_PADDING;
+    const paddedMaxX = maxX + OUTLINE_PADDING;
+    const paddedMinY = minY - OUTLINE_PADDING;
+    const paddedMaxY = maxY + OUTLINE_PADDING;
+
+    const width = paddedMaxX - paddedMinX;
+    const height = paddedMaxY - paddedMinY;
+
+    if (width <= 0 || height <= 0) {
+      cache.set(cacheKey, null);
+      return null;
+    }
+
+    const radius = Math.min(OUTLINE_CORNER_RADIUS, width / 2, height / 2);
+
+    if (radius <= 0) {
+      const polygon: [number, number][] = [
+        [paddedMinX, paddedMinY],
+        [paddedMinX, paddedMaxY],
+        [paddedMaxX, paddedMaxY],
+        [paddedMaxX, paddedMinY],
+        [paddedMinX, paddedMinY]
+      ];
+      cache.set(cacheKey, polygon);
+      return polygon;
+    }
+
+    const left = paddedMinX;
+    const right = paddedMaxX;
+    const top = paddedMinY;
+    const bottom = paddedMaxY;
+
+    const polygon: [number, number][] = [];
+    const pushArc = (cx: number, cy: number, startAngle: number, endAngle: number) => {
+      const step = (endAngle - startAngle) / OUTLINE_CORNER_SEGMENTS;
+      for (let i = 1; i <= OUTLINE_CORNER_SEGMENTS; i++) {
+        const angle = startAngle + step * i;
+        polygon.push([cx + radius * Math.cos(angle), cy + radius * Math.sin(angle)]);
+      }
+    };
+
+    polygon.push([right - radius, top]);
+    pushArc(right - radius, top + radius, -Math.PI / 2, 0);
+    polygon.push([right, bottom - radius]);
+    pushArc(right - radius, bottom - radius, 0, Math.PI / 2);
+    polygon.push([left + radius, bottom]);
+    pushArc(left + radius, bottom - radius, Math.PI / 2, Math.PI);
+    polygon.push([left, top + radius]);
+    pushArc(left + radius, top + radius, Math.PI, (3 * Math.PI) / 2);
+    polygon.push(polygon[0]);
+
+    cache.set(cacheKey, polygon);
+    return polygon;
+  };
+}
+
+export interface CollapsedChainLayerData {
+  representativeNodes: Node[];
+  collapsedNodes: Node[];
+  collapsedOutlineNodes: Node[];
+  expandedNodes: Node[];
+  expandedOutlineNodes: Node[];
+  getChainOutlinePolygon: ChainOutlineGetter;
+  outlineUpdateTrigger: string;
+}
+
+export function buildCollapsedChainLayers(
+  engine: GraphEngine | null | undefined
+): CollapsedChainLayerData | null {
+  if (!engine) {
+    return null;
+  }
+
+  const representativeNodes = getRepresentativeNodes(engine);
+  if (representativeNodes.length === 0) {
+    return null;
+  }
+
+  const getChainOutlinePolygon = createChainOutlineGetter(engine);
+  const outlineUpdateTrigger = [engine.getLayoutLastUpdate(), engine.getLayoutState()].join();
+
+  const collapsedNodes = representativeNodes.filter((node) =>
+    Boolean(node.getPropertyValue('isCollapsedChain'))
+  );
+  const collapsedOutlineNodes = collapsedNodes.filter((node) => getChainOutlinePolygon(node));
+
+  const expandedNodes = representativeNodes.filter((node) => !node.getPropertyValue('isCollapsedChain'));
+  const expandedOutlineNodes = expandedNodes.filter((node) => getChainOutlinePolygon(node));
+
+  return {
+    representativeNodes,
+    collapsedNodes,
+    collapsedOutlineNodes,
+    expandedNodes,
+    expandedOutlineNodes,
+    getChainOutlinePolygon,
+    outlineUpdateTrigger
+  };
+}

package/src/utils/log.ts

@@ -6,4 +6,18 @@ import {Log, COLOR} from '@probe.gl/log';
 
 export const log = new Log({id: 'graph-layers'}).enable();
 
-log.log({color: COLOR.CYAN}, 'Initialize graph-layers logger.')();
+log.log({color: COLOR.CYAN}, 'Initialize graph-layers logger.');
+
+function invokeLogFunction(result: unknown) {
+  if (typeof result === 'function') {
+    result();
+  }
+}
+
+export function warn(message: string, ...args: unknown[]) {
+  invokeLogFunction(log.warn(message, ...args));
+}
+
+export function error(message: string, ...args: unknown[]) {
+  invokeLogFunction(log.error(message, ...args));
+}