ggaction 0.0.17 → 0.0.19

package/src/grammar/arcs.js

@@ -1,386 +1 @@
-import { cloneAndFreeze } from "../core/immutable.js";
-import {
-  mapContinuousScaleValues,
-  mapOrdinalPositionValues,
-  readNominalField,
-  readQuantitativeField
-} from "./scales/index.js";
-import {
-  interpolateNumber,
-  normalizedFiniteSum,
-  requireFiniteResult,
-  stableFiniteSum
-} from "./numeric.js";
-
-function requireArcLayer(layer) {
-  if (layer?.mark?.type !== "arc") {
-    throw new Error("Arc derivation requires a semantic arc mark.");
-  }
-  const theta = layer.encoding?.theta;
-  if (
-    theta === undefined ||
-    !["quantitative", "nominal", "ordinal"].includes(theta.fieldType)
-  ) {
-    throw new Error(
-      `Arc mark "${layer.id}" requires quantitative or categorical theta.`
-    );
-  }
-  return theta;
-}
-
-function requireContinuousThetaScale(scale, label) {
-  if (
-    scale?.type !== "linear" ||
-    !Array.isArray(scale.range) ||
-    scale.range.length !== 2 ||
-    !scale.range.every(Number.isFinite) ||
-    scale.range[0] === scale.range[1]
-  ) {
-    throw new Error(`${label} requires a resolved linear scale.`);
-  }
-  return scale;
-}
-
-function requireBandScale(scale, label) {
-  if (
-    scale?.type !== "band" ||
-    !Array.isArray(scale.domain) ||
-    !Array.isArray(scale.range) ||
-    scale.range.length !== 2 ||
-    !scale.range.every(Number.isFinite) ||
-    scale.range[0] === scale.range[1] ||
-    !Number.isFinite(scale.bandwidth) ||
-    scale.bandwidth <= 0
-  ) {
-    throw new Error(`${label} requires a resolved band scale.`);
-  }
-  return scale;
-}
-
-function colorValues(rows, encoding) {
-  return encoding === undefined
-    ? rows.map(() => undefined)
-    : readNominalField(rows, encoding.field);
-}
-
-function readNonNegativeArcThetaValues(rows, field, layerId, role) {
-  if (!Array.isArray(rows)) throw new TypeError(`Arc theta ${role}s require rows.`);
-  if (typeof field !== "string" || field.length === 0) {
-    throw new TypeError(`Arc theta ${role} must be a non-empty string.`);
-  }
-  const values = rows.map((row, index) => {
-    const value = row?.[field];
-    if (!Number.isFinite(value) || value < 0) {
-      throw new TypeError(
-        `Arc theta ${role} field "${field}" must contain non-negative finite numbers at row ${index}.`
-      );
-    }
-    return value;
-  });
-  if (values.every(value => value === 0)) {
-    throw new Error(`Arc mark "${layerId}" theta ${role}s must have a positive total.`);
-  }
-  return cloneAndFreeze(values);
-}
-
-export function readArcThetaWeights(rows, field, layerId = "arc") {
-  return readNonNegativeArcThetaValues(rows, field, layerId, "weight");
-}
-
-export function readArcThetaValues(rows, field, layerId = "arc") {
-  return readNonNegativeArcThetaValues(rows, field, layerId, "value");
-}
-
-function resolveProportionalRanges(values, range, labelAt) {
-  const total = values.reduce((sum, value) => sum + value, 0);
-  const normalizedTotal = Number.isFinite(total)
-    ? undefined
-    : normalizedFiniteSum(values, "Arc theta values");
-  if (total === 0 || normalizedTotal?.total <= 0) {
-    throw new Error("Arc theta values must have a positive total.");
-  }
-  const span = range[1] - range[0];
-  let cursor = range[0];
-  let cumulative = 0;
-  let cumulativeCorrection = 0;
-  return values.map((value, index) => {
-    const normalizedValue = normalizedTotal === undefined
-      ? value
-      : value / normalizedTotal.scale;
-    const next = cumulative + normalizedValue;
-    if (normalizedTotal !== undefined) {
-      cumulativeCorrection += Math.abs(cumulative) >= Math.abs(normalizedValue)
-        ? cumulative - next + normalizedValue
-        : normalizedValue - next + cumulative;
-    }
-    cumulative = next;
-    const directEnd = cursor + value / total * span;
-    const endTheta = index === values.length - 1
-      ? range[1]
-      : normalizedTotal === undefined && Number.isFinite(directEnd)
-        ? directEnd
-        : interpolateNumber(
-            range[0],
-            range[1],
-            (cumulative + cumulativeCorrection) /
-              (normalizedTotal?.total ?? total)
-          );
-    if (!Number.isFinite(endTheta) || endTheta === cursor) {
-      throw new RangeError(
-        `Arc theta ${labelAt(index)} cannot resolve a distinct finite sector.`
-      );
-    }
-    const result = { startTheta: cursor, endTheta };
-    cursor = endTheta;
-    return result;
-  });
-}
-
-function resolveProportionalRadii(layer, frame, innerRadiusRatio) {
-  if (!Number.isFinite(frame?.availableRadius) || frame.availableRadius < 0) {
-    throw new RangeError(`Arc mark "${layer.id}" requires a finite available radius.`);
-  }
-  return {
-    innerRadius: requireFiniteResult(
-      frame.availableRadius * innerRadiusRatio,
-      `Arc mark "${layer.id}" inner radius`
-    ),
-    outerRadius: frame.availableRadius
-  };
-}
-
-function proportionalSectors(rows, layer, thetaScale, frame, innerRadiusRatio) {
-  const theta = layer.encoding.theta;
-  if (!["count", "sum"].includes(theta.aggregate)) {
-    throw new Error(`Arc mark "${layer.id}" requires count, sum, or radial layout.`);
-  }
-  const values = readNominalField(rows, theta.field);
-  const colors = colorValues(rows, layer.encoding?.color);
-  const weights = theta.aggregate === "count"
-    ? rows.map(() => 1)
-    : readArcThetaWeights(rows, theta.weight, layer.id);
-  const groups = new Map(thetaScale.domain.map(value => [value, []]));
-  for (let index = 0; index < rows.length; index += 1) {
-    const group = groups.get(values[index]);
-    if (group === undefined) {
-      throw new Error(`Arc theta value "${values[index]}" is outside the scale domain.`);
-    }
-    group.push({
-      color: colors[index],
-      sourceIndex: index,
-      weight: weights[index]
-    });
-  }
-  const radii = resolveProportionalRadii(layer, frame, innerRadiusRatio);
-  const sectors = [];
-  const positiveValues = thetaScale.domain.filter(value =>
-    groups.get(value).some(item => item.weight > 0)
-  );
-  const aggregateValues = positiveValues.map(value => stableFiniteSum(
-    groups.get(value).map(item => item.weight),
-    `Arc theta group "${String(value)}" aggregate`
-  ));
-  const ranges = resolveProportionalRanges(
-    aggregateValues,
-    thetaScale.range,
-    index => `group "${String(positiveValues[index])}"`
-  );
-  for (const [positiveIndex, value] of positiveValues.entries()) {
-    const group = groups.get(value);
-    const aggregateValue = aggregateValues[positiveIndex];
-    const { startTheta, endTheta } = ranges[positiveIndex];
-    const distinctColors = [...new Set(group.map(item => item.color))];
-    if (distinctColors.length > 1) {
-      throw new Error(
-        `Aggregated arc theta group "${value}" must resolve to one color value.`
-      );
-    }
-    sectors.push({
-      key: value,
-      theta: value,
-      count: group.length,
-      aggregateValue,
-      color: distinctColors[0],
-      startTheta,
-      endTheta,
-      ...radii,
-      sourceIndices: group.map(item => item.sourceIndex)
-    });
-  }
-  return sectors;
-}
-
-function quantitativeSectors(rows, layer, thetaScale, frame, innerRadiusRatio) {
-  const theta = layer.encoding.theta;
-  if (layer.encoding?.radius !== undefined) {
-    throw new Error(
-      `Arc mark "${layer.id}" cannot combine quantitative theta with radius.`
-    );
-  }
-  const values = readArcThetaValues(rows, theta.field, layer.id);
-  const colors = colorValues(rows, layer.encoding?.color);
-  const positiveIndices = values
-    .map((value, index) => value > 0 ? index : undefined)
-    .filter(index => index !== undefined);
-  const positiveValues = positiveIndices.map(index => values[index]);
-  const ranges = resolveProportionalRanges(
-    positiveValues,
-    thetaScale.range,
-    index => `row ${positiveIndices[index]}`
-  );
-  const radii = resolveProportionalRadii(layer, frame, innerRadiusRatio);
-  return positiveIndices.map((sourceIndex, index) => ({
-    key: `${String(values[sourceIndex])}:${sourceIndex}`,
-    theta: values[sourceIndex],
-    count: 1,
-    aggregateValue: values[sourceIndex],
-    color: colors[sourceIndex],
-    ...ranges[index],
-    ...radii,
-    sourceIndices: [sourceIndex]
-  }));
-}
-
-export function deriveMeasuredArcValues(rows, layer) {
-  const theta = requireArcLayer(layer);
-  const radius = layer.encoding?.radius;
-  if (!["nominal", "ordinal"].includes(theta.fieldType) || theta.aggregate !== undefined ||
-    !["count", "sum"].includes(radius?.aggregate) || radius.fieldType !== "quantitative") {
-    throw new Error("Measured Arc requires equal-angle categorical theta and count or sum radius.");
-  }
-  if (radius.aggregate === "count" && Object.hasOwn(radius, "field")) {
-    throw new Error("Measured count radius does not accept a field.");
-  }
-  const categories = readNominalField(rows, theta.field);
-  const measures = radius.aggregate === "count" ? rows.map(() => 1)
-    : readQuantitativeField(rows, radius.field);
-  if (measures.some(value => value < 0)) {
-    throw new RangeError("Measured Arc radius inputs must be non-negative.");
-  }
-  const colors = colorValues(rows, layer.encoding?.color);
-  const groups = new Map();
-  for (const [index, category] of categories.entries()) {
-    const group = groups.get(category) ?? { key: category, sourceIndices: [], values: [], colors: [] };
-    group.sourceIndices.push(index);
-    group.values.push(measures[index]);
-    group.colors.push(colors[index]);
-    groups.set(category, group);
-  }
-  const result = [...groups.values()].map(group => {
-    const distinctColors = [...new Set(group.colors)];
-    if (distinctColors.length > 1) {
-      throw new Error(`Measured Arc category "${group.key}" must resolve to one color value.`);
-    }
-    return { key: group.key, theta: group.key, count: group.sourceIndices.length,
-      radius: stableFiniteSum(group.values, "Measured Arc radius aggregate"),
-      color: distinctColors[0], sourceIndices: group.sourceIndices };
-  });
-  if (!result.some(group => group.radius > 0)) {
-    throw new Error("Measured Arc radius requires at least one positive category aggregate.");
-  }
-  return cloneAndFreeze(result);
-}
-
-function measuredRadialSectors(rows, layer, thetaScale, radiusScale) {
-  const items = deriveMeasuredArcValues(rows, layer);
-  const centers = mapOrdinalPositionValues(items.map(item => item.theta), thetaScale);
-  const radii = mapContinuousScaleValues(items.map(item => item.radius), radiusScale);
-  const halfBand = (Math.sign(thetaScale.step) || 1) * thetaScale.bandwidth / 2;
-  const byCategory = new Map(items.map((item, index) => [item.theta, {
-    ...item, startTheta: centers[index] - halfBand, endTheta: centers[index] + halfBand,
-    innerRadius: radiusScale.range[0], outerRadius: radii[index]
-  }]));
-  return thetaScale.domain.flatMap(category => {
-    const item = byCategory.get(category);
-    return item === undefined || item.radius === 0 ? [] : [item];
-  });
-}
-
-function radialSectors(rows, layer, thetaScale, radiusScale) {
-  const theta = layer.encoding.theta;
-  const radius = layer.encoding?.radius;
-  if (radius?.fieldType !== "quantitative") {
-    throw new Error(`Arc mark "${layer.id}" requires quantitative radius.`);
-  }
-  const thetaValues = readNominalField(rows, theta.field);
-  const radiusValues = readQuantitativeField(rows, radius.field);
-  const colors = colorValues(rows, layer.encoding?.color);
-  const centers = mapOrdinalPositionValues(thetaValues, thetaScale);
-  const outerRadii = mapContinuousScaleValues(radiusValues, radiusScale);
-  const innerRadius = Math.min(...radiusScale.range);
-  const direction = Math.sign(thetaScale.step) || 1;
-  const halfBand = direction * thetaScale.bandwidth / 2;
-  const grouped = new Map(thetaScale.domain.map(value => [value, []]));
-  for (let index = 0; index < rows.length; index += 1) {
-    if (outerRadii[index] <= innerRadius) continue;
-    const group = grouped.get(thetaValues[index]);
-    if (group === undefined) {
-      throw new Error(
-        `Arc theta value "${thetaValues[index]}" is outside the scale domain.`
-      );
-    }
-    group.push({
-      key: `${String(thetaValues[index])}:${index}`,
-      theta: thetaValues[index],
-      radius: radiusValues[index],
-      color: colors[index],
-      startTheta: centers[index] - halfBand,
-      endTheta: centers[index] + halfBand,
-      innerRadius,
-      outerRadius: outerRadii[index],
-      sourceIndices: [index]
-    });
-  }
-  const sectors = [];
-  for (const value of thetaScale.domain) {
-    const group = grouped.get(value);
-    group.sort((left, right) =>
-      right.outerRadius - left.outerRadius ||
-      left.sourceIndices[0] - right.sourceIndices[0]
-    );
-    sectors.push(...group);
-  }
-  return sectors;
-}
-
-export function deriveArcSectors(rows, layer, {
-  thetaScale,
-  radiusScale,
-  frame,
-  innerRadiusRatio = 0
-} = {}) {
-  if (!Array.isArray(rows)) throw new TypeError("Arc derivation requires rows.");
-  const theta = requireArcLayer(layer);
-  if (
-    !Number.isFinite(innerRadiusRatio) ||
-    innerRadiusRatio < 0 ||
-    innerRadiusRatio >= 1
-  ) {
-    throw new RangeError("Arc innerRadius must be from 0 (inclusive) to 1 (exclusive).");
-  }
-  const sectors = radiusScale?.radialMapping !== undefined
-    ? measuredRadialSectors(rows, layer, requireBandScale(thetaScale, `Arc mark "${layer.id}" theta`), radiusScale)
-    : theta.fieldType === "quantitative"
-    ? quantitativeSectors(
-        rows,
-        layer,
-        requireContinuousThetaScale(thetaScale, `Arc mark "${layer.id}" theta`),
-        frame,
-        innerRadiusRatio
-      )
-    : ["count", "sum"].includes(theta.aggregate)
-      ? proportionalSectors(
-          rows,
-          layer,
-          requireBandScale(thetaScale, `Arc mark "${layer.id}" theta`),
-          frame,
-          innerRadiusRatio
-        )
-      : radialSectors(
-          rows,
-          layer,
-          requireBandScale(thetaScale, `Arc mark "${layer.id}" theta`),
-          radiusScale
-        );
-  return cloneAndFreeze({ sectors });
-}
+import{validateOptionObject as P,validateNonNegativeFinite as j}from"../core/validation.js";import{cloneAndFreeze as R,isPlainObject as B}from"../core/immutable.js";import{mapContinuousScaleValues as y,mapOrdinalPositionValues as M,readNominalField as b,readQuantitativeField as I}from"./scales/index.js";import{interpolateNumber as S,normalizedFiniteSum as _,stableFiniteSum as q}from"./numeric.js";function k(e){if(e?.mark?.type!=="arc")throw new Error("Arc derivation requires a semantic arc mark.");const t=e.encoding?.theta;if(t===void 0||!["quantitative","nominal","ordinal"].includes(t.fieldType))throw new Error(`Arc mark "${e.id}" requires quantitative or categorical theta.`);return t}function G(e,t){if(e?.type!=="linear"||!Array.isArray(e.range)||e.range.length!==2||!e.range.every(Number.isFinite)||e.range[0]===e.range[1])throw new Error(`${t} requires a resolved linear scale.`);return e}function L(e,t){if(e?.type!=="band"||!Array.isArray(e.domain)||!Array.isArray(e.range)||e.range.length!==2||!e.range.every(Number.isFinite)||e.range[0]===e.range[1]||!Number.isFinite(e.bandwidth)||e.bandwidth<=0)throw new Error(`${t} requires a resolved band scale.`);return e}function $(e,t){return t===void 0?e.map(()=>{}):b(e,t.field)}function F(e,t,r,n){if(!Array.isArray(e))throw new TypeError(`Arc theta ${n}s require rows.`);if(typeof t!="string"||t.length===0)throw new TypeError(`Arc theta ${n} must be a non-empty string.`);const s=e.map((u,a)=>{const i=u?.[t];if(!Number.isFinite(i)||i<0)throw new TypeError(`Arc theta ${n} field "${t}" must contain non-negative finite numbers at row ${a}.`);return i});if(s.every(u=>u===0))throw new Error(`Arc mark "${r}" theta ${n}s must have a positive total.`);return R(s)}function N(e,t,r="arc"){return F(e,t,r,"weight")}function V(e,t,r="arc"){return F(e,t,r,"value")}function Q(e,t,r){const n=e.reduce((c,d)=>c+d,0),s=Number.isFinite(n)?void 0:_(e,"Arc theta values");if(n===0||s?.total<=0)throw new Error("Arc theta values must have a positive total.");const u=t[1]-t[0];let a=t[0],i=0,o=0;return e.map((c,d)=>{const h=s===void 0?c:c/s.scale,v=i+h;s!==void 0&&(o+=Math.abs(i)>=Math.abs(h)?i-v+h:h-v+i),i=v;const p=a+c/n*u,l=d===e.length-1?t[1]:s===void 0&&Number.isFinite(p)?p:S(t[0],t[1],(i+o)/(s?.total??n));if(!Number.isFinite(l)||l===a)throw new RangeError(`Arc theta ${r(d)} cannot resolve a distinct finite sector.`);const m={startTheta:a,endTheta:l};return a=l,m})}function W(e,t,r){if(!Number.isFinite(t?.availableRadius)||t.availableRadius<0)throw new RangeError(`Arc mark "${e.id}" requires a finite available radius.`);return{innerRadius:U(r,t.availableRadius),outerRadius:t.availableRadius}}function D(e,t,r,n,s){const u=t.encoding.theta,a=u.fieldType==="quantitative";if(!a&&!["count","sum"].includes(u.aggregate))throw new Error(`Arc mark "${t.id}" requires count, sum, or radial layout.`);const i=a?V(e,u.field,t.id):u.aggregate==="count"?e.map(()=>1):N(e,u.weight,t.id),o=a?e.map((g,w)=>w):b(e,u.field),c=$(e,t.encoding?.color),d=new Map(z(o,i).map(g=>[g.key,g])),h=a?o:r.domain,v=new Set(h);for(const g of d.keys())if(!v.has(g))throw new Error(`Arc theta value "${g}" is outside the scale domain.`);const p=h.filter(g=>d.get(g)?.values.some(w=>w>0)),l=g=>a?`row ${p[g]}`:`group "${String(p[g])}"`,m=p.map((g,w)=>a?i[g]:q(d.get(g).values,`Arc theta ${l(w)} aggregate`)),f=Q(m,r.range,l),A=W(t,n,s);return p.map((g,w)=>{const E=d.get(g),T=[...new Set(E.sourceIndices.map(O=>c[O]))];if(T.length>1)throw new Error(`Aggregated arc theta group "${g}" must resolve to one color value.`);return{key:a?`${String(i[g])}:${g}`:g,theta:a?i[g]:g,count:E.sourceIndices.length,aggregateValue:m[w],color:T[0],...f[w],...A,sourceIndices:E.sourceIndices}})}function x(e,t,r){const n=t.aggregate==="count"?e.map(()=>1):I(e,t.field);return z(r,n)}function z(e,t){const r=new Map;for(const[n,s]of e.entries()){const u=r.get(s)??{key:s,sourceIndices:[],values:[]};u.sourceIndices.push(n),u.values.push(t[n]),r.set(s,u)}return[...r.values()]}function H(e,t){const r=k(t),n=t.encoding?.radius;if(!["nominal","ordinal"].includes(r.fieldType)||r.aggregate!==void 0||!["count","sum"].includes(n?.aggregate)||n.fieldType!=="quantitative")throw new Error("Measured Arc requires equal-angle categorical theta and count or sum radius.");if(n.aggregate==="count"&&Object.hasOwn(n,"field"))throw new Error("Measured count radius does not accept a field.");const s=b(e,r.field),u=$(e,t.encoding?.color),a=x(e,n,s);if(a.some(o=>o.values.some(c=>c<0)))throw new RangeError("Measured Arc radius inputs must be non-negative.");const i=a.map(o=>{const c=[...new Set(o.sourceIndices.map(d=>u[d]))];if(c.length>1)throw new Error(`Measured Arc category "${o.key}" must resolve to one color value.`);return{key:o.key,theta:o.key,count:o.sourceIndices.length,radius:q(o.values,"Measured Arc radius aggregate"),color:c[0],sourceIndices:o.sourceIndices}});if(!i.some(o=>o.radius>0))throw new Error("Measured Arc radius requires at least one positive category aggregate.");return R(i)}function J(e,t,r,n){const s=H(e,t),u=M(s.map(c=>c.theta),r),a=y(s.map(c=>c.radius),n),i=(Math.sign(r.step)||1)*r.bandwidth/2,o=new Map(s.map((c,d)=>[c.theta,{...c,startTheta:u[d]-i,endTheta:u[d]+i,innerRadius:n.range[0],outerRadius:a[d]}]));return r.domain.flatMap(c=>{const d=o.get(c);return d===void 0||d.radius===0?[]:[d]})}function K(e,t,r,n){const s=t.encoding.theta,u=t.encoding?.radius;if(u?.fieldType!=="quantitative")throw new Error(`Arc mark "${t.id}" requires quantitative radius.`);const a=b(e,s.field),i=I(e,u.field),o=$(e,t.encoding?.color),c=M(a,r),d=y(i,n),h=Math.min(...n.range),p=(Math.sign(r.step)||1)*r.bandwidth/2,l=new Map(r.domain.map(f=>[f,[]]));for(let f=0;f<e.length;f+=1){if(d[f]<=h)continue;const A=l.get(a[f]);if(A===void 0)throw new Error(`Arc theta value "${a[f]}" is outside the scale domain.`);A.push({key:`${String(a[f])}:${f}`,theta:a[f],radius:i[f],color:o[f],startTheta:c[f]-p,endTheta:c[f]+p,innerRadius:h,outerRadius:d[f],sourceIndices:[f]})}const m=[];for(const f of r.domain){const A=l.get(f);A.sort((g,w)=>w.outerRadius-g.outerRadius||g.sourceIndices[0]-w.sourceIndices[0]),m.push(...A)}return m}function re(e,t,{thetaScale:r,radiusScale:n,frame:s,innerRadius:u=0}={}){if(!Array.isArray(e))throw new TypeError("Arc derivation requires rows.");const a=k(t);C(u);const i=n?.radialMapping!==void 0,o=a.fieldType==="quantitative",c=(o&&!i?G:L)(r,`Arc mark "${t.id}" theta`);let d=i?J(e,t,c,n):o||["count","sum"].includes(a.aggregate)?D(e,t,c,s,u):K(e,t,c,n);if(n!==void 0&&!i&&(o||a.aggregate!==void 0)){const h=X(e,t),v=y(h.map(l=>l.radius),n),p=new Map(h.map((l,m)=>[l.sourceIndices[0],{radius:l.radius,outerRadius:v[m]}]));d=d.map(l=>{const m=p.get(l.sourceIndices[0]);if(m===void 0||!Number.isFinite(m.outerRadius)||m.outerRadius<=l.innerRadius)throw new RangeError("Arc outer radius must exceed inner radius.");return{...l,...m}})}return R({sectors:d})}function C(e){if(B(e)){if(P(e,["unit","value"],"Arc innerRadius"),e.unit!=="px")throw new RangeError("Arc innerRadius unit must be px.");return R({unit:"px",value:j(e.value,"Arc innerRadius")})}if(!Number.isFinite(e)||e<0||e>=1)throw new RangeError("Arc innerRadius must be from 0 (inclusive) to 1 (exclusive).");return e}function U(e,t){const r=C(e);if(typeof r=="number")return r*t;if(r.value>=t)throw new RangeError("Arc pixel innerRadius must be smaller than its outer radius.");return r.value}function X(e,t){const r=t.encoding?.theta,n=t.encoding?.radius;if(r===void 0)return[];const s=r.fieldType==="quantitative";if(s?n.aggregate!==void 0:!["count","sum"].includes(r.aggregate))throw new Error("Grouped arc radius requires aggregated categorical theta.");const u=s?V(e,r.field,t.id):r.aggregate==="count"?e.map(()=>1):N(e,r.weight,t.id),a=s?e.map((i,o)=>o):b(e,r.field);return x(e,n,a).filter(i=>i.sourceIndices.some(o=>u[o]>0)).map(({sourceIndices:i,values:o})=>{if(n.aggregate===void 0&&new Set(o).size!==1)throw new Error("Arc radius requires one value per theta group or explicit aggregation.");return{sourceIndices:i,radius:n.aggregate===void 0?o[0]:q(o,"Arc radius aggregate")}})}export{re as deriveArcSectors,H as deriveMeasuredArcValues,X as deriveProportionalArcRadiusValues,C as normalizeArcInnerRadius,V as readArcThetaValues,N as readArcThetaWeights,U as resolveArcInnerRadius};

package/src/grammar/areaPaint.js

@@ -0,0 +1,10 @@
+import { isLinearGradientPaint, validateFillPaint } from "./paint.js";
+
+// Area fill shares the concrete paint grammar; outlines remain solid colors.
+export function validateAreaPaintConfig(config) {
+  if (config.fill !== undefined) validateFillPaint(config.fill, "Area fill");
+  if (config.strokeFromFill === true && isLinearGradientPaint(config.fill)) {
+    throw new Error("Area stroke-from-fill requires a solid fill; specify a solid stroke for a gradient area.");
+  }
+  return config;
+}

package/src/grammar/areaSeries.js

@@ -13,30 +13,31 @@ function indexSegments(segments) {
   return indexed;
 }
 
-export function deriveAreaSeries(rows, layer) {
+export function deriveAreaSeries(rows, layer, options = {}) {
   if (layer?.mark?.type !== "area") {
     throw new Error("Area series derivation requires a semantic area mark.");
   }
   const { x, y, x2, y2 } = layer.encoding ?? {};
   const vertical =
-    ["quantitative", "temporal"].includes(x?.fieldType) &&
+    ["quantitative", "temporal", "nominal", "ordinal"].includes(x?.fieldType) &&
     y?.fieldType === "quantitative" &&
     y2?.fieldType === "quantitative" &&
     x2 === undefined;
   const horizontal =
-    ["quantitative", "temporal"].includes(y?.fieldType) &&
+    ["quantitative", "temporal", "nominal", "ordinal"].includes(y?.fieldType) &&
     x?.fieldType === "quantitative" &&
     x2?.fieldType === "quantitative" &&
     y2 === undefined;
   if (vertical === horizontal) {
     throw new Error(
-      `Area mark "${layer.id}" requires exactly one quantitative x/x2 or y/y2 range and one quantitative or temporal independent position.`
+      `Area mark "${layer.id}" requires exactly one quantitative x/x2 or y/y2 range and one quantitative, temporal, or categorical independent position.`
     );
   }
   const grouping = validatePathSeriesAppearance(rows, layer);
   const orientation = vertical ? "vertical" : "horizontal";
   const independent = vertical ? x : y;
-  const independentValues = independent.fieldType === "temporal"
+  const categorical = ["nominal", "ordinal"].includes(independent.fieldType);
+  const independentValues = categorical ? readNominalField(rows, independent.field) : independent.fieldType === "temporal"
     ? readTemporalField(rows, independent.field, independent.temporalUnit)
     : readQuantitativeField(rows, independent.field);
   if (Object.hasOwn(independent, "datum")) throw new Error("Area independent position requires a field.");
@@ -46,6 +47,9 @@ export function deriveAreaSeries(rows, layer) {
   const missing = layer.mark.missing ?? "error";
   const lower = readAreaEndpoint(rows, primary, missing);
   const upper = readAreaEndpoint(rows, secondary, missing);
+  const categoryOrder = categorical ? options[vertical ? "xDomain" : "yDomain"] ?? [...new Set(independentValues)] : undefined;
+  const ranks = new Map(categoryOrder?.map((value, index) => [value, index]));
+  if (categorical && independentValues.some(value => !ranks.has(value))) throw new Error("Area categorical domain must contain every observed position.");
   const pathOrder = layer.encoding?.pathOrder;
   const orderValues = pathOrder === undefined
     ? undefined
@@ -83,7 +87,7 @@ export function deriveAreaSeries(rows, layer) {
   const series = [...groups.values()].flatMap(item => {
     const key = vertical ? "x" : "y";
     const values = pathOrder === undefined
-      ? item.values.sort((left, right) => left[key] - right[key])
+      ? item.values.sort((left, right) => categorical ? ranks.get(left[key]) - ranks.get(right[key]) : left[key] - right[key])
       : stableOrderPathValues(
           item.values.map(({ pathOrder: _pathOrder, ...value }) => value),
           item.values.map(value => value.pathOrder),
@@ -125,13 +129,13 @@ export function deriveAreaSeries(rows, layer) {
   });
 }
 
-export function deriveCenteredAreaSeries(rows, layer) {
+export function deriveCenteredAreaSeries(rows, layer, options = {}) {
   if (layer?.mark?.type !== "area") {
     throw new Error("Centered area series derivation requires an area mark.");
   }
   const { x, y, x2, y2, group, color } = layer.encoding ?? {};
   if (
-    !["quantitative", "temporal"].includes(x?.fieldType) ||
+    !["quantitative", "temporal", "nominal", "ordinal"].includes(x?.fieldType) ||
     y?.fieldType !== "quantitative" ||
     y?.stack !== "center" ||
     x2 !== undefined ||
@@ -149,7 +153,8 @@ export function deriveCenteredAreaSeries(rows, layer) {
       `Centered area color on mark "${layer.id}" must match its group field.`
     );
   }
-  const xValues = x.fieldType === "temporal"
+  const categorical = ["nominal", "ordinal"].includes(x.fieldType);
+  const xValues = categorical ? readNominalField(rows, x.field) : x.fieldType === "temporal"
     ? readTemporalField(rows, x.field, x.temporalUnit)
     : readQuantitativeField(rows, x.field);
   const yValues = readQuantitativeField(rows, y.field);
@@ -172,7 +177,10 @@ export function deriveCenteredAreaSeries(rows, layer) {
     values.set(xValues[index], yValues[index]);
     positions.add(xValues[index]);
   }
-  const orderedPositions = [...positions].sort((left, right) => left - right);
+  const orderedPositions = categorical
+    ? (options.xDomain ?? [...positions]).filter(value => positions.has(value))
+    : [...positions].sort((left, right) => left - right);
+  if (orderedPositions.length !== positions.size) throw new Error("Area categorical domain must contain every observed position.");
   if (groupOrder.length === 0 || orderedPositions.length < 2) {
     throw new Error(
       `Centered area mark "${layer.id}" requires at least two aligned positions.`

package/src/grammar/axisTextPlacement.js

@@ -0,0 +1 @@
+import{resolveTextLines as o}from"../core/textMetrics.js";function a(e,{title:i=!1}={}){if(Object.hasOwn(e,"align")&&!["left","center","right"].includes(e.align))throw new TypeError("Axis text align must be left, center, or right.");if(i){if(Object.hasOwn(e,"baseline")&&!["top","hanging","middle","alphabetic","ideographic","bottom"].includes(e.baseline))throw new TypeError("Axis title baseline must be a supported text baseline.");for(const t of["offset","alongOffset"])if(Object.hasOwn(e,t)&&!Number.isFinite(e[t]))throw new TypeError(`Axis title ${t} must be a finite number.`)}}function f(e,i){if(!/[\r\n]/u.test(e))return;const t=i.baseline??"middle",n=o(e,{fontSize:i.fontSize,align:i.align??"center",baseline:t,...t==="middle"?{blockAlign:"middle"}:{}});if(["bottom","ideographic"].includes(t)){const s=(n.length-1)*i.fontSize*1.2;return n.map(r=>({...r,y:r.y-s}))}return n.length>1?n:void 0}export{f as axisTitleTextLines,a as validateAxisTextPlacement};

package/src/grammar/bars/geometry.js

@@ -1,3 +1,6 @@
+import { validateOptionObject } from "../../core/validation.js";
+import { floorUtcTimeUnit, offsetUtcTimeUnit, TIME_UNITS, validTimestamp } from "../timeUnit.js";
+import { mapContinuousScaleValues } from "../scales/mapping.js";
 import { cloneAndFreeze } from "../../core/immutable.js";
 
 export const DEFAULT_BAR_WIDTH = Object.freeze({ band: 0.72 });
@@ -9,8 +12,16 @@ export const DEFAULT_OFFSET_PADDING = Object.freeze({
 export function normalizeBarWidth(options = {}, existing) {
   const hasBand = options.band !== undefined;
   const hasPixels = options.pixels !== undefined;
-  if (hasBand && hasPixels) {
-    throw new Error("encodeBarWidth band and pixels are mutually exclusive.");
+  const hasInterval = options.interval !== undefined;
+  if (Number(hasBand) + Number(hasPixels) + Number(hasInterval) > 1) {
+    throw new Error("encodeBarWidth band, pixels, and interval are mutually exclusive.");
+  }
+  if (hasInterval) {
+    validateOptionObject(options.interval, ["unit", "insetStart", "insetEnd"], "Bar width interval");
+    const { unit, insetStart = 0, insetEnd = 0 } = options.interval;
+    if (!TIME_UNITS.includes(unit) || ["week", "weekday"].includes(unit)) throw new Error("Bar width interval requires year, quarter, month, day, hour, minute, or second.");
+    if (![insetStart, insetEnd].every(v => Number.isFinite(v) && v >= 0)) throw new RangeError("Bar interval insets must be non-negative finite pixels.");
+    return cloneAndFreeze({ interval: { unit, insetStart, insetEnd } });
   }
   if (!hasBand && !hasPixels) {
     return cloneAndFreeze(existing ?? DEFAULT_BAR_WIDTH);
@@ -90,9 +101,25 @@ export function normalizeOffsetScalePolicy(
 }
 
 export function resolveBarWidth(config, slotBandwidth) {
+  const normalized = normalizeBarWidth(config);
+  if (normalized.pixels !== undefined) return normalized.pixels;
   if (!Number.isFinite(slotBandwidth) || slotBandwidth <= 0) {
     throw new Error("Bar width requires a positive resolved slot bandwidth.");
   }
-  const normalized = normalizeBarWidth(config);
   return normalized.pixels ?? slotBandwidth * normalized.band;
 }
+
+
+// Width intent never buckets or aggregates data: category values are interval starts.
+export function resolveBarInterval(config, value, scale) {
+  if (scale.type !== "time") throw new Error("Bar interval width requires a temporal category scale.");
+  const { unit, insetStart, insetEnd } = normalizeBarWidth(config).interval;
+  const start = floorUtcTimeUnit(value, unit);
+  if (start !== value) throw new Error("Bar interval category values must be UTC interval starts.");
+  const end = offsetUtcTimeUnit(start, unit);
+  if (!validTimestamp(end)) throw new RangeError("Bar interval end exceeds the supported Date range.");
+  if (start < Math.min(...scale.domain) || end > Math.max(...scale.domain)) throw new RangeError("Bar interval endpoints must be inside the temporal scale domain; set an explicit covering domain.");
+  const [a, b] = mapContinuousScaleValues([start, end], scale), width = Math.abs(b - a) - insetStart - insetEnd;
+  if (width <= 0) throw new RangeError("Bar interval insets must leave a positive width.");
+  return { position: Math.min(a, b) + (b >= a ? insetStart : insetEnd), width };
+}

package/src/grammar/bars/policy.js

@@ -3,6 +3,7 @@ import { isAggregate } from "../aggregate.js";
 export const BAR_GRAINS = Object.freeze({
   histogram: "histogram",
   aggregate: "aggregate",
+  centered: "centered",
   ranged: "ranged"
 });
 
@@ -20,10 +21,17 @@ function isMeasure(encoding) {
     isAggregate(encoding.aggregate);
 }
 
+function hasNumericCenters(layer) {
+  return layer.mark.orientation !== undefined && [layer.encoding?.x, layer.encoding?.y].every(
+    encoding => encoding?.fieldType === "quantitative" && encoding.bin === undefined && encoding.aggregate === undefined
+  );
+}
+
 export function resolveBarOrientation(layer) {
   if (layer?.mark?.type !== "bar") return undefined;
   const x = layer.encoding?.x;
   const y = layer.encoding?.y;
+  if (hasNumericCenters(layer)) return layer.mark.orientation;
   if (x?.bin !== undefined && y?.aggregate === "count") {
     return BAR_ORIENTATIONS.vertical;
   }
@@ -56,6 +64,8 @@ export function resolveBarGrain(layer) {
   const x = layer.encoding?.x;
   const y = layer.encoding?.y;
 
+  if (hasNumericCenters(layer)) return BAR_GRAINS.centered;
+
   if (
     x?.bin !== undefined &&
     y?.aggregate === "count"
@@ -80,7 +90,7 @@ export function inferBarColorLayout(layer) {
   const grain = resolveBarGrain(layer);
   if (grain === BAR_GRAINS.histogram) return "stack";
   if (grain === BAR_GRAINS.aggregate) return "group";
-  if (grain === BAR_GRAINS.ranged) return "overlay";
+  if (grain === BAR_GRAINS.ranged || grain === BAR_GRAINS.centered) return "overlay";
   return undefined;
 }
 
@@ -89,6 +99,7 @@ export function resolveBarColorLayout(layer) {
   if (layer?.encoding?.color?.layout !== undefined) {
     return layer.encoding.color.layout;
   }
+  if (resolveBarGrain(layer) === BAR_GRAINS.centered) return "overlay";
   const channels = resolveBarChannels(layer);
   if (layer?.encoding?.[channels?.measure]?.stack === "normalize") return "fill";
   const offsetChannel = resolveBarOffsetChannel(layer);

package/src/grammar/bin.js

@@ -1,3 +1,5 @@
+import { rejectUnknownProperties as rejectUnknownKeys } from "../core/validation.js";
+import { requireStringValue as requireField } from "../core/validation.js";
 import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
 import {
   findHistogramBinIndex,
@@ -20,19 +22,7 @@ const TRANSFORM_KEYS = Object.freeze([
 const AS_KEYS = Object.freeze(["lower", "upper", "count", "members"]);
 const RESOLVED_KEYS = Object.freeze(["domain", "step", "boundaries"]);
 
-function rejectUnknownKeys(value, supported, label) {
-  const unknown = Object.keys(value).find(key => !supported.includes(key));
-  if (unknown !== undefined) {
-    throw new Error(`Unknown ${label} property "${unknown}".`);
-  }
-}
 
-function requireField(value, label) {
-  if (typeof value !== "string" || value.length === 0) {
-    throw new TypeError(`${label} must be a non-empty string.`);
-  }
-  return value;
-}
 
 function normalizeAs(field, value, members) {
   const requested = value ?? {};

package/src/grammar/bin2d.js

@@ -1,3 +1,4 @@
+import { rejectUnknownProperties as rejectUnknownKeys } from "../core/validation.js";
 import {
   cloneAndFreeze,
   isPlainObject
@@ -18,12 +19,6 @@ const RESOLVED_KEYS = Object.freeze([
   "extent", "edges", "eligibleCount", "occupiedCount"
 ]);
 
-function rejectUnknownKeys(value, supported, label) {
-  const unknown = Object.keys(value).find(key => !supported.includes(key));
-  if (unknown !== undefined) {
-    throw new Error(`Unknown ${label} property "${unknown}".`);
-  }
-}
 
 function requirePositiveInteger(value, label) {
   if (!Number.isInteger(value) || value <= 0) {