@malloydata/render 0.0.323 → 0.0.325

package/CONTEXT.md

@@ -0,0 +1,93 @@
+# Malloy Render
+
+The `malloy-render` package handles visualization and rendering of Malloy query results. It transforms query results into rich, interactive visualizations and tables.
+
+## Purpose
+
+Malloy queries return structured data with metadata about how it should be displayed. The render package:
+- Interprets query result metadata
+- Generates appropriate visualizations
+- Provides interactive data exploration
+- Supports multiple rendering formats
+
+## Technology Stack
+
+### Solid.js
+The rendering system uses **Solid.js** as its reactive UI framework.
+
+### Vega
+The package uses **Vega** for declarative data visualizations.
+
+## Rendering Process
+
+```
+Query Results + Metadata → Renderer → Visualization Selection → Vega Spec / Table → UI Output
+```
+
+**Steps:**
+1. Query results arrive with rendering metadata
+2. Renderer examines result structure and annotations
+3. Appropriate visualization type is selected
+4. Vega specification is generated (for charts) or table is formatted
+5. UI components render the visualization
+
+## Rendering Hints
+
+The renderer respects annotations and metadata from Malloy models:
+
+- **Renderer annotations** (prefix `# `) provide display hints
+- **Field types** influence default visualizations
+- **Data structure** (nested, flat, aggregated) affects rendering choices
+- **User preferences** can override defaults
+
+## Visualization Types
+
+The renderer supports various output formats:
+
+- **Tables** - Default for most query results
+- **Bar charts** - For categorical comparisons
+- **Line charts** - For time series data
+- **Scatter plots** - For correlation analysis
+- **Nested tables** - For hierarchical data
+- **Sparklines** - For inline visualizations
+- And more...
+
+## Package Integration
+
+The render package integrates with:
+- **malloy-core** - Consumes query results and metadata
+- **VS Code extension** - Provides visualization in editor
+- **Web applications** - Can be embedded in web apps
+- **Reports** - Generates static visualizations
+
+## Architecture
+
+### Two Renderers
+- **New renderer** (`src/component/`) - Solid.js-based, the default
+- **Legacy renderer** (`src/html/`) - HTML string-based, activated with `## renderer_legacy` model tag
+
+### Tag System
+Render annotations use the Malloy Tag API to check for rendering hints. For tag language syntax, see [packages/malloy-tag/CONTEXT.md](../malloy-tag/CONTEXT.md).
+
+Common API patterns in the renderer:
+- `field.tag.has('pivot')` - Check if a tag exists
+- `field.tag.text('label')` - Get a text property
+- `field.tag.textArray('pivot', 'dimensions')` - Get array property with path
+- `field.tag.tag('table', 'size')` - Navigate nested tag properties
+
+### Table Layout
+The table uses CSS Grid with subgrid. Layout is calculated in `table-layout.ts`:
+- `getTableLayout()` - Creates base layout from field structure
+- `adjustLayoutForPivots()` - Adjusts column counts for pivot expansion
+- Column ranges are tracked for each field to support nested tables
+
+### Testing
+Use Storybook (`npm run storybook`) to test visual changes. Stories are in `src/stories/*.stories.malloy`.
+
+## Important Notes
+
+- Rendering is **separate from query execution** - it only processes results
+- The renderer is **stateless** - same results produce same visualizations
+- Visualizations respect **user accessibility** preferences where possible
+- The package is designed to be **embeddable** in various contexts
+- **Never run the full test suite** without restrictions - use targeted tests or storybook

package/dist/module/component/table/pivot-cells.d.ts

@@ -0,0 +1,13 @@
+import { JSX } from 'solid-js';
+import { RecordCell } from '../../data_tree';
+import { PivotConfig } from './pivot-utils';
+/**
+ * Renders all pivot cells for one row's nested pivot field.
+ */
+export declare const PivotFieldCells: (props: {
+    row: RecordCell;
+    pivotConfig: PivotConfig;
+    rowPath: number[];
+    startColumn: number;
+}) => JSX.Element;
+export default PivotFieldCells;

package/dist/module/component/table/pivot-header.d.ts

@@ -0,0 +1,22 @@
+import { Field } from '../../data_tree';
+import { PivotConfig } from './pivot-utils';
+/**
+ * Info about a sibling field (non-pivot field at same depth as pivot).
+ */
+export type SiblingFieldInfo = {
+    field: Field;
+    startColumn: number;
+    endColumn: number;
+};
+/**
+ * Renders all header rows for a pivot field.
+ * Row 1: Empty for siblings + dimension values with colspan
+ * Row 2: Sibling headers + measure names repeated
+ */
+export declare const PivotHeaders: (props: {
+    pivotConfig: PivotConfig;
+    pivotStartColumn: number;
+    totalColumns: number;
+    siblingFields: SiblingFieldInfo[];
+}) => import("solid-js").JSX.Element;
+export default PivotHeaders;

package/dist/module/component/table/pivot-utils.d.ts

@@ -0,0 +1,127 @@
+import { Cell, Field, NestField, RecordOrRepeatedRecordCell, RecordOrRepeatedRecordField, SortableField } from '../../data_tree';
+/**
+ * Represents a unique combination of dimension values in a pivot.
+ * Each PivotedField corresponds to one set of column headers.
+ */
+export type PivotedField = {
+    /** JSON-stringified key for lookup (includes parent field name and dimension values) */
+    key: string;
+    /** The dimension cell values for this pivot combination */
+    values: Cell[];
+    /** The parent nested field being pivoted */
+    parentField: RecordOrRepeatedRecordField;
+    /** Number of non-dimension (measure) columns this spans */
+    span: number;
+    /** Map from dimension field name to cell value for quick lookup */
+    fieldValueMap: Map<string, Cell>;
+};
+/**
+ * Represents a single column in a pivoted table.
+ * Combines a specific dimension value combination with a measure field.
+ */
+export type PivotedColumnField = {
+    /** The pivot dimension combination */
+    pivotedField: PivotedField;
+    /** The actual measure field to render */
+    field: Field;
+    /** User-defined dimension fields (if specified) */
+    userDefinedPivotDimensions?: string[];
+};
+export type { SortableField };
+/**
+ * Complete configuration for a pivot field.
+ */
+export type PivotConfig = {
+    /** The nested field being pivoted */
+    field: NestField;
+    /** Dimension fields (used for column headers) */
+    dimensions: SortableField[];
+    /** Non-dimension fields (measures to display) */
+    nonDimensions: SortableField[];
+    /** All unique dimension value combinations, sorted */
+    pivotedFields: PivotedField[];
+    /** Expanded column list: pivotedFields * nonDimensions */
+    columnFields: PivotedColumnField[];
+    /** Max number of dimension levels (for header row depth) */
+    pivotDepth: number;
+};
+/** Maximum number of pivot columns allowed */
+export declare const PIVOT_COLUMN_LIMIT = 30;
+/** Maximum number of transpose columns allowed */
+export declare const TRANSPOSE_COLUMN_LIMIT = 20;
+/**
+ * Creates a unique key for a pivot dimension combination.
+ */
+export declare function createPivotKey(parentField: RecordOrRepeatedRecordField, values: Cell[]): string;
+/**
+ * Separates fields into dimensions and non-dimensions (measures).
+ *
+ * @param field The nested field being pivoted
+ * @param userDimensions Optional explicit dimension field names
+ * @returns Object with dimensions and nonDimensions arrays
+ */
+export declare function calculatePivotDimensions(field: NestField, userDimensions?: string[]): {
+    dimensions: SortableField[];
+    nonDimensions: SortableField[];
+};
+/**
+ * Collects all unique dimension value combinations across all rows of data.
+ *
+ * @param field The nested field being pivoted
+ * @param data The parent table data
+ * @param dimensions The dimension fields to extract values from
+ * @returns Map of pivot keys to PivotedField objects
+ */
+export declare function collectPivotedFields(field: NestField, data: RecordOrRepeatedRecordCell, dimensions: SortableField[], nonDimensionCount: number): Map<string, PivotedField>;
+/**
+ * Sorts pivoted fields by their dimension values.
+ * Uses Cell.compareTo() for type-appropriate sorting.
+ *
+ * @param pivotedFields Array of PivotedField objects
+ * @param dimensions Dimension fields with sort direction
+ * @returns Sorted array
+ */
+export declare function sortPivotedFields(pivotedFields: PivotedField[], dimensions: SortableField[]): PivotedField[];
+/**
+ * Expands sorted pivot fields into individual column fields.
+ * Each pivot combination * each non-dimension = one column.
+ *
+ * @param pivotedFields Sorted array of PivotedField objects
+ * @param nonDimensions Non-dimension (measure) fields
+ * @param userDimensions Optional user-specified dimension names
+ * @returns Array of PivotedColumnField objects
+ */
+export declare function expandPivotColumns(pivotedFields: PivotedField[], nonDimensions: SortableField[], userDimensions?: string[]): PivotedColumnField[];
+/**
+ * Builds a complete pivot configuration for a nested field.
+ *
+ * @param field The nested field with # pivot tag
+ * @param data The parent table data
+ * @param userDimensions Optional explicit dimension field names
+ * @returns PivotConfig or null if pivot cannot be created
+ */
+export declare function buildPivotConfig(field: NestField, data: RecordOrRepeatedRecordCell, userDimensions?: string[]): PivotConfig;
+/**
+ * Generates a map of pivot keys to cell values for a single row's nested data.
+ * Used during rendering to look up the correct cell for each pivot column.
+ *
+ * @param nestedCell The nested record data for one row
+ * @param pivotConfig The pivot configuration
+ * @returns Map from pivot key to map of field name to cell
+ */
+export declare function generatePivotedCellsMap(nestedCell: RecordOrRepeatedRecordCell, pivotConfig: PivotConfig): Map<string, Map<string, Cell>>;
+/**
+ * Gets the pivot dimension values to display in a cell.
+ * Used for rendering dimension value header cells.
+ */
+export declare function getPivotDimensionValue(pivotedField: PivotedField, dimensionIndex: number): Cell | undefined;
+/**
+ * Checks if a field should be rendered as a pivot table.
+ * Syntax: # pivot
+ */
+export declare function shouldPivot(field: Field): boolean;
+/**
+ * Gets user-defined pivot dimensions from the tag.
+ * Syntax: # pivot { dimensions=[d1, d2] }
+ */
+export declare function getUserDefinedDimensions(field: Field): string[] | undefined;

package/dist/module/component/table/table-context.d.ts

@@ -1,5 +1,6 @@
 import { SetStoreFunction, Store, createStore } from 'solid-js/store';
 import { TableLayout } from './table-layout';
+import { PivotConfig } from './pivot-utils';
 type TableStore = {
     headerSizes: Record<string, number>;
     columnWidths: Record<string, number>;
@@ -15,6 +16,8 @@ export type TableContext = {
     headerSizeStore: ReturnType<typeof createStore<Record<string, number>>>;
     currentRow: number[];
     currentExplore: string[];
+    /** Map of field key to pivot configuration */
+    pivotConfigs: Map<string, PivotConfig>;
 };
 export declare const TableContext: import('solid-js').Context<TableContext | undefined>;
 export declare const useTableContext: () => TableContext | undefined;

package/dist/module/component/table/table-layout.d.ts

@@ -1,5 +1,6 @@
 import { Field, NestField } from '../../data_tree';
 import { FieldHeaderRangeMap } from '../types';
+import { PivotConfig } from './pivot-utils';
 type LayoutEntry = {
     field: Field;
     width: number | null;
@@ -16,4 +17,13 @@ export type TableLayout = {
     maxDepth: number;
 };
 export declare function getTableLayout(rootField: NestField): TableLayout;
+/**
+ * Adjusts a table layout to account for pivot column expansion.
+ * Pivot fields may have more columns than their original nested structure.
+ *
+ * @param layout The original table layout
+ * @param pivotConfigs Map of field keys to their pivot configurations
+ * @returns Adjusted layout with correct column counts for pivot fields
+ */
+export declare function adjustLayoutForPivots(layout: TableLayout, pivotConfigs: Map<string, PivotConfig>): TableLayout;
 export {};

package/dist/module/component/table/transpose-table.d.ts

@@ -0,0 +1,16 @@
+import { Component } from 'solid-js';
+import { RecordOrRepeatedRecordCell, Field } from '../../data_tree';
+/**
+ * TransposeTable renders a table with rows and columns swapped.
+ * Each field becomes a row, and each data record becomes a column.
+ */
+declare const TransposeTable: Component<{
+    data: RecordOrRepeatedRecordCell;
+    rowLimit?: number;
+}>;
+export default TransposeTable;
+/**
+ * Checks if a field should be rendered as a transposed table.
+ * Syntax: # transpose
+ */
+export declare function shouldTranspose(field: Field): boolean;