@aquera/nile-visualization 2.9.1 → 2.9.3

package/dist/src/nile-filter-chart/utils/radio.js

@@ -0,0 +1,13 @@
+import { html } from 'lit';
+export function renderRadio(host, ctrl) {
+    const current = host.selectedValues.get(ctrl.id) ?? '';
+    return html `
+    <nile-radio-group
+      .value="${current}"
+      @nile-change="${(e) => { e.stopPropagation(); host.setValue(ctrl.id, e.detail.value); }}"
+    >
+      ${(ctrl.options ?? []).map(opt => html `
+        <nile-radio value="${opt.value}" ?checked="${current === opt.value}">${opt.label}</nile-radio>`)}
+    </nile-radio-group>`;
+}
+//# sourceMappingURL=radio.js.map

package/dist/src/nile-filter-chart/utils/search.d.ts

@@ -0,0 +1,3 @@
+import { TemplateResult } from 'lit';
+import type { FilterChartHost, NormalizedFilterControl } from './types.js';
+export declare function renderSearch(host: FilterChartHost, ctrl: NormalizedFilterControl): TemplateResult;

package/dist/src/nile-filter-chart/utils/search.js

@@ -0,0 +1,12 @@
+import { html } from 'lit';
+export function renderSearch(host, ctrl) {
+    return html `
+    <nile-input
+      type="search"
+      placeholder="${ctrl.placeholders?.[0] ?? `Search ${ctrl.label}…`}"
+      .value="${host.selectedValues.get(ctrl.id) ?? ''}"
+      clearable
+      @nile-input="${(e) => { e.stopPropagation(); host.setValue(ctrl.id, e.detail.value); }}"
+    ></nile-input>`;
+}
+//# sourceMappingURL=search.js.map

package/dist/src/nile-filter-chart/utils/segmented.d.ts

@@ -0,0 +1,3 @@
+import { TemplateResult } from 'lit';
+import type { FilterChartHost, NormalizedFilterControl } from './types.js';
+export declare function renderSegmented(host: FilterChartHost, ctrl: NormalizedFilterControl): TemplateResult;

package/dist/src/nile-filter-chart/utils/segmented.js

@@ -0,0 +1,15 @@
+import { html } from 'lit';
+export function renderSegmented(host, ctrl) {
+    return html `
+    <div class="fc-segmented-scroll">
+      <nile-button-toggle-group
+        .value="${host.selectedValues.get(ctrl.id) ?? ''}"
+        ?multiple="${ctrl.selection === 'multi'}"
+        @nile-change="${(e) => { e.stopPropagation(); host.setValue(ctrl.id, e.detail.value); }}"
+      >
+        ${(ctrl.options ?? []).map(opt => html `
+          <nile-button-toggle value="${opt.value}">${opt.label}</nile-button-toggle>`)}
+      </nile-button-toggle-group>
+    </div>`;
+}
+//# sourceMappingURL=segmented.js.map

package/dist/src/nile-filter-chart/utils/threshold.d.ts

@@ -0,0 +1,3 @@
+import { TemplateResult } from 'lit';
+import type { FilterChartHost, NormalizedFilterControl } from './types.js';
+export declare function renderThreshold(host: FilterChartHost, ctrl: NormalizedFilterControl): TemplateResult;

package/dist/src/nile-filter-chart/utils/threshold.js

@@ -0,0 +1,58 @@
+import { html, nothing } from 'lit';
+const OPERATORS = [
+    { value: '>', label: '> (greater)' },
+    { value: '>=', label: '>= (min)' },
+    { value: '<', label: '< (less)' },
+    { value: '<=', label: '<= (max)' },
+    { value: '=', label: '= (equals)' },
+    { value: '!=', label: '≠ (not)' },
+];
+export function renderThreshold(host, ctrl) {
+    const metric = host.selectedValues.get(ctrl.id) ?? '';
+    const op = host.selectedValues.get(`${ctrl.id}__op`) ?? '>';
+    const val = host.selectedValues.get(`${ctrl.id}__val`) ?? '';
+    const metricLabel = (ctrl.options ?? []).find(o => o.value === metric)?.label ?? metric;
+    const hasPreview = metric && val !== '';
+    const previewText = hasPreview ? `${metricLabel}  ${op}  ${val}` : 'Set metric, condition, and value above';
+    return html `
+    <div class="fc-threshold">
+      <div class="fc-threshold-metric-row">
+        <span class="fc-threshold-where">WHERE</span>
+        <div class="fc-threshold-field fc-threshold-field--metric">
+          <span class="fc-threshold-field-label">Metric</span>
+          <nile-select
+            .value="${metric}"
+            placeholder="Select metric…"
+            @nile-change="${(e) => { e.stopPropagation(); host.setValue(ctrl.id, e.detail.value); }}"
+          >
+            ${(ctrl.options ?? []).map(o => html `<nile-option value="${o.value}">${o.label}</nile-option>`)}
+          </nile-select>
+        </div>
+      </div>
+      <div class="fc-threshold-cond-row">
+        <div class="fc-threshold-field fc-threshold-field--op">
+          <span class="fc-threshold-field-label">Condition</span>
+          <nile-select
+            .value="${op}"
+            @nile-change="${(e) => { e.stopPropagation(); host.setValue(`${ctrl.id}__op`, e.detail.value); }}"
+          >
+            ${OPERATORS.map(o => html `<nile-option value="${o.value}">${o.label}</nile-option>`)}
+          </nile-select>
+        </div>
+        <div class="fc-threshold-field fc-threshold-field--val">
+          <span class="fc-threshold-field-label">Value</span>
+          <nile-input
+            type="number"
+            placeholder="e.g. 10000"
+            .value="${String(val)}"
+            @nile-input="${(e) => { e.stopPropagation(); host.setValue(`${ctrl.id}__val`, e.detail.value); }}"
+          ></nile-input>
+        </div>
+      </div>
+      <div class="fc-threshold-preview ${hasPreview ? '' : 'fc-threshold-preview--empty'}">
+        ${hasPreview ? html `<strong>Filter:</strong>` : nothing}
+        ${previewText}
+      </div>
+    </div>`;
+}
+//# sourceMappingURL=threshold.js.map

package/dist/src/nile-filter-chart/utils/toggle.d.ts

@@ -0,0 +1,3 @@
+import { TemplateResult } from 'lit';
+import type { FilterChartHost, NormalizedFilterControl } from './types.js';
+export declare function renderToggle(host: FilterChartHost, ctrl: NormalizedFilterControl): TemplateResult;

package/dist/src/nile-filter-chart/utils/toggle.js

@@ -0,0 +1,19 @@
+import { html } from 'lit';
+export function renderToggle(host, ctrl) {
+    const current = host.selectedValues.get(ctrl.id) ?? {};
+    return html `
+    <div class="fc-toggle-group">
+      ${(ctrl.options ?? []).map(opt => html `
+        <nile-slide-toggle
+          label="${opt.label}"
+          ?isChecked="${!!current[opt.value]}"
+          fullWidth
+          @nile-change="${(e) => {
+        e.stopPropagation();
+        const updated = { ...current, [opt.value]: e.detail.checked };
+        host.setValue(ctrl.id, updated);
+    }}"
+        ></nile-slide-toggle>`)}
+    </div>`;
+}
+//# sourceMappingURL=toggle.js.map

package/dist/src/nile-filter-chart/utils/types.d.ts

@@ -0,0 +1,334 @@
+export type NileTagVariant = 'primary' | 'success' | 'normal' | 'warning' | 'error' | 'info';
+export interface FilterOption {
+    label: string;
+    value: string;
+    /** Optional color dot (CSS color string). */
+    color?: string;
+    /** Optional nile-tag semantic variant — uses ng tokens directly (preferred over color). */
+    ngVariant?: NileTagVariant;
+    /** Optional icon name for preset variant. */
+    icon?: string;
+}
+/** Suggestion shown in the prompt's autocomplete dropdown. */
+export interface SuggestionItem {
+    /**
+     * Stable identifier. Meaning depends on `type`:
+     *   - `attribute` → the token inserted into the expression on pick (lets a
+     *     friendly `label` like "Status" map to the actual field token `status`).
+     *     Falls back to `label` if omitted.
+     *   - `value` → the parent attribute's `id`. Scopes the value to that
+     *     attribute (`status == |` only suggests values whose `id === 'status'`).
+     *     Omit for cross-attribute literals (`true` / `false` / `null`).
+     *   - other types → optional metadata, currently unused for routing.
+     */
+    id?: string;
+    /** Primary text shown in the row. For values, also the literal inserted (auto-quoted). */
+    label: string;
+    /**
+     * Drives both the row's colour in the dropdown and where in the expression
+     * the item shows up (context routing):
+     *   - `attribute` → field position (status, priority, …)
+     *   - `operator`  → after a known field (==, !=, <, …)
+     *   - `value`     → after `<attr> <op>` (scope per-attribute by setting `id` to the attribute's id)
+     *   - `connector` → after a complete predicate (and, or, not, in)
+     *   - `keyword`   → trailing SQL-ish keywords (ORDER BY, ASC, DESC, LIMIT)
+     *   - `function`  → callable templates (abs(value), …)
+     *   - `snippet`   → ready-made full expressions
+     *   - `clause`    → DEPRECATED. Treated as `connector` at routing time.
+     */
+    type?: 'attribute' | 'operator' | 'value' | 'connector' | 'keyword' | 'function' | 'snippet' | 'clause';
+    /** Legacy: text inserted on pick. New shape uses `label` for both. */
+    value?: string;
+    /** Legacy: muted secondary text. */
+    description?: string;
+    /** Legacy: category — superseded by `type`. */
+    group?: string;
+}
+/** Visual config for one segment of the prompt's mode toggle. */
+export interface PromptModeToggleOption {
+    /** Visible text inside the segment. Defaults: 'Expression' for basic, '' for nql. */
+    label?: string;
+    /** nile-glyph icon name (e.g. `'ng-ai_magic'`). Defaults: none for basic, `'ng-ai_magic'` for nql. */
+    icon?: string;
+    /** ARIA label for screen readers — required when the segment is icon-only. */
+    ariaLabel?: string;
+}
+/** Override the Basic / NQL toggle's two segments. */
+export interface PromptModeToggleConfig {
+    basic?: PromptModeToggleOption;
+    nql?: PromptModeToggleOption;
+}
+export interface QueryLanguageConfig {
+    /** Enables the query layer at all. Default: false. */
+    enabled: boolean;
+    /**
+     * Customise the Basic / NQL mode toggle's segments. Defaults:
+     *   - basic → label `'Basic'`
+     *   - nql   → label `'JQL'`
+     * Either segment can be overridden with a label, an icon, or both.
+     */
+    toggle?: PromptModeToggleConfig;
+    /**
+     * - `'auto'`   → no validation; the raw string flows through `nile-change`.
+     * - `'strict'` → every change is parsed with filtrex. On success the compiled
+     *                predicate appears in `nile-change.detail.evaluators[id]`.
+     *                On failure the message appears in `nile-change.detail.errors[id]`
+     *                and the input is rendered in an error state.
+     * Default: `'auto'`.
+     */
+    mode?: 'auto' | 'strict';
+    /** Parser engine. Currently only `'filtrex'` is supported. */
+    engine?: 'filtrex';
+    /**
+     * When validation runs in NQL mode.
+     *   - `'change'` (default) → debounced parse on every keystroke.
+     *   - `'submit'`            → parse only when the user presses Enter.
+     *
+     * In `'submit'` mode `nile-change` still fires after the debounce with the
+     * raw text, but `errors` / `evaluators` only populate after Enter.
+     */
+    validateOn?: 'change' | 'submit';
+    /** Optional hint text shown beneath the input describing the syntax. */
+    syntaxHint?: string;
+    /**
+     * Extra functions registered with filtrex on top of its built-in set
+     * (`abs`, `ceil`, `floor`, `log`, `log2`, `log10`, `max`, `min`, `round`,
+     * `sqrt`, `exists`, `empty`) and our project additions (`contains`,
+     * `startsWith`, `endsWith`, `lower`, `upper`, `len`, `isEmpty`,
+     * `isNotEmpty`, `between`, `year`, `month`, `day`, `daysAgo`, `matches`,
+     * `coalesce`).
+     *
+     * Example: `{ daysAgo: (d) => (Date.now() - +new Date(d)) / 86400000 }`
+     * Used in expressions like `daysAgo(lastSeen) < 7`.
+     */
+    extraFunctions?: Record<string, (...args: any[]) => unknown>;
+    /**
+     * Constants made available to expressions without polluting the data
+     * object. `'pi'` (single-quoted in the expression) escapes the constant
+     * to fall back to data access.
+     *
+     * Example: `{ pi: Math.PI, currentUser: 'Birat' }` →
+     *   `assignee == currentUser` resolves `currentUser` to `"Birat"`.
+     */
+    constants?: Record<string, unknown>;
+    /**
+     * Override comparison / arithmetic operators. Use this to localise
+     * comparisons (e.g. case-insensitive string equality) or to plug in
+     * a domain-specific arithmetic.
+     *
+     * Example: `{ '==': (a, b) => String(a).toLowerCase() === String(b).toLowerCase() }`
+     */
+    operators?: Partial<{
+        '+': (a: unknown, b: unknown) => unknown;
+        '-': (a: unknown, b?: unknown) => unknown;
+        '*': (a: unknown, b: unknown) => unknown;
+        '/': (a: unknown, b: unknown) => unknown;
+        '%': (a: unknown, b: unknown) => unknown;
+        '^': (a: unknown, b: unknown) => unknown;
+        '==': (a: unknown, b: unknown) => boolean;
+        '!=': (a: unknown, b: unknown) => boolean;
+        '<': (a: unknown, b: unknown) => boolean;
+        '>=': (a: unknown, b: unknown) => boolean;
+        '<=': (a: unknown, b: unknown) => boolean;
+        '>': (a: unknown, b: unknown) => boolean;
+        '~=': (a: unknown, b: unknown) => boolean;
+    }>;
+    /**
+     * Optional value-getter for accessing row properties. Filtrex calls
+     * this for every identifier reference. Default: dotted property
+     * access (`row.foo.bar` works out of the box).
+     *
+     * Override when your data model uses a Map / class / proxy that
+     * standard property access can't read. The fourth argument is the
+     * lookup type (`'unescaped'` for bare identifiers, `'single-quoted'`
+     * for `'foo-bar'` style).
+     */
+    customProp?: (name: string, get: (key: string) => unknown, obj: unknown, type?: 'unescaped' | 'single-quoted') => unknown;
+    /**
+     * Convenience flag — turn on filtrex's bundled `useDotAccessOperator`
+     * customProp. Lets users type `foo.bar` instead of `bar of foo`.
+     * Mutually exclusive with a custom `customProp`.
+     */
+    dotAccess?: boolean;
+    /**
+     * Convenience flag — turn on filtrex's bundled optional-chaining
+     * customProp. `a of b` (or `b.a` with `dotAccess`) returns `null`
+     * when the LHS is `null`/`undefined` instead of throwing.
+     * Mutually exclusive with a custom `customProp`.
+     */
+    optionalChaining?: boolean;
+}
+/**
+ * Recursive ESTree-shaped node returned by the AST parser. The shape
+ * matches what `jsep` produces — a small, well-known JS-expression AST.
+ * Pure JSON: every field is a string, number, boolean, null, or another
+ * `QueryNode`, so `JSON.stringify` round-trips cleanly.
+ */
+export type QueryNode = {
+    type: 'Identifier';
+    name: string;
+} | {
+    type: 'Literal';
+    value: string | number | boolean | null;
+    raw?: string;
+} | {
+    type: 'BinaryExpression';
+    operator: string;
+    left: QueryNode;
+    right: QueryNode;
+} | {
+    type: 'LogicalExpression';
+    operator: string;
+    left: QueryNode;
+    right: QueryNode;
+} | {
+    type: 'UnaryExpression';
+    operator: string;
+    argument: QueryNode;
+    prefix: boolean;
+} | {
+    type: 'CallExpression';
+    callee: QueryNode;
+    arguments: QueryNode[];
+} | {
+    type: 'MemberExpression';
+    computed: boolean;
+    object: QueryNode;
+    property: QueryNode;
+} | {
+    type: 'ArrayExpression';
+    elements: QueryNode[];
+} | {
+    type: 'Compound';
+    body: QueryNode[];
+};
+export type QueryJson = {
+    /** The exact string the user typed, retained for display / serialization. */
+    source: string;
+    ast: QueryNode;
+};
+/**
+ * Detail emitted with `nile-change`.
+ *
+ * `filters[id]` shape depends on the variant + (for prompts) the runtime mode:
+ *   - any non-prompt variant      → the variant's natural value
+ *   - prompt in `'basic'` mode    → plain `string` (raw text)
+ *   - prompt in `'nql'` mode,
+ *     parse succeeded             → `QueryJson` ({ source, ast }) — JSON-serializable
+ *   - prompt in `'nql'` mode,
+ *     pre-validation / parse fail → plain `string` (the typed text)
+ *
+ * `errors` and `evaluators` are populated for prompt controls in NQL mode.
+ */
+export type FilterChangeDetail = {
+    filters: Record<string, unknown>;
+    /** Map of control id → human-readable validation message. Present when at least one control failed validation. */
+    errors?: Record<string, string>;
+    /** Map of control id → compiled filtrex predicate. Present for prompt controls whose expression validated. */
+    evaluators?: Record<string, (row: unknown) => unknown>;
+};
+export interface FilterControl {
+    /**
+     * Unique key under which this control's value is emitted in
+     * `nile-change.detail.filters`. Optional — when omitted the component
+     * derives one from `label` (slugified) and appends a numeric suffix on
+     * collision, falling back to `ctrl_<index>` if `label` is also missing.
+     * Provide an explicit `id` when downstream code reads a stable key.
+     */
+    id?: string;
+    label: string;
+    /** Optional subtitle shown below the label. */
+    description?: string;
+    selection: 'single' | 'multi';
+    variant: 'badge' | 'dropdown' | 'segmented' | 'radio' | 'toggle' | 'search' | 'comparison' | 'threshold' | 'preset' | 'prompt' | 'expression' | 'hybrid';
+    options?: FilterOption[];
+    value?: string | string[] | number[] | boolean;
+    /**
+     * Placeholder text. Always an array — `placeholders[0]` is the initial /
+     * static placeholder used by every variant (search, dropdown, prompt).
+     * For the `prompt` variant only, additional entries are cycled through
+     * with a typewriter effect.
+     */
+    placeholders?: string[];
+    /** Typewriter speed in ms per character (default 60). */
+    typeSpeedMs?: number;
+    /** Pause before deleting a typed phrase (default 1400). */
+    pauseBeforeDeleteMs?: number;
+    /** Pause between phrases after deletion (default 400). */
+    pauseBetweenMs?: number;
+    queryLanguage?: QueryLanguageConfig;
+    gradientColors?: string[];
+    gradientDirection?: string;
+    gradientSpeedMs?: number;
+    /** Prompt variant only. When true, disables the animated AI gradient border. */
+    noAiBorder?: boolean;
+    /**
+     * Prompt variant only. Inline autocomplete suggestions shown below the
+     * input when the prompt is focused (Basic mode). Items are filtered
+     * client-side by case-insensitive substring match against the current
+     * input text.
+     */
+    suggestions?: SuggestionItem[];
+    /**
+     * How a clicked suggestion is inserted into the input value.
+     *   - `'replace'` (default) → suggestion's `value` replaces the entire input
+     *   - `'append'`            → appends the suggestion to the existing text (space-separated)
+     */
+    suggestionInsert?: 'replace' | 'append';
+    valueB?: string;
+    operator?: string;
+    thresholdValue?: number | string;
+}
+export interface FilterGroup {
+    type: 'group';
+    label: string;
+    description?: string;
+    collapsible?: boolean;
+    controls: FilterControl[];
+}
+export type FilterEntry = FilterControl | FilterGroup;
+export type FilterChartConfig = {
+    type: 'filter';
+    controls: FilterEntry[];
+    [key: string]: unknown;
+};
+export type FilterChartSeparatedPayload = {
+    chart: FilterChartConfig;
+    aq?: Record<string, unknown>;
+};
+/**
+ * Surface that variant render functions need from the host element.
+ * The chart class implements this so render functions stay decoupled
+ * from the LitElement subclass.
+ */
+/** Runtime mode for a prompt control. `'basic'` = plain text, no validation. `'nql'` = strict filtrex parsing. */
+export type PromptMode = 'basic' | 'nql';
+/**
+ * A `FilterControl` after the chart has filled in a guaranteed `id` (either
+ * the author-supplied one, or one derived from `label`). Render helpers and
+ * host methods receive this — they always have a stable key to read/write
+ * per-control state.
+ */
+export type NormalizedFilterControl = FilterControl & {
+    id: string;
+};
+export interface FilterChartHost {
+    readonly selectedValues: Map<string, unknown>;
+    readonly promptPlaceholder: Map<string, string>;
+    /** Prompt validation messages, keyed by control id. */
+    readonly promptErrors: Map<string, string>;
+    /** Per-control prompt mode (only set for prompt controls with `queryLanguage.enabled`). */
+    readonly promptModes: Map<string, PromptMode>;
+    /** Highlighted suggestion index per prompt control id (-1 = none highlighted). */
+    readonly promptActiveIndex: Map<string, number>;
+    setValue(id: string, value: unknown): void;
+    emit(name: string, detail?: unknown): void;
+    /** Update a prompt's value and (when in NQL mode) re-validate it. */
+    handlePromptInput(ctrl: NormalizedFilterControl, value: string): void;
+    /** Switch a prompt control's mode at runtime; clears or re-runs validation accordingly. */
+    setPromptMode(ctrl: NormalizedFilterControl, mode: PromptMode): void;
+    /** Force-validate a prompt's current value (used by `validateOn: 'submit'` on Enter). */
+    submitPrompt(ctrl: NormalizedFilterControl): void;
+    /** Set the highlighted suggestion index. Use -1 to clear the highlight. */
+    setPromptActiveIndex(id: string, idx: number): void;
+}

package/dist/src/nile-filter-chart/utils/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -47,7 +47,7 @@ export const styles = css `
     --nile-kpi-label-color: var(--nile-colors-neutral-700, var(--ng-colors-text-secondary-700));
     --nile-kpi-label-font-size: var(--nile-type-scale-3, var(--ng-font-size-text-sm));
     --nile-kpi-label-font-weight: var(--nile-font-weight-medium, var(--ng-font-weight-medium));
-    --nile-kpi-value-font-size: clamp(1.25rem, 5cqi + 0.5rem, 36px);
+    --nile-kpi-value-font-size: clamp(1rem, 5cqi + 0.25rem, 36px);
     --nile-kpi-value-color: var(--nile-colors-dark-900, var(--ng-colors-text-primary-900));
     --nile-kpi-prefix-suffix-font-size: var(--nile-type-scale-6, var(--ng-font-size-text-xl));
     --nile-kpi-prefix-suffix-color: var(--nile-colors-neutral-700, var(--ng-colors-text-secondary-700));
@@ -111,13 +111,17 @@ export const styles = css `
     flex: 1 1 auto;
     display: flex;
     flex-direction: column;
-    gap: var(--nile-kpi-content-gap);
+    /* gap: var(--nile-kpi-content-gap); */
     padding: var(--nile-kpi-padding-v) var(--nile-kpi-padding-h);
     min-width: 0;
+    width: 100%;
+    max-width: 100%;
+    box-sizing: border-box;
     overflow: hidden;
   }
 
   .kpi-label {
+    display: block;
     margin: 0;
     font-family: var(--nile-font-family-serif, var(--ng-font-family-body));
     font-size: var(--nile-kpi-label-font-size);
@@ -129,6 +133,8 @@ export const styles = css `
     text-overflow: ellipsis;
     min-width: 0;
     width: 100%;
+    max-width: 100%;
+    box-sizing: border-box;
   }
 
   .kpi-value-row {
@@ -149,7 +155,10 @@ export const styles = css `
     line-height: 1.2;
     cursor: default;
     white-space: nowrap;
-    flex-shrink: 0;
+    min-width: 0;
+    flex: 0 1 auto;
+    overflow: hidden;
+    text-overflow: ellipsis;
   }
 
   .kpi-prefix,
@@ -204,16 +213,18 @@ export const styles = css `
   }
 
   .kpi-description {
+    display: block;
     margin: 0;
     font-family: var(--nile-font-family-serif, var(--ng-font-family-body));
     font-size: var(--nile-kpi-description-font-size);
     color: var(--nile-kpi-description-color);
     line-height: 1.5;
-    white-space: nowrap;
     overflow: hidden;
     text-overflow: ellipsis;
     min-width: 0;
     width: 100%;
+    max-width: 100%;
+    box-sizing: border-box;
   }
 
   .kpi-sparkline {
@@ -223,6 +234,53 @@ export const styles = css `
     margin-top: var(--nile-spacing-xs, var(--ng-spacing-xs));
   }
 
+  /* ── Container queries: scale down for narrow cards ── */
+
+  /* Medium-small: ~280px and below — tighten padding, shrink prefix/suffix. */
+  @container (max-width: 280px) {
+    :host {
+      --nile-kpi-padding-v: var(--nile-spacing-lg, var(--ng-spacing-lg));
+      --nile-kpi-padding-h: var(--nile-spacing-xl, var(--ng-spacing-xl));
+      --nile-kpi-prefix-suffix-font-size: var(--nile-type-scale-4, var(--ng-font-size-text-md));
+      --nile-kpi-label-font-size: var(--nile-type-scale-2, var(--ng-font-size-text-xs));
+    }
+
+    .kpi-value-row {
+      gap: var(--nile-spacing-xs, var(--ng-spacing-xs));
+    }
+
+    .kpi-trend {
+      padding: 0;
+    }
+  }
+
+  /* Small: ~220px and below — tighten further; description/sparkline stay visible. */
+  @container (max-width: 220px) {
+    :host {
+      --nile-kpi-padding-v: var(--nile-spacing-md, var(--ng-spacing-md));
+      --nile-kpi-padding-h: var(--nile-spacing-lg, var(--ng-spacing-lg));
+      --nile-kpi-prefix-suffix-font-size: var(--nile-type-scale-3, var(--ng-font-size-text-sm));
+      --nile-kpi-description-font-size: var(--nile-type-scale-1, var(--ng-font-size-text-xs));
+    }
+
+    .kpi-sparkline {
+      flex-basis: 32px;
+      min-height: 18px;
+    }
+  }
+
+  /* Very small: under ~180px — stack the trend below the value so neither clips. */
+  @container (max-width: 180px) {
+    .kpi-value-row {
+      flex-wrap: wrap;
+      row-gap: var(--nile-spacing-xs, var(--ng-spacing-xs));
+    }
+
+    .kpi-trend {
+      flex-basis: 100%;
+    }
+  }
+
   /* ── Gauge variant ── */
 
   .kpi--gauge {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aquera/nile-visualization",
-  "version": "2.9.1",
+  "version": "2.9.3",
   "description": "A visualization Library for the Nile Design System",
   "license": "MIT",
   "author": "Aquera Inc",