@platforma-sdk/model 1.66.2 → 1.68.0

package/src/components/PlDatasetSelector/filter_discovery.test.ts

@@ -0,0 +1,156 @@
+import { Annotation, createPlRef } from "@milaboratories/pl-model-common";
+import type { AxisSpec, PColumnSpec, PlRef, PObjectId } from "@milaboratories/pl-model-common";
+import { SpecDriver } from "@milaboratories/pf-spec-driver";
+import canonicalize from "canonicalize";
+import { afterEach, describe, expect, test } from "vitest";
+import type { ColumnSnapshot } from "../../columns/column_snapshot";
+import { ColumnCollectionBuilder } from "../../columns/column_collection_builder";
+import { buildRefMap, filterMatchesToOptions, findFilterColumns } from "./filter_discovery";
+
+const drivers: SpecDriver[] = [];
+
+function createSpecFrameCtx() {
+  const driver = new SpecDriver();
+  drivers.push(driver);
+  return driver;
+}
+
+afterEach(async () => {
+  for (const driver of drivers) await driver.dispose();
+  drivers.length = 0;
+});
+
+function axis(name: string): AxisSpec {
+  return { name, type: "String" } as AxisSpec;
+}
+
+function spec(
+  name: string,
+  axesSpec: AxisSpec[],
+  annotations: Record<string, string> = {},
+): PColumnSpec {
+  return { kind: "PColumn", name, valueType: "Int", axesSpec, annotations } as PColumnSpec;
+}
+
+function snap(id: string, s: PColumnSpec): ColumnSnapshot<PObjectId> {
+  return { id: id as PObjectId, spec: s, dataStatus: "ready", data: { get: () => ({}) as never } };
+}
+
+// anchor defines the key space: [sample, gene]
+const anchorAxes = [axis("sample"), axis("gene")];
+const anchorSpec = spec("anchor", anchorAxes);
+const anchorSnap = snap("anchor-id", anchorSpec);
+
+describe("findFilterColumns", () => {
+  test("returns columns with pl7.app/isSubset annotation", () => {
+    const filter = snap("f1", spec("filter1", [axis("sample")], { [Annotation.IsSubset]: "true" }));
+    const regular = snap("r1", spec("regular1", [axis("sample")]));
+
+    const builder = new ColumnCollectionBuilder(createSpecFrameCtx());
+    builder.addSource([filter, regular, anchorSnap]);
+    const collection = builder.build({ anchors: { main: anchorSpec } })!;
+
+    const results = findFilterColumns(collection);
+    expect(results.every((m) => m.column.spec.name !== "regular1")).toBe(true);
+    expect(results.some((m) => m.column.spec.name === "filter1")).toBe(true);
+  });
+
+  test("axes subset: excludes filter whose axes are not a subset of anchor axes", () => {
+    // filter with axis "other" — not a subset of anchor axes [sample, gene]
+    const badFilter = snap(
+      "f2",
+      spec("bad-filter", [axis("other")], { [Annotation.IsSubset]: "true" }),
+    );
+
+    const builder = new ColumnCollectionBuilder(createSpecFrameCtx());
+    builder.addSource([badFilter, anchorSnap]);
+    const collection = builder.build({ anchors: { main: anchorSpec } })!;
+
+    const results = findFilterColumns(collection);
+    expect(results.every((m) => m.column.spec.name !== "bad-filter")).toBe(true);
+  });
+
+  test("empty result when no filters exist", () => {
+    const regular = snap("r1", spec("regular1", [axis("sample")]));
+
+    const builder = new ColumnCollectionBuilder(createSpecFrameCtx());
+    builder.addSource([regular, anchorSnap]);
+    const collection = builder.build({ anchors: { main: anchorSpec } })!;
+
+    expect(findFilterColumns(collection)).toHaveLength(0);
+  });
+});
+
+describe("buildRefMap", () => {
+  test("maps canonicalized PlRef to original ref", () => {
+    const ref1 = createPlRef("b1", "out1");
+    const ref2 = createPlRef("b2", "out2", true);
+    const entries = [{ ref: ref1 }, { ref: ref2 }];
+
+    const map = buildRefMap(entries);
+
+    expect(map.get(canonicalize(ref1)! as PObjectId)).toBe(ref1);
+    expect(map.get(canonicalize(ref2)! as PObjectId)).toBe(ref2);
+    expect(map.size).toBe(2);
+  });
+
+  test("returns empty map for empty entries", () => {
+    expect(buildRefMap([]).size).toBe(0);
+  });
+});
+
+describe("filterMatchesToOptions", () => {
+  test("converts filter matches to Option[] with derived labels", () => {
+    const filterRef1 = createPlRef("b1", "filter-top1000");
+    const filterRef2 = createPlRef("b1", "filter-highconf");
+
+    // Build ref map from entries (simulating result pool)
+    const refMap = buildRefMap([
+      { ref: anchorSnap.id as unknown as PlRef }, // anchor — won't be looked up
+      { ref: filterRef1 },
+      { ref: filterRef2 },
+    ]);
+
+    // Build filter specs with isSubset annotation
+    const filterSpec1 = spec("filter1", [axis("sample")], { [Annotation.IsSubset]: "true" });
+    const filterSpec2 = spec("filter2", [axis("sample")], { [Annotation.IsSubset]: "true" });
+
+    // Use the canonical PlRef as the PObjectId (matches how result pool works)
+    const f1Snap = snap(canonicalize(filterRef1)! as string, filterSpec1);
+    const f2Snap = snap(canonicalize(filterRef2)! as string, filterSpec2);
+
+    const builder = new ColumnCollectionBuilder(createSpecFrameCtx());
+    builder.addSource([f1Snap, f2Snap, anchorSnap]);
+    const collection = builder.build({ anchors: { main: anchorSpec } })!;
+
+    const matches = findFilterColumns(collection);
+    expect(matches.length).toBe(2);
+
+    const options = filterMatchesToOptions(matches, refMap);
+    expect(options).toHaveLength(2);
+    // Each option has a ref and label
+    for (const opt of options) {
+      expect(opt.ref).toBeDefined();
+      expect(opt.label).toBeDefined();
+      expect(typeof opt.label).toBe("string");
+    }
+  });
+
+  test("returns empty array for empty matches", () => {
+    expect(filterMatchesToOptions([], new Map())).toEqual([]);
+  });
+
+  test("throws when ref not found in map", () => {
+    const filterSpec1 = spec("orphan", [axis("sample")], { [Annotation.IsSubset]: "true" });
+    const f1Snap = snap("orphan-id", filterSpec1);
+
+    const builder = new ColumnCollectionBuilder(createSpecFrameCtx());
+    builder.addSource([f1Snap, anchorSnap]);
+    const collection = builder.build({ anchors: { main: anchorSpec } })!;
+
+    const matches = findFilterColumns(collection);
+    expect(matches.length).toBe(1);
+
+    expect(() => filterMatchesToOptions(matches, new Map())).toThrow(/no PlRef found/);
+  });
+});

package/src/components/PlDatasetSelector/filter_discovery.ts

@@ -0,0 +1,77 @@
+import { Annotation } from "@milaboratories/pl-model-common";
+import type { Option, PlRef, PObjectId } from "@milaboratories/pl-model-common";
+import canonicalize from "canonicalize";
+import type {
+  AnchoredColumnCollection,
+  ColumnMatch,
+} from "../../columns/column_collection_builder";
+import {
+  deriveDistinctLabels,
+  type DeriveLabelsOptions,
+  type Entry,
+} from "../../labels/derive_distinct_labels";
+
+/**
+ * Matches columns annotated `pl7.app/isSubset: "true"` whose axes ⊆ anchor axes.
+ *
+ * The axes-subset constraint is enforced by `mode: "enrichment"`, which sets
+ * `allowFloatingHitAxes: false` — every axis of the matched column must be
+ * present in the anchor's axes. See `matchingModeToConstraints()` in
+ * `column_collection_builder.ts`.
+ */
+export function findFilterColumns(collection: AnchoredColumnCollection): ColumnMatch[] {
+  return collection.findColumns({
+    mode: "enrichment",
+    include: {
+      annotations: { [Annotation.IsSubset]: "true" },
+    },
+  });
+}
+
+/**
+ * Derive labeled options from filter column matches, for use in DatasetOption.filters.
+ *
+ * @param matches - from findFilterColumns()
+ * @param refsByObjectId - from {@link buildRefMap}
+ * @param labelOptions - forwarded to deriveDistinctLabels()
+ */
+export function filterMatchesToOptions(
+  matches: ColumnMatch[],
+  refsByObjectId: ReadonlyMap<PObjectId, PlRef>,
+  labelOptions?: DeriveLabelsOptions,
+): Option[] {
+  if (matches.length === 0) return [];
+
+  // Each ColumnMatch can be reached via multiple variants (different linker
+  // paths / qualifications). We emit one Option per variant so the user can
+  // pick a specific path — `deriveDistinctLabels` disambiguates labels by
+  // path.
+  const flattened = matches.flatMap((m) => m.variants.map((v) => ({ match: m, variant: v })));
+
+  const entries: Entry[] = flattened.map(({ match, variant }) => ({
+    spec: match.column.spec,
+    linkerPath: variant.path.map((p) => ({ spec: p.linker.spec })),
+  }));
+
+  const labels = deriveDistinctLabels(entries, labelOptions);
+
+  return flattened.map(({ match }, i) => {
+    const ref = refsByObjectId.get(match.column.id);
+    if (ref === undefined)
+      throw new Error(
+        `no PlRef found for filter column ${match.column.spec.name} (id: ${match.column.id})`,
+      );
+    return { ref, label: labels[i] };
+  });
+}
+
+/**
+ * Usage: `buildRefMap(ctx.resultPool.getSpecs().entries)`
+ */
+export function buildRefMap(entries: readonly { readonly ref: PlRef }[]): Map<PObjectId, PlRef> {
+  const map = new Map<PObjectId, PlRef>();
+  for (const entry of entries) {
+    map.set(canonicalize(entry.ref)! as PObjectId, entry.ref);
+  }
+  return map;
+}

package/src/components/PlDatasetSelector/index.ts

@@ -0,0 +1,2 @@
+export * from "./filter_discovery";
+export * from "./build_dataset_options";

package/src/components/index.ts

@@ -1,5 +1,6 @@
 export * from "./PFrameForGraphs";
 export * from "./PlAnnotations";
+export * from "./PlDatasetSelector";
 export * from "./PlDataTable";
 export * from "./PlMultiSequenceAlignment";
 export * from "./PlSelectionModel";

package/src/platforma.ts

@@ -7,9 +7,10 @@ import type {
   BlockStateV3,
   DriverKit,
   OutputWithStatus,
+  UiServices as AllUiServices,
 } from "@milaboratories/pl-model-common";
 import type { SdkInfo } from "./version";
-import type { ServiceDispatch, UiServices as AllUiServices } from "@milaboratories/pl-model-common";
+import type { ServiceDispatch } from "@milaboratories/pl-model-common";
 import type { BlockStatePatch } from "./block_state_patch";
 import type { PluginRecord } from "./block_model";
 import type { PluginHandle, PluginFactoryLike } from "./plugin_handle";

package/src/services/block_services.ts

@@ -10,6 +10,8 @@ import { resolveRequiredServices } from "@milaboratories/pl-model-common";
  */
 export const BLOCK_SERVICE_FLAGS = {
   requiresPFrameSpec: true,
+  requiresPFrame: true,
+  requiresDialog: true,
 } as const satisfies Partial<ServiceRequireFlags>;
 
 export type BlockServiceFlags = typeof BLOCK_SERVICE_FLAGS;

package/src/services/service_resolve.ts

@@ -50,9 +50,7 @@ void _modelSpec;
 void _uiSpec;
 
 // Block default services do NOT include pframe (only plugins can request it)
-// @ts-expect-error pframe is not in default block model services
 const _modelPframe: BlockDefaultModelServices["pframe"] = undefined!;
-// @ts-expect-error pframe is not in default block UI services
 const _uiPframe: BlockDefaultUiServices["pframe"] = undefined!;
 void _modelPframe;
 void _uiPframe;