@skyfall_ai/aegis 0.1.0 → 0.2.0

package/dist/index.d.mts

@@ -1,6 +1,7 @@
 import * as react from 'react';
 import { ButtonHTMLAttributes, ReactNode, InputHTMLAttributes, TextareaHTMLAttributes, SelectHTMLAttributes, LabelHTMLAttributes, HTMLAttributes, TableHTMLAttributes, TdHTMLAttributes, ThHTMLAttributes } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import { TooltipProps as TooltipProps$1, LegendProps } from 'recharts';
 
 /** Brand primary palette */
 declare const brandPrimary: {
@@ -1726,6 +1727,340 @@ interface BannerProps extends HTMLAttributes<HTMLDivElement> {
  */
 declare function Banner({ status, dismissible, onDismiss, action, children, className, ...props }: BannerProps): react_jsx_runtime.JSX.Element;
 
+type ChartCardState = 'ready' | 'loading' | 'empty' | 'error';
+interface ChartCardProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
+    /** Card title (e.g. "30-day patient adherence") */
+    title?: ReactNode;
+    /** Optional subtitle / explanation */
+    subtitle?: ReactNode;
+    /** Headline metric displayed prominently in the header */
+    metric?: ReactNode;
+    /** Trend chip beside the metric (use the Aegis Badge or any node) */
+    trend?: ReactNode;
+    /** Optional actions (filters, export, etc.) rendered in the header */
+    actions?: ReactNode;
+    /** Footer content rendered below the chart body */
+    footer?: ReactNode;
+    /** Visual padding density */
+    density?: 'comfortable' | 'compact';
+    /** Render state — controls whether children, loader, empty, or error renders */
+    state?: ChartCardState;
+    /** Custom empty-state node */
+    emptyState?: ReactNode;
+    /** Custom loading-state node */
+    loadingState?: ReactNode;
+    /** Custom error-state node */
+    errorState?: ReactNode;
+    /** Optional aria-label for the chart region */
+    ariaLabel?: string;
+}
+/**
+ * ChartCard — the unifying shell for every Aegis chart component.
+ *
+ * Provides a consistent header (title, subtitle, headline metric, trend chip,
+ * actions), body slot, footer slot, and built-in loading / empty / error states.
+ *
+ * Every chart component in Aegis composes this card so the system feels
+ * cohesive and developers get visual states for free.
+ */
+declare function ChartCard({ title, subtitle, metric, trend, actions, footer, density, state, emptyState, loadingState, errorState, ariaLabel, className, children, ...props }: ChartCardProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Skyfall Aegis — Chart Theme
+ *
+ * Centralized theme tokens for all Recharts-based components.
+ * Reads from CSS custom properties so chart visuals stay in sync with
+ * the rest of the Aegis design system.
+ */
+/**
+ * The Aegis chart series palette. Order is intentional — earlier colors
+ * are used first so simple charts always pull from the most credible,
+ * brand-aligned hues before moving into supporting accents.
+ */
+declare const aegisSeriesPalette: readonly ["var(--aegis-data-vis-1)", "var(--aegis-data-vis-2)", "var(--aegis-data-vis-3)", "var(--aegis-data-vis-4)", "var(--aegis-data-vis-5)"];
+/**
+ * Resolve a series color by index, wrapping the palette if more series
+ * exist than available colors. Accepts an explicit override.
+ */
+declare function getSeriesColor(index: number, override?: string): string;
+/**
+ * Token-driven chart theme. Used to style axes, gridlines, tooltips,
+ * legends, etc. so every chart in Aegis feels like part of one system.
+ */
+declare const aegisChartTheme: {
+    readonly axis: {
+        readonly stroke: "var(--aegis-data-vis-axis)";
+        readonly fontSize: 12;
+        readonly fontFamily: "var(--aegis-font-family-sans)";
+        readonly tickColor: "var(--aegis-color-text-muted)";
+    };
+    readonly grid: {
+        readonly stroke: "var(--aegis-data-vis-gridline)";
+        readonly strokeDasharray: "3 3";
+    };
+    readonly tooltip: {
+        readonly background: "var(--aegis-color-surface-overlay)";
+        readonly border: "var(--aegis-color-border-default)";
+        readonly text: "var(--aegis-color-text-primary)";
+        readonly muted: "var(--aegis-color-text-secondary)";
+    };
+    readonly reference: {
+        readonly stroke: "var(--aegis-color-text-muted)";
+        readonly strokeDasharray: "4 4";
+    };
+};
+type ChartSeries<T = Record<string, unknown>> = {
+    /** Property key on the data row that holds the series value */
+    dataKey: keyof T & string;
+    /** Display label for tooltip / legend */
+    label?: string;
+    /** Optional explicit color (defaults to Aegis palette) */
+    color?: string;
+};
+type ValueFormatter = (value: number | string) => string;
+/** Default number formatter — locale-aware, with sensible compact behavior */
+declare const defaultValueFormatter: ValueFormatter;
+
+interface ChartTooltipProps extends TooltipProps$1<number, string> {
+    /** Optional formatter for displayed values */
+    valueFormatter?: ValueFormatter;
+    /** Optional formatter for the tooltip label (e.g. axis category) */
+    labelFormatter?: (label: string) => string;
+}
+/**
+ * Aegis-styled tooltip used by every chart in the system.
+ *
+ * Pass directly to Recharts `<Tooltip content={<ChartTooltip />} />`.
+ */
+declare function ChartTooltip({ active, payload, label, valueFormatter, labelFormatter, }: ChartTooltipProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Aegis-styled chart legend. Pass to Recharts via:
+ *   <Legend content={<ChartLegend />} />
+ */
+declare function ChartLegend({ payload }: LegendProps): react_jsx_runtime.JSX.Element | null;
+
+interface LineChartProps<T extends Record<string, unknown>> extends Omit<ChartCardProps, 'children'> {
+    /** Row-shaped data — each row represents one x-axis category */
+    data: T[];
+    /** Property name on each row used for the x-axis */
+    xKey: keyof T & string;
+    /** One or more series definitions */
+    series: ChartSeries<T>[];
+    /** Chart height in pixels (defaults to 280) */
+    height?: number;
+    /** Show legend (defaults to true when more than one series) */
+    showLegend?: boolean;
+    /** Show grid (defaults to true) */
+    showGrid?: boolean;
+    /** Format values in tooltip / axis */
+    valueFormatter?: ValueFormatter;
+    /** Optional reference line value(s) (e.g. target threshold) */
+    referenceLines?: {
+        value: number;
+        label?: string;
+    }[];
+    /** Smooth curves (defaults to true) */
+    smooth?: boolean;
+}
+/**
+ * Aegis LineChart — wraps Recharts with Aegis tokens, shell, and states.
+ *
+ * Time-series and trend visualization for dashboards. Pair with KpiStatCard
+ * for headline metrics or use standalone in a ChartCard layout.
+ */
+declare function LineChart<T extends Record<string, unknown>>({ data, xKey, series, height, showLegend, showGrid, valueFormatter, referenceLines, smooth, state, ...cardProps }: LineChartProps<T>): react_jsx_runtime.JSX.Element;
+
+interface AreaChartProps<T extends Record<string, unknown>> extends Omit<ChartCardProps, 'children'> {
+    data: T[];
+    xKey: keyof T & string;
+    series: ChartSeries<T>[];
+    height?: number;
+    showLegend?: boolean;
+    showGrid?: boolean;
+    /** Stack areas (false = overlapping) */
+    stacked?: boolean;
+    valueFormatter?: ValueFormatter;
+    referenceLines?: {
+        value: number;
+        label?: string;
+    }[];
+}
+/**
+ * Aegis AreaChart — for cumulative trend / volume visualization.
+ *
+ * Set `stacked` to true to stack series on top of each other (e.g. cohort
+ * composition over time).
+ */
+declare function AreaChart<T extends Record<string, unknown>>({ data, xKey, series, height, showLegend, showGrid, stacked, valueFormatter, referenceLines, state, ...cardProps }: AreaChartProps<T>): react_jsx_runtime.JSX.Element;
+
+interface BarChartProps<T extends Record<string, unknown>> extends Omit<ChartCardProps, 'children'> {
+    data: T[];
+    xKey: keyof T & string;
+    series: ChartSeries<T>[];
+    height?: number;
+    showLegend?: boolean;
+    showGrid?: boolean;
+    /** Stack bars (renders as a stacked bar chart) */
+    stacked?: boolean;
+    /** Render bars horizontally */
+    horizontal?: boolean;
+    valueFormatter?: ValueFormatter;
+    referenceLines?: {
+        value: number;
+        label?: string;
+    }[];
+}
+/**
+ * Aegis BarChart — for categorical comparisons.
+ *
+ * Set `stacked` for stacked bars, `horizontal` for horizontal layout
+ * (better for long category labels).
+ */
+declare function BarChart<T extends Record<string, unknown>>({ data, xKey, series, height, showLegend, showGrid, stacked, horizontal, valueFormatter, referenceLines, state, ...cardProps }: BarChartProps<T>): react_jsx_runtime.JSX.Element;
+
+/**
+ * Aegis StackedBarChart — convenience wrapper around BarChart with
+ * `stacked` enabled by default. Use this when stacking is the default
+ * intent (e.g. cohort breakdown over time).
+ */
+declare function StackedBarChart<T extends Record<string, unknown>>(props: Omit<BarChartProps<T>, 'stacked'>): react_jsx_runtime.JSX.Element;
+
+interface DonutChartDatum {
+    /** Display label for the slice */
+    name: string;
+    /** Numeric value */
+    value: number;
+    /** Optional explicit color (defaults to Aegis palette) */
+    color?: string;
+}
+interface DonutChartProps extends Omit<ChartCardProps, 'children'> {
+    data: DonutChartDatum[];
+    /** Center label (e.g. total value) */
+    centerLabel?: string;
+    /** Center sublabel (e.g. "patients") */
+    centerSublabel?: string;
+    /** Render as full pie instead of donut */
+    variant?: 'donut' | 'pie';
+    /** Chart height (defaults to 280) */
+    height?: number;
+    /** Format slice values in tooltip */
+    valueFormatter?: ValueFormatter;
+    /** Show legend list to the right of the chart */
+    showLegend?: boolean;
+}
+/**
+ * Aegis DonutChart — for distribution / part-to-whole comparisons.
+ *
+ * Center label/sublabel slots support headline metrics inside the donut.
+ * For pie semantics, set `variant="pie"`.
+ */
+declare function DonutChart({ data, centerLabel, centerSublabel, variant, height, valueFormatter, showLegend, state, ...cardProps }: DonutChartProps): react_jsx_runtime.JSX.Element;
+
+interface SparklineProps {
+    /** Array of numeric values OR row objects */
+    data: number[] | Record<string, unknown>[];
+    /** Property name when `data` is row-shaped (defaults to "value") */
+    dataKey?: string;
+    /** Render style */
+    variant?: 'line' | 'area';
+    /** Width in px (defaults to 120) — accepts any CSS length */
+    width?: number | string;
+    /** Height in px (defaults to 36) */
+    height?: number | string;
+    /** Line/area color (defaults to first Aegis series color) */
+    color?: string;
+    /** Stroke width (defaults to 2) */
+    strokeWidth?: number;
+    /** Optional accessible label */
+    ariaLabel?: string;
+}
+/**
+ * Aegis Sparkline — minimal inline trend chart for KPIs and table cells.
+ *
+ * Pure visual: no axes, grid, tooltip, or legend. Designed to live inside
+ * stat cards, data grid cells, and dense dashboard surfaces.
+ */
+declare function Sparkline({ data, dataKey, variant, width, height, color, strokeWidth, ariaLabel, }: SparklineProps): react_jsx_runtime.JSX.Element;
+
+type TrendDirection = 'up' | 'down' | 'neutral';
+interface KpiStatCardProps extends HTMLAttributes<HTMLDivElement> {
+    /** Metric label (e.g. "Active patients") */
+    label: string;
+    /** Headline value (e.g. 1284 or "98.2%") */
+    value: ReactNode;
+    /** Optional unit/suffix shown next to the value */
+    unit?: ReactNode;
+    /** Percent change (number) — positive renders as up, negative as down */
+    change?: number;
+    /** Label for the change context (e.g. "vs last 30 days") */
+    changeLabel?: string;
+    /** Override trend direction (otherwise inferred from `change`) */
+    trend?: TrendDirection;
+    /**
+     * For success-positive metrics, set `inverse` to flip color semantics
+     * (e.g. "wait time" — a decrease is good).
+     */
+    inverse?: boolean;
+    /** Optional icon rendered top-right */
+    icon?: ReactNode;
+    /** Optional sparkline data — when present, renders an inline trend chart */
+    sparklineData?: SparklineProps['data'];
+    /** Sparkline color override */
+    sparklineColor?: string;
+    /** Sparkline render variant */
+    sparklineVariant?: SparklineProps['variant'];
+    /** Density variant */
+    density?: 'comfortable' | 'compact';
+}
+/**
+ * KpiStatCard — premium stat card with optional inline sparkline.
+ *
+ * The chart-aware evolution of StatCard. Use for headline KPIs in
+ * dashboards. Pair with `inverse` for metrics where a decrease is positive
+ * (e.g. wait time, error rate).
+ *
+ * Accessibility:
+ * - Trend icons are aria-hidden; meaning is conveyed in visible text plus an
+ *   sr-only direction phrase.
+ * - Sparkline accepts `aria-label` for screen reader trend description.
+ */
+declare function KpiStatCard({ label, value, unit, change, changeLabel, trend, inverse, icon, sparklineData, sparklineColor, sparklineVariant, density, className, ...props }: KpiStatCardProps): react_jsx_runtime.JSX.Element;
+
+interface TrendStatCardProps<T extends Record<string, unknown>> extends HTMLAttributes<HTMLDivElement> {
+    /** Metric label (e.g. "30-day readmissions") */
+    label: string;
+    /** Headline value */
+    value: ReactNode;
+    /** Optional unit (e.g. "%", "patients") */
+    unit?: ReactNode;
+    /** Trend chart data — row-shaped */
+    data: T[];
+    /** X-axis key on each row */
+    xKey: keyof T & string;
+    /** Y value key on each row */
+    yKey: keyof T & string;
+    /** Percent change value */
+    change?: number;
+    /** Change context label */
+    changeLabel?: string;
+    /** Inverse semantics — set true when a decrease is "good" */
+    inverse?: boolean;
+    /** Color override for the trend area */
+    color?: string;
+    /** Format values shown in tooltip */
+    valueFormatter?: ValueFormatter;
+    /** Chart height (defaults to 80) */
+    chartHeight?: number;
+}
+/**
+ * TrendStatCard — KPI card with a prominent trend chart underneath.
+ *
+ * Larger than KpiStatCard's inline sparkline, designed to fill more space
+ * in dashboard rows where a trend story is the primary message.
+ */
+declare function TrendStatCard<T extends Record<string, unknown>>({ label, value, unit, data, xKey, yKey, change, changeLabel, inverse, color, valueFormatter, chartHeight, className, ...props }: TrendStatCardProps<T>): react_jsx_runtime.JSX.Element;
+
 /** Merge CSS module class names, filtering out falsy values */
 declare function cn(...classes: (string | false | null | undefined)[]): string;
 
@@ -1733,4 +2068,4 @@ type Size = 'sm' | 'md' | 'lg';
 type Status = 'success' | 'warning' | 'error' | 'info';
 type Variant = 'primary' | 'secondary' | 'ghost' | 'danger';
 
-export { Accordion, type AccordionItem, type AccordionProps, Alert, type AlertProps, AppointmentCard, type AppointmentCardProps, type AppointmentStatus, Autocomplete, type AutocompleteOption, type AutocompleteProps, Avatar, type AvatarProps, Badge, type BadgeProps, Banner, type BannerProps, type BannerStatus, type BreadcrumbItem, Breadcrumbs, type BreadcrumbsProps, Button, type ButtonProps, Card, type CardProps, Checkbox, CheckboxGroup, type CheckboxGroupOption, type CheckboxGroupProps, type CheckboxProps, ClinicalBanner, type ClinicalBannerProps, type ClinicalSeverity, CollapsiblePanel, type CollapsiblePanelProps, ConfirmDialog, type ConfirmDialogProps, DataGrid, type DataGridColumn, type DataGridProps, DatePicker, type DatePickerProps, DescriptionList, type DescriptionListItem, type DescriptionListProps, Divider, type DividerProps, Drawer, type DrawerProps, EmptyState, type EmptyStateProps, FileUpload, type FileUploadProps, FormField, type FormFieldProps, HelperText, type HelperTextProps, IconButton, type IconButtonProps, Input, type InputProps, InsuranceCard, type InsuranceCardProps, type InsurancePlanType, type InsuranceStatus, LabResultRow, type LabResultRowProps, type LabResultStatus, Label, type LabelProps, List, ListItem, type ListItemProps, type ListProps, MedicationRow, type MedicationRowProps, type MedicationStatus, Modal, type ModalProps, MultiSelect, type MultiSelectOption, type MultiSelectProps, NumberField, type NumberFieldProps, OTPInput, type OTPInputProps, Pagination, type PaginationProps, PatientCard, type PatientCardProps, type PatientStatus, Popover, type PopoverProps, ProgressBar, type ProgressBarProps, Radio, RadioGroup, type RadioGroupOption, type RadioGroupProps, type RadioProps, SearchField, type SearchFieldProps, Select, type SelectProps, SideNav, type SideNavItem, type SideNavProps, type Size, Skeleton, type SkeletonProps, Slider, type SliderProps, type SortDirection, Spinner, type SpinnerProps, StatCard, type StatCardProps, type Status, StatusBadge, type StatusBadgeProps, type StatusBadgeStatus, Stepper, type StepperProps, type StepperStep, Switch, type SwitchProps, type Tab, Table, TableBody, TableCell, TableHead, TableHeaderCell, type TableProps, TableRow, Tabs, type TabsProps, Textarea, type TextareaProps, Timeline, type TimelineItem, type TimelineItemVariant, type TimelineProps, Toast, type ToastProps, type ToastStatus, Tooltip, type TooltipProps, TopNav, type TopNavProps, type Variant, accentTeal, border, borderStyle, borderWidth, brandPrimary, cn, container, controlSize, dataVis, duration, easing, focusRing, fontFamily, fontSize, fontWeight, grid, iconSize, lineHeight, modalSize, neutral, opacity, radius, semantic, shadow, sidebarDefault, space, surface, text, touchMin, tracking, zIndex };
+export { Accordion, type AccordionItem, type AccordionProps, Alert, type AlertProps, AppointmentCard, type AppointmentCardProps, type AppointmentStatus, AreaChart, type AreaChartProps, Autocomplete, type AutocompleteOption, type AutocompleteProps, Avatar, type AvatarProps, Badge, type BadgeProps, Banner, type BannerProps, type BannerStatus, BarChart, type BarChartProps, type BreadcrumbItem, Breadcrumbs, type BreadcrumbsProps, Button, type ButtonProps, Card, type CardProps, ChartCard, type ChartCardProps, type ChartCardState, ChartLegend, type ChartSeries, ChartTooltip, type ChartTooltipProps, Checkbox, CheckboxGroup, type CheckboxGroupOption, type CheckboxGroupProps, type CheckboxProps, ClinicalBanner, type ClinicalBannerProps, type ClinicalSeverity, CollapsiblePanel, type CollapsiblePanelProps, ConfirmDialog, type ConfirmDialogProps, DataGrid, type DataGridColumn, type DataGridProps, DatePicker, type DatePickerProps, DescriptionList, type DescriptionListItem, type DescriptionListProps, Divider, type DividerProps, DonutChart, type DonutChartDatum, type DonutChartProps, Drawer, type DrawerProps, EmptyState, type EmptyStateProps, FileUpload, type FileUploadProps, FormField, type FormFieldProps, HelperText, type HelperTextProps, IconButton, type IconButtonProps, Input, type InputProps, InsuranceCard, type InsuranceCardProps, type InsurancePlanType, type InsuranceStatus, KpiStatCard, type KpiStatCardProps, LabResultRow, type LabResultRowProps, type LabResultStatus, Label, type LabelProps, LineChart, type LineChartProps, List, ListItem, type ListItemProps, type ListProps, MedicationRow, type MedicationRowProps, type MedicationStatus, Modal, type ModalProps, MultiSelect, type MultiSelectOption, type MultiSelectProps, NumberField, type NumberFieldProps, OTPInput, type OTPInputProps, Pagination, type PaginationProps, PatientCard, type PatientCardProps, type PatientStatus, Popover, type PopoverProps, ProgressBar, type ProgressBarProps, Radio, RadioGroup, type RadioGroupOption, type RadioGroupProps, type RadioProps, SearchField, type SearchFieldProps, Select, type SelectProps, SideNav, type SideNavItem, type SideNavProps, type Size, Skeleton, type SkeletonProps, Slider, type SliderProps, type SortDirection, Sparkline, type SparklineProps, Spinner, type SpinnerProps, StackedBarChart, type BarChartProps as StackedBarChartProps, StatCard, type StatCardProps, type Status, StatusBadge, type StatusBadgeProps, type StatusBadgeStatus, Stepper, type StepperProps, type StepperStep, Switch, type SwitchProps, type Tab, Table, TableBody, TableCell, TableHead, TableHeaderCell, type TableProps, TableRow, Tabs, type TabsProps, Textarea, type TextareaProps, Timeline, type TimelineItem, type TimelineItemVariant, type TimelineProps, Toast, type ToastProps, type ToastStatus, Tooltip, type TooltipProps, TopNav, type TopNavProps, type TrendDirection, TrendStatCard, type TrendStatCardProps, type ValueFormatter, type Variant, accentTeal, aegisChartTheme, aegisSeriesPalette, border, borderStyle, borderWidth, brandPrimary, cn, container, controlSize, dataVis, defaultValueFormatter, duration, easing, focusRing, fontFamily, fontSize, fontWeight, getSeriesColor, grid, iconSize, lineHeight, modalSize, neutral, opacity, radius, semantic, shadow, sidebarDefault, space, surface, text, touchMin, tracking, zIndex };