@platforma-sdk/model 1.68.8 → 1.70.0

package/src/components/PlDataTable/createPlDataTable/createPlDataTableV3.ts

@@ -21,7 +21,6 @@ import type { PlDataTableFilters, PlDataTableFilterSpecLeaf, PlDataTableModel }
 import { upgradePlDataTableStateV2 } from "../state-migration";
 import type { PlDataTableStateV2 } from "../state-migration";
 import type { ColumnSelector, ColumnSnapshot, ColumnVariant, MatchingMode } from "../../../columns";
-import { getAllLabelColumns, getMatchingLabelColumns } from "../labels";
 import type { DeriveLabelsOptions } from "../../../labels/derive_distinct_labels";
 import {
   deriveAllLabels,
@@ -97,11 +96,6 @@ export function createPlDataTableV3<A, U>(
 
   const splited = splitDiscoveredColumns(discovered);
 
-  const labelColumns = getMatchingLabelColumns(
-    [...splited.direct, ...splited.linked].map((v) => v.column),
-    getAllLabelColumns(ctx),
-  );
-
   const derivedLabels = deriveAllLabels({
     columns: discovered.map((dc) => ({
       id: dc.column.id,
@@ -109,7 +103,6 @@ export function createPlDataTableV3<A, U>(
       linkerPath: dc.path,
       qualifications: dc.qualifications,
     })),
-    labelColumns,
     deriveLabelsOptions: {
       includeNativeLabel: true,
       ...options.labelsOptions,
@@ -129,7 +122,6 @@ export function createPlDataTableV3<A, U>(
   const annotated = annotateColumnGroups({
     pframeSpec,
     ...splited,
-    labelColumns,
     derivedLabels,
     derivedTooltips,
     displayOptions: options.displayOptions,
@@ -143,7 +135,6 @@ export function createPlDataTableV3<A, U>(
   const columnIsAvailable = createColumnValidationById([
     ...annotated.direct.map((v) => v.column),
     ...annotated.linked.flatMap((lc) => [...lc.path.map((s) => s.linker), lc.column]),
-    ...annotated.labels,
   ]);
 
   const remapedDefaultFilters = remapFilterColumnIds(options.filters, discovered);
@@ -165,7 +156,6 @@ export function createPlDataTableV3<A, U>(
   const secondaryGroups: SecondaryGroup<undefined | PColumnDataUniversal>[] = buildSecondaryGroups(
     secondarySnapshots,
     annotated.linked,
-    annotated.labels,
   );
   const fullDef = createPTableDefV3({
     primaryJoinType,
@@ -181,7 +171,6 @@ export function createPlDataTableV3<A, U>(
   const pframeHandle = ctx.createPFrame([
     ...annotated.direct.map((v) => resolveSnapshot(v.column)),
     ...annotated.linked.map((v) => resolveSnapshot(v.column)),
-    ...annotated.labels,
     ...collectLinkerSnapshots(annotated.linked).map(resolveSnapshot),
   ]);
 
@@ -193,14 +182,13 @@ export function createPlDataTableV3<A, U>(
     hiddenSpecs,
   );
 
-  const visible = buildVisibleColumns(annotated, hiddenColumnIds, labelColumns);
+  const visible = buildVisibleColumns(annotated, hiddenColumnIds);
   const visibleDef = createPTableDefV3({
     primaryJoinType,
     primary: primaryEntries,
     secondary: buildSecondaryGroups(
       visible.direct.filter((c) => !c.isPrimary),
       visible.linked,
-      visible.labels,
     ),
     filters,
     sorting,
@@ -229,13 +217,11 @@ type SplitDiscoveredColumns = {
 type AnnotatedColumnGroups = {
   readonly direct: TableColumnVariant[];
   readonly linked: TableColumnVariant[];
-  readonly labels: PColumn<PColumnDataUniversal>[];
 };
 
 type VisibleColumns = {
   readonly direct: TableColumnVariant[];
   readonly linked: TableColumnVariant[];
-  readonly labels: PColumn<PColumnDataUniversal>[];
 };
 
 /** Split discovered columns into direct (no linker path) and linked (with linker path). */
@@ -262,26 +248,16 @@ function collectLinkerSnapshots(linked: TableColumnVariant[]): ColumnSnapshot<PO
 function annotateColumnGroups(params: {
   direct: TableColumnVariant[];
   linked: TableColumnVariant[];
-  labelColumns: PColumn<PColumnDataUniversal>[];
   derivedLabels: Record<string, string>;
   derivedTooltips: Record<string, string>;
   displayOptions?: ColumnsDisplayOptions;
   pframeSpec: PFrameSpecDriver;
 }): AnnotatedColumnGroups {
-  const {
-    direct,
-    linked,
-    labelColumns,
-    derivedLabels,
-    derivedTooltips,
-    displayOptions,
-    pframeSpec,
-  } = params;
+  const { direct, linked, derivedLabels, derivedTooltips, displayOptions, pframeSpec } = params;
 
   const allColumnsForRules = [
     ...direct.map((v) => v.column),
     ...linked.map((v) => v.column),
-    ...labelColumns,
     ...collectLinkerSnapshots(linked),
   ];
   const visibilityByColId = evaluateRules(
@@ -314,15 +290,9 @@ function annotateColumnGroups(params: {
     ),
   ).map((lc) => ({ ...lc, path: annotateLinkerPath(derivedLabels, lc.path) }));
 
-  const labelColumnsAnnotated = flow(
-    (cols: PColumn<PColumnDataUniversal>[]) => withHidenAxesAnnotations(cols),
-    (cols) => withLabelAnnotations(derivedLabels, cols),
-  )(labelColumns);
-
   return {
     direct: directAnnotated,
     linked: linkedAnnotated,
-    labels: labelColumnsAnnotated,
   };
 }
 
@@ -422,7 +392,6 @@ function validateSorting(sorting: PTableSorting[], isValidColumnId: (id: string)
 function buildSecondaryGroups(
   direct: TableColumnVariant[],
   linked: TableColumnVariant[],
-  labels: PColumn<PColumnDataUniversal>[],
 ): SecondaryGroup<undefined | PColumnDataUniversal>[] {
   return [
     ...direct.map(
@@ -436,16 +405,12 @@ function buildSecondaryGroups(
         entries: [
           ...lc.path.map((s) => ({
             column: resolveSnapshot(s.linker),
-            qualifications: s.qualifications,
           })),
           { column: resolveSnapshot(lc.column), qualifications: lc.qualifications.forHit },
         ],
         primaryQualifications: lc.qualifications.forQueries,
       }),
     ),
-    ...labels.map(
-      (c): SecondaryGroup<undefined | PColumnDataUniversal> => ({ entries: [{ column: c }] }),
-    ),
   ];
 }
 
@@ -490,15 +455,10 @@ function collectPreservedColumnIds(
 function buildVisibleColumns(
   annotated: AnnotatedColumnGroups,
   hiddenColumns: Set<PObjectId>,
-  originalLabelColumns: PColumn<PColumnDataUniversal>[],
 ): VisibleColumns {
   const direct = annotated.direct.filter((c) => !hiddenColumns.has(c.column.id));
   const linked = annotated.linked.filter((c) => !hiddenColumns.has(c.column.id));
-  const labels = getMatchingLabelColumns(
-    [...direct, ...linked].map((v) => v.column),
-    originalLabelColumns,
-  );
-  return { direct, linked, labels };
+  return { direct, linked };
 }
 
 /** Resolve a ColumnSnapshot to a PColumn with lazily-evaluated data. */

package/src/components/PlDataTable/createPlDataTable/discoverColumns.ts

@@ -13,7 +13,6 @@ import { toColumnSnapshotProvider } from "../../../columns/column_snapshot_provi
 import { collectCtxColumnSnapshotProviders } from "../../../columns/ctx_column_sources";
 import { throwError } from "@milaboratories/helpers";
 import type { ColumnsSelectorConfig, TableColumnVariant } from "./createPlDataTableV3";
-import { isNil } from "es-toolkit";
 
 export type DiscoverTableColumnOptions = {
   sources?: ColumnSource[];
@@ -45,14 +44,6 @@ export function discoverTableColumnSnaphots(
   try {
     const variants = collection.findColumnVariants({
       ...(resolvedOptions.selector ?? {}),
-      exclude: [
-        ...(Array.isArray(resolvedOptions.selector?.exclude)
-          ? resolvedOptions.selector.exclude
-          : !isNil(resolvedOptions.selector.exclude)
-            ? [resolvedOptions.selector.exclude]
-            : []),
-        { name: "pl7.app/label" },
-      ],
     });
     const anchors = collection.getAnchors();
     return mapToTableColumnVariants(variants, anchors);
@@ -111,7 +102,6 @@ function mapToTableColumnVariants(
       path: variant.path.map((p) => ({
         type: "linker",
         column: p.linker.id,
-        qualifications: p.qualifications,
       })),
       columnQualifications: variant.qualifications.forHit,
       queriesQualifications: variant.qualifications.forQueries,

package/src/components/PlDataTable/createPlDataTable/utils.test.ts

@@ -1,11 +1,4 @@
-import {
-  Annotation,
-  canonicalizeJson,
-  getAxisId,
-  type AxisId,
-  type PColumnSpec,
-  type PObjectId,
-} from "@milaboratories/pl-model-common";
+import { Annotation, type PColumnSpec, type PObjectId } from "@milaboratories/pl-model-common";
 import { SpecDriver } from "@milaboratories/pf-spec-driver";
 import { describe, expect, test } from "vitest";
 import { deriveAllLabels, evaluateRules, type LabelableColumn, type RuleColumn } from "./utils";
@@ -38,24 +31,6 @@ function makeLabelableColumn(
   };
 }
 
-function makeLabelColumn(
-  axisSpec: PColumnSpec["axesSpec"][0],
-  label: string,
-): { readonly spec: PColumnSpec } {
-  return {
-    spec: makeSpec({
-      name: "label-col",
-      valueType: "String",
-      annotations: { [Annotation.Label]: label },
-      axesSpec: [axisSpec],
-    }),
-  };
-}
-
-function axisKey(axis: PColumnSpec["axesSpec"][0]): string {
-  return canonicalizeJson<AxisId>(getAxisId(axis));
-}
-
 // ---------------------------------------------------------------------------
 // deriveAllLabels
 // ---------------------------------------------------------------------------
@@ -75,7 +50,6 @@ describe("deriveAllLabels", () => {
 
     const result = deriveAllLabels({
       columns,
-      labelColumns: [],
       deriveLabelsOptions: { includeNativeLabel: true },
     });
 
@@ -83,7 +57,7 @@ describe("deriveAllLabels", () => {
     expect(result["c2"]).toBe("Beta");
   });
 
-  test("returns axis labels from label columns when available", () => {
+  test("does not produce axis labels", () => {
     const axis = { type: "String", name: "sample" } as const;
     const columns: LabelableColumn[] = [
       makeLabelableColumn("c1", {
@@ -92,56 +66,17 @@ describe("deriveAllLabels", () => {
         annotations: { [Annotation.Label]: "Score" },
       }),
     ];
-    const labelColumns = [makeLabelColumn(axis, "Sample Name")];
-
-    const result = deriveAllLabels({
-      columns,
-      labelColumns,
-      deriveLabelsOptions: { includeNativeLabel: true },
-    });
-
-    expect(result[axisKey(axis)]).toBe("Sample Name");
-  });
-
-  test("falls back to axis annotation when no label column matches", () => {
-    const axis = { type: "String", name: "gene" } as const;
-    const columns: LabelableColumn[] = [
-      makeLabelableColumn("c1", {
-        name: "expr",
-        axesSpec: [{ ...axis, annotations: { [Annotation.Label]: "Gene ID" } }],
-        annotations: { [Annotation.Label]: "Expression" },
-      }),
-    ];
-
-    const result = deriveAllLabels({
-      columns,
-      labelColumns: [],
-      deriveLabelsOptions: { includeNativeLabel: true },
-    });
-
-    expect(result[axisKey(axis)]).toBe("Gene ID");
-  });
-
-  test("axis with no label annotation and no label column gets 'Unlabeled'", () => {
-    const axis = { type: "Int", name: "idx" } as const;
-    const columns: LabelableColumn[] = [
-      makeLabelableColumn("c1", {
-        name: "val",
-        axesSpec: [axis],
-        annotations: { [Annotation.Label]: "Value" },
-      }),
-    ];
 
     const result = deriveAllLabels({
       columns,
-      labelColumns: [],
       deriveLabelsOptions: { includeNativeLabel: true },
     });
 
-    expect(result[axisKey(axis)]).toBe("Unlabeled");
+    expect(Object.keys(result)).toEqual(["c1"]);
+    expect(result["c1"]).toBe("Score");
   });
 
-  test("deduplicates axes shared across columns", () => {
+  test("distinct labels for columns sharing an axis", () => {
     const sharedAxis = { type: "String", name: "sample" } as const;
     const columns: LabelableColumn[] = [
       makeLabelableColumn("c1", {
@@ -155,75 +90,15 @@ describe("deriveAllLabels", () => {
         annotations: { [Annotation.Label]: "Score 2" },
       }),
     ];
-    const labelColumns = [makeLabelColumn(sharedAxis, "Sample")];
 
     const result = deriveAllLabels({
       columns,
-      labelColumns,
       deriveLabelsOptions: { includeNativeLabel: true },
     });
 
-    // axis label appears once
-    expect(result[axisKey(sharedAxis)]).toBe("Sample");
-    // column labels are distinct
     expect(result["c1"]).toBe("Score 1");
     expect(result["c2"]).toBe("Score 2");
   });
-});
-
-// ---------------------------------------------------------------------------
-// deriveAxisLabels (tested through deriveAllLabels)
-// ---------------------------------------------------------------------------
-
-describe("deriveAxisLabels via deriveAllLabels", () => {
-  test("multiple axes each get their own label", () => {
-    const axis1 = { type: "String", name: "sample" } as const;
-    const axis2 = { type: "String", name: "chain" } as const;
-    const columns: LabelableColumn[] = [
-      makeLabelableColumn("c1", {
-        name: "value",
-        axesSpec: [axis1, axis2],
-        annotations: { [Annotation.Label]: "Value" },
-      }),
-    ];
-    const labelColumns = [
-      makeLabelColumn(axis1, "Sample ID"),
-      makeLabelColumn(axis2, "Chain Type"),
-    ];
-
-    const result = deriveAllLabels({
-      columns,
-      labelColumns,
-      deriveLabelsOptions: { includeNativeLabel: true },
-    });
-
-    expect(result[axisKey(axis1)]).toBe("Sample ID");
-    expect(result[axisKey(axis2)]).toBe("Chain Type");
-  });
-
-  test("label column overrides axis annotation", () => {
-    const axis = {
-      type: "String",
-      name: "sample",
-      annotations: { [Annotation.Label]: "Axis Annotation Label" },
-    } as const;
-    const columns: LabelableColumn[] = [
-      makeLabelableColumn("c1", {
-        name: "v",
-        axesSpec: [axis],
-        annotations: { [Annotation.Label]: "V" },
-      }),
-    ];
-    const labelColumns = [makeLabelColumn({ type: "String", name: "sample" }, "Label Col Label")];
-
-    const result = deriveAllLabels({
-      columns,
-      labelColumns,
-      deriveLabelsOptions: { includeNativeLabel: true },
-    });
-
-    expect(result[axisKey(axis)]).toBe("Label Col Label");
-  });
 
   // Regression: LabelableColumn.linkerPath used to be `linkerPath` while
   // deriveDistinctLabels.Entry expected `linkersPath`. Structural typing +
@@ -249,7 +124,6 @@ describe("deriveAxisLabels via deriveAllLabels", () => {
 
     const result = deriveAllLabels({
       columns,
-      labelColumns: [],
       deriveLabelsOptions: { includeNativeLabel: true },
     });
 

package/src/components/PlDataTable/createPlDataTable/utils.ts

@@ -5,9 +5,7 @@ import {
   type PObjectId,
   Annotation,
   canonicalizeAxisId,
-  canonicalizeJson,
   DiscoveredPColumnId,
-  getAxisId,
   readAnnotation,
   readAnnotationJson,
 } from "@milaboratories/pl-model-common";
@@ -236,16 +234,13 @@ export type LabelableColumn = {
 /** Derive labels for all table elements: columns via deriveDistinctLabels, axes from label columns. */
 export function deriveAllLabels(options: {
   columns: LabelableColumn[];
-  labelColumns: { readonly spec: PColumnSpec }[];
   deriveLabelsOptions?: DeriveLabelsOptions;
 }): Record<string, string> {
-  const { columns, labelColumns, deriveLabelsOptions } = options;
-  const axisLabels = deriveAxisLabels(columns, labelColumns);
+  const { columns, deriveLabelsOptions } = options;
   const entries = columns.map((c) => ({
     spec: c.spec,
     linkerPath: c.linkerPath?.map((step) => ({
       spec: step.linker.spec,
-      qualifications: step.qualifications,
     })),
     qualifications: c.qualifications,
   }));
@@ -253,26 +248,7 @@ export function deriveAllLabels(options: {
     (acc, label, index) => ((acc[columns[index].id] = label), acc),
     {} as Record<string, string>,
   );
-  return { ...axisLabels, ...columnLabels };
-}
-
-/** Derive axis labels from matching label columns, falling back to axis spec annotations. */
-function deriveAxisLabels(
-  columns: { readonly spec: PColumnSpec }[],
-  labelColumns: { readonly spec: PColumnSpec }[],
-): Record<string, string> {
-  const axisSpecMap = new Map(
-    columns.flatMap((c) => c.spec.axesSpec).map((a) => [canonicalizeJson(getAxisId(a)), a]),
-  );
-  const result: Record<string, string> = {};
-  for (const axisKey of axisSpecMap.keys()) {
-    const labelCol = labelColumns.find(
-      (lc) => canonicalizeJson(getAxisId(lc.spec.axesSpec[0])) === axisKey,
-    );
-    const source = labelCol?.spec ?? axisSpecMap.get(axisKey);
-    result[axisKey] = readAnnotation(source ?? {}, Annotation.Label)?.trim() ?? "Unlabeled";
-  }
-  return result;
+  return columnLabels;
 }
 
 /** Column shape required by tooltip derivation. */

package/src/components/PlDatasetSelector/build_dataset_options.ts

@@ -1,20 +1,25 @@
-import type {
-  DatasetOption,
-  Option,
-  PColumnSelector,
-  PObjectSpec,
-} from "@milaboratories/pl-model-common";
+import type { MultiColumnSelector, Option, PObjectSpec } from "@milaboratories/pl-model-common";
+import { multiColumnSelectorsToPredicate } from "@milaboratories/pl-model-common";
 import type { DeriveLabelsOptions } from "../../labels/derive_distinct_labels";
 import type { RenderCtxBase } from "../../render";
 import { ColumnCollectionBuilder } from "../../columns/column_collection_builder";
 import { collectCtxColumnSnapshotProviders } from "../../columns/ctx_column_sources";
+import type { DatasetOption } from "./dataset_selection";
 import { buildRefMap, filterMatchesToOptions, findFilterColumns } from "./filter_discovery";
+import { enrichmentVariantsToRefs, findEnrichmentColumns } from "./enrichment_discovery";
 
 export type BuildDatasetOptions = {
   /** Which result pool columns qualify as datasets. Defaults to all. */
-  selector?: PColumnSelector | PColumnSelector[] | ((spec: PObjectSpec) => boolean);
+  primary?: MultiColumnSelector | MultiColumnSelector[] | ((spec: PObjectSpec) => boolean);
   /** Formatting options for filter labels. */
   labelOptions?: DeriveLabelsOptions;
+  /**
+   * Enables enrichment discovery and filters hits attached to
+   * `DatasetOption.enrichments`. Use `() => true` to accept all; omit to disable.
+   */
+  withEnrichments?: MultiColumnSelector | MultiColumnSelector[] | ((spec: PObjectSpec) => boolean);
+  /** Maximum linker hops considered. Only used when `withEnrichments` is set. */
+  enrichmentMaxHops?: number;
 };
 
 /**
@@ -27,28 +32,54 @@ export function buildDatasetOptions(
   ctx: RenderCtxBase,
   opts?: BuildDatasetOptions,
 ): DatasetOption[] | undefined {
-  const predicate = opts?.selector ?? (() => true);
-  const options = ctx.resultPool.getOptions(predicate, { refsWithEnrichments: true });
+  const primary = opts?.primary;
+  const primaryPredicate =
+    primary === undefined
+      ? () => true
+      : typeof primary === "function"
+        ? primary
+        : multiColumnSelectorsToPredicate(primary);
+  const options = ctx.resultPool.getOptions(primaryPredicate, { refsWithEnrichments: true });
   if (options.length === 0) return [];
 
   const columnSources = collectCtxColumnSnapshotProviders(ctx);
   const refMap = buildRefMap(ctx.resultPool.getSpecs().entries);
   const pframeSpec = ctx.getService("pframeSpec");
 
-  return options.map((o: Option): DatasetOption => {
-    const datasetSpec = ctx.resultPool.getPColumnSpecByRef(o.ref);
-    if (!datasetSpec) return o;
+  return options.map((primary: Option): DatasetOption => {
+    const datasetSpec = ctx.resultPool.getPColumnSpecByRef(primary.ref);
+    if (!datasetSpec) return { primary };
 
     const builder = new ColumnCollectionBuilder(pframeSpec);
     for (const src of columnSources) builder.addSource(src);
     const collection = builder.build({ anchors: { main: datasetSpec } });
-    if (!collection) return o;
+    if (!collection) return { primary };
 
     try {
-      const matches = findFilterColumns(collection);
-      if (matches.length === 0) return o;
-      const filters = filterMatchesToOptions(matches, refMap, opts?.labelOptions);
-      return { ...o, filters };
+      const filterMatches = findFilterColumns(collection);
+      const filters =
+        filterMatches.length === 0
+          ? undefined
+          : filterMatchesToOptions(filterMatches, refMap, opts?.labelOptions);
+
+      let enrichments;
+      if (opts?.withEnrichments !== undefined) {
+        const enrichmentVariants = findEnrichmentColumns(collection, {
+          maxHops: opts.enrichmentMaxHops,
+          ...(typeof opts.withEnrichments === "function"
+            ? { predicate: opts.withEnrichments }
+            : { include: opts.withEnrichments }),
+        });
+        if (enrichmentVariants.length > 0) {
+          enrichments = enrichmentVariantsToRefs(enrichmentVariants, opts.labelOptions);
+        }
+      }
+
+      return {
+        primary,
+        ...(filters !== undefined && filters.length > 0 ? { filters } : {}),
+        ...(enrichments !== undefined && enrichments.length > 0 ? { enrichments } : {}),
+      };
     } finally {
       collection.dispose();
     }

package/src/components/PlDatasetSelector/dataset_selection.ts

@@ -0,0 +1,37 @@
+import type { LabeledEnrichmentRefs, Option, PrimaryRef } from "@milaboratories/pl-model-common";
+
+/** Dataset picker entry: user picks {@link primary}, gets {@link enrichments} attached. */
+export type DatasetOption = {
+  readonly primary: Option;
+  readonly filters?: readonly Option[];
+  readonly enrichments?: LabeledEnrichmentRefs;
+};
+
+/**
+ * Picked dataset bundle emitted by `PlDatasetSelector`. Stored opaquely in
+ * block data; block authors unbundle inside their args resolver.
+ */
+export type DatasetSelection = {
+  readonly __isDatasetSelection: "v1";
+  readonly primary: PrimaryRef;
+  readonly enrichments?: LabeledEnrichmentRefs;
+};
+
+export function isDatasetSelection(value: unknown): value is DatasetSelection {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { __isDatasetSelection?: unknown }).__isDatasetSelection === "v1" &&
+    "primary" in value
+  );
+}
+
+export function createDatasetSelection(
+  primary: PrimaryRef,
+  enrichments?: LabeledEnrichmentRefs,
+): DatasetSelection {
+  if (enrichments !== undefined && enrichments.length > 0) {
+    return { __isDatasetSelection: "v1", primary, enrichments };
+  }
+  return { __isDatasetSelection: "v1", primary };
+}