data-navigator 2.3.1 → 2.4.0

package/dist/index.cjs

@@ -461,7 +461,7 @@ var buildNodes = (options) => {
   return nodes;
 };
 var scaffoldDimensions = (options, nodes) => {
-  var _a, _b;
+  var _a, _b, _c;
   let dimensions = {};
   if ((_b = (_a = options.dimensions) == null ? void 0 : _a.parentOptions) == null ? void 0 : _b.addLevel0) {
     let level0 = options.dimensions.parentOptions.addLevel0;
@@ -475,10 +475,11 @@ var scaffoldDimensions = (options, nodes) => {
     dim.numericalExtents[1] = max > val ? max : val;
   };
   options.data.forEach((d) => {
-    let ods = options.dimensions.values || [];
+    var _a2;
+    let ods = ((_a2 = options.dimensions) == null ? void 0 : _a2.values) || [];
     let i = 0;
     ods.forEach((dim) => {
-      var _a2, _b2, _c, _d, _e, _f, _g, _h;
+      var _a3, _b2, _c2, _d, _e, _f, _g, _h;
       if (!dim.dimensionKey) {
         console.error(
           `Building nodes, parsing dimensions. Each dimension in options.dimensions must contain a dimensionKey. This dimension has no key: ${JSON.stringify(
@@ -489,7 +490,7 @@ var scaffoldDimensions = (options, nodes) => {
       }
       if (dim.dimensionKey in d) {
         let value = d[dim.dimensionKey];
-        let keepValue = typeof ((_a2 = dim.operations) == null ? void 0 : _a2.filterFunction) === "function" ? dim.operations.filterFunction(d, dim) : true;
+        let keepValue = typeof ((_a3 = dim.operations) == null ? void 0 : _a3.filterFunction) === "function" ? dim.operations.filterFunction(d, dim) : true;
         if (value !== void 0 && keepValue) {
           if (!dim.type) {
             dim.type = typeof value === "bigint" || typeof value === "number" ? "numerical" : "categorical";
@@ -505,7 +506,7 @@ var scaffoldDimensions = (options, nodes) => {
               type: dim.type,
               operations: {
                 compressSparseDivisions: ((_b2 = dim.operations) == null ? void 0 : _b2.compressSparseDivisions) || false,
-                sortFunction: ((_c = dim.operations) == null ? void 0 : _c.sortFunction) || void 0
+                sortFunction: ((_c2 = dim.operations) == null ? void 0 : _c2.sortFunction) || void 0
               },
               behavior: dim.behavior || {
                 extents: "circular"
@@ -579,7 +580,7 @@ var scaffoldDimensions = (options, nodes) => {
     });
   });
   Object.keys(dimensions).forEach((s) => {
-    var _a2, _b2, _c, _d, _e;
+    var _a2, _b2, _c2, _d, _e;
     let dimension = dimensions[s];
     let divisions = dimension.divisions;
     if (dimension.type === "numerical") {
@@ -598,14 +599,18 @@ var scaffoldDimensions = (options, nodes) => {
         let i = dimension.numericalExtents[0] + interval;
         let divisionCount = 0;
         let index = 0;
+        let lastDivisionId = null;
+        let prevBound = dimension.numericalExtents[0];
         for (i = dimension.numericalExtents[0] + interval; i <= dimension.numericalExtents[1]; i += interval) {
-          let divisionId = typeof ((_a2 = dimension.divisionOptions) == null ? void 0 : _a2.divisionNodeIds) === "function" ? dimension.divisionOptions.divisionNodeIds(s, i, i) : dimension.nodeId + "_" + i;
+          let divisionId = typeof ((_a2 = dimension.divisionOptions) == null ? void 0 : _a2.divisionNodeIds) === "function" ? dimension.divisionOptions.divisionNodeIds(s, i, i) : createValidId(dimension.nodeId + "_" + i);
+          lastDivisionId = divisionId;
           dimension.divisions[divisionId] = {
             id: divisionId,
             sortFunction: ((_b2 = dimension.divisionOptions) == null ? void 0 : _b2.sortFunction) || void 0,
-            values: {}
+            values: {},
+            numericalExtents: [prevBound, i]
           };
-          let divisionRenderId = typeof ((_c = dimension.divisionOptions) == null ? void 0 : _c.divisionRenderIds) === "function" ? dimension.divisionOptions.divisionRenderIds(s, i, i) : divisionId;
+          let divisionRenderId = typeof ((_c2 = dimension.divisionOptions) == null ? void 0 : _c2.divisionRenderIds) === "function" ? dimension.divisionOptions.divisionRenderIds(s, i, i) : divisionId;
           nodes[divisionId] = {
             id: divisionId,
             renderId: divisionRenderId,
@@ -622,14 +627,21 @@ var scaffoldDimensions = (options, nodes) => {
             let value = node[s];
             if (value <= i) {
               dimension.divisions[divisionId].values[node.id] = node;
+              index++;
             } else {
-              i += interval;
               limit = true;
             }
-            index++;
           }
+          prevBound = i;
           divisionCount++;
         }
+        if (lastDivisionId && index < valueKeys.length) {
+          while (index < valueKeys.length) {
+            let node = values[valueKeys[index]];
+            dimension.divisions[lastDivisionId].values[node.id] = node;
+            index++;
+          }
+        }
         delete divisions[s];
       }
     } else if (typeof ((_e = dimension.operations) == null ? void 0 : _e.sortFunction) === "function") {
@@ -681,7 +693,7 @@ var scaffoldDimensions = (options, nodes) => {
       }
     }
   });
-  if (options.dimensions.adjustDimensions) {
+  if ((_c = options.dimensions) == null ? void 0 : _c.adjustDimensions) {
     dimensions = options.dimensions.adjustDimensions(dimensions);
   }
   return dimensions;
@@ -818,13 +830,15 @@ var buildEdges = (options, nodes, dimensions) => {
         } else {
           createEdge(division.id, dimension.nodeId, dimension.navigationRules.parent_child, "source");
         }
-        const firstChildId = typeof options.idKey === "function" ? options.idKey(division.values[valueKeys[0]]) : options.idKey;
-        createEdge(
-          division.id,
-          division.values[valueKeys[0]][firstChildId],
-          dimension.navigationRules.parent_child,
-          "source"
-        );
+        if (valueKeys.length > 0) {
+          const firstChildId = typeof options.idKey === "function" ? options.idKey(division.values[valueKeys[0]]) : options.idKey;
+          createEdge(
+            division.id,
+            division.values[valueKeys[0]][firstChildId],
+            dimension.navigationRules.parent_child,
+            "source"
+          );
+        }
         let i = 0;
         if (valueKeys.length >= 1) {
           valueKeys.forEach((vk) => {
@@ -1588,6 +1602,8 @@ var text_chat_default = (options) => {
     commandLabels = {},
     onNavigate,
     onExit,
+    onClick,
+    onHover,
     llm,
     data
   } = options;
@@ -1757,7 +1773,7 @@ var text_chat_default = (options) => {
   } else {
     addSystemMessage('Text navigation ready. Type "enter" to begin or "help" for available commands.');
   }
-  const specialCommands = ["enter", "help", "more", "more help", "clear"];
+  const specialCommands = ["enter", "help", "more", "more help", "clear", "click", "select", "hover", "inspect"];
   const moveToNode = (nodeId) => {
     const node = inputHandler.moveTo(nodeId);
     if (node) {
@@ -1808,15 +1824,55 @@ var text_chat_default = (options) => {
     }
     if (lower === "help") {
       const llmHint = llm ? " You can also type any question about the data." : "";
+      const interactionHints = [];
+      if (onClick)
+        interactionHints.push('"click" or "select"');
+      if (onHover)
+        interactionHints.push('"hover" or "inspect"');
+      const interactionSuffix = interactionHints.length ? ` Interaction: ${interactionHints.join(", ")}.` : "";
       if (!currentNodeId) {
         addResponse(
-          'Not yet in the structure. Type "enter" to begin navigating, or "move to <search>" to jump to a node.' + llmHint
+          'Not yet in the structure. Type "enter" to begin navigating, or "move to <search>" to jump to a node.' + interactionSuffix + llmHint
         );
       } else {
         const node = structure.nodes[currentNodeId];
         const available = getAvailableRules(currentNodeId, node, structure);
         const formatted = available.map((r) => formatRule(r, commandLabels));
-        addResponse(`Available: ${formatted.join(", ")}, move to <search>.` + llmHint);
+        addResponse(
+          `Available: ${formatted.join(", ")}, move to <search>.` + interactionSuffix + llmHint
+        );
+      }
+      return;
+    }
+    if (lower === "click" || lower === "select") {
+      if (!currentNodeId) {
+        addResponse('Not in the structure. Type "enter" to begin.');
+        return;
+      }
+      const node = structure.nodes[currentNodeId];
+      if (onClick && node) {
+        onClick(node);
+        addResponse(`Clicked: ${describeNode2(node)}`);
+      } else {
+        addResponse(
+          onClick ? "Nothing to click here." : "Click interaction is not enabled for this chart."
+        );
+      }
+      return;
+    }
+    if (lower === "hover" || lower === "inspect") {
+      if (!currentNodeId) {
+        addResponse('Not in the structure. Type "enter" to begin.');
+        return;
+      }
+      const node = structure.nodes[currentNodeId];
+      if (onHover && node) {
+        onHover(node);
+        addResponse(`Hovering over: ${describeNode2(node)}`);
+      } else {
+        addResponse(
+          onHover ? "Nothing to hover over here." : "Hover interaction is not enabled for this chart."
+        );
       }
       return;
     }

package/dist/index.d.cts

@@ -0,0 +1,265 @@
+type StructureOptions = {
+    data: GenericDataset;
+    idKey: DynamicNodeIdKey;
+    renderIdKey?: DynamicRenderIdKey;
+    dimensions?: DimensionOptions;
+    genericEdges?: EdgeOptions;
+    useDirectedEdges?: boolean;
+    dataType?: DataType;
+    addIds?: boolean;
+    keysForIdGeneration?: KeyList;
+    navigationRules?: NavigationRules;
+};
+type InputOptions = {
+    structure: Structure;
+    navigationRules: NavigationRules;
+    entryPoint?: NodeId;
+    exitPoint?: RenderId;
+};
+type RenderingOptions = {
+    elementData: ElementData | Nodes;
+    suffixId: string;
+    root: RootObject;
+    defaults?: RenderObject;
+    entryButton?: EntryObject;
+    exitElement?: ExitObject;
+};
+type DimensionOptions = {
+    values: DimensionList;
+    parentOptions?: {
+        level1Options?: {
+            order: AddOrReferenceNodeList;
+            behavior?: Level1Behavior;
+            navigationRules?: DimensionNavigationRules;
+        };
+        addLevel0?: NodeObject;
+    };
+    adjustDimensions?: AdjustingFunction;
+};
+type Structure = {
+    nodes: Nodes;
+    edges: Edges;
+    dimensions?: Dimensions;
+    navigationRules?: NavigationRules;
+    elementData?: ElementData;
+};
+type Nodes = Record<NodeId, NodeObject>;
+type Edges = Record<EdgeId, EdgeObject>;
+type Dimensions = Record<DimensionKey, DimensionObject>;
+type NavigationRules = Record<NavId, NavObject>;
+type ElementData = Record<RenderId, RenderObject>;
+type DimensionDivisions = Record<NodeId, DivisionObject>;
+type AddOrReferenceNodeList = Array<NodeToAddOrReference>;
+type EdgeList = Array<EdgeId>;
+type GenericDataset = Array<DatumObject>;
+type NavigationList = Array<NavId>;
+type DimensionNavigationPair = [NavId, NavId];
+type NumericalExtentsPair = [number, number];
+type DimensionList = Array<DimensionDatum>;
+type EdgeOptions = Array<EdgeDatum>;
+type KeyList = Array<string>;
+type Semantics = ((RenderObject?: any, DatumObject?: any) => SemanticsObject) | SemanticsObject;
+type SpatialProperties = ((RenderObject?: any, DatumObject?: any) => SpatialObject) | SpatialObject;
+type Attributes = ((RenderObject?: any, DatumObject?: any) => AttributesObject) | AttributesObject;
+type NodeObject = {
+    id: NodeId;
+    edges: EdgeList;
+    renderId?: RenderId;
+    renderingStrategy?: RenderingStrategy;
+    derivedNode?: DerivedNode;
+    dimensionLevel?: DimensionLevel;
+    [key: string | number]: any;
+};
+type EdgeObject = {
+    source: ((d: DatumObject, currentFocus: NodeId) => NodeId) | NodeId;
+    target: ((d: DatumObject, currentFocus: NodeId) => NodeId) | NodeId;
+    navigationRules: NavigationList;
+    edgeId?: EdgeId;
+};
+type EdgeDatum = {
+    edgeId: EdgeId;
+    edge: EdgeObject;
+    conditional?: ConditionalFunction;
+};
+type DimensionObject = {
+    nodeId: NodeId;
+    dimensionKey: DimensionKey;
+    divisions: DimensionDivisions;
+    operations: {
+        compressSparseDivisions: boolean;
+        sortFunction?: SortingFunction;
+    };
+    behavior?: DimensionBehavior;
+    navigationRules?: DimensionNavigationRules;
+    type?: DimensionType;
+    numericalExtents?: NumericalExtentsPair;
+    subdivisions?: NumericallySubdivide;
+    divisionOptions?: DivisionOptions;
+};
+type DimensionDatum = {
+    dimensionKey: DimensionKey;
+    behavior?: DimensionBehavior;
+    navigationRules?: DimensionNavigationRules;
+    type?: DimensionType;
+    operations?: DimensionOperations;
+    nodeId?: DynamicDimensionId;
+    renderId?: DynamicDimensionRenderId;
+    renderingStrategy?: RenderingStrategy;
+    divisionOptions?: DivisionOptions;
+};
+type DimensionNavigationRules = {
+    sibling_sibling: DimensionNavigationPair;
+    parent_child: DimensionNavigationPair;
+};
+type DivisionOptions = {
+    sortFunction?: SortingFunction;
+    divisionNodeIds?: (dimensionKey: DimensionKey, keyValue: any, i: number) => string;
+    divisionRenderIds?: (dimensionKey: DimensionKey, keyValue: any, i: number) => string;
+    renderingStrategy?: RenderingStrategy;
+};
+type DimensionOperations = {
+    filterFunction?: FilteringFunction;
+    sortFunction?: SortingFunction;
+    createNumericalSubdivisions?: NumericallySubdivide;
+    compressSparseDivisions?: boolean;
+};
+type DivisionObject = {
+    id: NodeId;
+    values: Nodes;
+    sortFunction?: SortingFunction;
+    numericalExtents?: NumericalExtentsPair;
+};
+type NavObject = {
+    direction: Direction;
+    key?: string;
+};
+type RenderObject = {
+    cssClass?: DynamicString;
+    spatialProperties?: SpatialProperties;
+    semantics?: Semantics;
+    parentSemantics?: Semantics;
+    existingElement?: ExistingElement;
+    showText?: boolean;
+};
+type RootObject = {
+    id: string;
+    cssClass?: string;
+    description?: string;
+    width?: string | number;
+    height?: string | number;
+};
+type EntryObject = {
+    include: boolean;
+    callbacks?: EntryCallbacks;
+};
+type ExitObject = {
+    include: boolean;
+    callbacks?: ExitCallbacks;
+};
+type SemanticsObject = {
+    label?: DynamicString;
+    elementType?: DynamicString;
+    role?: DynamicString;
+    attributes?: Attributes;
+};
+type SpatialObject = {
+    x?: DynamicNumber;
+    y?: DynamicNumber;
+    width?: DynamicNumber;
+    height?: DynamicNumber;
+    path?: DynamicString;
+};
+type DimensionBehavior = {
+    extents: ExtentType;
+    customBridgePrevious?: NodeId;
+    customBridgePost?: NodeId;
+    childmostNavigation?: ChildmostNavigationStrategy;
+    childmostMatching?: ChildmostMatchingStrategy;
+};
+type Level1Behavior = {
+    extents: Level0ExtentType;
+    customBridgePrevious?: NodeId;
+    customBridgePost?: NodeId;
+};
+type DescriptionOptions = {
+    omitKeyNames?: boolean;
+    semanticLabel?: string;
+};
+type ExistingElement = {
+    useForSpatialProperties: boolean;
+    spatialProperties?: SpatialProperties;
+};
+type EntryCallbacks = {
+    focus?: Function;
+    click?: Function;
+};
+type ExitCallbacks = {
+    focus?: Function;
+    blur?: Function;
+};
+type DatumObject = {
+    [key: string | number]: any;
+};
+type AttributesObject = {
+    [key: string]: string;
+};
+type DynamicNumber = ((r?: RenderObject, d?: DatumObject) => number) | number;
+type DynamicString = ((r?: RenderObject, d?: DatumObject) => string) | string;
+type DynamicNodeId = ((d?: DatumObject, dim?: DimensionDatum) => NodeId) | NodeId;
+type DynamicRenderId = ((d?: DatumObject) => RenderId) | RenderId;
+type DynamicNodeIdKey = ((d?: DatumObject) => string) | string;
+type DynamicRenderIdKey = ((d?: DatumObject) => string) | string;
+type DynamicDimensionId = ((d?: DimensionDatum, a?: GenericDataset) => NodeId) | NodeId;
+type DynamicDimensionRenderId = ((d?: DimensionDatum, a?: GenericDataset) => RenderId) | RenderId;
+type NumericallySubdivide = ((d?: DimensionKey, n?: Nodes) => number) | number;
+type ChildmostMatchingStrategy = (index?: number, currentDivisionChild?: DatumObject, currentDivision?: DivisionObject, nextDivision?: DivisionObject) => DatumObject | undefined;
+type AdjustingFunction = (d: Dimensions) => Dimensions;
+type SortingFunction = (a: DatumObject, b: DatumObject, c?: any) => number;
+type FilteringFunction = (a: DatumObject, b?: any) => boolean;
+type ConditionalFunction = (n: NodeObject, d: EdgeDatum) => boolean;
+type NodeId = string;
+type EdgeId = string;
+type RenderId = string;
+type NavId = string;
+type DimensionId = string;
+type DimensionKey = string;
+type NodeToAddOrReference = NodeObject | NodeId;
+type Direction = 'target' | 'source';
+type RenderingStrategy = 'outlineEach' | 'convexHull' | 'singleSquare' | 'custom';
+type DimensionType = 'numerical' | 'categorical';
+type ExtentType = 'circular' | 'terminal' | 'bridgedCousins' | 'bridgedCustom';
+type ChildmostNavigationStrategy = 'within' | 'across';
+type Level0ExtentType = 'circular' | 'terminal' | 'bridgedCustom';
+type DataType = 'vega-lite' | 'vl' | 'Vega-Lite' | 'generic' | 'default';
+type DimensionLevel = 0 | 1 | 2 | 3;
+type DerivedNode = string;
+type LLMMessage = {
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+};
+type TextChatOptions = {
+    structure: Structure;
+    container: string | HTMLElement;
+    entryPoint?: NodeId;
+    describeNode?: (node: NodeObject) => string;
+    commandLabels?: Record<string, string>;
+    onNavigate?: (node: NodeObject) => void;
+    onExit?: () => void;
+    onClick?: (node: NodeObject) => void;
+    onHover?: (node: NodeObject) => void;
+    llm?: (messages: LLMMessage[]) => Promise<string | null>;
+    data?: Record<string, unknown>[];
+};
+type TextChatInstance = {
+    destroy: () => void;
+    getCurrentNode: () => NodeObject | null;
+};
+
+declare const _default: {
+    structure: (options: StructureOptions) => Structure;
+    input: (options: InputOptions) => any;
+    rendering: (options: RenderingOptions) => any;
+    textChat: (options: TextChatOptions) => TextChatInstance;
+};
+
+export { type AddOrReferenceNodeList, type AdjustingFunction, type Attributes, type AttributesObject, type ChildmostMatchingStrategy, type ChildmostNavigationStrategy, type ConditionalFunction, type DataType, type DatumObject, type DerivedNode, type DescriptionOptions, type DimensionBehavior, type DimensionDatum, type DimensionDivisions, type DimensionId, type DimensionKey, type DimensionLevel, type DimensionList, type DimensionNavigationPair, type DimensionNavigationRules, type DimensionObject, type DimensionOperations, type DimensionOptions, type DimensionType, type Dimensions, type Direction, type DivisionObject, type DivisionOptions, type DynamicDimensionId, type DynamicDimensionRenderId, type DynamicNodeId, type DynamicNodeIdKey, type DynamicNumber, type DynamicRenderId, type DynamicRenderIdKey, type DynamicString, type EdgeDatum, type EdgeId, type EdgeList, type EdgeObject, type EdgeOptions, type Edges, type ElementData, type EntryCallbacks, type EntryObject, type ExistingElement, type ExitCallbacks, type ExitObject, type ExtentType, type FilteringFunction, type GenericDataset, type InputOptions, type KeyList, type LLMMessage, type Level0ExtentType, type Level1Behavior, type NavId, type NavObject, type NavigationList, type NavigationRules, type NodeId, type NodeObject, type NodeToAddOrReference, type Nodes, type NumericalExtentsPair, type NumericallySubdivide, type RenderId, type RenderObject, type RenderingOptions, type RenderingStrategy, type RootObject, type Semantics, type SemanticsObject, type SortingFunction, type SpatialObject, type SpatialProperties, type Structure, type StructureOptions, type TextChatInstance, type TextChatOptions, _default as default };