@gravity-ui/page-constructor 8.14.2 → 8.16.0

package/build/docs/blocks/Slider.md

@@ -0,0 +1,89 @@
+# Slider
+
+A carousel block that renders any number of child cards as swipeable slides, with optional title, description, dots, arrows, autoplay, and per-breakpoint slide counts. Built on top of Swiper.
+
+## Block type
+
+`type: 'slider-block'`
+
+## When to use
+
+- You need to display a sequence of cards (basic cards, quote cards, image cards, etc.) in a carousel.
+- You need responsive control over how many slides are visible at each breakpoint.
+- You want autoplay, pagination dots, and navigation arrows.
+
+## Example
+
+```json
+{
+  "type": "slider-block",
+  "title": {"text": "QuoteCards", "url": "https://example.com"},
+  "description": "Lorem ipsum dolor sit amet",
+  "dots": true,
+  "arrows": true,
+  "slidesToShow": 1,
+  "children": [
+    {
+      "type": "quote",
+      "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
+      "image": {
+        "light": "/images/quote-light.png",
+        "dark": "/images/quote-dark.png"
+      },
+      "logo": "/images/company-logo.svg",
+      "author": {
+        "firstName": "Lorem",
+        "secondName": "ipsum",
+        "description": "Lorem ipsum",
+        "avatar": "/story-assets/img_6-12_light.png"
+      }
+    },
+    {
+      "type": "basic-card",
+      "title": "Basic card",
+      "text": "Ut enim ad minim veniam.",
+      "icon": "/story-assets/icon_1_light.svg"
+    }
+  ]
+}
+```
+
+Responsive `slidesToShow`:
+
+```json
+"slidesToShow": {"sm": 1, "md": 2, "lg": 3, "xl": 4}
+```
+
+## Properties
+
+| Property       | Type                                                   | Default | Description                                                                                                                   |
+| -------------- | ------------------------------------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `title`        | `string \| TitleProps`                                 | —       | Block title (plain string or options object).                                                                                 |
+| `description`  | `string` (YFM)                                         | —       | Block description under the title.                                                                                            |
+| `children`     | `Card[]`                                               | —       | Array of child card blocks rendered as slides. Any registered card type is allowed.                                           |
+| `slidesToShow` | `number \| {sm?, md?, lg?, xl?}`                       | —       | Number of slides to show. A number applies to all breakpoints; an object sets per-breakpoint counts (`sm`, `md`, `lg`, `xl`). |
+| `dots`         | `boolean`                                              | `true`  | Show pagination dots.                                                                                                         |
+| `arrows`       | `boolean`                                              | `true`  | Show prev/next navigation arrows.                                                                                             |
+| `arrowSize`    | `number`                                               | —       | Size of the navigation arrows in pixels.                                                                                      |
+| `autoplay`     | `number`                                               | —       | Autoplay interval in milliseconds. When set and positive, dots are hidden from the accessibility tab order.                   |
+| `adaptive`     | `boolean`                                              | —       | Adaptive slide height.                                                                                                        |
+| `randomOrder`  | `boolean`                                              | —       | Shuffle slides on render.                                                                                                     |
+| `type`         | `string`                                               | —       | Logical slider type, used for grouping / loadable sources.                                                                    |
+| `disclaimer`   | `{text *required*, size?}`                             | —       | Disclaimer text under the slider. `size` is one of `'xs' \| 's' \| 'sm' \| 'm' \| 'l'`.                                       |
+| `loadable`     | `{source *required*, params?, minCount? (deprecated)}` | —       | Disabled in the default schema. Used by projects that wire up a custom loadable source for slides.                            |
+
+### Common properties
+
+Inherits: `anchor`, `visible`, `indent`, `qa`, `className`, `animated`, `theme`, `when`, `context`. See root README.
+
+## Notes
+
+`children` accepts any block registered as a "card" in the schema. Common examples include `basic-card`, `quote`, image cards, and other content cards. A slider with a single child automatically renders without dots and arrows.
+
+## Themed values
+
+Child cards may individually use themed values (e.g. `{light, dark}` images); the block itself does not theme its scalar properties.
+
+## Storybook
+
+[Slider](https://preview.gravity-ui.com/page-constructor/?path=/docs/blocks-slider--docs)

package/build/docs/blocks/SliderOld.md

@@ -0,0 +1,63 @@
+# SliderOld
+
+> ⚠️ **Deprecated.** `slider-old-block` is deprecated and will be removed in a future major release. Use [`slider-block`](./Slider.md) (the `Slider` block, built on Swiper) for new and existing pages.
+
+The legacy carousel block, built on top of `react-slick`. Renders child cards as slides with optional title, description, dots, arrows, autoplay, and per-breakpoint slide counts.
+
+## Block type
+
+`type: 'slider-old-block'`
+
+## When to use
+
+- Only for backward compatibility with existing JSON that already uses `slider-old-block`.
+- For anything new, use `slider-block`.
+
+## Example
+
+```json
+{
+  "type": "slider-old-block",
+  "title": {"text": "Slider", "url": "https://example.com"},
+  "description": "Lorem ipsum dolor sit amet",
+  "dots": true,
+  "arrows": true,
+  "animated": true,
+  "children": [
+    {
+      "type": "basic-card",
+      "url": "https://example.com",
+      "title": "Lorem ipsum dolor sit amet",
+      "text": "Ut enim ad minim veniam.",
+      "icon": "/story-assets/icon_1_light.svg"
+    }
+  ]
+}
+```
+
+## Properties
+
+| Property       | Type                                                   | Default | Description                                                                             |
+| -------------- | ------------------------------------------------------ | ------- | --------------------------------------------------------------------------------------- |
+| `title`        | `string \| TitleProps`                                 | —       | Block title (plain string or options object).                                           |
+| `description`  | `string` (YFM)                                         | —       | Block description under the title.                                                      |
+| `children`     | `Card[]`                                               | —       | Array of child card blocks rendered as slides.                                          |
+| `slidesToShow` | `number \| {sm?, md?, lg?, xl?}`                       | —       | Number of slides to show, constant or per-breakpoint.                                   |
+| `dots`         | `boolean`                                              | `true`  | Show pagination dots.                                                                   |
+| `arrows`       | `boolean`                                              | `true`  | Show prev/next navigation arrows.                                                       |
+| `autoplay`     | `number`                                               | —       | Autoplay speed in milliseconds.                                                         |
+| `randomOrder`  | `boolean`                                              | —       | Shuffle slides on render.                                                               |
+| `disclaimer`   | `{text *required*, size?}`                             | —       | Disclaimer text under the slider. `size` is one of `'xs' \| 's' \| 'sm' \| 'm' \| 'l'`. |
+| `loadable`     | `{source *required*, params?, minCount? (deprecated)}` | —       | Disabled in the default schema; used by projects that wire up a custom loadable source. |
+
+### Common properties
+
+Inherits: `anchor`, `visible`, `indent`, `qa`, `className`, `animated`, `theme`, `when`, `context`. See root README.
+
+## Themed values
+
+Child cards may individually use themed values; the block itself does not theme its scalar properties.
+
+## Storybook
+
+[SliderOld](https://preview.gravity-ui.com/page-constructor/?path=/docs/blocks-sliderold-deprecated--docs)

package/build/docs/blocks/Table.md

@@ -0,0 +1,64 @@
+# Table
+
+Renders a title followed by a comparison-style table whose cells are plain strings or numbers. A legend column can be marked with `disk` or `tick` markers, and an optional legend list explains the marked columns.
+
+## Block type
+
+`type: 'table-block'`
+
+## When to use
+
+- Side-by-side feature/plan comparison tables.
+- Dense matrices of boolean-style checks ("0"/"1") with a legend.
+- Tabular reference data that needs per-column text alignment control.
+
+## Example
+
+```json
+{
+  "type": "table-block",
+  "title": "Lorem ipsum dolor sit amet",
+  "table": {
+    "content": [
+      ["Lorem", "ipsum 1", "dolor 2", "sit 3"],
+      ["Lorem 1", "0", "0", "0"],
+      ["Lorem 2", "0", "0", "1"],
+      ["Lorem 3", "1", "1", "1"]
+    ],
+    "legend": ["ipsum 1", "ipsum 2"],
+    "marker": "tick",
+    "justify": ["start", "center", "center", "center"],
+    "caption": "Comparison of features"
+  }
+}
+```
+
+## Properties
+
+| Property           | Type         | Default | Description                   |
+| ------------------ | ------------ | ------- | ----------------------------- |
+| `title` _required_ | `string`     | —       | Section heading (plain text). |
+| `table` _required_ | `TableProps` | —       | Table definition. See below.  |
+
+### `table`
+
+| Property             | Type                               | Default | Description                                                                                   |
+| -------------------- | ---------------------------------- | ------- | --------------------------------------------------------------------------------------------- |
+| `content` _required_ | `(string \| number)[][]`           | —       | Rows of cells. The first row is treated as the header row. Each cell is a string or a number. |
+| `legend`             | `string[]`                         | —       | YFM captions describing the marked columns; rendered as a legend list.                        |
+| `hideLegend`         | `boolean`                          | —       | Hides the rendered legend list while keeping markers in the table.                            |
+| `marker`             | `'disk' \| 'tick'`                 | —       | Marker style applied to legend cells. When omitted, no marker is rendered.                    |
+| `justify`            | `('start' \| 'center' \| 'end')[]` | —       | Per-column horizontal alignment. Values map to columns by index.                              |
+| `caption`            | `string`                           | —       | Accessible name for the table (not displayed visually).                                       |
+
+### Common properties
+
+Inherits: `anchor`, `visible`, `indent` (`{top?, bottom?}`), `qa`, `className`, `when`, `context`. See the root README for details.
+
+## Themed values
+
+This block does not introduce theme-aware properties of its own.
+
+## Storybook
+
+[Table](https://preview.gravity-ui.com/page-constructor/?path=/docs/blocks-table--docs)

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: Другая вложенная информация"
+    }
+  }
+]
+```