@sisense/sdk-ui 2.28.0 → 2.30.0

package/dist/packages/sdk-ui/src/infra/app/types.d.ts

@@ -3,6 +3,7 @@ import { PivotQueryClient } from '@sisense/sdk-pivot-query-client';
 import { QueryClient } from '@sisense/sdk-query-client';
 import { HttpClient } from '@sisense/sdk-rest-client';
 import { TrackingEventDetails } from '@sisense/sdk-tracking';
+import type { Locale } from 'date-fns';
 import { DateConfig, LoadingIndicatorConfig, TranslationConfig } from '../../types';
 import { AppSettings } from './settings/settings';
 /**
@@ -159,6 +160,24 @@ export type AppConfig = {
          */
         enabled?: boolean;
     };
+    /**
+     * Configuration of the Narrative feature for widgets
+     * Temporary feature flag to explicitly enable narrative on widgets
+     * (avoid narratives appearing in fusion dashboards/widgets before this feature is released)
+     * @sisenseInternal
+     */
+    narrativeConfig?: {
+        /**
+         * Whether to enable or disable the Widget Narrative feature
+         *
+         * When `true`, the Widget Narrative feature is enabled if the Fusion server supports it.
+         *
+         * When `false`, the Widget Narrative feature is disabled.
+         *
+         * @default false
+         */
+        widgetNarrativeEnabled?: boolean;
+    };
     /**
      * Global configuration for some specific aspects of data visualizations.
      */
@@ -190,6 +209,19 @@ export type AppConfig = {
              */
             alwaysShowResultsPerPage?: boolean;
         };
+        /**
+         * Configuration of the default number formatting for visualizations.
+         *
+         * @sisenseInternal
+         */
+        defaultNumberFormatting?: {
+            /**
+             *  If `false`, raw values are displayed without applying the default number formatting configuration.
+             *
+             * @default true
+             */
+            enabled?: boolean;
+        };
     };
 };
 /**

package/dist/packages/sdk-ui/src/infra/contexts/sisense-context/sisense-context-provider.d.ts

@@ -1,4 +1,4 @@
-import { type FunctionComponent, PropsWithChildren } from 'react';
+import { type FunctionComponent, type PropsWithChildren } from 'react';
 import { SisenseContextProviderProps } from '../../../props';
 /**
  * Sisense Context Provider Component allowing you to connect to

package/dist/packages/sdk-ui/src/infra/formatting/format-data-set.d.ts

@@ -0,0 +1,21 @@
+import { Data, QueryResultData } from '@sisense/sdk-data';
+import { CommonDataOptions } from '../../domains/visualizations/core/chart-data-options/types';
+import { FormatDateOptions } from './format-date';
+/**
+ * Options for {@link formatDataSet}.
+ */
+export type FormatDataSetOptions = FormatDateOptions;
+/**
+ * Formats a data set by applying the number and date formatting declared in `dataOptions` to a data set.
+ * Writes the formatted result into each affected cell's `text` property.
+ *
+ * @example
+ * const formattedData = formatDataSet(data, dataOptions);
+ *
+ * @param data - Query result or user-provided data set.
+ * @param dataOptions - Any chart, pivot, or custom-widget data options.
+ * @param options - Formatting options.
+ * @returns A new data set with formatted `text` values on affected cells.
+ * @group Formatting
+ */
+export declare function formatDataSet<DataSet extends QueryResultData | Data>(data: DataSet, dataOptions: CommonDataOptions, options?: FormatDataSetOptions): DataSet;

package/dist/packages/sdk-ui/src/infra/formatting/format-date.d.ts

@@ -0,0 +1,67 @@
+import type { Locale } from 'date-fns';
+import type { DateConfig } from '../../domains/query-execution/core/date-formats';
+/**
+ * Options for {@link formatDate}.
+ */
+export type FormatDateOptions = {
+    /**
+     * A [date-fns Locale](https://date-fns.org/v2.30.0/docs/Locale) for language-specific formatting.
+     * Defaults to 'en-US'.
+     */
+    locale?: Locale;
+    /**
+     * Fiscal year, timezone, and date-level configuration.
+     */
+    dateConfig?: DateConfig;
+};
+/**
+ * Formats a single date value (Date instance or ISO 8601 string) using the
+ * provided format mask.
+ *
+ * Accepts standard [date-fns format tokens](https://date-fns.org/v2.30.0/docs/format)
+ * plus the SDK's extended Angular-style masks (locale-aware; examples use en-US):
+ *
+ * ```
+ * shortDate   → '3/15/26'                  (M/d/yy)
+ * mediumDate  → 'Mar 15, 2026'             (MMM d, y)
+ * longDate    → 'March 15, 2026'           (MMMM d, y)
+ * fullDate    → 'Sunday, March 15, 2026'   (EEEE, MMMM d, y)
+ * shortTime   → '1:45 PM'                  (h:mm a)
+ * mediumTime  → '1:45:00 PM'               (h:mm:ss a)
+ * short       → '3/15/26 1:45 PM'          (M/d/yy h:mm a)
+ * medium      → 'Mar 15, 2026 1:45:00 PM'  (MMM d, y h:mm:ss a)
+ * ```
+ *
+ * Returns the input unchanged if it matches the reserved "not available" value (`'N\A'`).
+ *
+ * @example
+ * formatDate(new Date('2026-03-15'), 'MM/yyyy');
+ * // returns '03/2026'
+ *
+ * formatDate('2026-03-15T13:45:00Z', 'shortDate');
+ * // returns '3/15/26'  (en-US locale)
+ *
+ * formatDate('2026-03-15T13:45:00Z', 'mediumDate');
+ * // returns 'Mar 15, 2026'
+ *
+ * @param value - Date value to format.
+ * @param format - Format mask string (date-fns tokens or SDK extended masks).
+ * @param options - Optional locale and date configuration.
+ * @returns Formatted date string.
+ * @group Formatting
+ */
+export declare function formatDate(value: Date | string, format: string, options?: FormatDateOptions): string;
+/**
+ * Returns a default date-format mask for a given granularity level from {@link @sisense/sdk-data!DateLevels | `DateLevels`}
+ *
+ * Falls back to default `'fullDate'` for unknown or absent granularities.
+ *
+ * @example
+ * getDefaultDateFormat('months'); // 'MM/yyyy'
+ * getDefaultDateFormat('years');  // 'yyyy'
+ * getDefaultDateFormat('days');   // 'shortDate'
+ * @param granularity - Optional granularity string.
+ * @returns A date-format mask string.
+ * @group Formatting
+ */
+export declare function getDefaultDateFormat(granularity?: string): string;

package/dist/packages/sdk-ui/src/infra/formatting/format-number.d.ts

@@ -0,0 +1,24 @@
+import type { NumberFormatConfig } from '../../types';
+/**
+ * Formats a single numeric value using the provided {@link NumberFormatConfig}.
+ *
+ * Missing config falls back to defaults:
+ * Numbers type, auto decimal scale, thousand separator enabled, all abbreviations (K/M/B/T) enabled.
+ *
+ * Returns an empty string when `value` is `NaN`.
+ *
+ * @example
+ * formatNumber(1234567);
+ * // returns '1.23M'
+ *
+ * formatNumber(0.42, { name: 'Percent', decimalScale: 1 });
+ * // returns '42.0%'
+ *
+ * formatNumber(1500, { name: 'Currency', symbol: '€', prefix: true });
+ * // returns '€1.5K'
+ * @param value - The numeric value to format.
+ * @param config - Formatting configuration.
+ * @returns Formatted string representation of the value.
+ * @group Formatting
+ */
+export declare function formatNumber(value: number, config?: NumberFormatConfig): string;

package/dist/packages/sdk-ui/src/infra/formatting/index.d.ts

@@ -0,0 +1,5 @@
+export { formatNumber } from './format-number';
+export { formatDate, getDefaultDateFormat } from './format-date';
+export { formatDataSet } from './format-data-set';
+export type { FormatDateOptions } from './format-date';
+export type { FormatDataSetOptions } from './format-data-set';

package/dist/packages/sdk-ui/src/infra/modules/build-module-graph.d.ts

@@ -0,0 +1,31 @@
+import type { Module } from './types.js';
+/** Normalised view of a `ModuleRequirement`. */
+interface NormalizedRequirement {
+    name: string;
+    optional: boolean;
+    requiredVersion?: string;
+}
+/** A module after graph resolution, with its normalised requirements attached. */
+export interface ResolvedModule {
+    module: Module;
+    requirements: NormalizedRequirement[];
+    /**
+     * Names of soft requirements that were absent or version-incompatible at boot.
+     * Integrations targeting these names are silently dropped.
+     */
+    missingOptionalTargets: Set<string>;
+}
+/**
+ * Builds the validated, topologically-ordered module graph from the given roots.
+ *
+ * - Recursively expands `includes` and dedupes by `name` (versions must match).
+ * - Validates every hard `requires` target is present and its version satisfies
+ *   any declared `requiredVersion`.
+ * - Drops contributions to soft requirements (`optional: true`) that are missing
+ *   or version-incompatible.
+ * - Validates each integration targets a declared requirement and a known field
+ *   on the target's `api`.
+ * - Returns modules sorted so each appears after its requirements.
+ */
+export declare const buildModuleGraph: (modules: ReadonlyArray<Module>) => ResolvedModule[];
+export {};

package/dist/packages/sdk-ui/src/infra/modules/build-module-registry.d.ts

@@ -0,0 +1,31 @@
+import type { Module } from './types.js';
+/**
+ * Modules API registry.
+ *
+ * Each registry is an opaque value produced by the owning module's
+ * `ApiField.createRegistry` and written to by every contributor's
+ * `ApiField.register`. Keyed by `(moduleName, fieldName)` to keep field names
+ * scoped to their owning module.
+ */
+export interface ModulesApiRegistry {
+    /** Returns the registry for a module's API field, or `undefined` if absent. */
+    get(moduleName: string, fieldName: string): unknown;
+    /** Whether the given module's API field has a registry in this store. */
+    has(moduleName: string, fieldName: string): boolean;
+}
+/** Result of building a module registry from a set of user-provided modules. */
+export interface ModulesRegistry {
+    /** Registered modules array (in topological order) */
+    modules: Module[];
+    /** Modules api registry. */
+    apiRegistry: ModulesApiRegistry;
+}
+/**
+ * Builds a per-`ModuleProvider` registry from the given user-provided modules.
+ *
+ * - Always includes `CoreModule`.
+ * - Builds and validates the module graph (`buildModuleGraph`).
+ * - Creates a fresh registry per API field via `ApiField.createRegistry`.
+ * - Applies every contribution in topological order via `ApiField.register`.
+ */
+export declare const buildModuleRegistry: (modules?: ReadonlyArray<Module>) => ModulesRegistry;

package/dist/packages/sdk-ui/src/infra/modules/core-module-providers-tree.d.ts

@@ -0,0 +1,11 @@
+import { type FunctionComponent, type PropsWithChildren } from 'react';
+/**
+ * Registers providers passed via the `core.providers` API.
+ *
+ * The registry is read from the enclosing `ModuleProvider`, so each
+ * `SisenseContextProvider` instance mounts only the providers contributed by
+ * the modules it registered. Providers are mounted in registration
+ * (topological) order — the first entry is the outermost wrapper.
+ *
+ */
+export declare const CoreModuleProvidersTree: FunctionComponent<PropsWithChildren>;

package/dist/packages/sdk-ui/src/infra/modules/core-module.d.ts

@@ -0,0 +1,26 @@
+import type { ComponentType, ReactNode } from 'react';
+import type { ApiContract, ApiField, Module } from './types.js';
+type ProviderComponent = ComponentType<{
+    children: ReactNode;
+}>;
+/**
+ * API declaration for the `core` module.
+ */
+export interface CoreModuleApiDefinition {
+    /** Root-level React providers mounted by `SisenseContextProvider`. */
+    providers: ApiField<ProviderComponent[], ProviderComponent[]>;
+}
+/**
+ * API contract for contributing to the `core` module.
+ */
+export type CoreModuleApi = ApiContract<CoreModuleApiDefinition>;
+export declare const CORE_MODULE_NAME = "core";
+/**
+ * The `core` module.
+ * Always registered automatically by `ModuleProvider`; consumers do not need to list it in the `modules` prop.
+ *
+ * Owns the `providers` registry — other modules contribute root-level React
+ * providers there, which `CoreModuleProvidersTree` mounts inside `SisenseContextProvider`.
+ */
+export declare const CoreModule: Module<CoreModuleApiDefinition>;
+export {};

package/dist/packages/sdk-ui/src/infra/modules/index.d.ts

@@ -0,0 +1,3 @@
+export type { Module, ModuleRequirement } from './types.js';
+export { useModuleApiRegistry } from './modules-context.js';
+export { ModuleProvider, type ModuleProviderProps } from './module-provider.js';

package/dist/packages/sdk-ui/src/infra/modules/module-provider.d.ts

@@ -0,0 +1,17 @@
+import { type FunctionComponent, type PropsWithChildren } from 'react';
+import type { Module } from './types.js';
+/**
+ * Props for `ModuleProvider`.
+ */
+export interface ModuleProviderProps {
+    /**
+     * Modules to register.
+     *
+     * `CoreModule` is registered automatically; consumers do not need to list it.
+     */
+    modules?: ReadonlyArray<Module>;
+}
+/**
+ * Registers the given modules and makes the API registry available to the children.
+ */
+export declare const ModuleProvider: FunctionComponent<PropsWithChildren<ModuleProviderProps>>;

package/dist/packages/sdk-ui/src/infra/modules/modules-context.d.ts

@@ -0,0 +1,20 @@
+/// <reference types="react" />
+import type { ModulesApiRegistry } from './build-module-registry.js';
+import type { Module, RegistryOf } from './types.js';
+/**
+ * Modules API registry context.
+ */
+export declare const ModulesContext: import("react").Context<ModulesApiRegistry | null>;
+/**
+ * Gives access to the API registry for a given module and field.
+ *
+ * @example
+ * ```ts
+ * const chartBuilders = useModuleApiRegistry(VisualizationsModule, 'chartBuilders');
+ * ```
+ * @throws if used outside a `ModuleProvider`.
+ * @throws if `module` was not registered in the enclosing provider.
+ *
+ * @alpha
+ */
+export declare const useModuleApiRegistry: <TSchema, K extends keyof TSchema & string>(module: Module<TSchema>, field: K) => RegistryOf<TSchema, K>;

package/dist/packages/sdk-ui/src/infra/modules/types.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Producer-side declaration of a single API field on a module.
+ */
+export interface ApiField<TValue, TRegistry> {
+    /** Creates the per-registration registry holding contributions for this field. */
+    createRegistry: () => TRegistry;
+    /** Writes a contribution into the registry. Invoked once per contributor. */
+    register: (value: TValue, registry: TRegistry, fromModule: Module) => void;
+}
+/**
+ * The shape of a producer module's `api` property — a record of `ApiField` declarations.
+ * Each module declares its own concrete schema (e.g. `CoreModuleApiDefinition`);
+ */
+export type ApiSchema = Record<string, ApiField<any, any>>;
+/**
+ * Module definition
+ *
+ * @alpha
+ */
+export interface Module<TSchema = any> {
+    /** Unique module identifier, e.g. `'dashboard'`. */
+    name: string;
+    /** Module version */
+    version: string;
+    /**
+     * Modules this module integrates with.
+     * - `'name'` → hard requirement.
+     * - `{ name }` → hard requirement.
+     * - `{ name, optional: true }` → soft; contributions to it are dropped if absent.
+     * - `{ ..., requiredVersion: '^2.0.0' }` → optional semver range constraint.
+     */
+    requires?: ReadonlyArray<ModuleRequirement>;
+    /** Modules this one ships as part of its own feature */
+    includes?: ReadonlyArray<Module>;
+    /**
+     * Declarative contributions to other modules, keyed by target module name.
+     */
+    integrations?: Record<string, unknown>;
+    /** Producer-side API declaration; defines registries other modules contribute to. */
+    api?: TSchema;
+}
+/**
+ * Hard or soft requirement on another module, optionally version-constrained.
+ *
+ * @alpha
+ */
+export type ModuleRequirement = string | {
+    name: string;
+    /** If true, the requirement may be missing and contributions to it are dropped. */
+    optional?: boolean;
+    /**
+     * Semver range the registered target's `version` must satisfy
+     * (e.g. `'^2.0.0'`). Mismatches throw at boot unless `optional`.
+     */
+    requiredVersion?: string;
+};
+/**
+ * Resolves the registry type owned by a producer module's API field — the
+ * value `useModuleApiRegistry(module, field)` returns.
+ */
+export type RegistryOf<TSchema, K extends keyof TSchema> = TSchema[K] extends ApiField<any, infer R> ? R : never;
+/**
+ * Resolves the contribution value type a consumer must supply for a producer's API field.
+ */
+export type ValueOf<TSchema, K extends keyof TSchema> = TSchema[K] extends ApiField<infer V, any> ? V : never;
+/**
+ * Derives the consumer-facing `*ModuleApi` contract from a producer schema.
+ * Each field becomes optional and typed as its contribution value.
+ *
+ * @example
+ * ```ts
+ * export type CoreModuleApi = ApiContract<CoreModuleApiDefinition>;
+ * // → { providers?: ComponentType<{ children: ReactNode }>[] }
+ * ```
+ * @alpha
+ */
+export type ApiContract<TSchema> = {
+    [K in keyof TSchema]?: ValueOf<TSchema, K>;
+};

package/dist/packages/sdk-ui/src/infra/plugins/types.d.ts

@@ -1,8 +1,17 @@
-import type { AnyWidgetPlugin } from './widget-plugins/types.js';
+import type { WidgetPlugin } from './widget-plugins/types.js';
 /**
- * Base plugin information
+ * Defines base information shared by all plugin types.
  *
- * @sisenseInternal
+ * @group Plugin System
+ * @example
+ * ```ts
+ * const info: BasePluginInfo = {
+ *   name: 'my-widget-plugin',
+ *   version: '1.0.0',
+ *   requiredApiVersion: '^2.9.0',
+ * };
+ * ```
+ * @beta
  */
 export interface BasePluginInfo {
     /**
@@ -50,9 +59,28 @@ export interface PluginValidationResult {
     reason?: string;
 }
 /**
- * Plugin declaration.
+ * Declares a plugin for registration with the Compose SDK.
  * Currently only widget plugins are supported.
  *
- * @sisenseInternal
+ * @group Plugin System
+ * @example
+ * ```tsx
+ * import { SisenseContextProvider } from '@sisense/sdk-ui';
+ *
+ * const myPlugin: Plugin = {
+ *   name: 'my-widget-plugin',
+ *   version: '1.0.0',
+ *   requiredApiVersion: '^2.9.0',
+ *   pluginType: 'widget',
+ *   customWidget: {
+ *     name: 'my-widget',
+ *     displayName: 'My Widget',
+ *     visualization: { Component: MyVisualization },
+ *   },
+ * };
+ *
+ * <SisenseContextProvider plugins={[myPlugin]} {...props} />
+ * ```
+ * @beta
  */
-export type Plugin = AnyWidgetPlugin;
+export type Plugin = WidgetPlugin<any>;