@opendata-ai/openchart-core 6.27.0 → 6.27.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-core",
-  "version": "6.27.0",
+  "version": "6.27.2",
   "description": "Types, theme, colors, accessibility, and utilities for openchart",
   "license": "Apache-2.0",
   "author": "Riley Hilliard",

package/src/types/events.ts

@@ -64,6 +64,11 @@ export const elementRef = {
  * Fired by the `onEdit` callback when any editable chart element is modified.
  * Covers repositioning (drag), deletion (Delete key), and text editing (double-click).
  * Selection events (onSelect/onDeselect) are separate callbacks, not part of this union.
+ *
+ * For the `annotation` variant:
+ * - `annotation` is the ORIGINAL spec annotation (may have a stale or missing offset)
+ * - `offset` is the NEW accumulated position after the drag completes
+ * - To persist a drag edit back into your spec: `{ ...edit.annotation, offset: edit.offset }`
  */
 export type ElementEdit =
   | { type: 'annotation'; annotation: TextAnnotation; offset: AnnotationOffset }

package/src/types/spec.ts

@@ -321,7 +321,15 @@ export interface EncodingChannel {
    * - undefined | true | 'zero': stack from zero baseline (default)
    * - 'normalize': stack and normalize to fraction of total (0-1 per category)
    * - 'center': center stacks around zero (streamgraph style)
-   * - null | false: no stacking (grouped/dodged side-by-side)
+   * - null | false: no stacking -- renders grouped (side-by-side) bars instead
+   *
+   * Use `stack: null` to get grouped/dodged bars. This is the idiomatic way to
+   * compare values across categories side-by-side rather than stacked on top of
+   * each other. Without it, multi-series bar data stacks by default.
+   *
+   * @example
+   * // Side-by-side grouped bars (comparing 2018 vs 2022 wages by firm size):
+   * "x": { "field": "pay", "type": "quantitative", "stack": null }
    */
   stack?: boolean | 'zero' | 'normalize' | 'center' | null;
   /**