@akcelik/strct 0.28.0 → 0.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akcelik/strct",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "description": "UIStruct — a standalone Angular component library with a tokenised, multi-palette theme system, built for datacenter / infrastructure management UIs.",
   "author": "Serkan Akcelik <serkan.akcelik@gmail.com>",
   "license": "MIT",
@@ -32,7 +32,8 @@
     "@angular/common": "^21.2.0",
     "@angular/core": "^21.2.0",
     "@angular/forms": "^21.2.0",
-    "@angular/platform-browser": "^21.2.0"
+    "@angular/platform-browser": "^21.2.0",
+    "@angular/router": "^21.2.0"
   },
   "dependencies": {
     "tslib": "^2.3.0"

package/types/akcelik-strct.d.ts

@@ -247,6 +247,22 @@ interface StrctRailItem {
     /** Badge colour (defaults to `accent`). When collapsed it renders as a dot. */
     badgeStatus?: StrctRailStatus;
     disabled?: boolean;
+    /** `'bottom'` pins the item to the foot of the rail (e.g. Administration). */
+    placement?: 'top' | 'bottom';
+    /**
+     * Render as a real router link (`<a routerLink>`): middle-click, ⌘/Ctrl-click
+     * and "open in new tab" work; `(select)` still fires on plain activation.
+     * When neither `routerLink` nor `href` is set the item stays a `<button>`.
+     */
+    routerLink?: string | unknown[];
+    /** Render as a plain `<a href>` (external or non-router destinations). */
+    href?: string;
+    /** Small trailing status dot with no text (e.g. "unsaved changes"). */
+    dot?: boolean;
+    /** Dot tone; defaults to `accent`. */
+    dotStatus?: StrctRailStatus;
+    /** Muted trailing icon (e.g. "restart required"), before any badge / dot. */
+    trailingIcon?: string;
 }
 /**
  * Collapsible, data-driven primary navigation rail for an application shell.
@@ -269,7 +285,16 @@ declare class StrctRail {
     readonly ariaLabel: _angular_core.InputSignal<string>;
     /** Emitted when an item is chosen. */
     readonly select: _angular_core.OutputEmitterRef<StrctRailItem>;
-    protected pick(item: StrctRailItem): void;
+    protected readonly topItems: _angular_core.Signal<StrctRailItem[]>;
+    protected readonly bottomItems: _angular_core.Signal<StrctRailItem[]>;
+    /** Enabled item with a router destination → renders as `<a routerLink>`. */
+    protected isRouted(item: StrctRailItem): boolean;
+    /**
+     * Active state of a router-link item: an explicit `activeId` is authoritative;
+     * without one, the router's own active state drives it.
+     */
+    protected isActive(item: StrctRailItem, routerActive: boolean): boolean;
+    protected pick(item: StrctRailItem, event?: MouseEvent): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<StrctRail, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<StrctRail, "strct-rail", never, { "items": { "alias": "items"; "required": true; "isSignal": true; }; "activeId": { "alias": "activeId"; "required": false; "isSignal": true; }; "collapsed": { "alias": "collapsed"; "required": false; "isSignal": true; }; "collapsible": { "alias": "collapsible"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; }, { "activeId": "activeIdChange"; "collapsed": "collapsedChange"; "select": "select"; }, never, never, true, never>;
 }
@@ -1111,6 +1136,16 @@ interface StrctMenuLink {
     /** Optional leading icon name. */
     icon?: string;
     disabled?: boolean;
+    /** Trailing count/label chip (e.g. a deviation count). */
+    badge?: string | number;
+    /** Badge tone; defaults to `accent` (shared vocabulary with {@link StrctRailItem}). */
+    badgeStatus?: StrctRailStatus;
+    /** Small trailing status dot with no text (e.g. "unsaved changes"). */
+    dot?: boolean;
+    /** Dot tone; defaults to `accent`. */
+    dotStatus?: StrctRailStatus;
+    /** Muted trailing icon (e.g. "restart required"), before any badge / dot. */
+    trailingIcon?: string;
 }
 /** A category (level 1) that groups {@link StrctMenuLink} items (level 2). */
 interface StrctMenuSection {
@@ -2240,7 +2275,8 @@ type StrctChartType = 'line' | 'area' | 'bar';
 type StrctChartCurve = 'smooth' | 'linear' | 'step';
 /** One series in a multi-series chart. */
 interface StrctChartSeries {
-    data: number[];
+    /** Values; `null` (or `NaN`) marks a data gap — the line breaks, no interpolation. */
+    data: (number | null)[];
     /** Legend + tooltip name. */
     label?: string;
     /** Per-series color; falls back to the chart's `status`. */
@@ -2255,6 +2291,24 @@ interface StrctChartSeries {
      * custom SVG dasharray string to tune it.
      */
     dash?: boolean | string;
+    /**
+     * Optional per-point lower/upper bound (e.g. min/max per downsampled bucket).
+     * When both are set a soft band is filled between them behind the line, so
+     * within-bucket spikes stay visible; the tooltip shows `avg (min–max)`.
+     */
+    lower?: (number | null)[];
+    upper?: (number | null)[];
+}
+/** A vertical event / annotation marker anchored to a data index. */
+interface StrctChartAnnotation {
+    /** X position as a data index. */
+    index: number;
+    /** Shown near the top of the line and in the tooltip at that index. */
+    label?: string;
+    /** Line color; default 'accent'. */
+    status?: StrctChartStatus;
+    /** Dashed line; default true. */
+    dashed?: boolean;
 }
 /** A horizontal reference / threshold line. */
 interface StrctChartThreshold {
@@ -2274,12 +2328,15 @@ interface SeriesRender {
     label: string;
     area: boolean;
     dash: string | null;
-    pts: Pt[];
+    pts: (Pt | null)[];
     path: string;
     areaPath: string;
+    bandPath: string;
     /** Global x-offset (right-aligned) so shorter series line up on the right. */
     offset: number;
-    data: number[];
+    data: (number | null)[];
+    lower?: (number | null)[];
+    upper?: (number | null)[];
 }
 /**
  * Single- or multi-series chart (line / area / bar). Dependency-free SVG,
@@ -2297,8 +2354,8 @@ interface SeriesRender {
  *   <strct-chart [series]="[{data:inArr,label:'In'},{data:outArr,label:'Out'}]" legend />
  */
 declare class StrctChart {
-    /** Single-series data (or use `series`). */
-    readonly data: _angular_core.InputSignal<number[]>;
+    /** Single-series data (or use `series`). `null` / `NaN` marks a gap — the line breaks. */
+    readonly data: _angular_core.InputSignal<(number | null)[]>;
     /** Multiple series; when set it takes precedence over `data`. */
     readonly series: _angular_core.InputSignal<StrctChartSeries[] | null>;
     /** Visual type / variant. */
@@ -2355,6 +2412,28 @@ declare class StrctChart {
      * `[valueFormat]="v => v.toFixed(3) + ' %'"`. When null, the raw value is shown.
      */
     readonly valueFormat: _angular_core.InputSignal<((v: number) => string) | null>;
+    /** Vertical event / annotation markers ("alarm raised", "deploy", …). */
+    readonly annotations: _angular_core.InputSignal<StrctChartAnnotation[]>;
+    /**
+     * Drive the crosshair externally (e.g. mirror a sibling chart's hover for a
+     * vCenter-style synced dashboard). A local pointer wins while over this chart.
+     */
+    readonly activeIndex: _angular_core.InputSignal<number | null>;
+    /** Drag-select a range; the selection is emitted through `brushChange`. */
+    readonly brush: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Drag-select **zooms into** the selected range (implies `brush`).
+     * Double-click, Escape or the reset chip zooms back out.
+     */
+    readonly zoom: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Tooltip text for a gap (null) point. */
+    readonly gapText: _angular_core.InputSignal<string>;
+    /** Accessible label of the reset-zoom chip (localizable). */
+    readonly resetLabel: _angular_core.InputSignal<string>;
+    /** Emits the hovered point index (or null on leave) — wire cross-chart sync with it. */
+    readonly hoverIndex: _angular_core.OutputEmitterRef<number | null>;
+    /** Emits the brushed [startIndex, endIndex] (inclusive), or null when cleared. */
+    readonly brushChange: _angular_core.OutputEmitterRef<[number, number] | null>;
     protected readonly pad: {
         l: number;
         r: number;
@@ -2376,6 +2455,14 @@ declare class StrctChart {
     /** Reactive OS motion preference (tracks live changes, not just first load). */
     private readonly reduceMotion;
     protected readonly hoverIdx: _angular_core.WritableSignal<number | null>;
+    protected readonly dispIdx: _angular_core.Signal<number | null>;
+    private readonly viewRange;
+    protected readonly brushDrag: _angular_core.WritableSignal<{
+        a: number;
+        b: number;
+    } | null>;
+    private readonly brushEnabled;
+    protected readonly zoomed: _angular_core.Signal<boolean>;
     constructor();
     private readonly seriesResolved;
     protected readonly isMulti: _angular_core.Signal<boolean>;
@@ -2384,16 +2471,22 @@ declare class StrctChart {
     protected readonly isEmpty: _angular_core.Signal<boolean>;
     /** Number of x slots. */
     private readonly nx;
+    /** Visible index window: the brush-zoom range, or the full data. */
+    private readonly domain;
     /** Left padding: wider when the y-axis labels are shown. */
     protected readonly pl: _angular_core.Signal<number>;
     private chartW;
     private chartH;
-    /** Horizontal gap between two data points, in px. */
+    /** Horizontal gap between two data points, in px (of the visible window). */
     private stepX;
+    /** Real values inside the visible window (multi-aware; bands included). */
+    private readonly visibleValues;
     private readonly yMax;
     private readonly yMin;
     private yOf;
-    protected readonly points: _angular_core.Signal<Pt[]>;
+    protected readonly points: _angular_core.Signal<(Pt | null)[]>;
+    /** Non-gap points only (dot rendering). */
+    protected readonly dotPts: _angular_core.Signal<Pt[]>;
     protected readonly head: _angular_core.Signal<Pt | null>;
     private readonly plotPoints;
     protected readonly linePath: _angular_core.Signal<string>;
@@ -2430,17 +2523,19 @@ declare class StrctChart {
     protected readonly hoverX: _angular_core.Signal<number | null>;
     protected readonly hoverPt: _angular_core.Signal<Pt | null>;
     protected readonly hoverValue: _angular_core.Signal<number | "">;
+    /** The hovered slot exists but holds a gap (single-series). */
+    protected readonly hoverGap: _angular_core.Signal<boolean>;
     /** hoverValue run through valueFormat (unit / precision), else the raw value. */
     protected readonly hoverValueText: _angular_core.Signal<string>;
     /** Delta magnitude, formatted the same way so its unit matches the value. */
     protected readonly absDeltaText: _angular_core.Signal<string>;
     protected readonly hoverLabel: _angular_core.Signal<string>;
-    /** Change from the previous point (single-series; null at the first point). */
+    /** Change from the previous point (single-series; null at the first point or across a gap). */
     protected readonly hoverDelta: _angular_core.Signal<number | null>;
     protected readonly absDelta: _angular_core.Signal<number>;
     /** Second tooltip line: "Xs ago" while live, else the x label. */
     protected readonly hoverMeta: _angular_core.Signal<string>;
-    /** Per-series value at the hovered index (multi-series tooltip). */
+    /** Per-series value at the hovered index (multi-series tooltip; bands as `avg (min–max)`). */
     protected readonly hoverRows: _angular_core.Signal<{
         label: string;
         color: string;
@@ -2453,17 +2548,53 @@ declare class StrctChart {
         y: number;
         color: string;
     }[]>;
+    protected readonly annotationLines: _angular_core.Signal<{
+        x: number;
+        color: string;
+        dashed: boolean;
+        label: string;
+        index: number;
+    }[]>;
+    /** The annotation sitting exactly under the crosshair, if any. */
+    protected readonly annAt: _angular_core.Signal<{
+        x: number;
+        color: string;
+        dashed: boolean;
+        label: string;
+        index: number;
+    } | null>;
+    protected readonly brushRect: _angular_core.Signal<{
+        x: number;
+        w: number;
+    } | null>;
+    /** Zoom back out to the full data window (also emits `brushChange` null). */
+    resetZoom(): void;
     /** Screen-reader summary of the whole chart (role="img" name). */
     protected readonly chartAria: _angular_core.Signal<string>;
     /** aria-live text announcing the hovered / keyboard-selected point. */
     protected readonly srText: _angular_core.Signal<string>;
-    /** Pixel x of a data index (shared by the plot and the x-axis labels). */
+    /** Pixel x of a data index (shared by the plot, labels and annotations). */
     protected xOf(i: number): number;
-    /** Keyboard access to the crosshair: arrows walk the points. */
+    /** Set the local hover index, emitting `hoverIndex` on change. */
+    private setHover;
+    protected onLeave(): void;
+    /** Keyboard access: arrows walk the points; Escape unwinds brush → zoom → crosshair. */
     protected onKey(event: KeyboardEvent): void;
+    /** Data index under the pointer, clamped to the visible window. */
+    private idxAt;
+    protected onDown(event: PointerEvent): void;
     protected onMove(event: PointerEvent): void;
+    protected onUp(): void;
+    protected onDblClick(): void;
+    /**
+     * The rendered chart as a standalone SVG string — theme colors resolved to
+     * literals, background baked in, y-tick / x-label text included.
+     */
+    toSVG(): string;
+    /** The chart as a PNG data URL at the given scale (default 2×). */
+    toPNG(scale?: number): Promise<string>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<StrctChart, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<StrctChart, "strct-chart", never, { "data": { "alias": "data"; "required": false; "isSignal": true; }; "series": { "alias": "series"; "required": false; "isSignal": true; }; "type": { "alias": "type"; "required": false; "isSignal": true; }; "curve": { "alias": "curve"; "required": false; "isSignal": true; }; "area": { "alias": "area"; "required": false; "isSignal": true; }; "glow": { "alias": "glow"; "required": false; "isSignal": true; }; "live": { "alias": "live"; "required": false; "isSignal": true; }; "interval": { "alias": "interval"; "required": false; "isSignal": true; }; "interactive": { "alias": "interactive"; "required": false; "isSignal": true; }; "strokeWidth": { "alias": "strokeWidth"; "required": false; "isSignal": true; }; "grid": { "alias": "grid"; "required": false; "isSignal": true; }; "dots": { "alias": "dots"; "required": false; "isSignal": true; }; "legend": { "alias": "legend"; "required": false; "isSignal": true; }; "labels": { "alias": "labels"; "required": false; "isSignal": true; }; "xTicks": { "alias": "xTicks"; "required": false; "isSignal": true; }; "xFormat": { "alias": "xFormat"; "required": false; "isSignal": true; }; "status": { "alias": "status"; "required": false; "isSignal": true; }; "height": { "alias": "height"; "required": false; "isSignal": true; }; "max": { "alias": "max"; "required": false; "isSignal": true; }; "min": { "alias": "min"; "required": false; "isSignal": true; }; "yAxis": { "alias": "yAxis"; "required": false; "isSignal": true; }; "yTicks": { "alias": "yTicks"; "required": false; "isSignal": true; }; "axisFormat": { "alias": "axisFormat"; "required": false; "isSignal": true; }; "thresholds": { "alias": "thresholds"; "required": false; "isSignal": true; }; "emptyText": { "alias": "emptyText"; "required": false; "isSignal": true; }; "agoFormat": { "alias": "agoFormat"; "required": false; "isSignal": true; }; "valueFormat": { "alias": "valueFormat"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<StrctChart, "strct-chart", never, { "data": { "alias": "data"; "required": false; "isSignal": true; }; "series": { "alias": "series"; "required": false; "isSignal": true; }; "type": { "alias": "type"; "required": false; "isSignal": true; }; "curve": { "alias": "curve"; "required": false; "isSignal": true; }; "area": { "alias": "area"; "required": false; "isSignal": true; }; "glow": { "alias": "glow"; "required": false; "isSignal": true; }; "live": { "alias": "live"; "required": false; "isSignal": true; }; "interval": { "alias": "interval"; "required": false; "isSignal": true; }; "interactive": { "alias": "interactive"; "required": false; "isSignal": true; }; "strokeWidth": { "alias": "strokeWidth"; "required": false; "isSignal": true; }; "grid": { "alias": "grid"; "required": false; "isSignal": true; }; "dots": { "alias": "dots"; "required": false; "isSignal": true; }; "legend": { "alias": "legend"; "required": false; "isSignal": true; }; "labels": { "alias": "labels"; "required": false; "isSignal": true; }; "xTicks": { "alias": "xTicks"; "required": false; "isSignal": true; }; "xFormat": { "alias": "xFormat"; "required": false; "isSignal": true; }; "status": { "alias": "status"; "required": false; "isSignal": true; }; "height": { "alias": "height"; "required": false; "isSignal": true; }; "max": { "alias": "max"; "required": false; "isSignal": true; }; "min": { "alias": "min"; "required": false; "isSignal": true; }; "yAxis": { "alias": "yAxis"; "required": false; "isSignal": true; }; "yTicks": { "alias": "yTicks"; "required": false; "isSignal": true; }; "axisFormat": { "alias": "axisFormat"; "required": false; "isSignal": true; }; "thresholds": { "alias": "thresholds"; "required": false; "isSignal": true; }; "emptyText": { "alias": "emptyText"; "required": false; "isSignal": true; }; "agoFormat": { "alias": "agoFormat"; "required": false; "isSignal": true; }; "valueFormat": { "alias": "valueFormat"; "required": false; "isSignal": true; }; "annotations": { "alias": "annotations"; "required": false; "isSignal": true; }; "activeIndex": { "alias": "activeIndex"; "required": false; "isSignal": true; }; "brush": { "alias": "brush"; "required": false; "isSignal": true; }; "zoom": { "alias": "zoom"; "required": false; "isSignal": true; }; "gapText": { "alias": "gapText"; "required": false; "isSignal": true; }; "resetLabel": { "alias": "resetLabel"; "required": false; "isSignal": true; }; }, { "hoverIndex": "hoverIndex"; "brushChange": "brushChange"; }, never, never, true, never>;
 }
 
 /** A single weighted slice of a donut chart. */
@@ -2819,4 +2950,4 @@ declare class StrctEmptyState {
 }
 
 export { STRCT_ICONS, STRCT_ICON_GROUPS, STRCT_MASKS, STRCT_PALETTES, STRCT_RAW_ICONS, StrctAccordion, StrctAccordionPanel, StrctAlert, StrctAvatar, StrctBadge, StrctBreadcrumb, StrctBreadcrumbItem, StrctButton, StrctButtonGroup, StrctCard, StrctCardBlock, StrctCardFooter, StrctCardHeader, StrctCascadeHost, StrctCascadeNode, StrctCascadeSelect, StrctCellDef, StrctCellStatus, StrctChart, StrctCheckbox, StrctChips, StrctColorPicker, StrctCombobox, StrctCommandPalette, StrctContextMenu, StrctContextMenuTrigger, StrctDatagrid, StrctDatagridActionBar, StrctDatepicker, StrctDesc, StrctDescriptionList, StrctDivider, StrctDonut, StrctDrawer, StrctDrawerFooter, StrctDropdown, StrctDropdownDivider, StrctDropdownItem, StrctEmptyState, StrctField, StrctFile, StrctFlow, StrctFooter, StrctGauge, StrctHeader, StrctHero, StrctIcon, StrctInput, StrctInputMask, StrctInputOtp, StrctKbd, StrctKnob, StrctLogin, StrctMenuPanel, StrctMenuService, StrctMetricTile, StrctModal, StrctNav, StrctNavItem, StrctOverlay, StrctPagination, StrctPassword, StrctProgress, StrctRadio, StrctRadioGroup, StrctRail, StrctRange, StrctRating, StrctRowDetailDef, StrctSectionMenu, StrctSegmented, StrctShell, StrctShellService, StrctSignpost, StrctSkeleton, StrctSparkline, StrctSpeedDial, StrctSpinner, StrctStack, StrctStackItem, StrctStep, StrctSubmenu, StrctTab, StrctTable, StrctTabs, StrctTag, StrctThemeService, StrctThemeSwitcher, StrctTimeline, StrctTimelineItem, StrctToastOutlet, StrctToastService, StrctToggle, StrctTooltip, StrctTree, StrctTreeNode, StrctVerticalNav, StrctWizard, registerStrctIcon, strctValidationIcon, strctValidationTone };
-export type { StrctAlertType, StrctAvatarSize, StrctAvatarStatus, StrctBadgeStatus, StrctButtonSize, StrctButtonVariant, StrctCascadeOption, StrctCellContext, StrctChartCurve, StrctChartSeries, StrctChartStatus, StrctChartThreshold, StrctChartType, StrctColumn, StrctCommandItem, StrctDatagridColumn, StrctDatagridLabels, StrctDescAlign, StrctDescItem, StrctDonutSegment, StrctDrawerSide, StrctDrawerSize, StrctEmptyVariant, StrctFlowDirection, StrctFlowNode, StrctFlowOrientation, StrctIconBadge, StrctKnobStatus, StrctMenuItem, StrctMenuLink, StrctMenuOpenOptions, StrctMenuSection, StrctMetricStatus, StrctModalSize, StrctMode, StrctOption, StrctOverlayPlacement, StrctPalette, StrctPaletteInfo, StrctProgressStatus, StrctRailItem, StrctRailStatus, StrctRow, StrctRowId, StrctSegmentedOption, StrctSegmentedSize, StrctSignpostPosition, StrctSpeedDialDirection, StrctSpinnerSize, StrctStatus, StrctTagStatus, StrctThresholds, StrctTimelineState, StrctToast, StrctToastOptions, StrctToastType, StrctTooltipPosition, StrctTreeMenuEvent, StrctTreeNodeData, StrctTreeNodeMenuFn, StrctValidationState, StrctValidationStatus };
+export type { StrctAlertType, StrctAvatarSize, StrctAvatarStatus, StrctBadgeStatus, StrctButtonSize, StrctButtonVariant, StrctCascadeOption, StrctCellContext, StrctChartAnnotation, StrctChartCurve, StrctChartSeries, StrctChartStatus, StrctChartThreshold, StrctChartType, StrctColumn, StrctCommandItem, StrctDatagridColumn, StrctDatagridLabels, StrctDescAlign, StrctDescItem, StrctDonutSegment, StrctDrawerSide, StrctDrawerSize, StrctEmptyVariant, StrctFlowDirection, StrctFlowNode, StrctFlowOrientation, StrctIconBadge, StrctKnobStatus, StrctMenuItem, StrctMenuLink, StrctMenuOpenOptions, StrctMenuSection, StrctMetricStatus, StrctModalSize, StrctMode, StrctOption, StrctOverlayPlacement, StrctPalette, StrctPaletteInfo, StrctProgressStatus, StrctRailItem, StrctRailStatus, StrctRow, StrctRowId, StrctSegmentedOption, StrctSegmentedSize, StrctSignpostPosition, StrctSpeedDialDirection, StrctSpinnerSize, StrctStatus, StrctTagStatus, StrctThresholds, StrctTimelineState, StrctToast, StrctToastOptions, StrctToastType, StrctTooltipPosition, StrctTreeMenuEvent, StrctTreeNodeData, StrctTreeNodeMenuFn, StrctValidationState, StrctValidationStatus };