@aquera/nile-visualization 0.6.0 → 0.8.0

package/dist/src/nile-executive-summary/nile-executive-summary.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Copyright Aquera Inc 2023
+ *
+ * This source code is licensed under the BSD-3-Clause license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import type { CSSResultGroup, TemplateResult } from 'lit';
+import NileElement from '../internal/nile-element.js';
+import type { NileExecutiveSummaryConfig } from './nile-executive-summary-config.js';
+/**
+ * Nile Executive Summary component.
+ *
+ * @tag nile-executive-summary
+ *
+ * @summary A self-contained drawer component with a built-in trigger button.
+ * Place it anywhere — clicking the button slides in a right-side drawer that
+ * displays summary content (plain text or HTML) with a typewriter animation.
+ * Configured entirely via the `config` JS property.
+ *
+ * @event nile-show         - Emitted when the drawer starts opening.
+ * @event nile-after-show   - Emitted when the drawer is fully open and typing begins.
+ * @event nile-hide         - Emitted when the drawer starts closing.
+ * @event nile-after-hide   - Emitted when the drawer is fully closed.
+ * @event nile-typing-complete - Emitted when the typewriter animation finishes.
+ * @event nile-init         - Emitted when the component connects to the DOM.
+ * @event nile-destroy      - Emitted when the component disconnects from the DOM.
+ *
+ * @csspart base    - Root wrapper (contains trigger + drawer).
+ * @csspart trigger - The built-in button that opens the drawer.
+ * @csspart overlay - The dim overlay behind the panel.
+ * @csspart panel   - The drawer panel.
+ * @csspart header  - The drawer header.
+ * @csspart title   - The drawer title.
+ * @csspart close   - The close button.
+ * @csspart body    - The drawer body containing the typed summary.
+ *
+ * @cssproperty --executive-summary-size           - Drawer width. Default: 480px.
+ * @cssproperty --executive-summary-header-spacing - Header padding. Default: 16px 20px.
+ * @cssproperty --executive-summary-body-spacing   - Body padding. Default: 20px.
+ * @cssproperty --executive-summary-z-index        - Z-index of the drawer. Default: 700.
+ * @cssproperty --executive-summary-overlay-color  - Overlay background colour.
+ * @cssproperty --executive-summary-btn-bg         - Trigger button background.
+ * @cssproperty --executive-summary-btn-color      - Trigger button text colour.
+ * @cssproperty --executive-summary-btn-radius     - Trigger button border-radius.
+ */
+export declare class NileExecutiveSummary extends NileElement {
+    static styles: CSSResultGroup;
+    private typingTimer;
+    private keyDownHandler;
+    private originalTrigger;
+    private scrollLockActive;
+    private backdrop;
+    private panel;
+    private overlay;
+    /**
+     * Full configuration. Assign via JavaScript — all fields are optional except `summary`.
+     *
+     * @example
+     * ```js
+     * el.config = {
+     *   summary: '<p>Q1 revenue grew <strong>23%</strong>.</p>',
+     *   buttonLabel: 'View Summary',
+     *   drawerLabel: 'AI Executive Summary',
+     *   typingSpeed: 20,
+     * };
+     * ```
+     */
+    config: NileExecutiveSummaryConfig | null;
+    /**
+     * Whether the drawer is currently open.
+     * Can be set programmatically; use `show()` / `hide()` for animated transitions.
+     */
+    open: boolean;
+    /** @internal Characters revealed so far during typing. */
+    private displayedText;
+    /** @internal Whether typing is still in progress (drives cursor visibility). */
+    private isTyping;
+    connectedCallback(): void;
+    firstUpdated(): void;
+    disconnectedCallback(): void;
+    private addKeyListener;
+    private removeKeyListener;
+    private handleKeyDown;
+    private lockScroll;
+    private unlockScroll;
+    private animatePanel;
+    private animateOverlay;
+    private requestClose;
+    private startTyping;
+    private stopTyping;
+    /** Opens the drawer with animation. Resolves when the animation completes. */
+    show(): Promise<void>;
+    /** Closes the drawer with animation. Resolves when the animation completes. */
+    hide(): Promise<void>;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'nile-executive-summary': NileExecutiveSummary;
+    }
+}

package/dist/src/nile-executive-summary/nile-executive-summary.js

@@ -0,0 +1,308 @@
+/**
+ * Copyright Aquera Inc 2023
+ *
+ * This source code is licensed under the BSD-3-Clause license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { __decorate } from "tslib";
+import { customElement, property, query, state } from 'lit/decorators.js';
+import { classMap } from 'lit/directives/class-map.js';
+import { html } from 'lit';
+import { unsafeHTML } from 'lit/directives/unsafe-html.js';
+import NileElement from '../internal/nile-element.js';
+import { styles } from './nile-executive-summary.css.js';
+/**
+ * Nile Executive Summary component.
+ *
+ * @tag nile-executive-summary
+ *
+ * @summary A self-contained drawer component with a built-in trigger button.
+ * Place it anywhere — clicking the button slides in a right-side drawer that
+ * displays summary content (plain text or HTML) with a typewriter animation.
+ * Configured entirely via the `config` JS property.
+ *
+ * @event nile-show         - Emitted when the drawer starts opening.
+ * @event nile-after-show   - Emitted when the drawer is fully open and typing begins.
+ * @event nile-hide         - Emitted when the drawer starts closing.
+ * @event nile-after-hide   - Emitted when the drawer is fully closed.
+ * @event nile-typing-complete - Emitted when the typewriter animation finishes.
+ * @event nile-init         - Emitted when the component connects to the DOM.
+ * @event nile-destroy      - Emitted when the component disconnects from the DOM.
+ *
+ * @csspart base    - Root wrapper (contains trigger + drawer).
+ * @csspart trigger - The built-in button that opens the drawer.
+ * @csspart overlay - The dim overlay behind the panel.
+ * @csspart panel   - The drawer panel.
+ * @csspart header  - The drawer header.
+ * @csspart title   - The drawer title.
+ * @csspart close   - The close button.
+ * @csspart body    - The drawer body containing the typed summary.
+ *
+ * @cssproperty --executive-summary-size           - Drawer width. Default: 480px.
+ * @cssproperty --executive-summary-header-spacing - Header padding. Default: 16px 20px.
+ * @cssproperty --executive-summary-body-spacing   - Body padding. Default: 20px.
+ * @cssproperty --executive-summary-z-index        - Z-index of the drawer. Default: 700.
+ * @cssproperty --executive-summary-overlay-color  - Overlay background colour.
+ * @cssproperty --executive-summary-btn-bg         - Trigger button background.
+ * @cssproperty --executive-summary-btn-color      - Trigger button text colour.
+ * @cssproperty --executive-summary-btn-radius     - Trigger button border-radius.
+ */
+let NileExecutiveSummary = class NileExecutiveSummary extends NileElement {
+    constructor() {
+        super(...arguments);
+        this.typingTimer = null;
+        this.originalTrigger = null;
+        this.scrollLockActive = false;
+        /**
+         * Full configuration. Assign via JavaScript — all fields are optional except `summary`.
+         *
+         * @example
+         * ```js
+         * el.config = {
+         *   summary: '<p>Q1 revenue grew <strong>23%</strong>.</p>',
+         *   buttonLabel: 'View Summary',
+         *   drawerLabel: 'AI Executive Summary',
+         *   typingSpeed: 20,
+         * };
+         * ```
+         */
+        this.config = null;
+        /**
+         * Whether the drawer is currently open.
+         * Can be set programmatically; use `show()` / `hide()` for animated transitions.
+         */
+        this.open = false;
+        /** @internal Characters revealed so far during typing. */
+        this.displayedText = '';
+        /** @internal Whether typing is still in progress (drives cursor visibility). */
+        this.isTyping = false;
+    }
+    // ─── Lifecycle ─────────────────────────────────────────────────────────────
+    connectedCallback() {
+        super.connectedCallback();
+        this.keyDownHandler = this.handleKeyDown.bind(this);
+        this.emit('nile-init');
+    }
+    firstUpdated() {
+        this.backdrop.hidden = !this.open;
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.stopTyping();
+        this.removeKeyListener();
+        this.unlockScroll();
+        this.emit('nile-destroy');
+    }
+    // ─── Keyboard / scroll ─────────────────────────────────────────────────────
+    addKeyListener() {
+        if (this.config?.closeOnEscape ?? true) {
+            document.addEventListener('keydown', this.keyDownHandler);
+        }
+    }
+    removeKeyListener() {
+        document.removeEventListener('keydown', this.keyDownHandler);
+    }
+    handleKeyDown(e) {
+        if (this.open && e.key === 'Escape') {
+            e.stopPropagation();
+            this.requestClose('keyboard');
+        }
+    }
+    lockScroll() {
+        if (!this.scrollLockActive) {
+            document.body.style.overflow = 'hidden';
+            this.scrollLockActive = true;
+        }
+    }
+    unlockScroll() {
+        if (this.scrollLockActive) {
+            document.body.style.overflow = '';
+            this.scrollLockActive = false;
+        }
+    }
+    // ─── Animation helpers ──────────────────────────────────────────────────────
+    async animatePanel(show) {
+        const from = show ? { opacity: '0', translate: '100%' } : { opacity: '1', translate: '0' };
+        const to = show ? { opacity: '1', translate: '0' } : { opacity: '0', translate: '100%' };
+        await this.panel.animate([from, to], { duration: 250, easing: 'ease', fill: 'forwards' }).finished;
+    }
+    async animateOverlay(show) {
+        const from = show ? { opacity: '0' } : { opacity: '1' };
+        const to = show ? { opacity: '1' } : { opacity: '0' };
+        await this.overlay.animate([from, to], { duration: 250, fill: 'forwards' }).finished;
+    }
+    // ─── Close request ──────────────────────────────────────────────────────────
+    requestClose(source) {
+        const preventOverlayClose = this.config?.preventOverlayClose ?? false;
+        if ((source === 'overlay' || source === 'keyboard') && preventOverlayClose)
+            return;
+        const ev = this.emit('nile-request-close', { cancelable: true, detail: { source } });
+        if (ev.defaultPrevented) {
+            // Deny-close jiggle
+            this.panel.animate([{ scale: '1' }, { scale: '1.01' }, { scale: '1' }], { duration: 250 });
+            return;
+        }
+        this.hide();
+    }
+    // ─── Typing animation ───────────────────────────────────────────────────────
+    startTyping() {
+        this.stopTyping();
+        this.displayedText = '';
+        this.isTyping = true;
+        const text = this.config?.summary ?? '';
+        const speed = this.config?.typingSpeed ?? 30;
+        let index = 0;
+        const tick = () => {
+            if (index < text.length) {
+                this.displayedText += text[index++];
+                this.typingTimer = setTimeout(tick, speed);
+            }
+            else {
+                this.isTyping = false;
+                this.emit('nile-typing-complete');
+            }
+        };
+        tick();
+    }
+    stopTyping() {
+        if (this.typingTimer !== null) {
+            clearTimeout(this.typingTimer);
+            this.typingTimer = null;
+        }
+        this.isTyping = false;
+    }
+    // ─── Open / close ───────────────────────────────────────────────────────────
+    /** Opens the drawer with animation. Resolves when the animation completes. */
+    async show() {
+        if (this.open)
+            return;
+        this.open = true;
+        this.emit('nile-show');
+        this.addKeyListener();
+        this.lockScroll();
+        this.originalTrigger = document.activeElement;
+        this.backdrop.hidden = false;
+        await Promise.all([this.animatePanel(true), this.animateOverlay(true)]);
+        requestAnimationFrame(() => this.panel.focus({ preventScroll: true }));
+        this.emit('nile-after-show');
+        this.startTyping();
+    }
+    /** Closes the drawer with animation. Resolves when the animation completes. */
+    async hide() {
+        if (!this.open)
+            return;
+        this.open = false;
+        this.emit('nile-hide');
+        this.removeKeyListener();
+        this.stopTyping();
+        this.displayedText = '';
+        this.unlockScroll();
+        await Promise.all([this.animatePanel(false), this.animateOverlay(false)]);
+        this.backdrop.hidden = true;
+        // Reset animation fill state for next open
+        this.panel.getAnimations().forEach(a => a.cancel());
+        this.overlay.getAnimations().forEach(a => a.cancel());
+        // Restore focus to original trigger
+        const trigger = this.originalTrigger;
+        if (typeof trigger?.focus === 'function')
+            setTimeout(() => trigger.focus());
+        this.emit('nile-after-hide');
+    }
+    // ─── Render ─────────────────────────────────────────────────────────────────
+    render() {
+        const buttonLabel = this.config?.buttonLabel ?? 'Executive Summary';
+        const buttonVariant = this.config?.buttonVariant ?? 'primary';
+        const drawerLabel = this.config?.drawerLabel ?? 'Executive Summary';
+        return html `
+      <div part="base">
+
+        <!-- Built-in trigger — renders wherever the element is placed -->
+        <nile-button
+          part="trigger"
+          type="button"
+          variant=${buttonVariant}
+          aria-haspopup="dialog"
+          aria-expanded=${this.open ? 'true' : 'false'}
+          @click=${this.show}
+        >${buttonLabel}</nile-button>
+
+        <!-- Fixed backdrop: overlay + panel -->
+        <div class="es-backdrop">
+
+          <div
+            part="overlay"
+            class="es-overlay"
+            @click=${() => this.requestClose('overlay')}
+            tabindex="-1"
+          ></div>
+
+          <div
+            part="panel"
+            class="es-panel"
+            role="dialog"
+            aria-modal="true"
+            aria-hidden=${this.open ? 'false' : 'true'}
+            aria-labelledby="es-title"
+            tabindex="0"
+          >
+            <header part="header" class="es-header">
+              <h2 part="title" class="es-title" id="es-title">${drawerLabel}</h2>
+
+              <button
+                part="close"
+                class="es-close"
+                type="button"
+                aria-label="Close"
+                @click=${() => this.requestClose('close-button')}
+              >
+                <!-- X icon (inline SVG — no icon lib dependency) -->
+                <svg viewBox="0 0 24 24" aria-hidden="true">
+                  <line x1="18" y1="6" x2="6" y2="18"/>
+                  <line x1="6" y1="6" x2="18" y2="18"/>
+                </svg>
+              </button>
+            </header>
+
+            <div part="body" class="es-body">
+              <div
+                class=${classMap({
+            'es-typed-text': true,
+            'es-typed-text--typing': this.isTyping,
+        })}
+              >${unsafeHTML(this.displayedText)}</div>
+              <slot></slot>
+            </div>
+
+          </div>
+        </div>
+      </div>
+    `;
+    }
+};
+NileExecutiveSummary.styles = styles;
+__decorate([
+    query('.es-backdrop')
+], NileExecutiveSummary.prototype, "backdrop", void 0);
+__decorate([
+    query('.es-panel')
+], NileExecutiveSummary.prototype, "panel", void 0);
+__decorate([
+    query('.es-overlay')
+], NileExecutiveSummary.prototype, "overlay", void 0);
+__decorate([
+    property({ type: Object })
+], NileExecutiveSummary.prototype, "config", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], NileExecutiveSummary.prototype, "open", void 0);
+__decorate([
+    state()
+], NileExecutiveSummary.prototype, "displayedText", void 0);
+__decorate([
+    state()
+], NileExecutiveSummary.prototype, "isTyping", void 0);
+NileExecutiveSummary = __decorate([
+    customElement('nile-executive-summary')
+], NileExecutiveSummary);
+export { NileExecutiveSummary };
+//# sourceMappingURL=nile-executive-summary.js.map

package/dist/src/nile-kpi-chart/nile-kpi-chart.css.d.ts

@@ -1 +1,6 @@
+/**
+ * Global tooltip styles — injected once into document.head so the tooltip
+ * element on document.body is styled independently of the shadow DOM.
+ */
+export declare const tooltipCss = "\n  .nile-kpi-tooltip {\n    position: fixed;\n    display: none;\n    transform: translate(-50%, calc(-100% - 10px));\n    background: #1D2939;\n    color: #fff;\n    font-family: system-ui, sans-serif;\n    font-size: 12px;\n    font-weight: 500;\n    line-height: 1.4;\n    padding: 5px 10px;\n    border-radius: 6px;\n    pointer-events: none;\n    white-space: nowrap;\n    z-index: 2147483647;\n    box-shadow: 0 4px 12px rgba(16, 24, 40, 0.22);\n  }\n\n  .nile-kpi-tooltip::after {\n    content: '';\n    position: absolute;\n    top: 100%;\n    left: 50%;\n    transform: translateX(-50%);\n    border: 5px solid transparent;\n    border-top-color:rgb(54, 74, 99);\n  }\n";
 export declare const styles: import("lit").CSSResult;

package/dist/src/nile-kpi-chart/nile-kpi-chart.css.js

@@ -1,18 +1,53 @@
 import { css } from 'lit';
+/**
+ * Global tooltip styles — injected once into document.head so the tooltip
+ * element on document.body is styled independently of the shadow DOM.
+ */
+export const tooltipCss = `
+  .nile-kpi-tooltip {
+    position: fixed;
+    display: none;
+    transform: translate(-50%, calc(-100% - 10px));
+    background: #1D2939;
+    color: #fff;
+    font-family: system-ui, sans-serif;
+    font-size: 12px;
+    font-weight: 500;
+    line-height: 1.4;
+    padding: 5px 10px;
+    border-radius: 6px;
+    pointer-events: none;
+    white-space: nowrap;
+    z-index: 2147483647;
+    box-shadow: 0 4px 12px rgba(16, 24, 40, 0.22);
+  }
+
+  .nile-kpi-tooltip::after {
+    content: '';
+    position: absolute;
+    top: 100%;
+    left: 50%;
+    transform: translateX(-50%);
+    border: 5px solid transparent;
+    border-top-color:rgb(54, 74, 99);
+  }
+`;
 export const styles = css `
   :host {
-    display: block;
+    display: flex;
+    flex-direction: column;
     width: 100%;
     position: relative;
+    box-sizing: border-box;
   }
 
   :host([hidden]) {
     display: none;
   }
 
-  /* ── Card variant ── */
-
-  .kpi-card {
+  /* Card / gauge chrome on the host when used alone (inside nile-chart, embed-in-nile-chart skips this). */
+  :host([variant='card']:not([embed-in-nile-chart])),
+  :host([variant='gauge']:not([embed-in-nile-chart])) {
     background: transparent;
     border: var(--nile-border-width-1, var(--ng-stroke-width-1)) solid var(--nile-colors-neutral-400, var(--ng-colors-border-secondary));
     border-radius: var(--nile-radius-radius-3xl, var(--ng-radius-xl));
@@ -20,13 +55,13 @@ export const styles = css `
     transition: box-shadow var(--nile-transition-duration-default, var(--ng-transition-duration-default)) ease;
   }
 
-  .kpi-card:hover {
+  :host([variant='card']:not([embed-in-nile-chart]):hover),
+  :host([variant='gauge']:not([embed-in-nile-chart]):hover) {
     box-shadow: var(--nile-box-shadow-7, var(--ng-shadow-md));
   }
 
-  /* ── Base layout ── */
-
   .kpi {
+    flex: 1 1 auto;
     display: flex;
     flex-direction: column;
     gap: var(--nile-spacing-md, var(--ng-spacing-md));
@@ -52,10 +87,11 @@ export const styles = css `
   .kpi-value {
     margin: 0;
     font-family: var(--nile-font-family-serif-colfax-medium, var(--ng-font-family-display));
-    font-size: 36px;
+    font-size: clamp(1.25rem, 2.5vw + 0.75rem, 36px);
     font-weight: var(--nile-font-weight-semi-bold, var(--ng-font-weight-semibold));
     color: var(--nile-colors-dark-900, var(--ng-colors-text-primary-900));
     line-height: 1.2;
+    cursor: default;
   }
 
   .kpi-prefix,
@@ -115,7 +151,8 @@ export const styles = css `
 
   .kpi-sparkline {
     width: 100%;
-    height: 48px;
+    flex: 0 1 48px;
+    min-height: 22px;
     margin-top: var(--nile-spacing-xs, var(--ng-spacing-xs));
   }
 
@@ -127,8 +164,11 @@ export const styles = css `
   }
 
   .kpi-gauge-container {
-    width: 160px;
-    height: 160px;
+    width: 100%;
+    max-width: 160px;
+    aspect-ratio: 1;
+    flex: 0 1 160px;
+    min-width: 72px;
     margin: 0 auto;
   }
 
@@ -153,6 +193,7 @@ export const styles = css `
   /* ── Loading state ── */
 
   .chart-loading {
+    flex: 1 1 auto;
     display: flex;
     align-items: center;
     justify-content: center;

package/dist/src/nile-kpi-chart/nile-kpi-chart.d.ts

@@ -24,8 +24,8 @@ export interface ChartKpiSeparatedPayload {
     gaugeColor?: string;
     loading?: boolean;
     options?: Highcharts.Options;
-    /** Optional min height when embedded in `<nile-chart>` (maps to host `min-height`). */
-    height?: string;
+    /** Box size when a height is set (host min-height and height). */
+    height?: string | number;
 }
 /** Separated `{ chart, aq }` input for `<nile-kpi-chart>`. */
 export interface NileKpiConfigInputType {
@@ -51,6 +51,8 @@ export declare class NileKpiChart extends NileElement {
     private sparklineChart;
     private gaugeChart;
     private resizeObserver;
+    /** Tooltip element on document.body — outside shadow DOM, never clipped. */
+    private _tipEl;
     private sparklineContainer;
     private gaugeContainer;
     /** Full configuration: `{ chart, aq }` (same convention as other Nile charts). */
@@ -89,13 +91,27 @@ export declare class NileKpiChart extends NileElement {
     loading: boolean;
     /** Highcharts options override for the sparkline or gauge. */
     options: Highcharts.Options;
-    /** Apply `{ chart, aq }` to individual properties. */
+    /**
+     * Set by nile-chart: skip host border/shadow (variant card/gauge) so the parent chart-card is the only frame.
+     */
+    embedInNileChart: boolean;
+    private _createTipEl;
+    private _showTip;
+    private _hideTip;
+    private formatCssLength;
+    private parseNumericValue;
+    private formatTooltipNumber;
+    private inferSparklineTooltipScale;
+    private getTooltipContent;
     private applyConfig;
     connectedCallback(): void;
     disconnectedCallback(): void;
     protected firstUpdated(): void;
     protected updated(changedProperties: PropertyValues): void;
+    private syncSparklineChartSize;
     private setupResizeObserver;
+    private _onSparklineMouseMove;
+    private _onSparklineMouseLeave;
     private buildSparklineOptions;
     private buildGaugeOptions;
     private initSparkline;
@@ -103,8 +119,10 @@ export declare class NileKpiChart extends NileElement {
     private destroySparkline;
     private destroyGauge;
     private destroyCharts;
+    private _onValueEnter;
+    private _onGaugeEnter;
+    private _onTipLeave;
     private renderTrend;
-    private renderContent;
     render(): TemplateResult;
 }
 declare global {