@ixfx/components 0.4.0 → 0.4.2

package/bundle/index.d.ts

@@ -1154,36 +1154,6 @@ declare global {
   }
 } //# sourceMappingURL=ac-text.d.ts.map
 //#endregion
-//#region src/ac-token/types.d.ts
-type AcTokenItem = {
-  readonly label: string;
-  readonly subLabel?: string;
-  readonly icon?: string;
-  readonly key?: string;
-  readonly data?: unknown;
-  readonly positions?: ReadonlySet<number>;
-};
-type AcTokenizerFn = (text: string) => string[];
-type AcTokensChangeDetail = {
-  readonly tokens: readonly AcTokenItem[];
-};
-type AcTokensChangeEvent = CustomEvent<AcTokensChangeDetail>;
-type AcTokenAddDetail = {
-  readonly item: AcTokenItem;
-  readonly index: number;
-};
-type AcTokenAddEvent = CustomEvent<AcTokenAddDetail>;
-type AcTokenRemoveDetail = {
-  readonly item: AcTokenItem;
-  readonly index: number;
-};
-type AcTokenRemoveEvent = CustomEvent<AcTokenRemoveDetail>;
-interface AcTokenElementEventMap {
-  'ac-token-change': AcTokensChangeEvent;
-  'ac-token-add': AcTokenAddEvent;
-  'ac-token-remove': AcTokenRemoveEvent;
-}
-//#endregion
 //#region src/common/data-provider.d.ts
 /**
  * Shared data-provider contract used by components that render a list of items.
@@ -1242,6 +1212,36 @@ type IDataProvider<TQuery, TItem> = (query: TQuery, signal: AbortSignal) => Data
  */
 declare function collectDataResult<T>(result: DataProviderResult<T>, signal: AbortSignal): Promise<readonly T[]>;
 //#endregion
+//#region src/ac-token/types.d.ts
+type AcTokenItem = {
+  readonly label: string;
+  readonly subLabel?: string;
+  readonly icon?: string;
+  readonly key?: string;
+  readonly data?: unknown;
+  readonly positions?: ReadonlySet<number>;
+};
+type AcTokenizerFn = (text: string) => string[];
+type AcTokensChangeDetail = {
+  readonly tokens: readonly AcTokenItem[];
+};
+type AcTokensChangeEvent = CustomEvent<AcTokensChangeDetail>;
+type AcTokenAddDetail = {
+  readonly item: AcTokenItem;
+  readonly index: number;
+};
+type AcTokenAddEvent = CustomEvent<AcTokenAddDetail>;
+type AcTokenRemoveDetail = {
+  readonly item: AcTokenItem;
+  readonly index: number;
+};
+type AcTokenRemoveEvent = CustomEvent<AcTokenRemoveDetail>;
+interface AcTokenElementEventMap {
+  'ac-token-change': AcTokensChangeEvent;
+  'ac-token-add': AcTokenAddEvent;
+  'ac-token-remove': AcTokenRemoveEvent;
+}
+//#endregion
 //#region src/ac-token/ac-token.d.ts
 /**
  * Token/tag input with per-token autocomplete suggestions.
@@ -2985,11 +2985,6 @@ declare class DataController<TQuery, TItem> implements ReactiveController {
 }
 //#endregion
 //#region src/common/types.d.ts
-/**
- * Canonical shared types for all tree-like components (ixfx-tree-list, ixfx-miller-list,
- * ixfx-crumb-navigation). Import from here rather than from individual component packages.
- */
-/** A single node's display data. */
 type TreeItem = {
   /** Unique identifier within the tree. */key: string; /** Visible label text. */
   label: string; /** When true the node cannot have children and will not show an expand affordance. */
@@ -3796,9 +3791,9 @@ interface IGroupedSubComponentEventMap<T> {
  */
 interface IGroupedSubComponent<T> extends HTMLElement {
   /** Replace the full item list. Called whenever the lister's items or grouping changes. */
-  setItems(items: readonly T[]): void;
+  setItems: (items: readonly T[]) => void;
   /** Clear the current selection without firing a `select` event (avoids re-entrant loops). */
-  clearSelection(): void;
+  clearSelection: () => void;
   /** The current selection set. */
   readonly selectedItems: ReadonlySet<T>;
   /** Controls how many items can be selected simultaneously. */
@@ -3807,9 +3802,8 @@ interface IGroupedSubComponent<T> extends HTMLElement {
    * Forward a command (e.g. sort-order change) to this sub-component.
    * Uses `CommandId` from `@clinth/ui-commands` for interoperability.
    */
-  dispatch(commandId: CommandId, args?: Record<string, unknown>): void;
-  addEventListener<K extends keyof IGroupedSubComponentEventMap<T>>(type: K, listener: (event: IGroupedSubComponentEventMap<T>[K]) => void, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+  dispatch: (commandId: CommandId, args?: Record<string, unknown>) => void;
+  addEventListener: (<K extends keyof IGroupedSubComponentEventMap<T>>(type: K, listener: (event: IGroupedSubComponentEventMap<T>[K]) => void, options?: boolean | AddEventListenerOptions) => void) & ((type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions) => void);
 }
 /**
  * Factory that creates a sub-component for a given group.
@@ -3898,8 +3892,7 @@ declare global {
   }
 }
 interface GroupedItemListerElement<T> {
-  addEventListener<K extends keyof GroupedItemListerElementEventMap<T>>(type: K, listener: (this: GroupedItemListerElement<T>, event: GroupedItemListerElementEventMap<T>[K]) => void, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+  addEventListener: (<K extends keyof GroupedItemListerElementEventMap<T>>(type: K, listener: (this: GroupedItemListerElement<T>, event: GroupedItemListerElementEventMap<T>[K]) => void, options?: boolean | AddEventListenerOptions) => void) & ((type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions) => void);
 }
 //#endregion
 //#region src/interaction/tickled-controller.d.ts
@@ -4224,7 +4217,7 @@ type TreeListAdapterOptions<T> = {
  *   );
  * ```
  */
-declare function createTreeListAdapter<T>(toTreeItem: (item: T) => Omit<TreeItem, 'data'>, options?: TreeListAdapterOptions<T>): HTMLElement & IGroupedSubComponent<T>;
+declare function createTreeListAdapter<T>(toTreeItem: (item: T) => Omit<TreeItem, `data`>, options?: TreeListAdapterOptions<T>): HTMLElement & IGroupedSubComponent<T>;
 //#endregion
 //#region src/vertical-list/vertical-list.d.ts
 declare class VerticalListElement extends LitElement {
@@ -5328,6 +5321,9 @@ type PlotDataSeriesOptions = {
    */
   persistentScaling: boolean;
 };
+/**
+ * A data series
+ */
 declare class PlotDataSeries {
   #private;
   values: number[];
@@ -5335,10 +5331,136 @@ declare class PlotDataSeries {
     min: number;
     max: number;
   };
+  /**
+   * Constructor.
+   *
+   * Default options:
+   * - `capacityLimit`: 100
+   * - `persistentScaling`: true
+   * @param options
+   */
   constructor(options?: Partial<PlotDataSeriesOptions>);
-  add(value: number): void;
+  /**
+   * Adds a single value
+   * @param valueOrValues Value to add
+   */
+  add(valueOrValues: number | number[]): void;
+  /**
+   * Sets the entire data series at once, replacing any existing data. If the number of values exceeds the `capacityLimit`, only the most recent values up to the limit are kept.
+   * @param values
+   */
   set(values: number[]): void;
-  clear(): void;
+  /**
+   * Clear all data and reset range. If `persistentScaling` is _false_, also resets scaling to initial state.
+   * @returns _true_ if there was data to clear
+   */
+  clear(): boolean;
+}
+//#endregion
+//#region src/plots/single-axis.d.ts
+type SingleAxisDrawStyle = `line-sharp` | `line-round` | `circles` | `squares` | `vbar` | `hbar` | `hist-bottom` | `hist-top` | `hist-middle`;
+type SingleAxisAgeStyle = `none` | `opacity` | `desaturation` | `size`;
+/**
+ * PlotSingleAxis
+ *
+ * Adding data:
+ * - add(value: number): adds a single value to the end of the data series.
+ * - set(values: number[]): replaces the entire data series at once.
+ */
+declare class PlotSingleAxis extends LitElement {
+  #private;
+  drawStyle: SingleAxisDrawStyle;
+  ageStyle: SingleAxisAgeStyle;
+  title: string;
+  precise: boolean;
+  tooltips: boolean;
+  capacity: number;
+  persistentScale: boolean;
+  paused: boolean;
+  clickPauses: boolean;
+  shaded: boolean;
+  areaColor: string;
+  colorMode: ColourMode;
+  colorEasing: string;
+  colorScale: string;
+  /** Custom value-mapping function (0..1 → 0..1). Ignored when color-easing is set. */
+  colorValueMap: ((v: number) => number) | null;
+  private _width;
+  private _height;
+  /** Override to customize tooltip label. */
+  valueFormat: (v: number | undefined) => string;
+  /**
+   * Get all values in the data series as a readonly array.
+   */
+  get values(): readonly number[];
+  /**
+   * Get length of data series
+   */
+  get dataCount(): number;
+  /**
+   * Get value at specific index of data series
+   * @param index
+   */
+  getValueAt(index: number): number | undefined;
+  /**
+   * Get value index based on client X position
+   * @param clientX
+   */
+  getIndexFromClientX(clientX: number): number;
+  /**
+   * Adds a value to the data series.
+   *
+   * Pass `withholdRedraw = true` to prevent automatic redraw after adding the value. In this case, call `redraw()` manually after adding all values to update the plot.
+   *
+   * Use {@link set} to replace the entire data series at once.
+   * @param valueOrValues Single value, or several values
+   * @param withholdRedraw If _false_ (default) plot is automatically redrawn
+   */
+  add(valueOrValues: number | number[], withholdRedraw?: boolean): void;
+  /**
+   * Redraws the plot.
+   * Normally not needed, unless add() is called with withholdRedraw = true, or styleSeries() is used to update series styles.
+   */
+  redraw(): void;
+  /**
+   * Sets the entire data for a series at once, replacing contents.
+   *
+   * Use add() to add values one by one.
+   *
+   * Pass `withholdRedraw = true` to prevent automatic redraw after setting the values. In this case, call `redraw()` manually after setting the values to update the plot.
+   * @param values Values
+   * @param withholdRedraw If _false_ (default) plot is automatically redrawn
+   */
+  set(values: number[], withholdRedraw?: boolean): void;
+  /**
+   * Clears all data and redraws
+   */
+  clear(): boolean;
+  protected firstUpdated(_changed: PropertyValues): void;
+  protected updated(changed: PropertyValues): void;
+  render(): TemplateResult<1>;
+  static styles: CSSResult;
+}
+type PlotSingleAxisPointerMoveDetail = {
+  readonly clientX: number;
+  readonly clientY: number;
+  readonly index: number;
+};
+type PlotSingleAxisPointerMoveEvent = CustomEvent<PlotSingleAxisPointerMoveDetail>;
+interface PlotSingleAxisElementEventMap {
+  'plot-pointer-move': PlotSingleAxisPointerMoveEvent;
+  'plot-pointer-leave': Event;
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    'ixfx-plot-single-axis': PlotSingleAxis;
+  }
+}
+interface PlotSingleAxis {
+  addEventListener: {
+    <K extends keyof PlotSingleAxisElementEventMap>(type: K, listener: (this: PlotSingleAxis, event: PlotSingleAxisElementEventMap[K]) => void, options?: boolean | AddEventListenerOptions): void;
+    (type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+  };
 }
 //#endregion
 //#region src/plots/multi-axis.d.ts
@@ -5358,11 +5480,45 @@ declare class PlotMultiAxis extends LitElement {
   gridMinWidth: number;
   /** Override to customize tooltip value display. */
   valueFormat: (v: number | undefined) => string;
-  addData(data: Record<string, number>): void;
-  addData(name: string, value: number): void;
+  /**
+   * Adds a single data point
+   * @param name Series name
+   * @param value Value
+   * @param witholdRedraw If _false_ (default) plot is automatically redrawn
+   */
+  addData(name: string, value: number, witholdRedraw?: boolean): PlotSingleAxis;
+  setData(name: string, values: number[], witholdRedraw?: boolean): PlotSingleAxis;
+  setObjects(data: Record<string, number[]>, witholdRedraw?: boolean): void;
+  /**
+   * Calls redraw() on all subplots.
+   */
+  redraw(): void;
+  /**
+   * Adds a record of data points to the plot. Each key in the record corresponds to a series name, and its value is added as a data point to that series. If a series does not exist for a given key, it will be created.
+   * @param data Data to add
+   * @param witholdRedraw If _false_ (default) plot is automatically redrawn after adding the data. If _true_, plot is not redrawn automatically, and you need to call `redraw()` manually to update the plot after adding the data.
+   */
+  addObject(data: Record<string, number | number[]>, witholdRedraw?: boolean): void;
+  /**
+   * Styles a series by setting CSS variables on the subplot.
+   * @param name Name of series
+   * @param styles Styles to apply
+   */
   styleSeries(name: string, styles: Record<string, string>): void;
-  clear(): void;
-  clearSeries(name: string): void;
+  /**
+   * Clears data from all sub-plots
+   * @returns _True_ if there was data to clear
+   */
+  clear(): boolean;
+  /**
+   * Clears data from a given series
+   * @param name Series name
+   * @returns _True_ if series was found and had data
+   */
+  clearSeries(name: string): boolean;
+  /**
+   * Returns a copy of the series names
+   */
   get series(): string[];
   protected render(): TemplateResult<1>;
   static styles: CSSResult;
@@ -5380,7 +5536,7 @@ interface PlotMultiAxis {
 }
 //#endregion
 //#region src/plots/plot-histogram.d.ts
-type PlotHistogramOrientation = 'horizontal' | 'vertical';
+type PlotHistogramOrientation = `horizontal` | `vertical`;
 type PlotHistogramBucketClickDetail = {
   readonly bucketIndex: number;
   readonly valueMin: number;
@@ -5416,67 +5572,7 @@ declare global {
   }
 }
 interface PlotHistogram {
-  addEventListener<K extends keyof PlotHistogramElementEventMap>(type: K, listener: (this: PlotHistogram, event: PlotHistogramElementEventMap[K]) => void, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
-}
-//#endregion
-//#region src/plots/single-axis.d.ts
-type SingleAxisDrawStyle = `line-sharp` | `line-round` | `circles` | `squares` | `vbar` | `hbar` | `hist-bottom` | `hist-top` | `hist-middle`;
-type SingleAxisAgeStyle = `none` | `opacity` | `desaturation` | `size`;
-declare class PlotSingleAxis extends LitElement {
-  #private;
-  drawStyle: SingleAxisDrawStyle;
-  ageStyle: SingleAxisAgeStyle;
-  title: string;
-  precise: boolean;
-  tooltips: boolean;
-  capacity: number;
-  persistentScale: boolean;
-  paused: boolean;
-  clickPauses: boolean;
-  shaded: boolean;
-  areaColor: string;
-  colorMode: ColourMode;
-  colorEasing: string;
-  colorScale: string;
-  /** Custom value-mapping function (0..1 → 0..1). Ignored when color-easing is set. */
-  colorValueMap: ((v: number) => number) | null;
-  private _width;
-  private _height;
-  /** Override to customize tooltip label. */
-  valueFormat: (v: number | undefined) => string;
-  get values(): readonly number[];
-  get dataCount(): number;
-  getValueAt(index: number): number | undefined;
-  getIndexFromClientX(clientX: number): number;
-  add(v: number): void;
-  set(values: number[]): void;
-  clear(): void;
-  protected firstUpdated(_changed: PropertyValues): void;
-  protected updated(changed: PropertyValues): void;
-  render(): TemplateResult<1>;
-  static styles: CSSResult;
-}
-type PlotSingleAxisPointerMoveDetail = {
-  readonly clientX: number;
-  readonly clientY: number;
-  readonly index: number;
-};
-type PlotSingleAxisPointerMoveEvent = CustomEvent<PlotSingleAxisPointerMoveDetail>;
-interface PlotSingleAxisElementEventMap {
-  'plot-pointer-move': PlotSingleAxisPointerMoveEvent;
-  'plot-pointer-leave': Event;
-}
-declare global {
-  interface HTMLElementTagNameMap {
-    'ixfx-plot-single-axis': PlotSingleAxis;
-  }
-}
-interface PlotSingleAxis {
-  addEventListener: {
-    <K extends keyof PlotSingleAxisElementEventMap>(type: K, listener: (this: PlotSingleAxis, event: PlotSingleAxisElementEventMap[K]) => void, options?: boolean | AddEventListenerOptions): void;
-    (type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
-  };
+  addEventListener: (<K extends keyof PlotHistogramElementEventMap>(type: K, listener: (this: PlotHistogram, event: PlotHistogramElementEventMap[K]) => void, options?: boolean | AddEventListenerOptions) => void) & ((type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions) => void);
 }
 //#endregion
 //#region src/plots/xy-axis.d.ts