@platforma-sdk/model 1.65.10 → 1.67.0

package/src/labels/derive_distinct_tooltips.test.ts

@@ -0,0 +1,233 @@
+import {
+  Annotation,
+  type AxisQualification,
+  type PColumnSpec,
+  type PObjectId,
+} from "@milaboratories/pl-model-common";
+import { describe, expect, test } from "vitest";
+import { deriveDistinctTooltips, type TooltipEntry } from "./derive_distinct_tooltips";
+import type { ColumnSnapshot, MatchVariant } from "../columns";
+
+function createSpec(name: string, label?: string): PColumnSpec {
+  return {
+    kind: "PColumn",
+    name,
+    valueType: "Int",
+    axesSpec: [],
+    annotations: label !== undefined ? { [Annotation.Label]: label } : {},
+  } as PColumnSpec;
+}
+
+function axisQualification(
+  axisName: string,
+  contextDomain: Record<string, string>,
+): AxisQualification {
+  return { axis: { name: axisName }, contextDomain };
+}
+
+function linkerSnapshot(name: string, label?: string): ColumnSnapshot<PObjectId> {
+  return {
+    id: `linker-${name}` as PObjectId,
+    spec: createSpec(name, label),
+    dataStatus: "ready",
+    data: undefined,
+  };
+}
+
+function pathStep(
+  linkerName: string,
+  qualifications: AxisQualification[],
+  label?: string,
+): MatchVariant["path"][number] {
+  return { linker: linkerSnapshot(linkerName, label), qualifications };
+}
+
+describe("deriveDistinctTooltips", () => {
+  test("empty entry (no qualifications, no linker path) → undefined", () => {
+    const entries: TooltipEntry[] = [{ spec: createSpec("col1") }];
+    expect(deriveDistinctTooltips(entries)).toEqual([undefined]);
+  });
+
+  test("only header info but no sections → undefined (single section filtered)", () => {
+    const entries: TooltipEntry[] = [
+      {
+        spec: createSpec("col1", "Column 1"),
+        variantIndex: 1,
+        variantCount: 1,
+      },
+    ];
+    expect(deriveDistinctTooltips(entries)).toEqual([undefined]);
+  });
+
+  test("linker path produces Origin path section", () => {
+    const entries: TooltipEntry[] = [
+      {
+        spec: createSpec("hit_col", "Hit Col"),
+        linkerPath: [
+          pathStep("linker_a", [axisQualification("sample", { batch: "A" })], "Linker A"),
+        ],
+      },
+    ];
+    const [tooltip] = deriveDistinctTooltips(entries);
+    expect(tooltip).toBeDefined();
+    expect(tooltip).toContain("Origin path");
+    expect(tooltip).toContain("linker 1: Linker A");
+    expect(tooltip).toContain("qualifies: sample context: batch=A");
+    expect(tooltip).toContain("hit column: Hit Col");
+  });
+
+  test("qualifications.forQueries produces Anchors section", () => {
+    const entries: TooltipEntry[] = [
+      {
+        spec: createSpec("col1", "Col 1"),
+        qualifications: {
+          forQueries: {
+            ["main" as PObjectId]: [axisQualification("sample", { batch: "A" })],
+            ["other" as PObjectId]: [axisQualification("gene", { source: "X" })],
+          },
+          forHit: [],
+        },
+      },
+    ];
+    const [tooltip] = deriveDistinctTooltips(entries);
+    expect(tooltip).toContain("Anchors (bound via this variant)");
+    expect(tooltip).toContain("main   sample context: batch=A");
+    expect(tooltip).toContain("other   gene context: source=X");
+  });
+
+  test("qualifications.forHit produces Hit section", () => {
+    const entries: TooltipEntry[] = [
+      {
+        spec: createSpec("col1", "Col 1"),
+        qualifications: {
+          forQueries: {},
+          forHit: [axisQualification("sample", { batch: "B" })],
+        },
+      },
+    ];
+    const [tooltip] = deriveDistinctTooltips(entries);
+    expect(tooltip).toContain("Hit column qualifications");
+    expect(tooltip).toContain("sample context: batch=B");
+  });
+
+  test("distinctiveQualifications produces Distinctive section", () => {
+    const entries: TooltipEntry[] = [
+      {
+        spec: createSpec("col1", "Col 1"),
+        distinctiveQualifications: {
+          forQueries: { ["main" as PObjectId]: [axisQualification("sample", { batch: "A" })] },
+          forHit: [axisQualification("gene", { source: "Y" })],
+        },
+      },
+    ];
+    const [tooltip] = deriveDistinctTooltips(entries);
+    expect(tooltip).toContain("Distinctive (what separates this variant)");
+    expect(tooltip).toContain("main: sample context: batch=A");
+    expect(tooltip).toContain("hit: gene context: source=Y");
+  });
+
+  test("variantCount > 1 adds Variant N of M line in header", () => {
+    const entries: TooltipEntry[] = [
+      {
+        spec: createSpec("col1", "Col 1"),
+        variantIndex: 1,
+        variantCount: 2,
+        qualifications: {
+          forQueries: { ["main" as PObjectId]: [axisQualification("sample", { batch: "A" })] },
+          forHit: [],
+        },
+      },
+    ];
+    const [tooltip] = deriveDistinctTooltips(entries);
+    expect(tooltip).toContain("Variant: 1 of 2");
+  });
+
+  test("axis qualification with empty contextDomain shows only axis name", () => {
+    const entries: TooltipEntry[] = [
+      {
+        spec: createSpec("col1", "Col 1"),
+        qualifications: {
+          forQueries: { ["main" as PObjectId]: [axisQualification("sample", {})] },
+          forHit: [],
+        },
+      },
+    ];
+    const [tooltip] = deriveDistinctTooltips(entries);
+    expect(tooltip).toContain("main   sample");
+    expect(tooltip).not.toContain("context:");
+  });
+
+  test("empty forQueries object → no Anchors section", () => {
+    const entries: TooltipEntry[] = [
+      {
+        spec: createSpec("col1", "Col 1"),
+        qualifications: { forQueries: {}, forHit: [] },
+        linkerPath: [pathStep("linker_a", [], "Linker A")],
+      },
+    ];
+    const [tooltip] = deriveDistinctTooltips(entries);
+    expect(tooltip).not.toContain("Anchors");
+  });
+
+  test("multi-step linker path numbers sequentially", () => {
+    const entries: TooltipEntry[] = [
+      {
+        spec: createSpec("hit_col", "Hit Col"),
+        linkerPath: [
+          pathStep("linker_a", [], "Linker A"),
+          pathStep("linker_b", [axisQualification("sample", { batch: "B" })], "Linker B"),
+        ],
+      },
+    ];
+    const [tooltip] = deriveDistinctTooltips(entries);
+    expect(tooltip).toContain("linker 1: Linker A");
+    expect(tooltip).toContain("linker 2: Linker B");
+  });
+
+  test("all sections compose with double-newline separators", () => {
+    const entries: TooltipEntry[] = [
+      {
+        spec: createSpec("hit_col", "Hit"),
+        variantIndex: 2,
+        variantCount: 2,
+        linkerPath: [pathStep("linker_a", [axisQualification("sample", { batch: "B" })], "LA")],
+        qualifications: {
+          forQueries: { ["main" as PObjectId]: [axisQualification("sample", { batch: "B" })] },
+          forHit: [axisQualification("sample", { batch: "B" })],
+        },
+        distinctiveQualifications: {
+          forQueries: { ["main" as PObjectId]: [axisQualification("sample", { batch: "B" })] },
+          forHit: [],
+        },
+      },
+    ];
+    const [tooltip] = deriveDistinctTooltips(entries);
+    expect(tooltip).toBeDefined();
+    const sections = tooltip!.split("\n\n");
+    expect(sections.length).toBe(5);
+    expect(sections[0]).toContain("Variant: 2 of 2");
+    expect(sections[1]).toContain("Origin path");
+    expect(sections[2]).toContain("Anchors");
+    expect(sections[3]).toContain("Hit column qualifications");
+    expect(sections[4]).toContain("Distinctive");
+  });
+
+  test("parallel results — array aligns with input", () => {
+    const entries: TooltipEntry[] = [
+      { spec: createSpec("a") },
+      {
+        spec: createSpec("b", "B"),
+        qualifications: {
+          forQueries: { ["main" as PObjectId]: [axisQualification("sample", { batch: "A" })] },
+          forHit: [],
+        },
+      },
+      { spec: createSpec("c") },
+    ];
+    const result = deriveDistinctTooltips(entries);
+    expect(result.length).toBe(3);
+    expect(result[0]).toBeUndefined();
+    expect(result[1]).toBeDefined();
+    expect(result[2]).toBeUndefined();
+  });
+});

package/src/labels/derive_distinct_tooltips.ts

@@ -0,0 +1,130 @@
+import {
+  Annotation,
+  PObjectId,
+  readAnnotation,
+  type AxisQualification,
+  type PColumnSpec,
+} from "@milaboratories/pl-model-common";
+import { isNil } from "es-toolkit";
+import type { MatchQualifications, MatchVariant } from "../columns";
+
+export type TooltipEntry = {
+  /** Main column spec — used for column-name fallback when no label. */
+  spec: PColumnSpec;
+  /** Full qualifications carried by this variant. */
+  qualifications?: MatchQualifications;
+  /** Minimal qualifications that separate this variant from its siblings. */
+  distinctiveQualifications?: MatchQualifications;
+  /** Linker steps traversed to reach the hit column. */
+  linkerPath?: MatchVariant["path"];
+  /** Position of this variant within the same physical column (1-based). */
+  variantIndex?: number;
+  /** Total variants for the same physical column. */
+  variantCount?: number;
+};
+
+/** Format tooltip strings for each entry. Returns `undefined` when nothing useful. */
+export function deriveDistinctTooltips(entries: TooltipEntry[]): (undefined | string)[] {
+  return entries.map(formatTooltip);
+}
+
+function formatTooltip(entry: TooltipEntry): undefined | string {
+  const sections: string[] = [];
+
+  const header = formatHeader(entry);
+  if (header !== undefined) sections.push(header);
+
+  const origin = formatOriginPath(entry);
+  if (origin !== undefined) sections.push(origin);
+
+  const anchors = formatAnchors(entry.qualifications);
+  if (anchors !== undefined) sections.push(anchors);
+
+  const hit = formatHit(entry.qualifications);
+  if (hit !== undefined) sections.push(hit);
+
+  const distinctive = formatDistinctive(entry.distinctiveQualifications);
+  if (distinctive !== undefined) sections.push(distinctive);
+
+  if (sections.length <= 1) return undefined;
+  return sections.join("\n\n");
+}
+
+const BULLET_1 = "  • ";
+const SUB_BULLET = "      ";
+
+function formatHeader(entry: TooltipEntry): undefined | string {
+  const lines: string[] = [];
+  if (entry.variantCount !== undefined && entry.variantCount > 1) {
+    lines.push(`Variant: ${entry.variantIndex ?? "?"} of ${entry.variantCount}`);
+  }
+  return lines.join("\n");
+}
+
+function formatOriginPath(entry: TooltipEntry): undefined | string {
+  const path = entry.linkerPath ?? [];
+  if (path.length === 0) return undefined;
+
+  const lines = ["Origin path"];
+  path.forEach((step, i) => {
+    const label =
+      readAnnotation(step.linker.spec, Annotation.LinkLabel) ??
+      readAnnotation(step.linker.spec, Annotation.Label) ??
+      step.linker.spec.name;
+    lines.push(`${BULLET_1}linker ${i + 1}: ${label}`);
+    const qs = formatAxisQualifications(step.qualifications);
+    if (qs !== undefined) lines.push(`${SUB_BULLET}qualifies: ${qs}`);
+  });
+  const hitName = readAnnotation(entry.spec, Annotation.Label) ?? entry.spec.name;
+  lines.push(`${BULLET_1}hit column: ${hitName}`);
+  return lines.join("\n");
+}
+
+function formatAnchors(q: undefined | MatchQualifications): undefined | string {
+  if (isNil(q)) return undefined;
+  const ids = Object.keys(q.forQueries);
+  if (ids.length === 0) return undefined;
+
+  const lines = [];
+  for (const id of ids) {
+    const item = q.forQueries[id as PObjectId];
+    if (item.length === 0) continue;
+    const rendered = formatAxisQualifications(item);
+    lines.push(`${BULLET_1}${id}${rendered !== undefined ? `   ${rendered}` : ""}`);
+  }
+  return lines.length > 0
+    ? ["Anchors (bound via this variant)"].concat(lines).join("\n")
+    : undefined;
+}
+
+function formatHit(q: undefined | MatchQualifications): undefined | string {
+  if (isNil(q) || q.forHit.length === 0) return undefined;
+  const rendered = formatAxisQualifications(q.forHit);
+  if (rendered === undefined) return undefined;
+  return ["Hit column qualifications", `${BULLET_1}${rendered}`].join("\n");
+}
+
+function formatDistinctive(q: undefined | MatchQualifications): undefined | string {
+  if (isNil(q)) return undefined;
+  const bullets: string[] = [];
+  for (const id of Object.keys(q.forQueries)) {
+    for (const item of q.forQueries[id as PObjectId])
+      bullets.push(`${BULLET_1}${id}: ${formatQualification(item)}`);
+  }
+  for (const item of q.forHit) bullets.push(`${BULLET_1}hit: ${formatQualification(item)}`);
+  if (bullets.length === 0) return undefined;
+  return ["Distinctive (what separates this variant)", ...bullets].join("\n");
+}
+
+function formatAxisQualifications(qs: AxisQualification[]): undefined | string {
+  if (qs.length === 0) return undefined;
+  return qs.map(formatQualification).join("; ");
+}
+
+function formatQualification(q: AxisQualification): string {
+  const axisName = typeof q.axis === "string" ? q.axis : (q.axis.name ?? JSON.stringify(q.axis));
+  const entries = Object.entries(q.contextDomain);
+  if (entries.length === 0) return axisName;
+  const kv = entries.map(([k, v]) => `${k}=${v}`).join(", ");
+  return `${axisName} context: ${kv}`;
+}

package/src/labels/index.ts

@@ -1 +1,2 @@
 export * from "./derive_distinct_labels";
+export * from "./derive_distinct_tooltips";

package/src/render/api.ts

@@ -3,6 +3,7 @@ import type {
   AnyFunction,
   AxisId,
   DataInfo,
+  ModelServices,
   Option,
   PColumn,
   PColumnLazy,
@@ -23,7 +24,6 @@ import type {
   PlRef,
   ResolveAnchorsOptions,
   ResultCollection,
-  ServiceName,
   SUniversalPColumnId,
   ValueOrError,
 } from "@milaboratories/pl-model-common";
@@ -55,11 +55,8 @@ import type {
   PluginHandle,
   PluginFactoryLike,
   InferFactoryData,
-  InferFactoryModelServices,
   InferFactoryParams,
 } from "../plugin_handle";
-import type { BlockDefaultModelServices } from "../services/service_resolve";
-import type { ModelServices as AllModelServices } from "@milaboratories/pl-model-common";
 import { TreeNodeAccessor, ifDef } from "./accessor";
 import type { FutureRef } from "./future";
 import type { AccessorHandle, GlobalCfgRenderCtx } from "./internal";
@@ -75,6 +72,7 @@ import type { APColumnSelectorWithSplit } from "./util/split_selectors";
 import { patchInSetFilters } from "./util/pframe_upgraders";
 import { allPColumnsReady } from "./util/pcolumn_data";
 import type { PColumnDataUniversal } from "./internal";
+import { getService } from "../services";
 
 /**
  * Helper function to match domain objects
@@ -554,40 +552,11 @@ export class ResultPool implements ColumnProvider, AxisLabelProvider {
 }
 
 /** Main entry point to the API available within model lambdas (like outputs, sections, etc..) */
-export abstract class RenderCtxBase<
-  Args = unknown,
-  Data = unknown,
-  ModelServices = Partial<AllModelServices>,
-> {
+export abstract class RenderCtxBase<Args = unknown, Data = unknown> {
   protected readonly ctx: GlobalCfgRenderCtx;
-  private readonly requiredServiceNames: ServiceName[];
-  private cachedServices?: ModelServices;
 
-  constructor(requiredServiceNames: ServiceName[] = []) {
+  constructor() {
     this.ctx = getCfgRenderCtx();
-    this.requiredServiceNames = requiredServiceNames;
-  }
-
-  get services(): ModelServices {
-    if (this.cachedServices) return this.cachedServices;
-    const ctx = this.ctx;
-    const services = Object.freeze(
-      Object.fromEntries(
-        this.requiredServiceNames.map((id) => [
-          id,
-          Object.freeze(
-            Object.fromEntries(
-              (ctx.getServiceMethods(id) as string[]).map((method) => [
-                method,
-                (...args: unknown[]) => ctx.callServiceMethod(id, method, ...args),
-              ]),
-            ),
-          ),
-        ]),
-      ),
-    ) as ModelServices;
-    this.cachedServices = services;
-    return services;
   }
 
   private dataCache?: { v: Data };
@@ -619,6 +588,10 @@ export abstract class RenderCtxBase<
     return this.activeArgsCache.v;
   }
 
+  public getService<T extends keyof ModelServices>(name: T): ModelServices[T] {
+    return getService(name);
+  }
+
   // /** Can be used to determine features provided by the desktop instance. */
   // public get featureFlags() {
   //   return this.ctx.featureFlags;
@@ -771,11 +744,7 @@ export abstract class RenderCtxBase<
 }
 
 /** Main entry point to the API available within model lambdas (like outputs, sections, etc..) for v3+ blocks */
-export class BlockRenderCtx<
-  Args = unknown,
-  Data = unknown,
-  ModelServices = BlockDefaultModelServices,
-> extends RenderCtxBase<Args, Data, ModelServices> {
+export class BlockRenderCtx<Args = unknown, Data = unknown> extends RenderCtxBase<Args, Data> {
   private argsCache?: { v: Args | undefined };
   public get args(): Args | undefined {
     if (this.argsCache === undefined) {
@@ -824,19 +793,15 @@ export class RenderCtxLegacy<Args = unknown, UiState = unknown> extends RenderCt
  *
  * @typeParam F - PluginFactoryLike phantom carrying data/params/outputs types
  */
-export class PluginRenderCtx<
-  F extends PluginFactoryLike = PluginFactoryLike,
-  ModelServices = InferFactoryModelServices<F>,
-> extends RenderCtxBase<unknown, InferFactoryData<F>, ModelServices> {
+export class PluginRenderCtx<F extends PluginFactoryLike = PluginFactoryLike> extends RenderCtxBase<
+  unknown,
+  InferFactoryData<F>
+> {
   private readonly handle: PluginHandle<F>;
   private readonly wrappedInputs: Record<string, () => unknown>;
 
-  constructor(
-    handle: PluginHandle<F>,
-    wrappedInputs: Record<string, () => unknown>,
-    requiredServiceNames: ServiceName[] = [],
-  ) {
-    super(requiredServiceNames);
+  constructor(handle: PluginHandle<F>, wrappedInputs: Record<string, () => unknown>) {
+    super();
     this.handle = handle;
     this.wrappedInputs = wrappedInputs;
   }

package/src/services/get_services.ts

@@ -0,0 +1,28 @@
+import { ModelServices, ServiceName } from "@milaboratories/pl-model-common";
+import { getCfgRenderCtx } from "../internal";
+import { ValueOf } from "@milaboratories/helpers";
+import { createServiceProxy } from "./service_bridge";
+import { GlobalCfgRenderCtx } from "../render/internal";
+
+const cachedServices = new WeakMap<
+  GlobalCfgRenderCtx,
+  Map<keyof ModelServices, ValueOf<ModelServices>>
+>();
+
+export function getService<T extends keyof ModelServices>(name: T): ModelServices[T] {
+  const ctx = getCfgRenderCtx();
+
+  const map = cachedServices.has(ctx)
+    ? cachedServices.get(ctx)!
+    : (() => {
+        cachedServices.set(ctx, new Map());
+        return cachedServices.get(ctx)!;
+      })();
+
+  return map.has(name)
+    ? (map.get(name) as ModelServices[T])
+    : (() => {
+        map.set(name, createServiceProxy(ctx)(name as ServiceName) as ModelServices[T]);
+        return map.get(name) as ModelServices[T];
+      })();
+}

package/src/services/index.ts

@@ -1,3 +1,4 @@
 export * from "./block_services";
 export * from "./service_resolve";
 export * from "./service_bridge";
+export * from "./get_services";

package/src/services/service_bridge.ts

@@ -15,7 +15,7 @@ import { UiServiceRegistry } from "@milaboratories/pl-model-common";
 // Makes a remote node service appear local.
 // Given a service ID, returns an object implementing the service's UI interface.
 // Provided by the desktop app (e.g. backed by Electron IPC).
-export type NodeServiceProxy = <S extends ServiceTypesLike>(
+export type ServiceProxy = <S extends ServiceTypesLike>(
   serviceId: ServiceName<S>,
 ) => InferServiceUi<S>;
 
@@ -53,10 +53,10 @@ export function buildServices<S extends Partial<AllUiServices> = Partial<AllUiSe
 }
 
 /**
- * Builds a NodeServiceProxy from a ServiceDispatch.
+ * Builds a ServiceProxy from a ServiceDispatch.
  * Each service method call is forwarded to dispatch.callServiceMethod.
  */
-export function createNodeServiceProxy(dispatch: ServiceDispatch): NodeServiceProxy {
+export function createServiceProxy(dispatch: ServiceDispatch): ServiceProxy {
   return ((serviceId: ServiceName) =>
     Object.freeze(
       Object.fromEntries(
@@ -64,8 +64,8 @@ export function createNodeServiceProxy(dispatch: ServiceDispatch): NodeServicePr
           .getServiceMethods(serviceId)
           .map((method) => [
             method,
-            async (...args: unknown[]) => dispatch.callServiceMethod(serviceId, method, ...args),
+            (...args: unknown[]) => dispatch.callServiceMethod(serviceId, method, ...args),
           ]),
       ),
-    )) as NodeServiceProxy;
+    )) as ServiceProxy;
 }