@camstack/ui-library 1.2.328 → 1.2.330

package/dist/composites/charts/BarSeries.d.ts

@@ -9,6 +9,7 @@
 * and every bucket is also a real button for keyboard and screen readers.
 */
 import { type JSX, type ReactNode } from "react";
+import type { DisplayPreference } from "@camstack/types";
 import { type ChartWindowToggleProps } from "./chart-window";
 import { type BarBucket, type BarLayerDef } from "./bar-series-model";
 import type { ChartRange } from "./TimeSeriesChart";
@@ -22,6 +23,8 @@ export interface BarSeriesProps<TId extends string = string> {
 	readonly range: ChartRange;
 	readonly unit?: string | null;
 	readonly formatValue?: (v: number, unit: string | null) => string;
+	/** Display preference for base-unit samples in the point tooltip. Default metric. */
+	readonly displayPreference?: DisplayPreference;
 	/** Plot height in px. Default 100 (24 when `compact`). */
 	readonly height?: number;
 	/** Stack the layers (default true for more than one layer). */
@@ -46,4 +49,4 @@ export interface BarSeriesProps<TId extends string = string> {
 	readonly bucketTestId?: string;
 	readonly className?: string;
 }
-export declare function BarSeries<TId extends string = string>({ title, layers, buckets, bucketMs, range, unit, formatValue, height, stacked, showTotal, syncKey, pending, emptyMessage, actions, footer, windowToggle, compact, minBarFraction, selectedIndex, onSelect, bucketLabel, bucketTestId, className }: BarSeriesProps<TId>): JSX.Element;
+export declare function BarSeries<TId extends string = string>({ title, layers, buckets, bucketMs, range, unit, formatValue, displayPreference, height, stacked, showTotal, syncKey, pending, emptyMessage, actions, footer, windowToggle, compact, minBarFraction, selectedIndex, onSelect, bucketLabel, bucketTestId, className }: BarSeriesProps<TId>): JSX.Element;

package/dist/composites/charts/Sparkline.d.ts

@@ -4,6 +4,7 @@
 * by (an epoch, a time); the value next to it names what the line is.
 */
 import { type JSX } from "react";
+import type { DisplayPreference, ReadingQuantity } from "@camstack/types";
 import { type ChartChromeToken, type ChartSeriesToken } from "./chart-palette";
 export interface SparklinePoint {
 	readonly x: number;
@@ -21,6 +22,10 @@ export interface SparklineProps {
 	readonly widthClassName?: string;
 	/** Start the value axis at zero (default true). */
 	readonly zeroBased?: boolean;
+	readonly unit?: string | null;
+	readonly quantity?: ReadingQuantity;
+	/** Display preference for a base-unit sample in the point tooltip. Default metric. */
+	readonly displayPreference?: DisplayPreference;
 	readonly className?: string;
 }
-export declare function Sparkline({ points, ariaLabel, token, height, widthClassName, zeroBased, className }: SparklineProps): JSX.Element;
+export declare function Sparkline({ points, ariaLabel, token, height, widthClassName, zeroBased, unit, quantity, displayPreference, className }: SparklineProps): JSX.Element;

package/dist/composites/charts/TimeSeriesChart.d.ts

@@ -11,6 +11,7 @@
 * for the cross-device History page, where the reader chose the series.
 */
 import { type JSX, type ReactNode } from "react";
+import type { DisplayPreference } from "@camstack/types";
 import { type ValueAxisSpec } from "./chart-uplot";
 import { type ChartWindowToggleProps } from "./chart-window";
 import { type TimeSeriesDef } from "./time-series-model";
@@ -34,6 +35,8 @@ export interface TimeSeriesChartProps<TId extends string = string> {
 	readonly syncKey?: string;
 	/** Value formatter per unit; default: bytes binary, `%` glued, unit after a space. */
 	readonly formatValue?: (v: number, unit: string | null) => string;
+	/** Display preference for base-unit samples in the point tooltip. Default metric. */
+	readonly displayPreference?: DisplayPreference;
 	/** Axis layout per unit; default by unit (°C floats, `%` floors at 10, bytes binary). */
 	readonly axisFor?: (unit: string | null) => ValueAxisSpec;
 	/** Shown when no series has a known value. */
@@ -45,4 +48,4 @@ export interface TimeSeriesChartProps<TId extends string = string> {
 	readonly windowToggle?: ChartWindowToggleProps<TId>;
 	readonly className?: string;
 }
-export declare function TimeSeriesChart<TId extends string = string>({ title, series, range, height, stacked, area, syncKey, formatValue, axisFor, emptyMessage, pending, actions, footer, windowToggle, className }: TimeSeriesChartProps<TId>): JSX.Element;
+export declare function TimeSeriesChart<TId extends string = string>({ title, series, range, height, stacked, area, syncKey, formatValue, displayPreference, axisFor, emptyMessage, pending, actions, footer, windowToggle, className }: TimeSeriesChartProps<TId>): JSX.Element;

package/dist/composites/charts/chart-tooltip-host.d.ts

@@ -0,0 +1,27 @@
+/**
+* One tooltip for every chart. The plot stays in `UPlotHost`; this shell
+* tracks the pointer, a touch scrub and the arrow keys, and draws the
+* readout inside the chart.
+*/
+import { type JSX, type ReactNode, type RefObject } from "react";
+import type uPlot from "uplot";
+import { type ChartTooltipBody } from "./chart-tooltip-model";
+export type ChartKind = "lines" | "states" | "bars" | "spark";
+export interface ChartTooltipSpec {
+	readonly xMin: number;
+	readonly xMax: number;
+	readonly stops: readonly number[];
+	/** `null` means this x has nothing to show (the tooltip hides). */
+	readonly resolve: (dataX: number) => ChartTooltipBody | null;
+	/** The chart's own cursor (legend, state label) follows the selection. */
+	readonly onDataX?: (dataX: number | null) => void;
+}
+export interface ChartTooltipShellProps {
+	readonly spec: ChartTooltipSpec | null;
+	readonly plotRef: RefObject<uPlot | null>;
+	readonly kind?: ChartKind;
+	readonly label?: string;
+	readonly inline?: boolean;
+	readonly children: ReactNode;
+}
+export declare function ChartTooltipShell({ spec, plotRef, kind, label, inline, children }: ChartTooltipShellProps): JSX.Element;

package/dist/composites/charts/chart-tooltip-model.d.ts

@@ -0,0 +1,174 @@
+/**
+* Selection, placement and readout for the chart point tooltip.
+* Pure: no DOM. Every chart asks this, then the shared host draws one tooltip.
+*
+* A numeric sample is a base-unit reading (D944 §4): the quantity formatter
+* applies the display preference. A unit string is used only when it names
+* one quantity, so the tooltip never shows a bare number that has a unit.
+*/
+import { type DisplayPreference, type ReadingQuantity } from "@camstack/types";
+import { type StateSegment } from "./chart-data";
+/** Movement below this is still a tap, not a scrub. */
+export declare const CHART_TOUCH_SLOP_PX: number;
+/** Gap between the selected point and the tooltip, in px. */
+export declare const CHART_TOOLTIP_GAP_PX: number;
+/** Inset that keeps the tooltip inside the chart. */
+export declare const CHART_TOOLTIP_PAD_PX: number;
+export type ChartPointerKind = "mouse" | "touch";
+export interface ChartSelection {
+	readonly visible: boolean;
+	readonly dataX: number | null;
+	readonly anchorX: number;
+	readonly anchorY: number;
+	readonly pinned: boolean;
+}
+export interface ChartGesture {
+	readonly kind: ChartPointerKind;
+	readonly originX: number;
+	readonly originY: number;
+	readonly axis: "pending" | "x" | "y";
+}
+export interface ChartInteraction {
+	readonly selection: ChartSelection;
+	readonly gesture: ChartGesture | null;
+	readonly lockHorizontalScroll: boolean;
+}
+export declare const HIDDEN_SELECTION: ChartSelection;
+export declare const HIDDEN_INTERACTION: ChartInteraction;
+export interface ChartPointerEvent {
+	readonly type: "down" | "move" | "up";
+	readonly kind: ChartPointerKind;
+	readonly x: number;
+	readonly y: number;
+	readonly dataX: number | null;
+}
+export type ChartInteractionEvent = {
+	readonly type: "hover";
+	readonly dataX: number;
+	readonly anchorX: number;
+	readonly anchorY: number;
+} | {
+	readonly type: "leave";
+} | {
+	readonly type: "outside";
+} | {
+	readonly type: "hide";
+} | {
+	readonly type: "key";
+	readonly dataX: number;
+	readonly anchorX: number;
+	readonly anchorY: number;
+} | ChartPointerEvent;
+export interface DataXFromPointerInput {
+	readonly localX: number;
+	readonly plotLeft: number;
+	readonly plotWidth: number;
+	readonly xMin: number;
+	readonly xMax: number;
+	readonly clamp: boolean;
+}
+export interface PlaceTooltipInput {
+	readonly anchorX: number;
+	readonly anchorY: number;
+	readonly tooltipWidth: number;
+	readonly tooltipHeight: number;
+	readonly boundsWidth: number;
+	readonly boundsHeight: number;
+	readonly gap?: number;
+}
+export interface TooltipPlacement {
+	readonly left: number;
+	readonly top: number;
+	readonly placed: "left" | "right";
+	readonly vertical: "above" | "below";
+}
+export interface TooltipValueInput {
+	readonly value: number | null;
+	readonly quantity?: ReadingQuantity;
+	readonly preference?: DisplayPreference;
+	readonly precision?: number;
+	readonly unit?: string | null;
+	readonly unknownLabel?: string;
+}
+export interface ChartTooltipLine {
+	readonly id: string;
+	readonly label: string;
+	readonly value: string;
+}
+export interface ChartTooltipBody {
+	readonly heading: string;
+	readonly lines: readonly ChartTooltipLine[];
+	readonly liveText: string;
+}
+export interface LineTooltipSample {
+	readonly id: string;
+	readonly label: string;
+	readonly value: number | null;
+	readonly quantity?: ReadingQuantity;
+	readonly unit?: string | null;
+	readonly precision?: number;
+	readonly visible?: boolean;
+}
+export interface StateTooltipRow {
+	readonly id: string;
+	readonly label: string;
+	readonly stateLabel: string | null;
+	readonly spanMs: number | null;
+}
+export interface StateSpanHit {
+	readonly state: string | null;
+	readonly spanMs: number;
+}
+export interface BarTooltipLayer {
+	readonly id: string;
+	readonly label: string;
+	readonly value: number | null;
+	readonly quantity?: ReadingQuantity;
+	readonly unit?: string | null;
+	readonly precision?: number;
+}
+export interface BucketStart {
+	readonly t: number;
+}
+/** Index of the sample closest to `x`. A tie keeps the earlier sample. */
+export declare function nearestPointIndex(xs: readonly number[], x: number): number | null;
+/** Data x for a pointer inside the plot. `null` when it is outside and clamping is off. */
+export declare function dataXFromPointer(input: DataXFromPointerInput): number | null;
+/** Bucket that contains `dataX`, or the nearest one when `dataX` falls in a gap. */
+export declare function bucketSelectionIndex(buckets: readonly BucketStart[], bucketMs: number, dataX: number): number | null;
+/** Next keyboard stop. A null current starts at the first or last stop. */
+export declare function stepStop(stops: readonly number[], current: number | null, direction: -1 | 1): number | null;
+/** Pointer, keyboard and dismiss rules for one chart. */
+export declare function reduceChartInteraction(state: ChartInteraction, event: ChartInteractionEvent): ChartInteraction;
+/** One sample, with its unit. Missing samples are an em dash, never zero. */
+export declare function formatTooltipValue(input: TooltipValueInput): string;
+export interface LineTooltipBodyInput {
+	readonly timeLabel: string;
+	readonly series: readonly LineTooltipSample[];
+	readonly preference?: DisplayPreference;
+}
+/** Time plus one line per visible series. */
+export declare function lineTooltipBody(input: LineTooltipBodyInput): ChartTooltipBody;
+/** The state in force at `t`, and how long that span lasts. */
+export declare function stateSpanAt(segments: readonly StateSegment[], t: number): StateSpanHit | null;
+export declare function stateTooltipValue(stateLabel: string | null, spanMs: number | null): string;
+export interface StateTooltipBodyInput {
+	readonly timeLabel: string;
+	readonly rows: readonly StateTooltipRow[];
+}
+/** One row per state series: the label and the span under the pointer. */
+export declare function stateTooltipBody(input: StateTooltipBodyInput): ChartTooltipBody;
+/** `start – end` for one bar bucket, at the window's time precision. */
+export declare function barRangeLabel(start: number, bucketMs: number, spanMs: number): string;
+export interface BarTooltipBodyInput {
+	readonly rangeLabel: string;
+	readonly layers: readonly BarTooltipLayer[];
+	readonly preference?: DisplayPreference;
+}
+/** The bucket's range, and each layer's value with its unit. */
+export declare function barTooltipBody(input: BarTooltipBodyInput): ChartTooltipBody;
+/**
+* Place the tooltip beside the point, inside the chart. The first side that
+* fits and does not cover the point wins; the edges flip before the corners.
+*/
+export declare function placeChartTooltip(input: PlaceTooltipInput): TooltipPlacement;

package/dist/composites/charts/time-series-model.d.ts

@@ -2,6 +2,7 @@
 * The pure half of `TimeSeriesChart`: which series go on which value axis,
 * the aligned data uPlot draws, and what the readout says at an index.
 */
+import type { ReadingQuantity } from "@camstack/types";
 import { type AlignedValue, type GapSpan, type TimePoint } from "./chart-data";
 export type SeriesInterpolation = "linear" | "step";
 export interface TimeSeriesDef {
@@ -10,6 +11,8 @@ export interface TimeSeriesDef {
 	readonly label: string;
 	/** `null` is an unknown unit; series sharing a unit share an axis. */
 	readonly unit?: string | null;
+	/** Stored base-unit quantity (D944 §4). The tooltip formats through it. */
+	readonly quantity?: ReadingQuantity;
 	readonly points: readonly TimePoint[];
 	/** Categorical slot (`chartSeriesStyle`); the caller keeps it stable across filters. */
 	readonly colorIndex: number;

package/dist/composites/charts/uplot-host.d.ts

@@ -13,6 +13,7 @@
 */
 import { type JSX } from "react";
 import type uPlot from "uplot";
+import { type ChartKind, type ChartTooltipSpec } from "./chart-tooltip-host";
 export type UPlotCtor = typeof uPlot;
 /** Options without the size: the host owns width (the container) and height (the prop). */
 export type ChartPlotOptions = Omit<uPlot.Options, "width" | "height">;
@@ -30,5 +31,12 @@ export interface UPlotHostProps {
 	readonly className?: string;
 	/** Render a `<span class="block">` host, for a plot inside phrasing content. */
 	readonly inline?: boolean;
+	/** Point tooltip. Absent on a plot that has nothing to select. */
+	readonly tooltip?: ChartTooltipSpec | null;
+	/** Which chart this plot is, so a shot can aim the pointer at one of them. */
+	readonly kind?: ChartKind;
+	/** Accessible name for the focusable plot. */
+	readonly label?: string;
 }
-export declare function UPlotHost({ optionsKey, buildOptions, data, height, onInstance, className, inline }: UPlotHostProps): JSX.Element;
+export type { ChartKind, ChartTooltipSpec };
+export declare function UPlotHost({ optionsKey, buildOptions, data, height, onInstance, className, inline, tooltip, kind, label }: UPlotHostProps): JSX.Element;

package/dist/generated/system-hooks.d.ts

@@ -63,6 +63,8 @@ export declare const useAddonsListCapabilityProviders: typeof trpc.addons.listCa
 export declare const useAddonsSetCapabilityProviderEnabled: typeof trpc.addons.setCapabilityProviderEnabled.useMutation;
 /** Generated alias around `trpc.addons.getVersions.useQuery`. */
 export declare const useAddonsGetVersions: typeof trpc.addons.getVersions.useQuery;
+/** Generated alias around `trpc.addons.getPackageDocs.useQuery`. */
+export declare const useAddonsGetPackageDocs: typeof trpc.addons.getPackageDocs.useQuery;
 /** Generated alias around `trpc.addons.restartAddon.useMutation`. */
 export declare const useAddonsRestartAddon: typeof trpc.addons.restartAddon.useMutation;
 /** Generated alias around `trpc.addons.retryLoad.useMutation`. */
@@ -841,6 +843,8 @@ export declare const useFeatureProbeGetStatus: typeof trpc.featureProbe.getStatu
 export declare const useFloodGetStatus: typeof trpc.flood.getStatus.useQuery;
 /** Generated alias around `trpc.gas.getStatus.useQuery`. */
 export declare const useGasGetStatus: typeof trpc.gas.getStatus.useQuery;
+/** Generated alias around `trpc.groupCommands.getStatus.useQuery`. */
+export declare const useGroupCommandsGetStatus: typeof trpc.groupCommands.getStatus.useQuery;
 /** Generated alias around `trpc.groupStatus.getStatus.useQuery`. */
 export declare const useGroupStatusGetStatus: typeof trpc.groupStatus.getStatus.useQuery;
 /** Generated alias around `trpc.heatingValve.getStatus.useQuery`. */