@kubex/zinc 1.1.180 → 1.1.181

package/src/components/chart/live.ts

@@ -0,0 +1,164 @@
+import type { SeriesItem } from './builders';
+
+export interface LivePoint { at: number; value: number | null }
+export interface LivePrediction {
+  status: string; average_rates?: boolean;
+  points: { at: number; expected: number; lower: number; upper: number; available: boolean }[];
+}
+export interface LiveFrame {
+  from: number; until: number; server_time: number; expires_at: number;
+  resolution_seconds: number; metric: string; points: LivePoint[]; prediction?: LivePrediction;
+}
+export interface LiveGrant { stream_url: string; expires_at: number; server_time: number }
+
+const finite = (n: unknown): n is number => typeof n === 'number' && Number.isFinite(n);
+
+/** Authoritative bucket replacement, never increment counts on delivery/reconnect. */
+export class LiveWindow {
+  frame?: LiveFrame;
+  private points = new Map<number, number | null>();
+  private prediction?: LivePrediction;
+
+  apply(value: unknown, snapshot: boolean): LiveFrame {
+    const f = value as LiveFrame;
+    if (!f || !finite(f.from) || !finite(f.until) || f.until <= f.from || !finite(f.server_time) ||
+        !finite(f.expires_at) || !finite(f.resolution_seconds) || f.resolution_seconds <= 0 ||
+        !['hits', 'sum', 'average'].includes(f.metric) || !Array.isArray(f.points) || f.points.length > 10000 ||
+        f.points.some(p => !p || !finite(p.at) || !(p.value === null || finite(p.value)))) throw new Error('Invalid chart frame');
+    if (!snapshot && (!this.frame || this.frame.resolution_seconds !== f.resolution_seconds || this.frame.metric !== f.metric)) throw new Error('Snapshot required');
+    if (f.prediction && (!Array.isArray(f.prediction.points) || f.prediction.points.length > 10000 ||
+        f.prediction.points.some(p => !p || !finite(p.at) || !finite(p.lower) || !finite(p.upper) || !finite(p.expected) || p.upper < p.lower))) throw new Error('Invalid prediction');
+    if (snapshot) { this.points.clear(); this.prediction = f.prediction; }
+    else if (f.prediction) this.prediction = f.prediction;
+    const start = Math.floor(f.from / (f.resolution_seconds * 1000)) * f.resolution_seconds * 1000;
+    for (const p of f.points) if (p.at >= start && p.at < f.until) this.points.set(p.at, p.value);
+    for (const at of this.points.keys()) if (at < start || at >= f.until) this.points.delete(at);
+    // Never keep an unbounded history, including malformed streams with many timestamps.
+    if (this.points.size > 10000) {
+      const ordered = [...this.points.keys()].sort((a, b) => a - b);
+      for (const at of ordered.slice(0, ordered.length - 10000)) this.points.delete(at);
+    }
+    this.frame = f;
+    return f;
+  }
+
+  advance(serverTime: number) {
+    if (!this.frame || !finite(serverTime) || serverTime <= this.frame.server_time) return;
+    const delta = serverTime - this.frame.server_time;
+    this.frame = { ...this.frame, server_time: serverTime, from: this.frame.from + delta, until: this.frame.until + delta };
+    const start = Math.floor(this.frame.from / (this.frame.resolution_seconds * 1000)) * this.frame.resolution_seconds * 1000;
+    for (const at of this.points.keys()) if (at < start) this.points.delete(at);
+  }
+
+  get predictionStatus() { return this.prediction?.status ?? 'unavailable'; }
+
+  series(hideZero = false): SeriesItem[] {
+    const points = [...this.points].sort((a,b) => a[0]-b[0]);
+    const series: SeriesItem[] = [];
+    if (this.prediction && this.frame) {
+      const ps = this.prediction.points.filter(p => p.at < this.frame!.until && p.at >= this.frame!.from - 86400000);
+      const name = this.prediction.average_rates ? 'Expected range (average rate)' : 'Expected range';
+      const data = (pick: (p: typeof ps[number]) => number) => ps.map(p => ({ name: String(p.at), value: [p.at, p.available ? pick(p) : null] }));
+      if (ps.some(p => p.available)) {
+        series.push({ id: 'live-range-base', animation: false, name: '_range_base', data: data(p => p.lower), stack: 'expected', stackStrategy: 'all', symbol: 'none', silent: true,
+          lineStyle: { opacity: 0 }, areaStyle: { opacity: 0 }, z: 1 });
+        series.push({ id: 'live-range', animation: false, name, data: data(p => p.upper - p.lower), stack: 'expected', stackStrategy: 'all', symbol: 'none', silent: true,
+          color: '#93c5fd', lineStyle: { opacity: 0 }, areaStyle: { opacity: 0.3 }, z: 1 });
+      }
+    }
+    series.push({ id: 'live-values', animation: false, name: this.frame?.metric ?? 'Values', data: points.map(([at, value]) => ({ name: String(at), value: [at, hideZero && value === 0 ? null : value] })), symbol: 'none', z: 3 });
+    return series;
+  }
+}
+
+/** One transport per chart. Grants renew only through a same-origin login gate. */
+export class LiveTransport {
+  private source?: EventSource;
+  private timer?: ReturnType<typeof setTimeout>;
+  private expiryTimer?: ReturnType<typeof setTimeout>;
+  private abort?: AbortController;
+  private stopped = true;
+  private generation = 0;
+  private retry = 0;
+  private renewing = false;
+  private readonly frame: (data: unknown, snapshot: boolean) => void;
+  private readonly status: (status: string) => void;
+  private readonly heartbeat?: (serverTime: number) => void;
+  constructor(frame: (data: unknown, snapshot: boolean) => void, status: (status: string) => void,
+              heartbeat?: (serverTime: number) => void) {
+    this.frame = frame; this.status = status; this.heartbeat = heartbeat;
+  }
+
+  start(streamURL: string, renewURL: string) {
+    this.stop(); this.stopped = false;
+    const generation = this.generation;
+    if (streamURL) {
+      this.deadline(Date.now() + 60000, Date.now(), renewURL, generation);
+      this.connect(streamURL, renewURL, generation);
+    }
+    else if (renewURL) void this.renew(renewURL, generation);
+  }
+  stop() {
+    this.stopped = true; this.generation++;
+    this.source?.close(); this.source = undefined;
+    clearTimeout(this.timer); clearTimeout(this.expiryTimer); this.abort?.abort();
+    this.retry = 0; this.renewing = false;
+  }
+  private active(generation: number) { return !this.stopped && generation === this.generation; }
+  private deadline(expires: number, serverTime: number, renewURL: string, generation: number) {
+    if (!finite(expires) || !finite(serverTime)) throw new Error('Invalid grant expiry');
+    const remaining = expires - serverTime;
+    clearTimeout(this.expiryTimer); clearTimeout(this.timer);
+    this.expiryTimer = setTimeout(() => {
+      if (!this.active(generation)) return;
+      this.source?.close(); this.source = undefined; this.status('expired');
+    }, Math.max(0, remaining));
+    if (renewURL && !this.renewing) this.timer = setTimeout(() => void this.renew(renewURL, generation), Math.max(0, remaining - 10000));
+  }
+  private connect(streamURL: string, renewURL: string, generation: number) {
+    const url = new URL(streamURL, location.href);
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password) throw new Error('Invalid stream URL');
+    this.source?.close();
+    const source = new EventSource(url.href); // No cross-origin cookies or app credentials.
+    this.source = source;
+    this.status('connecting');
+    source.onopen = () => { if (this.active(generation)) this.status('connected'); };
+    for (const event of ['snapshot', 'delta', 'heartbeat']) source.addEventListener(event, (message: MessageEvent<string>) => {
+      if (!this.active(generation) || this.source !== source) return;
+      try {
+        const f = JSON.parse(message.data) as LiveFrame;
+        if (event !== 'heartbeat') this.frame(f, event === 'snapshot');
+        else this.heartbeat?.(f.server_time);
+        this.deadline(f.expires_at, f.server_time, renewURL, generation);
+        this.status('connected');
+      } catch { this.stop(); this.status('invalid'); }
+    });
+    source.onerror = () => { if (this.active(generation) && this.source === source) this.status('reconnecting'); };
+  }
+  private async renew(renewURL: string, generation: number) {
+    if (!this.active(generation) || this.renewing) return;
+    const url = new URL(renewURL, location.href);
+    if (url.origin !== location.origin || url.username || url.password) { this.stop(); this.status('denied'); return; }
+    this.renewing = true;
+    const controller = new AbortController(); this.abort = controller;
+    const timeout = setTimeout(() => controller.abort(), 8000);
+    try {
+      const response = await fetch(url.href, { credentials: 'same-origin', redirect: 'error', cache: 'no-store', signal: controller.signal, headers: { Accept: 'application/json', 'x-kx-fetch-style': 'raw-json' } });
+      if (!this.active(generation)) return;
+      if ([401,403].includes(response.status)) { this.stop(); this.status('denied'); return; }
+      if (!response.ok) throw new Error('Grant unavailable');
+      const grant = await response.json() as LiveGrant;
+      if (!this.active(generation)) return;
+      if (!finite(grant.expires_at) || !finite(grant.server_time) || grant.expires_at <= grant.server_time || typeof grant.stream_url !== 'string') throw new Error('Invalid grant');
+      this.renewing = false;
+      this.deadline(grant.expires_at, grant.server_time, renewURL, generation);
+      this.connect(grant.stream_url, renewURL, generation); this.retry = 0;
+    } catch {
+      if (this.active(generation)) {
+        if (this.retry >= 4) { this.stop(); this.status('unavailable'); return; }
+        this.status('reconnecting');
+        this.timer = setTimeout(() => void this.renew(renewURL, generation), Math.min(10000, 1000 * 2 ** Math.min(this.retry++, 4)));
+      }
+    } finally { clearTimeout(timeout); if (this.active(generation)) this.renewing = false; }
+  }
+}

package/src/components/cols/cols.scss

@@ -69,6 +69,11 @@
     gap: 0;
   }
 
+  // Without a gap to sit in, the divider goes on the column's own edge.
+  &--no-gap.cols--divide ::slotted(*:not(:last-child)):after {
+    right: 0;
+  }
+
   // The row rule below each child is drawn by a pseudo reaching to -100vw, so border mode has to clip. Clipping
   // every layout would cut the focus ring off any control sitting flush against a column edge.
   &--border {
@@ -146,6 +151,17 @@ $stack-sizes: (sm, smp, ph, md, lg, hd, '3k', '4k');
       .cols--divide ::slotted(*:not(:last-child)):after {
         display: none;
       }
+
+      // Edge-to-edge columns keep their separation as a rule between the stacked rows
+      .cols--no-gap.cols--divide ::slotted(*:not(:last-child)):after {
+        display: block;
+        top: auto;
+        right: 0;
+        bottom: 0;
+        left: 0;
+        width: auto;
+        height: 1px;
+      }
     }
   }
 }

package/src/components/stat/stat.component.ts

@@ -1,26 +1,19 @@
 import {classMap} from "lit/directives/class-map.js";
 import {type CSSResultGroup, html, unsafeCSS} from 'lit';
+import {ifDefined} from "lit/directives/if-defined.js";
 import {property} from 'lit/decorators.js';
 import ZincElement from '../../internal/zinc-element';
+import type {IconColor} from '../icon';
 
 import styles from './stat.scss';
 
 /**
- * @summary Short summary of the component's intended use.
+ * @summary Displays a key metric, optionally compared with a previous value.
  * @documentation https://zinc.style/components/stats-tile
  * @status experimental
  * @since 1.0
  *
- * @dependency zn-example
- *
- * @event zn-event-name - Emitted as an example.
- *
- * @slot - The default slot.
- * @slot example - An example slot.
- *
- * @csspart base - The component's base wrapper.
- *
- * @cssproperty --example - An example CSS custom property.
+ * @dependency zn-icon
  */
 export default class ZnStatsTile extends ZincElement {
   static styles: CSSResultGroup = unsafeCSS(styles);
@@ -34,6 +27,25 @@ export default class ZnStatsTile extends ZincElement {
   @property({type: Boolean, attribute: 'show-delta'}) showDelta = false;
   @property() color: 'primary' | 'error' | 'info' | 'warning' | 'success' | 'neutral' = 'primary';
 
+  /** `value-first` puts the amount under the caption with the description beneath it, and tints the amount rather
+   * than the description with `color`. */
+  @property({reflect: true}) layout: 'default' | 'value-first' = 'default';
+
+  /** How `show-delta` compares with `previous`: the relative change, or the difference in points. */
+  @property({attribute: 'delta-format'}) deltaFormat: 'percent' | 'points' = 'percent';
+
+  /** An icon shown beside the amount. */
+  @property() icon = '';
+
+  /** The icon's color; without one it takes the amount's. */
+  @property({attribute: 'icon-color'}) iconColor: IconColor;
+
+  /** `large` gives the amount more weight, for a summary row of a few headline figures. */
+  @property({reflect: true}) size: 'medium' | 'large' = 'medium';
+
+  /** Pads the stat, for stats laid edge to edge in a flush container such as `zn-cols no-gap divide`. */
+  @property({type: Boolean}) padded = false;
+
   calcPercentageDifference() {
     const previous = parseFloat(this.previous);
     const amount = parseFloat(this.amount);
@@ -93,16 +105,73 @@ export default class ZnStatsTile extends ZincElement {
         diffIcon = '-';
       }
 
+      if (this.deltaFormat === 'points') {
+        return html`<p class="diff">${this.pointsDelta()} on Previous Period</p>`;
+      }
+
       return html`<p class="diff"><span class="${diffClass}">${diffIcon}${diff}%</span> on Previous Period</p>`;
     }
 
     return null;
   }
 
+  private pointsDelta() {
+    const diff = Math.round((parseFloat(this.amount) - parseFloat(this.previous)) * 10) / 10;
+    if (diff > 0) {
+      return html`<span class="positive">+${diff} pts</span>`;
+    }
+    if (diff < 0) {
+      return html`<span class="negative">-${Math.abs(diff)} pts</span>`;
+    }
+    return html`<span class="neutral">No change</span>`;
+  }
+
+  private renderAmount() {
+    return html`${this.getDisplayAmount()}${this.icon ? html`
+      <zn-icon class="icon" src="${this.icon}" size="20" color="${ifDefined(this.iconColor)}"></zn-icon>` : null}`;
+  }
+
+  private renderValueFirst() {
+    const delta = this.showDelta
+      ? (this.deltaFormat === 'points' ? this.pointsDelta() : this.percentDelta())
+      : null;
+
+    return html`
+      <div class="${classMap({
+        'stat-tile': true,
+        'stat-tile--value-first': true,
+        'stat-tile--large': this.size === 'large',
+        'stat-tile--padded': this.padded,
+        [`stat-tile--${this.color}`]: true
+      })}">
+        <h3 class="caption">${this.caption}</h3>
+        <p class="amount">${this.renderAmount()}${delta ? html`<span class="diff">${delta}</span>` : null}</p>
+        ${this.description ? html`<p class="description">${this.description}</p>` : null}
+      </div>
+    `;
+  }
+
+  private percentDelta() {
+    const diff = this.calcPercentageDifference();
+    if (diff > 0) {
+      return html`<span class="positive">+${diff}%</span>`;
+    }
+    if (diff < 0) {
+      return html`<span class="negative">${diff}%</span>`;
+    }
+    return html`<span class="neutral">No change</span>`;
+  }
+
   render() {
+    if (this.layout === 'value-first') {
+      return this.renderValueFirst();
+    }
+
     return html`
       <div class="${classMap({
         'stat-tile': true,
+        'stat-tile--large': this.size === 'large',
+        'stat-tile--padded': this.padded,
         [`stat-tile--${this.color}`]: true
       })}">
         <div class="container">
@@ -111,7 +180,7 @@ export default class ZnStatsTile extends ZincElement {
               <h3 class="caption">${this.caption}</h3>
               <p class="description">${this.description}</p>
             </div>
-            <p class="amount">${this.getDisplayAmount()}</p>
+            <p class="amount">${this.renderAmount()}</p>
             <p class="bottom">${this.diffText()}</p>
           </div>
         </div>

package/src/components/stat/stat.scss

@@ -5,6 +5,11 @@
   display: contents;
 }
 
+// A box of its own lets zn-cols draw its dividers between value-first stats.
+:host([layout="value-first"]) {
+  display: block;
+}
+
 .stat-tile {
 
   .caption, .description, .amount, .bottom {
@@ -68,6 +73,55 @@
     }
   }
 
+  .icon {
+    margin-left: var(--zn-spacing-x-small);
+  }
+
+  &--value-first {
+    display: flex;
+    flex-direction: column;
+    gap: var(--zn-spacing-2x-small);
+    color: var(--zn-text-chart-major-color);
+
+    .caption {
+      margin-bottom: 0;
+    }
+
+    .amount {
+      flex-grow: 0;
+      gap: var(--zn-spacing-x-small);
+      color: inherit;
+    }
+
+    .diff {
+      font-size: var(--zn-font-size-small);
+      font-weight: 400;
+    }
+
+    .diff .neutral,
+    .description {
+      color: rgba(var(--zn-color-text), 0.6);
+    }
+
+    .description {
+      font-size: var(--zn-font-size-x-small);
+    }
+
+    .icon {
+      margin-left: 0;
+    }
+  }
+
+  &--padded {
+    padding: var(--zn-spacing-large);
+  }
+
+  &--large .amount {
+    font-size: var(--zn-font-size-3x-large);
+    font-weight: var(--zn-font-weight-semibold);
+    line-height: 1.15;
+  }
+
   &--chart {
     .amount {
       padding-top: var(--zn-spacing-small);
@@ -102,6 +156,10 @@
     color: rgb(var(--zn-text));
   }
 
+  &--value-first.stat-tile--neutral {
+    color: var(--zn-text-chart-major-color);
+  }
+
   @container (max-width:550px) {
     ::slotted(.zn-col-1) {
       flex-basis: 170px;
@@ -112,5 +170,11 @@
       line-height: 20px;
       padding-top: 5px;
     }
+
+    &--large .amount {
+      font-size: var(--zn-font-size-2x-large);
+      line-height: 1.15;
+      padding-top: 0;
+    }
   }
 }

package/src/components/tile/tile.component.ts

@@ -53,6 +53,9 @@ export default class ZnTile extends ZincElement {
   /** Renders the caption in the normal table-content weight instead of bold. */
   @property({type: Boolean}) plain: boolean;
 
+  /** Moves the actions under the caption and description when the tile is narrower than 600px. */
+  @property({attribute: 'stack-actions', type: Boolean, reflect: true}) stackActions: boolean;
+
   /** Set by `zn-tile-group` to lay the tile out as a shared-column subgrid row. */
   @property({type: Boolean, reflect: true}) grouped: boolean;
 

package/src/components/tile/tile.scss

@@ -124,6 +124,11 @@ a {
   text-overflow: ellipsis;
 }
 
+// A slot has no box of its own, so the slotted description would overflow rather than truncate
+slot.tile__description {
+  display: block;
+}
+
 .tile--inline .tile__description {
   margin: 0;
 }
@@ -190,3 +195,28 @@ a {
   min-width: 0;
   overflow: hidden;
 }
+
+:host([stack-actions]) {
+  container-type: inline-size;
+}
+
+:host([stack-actions]) .tile {
+  @include wc.container-query(null, ph) {
+    flex-wrap: wrap;
+    row-gap: var(--zn-spacing-x-small);
+
+    .tile__link {
+      flex-basis: 100%;
+    }
+
+    .tile__right {
+      justify-content: flex-start;
+      flex-wrap: wrap;
+    }
+
+    .tile__actions {
+      flex-wrap: wrap;
+      row-gap: var(--zn-spacing-x-small);
+    }
+  }
+}