@lilt-ui/charts 0.12.2 → 0.13.1

package/dist/watch/board/board-state.d.ts

@@ -1,72 +0,0 @@
-import { NormalSeverity } from '../engine/normal';
-/** What a watched chart tells its board. `null` means it is not watching anything. */
-export interface NormalReport {
-    /** The series has stayed unusual long enough to count as an incident. */
-    active: boolean;
-    severity: NormalSeverity | null;
-    /** A short sentence, such as "Unusually low". */
-    reason: string | null;
-    /** Which segment caused it, when the chart has a breakdown: "91% of the drop is Mobile Safari". */
-    why: string | null;
-    /** Where the incident started, as the chart labels it, such as "Tue 2 PM". */
-    since: string | null;
-    /** The incident's start as an x position; epoch milliseconds on time axes. */
-    sinceAt: number | null;
-    /** How far past normal, where 1 is just outside. */
-    score: number;
-}
-/**
- * `active` needs attention, `acknowledged` has been seen, `cleared` recently returned to normal
- * and is about to settle back into place.
- */
-export type BoardAlarm = 'normal' | 'active' | 'acknowledged' | 'cleared';
-export interface BoardItemState {
-    id: string;
-    /** Position among the board's children, used when nothing else decides. */
-    order: number;
-    alarm: BoardAlarm;
-    /** Pinned by the viewer. Always first, and never moved by the board. */
-    pinned: boolean;
-    severity: NormalSeverity | null;
-    reason: string | null;
-    why: string | null;
-    since: string | null;
-    sinceAt: number | null;
-    score: number;
-    /** Wall-clock times, in milliseconds. */
-    raisedAt: number | null;
-    acknowledgedAt: number | null;
-    clearedAt: number | null;
-}
-export type BoardAction = {
-    type: 'register';
-    id: string;
-    order: number;
-} | {
-    type: 'unregister';
-    id: string;
-} | {
-    type: 'report';
-    id: string;
-    report: NormalReport | null;
-    now: number;
-} | {
-    type: 'acknowledge';
-    id: string;
-    now: number;
-} | {
-    type: 'pin';
-    id: string;
-    pinned: boolean;
-} | {
-    type: 'settle';
-    id: string;
-};
-export type BoardState = Readonly<Record<string, BoardItemState>>;
-export declare function boardReducer(state: BoardState, action: BoardAction): BoardState;
-/**
- * The order to show items in: the viewer's pins, then what needs attention (critical first, then
- * whatever has been wrong longest), then what has been seen, then what just cleared, then the
- * rest in their written order.
- */
-export declare function rankBoard(state: BoardState): string[];

package/dist/watch/board/board-toast.d.ts

@@ -1,19 +0,0 @@
-import { ReactElement } from 'react';
-import { NormalSeverity } from '../engine/normal';
-/** One item waiting in the toast. */
-export interface BoardAlert {
-    id: string;
-    title: string;
-    reason: string | null;
-    severity: NormalSeverity;
-}
-/**
- * A small glass toast for items that turned unusual off screen. One item names itself and its
- * reason; several group into a count. View takes the viewer to the most urgent one.
- */
-export declare function BoardToast({ alerts, reducedMotion, onView, onDismiss, }: {
-    alerts: readonly BoardAlert[];
-    reducedMotion: boolean;
-    onView: () => void;
-    onDismiss: () => void;
-}): ReactElement | null;

package/dist/watch/board/chart-board.d.ts

@@ -1,93 +0,0 @@
-import { CSSProperties, ReactElement, ReactNode } from 'react';
-import { ChartMotion } from '../../types';
-import { BoardItemState } from './board-state';
-export interface BoardItemProps {
-    /** Stable and unique within the board. */
-    id: string;
-    /** Names the item in announcements and controls, e.g. "Orders". */
-    title: string;
-    /** Grid columns to span. Defaults to 1. */
-    span?: 1 | 2;
-    children?: ReactNode;
-}
-/**
- * One chart on a board. A watched chart inside it reports its own status; the board ranks,
- * pins, and announces it.
- */
-export declare function BoardItem({ children }: BoardItemProps): ReactElement;
-/** Something that happened to an item, for your own alerts. */
-export interface BoardEvent {
-    type: 'raised' | 'escalated' | 'acknowledged' | 'cleared';
-    id: string;
-    title: string;
-    item: BoardItemState;
-    /** Scroll the item into view, focus it, and highlight it briefly. */
-    show: () => void;
-}
-/** Where a board remembers what you last saw. Defaults to `localStorage`. */
-export interface BoardStorage {
-    get: (key: string) => string | null;
-    set: (key: string, value: string) => void;
-}
-export interface ChartBoardProps {
-    /** `BoardItem`s, in the order they sit while everything is normal. */
-    children?: ReactNode;
-    'aria-label': string;
-    /** How long a cleared item stays in place before settling back, in milliseconds. Defaults to 8000. */
-    settleAfter?: number;
-    /**
-     * Remember which incidents you have seen under this name, and mark new ones "New since you
-     * last looked". Off unless set.
-     */
-    memory?: string;
-    storage?: BoardStorage;
-    /** Called when an item is raised, escalates, is acknowledged, or clears. */
-    onEvent?: (event: BoardEvent) => void;
-    /**
-     * Show a small toast when an item needs attention while it is off screen, with View to go
-     * there, and count alerts in the page title while the tab is in the background. Off unless
-     * set; `onEvent` and its `show` build your own.
-     */
-    toast?: boolean;
-    /** Offer "Order changed · Show" while a new order waits. Defaults to true. */
-    toolbar?: boolean;
-    /**
-     * Give each card the board's tab, edge tone, and pin. Defaults to true; turn off to build your
-     * own with `useBoardItem` and `CardFrameContext`.
-     */
-    status?: boolean;
-    /** `none` turns off reordering motion; reduced-motion users get this automatically. */
-    motion?: ChartMotion;
-    className?: string;
-    style?: CSSProperties;
-}
-/** The whole board's state, for a custom summary or controls. */
-export declare function useBoard(): {
-    items: BoardItemState[];
-    attention: BoardItemState[];
-    fresh: BoardItemState[];
-    pending: boolean;
-    apply: () => void;
-    acknowledge: (id: string) => void;
-    pin: (id: string, pinned: boolean) => void;
-};
-/** The enclosing item's state and actions, for a custom tab. */
-export declare function useBoardItem(): {
-    item: BoardItemState;
-    title: string;
-    fresh: boolean;
-    acknowledge: () => void;
-    pin: (pinned: boolean) => void;
-};
-/**
- * The default tab for an item's card: what is going on, how new it is, and quiet actions to
- * acknowledge it or keep it pinned.
- */
-export declare function BoardItemTab(): ReactElement;
-/**
- * The default bar over the board. It appears only while a new order is waiting for the viewer
- * to finish reading; `useBoard` builds a summary of your own.
- */
-export declare function BoardToolbar(): ReactElement | null;
-/** ChartBoard with its own MotionScope, so it animates wherever it is rendered. */
-export declare function ChartBoard(props: ChartBoardProps): ReactElement;

package/dist/watch/board/report-context.d.ts

@@ -1,3 +0,0 @@
-import { NormalReport } from './board-state';
-/** Set by a board item, so a watched chart inside it reports its status without wiring. */
-export declare const NormalReportContext: import('react').Context<((report: NormalReport | null) => void) | null>;

package/dist/watch/engine/describe.d.ts

@@ -1,9 +0,0 @@
-import { NormalFlag } from './normal';
-export interface DescribeFlagOptions {
-    /** Formats bounds in the series' unit. Defaults to plain numbers. */
-    formatValue?: (value: number) => string;
-    /** Names the `around` series, e.g. "target". Defaults to "reference". */
-    aroundLabel?: string;
-}
-/** A short sentence for a flag, such as "Above max 2%" or "Unusually low". */
-export declare function describeFlag(flag: NormalFlag, { formatValue, aroundLabel }?: DescribeFlagOptions): string;

package/dist/watch/engine/explain.d.ts

@@ -1,48 +0,0 @@
-import { NormalPoint } from './normal';
-export interface DeviationPart {
-    segment: string;
-    actual: number;
-    expected: number;
-    /** `actual - expected` for this segment. */
-    delta: number;
-    /** This segment's part of the total difference. Offsetting segments are negative. */
-    share: number;
-}
-export interface DeviationExplanation {
-    actual: number;
-    expected: number;
-    delta: number;
-    /** Largest contributor first, in the direction of the total difference. */
-    parts: readonly DeviationPart[];
-    /** Segments without both readings. They are left out rather than counted as zero. */
-    missing: readonly string[];
-}
-/**
- * Split a difference from normal into the segments that caused it, such as regions or
- * devices: "87% of the drop is EU".
- */
-export declare function explainDeviation(actual: Readonly<Record<string, number | null | undefined>>, expected: Readonly<Record<string, number | null | undefined>>): DeviationExplanation;
-/** Splits one row into the segments that add up to the watched value, such as orders by device. */
-export type NormalBreakdown<Row> = (row: Row) => Readonly<Record<string, number | null | undefined>>;
-export interface ExplainReadingsOptions<Row> {
-    /** The rows `points` were evaluated on. */
-    data: readonly Row[];
-    points: readonly NormalPoint[];
-    /** Row indices to explain, such as one unusual stretch. */
-    indices: readonly number[];
-    breakdown: NormalBreakdown<Row>;
-    /** Normal readings to compare with when a row has no learned basis. Defaults to 6. */
-    fallback?: number;
-}
-/**
- * Explain unusual readings by segment. Each segment is compared with the same earlier rows the
- * learned normal came from, so "usual for this segment" means the same hour on the same weekday;
- * without a learned normal, with the latest normal readings before the stretch.
- */
-export declare function explainReadings<Row>({ data, points, indices, breakdown, fallback, }: ExplainReadingsOptions<Row>): DeviationExplanation | null;
-export interface DescribeExplanationOptions {
-    /** Share of the difference one segment needs to be named alone. Defaults to 0.5. */
-    lead?: number;
-}
-/** A short sentence, such as "91% of the drop is Mobile Safari". `null` when nothing stands out. */
-export declare function describeExplanation(explanation: DeviationExplanation | null, { lead }?: DescribeExplanationOptions): string | null;

package/dist/watch/engine/normal.d.ts

@@ -1,114 +0,0 @@
-import { NumericKey } from '../../cards/keys';
-export type NormalSeverity = 'warning' | 'critical';
-/** Which layer raised a flag, so explanations can say why a value is unusual. */
-export type NormalSource = 'limit' | 'around' | 'learned' | 'rule';
-/** An absolute distance in the series unit, or a share of the reference such as `'10%'`. */
-export type NormalTolerance = number | `${number}%`;
-export interface NormalLimits {
-    min?: number;
-    max?: number;
-    /** Defaults to `'critical'`: a declared limit is the strongest signal. */
-    severity?: NormalSeverity;
-}
-export type NormalPeriod = 'week' | 'day' | 'all';
-export interface NormalLearnOptions {
-    /**
-     * `'week'` compares with the same time on the same weekday, `'day'` with the same time of day,
-     * and `'all'` with every earlier value.
-     */
-    period: NormalPeriod;
-    /** Band half-width in robust standard deviations. Defaults to 3. */
-    width?: number;
-    /** Earlier samples kept per time slot. Defaults to 8. */
-    history?: number;
-    /** Samples needed before a slot has a learned normal. Defaults to 3. */
-    minSamples?: number;
-    /** Time slot size. Defaults to the typical spacing of the data, capped at one day. */
-    slotMinutes?: number;
-    /** Offset from UTC used to find the weekday and time of day. Defaults to 0. */
-    utcOffsetMinutes?: number;
-    /** Defaults to `'warning'`. */
-    severity?: NormalSeverity;
-}
-export interface NormalGiven<Row> {
-    key: NumericKey<Row>;
-    /** Width of each condition bin. Defaults to an eighth of the observed range. */
-    step?: number;
-}
-export interface NormalRuleContext<Row> {
-    index: number;
-    rows: readonly Row[];
-    /** The watched value at this row. `null` is missing. */
-    value: number | null;
-    /** Every watched value, in row order. */
-    values: readonly (number | null)[];
-}
-export type NormalRuleTest<Row> = (row: Row, context: NormalRuleContext<Row>) => boolean;
-export interface NormalRuleConfig<Row> {
-    test: NormalRuleTest<Row>;
-    /** Defaults to `'critical'`. */
-    severity?: NormalSeverity;
-    /** A short sentence shown when the rule fires. Defaults to the rule name. */
-    message?: string;
-}
-export type NormalRule<Row> = NormalRuleTest<Row> | NormalRuleConfig<Row>;
-/**
- * What counts as normal for one series. Every layer is off unless you set it; an empty spec
- * judges nothing.
- */
-export interface NormalSpec<Row> {
-    limits?: NormalLimits;
-    /** Normal is close to another series, such as a target or setpoint. */
-    around?: NumericKey<Row>;
-    /** Distance from `around` that is still normal. Required with `around`. */
-    tolerance?: NormalTolerance;
-    /** Defaults to `'warning'`. */
-    aroundSeverity?: NormalSeverity;
-    /** Learn normal from the series' own history. Off unless set. */
-    learn?: NormalPeriod | NormalLearnOptions;
-    /** Compare only with earlier values taken under similar conditions. Needs `learn`. */
-    given?: NumericKey<Row> | NormalGiven<Row>;
-    /** Judge only rows where this returns true. Other rows are skipped and never learned from. */
-    when?: (row: Row, index: number) => boolean;
-    rules?: Record<string, NormalRule<Row>>;
-}
-export interface NormalFlag {
-    source: NormalSource;
-    /** `'min'`, `'max'`, `'around'`, `'learned'`, or the rule name. */
-    id: string;
-    severity: NormalSeverity;
-    direction?: 'above' | 'below';
-    /** The edge that was crossed. */
-    bound?: number;
-    message?: string;
-    /** How far past normal, where 1 is just outside. Used to rank. */
-    score: number;
-}
-export interface NormalPoint {
-    index: number;
-    value: number | null;
-    /** False where `when` skipped the row. */
-    judged: boolean;
-    /** The learned median, or the `around` value. */
-    expected: number | null;
-    /** The normal band to draw: every declared and learned layer combined. */
-    lower: number | null;
-    upper: number | null;
-    flags: readonly NormalFlag[];
-    severity: NormalSeverity | null;
-    score: number;
-    /**
-     * The earlier rows the learned normal came from, such as the same hour in previous weeks.
-     * Explanations compare each segment with these same rows. `null` without a learned normal.
-     */
-    basis: readonly number[] | null;
-}
-export interface EvaluateNormalOptions<Row> {
-    data: readonly Row[];
-    /** The x key. Learning by `'week'` or `'day'` needs dates or epoch milliseconds. */
-    x: string;
-    value: NumericKey<Row>;
-    normal: NormalSpec<Row>;
-}
-/** Judge each row against the layers switched on in `normal`. Learning only uses earlier rows. */
-export declare function evaluateNormal<Row>({ data, x, value, normal, }: EvaluateNormalOptions<Row>): NormalPoint[];

package/dist/watch/engine/robust.d.ts

@@ -1,7 +0,0 @@
-/** Median of finite values. Returns null for an empty list. */
-export declare function median(values: readonly number[]): number | null;
-/**
- * Median absolute deviation, scaled so it estimates a standard deviation for normal data.
- * A few extreme values barely move it, so past incidents do not widen the learned band.
- */
-export declare function robustScale(values: readonly number[], center: number): number;

package/dist/watch/engine/rules.d.ts

@@ -1,22 +0,0 @@
-import { NormalRuleConfig, NormalSeverity } from './normal';
-export interface FlatlineOptions {
-    /** Identical readings in a row before the series counts as stuck. Defaults to 6. */
-    points?: number;
-    severity?: NormalSeverity;
-    message?: string;
-}
-/** Flags a reading that has not changed for `points` readings, such as a stuck sensor. */
-export declare function flatline<Row>({ points, severity, message, }?: FlatlineOptions): NormalRuleConfig<Row>;
-export interface JumpOptions {
-    /** Relative change from the previous reading, such as 0.5 for 50%. */
-    by: number;
-    /** Defaults to `'both'`. */
-    direction?: 'up' | 'down' | 'both';
-    severity?: NormalSeverity;
-    message?: string;
-}
-/**
- * Flags a sudden relative change from the previous known reading. Gaps are skipped, and a
- * previous reading of zero has no relative change, so it never fires.
- */
-export declare function jump<Row>({ by, direction, severity, message, }: JumpOptions): NormalRuleConfig<Row>;

package/dist/watch/engine/status.d.ts

@@ -1,39 +0,0 @@
-import { NormalFlag, NormalPoint, NormalSeverity } from './normal';
-export interface NormalStatusOptions {
-    /** Flagged readings in a row before the series becomes active. Defaults to 2. */
-    enter?: number;
-    /** Normal readings in a row before an active series clears. Defaults to 3. */
-    exit?: number;
-}
-export type NormalStatusEvent = {
-    type: 'activated';
-    index: number;
-    severity: NormalSeverity;
-    flags: readonly NormalFlag[];
-} | {
-    type: 'escalated';
-    index: number;
-    severity: 'critical';
-    flags: readonly NormalFlag[];
-} | {
-    type: 'cleared';
-    index: number;
-};
-export interface NormalStatus {
-    active: boolean;
-    /** The strongest severity since the series became active. */
-    severity: NormalSeverity | null;
-    /** Row index where the current incident started. */
-    since: number | null;
-    /** Flags on the latest flagged reading of the current incident. */
-    flags: readonly NormalFlag[];
-    /** The largest score in the current incident. */
-    score: number;
-    events: readonly NormalStatusEvent[];
-}
-/**
- * Turn per-reading flags into a steady incident state. A series must stay unusual for `enter`
- * readings to activate and normal for `exit` readings to clear, so a value sitting on an edge
- * does not flicker. Skipped rows and missing readings hold the current state.
- */
-export declare function trackNormalStatus(points: readonly NormalPoint[], { enter, exit }?: NormalStatusOptions): NormalStatus;

package/dist/watch/index.d.ts

@@ -1,14 +0,0 @@
-export { evaluateNormal } from './engine/normal';
-export type { EvaluateNormalOptions, NormalFlag, NormalGiven, NormalLearnOptions, NormalLimits, NormalPeriod, NormalPoint, NormalRule, NormalRuleConfig, NormalRuleContext, NormalRuleTest, NormalSeverity, NormalSource, NormalSpec, NormalTolerance, } from './engine/normal';
-export { flatline, jump } from './engine/rules';
-export type { FlatlineOptions, JumpOptions } from './engine/rules';
-export { trackNormalStatus } from './engine/status';
-export type { NormalStatus, NormalStatusEvent, NormalStatusOptions } from './engine/status';
-export { describeFlag } from './engine/describe';
-export type { DescribeFlagOptions } from './engine/describe';
-export { describeExplanation, explainDeviation, explainReadings } from './engine/explain';
-export type { DescribeExplanationOptions, DeviationExplanation, DeviationPart, ExplainReadingsOptions, NormalBreakdown, } from './engine/explain';
-export { BoardItem, BoardItemTab, BoardToolbar, ChartBoard, useBoard, useBoardItem, } from './board/chart-board';
-export type { BoardEvent, BoardItemProps, BoardStorage, ChartBoardProps, } from './board/chart-board';
-export { boardReducer, rankBoard } from './board/board-state';
-export type { BoardAction, BoardAlarm, BoardItemState, BoardState, NormalReport, } from './board/board-state';

package/dist/watch/normal-layer.d.ts

@@ -1,18 +0,0 @@
-import { ReactElement } from 'react';
-import { NormalSeverity } from './engine/normal';
-/** Field IDs a watched series carries for its normal band. */
-export declare const NORMAL_LOWER = "normalLower";
-export declare const NORMAL_UPPER = "normalUpper";
-export interface NormalLayerProps {
-    series: string;
-    /** Severity of each unusual reading, by row index in the card's data. */
-    flagged: ReadonlyMap<number, NormalSeverity>;
-    /** The band sits under the series' line; the unusual stretches sit over it. */
-    part: 'band' | 'flags';
-}
-/**
- * The calm band where a series is expected to be, and the series' own line recolored where it
- * is unusual, with a dot where each unusual stretch ends. The band reads from the series'
- * normal fields and breaks wherever either edge is unknown.
- */
-export declare function NormalLayer({ series, flagged, part }: NormalLayerProps): ReactElement;

package/dist/watch.d.ts

@@ -1,2 +0,0 @@
-export * from './watch/index'
-export {}