@milaboratories/uikit 2.16.3 → 2.17.1

package/src/components/PlDropdownMulti/PlDropdownMulti.vue

@@ -19,6 +19,8 @@ import {
   watchPostEffect,
 } from "vue";
 import SvgRequired from "../../assets/images/required.svg?raw";
+import { missingValueText, missingValueTooltip, pickedValueText } from "../../helpers/columnValue";
+import type { MissingValueLabel, MissingValueTooltip } from "../../helpers/columnValue";
 import { getErrorMessage } from "../../helpers/error.ts";
 import { deepEqual, deepIncludes } from "../../helpers/objects";
 import { normalizeListOptions } from "../../helpers/utils";
@@ -69,9 +71,16 @@ const props = withDefaults(
     placeholder?: string;
     /**
      * Text shown in a chip when a `modelValue` entry is missing from `options` —
-     * e.g. its upstream source was deleted. Rendered italic in error color.
+     * e.g. its upstream source was deleted. Rendered italic in error color. One text for every
+     * such value, or a function giving it per value. By default, the value a column value id
+     * picks, marked as not available, or "Value not available".
      */
-    missingValueLabel?: string;
+    missingValueLabel?: MissingValueLabel;
+    /**
+     * Explains a selected value missing from the options in a tooltip over it: one text for every
+     * such value, or a function giving the content per value.
+     */
+    missingValueTooltip?: MissingValueTooltip;
     /**
      * If `true`, the dropdown component is marked as required.
      */
@@ -100,7 +109,8 @@ const props = withDefaults(
     helper: undefined,
     error: undefined,
     placeholder: "...",
-    missingValueLabel: "Value not available",
+    missingValueLabel: undefined,
+    missingValueTooltip: undefined,
     required: false,
     disabled: false,
     options: undefined,
@@ -134,7 +144,8 @@ const normalizedOptionsRef = computed(() => normalizeListOptions(props.options ?
 
 const selectedOptionsRef = computed(() => {
   // While options load (`options === undefined`), hide chips for unresolved values
-  // to avoid a "missing" flash that resolves once options arrive.
+  // to avoid a "missing" flash that resolves once options arrive. A picked column value
+  // is shown by its own label meanwhile.
   const optionsLoaded = props.options !== undefined;
   return selectedValuesRef.value
     .map((v) => {
@@ -143,16 +154,20 @@ const selectedOptionsRef = computed(() => {
         // Found: render the option's own (normalized) label verbatim — matches
         // PlDropdown. `opt.label` is always a string (possibly ""), never an object,
         // so there is no raw-value leak to guard against.
-        return { ...opt, isMissing: false };
+        return { ...opt, isMissing: false, hint: undefined };
       }
       if (!optionsLoaded) {
-        return undefined;
+        const label = pickedValueText(v);
+        return label === undefined
+          ? undefined
+          : { value: v, label, isMissing: false, hint: undefined };
       }
       // Honor empty `missingValueLabel` verbatim — caller's explicit "render nothing".
       return {
         value: v,
-        label: props.missingValueLabel,
+        label: missingValueText(v, props.missingValueLabel),
         isMissing: true,
+        hint: missingValueTooltip(v, props.missingValueTooltip),
       };
     })
     .filter((v): v is NonNullable<typeof v> => v !== undefined);
@@ -327,7 +342,20 @@ watchPostEffect(() => {
               @click.stop="data.open = true"
               @close="unselectOption(opt.value)"
             >
-              {{ opt.label }}
+              <!-- The hover stops here: the tooltip of the chip itself would close this one. -->
+              <PlTooltip
+                v-if="opt.hint !== undefined"
+                element="span"
+                position="top"
+                data-testid="pl-dropdown-multi-chip-hint"
+                @mouseover.stop
+              >
+                <span>{{ opt.label }}</span>
+                <template #tooltip>
+                  <component :is="opt.hint" />
+                </template>
+              </PlTooltip>
+              <template v-else>{{ opt.label }}</template>
             </PlChip>
           </div>
 
@@ -384,7 +412,20 @@ watchPostEffect(() => {
               small
               @close="unselectOption(opt.value)"
             >
-              {{ opt.label }}
+              <!-- The hover stops here: the tooltip of the chip itself would close this one. -->
+              <PlTooltip
+                v-if="opt.hint !== undefined"
+                element="span"
+                position="top"
+                data-testid="pl-dropdown-multi-chip-hint"
+                @mouseover.stop
+              >
+                <span>{{ opt.label }}</span>
+                <template #tooltip>
+                  <component :is="opt.hint" />
+                </template>
+              </PlTooltip>
+              <template v-else>{{ opt.label }}</template>
             </PlChip>
           </div>
           <DropdownListItem

package/src/components/PlDropdownMulti/__tests__/PlDropdownMulti.spec.ts

@@ -1,6 +1,8 @@
 import { describe, it, expect } from "vitest";
 
 import { mount, flushPromises } from "@vue/test-utils";
+import { createColumnValueId, createGlobalPObjectId } from "@platforma-sdk/model";
+import type { MissingValueTooltip } from "../../../helpers/columnValue";
 import PlDropdownMulti from "../PlDropdownMulti.vue";
 
 describe("PlDropdownMulti", () => {
@@ -167,4 +169,49 @@ describe("PlDropdownMulti", () => {
     expect(wrapper.findAll(".pl-dropdown-multi__chip--missing").length).toBe(0);
     expect(wrapper.findAll(".pl-chip").length).toBe(1);
   });
+
+  describe("with column value ids", () => {
+    const valueOf = (value: string) =>
+      createColumnValueId({
+        column: createGlobalPObjectId("samples", "metadata.antigen"),
+        value,
+      });
+    const bsa = valueOf("BSA");
+    const plastic = valueOf("Plastic");
+
+    it("shows picked values while options are loading", async () => {
+      const wrapper = mount(PlDropdownMulti, {
+        props: { modelValue: [bsa, plastic], options: undefined },
+      });
+      await flushPromises();
+      expect(wrapper.findAll(".pl-chip").map((chip) => chip.text())).toEqual(["BSA", "Plastic"]);
+      expect(wrapper.findAll(".pl-dropdown-multi__chip--missing").length).toBe(0);
+    });
+
+    it("marks each picked value the options lack as not available", async () => {
+      const wrapper = mount(PlDropdownMulti, {
+        props: { modelValue: [bsa, plastic], options: [{ label: "BSA", value: bsa }] },
+      });
+      await flushPromises();
+      const missingChips = wrapper.findAll(".pl-dropdown-multi__chip--missing");
+      expect(missingChips.map((chip) => chip.text())).toEqual(["Plastic — not available"]);
+    });
+
+    it("explains each missing value by the hint of the app", async () => {
+      const hint: MissingValueTooltip = (value) =>
+        value === plastic ? () => "Samples has no Plastic" : undefined;
+      const wrapper = mount(PlDropdownMulti, {
+        props: { modelValue: [bsa, plastic], options: [], missingValueTooltip: hint },
+        attachTo: document.body,
+      });
+      await flushPromises();
+      const hinted = wrapper.findAll("[data-testid='pl-dropdown-multi-chip-hint']");
+      expect(hinted.map((chip) => chip.text())).toEqual(["Plastic — not available"]);
+
+      await hinted[0].trigger("mouseover");
+      await new Promise((resolve) => setTimeout(resolve, 200));
+      expect(document.body.textContent).toContain("Samples has no Plastic");
+      wrapper.unmount();
+    });
+  });
 });

package/src/components/PlDropdownMultiRef/PlDropdownMultiRef.vue

@@ -1,4 +1,5 @@
 <script lang="ts" setup>
+import type { MissingValueLabel, MissingValueTooltip } from "../../helpers/columnValue";
 import type { ModelRef, RefOption } from "../../types";
 import PlDropdownMulti from "../PlDropdownMulti/PlDropdownMulti.vue";
 import { computed, useSlots } from "vue";
@@ -41,9 +42,14 @@ const props = withDefaults(
     placeholder?: string;
     /**
      * Text shown in a chip when a `modelValue` entry's upstream block no longer
-     * exists. Defaults to "Upstream value removed".
+     * exists: one text, or a function giving it per value. Defaults to "Value not available".
      */
-    missingValueLabel?: string;
+    missingValueLabel?: MissingValueLabel;
+    /**
+     * Explains a selected value missing from the options in a tooltip over it: one text for every
+     * such value, or a function giving the content per value.
+     */
+    missingValueTooltip?: MissingValueTooltip;
     /**
      * If `true`, the dropdown component is marked as required.
      */
@@ -59,7 +65,8 @@ const props = withDefaults(
     helper: undefined,
     error: undefined,
     placeholder: "...",
-    missingValueLabel: "Upstream value removed",
+    missingValueLabel: undefined,
+    missingValueTooltip: undefined,
     required: false,
     disabled: false,
     options: undefined,

package/src/components/PlDropdownMultiRef/__tests__/PlDropdownMultiRef.spec.ts

@@ -84,10 +84,10 @@ describe("PlDropdownMultiRef", () => {
 
     const missing = wrapper.findAll(".pl-dropdown-multi__chip--missing");
     expect(missing.length).toBe(1);
-    expect(missing[0].text()).toContain("Upstream value removed");
+    expect(missing[0].text()).toContain("Value not available");
   });
 
-  it("forwards a caller-supplied missingValueLabel that overrides the Ref default", async () => {
+  it("forwards a caller-supplied missingValueLabel that overrides the default", async () => {
     const wrapper = mount(PlDropdownMultiRef, {
       props: {
         modelValue: [{ __isRef: true as const, blockId: "deleted", name: "Ref to deleted block" }],

package/src/components/PlDropdownRef/PlDropdownRef.vue

@@ -9,6 +9,7 @@ export default {
 
 <script lang="ts" setup generic="M = ModelRef">
 import { computed, useSlots } from "vue";
+import type { MissingValueLabel, MissingValueTooltip } from "../../helpers/columnValue";
 import type { ListOption, ModelRef, RefOption } from "../../types";
 import { PlDropdown } from "../PlDropdown";
 
@@ -54,9 +55,14 @@ const props = withDefaults(
     placeholder?: string;
     /**
      * Text shown in the field when the referenced upstream block / output no longer
-     * exists. Defaults to "Upstream value removed".
+     * exists: one text, or a function giving it per value. Defaults to "Value not available".
      */
-    missingValueLabel?: string;
+    missingValueLabel?: MissingValueLabel;
+    /**
+     * Explains a selected value missing from the options in a tooltip over it: one text for every
+     * such value, or a function giving the content per value.
+     */
+    missingValueTooltip?: MissingValueTooltip;
     /**
      * Enables a button to clear the selected value (default: false)
      */
@@ -80,7 +86,8 @@ const props = withDefaults(
     loadingOptionsHelper: undefined,
     error: undefined,
     placeholder: "...",
-    missingValueLabel: "Upstream value removed",
+    missingValueLabel: undefined,
+    missingValueTooltip: undefined,
     clearable: false,
     required: false,
     disabled: false,

package/src/components/PlDropdownRef/__tests__/PlDropdownRef.spec.ts

@@ -77,10 +77,10 @@ describe("PlDropdownRef", () => {
 
     const missing = wrapper.find(".input-value--missing");
     expect(missing.exists()).toBe(true);
-    expect(missing.text()).toBe("Upstream value removed");
+    expect(missing.text()).toBe("Value not available");
   });
 
-  it("forwards a caller-supplied missingValueLabel that overrides the Ref default", async () => {
+  it("forwards a caller-supplied missingValueLabel that overrides the default", async () => {
     const wrapper = mount(PlDropdownRef, {
       props: {
         modelValue: {

package/src/components/PlTooltip/PlTooltip.vue

@@ -249,6 +249,7 @@ const anchorName = `--anchor-${uniqueId()}`;
 }
 
 .plTooltipContent {
+  --txt-link: var(--tooltip-link-color);
   display: inline-block;
   padding: 8px 12px 9px 12px;
   background: var(--tooltip-bg);

package/src/components/PlValueLabel/PlValueLabel.vue

@@ -0,0 +1,80 @@
+<script lang="ts">
+/**
+ * A selected value shown as text, the way a dropdown shows it: by the label of its option, or,
+ * for a column value id, by the value it picks. A value the options lack is marked as not
+ * available, in error color, with the reason in a tooltip when there is a hint for it.
+ */
+export default {
+  name: "PlValueLabel",
+};
+</script>
+
+<script lang="ts" setup generic="M = unknown">
+import { computed } from "vue";
+import { missingValueText, missingValueTooltip, pickedValueText } from "../../helpers/columnValue";
+import type { MissingValueLabel, MissingValueTooltip } from "../../helpers/columnValue";
+import { deepEqual } from "../../helpers/objects";
+import { normalizeListOptions } from "../../helpers/utils";
+import type { ListOption } from "../../types";
+import { PlTooltip } from "../PlTooltip";
+
+const props = defineProps<{
+  /** The value to show. */
+  value: M;
+  /**
+   * Options the value is picked from. While they are `undefined` — not loaded yet — the value
+   * is never marked as not available.
+   */
+  options?: Readonly<ListOption<M>[]>;
+  /**
+   * Text shown when the options lack the value: one text, or a function giving it per value. By
+   * default, the value a column value id picks, marked as not available, or "Value not
+   * available".
+   */
+  missingValueLabel?: MissingValueLabel;
+  /**
+   * Explains the value in a tooltip over it while the options lack it: one text, or a function
+   * giving the content per value.
+   */
+  missingValueTooltip?: MissingValueTooltip;
+}>();
+
+const option = computed(() =>
+  props.options === undefined
+    ? undefined
+    : normalizeListOptions(props.options).find((o) => deepEqual(o.value, props.value)),
+);
+
+const isMissing = computed(() => props.options !== undefined && option.value === undefined);
+
+const hint = computed(() =>
+  isMissing.value ? missingValueTooltip(props.value, props.missingValueTooltip) : undefined,
+);
+
+const text = computed(() => {
+  if (option.value !== undefined) return option.value.label;
+  if (isMissing.value) {
+    return missingValueText(props.value, props.missingValueLabel);
+  }
+  return pickedValueText(props.value) ?? String(props.value);
+});
+</script>
+
+<template>
+  <PlTooltip v-if="hint !== undefined" element="span" position="top">
+    <span :class="$style.missing" data-testid="pl-value-label">{{ text }}</span>
+    <template #tooltip>
+      <component :is="hint" />
+    </template>
+  </PlTooltip>
+  <span v-else :class="{ [$style.missing]: isMissing }" data-testid="pl-value-label">{{
+    text
+  }}</span>
+</template>
+
+<style module>
+.missing {
+  font-style: italic;
+  color: var(--txt-error);
+}
+</style>

package/src/components/PlValueLabel/__tests__/PlValueLabel.spec.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect } from "vitest";
+
+import { flushPromises, mount } from "@vue/test-utils";
+import { createColumnValueId, createGlobalPObjectId } from "@platforma-sdk/model";
+import type { MissingValueTooltip } from "../../../helpers/columnValue";
+import PlValueLabel from "../PlValueLabel.vue";
+
+const treated = createColumnValueId({
+  column: createGlobalPObjectId("samples", "metadata.condition"),
+  value: "treated",
+});
+
+const isMarkedMissing = (wrapper: ReturnType<typeof mount>) =>
+  wrapper.find("[data-testid='pl-value-label']").classes().length > 0;
+
+describe("PlValueLabel", () => {
+  it("shows the label of the value's option", () => {
+    const wrapper = mount(PlValueLabel, {
+      props: { value: treated, options: [{ label: "Treated", value: treated }] },
+    });
+    expect(wrapper.text()).toBe("Treated");
+    expect(isMarkedMissing(wrapper)).toBe(false);
+  });
+
+  it("shows the value a column value id picks while options are not loaded", () => {
+    const wrapper = mount(PlValueLabel, { props: { value: treated } });
+    expect(wrapper.text()).toBe("treated");
+    expect(isMarkedMissing(wrapper)).toBe(false);
+  });
+
+  it("marks a value the options lack as not available", () => {
+    const wrapper = mount(PlValueLabel, { props: { value: treated, options: [] } });
+    expect(wrapper.text()).toBe("treated — not available");
+    expect(isMarkedMissing(wrapper)).toBe(true);
+  });
+
+  it("keeps the caller's missingValueLabel", () => {
+    const wrapper = mount(PlValueLabel, {
+      props: { value: treated, options: [], missingValueLabel: "Gone" },
+    });
+    expect(wrapper.text()).toBe("Gone");
+  });
+
+  it("explains a missing value by the hint of the app in a tooltip", async () => {
+    const hint: MissingValueTooltip = () => () => "Samples does not provide it";
+    const wrapper = mount(PlValueLabel, {
+      props: { value: treated, options: [], missingValueTooltip: hint },
+      attachTo: document.body,
+    });
+    expect(wrapper.text()).toBe("treated — not available");
+    expect(isMarkedMissing(wrapper)).toBe(true);
+
+    await wrapper.find("[data-testid='pl-value-label']").trigger("mouseover");
+    await new Promise((resolve) => setTimeout(resolve, 200));
+    await flushPromises();
+    expect(document.body.textContent).toContain("Samples does not provide it");
+    wrapper.unmount();
+  });
+
+  it("shows a plain value as is", () => {
+    const wrapper = mount(PlValueLabel, { props: { value: "R1" } });
+    expect(wrapper.text()).toBe("R1");
+  });
+});

package/src/components/PlValueLabel/index.ts

@@ -0,0 +1 @@
+export { default as PlValueLabel } from "./PlValueLabel.vue";

package/src/helpers/columnValue.ts

@@ -0,0 +1,43 @@
+import { columnValueLabel, isColumnValueId } from "@platforma-sdk/model";
+import type { FunctionalComponent } from "vue";
+
+/**
+ * Text shown in place of a selected value missing from its options: one for every such value,
+ * or one per value, `undefined` leaving the usual text.
+ */
+export type MissingValueLabel = string | ((value: unknown) => string | undefined);
+
+/**
+ * Tooltip over a selected value missing from its options: one text for every such value, or
+ * content per value, `undefined` when there is nothing to tell about it.
+ */
+export type MissingValueTooltip = string | ((value: unknown) => FunctionalComponent | undefined);
+
+/**
+ * The value a column value id picks, as text; `undefined` for any other value. A picked value
+ * keeps a readable label while the options that would carry it are not loaded or no longer
+ * hold it.
+ */
+export function pickedValueText(value: unknown): string | undefined {
+  return isColumnValueId(value) ? columnValueLabel(value) : undefined;
+}
+
+/**
+ * Text shown for a selected value missing from the options: the one `label` gives for it, else
+ * the picked value of a column value id marked as not available, else a generic one.
+ */
+export function missingValueText(value: unknown, label: MissingValueLabel | undefined): string {
+  const given = typeof label === "function" ? label(value) : label;
+  if (given !== undefined) return given;
+  const picked = pickedValueText(value);
+  return picked === undefined ? "Value not available" : `${picked} — not available`;
+}
+
+/** Content of the tooltip `tooltip` gives over a selected value missing from the options. */
+export function missingValueTooltip(
+  value: unknown,
+  tooltip: MissingValueTooltip | undefined,
+): FunctionalComponent | undefined {
+  if (typeof tooltip === "string") return () => tooltip;
+  return tooltip?.(value);
+}

package/src/index.ts

@@ -74,6 +74,8 @@ export * from "./components/PlTextField";
 export * from "./components/PlToggleSwitch";
 export * from "./components/PlTooltip";
 export * from "./components/PlColumnLabel";
+export * from "./components/PlValueLabel";
+export type { MissingValueLabel, MissingValueTooltip } from "./helpers/columnValue";
 
 export * from "./components/PlFileDialog";
 export * from "./components/PlFileInput";