@gravity-ui/dashkit 10.3.0 → 10.4.0

package/README.md

@@ -629,5 +629,36 @@ server {
         proxy_redirect off;
     }
 }
-
 ```
+
+## License
+
+Distributed under the MIT License. See [LICENSE](LICENSE) for details.
+
+## 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.
+
+## Documentation for AI agents
+
+Agent-readable documentation for the installed version is located in `node_modules/@gravity-ui/dashkit/build/docs/INDEX.md`.

package/build/cjs/package.json

@@ -1 +1 @@
-{"version":"10.3.0","type":"commonjs","sideEffects":["*.scss","*.css"]}
+{"version":"10.4.0","type":"commonjs","sideEffects":["*.scss","*.css"]}

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/package.json

@@ -1 +1 @@
-{"version":"10.3.0","type":"module","sideEffects":["*.scss","*.css"]}
+{"version":"10.4.0","type":"module","sideEffects":["*.scss","*.css"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gravity-ui/dashkit",
-  "version": "10.3.0",
+  "version": "10.4.0",
   "description": "Library for rendering dashboard grid layout",
   "license": "MIT",
   "repository": {
@@ -63,6 +63,7 @@
     "test": "jest",
     "clean": "gulp clean",
     "build": "gulp",
+    "build:docs": "gulp copy-docs",
     "build:watch": "gulp watch",
     "start": "storybook dev -p 7120",
     "typecheck": "tsc --noEmit",
@@ -91,6 +92,7 @@
     "@gravity-ui/gulp-utils": "^1.0.2",
     "@gravity-ui/icons": "^2.13.0",
     "@gravity-ui/prettier-config": "^1.1.0",
+    "@gravity-ui/readme-validator": "^1.3.0",
     "@gravity-ui/stylelint-config": "^4.0.1",
     "@gravity-ui/tsconfig": "^1.0.0",
     "@gravity-ui/uikit": "^7.2.0",