simple-table-core 3.7.6 → 3.8.0

package/dist/src/consts/general-consts.d.ts

@@ -11,3 +11,10 @@ export declare const TABLE_HEADER_CELL_WIDTH_DEFAULT = 150;
 export declare const PINNED_BORDER_WIDTH = 1;
 export declare const CHART_COLUMN_TYPES: string[];
 export declare const OPTIMAL_CHART_COLUMN_WIDTH = 150;
+export declare const AUTO_SIZE_HEAD_SAMPLE_SIZE = 25;
+export declare const AUTO_SIZE_STRIDED_SAMPLE_SIZE = 75;
+export declare const AUTO_SIZE_MAX_WIDTH = 500;
+export declare const AUTO_SIZE_OUTLIER_PERCENTILE = 95;
+export declare const AUTO_SIZE_OUTLIER_THRESHOLD = 0.5;
+export declare const AUTO_SIZE_MIN_SAMPLE_FOR_CLIP = 20;
+export declare const AUTO_SIZE_WIDTH_BUFFER = 2;

package/dist/src/core/SimpleTableVanilla.d.ts

@@ -14,6 +14,12 @@ export declare class SimpleTableVanilla {
     private localRows;
     private headers;
     private essentialAccessors;
+    /** Accessors of leaf columns that should size to content (width:"auto" or autoSizeColumns). */
+    private autoSizeAccessors;
+    /** Accessors awaiting a content-fit measurement on the next render. */
+    private pendingAutoSize;
+    /** Guard against re-entrancy while the auto-size pass re-renders. */
+    private isAutoSizing;
     private currentPage;
     private scrollTop;
     private scrollDirection;
@@ -215,6 +221,27 @@ export declare class SimpleTableVanilla {
     private updateAriaLiveRegion;
     private getRenderContext;
     private getRenderState;
+    /** A leaf column that should size to content (declared with width:"auto"). */
+    private isAutoSizeLeaf;
+    private computeAutoSizeAccessors;
+    private getAutoSizeStyleRoot;
+    /** Immutably write measured pixel widths into the leaf headers. */
+    private applyMeasuredWidths;
+    /**
+     * Measure and apply content-fit widths for any pending "auto" columns, then
+     * re-render once at the final widths. Called at the end of render(); the
+     * measurement reads the just-rendered (provisional-width) DOM and the
+     * corrective render happens in the same synchronous task, so there is no
+     * visible width snap.
+     */
+    private maybeAutoSizeColumns;
+    /**
+     * Re-run the content-fit measurement for all auto-size columns. Useful for
+     * host frameworks (e.g. React) whose custom renderers mount asynchronously:
+     * calling this from a layout effect (pre-paint) re-measures once the real
+     * renderer DOM is present, so the column fits accurately without flicker.
+     */
+    refitAutoSizeColumns(): void;
     private render;
     update(config: Partial<SimpleTableConfig>): void;
     /** @deprecated Use {@link update} — same behavior. */

package/dist/src/types/HeaderObject.d.ts

@@ -10,6 +10,12 @@ import { QuickFilterGetter } from "./QuickFilterTypes";
 export type Accessor = keyof Row | string;
 export type ColumnType = "string" | "number" | "boolean" | "date" | "enum" | "lineAreaChart" | "barChart" | "other";
 export type ShowWhen = "parentCollapsed" | "parentExpanded" | "always";
+/**
+ * Controls what an auto-sized column (`width: "auto"`) fits to:
+ * - "content" (default): fit the wider of the header and the sampled cell content
+ * - "header": fit the header label only (ignore cell content)
+ */
+export type AutoSizeMode = "content" | "header";
 export interface ChartOptions {
     min?: number;
     max?: number;
@@ -57,6 +63,13 @@ type HeaderObject = {
     accessor: Accessor;
     aggregation?: AggregationConfig;
     align?: "left" | "center" | "right";
+    /**
+     * When `width` is the string `"auto"`, the column is sized to fit its content
+     * on load (and re-fit when row data changes). `autoSizeMode` controls whether
+     * it fits the header + cells (`"content"`, default) or the header label only
+     * (`"header"`). `minWidth` / `maxWidth` clamp the computed width.
+     */
+    autoSizeMode?: AutoSizeMode;
     cellRenderer?: CellRenderer;
     chartOptions?: ChartOptions;
     children?: HeaderObject[];
@@ -92,6 +105,10 @@ type HeaderObject = {
     valueFormatter?: ValueFormatter;
     valueGetter?: ValueGetter;
     showWhen?: ShowWhen;
+    /**
+     * Column width. A number or px/fr/% string sets a fixed/proportional width.
+     * The special value `"auto"` sizes the column to fit its content (see `autoSizeMode`).
+     */
     width: number | string;
     maxWidth?: number | string;
 };

package/dist/src/utils/bodyCell/styling.d.ts

@@ -1,6 +1,6 @@
 import type Row from "../../types/Row";
 import type TableRow from "../../types/TableRow";
-import { AbsoluteBodyCell, CellRenderContext } from "./types";
+import { AbsoluteBodyCell, CellRegistryEntry, CellRenderContext } from "./types";
 export interface CellLiveRef {
     row: Row;
     tableRow: TableRow;
@@ -8,6 +8,7 @@ export interface CellLiveRef {
 }
 export declare const cellLiveRefMap: WeakMap<HTMLElement, CellLiveRef>;
 export declare const untrackCellByRow: (rowId: string, cellElement: HTMLElement) => void;
+export declare const unregisterCellFromRegistry: (cellElement: HTMLElement, cellRegistry?: Map<string, CellRegistryEntry>) => void;
 export declare const createBodyCellElement: (cell: AbsoluteBodyCell, context: CellRenderContext) => HTMLElement;
 export declare const updateBodyCellPosition: (cellElement: HTMLElement, cell: AbsoluteBodyCell) => void;
 export declare const updateBodyCellElement: (cellElement: HTMLElement, cell: AbsoluteBodyCell, context: CellRenderContext) => void;

package/dist/src/utils/headerWidthUtils.d.ts

@@ -1,4 +1,29 @@
 import HeaderObject, { Accessor } from "../types/HeaderObject";
+/**
+ * Build the set of row indices to sample for auto-size measurement.
+ * Hybrid strategy: the first `headSize` rows (always include the top / initial
+ * viewport) plus `stridedSize` rows spread at an even stride across the rest of
+ * the dataset, so wide values deeper in the data are caught without scanning
+ * every row. Strided (not random) keeps the result deterministic across renders.
+ */
+export declare const buildHybridSampleIndices: (rowCount: number, headSize: number, stridedSize: number) => number[];
+/** Linear-interpolated percentile (0-100) of a numeric array. */
+export declare const percentileOf: (values: number[], percentile: number) => number;
+/**
+ * Choose a representative "content width" from sampled cell widths, clipping
+ * outliers only when they clearly stand apart from the bulk of the data.
+ *
+ * - Uses the true max when the column is uniform (max close to the percentile),
+ *   so nothing legitimate gets truncated.
+ * - Falls back to the percentile width only when `max > p * (1 + threshold)` and
+ *   there are enough samples to trust the percentile, so a single rogue 2000px
+ *   row can't define the whole column.
+ */
+export declare const selectContentWidthWithOutlierClip: (widths: number[], options?: {
+    percentile?: number;
+    threshold?: number;
+    minSampleForClip?: number;
+}) => number;
 /**
  * Find all leaf headers (headers without children) in a header tree
  * Takes collapsed state into account - when a header is collapsed, only returns
@@ -9,6 +34,8 @@ export declare const findLeafHeaders: (header: HeaderObject, collapsedHeaders?:
 export declare const DEFAULT_FR_PX = 150;
 /** Default total table width used when normalizing fr/% if container width unknown */
 export declare const DEFAULT_TABLE_WIDTH = 800;
+/** True when a header's width requests content-based auto-sizing (`width: "auto"`). */
+export declare const isAutoWidth: (header: HeaderObject) => boolean;
 /**
  * Normalize header widths so that fr and % are converted to pixels.
  * Call this as soon as headers are received so the rest of the code can assume numeric widths.
@@ -52,7 +79,20 @@ export declare const calculateHeaderContentWidth: (accessor: Accessor, options?:
     rows?: any[];
     header?: HeaderObject;
     maxWidth?: number;
+    /** Leading rows always measured (default AUTO_SIZE_HEAD_SAMPLE_SIZE) */
+    headSampleSize?: number;
+    /** Rows sampled at an even stride across the rest (default AUTO_SIZE_STRIDED_SAMPLE_SIZE) */
+    stridedSampleSize?: number;
+    /** Back-compat: when set, used as the head sample size (strided defaults to 0) */
     sampleSize?: number;
+    /** Outlier clip percentile (default AUTO_SIZE_OUTLIER_PERCENTILE) */
+    outlierPercentile?: number;
+    /** Outlier clip threshold fraction (default AUTO_SIZE_OUTLIER_THRESHOLD) */
+    outlierThreshold?: number;
+    /** When "header", ignore cell content and fit the header label only */
+    autoSizeMode?: "content" | "header";
+    /** Theme passed to a custom cellRenderer during measurement */
+    theme?: any;
     /** Scope `.st-cell-content` font/padding sampling to this table instance */
     styleRoot?: ParentNode | null;
 }) => number;

package/dist/stories/tests/46-AutoSizeColumnsTests.stories.d.ts

@@ -0,0 +1,258 @@
+/**
+ * AUTO-SIZE COLUMNS TESTS
+ *
+ * Comprehensive coverage for content-fit columns (`width: "auto"`):
+ * - shrink / grow, per-column `maxWidth` cap and `minWidth` floor
+ * - `autoSizeMode: "header"`
+ * - custom (vanilla) renderers, valueFormatter, valueGetter, chart columns
+ * - outliers (single giant value clipped) vs. a legitimate wide minority (kept)
+ * - very large datasets (50k rows) with bounded sampling
+ * - re-fit on data change, sort stability, empty data, mixed/pinned layouts
+ * - a no-flicker stability guard
+ * - an exhaustive deterministic unit block for the sampling/percentile/outlier helpers
+ *
+ * Width assertions rely on real layout, so these run under the Storybook
+ * test-runner (Playwright). The helper unit block is layout-independent.
+ */
+import { SimpleTableVanilla } from "../../src/index";
+import type { Meta } from "@storybook/html";
+declare const meta: Meta;
+export default meta;
+export declare const AutoWidthShrinksNarrowColumn: {
+    parameters: {
+        tags: string[];
+    };
+    render: () => HTMLDivElement & {
+        _table?: SimpleTableVanilla | undefined;
+    };
+    play: ({ canvasElement }: {
+        canvasElement: HTMLElement;
+    }) => Promise<void>;
+};
+export declare const AutoWidthGrowsForLongContent: {
+    parameters: {
+        tags: string[];
+    };
+    render: () => HTMLDivElement & {
+        _table?: SimpleTableVanilla | undefined;
+    };
+    play: ({ canvasElement }: {
+        canvasElement: HTMLElement;
+    }) => Promise<void>;
+};
+export declare const AutoWidthRespectsMaxWidth: {
+    parameters: {
+        tags: string[];
+    };
+    render: () => HTMLDivElement & {
+        _table?: SimpleTableVanilla | undefined;
+    };
+    play: ({ canvasElement }: {
+        canvasElement: HTMLElement;
+    }) => Promise<void>;
+};
+export declare const AutoWidthRespectsMinWidth: {
+    parameters: {
+        tags: string[];
+    };
+    render: () => HTMLDivElement & {
+        _table?: SimpleTableVanilla | undefined;
+    };
+    play: ({ canvasElement }: {
+        canvasElement: HTMLElement;
+    }) => Promise<void>;
+};
+export declare const AutoSizeHeaderModeIgnoresCells: {
+    parameters: {
+        tags: string[];
+    };
+    render: () => HTMLDivElement & {
+        _table?: SimpleTableVanilla | undefined;
+    };
+    play: ({ canvasElement }: {
+        canvasElement: HTMLElement;
+    }) => Promise<void>;
+};
+export declare const AutoSizeMeasuresCustomRenderer: {
+    parameters: {
+        tags: string[];
+    };
+    render: () => HTMLDivElement & {
+        _table?: SimpleTableVanilla | undefined;
+    };
+    play: ({ canvasElement }: {
+        canvasElement: HTMLElement;
+    }) => Promise<void>;
+};
+export declare const AutoSizeMeasuresFormattedValue: {
+    parameters: {
+        tags: string[];
+    };
+    render: () => HTMLDivElement & {
+        _table?: SimpleTableVanilla | undefined;
+    };
+    play: ({ canvasElement }: {
+        canvasElement: HTMLElement;
+    }) => Promise<void>;
+};
+export declare const AutoSizeMeasuresValueGetter: {
+    parameters: {
+        tags: string[];
+    };
+    render: () => HTMLDivElement & {
+        _table?: SimpleTableVanilla | undefined;
+    };
+    play: ({ canvasElement }: {
+        canvasElement: HTMLElement;
+    }) => Promise<void>;
+};
+export declare const AutoSizeChartColumnUsesChartMinimum: {
+    parameters: {
+        tags: string[];
+    };
+    render: () => HTMLDivElement & {
+        _table?: SimpleTableVanilla | undefined;
+    };
+    play: ({ canvasElement }: {
+        canvasElement: HTMLElement;
+    }) => Promise<void>;
+};
+export declare const AutoSizeClipsSingleOutlier: {
+    parameters: {
+        tags: string[];
+    };
+    render: () => HTMLDivElement & {
+        _table?: SimpleTableVanilla | undefined;
+    };
+    play: ({ canvasElement }: {
+        canvasElement: HTMLElement;
+    }) => Promise<void>;
+};
+export declare const AutoSizeKeepsLegitimateWideMinority: {
+    parameters: {
+        tags: string[];
+    };
+    render: () => HTMLDivElement & {
+        _table?: SimpleTableVanilla | undefined;
+    };
+    play: ({ canvasElement }: {
+        canvasElement: HTMLElement;
+    }) => Promise<void>;
+};
+export declare const AutoSizeClipsFewOutliers: {
+    parameters: {
+        tags: string[];
+    };
+    render: () => HTMLDivElement & {
+        _table?: SimpleTableVanilla | undefined;
+    };
+    play: ({ canvasElement }: {
+        canvasElement: HTMLElement;
+    }) => Promise<void>;
+};
+export declare const AutoSize50kUniformShort: {
+    parameters: {
+        tags: string[];
+    };
+    render: () => HTMLDivElement & {
+        _table?: SimpleTableVanilla | undefined;
+    };
+    play: ({ canvasElement }: {
+        canvasElement: HTMLElement;
+    }) => Promise<void>;
+};
+export declare const AutoSize50kDeepOutlierStaysCompact: {
+    parameters: {
+        tags: string[];
+    };
+    render: () => HTMLDivElement & {
+        _table?: SimpleTableVanilla | undefined;
+    };
+    play: ({ canvasElement }: {
+        canvasElement: HTMLElement;
+    }) => Promise<void>;
+};
+export declare const AutoSize50kWidespreadLongGrows: {
+    parameters: {
+        tags: string[];
+    };
+    render: () => HTMLDivElement & {
+        _table?: SimpleTableVanilla | undefined;
+    };
+    play: ({ canvasElement }: {
+        canvasElement: HTMLElement;
+    }) => Promise<void>;
+};
+export declare const AutoSizeRefitsOnDataChange: {
+    parameters: {
+        tags: string[];
+    };
+    render: () => HTMLDivElement & {
+        _table?: SimpleTableVanilla | undefined;
+    };
+    play: ({ canvasElement }: {
+        canvasElement: HTMLElement;
+    }) => Promise<void>;
+};
+export declare const AutoSizeStableAcrossSort: {
+    parameters: {
+        tags: string[];
+    };
+    render: () => HTMLDivElement & {
+        _table?: SimpleTableVanilla | undefined;
+    };
+    play: ({ canvasElement }: {
+        canvasElement: HTMLElement;
+    }) => Promise<void>;
+};
+export declare const AutoSizeEmptyDataFitsHeader: {
+    parameters: {
+        tags: string[];
+    };
+    render: () => HTMLDivElement & {
+        _table?: SimpleTableVanilla | undefined;
+    };
+    play: ({ canvasElement }: {
+        canvasElement: HTMLElement;
+    }) => Promise<void>;
+};
+export declare const AutoSizeMixedColumnsLayout: {
+    parameters: {
+        tags: string[];
+    };
+    render: () => HTMLDivElement & {
+        _table?: SimpleTableVanilla | undefined;
+    };
+    play: ({ canvasElement }: {
+        canvasElement: HTMLElement;
+    }) => Promise<void>;
+};
+export declare const AutoSizePinnedColumn: {
+    parameters: {
+        tags: string[];
+    };
+    render: () => HTMLDivElement & {
+        _table?: SimpleTableVanilla | undefined;
+    };
+    play: ({ canvasElement }: {
+        canvasElement: HTMLElement;
+    }) => Promise<void>;
+};
+export declare const AutoSizeNoFlicker: {
+    parameters: {
+        tags: string[];
+    };
+    render: () => HTMLDivElement & {
+        _table?: SimpleTableVanilla | undefined;
+    };
+    play: ({ canvasElement }: {
+        canvasElement: HTMLElement;
+    }) => Promise<void>;
+};
+export declare const SamplingAndOutlierHelpers: {
+    parameters: {
+        tags: string[];
+    };
+    render: () => HTMLDivElement;
+    play: () => Promise<void>;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simple-table-core",
-  "version": "3.7.6",
+  "version": "3.8.0",
   "main": "dist/cjs/index.js",
   "module": "dist/index.es.js",
   "types": "dist/src/index.d.ts",