@gravity-ui/page-constructor 8.15.0 → 8.17.0

package/build/docs/blocks/Tabs.md

@@ -0,0 +1,92 @@
+# Tabs
+
+Renders a set of tab buttons that switch between rich content panels. Each tab panel pairs a content column (title, text, lists, buttons, links) with an optional media column (image, video, YouTube, iframe, DataLens), with control over column order, sizing, and border treatment.
+
+## Block type
+
+`type: 'tabs-block'`
+
+## When to use
+
+- Grouping several feature/explainer panels under a single heading where only one is visible at a time.
+- Product or capability overviews that share the same layout but differ in text and media.
+- Sections needing media + content panels with light/dark artwork variants per tab.
+
+## Example
+
+```json
+{
+  "type": "tabs-block",
+  "title": {"text": "Lorem ipsum"},
+  "description": "**Ut enim ad minim veniam** [quis nostrud](https://example.com) exercitation.",
+  "direction": "media-content",
+  "centered": false,
+  "contentSize": "s",
+  "tabsColSizes": {"all": 12, "md": 12},
+  "items": [
+    {
+      "tabName": "Dolor sit amet",
+      "title": "Dolor sit amet",
+      "text": "**Ut enim ad minim veniam** exercitation.",
+      "buttons": [{"text": "Button", "theme": "action", "url": "https://example.com"}],
+      "media": {
+        "light": {"image": "/images/panel-light.png"},
+        "dark": {"image": "/images/panel-dark.png"}
+      },
+      "border": "shadow"
+    },
+    {
+      "tabName": "Lorem ipsum",
+      "title": "Lorem ipsum",
+      "caption": "Dolor sit amet",
+      "text": "* Ut enim ad minim veniam",
+      "links": [{"url": "https://example.com", "text": "Link", "theme": "normal", "arrow": true}],
+      "media": {"light": {"youtube": "https://youtu.be/0Qd3T6skprA"}},
+      "border": "shadow"
+    }
+  ]
+}
+```
+
+## Properties
+
+| Property           | Type                                                            | Default           | Description                                     |
+| ------------------ | --------------------------------------------------------------- | ----------------- | ----------------------------------------------- |
+| `items` _required_ | `TabsItem[]`                                                    | —                 | Array of tab panels. See below.                 |
+| `title`            | `string \| TitleProps`                                          | —                 | Block heading (string or `TitleProps`).         |
+| `description`      | `string`                                                        | —                 | YFM subtitle rendered under the title.          |
+| `direction`        | `'media-content' \| 'content-media'`                            | `'media-content'` | Column order within each tab panel on desktop.  |
+| `centered`         | `boolean`                                                       | —                 | Centers the title and the tab buttons row.      |
+| `contentSize`      | `'s' \| 'm' \| 'l' \| 'xl'`                                     | `'s'`             | Content/media scale used inside each tab panel. |
+| `tabsColSizes`     | `{sm?, md?, lg?, xl?, all?}` (values are column numbers `1–12`) | —                 | Grid column sizes for the tab buttons row.      |
+| `animated`         | `boolean`                                                       | —                 | Enables an entrance/scroll animation.           |
+
+### `items[]` (`TabsItem`)
+
+| Property             | Type                           | Default | Description                                                                                                                                    |
+| -------------------- | ------------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tabName` _required_ | `string`                       | —       | Label displayed on the tab button; also used as the tab identifier.                                                                            |
+| `title`              | `string \| TitleProps`         | —       | Panel heading.                                                                                                                                 |
+| `text`               | `string`                       | —       | YFM body text.                                                                                                                                 |
+| `additionalInfo`     | `string`                       | —       | YFM supplementary text below the body.                                                                                                         |
+| `links`              | `LinkProps[]`                  | —       | Inline text links.                                                                                                                             |
+| `buttons`            | `ButtonBlock[]`                | —       | CTA buttons.                                                                                                                                   |
+| `list`               | `ContentItem[]`                | —       | Bullet-style list with optional icons per item (`icon` or `gravityIcon`, plus `title`/`text`).                                                 |
+| `controlPosition`    | `'default' \| 'bottom'`        | —       | Vertical placement of buttons/links.                                                                                                           |
+| `media`              | `MediaProps \| {light, dark}`  | —       | Media column: `image` (single or array → slider), `video`, `youtube`, `videoIframe`, `iframe`, `dataLens`, plus `previewImg`, `autoplay`, etc. |
+| `caption`            | `string`                       | —       | Plain-text caption rendered with the media.                                                                                                    |
+| `image` _deprecated_ | `ImageProps \| {light, dark}`  | —       | Legacy single image; prefer `media`.                                                                                                           |
+| `link` _deprecated_  | `LinkProps`                    | —       | Legacy single link; prefer `links`.                                                                                                            |
+| `border`             | `'shadow' \| 'line' \| 'none'` | —       | Border/shadow treatment around the tab panel.                                                                                                  |
+
+### Common properties
+
+Inherits: `anchor`, `visible`, `indent` (`{top?, bottom?}`), `qa`, `className`, `animated`, `when`, `context`. See the root README for details.
+
+## Themed values
+
+Each tab's `media` (and the legacy `image`) accepts either a plain value or a `{light, dark}` object resolved against the active runtime theme.
+
+## Storybook
+
+[Tabs](https://preview.gravity-ui.com/page-constructor/?path=/docs/blocks-tabs--docs)

package/build/docs/guides/data-preparation-ru.md

@@ -0,0 +1,257 @@
+# Подготовка данных
+
+Документацию по серверным утилитам для преобразования контента, включая конвертацию Yandex Flavored Markdown (YFM) в HTML и обработку текста. Основные возможности:
+
+- **`fullTransform`**: Преобразует контент в формате YFM в HTML с настраиваемыми параметрами.
+- **Утилиты**: `typografToText`, `typografToHTML` и `yfmTransformer` для обработки текста в пользовательских компонентах.
+- **`createItemsParser`**: Утилита для преобразования определённых полей в блоках, поддерживающая вложенные поля и массивы.
+
+### Серверные утилиты
+
+Пакет включает набор серверных утилит для преобразования контента.
+
+```ts
+const {fullTransform} = require('@gravity-ui/page-constructor/server');
+
+const {html} = fullTransform(content, {
+  lang,
+  extractTitle: true,
+  allowHTML: true,
+  path: __dirname,
+  plugins,
+});
+```
+
+Для преобразования Yandex Flavored Markdown в HTML используется пакет `diplodoc/transfrom`, который входит в peer-зависимости.
+
+Эти утилиты можно также использовать в кастомных компонентах или других частях проекта.
+
+```ts
+const {
+  typografToText,
+  typografToHTML,
+  yfmTransformer,
+} = require('@gravity-ui/page-constructor/server');
+
+const post = {
+  title: typografToText(title, lang),
+  content: typografToHTML(content, lang),
+  description: yfmTransformer(lang, description, {plugins}),
+};
+```
+
+Список других доступных утилит можно найти в [этом разделе](https://github.com/gravity-ui/page-constructor/tree/main/src/text-transform).
+
+## Документация к `createItemsParser`
+
+Метод `createItemsParser` — это утилита, для создания парсеров блоков. Он помогает с преобразованием определённых полей с использованием трансформера. Метод имеет опции, позволяющие указать, какие поля нужно преобразовать и как обрабатывать вложенные поля.
+
+### Сигнатура метода
+
+```typescript
+export const createItemsParser = (fields: string[]) => (transformer: Transformer, items: Item[]) => Item[];
+```
+
+### Параметры
+
+- **fields**: Массив строк, указывающих поля для преобразования. Эти поля могут быть вложенными, используя точечную нотацию (например, `'nested.field'`).
+- **transformer**: Функция, которая принимает строку и возвращает преобразованную строку. Эта функция будет применена к указанным полям.
+- **items**: Массив элементов для парсинга и преобразования. Каждый элемент может быть строкой или сложным объектом.
+
+### Возвращаемое значение
+
+- Возвращает массив элементов с преобразованными указанными полями с помощью функции `transformer`.
+
+## Примеры использования
+
+### Пример 1: Базовое использование
+
+В этом примере преобразуются поля `text` и `additionalInfo` каждого элемента в массиве `items` с использованием `yfmTransformer`.
+
+```typescript
+const config = {
+  fields: ['items'],
+  transformer: yfmTransformer,
+  parser: createItemsParser(['text', 'additionalInfo']),
+};
+```
+
+**Input:**
+
+```json
+[
+  {"text": "Hello, world!", "additionalInfo": "This is a test."},
+  {"text": "Another item", "additionalInfo": "More info here."}
+]
+```
+
+**Output:**
+
+```json
+[
+  {"text": "Transformed: Hello, world!", "additionalInfo": "Transformed: This is a test."},
+  {"text": "Transformed: Another item", "additionalInfo": "Transformed: More info here."}
+]
+```
+
+### Пример 2: Вложенные поля
+
+В этом примере преобразуется вложенное поле `list.text` внутри каждого элемента.
+
+```typescript
+const config = {
+  fields: ['items'],
+  transformer: yfmTransformer,
+  parser: createItemsParser(['list.text']),
+  renderInline: true,
+};
+```
+
+**Input:**
+
+```json
+[{"list": {"text": "Вложенный текст 1"}}, {"list": {"text": "Вложенный текст 2"}}]
+```
+
+**Output:**
+
+```json
+[
+  {"list": {"text": "Transformed: Вложенный текст 1"}},
+  {"list": {"text": "Transformed: Вложенный текст 2"}}
+]
+```
+
+### Пример 3: Смешанные типы данных
+
+В этом примере массив `items` содержит как строки, так и сложные объекты. Метод `createItemsParser` корректно обрабатывает оба типа данных.
+
+```typescript
+const config = {
+  fields: ['items'],
+  transformer: yfmTransformer,
+  parser: createItemsParser(['text', 'list.text']),
+};
+```
+
+**Input:**
+
+```json
+["Простая строка", {"text": "Текст объекта", "list": {"text": "Вложенный текст"}}]
+```
+
+**Output:**
+
+```json
+[
+  "Transformed: Простая строка",
+  {"text": "Transformed: Текст объекта", "list": {"text": "Transformed: Вложенный текст"}}
+]
+```
+
+## Примечания
+
+- Если поле не найдено в элементе, оно будет пропущено.
+- Если указано вложенное поле, но родительский объект не является объектом или не является массивом, преобразование для этого поля будет пропущено.
+- Метод не изменяет исходные элементы, а возвращает новый массив с преобразованными данными.
+
+### Обработка вложенных массивов
+
+Если вложенное поле является массивом, метод `createItemsParser` будет итерировать по каждому элементу массива и применять трансформер к указанному полю. Это особенно полезно при работе с массивами объектов, содержащими поля, которые требуют преобразования.
+
+### Пример 4: Вложенное поле как массив
+
+В этом примере преобразуется поле `text` внутри каждого объекта в массиве `list`, который является вложенным полем элементов `items`.
+
+```typescript
+const config = {
+  fields: ['items'],
+  transformer: yfmTransformer,
+  parser: createItemsParser(['list.text']),
+};
+```
+
+**Input:**
+
+```json
+[
+  {
+    "list": [{"text": "Вложенный текст 1"}, {"text": "Вложенный текст 2"}]
+  },
+  {
+    "list": [{"text": "Вложенный текст 3"}, {"text": "Вложенный текст 4"}]
+  }
+]
+```
+
+**Output:**
+
+```json
+[
+  {
+    "list": [{"text": "Transformed: Вложенный текст 1"}, {"text": "Transformed: Вложенный текст 2"}]
+  },
+  {
+    "list": [{"text": "Transformed: Вложенный текст 3"}, {"text": "Transformed: Вложенный текст 4"}]
+  }
+]
+```
+
+## Полный пример со всеми случаями
+
+Вот комплексный пример, включающий все возможные случаи: обычные поля, вложенные объекты и вложенные массивы.
+
+```typescript
+const config = {
+  fields: ['items'],
+  transformer: yfmTransformer,
+  parser: createItemsParser(['text', 'list.text', 'details.info']),
+};
+
+const transformedItems = config.parser(config.transformer, items);
+```
+
+**Input:**
+
+```json
+[
+  {
+    "text": "Обычный текст",
+    "list": [{"text": "Вложенный текст 1"}, {"text": "Вложенный текст 2"}],
+    "details": {
+      "info": "Вложенная информация"
+    }
+  },
+  {
+    "text": "Другой обычный текст",
+    "list": {"text": "Вложенный текст 3"},
+    "details": {
+      "info": "Другая вложенная информация"
+    }
+  }
+]
+```
+
+**Output:**
+
+```json
+[
+  {
+    "text": "Transformed: Обычный текст",
+    "list": [
+      {"text": "Transformed: Вложенный текст 1"},
+      {"text": "Transformed: Вложенный текст 2"}
+    ],
+    "details": {
+      "info": "Transformed: Вложенная информация"
+    }
+  },
+  {
+    "text": "Transformed: Другой обычный текст",
+    "list": {"text": "Transformed: Вложенный текст 3"},
+    "details": {
+      "info": "Transformed: Другая вложенная информация"
+    }
+  }
+]
+```

package/build/docs/guides/data-preparation.md

@@ -0,0 +1,259 @@
+# Data preparation
+
+This chapter provides documentaion for server utilities for transforming content, including Yandex Flavored Markdown (YFM) to HTML conversion and text processing. Key features include:
+
+- fullTransform: Converts YFM content into HTML with customizable options.
+
+- Utilities: Includes typografToText, typografToHTML, and yfmTransformer for text processing in custom components.
+
+- createItemsParser: A flexible utility for transforming specific fields in complex data structures, supporting nested fields and arrays.
+
+## Server utils
+
+The package provides a set of server utilities for transforming your content.
+
+```ts
+const {fullTransform} = require('@gravity-ui/page-constructor/server');
+
+const {html} = fullTransform(content, {
+  lang,
+  extractTitle: true,
+  allowHTML: true,
+  path: __dirname,
+  plugins,
+});
+```
+
+Under the hood, a package is used to transform Yandex Flavored Markdown into HTML - `diplodoc/transfrom`, so it is also in peer dependencies
+
+You can also use useful utilities in the places you need, for example in your custom components
+
+```ts
+const {
+  typografToText,
+  typografToHTML,
+  yfmTransformer,
+} = require('@gravity-ui/page-constructor/server');
+
+const post = {
+  title: typografToText(title, lang),
+  content: typografToHTML(content, lang),
+  description: yfmTransformer(lang, description, {plugins}),
+};
+```
+
+You can find more utilities in this [section](https://github.com/gravity-ui/page-constructor/tree/main/src/text-transform)
+
+## `createItemsParser` Method Documentation
+
+The `createItemsParser` method is a utility function designed to parse and transform items in a flexible and customizable way. It is particularly useful when dealing with complex data structures that require specific fields to be transformed using a provided transformer function. This method is highly configurable, allowing you to specify which fields to transform and how to handle nested fields.
+
+### Method Signature
+
+```typescript
+export const createItemsParser = (fields: string[]) => (transformer: Transformer, items: Item[]) => Item[];
+```
+
+### Parameters
+
+- **fields**: An array of strings specifying the fields to be transformed. These fields can be nested, using dot notation (e.g., `'nested.field'`).
+- **transformer**: A function that takes a string and returns a transformed string. This function will be applied to the specified fields.
+- **items**: An array of items to be parsed and transformed. Each item can be a string or a complex object.
+
+### Return Value
+
+- Returns an array of items with the specified fields transformed by the `transformer` function.
+
+## Usage Examples
+
+### Example 1: Basic Usage
+
+In this example, we want to transform the `text` and `additionalInfo` fields of each item in the `items` array using the `yfmTransformer`.
+
+```typescript
+const config = {
+  fields: ['items'],
+  transformer: yfmTransformer,
+  parser: createItemsParser(['text', 'additionalInfo']),
+};
+```
+
+**Input:**
+
+```json
+[
+  {"text": "Hello, world!", "additionalInfo": "This is a test."},
+  {"text": "Another item", "additionalInfo": "More info here."}
+]
+```
+
+**Output:**
+
+```json
+[
+  {"text": "Transformed: Hello, world!", "additionalInfo": "Transformed: This is a test."},
+  {"text": "Transformed: Another item", "additionalInfo": "Transformed: More info here."}
+]
+```
+
+### Example 2: Nested Fields
+
+In this example, we want to transform a nested field `list.text` within each item.
+
+```typescript
+const config = {
+  fields: ['items'],
+  transformer: yfmTransformer,
+  parser: createItemsParser(['list.text']),
+  renderInline: true,
+};
+```
+
+**Input:**
+
+```json
+[{"list": {"text": "Nested text 1"}}, {"list": {"text": "Nested text 2"}}]
+```
+
+**Output:**
+
+```json
+[{"list": {"text": "Transformed: Nested text 1"}}, {"list": {"text": "Transformed: Nested text 2"}}]
+```
+
+### Example 3: Mixed Data Types
+
+In this example, the `items` array contains a mix of strings and complex objects. The `createItemsParser` will handle both types appropriately.
+
+```typescript
+const config = {
+  fields: ['items'],
+  transformer: yfmTransformer,
+  parser: createItemsParser(['text', 'list.text']),
+};
+```
+
+**Input:**
+
+```json
+["Simple string", {"text": "Object text", "list": {"text": "Nested text"}}]
+```
+
+**Output:**
+
+```json
+[
+  "Transformed: Simple string",
+  {"text": "Transformed: Object text", "list": {"text": "Transformed: Nested text"}}
+]
+```
+
+## Key Features
+
+- **Flexible Field Specification**: You can specify both top-level and nested fields using dot notation.
+- **Mixed Data Handling**: The method can handle arrays containing both strings and complex objects.
+- **Custom Transformers**: You can pass any transformer function to apply custom transformations to the specified fields.
+
+## Notes
+
+- If a field is not found in an item, it will be skipped.
+- If a nested field is specified but the parent object is not an object or is an array, the transformation will be skipped for that field.
+- The method does not mutate the original items but returns a new array with the transformed items.
+
+### Handling Nested Arrays
+
+When a nested field is an array, the `createItemsParser` method will iterate over each element in the array and apply the transformer function to the specified subfield. This is particularly useful when dealing with arrays of objects that contain fields requiring transformation.
+
+### Example 4: Nested Field as an Array
+
+In this example, we want to transform the `text` field within each object in the `list` array, which is a nested field of the `items`.
+
+```typescript
+const config = {
+  fields: ['items'],
+  transformer: yfmTransformer,
+  parser: createItemsParser(['list.text']),
+};
+```
+
+**Input:**
+
+```json
+[
+  {
+    "list": [{"text": "Nested text 1"}, {"text": "Nested text 2"}]
+  },
+  {
+    "list": [{"text": "Nested text 3"}, {"text": "Nested text 4"}]
+  }
+]
+```
+
+**Output:**
+
+```json
+[
+  {
+    "list": [{"text": "Transformed: Nested text 1"}, {"text": "Transformed: Nested text 2"}]
+  },
+  {
+    "list": [{"text": "Transformed: Nested text 3"}, {"text": "Transformed: Nested text 4"}]
+  }
+]
+```
+
+## Full Example with All Cases
+
+Here’s a comprehensive example that includes all possible cases: top-level fields, nested objects, and nested arrays.
+
+```typescript
+const config = {
+  fields: ['items'],
+  transformer: yfmTransformer,
+  parser: createItemsParser(['text', 'list.text', 'details.info']),
+};
+
+const transformedItems = config.parser(config.transformer, items);
+```
+
+**Input:**
+
+```json
+[
+  {
+    "text": "Top-level text",
+    "list": [{"text": "Nested text 1"}, {"text": "Nested text 2"}],
+    "details": {
+      "info": "Nested info"
+    }
+  },
+  {
+    "text": "Another top-level text",
+    "list": {"text": "Nested text 3"},
+    "details": {
+      "info": "Another nested info"
+    }
+  }
+]
+```
+
+**Output:**
+
+```json
+[
+  {
+    "text": "Transformed: Top-level text",
+    "list": [{"text": "Transformed: Nested text 1"}, {"text": "Transformed: Nested text 2"}],
+    "details": {
+      "info": "Transformed: Nested info"
+    }
+  },
+  {
+    "text": "Transformed: Another top-level text",
+    "list": {"text": "Transformed: Nested text 3"},
+    "details": {
+      "info": "Transformed: Another nested info"
+    }
+  }
+]
+```

package/build/docs/sub-blocks/BackgroundCard.md

@@ -0,0 +1,63 @@
+# BackgroundCard
+
+A card that renders text content (title, text, links, buttons, or a content list) over a decorative background image or solid color. Useful for promotional cards inside a card layout.
+
+## Sub-block type
+
+`type: 'background-card'`
+
+## Used in
+
+Accepted as a child of: `card-layout-block`, `slider-block`, `slider-old-block`.
+
+## Example
+
+```json
+{
+  "type": "background-card",
+  "title": "Launch your product",
+  "text": "**Ut enim ad minim veniam** [quis nostrud](https://example.com) exercitation ullamco.",
+  "additionalInfo": "Duis aute irure dolor in reprehenderit.",
+  "background": {
+    "light": {"src": "/story-assets/img-bg_nopadding_4-12_light.png", "alt": "Background"},
+    "dark": {"src": "/story-assets/img-bg_nopadding_4-12_dark.png", "alt": "Background"}
+  },
+  "buttons": [
+    {"text": "Get started", "theme": "action", "url": "https://example.com"},
+    {"text": "Learn more", "theme": "outlined", "url": "https://example.com"}
+  ],
+  "theme": "dark"
+}
+```
+
+## Properties
+
+| Property           | Type                                              | Default             | Description                                                                                            |
+| ------------------ | ------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------ |
+| `type` _required_  | `'background-card'`                               | —                   | Sub-block discriminator.                                                                               |
+| `when`             | `string`                                          | —                   | Conditional rendering expression.                                                                      |
+| `title` _required_ | `string \| TitleProps`                            | —                   | Card title (plain string or Title options). |
+| `text` _required_  | `string`                                          | —                   | Body text (YFM supported).                                                                             |
+| `additionalInfo`   | `string`                                          | —                   | Secondary gray text (YFM supported).                                                                   |
+| `size`             | `'s' \| 'm' \| 'l' \| 'xl'`                       | `'s'`               | Content size; controls font sizes.                                                                     |
+| `theme`            | `'default' \| 'dark' \| 'light'`                  | `'default'`         | Card content theme. When not `default`, or when `backgroundColor` is set, the card border is hidden.   |
+| `links`            | `LinkProps[]`                                     | —                   | Array of links.                                          |
+| `buttons`          | `ButtonProps[]`                                   | —                   | Array of buttons.                                      |
+| `list`             | `ContentItem[]`                                   | —                   | Array of icon-content items (each requires `icon` or `gravityIcon`).                                   |
+| `border`           | `'line' \| 'shadow' \| 'none'`                    | —                   | Card border style. Overridden to `'none'` when `backgroundColor` is set or `theme` is not `default`.   |
+| `controlPosition`  | `'content' \| 'footer'`                           | `'content'`         | Position of buttons/links. `'footer'` only applies when `paddingBottom` is unset.                      |
+| `colSizes`         | `{all?, sm?, md?, lg?, xl?}` (each `number` 1–12) | `{all: 12, md: 12}` | Column width per breakpoint.                                                                           |
+| `url`              | `string`                                          | —                   | Wraps the whole card in a link.                                                                        |
+| `urlTitle`         | `string`                                          | —                   | `title` attribute for the card link.                                                                   |
+| `background`       | `ImageObjectProps \| {light, dark}`               | —                   | Decorative background image (themed).                                                                  |
+| `backgroundColor`  | `string`                                          | —                   | Solid background color (CSS value). Hides the border.                                                  |
+| `paddingBottom`    | `'s' \| 'm' \| 'l' \| 'xl'`                       | —                   | Adds bottom padding. When set, `controlPosition: 'footer'` is ignored.                                 |
+| `analyticsEvents`  | `AnalyticsEvent \| AnalyticsEvent[]`              | —                   | Analytics events fired on card interaction.                                                            |
+
+## Themed values
+
+`background` accepts either a plain value or a `{light, dark}` object resolved against the active runtime theme.
+
+## Storybook
+
+[BackgroundCard](https://preview.gravity-ui.com/page-constructor/?path=/docs/components-cards-backgroundcard--docs)