@aceshooting/lyra-ui 1.2.0 → 2.1.0

package/dist/components/chart/lite-chart.d.ts

@@ -7,6 +7,13 @@ export interface LiteSeries {
     color?: string;
 }
 export type LyraLiteChartType = 'bar' | 'line';
+/**
+ * `'fit'` (default) squeezes the whole plot into the measured host width,
+ * exactly as this component always behaved. `'scroll'` gives every bar a
+ * fixed `barWidth` instead and lets the plot's content width exceed the
+ * host's, making the host horizontally scrollable.
+ */
+export type LyraLiteChartLayout = 'fit' | 'scroll';
 /**
  * `<lyra-lite-chart>` — a dependency-free bar/line chart, plain SVG/DOM
  * rendering with zero peer dependencies (unlike `lyra-chart`, which wraps
@@ -22,6 +29,33 @@ export type LyraLiteChartType = 'bar' | 'line';
  * `getComputedStyle()`-based re-theming step is needed the way `chart.ts`
  * needs one for its canvas.
  *
+ * By default (`layout="fit"`) the plot always squeezes to the measured host
+ * width. Three independent, opt-in escape hatches for dense/aligned data:
+ * `layout="scroll"` (+ `barWidth`) gives every bar a fixed pixel width and
+ * lets the plot overflow the host horizontally (scrollable) instead of
+ * squeezing; `maxLabels` decimates which x-axis text labels render (bars
+ * always still render) once there are more categories than that; and
+ * `barX` lets a consumer hand in its own per-category x-coordinate function
+ * — e.g. to pixel-align this chart's bars with a sibling `lyra-heatmap`'s
+ * calendar columns — overriding the internal slot math for both bars and
+ * their labels. All three are additive and no-ops when left unset.
+ *
+ * Seven further additive, opt-in properties: `pointText` overrides the
+ * per-bar/per-point `<title>`/`aria-label` tooltip text (mirrors
+ * `lyra-heatmap`'s `cellText` hook), falling back to the built-in raw-value
+ * template when unset; `roundedBars` draws bars as a rounded-top path
+ * instead of a square-cornered rect; `skipZero` omits a bar entirely (not
+ * just zero-height) for an exactly-`0` value; `padLeft`/`barGapRatio`
+ * override the internal `PAD_LEFT`/`BAR_GROUP_GAP` layout constants; `scale`
+ * (`type="bar"` only) switches the bar-height mapping from the default
+ * linear `niceDomain` fraction to a `Math.sqrt(value / domainMax)`
+ * compression (mirroring `lyra-heatmap`'s matrix-mode `sqrt` scale) so a
+ * skewed dataset's smaller bars don't get washed out by one dominant value
+ * — gridlines/tick labels stay on the linear domain regardless, only the bar
+ * marks' own height changes, and `type="line"` ignores `scale` entirely; and
+ * `hideAxis` suppresses `renderGrid()`'s gridlines/tick labels altogether
+ * (x-axis category labels, rendered separately, are unaffected).
+ *
  * @customElement lyra-lite-chart
  * @event lyra-point-click - Fired when a bar/point is activated (click, or
  *   Enter/Space while focused). `detail: { datasetIndex: number, index:
@@ -37,6 +71,8 @@ export type LyraLiteChartType = 'bar' | 'line';
  * @csspart legend - The legend row, when `legend` is set.
  * @csspart legend-item - Each legend entry.
  * @csspart legend-swatch - Each legend entry's color swatch.
+ * @csspart live-region - The current mark announcement for keyboard users.
+ * @csspart data-list - A visually hidden list of all plotted data points.
  */
 export declare class LyraLiteChart extends LyraElement {
     static styles: import("lit").CSSResultGroup[];
@@ -53,27 +89,122 @@ export declare class LyraLiteChart extends LyraElement {
     /** Formats a y-axis tick value for display (e.g. `(v) => \`$${v.toFixed(2)}\``). Falls back to the
      *  built-in nice-number formatter when unset. */
     tickFormat?: (value: number) => string;
+    /** `'fit'` (default) squeezes the plot into the measured host width, unchanged from before this
+     *  property existed. `'scroll'` gives every bar a fixed `barWidth` instead, letting the plot's
+     *  content width exceed the host's — the host becomes horizontally scrollable
+     *  (`overflow-x: auto`) so every bar stays exactly `barWidth` wide regardless of category count.
+     *  Reflects to the `layout` attribute (e.g. for `:host([layout='scroll'])` host styling). */
+    layout: LyraLiteChartLayout;
+    /** Fixed per-category bar width in px, used only when `layout="scroll"`. Ignored (as before this
+     *  property existed) in `layout="fit"`, the default. */
+    barWidth: number;
+    /** Caps how many x-axis category labels render text once `this.labels.length` exceeds it,
+     *  decimating roughly evenly while always keeping the first and last label. Bars themselves
+     *  always render regardless — only the axis text is decimated. Unset (the default) renders every
+     *  label, unchanged from before this property existed. Works in either `layout` mode. */
+    maxLabels?: number;
+    /** Overrides the x-origin `renderBars()`/the category labels would otherwise compute internally
+     *  for a given category index, for `type="bar"` only (bars and their axis labels stay
+     *  consistent with each other either way). Lets a consumer pixel-align this chart's bars with,
+     *  e.g., a sibling `lyra-heatmap`'s calendar columns by handing both components the same
+     *  coordinate function. Unset (the default) uses the existing internal per-category slot math,
+     *  unchanged from before this property existed. */
+    barX?: (index: number) => number;
+    /** Formats the per-bar/per-point `<title>`/`aria-label` tooltip text — receives the category
+     *  label, the raw value, and the dataset index. Falls back to the built-in raw-value template
+     *  when unset (mirrors `lyra-heatmap`'s `cellText` hook). */
+    pointText?: (label: string, value: number, datasetIndex: number) => string;
+    /** `type="bar"` only: draws each bar as a rounded-top-corner shape instead of the default
+     *  square-cornered rect. Default `false` renders exactly today's plain `<rect>`. */
+    roundedBars: boolean;
+    /** `type="bar"` only: omits a bar entirely (no mark, no `tabindex`, no tooltip) for a value that
+     *  is exactly `0` — `null`/non-finite values are always skipped regardless of this flag. Default
+     *  `false` preserves today's behavior of a zero-height but focusable/titled bar. */
+    skipZero: boolean;
+    /** Overrides the internal `PAD_LEFT` (36px) plot-left-padding constant. Unset (the default) keeps
+     *  today's fixed 36px. */
+    padLeft?: number;
+    /** Overrides the internal `BAR_GROUP_GAP` (0.2) fraction of a category slot left as a gap between
+     *  categories. Unset (the default) keeps today's fixed 0.2. */
+    barGapRatio?: number;
+    /** `type="bar"` only (no effect on `type="line"`): `'linear'` (default) maps a bar's value to
+     *  height via the standard `niceDomain`-based fraction, unchanged from before this property
+     *  existed. `'sqrt'` instead maps via `Math.sqrt(value / domainMax)` (mirroring `lyra-heatmap`'s
+     *  matrix-mode `sqrt` scale), boosting smaller values relative to one dominant value so a skewed
+     *  dataset's smaller bars don't get washed out. Gridlines/tick labels stay on the linear domain
+     *  either way — only the bar marks' own height mapping changes. */
+    scale: 'linear' | 'sqrt';
+    /** Suppresses `renderGrid()` entirely — no gridlines, no y-axis tick labels. x-axis category
+     *  labels (rendered separately) are unaffected. Default `false` preserves today's behavior. */
+    hideAxis: boolean;
     private plotWidth;
     private plotHeight;
     private visible;
+    /** One roving tab stop across all bar/point marks. */
+    private activeMarkIndex;
+    private liveText;
     private svgEl?;
     private resizeObserver?;
     private intersectionObserver?;
-    private lastSignature;
-    private lastResult?;
     connectedCallback(): void;
     disconnectedCallback(): void;
     protected firstUpdated(): void;
     protected updated(changed: PropertyValues): void;
     private colorFor;
+    /** Dispatches to the host-provided `pointText` formatter when set, otherwise `undefined` (the
+     *  caller falls back to its own built-in template) — mirrors `lyra-heatmap`'s `resolveCellText()`. */
+    private resolvePointText;
+    /** The ordered set of visible marks used by both keyboard navigation and
+     * the screen-reader data alternative. */
+    private interactiveMarks;
+    private markIndexMap;
+    private normalizedMarkIndex;
+    private markAnnouncement;
+    private onMarkFocus;
+    private focusMark;
+    /**
+     * A value-to-y-pixel mapping for a bar's top/bottom edge. `'linear'` (the
+     * default) is the standard `niceDomain`-fraction formula, unchanged from
+     * before `scale` existed. `'sqrt'` instead compresses via
+     * `Math.sqrt(value / domainMax)` (mirroring `lyra-heatmap`'s matrix-mode
+     * `sqrt` branch), clamping `value` to `[0, hi]` first since a negative
+     * input has no real square root — bar charts using `scale="sqrt"` are
+     * expected to carry non-negative data, same assumption as the heatmap
+     * precedent this mirrors.
+     */
+    private barValueToY;
+    /**
+     * A rounded-top-corners `<path>` `d` string for a bar occupying
+     * `[x, y, x+w, y+h]` — an SVG `<rect>` can only express a uniform radius
+     * on all four corners, so `roundedBars` switches the mark to a path
+     * instead of adding `rx`/`ry` to keep the bottom edge square against the
+     * baseline. `r` is clamped so it never exceeds half the bar's width or its
+     * full height (a thin/short bar degrades to a plain rectangle path rather
+     * than self-intersecting).
+     */
+    private roundedBarPath;
     private domain;
-    private computeSignature;
     private emitPoint;
     private onPointKeyDown;
     private renderGrid;
+    /**
+     * `slot` is the per-category width to lay bars out against — either the
+     * measured-width-derived `plotW / n` (`layout="fit"`) or the fixed
+     * `barWidth` (`layout="scroll"`), computed once by the caller
+     * (`renderChart()`) and handed to both this method and the category-label
+     * x-position calc so the two can never drift apart from each other.
+     */
     private renderBars;
     private renderLines;
     render(): TemplateResult;
+    /**
+     * Step size for `maxLabels` decimation: 1 (show every label, today's
+     * unchanged default) when `maxLabels` is unset or already >= the label
+     * count, otherwise the ceil-divide spacing that lands close to
+     * `maxLabels` shown labels while always keeping index 0 and the last
+     * index (enforced by the caller, not here).
+     */
+    private labelStep;
     private renderChart;
 }
 declare global {