@memberjunction/ng-clustering 0.0.1 → 5.24.0

package/dist/lib/clustering.types.d.ts

@@ -0,0 +1,271 @@
+/**
+ * @fileoverview Shared types for the clustering visualization library.
+ *
+ * This module defines every interface, type alias, and constant used across the
+ * `@memberjunction/ng-clustering` package.  It is the single source of truth for:
+ *
+ * - **Data shapes** (`ClusterPoint`, `ClusterInfo`, `ClusterVisualizationResult`, ...)
+ * - **Configuration** (`ClusterConfig`, `ClusterAlgorithm`, `ClusterDistanceMetric`)
+ * - **Event payloads** (`CancelableEvent`, `ViewportRect`, `ClusterSelectedEvent`, ...)
+ * - **Constants** (`CLUSTER_COLORS`, `DefaultClusterConfig`)
+ *
+ * @example
+ * ```typescript
+ * import {
+ *     CancelableEvent,
+ *     ClusterPoint,
+ *     ClusterConfig,
+ *     DefaultClusterConfig,
+ * } from '@memberjunction/ng-clustering';
+ *
+ * const cfg = DefaultClusterConfig();
+ * cfg.EntityName = 'Companies';
+ * cfg.K = 5;
+ * ```
+ */
+/**
+ * Generic wrapper for cancelable events emitted by clustering components.
+ *
+ * The component emits a `CancelableEvent<T>` **before** performing a
+ * side-effect.  The consumer can inspect `Data`, and set `Cancel = true` to
+ * prevent the default behavior.
+ *
+ * @typeParam T  Payload type carried by the event.
+ *
+ * @example
+ * ```html
+ * <mj-cluster-scatter
+ *     (BeforePointClick)="onBeforeClick($event)">
+ * </mj-cluster-scatter>
+ * ```
+ * ```typescript
+ * onBeforeClick(event: CancelableEvent<ClusterPoint>): void {
+ *     if (event.Data.ClusterId === -1) {
+ *         event.Cancel = true; // suppress click on outliers
+ *     }
+ * }
+ * ```
+ */
+export interface CancelableEvent<T = unknown> {
+    /** The event payload. */
+    Data: T;
+    /** Set to `true` to cancel the default operation that would follow. */
+    Cancel: boolean;
+}
+/**
+ * Describes the visible rectangle of the scatter plot after a zoom or pan.
+ *
+ * Coordinates are in the SVG coordinate space (the `viewBox`).
+ */
+export interface ViewportRect {
+    /** Left edge X coordinate. */
+    MinX: number;
+    /** Top edge Y coordinate. */
+    MinY: number;
+    /** Viewport width in SVG units. */
+    Width: number;
+    /** Viewport height in SVG units. */
+    Height: number;
+}
+/**
+ * Payload emitted when the user clicks a cluster label in the legend.
+ */
+export interface ClusterSelectedEvent {
+    /** The numeric cluster ID that was selected. */
+    ClusterId: number;
+    /** The human-readable label shown in the legend. */
+    Label: string;
+    /** The display color of the cluster. */
+    Color: string;
+    /** Number of points belonging to this cluster. */
+    MemberCount: number;
+}
+/**
+ * Simple entity option used by the config panel's entity dropdown.
+ * The parent component is responsible for populating this list.
+ */
+export interface ClusterConfigPanelEntityOption {
+    /** Entity display name shown in the dropdown. */
+    Name: string;
+}
+/** Option for the entity document dropdown in the config panel. */
+export interface ClusterConfigPanelEntityDocOption {
+    /** Entity Document ID */
+    ID: string;
+    /** Display name of the entity document */
+    Name: string;
+}
+/**
+ * A single vector provided to `ClusteringService.RunClustering()`.
+ *
+ * The caller is responsible for fetching/building these vectors from
+ * whatever data source is appropriate (database, vector index, API, etc.).
+ */
+export interface ClusterInputVector {
+    /** Unique key identifying this vector (e.g., a record ID). */
+    Key: string;
+    /** The raw embedding / feature vector. */
+    Vector: number[];
+    /** Optional display label for this point (defaults to Key if omitted). */
+    Label?: string;
+    /** Arbitrary metadata surfaced in tooltips and click handlers. */
+    Metadata?: Record<string, unknown>;
+}
+/**
+ * A single point in the 2D scatter plot.
+ *
+ * Each point corresponds to one vectorized entity record after
+ * dimensionality reduction (UMAP or PCA).
+ */
+export interface ClusterPoint {
+    /** X coordinate in 2D projected space. */
+    X: number;
+    /** Y coordinate in 2D projected space. */
+    Y: number;
+    /** Cluster assignment ID (`-1` for outliers / noise). */
+    ClusterId: number;
+    /** Display label for this point (typically the entity record identifier). */
+    Label: string;
+    /** Original vector key (e.g., entity record ID). */
+    VectorKey: string;
+    /** Arbitrary metadata surfaced in tooltips and click handlers. */
+    Metadata: Record<string, unknown>;
+}
+/**
+ * Summary information about a single cluster.
+ *
+ * Produced by `ClusteringService.RunPipeline()` and consumed by the
+ * scatter plot legend and various event payloads.
+ */
+export interface ClusterInfo {
+    /** Unique cluster identifier (zero-based). */
+    Id: number;
+    /** Human-readable label (auto-generated or user-defined). */
+    Label: string;
+    /** Display color as a CSS hex string (e.g., `#5b8def`). */
+    Color: string;
+    /** Number of member points in this cluster. */
+    MemberCount: number;
+}
+/** Supported clustering algorithms. */
+export type ClusterAlgorithm = 'kmeans' | 'dbscan';
+/** Supported distance metrics for clustering. */
+export type ClusterDistanceMetric = 'cosine' | 'euclidean' | 'dotproduct';
+/**
+ * Full configuration for a clustering run.
+ *
+ * Pass an instance to `ClusteringService.RunPipeline()` or emit from the
+ * config panel's `RunClustering` output.
+ */
+export interface ClusterConfig {
+    /** Entity name to cluster (must have Entity Documents with vectors). */
+    EntityName: string;
+    /** Specific Entity Document ID to use. When blank, the first active doc for the entity is used. */
+    EntityDocumentID: string;
+    /** Clustering algorithm to use. */
+    Algorithm: ClusterAlgorithm;
+    /** Number of clusters for K-Means (ignored for DBSCAN). */
+    K: number;
+    /** Epsilon neighbourhood radius for DBSCAN (ignored for K-Means). */
+    Epsilon: number;
+    /** Minimum points to form a dense region in DBSCAN (ignored for K-Means). */
+    MinPoints: number;
+    /** Distance metric used when comparing vectors. */
+    DistanceMetric: ClusterDistanceMetric;
+    /** Maximum number of entity records to fetch for clustering. */
+    MaxRecords: number;
+    /** Optional SQL-style filter applied to the Entity Document Runs query. */
+    Filter: string;
+}
+/**
+ * Quality and performance metrics returned after a clustering run.
+ */
+export interface ClusterMetrics {
+    /** Silhouette score ranging from -1 (poor) to 1 (excellent). */
+    SilhouetteScore: number;
+    /** Total number of clusters discovered. */
+    ClusterCount: number;
+    /** Wall-clock computation time in milliseconds. */
+    ComputationTimeMs: number;
+    /** Total records that were processed. */
+    RecordCount: number;
+    /** Number of outlier points (DBSCAN only; 0 for K-Means). */
+    OutlierCount: number;
+}
+/**
+ * Complete result of a clustering visualization pipeline.
+ *
+ * Returned by {@link ClusteringService.RunPipeline} and consumed by
+ * both `mj-cluster-scatter` and `mj-cluster-config-panel`.
+ */
+export interface ClusterVisualizationResult {
+    /** 2D projected points ready for rendering. */
+    Points: ClusterPoint[];
+    /** Cluster summaries with colors and counts. */
+    Clusters: ClusterInfo[];
+    /** Performance and quality metrics. */
+    Metrics: ClusterMetrics;
+    /** The config that produced this result. */
+    Config: ClusterConfig;
+}
+/**
+ * Serializable reference to a saved cluster visualization.
+ *
+ * Persisted via `UserInfoEngine` user settings so the user can reload
+ * previous analyses.
+ */
+export interface SavedClusterVisualization {
+    /** Unique identifier (UUID). */
+    Id: string;
+    /** User-given display name. */
+    Name: string;
+    /** Entity that was clustered. */
+    EntityName: string;
+    /** Algorithm used. */
+    Algorithm: ClusterAlgorithm;
+    /** Snapshot of the full config at save time. */
+    Params: Partial<ClusterConfig>;
+    /** ISO 8601 timestamp of when this was saved. */
+    CreatedAt: string;
+    /** Cached clustering result (points, clusters, metrics) — avoids re-computation on restore. */
+    Result?: ClusterVisualizationResult;
+    /** Viewport transform at save time (pan + zoom state). */
+    Viewport?: ViewportTransform;
+    /** LLM-generated (or user-edited) labels for each cluster. */
+    ClusterLabels?: ClusterLabel[];
+}
+/** Viewport pan/zoom state for restoring scatter plot position. */
+export interface ViewportTransform {
+    TranslateX: number;
+    TranslateY: number;
+    Scale: number;
+}
+/** A human-readable label for a cluster. */
+export interface ClusterLabel {
+    /** The cluster ID this label applies to. */
+    ClusterId: number;
+    /** Short descriptive label (2-5 words). */
+    Label: string;
+    /** Whether the user has manually edited this label. */
+    IsUserEdited: boolean;
+}
+/**
+ * Default cluster color palette -- 10 distinct, accessible colors.
+ *
+ * Override at the component level via `ClusterScatterComponent.ColorPalette`.
+ */
+export declare const CLUSTER_COLORS: string[];
+/**
+ * Create a `ClusterConfig` populated with sensible defaults.
+ *
+ * @returns A new `ClusterConfig` with K-Means / cosine / 500 max records.
+ *
+ * @example
+ * ```typescript
+ * const cfg = DefaultClusterConfig();
+ * cfg.EntityName = 'Accounts';
+ * cfg.K = 6;
+ * ```
+ */
+export declare function DefaultClusterConfig(): ClusterConfig;
+//# sourceMappingURL=clustering.types.d.ts.map

package/dist/lib/clustering.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clustering.types.d.ts","sourceRoot":"","sources":["../../src/lib/clustering.types.ts"],"names":[],"mappings":"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"}

package/dist/lib/clustering.types.js

@@ -0,0 +1,74 @@
+/**
+ * @fileoverview Shared types for the clustering visualization library.
+ *
+ * This module defines every interface, type alias, and constant used across the
+ * `@memberjunction/ng-clustering` package.  It is the single source of truth for:
+ *
+ * - **Data shapes** (`ClusterPoint`, `ClusterInfo`, `ClusterVisualizationResult`, ...)
+ * - **Configuration** (`ClusterConfig`, `ClusterAlgorithm`, `ClusterDistanceMetric`)
+ * - **Event payloads** (`CancelableEvent`, `ViewportRect`, `ClusterSelectedEvent`, ...)
+ * - **Constants** (`CLUSTER_COLORS`, `DefaultClusterConfig`)
+ *
+ * @example
+ * ```typescript
+ * import {
+ *     CancelableEvent,
+ *     ClusterPoint,
+ *     ClusterConfig,
+ *     DefaultClusterConfig,
+ * } from '@memberjunction/ng-clustering';
+ *
+ * const cfg = DefaultClusterConfig();
+ * cfg.EntityName = 'Companies';
+ * cfg.K = 5;
+ * ```
+ */
+// ================================================================
+// Constants
+// ================================================================
+/**
+ * Default cluster color palette -- 10 distinct, accessible colors.
+ *
+ * Override at the component level via `ClusterScatterComponent.ColorPalette`.
+ */
+export const CLUSTER_COLORS = [
+    '#5b8def', // blue
+    '#34d399', // emerald
+    '#fbbf24', // amber
+    '#f472b6', // pink
+    '#a78bfa', // violet
+    '#fb923c', // orange
+    '#22d3ee', // cyan
+    '#f87171', // red
+    '#4ade80', // green
+    '#e879f9', // fuchsia
+];
+// ================================================================
+// Factory functions
+// ================================================================
+/**
+ * Create a `ClusterConfig` populated with sensible defaults.
+ *
+ * @returns A new `ClusterConfig` with K-Means / cosine / 500 max records.
+ *
+ * @example
+ * ```typescript
+ * const cfg = DefaultClusterConfig();
+ * cfg.EntityName = 'Accounts';
+ * cfg.K = 6;
+ * ```
+ */
+export function DefaultClusterConfig() {
+    return {
+        EntityName: '',
+        EntityDocumentID: '',
+        Algorithm: 'kmeans',
+        K: 4,
+        Epsilon: 0.3,
+        MinPoints: 3,
+        DistanceMetric: 'cosine',
+        MaxRecords: 500,
+        Filter: '',
+    };
+}
+//# sourceMappingURL=clustering.types.js.map

package/dist/lib/clustering.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clustering.types.js","sourceRoot":"","sources":["../../src/lib/clustering.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAwQH,mEAAmE;AACnE,YAAY;AACZ,mEAAmE;AAEnE;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAa;IACpC,SAAS,EAAE,OAAO;IAClB,SAAS,EAAE,UAAU;IACrB,SAAS,EAAE,QAAQ;IACnB,SAAS,EAAE,OAAO;IAClB,SAAS,EAAE,SAAS;IACpB,SAAS,EAAE,SAAS;IACpB,SAAS,EAAE,OAAO;IAClB,SAAS,EAAE,MAAM;IACjB,SAAS,EAAE,QAAQ;IACnB,SAAS,EAAE,UAAU;CACxB,CAAC;AAEF,mEAAmE;AACnE,oBAAoB;AACpB,mEAAmE;AAEnE;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,oBAAoB;IAChC,OAAO;QACH,UAAU,EAAE,EAAE;QACd,gBAAgB,EAAE,EAAE;QACpB,SAAS,EAAE,QAAQ;QACnB,CAAC,EAAE,CAAC;QACJ,OAAO,EAAE,GAAG;QACZ,SAAS,EAAE,CAAC;QACZ,cAAc,EAAE,QAAQ;QACxB,UAAU,EAAE,GAAG;QACf,MAAM,EAAE,EAAE;KACb,CAAC;AACN,CAAC","sourcesContent":["/**\n * @fileoverview Shared types for the clustering visualization library.\n *\n * This module defines every interface, type alias, and constant used across the\n * `@memberjunction/ng-clustering` package.  It is the single source of truth for:\n *\n * - **Data shapes** (`ClusterPoint`, `ClusterInfo`, `ClusterVisualizationResult`, ...)\n * - **Configuration** (`ClusterConfig`, `ClusterAlgorithm`, `ClusterDistanceMetric`)\n * - **Event payloads** (`CancelableEvent`, `ViewportRect`, `ClusterSelectedEvent`, ...)\n * - **Constants** (`CLUSTER_COLORS`, `DefaultClusterConfig`)\n *\n * @example\n * ```typescript\n * import {\n *     CancelableEvent,\n *     ClusterPoint,\n *     ClusterConfig,\n *     DefaultClusterConfig,\n * } from '@memberjunction/ng-clustering';\n *\n * const cfg = DefaultClusterConfig();\n * cfg.EntityName = 'Companies';\n * cfg.K = 5;\n * ```\n */\n\n// ================================================================\n// Cancelable event pattern\n// ================================================================\n\n/**\n * Generic wrapper for cancelable events emitted by clustering components.\n *\n * The component emits a `CancelableEvent<T>` **before** performing a\n * side-effect.  The consumer can inspect `Data`, and set `Cancel = true` to\n * prevent the default behavior.\n *\n * @typeParam T  Payload type carried by the event.\n *\n * @example\n * ```html\n * <mj-cluster-scatter\n *     (BeforePointClick)=\"onBeforeClick($event)\">\n * </mj-cluster-scatter>\n * ```\n * ```typescript\n * onBeforeClick(event: CancelableEvent<ClusterPoint>): void {\n *     if (event.Data.ClusterId === -1) {\n *         event.Cancel = true; // suppress click on outliers\n *     }\n * }\n * ```\n */\nexport interface CancelableEvent<T = unknown> {\n    /** The event payload. */\n    Data: T;\n    /** Set to `true` to cancel the default operation that would follow. */\n    Cancel: boolean;\n}\n\n// ================================================================\n// Viewport / selection event payloads\n// ================================================================\n\n/**\n * Describes the visible rectangle of the scatter plot after a zoom or pan.\n *\n * Coordinates are in the SVG coordinate space (the `viewBox`).\n */\nexport interface ViewportRect {\n    /** Left edge X coordinate. */\n    MinX: number;\n    /** Top edge Y coordinate. */\n    MinY: number;\n    /** Viewport width in SVG units. */\n    Width: number;\n    /** Viewport height in SVG units. */\n    Height: number;\n}\n\n/**\n * Payload emitted when the user clicks a cluster label in the legend.\n */\nexport interface ClusterSelectedEvent {\n    /** The numeric cluster ID that was selected. */\n    ClusterId: number;\n    /** The human-readable label shown in the legend. */\n    Label: string;\n    /** The display color of the cluster. */\n    Color: string;\n    /** Number of points belonging to this cluster. */\n    MemberCount: number;\n}\n\n// ================================================================\n// Config panel types\n// ================================================================\n\n/**\n * Simple entity option used by the config panel's entity dropdown.\n * The parent component is responsible for populating this list.\n */\nexport interface ClusterConfigPanelEntityOption {\n    /** Entity display name shown in the dropdown. */\n    Name: string;\n}\n\n/** Option for the entity document dropdown in the config panel. */\nexport interface ClusterConfigPanelEntityDocOption {\n    /** Entity Document ID */\n    ID: string;\n    /** Display name of the entity document */\n    Name: string;\n}\n\n// ================================================================\n// Input types\n// ================================================================\n\n/**\n * A single vector provided to `ClusteringService.RunClustering()`.\n *\n * The caller is responsible for fetching/building these vectors from\n * whatever data source is appropriate (database, vector index, API, etc.).\n */\nexport interface ClusterInputVector {\n    /** Unique key identifying this vector (e.g., a record ID). */\n    Key: string;\n    /** The raw embedding / feature vector. */\n    Vector: number[];\n    /** Optional display label for this point (defaults to Key if omitted). */\n    Label?: string;\n    /** Arbitrary metadata surfaced in tooltips and click handlers. */\n    Metadata?: Record<string, unknown>;\n}\n\n// ================================================================\n// Core data types\n// ================================================================\n\n/**\n * A single point in the 2D scatter plot.\n *\n * Each point corresponds to one vectorized entity record after\n * dimensionality reduction (UMAP or PCA).\n */\nexport interface ClusterPoint {\n    /** X coordinate in 2D projected space. */\n    X: number;\n    /** Y coordinate in 2D projected space. */\n    Y: number;\n    /** Cluster assignment ID (`-1` for outliers / noise). */\n    ClusterId: number;\n    /** Display label for this point (typically the entity record identifier). */\n    Label: string;\n    /** Original vector key (e.g., entity record ID). */\n    VectorKey: string;\n    /** Arbitrary metadata surfaced in tooltips and click handlers. */\n    Metadata: Record<string, unknown>;\n}\n\n/**\n * Summary information about a single cluster.\n *\n * Produced by `ClusteringService.RunPipeline()` and consumed by the\n * scatter plot legend and various event payloads.\n */\nexport interface ClusterInfo {\n    /** Unique cluster identifier (zero-based). */\n    Id: number;\n    /** Human-readable label (auto-generated or user-defined). */\n    Label: string;\n    /** Display color as a CSS hex string (e.g., `#5b8def`). */\n    Color: string;\n    /** Number of member points in this cluster. */\n    MemberCount: number;\n}\n\n/** Supported clustering algorithms. */\nexport type ClusterAlgorithm = 'kmeans' | 'dbscan';\n\n/** Supported distance metrics for clustering. */\nexport type ClusterDistanceMetric = 'cosine' | 'euclidean' | 'dotproduct';\n\n/**\n * Full configuration for a clustering run.\n *\n * Pass an instance to `ClusteringService.RunPipeline()` or emit from the\n * config panel's `RunClustering` output.\n */\nexport interface ClusterConfig {\n    /** Entity name to cluster (must have Entity Documents with vectors). */\n    EntityName: string;\n    /** Specific Entity Document ID to use. When blank, the first active doc for the entity is used. */\n    EntityDocumentID: string;\n    /** Clustering algorithm to use. */\n    Algorithm: ClusterAlgorithm;\n    /** Number of clusters for K-Means (ignored for DBSCAN). */\n    K: number;\n    /** Epsilon neighbourhood radius for DBSCAN (ignored for K-Means). */\n    Epsilon: number;\n    /** Minimum points to form a dense region in DBSCAN (ignored for K-Means). */\n    MinPoints: number;\n    /** Distance metric used when comparing vectors. */\n    DistanceMetric: ClusterDistanceMetric;\n    /** Maximum number of entity records to fetch for clustering. */\n    MaxRecords: number;\n    /** Optional SQL-style filter applied to the Entity Document Runs query. */\n    Filter: string;\n}\n\n/**\n * Quality and performance metrics returned after a clustering run.\n */\nexport interface ClusterMetrics {\n    /** Silhouette score ranging from -1 (poor) to 1 (excellent). */\n    SilhouetteScore: number;\n    /** Total number of clusters discovered. */\n    ClusterCount: number;\n    /** Wall-clock computation time in milliseconds. */\n    ComputationTimeMs: number;\n    /** Total records that were processed. */\n    RecordCount: number;\n    /** Number of outlier points (DBSCAN only; 0 for K-Means). */\n    OutlierCount: number;\n}\n\n/**\n * Complete result of a clustering visualization pipeline.\n *\n * Returned by {@link ClusteringService.RunPipeline} and consumed by\n * both `mj-cluster-scatter` and `mj-cluster-config-panel`.\n */\nexport interface ClusterVisualizationResult {\n    /** 2D projected points ready for rendering. */\n    Points: ClusterPoint[];\n    /** Cluster summaries with colors and counts. */\n    Clusters: ClusterInfo[];\n    /** Performance and quality metrics. */\n    Metrics: ClusterMetrics;\n    /** The config that produced this result. */\n    Config: ClusterConfig;\n}\n\n/**\n * Serializable reference to a saved cluster visualization.\n *\n * Persisted via `UserInfoEngine` user settings so the user can reload\n * previous analyses.\n */\nexport interface SavedClusterVisualization {\n    /** Unique identifier (UUID). */\n    Id: string;\n    /** User-given display name. */\n    Name: string;\n    /** Entity that was clustered. */\n    EntityName: string;\n    /** Algorithm used. */\n    Algorithm: ClusterAlgorithm;\n    /** Snapshot of the full config at save time. */\n    Params: Partial<ClusterConfig>;\n    /** ISO 8601 timestamp of when this was saved. */\n    CreatedAt: string;\n    /** Cached clustering result (points, clusters, metrics) — avoids re-computation on restore. */\n    Result?: ClusterVisualizationResult;\n    /** Viewport transform at save time (pan + zoom state). */\n    Viewport?: ViewportTransform;\n    /** LLM-generated (or user-edited) labels for each cluster. */\n    ClusterLabels?: ClusterLabel[];\n}\n\n/** Viewport pan/zoom state for restoring scatter plot position. */\nexport interface ViewportTransform {\n    TranslateX: number;\n    TranslateY: number;\n    Scale: number;\n}\n\n/** A human-readable label for a cluster. */\nexport interface ClusterLabel {\n    /** The cluster ID this label applies to. */\n    ClusterId: number;\n    /** Short descriptive label (2-5 words). */\n    Label: string;\n    /** Whether the user has manually edited this label. */\n    IsUserEdited: boolean;\n}\n\n// ================================================================\n// Constants\n// ================================================================\n\n/**\n * Default cluster color palette -- 10 distinct, accessible colors.\n *\n * Override at the component level via `ClusterScatterComponent.ColorPalette`.\n */\nexport const CLUSTER_COLORS: string[] = [\n    '#5b8def', // blue\n    '#34d399', // emerald\n    '#fbbf24', // amber\n    '#f472b6', // pink\n    '#a78bfa', // violet\n    '#fb923c', // orange\n    '#22d3ee', // cyan\n    '#f87171', // red\n    '#4ade80', // green\n    '#e879f9', // fuchsia\n];\n\n// ================================================================\n// Factory functions\n// ================================================================\n\n/**\n * Create a `ClusterConfig` populated with sensible defaults.\n *\n * @returns A new `ClusterConfig` with K-Means / cosine / 500 max records.\n *\n * @example\n * ```typescript\n * const cfg = DefaultClusterConfig();\n * cfg.EntityName = 'Accounts';\n * cfg.K = 6;\n * ```\n */\nexport function DefaultClusterConfig(): ClusterConfig {\n    return {\n        EntityName: '',\n        EntityDocumentID: '',\n        Algorithm: 'kmeans',\n        K: 4,\n        Epsilon: 0.3,\n        MinPoints: 3,\n        DistanceMetric: 'cosine',\n        MaxRecords: 500,\n        Filter: '',\n    };\n}\n"]}

package/dist/public-api.d.ts

@@ -0,0 +1,6 @@
+export * from './lib/clustering.module';
+export * from './lib/cluster-scatter.component';
+export * from './lib/cluster-config-panel.component';
+export * from './lib/clustering.service';
+export * from './lib/clustering.types';
+//# sourceMappingURL=public-api.d.ts.map

package/dist/public-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-api.d.ts","sourceRoot":"","sources":["../src/public-api.ts"],"names":[],"mappings":"AAGA,cAAc,yBAAyB,CAAC;AAGxC,cAAc,iCAAiC,CAAC;AAChD,cAAc,sCAAsC,CAAC;AAGrD,cAAc,0BAA0B,CAAC;AAGzC,cAAc,wBAAwB,CAAC"}

package/dist/public-api.js

@@ -0,0 +1,11 @@
+// Public API Surface of @memberjunction/ng-clustering
+// Module
+export * from './lib/clustering.module';
+// Components
+export * from './lib/cluster-scatter.component';
+export * from './lib/cluster-config-panel.component';
+// Service
+export * from './lib/clustering.service';
+// Types
+export * from './lib/clustering.types';
+//# sourceMappingURL=public-api.js.map

package/dist/public-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-api.js","sourceRoot":"","sources":["../src/public-api.ts"],"names":[],"mappings":"AAAA,sDAAsD;AAEtD,SAAS;AACT,cAAc,yBAAyB,CAAC;AAExC,aAAa;AACb,cAAc,iCAAiC,CAAC;AAChD,cAAc,sCAAsC,CAAC;AAErD,UAAU;AACV,cAAc,0BAA0B,CAAC;AAEzC,QAAQ;AACR,cAAc,wBAAwB,CAAC","sourcesContent":["// Public API Surface of @memberjunction/ng-clustering\n\n// Module\nexport * from './lib/clustering.module';\n\n// Components\nexport * from './lib/cluster-scatter.component';\nexport * from './lib/cluster-config-panel.component';\n\n// Service\nexport * from './lib/clustering.service';\n\n// Types\nexport * from './lib/clustering.types';\n"]}

package/package.json

@@ -1,10 +1,45 @@
 {
   "name": "@memberjunction/ng-clustering",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @memberjunction/ng-clustering",
+  "version": "5.24.0",
+  "description": "MemberJunction: Reusable Angular clustering visualization components with scatter plot, config panel, and clustering service",
+  "main": "./dist/public-api.js",
+  "typings": "./dist/public-api.d.ts",
+  "files": [
+    "/dist"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "build": "ngc",
+    "test:watch": "vitest"
+  },
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
+    "angular",
+    "clustering",
+    "visualization",
+    "scatter-plot",
+    "memberjunction"
+  ],
+  "author": "MemberJunction",
+  "license": "ISC",
+  "devDependencies": {
+    "@angular/compiler": "21.1.3",
+    "@angular/compiler-cli": "21.1.3",
+    "vitest": "^4.0.18"
+  },
+  "peerDependencies": {
+    "@angular/common": "21.1.3",
+    "@angular/core": "21.1.3",
+    "@angular/forms": "21.1.3"
+  },
+  "dependencies": {
+    "@memberjunction/ai-vectors-memory": "5.24.0",
+    "@memberjunction/ng-entity-card": "5.24.0",
+    "tslib": "^2.8.1",
+    "umap-js": "^1.4.0"
+  },
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MemberJunction/MJ"
+  }
 }