@platforma-sdk/model 1.53.15 → 1.54.7

package/src/components/PlDataTable/table.ts

@@ -0,0 +1,279 @@
+import type {
+  AxisId,
+  AxisSpec,
+  DataInfo,
+  PColumn,
+  PColumnIdAndSpec,
+  PColumnValues,
+  PObjectId,
+  PTableColumnId,
+  PTableColumnIdAxis,
+  PTableColumnIdColumn,
+  PTableDefV2,
+  PTableSorting,
+  SpecQuery,
+  SingleAxisSelector,
+  SpecQueryExpression,
+  SpecQueryJoinEntry,
+} from "@milaboratories/pl-model-common";
+import {
+  Annotation,
+  canonicalizeJson,
+  getAxisId,
+  getColumnIdAndSpec,
+  isLinkerColumn,
+  readAnnotation,
+  uniqueBy,
+  isBooleanExpression,
+} from "@milaboratories/pl-model-common";
+import type { PTableFilters } from "../../filters";
+import { filterSpecToSpecQueryExpr } from "../../filters";
+import type { RenderCtxBase, TreeNodeAccessor, PColumnDataUniversal } from "../../render";
+import { allPColumnsReady, deriveLabels } from "../../render";
+import { identity, isFunction, isNil } from "es-toolkit";
+import { filterEmptyPieces } from "../../filters/converters/filterEmpty";
+import type { CreatePlDataTableOps, PlDataTableModel } from "./v5";
+import { upgradePlDataTableStateV2 } from "./state-migration";
+import type { PlDataTableStateV2 } from "./state-migration";
+import type { PlDataTableSheet } from "./v5";
+import { getAllLabelColumns, getMatchingLabelColumns } from "./labels";
+
+/** Convert a PTableColumnId to a SpecQueryExpression reference. */
+function columnIdToExpr(col: PTableColumnId): SpecQueryExpression {
+  if (col.type === "axis") {
+    return { type: "axisRef", value: col.id as SingleAxisSelector };
+  }
+  return { type: "columnRef", value: col.id };
+}
+
+/** Wrap a SpecQuery as a SpecQueryJoinEntry with empty qualifications. */
+function joinEntry<C>(input: SpecQuery<C>): SpecQueryJoinEntry<C> {
+  return { entry: input, qualifications: [] };
+}
+
+function createPTableDef(params: {
+  columns: PColumn<PColumnDataUniversal>[];
+  labelColumns: PColumn<PColumnDataUniversal>[];
+  coreJoinType: "inner" | "full";
+  filters: PTableFilters;
+  sorting: PTableSorting[];
+  coreColumnPredicate?: (spec: PColumnIdAndSpec) => boolean;
+}): PTableDefV2<PColumn<TreeNodeAccessor | PColumnValues | DataInfo<TreeNodeAccessor>>> {
+  let coreColumns = params.columns;
+  const secondaryColumns: typeof params.columns = [];
+
+  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);
+
+  // Build SpecQuery directly from columns
+  const coreJoinQuery: SpecQuery<
+    PColumn<TreeNodeAccessor | PColumnValues | DataInfo<TreeNodeAccessor>>
+  > = {
+    type: params.coreJoinType === "inner" ? "innerJoin" : "fullJoin",
+    entries: coreColumns.map((c) => joinEntry({ type: "column", column: c })),
+  };
+
+  let query: SpecQuery<PColumn<TreeNodeAccessor | PColumnValues | DataInfo<TreeNodeAccessor>>> = {
+    type: "outerJoin",
+    primary: joinEntry(coreJoinQuery),
+    secondary: secondaryColumns.map((c) => joinEntry({ type: "column", column: c })),
+  };
+
+  // Apply filters
+  if (params.filters !== null) {
+    const nonEmpty = filterEmptyPieces(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,
+      };
+    }
+  }
+
+  // Apply sorting
+  if (params.sorting.length > 0) {
+    query = {
+      type: "sort",
+      input: query,
+      sortBy: params.sorting.map((s) => ({
+        expression: columnIdToExpr(s.column),
+        ascending: s.ascending,
+        nullsFirst: s.ascending === s.naAndAbsentAreLeastValues,
+      })),
+    };
+  }
+
+  return { query };
+}
+
+/** Check if column should be omitted from the table */
+export function isColumnHidden(spec: { annotations?: Annotation }): boolean {
+  return readAnnotation(spec, Annotation.Table.Visibility) === "hidden";
+}
+
+/** Check if column is hidden by default */
+export function isColumnOptional(spec: { annotations?: Annotation }): boolean {
+  return readAnnotation(spec, Annotation.Table.Visibility) === "optional";
+}
+
+/**
+ * Create p-table spec and handle given ui table state
+ *
+ * @param ctx context
+ * @param columns column list
+ * @param tableState table ui state
+ * @returns PlAgDataTableV2 table source
+ */
+export function createPlDataTableV2<A, U>(
+  ctx: RenderCtxBase<A, U>,
+  columns: PColumn<PColumnDataUniversal>[],
+  tableState: PlDataTableStateV2 | undefined,
+  ops?: CreatePlDataTableOps,
+): PlDataTableModel | undefined {
+  if (columns.length === 0) return undefined;
+
+  const tableStateNormalized = upgradePlDataTableStateV2(tableState);
+
+  const allLabelColumns = getAllLabelColumns(ctx.resultPool);
+  if (!allLabelColumns) return undefined;
+
+  let fullLabelColumns = getMatchingLabelColumns(columns.map(getColumnIdAndSpec), allLabelColumns);
+  fullLabelColumns = deriveLabels(fullLabelColumns, identity, { includeNativeLabel: true }).map(
+    (v) => {
+      return {
+        ...v.value,
+        spec: {
+          ...v.value.spec,
+          annotations: {
+            ...v.value.spec.annotations,
+            [Annotation.Label]: v.label,
+          },
+        },
+      };
+    },
+  );
+
+  const fullColumns = [...columns, ...fullLabelColumns];
+
+  const fullColumnsAxes = uniqueBy(
+    fullColumns.flatMap((c) => c.spec.axesSpec.map((a) => getAxisId(a))),
+    (a) => canonicalizeJson<AxisId>(a),
+  );
+  const fullColumnsIds: PTableColumnId[] = [
+    ...fullColumnsAxes.map((a) => ({ type: "axis", id: a }) satisfies PTableColumnIdAxis),
+    ...fullColumns.map((c) => ({ type: "column", id: c.id }) satisfies PTableColumnIdColumn),
+  ];
+  const fullColumnsIdsSet = new Set(fullColumnsIds.map((c) => canonicalizeJson<PTableColumnId>(c)));
+  const isValidColumnId = (id: PTableColumnId): boolean =>
+    fullColumnsIdsSet.has(canonicalizeJson<PTableColumnId>(id));
+
+  const coreJoinType = ops?.coreJoinType ?? "full";
+  const filters = tableStateNormalized.pTableParams.filters;
+  const sorting: PTableSorting[] = uniqueBy(
+    [...tableStateNormalized.pTableParams.sorting, ...(ops?.sorting ?? [])],
+    (s) => canonicalizeJson<PTableColumnId>(s.column),
+  ).filter((s) => {
+    const valid = isValidColumnId(s.column);
+    if (!valid)
+      ctx.logWarn(`Sorting ${JSON.stringify(s)} does not match provided columns, skipping`);
+    return valid;
+  });
+
+  const fullDef = createPTableDef({
+    columns,
+    labelColumns: fullLabelColumns,
+    coreJoinType,
+    filters,
+    sorting,
+    coreColumnPredicate: ops?.coreColumnPredicate,
+  });
+  const fullHandle = ctx.createPTableV2(fullDef);
+  if (!fullHandle) return undefined;
+
+  const hiddenColumns = new Set<PObjectId>(
+    ((): PObjectId[] => {
+      // Inner join works as a filter - all columns must be present
+      if (coreJoinType === "inner") return [];
+
+      const hiddenColIds = tableStateNormalized.pTableParams.hiddenColIds;
+      if (hiddenColIds) return hiddenColIds;
+
+      return columns.filter((c) => isColumnOptional(c.spec)).map((c) => c.id);
+    })(),
+  );
+
+  // Preserve linker columns
+  columns.filter((c) => isLinkerColumn(c.spec)).forEach((c) => hiddenColumns.delete(c.id));
+
+  // Preserve core columns as they change the shape of join.
+  const coreColumnPredicate = ops?.coreColumnPredicate;
+  if (coreColumnPredicate) {
+    const coreColumns = columns.flatMap((c) =>
+      coreColumnPredicate(getColumnIdAndSpec(c)) ? [c.id] : [],
+    );
+    coreColumns.forEach((c) => hiddenColumns.delete(c));
+  }
+
+  // Sorting changes the order of result rows — preserve sorted columns from being hidden
+  sorting
+    .map((s) => s.column)
+    .filter((c): c is PTableColumnIdColumn => c.type === "column")
+    .forEach((c) => hiddenColumns.delete(c.id));
+
+  const visibleColumns = columns.filter((c) => !hiddenColumns.has(c.id));
+  const visibleLabelColumns = getMatchingLabelColumns(
+    visibleColumns.map(getColumnIdAndSpec),
+    allLabelColumns,
+  );
+
+  // if at least one column is not yet computed, we can't show the table
+  if (!allPColumnsReady([...visibleColumns, ...visibleLabelColumns])) return undefined;
+
+  const visibleDef = createPTableDef({
+    columns: visibleColumns,
+    labelColumns: visibleLabelColumns,
+    coreJoinType,
+    filters,
+    sorting,
+    coreColumnPredicate,
+  });
+  const visibleHandle = ctx.createPTableV2(visibleDef);
+  if (!visibleHandle) return undefined;
+
+  return {
+    sourceId: tableStateNormalized.pTableParams.sourceId,
+    fullTableHandle: fullHandle,
+    visibleTableHandle: visibleHandle,
+  } satisfies PlDataTableModel;
+}
+
+/** Create sheet entries for PlDataTable */
+export function createPlDataTableSheet<A, U>(
+  ctx: RenderCtxBase<A, U>,
+  axis: AxisSpec,
+  values: (string | number)[],
+): PlDataTableSheet {
+  const labels = ctx.resultPool.findLabels(axis);
+  return {
+    axis,
+    options: values.map((v) => ({
+      value: v,
+      label: labels?.[v] ?? v.toString(),
+    })),
+    defaultValue: values[0],
+  };
+}

package/src/components/PlDataTable/v4.ts

@@ -0,0 +1,193 @@
+import type { PTableColumnId } from "@milaboratories/pl-model-common";
+
+export type PlDataTableFilterState = {
+  id: PTableColumnId;
+  alphabetic: boolean;
+  filter: null | {
+    value: PlTableFilter;
+    disabled: boolean;
+  };
+};
+
+/** PlTableFilters filter entry */
+export type PlTableFilterIsNotNA = {
+  /** Predicate type */
+  type: "isNotNA";
+};
+
+/** PlTableFilters filter entry */
+export type PlTableFilterIsNA = {
+  /** Predicate type */
+  type: "isNA";
+};
+
+/** PlTableFilters filter entries applicable to both string and number values */
+export type PlTableFilterCommon = PlTableFilterIsNotNA | PlTableFilterIsNA;
+
+/** PlTableFilters numeric filter entry */
+export type PlTableFilterNumberEquals = {
+  /** Predicate type */
+  type: "number_equals";
+  /** Reference value */
+  reference: number;
+};
+
+/** PlTableFilters numeric filter entry */
+export type PlTableFilterNumberNotEquals = {
+  /** Predicate type */
+  type: "number_notEquals";
+  /** Reference value */
+  reference: number;
+};
+
+/** PlTableFilters numeric filter entry */
+export type PlTableFilterNumberGreaterThan = {
+  /** Predicate type */
+  type: "number_greaterThan";
+  /** Reference value */
+  reference: number;
+};
+
+/** PlTableFilters numeric filter entry */
+export type PlTableFilterNumberGreaterThanOrEqualTo = {
+  /** Predicate type */
+  type: "number_greaterThanOrEqualTo";
+  /** Reference value */
+  reference: number;
+};
+
+/** PlTableFilters numeric filter entry */
+export type PlTableFilterNumberLessThan = {
+  /** Predicate type */
+  type: "number_lessThan";
+  /** Reference value */
+  reference: number;
+};
+
+/** PlTableFilters numeric filter entry */
+export type PlTableFilterNumberLessThanOrEqualTo = {
+  /** Predicate type */
+  type: "number_lessThanOrEqualTo";
+  /** Reference value */
+  reference: number;
+};
+
+/** PlTableFilters numeric filter entry */
+export type PlTableFilterNumberBetween = {
+  /** Predicate type */
+  type: "number_between";
+  /** Reference value for the lower bound */
+  lowerBound: number;
+  /** Defines whether values equal to lower bound reference value should be matched */
+  includeLowerBound: boolean;
+  /** Reference value for the upper bound */
+  upperBound: number;
+  /** Defines whether values equal to upper bound reference value should be matched */
+  includeUpperBound: boolean;
+};
+
+/** All PlTableFilters numeric filter entries */
+export type PlTableFilterNumber =
+  | PlTableFilterCommon
+  | PlTableFilterNumberEquals
+  | PlTableFilterNumberNotEquals
+  | PlTableFilterNumberGreaterThan
+  | PlTableFilterNumberGreaterThanOrEqualTo
+  | PlTableFilterNumberLessThan
+  | PlTableFilterNumberLessThanOrEqualTo
+  | PlTableFilterNumberBetween;
+/** All types of PlTableFilters numeric filter entries */
+export type PlTableFilterNumberType = PlTableFilterNumber["type"];
+
+/** PlTableFilters string filter entry */
+export type PlTableFilterStringEquals = {
+  /** Predicate type */
+  type: "string_equals";
+  /** Reference value */
+  reference: string;
+};
+
+/** PlTableFilters string filter entry */
+export type PlTableFilterStringNotEquals = {
+  /** Predicate type */
+  type: "string_notEquals";
+  /** Reference value */
+  reference: string;
+};
+
+/** PlTableFilters string filter entry */
+export type PlTableFilterStringContains = {
+  /** Predicate type */
+  type: "string_contains";
+  /** Reference value */
+  reference: string;
+};
+
+/** PlTableFilters string filter entry */
+export type PlTableFilterStringDoesNotContain = {
+  /** Predicate type */
+  type: "string_doesNotContain";
+  /** Reference value */
+  reference: string;
+};
+
+/** PlTableFilters string filter entry */
+export type PlTableFilterStringMatches = {
+  /** Predicate type */
+  type: "string_matches";
+  /** Reference value */
+  reference: string;
+};
+
+/** PlTableFilters string filter entry */
+export type PlTableFilterStringDoesNotMatch = {
+  /** Predicate type */
+  type: "string_doesNotMatch";
+  /** Reference value */
+  reference: string;
+};
+
+/** PlTableFilters string filter entry */
+export type PlTableFilterStringContainsFuzzyMatch = {
+  /** Predicate type */
+  type: "string_containsFuzzyMatch";
+  /** Reference value */
+  reference: string;
+  /**
+   * Maximum acceptable edit distance between reference value and matched substring
+   * @see https://en.wikipedia.org/wiki/Edit_distance
+   */
+  maxEdits: number;
+  /**
+   * When {@link substitutionsOnly} is set to false
+   * Levenshtein distance is used as edit distance (substitutions and indels)
+   * @see https://en.wikipedia.org/wiki/Levenshtein_distance
+   * When {@link substitutionsOnly} is set to true
+   * Hamming distance is used as edit distance (substitutions only)
+   * @see https://en.wikipedia.org/wiki/Hamming_distance
+   */
+  substitutionsOnly: boolean;
+  /**
+   * Single character in {@link reference} that will labelColumn any
+   * single character in searched text.
+   */
+  wildcard?: string;
+};
+
+/** All PlTableFilters string filter entries */
+export type PlTableFilterString =
+  | PlTableFilterCommon
+  | PlTableFilterStringEquals
+  | PlTableFilterStringNotEquals
+  | PlTableFilterStringContains
+  | PlTableFilterStringDoesNotContain
+  | PlTableFilterStringMatches
+  | PlTableFilterStringDoesNotMatch
+  | PlTableFilterStringContainsFuzzyMatch;
+/** All types of PlTableFilters string filter entries */
+export type PlTableFilterStringType = PlTableFilterString["type"];
+
+/** All PlTableFilters filter entries */
+export type PlTableFilter = PlTableFilterNumber | PlTableFilterString;
+/** All types of PlTableFilters filter entries */
+export type PlTableFilterType = PlTableFilter["type"];

package/src/components/PlDataTable/v5.ts

@@ -0,0 +1,140 @@
+import type {
+  AxisId,
+  AxisSpec,
+  CanonicalizedJson,
+  ListOptionBase,
+  PObjectId,
+  PTableColumnSpec,
+  PTableFilters,
+  PTableRecordFilter,
+  PTableSorting,
+  PColumnIdAndSpec,
+  PTableHandle,
+} from "@milaboratories/pl-model-common";
+import type { FilterSpec, FilterSpecLeaf } from "../../filters";
+
+export type PlTableColumnId = {
+  /** Original column spec */
+  source: PTableColumnSpec;
+  /** Column spec with labeled axes replaced by label columns */
+  labeled: PTableColumnSpec;
+};
+
+export type PlTableColumnIdJson = CanonicalizedJson<PlTableColumnId>;
+
+export type PlDataTableGridStateCore = {
+  /** Includes column ordering */
+  columnOrder?: {
+    /** All colIds in order */
+    orderedColIds: PlTableColumnIdJson[];
+  };
+  /** Includes current sort columns and direction */
+  sort?: {
+    /** Sorted columns and directions in order */
+    sortModel: {
+      /** Column Id to apply the sort to. */
+      colId: PlTableColumnIdJson;
+      /** Sort direction */
+      sort: "asc" | "desc";
+    }[];
+  };
+  /** Includes column visibility */
+  columnVisibility?: {
+    /** All colIds which were hidden */
+    hiddenColIds: PlTableColumnIdJson[];
+  };
+};
+
+export type PlDataTableSheet = {
+  /** spec of the axis to use */
+  axis: AxisSpec;
+  /** options to show in the filter dropdown */
+  options: ListOptionBase<string | number>[];
+  /** default (selected) value */
+  defaultValue?: string | number;
+};
+
+export type PlDataTableSheetState = {
+  /** id of the axis */
+  axisId: AxisId;
+  /** selected value */
+  value: string | number;
+};
+
+/** Tree-based filter state compatible with PlAdvancedFilter's RootFilter */
+export type PlDataTableAdvancedFilter = FilterSpec<
+  FilterSpecLeaf<string>,
+  { id: number; isExpanded?: boolean }
+>;
+
+export type PlDataTableStateV2CacheEntry = {
+  /** DataSource identifier for state management */
+  sourceId: string;
+  /** Internal ag-grid state */
+  gridState: PlDataTableGridStateCore;
+  /** Sheets state */
+  sheetsState: PlDataTableSheetState[];
+  /** Filters state (tree-based, compatible with PlAdvancedFilter) */
+  filtersState: PlDataTableAdvancedFilter | null;
+};
+
+export type PTableParamsV2 =
+  | {
+      sourceId: null;
+      hiddenColIds: null;
+      filters: null;
+      sorting: [];
+    }
+  | {
+      sourceId: string;
+      hiddenColIds: PObjectId[] | null;
+      filters: PTableFilters;
+      sorting: PTableSorting[];
+    };
+
+export type PlDataTableStateV2Normalized = {
+  /** Version for upgrades */
+  version: 5;
+  /** Internal states, LRU cache for 5 sourceId-s */
+  stateCache: PlDataTableStateV2CacheEntry[];
+  /** PTable params derived from the cache state for the current sourceId */
+  pTableParams: PTableParamsV2;
+};
+
+/** PlAgDataTable model */
+export type PlDataTableModel = {
+  /** DataSource identifier for state management */
+  sourceId: string | null;
+  /** p-table including all columns, used to show the full specification of the table */
+  fullTableHandle: PTableHandle;
+  /** p-table including only visible columns, used to get the data */
+  visibleTableHandle: PTableHandle;
+};
+
+export type CreatePlDataTableOps = {
+  /** Filters for columns and non-partitioned axes */
+  filters?: PTableRecordFilter[];
+
+  /** Sorting to columns hidden from user */
+  sorting?: PTableSorting[];
+
+  /**
+   * Selects columns for which will be inner-joined to the table.
+   *
+   * Default behaviour: all columns are considered to be core
+   */
+  coreColumnPredicate?: (spec: PColumnIdAndSpec) => boolean;
+
+  /**
+   * Determines how core columns should be joined together:
+   *   inner - so user will only see records present in all core columns
+   *   full - so user will only see records present in any of the core columns
+   *
+   * All non-core columns will be left joined to the table produced by the core
+   * columns, in other words records form the pool of non-core columns will only
+   * make their way into the final table if core table contains corresponding key.
+   *
+   * Default: 'full'
+   */
+  coreJoinType?: "inner" | "full";
+};