expressive-charts 0.9.0 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -918,8 +918,19 @@ interface ChartSwitchView {
918
918
  */
919
919
  keyOf?(element: Element): string | undefined;
920
920
  /**
921
- * Hides (true) or shows again (false) the marks and labels the switch draws in its overlay, while
922
- * a switch plays: called as `element` takes `ec-morphing`, and as it loses it or the switch is
921
+ * The parts of the chart that can stay put through a switch: an axis, a grid, a tick, each an
922
+ * element in `element` with a key of its own, read as each switch starts, before morphing(true). A
923
+ * guide stays on screen at full strength, where it is, while the switch plays, when the other view
924
+ * has a guide with its key drawn the same: the same markup in the same computed paint, with any ids
925
+ * left out, at the same place within 0.5 px and at the same scale and turn. The old view's is drawn
926
+ * until half way and the new view's from there, so one drawn the same doesn't change. Every other
927
+ * guide fades with its view. The switch draws each one as a copy in its overlay, so the view hides
928
+ * them while it plays, as it hides its marks. Without it, a view has none.
929
+ */
930
+ guides?(): readonly ChartSwitchGuide[];
931
+ /**
932
+ * Hides (true) or shows again (false) the marks, labels and guides the switch draws in its overlay,
933
+ * while a switch plays: called as `element` takes `ec-morphing`, and as it loses it or the switch is
923
934
  * destroyed mid-way. A host chart's marks don't have the class that hides a chart's. Without it,
924
935
  * the class hides them.
925
936
  */
@@ -944,6 +955,13 @@ interface ChartSwitchPaint {
944
955
  /** The width of the ring in `--ec-surface` the chart draws round the mark's filled shape, or round its end dot when it has one: 2 round a line chart's point and end dot. Unset: none. */
945
956
  readonly ring?: number;
946
957
  }
958
+ /** A part of a view's chart that stays put through a switch when the next view draws it the same: an axis, a grid, a tick. */
959
+ interface ChartSwitchGuide {
960
+ /** The element, in the view's `<svg>`: drawn as it is, with everything in it. */
961
+ readonly element: Element;
962
+ /** Its own key: it pairs with the other view's guide with this key, never with a mark or a label. */
963
+ readonly key: string;
964
+ }
947
965
  /**
948
966
  * Draws one view's chart in `container` and returns it. `colors` is the switch's assignment: pass it
949
967
  * to the chart as its `colors`, so a key has the same colour in every view and in the overlay.
@@ -973,8 +991,18 @@ interface ChartSwitchOptions<T extends ChartSwitchViews> {
973
991
  /** A polite live region that says the new view's label (its chart's `label`) after each switch. Default false. */
974
992
  readonly announce?: boolean;
975
993
  }
994
+ /** How show() switches. */
995
+ interface ChartSwitchShowOptions<T extends ChartSwitchViews> {
996
+ /**
997
+ * A view to stage the jump through. In Presentation (`motion.staged`), the switch plays from the
998
+ * view on show to `via`, then from `via` to the view, each a full switch, and lands once: focus
999
+ * follows its key into the view, and the view alone is announced. In Analysis and Off, and when
1000
+ * `via` is the view on show or the view itself, it switches straight there. Rejects for an unknown view.
1001
+ */
1002
+ readonly via?: ChartSwitchViewName<T>;
1003
+ }
976
1004
  interface ChartSwitch<T extends ChartSwitchViews> {
977
- /** The view shown, or the one a switch is heading for. */
1005
+ /** The view shown, or the one a switch is heading for: a staged jump's view from its start. */
978
1006
  readonly current: ChartSwitchViewName<T>;
979
1007
  /**
980
1008
  * Switches to `view`: each mark morphs into the mark with its key, by the motion mode. Resolves
@@ -982,8 +1010,15 @@ interface ChartSwitch<T extends ChartSwitchViews> {
982
1010
  * a switch is leaving reverses it from where the shapes are; one to a third view lands the switch
983
1011
  * first. With motion off, the switch has landed when show() returns. Rejects for an unknown view.
984
1012
  * One a `leave` listener calls as the old view's hover ends runs once the switch has begun.
985
- */
986
- show(view: ChartSwitchViewName<T>): Promise<void>;
1013
+ *
1014
+ * With `via`, in Presentation, the jump is staged through that view, and `current` is `view` from
1015
+ * the start. A show() for `view` plays on. One in the first leg drops the leg still to come and acts
1016
+ * on the one playing, as on any switch: back to the view it began in, it reverses; to `via`, it plays
1017
+ * on and stops there; to another view, it lands on `via` and switches on from there, by that show()'s
1018
+ * own `via`. The second leg is a switch from `via` to `view`, as any other. Motion turning off, or a
1019
+ * resize, lands the jump on `view` at once.
1020
+ */
1021
+ show(view: ChartSwitchViewName<T>, options?: ChartSwitchShowOptions<T>): Promise<void>;
987
1022
  /** The chart a view's function returned: for update(), on() and the rest. */
988
1023
  chart<K extends ChartSwitchViewName<T>>(view: K): ReturnType<T[K]>;
989
1024
  /**
@@ -1011,6 +1046,13 @@ interface HostLabel {
1011
1046
  /** "category": the mark's name (a slice's outside label, a column's name). "value": its value. */
1012
1047
  readonly role: "category" | "value";
1013
1048
  }
1049
+ /** A part of the host's drawing that a chart switch keeps where it is when the next view draws it the same: an axis, a grid, a tick. */
1050
+ interface HostGuide {
1051
+ /** An element in the host's `<svg>`, drawn as it is, with everything in it. */
1052
+ readonly element: Element;
1053
+ /** Its own key: it pairs with the next view's guide with this key, never with a mark or a label. */
1054
+ readonly key: string;
1055
+ }
1014
1056
  interface HostViewOptions {
1015
1057
  /**
1016
1058
  * The host's labels, each a `<text>` in its `<svg>` with its mark's key and its role, read as each
@@ -1020,15 +1062,28 @@ interface HostViewOptions {
1020
1062
  * Default: none.
1021
1063
  */
1022
1064
  readonly labels?: () => Iterable<HostLabel>;
1065
+ /**
1066
+ * The host's guides (an axis, a grid, a tick), each an element in its `<svg>` with a key of its
1067
+ * own, read as each switch starts. One whose key the next view's guides have too stays on screen at
1068
+ * full strength, where it is, while the switch plays, when the two are drawn the same; every other
1069
+ * fades with its view. One that isn't in the `<svg>`, or has no key, is left out, and so is
1070
+ * everything if it throws (reported). Default: none.
1071
+ */
1072
+ readonly guides?: () => Iterable<HostGuide>;
1023
1073
  }
1024
- /** An attachment as a chart switch's view: the attachment's own methods, with the view's. */
1074
+ /**
1075
+ * An attachment, or several on one `<svg>`, as a chart switch's view: the attachment's own methods, or
1076
+ * each of theirs, with the view's.
1077
+ */
1025
1078
  interface HostView<D> extends Attachment<D>, ChartSwitchView {
1026
- /** The host's root `<svg>`. Its `aria-label` is what a switch's `announce` says. */
1079
+ /** The host's root `<svg>`, which its attachments share. Its `aria-label` is what a switch's `announce` says. */
1027
1080
  readonly element: SVGSVGElement;
1028
- /** The marks' nearest common ancestor, whose space marks() and labels() are in. */
1081
+ /** The marks' nearest common ancestor, whose space marks() and labels() are in: every attachment's marks'. */
1029
1082
  readonly space: Element;
1030
1083
  /** The labels `labels` gives, as a switch draws them: at their anchor, in the host text's computed font and fill. */
1031
1084
  labels(): readonly ChartLabel[];
1085
+ /** The guides `guides` gives: each the host's own element, with its key. */
1086
+ guides(): readonly ChartSwitchGuide[];
1032
1087
  /** The host's colour for the mark, its fill or its stroke on a line, as its first part draws it. */
1033
1088
  paintOf(key: string): ChartSwitchPaint | undefined;
1034
1089
  keyOf(element: Element): string | undefined;
@@ -1043,6 +1098,15 @@ interface HostView<D> extends Attachment<D>, ChartSwitchView {
1043
1098
  * anything else, or on an attachment with no marks yet, which has no `<svg>`.
1044
1099
  */
1045
1100
  export declare function hostView<D>(attachment: Attachment<D>, options?: HostViewOptions): HostView<D>;
1101
+ /**
1102
+ * Makes several attachments on one `<svg>` one view for chartSwitch, as a chart drawn with several
1103
+ * (a dumbbell's dots and its connectors) is one chart: its marks are all of theirs, and each mark's
1104
+ * focus, tab stop, colour and hiding go to the attachment it's from. Its rows are theirs, as a union.
1105
+ * Throws a TypeError, naming it, on anything but attachments with marks, on two in different `<svg>`s,
1106
+ * and on a key two of them give a mark: key each one's marks apart (`first@Okafor`). An array of one
1107
+ * makes that attachment's view.
1108
+ */
1109
+ export declare function hostView<A extends Attachment<unknown>>(attachments: readonly A[], options?: HostViewOptions): HostView<RowsOf<A>>;
1046
1110
  /**
1047
1111
  * What fromVegaView() uses of a Vega View: its renderer, its scenegraph and the element it renders
1048
1112
  * into. The scenegraph is read as `{ root }` (what Vega returns) or as the root mark itself (what
@@ -1411,6 +1475,14 @@ interface MorphOptions {
1411
1475
  * where that place is outside it or near its edge. Where it would leave the shape on the way, it
1412
1476
  * closes sooner, as soon as a sixteenth of the way. Each is written the other way round from the
1413
1477
  * outside, so it stays a hole under either fill rule.
1478
+ * - **Two bands across the same x's** (closed outlines whose longest loop, with no arc, splits at its
1479
+ * leftmost and rightmost points into an upper run and a lower run, each going one way across x in
1480
+ * two straight pieces or more, as d3.area() draws an area; the two bands' leftmost x's within
1481
+ * 0.01 px, and their rightmost) pair by x: upper run with upper and lower with lower, each as two
1482
+ * lines across x pair, by share of its span, with stops at `points` shares and at each vertex of
1483
+ * either run. So two areas over the same weeks keep each week's x on every frame, corners pair with
1484
+ * corners, and the edges at each end join the runs as they move. `align` doesn't turn them. Holes
1485
+ * morph as above. A rectangle's top and base are a piece each, so bars aren't bands.
1414
1486
  * - **Two lines that each run one way across x** (every vertex's x more than the one before, or
1415
1487
  * every one less, the same way for both) pair by x: the point a share of the way across one
1416
1488
  * line's x span moves to the point that share across the other's. They're sampled at `points`
@@ -1541,7 +1613,7 @@ export declare function registerIcons(icons: readonly Icon[]): void;
1541
1613
  * has the same rules. For a CSP that allows no inline styles at all.
1542
1614
  */
1543
1615
  export declare function configure(options: StyleOptions): void;
1544
- export declare const VERSION = "0.9.0";
1616
+ export declare const VERSION = "0.11.0";
1545
1617
  /**
1546
1618
  * A bar chart in `target` (an element or a selector). The axis whose values aren't numbers is the
1547
1619
  * category; `stack` stacks numeric fields; `on` attaches effects by slot.
@@ -1562,8 +1634,9 @@ export declare function lineChart<D>(target: string | Element, options: LineChar
1562
1634
  /**
1563
1635
  * Views of the same data in `target` (an element or a selector), one shown at a time: `show(view)`
1564
1636
  * turns each mark into the mark with its key in the other view with `transition`, morph() by default,
1565
- * while the labels move and swap their text. Each view's function draws its chart in the container
1566
- * it's given; pass it the `colors` it's given too, so a key keeps its colour from view to view.
1637
+ * while the labels move and swap their text, and `show(view, { via })` stages a jump through a third
1638
+ * view in Presentation. Each view's function draws its chart in the container it's given; pass it the
1639
+ * `colors` it's given too, so a key keeps its colour from view to view.
1567
1640
  */
1568
1641
  export declare function chartSwitch<T extends ChartSwitchViews>(target: string | Element, options: ChartSwitchOptions<T>): ChartSwitch<T>;
1569
1642
  /**
@@ -1586,5 +1659,4 @@ export declare function fromVegaView<D = Record<string, unknown>>(view: VegaView
1586
1659
  * page-wide `motion`. `persist: "key"` saves the choice in localStorage.
1587
1660
  */
1588
1661
  export declare function motionSwitch(target: string | Element, motion?: Motion, options?: MotionSwitchOptions): MotionSwitch;
1589
- export { type Accessor, type AnimateOptions, type Animated, type AnimatedOptions, type AnyMarkEffect, type ArcSpec, type Attachment, type BarChart, type BarChartOptions, type BarSegmentSpec, type BarSpec, type Baseline, type Chart, type ChartChange, type ChartLabel, type ChartOptions, type ChartSwitch, type ChartSwitchOptions, type ChartSwitchPaint, type ChartSwitchView, type ChartSwitchViewFactory, type ChartSwitchViewName, type ChartSwitchViews, type Clock, type Color, type ColorAssignment, type Combined, type DataEffect, type DataEffectSpec, type DeltaOptions, type DonutChart, type DonutChartOptions, type DrawInOptions, type Easing, type EffectContext, type EffectOption, type EffectSlot, type EffectSlots, type ExpressiveOptions, type FlashOptions, type FrameSource, type Gait, type GaitName, type GaitPose, type GaitState, type GeometryEffect, type GeometryEffectSpec, type HostLabel, type HostMark, type HostView, type HostViewOptions, type Icon, type IconHandle, type IconShape, type IconSource, type IconSpec, type Interpolator, type KeyOfType, type LabelOptions, type Layer, type LegendEntry, type LegendOptions, type LineChart, type LineChartOptions, type LineSpec, type Link, type LinkOptions, type LinkSource, type ManualClock, type MarkData, type MarkEffect, type MarkEvent, type MarkEvents, type MarkGeometry, type MarkHandle, type MarkSource, type MarkStyle, type MarkSummary, type Matrix, type MorphAlign, type MorphOptions, type Motion, type MotionEnv, type MotionMode, type MotionOptions, type MotionSwitch, type MotionSwitchOptions, type MotionView, type NumericKey, type Outline, type Paint, type PathHandle, type PlayButton, type PlayButtonOptions, type Playback, type PlaybackEvent, type PlaybackOptions, type Point, type PointSpec, type PresetName, type PulseOptions, type Rect, type ReducedMotionSource, type Sample, type SamplePoint, type ScalingOverrides, type ScalingRule, type ScalingTable, type SeekOptions, type ShapeSpec, type SliceSummary, type StaggerOptions, type StepOptions, type StyleOptions, type SvgIconSpec, type TableColumn, type TableOptions, type TextHandle, type TextSpace, type TextStyle, type ThresholdOptions, type Timing, type TraceOptions, type TransitionContext, type TransitionEffect, type TravelOptions, type Tween, type TweenOptions, type TweenResult, type VegaAttachment, type VegaItem, type VegaMark, type VegaOptions, type VegaSample, type VegaViewLike, type WiggleOptions, createClock, createMotion, defaultClock, defaultScaling, easeInOutCubic, easeOutCubic, linear, manualClock, mediaReducedMotion, motion, scaleDuration, tween };
1590
- //# sourceMappingURL=index.d.ts.map
1662
+ export { type Accessor, type AnimateOptions, type Animated, type AnimatedOptions, type AnyMarkEffect, type ArcSpec, type Attachment, type BarChart, type BarChartOptions, type BarSegmentSpec, type BarSpec, type Baseline, type Chart, type ChartChange, type ChartLabel, type ChartOptions, type ChartSwitch, type ChartSwitchGuide, type ChartSwitchOptions, type ChartSwitchPaint, type ChartSwitchShowOptions, type ChartSwitchView, type ChartSwitchViewFactory, type ChartSwitchViewName, type ChartSwitchViews, type Clock, type Color, type ColorAssignment, type Combined, type DataEffect, type DataEffectSpec, type DeltaOptions, type DonutChart, type DonutChartOptions, type DrawInOptions, type Easing, type EffectContext, type EffectOption, type EffectSlot, type EffectSlots, type ExpressiveOptions, type FlashOptions, type FrameSource, type Gait, type GaitName, type GaitPose, type GaitState, type GeometryEffect, type GeometryEffectSpec, type HostGuide, type HostLabel, type HostMark, type HostView, type HostViewOptions, type Icon, type IconHandle, type IconShape, type IconSource, type IconSpec, type Interpolator, type KeyOfType, type LabelOptions, type Layer, type LegendEntry, type LegendOptions, type LineChart, type LineChartOptions, type LineSpec, type Link, type LinkOptions, type LinkSource, type ManualClock, type MarkData, type MarkEffect, type MarkEvent, type MarkEvents, type MarkGeometry, type MarkHandle, type MarkSource, type MarkStyle, type MarkSummary, type Matrix, type MorphAlign, type MorphOptions, type Motion, type MotionEnv, type MotionMode, type MotionOptions, type MotionSwitch, type MotionSwitchOptions, type MotionView, type NumericKey, type Outline, type Paint, type PathHandle, type PlayButton, type PlayButtonOptions, type Playback, type PlaybackEvent, type PlaybackOptions, type Point, type PointSpec, type PresetName, type PulseOptions, type Rect, type ReducedMotionSource, type Sample, type SamplePoint, type ScalingOverrides, type ScalingRule, type ScalingTable, type SeekOptions, type ShapeSpec, type SliceSummary, type StaggerOptions, type StepOptions, type StyleOptions, type SvgIconSpec, type TableColumn, type TableOptions, type TextHandle, type TextSpace, type TextStyle, type ThresholdOptions, type Timing, type TraceOptions, type TransitionContext, type TransitionEffect, type TravelOptions, type Tween, type TweenOptions, type TweenResult, type VegaAttachment, type VegaItem, type VegaMark, type VegaOptions, type VegaSample, type VegaViewLike, type WiggleOptions, createClock, createMotion, defaultClock, defaultScaling, easeInOutCubic, easeOutCubic, linear, manualClock, mediaReducedMotion, motion, scaleDuration, tween };