@platforma-sdk/model 1.63.1 → 1.64.0

package/dist/components/PlDataTable/createPlDataTable/createPlDataTableV3.d.ts

@@ -1,39 +1,53 @@
+import { DeriveLabelsOptions } from "../../../labels/derive_distinct_labels.js";
 import { RenderCtxBase } from "../../../render/api.js";
-import "../../../render/index.js";
 import { PlDataTableFilters, PlDataTableModel } from "../typesV5.js";
 import { PlDataTableStateV2 } from "../state-migration.js";
-import { ColumnSource } from "../../../columns/column_snapshot_provider.js";
-import { MatchingMode } from "../../../columns/column_collection_builder.js";
-import "../../../columns/index.js";
-import { Annotation, DataInfo, MultiColumnSelector, PColumn, PColumnIdAndSpec, PColumnSpec, PColumnValues, PObjectId, PTableColumnId, PTableDefV2, PTableSorting, PlRef, RequireServices, Services, SpecQueryExpression } from "@milaboratories/pl-model-common";
+import { ColumnSnapshot } from "../../../columns/column_snapshot.js";
+import { ColumnMatch, MatchingMode } from "../../../columns/column_collection_builder.js";
+import { DiscoveredTableColumnOptions } from "./discoverColumns.js";
+import { MultiColumnSelector, PColumnSpec, PObjectId, PTableSorting, RequireServices, SUniversalPColumnId, Services } from "@milaboratories/pl-model-common";
+import { Nil } from "@milaboratories/helpers";
 
 //#region src/components/PlDataTable/createPlDataTable/createPlDataTableV3.d.ts
-/** Check if column should be omitted from the table */
-declare function isColumnHidden(spec: {
-  annotations?: Annotation;
-}): boolean;
-/** Check if column is hidden by default */
-declare function isColumnOptional(spec: {
-  annotations?: Annotation;
-}): boolean;
+type createPlDataTableOptionsV3 = ({
+  discoverColumnOptions: DiscoveredTableColumnOptions;
+} | {
+  columns: Nil | TableColumnSnapshot<SUniversalPColumnId>[];
+}) & {
+  filters?: PlDataTableFilters;
+  sorting?: PTableSorting[];
+  primaryJoinType?: "inner" | "full";
+  tableState?: PlDataTableStateV2;
+  labelsOptions?: DeriveLabelsOptions;
+  columnsDisplayOptions?: ColumnsDisplayOptions;
+};
 /** Structured source config — selectors/anchors instead of raw ColumnSource. */
 type ColumnsSelectorConfig = {
   include?: MultiColumnSelector | MultiColumnSelector[];
   exclude?: MultiColumnSelector | MultiColumnSelector[];
-  anchors?: Record<string, PlRef | PObjectId | PColumnSpec>;
   mode?: MatchingMode;
   maxHops?: number;
 };
-type createPlDataTableOptionsV3 = {
-  source?: ColumnSource | ColumnSource[];
-  columns: ColumnsSelectorConfig;
-  filters?: PlDataTableFilters;
-  sorting?: PTableSorting[];
-  coreJoinType?: "inner" | "full";
-  coreColumnPredicate?: (spec: PColumnIdAndSpec) => boolean;
-  state?: PlDataTableStateV2;
+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[];
+};
+type ColumnOrderRule = {
+  match: ColumnMatcher; /** Higher number = further left in table */
+  priority: number;
 };
+type ColumnVisibilityRule = {
+  match: ColumnMatcher;
+  visibility: "default" | "optional" | "hidden";
+};
+type ColumnMatcher = (spec: PColumnSpec) => boolean;
 declare function createPlDataTableV3<A, U, S extends RequireServices<typeof Services.PFrameSpec>>(ctx: RenderCtxBase<A, U, S>, options: createPlDataTableOptionsV3): PlDataTableModel | undefined;
+/** A single column discovered from sources — normalized from raw ColumnSnapshot/ColumnMatch. */
+type TableColumnSnapshot<Id extends PObjectId | SUniversalPColumnId> = ColumnSnapshot<Id> & {
+  readonly isPrimary?: boolean;
+  readonly originalId?: PObjectId;
+  readonly linkerPath?: ColumnMatch["path"];
+};
 //#endregion
-export { createPlDataTableOptionsV3, createPlDataTableV3, isColumnHidden, isColumnOptional };
+export { ColumnMatcher, ColumnOrderRule, ColumnVisibilityRule, ColumnsDisplayOptions, ColumnsSelectorConfig, TableColumnSnapshot, createPlDataTableOptionsV3, createPlDataTableV3 };
 //# sourceMappingURL=createPlDataTableV3.d.ts.map

package/dist/components/PlDataTable/createPlDataTable/createPlDataTableV3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createPlDataTableV3.d.ts","names":[],"sources":["../../../../src/components/PlDataTable/createPlDataTable/createPlDataTableV3.ts"],"mappings":";;;;;;;;;;;KA0CY,0BAAA;EAEN,qBAAA,EAAuB,4BAAA;AAAA;EAGvB,OAAA,EAAS,GAAA,GAAM,mBAAA,CAAoB,mBAAA;AAAA;EAGvC,OAAA,GAAU,kBAAA;EACV,OAAA,GAAU,aAAA;EACV,eAAA;EAEA,UAAA,GAAa,kBAAA;EACb,aAAA,GAAgB,mBAAA;EAChB,qBAAA,GAAwB,qBAAA;AAAA;;KAId,qBAAA;EACV,OAAA,GAAU,mBAAA,GAAsB,mBAAA;EAChC,OAAA,GAAU,mBAAA,GAAsB,mBAAA;EAChC,IAAA,GAAO,YAAA;EACP,OAAA;AAAA;AAAA,KAGU,qBAAA;EApBN,uFAsBJ,QAAA,GAAW,eAAA,IAtBQ;EAwBnB,UAAA,GAAa,oBAAA;AAAA;AAAA,KAGH,eAAA;EACV,KAAA,EAAO,aAAA,EAxBG;EA0BV,QAAA;AAAA;AAAA,KAGU,oBAAA;EACV,KAAA,EAAO,aAAA;EACP,UAAA;AAAA;AAAA,KAGU,aAAA,IAAiB,IAAA,EAAM,WAAA;AAAA,iBAInB,mBAAA,iBAAoC,eAAA,QAAuB,QAAA,CAAS,UAAA,EAAA,CAClF,GAAA,EAAK,aAAA,CAAc,CAAA,EAAG,CAAA,EAAG,CAAA,GACzB,OAAA,EAAS,0BAAA,GACR,gBAAA;;KA2HS,mBAAA,YAA+B,SAAA,GAAY,mBAAA,IAAuB,cAAA,CAAe,EAAA;EAAA,SAClF,SAAA;EAAA,SACA,UAAA,GAAa,SAAA;EAAA,SACb,UAAA,GAAa,WAAA;AAAA"}

package/dist/components/PlDataTable/createPlDataTable/createPlDataTableV3.js

@@ -1,200 +1,284 @@
-import { allPColumnsReady } from "../../../render/util/pcolumn_data.js";
-import "../../../render/index.js";
-import { collectFilterSpecColumns } from "../../../filters/traverse.js";
-import { filterSpecToSpecQueryExpr } from "../../../filters/converters/filterToQuery.js";
-import { distillFilterSpec } from "../../../filters/distill.js";
-import "../../../filters/index.js";
+import { collectFilterSpecColumns, traverseFilterSpec } from "../../../filters/traverse.js";
 import { upgradePlDataTableStateV2 } from "../state-migration.js";
 import { getAllLabelColumns, getMatchingLabelColumns } from "../labels.js";
-import { isColumnSnapshotProvider } from "../../../columns/column_snapshot_provider.js";
-import { ColumnCollectionBuilder } from "../../../columns/column_collection_builder.js";
-import { collectCtxColumnSnapshotProviders } from "../../../columns/ctx_column_sources.js";
-import "../../../columns/index.js";
-import { Annotation, canonicalizeJson, getAxisId, getColumnIdAndSpec, isBooleanExpression, isLinkerColumn, parseJson, readAnnotation, uniqueBy } from "@milaboratories/pl-model-common";
+import { createPTableDefV3 } from "./createPTableDefV3.js";
+import { deriveAllLabels, isColumnHidden, isColumnOptional, withLabelAnnotations, withTableVisualAnnotations } from "./utils.js";
+import { discoverTableColumnSnaphots } from "./discoverColumns.js";
+import { canonicalizeJson, getAxisId, getColumnIdAndSpec, parseJson, uniqueBy } from "@milaboratories/pl-model-common";
+import { isNil, throwError } from "@milaboratories/helpers";
 import { isEmpty } from "es-toolkit/compat";
-import { isFunction, isNil } from "es-toolkit";
-
 //#region src/components/PlDataTable/createPlDataTable/createPlDataTableV3.ts
-/** Convert a PTableColumnId to a SpecQueryExpression reference. */
-function columnIdToExpr(col) {
-	if (col.type === "axis") return {
-		type: "axisRef",
-		value: col.id
+function createPlDataTableV3(ctx, options) {
+	const state = upgradePlDataTableStateV2(options.tableState);
+	const primaryJoinType = options.primaryJoinType ?? "full";
+	const discovered = "discoverColumnOptions" in options ? discoverTableColumnSnaphots(ctx, options.discoverColumnOptions) : options.columns;
+	if (isNil(discovered) || discovered.length === 0) return void 0;
+	const resolved = resolveDiscoveredColumns(splitDiscoveredColumns(discovered), discovered);
+	const labelColumns = getMatchingLabelColumns(resolved.all, getAllLabelColumns(ctx));
+	const annotated = annotateColumnGroups(resolved, labelColumns, deriveAllLabels({
+		columns: discovered.map((dc) => ({
+			id: dc.id,
+			spec: dc.spec,
+			linkerPath: dc.linkerPath?.map((lp) => ({ spec: lp.linker.spec }))
+		})),
+		labelColumns,
+		deriveLabelsOptions: {
+			includeNativeLabel: true,
+			...options.labelsOptions
+		}
+	}), options.columnsDisplayOptions);
+	const columnIsAvailable = createColumnValidationById([
+		...annotated.direct,
+		...annotated.linked.flatMap((lc) => [...annotated.linkers.get(lc.id) ?? [], lc]),
+		...annotated.labels
+	]);
+	const filters = mergeFilters(state.pTableParams.filters, remapFilterColumnIds(options.filters, discovered));
+	validateFilters(filters, columnIsAvailable);
+	const sorting = resolveSorting(state.pTableParams.sorting, remapSortingColumnIds(options.sorting, discovered));
+	validateSorting(sorting, columnIsAvailable);
+	const primaryColumnIds = new Set(discovered.filter((dc) => dc.isPrimary).map((dc) => dc.id));
+	const primaryColumns = annotated.direct.filter((c) => primaryColumnIds.has(c.id));
+	const secondaryColumns = annotated.direct.filter((c) => !primaryColumnIds.has(c.id));
+	if (primaryColumns.length === 0) return void 0;
+	const fullDef = createPTableDefV3({
+		primaryJoinType,
+		primaryColumns,
+		secondaryGroups: [
+			...secondaryColumns.map((c) => [c]),
+			...annotated.linked.map((lc) => [...annotated.linkers.get(lc.id) ?? [], lc]),
+			...annotated.labels.map((c) => [c])
+		],
+		filters,
+		sorting
+	});
+	const fullHandle = ctx.createPTableV2(fullDef);
+	const pframeHandle = ctx.createPFrame([
+		...annotated.direct,
+		...annotated.linked,
+		...annotated.labels,
+		...uniqueBy([...annotated.linkers.values()].flat(), (c) => c.id)
+	]);
+	if (!fullHandle || !pframeHandle) return void 0;
+	const hiddenSpecs = state.pTableParams.hiddenColIds;
+	const hiddenColumnIds = computeHiddenColumns([...annotated.direct, ...annotated.linked], sorting, filters, hiddenSpecs);
+	const visible = buildVisibleColumns(annotated, hiddenColumnIds, labelColumns);
+	const visibleNonCoreDirect = secondaryColumns.filter((c) => !hiddenColumnIds.has(c.id));
+	const visibleLinkedGroups = buildVisibleLinkedGroups(visible.direct, visible.linked, annotated.linkers, hiddenSpecs);
+	const visibleDef = createPTableDefV3({
+		primaryJoinType,
+		primaryColumns,
+		secondaryGroups: [
+			...visibleNonCoreDirect.map((c) => [c]),
+			...visibleLinkedGroups,
+			...visible.labels.map((c) => [c])
+		],
+		filters,
+		sorting
+	});
+	const visibleHandle = ctx.createPTableV2(visibleDef);
+	if (!visibleHandle) return void 0;
+	return {
+		sourceId: state.pTableParams.sourceId,
+		fullTableHandle: fullHandle,
+		fullPframeHandle: pframeHandle,
+		visibleTableHandle: visibleHandle
 	};
+}
+/** Split discovered columns into direct (no linker path) and linked (with linker path). */
+function splitDiscoveredColumns(columns) {
 	return {
-		type: "columnRef",
-		value: col.id
+		direct: columns.filter((dc) => isNil(dc.linkerPath) || dc.linkerPath.length === 0),
+		linked: columns.filter((dc) => !isNil(dc.linkerPath) && dc.linkerPath.length > 0)
 	};
 }
-/** Wrap a SpecQuery as a SpecQueryJoinEntry with empty qualifications. */
-function joinEntry(input) {
+/** Resolve DiscoveredColumn snapshots into PColumn objects with lazily-evaluated data. */
+function resolveDiscoveredColumns(split, allDiscovered) {
+	const linked = split.linked.map(resolveSnapshot);
+	const linkers = new Map(split.linked.filter((dc) => !isNil(dc.linkerPath)).map((dc, i) => [linked[i].id, dc.linkerPath.map((s) => resolveSnapshot(s.linker))]));
 	return {
-		entry: input,
-		qualifications: []
+		all: allDiscovered.map(resolveSnapshot),
+		direct: split.direct.map(resolveSnapshot),
+		linked,
+		linkers
 	};
 }
-function createPTableDef(params) {
-	let coreColumns = params.columns;
-	const secondaryColumns = [];
-	if (isFunction(params.coreColumnPredicate)) {
-		coreColumns = [];
-		for (const c of params.columns) if (params.coreColumnPredicate(getColumnIdAndSpec(c))) coreColumns.push(c);
-		else secondaryColumns.push(c);
-	}
-	secondaryColumns.push(...params.labelColumns);
-	let query = {
-		type: "outerJoin",
-		primary: joinEntry({
-			type: params.coreJoinType === "inner" ? "innerJoin" : "fullJoin",
-			entries: coreColumns.map((c) => joinEntry({
-				type: "column",
-				column: c
-			}))
-		}),
-		secondary: secondaryColumns.map((c) => joinEntry({
-			type: "column",
-			column: c
-		}))
+/** Annotate all column groups with derived labels and display options. */
+function annotateColumnGroups(resolved, labelColumns, derivedLabels, displayOptions) {
+	return {
+		direct: withTableVisualAnnotations(displayOptions, withLabelAnnotations(derivedLabels, resolved.direct)),
+		linked: withTableVisualAnnotations(displayOptions, withLabelAnnotations(derivedLabels, resolved.linked)),
+		linkers: new Map([...resolved.linkers].map(([id, cols]) => [id, withLabelAnnotations(derivedLabels, cols)])),
+		labels: withLabelAnnotations(derivedLabels, labelColumns)
 	};
-	if (params.filters !== null) {
-		const nonEmpty = distillFilterSpec(params.filters);
-		if (!isNil(nonEmpty)) {
-			const pridicate = filterSpecToSpecQueryExpr(nonEmpty);
-			if (!isBooleanExpression(pridicate)) throw new Error(`Filter conversion produced a non-boolean expression (got type "${pridicate.type}"), expected a boolean predicate for query filtering`);
-			query = {
-				type: "filter",
-				input: query,
-				predicate: pridicate
-			};
-		}
-	}
-	if (params.sorting.length > 0) query = {
-		type: "sort",
-		input: query,
-		sortBy: params.sorting.map((s) => ({
-			expression: columnIdToExpr(s.column),
-			ascending: s.ascending,
-			nullsFirst: !s.naAndAbsentAreLeastValues
-		}))
+}
+/** Build an index of all valid column IDs (axes + columns) for filter/sorting validation. */
+function createColumnValidationById(fullColumns) {
+	const allIds = [...uniqueBy(fullColumns.flatMap((c) => c.spec.axesSpec.map(getAxisId)), (a) => canonicalizeJson(a)).map((a) => ({
+		type: "axis",
+		id: a
+	})), ...fullColumns.map((c) => ({
+		type: "column",
+		id: c.id
+	}))];
+	const validIdSet = new Set(allIds.map((c) => canonicalizeJson(c)));
+	return (id) => {
+		return validIdSet.has(id);
 	};
-	return { query };
 }
-/** Check if column should be omitted from the table */
-function isColumnHidden(spec) {
-	return readAnnotation(spec, Annotation.Table.Visibility) === "hidden";
+/** Merge filters from table state and options into a single filter spec. */
+function mergeFilters(stateFilters, optionsFilters) {
+	const normalized = optionsFilters ?? null;
+	return stateFilters !== null && normalized !== null ? {
+		type: "and",
+		filters: [stateFilters, normalized]
+	} : stateFilters ?? normalized;
 }
-/** Check if column is hidden by default */
-function isColumnOptional(spec) {
-	return readAnnotation(spec, Annotation.Table.Visibility) === "optional";
+/** Validate that all column references in filters exist in the table. */
+function validateFilters(filters, isValidColumnId) {
+	if (filters == null) return;
+	const firstInvalid = collectFilterSpecColumns(filters).find((col) => !isValidColumnId(col));
+	if (firstInvalid !== void 0) throw new Error(`Invalid filter column ${firstInvalid}: column reference does not match the table columns`);
 }
-function createPlDataTableV3(ctx, options) {
-	const providers = options.source ? normalizeSourceList(options.source).filter(isColumnSnapshotProvider) : collectCtxColumnSnapshotProviders(ctx);
-	if (providers.length === 0) return void 0;
-	const builder = new ColumnCollectionBuilder(ctx.services.pframeSpec).addSources(providers);
-	const anchors = options.columns.anchors;
-	const collection = isNil(anchors) ? builder.build() : builder.build({ anchors });
-	if (!collection) return void 0;
-	try {
-		const findOptions = options.columns ? {
-			include: options.columns.include,
-			exclude: options.columns.exclude,
-			mode: options.columns.mode,
-			maxHops: options.columns.maxHops
-		} : void 0;
-		const dataSnapshots = collection.findColumns(findOptions).map((v) => "column" in v ? v.column : v).filter((s) => !isColumnHidden(s.spec));
-		if (dataSnapshots.length === 0) return void 0;
-		const columns = [];
-		for (const snap of dataSnapshots) {
-			if (!snap.data) return void 0;
-			const data = snap.data.get();
-			if (data === void 0) return void 0;
-			columns.push({
-				id: snap.id,
-				spec: snap.spec,
-				data
-			});
+/** Pick user sorting from state if non-empty, otherwise fall back to options default. */
+function resolveSorting(userSorting, defaultSorting) {
+	return (isEmpty(userSorting) ? defaultSorting : userSorting) ?? [];
+}
+/** Validate that all column references in sorting exist in the table. */
+function validateSorting(sorting, isValidColumnId) {
+	const firstInvalid = sorting.find((s) => !isValidColumnId(canonicalizeJson(s.column)));
+	if (firstInvalid !== void 0) throw new Error(`Invalid sorting column ${JSON.stringify(firstInvalid.column)}: column reference does not match the table columns`);
+}
+/** Determine which columns should be hidden based on state or optional-column defaults. */
+function computeHiddenColumns(columns, sorting, filters, hiddenSpecs) {
+	const alwaysHidden = columns.filter((c) => isColumnHidden(c.spec)).map((c) => c.id);
+	const optionalHidden = !isNil(hiddenSpecs) ? hiddenSpecs.filter((s) => s.type === "column").map((s) => s.id) : columns.filter((c) => isColumnOptional(c.spec)).map((c) => c.id);
+	const initial = [...alwaysHidden, ...optionalHidden];
+	const preserved = collectPreservedColumnIds(sorting, filters);
+	return new Set(initial.filter((id) => !preserved.has(id)));
+}
+/**
+* Build visible linked column groups. Non-hidden groups are included fully;
+* hidden groups are trimmed to only the prefix that brings axes not yet
+* covered by earlier groups (visible or previously trimmed).
+*/
+function buildVisibleLinkedGroups(direct, linked, linkers, hiddenSpecs) {
+	const result = [];
+	const coveredAxisIds = /* @__PURE__ */ new Set();
+	const collectAxes = (group) => {
+		for (const col of group) for (const as of col.spec.axesSpec) coveredAxisIds.add(canonicalizeJson(getAxisId(as)));
+	};
+	collectAxes(direct);
+	for (const lc of linked) {
+		const group = [...linkers.get(lc.id) ?? [], lc];
+		result.push(group);
+		collectAxes(group);
+	}
+	for (const group of linkers.values()) {
+		const trimmed = trimGroupByVisibleAxes(group, hiddenSpecs, coveredAxisIds);
+		if (trimmed.length > 0) {
+			result.push(trimmed);
+			collectAxes(trimmed);
 		}
-		const tableStateNormalized = upgradePlDataTableStateV2(options.state);
-		const allLabelColumns = getAllLabelColumns(ctx.resultPool);
-		if (!allLabelColumns) return void 0;
-		const fullLabelColumns = getMatchingLabelColumns(columns.map(getColumnIdAndSpec), allLabelColumns);
-		const fullColumns = [...columns, ...fullLabelColumns];
-		const fullColumnsIds = [...uniqueBy(fullColumns.flatMap((c) => c.spec.axesSpec.map((a) => getAxisId(a))), (a) => canonicalizeJson(a)).map((a) => ({
-			type: "axis",
-			id: a
-		})), ...fullColumns.map((c) => ({
-			type: "column",
-			id: c.id
-		}))];
-		const fullColumnsIdsSet = new Set(fullColumnsIds.map((c) => canonicalizeJson(c)));
-		const isValidColumnId = (id) => fullColumnsIdsSet.has(id);
-		const stateFilters = tableStateNormalized.pTableParams.filters;
-		const opsFilters = options?.filters ?? null;
-		const filters = stateFilters != null && opsFilters != null ? {
-			type: "and",
-			filters: [stateFilters, opsFilters]
-		} : stateFilters ?? opsFilters;
-		const firstInvalidFilterColumn = (filters ? collectFilterSpecColumns(filters) : []).find((col) => !isValidColumnId(col));
-		if (firstInvalidFilterColumn) throw new Error(`Invalid filter column ${firstInvalidFilterColumn}: column reference does not match the table columns`);
-		const userSorting = tableStateNormalized.pTableParams.sorting;
-		const sorting = (isEmpty(userSorting) ? options?.sorting : userSorting) ?? [];
-		const firstInvalidSortingColumn = sorting.find((s) => !isValidColumnId(canonicalizeJson(s.column)));
-		if (firstInvalidSortingColumn) throw new Error(`Invalid sorting column ${JSON.stringify(firstInvalidSortingColumn.column)}: column reference does not match the table columns`);
-		const coreJoinType = options?.coreJoinType ?? "full";
-		const fullDef = createPTableDef({
-			columns,
-			labelColumns: fullLabelColumns,
-			coreJoinType,
-			filters,
-			sorting,
-			coreColumnPredicate: options?.coreColumnPredicate
-		});
-		const fullHandle = ctx.createPTableV2(fullDef);
-		const pframeHandle = ctx.createPFrame(fullColumns);
-		if (!fullHandle || !pframeHandle) return void 0;
-		const hiddenColumns = new Set((() => {
-			if (coreJoinType === "inner") return [];
-			const hiddenColIds = tableStateNormalized.pTableParams.hiddenColIds;
-			if (hiddenColIds) return hiddenColIds;
-			return columns.filter((c) => isColumnOptional(c.spec)).map((c) => c.id);
-		})());
-		columns.filter((c) => isLinkerColumn(c.spec)).forEach((c) => hiddenColumns.delete(c.id));
-		const coreColumnPredicate = options?.coreColumnPredicate;
-		if (coreColumnPredicate) columns.flatMap((c) => coreColumnPredicate(getColumnIdAndSpec(c)) ? [c.id] : []).forEach((c) => hiddenColumns.delete(c));
-		sorting.map((s) => s.column).filter((c) => c.type === "column").forEach((c) => hiddenColumns.delete(c.id));
-		if (filters) collectFilterSpecColumns(filters).flatMap((c) => {
-			const obj = parseJson(c);
-			return obj.type === "column" ? [obj.id] : [];
-		}).forEach((c) => hiddenColumns.delete(c));
-		const visibleColumns = columns.filter((c) => !hiddenColumns.has(c.id));
-		const visibleLabelColumns = getMatchingLabelColumns(visibleColumns.map(getColumnIdAndSpec), allLabelColumns);
-		if (!allPColumnsReady([...visibleColumns, ...visibleLabelColumns])) return void 0;
-		const visibleDef = createPTableDef({
-			columns: visibleColumns,
-			labelColumns: visibleLabelColumns,
-			coreJoinType,
-			filters,
-			sorting,
-			coreColumnPredicate
-		});
-		const visibleHandle = ctx.createPTableV2(visibleDef);
-		if (!visibleHandle) return void 0;
+	}
+	return result;
+}
+/**
+* For a linked column group [linker1, ..., linkerN, column], find the rightmost
+* element that has at least one non-hidden and not-yet-covered axis.
+* Return the prefix up to and including that element.
+* If no element has such an axis, return empty array.
+*/
+function trimGroupByVisibleAxes(group, hiddenSpecs, coveredAxisIds) {
+	if (hiddenSpecs === null) return group;
+	const hiddenAxisIds = new Set(hiddenSpecs.filter((s) => s.type === "axis").map((s) => canonicalizeJson(s.id)));
+	const uncoveredAxisIds = new Set(group.flatMap((c) => c.spec.axesSpec.map((as) => canonicalizeJson(getAxisId(as)))).filter((id) => !hiddenAxisIds.has(id) && !coveredAxisIds.has(id)));
+	let lastNeeded = -1;
+	for (let i = 0; i < group.length; i++) {
+		const newAxes = group[i].spec.axesSpec.map((as) => canonicalizeJson(getAxisId(as))).filter((id) => uncoveredAxisIds.has(id));
+		if (newAxes.length > 0) {
+			for (const id of newAxes) uncoveredAxisIds.delete(id);
+			lastNeeded = i;
+		}
+	}
+	return lastNeeded === -1 ? [] : group.slice(0, lastNeeded + 1);
+}
+/** Collect IDs of columns that must remain visible (sorted, filtered). */
+function collectPreservedColumnIds(sorting, filters) {
+	const sortedIds = (sorting ?? []).map((s) => s.column).filter((c) => c.type === "column").map((c) => c.id);
+	const filterIds = !isNil(filters) ? collectFilterSpecColumns(filters).flatMap((c) => {
+		const obj = parseJson(c);
+		return obj.type === "column" ? [obj.id] : [];
+	}) : [];
+	return new Set([...sortedIds, ...filterIds]);
+}
+/** Filter annotated columns to only visible ones, re-matching label columns for the visible subset. */
+function buildVisibleColumns(annotated, hiddenColumns, originalLabelColumns) {
+	const direct = annotated.direct.filter((c) => !hiddenColumns.has(c.id));
+	const linked = annotated.linked.filter((c) => !hiddenColumns.has(c.id));
+	return {
+		direct,
+		linked,
+		labels: getMatchingLabelColumns([...direct, ...linked].map(getColumnIdAndSpec), originalLabelColumns)
+	};
+}
+/** Resolve a ColumnSnapshot to a PColumn with lazily-evaluated data. */
+function resolveSnapshot(snap) {
+	return {
+		id: snap.id,
+		spec: snap.spec,
+		data: snap.data?.get()
+	};
+}
+/** Remap column references in sorting entries. */
+function remapSortingColumnIds(sorting, columns) {
+	return sorting?.map((s) => {
+		if (s.column.type === "axis") return s;
+		const id = s.column.id;
+		const column = columns.find((c) => (c.originalId ?? c.id) === id) ?? throwError(`Column ID "${id}" in sorting does not match any discovered column`);
 		return {
-			sourceId: tableStateNormalized.pTableParams.sourceId,
-			fullTableHandle: fullHandle,
-			fullPframeHandle: pframeHandle,
-			visibleTableHandle: visibleHandle
+			...s,
+			column: {
+				type: "column",
+				id: column.id
+			}
 		};
-	} finally {
-		collection.dispose();
-	}
+	});
 }
-/** Normalize raw ColumnSource | ColumnSource[] into a flat list of sources. */
-function normalizeSourceList(source) {
-	if (Array.isArray(source) && source.length > 0 && (Array.isArray(source[0]) || isColumnSnapshotProvider(source[0]))) return source;
-	return [source];
+/** Remap column references in a filter tree. */
+function remapFilterColumnIds(filters, columns) {
+	if (isNil(filters)) return filters;
+	const map = (tableColumnId) => {
+		const parsed = parseJson(tableColumnId);
+		if (parsed.type === "axis") return tableColumnId;
+		const originalId = parsed.id;
+		return canonicalizeJson({
+			type: "column",
+			id: (columns.find((c) => (c.originalId ?? c.id) === originalId) ?? throwError(`Column ID "${parsed.id}" in filters does not match any discovered column`)).id
+		});
+	};
+	return traverseFilterSpec(filters, {
+		leaf: (leaf) => {
+			if (leaf.type === void 0) return leaf;
+			const result = { ...leaf };
+			if ("column" in result) result.column = map(result.column);
+			if ("rhs" in result) result.rhs = map(result.rhs);
+			return result;
+		},
+		and: (results) => ({
+			type: "and",
+			filters: results
+		}),
+		or: (results) => ({
+			type: "or",
+			filters: results
+		}),
+		not: (result) => ({
+			type: "not",
+			filter: result
+		})
+	});
 }
-
 //#endregion
-export { createPTableDef, createPlDataTableV3, isColumnHidden, isColumnOptional };
+export { createPlDataTableV3 };
+
 //# sourceMappingURL=createPlDataTableV3.js.map