ggaction 0.0.23 → 0.0.26

package/src/materialization/selection/items/bar.js

@@ -19,6 +19,7 @@ import { deriveHistogramSegments } from "../../bars/histogram.js";
 import {
   channelMapFromRow,
   finalizeItems,
+  reorderHighlightedItems,
   itemKey,
   ownFields,
   uniqueFields
@@ -203,7 +204,7 @@ function barStackDefinitions(layer, barGrain, definitions) {
   });
 }
 
-export function resolveBarItems(program, layer, dataset, selectionGrain) {
+export function resolveBarItemDefinitions(program, layer, dataset) {
   const grain = resolveBarGrain(layer);
   const definitions = grain === BAR_GRAINS.histogram
     ? histogramDefinitions(program, layer, dataset)
@@ -215,15 +216,32 @@ export function resolveBarItems(program, layer, dataset, selectionGrain) {
   if (definitions === undefined) {
     throw new Error(`Bar mark "${layer.id}" is incomplete for selection.`);
   }
+  return definitions;
+}
+
+export function resolveBarItems(program, layer, dataset, selectionGrain) {
+  const grain = resolveBarGrain(layer);
+  const definitions = resolveBarItemDefinitions(program, layer, dataset).map((definition, index) => ({
+    ...definition, key: definition.key ?? itemKey(layer, grain, index)
+  }));
+  const needsStacks = selectionGrain === 'stack' || Object.values(program.materializationConfigs.highlights ?? {}).some(config =>
+    config.target === layer.id && program.materializationConfigs.selections?.[config.selection]?.selector.grain === 'stack');
+  const stacks = needsStacks ? barStackDefinitions(layer, grain, definitions) : undefined;
+  const ordered = reorderHighlightedItems(program, layer, definitions, { stack: stacks });
   const graphicTypes = hasRectRadius(program.markConfigs[layer.id]?.barAppearance) ? ["rect", "path"] : "rect";
   if (selectionGrain === "stack") {
     return finalizeItems(
       program,
       layer,
       "stack",
-      barStackDefinitions(layer, grain, definitions),
+      stacks.map(stack => ({ ...stack, graphicIndices: stack.graphicIndices.map(index => ordered.indexOf(definitions[index])) })),
       graphicTypes
     );
   }
-  return finalizeItems(program, layer, grain, definitions, graphicTypes);
+  return finalizeItems(program, layer, grain, ordered, graphicTypes, { reorder: false });
+}
+
+export function resolveBarSourceItems(program, layer, dataset, selectionGrain) {
+  const definitions = resolveBarItemDefinitions(program, layer, dataset);
+  return selectionGrain === 'stack' ? barStackDefinitions(layer, resolveBarGrain(layer), definitions) : definitions;
 }

package/src/materialization/selection/items/common.js

@@ -1,3 +1,4 @@
+import { memberRowReferences } from "../rows.js";
 import { normalizeTemporalValue } from "../../../grammar/scales/fields.js";
 import { cloneAndFreeze, isPlainObject } from "../../../core/immutable.js";
 import {
@@ -108,7 +109,7 @@ function collectionBounds(program, items) {
   return { x: left, y: top, width: right - left, height: bottom - top };
 }
 
-export function finalizeItems(program, layer, grain, definitions, graphicType) {
+export function finalizeItems(program, layer, grain, definitions, graphicType, { reorder = true } = {}) {
   const graphic = requireResolvedGraphic(program, layer, graphicType);
   const referenced = definitions.flatMap((definition, index) =>
     definition.graphicIndices ?? [index]
@@ -122,10 +123,14 @@ export function finalizeItems(program, layer, grain, definitions, graphicType) {
       `Mark "${layer.id}" item count does not match its materialized graphics.`
     );
   }
+  definitions = definitions.map((definition, index) => ({ ...definition, key: definition.key ?? itemKey(layer, grain, index) }));
+  if (reorder && definitions.every(definition => definition.graphicIndices === undefined)) {
+    definitions = reorderHighlightedItems(program, layer, definitions);
+  }
   return Object.freeze(definitions.map((definition, index) => {
     const indices = definition.graphicIndices ?? [index];
     const items = indices.map(childIndex => graphic.items[childIndex]);
-    const properties = definition.properties ?? (
+    const properties = definition.properties === undefined ? (
       items.length === 1
         ? selectableGraphicProperties({
             type: items[0].type ?? graphic.type,
@@ -135,7 +140,7 @@ export function finalizeItems(program, layer, grain, definitions, graphicType) {
             ...sharedConcreteProperties(items),
             ...collectionBounds(program, items)
           }
-    );
+    ) : { ...definition.properties, ...concreteProperties(items[0]?.properties) };
     return Object.freeze({
       key: definition.key ?? itemKey(layer, grain, index),
       layer: layer.id,
@@ -147,6 +152,7 @@ export function finalizeItems(program, layer, grain, definitions, graphicType) {
         ? {}
         : { geometry: cloneAndFreeze(definition.geometry) }),
       members: Object.freeze([...definition.members]),
+      rows: Object.freeze(memberRowReferences(program, definition.members)),
       graphicIds: Object.freeze(items.map((child, childOffset) =>
         child.id ?? graphicId(layer, indices[childOffset])
       ))
@@ -154,7 +160,7 @@ export function finalizeItems(program, layer, grain, definitions, graphicType) {
   }));
 }
 
-export function reorderHighlightedItems(program, layer, definitions) {
+export function reorderHighlightedItems(program, layer, definitions, groups = {}) {
   let ordered = definitions;
   for (const config of Object.values(
     program.materializationConfigs.highlights ?? {}
@@ -162,7 +168,14 @@ export function reorderHighlightedItems(program, layer, definitions) {
     if (config.target !== layer.id || config.bringToFront !== true) continue;
     const selection = program.materializationConfigs.selections?.[config.selection];
     if (selection?.target !== layer.id) continue;
-    const selected = new Set(selectMarkItemKeys(ordered, selection.selector));
+    const predicate = selection.selector;
+    const grouped = groups[predicate.grain];
+    const candidates = (grouped ?? ordered).map(item => ({ ...item, properties: item.properties ?? {}, ...(predicate.rows ? { rows: memberRowReferences(program, item.members) } : {}) }));
+    let selected = new Set(selectMarkItemKeys(candidates, predicate));
+    if (grouped) {
+      const members = new Set(grouped.filter(item => selected.has(item.key)).flatMap(item => item.members));
+      selected = new Set(ordered.filter(item => item.members.some(row => members.has(row))).map(item => item.key));
+    }
     ordered = [
       ...ordered.filter(definition => !selected.has(definition.key)),
       ...ordered.filter(definition => selected.has(definition.key))

package/src/materialization/selection/items/overlay.js

@@ -0,0 +1,15 @@
+import { resolveOverlaySeries, overlaySegments } from "../../overlayItems.js";
+import { finalizeItems, uniqueFields, channelMapFromRow } from "./common.js";
+
+export function resolveOverlayItems(program, layer) {
+  const binding = layer.derivedBindings.overlay;
+  const series = resolveOverlaySeries(program, binding);
+  const definitions = layer.mark.type === "point" ? series.flatMap(group => group.points)
+    : series.flatMap(group => overlaySegments(group, binding).map(points => {
+      const members = [...new Set(points.flatMap(point => point.members))];
+      const fields = uniqueFields(points.map(point => point.fields));
+      return { fields, channels: channelMapFromRow(fields, layer), members };
+    }));
+  return finalizeItems(program, layer, layer.mark.type === "point" ? "point" : "series", definitions,
+    layer.mark.type === "line" ? "path" : ["circle", "rect", "path"]);
+}

package/src/materialization/selection/items/path.js

@@ -62,6 +62,7 @@ export function resolveLineItems(program, layer, dataset) {
     {
       scales: program.semanticSpec.scales,
       xDomain: program.resolvedScales[x?.scale]?.domain,
+      yDomain: program.resolvedScales[layer.encoding.y?.scale]?.domain,
       ...(x?.bin === undefined ? {} : {
           xBinBoundaries: resolveLineBins(
             dataset.values,

package/src/materialization/selection/items/point.js

@@ -3,8 +3,7 @@ import {
   concreteProperties,
   finalizeItems,
   itemKey,
-  ownFields,
-  reorderHighlightedItems
+  ownFields
 } from "./common.js";
 
 export function resolvePointItems(program, layer, dataset) {
@@ -33,7 +32,7 @@ export function resolvePointItems(program, layer, dataset) {
     program,
     layer,
     "point",
-    reorderHighlightedItems(program, layer, definitions),
+    definitions,
     program.graphicSpec.objects[layer.id]?.type
   );
 }

package/src/materialization/selection/items/tick.js

@@ -3,8 +3,7 @@ import {
   concreteProperties,
   finalizeItems,
   itemKey,
-  ownFields,
-  reorderHighlightedItems
+  ownFields
 } from "./common.js";
 
 export function resolveTickItems(program, layer, dataset) {
@@ -15,20 +14,12 @@ export function resolveTickItems(program, layer, dataset) {
   if (!Array.isArray(graphic?.items) || !completePosition) {
     throw new Error(`Tick mark "${layer.id}" is incomplete for selection.`);
   }
-  let definitions = reorderHighlightedItems(
-    program,
-    layer,
-    dataset.values.map((row, index) => ({
+  const definitions = dataset.values.map((row, index) => ({
       key: itemKey(layer, "tick", index),
       fields: ownFields(row),
       channels: channelMapFromRow(row, layer),
       properties: concreteProperties(graphic.items[index]?.properties),
       members: [row]
-    }))
-  );
-  definitions = definitions.map((definition, index) => ({
-    ...definition,
-    properties: concreteProperties(graphic.items[index]?.properties)
-  }));
+    }));
   return finalizeItems(program, layer, "tick", definitions, "line");
 }

package/src/materialization/selection/path.js

@@ -17,9 +17,9 @@ export function transformPathHighlightProperties(properties, style) {
     ...(offset.x === 0 && offset.y === 0
       ? {}
       : {
-          commands: properties.commands.map(command =>
+          ...(properties.commands ? { commands: properties.commands.map(command =>
             translateCommand(command, offset)
-          )
+          ) } : { x: properties.x + offset.x, y: properties.y + offset.y })
         })
   };
 }

package/src/materialization/selection/policies/bar.js

@@ -1,9 +1,11 @@
+import { resolveBarSourceItems } from "../items/bar.js";
 import { resolveBarItems } from "../items/index.js";
 import { normalizeBarHighlightStyle } from "../styles.js";
 
 export const barSelectionPolicy = Object.freeze({
   supportedGrains: Object.freeze(["item", "stack"]),
   resolveItems: resolveBarItems,
+  resolveSourceItems: resolveBarSourceItems,
   normalizeHighlightStyle: normalizeBarHighlightStyle,
   applyHighlightOp: "applyBarHighlight",
   rematerializeOp: "rematerializeBarMark"

package/src/materialization/selection/policies/index.js

@@ -1,3 +1,6 @@
+import { rowsForSelectedItems, memberRowReferences } from "../rows.js";
+import { selectMarkItemKeys } from "../../../grammar/markSelection.js";
+import { textSelectionPolicy } from "./text.js";
 import { findDataset } from "../../../selectors/datasets.js";
 import { requireLayer } from "../../../selectors/layers.js";
 import { areaSelectionPolicy } from "./area.js";
@@ -9,8 +12,10 @@ import { ruleSelectionPolicy } from "./rule.js";
 import { tickSelectionPolicy } from "./tick.js";
 import { rectSelectionPolicy } from "./rect.js";
 import { applyItemMissingPolicy } from "../../../grammar/itemMissing.js";
+import { resolveOverlayItems } from "../items/overlay.js";
 
 const POLICIES = Object.freeze({
+  text: textSelectionPolicy,
   arc: arcSelectionPolicy,
   area: areaSelectionPolicy,
   bar: barSelectionPolicy,
@@ -34,7 +39,24 @@ export function requireSelectionPolicy(markType) {
 }
 
 export function resolveMarkItems(program, target, grain = "item") {
+  for (const config of Object.values(program.materializationConfigs.highlights ?? {})) {
+    const definition = program.materializationConfigs.selections?.[config.selection];
+    if (config.target !== target || !definition?.sourceSelection) continue;
+    const parent = program.materializationConfigs.selections[definition.sourceSelection];
+    if (!parent || parent.sourceSelection) throw new Error('Invalid composite selection owner.');
+    if (!definition.selector.rows) {
+      program = program._withSelectionConfig(config.selection, { ...definition, selector: parent.selector });
+      continue;
+    }
+    const parentItems = parent.selector.property ? resolveMarkItems(program, parent.target, parent.selector.grain) : resolveMarkSourceItems(program, parent.target, parent.selector.grain);
+    const rows = rowsForSelectedItems(program, parentItems, selectMarkItemKeys(parentItems, parent.selector), definition.selector.rows.data);
+    program = program._withSelectionConfig(config.selection, { ...definition, selector: { ...definition.selector, rows } });
+  }
   const layer = requireLayer(program, target, `Unknown mark target "${target}"`);
+  if (layer.derivedBindings?.overlay) {
+    if (grain !== "item") throw new Error(`Overlay "${target}" supports item selection grain.`);
+    return resolveOverlayItems(program, layer);
+  }
   const dataset = findDataset(program, layer.data);
   if (dataset === undefined) {
     throw new Error(`Mark "${target}" requires an existing dataset for selection.`);
@@ -43,5 +65,17 @@ export function resolveMarkItems(program, target, grain = "item") {
   if (!policy.supportedGrains.includes(grain)) {
     throw new Error(`Mark "${target}" does not support ${grain} selection grain.`);
   }
-  return policy.resolveItems(program, layer, applyItemMissingPolicy(layer, dataset), grain);
+  return policy.resolveItems(program, layer, applyItemMissingPolicy(layer, dataset), grain, resolveMarkItems);
+}
+
+// Composite source membership does not require the parent's graphics to have
+// finished rebuilding. Each owning policy supplies its same final semantic grain.
+export function resolveMarkSourceItems(program, target, grain = 'item') {
+  const layer = requireLayer(program, target), policy = requireSelectionPolicy(layer.mark.type);
+  if (!policy.resolveSourceItems) return resolveMarkItems(program, target, grain);
+  const dataset = applyItemMissingPolicy(layer, findDataset(program, layer.data));
+  return policy.resolveSourceItems(program, layer, dataset, grain).map((item,index) => ({
+    ...item, key: item.key ?? `${layer.id}/source/${index}`, properties: item.properties ?? {},
+    rows: memberRowReferences(program, item.members)
+  }));
 }

package/src/materialization/selection/policies/point.js

@@ -1,9 +1,11 @@
+import { ownFields, channelMapFromRow } from "../items/common.js";
 import { resolvePointItems } from "../items/index.js";
 import { normalizePointHighlightStyle } from "../styles.js";
 
 export const pointSelectionPolicy = Object.freeze({
   supportedGrains: Object.freeze(["item"]),
   resolveItems: resolvePointItems,
+  resolveSourceItems: (program, layer, dataset) => dataset.values.map(row => ({fields:ownFields(row),channels:channelMapFromRow(row,layer),members:[row]})),
   normalizeHighlightStyle: normalizePointHighlightStyle,
   applyHighlightOp: "applyPointHighlight",
   rematerializeOp: "rematerializePointMark"

package/src/materialization/selection/policies/text.js

@@ -0,0 +1,17 @@
+import { DEFAULT_TEXT_MARK } from '../../../grammar/text.js';
+import { resolveTextGraphicEntries } from '../../textGeometry.js';
+import { finalizeItems, itemKey } from '../items/common.js';
+import { normalizeTextHighlightStyle } from '../styles.js';
+
+export const textSelectionPolicy = Object.freeze({
+  supportedGrains: Object.freeze(['item']),
+  resolveItems(program, layer, dataset, grain, resolveMarkItems) {
+    const entries = resolveTextGraphicEntries(program, layer, program.markConfigs[layer.id] ?? DEFAULT_TEXT_MARK, { members: true, resolveMarkItems });
+    const definitions = entries.map((entry, i) => ({ key: itemKey(layer, 'text', i), fields: entry.fields,
+      channels: entry.channels, properties: {}, members: entry.members }));
+    return finalizeItems(program, layer, 'text', definitions, 'text');
+  },
+  normalizeHighlightStyle: normalizeTextHighlightStyle,
+  applyHighlightOp: 'applyPathHighlight',
+  rematerializeOp: 'rematerializeTextMark'
+});

package/src/materialization/selection/rows.js

@@ -0,0 +1,103 @@
+import { validateRowSelectionDataset } from "../../grammar/markSelection.js";
+import { findDataset } from "../../selectors/datasets.js";
+import { deriveBin2DRows } from "../../grammar/bin2d.js";
+import { deriveBoxData } from "../../grammar/boxPlot.js";
+import { deriveFilteredRows } from '../../grammar/filter.js';
+import { deriveSortedRows } from '../../grammar/sort.js';
+
+const cache = new WeakMap();
+
+// Provenance is an inspection cache, never an injected data column. Identical
+// observations retain distinct indices. Only explicit transform semantics are
+// used to traverse a derived dataset; unknown lineage is not guessed by value.
+function indexRows(program) {
+  const provenance = program.materializationConfigs.rowProvenance;
+  const cached = cache.get(program.semanticSpec.datasets);
+  if (cached && cached.provenance === provenance) return cached.byRow;
+  const datasets = new Map(program.semanticSpec.datasets.filter(d => Array.isArray(d.values)).map(d => [d.id, d]));
+  const references = new Map(), building = new Set();
+  function visit(id) {
+    if (references.has(id)) return references.get(id);
+    if (building.has(id)) throw new Error('Cyclic dataset lineage.');
+    building.add(id);
+    const d = datasets.get(id);
+    if (!d) throw new Error(`Unknown row dataset "${id}".`);
+    const result = d.values.map((_, index) => [{ data: id, index }]);
+    references.set(id, result);
+    if (d.source && datasets.has(d.source)) {
+      const source = datasets.get(d.source), parents = visit(d.source), t = d.transform?.length === 1 ? d.transform[0] : null;
+      let mapping;
+      if (t?.type === 'markFilter' && program.materializationConfigs.rowProvenance?.[id]) {
+        mapping = program.materializationConfigs.rowProvenance[id].indices.map(index => [index]);
+      } else if (t && ['filter', 'sort'].includes(t.type)) {
+        const derived = (t.type === 'filter' ? deriveFilteredRows : deriveSortedRows)(source.values, t);
+        const positions = new Map(source.values.map((row, i) => [row, i]));
+        mapping = derived.map(row => [positions.get(row)]);
+      } else if (t && ['computed', 'timeUnit', 'lookup', 'window', 'normalize'].includes(t.type) && d.values.length === source.values.length) {
+        mapping = d.values.map((_, i) => [i]);
+      } else if (t?.type === 'fold') {
+        mapping = d.values.map((_, i) => [Math.floor(i / t.fields.length)]);
+      } else if (t?.type === 'bin2d') {
+        const memberField = '__selection_members';
+        mapping = deriveBin2DRows(source.values, { ...t, members: true, as: { ...t.as, members: memberField } }).values.map(row => row[memberField]);
+      } else if (t?.type === 'boxOutlier') {
+        const summaries = deriveBoxData(source.values, { ...t, type: 'boxSummary' }).summaries;
+        const groups = new Map(summaries.map(row => [row[t.category], row]));
+        mapping = source.values.flatMap((row,i) => { const group = groups.get(row[t.category]); return group && (row[t.field] < group[t.as.lowerWhisker] || row[t.field] > group[t.as.upperWhisker]) ? [[i]] : []; });
+      } else if (t && ['ecdf', 'horizon', 'boxSummary', 'summary', 'interval', 'density', 'gradientProfile', 'regression', 'regressionStatistics'].includes(t.type)) {
+        const fields = [...new Set([...(Array.isArray(t.groupBy) ? t.groupBy : t.groupBy ? [t.groupBy] : []), ...(t.category ? [t.category] : [])])];
+        const groups = new Map();
+        source.values.forEach((row, i) => { const key = JSON.stringify(fields.map(f => row[f])); if (!groups.has(key)) groups.set(key, []); groups.get(key).push(i); });
+        mapping = d.values.map(row => groups.get(JSON.stringify(fields.map(f => row[f]))) ?? []);
+      }
+      if (mapping?.length === result.length) mapping.forEach((indices, i) => {
+        for (const index of indices) if (Number.isInteger(index)) result[i].push(...parents[index]);
+      });
+    }
+    building.delete(id);
+    return result;
+  }
+  const byRow = new Map();
+  for (const d of datasets.values()) {
+    const refs = visit(d.id);
+    d.values.forEach((row, i) => byRow.set(row, [...(byRow.get(row) ?? []), ...refs[i]]));
+  }
+  cache.set(program.semanticSpec.datasets, { provenance, byRow });
+  return byRow;
+}
+
+// Record identity while the retained rows still share their source objects.
+// Persisting these positions avoids guessing between equal-valued rows on restore.
+export function markFilterSourceIndices(sourceRows, rows) {
+  const positions = new Map(sourceRows.map((row, index) => [row, index]));
+  return rows.map(row => {
+    const index = positions.get(row);
+    if (index === undefined) throw new Error('Filtered row has no source identity.');
+    return index;
+  });
+}
+
+export function memberRowReferences(program, members) {
+  const index = indexRows(program), refs = new Map();
+  for (const row of members) for (const ref of index.get(row) ?? []) refs.set(`${ref.data}:${ref.index}`, ref);
+  const order = new Map(program.semanticSpec.datasets.map((dataset, index) => [dataset.id, index]));
+  return [...refs.values()].sort((a, b) => order.get(a.data) - order.get(b.data) || a.index - b.index);
+}
+
+export function validateRowSelection(program, rows, items) {
+  const dataset = findDataset(program, rows.data);
+  validateRowSelectionDataset(rows, dataset);
+  if (items.length && !items.some(item => item.rows.some(ref => ref.data === rows.data))) {
+    throw new Error(`Row lineage from "${rows.data}" is unavailable for this mark; select its materialized dataset instead.`);
+  }
+}
+
+export function rowsForSelectedItems(program, items, keys, preferredData) {
+  const available = new Set(items.flatMap(item => item.rows.map(ref => ref.data)));
+  const data = available.has(preferredData) ? preferredData
+    : program.semanticSpec.datasets.filter(dataset => available.has(dataset.id))[0]?.id ?? preferredData;
+  const selected = new Set(keys);
+  const indices = [...new Set(items.filter(item => selected.has(item.key)).flatMap(item => item.rows)
+    .filter(ref => ref.data === data).map(ref => ref.index))];
+  return { data, indices };
+}

package/src/materialization/selection/state.js

@@ -1,11 +1,13 @@
+import { validateRowSelection, rowsForSelectedItems } from "./rows.js";
 import { validateUserId } from "../../core/identifiers.js";
 import { normalizeMarkSelector, selectMarkItemKeys } from "../../grammar/markSelection.js";
-import { resolveMarkItems } from "./policies/index.js";
+import { resolveMarkItems, resolveMarkSourceItems } from "./policies/index.js";
 
 export function resolveMarkSelection(program, target, selector) {
   const normalized = normalizeMarkSelector(selector);
   const items = resolveMarkItems(program, target, normalized.grain);
-  if (items.length > 0) {
+  if (normalized.rows) validateRowSelection(program, normalized.rows, items);
+  if (items.length > 0 && !normalized.rows) {
     const source = normalized.field !== undefined
       ? "fields"
       : normalized.channel !== undefined
@@ -41,6 +43,20 @@ export function resolveSelectionCreationId(program, id, target) {
   return resolved;
 }
 
+
+// Dependent components follow their owner's current selection after data or
+// encoding revisions, rather than freezing a list of previously selected rows.
+export function selectionPredicate(program, definition) {
+  if (!definition.sourceSelection) return definition.selector;
+  const parent = program.materializationConfigs.selections?.[definition.sourceSelection];
+  if (!parent || parent.sourceSelection) throw new Error('Invalid composite selection owner.');
+  if (!definition.selector.rows) return parent.selector;
+  const items = parent.selector.property ? resolveMarkItems(program, parent.target, parent.selector.grain)
+    : resolveMarkSourceItems(program, parent.target, parent.selector.grain);
+  const resolved = { items, keys: selectMarkItemKeys(items, parent.selector) };
+  return { ...definition.selector, rows: rowsForSelectedItems(program, resolved.items, resolved.keys, definition.selector.rows.data) };
+}
+
 export function resolveStoredSelection(program, id) {
   const selections = program.materializationConfigs.selections ?? {};
   const requested = id ?? program.context.currentSelection;
@@ -61,7 +77,7 @@ export function resolveStoredSelection(program, id) {
   const resolved = resolveMarkSelection(
     program,
     definition.target,
-    definition.selector
+    selectionPredicate(program, definition)
   );
   return Object.freeze({ id: resolvedId, definition, ...resolved });
 }

package/src/materialization/selection/styles.js

@@ -192,3 +192,11 @@ export function normalizeAreaHighlightStyle(args, mark = "Area") {
     offset: normalizeOffset(args.offset)
   };
 }
+
+export function normalizeTextHighlightStyle(args) {
+  for (const key of ['shape', 'size', 'stroke', 'strokeWidth', 'strokeDash']) if (args[key] !== undefined) throw new Error(`Text highlight does not support ${key}.`);
+  if (args.color !== undefined && args.fill !== undefined) throw new Error('Text highlight accepts color or fill, not both.');
+  return { fill: validateNonEmptyString(args.color ?? args.fill ?? DEFAULT_COLORS.highlight, 'Text highlight color'),
+    ...(args.opacity === undefined ? {} : { opacity: validateUnitInterval(args.opacity, 'Text highlight opacity') }),
+    ...(args.fontSize === undefined ? {} : { fontSize: validatePositiveFinite(args.fontSize, 'Text highlight fontSize') }), offset: normalizeOffset(args.offset) };
+}