import type {
ColumnUniversalId,
FilterSpecNode,
PObjectId,
PTableColumnId,
PTableColumnIdColumn,
PTableSorting,
MultiColumnSelector,
ColumnSelector,
} from "@milaboratories/pl-model-common";
import {
canonicalizeAxisId,
dedupColumns,
extractPObjectId,
uniqueBy,
} from "@milaboratories/pl-model-common";
import { collectFilterSpecColumns } from "../../../filters/traverse";
import { createColumnResolver, type ColumnResolver } from "../columnResolver";
import type { RenderCtxBase } from "../../../render";
import type {
PlDataTableColumnsMeta,
PlDataTableFilters,
PlDataTableFilterSpecLeaf,
PlDataTableModel,
} from "../typesV8";
import { upgradePlDataTableStateV2 } from "../state-migration";
import type { PlDataTableStateV2 } from "../state-migration";
import {
collectSearchColumns,
createSearchFilter,
createSheetFilters,
joinFilters,
readPlDataTableUserParams,
} from "../tableParams";
import type { MatchingMode } from "@milaboratories/pl-model-common";
import {
hasSingleDataColumn,
hitQualifications,
collectLinkerColumns,
describePeerLinks,
findPeerLinks,
getResultPoolDatasetAxes,
queriesQualifications,
type ColumnRecipe,
} from "../../../columns";
import type { DeriveLabelsOptions } from "../../../labels/derive_distinct_labels";
import {
deriveAllLabels,
evaluateRules,
getEffectiveVisibility,
getOrderPriority,
isColumnHidden,
buildDataStatusMap,
toRuleColumn,
type LabelableColumn,
} from "./utils";
import { createPTableDefV3 } from "./createPTableDefV3";
import {
discoverLabelColumns,
discoverTableColumns,
type DiscoverTableColumnOptions,
} from "./discoverColumns";
import { isNil, isPlainObject, type Nil } from "@milaboratories/helpers";
import { uniq } from "es-toolkit";
export type createPlDataTableOptionsV3 = (
| {
columns: Nil | DiscoverTableColumnOptions;
}
| {
primaryColumns: ColumnRecipe[];
columns: Nil | ColumnRecipe[];
}
) & {
tableState?: PlDataTableStateV2;
filters?: PlDataTableFilters;
sorting?: PTableSorting[];
primaryJoinType?: "inner" | "full";
labelsOptions?: DeriveLabelsOptions;
displayOptions?: ColumnsDisplayOptions;
};
/** Structured source config — selectors/anchors instead of raw ColumnsSource. */
export type ColumnsSelectorConfig = {
include?: MultiColumnSelector | MultiColumnSelector[];
exclude?: MultiColumnSelector | MultiColumnSelector[];
mode?: MatchingMode;
maxHops?: number;
};
export type ColumnsDisplayOptions = {
/** Column ordering rules. Higher priority = further left. First matching rule wins. */
ordering?: ColumnOrderRule[];
/** Column visibility rules. First matching rule wins. Unmatched columns use default visibility. */
visibility?: ColumnVisibilityRule[];
};
export type ColumnOrderRule = {
match: ColumnSelector;
/** Higher number = further left in table */
priority: number;
};
export type ColumnVisibilityRule = {
match: ColumnSelector;
visibility: "default" | "optional" | "hidden";
};
export function createPlDataTableV3(
ctx: RenderCtxBase,
options: createPlDataTableOptionsV3,
): PlDataTableModel | undefined {
const params = readPlDataTableUserParams(upgradePlDataTableStateV2(options.tableState));
const primaryJoinType = options.primaryJoinType ?? "full";
const resolved = resolveInputColumns(ctx, options);
if (resolved === undefined) return undefined;
const { primary, secondary } = resolved;
if (primary.length === 0) return undefined;
const { direct, linked } = splitByTopology(secondary);
const allColumns = [...primary, ...secondary];
const labelable = allColumns.map(toLabelableColumn);
// From all columns: a hidden one still shows when sorted, filtered or made visible by a rule.
const linkHints = collectLinkHints(labelable);
const derivedLabels = deriveAllLabels({
// Skip hidden columns when deriving labels — they don't appear in the
// table, so they shouldn't influence label disambiguation (#1623).
// The link icon and its hover text tell same-named columns apart, so they get no "via" text.
columns: labelable
.filter((c) => !isColumnHidden(c.spec))
.map((c) => ({ ...c, marker: linkHints.get(c.id) })),
deriveLabelsOptions: {
includeNativeLabel: true,
...options.labelsOptions,
},
});
// Rule-based visibility/order maps (keyed by bare PObjectId). Computed once
// here: `computeHiddenColumns` needs visibility to decide the visible set,
// and `buildColumnsMeta` (below, once the visible set is known) reuses both.
const allColumnsForRules = [...primary, ...direct, ...linked, ...collectLinkerSnapshots(linked)];
const visibilityByColId = evaluateRules(
options.displayOptions?.visibility ?? [],
allColumnsForRules,
);
const orderByColId = evaluateRules(options.displayOptions?.ordering ?? [], allColumnsForRules);
const resolver = createColumnResolver([
...primary,
...direct,
...linked.flatMap((lc) => [...collectLinkerColumns(lc), lc]),
]);
const tableColumns = [...primary, ...direct, ...linked];
// The table shows only the axes of its primary columns.
const primaryAxisKeys = new Set(
primary.flatMap((c) => c.getSpec().axesSpec.map((a) => canonicalizeAxisId(a))),
);
const searchFilter = createSearchFilter(
params.searchString,
collectSearchColumns({
columns: tableColumns.map((c) => ({
id: c.id,
spec: c.getSpec(),
visibility: getEffectiveVisibility(toRuleColumn(c), visibilityByColId) ?? "default",
})),
isAxisHidden: (axis) =>
!primaryAxisKeys.has(canonicalizeAxisId(axis)) || isColumnHidden(axis),
sheetAxes: params.sheetsState.map((sheet) => sheet.axisId),
hiddenColIds: params.hiddenColIds,
}),
);
const remapedDefaultFilters = remapFilterColumnIds(options.filters, resolver);
const filters = filterFilters(
joinFilters([
...createSheetFilters(params.sheetsState),
params.userFilters,
searchFilter,
params.defaultFilters ?? remapedDefaultFilters,
]),
resolver,
);
const sorting = filterSorting(
resolveSorting(params.sorting, remapSortingColumnIds(options.sorting, resolver)),
resolver,
);
const fullDef = createPTableDefV3({
primaryJoinType,
primary,
secondary: [...direct, ...linked],
filters,
sorting,
});
const fullHandle = ctx.createPTableV2(fullDef);
// TODO: is workaround for dropdown suggestions.
// Pframe have not equivalent data for columns relativly to Ptable.
// PFrame is the physical column registry — one entry per bare PObjectId,
// so strip the rich recipe ids down to their physical leaf id and dedupe:
// multiple discovered variants of the same hit collapse to the same bare id.
const pframeHandle = ctx.createPFrame(
uniq([
...primary.map((v) => extractPObjectId(v.id)),
...direct.map((v) => extractPObjectId(v.id)),
...linked.map((v) => extractPObjectId(v.id)),
]),
);
const hiddenColumnIds = computeHiddenColumns({
columns: tableColumns,
visibilityByColId,
sorting,
filters,
hiddenSpecs: params.hiddenColIds,
});
const visible = {
primary,
direct: direct.filter((c) => !hiddenColumnIds.has(c.id)),
linked: linked.filter((c) => !hiddenColumnIds.has(c.id)),
};
const visibleDef = createPTableDefV3({
primaryJoinType,
primary,
secondary: [...visible.direct, ...visible.linked],
filters,
sorting,
});
const visibleHandle = ctx.createPTableV2(visibleDef);
// Built here, where the visible set is known: per-column data status is
// computed for visible columns only (the probe is meaningful only for what
// the user sees), while label/visibility/order/axes cover all columns.
const columnsMeta = buildColumnsMeta({
fullColumns: [...primary, ...direct, ...linked],
visibleColumns: [...visible.primary, ...visible.direct, ...visible.linked],
primaryColumns: primary,
derivedLabels,
linkHints,
visibilityByColId,
orderByColId,
});
return {
sourceId: params.sourceId,
fullTableHandle: fullHandle,
fullPframeHandle: pframeHandle,
visibleTableHandle: visibleHandle,
defaultFilters: remapedDefaultFilters,
columnsMeta,
} satisfies PlDataTableModel;
}
type ResolvedColumns = {
readonly primary: ColumnRecipe[];
readonly secondary: ColumnRecipe[];
};
/** Normalize either option branch into a {primary, secondary} pair of recipes. */
function resolveInputColumns(
ctx: RenderCtxBase,
options: createPlDataTableOptionsV3,
): undefined | ResolvedColumns {
if ("primaryColumns" in options) {
const primary = options.primaryColumns;
const secondary = options.columns ?? [];
const labels = discoverLabelColumns(ctx, primary);
// Exclude from secondary anything already present in primary: a label
// column the block hands in as primary can be re-discovered here as a
// label for that same axis, landing in the table twice with the same id.
const primaryIds = new Set(primary.map((c) => c.id));
return {
primary,
secondary: dedupColumns(
[...secondary, ...labels].filter((c) => !primaryIds.has(c.id)),
(c) => c.id,
(c) => c.getSpec(),
),
};
}
if (isPlainObject(options.columns)) {
return discoverTableColumns(ctx, options.columns);
}
return undefined;
}
/** Split secondary recipes by query topology: leaves (no linker chain) vs joined. */
function splitByTopology(columns: ColumnRecipe[]): {
direct: ColumnRecipe[];
linked: ColumnRecipe[];
} {
const direct: ColumnRecipe[] = [];
const linked: ColumnRecipe[] = [];
for (const c of columns) {
if (hasSingleDataColumn(c)) direct.push(c);
else linked.push(c);
}
return { direct, linked };
}
/** All linker recipes across the given linked columns, deduped by id. */
function collectLinkerSnapshots(linked: ColumnRecipe[]): ColumnRecipe[] {
return uniqueBy(
linked.flatMap((c) => collectLinkerColumns(c)),
(c) => c.id,
);
}
/** Link icon hover text per column, for columns reached through at least one peer link. */
function collectLinkHints(columns: LabelableColumn[]): Map {
if (!columns.some((c) => c.linkerPath?.length)) return new Map();
const datasetAxes = getResultPoolDatasetAxes();
return new Map(
columns.flatMap((c) => {
const links = findPeerLinks(c.linkerPath?.map((step) => step.linker.spec) ?? [], datasetAxes);
return links.length > 0 ? [[c.id, describePeerLinks(links)] as const] : [];
}),
);
}
function toLabelableColumn(col: ColumnRecipe): LabelableColumn {
return {
id: col.id,
spec: col.getSpec(),
linkerPath: collectLinkerColumns(col).map((linker) => ({
linker: { spec: linker.getSpec() },
})),
qualifications: {
forHit: [...hitQualifications(col)],
forQueries: queriesQualifications(col),
},
};
}
/**
* Compute display metadata as a sidecar keyed by each emitted column's
* `ColumnUniversalId` (and axis `AxisId`), instead of baking it into the specs
* via `withSpecs`. Spec overrides change a recipe's id, so the same physical
* column reached two ways would diverge into two ids and render twice; keeping
* meta out of the spec preserves identity and lets dedup collapse such cases.
* The UI overlays this onto the engine-emitted specs at render time.
*/
function buildColumnsMeta(params: {
/** Every column in the table (primary + secondary) — drives `columns` and `axes`. */
fullColumns: ColumnRecipe[];
/** The visible subset — `status` is probed for these only. */
visibleColumns: ColumnRecipe[];
/** The primary join columns — their axes are the visible index; all other axes are hidden. */
primaryColumns: ColumnRecipe[];
derivedLabels: Record;
linkHints: Map;
visibilityByColId: Map;
orderByColId: Map;
}): PlDataTableColumnsMeta {
const { fullColumns, visibleColumns, primaryColumns, derivedLabels, linkHints } = params;
const { visibilityByColId, orderByColId } = params;
// Status only for visible columns — the probe is meaningful only for what the
// user actually sees; non-visible columns get no `status`.
const visibleStatus = buildDataStatusMap(visibleColumns);
const columns = fullColumns.reduce((acc, c) => {
const rc = toRuleColumn(c);
acc[c.id] = {
label: derivedLabels[c.id],
visibility: getEffectiveVisibility(rc, visibilityByColId),
order: getOrderPriority(rc, orderByColId),
status: visibleStatus[c.id],
linkHint: linkHints.get(c.id),
};
return acc;
}, {});
// Only primary columns declare the table's visible axes. Any axis introduced
// solely by a secondary column (a linker-bridge axis, or a distinct-domain
// copy) is flagged hidden — otherwise it renders as a second index axis.
const primaryAxisKeys = new Set(
primaryColumns.flatMap((c) => c.getSpec().axesSpec.map((a) => canonicalizeAxisId(a))),
);
const axes = fullColumns.reduce(
(acc, c) =>
c.getSpec().axesSpec.reduce((inner, ax) => {
const key = canonicalizeAxisId(ax);
if (inner[key] === undefined) inner[key] = { hidden: !primaryAxisKeys.has(key) };
return inner;
}, acc),
{},
);
return { columns, axes };
}
/** Drop filter leaves whose column references cannot be resolved; rewrite the
* resolvable ones through the resolver. Prune empty and/or/not groups. */
function filterFilters(
filters: Nil | PlDataTableFilters,
resolver: ColumnResolver,
): Nil | PlDataTableFilters {
if (isNil(filters)) return filters;
const rewriteLeaf = (leaf: PlDataTableFilterSpecLeaf): Nil | PlDataTableFilterSpecLeaf => {
if (leaf.type === undefined) return leaf;
const result = { ...leaf };
if ("column" in result) {
const c = resolver(result.column);
if (isNil(c)) return undefined;
result.column = c;
}
if ("rhs" in result) {
const c = resolver(result.rhs);
if (isNil(c)) return undefined;
result.rhs = c;
}
return result;
};
const prune = (node: PlDataTableFilterNode): Nil | PlDataTableFilterNode => {
if (node.type === "and" || node.type === "or") {
const kept = node.filters
.map((f) => prune(f))
.filter((f): f is PlDataTableFilterNode => !isNil(f));
if (kept.length === 0) return undefined;
return { type: node.type, filters: kept };
}
if (node.type === "not") {
const inner = prune(node.filter);
return isNil(inner) ? undefined : { type: "not", filter: inner };
}
return rewriteLeaf(node);
};
return prune(filters) as Nil | PlDataTableFilters;
}
/** Pick user sorting from state if set, otherwise fall back to options default.
* null = user has not touched sorting → use default;
* [] = user has explicitly cleared sorting → no sorting (default ignored). */
function resolveSorting(
userSorting: Nil | PTableSorting[],
defaultSorting: Nil | PTableSorting[],
): PTableSorting[] {
return (isNil(userSorting) ? defaultSorting : userSorting) ?? [];
}
/** Rewrite sorting entries through the resolver; drop those that fail to resolve. */
function filterSorting(sorting: PTableSorting[], resolver: ColumnResolver): PTableSorting[] {
return sorting.flatMap((s) => {
const col = resolver(s.column);
return isNil(col) ? [] : [{ ...s, column: col }];
});
}
/** Determine which columns should be hidden based on state or optional-column defaults.
* Keyed by the recipe's logical {@link ColumnUniversalId} (rich) — variants of
* the same physical column are independently visible/hidden. */
function computeHiddenColumns(params: {
columns: ColumnRecipe[];
visibilityByColId: Map;
sorting: Nil | PTableSorting[];
filters: Nil | PlDataTableFilters;
hiddenSpecs: Nil | PTableColumnId[];
}): Set {
const { columns, visibilityByColId, sorting, filters, hiddenSpecs } = params;
const visibilityOf = (c: ColumnRecipe) =>
getEffectiveVisibility(toRuleColumn(c), visibilityByColId);
const alwaysHidden = columns.filter((c) => visibilityOf(c) === "hidden").map((c) => c.id);
const optionalHidden = !isNil(hiddenSpecs)
? hiddenSpecs.filter((s): s is PTableColumnIdColumn => s.type === "column").map((s) => s.id)
: columns.filter((c) => visibilityOf(c) === "optional").map((c) => c.id);
const initial = [...alwaysHidden, ...optionalHidden];
const preserved = collectPreservedColumnIds(sorting, filters);
return new Set(initial.filter((id) => !preserved.has(id)));
}
/** Collect IDs of columns that must remain visible (sorted, filtered). */
function collectPreservedColumnIds(
sorting: Nil | PTableSorting[],
filters: Nil | PlDataTableFilters,
): Set {
const sortedIds = (sorting ?? [])
.map((s) => s.column)
.filter((c): c is PTableColumnIdColumn => c.type === "column")
.map((c) => c.id);
const filterIds = !isNil(filters)
? collectFilterSpecColumns(filters).flatMap((c) => (c.type === "column" ? [c.id] : []))
: [];
return new Set([...sortedIds, ...filterIds]);
}
/** Remap column references in sorting entries through the resolver.
* Unresolved entries are dropped with a warning (best-effort contract). */
function remapSortingColumnIds(
sorting: Nil | PTableSorting[],
resolver: ColumnResolver,
): Nil | PTableSorting[] {
return sorting?.flatMap((s) => {
const col = resolver(s.column);
if (isNil(col)) {
console.warn(
`Sorting column ${JSON.stringify(s.column)} does not match any discovered column — dropped.`,
);
return [];
}
return [{ ...s, column: col }];
});
}
type PlDataTableFilterNode = FilterSpecNode;
/** Remap column references in a filter tree through the resolver.
* Unresolved leaves are dropped with a warning; empty groups are pruned. */
function remapFilterColumnIds(
filters: Nil | PlDataTableFilters,
resolver: ColumnResolver,
): Nil | PlDataTableFilters {
if (isNil(filters)) return filters;
const mapLeaf = (leaf: PlDataTableFilterSpecLeaf): Nil | PlDataTableFilterSpecLeaf => {
if (leaf.type === undefined) return leaf;
const result = { ...leaf };
if ("column" in result) {
const c = resolver(result.column);
if (isNil(c)) {
console.warn(
`Filter column ${JSON.stringify(result.column)} does not match any discovered column — dropped.`,
);
return undefined;
}
result.column = c;
}
if ("rhs" in result) {
const c = resolver(result.rhs);
if (isNil(c)) {
console.warn(
`Filter rhs ${JSON.stringify(result.rhs)} does not match any discovered column — dropped.`,
);
return undefined;
}
result.rhs = c;
}
return result;
};
const prune = (node: PlDataTableFilterNode): Nil | PlDataTableFilterNode => {
if (node.type === "and" || node.type === "or") {
const kept = node.filters
.map((f) => prune(f))
.filter((f): f is PlDataTableFilterNode => !isNil(f));
if (kept.length === 0) return undefined;
return { type: node.type, filters: kept };
}
if (node.type === "not") {
const inner = prune(node.filter);
return isNil(inner) ? undefined : { type: "not", filter: inner };
}
return mapLeaf(node);
};
return prune(filters) as Nil | PlDataTableFilters;
}