@design.estate/dees-catalog 12.4.0 → 13.0.0

package/ts_web/elements/00group-chart/dees-chart-area/component.ts

@@ -19,7 +19,14 @@ import { getEchartsSeriesColors, hexToRgba, getThemeColors } from '../dees-chart
 
 import { systemFontFamily } from '../../00fonts.js';
 
-import type { IChartApi, ISeriesApi, UTCTimestamp, MouseEventParams } from 'lightweight-charts';
+import type {
+  AreaData,
+  IChartApi,
+  ISeriesApi,
+  MouseEventParams,
+  UTCTimestamp,
+  WhitespaceData,
+} from 'lightweight-charts';
 import { DeesServiceLibLoader, type ILightweightChartsBundle } from '../../../services/index.js';
 import '../../00group-layout/dees-tile/dees-tile.js';
 
@@ -27,9 +34,28 @@ export type ChartSeriesConfig = {
   name?: string;
   /** Explicit series color (hex or hsl). Falls back to the shared catalog palette by index. */
   color?: string;
-  data: Array<{ x: any; y: number }>;
+  /** A null reading keeps its timestamp and breaks the drawn area line. */
+  data: Array<{ x: any; y: number | null }>;
 }[];
 
+export interface IChartSeriesStats {
+  name: string;
+  /** Null when the newest sample is unavailable, even if older samples exist. */
+  latest: number | null;
+  min: number | null;
+  max: number | null;
+  avg: number | null;
+  color: string;
+}
+
+type TChartAreaData = AreaData<UTCTimestamp> | WhitespaceData<UTCTimestamp>;
+
+interface IChartRenderedSegment {
+  key: string;
+  logicalIndex: number;
+  data: TChartAreaData[];
+}
+
 export type TChartLegendStat = 'latest' | 'min' | 'max' | 'avg';
 export type TChartPriceLine = 'avg' | 'max';
 
@@ -55,7 +81,7 @@ export class DeesChartArea extends DeesElement {
   accessor chart: IChartApi | null = null;
 
   @state()
-  accessor seriesStats: Array<{ name: string; latest: number; min: number; max: number; avg: number; color: string }> = [];
+  accessor seriesStats: IChartSeriesStats[] = [];
 
   @state()
   accessor isFullPage: boolean = false;
@@ -117,6 +143,9 @@ export class DeesChartArea extends DeesElement {
   private autoScrollTimer: number | null = null;
   private lcBundle: ILightweightChartsBundle | null = null;
   private seriesApis: Map<string, ISeriesApi<any>> = new Map();
+  /** LC's data() omits whitespace; this mirrors the exact points sent to each series API. */
+  private renderedSeriesData: Map<string, IRealtimeChartPoint[]> = new Map();
+  private renderedSegments: IChartRenderedSegment[] = [];
   private priceLines: Map<string, any[]> = new Map();
   private tooltipEl: HTMLDivElement | null = null;
   private crosshairActive = false;
@@ -219,6 +248,8 @@ export class DeesChartArea extends DeesElement {
         console.error('Error destroying chart:', error);
       } finally {
         this.seriesApis.clear();
+        this.renderedSeriesData.clear();
+        this.renderedSegments = [];
         this.priceLines.clear();
       }
     });
@@ -316,15 +347,17 @@ export class DeesChartArea extends DeesElement {
     this.paintRangeOverlay(fromCoordinate, toCoordinate);
   }
 
-  private convertDataToLC(data: Array<{ x: any; y: number }>): Array<{ time: UTCTimestamp; value: number }> {
-    const pointsByTime = new Map<number, { time: UTCTimestamp; value: number }>();
+  private convertDataToLC(data: ChartSeriesConfig[number]['data']): TChartAreaData[] {
+    const pointsByTime = new Map<number, TChartAreaData>();
     for (const point of data) {
       const ms = typeof point.x === 'number' ? point.x : new Date(point.x).getTime();
       const time = Math.floor(ms / 1000);
-      if (!Number.isFinite(time) || !Number.isFinite(point.y)) continue;
+      if (!Number.isFinite(time) || (point.y !== null && !Number.isFinite(point.y))) continue;
       // Lightweight Charts requires unique ordered timestamps. The latest
-      // sample wins when multiple updates land in the same second.
-      pointsByTime.set(time, { time: time as UTCTimestamp, value: point.y });
+      // sample, including an unavailable one, wins within the same second.
+      pointsByTime.set(time, point.y === null
+        ? { time: time as UTCTimestamp }
+        : { time: time as UTCTimestamp, value: point.y });
     }
     return [...pointsByTime.values()]
       .sort((a, b) => (a.time as number) - (b.time as number));
@@ -338,6 +371,45 @@ export class DeesChartArea extends DeesElement {
     return `${index}:${this.getSeriesName(series, index)}`;
   }
 
+  /**
+   * Lightweight Charts joins Area points across whitespace. Render each
+   * uninterrupted numeric run as its own Area series instead. All missing
+   * timestamps stay on the first real series so the time scale keeps them;
+   * there is no synthetic numeric value or extra public legend series.
+   */
+  private getRenderedSegments(chartSeries: ChartSeriesConfig): IChartRenderedSegment[] {
+    const renderedSegments: IChartRenderedSegment[] = [];
+    chartSeries.forEach((series, logicalIndex) => {
+      const points = this.convertDataToLC(series.data);
+      const missingPoints = points.filter((point) => !('value' in point));
+      const numericRuns: TChartAreaData[][] = [];
+      let currentRun: TChartAreaData[] = [];
+      for (const point of points) {
+        if ('value' in point) {
+          currentRun.push(point);
+        } else if (currentRun.length > 0) {
+          numericRuns.push(currentRun);
+          currentRun = [];
+        }
+      }
+      if (currentRun.length > 0) numericRuns.push(currentRun);
+      if (numericRuns.length === 0) numericRuns.push([]);
+
+      const baseKey = this.getSeriesKey(series, logicalIndex);
+      numericRuns.forEach((run, segmentIndex) => {
+        const data = segmentIndex === 0
+          ? [...run, ...missingPoints].sort((left, right) => left.time - right.time)
+          : run;
+        renderedSegments.push({
+          key: segmentIndex === 0 ? baseKey : `${baseKey}#${segmentIndex}`,
+          logicalIndex,
+          data,
+        });
+      });
+    });
+    return renderedSegments;
+  }
+
   private getCanonicalChartSeries(chartSeries: ChartSeriesConfig): ChartSeriesConfig {
     const cutoffTime = Date.now() - this.rollingWindow;
     return chartSeries.map((series) => ({
@@ -348,15 +420,34 @@ export class DeesChartArea extends DeesElement {
         return ms > cutoffTime;
       })).map((point) => ({
         x: (point.time as number) * 1000,
-        y: point.value,
+        y: 'value' in point ? point.value : null,
       })),
     }));
   }
 
-  private getRenderedSeriesData(api: ISeriesApi<any>): IRealtimeChartPoint[] {
-    return api.data()
-      .filter((point): point is { time: UTCTimestamp; value: number } => 'value' in point)
-      .map((point) => ({ time: point.time as number, value: point.value }));
+  private getRenderedSeriesData(segmentKey: string): IRealtimeChartPoint[] {
+    const renderedData = this.renderedSeriesData.get(segmentKey);
+    if (!renderedData) throw new Error(`Missing rendered chart data for ${segmentKey}`);
+    return renderedData;
+  }
+
+  private rememberRenderedSeriesData(segmentKey: string, data: readonly TChartAreaData[]): void {
+    this.renderedSeriesData.set(segmentKey, data
+      .map((point) => 'value' in point
+        ? { time: point.time as number, value: point.value }
+        : { time: point.time as number }));
+  }
+
+  private rememberIncrementalUpdate(segmentKey: string, point: IRealtimeChartPoint): void {
+    const renderedData = this.getRenderedSeriesData(segmentKey);
+    const existingIndex = renderedData.findIndex((entry) => entry.time === point.time);
+    if (existingIndex >= 0) renderedData[existingIndex] = point;
+    else renderedData.push(point);
+  }
+
+  private toLcPoint(point: IRealtimeChartPoint): TChartAreaData {
+    const time = point.time as UTCTimestamp;
+    return point.value === undefined ? { time } : { time, value: point.value };
   }
 
   private colorToRgba(color: string, alpha: number): string {
@@ -423,19 +514,21 @@ export class DeesChartArea extends DeesElement {
       },
     } as any);
 
-    let idx = 0;
-    for (const [, api] of this.seriesApis) {
-      const color = this.resolveSeriesColor(this.chartSeries[idx], idx, isDark);
+    for (const segment of this.renderedSegments) {
+      const api = this.seriesApis.get(segment.key);
+      if (!api) continue;
+      const color = this.resolveSeriesColor(
+        this.chartSeries[segment.logicalIndex], segment.logicalIndex, isDark,
+      );
       api.applyOptions({
         topColor: this.colorToRgba(color, isDark ? 0.4 : 0.5),
         bottomColor: this.colorToRgba(color, 0),
         lineColor: color,
       });
-      idx++;
     }
   }
 
-  private recreateSeries(chartSeries: ChartSeriesConfig) {
+  private recreateSeries(chartSeries: ChartSeriesConfig, renderedSegments = this.getRenderedSegments(chartSeries)) {
     if (!this.chart || !this.lcBundle) return;
     const isDark = !this.goBright;
 
@@ -443,10 +536,13 @@ export class DeesChartArea extends DeesElement {
       this.chart.removeSeries(api);
     }
     this.seriesApis.clear();
+    this.renderedSeriesData.clear();
     this.priceLines.clear();
+    this.renderedSegments = renderedSegments;
 
-    chartSeries.forEach((s, index) => {
-      const color = this.resolveSeriesColor(s, index, isDark);
+    renderedSegments.forEach((segment) => {
+      const series = chartSeries[segment.logicalIndex];
+      const color = this.resolveSeriesColor(series, segment.logicalIndex, isDark);
       const api = this.chart!.addSeries(this.lcBundle!.AreaSeries, {
         topColor: this.colorToRgba(color, isDark ? 0.4 : 0.5),
         bottomColor: this.colorToRgba(color, 0),
@@ -459,10 +555,12 @@ export class DeesChartArea extends DeesElement {
         crosshairMarkerRadius: 4,
       });
 
-      api.setData(this.convertDataToLC(s.data));
-      this.updatePriceLines(this.getSeriesKey(s, index), api, s.data, color);
-
-      this.seriesApis.set(this.getSeriesKey(s, index), api);
+      api.setData(segment.data);
+      this.seriesApis.set(segment.key, api);
+      this.rememberRenderedSeriesData(segment.key, segment.data);
+      if (segment.key === this.getSeriesKey(series, segment.logicalIndex)) {
+        this.updatePriceLines(segment.key, api, series.data, color);
+      }
     });
     this.applyYAxisScale(chartSeries);
     this.computeStats(chartSeries);
@@ -477,17 +575,19 @@ export class DeesChartArea extends DeesElement {
 
   private updateSeriesPresentation(chartSeries: ChartSeriesConfig) {
     const isDark = !this.goBright;
-    chartSeries.forEach((series, index) => {
-      const seriesKey = this.getSeriesKey(series, index);
-      const api = this.seriesApis.get(seriesKey);
+    this.renderedSegments.forEach((segment) => {
+      const series = chartSeries[segment.logicalIndex];
+      const api = this.seriesApis.get(segment.key);
       if (!api) return;
-      const color = this.resolveSeriesColor(series, index, isDark);
+      const color = this.resolveSeriesColor(series, segment.logicalIndex, isDark);
       api.applyOptions({
         topColor: this.colorToRgba(color, isDark ? 0.4 : 0.5),
         bottomColor: this.colorToRgba(color, 0),
         lineColor: color,
       });
-      this.updatePriceLines(seriesKey, api, series.data, color);
+      if (segment.key === this.getSeriesKey(series, segment.logicalIndex)) {
+        this.updatePriceLines(segment.key, api, series.data, color);
+      }
     });
     this.computeStats(chartSeries);
 
@@ -500,7 +600,7 @@ export class DeesChartArea extends DeesElement {
     if (this.yAxisScaling === 'dynamic') {
       maxValue = 1;
       for (const entry of series) for (const point of entry.data) {
-        if (!Number.isFinite(point.y)) continue;
+        if (point.y === null || !Number.isFinite(point.y)) continue;
         minValue = Math.min(minValue, Math.floor(point.y * 1.1));
         maxValue = Math.max(maxValue, Math.ceil(point.y * 1.1));
       }
@@ -533,22 +633,39 @@ export class DeesChartArea extends DeesElement {
     ) return;
 
     const canonicalSeries = this.getCanonicalChartSeries(this.internalChartData);
-    canonicalSeries.forEach((series, index) => {
-      const api = this.seriesApis.get(this.getSeriesKey(series, index));
-      if (api) api.setData(this.convertDataToLC(series.data));
+    const canonicalSegments = this.getRenderedSegments(canonicalSeries);
+    if (!haveSameSeriesLayout(
+      [...this.seriesApis.keys()], canonicalSegments.map((segment) => segment.key),
+    )) {
+      this.clearCrosshairForDataReplacement();
+      this.internalChartData = canonicalSeries;
+      this.recreateSeries(canonicalSeries, canonicalSegments);
+      return;
+    }
+    canonicalSegments.forEach((segment) => {
+      const api = this.seriesApis.get(segment.key);
+      if (api) {
+        api.setData(segment.data);
+        this.rememberRenderedSeriesData(segment.key, segment.data);
+      }
     });
+    this.internalChartData = canonicalSeries;
+    this.renderedSegments = canonicalSegments;
     this.pendingRealtimePrune = false;
+    this.updateSeriesPresentation(canonicalSeries);
   }
 
   private computeStats(chartSeries: ChartSeriesConfig) {
     const isDark = !this.goBright;
     this.seriesStats = chartSeries.map((s, index) => {
       const color = this.resolveSeriesColor(s, index, isDark);
-      const values = s.data.map(d => d.y);
+      const values = s.data
+        .map((point) => point.y)
+        .filter((value): value is number => value !== null && Number.isFinite(value));
+      const latest = s.data.length > 0 ? s.data[s.data.length - 1].y : null;
       if (values.length === 0) {
-        return { name: s.name || `series-${index}`, latest: 0, min: 0, max: 0, avg: 0, color };
+        return { name: s.name || `series-${index}`, latest: null, min: null, max: null, avg: null, color };
       }
-      const latest = values[values.length - 1];
       const min = Math.min(...values);
       const max = Math.max(...values);
       const avg = Math.round((values.reduce((sum, v) => sum + v, 0) / values.length) * 100) / 100;
@@ -556,7 +673,7 @@ export class DeesChartArea extends DeesElement {
     });
   }
 
-  private updatePriceLines(name: string, api: ISeriesApi<any>, data: Array<{ x: any; y: number }>, color: string) {
+  private updatePriceLines(name: string, api: ISeriesApi<any>, data: ChartSeriesConfig[number]['data'], color: string) {
     // Remove existing price lines for this series
     const existing = this.priceLines.get(name);
     if (existing) {
@@ -565,12 +682,14 @@ export class DeesChartArea extends DeesElement {
       }
     }
 
-    if (data.length === 0) {
+    const values = data
+      .map((point) => point.y)
+      .filter((value): value is number => value !== null && Number.isFinite(value));
+    if (values.length === 0) {
       this.priceLines.set(name, []);
       return;
     }
 
-    const values = data.map(d => d.y);
     const avg = values.reduce((sum, v) => sum + v, 0) / values.length;
     const max = Math.max(...values);
 
@@ -627,23 +746,24 @@ export class DeesChartArea extends DeesElement {
       const borderColor = isDark ? 'hsl(0 0% 14.9%)' : 'hsl(0 0% 89.8%)';
 
       let html = '';
-      let idx = 0;
       let hasData = false;
-      for (const api of this.seriesApis.values()) {
+      for (const segment of this.renderedSegments) {
+        const api = this.seriesApis.get(segment.key);
+        if (!api) continue;
         const data = param.seriesData.get(api);
-        if (data && 'value' in data && (data as any).value !== undefined) {
+        if (data && 'value' in data && typeof data.value === 'number') {
+          const marginTop = hasData ? '6px' : '0';
           hasData = true;
-          const series = this.internalChartData[idx];
-          const name = series ? this.getSeriesName(series, idx) : `series-${idx}`;
-          const color = this.resolveSeriesColor(series, idx, isDark);
-          const formatted = this.yAxisFormatter((data as any).value);
-          html += `<div style="display:flex;align-items:center;gap:8px;margin:${idx > 0 ? '6px' : '0'} 0;">
+          const series = this.internalChartData[segment.logicalIndex];
+          const name = this.getSeriesName(series, segment.logicalIndex);
+          const color = this.resolveSeriesColor(series, segment.logicalIndex, isDark);
+          const formatted = this.yAxisFormatter(data.value);
+          html += `<div style="display:flex;align-items:center;gap:8px;margin:${marginTop} 0;">
             <span style="display:inline-block;width:10px;height:10px;background:${color};border-radius:2px;"></span>
             <span style="font-weight:500;">${name}:</span>
             <span style="margin-left:auto;font-weight:600;">${formatted}</span>
           </div>`;
         }
-        idx++;
       }
 
       if (!hasData) {
@@ -786,55 +906,55 @@ export class DeesChartArea extends DeesElement {
     try {
       void animate;
       const canonicalSeries = this.getCanonicalChartSeries(newSeries);
+      const renderedSegments = this.getRenderedSegments(canonicalSeries);
       this.internalChartData = canonicalSeries;
       const renderedKeys = [...this.seriesApis.keys()];
-      const canonicalKeys = canonicalSeries.map((series, index) => this.getSeriesKey(series, index));
+      const canonicalKeys = renderedSegments.map((segment) => segment.key);
 
       if (!haveSameSeriesLayout(renderedKeys, canonicalKeys)) {
         this.clearCrosshairForDataReplacement();
-        this.recreateSeries(canonicalSeries);
+        this.recreateSeries(canonicalSeries, renderedSegments);
         this.updateSeriesPresentation(canonicalSeries);
         return;
       }
+      this.renderedSegments = renderedSegments;
 
       if (!this.realtimeMode || this.rollingWindow <= 0) {
         this.clearCrosshairForDataReplacement();
-        canonicalSeries.forEach((series, index) => {
-          this.seriesApis.get(this.getSeriesKey(series, index))!
-            .setData(this.convertDataToLC(series.data));
+        renderedSegments.forEach((segment) => {
+          this.seriesApis.get(segment.key)!.setData(segment.data);
+          this.rememberRenderedSeriesData(segment.key, segment.data);
         });
         this.pendingRealtimePrune = false;
         this.updateSeriesPresentation(canonicalSeries);
         return;
       }
 
-      const plannedUpdates = canonicalSeries.map((series, index) => {
-        const api = this.seriesApis.get(this.getSeriesKey(series, index))!;
-        const canonicalData = this.convertDataToLC(series.data)
-          .map((point) => ({ time: point.time as number, value: point.value }));
+      const plannedUpdates = renderedSegments.map((segment) => {
+        const api = this.seriesApis.get(segment.key)!;
+        const canonicalData = segment.data.map((point) => 'value' in point
+          ? { time: point.time as number, value: point.value }
+          : { time: point.time as number });
         return {
+          key: segment.key,
           api,
           canonicalData,
-          plan: planRealtimeChartUpdates(this.getRenderedSeriesData(api), canonicalData),
+          plan: planRealtimeChartUpdates(this.getRenderedSeriesData(segment.key), canonicalData),
         };
       });
 
       if (plannedUpdates.some(({ plan }) => plan.replacementRequired)) {
         this.clearCrosshairForDataReplacement();
-        for (const { api, canonicalData } of plannedUpdates) {
-          api.setData(canonicalData.map((point) => ({
-            time: point.time as UTCTimestamp,
-            value: point.value,
-          })));
+        for (const { key, api, canonicalData } of plannedUpdates) {
+          api.setData(canonicalData.map((point) => this.toLcPoint(point)));
+          this.renderedSeriesData.set(key, [...canonicalData]);
         }
         this.pendingRealtimePrune = false;
       } else {
-        for (const { api, plan } of plannedUpdates) {
+        for (const { key, api, plan } of plannedUpdates) {
           for (const update of plan.updates) {
-            api.update({
-              time: update.point.time as UTCTimestamp,
-              value: update.point.value,
-            }, update.historicalUpdate);
+            api.update(this.toLcPoint(update.point), update.historicalUpdate);
+            this.rememberIncrementalUpdate(key, update.point);
           }
         }
 
@@ -842,20 +962,16 @@ export class DeesChartArea extends DeesElement {
         const pruneRecommended = plannedUpdates.some(({ plan }) => plan.pruneRecommended);
         if (pruneRequired) {
           this.clearCrosshairForDataReplacement();
-          for (const { api, canonicalData } of plannedUpdates) {
-            api.setData(canonicalData.map((point) => ({
-              time: point.time as UTCTimestamp,
-              value: point.value,
-            })));
+          for (const { key, api, canonicalData } of plannedUpdates) {
+            api.setData(canonicalData.map((point) => this.toLcPoint(point)));
+            this.renderedSeriesData.set(key, [...canonicalData]);
           }
         } else if (pruneRecommended && this.crosshairActive) {
           this.pendingRealtimePrune = true;
         } else if (pruneRecommended) {
-          for (const { api, canonicalData } of plannedUpdates) {
-            api.setData(canonicalData.map((point) => ({
-              time: point.time as UTCTimestamp,
-              value: point.value,
-            })));
+          for (const { key, api, canonicalData } of plannedUpdates) {
+            api.setData(canonicalData.map((point) => this.toLcPoint(point)));
+            this.renderedSeriesData.set(key, [...canonicalData]);
           }
           this.pendingRealtimePrune = false;
         }
@@ -879,7 +995,7 @@ export class DeesChartArea extends DeesElement {
     } catch (e) { /* range may be invalid */ }
   }
 
-  public async appendData(newData: { name?: string; data: Array<{ x: any; y: number }> }[]) {
+  public async appendData(newData: ChartSeriesConfig) {
     if (!this.chart) return;
     const nextSeries = this.internalChartData.map((series) => ({
       ...series,

package/ts_web/elements/00group-chart/dees-chart-area/realtime-updates.ts

@@ -1,6 +1,7 @@
 export interface IRealtimeChartPoint {
   time: number;
-  value: number;
+  /** Omitted for a time point where this series has no reading. */
+  value?: number;
 }
 
 export interface IRealtimeChartUpdate {
@@ -78,7 +79,8 @@ export const planRealtimeChartUpdates = (
       continue;
     }
 
-    if (renderedPoint.value !== canonicalPoint.value) {
+    if (renderedPoint.value !== canonicalPoint.value
+      || ('value' in renderedPoint) !== ('value' in canonicalPoint)) {
       updates.push({
         point: canonicalPoint,
         historicalUpdate: canonicalPoint.time < renderedLastTime,

package/ts_web/elements/00group-chart/dees-chart-area/template.ts

@@ -14,7 +14,8 @@ export const renderChartArea = (component: DeesChartArea): TemplateResult => {
           <div class="chartContainer">
             <div class="rangeSelectionOverlay" aria-hidden="true"></div>
           </div>
-          ${!component.chartSeries.some(series => series.data.length) ? html`<div class="chartState" role="status">No data for this period</div>` : ''}
+          ${!component.chartSeries.some(series => series.data.some(point => point.y !== null))
+            ? html`<div class="chartState" role="status">No data for this period</div>` : ''}
           ${component.seriesStats.length > 0 && !component.hideLegend ? html`
             <div slot="footer" class="statsBar">
               ${component.seriesStats.map(s => html`
@@ -24,7 +25,7 @@ export const renderChartArea = (component: DeesChartArea): TemplateResult => {
                   ${component.legendStats
                     .filter(key => key === 'latest' || key === 'min' || key === 'max' || key === 'avg')
                     .map(key => html`
-                      <span class="statsItem">${key} <strong>${component.yAxisFormatter(s[key])}</strong></span>
+                      <span class="statsItem">${key} <strong>${s[key] === null ? '—' : component.yAxisFormatter(s[key])}</strong></span>
                     `)}
                 </div>
               `)}

package/ts_web/elements/00group-input/dees-input-dropdown/dees-input-dropdown-popup.ts

@@ -19,6 +19,9 @@ declare global {
   }
 }
 
+export interface IDropdownSearchOption { key: string; option: string; payload?: unknown; }
+export type TDropdownSearch = (query: string, signal: AbortSignal) => Promise<IDropdownSearchOption[]>;
+
 @customElement('dees-input-dropdown-popup')
 export class DeesInputDropdownPopup extends DeesElement {
   @property({ type: Array })
@@ -39,6 +42,13 @@ export class DeesInputDropdownPopup extends DeesElement {
   @property({ type: String })
   accessor selectedKey = '';
 
+  /** Optional remote search. Results are authoritative and are not filtered again locally. */
+  @property({ attribute: false }) accessor searchOptions: TDropdownSearch | undefined;
+  @property({ type: String }) accessor searchLabel = 'Search options';
+  @state() accessor loading = false;
+  @state() accessor searchError = '';
+  private searchAbort?: AbortController;
+
   @state()
   accessor filteredOptions: { option: string; key: string; payload?: any }[] = [];
 
@@ -212,9 +222,9 @@ export class DeesInputDropdownPopup extends DeesElement {
               <div class="search">
                 <input
                   type="text"
-                  placeholder="Search options..."
+                  placeholder=${this.searchLabel}
                   role="combobox"
-                  aria-label="Search options"
+                  aria-label=${this.searchLabel}
                   aria-expanded="true"
                   aria-controls="dropdown-options"
                   aria-activedescendant=${this.filteredOptions.length ? `dropdown-option-${this.highlightedIndex}` : ''}
@@ -227,8 +237,8 @@ export class DeesInputDropdownPopup extends DeesElement {
           : null}
         <div class="options-container" id="dropdown-options" role="listbox" aria-label=${this.ownerComponent?.getAttribute('label') || 'Options'}
           tabindex=${this.enableSearch ? '-1' : '0'} aria-activedescendant=${this.filteredOptions.length ? `dropdown-option-${this.highlightedIndex}` : ''}>
-          ${this.filteredOptions.length === 0
-            ? html`<div class="no-options">No options found</div>`
+          ${this.loading || this.searchError || this.filteredOptions.length === 0
+            ? html`<div class="no-options" role="status">${this.loading ? 'Searching…' : this.searchError || 'No options found'}</div>`
             : this.filteredOptions.map((option, index) => {
                 const isHighlighted = this.highlightedIndex === index;
                 return html`
@@ -263,6 +273,8 @@ export class DeesInputDropdownPopup extends DeesElement {
   }
 
   public async show(): Promise<void> {
+    this.loading = false;
+    this.searchError = '';
     this.filteredOptions = this.options;
     this.highlightedIndex = Math.max(0, this.options.findIndex((option) => option.key === this.selectedKey));
     this.searchValue = '';
@@ -287,6 +299,7 @@ export class DeesInputDropdownPopup extends DeesElement {
     // Add scroll/resize listeners for repositioning
     window.addEventListener('scroll', this.handleScrollOrResize, { capture: true, passive: true });
     window.addEventListener('resize', this.handleScrollOrResize, { passive: true });
+    if (this.searchOptions) void this.searchRemote();
   }
 
   public async hide(): Promise<void> {
@@ -295,6 +308,7 @@ export class DeesInputDropdownPopup extends DeesElement {
       return;
     }
     this.isDestroying = true;
+    this.searchAbort?.abort();
 
     // Remove scroll/resize listeners
     window.removeEventListener('scroll', this.handleScrollOrResize, { capture: true } as EventListenerOptions);
@@ -331,6 +345,7 @@ export class DeesInputDropdownPopup extends DeesElement {
 
   public updateOptions(options: { option: string; key: string; payload?: any }[]): void {
     this.options = options;
+    if (this.searchOptions) return;
     // Re-filter with current search value
     if (this.searchValue) {
       const searchLower = this.searchValue.toLowerCase();
@@ -354,6 +369,7 @@ export class DeesInputDropdownPopup extends DeesElement {
   private handleSearch = (event: Event): void => {
     const searchTerm = (event.target as HTMLInputElement).value;
     this.searchValue = searchTerm;
+    if (this.searchOptions) { void this.searchRemote(); return; }
     const searchLower = searchTerm.toLowerCase();
     this.filteredOptions = this.options.filter((option) =>
       option.option.toLowerCase().includes(searchLower)
@@ -361,7 +377,25 @@ export class DeesInputDropdownPopup extends DeesElement {
     this.highlightedIndex = 0;
   };
 
+  private async searchRemote(): Promise<void> {
+    this.searchAbort?.abort();
+    const controller = this.searchAbort = new AbortController();
+    this.loading = true;
+    this.searchError = '';
+    this.filteredOptions = [];
+    this.highlightedIndex = 0;
+    try {
+      const options = await this.searchOptions!(this.searchValue, controller.signal);
+      if (!controller.signal.aborted) this.filteredOptions = options;
+    } catch (error) {
+      if (!controller.signal.aborted) this.searchError = error instanceof Error ? error.message : 'Search failed. Try again.';
+    } finally {
+      if (!controller.signal.aborted) this.loading = false;
+    }
+  }
+
   private handleSearchKeydown = (event: KeyboardEvent): void => {
+    if (event.isComposing) return;
     const key = event.key;
     const maxIndex = this.filteredOptions.length - 1;
 
@@ -370,7 +404,7 @@ export class DeesInputDropdownPopup extends DeesElement {
       this.highlightedIndex = this.highlightedIndex + 1 > maxIndex ? 0 : this.highlightedIndex + 1;
     } else if (key === 'ArrowUp') {
       event.preventDefault();
-      this.highlightedIndex = this.highlightedIndex - 1 < 0 ? maxIndex : this.highlightedIndex - 1;
+      this.highlightedIndex = Math.max(0, this.highlightedIndex - 1 < 0 ? maxIndex : this.highlightedIndex - 1);
     } else if (key === 'Enter') {
       event.preventDefault();
       if (this.filteredOptions[this.highlightedIndex]) {
@@ -391,6 +425,7 @@ export class DeesInputDropdownPopup extends DeesElement {
   };
 
   async disconnectedCallback() {
+    this.searchAbort?.abort();
     window.removeEventListener('scroll', this.handleScrollOrResize, { capture: true } as EventListenerOptions);
     window.removeEventListener('resize', this.handleScrollOrResize);
     zIndexRegistry.unregister(this);

package/ts_web/elements/00group-input/dees-input-reference/dees-input-reference.demo.ts

@@ -0,0 +1,9 @@
+import { html } from '@design.estate/dees-element';
+import { demoPage, demoSection } from '../../../demos/templates.js';
+
+export const demoFunc = () => demoPage('Reference composer', 'Type #_ to search at the cursor. Choose a ticket and continue writing.',
+  demoSection('Ticket references', 'References preserve IDs through editing, undo and copy/paste.', html`
+    <dees-input-reference .searchReferences=${async (query: string) => [
+      { id: 'ticket-1', label: '#CAT-101 Keyboard navigation' }, { id: 'ticket-2', label: '#CAT-102 Ticket detail' },
+    ].filter(item => item.label.toLowerCase().includes(query.toLowerCase()))}></dees-input-reference>
+  `));