@gravity-ui/page-constructor 8.14.2 → 8.16.0

package/build/docs/blocks/ExtendedFeatures.md

@@ -0,0 +1,74 @@
+# ExtendedFeatures
+
+Renders a responsive grid of feature cards, each with an icon, title, text, an optional label (`New` / `Preview`), and an optional link. Use it to present a list of product features, capabilities, or benefits in a compact, icon-driven layout.
+
+## Block type
+
+`type: 'extended-features-block'`
+
+## When to use
+
+- Showcasing a set of features or capabilities with a small icon each.
+- Highlighting new or preview items via a built-in `New` / `Preview` label.
+- When you need per-item links to documentation or landing pages.
+
+## Example
+
+```json
+{
+  "type": "extended-features-block",
+  "title": {"text": "Lorem ipsum dolor sit amet"},
+  "description": "Three **cards in a row on the desktop**, two cards in a row on a tablet, one card in a row on a mobile phone.",
+  "items": [
+    {
+      "title": "Sed do eiusmod tempor incididunt",
+      "text": "Ut enim ad minim veniam [quis nostrud](https://example.com) ullamco laboris nisi ut aliquip ex ea commodo consequat.",
+      "icon": {"light": "/story-assets/icon_1_light.svg", "dark": "/story-assets/icon_1_dark.svg"}
+    },
+    {
+      "title": "Sed do eiusmod tempor",
+      "text": "Ut enim ad minim veniam [quis nostrud](https://example.com) ullamco laboris nisi ut aliquip ex ea commodo consequat.",
+      "icon": {"light": "/story-assets/icon_2_light.svg", "dark": "/story-assets/icon_2_dark.svg"},
+      "label": "New"
+    },
+    {
+      "title": "Sed do eiusmod tempor incididunt",
+      "text": "Ut enim ad minim veniam [quis nostrud](https://example.com) ullamco laboris nisi ut aliquip ex ea commodo consequat.",
+      "icon": {"light": "/story-assets/icon_3_light.svg", "dark": "/story-assets/icon_3_dark.svg"},
+      "link": {"text": "Go", "url": "#", "arrow": true, "theme": "normal"}
+    }
+  ]
+}
+```
+
+## Properties
+
+| Property      | Type                                              | Default                   | Description                                                                                         |
+| ------------- | ------------------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------- |
+| `title`       | `string \| TitleProps`                            | —                         | Block heading (string or Title options). |
+| `description` | `string`                                          | —                         | YFM subtitle shown under the title.                                                                 |
+| `items`       | `ExtendedFeaturesItem[]`                          | —                         | Array of feature cards (see below).                                                                 |
+| `colSizes`    | `{all?, sm?, md?, lg?, xl?}` (each `number` 1–12) | `{all: 12, sm: 6, md: 4}` | Column width per breakpoint for a single feature.                                                   |
+| `animated`    | `boolean`                                         | —                         | Enables entrance animation for the block.                                                           |
+
+### `ExtendedFeaturesItem`
+
+| Property | Type                          | Default | Description                                                                     |
+| -------- | ----------------------------- | ------- | ------------------------------------------------------------------------------- |
+| `title`  | `string`                      | —       | Feature title. Rendered as `<h3>` when the block has a title, otherwise `<h2>`. |
+| `text`   | `string`                      | —       | YFM body text.                                                                  |
+| `label`  | `'New' \| 'Preview'`          | —       | Small badge rendered next to the title.                                         |
+| `link`   | `LinkProps`                   | —       | Single link rendered below the text.                                            |
+| `icon`   | `ImageProps \| {light, dark}` | —       | Icon image shown above the title.                                               |
+
+### Common properties
+
+Inherits common block properties: `anchor`, `visible`, `indent` (`{top?, bottom?}`), `qa`, `className`, `animated`, `theme` (`'light' | 'dark'`), `when`, `context`. See the root README for details.
+
+## Themed values
+
+`icon` accepts either a plain value or a `{light, dark}` object resolved against the active runtime theme.
+
+## Storybook
+
+[ExtendedFeatures](https://preview.gravity-ui.com/page-constructor/?path=/docs/blocks-extendedfeatures--docs)

package/build/docs/blocks/FilterBlock.md

@@ -0,0 +1,112 @@
+# FilterBlock
+
+Renders a set of cards grouped by tags, with a row of toggle buttons that lets the visitor filter the visible cards by tag. Use it to present a catalog of cards (articles, features, products) that the user can narrow down without leaving the page.
+
+## Block type
+
+`type: 'filter-block'`
+
+## When to use
+
+- A catalog or gallery of cards that should be filterable by category.
+- When you want tag-style toggle buttons above the cards.
+- When the same card may belong to multiple categories.
+
+## Example
+
+```json
+{
+  "type": "filter-block",
+  "title": "Filter Block Example",
+  "description": "Three **cards in a row on the desktop**, two cards in a row on a tablet, one card in a row on a mobile phone.",
+  "allTag": false,
+  "tagButtonSize": "l",
+  "centered": false,
+  "tags": [
+    {"id": "one", "label": "First category"},
+    {"id": "two", "label": "Second category"},
+    {"id": "three", "label": "Third category"}
+  ],
+  "items": [
+    {
+      "tags": ["one"],
+      "card": {
+        "type": "layout-item",
+        "media": {
+          "dark": {"image": "/story-assets/img-mini_4-12_dark.png"},
+          "light": {"image": "/story-assets/img-mini_4-12_light.png"}
+        },
+        "content": {"title": "Card 1", "text": "Dolor sit amet consectetur adipiscing elit"}
+      }
+    },
+    {
+      "tags": ["two"],
+      "card": {
+        "type": "layout-item",
+        "media": {
+          "dark": {"image": "/story-assets/img-mini_4-12_dark.png"},
+          "light": {"image": "/story-assets/img-mini_4-12_light.png"}
+        },
+        "content": {"title": "Card 2", "text": "Sed do eiusmod tempor incididunt ut labore"}
+      }
+    },
+    {
+      "tags": ["three"],
+      "card": {
+        "type": "layout-item",
+        "media": {
+          "dark": {"image": "/story-assets/img-mini_4-12_dark.png"},
+          "light": {"image": "/story-assets/img-mini_4-12_light.png"}
+        },
+        "content": {"title": "Card 3", "text": "Et dolore magna aliqua ut enim ad minim"}
+      }
+    }
+  ],
+  "colSizes": {"all": 12, "xl": 4, "lg": 4, "md": 6, "sm": 12}
+}
+```
+
+## Properties
+
+| Property           | Type                                              | Default                   | Description                                                                                                                      |
+| ------------------ | ------------------------------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `title`            | `string \| TitleProps`                            | —                         | Block heading (string or Title options).                              |
+| `description`      | `string`                                          | —                         | YFM subtitle shown under the title.                                                                                              |
+| `tags` _required_  | `FilterTag[]`                                     | —                         | Tag definitions used as filter toggles (see below).                                                                              |
+| `items` _required_ | `FilterItem[]`                                    | —                         | Cards to filter (see below).                                                                                                     |
+| `allTag`           | `boolean \| string \| FilterTag`                  | —                         | Adds an "All" toggle. `true` uses the default label; a string overrides the label; an object supplies `{label, analyticsEvent}`. |
+| `tagButtonSize`    | `'s' \| 'm' \| 'l' \| 'xl'`                       | —                         | Size of the filter tag buttons.                                                                                                  |
+| `centered`         | `boolean`                                         | `false`                   | Centers the header and the tag button row.                                                                                       |
+| `colSizes`         | `{all?, sm?, md?, lg?, xl?}` (each `number` 1–12) | `{all: 12, sm: 6, md: 4}` | Column width per breakpoint for a single card.                                                                                   |
+| `animated`         | `boolean`                                         | —                         | Enables entrance animation for the block.                                                                                        |
+
+### `FilterTag`
+
+| Property           | Type                   | Default | Description                                                        |
+| ------------------ | ---------------------- | ------- | ------------------------------------------------------------------ |
+| `id` _required_    | `string`               | —       | Tag identifier. Must match at least one value in an item's `tags`. |
+| `label` _required_ | `string`               | —       | Tag button label.                                                  |
+| `analyticsEvent`   | `AnalyticsEventSchema` | —       | Analytics event fired when the tag is selected.                    |
+
+### `FilterItem`
+
+| Property          | Type        | Default | Description                                                                                                |
+| ----------------- | ----------- | ------- | ---------------------------------------------------------------------------------------------------------- |
+| `tags` _required_ | `string[]`  | —       | Tag ids this card belongs to.                                                                              |
+| `card` _required_ | `CardBlock` | —       | Card sub-block to render (any of the `cards` definitions, e.g. `layout-item`, `basic-card`, `image-card`). |
+
+### Common properties
+
+Inherits common block properties: `anchor`, `visible`, `indent` (`{top?, bottom?}`), `qa`, `className`, `animated`, `theme` (`'light' | 'dark'`), `when`, `context`. See the root README for details.
+
+## Children / sub-blocks
+
+Cards are declared inside `items[].card` (not via a top-level `children` array). Each `card` may be any sub-block registered under the `cards` definition (`basic-card`, `image-card`, `background-card`, `price-card`, `layout-item`, etc.). The filtered cards are laid out via an internal `card-layout-block`.
+
+## Themed values
+
+No dedicated themed props on the block itself; individual card `media`/`background` may still accept `{light, dark}` objects per their own schemas.
+
+## Storybook
+
+[FilterBlock](https://preview.gravity-ui.com/page-constructor/?path=/docs/blocks-filterblock--docs)

package/build/docs/blocks/FoldableList.md

@@ -0,0 +1,78 @@
+# FoldableList
+
+Renders a two-column block: a content panel on the left (title, text, links, buttons) and a list of collapsible items on the right, each with its own title, YFM text, and optional link. Use it for FAQ-style or specification pages where each row expands to reveal more detail.
+
+## Block type
+
+`type: 'foldable-list-block'`
+
+## When to use
+
+- FAQs, glossaries, or specification lists where each entry should expand/collapse.
+- When you need a sticky intro panel (title, description, CTA) next to a long list.
+- When individual answers may contain a bulleted list (`dash` or `disk` markers).
+
+## Example
+
+```json
+{
+  "type": "foldable-list-block",
+  "title": "Lorem ipsum",
+  "text": "Dolor sit amet, consectetur adipiscing elit [sed do eiusmod](https://example.com) tempor incididunt ut labore et dolore magna aliqua.",
+  "additionalInfo": "Dolor sit amet [consectetur adipiscing](https://example.com) Duis aute irure dolor in reprehenderit.",
+  "links": [{"url": "/security", "text": "Learn more", "theme": "normal", "arrow": true}],
+  "buttons": [{"text": "Button", "theme": "action", "url": "https://example.com"}],
+  "items": [
+    {
+      "title": "Lorem ipsum dolor sit amet 0",
+      "text": "Consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
+      "link": {"url": "#", "text": "Documentation", "theme": "normal", "arrow": true}
+    },
+    {
+      "title": "Ut enim ad minim veniam, quis nostrud exercitation ullamco? 1",
+      "text": "laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.",
+      "link": {"url": "#", "text": "Documentation", "theme": "normal", "arrow": true}
+    },
+    {
+      "title": "Some title with a list",
+      "text": "Lorem ipsum dolor sit amet:\n\n- Lorem ipsum\n- Lorem ipsum\n- Lorem ipsum",
+      "link": {"url": "#", "text": "Documentation", "theme": "normal", "arrow": true},
+      "listStyle": "disk"
+    }
+  ]
+}
+```
+
+## Properties
+
+| Property           | Type                    | Default | Description                                                                                              |
+| ------------------ | ----------------------- | ------- | -------------------------------------------------------------------------------------------------------- |
+| `title` _required_ | `string \| TitleProps`  | —       | Left-panel heading (string or Title options). |
+| `text`             | `string`                | —       | YFM body text in the left panel.                                                                         |
+| `additionalInfo`   | `string`                | —       | YFM supplementary text in the left panel.                                                                |
+| `links`            | `LinkProps[]`           | —       | Array of links rendered in the left panel.                                                               |
+| `buttons`          | `ButtonBlock[]`         | —       | Array of buttons rendered in the left panel.                                                             |
+| `list`             | `ContentItem[]`         | —       | Icon + title + text list rendered in the left panel. Each item requires an `icon` or `gravityIcon`.      |
+| `controlPosition`  | `'default' \| 'bottom'` | —       | Position of the link/button controls in the left panel.                                                  |
+| `items` _required_ | `FoldableListItem[]`    | —       | Collapsible rows on the right (see below).                                                               |
+
+### `FoldableListItem`
+
+| Property           | Type               | Default  | Description                                      |
+| ------------------ | ------------------ | -------- | ------------------------------------------------ |
+| `title` _required_ | `string`           | —        | Row title (always visible).                      |
+| `text` _required_  | `string`           | —        | YFM body text revealed when the row is expanded. |
+| `link`             | `LinkProps`        | —        | Link rendered below the text.                    |
+| `listStyle`        | `'dash' \| 'disk'` | `'dash'` | Marker style for lists inside the text.          |
+
+### Common properties
+
+Inherits common block properties: `anchor`, `visible`, `indent` (`{top?, bottom?}`), `qa`, `className`, `animated`, `theme` (`'light' | 'dark'`), `when`, `context`. See the root README for details.
+
+## Themed values
+
+No dedicated themed props; the block follows the runtime `theme` for text/background coloring.
+
+## Storybook
+
+[FoldableList](https://preview.gravity-ui.com/page-constructor/?path=/docs/blocks-foldablelist--docs)

package/build/docs/blocks/Footer.md

@@ -0,0 +1,110 @@
+# Footer
+
+A configurable page footer assembled from optional floors: navigation columns, contacts (social icons), disclaimer, copyright (legal links, language switcher, logo), and an attribution strip.
+
+## Block type
+
+`type: 'footer-block'`
+
+## When to use
+
+- You need a site-wide footer with link columns and/or a logo.
+- You need social/contact icon links and/or a legal disclaimer.
+- You need a copyright floor with legal links, language switcher, or a logo.
+
+## Example
+
+```json
+{
+  "type": "footer-block",
+  "indentTop": "l",
+  "backgroundColor": {"light": "#ffffff", "dark": "#111111"},
+  "navigation": {
+    "logo": {
+      "image": {"src": "story-assets/icon_1-with-text_light.svg"},
+      "url": "/"
+    },
+    "columns": [
+      {
+        "title": "Product",
+        "links": [
+          {"text": "Overview", "url": "#overview"},
+          {"text": "Docs", "url": "#docs"}
+        ]
+      }
+    ]
+  },
+  "contacts": {
+    "title": "Join us",
+    "links": [
+      {
+        "icon": {"src": "story-assets/icons-github_light.svg"},
+        "url": "https://example.com",
+        "urlTitle": "GitHub"
+      }
+    ]
+  },
+  "disclaimer": {"text": "Legal disclaimer text.", "align": "left"},
+  "copyright": {
+    "links": [
+      {"text": "Privacy Policy", "url": "#privacy"},
+      {"text": "Terms", "url": "#terms"}
+    ],
+    "copyrightText": "© 2026 Company"
+  },
+  "attribution": true
+}
+```
+
+## Properties
+
+| Property          | Type                                                      | Default | Description                                                                             |
+| ----------------- | --------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------- |
+| `navigation`      | `FooterNavigation`                                        | —       | Navigation floor: logo and required link columns. Rendered when `columns` is non-empty. |
+| `contacts`        | `FooterContacts`                                          | —       | Contacts floor: title + icon links. Rendered when `links` is non-empty.                 |
+| `disclaimer`      | `{text *required*, align *required*: 'left' \| 'center'}` | —       | Disclaimer floor rendered as YFM.                                                       |
+| `copyright`       | `FooterCopyright`                                         | —       | Copyright floor with optional legal links, language switcher, logo, and copyright text. |
+| `attribution`     | `boolean`                                                 | —       | Shows the branded "Created with ..." attribution strip.                                 |
+| `backgroundColor` | `string \| {light, dark}`                                 | —       | Theme-aware footer background color.                                                    |
+| `indentTop`       | `'0' \| 'xs' \| 's' \| 'm' \| 'l' \| 'xl'`                | —       | Top indent of the footer.                                                               |
+
+### `navigation` (FooterNavigation)
+
+| Property             | Type                                                                                       | Default                         | Description                                             |
+| -------------------- | ------------------------------------------------------------------------------------------ | ------------------------------- | ------------------------------------------------------- |
+| `columns` _required_ | `Array<{title *required*, links *required*: LinkProps[]}>`                                 | —                               | Link columns.                                           |
+| `logo`               | `{image *required*: ImageProps \| {light, dark}, url?, alt?, placement?: 'left' \| 'top'}` | —                               | Optional footer logo. `placement` defaults to `'left'`. |
+| `colSizes`           | `{sm?, md?, lg?, xl?, all?}`                                                               | `{all: 6, sm: 4, md: 3, lg: 3}` | Grid sizes per column.                                  |
+| `columnsPerRow`      | `number` (1–12)                                                                            | —                               | Switches to a fixed percentage-width-per-column layout. |
+
+### `contacts` (FooterContacts)
+
+| Property        | Type                                                                               | Default  | Description                                   |
+| --------------- | ---------------------------------------------------------------------------------- | -------- | --------------------------------------------- |
+| `title`         | `string`                                                                           | —        | Contacts floor heading.                       |
+| `links`         | `Array<{icon *required*: ImageProps \| {light, dark}, url *required*, urlTitle?}>` | —        | Social/contact icon links. Open in a new tab. |
+| `iconsSize`     | `'m' \| 'l'`                                                                       | `'l'`    | Icon size.                                    |
+| `linksPosition` | `'left' \| 'center'`                                                               | `'left'` | Horizontal alignment of icons.                |
+| `titlePosition` | `'top' \| 'near'`                                                                  | `'top'`  | Title placement relative to icons.            |
+
+### `copyright` (FooterCopyright)
+
+| Property                | Type                                                                                                              | Default      | Description                                       |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------- |
+| `links`                 | `LinkProps[]`                                                                                                     | —            | Legal or service links.                           |
+| `linksOverflowStrategy` | `'dropdown' \| 'line-wrap'`                                                                                       | `'dropdown'` | Overflow behavior for links.                      |
+| `languageSwitcher`      | `{items *required*: Array<{text *required*, href *required*}>, buttonText?, image?: ImageProps \| {light, dark}}` | —            | Dropdown language switcher rendered on the right. |
+| `logo`                  | `{image *required*: ImageProps \| {light, dark}, url?, alt?}`                                                     | —            | Optional logo for the copyright floor.            |
+| `copyrightText`         | `string`                                                                                                          | —            | Copyright text rendered on the right.             |
+
+### Common properties
+
+Inherits: `anchor`, `visible`, `indent`, `qa`, `className`, `animated`, `theme`, `when`, `context`. See root README.
+
+## Themed values
+
+`backgroundColor`, `navigation.logo.image`, `contacts.links[].icon`, `copyright.languageSwitcher.image`, and `copyright.logo.image` accept either a plain value or `{light, dark}`.
+
+## Storybook
+
+[Footer](https://preview.gravity-ui.com/page-constructor/?path=/docs/blocks-footer--docs)

package/build/docs/blocks/Form.md

@@ -0,0 +1,89 @@
+# Form
+
+A two-column block that renders a third-party form (Yandex Forms or HubSpot) alongside optional YFM text content, with a configurable layout direction and background.
+
+## Block type
+
+`type: 'form-block'`
+
+## When to use
+
+- You need to embed a Yandex Form or HubSpot form into a page assembled from JSON.
+- You want to place marketing copy, title, and links next to a lead-generation form.
+- You need a themed background (color or image) behind the form.
+
+## Example
+
+```json
+{
+  "type": "form-block",
+  "title": "Hubspot form",
+  "direction": "center",
+  "textContent": {
+    "title": "Lorem ipsum dolor sit amet",
+    "text": "**Ut enim ad minim veniam** [quis nostrud](https://example.com) exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat."
+  },
+  "formData": {
+    "hubspot": {
+      "region": "eu1",
+      "portalId": "25764979",
+      "formId": "a3eb06a6-e8ce-45d4-81bd-7fadb7dab313"
+    }
+  }
+}
+```
+
+A Yandex form variant:
+
+```json
+{
+  "type": "form-block",
+  "formData": {
+    "yandex": {
+      "id": "5f3c4d2b1e2a4c0001a2b3c4"
+    }
+  }
+}
+```
+
+## Properties
+
+| Property              | Type                                                                                       | Default    | Description                                                                              |
+| --------------------- | ------------------------------------------------------------------------------------------ | ---------- | ---------------------------------------------------------------------------------------- |
+| `formData` _required_ | `{yandex?: YandexFormProps \| {light, dark}, hubspot?: HubspotFormProps \| {light, dark}}` | —          | The form to embed. Exactly one of `yandex` or `hubspot` is expected.                     |
+| `title`               | `string`                                                                                   | —          | Block title rendered above the form.                                                     |
+| `textContent`         | `ContentBase` (without `size`, `centered`, `colSizes`)                                     | —          | Title, text (YFM), links, buttons, list items for the content column.                    |
+| `direction`           | `'content-form' \| 'form-content' \| 'center'`                                             | `'center'` | Layout direction of the content column relative to the form.                             |
+| `background`          | `ImageProps`                                                                               | —          | Background image or CSS style; `style` supports `{desktop, mobile}` breakpoints. Themed. |
+
+### `formData.yandex` (YandexFormProps)
+
+| Property        | Type     | Default | Description                                      |
+| --------------- | -------- | ------- | ------------------------------------------------ |
+| `id` _required_ | `string` | —       | Yandex Forms form id.                            |
+| `containerId`   | `string` | —       | Optional DOM container id for the embedded form. |
+
+### `formData.hubspot` (HubspotFormProps)
+
+| Property              | Type     | Default | Description                        |
+| --------------------- | -------- | ------- | ---------------------------------- |
+| `portalId` _required_ | `string` | —       | HubSpot portal id.                 |
+| `formId` _required_   | `string` | —       | HubSpot form id.                   |
+| `region`              | `string` | —       | HubSpot region (e.g. `'eu1'`).     |
+| `formInstanceId`      | `string` | —       | Optional HubSpot form instance id. |
+
+### Common properties
+
+Inherits: `anchor`, `visible`, `indent`, `qa`, `className`, `animated`, `theme`, `when`, `context`. See root README.
+
+## Setup notes
+
+HubSpot forms are loaded through the HubSpot embed script automatically; no extra provider configuration is required. Yandex Forms are loaded via the Yandex Forms script. If you use a custom React node instead of `formData`, pass it via the `customFormNode` / `additionalContentNode` props when mounting the block from code (not available from JSON).
+
+## Themed values
+
+`background`, `formData.yandex`, and `formData.hubspot` accept either a plain value or `{light, dark}`.
+
+## Storybook
+
+[Form](https://preview.gravity-ui.com/page-constructor/?path=/docs/blocks-form--docs)

package/build/docs/blocks/Header.md

@@ -0,0 +1,70 @@
+# Header
+
+Renders a full-width page header with a title, optional overtitle/description, call-to-action buttons, breadcrumbs, and an optional media asset (image, video, or video iframe) positioned to the right or centered. Use it as the primary hero/landing block at the top of a page.
+
+## Block type
+
+`type: 'header-block'`
+
+## When to use
+
+- As the first block of a page to introduce the product, section, or campaign.
+- When you need a large headline paired with CTA buttons and an illustration or background media.
+- When you want breadcrumbs, status pills, or additional info alongside the title.
+
+## Example
+
+```json
+{
+  "type": "header-block",
+  "title": "Lorem ipsum dolor sit amet, consectetur adipiscing elit",
+  "description": "**Ut enim ad minim veniam** [quis nostrud](https://example.com) exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.",
+  "additionalInfo": "**Ut enim ad minim veniam** ut aliquip ex ea commodo consequat.",
+  "buttons": [
+    {"text": "Primary", "theme": "action", "url": "https://example.com"},
+    {"text": "Secondary", "theme": "outlined", "url": "https://example.com"}
+  ],
+  "background": {
+    "light": {"image": "/images/header-bg-light.png", "color": "#EFF2F8"},
+    "dark": {"image": "/images/header-bg-dark.png", "color": "#262626"}
+  }
+}
+```
+
+## Properties
+
+| Property           | Type                                                      | Default                | Description                                                                 |
+| ------------------ | --------------------------------------------------------- | ---------------------- | --------------------------------------------------------------------------- |
+| `title` _required_ | `string`                                                  | —                      | Main heading text (YFM-supported). Rendered as `<h1>`.                      |
+| `overtitle`        | `string`                                                  | —                      | Small label rendered above the title. Accepts YFM or a React node.          |
+| `description`      | `string`                                                  | —                      | YFM body text shown below the title.                                        |
+| `additionalInfo`   | `string`                                                  | —                      | YFM supplementary text shown below the description.                         |
+| `width`            | `'s' \| 'm' \| 'l'`                                       | `'m'`                  | Maximum text width; also drives the title size.                             |
+| `buttons`          | `ButtonBlock[]`                                           | —                      | Call-to-action buttons rendered under the text.                             |
+| `offset`           | `'default' \| 'large'`                                    | `'default'`            | Horizontal indent of the content column.                                    |
+| `image`            | `ImageProps \| {light, dark}`                             | —                      | Inline media image placed on the right side.                                |
+| `video`            | `VideoProps \| {light, dark}`                             | —                      | Inline media video placed on the right side.                                |
+| `videoIframe`      | `{src, autoplay?, previewImg?, height?} \| {light, dark}` | —                      | External iframe video (e.g. video hosting) placed on the right side.        |
+| `mediaView`        | `'fit' \| 'full'`                                         | `'full'`               | `fit` constrains the media height; `full` lets it fill the available space. |
+| `backLink`         | `{url, title}`                                            | —                      | "Back" navigation link rendered above the title.                            |
+| `imageSize`        | `'s' \| 'm'`                                              | derived from `width`   | Overrides the inline media column size.                                     |
+| `verticalOffset`   | `'0' \| 's' \| 'm' \| 'l' \| 'xl'`                        | `'m'`                  | Vertical spacing around the content.                                        |
+| `background`       | `HeaderBackgroundProps \| {light, dark}`                  | —                      | Full-bleed background media/color behind the content.                       |
+| `theme`            | `'default' \| 'dark'`                                     | `'light'` (text theme) | Text/background color scheme for the content area.                          |
+| `breadcrumbs`      | `{items: {url, text}[], theme?}`                          | —                      | Breadcrumb navigation rendered above the content.                           |
+| `status`           | `string`                                                  | —                      | Status text/React node rendered next to the title.                          |
+| `centered`         | `boolean`                                                 | `false`                | Centers the content and hides the right-side media.                         |
+
+`HeaderBackgroundProps` extends `MediaProps` with `fullWidth?: boolean` and `fullWidthMedia?: boolean`.
+
+### Common properties
+
+Inherits common block properties: `anchor`, `visible`, `indent` (`{top?, bottom?}`), `qa`, `className`, `animated`, `theme` (`'light' | 'dark'`), `when`, `context`. See the root README for details.
+
+## Themed values
+
+`image`, `video`, `videoIframe`, and `background` each accept either a plain value or a `{light, dark}` object resolved against the active runtime theme.
+
+## Storybook
+
+[Header](https://preview.gravity-ui.com/page-constructor/?path=/docs/blocks-header--docs)

package/build/docs/blocks/HeaderSlider.md

@@ -0,0 +1,70 @@
+# HeaderSlider
+
+Renders a carousel of full-bleed `header-block` slides — each slide carries its own title, description, buttons, and background media. Use it when the top of the page needs to rotate multiple equally important campaigns or announcements instead of a single hero.
+
+## Block type
+
+`type: 'header-slider-block'`
+
+## When to use
+
+- Top-of-page hero carousel with two or more featured items.
+- When each slide needs the full Header feature set (buttons, background image/video, breadcrumbs, theme).
+- When you want autoplay, dots, or arrows to navigate between slides.
+
+## Example
+
+```json
+{
+  "type": "header-slider-block",
+  "dots": true,
+  "arrows": true,
+  "autoplay": 3000,
+  "items": [
+    {
+      "title": "Lorem ipsum dolor sit amet",
+      "description": "Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris.",
+      "background": {
+        "light": {"image": "/images/header-bg-light.png", "color": "#EFF2F8", "fullWidth": true},
+        "dark": {"image": "/images/header-bg-dark.png", "color": "#262626", "fullWidth": true}
+      },
+      "buttons": [{"text": "Primary", "theme": "action", "url": "https://example.com"}]
+    },
+    {
+      "title": "Second campaign headline",
+      "description": "Duis aute irure dolor in reprehenderit in voluptate velit esse.",
+      "background": {"color": "#262626", "fullWidth": true},
+      "theme": "dark",
+      "buttons": [{"text": "Learn more", "theme": "normal-contrast", "url": "https://example.com"}]
+    }
+  ]
+}
+```
+
+## Properties
+
+| Property           | Type                                               | Default | Description                                                                                                   |
+| ------------------ | -------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------- |
+| `items` _required_ | `HeaderItem[]`                                     | —       | Array of slides. Each item follows the Header schema (`title` required) and renders as a full `header-block`. |
+| `dots`             | `boolean`                                          | —       | Shows pagination dots under the slider.                                                                       |
+| `arrows`           | `boolean`                                          | —       | Shows navigation arrows (hidden automatically on mobile).                                                     |
+| `randomOrder`      | `boolean`                                          | —       | Shuffles slide order on load.                                                                                 |
+| `autoplay`         | `number`                                           | —       | Slide interval in milliseconds; omit to disable autoplay.                                                     |
+| `adaptive`         | `boolean`                                          | —       | Lets the slider height adapt to the tallest slide.                                                            |
+| `arrowSize`        | `number`                                           | `20`    | Pixel size of the navigation arrows.                                                                          |
+| `slidesToShow`     | `{sm?, md?, lg?, xl?, all?}`                       | —       | Responsive count of slides visible (HeaderSlider forces a single slide).                                      |
+| `disclaimer`       | `{text: string, size?: 'xs'\|'s'\|'sm'\|'m'\|'l'}` | —       | Small legal/disclaimer text rendered near the slider.                                                         |
+
+Each `HeaderItem` supports every property of the [Header](./Header.md) block (`title`, `description`, `buttons`, `background`, `breadcrumbs`, `theme`, etc.).
+
+### Common properties
+
+Inherits common block properties: `anchor`, `visible`, `indent` (`{top?, bottom?}`), `qa`, `className`, `animated`, `theme` (`'light' | 'dark'`), `when`, `context`. See the root README for details.
+
+## Themed values
+
+Theming is delegated to the individual slide `items`, which support `{light, dark}` values per the Header block.
+
+## Storybook
+
+[HeaderSlider](https://preview.gravity-ui.com/page-constructor/?path=/docs/blocks-headerslider--docs)