ggaction 0.0.1

package/src/grammar/markSelection.js

@@ -0,0 +1,326 @@
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+import { ENCODING_CHANNELS } from "../core/vocabulary.js";
+
+export const MARK_SELECTOR_OPERATORS = Object.freeze([
+  "eq",
+  "neq",
+  "gt",
+  "gte",
+  "lt",
+  "lte",
+  "oneOf",
+  "range",
+  "min",
+  "max"
+]);
+
+export const MARK_SELECTOR_GRAINS = Object.freeze(["item", "stack"]);
+
+export const MARK_GRAPHIC_PROPERTIES = Object.freeze([
+  "x",
+  "y",
+  "width",
+  "height",
+  "radius",
+  "x1",
+  "y1",
+  "x2",
+  "y2",
+  "fill",
+  "stroke",
+  "strokeWidth",
+  "opacity"
+]);
+
+const COMPARISON_OPERATORS = new Set([
+  "eq",
+  "neq",
+  "gt",
+  "gte",
+  "lt",
+  "lte"
+]);
+const ORDERED_COMPARISON_OPERATORS = new Set(["gt", "gte", "lt", "lte"]);
+const RANK_OPERATORS = new Set(["min", "max"]);
+const SELECTOR_KEYS = Object.freeze([
+  "grain",
+  "field",
+  "channel",
+  "property",
+  "op",
+  "value",
+  "values",
+  "min",
+  "max",
+  "inclusive",
+  "count",
+  "groupBy",
+  "ties"
+]);
+
+function validateField(value, label = "Selector field") {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${label} must be a non-empty string.`);
+  }
+  return value;
+}
+
+function isOrderedValue(value) {
+  return Number.isFinite(value) || typeof value === "string";
+}
+
+function validateOrderedValue(value, label) {
+  if (!isOrderedValue(value)) {
+    throw new TypeError(`${label} must be a finite number or string.`);
+  }
+  return value;
+}
+
+function normalizeGroupBy(value) {
+  if (value === undefined) return undefined;
+  const fields = Array.isArray(value) ? value : [value];
+  if (fields.length === 0) {
+    throw new TypeError("Selector groupBy must contain at least one field.");
+  }
+  const normalized = fields.map(field => validateField(field, "Selector groupBy field"));
+  if (new Set(normalized).size !== normalized.length) {
+    throw new Error("Selector groupBy fields must be unique.");
+  }
+  return normalized;
+}
+
+export function normalizeMarkSelector(selector) {
+  if (!isPlainObject(selector)) {
+    throw new TypeError("Mark selector must be a plain object.");
+  }
+  const unknown = Object.keys(selector).find(key => !SELECTOR_KEYS.includes(key));
+  if (unknown !== undefined) {
+    throw new Error(`Unknown mark selector option "${unknown}".`);
+  }
+
+  const sources = ["field", "channel", "property"].filter(key =>
+    Object.hasOwn(selector, key)
+  );
+  if (sources.length !== 1) {
+    throw new Error(
+      "Mark selector requires exactly one of field, channel, or property."
+    );
+  }
+  const source = sources[0];
+  const sourceValue = source === "field"
+    ? validateField(selector.field)
+    : selector[source];
+  if (source === "channel" && !ENCODING_CHANNELS.includes(sourceValue)) {
+    throw new Error(`Unknown selector channel "${sourceValue}".`);
+  }
+  if (source === "property" && !MARK_GRAPHIC_PROPERTIES.includes(sourceValue)) {
+    throw new Error(`Unknown selector graphic property "${sourceValue}".`);
+  }
+  const grain = selector.grain ?? "item";
+  if (!MARK_SELECTOR_GRAINS.includes(grain)) {
+    throw new Error(`Unknown mark selector grain "${grain}".`);
+  }
+
+  if (!MARK_SELECTOR_OPERATORS.includes(selector.op)) {
+    throw new Error(`Unknown mark selector operator "${selector.op}".`);
+  }
+  const op = selector.op;
+  const allowedByOperation = RANK_OPERATORS.has(op)
+    ? new Set(["grain", source, "op", "count", "groupBy", "ties"])
+    : op === "range"
+      ? new Set(["grain", source, "op", "min", "max", "inclusive"])
+      : op === "oneOf"
+        ? new Set(["grain", source, "op", "values"])
+        : new Set(["grain", source, "op", "value"]);
+  const incompatible = Object.keys(selector).find(key => !allowedByOperation.has(key));
+  if (incompatible !== undefined) {
+    throw new Error(
+      `Mark selector operator "${op}" does not accept "${incompatible}".`
+    );
+  }
+
+  if (COMPARISON_OPERATORS.has(op)) {
+    if (!Object.hasOwn(selector, "value")) {
+      throw new TypeError(`Mark selector operator "${op}" requires value.`);
+    }
+    if (ORDERED_COMPARISON_OPERATORS.has(op)) {
+      validateOrderedValue(selector.value, "Ordered selector value");
+    }
+    return cloneAndFreeze({ grain, [source]: sourceValue, op, value: selector.value });
+  }
+
+  if (op === "oneOf") {
+    if (!Array.isArray(selector.values)) {
+      throw new TypeError("Mark selector oneOf values must be an array.");
+    }
+    return cloneAndFreeze({ grain, [source]: sourceValue, op, values: selector.values });
+  }
+
+  if (op === "range") {
+    const min = validateOrderedValue(selector.min, "Selector range min");
+    const max = validateOrderedValue(selector.max, "Selector range max");
+    if (typeof min !== typeof max) {
+      throw new TypeError("Selector range endpoints must have one type.");
+    }
+    if (min > max) {
+      throw new RangeError("Selector range min must not exceed max.");
+    }
+    if (selector.inclusive !== undefined && typeof selector.inclusive !== "boolean") {
+      throw new TypeError("Selector range inclusive must be a boolean.");
+    }
+    return cloneAndFreeze({
+      grain,
+      [source]: sourceValue,
+      op,
+      min,
+      max,
+      inclusive: selector.inclusive ?? true
+    });
+  }
+
+  const count = selector.count ?? 1;
+  if (!Number.isInteger(count) || count <= 0) {
+    throw new RangeError("Selector count must be a positive integer.");
+  }
+  const ties = selector.ties ?? "first";
+  if (!["first", "all"].includes(ties)) {
+    throw new Error(`Unknown selector ties policy "${ties}".`);
+  }
+  const groupBy = normalizeGroupBy(selector.groupBy);
+  return cloneAndFreeze({
+    grain,
+    [source]: sourceValue,
+    op,
+    count,
+    ...(groupBy === undefined ? {} : { groupBy }),
+    ties
+  });
+}
+
+function validateItems(items) {
+  if (!Array.isArray(items)) {
+    throw new TypeError("Selectable mark items must be an array.");
+  }
+  const keys = new Set();
+  for (const [index, item] of items.entries()) {
+    if (!isPlainObject(item)) {
+      throw new TypeError(`Selectable mark item ${index} must be a plain object.`);
+    }
+    if (typeof item.key !== "string" || item.key.length === 0) {
+      throw new TypeError(`Selectable mark item ${index} requires a non-empty key.`);
+    }
+    if (keys.has(item.key)) {
+      throw new Error(`Duplicate selectable mark item key "${item.key}".`);
+    }
+    keys.add(item.key);
+    if (
+      !isPlainObject(item.fields) ||
+      !isPlainObject(item.channels) ||
+      !isPlainObject(item.properties)
+    ) {
+      throw new TypeError(
+        `Selectable mark item "${item.key}" requires field, channel, and property value maps.`
+      );
+    }
+  }
+}
+
+function selectorValue(item, selector) {
+  if (selector.field !== undefined) return item.fields[selector.field];
+  if (selector.channel !== undefined) return item.channels[selector.channel];
+  return item.properties[selector.property];
+}
+
+function hasSelectorValue(item, selector) {
+  const values = selector.field !== undefined
+    ? item.fields
+    : selector.channel !== undefined
+      ? item.channels
+      : item.properties;
+  const key = selector.field ?? selector.channel ?? selector.property;
+  return Object.hasOwn(values, key) && values[key] !== undefined;
+}
+
+function comparable(value, operand) {
+  return (
+    Number.isFinite(value) && Number.isFinite(operand)
+  ) || (
+    typeof value === "string" && typeof operand === "string"
+  );
+}
+
+function matches(value, selector) {
+  if (selector.op === "eq") return value === selector.value;
+  if (selector.op === "neq") return value !== selector.value;
+  if (selector.op === "oneOf") return selector.values.includes(value);
+  if (selector.op === "range") {
+    if (!comparable(value, selector.min) || !comparable(value, selector.max)) {
+      return false;
+    }
+    return selector.inclusive
+      ? value >= selector.min && value <= selector.max
+      : value > selector.min && value < selector.max;
+  }
+  if (!comparable(value, selector.value)) return false;
+  if (selector.op === "gt") return value > selector.value;
+  if (selector.op === "gte") return value >= selector.value;
+  if (selector.op === "lt") return value < selector.value;
+  return value <= selector.value;
+}
+
+function groupKey(item, fields) {
+  return JSON.stringify(fields.map(field => item.fields[field]));
+}
+
+function rankGroup(items, selector) {
+  const eligible = items
+    .map((item, order) => ({ item, order, value: selectorValue(item, selector) }))
+    .filter(({ value }) => isOrderedValue(value));
+  if (eligible.length === 0) return [];
+
+  const valueType = typeof eligible[0].value;
+  const comparableItems = eligible.filter(({ value }) => typeof value === valueType);
+  const direction = selector.op === "min" ? 1 : -1;
+  comparableItems.sort((left, right) => {
+    if (left.value < right.value) return -1 * direction;
+    if (left.value > right.value) return 1 * direction;
+    return left.order - right.order;
+  });
+  if (selector.ties === "first" || comparableItems.length <= selector.count) {
+    return comparableItems.slice(0, selector.count);
+  }
+  const boundary = comparableItems[selector.count - 1].value;
+  return comparableItems.filter(({ value }, index) =>
+    index < selector.count || value === boundary
+  );
+}
+
+export function selectMarkItemKeys(items, selector) {
+  validateItems(items);
+  const normalized = normalizeMarkSelector(selector);
+  if (!RANK_OPERATORS.has(normalized.op)) {
+    return cloneAndFreeze(
+      items
+        .filter(item =>
+          hasSelectorValue(item, normalized) &&
+          matches(selectorValue(item, normalized), normalized)
+        )
+        .map(item => item.key)
+    );
+  }
+
+  const groups = new Map();
+  for (const item of items) {
+    const key = normalized.groupBy === undefined
+      ? "all"
+      : groupKey(item, normalized.groupBy);
+    const group = groups.get(key) ?? [];
+    group.push(item);
+    groups.set(key, group);
+  }
+  return cloneAndFreeze(
+    [...groups.values()].flatMap(group =>
+      rankGroup(group, normalized).map(({ item }) => item.key)
+    )
+  );
+}

package/src/grammar/palettes.js

@@ -0,0 +1,208 @@
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+import { validateKeys } from "../core/validation.js";
+
+function colors(encoded) {
+  return cloneAndFreeze(
+    encoded.match(/.{6}/g).map(value => `#${value.toLowerCase()}`)
+  );
+}
+
+const DISCRETE = Object.freeze({
+  accent: colors("7fc97fbeaed4fdc086ffff99386cb0f0027fbf5b17666666"),
+  category10: colors("1f77b4ff7f0e2ca02cd627289467bd8c564be377c27f7f7fbcbd2217becf"),
+  category20: colors("1f77b4aec7e8ff7f0effbb782ca02c98df8ad62728ff98969467bdc5b0d58c564bc49c94e377c2f7b6d27f7f7fc7c7c7bcbd22dbdb8d17becf9edae5"),
+  category20b: colors("393b795254a36b6ecf9c9ede6379398ca252b5cf6bcedb9c8c6d31bd9e39e7ba52e7cb94843c39ad494ad6616be7969c7b4173a55194ce6dbdde9ed6"),
+  category20c: colors("3182bd6baed69ecae1c6dbefe6550dfd8d3cfdae6bfdd0a231a35474c476a1d99bc7e9c0756bb19e9ac8bcbddcdadaeb636363969696bdbdbdd9d9d9"),
+  observable10: colors("4269d0efb118ff725c6cc5b03ca951ff8ab7a463f297bbf59c6b4e9498a0"),
+  dark2: colors("1b9e77d95f027570b3e7298a66a61ee6ab02a6761d666666"),
+  paired: colors("a6cee31f78b4b2df8a33a02cfb9a99e31a1cfdbf6fff7f00cab2d66a3d9affff99b15928"),
+  pastel1: colors("fbb4aeb3cde3ccebc5decbe4fed9a6ffffcce5d8bdfddaecf2f2f2"),
+  pastel2: colors("b3e2cdfdcdaccbd5e8f4cae4e6f5c9fff2aef1e2cccccccc"),
+  set1: colors("e41a1c377eb84daf4a984ea3ff7f00ffff33a65628f781bf999999"),
+  set2: colors("66c2a5fc8d628da0cbe78ac3a6d854ffd92fe5c494b3b3b3"),
+  set3: colors("8dd3c7ffffb3bebadafb807280b1d3fdb462b3de69fccde5d9d9d9bc80bdccebc5ffed6f"),
+  tableau10: colors("4c78a8f58518e4575672b7b254a24beeca3bb279a2ff9da69d755dbab0ac"),
+  tableau20: colors("4c78a89ecae9f58518ffbf7954a24b88d27ab79a20f2cf5b43989483bcb6e45756ff9d9879706ebab0acd67195fcbfd2b279a2d6a5c99e765fd8b5a5")
+});
+
+const CONTINUOUS = Object.freeze({
+  blues: colors("cfe1f2bed8eca8cee58fc1de74b2d75ba3cf4592c63181bd206fb2125ca40a4a90"),
+  tealblues: colors("bce4d89dd3d181c3cb65b3c245a2b9368fae347da0306a932c5985"),
+  teals: colors("bbdfdfa2d4d58ac9c975bcbb61b0af4da5a43799982b8b8c1e7f7f127273006667"),
+  greens: colors("d3eecdc0e6baabdda594d3917bc77d60ba6c46ab5e329a512089430e7735036429"),
+  browns: colors("eedbbdecca96e9b97ae4a865dc9856d18954c7784cc0673fb85536ad44339f3632"),
+  oranges: colors("fdd8b3fdc998fdb87bfda55efc9244f87f2cf06b18e4580bd14904b93d029f3303"),
+  reds: colors("fdc9b4fcb49afc9e80fc8767fa7051f6573fec3f2fdc2a25c81b1db21218970b13"),
+  purples: colors("e2e1efd4d4e8c4c5e0b4b3d6a3a0cc928ec3827cb97566ae684ea25c3696501f8c"),
+  warmgreys: colors("dcd4d0cec5c1c0b8b4b3aaa7a59c9998908c8b827f7e7673726866665c5a59504e"),
+  greys: colors("e2e2e2d4d4d4c4c4c4b1b1b19d9d9d8888887575756262624d4d4d3535351e1e1e"),
+  viridis: colors("440154470e61481a6c482575472f7d443a834144873d4e8a39568c35608d31688e2d708e2a788e27818e23888e21918d1f988b1fa08822a8842ab07f35b77943bf7154c56866cc5d7ad1518fd744a5db36bcdf27d2e21be9e51afde725"),
+  magma: colors("0000040404130b0924150e3720114b2c11603b0f704a107957157e651a80721f817f24828c29819a2e80a8327db6377ac43c75d1426fde4968e95462f1605df76f5cfa7f5efc8f65fe9f6dfeaf78febf84fece91fddea0fcedaffcfdbf"),
+  inferno: colors("0000040403130c0826170c3b240c4f330a5f420a68500d6c5d126e6b176e781c6d86216b932667a12b62ae305cbb3755c73e4cd24644dd513ae65c30ed6925f3771af8850ffb9506fca50afcb519fac62df6d645f2e661f3f484fcffa4"),
+  plasma: colors("0d088723069033059742039d5002a25d01a66a00a87801a88405a7900da49c179ea72198b12a90ba3488c33d80cb4779d35171da5a69e16462e76e5bed7953f2834cf68f44fa9a3dfca636fdb32ffec029fcce25f9dc24f5ea27f0f921"),
+  cividis: colors("00205100235800265d002961012b65042e670831690d346b11366c16396d1c3c6e213f6e26426e2c456e31476e374a6e3c4d6e42506e47536d4c566d51586e555b6e5a5e6e5e616e62646f66676f6a6a706e6d717270717573727976737c79747f7c75827f758682768985778c8877908b78938e789691789a94789e9778a19b78a59e77a9a177aea575b2a874b6ab73bbaf71c0b26fc5b66dc9b96acebd68d3c065d8c462ddc85fe2cb5ce7cf58ebd355f0d652f3da4ff7de4cfae249fce647"),
+  turbo: colors("23171b32204a3e2a71453493493eae4b49c54a53d7485ee44569ee4074f53c7ff8378af93295f72e9ff42ba9ef28b3e926bce125c5d925cdcf27d5c629dcbc2de3b232e9a738ee9d3ff39347f68950f9805afc7765fd6e70fe667cfd5e88fc5795fb51a1f84badf545b9f140c5ec3cd0e637dae034e4d931ecd12ef4c92bfac029ffb626ffad24ffa223ff9821ff8d1fff821dff771cfd6c1af76118f05616e84b14df4111d5380fcb2f0dc0260ab61f07ac1805a313029b0f00950c00910b00"),
+  bluegreen: colors("d5efedc1e8e0a7ddd18bd2be70c6a958ba9144ad77319c5d2089460e7736036429"),
+  bluepurple: colors("ccddecbad0e4a8c2dd9ab0d4919cc98d85be8b6db28a55a6873c99822287730f71"),
+  goldgreen: colors("f4d166d5ca60b6c35c98bb597cb25760a6564b9c533f8f4f33834a257740146c36"),
+  goldorange: colors("f4d166f8be5cf8aa4cf5983bf3852aef701be2621fd65322c54923b142239e3a26"),
+  goldred: colors("f4d166f6be59f9aa51fc964ef6834bee734ae56249db5247cf4244c43141b71d3e"),
+  greenblue: colors("d3eecec5e8c3b1e1bb9bd8bb82cec269c2ca51b2cd3c9fc7288abd1675b10b60a1"),
+  orangered: colors("fddcaffdcf9bfdc18afdad77fb9562f67d53ee6545e24932d32d1ebf130da70403"),
+  purplebluegreen: colors("dbd8eac8cee4b0c3de93b7d872acd1549fc83892bb1c88a3097f8702736b016353"),
+  purpleblue: colors("dbdaebc8cee4b1c3de97b7d87bacd15b9fc93a90c01e7fb70b70ab056199045281"),
+  purplered: colors("dcc9e2d3b3d7ce9eccd186c0da6bb2e14da0e23189d91e6fc61159ab07498f023a"),
+  redpurple: colors("fccfccfcbec0faa9b8f98faff571a5ec539ddb3695c41b8aa908808d0179700174"),
+  yellowgreenblue: colors("eff9bddbf1b4bde5b594d5b969c5be45b4c22c9ec02182b82163aa23479c1c3185"),
+  yellowgreen: colors("e4f4acd1eca0b9e2949ed68880c97c62bb6e47aa5e3297502083440e723b036034"),
+  yelloworangebrown: colors("feeaa1fedd84fecc63feb746fca031f68921eb7215db5e0bc54c05ab3d038f3204"),
+  yelloworangered: colors("fee087fed16ffebd59fea849fd903efc7335f9522bee3423de1b20ca0b22af0225"),
+  darkblue: colors("3232322d46681a5c930074af008cbf05a7ce25c0dd38daed50f3faffffff"),
+  darkgold: colors("3c3c3c584b37725e348c7631ae8b2bcfa424ecc31ef9de30fff184ffffff"),
+  darkgreen: colors("3a3a3a215748006f4d048942489e4276b340a6c63dd2d836ffeb2cffffaa"),
+  darkmulti: colors("3737371f5287197d8c29a86995ce3fffe800ffffff"),
+  darkred: colors("3434347036339e3c38cc4037e75d1eec8620eeab29f0ce32ffeb2c"),
+  lightgreyred: colors("efe9e6e1dad7d5cbc8bdb9bbaea9cd967ddc7b43e15f19df4011dc000b"),
+  lightgreyteal: colors("e4eaead6dcddc8ced2b7c2c7a6b4bc64b0bf22a6c32295c11f85be1876bc"),
+  lightmulti: colors("e0f1f2c4e9d0b0de9fd0e181f6e072f6c053f3993ef77440ef4a3c"),
+  lightorange: colors("f2e7daf7d5baf9c499fab184fa9c73f68967ef7860e8645bde515bd43d5b"),
+  lighttealblue: colors("e3e9e0c0dccf9aceca7abfc859afc0389fb9328dad2f7ca0276b95255988"),
+  blueorange: colors("134b852f78b35da2cb9dcae1d2e5eff2f0ebfce0bafbbf74e8932fc5690d994a07"),
+  brownbluegreen: colors("704108a0651ac79548e3c78af3e6c6eef1eac9e9e48ed1c74da79e187a72025147"),
+  purplegreen: colors("5b1667834792a67fb6c9aed3e6d6e8eff0efd9efd5aedda971bb75368e490e5e29"),
+  pinkyellowgreen: colors("8e0152c0267edd72adf0b3d6faddedf5f3efe1f2cab6de8780bb474f9125276419"),
+  purpleorange: colors("4114696647968f83b7b9b4d6dadbebf3eeeafce0bafbbf74e8932fc5690d994a07"),
+  redblue: colors("8c0d25bf363adf745ef4ae91fbdbc9f2efeed2e5ef9dcae15da2cb2f78b3134b85"),
+  redgrey: colors("8c0d25bf363adf745ef4ae91fcdccbfaf4f1e2e2e2c0c0c0969696646464343434"),
+  redyellowblue: colors("a50026d4322cf16e43fcac64fedd90faf8c1dcf1ecabd6e875abd04a74b4313695"),
+  redyellowgreen: colors("a50026d4322cf16e43fcac63fedd8df9f7aed7ee8ea4d86e64bc6122964f006837"),
+  spectral: colors("9e0142d13c4bf0704afcac63fedd8dfbf8b0e0f3a1a9dda269bda94288b55e4fa2"),
+  rainbow: colors("6e40aa883eb1a43db3bf3cafd83fa4ee4395fe4b83ff576eff6659ff7847ff8c38f3a130e2b72fcfcc36bee044aff05b8ff4576ff65b52f6673af27828ea8d1ddfa319d0b81cbecb23abd82f96e03d82e14c6edb5a5dd0664dbf6e40aa"),
+  sinebow: colors("ff4040fc582af47218e78d0bd5a703bfbf00a7d5038de70b72f41858fc2a40ff402afc5818f4720be78d03d5a700bfbf03a7d50b8de71872f42a58fc4040ff582afc7218f48d0be7a703d5bf00bfd503a7e70b8df41872fc2a58ff4040")
+});
+
+export const PALETTE_NAMES = cloneAndFreeze([
+  "accent",
+  "category10", "category20", "category20b", "category20c",
+  "observable10",
+  "dark2", "paired", "pastel1", "pastel2",
+  "set1", "set2", "set3",
+  "tableau10", "tableau20",
+  "blues", "tealblues", "teals", "greens", "browns",
+  "oranges", "reds", "purples", "warmgreys", "greys",
+  "viridis", "magma", "inferno", "plasma", "cividis", "turbo",
+  "bluegreen", "bluepurple",
+  "goldgreen", "goldorange", "goldred",
+  "greenblue", "orangered",
+  "purplebluegreen", "purpleblue", "purplered", "redpurple",
+  "yellowgreenblue", "yellowgreen", "yelloworangebrown", "yelloworangered",
+  "darkblue", "darkgold", "darkgreen", "darkmulti", "darkred",
+  "lightgreyred", "lightgreyteal", "lightmulti", "lightorange", "lighttealblue",
+  "blueorange", "brownbluegreen", "purplegreen", "pinkyellowgreen",
+  "purpleorange", "redblue", "redgrey",
+  "redyellowblue", "redyellowgreen", "spectral",
+  "rainbow", "sinebow"
+]);
+
+const PALETTE_SET = new Set(PALETTE_NAMES);
+
+export function validatePaletteName(name) {
+  if (typeof name !== "string" || !PALETTE_SET.has(name)) {
+    throw new Error(`Unknown palette "${name}".`);
+  }
+  return name;
+}
+
+export function normalizePalette(value) {
+  if (typeof value === "string") return { name: validatePaletteName(value) };
+  if (!isPlainObject(value)) {
+    throw new TypeError("Palette must be a name or a plain object.");
+  }
+  validateKeys(value, ["name", "count", "extent"], "palette");
+  const name = validatePaletteName(value.name);
+  const normalized = { name };
+  if (value.count !== undefined) {
+    if (!Number.isInteger(value.count) || value.count <= 0) {
+      throw new RangeError("Palette count must be a positive integer.");
+    }
+    normalized.count = value.count;
+  }
+  if (value.extent !== undefined) {
+    if (DISCRETE[name] !== undefined) {
+      throw new Error(`Categorical palette "${name}" does not support extent.`);
+    }
+    if (
+      !Array.isArray(value.extent) ||
+      value.extent.length !== 2 ||
+      !value.extent.every(item => Number.isFinite(item) && item >= 0 && item <= 1) ||
+      value.extent[0] === value.extent[1]
+    ) {
+      throw new RangeError(
+        "Palette extent must contain two distinct values from 0 to 1."
+      );
+    }
+    normalized.extent = cloneAndFreeze(value.extent);
+  }
+  return cloneAndFreeze(normalized);
+}
+
+function channel(hex, offset) {
+  return Number.parseInt(hex.slice(offset, offset + 2), 16);
+}
+
+function interpolateColor(left, right, amount) {
+  const channels = [1, 3, 5].map(offset =>
+    Math.round(channel(left, offset) +
+      (channel(right, offset) - channel(left, offset)) * amount)
+      .toString(16)
+      .padStart(2, "0")
+  );
+  return `#${channels.join("")}`;
+}
+
+function sample(colorsValue, position) {
+  const bounded = Math.max(0, Math.min(1, position));
+  const scaled = bounded * (colorsValue.length - 1);
+  const left = Math.floor(scaled);
+  const right = Math.min(colorsValue.length - 1, left + 1);
+  return interpolateColor(colorsValue[left], colorsValue[right], scaled - left);
+}
+
+export function resolvePalette(value, domainCount) {
+  const palette = normalizePalette(value);
+  const discrete = DISCRETE[palette.name];
+  if (discrete !== undefined) {
+    const count = palette.count ?? discrete.length;
+    return cloneAndFreeze(
+      Array.from({ length: count }, (_, index) => discrete[index % discrete.length])
+    );
+  }
+  if (!Number.isInteger(domainCount) || domainCount <= 0) {
+    throw new Error("Continuous palette sampling requires a positive domain count.");
+  }
+  const source = CONTINUOUS[palette.name];
+  const count = palette.count ?? domainCount;
+  const extent = palette.extent ?? [0, 1];
+  return cloneAndFreeze(Array.from({ length: count }, (_, index) => {
+    const unit = count === 1 ? 0.5 : index / (count - 1);
+    return sample(source, extent[0] + (extent[1] - extent[0]) * unit);
+  }));
+}
+
+export function resolveContinuousPalette(value, count = 31) {
+  if (!Number.isInteger(count) || count < 2) {
+    throw new RangeError("Continuous palette count must be an integer of at least 2.");
+  }
+  const palette = normalizePalette(value);
+  if (palette.count !== undefined) {
+    throw new Error("Continuous palette does not accept count.");
+  }
+  const discrete = DISCRETE[palette.name];
+  if (discrete !== undefined) return discrete;
+  return resolvePalette({ ...palette, count }, count);
+}
+
+export function paletteFamily(name) {
+  const validated = validatePaletteName(name);
+  return DISCRETE[validated] === undefined ? "continuous" : "categorical";
+}

package/src/grammar/pathCommands.js

@@ -0,0 +1,86 @@
+import { freezeOwned, isPlainObject } from "../core/immutable.js";
+
+const COMMAND_KEYS = Object.freeze({
+  M: Object.freeze(["op", "x", "y"]),
+  L: Object.freeze(["op", "x", "y"]),
+  C: Object.freeze(["op", "x1", "y1", "x2", "y2", "x", "y"]),
+  Z: Object.freeze(["op"])
+});
+
+function validateCommand(command, index) {
+  if (!isPlainObject(command) || !Object.hasOwn(COMMAND_KEYS, command.op)) {
+    throw new TypeError(
+      `path.commands[${index}] must be an M, L, C, or Z command.`
+    );
+  }
+  const expected = COMMAND_KEYS[command.op];
+  const keys = Object.keys(command);
+  if (
+    keys.length !== expected.length ||
+    !expected.every(key => Object.hasOwn(command, key))
+  ) {
+    throw new TypeError(
+      `path.commands[${index}] has invalid properties for ${command.op}.`
+    );
+  }
+  for (const key of expected) {
+    if (key !== "op" && !Number.isFinite(command[key])) {
+      throw new TypeError(
+        `path.commands[${index}].${key} must be a finite number.`
+      );
+    }
+  }
+  return command;
+}
+
+export function validatePathCommands(commands) {
+  if (!Array.isArray(commands) || commands.length < 2) {
+    throw new TypeError("path.commands must contain at least two commands.");
+  }
+  commands.forEach(validateCommand);
+  if (commands[0].op !== "M") {
+    throw new Error("path.commands must start with M.");
+  }
+  if (commands.slice(1).some(command => command.op === "M")) {
+    throw new Error("path.commands supports one subpath and only one initial M.");
+  }
+  if (!commands.some(command => command.op === "L" || command.op === "C")) {
+    throw new Error("path.commands requires at least one L or C segment.");
+  }
+  const closeIndex = commands.findIndex(command => command.op === "Z");
+  if (closeIndex !== -1 && closeIndex !== commands.length - 1) {
+    throw new Error("path.commands Z must be the final command.");
+  }
+  return commands;
+}
+
+function validatePoints(points) {
+  if (
+    !Array.isArray(points) ||
+    points.length < 2 ||
+    !points.every(point =>
+      isPlainObject(point) &&
+      Object.keys(point).length === 2 &&
+      Number.isFinite(point.x) &&
+      Number.isFinite(point.y)
+    )
+  ) {
+    throw new TypeError(
+      "Linear path points must contain at least two finite { x, y } objects."
+    );
+  }
+  return points;
+}
+
+export function buildLinearPathCommands(points, { close = false } = {}) {
+  validatePoints(points);
+  if (typeof close !== "boolean") {
+    throw new TypeError("Linear path close must be a boolean.");
+  }
+  const commands = [
+    { op: "M", x: points[0].x, y: points[0].y },
+    ...points.slice(1).map(point => ({ op: "L", x: point.x, y: point.y }))
+  ];
+  if (close) commands.push({ op: "Z" });
+  return freezeOwned(commands.map(command => freezeOwned(command)));
+}