origam 2.2.1 → 2.5.0

package/dist/src/interfaces/Chart/chart-cartesian.interface.d.ts

@@ -0,0 +1,124 @@
+import type { IChartAnnotation, IChartBaseEmits, IChartBaseProps, IChartBaseSlots, IChartDrilldownLink, IChartDrilldownProps, IChartPlotBand, IChartPlotLine, IChartPoint, IChartRangeSelector, IChartSecondaryYAxis } from '../../interfaces';
+import type { TChartCartesianKind, TChartSmoothing, TChartStacking } from '../../types';
+/**
+ * Props for `<OrigamChartCartesian>` — the cartesian family
+ * component. Owns the X+Y plotting area (axes, grid, tick labels)
+ * AND the line / area / bar / column / scatter / spline /
+ * stepped-line topologies.
+ *
+ * Distinct from the legacy `<OrigamChart>` shell because it
+ * deliberately rejects polar / radar / gauge values — the `type`
+ * field is narrowed to `TChartCartesianKind`. Use the shell when
+ * you need runtime type switching across families; use this
+ * component when you want a tightly-typed cartesian surface.
+ */
+export interface IChartCartesianProps extends IChartBaseProps {
+    /** Cartesian visualisation primitive. Default `'line'`. */
+    type?: TChartCartesianKind;
+    /**
+     * Stack series on top of each other. Applies to `bar`,
+     * `column`, and (when combined) `area`. Default `false`.
+     */
+    stacked?: boolean;
+    /**
+     * Stacking mode when `stacked=true`.
+     *
+     * - `'normal'`  — raw absolute values (default).
+     * - `'percent'` — every stack normalised to 100 %; Y-axis fixed
+     *                 `0 → 100`, tick labels use `${v}%`.
+     */
+    stacking?: TChartStacking;
+    /**
+     * Smoothing strategy for `line` / `area` / `spline`.
+     * Default `'none'` for `line` / `area`, `'monotone'` for
+     * `spline` (overridable).
+     */
+    smoothing?: TChartSmoothing;
+    /** Override the auto-computed Y min. */
+    yMin?: number;
+    /** Override the auto-computed Y max. */
+    yMax?: number;
+    /** Render grid lines behind the plot. Default `true`. */
+    showGrid?: boolean;
+    /** Render X / Y axes + tick labels. Default `true`. */
+    showAxis?: boolean;
+    /** Toggle the hover tooltip. Default `true`. */
+    showTooltip?: boolean;
+    /** Formatter applied to X-axis tick labels. */
+    xAxisFormat?: (value: string | number) => string;
+    /** Formatter applied to Y-axis tick labels. */
+    yAxisFormat?: (value: number) => string;
+    /**
+     * Configuration for the secondary (right-hand) Y axis. When
+     * provided, series with `yAxis: 1` are projected against this
+     * scale. The axis is only rendered when at least one visible
+     * series uses `yAxis: 1` OR when this prop is explicitly set.
+     */
+    secondaryYAxis?: IChartSecondaryYAxis;
+    /**
+     * Coloured rectangular zones drawn behind (or above) the chart
+     * data. Cartesian-only. Bands with `layer='below'` (default)
+     * are drawn before the series paths; `layer='above'` after.
+     */
+    plotBands?: Array<IChartPlotBand>;
+    /**
+     * Threshold lines drawn at a fixed axis value. Cartesian-only.
+     * Lines default to `layer='above'` so they remain visible over
+     * data; set `layer='below'` to draw them behind.
+     */
+    plotLines?: Array<IChartPlotLine>;
+    /**
+     * Drilldown configuration. When provided, data points that carry
+     * an `IChartDrilldownLink` in their object-form entry trigger a
+     * chart-level navigation instead of (or alongside) `point-click`.
+     * A breadcrumb `<nav>` appears above the chart when depth > 1.
+     */
+    drilldown?: IChartDrilldownProps;
+    /**
+     * Enable zoom / pan interactions on the plot area.
+     *
+     * - Mouse-down + drag → draws a selection rectangle; release zooms
+     *   to that X range.
+     * - Shift + scroll-wheel → zooms in / out around the cursor X.
+     * - Ctrl + drag → pans left / right.
+     * - A "Reset zoom" button appears in the top-right when zoomed.
+     *
+     * Default `false`.
+     */
+    zoomable?: boolean;
+    /**
+     * Optional band-style range-selector toolbar rendered above the chart.
+     * Provides preset zoom buttons (`1w`, `1m`, `3m`, `6m`, `1y`, `all`).
+     * Requires `zoomable` to be `true` for full effect but can be used
+     * independently to set an initial window via `selected`.
+     */
+    rangeSelector?: IChartRangeSelector;
+    /**
+     * Overlay annotations drawn on top of the series layer. Annotations
+     * are positioned in data coordinates and projected to SVG pixel space
+     * at render time. Cartesian-only — non-cartesian chart families ignore
+     * this prop.
+     *
+     * Four kinds: `'arrow'`, `'label'`, `'circle'`, `'bracket'`.
+     */
+    annotations?: Array<IChartAnnotation>;
+}
+/** Emits surfaced by `<OrigamChartCartesian>`. Extends the family base with drilldown and zoom events. */
+export interface IChartCartesianEmits extends IChartBaseEmits {
+    /** Fired when the user drills into a sub-dataset. */
+    (e: 'drill', link: IChartDrilldownLink, point: IChartPoint): void;
+    /** Fired when the user navigates back one drilldown level. */
+    (e: 'drill-up'): void;
+    /**
+     * Fired on every committed zoom (drag-release, wheel stop, or range-selector
+     * button click). `start` and `end` are category indices (inclusive).
+     */
+    (e: 'zoom', range: {
+        start: number;
+        end: number;
+    }): void;
+    /** Fired when the user resets the zoom to the full data range. */
+    (e: 'reset-zoom'): void;
+}
+/** Slot signatures exposed by `<OrigamChartCartesian>`. */
+export type IChartCartesianSlots = IChartBaseSlots;

package/dist/src/interfaces/Chart/chart-drilldown.interface.cjs

@@ -0,0 +1 @@
+"use strict";

package/dist/src/interfaces/Chart/chart-drilldown.interface.d.ts

@@ -0,0 +1,60 @@
+import type { IChartSeries } from './chart-series.interface';
+/**
+ * Reference attached to a data point that signals a drilldown is
+ * available. When the user clicks a point that carries this link,
+ * the chart looks up the matching `IChartDrilldownDataset` by `id`
+ * and re-renders with the sub-dataset.
+ */
+export interface IChartDrilldownLink {
+    /** Identifier used to look up the matching dataset in `IChartDrilldownProps.datasets`. */
+    id: string;
+    /** Display name shown in the breadcrumb trail for this level. */
+    name?: string;
+}
+/**
+ * A named sub-dataset associated with a drilldown level. The chart
+ * swaps its active series + categories with these values when the
+ * user drills in to this entry.
+ */
+export interface IChartDrilldownDataset {
+    /** Unique identifier — must match `IChartDrilldownLink.id` on the parent point. */
+    id: string;
+    /** Human-readable name shown in the breadcrumb trail. */
+    name: string;
+    /** Series rendered when this dataset is active. */
+    series: Array<IChartSeries>;
+    /**
+     * X-axis category labels for the sub-dataset. When absent the
+     * chart falls back to numeric indices.
+     */
+    categories?: Array<string>;
+}
+/**
+ * Chart-level prop that wires up the drilldown feature. Pass this to
+ * `drilldown` on `<OrigamChartCartesian>` or `<OrigamChartPolar>`.
+ */
+export interface IChartDrilldownProps {
+    /**
+     * Bank of named sub-datasets. Looked up by
+     * `IChartDrilldownLink.id` on point-click.
+     */
+    datasets: Array<IChartDrilldownDataset>;
+    /**
+     * Localized label rendered on the "Back" button / first breadcrumb
+     * segment. Default `'← Back'`.
+     */
+    backLabel?: string;
+}
+/**
+ * One frame in the navigation stack maintained internally by the chart.
+ * The root frame is pushed on mount; each drill-in pushes an additional
+ * frame; "Back" pops the top frame.
+ */
+export interface IChartDrilldownFrame {
+    /** Display name for this level (used in the breadcrumb). */
+    name: string;
+    /** Series rendered at this level. */
+    series: Array<IChartSeries>;
+    /** Category labels at this level. */
+    categories: Array<string>;
+}

package/dist/src/interfaces/Chart/chart-gauge.interface.cjs

@@ -0,0 +1 @@
+"use strict";

package/dist/src/interfaces/Chart/chart-gauge.interface.d.ts

@@ -0,0 +1,130 @@
+import type { IChartBaseEmits, IChartBaseProps, IChartBaseSlots } from '../../interfaces';
+/**
+ * Props for `<OrigamChartGauge>` — solid gauge (radial progress
+ * indicator). Mirrors Highcharts' "Solid Gauge" demo: a 270-degree
+ * track with a filled arc indicating the current value, an
+ * optional centre label, and optional min / max endpoint labels.
+ *
+ * Reads the first datum of the first series as the value. Extra
+ * series are ignored (gauges are single-value visualisations).
+ */
+export interface IChartGaugeProps extends IChartBaseProps {
+    /**
+     * Lower bound of the gauge range. Default `0`.
+     */
+    gaugeMin?: number;
+    /**
+     * Upper bound of the gauge range. Default `100`.
+     */
+    gaugeMax?: number;
+    /**
+     * Optional unit appended to the centre label (e.g. `'%'`,
+     * `' km/h'`). Default `''`.
+     */
+    gaugeUnit?: string;
+    /**
+     * Arc thickness in SVG pixels. Default `18`.
+     */
+    gaugeThickness?: number;
+    /**
+     * Arc start angle in radians. Defaults to `-3pi/4` (bottom-left
+     * of a 270deg arc centred on the bottom).
+     */
+    gaugeStartAngle?: number;
+    /**
+     * Arc end angle in radians. Defaults to `+3pi/4` (bottom-right).
+     */
+    gaugeEndAngle?: number;
+    /**
+     * Whether to render `gaugeMin` / `gaugeMax` labels at the arc
+     * endpoints. Default `true`.
+     */
+    gaugeShowEndpoints?: boolean;
+    /**
+     * Whether to render the centre value label. Default `true`.
+     */
+    gaugeShowValue?: boolean;
+}
+/** Emits surfaced by `<OrigamChartGauge>`. Mirrors the base family. */
+export type IChartGaugeEmits = IChartBaseEmits;
+/** Slot signatures exposed by `<OrigamChartGauge>`. */
+export interface IChartGaugeSlots extends IChartBaseSlots {
+    /**
+     * Replace the centre value label. Receives the formatted value
+     * + raw datum + ratio (0..1) for custom rendering.
+     */
+    'gauge-value'?: (bindings: {
+        value: number;
+        ratio: number;
+        formatted: string;
+        unit: string;
+    }) => any;
+    /** Replace the min label at the start of the arc. */
+    'gauge-min'?: (bindings: {
+        value: number;
+    }) => any;
+    /** Replace the max label at the end of the arc. */
+    'gauge-max'?: (bindings: {
+        value: number;
+    }) => any;
+}
+/**
+ * Output of `useChartGauge` — geometry descriptors for the arc
+ * track, the indicator arc, and the label anchor points. All
+ * fields are pre-formatted so the SFC just renders without
+ * computing anything itself.
+ */
+export interface IChartGaugeGeometry {
+    /** SVG `d` attribute for the full empty track arc. */
+    trackPath: string;
+    /** SVG `d` attribute for the filled value arc (empty when value === min). */
+    valuePath: string;
+    /** Radian angle where the value arc ends. Useful for needles. */
+    valueAngle: number;
+    /** Radian angle where the gauge arc starts. */
+    startAngle: number;
+    /** Radian angle where the gauge arc ends. */
+    endAngle: number;
+    /** Outer arc radius in SVG pixels. */
+    outerRadius: number;
+    /** Inner arc radius in SVG pixels (outerRadius - thickness). */
+    innerRadius: number;
+    /** SVG pixel coordinate of the arc centre (X). */
+    centerX: number;
+    /** SVG pixel coordinate of the arc centre (Y). */
+    centerY: number;
+    /** Normalised value in `[0..1]`. */
+    ratio: number;
+    /** Clamped value in `[min..max]`. */
+    clampedValue: number;
+}
+/**
+ * Strict options consumed by `useChartGauge`. All getters are
+ * thunks so the composable can be reactively driven by props,
+ * a store, or computed sources without re-instantiation.
+ */
+export interface IUseChartGaugeOptions {
+    /** Current value (un-clamped — the engine clamps to [min..max]). */
+    value: () => number;
+    /** Lower bound of the gauge range. */
+    min: () => number;
+    /** Upper bound of the gauge range. */
+    max: () => number;
+    /** SVG viewBox width. */
+    width: () => number;
+    /** SVG viewBox height. */
+    height: () => number;
+    /** SVG inner padding (frees room for endpoint labels). */
+    padding: () => {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    /** Optional override for the arc thickness. */
+    thickness?: () => number;
+    /** Optional override for the arc start angle (radians). */
+    startAngle?: () => number;
+    /** Optional override for the arc end angle (radians). */
+    endAngle?: () => number;
+}

package/dist/src/interfaces/Chart/chart-heatmap.interface.cjs

@@ -0,0 +1 @@
+"use strict";

package/dist/src/interfaces/Chart/chart-heatmap.interface.d.ts

@@ -0,0 +1,128 @@
+import type { IChartBaseEmits, IChartBaseProps, IChartBaseSlots, IChartPoint } from '../../interfaces';
+import type { TChartLegendPosition, TIntent } from '../../types';
+/**
+ * Props for `<OrigamChartHeatmap>` — the rectangular heatmap family.
+ *
+ * Renders a grid of `<rect>` cells where each cell is coloured by
+ * its `value` relative to the min/max of the dataset. Common uses:
+ * GitHub-style activity grids, correlation matrices, weekday × hour
+ * patterns.
+ *
+ * `series[0]` is the only consumed series. Each datum must supply
+ * `x` (column key), `y` (row key) and a numeric `value`.
+ */
+export interface IChartHeatmapProps extends IChartBaseProps {
+    /**
+     * Explicit X-axis category ordering. When omitted, unique `x`
+     * values from the dataset are sorted alphabetically / numerically.
+     */
+    xCategories?: Array<string>;
+    /**
+     * Explicit Y-axis category ordering. When omitted, unique `y`
+     * values from the dataset are sorted alphabetically / numerically.
+     */
+    yCategories?: Array<string>;
+    /**
+     * Two-stop colour range used to interpolate cell colour.
+     * First entry = min value colour, second = max value colour.
+     * Accepts intent tokens or raw CSS colour strings.
+     * Default `['info', 'danger']`.
+     */
+    colorRange?: [TIntent | string, TIntent | string];
+    /**
+     * Gap between cells in SVG user units. Default `2`.
+     */
+    cellGap?: number;
+    /**
+     * Render the numeric value centred inside each cell when the
+     * cell is wide/tall enough to accommodate it. Default `true`.
+     */
+    showLabel?: boolean;
+    /**
+     * Render X and Y axis category labels along the grid edges.
+     * Default `true`.
+     */
+    showAxis?: boolean;
+    /**
+     * Gradient legend bar with min / max labels.
+     * Default `true`.
+     */
+    showGradientLegend?: boolean;
+    /**
+     * Anchor of the gradient legend. Default `'bottom'`.
+     */
+    legendPosition?: TChartLegendPosition;
+    /**
+     * X-axis category label formatter. Applied to each column label.
+     * When omitted, the raw string / number is displayed.
+     */
+    xAxisFormat?: (value: string | number) => string;
+    /**
+     * Y-axis / value formatter. Applied to row labels AND to
+     * the min/max labels on the gradient legend.
+     * When omitted, the raw number is displayed.
+     */
+    yAxisFormat?: (value: number) => string;
+}
+/** Emits surfaced by `<OrigamChartHeatmap>`. Mirrors the base family. */
+export type IChartHeatmapEmits = IChartBaseEmits;
+/** Slot signatures exposed by `<OrigamChartHeatmap>`. */
+export interface IChartHeatmapSlots extends IChartBaseSlots {
+    /**
+     * Replace the tooltip body for a hovered cell.
+     * Receives the hovered point, its resolved colour, and
+     * the formatted x / y / value strings.
+     */
+    tooltip?: (bindings: {
+        point: IChartPoint;
+        color: string;
+        xLabel: string;
+        yLabel: string;
+        value: number;
+    }) => any;
+}
+/**
+ * Single datum shape consumed from `series[0].data`.
+ * Each entry represents one cell in the heatmap grid.
+ */
+export interface IChartHeatmapDatum {
+    /** Column key — maps to an X-axis category. */
+    x: number | string;
+    /** Row key — maps to a Y-axis category. */
+    y: number | string;
+    /** Numeric value driving the cell colour. */
+    value: number;
+}
+/**
+ * Pre-computed cell descriptor produced by the heatmap geometry engine.
+ * Contains every pre-computed value needed to render one `<rect>`,
+ * its label, and tooltip / accessibility content.
+ */
+export interface IChartHeatmapCell {
+    /** Original index of the datum in `series[0].data`. */
+    index: number;
+    /** Column category string. */
+    xCat: string;
+    /** Row category string. */
+    yCat: string;
+    /** Raw numeric value. */
+    value: number;
+    /** Resolved CSS colour string for the cell fill. */
+    color: string;
+    /** SVG x position (left edge of the rect). */
+    rx: number;
+    /** SVG y position (top edge of the rect). */
+    ry: number;
+    /** Cell width in SVG user units. */
+    rw: number;
+    /** Cell height in SVG user units. */
+    rh: number;
+    /** Centre X for the value label text. */
+    labelX: number;
+    /** Centre Y for the value label text. */
+    labelY: number;
+    /** `true` when the cell is tall / wide enough to show the label. */
+    labelFits: boolean;
+    /** Whether this cell is currently visible. */
+    visible: boolean;
+}

package/dist/src/interfaces/Chart/chart-honeycomb.interface.cjs

@@ -0,0 +1 @@
+"use strict";

package/dist/src/interfaces/Chart/chart-honeycomb.interface.d.ts

@@ -0,0 +1,109 @@
+import type { IChartBaseEmits, IChartBaseProps, IChartBaseSlots, IChartPoint } from '../../interfaces';
+import type { TChartHoneycombColorMode, TChartHoneycombOrientation, TIntent } from '../../types';
+/**
+ * Props for `<OrigamChartHoneycomb>` — the hexagonal tile-map family.
+ *
+ * Renders a grid of hexagonal tiles positioned by column (`x`) and
+ * row (`y`) index. Useful for categorical tile-maps (US states, periodic
+ * table), heatmaps, or any data where spatial arrangement matters more
+ * than a continuous axis.
+ */
+export interface IChartHoneycombProps extends IChartBaseProps {
+    /**
+     * Hex vertex orientation.
+     * `'pointy-top'` — vertex at the top (default).
+     * `'flat-top'` — flat edge at the top, vertex on the side.
+     */
+    orientation?: TChartHoneycombOrientation;
+    /**
+     * Colour-mapping strategy.
+     * `'categorical'` — each tile gets a colour from `colorScheme` or the intent cycle.
+     * `'heatmap'` — `value` drives a gradient between `heatmapColorRange` endpoints.
+     */
+    colorMode?: TChartHoneycombColorMode;
+    /**
+     * Two-stop colour range for `colorMode='heatmap'`.
+     * First entry = min value colour, second = max value colour.
+     * Accepts intent tokens or raw CSS colours.
+     * Default `['info', 'danger']`.
+     */
+    heatmapColorRange?: [TIntent | string, TIntent | string];
+    /**
+     * Hex side-length in SVG user units. Controls tile size.
+     * Default `30`.
+     */
+    tileSize?: number;
+    /**
+     * Gap between adjacent tiles in SVG user units. Default `2`.
+     */
+    tileGap?: number;
+    /**
+     * Render the tile's `name` (or `value` when `name` is absent)
+     * as text centred in the tile. Default `true`.
+     */
+    showLabel?: boolean;
+    /**
+     * X-axis / column formatter. Applied to the numeric `x` index
+     * in tooltip / axis text. When omitted the raw number is used.
+     */
+    xAxisFormat?: (value: number | string) => string;
+    /**
+     * Y-axis / row formatter. Applied to the numeric `y` index.
+     * When omitted the raw number is used.
+     */
+    yAxisFormat?: (value: number) => string;
+}
+/** Emits surfaced by `<OrigamChartHoneycomb>`. Mirrors the base family. */
+export type IChartHoneycombEmits = IChartBaseEmits;
+/** Slot signatures exposed by `<OrigamChartHoneycomb>`. */
+export interface IChartHoneycombSlots extends IChartBaseSlots {
+    /**
+     * Replace the label rendered inside each tile.
+     * Receives the tile's `name`, `value`, resolved `color`, and grid position.
+     */
+    'tile-label'?: (bindings: {
+        name: string;
+        value: number | undefined;
+        color: string;
+        x: number;
+        y: number;
+        index: number;
+    }) => any;
+}
+/**
+ * Internal tile descriptor produced by the honeycomb geometry engine.
+ * Contains every pre-computed value needed to render one `<polygon>`,
+ * its label, and tooltip / accessibility content.
+ */
+export interface IChartHoneycombTile {
+    /** Original index of the data point in `series[0].data`. */
+    index: number;
+    /** Column index from `data[i].x`. */
+    gridX: number;
+    /** Row index from `data[i].y`. */
+    gridY: number;
+    /** SVG `points` attribute string for the `<polygon>`. */
+    points: string;
+    /** Resolved CSS colour string. */
+    color: string;
+    /** Tile label (name or formatted value). */
+    label: string;
+    /** Raw `name` string from the data point. */
+    name: string;
+    /** Raw `value` from the data point. */
+    value: number | undefined;
+    /** Centre X in SVG user units. */
+    cx: number;
+    /** Centre Y in SVG user units. */
+    cy: number;
+    /** Whether this tile is currently visible (legend toggle). */
+    visible: boolean;
+}
+/**
+ * Payload passed to `IChartPoint` for a hovered / clicked tile.
+ * Exposes `x` = gridX, `y` = gridY for downstream consumers.
+ */
+export interface IChartHoneycombPoint extends IChartPoint {
+    tileName: string;
+    tileValue: number | undefined;
+}

package/dist/src/interfaces/Chart/chart-legend.interface.cjs

@@ -0,0 +1 @@
+"use strict";

package/dist/src/interfaces/Chart/chart-legend.interface.d.ts

@@ -0,0 +1,48 @@
+import type { IChartLegendItem, IChartSeries } from '../../interfaces';
+import type { TChartLegendPosition } from '../../types';
+/**
+ * Props for `<OrigamChartLegend>` — the series-name + colour-swatch
+ * + visibility-toggle list that sits on one side of the chart.
+ * Extracted from the legacy `<OrigamChart>` so every family
+ * (cartesian / polar / radar / gauge) can share the same rendering.
+ *
+ * The legend is a pure renderer: it expects the pre-resolved
+ * `IChartLegendItem[]` array from `useChart().legend.value` and
+ * emits clicks back upward.
+ */
+export interface IChartLegendProps {
+    /**
+     * Pre-resolved legend entries (series + index + colour + visibility).
+     * Comes verbatim from `useChart().legend.value`.
+     */
+    items: Array<IChartLegendItem>;
+    /**
+     * Anchor of the legend block. Drives the wrapping behaviour
+     * (`row` on top/bottom, `column` on left/right).
+     */
+    position?: TChartLegendPosition;
+}
+/**
+ * Emits surfaced by `<OrigamChartLegend>`. The parent chart wires
+ * these into its own `legend-click` + `series-toggle` emits so
+ * consumers don't need to know about the extracted component.
+ */
+export interface IChartLegendEmits {
+    /** Click on a legend entry — pair with `series-toggle` for state. */
+    (e: 'legend-click', series: IChartSeries, index: number): void;
+    /** Resulting visibility flip after a legend click. */
+    (e: 'series-toggle', series: IChartSeries, visible: boolean): void;
+}
+/**
+ * Slot signatures exposed by `<OrigamChartLegend>`. Currently
+ * just `legend-item` so a consumer can replace one entry with a
+ * custom render (chip, icon, …).
+ */
+export interface IChartLegendSlots {
+    /** Replace one legend entry. */
+    'legend-item'?: (bindings: {
+        series: IChartSeries;
+        index: number;
+        visible: boolean;
+    }) => any;
+}

package/dist/src/interfaces/Chart/chart-map.interface.cjs

@@ -0,0 +1 @@
+"use strict";