origam 2.3.0 → 2.5.0

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";

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

@@ -0,0 +1,137 @@
+import type { IChartBaseEmits, IChartBaseProps, IChartBaseSlots, IChartPoint, IChartSeries } from '../../interfaces';
+import type { TChartMapMode } from '../../types/Chart/chart-map-mode.type';
+import type { TIntent } from '../../types';
+/**
+ * A single choropleth data point keyed by ISO-3166-1 alpha-2 code.
+ */
+export interface IChartMapChoroplethDatum {
+    /** ISO-3166-1 alpha-2 country code (e.g. `'FR'`, `'US'`). */
+    code: string;
+    /** Numeric value used to drive the colour interpolation. */
+    value: number;
+    /** Human-readable label. Defaults to `code` when omitted. */
+    name?: string;
+}
+/**
+ * A single flight-route datum connecting two country centroids.
+ */
+export interface IChartMapRouteDatum {
+    /** ISO-3166-1 alpha-2 code for the route origin. */
+    from: string;
+    /** ISO-3166-1 alpha-2 code for the route destination. */
+    to: string;
+    /** Optional flow weight — drives the stroke width via `Math.log(value + 1) * 1.5`. */
+    value?: number;
+    /** Overrides `lineColor` for this route specifically. */
+    color?: TIntent | string;
+}
+/**
+ * Internal country descriptor produced by the map geometry engine.
+ * Holds the pre-resolved fill colour and ARIA metadata.
+ */
+export interface IChartMapCountry {
+    /** ISO-3166-1 alpha-2 code. */
+    code: string;
+    /** SVG `<path d="…">` string from `WORLD_MAP_PATHS`. */
+    d: string;
+    /** Resolved CSS fill colour string. */
+    fill: string;
+    /** Raw numeric value (undefined for countries not in the dataset). */
+    value: number | undefined;
+    /** Display name (from datum or code fallback). */
+    name: string;
+    /** Whether this country has data in the current series. */
+    hasData: boolean;
+}
+/**
+ * Internal route descriptor produced by the map geometry engine.
+ */
+export interface IChartMapRoute {
+    /** Zero-based index in the series data array. */
+    index: number;
+    /** SVG quadratic Bezier path string: `M x1,y1 Q cx,cy x2,y2`. */
+    d: string;
+    /** Resolved CSS stroke colour. */
+    stroke: string;
+    /** Stroke width in SVG pixels. */
+    strokeWidth: number;
+    /** Centroid [x, y] of the origin country. */
+    fromPoint: [number, number];
+    /** Centroid [x, y] of the destination country. */
+    toPoint: [number, number];
+    /** Origin country code. */
+    from: string;
+    /** Destination country code. */
+    to: string;
+    /** Optional flow value. */
+    value: number | undefined;
+}
+/**
+ * Props for `<OrigamChartMap>`.
+ *
+ * Supports two rendering modes:
+ *   - `'choropleth'` — country shapes coloured by a continuous value
+ *     interpolated between two intent / CSS colour endpoints.
+ *   - `'flight-routes'` — curved arcs between pairs of country centroids
+ *     drawn over a neutral map backdrop.
+ */
+export interface IChartMapProps extends IChartBaseProps {
+    /**
+     * Rendering mode. Default `'choropleth'`.
+     */
+    mode?: TChartMapMode;
+    /**
+     * Colour gradient endpoints for choropleth mode.
+     * First colour = min value; second colour = max value.
+     * Supports intent names and raw CSS strings.
+     * Default `['info', 'danger']`.
+     */
+    colorRange?: [TIntent | string, TIntent | string];
+    /**
+     * Fill colour for countries that have no value in the dataset.
+     * Default `'rgba(0,0,0,0.08)'`.
+     */
+    defaultCountryFill?: string;
+    /**
+     * Stroke colour applied to all country path outlines.
+     * Default `'rgba(0,0,0,0.2)'`.
+     */
+    borderColor?: string;
+    /**
+     * Default stroke colour for flight-route arcs.
+     * Overridden per route via `IChartMapRouteDatum.color`.
+     * Default `'primary'`.
+     */
+    lineColor?: TIntent | string;
+    /**
+     * Radius in SVG pixels of the endpoint circles on each route.
+     * Default `4`.
+     */
+    nodeRadius?: number;
+    /**
+     * Bezier control-point offset as a fraction of the chord length [0..1].
+     * `0` = straight line; `0.3` = gentle arc (default); `0.5` = visible arc.
+     */
+    routeCurvature?: number;
+    /**
+     * Y-axis value formatter used in tooltips and the choropleth legend.
+     * When omitted, values are displayed as-is.
+     */
+    yAxisFormat?: (value: number) => string;
+}
+/** Emits surfaced by `<OrigamChartMap>`. Mirrors the base family. */
+export type IChartMapEmits = IChartBaseEmits;
+/** Slot signatures exposed by `<OrigamChartMap>`. */
+export interface IChartMapSlots extends IChartBaseSlots {
+    /**
+     * Replace the default tooltip body.
+     * Receives the hovered point, series, and category label.
+     */
+    tooltip?: (bindings: {
+        point: IChartPoint;
+        series: IChartSeries;
+        category: string | number;
+    }) => any;
+    /** Render when `series` is empty or has no renderable data. */
+    empty?: () => any;
+}

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

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