plmt-constructor-sdk 0.13.5 → 0.13.7

package/README.md

@@ -0,0 +1,291 @@
+# Constructor SDK
+
+-   [Конфигурация виджета](#config)
+    -   [Настройка получения виджетом данных dataSettings](#data-settings)
+    -   [Метод группировки данных DataQueryMethod](#data-query-method)
+-   [Код виджета](#widget)
+    -   [SingleData и MultiData](#single-multy-data))
+    -   [Life cycle](#life-cycle)
+    -   [CSS переменные](#css-var)
+-   [Настройки виджета (установка параметров при создании)](#view-settings)
+
+<a name="config"></a>
+
+## Конфигурация виджета
+
+Конфигурацию описывает интерфейс `Config`. Рассмотрим пример:
+
+```ts
+import {
+    block,
+    colorize,
+    Config,
+    DataQueryFunction,
+    DataQueryMethod,
+    filter,
+    sort,
+} from 'plmt-constructor-sdk/config';
+
+export const config: Config = {
+    // Имя виджета. Отображается в списке загруженых выджетов
+    label: {
+        ru: 'Имя на русском',
+        en: 'И на английском',
+    },
+    // Иконка виджета. Отображается в списке загруженых выджетов
+    icon: 'icon.svg',
+
+    // метаданные для формирования документации виджета
+    documentation: {
+        // путь до файла в формате markdown с документацией
+        readme: 'widget/README.md',
+        // путь до папки и контентом для документации
+        assetsDirectory: 'widget/documentation-assets',
+        // пути к файлам превью виджета
+        images: [
+            'widget/documentation-assets/preview-1',
+            'widget/documentation-assets/preview-2',
+        ],
+    },
+
+    // см. Настройка получения виджетом данных
+    dataSettings: {
+        // см. Метод группировки данных
+        method: DataQueryMethod.Aggregate,
+
+        //
+        blocks: [
+            block({
+                // По данному ключу можно получить колонки в виджете
+                // this.dataSettings.columnsByBlock['uniq-key']
+                key: 'uniq-key',
+                label: { ru: 'Columns', en: '' },
+                // Влияет на агрегацию данных
+                // см. Метод группировки данных
+                dataQueryFunction: DataQueryFunction.Sum,
+            }),
+
+            // Добавляет блок для колонок, по которым будет осуществляться фильтрация
+            // Доступны в виджете через this.dataSettings.filters
+            filter(),
+
+            // Добавляет блок для колонок, по которым будет осуществляться сортировка
+            // Доступны в виджете через this.dataSettings.sort
+            sort(),
+
+            // Добавляет блок для колонок, по которым будет осуществляться раскраска
+            // Настройки раскраски доступна через
+            // this.dataSettings.colorize
+            colorize(),
+        ],
+    },
+};
+```
+
+<a name="data-settings"></a>
+
+### Настройка получения виджетом данных dataSettings
+
+Параметр конфигурации `dataSettings` описывает, из каких колонок датасета требуются данные, способ их фильтрации,
+сортировку, а также способ агрегации данных. Чаще всего виджет использует один датасет, но если требуется несколько
+датасетов, в конфигурации необходимо указать описание каждого в массиве, указав для каждого уникальный ключ:
+
+```ts
+    // ...
+    dataSettings: [
+        {
+            key: 'dataset-1',
+            label: { ru: 'Первый источник', en: '' },
+
+            method: DataQueryMethod.Table,
+            blocks: [
+                // ...
+            ],
+        },
+        {
+            key: 'dataset-2',
+            label: { ru: 'Второй источник', en: '' },
+
+            method: DataQueryMethod.Aggregate,
+            blocks: [
+                // ...
+            ],
+        },
+    ],
+    // ...
+```
+
+По значению ключей в виджете будут доступны данные и настройки (см. [SingleData и MultiData](#single-multy-data))
+
+<a name="data-query-method"></a>
+
+### Метод группировки данных DataQueryMethod
+
+Этот параметр может менять данные из датасета. Для примера рассмотрим исходную таблицу
+
+```
+╔═══╤═══╤═══╗
+║ A │ C │ 1 ║
+╟───┼───┼───╢
+║ A │ C │ 2 ║
+╟───┼───┼───╢
+║ B │ C │ 7 ║
+╚═══╧═══╧═══╝
+```
+
+Для `DataQueryMethod.Table` данные вернуться в исходном виде, тогда как для параметра
+`DataQueryMethod.Aggregate` будет произведена агрегация в зависимоти от параметра `dataQueryFunction`
+у блока. Например, при `DataQueryFunction.Sum` происходит суммирование числовых столбцов и
+группировка по значением в столбцах других типов. При этом данные в виджет попадут в таком виде:
+
+```
+╔═══╤═══╤═══╗
+║ A │ C │ 3 ║
+╟───┼───┼───╢
+║ B │ C │ 7 ║
+╚═══╧═══╧═══╝
+```
+
+<a name="widget"></a>
+
+## Код виджета
+
+Рассмотрим виджет
+
+```ts
+import { Declare, SingleData, Widget } from 'plmt-constructor-sdk';
+
+@Declare()
+export class Example extends Widget implements SingleData {
+    readonly data!: SingleData['data'];
+    readonly dataSettings!: SingleData['dataSettings'];
+
+    onChange(): void {
+        // ...
+
+        // ВАЖНО! Метод ready необходимо вызывать после каждого вызова onChange
+        this.ready();
+    }
+}
+```
+
+Чтобы класс стал виджетом, его необходимо декорировать `@Declare()`. Также, благодаря наследованию
+от базового класса `Widget`, будут доступны для автокомплика методы (например, `onThemeChange`) и свойства (например, `lang`).
+
+<a name="single-multy-data"></a>
+
+### SingleData и MultiData
+
+При конфигурировании можно указать [как один, так и несколько](#data-settings) источников данных.
+В зависимости от этого виджет будет реализовывать один из этих интерфейсов. Например, для нескольких датасетов, данные
+для каждого из них будут доступны через `key`, указанный в конфигурации:
+
+```ts
+import { Declare, MultiData, Widget } from 'plmt-constructor-sdk';
+
+@Declare()
+export class WidgetFilters extends Widget implements MultiData {
+    readonly data!: MultiData['data'];
+    readonly dataSettings!: MultiData['dataSettings'];
+
+    onChange(): void {
+        this.dataSettings['dataset-key'].dataset.name;
+    }
+```
+
+<a name="life-cycle"></a>
+
+### Life cycle
+
+Порядок срабатывания хуков виджета:
+
+-   `onThemeChange` при инициализации и при смене темы
+-   `onLangChange` при инициализации и при смене языка
+-   `onInit` при инициализации
+-   `onChange` при инициализации и при смене данных
+
+<a name="css-var"></a>
+
+### CSS переменные
+
+По умолчанию, css переменные не объявляются. Для их инициализации необходимо указать параметр
+`provideCssVariables` у декоратора `Declare`:
+
+```ts
+@Declare({
+    provideCssVariables: true,
+})
+```
+
+При этом будут объявлены все переменные, доступные для виджета через `this.theme`, но в kebab-case:
+
+```css
+/* this.theme.text → --text */
+color: var(--text);
+/* this.theme.backgroundBright → --background-bright */
+background: var(--background-bright);
+```
+
+<a name="view-settings"></a>
+
+## Настройки виджета (установка параметров при создании)
+
+При создании виджета, пользователь может установить параметры следующих типов:
+
+-   input
+-   checkbox
+-   radio
+-   select
+-   colorPicker
+-   title (заголовок блока настроек, используется для разделения параметров на блоки)
+
+Эти параметры получаются динамически из вызова функции `createViewSettings` в файле `src/view-settings.ts`.
+Рассмотрим пример. Здесь выводится текстовое поле, в которое можно ввести число от 1 до количества колонок
+в блоке с ключом `blocke-key`:
+
+```ts
+import { DataSettings } from 'plmt-constructor-sdk';
+import {
+    CreateViewSettings,
+    input,
+    ViewSettingsValidation,
+} from 'plmt-constructor-sdk/config';
+
+let max = 0;
+
+export const createViewSettings: CreateViewSettings<DataSettings> = ({
+    dataSettings,
+}) => {
+    max = dataSettings.columnsByBlock['blocke-key'].length;
+
+    return [
+        input({
+            key: 'number-key',
+            label: {
+                ru: `Число от 1 до ${max}`,
+                en: `Range 1 to ${max}`,
+            },
+        }),
+    ];
+};
+
+export const validation: ViewSettingsValidation = {
+    ['number-key']: (value: any) => {
+        const number = parseInt(value);
+
+        if (isNaN(number))
+            return {
+                ru: 'Значение должно быть числом',
+                en: 'Not a number',
+            };
+
+        if (number < 1 || number > max)
+            return {
+                ru: `Значение должно быть в диапозоне от 1 до ${max}`,
+                en: `Not in range 1 до ${max}`,
+            };
+
+        return null;
+    },
+};
+```

package/__internal__/config.d.ts

@@ -1,54 +1,60 @@
-import { Text, DataQueryMethod, DataQueryFunction } from '../config';
-import { ColumnType } from '../data';
-import { DatasetColumnType_Server } from './dataset';
-export declare enum ConfigDataBlockType_Server {
-    Column = "column",
-    Filter = "filter",
-    Sort = "sort",
-    Colorizer = "colorizer",
-    Drilldown = "drilldown"
-}
-export interface Config_Server {
-    label: Text;
-    icon: string;
-    data_options: ConfigDataOption_Server[];
-    doc: {
-        info: string;
-        assets: string;
-        images: string[];
-    };
-    sdk_version: string;
-    type?: string;
-    version: string;
-}
-export interface ConfigDataOption_Server {
-    key: string;
-    method: DataQueryMethod;
-    label?: Text;
-    min?: number;
-    max?: number;
-    validation?: {
-        required_some?: string[];
-        required_every?: string[];
-    };
-    blocks: ConfigDataOptionBlock_Server[];
-}
-export interface ConfigDataOptionBlock_Server {
-    type: ConfigDataBlockType_Server;
-    key: string;
-    label: Text;
-    icon?: string;
-    data_type?: DatasetColumnType_Server;
-    field_type?: ColumnType;
-    max?: number;
-    function?: DataQueryFunction;
-}
-export declare const configDataBlock_Server = "8316067a-d04b-4b21-bd4d-35529846617b";
-export declare const blockFilterKey = "34642664-dbd1-4e35-b0ea-2eaabe796b48";
-export declare const blockSortKey = "2c849ed6-6105-4aa2-a961-9f95135dfe3b";
-export declare const blockColorizeKey = "badd51f7-82ce-45b2-a67e-37d52df88c5c";
-export declare function decodeDrilldownData(source: string, additionalFilterSources: string[]): string;
-export declare function encodeDrilldownData(key: string): {
-    source: string;
-    additionalFilterSources: string[];
-};
+import { Text, DataQueryMethod, DataQueryFunction } from '../config';
+import { ColumnType } from '../data';
+import { DatasetColumnType_Server } from './dataset';
+export declare enum ConfigDataBlockType_Server {
+    Column = "column",
+    Filter = "filter",
+    Sort = "sort",
+    Colorizer = "colorizer",
+    Drilldown = "drilldown"
+}
+export interface Config_Server {
+    label: Text;
+    icon: string;
+    data_options: ConfigDataOption_Server[];
+    doc: {
+        info: string;
+        assets: string;
+        images: string[];
+    };
+    sdk_version: string;
+    type?: string;
+    repeatable?: true | {
+        min?: number;
+        max?: number;
+    };
+    version: string;
+}
+export interface ConfigDataOption_Server {
+    key: string;
+    method: DataQueryMethod;
+    label?: Text;
+    min?: number;
+    max?: number;
+    hideSort?: boolean;
+    hideCounter?: boolean;
+    validation?: {
+        required_some?: string[];
+        required_every?: string[];
+    };
+    blocks: ConfigDataOptionBlock_Server[];
+}
+export interface ConfigDataOptionBlock_Server {
+    type: ConfigDataBlockType_Server;
+    key: string;
+    label: Text;
+    icon?: string;
+    data_type?: DatasetColumnType_Server;
+    field_type?: ColumnType;
+    max?: number;
+    function?: DataQueryFunction;
+}
+export declare const configDataBlock_Server = "8316067a-d04b-4b21-bd4d-35529846617b";
+export declare const blockFilterKey = "34642664-dbd1-4e35-b0ea-2eaabe796b48";
+export declare const blockSortKey = "2c849ed6-6105-4aa2-a961-9f95135dfe3b";
+export declare const blockColorizeKey = "badd51f7-82ce-45b2-a67e-37d52df88c5c";
+export declare function decodeDrilldownData(source: string, additionalFilterSources: string[]): string;
+export declare function encodeDrilldownData(key: string): {
+    source: string;
+    additionalFilterSources: string[];
+};

package/__internal__/config.js

@@ -1,46 +1,46 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.encodeDrilldownData = exports.decodeDrilldownData = exports.blockColorizeKey = exports.blockSortKey = exports.blockFilterKey = exports.configDataBlock_Server = exports.ConfigDataBlockType_Server = void 0;
-// enums
-var ConfigDataBlockType_Server;
-(function (ConfigDataBlockType_Server) {
-    ConfigDataBlockType_Server["Column"] = "column";
-    ConfigDataBlockType_Server["Filter"] = "filter";
-    ConfigDataBlockType_Server["Sort"] = "sort";
-    ConfigDataBlockType_Server["Colorizer"] = "colorizer";
-    ConfigDataBlockType_Server["Drilldown"] = "drilldown";
-})(ConfigDataBlockType_Server = exports.ConfigDataBlockType_Server || (exports.ConfigDataBlockType_Server = {}));
-exports.configDataBlock_Server = '8316067a-d04b-4b21-bd4d-35529846617b';
-exports.blockFilterKey = '34642664-dbd1-4e35-b0ea-2eaabe796b48';
-exports.blockSortKey = '2c849ed6-6105-4aa2-a961-9f95135dfe3b';
-exports.blockColorizeKey = 'badd51f7-82ce-45b2-a67e-37d52df88c5c';
-function decodeDrilldownData(source, additionalFilterSources) {
-    const keyParts = [length(source.length), source];
-    additionalFilterSources.forEach((item) => keyParts.push(length(item.length), item));
-    return keyParts.join('');
-    function length(value) {
-        if (value > 0xff)
-            throw new RangeError();
-        return value > 0xf
-            ? `0x${value.toString(16)}`
-            : `0x0${value.toString(16)}`;
-    }
-}
-exports.decodeDrilldownData = decodeDrilldownData;
-function encodeDrilldownData(key) {
-    const parts = [];
-    parse();
-    const [source, ...additionalFilterSources] = parts;
-    return {
-        source,
-        additionalFilterSources,
-    };
-    function parse(offset = 0) {
-        const start = offset + 4;
-        const end = start + parseInt(key.slice(offset, start));
-        parts.push(key.slice(start, end));
-        if (end < key.length)
-            parse(end);
-    }
-}
-exports.encodeDrilldownData = encodeDrilldownData;
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeDrilldownData = exports.decodeDrilldownData = exports.blockColorizeKey = exports.blockSortKey = exports.blockFilterKey = exports.configDataBlock_Server = exports.ConfigDataBlockType_Server = void 0;
+// enums
+var ConfigDataBlockType_Server;
+(function (ConfigDataBlockType_Server) {
+    ConfigDataBlockType_Server["Column"] = "column";
+    ConfigDataBlockType_Server["Filter"] = "filter";
+    ConfigDataBlockType_Server["Sort"] = "sort";
+    ConfigDataBlockType_Server["Colorizer"] = "colorizer";
+    ConfigDataBlockType_Server["Drilldown"] = "drilldown";
+})(ConfigDataBlockType_Server = exports.ConfigDataBlockType_Server || (exports.ConfigDataBlockType_Server = {}));
+exports.configDataBlock_Server = '8316067a-d04b-4b21-bd4d-35529846617b';
+exports.blockFilterKey = '34642664-dbd1-4e35-b0ea-2eaabe796b48';
+exports.blockSortKey = '2c849ed6-6105-4aa2-a961-9f95135dfe3b';
+exports.blockColorizeKey = 'badd51f7-82ce-45b2-a67e-37d52df88c5c';
+function decodeDrilldownData(source, additionalFilterSources) {
+    const keyParts = [length(source.length), source];
+    additionalFilterSources.forEach((item) => keyParts.push(length(item.length), item));
+    return keyParts.join('');
+    function length(value) {
+        if (value > 0xff)
+            throw new RangeError();
+        return value > 0xf
+            ? `0x${value.toString(16)}`
+            : `0x0${value.toString(16)}`;
+    }
+}
+exports.decodeDrilldownData = decodeDrilldownData;
+function encodeDrilldownData(key) {
+    const parts = [];
+    parse();
+    const [source, ...additionalFilterSources] = parts;
+    return {
+        source,
+        additionalFilterSources,
+    };
+    function parse(offset = 0) {
+        const start = offset + 4;
+        const end = start + parseInt(key.slice(offset, start));
+        parts.push(key.slice(start, end));
+        if (end < key.length)
+            parse(end);
+    }
+}
+exports.encodeDrilldownData = encodeDrilldownData;

package/__internal__/dataset.d.ts

@@ -1,19 +1,19 @@
-import { ColumnType } from '../data';
-export { ColumnType as ColumnFieldType_Server } from '../data';
-export declare enum DatasetColumnType_Server {
-    Dimension = "dimension",
-    Fact = "fact",
-    Any = "any"
-}
-export interface Dataset_Server {
-    id: number;
-    name: string;
-    columns_id: Column_Server[];
-}
-export interface Column_Server {
-    id: number;
-    name: string;
-    path: string;
-    base_type: ColumnType;
-    data_type?: DatasetColumnType_Server;
-}
+import { ColumnType } from '../data';
+export { ColumnType as ColumnFieldType_Server } from '../data';
+export declare enum DatasetColumnType_Server {
+    Dimension = "dimension",
+    Fact = "fact",
+    Any = "any"
+}
+export interface Dataset_Server {
+    id: number;
+    name: string;
+    columns_id: Column_Server[];
+}
+export interface Column_Server {
+    id: number;
+    name: string;
+    path: string;
+    base_type: ColumnType;
+    data_type?: DatasetColumnType_Server;
+}

package/__internal__/dataset.js

@@ -1,12 +1,12 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DatasetColumnType_Server = exports.ColumnFieldType_Server = void 0;
-// enums
-var data_1 = require("../data");
-Object.defineProperty(exports, "ColumnFieldType_Server", { enumerable: true, get: function () { return data_1.ColumnType; } });
-var DatasetColumnType_Server;
-(function (DatasetColumnType_Server) {
-    DatasetColumnType_Server["Dimension"] = "dimension";
-    DatasetColumnType_Server["Fact"] = "fact";
-    DatasetColumnType_Server["Any"] = "any";
-})(DatasetColumnType_Server = exports.DatasetColumnType_Server || (exports.DatasetColumnType_Server = {}));
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DatasetColumnType_Server = exports.ColumnFieldType_Server = void 0;
+// enums
+var data_1 = require("../data");
+Object.defineProperty(exports, "ColumnFieldType_Server", { enumerable: true, get: function () { return data_1.ColumnType; } });
+var DatasetColumnType_Server;
+(function (DatasetColumnType_Server) {
+    DatasetColumnType_Server["Dimension"] = "dimension";
+    DatasetColumnType_Server["Fact"] = "fact";
+    DatasetColumnType_Server["Any"] = "any";
+})(DatasetColumnType_Server = exports.DatasetColumnType_Server || (exports.DatasetColumnType_Server = {}));

package/__internal__/theme.d.ts

@@ -1,13 +1,13 @@
-import { Theme } from '../theme';
-export interface ThemeProvide {
-    theme: Theme;
-    themeKey: string;
-    themeProjectKey: string;
-}
-export declare type ThemeKey = keyof Pick<Theme, 'background' | 'backgroundBright' | 'backgroundTint' | 'text' | 'textTint'>;
-export declare type ThemeProjectKey = keyof Pick<Theme, 'colors'>;
-export declare const themeKeys: ThemeKey[];
-export declare const themeProjectKeys: ThemeProjectKey[];
-export declare function provideCssVariables({ theme, themeKey, themeProjectKey, }: ThemeProvide): void;
-export declare function colorizeClassName(i: number, j: number): string;
-export declare function createColorizeColors(source: string[]): string[][];
+import { Theme } from '../theme';
+export interface ThemeProvide {
+    theme: Theme;
+    themeKey: string;
+    themeProjectKey: string;
+}
+export declare type ThemeKey = keyof Pick<Theme, 'background' | 'backgroundBright' | 'backgroundTint' | 'text' | 'textTint'>;
+export declare type ThemeProjectKey = keyof Pick<Theme, 'colors'>;
+export declare const themeKeys: ThemeKey[];
+export declare const themeProjectKeys: ThemeProjectKey[];
+export declare function provideCssVariables({ theme, themeKey, themeProjectKey, }: ThemeProvide): void;
+export declare function colorizeClassName(i: number, j: number): string;
+export declare function createColorizeColors(source: string[]): string[][];