@gravity-ui/dashkit 10.2.0 → 10.4.0

package/build/docs/INDEX.md

@@ -0,0 +1,534 @@
+# @gravity-ui/dashkit documentation
+
+Documentation for the **installed** version of `@gravity-ui/dashkit`.
+Your training data may be outdated — these files are the source of truth.
+
+Paths are relative to this file (`node_modules/@gravity-ui/dashkit/build/docs/`).
+
+## For AI agents
+
+A dashboard grid composer that arranges resizable, draggable widgets in a responsive grid via a plugin system — reach for it when you build a user-editable dashboard (add/move/resize/delete widgets) instead of placing individual charts or panels by hand.
+
+### When to use
+
+- Rendering a configurable dashboard where widgets are positioned, resized, and rearranged on a grid (built on `react-grid-layout`).
+- User-editable layouts: adding/removing widgets from an action panel, drag-and-drop, edit mode with overlay controls.
+- Plugin-based widgets where each widget type (title, text, chart, custom) is registered once and driven by a `config`.
+
+### When not to use
+
+- For a single, fixed chart or panel, use [`@gravity-ui/charts`](https://gravity-ui.com/charts) or [`@gravity-ui/chartkit`](https://github.com/gravity-ui/chartkit) directly — the grid/plugin machinery is overhead for one widget.
+- For a general-purpose responsive grid that is not a widget dashboard, use `react-grid-layout` directly.
+- For embedding ChartKit-backed chart widgets inside a DashKit dashboard, DashKit is the shell; it still relies on [`@gravity-ui/chartkit`](https://github.com/gravity-ui/chartkit) to render the actual charts.
+
+### Common pitfalls
+
+- **Hallucinated component `<Dashboard>`** — the export is `<DashKit>` (the drag-and-drop shell is `<DashKitDnDWrapper>` wrapping `<DashKit>` + `<ActionPanel>`).
+- **Mutating `config` instead of using helpers** — use the static `DashKit.setItem({...})` / `DashKit.removeItem({...})` helpers to add/change/remove items so layout and ids stay consistent.
+- **Forgetting `DashKit.setSettings` / `DashKit.registerPlugins`** — the component must be configured (language, grid settings, plugin registration) before it is rendered, or widgets show nothing.
+- **Confusing the two param props** — `defaultGlobalParams` (dashboard-level defaults) vs `globalParams` (URL-overridable globals); both flow into the params generation queue consumed by ChartKit.
+- **Calling `onChange` manually with the `change` event** — when you `event.preventDefault()` in the experimental `change` handler, DashKit keeps the visual state internally; re-setting `config.layout` from props resets that baseline.
+
+## Install
+
+```bash
+npm i @gravity-ui/dashkit @gravity-ui/uikit
+```
+
+## Usage
+
+### DashKit configuration
+
+Before using `DashKit` as a react component, it must be configured.
+
+- set language
+
+  ```js
+  import {configure, Lang} from '@gravity-ui/uikit';
+
+  configure({lang: Lang.En});
+  ```
+
+- DashKit.setSettings
+
+  Used for global DashKit settings (such as margins between widgets, default widget sizes and widget overlay menu)
+
+  ```js
+  import {DashKit} from '@gravity-ui/dashkit';
+
+  DashKit.setSettings({
+    gridLayout: {margin: [8, 8]},
+    isMobile: true,
+    // menu: [] as Array<MenuItem>,
+  });
+  ```
+
+- DashKit.registerPlugins
+
+  Registering and configuring plugins
+
+  ```js
+  import {DashKit} from '@gravity-ui/dashkit';
+  import {pluginTitle, pluginText} from '@gravity-ui/dashkit';
+
+  DashKit.registerPlugins(
+    pluginTitle,
+    pluginText.setSettings({
+      apiHandler({text}) {
+        return api.getMarkdown(text);
+      },
+    }),
+  );
+
+  DashKit.registerPlugins({
+    type: 'custom',
+    defaultLayout: {
+      w: 10,
+      h: 8,
+    },
+    renderer: function CustomPlugin() {
+      return <div>Custom widget with custom controls</div>;
+    },
+  });
+  ```
+
+### Config
+
+```ts
+export interface Config {
+  salt: string; // to form a unique id
+  counter: number; // to form a unique id, only increases
+  items: ConfigItem[]; //  initial widget states
+  layout: ConfigLayout[]; // widget position on the grid https://github.com/react-grid-layout
+  aliases: ConfigAliases; // aliases for parameters see #Params
+  connections: ConfigConnection[]; // links between widgets see #Params
+}
+```
+
+Config example:
+
+```ts
+import {DashKitProps} from '@gravity-ui/dashkit';
+
+const config: DashKitProps['config'] = {
+  salt: '0.46703554571365613',
+  counter: 4,
+  items: [
+    {
+      id: 'tT',
+      data: {
+        size: 'm',
+        text: 'Caption',
+        showInTOC: true,
+      },
+      type: 'title',
+      namespace: 'default',
+      orderId: 1,
+    },
+    {
+      id: 'Ea',
+      data: {
+        text: 'mode _editActive',
+        _editActive: true,
+      },
+      type: 'text',
+      namespace: 'default',
+    },
+    {
+      id: 'zR',
+      data: {
+        text: '### Text',
+      },
+      type: 'text',
+      namespace: 'default',
+      orderId: 0,
+    },
+    {
+      id: 'Dk',
+      data: {
+        foo: 'bar',
+      },
+      type: 'custom',
+      namespace: 'default',
+      orderId: 5,
+    },
+  ],
+  layout: [
+    {
+      h: 2,
+      i: 'tT',
+      w: 36,
+      x: 0,
+      y: 0,
+    },
+    {
+      h: 6,
+      i: 'Ea',
+      w: 12,
+      x: 0,
+      y: 2,
+    },
+    {
+      h: 6,
+      i: 'zR',
+      w: 12,
+      x: 12,
+      y: 2,
+    },
+    {
+      h: 4,
+      i: 'Dk',
+      w: 8,
+      x: 0,
+      y: 8,
+    },
+  ],
+  aliases: {},
+  connections: [],
+};
+```
+
+Add a new item to the config:
+
+```ts
+const newLayout = updateLayout: [
+  {
+    h: 6,
+    i: 'Ea',
+    w: 12,
+    x: 0,
+    y: 6,
+  },
+  {
+    h: 4,
+    i: 'Dk',
+    w: 8,
+    x: 0,
+    y: 12,
+  },
+];
+
+const newConfig = DashKit.setItem({
+  item: {
+    data: {
+      text: `Some text`,
+    },
+    namespace: 'default',
+    type: 'text',
+    // Optional. If new item needed to be inserted in current layout with predefined dimensions
+    layout: { // Current item inseterted before 'Ea'
+      h: 6,
+      w: 12,
+      x: 0,
+      y: 2,
+    },,
+  },
+  config: config,
+  options: {
+    // Optional. New layout values for existing items when new element is dropped from ActionPanel
+    updateLayout: newLayout,
+  },
+});
+```
+
+Change an existing item in the config:
+
+```ts
+const newConfig = DashKit.setItem({
+  item: {
+    id: 'tT', // item.id
+    data: {
+      size: 'm',
+      text: `New caption`,
+    },
+    namespace: 'default',
+    type: 'title',
+  },
+  config: config,
+});
+```
+
+Delete an item from the config:
+
+```ts
+import {DashKitProps} from '@gravity-ui/dashkit';
+
+const oldItemsStateAndParams: DashKitProps['itemsStateAndParams'] = {};
+
+const {config: newConfig, itemsStateAndParams} = DashKit.removeItem({
+  id: 'tT', // item.id
+  config: config,
+  itemsStateAndParams: this.state.itemsStateAndParams,
+});
+```
+
+### Params
+
+```ts
+type Params = Record<string, string | string[]>;
+```
+
+`DashKit` generates parameters according to the default parameters for widgets, links, and aliases. These parameters are required for the [ChartKit](https://github.com/gravity-ui/chartkit) library.
+
+Generation order:
+
+1. `defaultGlobalParams`
+2. Default widget parameters `item.default`
+3. `globalParams`
+4. Parameters from [itemsStateAndParams](#itemsStateAndParams) according to the queue.
+
+### itemsStateAndParams
+
+Object that stores widget parameters and states as well as a parameter change queue.
+It has a `__meta__` field for storing queue and meta information.
+
+```ts
+interface StateAndParamsMeta = {
+    __meta__: {
+        queue: {id: string}[]; // queue
+        version: number; // current version itemsStateAndParams
+    };
+}
+```
+
+And also widget states and parameters:
+
+```ts
+interface ItemsStateAndParamsBase {
+  [itemId: string]: {
+    state?: Record<string, any>;
+    params?: Params;
+  };
+}
+```
+
+```ts
+type ItemsStateAndParams = StateAndParamsMeta & ItemsStateAndParamsBase;
+```
+
+### Experimental DashKit events
+
+> Experimental: this API can change in minor releases.
+
+`DashKit` exposes an experimental instance event API. Use a component ref and subscribe with `dashkitRef.current?.on(eventName, handler)`. The method returns an unsubscribe callback.
+
+The first supported event is `change`. It is emitted when the layout changes, before `onChange` is called. The handler can read the full next and previous layouts, read layout patches, or call `preventDefault()` to stop the default `onChange` call.
+
+```tsx
+import React from 'react';
+import {DashKit} from '@gravity-ui/dashkit';
+import type {DashKitChangeEvent} from '@gravity-ui/dashkit';
+
+function Dashboard() {
+  const dashkitRef = React.useRef<DashKit>(null);
+
+  React.useEffect(() => {
+    const unsubscribe = dashkitRef.current?.on('change', (event: DashKitChangeEvent) => {
+      console.log(event.patches);
+
+      if (event.patches.length > 0) {
+        event.preventDefault();
+      }
+    });
+
+    return () => unsubscribe?.();
+  }, []);
+
+  return <DashKit ref={dashkitRef} config={config} editMode={true} onChange={onChange} />;
+}
+```
+
+```ts
+type DashKitLayoutPatch = Pick<ConfigLayout, 'i'> &
+  Partial<Pick<ConfigLayout, 'x' | 'y' | 'w' | 'h' | 'parent'>>;
+
+type DashKitChangeEvent = {
+  patches: DashKitLayoutPatch[];
+  layout: ConfigLayout[];
+  previousLayout: ConfigLayout[];
+  preventDefault: () => void;
+  readonly defaultPrevented: boolean;
+};
+```
+
+#### Event-driven layout updates
+
+If you use `preventDefault()` in the `change` event handler, you can now handle layout updates without re-initializing the config prop. DashKit maintains an internal baseline and computes patches incrementally:
+
+```tsx
+function Dashboard() {
+  const [config, setConfig] = useState(initialConfig);
+  const dashkitRef = useRef<DashKit>(null);
+
+  useEffect(() => {
+    const unsubscribe = dashkitRef.current?.on('change', (event) => {
+      event.preventDefault(); // Don't call onChange
+
+      // Send only the incremental patches to your backend
+      sendPatches(event.patches);
+
+      // No need to call setConfig({ ...config, layout: event.layout })
+      // DashKit maintains the visual state internally
+    });
+
+    return unsubscribe;
+  }, []);
+
+  return <DashKit ref={dashkitRef} config={config} editMode onChange={() => {}} />;
+}
+```
+
+**Important:** If you later update `config.layout` from props (e.g., from server sync), DashKit will reset its internal baseline to match the new prop. This ensures compatibility with both event-driven and controlled workflows.
+
+### Menu
+
+You can specify custom DashKit widget overlay menu in edit mode
+
+```ts
+type MenuItem = {
+  id: string; // uniq id
+  title?: string; // string title
+  icon?: ReactNode; // node of icon
+  iconSize?: number | string; // icon size in px as number or as string with units
+  handler?: (item: ConfigItem) => void; // custom item action handler
+  visible?: (item: ConfigItem) => boolean; // optional visibility handler for filtering menu items
+  className?: string; // custom class property
+};
+
+// use array of menu items in settings
+<Dashkit overlayMenuItems={[] as Array<MenuItem> | null} />
+
+[deprecated]
+// overlayMenuItems property has greater priority over setSettings menu
+DashKit.setSettings({menu: [] as Array<MenuItem>});
+```
+
+### Draggable items from ActionPanel
+
+#### DashKitDnDWrapper
+
+```ts
+type DraggedOverItem = {
+  h: number;
+  w: number;
+  type: string;
+  parent: string;
+  i?: number;
+};
+
+interface DashKitDnDWrapperProps {
+  dragImageSrc?: string;
+  onDragStart?: (dragProps: ItemDragProps) => void;
+  onDragEnd?: () => void;
+  onDropDragOver?: (
+    draggedItem: DraggedOverItem,
+    sharedItem: DraggedOverItem | null,
+  ) => void | boolean;
+}
+```
+
+- **dragImageSrc**: Drag image preview, by default used transparent 1px png base64
+- **onDragStart**: Callback called when element is dragged from ActionPanel
+- **onDragEnd**: Callback called when element dropped or drag canceled
+
+```ts
+type ItemDragProps = {
+  type: string; // Plugin type
+  layout?: {
+    // Optional. Layout item size for preview and init
+    w?: number;
+    h?: number;
+  };
+  extra?: any; // Custom user context
+};
+```
+
+```ts
+type ItemDropProps = {
+  commit: () => void; // Callback should be called after all config operations are made
+  dragProps: ItemDragProps; // Item drag props
+  itemLayout: ConfigLayout; // Calculated item layout dimensions
+  newLayout: ConfigLayout[]; // New layout after element is dropped
+};
+```
+
+#### Example:
+
+```jsx
+const overlayMenuItems = [
+  {
+    id: 'chart',
+    icon: <Icon data={ChartColumn} />,
+    title: 'Chart',
+    qa: 'chart',
+    dragProps: { // ItemDragProps
+        type: 'custom', // Registered plugin type
+    },
+  }
+]
+
+const onDrop = (dropProps: ItemDropProps) => {
+  // ... add element to your config
+  dropProps.commit();
+}
+
+<DashKitDnDWrapper>
+  <DashKit editMode={true} config={config} onChange={onChange} onDrop={onDrop} />
+  <ActionPanel items={overlayMenuItems} />
+</DashKitDnDWrapper>
+```
+
+### CSS API
+
+| Name                                           | Description           |
+| :--------------------------------------------- | :-------------------- |
+| Action panel variables                         |                       |
+| `--dashkit-action-panel-color`                 | Background color      |
+| `--dashkit-action-panel-border-color`          | Border color          |
+| `--dashkit-action-panel-border-radius`         | Border radius         |
+| Action panel item variables                    |                       |
+| `--dashkit-action-panel-item-color`            | Backgroud color       |
+| `--dashkit-action-panel-item-text-color`       | Text color            |
+| `--dashkit-action-panel-item-color-hover`      | Hover backgroud color |
+| `--dashkit-action-panel-item-text-color-hover` | Hover text color      |
+| Overlay variables                              |                       |
+| `--dashkit-overlay-border-color`               | Border color          |
+| `--dashkit-overlay-color`                      | Background color      |
+| `--dashkit-overlay-opacity`                    | Opacity               |
+| Grid item variables                            |                       |
+| `--dashkit-grid-item-edit-opacity`             | Opacity               |
+| `--dashkit-grid-item-border-radius`            | Border radius         |
+| Placeholder variables                          |                       |
+| `--dashkit-placeholder-color`                  | Background color      |
+| `--dashkit-placeholder-opacity`                | Opacity               |
+
+#### Usage example
+
+```css
+.custom-theme-wrapper {
+  --dashkit-grid-item-edit-opacit: 1;
+  --dashkit-overlay-color: var(--g-color-base-float);
+  --dashkit-overlay-border-color: var(--g-color-base-float);
+  --dashkit-overlay-opacity: 0.5;
+
+  --dashkit-action-panel-border-color: var(--g-color-line-info);
+  --dashkit-action-panel-color: var(--g-color-base-float-accent);
+  --dashkit-action-panel-border-radius: var(--g-border-radius-xxl);
+}
+```
+
+```tsx
+// ....
+
+const CustomThemeWrapper = (props: {
+  dashkitProps: DashkitProps;
+  actionPanelProps: ActionPanelProps;
+}) => {
+  return (
+    <div className="custom-theme-wrapper">
+      <Dashkit {...props.dashkitProps} />
+      <ActionPanel {...props.actionPanelProps} />
+    </div>
+  );
+};
+```

package/build/esm/components/DashKit/DashKit.d.ts

@@ -1,6 +1,6 @@
 import React from 'react';
 import type { Config, ConfigItem, ConfigLayout, GlobalParams, ItemDropProps, ItemsStateAndParams } from "../../shared/index.js";
-import type { AddNewItemOptions, ContextProps, DashKitGroup, ItemManipulationCallback, MenuItem, Plugin, SetConfigItem, Settings, SettingsProps } from "../../typings/index.js";
+import type { AddNewItemOptions, ContextProps, DashKitEventHandler, DashKitEventMap, DashKitEventName, DashKitGroup, ItemManipulationCallback, MenuItem, Plugin, SetConfigItem, Settings, SettingsProps } from "../../typings/index.js";
 import GridLayout from "../GridLayout/GridLayout.js";
 import type { OverlayControlItem, PreparedCopyItemOptions } from "../OverlayControls/OverlayControls.js";
 interface DashKitGeneralProps {
@@ -72,11 +72,21 @@ export declare class DashKit extends React.PureComponent<DashKitInnerProps> {
         groups?: DashKitGroup[];
     }): ConfigLayout[];
     metaRef: React.RefObject<GridLayout | null>;
+    private _handlers;
     render(): React.JSX.Element;
     getItemsMeta(): Promise<any>[];
     reloadItems(options?: {
         targetIds?: string[];
         force?: boolean;
     }): void;
+    /**
+     * @experimental This API can change in minor releases.
+     * @param eventName Event name.
+     * @param handler Event handler.
+     * @returns Unsubscribe callback.
+     */
+    on<T extends DashKitEventName>(eventName: T, handler: DashKitEventHandler<T>): () => void;
+    [_emitSymbol]: <T extends DashKitEventName>(eventName: T, event: DashKitEventMap[T]) => void;
+    private _off;
 }
 export {};

package/build/esm/components/DashKit/DashKit.js

@@ -1,3 +1,4 @@
+var _a;
 import React from 'react';
 import noop from "lodash/noop.js";
 import pick from "lodash/pick.js";
@@ -7,6 +8,12 @@ import { RegisterManager, UpdateManager, reflowLayout } from "../../utils/index.
 import { DashKitDnDWrapper } from "../DashKitDnDWrapper/DashKitDnDWrapper.js";
 import DashKitView from "../DashKitView/DashKitView.js";
 const registerManager = new RegisterManager();
+/**
+ * @internal Not part of the public API. Do not use in production code.
+ * Module-scoped symbol — not accessible to external consumers holding a ref,
+ * preventing synthetic event injection via instance._emit.
+ */
+export const _emitSymbol = Symbol('DashKit._emit');
 const getReflowProps = (props) => Object.assign({ compactType: 'vertical', cols: 36 }, pick(props, 'cols', 'maxRows', 'compactType'));
 const getReflowGroupsConfig = (groups = []) => {
     const defaultGridProps = getReflowProps(registerManager.gridLayout);
@@ -25,6 +32,22 @@ export class DashKit extends React.PureComponent {
     constructor() {
         super(...arguments);
         this.metaRef = React.createRef();
+        this._handlers = new Map();
+        this[_a] = (eventName, event) => {
+            const handlers = this._handlers.get(eventName);
+            if (!handlers) {
+                return;
+            }
+            for (const handler of handlers) {
+                try {
+                    handler(event);
+                }
+                catch (e) {
+                    // eslint-disable-next-line no-console
+                    console.error('DashKit: event handler error', e);
+                }
+            }
+        };
     }
     static registerPlugins(...plugins) {
         plugins.forEach((plugin) => {
@@ -50,7 +73,8 @@ export class DashKit extends React.PureComponent {
         }
         else {
             const item = setItem;
-            const layout = Object.assign({}, registerManager.getItem(item.type).defaultLayout);
+            const registerManagerItem = registerManager.getItem(item.type);
+            const layout = Object.assign({}, registerManagerItem.defaultLayout);
             const reflowLayoutOptions = getReflowGroupsConfig(groups);
             const copyItem = Object.assign({}, item);
             if (copyItem.layout) {
@@ -77,21 +101,45 @@ export class DashKit extends React.PureComponent {
         });
     }
     render() {
-        const content = (React.createElement(DashKitView, Object.assign({ registerManager: registerManager, ref: this.metaRef }, this.props)));
+        const content = (React.createElement(DashKitView, Object.assign({ registerManager: registerManager, ref: this.metaRef }, this.props, { emitDashKitEvent: this[_emitSymbol] })));
         if (!this.context && this.props.groups) {
             return React.createElement(DashKitDnDWrapper, null, content);
         }
         return content;
     }
     getItemsMeta() {
-        var _a, _b;
-        return (_b = (_a = this.metaRef.current) === null || _a === void 0 ? void 0 : _a.getItemsMeta()) !== null && _b !== void 0 ? _b : [];
+        var _b, _c;
+        return (_c = (_b = this.metaRef.current) === null || _b === void 0 ? void 0 : _b.getItemsMeta()) !== null && _c !== void 0 ? _c : [];
     }
     reloadItems(options) {
-        var _a;
-        (_a = this.metaRef.current) === null || _a === void 0 ? void 0 : _a.reloadItems(options);
+        var _b;
+        (_b = this.metaRef.current) === null || _b === void 0 ? void 0 : _b.reloadItems(options);
+    }
+    /**
+     * @experimental This API can change in minor releases.
+     * @param eventName Event name.
+     * @param handler Event handler.
+     * @returns Unsubscribe callback.
+     */
+    on(eventName, handler) {
+        var _b;
+        if (!this._handlers.has(eventName)) {
+            this._handlers.set(eventName, new Set());
+        }
+        (_b = this._handlers.get(eventName)) === null || _b === void 0 ? void 0 : _b.add(handler);
+        return () => this._off(eventName, handler);
+    }
+    _off(eventName, handler) {
+        const handlers = this._handlers.get(eventName);
+        if (handlers) {
+            handlers.delete(handler);
+            if (handlers.size === 0) {
+                this._handlers.delete(eventName);
+            }
+        }
     }
 }
+_a = _emitSymbol;
 DashKit.defaultProps = {
     onItemEdit: noop,
     onChange: noop,