data-navigator 2.4.1 → 3.2.0

package/dist/index.d.cts

@@ -9,6 +9,61 @@ type StructureOptions = {
     addIds?: boolean;
     keysForIdGeneration?: KeyList;
     navigationRules?: NavigationRules;
+    frame?: FrameOptions;
+    spatialGrid?: SpatialGridOptions;
+    hierarchy?: HierarchyOptions;
+};
+type FrameOptions = {
+    root: NodeObject;
+    elements: Array<NodeObject>;
+    data?: NodeObject;
+    behavior?: {
+        extents: 'circular' | 'terminal';
+    };
+    navigationRules?: DimensionNavigationRules;
+};
+type FrameInfo = {
+    rootId: NodeId;
+    elementIds: Array<NodeId>;
+    dataId: NodeId;
+    parentRules: DimensionNavigationPair;
+};
+type SpatialGridOptions = {
+    xKey: string;
+    yKey: string;
+    xExtent?: NumericalExtentsPair;
+    yExtent?: NumericalExtentsPair;
+    levels: Array<number>;
+    leaves?: 'points' | 'cells';
+    levelNavigation?: 'across' | 'within';
+    skipEmpty?: boolean;
+    extents?: 'terminal' | 'circular';
+    root?: NodeObject;
+    cellIds?: (level: number, col: number, row: number) => NodeId;
+    navigationRules?: {
+        x?: DimensionNavigationPair;
+        y?: DimensionNavigationPair;
+        parent_child?: DimensionNavigationPair;
+    };
+};
+type SpatialGridInfo = {
+    rootId: NodeId;
+    levels: Array<number>;
+    cellsByLevel: Array<Array<NodeId>>;
+    leafIds: Array<NodeId>;
+    parentRules: DimensionNavigationPair;
+};
+type HierarchyOptions = {
+    parentKey: string;
+    sortFunction?: SortingFunction;
+    levelNavigation?: 'within' | 'across';
+    extents?: 'circular' | 'terminal';
+    navigationRules?: DimensionNavigationRules;
+};
+type HierarchyInfo = {
+    rootId: NodeId;
+    depthCount: number;
+    parentRules: DimensionNavigationPair;
 };
 type InputOptions = {
     structure: Structure;
@@ -23,6 +78,7 @@ type RenderingOptions = {
     defaults?: RenderObject;
     entryButton?: EntryObject;
     exitElement?: ExitObject;
+    commandsElement?: CommandsObject;
 };
 type DimensionOptions = {
     values: DimensionList;
@@ -42,6 +98,9 @@ type Structure = {
     dimensions?: Dimensions;
     navigationRules?: NavigationRules;
     elementData?: ElementData;
+    frame?: FrameInfo;
+    spatialGrid?: SpatialGridInfo;
+    hierarchy?: HierarchyInfo;
 };
 type Nodes = Record<NodeId, NodeObject>;
 type Edges = Record<EdgeId, EdgeObject>;
@@ -68,6 +127,9 @@ type NodeObject = {
     renderingStrategy?: RenderingStrategy;
     derivedNode?: DerivedNode;
     dimensionLevel?: DimensionLevel;
+    parentId?: NodeId;
+    depth?: number;
+    frameRole?: 'root' | 'element' | 'data';
     [key: string | number]: any;
 };
 type EdgeObject = {
@@ -156,6 +218,24 @@ type ExitObject = {
     include: boolean;
     callbacks?: ExitCallbacks;
 };
+type CommandsObject = {
+    include: boolean;
+    rootId?: string;
+    navigationRules?: NavigationRules;
+    commands?: Array<CommandObject> | ((genericCommands: Array<CommandObject>) => Array<CommandObject>);
+    descriptions?: Record<NavId, string>;
+    columns?: Array<{
+        label: string;
+        id: string;
+    }>;
+    title?: string;
+};
+type CommandObject = {
+    label: string;
+    description: string;
+    command?: NavId;
+    [key: string]: any;
+};
 type SemanticsObject = {
     label?: DynamicString;
     elementType?: DynamicString;
@@ -225,7 +305,7 @@ type DimensionId = string;
 type DimensionKey = string;
 type NodeToAddOrReference = NodeObject | NodeId;
 type Direction = 'target' | 'source';
-type RenderingStrategy = 'outlineEach' | 'convexHull' | 'singleSquare' | 'custom';
+type RenderingStrategy = 'convexHull' | 'unionOfAll' | 'boundingRect' | 'custom';
 type DimensionType = 'numerical' | 'categorical';
 type ExtentType = 'circular' | 'terminal' | 'bridgedCousins' | 'bridgedCustom';
 type ChildmostNavigationStrategy = 'within' | 'across';
@@ -255,6 +335,93 @@ type TextChatInstance = {
     getCurrentNode: () => NodeObject | null;
 };
 
+/**
+ * geometry — Pure SVG path geometry utilities for data navigation group shapes.
+ *
+ * All functions are side-effect-free: input is arrays of Rect/Point objects,
+ * output is an SVG path `d` string ready to set on a <path d="..."> element.
+ *
+ * Exported from the data-navigator core library so downstream tools (e.g.
+ * the Skeleton scaffolding app) can import them, and they can be packaged
+ * independently in future export flows.
+ */
+type Rect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+type Point = {
+    x: number;
+    y: number;
+};
+type Circle = Point & {
+    r: number;
+};
+/**
+ * Compute the convex hull of a set of 2-D points using the Graham scan
+ * algorithm. Returns the hull vertices in counter-clockwise order.
+ * Returns an empty array when fewer than 3 distinct points are supplied.
+ */
+declare function grahamScan(points: Point[]): Point[];
+/**
+ * Convex hull of a set of points as a closed SVG path string.
+ * Returns empty string when fewer than 2 points are given.
+ */
+declare function convexHullPath(points: Point[]): string;
+/**
+ * Expand a convex hull polygon outward from its centroid by `padPx` pixels.
+ * Each hull vertex is pushed radially away from the centroid.
+ */
+declare function expandHull(hullPoints: Point[], padPx: number): Point[];
+/**
+ * Convex hull of a set of axis-aligned rectangles.
+ * Collects all 4 corners of every rect and runs Graham scan.
+ * Returns a closed SVG path string.
+ */
+declare function convexHullOfRects(rects: Rect[], padPx?: number): string;
+/**
+ * Convert an array of rects into an SVG path containing one M…Z subpath per
+ * rect. This is a "true union" — non-overlapping marks each get their own
+ * outlined region. SVG fill-rule handles interior fill for all subpaths.
+ *
+ * @param padPx  Optional padding added to every rect before generating paths.
+ */
+declare function unionOfRectPaths(rects: Rect[], padPx?: number): string;
+/**
+ * Single axis-aligned bounding rect enclosing all input rects.
+ * Returns a closed SVG path string (one M…Z rectangle).
+ *
+ * @param padPx  Optional outward padding added to the resulting bounding box.
+ */
+declare function boundingRectPath(rects: Rect[], padPx?: number): string;
+/**
+ * Convex hull of a set of circles.
+ * Each circle is approximated by 16 sample points on its circumference before
+ * running Graham scan. The result is a polygon that is tangent (or very close)
+ * to the outer boundary of all circles.
+ *
+ * Used for scatter plots and line-chart interval groupings where marks are
+ * circular (not rectangular).
+ */
+declare function convexHullOfCircles(circles: Circle[], padPx?: number): string;
+/**
+ * Create a "fat" closed path around a polyline by tracing it at ±offsetPx
+ * using perpendicular offsets at each segment.
+ *
+ * The result is a single closed SVG path that looks like the line rendered
+ * with a stroke of width `offsetPx * 2`. Ideal for line-chart series grouping.
+ *
+ * @param points    Ordered control points of the polyline (left to right).
+ * @param offsetPx  Half-width of the resulting fat path.
+ */
+declare function offsetLinePath(points: Point[], offsetPx: number): string;
+
+declare const describeNode: (d: DatumObject, descriptionOptions?: DescriptionOptions) => string;
+declare const createValidId: (s: string) => string;
+declare const keyLabel: (code?: string) => string;
+declare function getGenericCommandsFromNavRules(navigationRules?: NavigationRules, descriptions?: Record<NavId, string>): CommandObject[];
+
 declare const _default: {
     structure: (options: StructureOptions) => Structure;
     input: (options: InputOptions) => any;
@@ -262,4 +429,4 @@ declare const _default: {
     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 };
+export { type AddOrReferenceNodeList, type AdjustingFunction, type Attributes, type AttributesObject, type ChildmostMatchingStrategy, type ChildmostNavigationStrategy, type Circle, type CommandObject, type CommandsObject, 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 FrameInfo, type FrameOptions, type GenericDataset, type HierarchyInfo, type HierarchyOptions, 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 Point, type Rect, type RenderId, type RenderObject, type RenderingOptions, type RenderingStrategy, type RootObject, type Semantics, type SemanticsObject, type SortingFunction, type SpatialGridInfo, type SpatialGridOptions, type SpatialObject, type SpatialProperties, type Structure, type StructureOptions, type TextChatInstance, type TextChatOptions, boundingRectPath, convexHullOfCircles, convexHullOfRects, convexHullPath, createValidId, _default as default, describeNode, expandHull, getGenericCommandsFromNavRules, grahamScan, keyLabel, offsetLinePath, unionOfRectPaths };

package/dist/index.d.ts

@@ -9,6 +9,61 @@ type StructureOptions = {
     addIds?: boolean;
     keysForIdGeneration?: KeyList;
     navigationRules?: NavigationRules;
+    frame?: FrameOptions;
+    spatialGrid?: SpatialGridOptions;
+    hierarchy?: HierarchyOptions;
+};
+type FrameOptions = {
+    root: NodeObject;
+    elements: Array<NodeObject>;
+    data?: NodeObject;
+    behavior?: {
+        extents: 'circular' | 'terminal';
+    };
+    navigationRules?: DimensionNavigationRules;
+};
+type FrameInfo = {
+    rootId: NodeId;
+    elementIds: Array<NodeId>;
+    dataId: NodeId;
+    parentRules: DimensionNavigationPair;
+};
+type SpatialGridOptions = {
+    xKey: string;
+    yKey: string;
+    xExtent?: NumericalExtentsPair;
+    yExtent?: NumericalExtentsPair;
+    levels: Array<number>;
+    leaves?: 'points' | 'cells';
+    levelNavigation?: 'across' | 'within';
+    skipEmpty?: boolean;
+    extents?: 'terminal' | 'circular';
+    root?: NodeObject;
+    cellIds?: (level: number, col: number, row: number) => NodeId;
+    navigationRules?: {
+        x?: DimensionNavigationPair;
+        y?: DimensionNavigationPair;
+        parent_child?: DimensionNavigationPair;
+    };
+};
+type SpatialGridInfo = {
+    rootId: NodeId;
+    levels: Array<number>;
+    cellsByLevel: Array<Array<NodeId>>;
+    leafIds: Array<NodeId>;
+    parentRules: DimensionNavigationPair;
+};
+type HierarchyOptions = {
+    parentKey: string;
+    sortFunction?: SortingFunction;
+    levelNavigation?: 'within' | 'across';
+    extents?: 'circular' | 'terminal';
+    navigationRules?: DimensionNavigationRules;
+};
+type HierarchyInfo = {
+    rootId: NodeId;
+    depthCount: number;
+    parentRules: DimensionNavigationPair;
 };
 type InputOptions = {
     structure: Structure;
@@ -23,6 +78,7 @@ type RenderingOptions = {
     defaults?: RenderObject;
     entryButton?: EntryObject;
     exitElement?: ExitObject;
+    commandsElement?: CommandsObject;
 };
 type DimensionOptions = {
     values: DimensionList;
@@ -42,6 +98,9 @@ type Structure = {
     dimensions?: Dimensions;
     navigationRules?: NavigationRules;
     elementData?: ElementData;
+    frame?: FrameInfo;
+    spatialGrid?: SpatialGridInfo;
+    hierarchy?: HierarchyInfo;
 };
 type Nodes = Record<NodeId, NodeObject>;
 type Edges = Record<EdgeId, EdgeObject>;
@@ -68,6 +127,9 @@ type NodeObject = {
     renderingStrategy?: RenderingStrategy;
     derivedNode?: DerivedNode;
     dimensionLevel?: DimensionLevel;
+    parentId?: NodeId;
+    depth?: number;
+    frameRole?: 'root' | 'element' | 'data';
     [key: string | number]: any;
 };
 type EdgeObject = {
@@ -156,6 +218,24 @@ type ExitObject = {
     include: boolean;
     callbacks?: ExitCallbacks;
 };
+type CommandsObject = {
+    include: boolean;
+    rootId?: string;
+    navigationRules?: NavigationRules;
+    commands?: Array<CommandObject> | ((genericCommands: Array<CommandObject>) => Array<CommandObject>);
+    descriptions?: Record<NavId, string>;
+    columns?: Array<{
+        label: string;
+        id: string;
+    }>;
+    title?: string;
+};
+type CommandObject = {
+    label: string;
+    description: string;
+    command?: NavId;
+    [key: string]: any;
+};
 type SemanticsObject = {
     label?: DynamicString;
     elementType?: DynamicString;
@@ -225,7 +305,7 @@ type DimensionId = string;
 type DimensionKey = string;
 type NodeToAddOrReference = NodeObject | NodeId;
 type Direction = 'target' | 'source';
-type RenderingStrategy = 'outlineEach' | 'convexHull' | 'singleSquare' | 'custom';
+type RenderingStrategy = 'convexHull' | 'unionOfAll' | 'boundingRect' | 'custom';
 type DimensionType = 'numerical' | 'categorical';
 type ExtentType = 'circular' | 'terminal' | 'bridgedCousins' | 'bridgedCustom';
 type ChildmostNavigationStrategy = 'within' | 'across';
@@ -255,6 +335,93 @@ type TextChatInstance = {
     getCurrentNode: () => NodeObject | null;
 };
 
+/**
+ * geometry — Pure SVG path geometry utilities for data navigation group shapes.
+ *
+ * All functions are side-effect-free: input is arrays of Rect/Point objects,
+ * output is an SVG path `d` string ready to set on a <path d="..."> element.
+ *
+ * Exported from the data-navigator core library so downstream tools (e.g.
+ * the Skeleton scaffolding app) can import them, and they can be packaged
+ * independently in future export flows.
+ */
+type Rect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+type Point = {
+    x: number;
+    y: number;
+};
+type Circle = Point & {
+    r: number;
+};
+/**
+ * Compute the convex hull of a set of 2-D points using the Graham scan
+ * algorithm. Returns the hull vertices in counter-clockwise order.
+ * Returns an empty array when fewer than 3 distinct points are supplied.
+ */
+declare function grahamScan(points: Point[]): Point[];
+/**
+ * Convex hull of a set of points as a closed SVG path string.
+ * Returns empty string when fewer than 2 points are given.
+ */
+declare function convexHullPath(points: Point[]): string;
+/**
+ * Expand a convex hull polygon outward from its centroid by `padPx` pixels.
+ * Each hull vertex is pushed radially away from the centroid.
+ */
+declare function expandHull(hullPoints: Point[], padPx: number): Point[];
+/**
+ * Convex hull of a set of axis-aligned rectangles.
+ * Collects all 4 corners of every rect and runs Graham scan.
+ * Returns a closed SVG path string.
+ */
+declare function convexHullOfRects(rects: Rect[], padPx?: number): string;
+/**
+ * Convert an array of rects into an SVG path containing one M…Z subpath per
+ * rect. This is a "true union" — non-overlapping marks each get their own
+ * outlined region. SVG fill-rule handles interior fill for all subpaths.
+ *
+ * @param padPx  Optional padding added to every rect before generating paths.
+ */
+declare function unionOfRectPaths(rects: Rect[], padPx?: number): string;
+/**
+ * Single axis-aligned bounding rect enclosing all input rects.
+ * Returns a closed SVG path string (one M…Z rectangle).
+ *
+ * @param padPx  Optional outward padding added to the resulting bounding box.
+ */
+declare function boundingRectPath(rects: Rect[], padPx?: number): string;
+/**
+ * Convex hull of a set of circles.
+ * Each circle is approximated by 16 sample points on its circumference before
+ * running Graham scan. The result is a polygon that is tangent (or very close)
+ * to the outer boundary of all circles.
+ *
+ * Used for scatter plots and line-chart interval groupings where marks are
+ * circular (not rectangular).
+ */
+declare function convexHullOfCircles(circles: Circle[], padPx?: number): string;
+/**
+ * Create a "fat" closed path around a polyline by tracing it at ±offsetPx
+ * using perpendicular offsets at each segment.
+ *
+ * The result is a single closed SVG path that looks like the line rendered
+ * with a stroke of width `offsetPx * 2`. Ideal for line-chart series grouping.
+ *
+ * @param points    Ordered control points of the polyline (left to right).
+ * @param offsetPx  Half-width of the resulting fat path.
+ */
+declare function offsetLinePath(points: Point[], offsetPx: number): string;
+
+declare const describeNode: (d: DatumObject, descriptionOptions?: DescriptionOptions) => string;
+declare const createValidId: (s: string) => string;
+declare const keyLabel: (code?: string) => string;
+declare function getGenericCommandsFromNavRules(navigationRules?: NavigationRules, descriptions?: Record<NavId, string>): CommandObject[];
+
 declare const _default: {
     structure: (options: StructureOptions) => Structure;
     input: (options: InputOptions) => any;
@@ -262,4 +429,4 @@ declare const _default: {
     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 };
+export { type AddOrReferenceNodeList, type AdjustingFunction, type Attributes, type AttributesObject, type ChildmostMatchingStrategy, type ChildmostNavigationStrategy, type Circle, type CommandObject, type CommandsObject, 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 FrameInfo, type FrameOptions, type GenericDataset, type HierarchyInfo, type HierarchyOptions, 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 Point, type Rect, type RenderId, type RenderObject, type RenderingOptions, type RenderingStrategy, type RootObject, type Semantics, type SemanticsObject, type SortingFunction, type SpatialGridInfo, type SpatialGridOptions, type SpatialObject, type SpatialProperties, type Structure, type StructureOptions, type TextChatInstance, type TextChatOptions, boundingRectPath, convexHullOfCircles, convexHullOfRects, convexHullPath, createValidId, _default as default, describeNode, expandHull, getGenericCommandsFromNavRules, grahamScan, keyLabel, offsetLinePath, unionOfRectPaths };