@gravity-ui/page-constructor 8.15.0 → 8.16.0

package/README.md

@@ -582,17 +582,39 @@ The Memory Bank is located in the `memory-bank/` directory and consists of regul
 - `usage/` - Component-specific usage documentation
 - `storybookComponents.md` - Storybook integration details
 
-### For AI Agents
+## Tests
 
-When working with AI agents on this project, the Memory Bank serves as a comprehensive knowledge base that helps agents understand:
+Comprehensive documentation is available at the provided [link](./test-utils/docs/README.md).
 
-- Project structure and patterns
-- Component APIs and usage examples
-- Development workflows and best practices
-- Current implementation status and next steps
+## License
 
-AI agents can read these files to quickly get up to speed with the project context and make more informed decisions about code changes and implementations.
+Distributed under the MIT License. See [LICENSE](LICENSE) for details.
 
-## Tests
+## For AI agents
 
-Comprehensive documentation is available at the provided [link](./test-utils/docs/README.md).
+A library for rendering whole web pages or page sections from declarative JSON/YAML config, using a set of ready-made, orderable blocks — reach for it to build marketing/landing pages, not general application UI.
+
+### When to use
+
+- Data-driven pages: render a `content` config of typed blocks with `PageConstructor` wrapped in `PageConstructorProvider`.
+- Marketing, landing, and documentation pages assembled from prebuilt blocks (headers, media, cards, etc.).
+- Server-side YFM processing of block text via the `@gravity-ui/page-constructor/server` utilities (`contentTransformer`, `fullTransform`).
+- Reusing just the responsive grid (`Grid`/`Row`/`Col`) or `Navigation` component standalone.
+
+### When not to use
+
+- General application UI (buttons, forms, modals) — use [`@gravity-ui/uikit`](https://github.com/gravity-ui/uikit).
+- Editing Markdown/YFM content — use [`@gravity-ui/markdown-editor`](https://github.com/gravity-ui/markdown-editor).
+- App navigation shells (aside header) — use [`@gravity-ui/navigation`](https://github.com/gravity-ui/navigation); this package's `Navigation` is a page-level top nav.
+
+### Common pitfalls
+
+- **`PageConstructor` must be wrapped in `PageConstructorProvider`.** Rendering it bare breaks context (locale, theme, SSR, analytics).
+- **The content prop is `content`, shaped `{blocks: [...]}`.** Each block object needs a `type` matching a known block plus its data fields; there is no `data`/`config` prop.
+- **YFM in block text needs server processing.** Markdown-like fields render as plain text unless you run content through `contentTransformer`/`fullTransform` from `@gravity-ui/page-constructor/server`; `@diplodoc/transform` is a required peer dependency.
+- **Import the SCSS styles.** Add `@gravity-ui/page-constructor/styles/styles.scss` (SCSS, not CSS); custom blocks import the same file to reuse mixins/variables.
+- **Vite needs `vite-plugin-dynamic-import`.** Dynamic block imports fail under Vite without it.
+
+## Documentation for AI agents
+
+Agent-readable documentation for the installed version is located in `node_modules/@gravity-ui/page-constructor/build/docs/INDEX.md`.

package/build/docs/INDEX.md

@@ -0,0 +1,191 @@
+# @gravity-ui/page-constructor documentation
+
+Documentation for the **installed** version of `@gravity-ui/page-constructor`.
+Your training data may be outdated — these files are the source of truth.
+
+Paths are relative to this file (`node_modules/@gravity-ui/page-constructor/build/docs/`).
+
+## For AI agents
+
+A library for rendering whole web pages or page sections from declarative JSON/YAML config, using a set of ready-made, orderable blocks — reach for it to build marketing/landing pages, not general application UI.
+
+### When to use
+
+- Data-driven pages: render a `content` config of typed blocks with `PageConstructor` wrapped in `PageConstructorProvider`.
+- Marketing, landing, and documentation pages assembled from prebuilt blocks (headers, media, cards, etc.).
+- Server-side YFM processing of block text via the `@gravity-ui/page-constructor/server` utilities (`contentTransformer`, `fullTransform`).
+- Reusing just the responsive grid (`Grid`/`Row`/`Col`) or `Navigation` component standalone.
+
+### When not to use
+
+- General application UI (buttons, forms, modals) — use [`@gravity-ui/uikit`](https://github.com/gravity-ui/uikit).
+- Editing Markdown/YFM content — use [`@gravity-ui/markdown-editor`](https://github.com/gravity-ui/markdown-editor).
+- App navigation shells (aside header) — use [`@gravity-ui/navigation`](https://github.com/gravity-ui/navigation); this package's `Navigation` is a page-level top nav.
+
+### Common pitfalls
+
+- **`PageConstructor` must be wrapped in `PageConstructorProvider`.** Rendering it bare breaks context (locale, theme, SSR, analytics).
+- **The content prop is `content`, shaped `{blocks: [...]}`.** Each block object needs a `type` matching a known block plus its data fields; there is no `data`/`config` prop.
+- **YFM in block text needs server processing.** Markdown-like fields render as plain text unless you run content through `contentTransformer`/`fullTransform` from `@gravity-ui/page-constructor/server`; `@diplodoc/transform` is a required peer dependency.
+- **Import the SCSS styles.** Add `@gravity-ui/page-constructor/styles/styles.scss` (SCSS, not CSS); custom blocks import the same file to reuse mixins/variables.
+- **Vite needs `vite-plugin-dynamic-import`.** Dynamic block imports fail under Vite without it.
+
+## Install
+
+```shell
+npm install @gravity-ui/page-constructor
+```
+
+## Usage
+
+First, we need a React project and some kind of server. For example, you can create a React project using Vite and an Express server, or you can create Next.js application - it will have a client and server side at once.
+
+Install the required dependencies:
+
+```shell
+npm install @gravity-ui/page-constructor @diplodoc/transform @gravity-ui/uikit
+```
+
+Insert the `Page Constructor` to the page. To work correctly, it must be wrapped in a `PageConstructorProvider`:
+
+```tsx
+import {PageConstructor, PageConstructorProvider} from '@gravity-ui/page-constructor';
+import '@gravity-ui/page-constructor/styles/styles.scss';
+
+const App = () => {
+  const content = {
+    blocks: [
+      {
+        type: 'header-block',
+        title: 'Hello world',
+        background: {color: '#f0f0f0'},
+        description:
+          '**Congratulations!** Have you built a [page-constructor](https://github.com/gravity-ui/page-constructor) into your website',
+      },
+    ],
+  };
+
+  return (
+    <PageConstructorProvider>
+      <PageConstructor content={content} />
+    </PageConstructorProvider>
+  );
+};
+
+export default App;
+```
+
+This was the simplest example of a connection. In order for YFM markup to work, you need to process content on the server and receive it on the client.
+
+If your server is a separate application, then you need to install page-constructor:
+
+```shell
+npm install @gravity-ui/page-constructor
+```
+
+To process YFM in all base blocks, call the `contentTransformer` and pass the content and options there:
+
+```ts
+const express = require('express');
+const app = express();
+const {contentTransformer} = require('@gravity-ui/page-constructor/server');
+
+const content = {
+  blocks: [
+    {
+      type: 'header-block',
+      title: 'Hello world',
+      background: {color: '#f0f0f0'},
+      description:
+        '**Congratulations!** Have you built a [page-constructor](https://github.com/gravity-ui/page-constructor) into your website',
+    },
+  ],
+};
+
+app.get('/content', (req, res) => {
+  res.send({content: contentTransformer({content, options: {lang: 'en'}})});
+});
+
+app.listen(3000);
+```
+
+On the client, add an endpoint call to receive content:
+
+```tsx
+import {PageConstructor, PageConstructorProvider} from '@gravity-ui/page-constructor';
+import '@gravity-ui/page-constructor/styles/styles.scss';
+import {useEffect, useState} from 'react';
+
+const App = () => {
+  const [content, setContent] = useState();
+
+  useEffect(() => {
+    (async () => {
+      const response = await fetch('http://localhost:3000/content').then((r) => r.json());
+      setContent(response.content);
+    })();
+  }, []);
+
+  return (
+    <PageConstructorProvider>
+      <PageConstructor content={content} />
+    </PageConstructorProvider>
+  );
+};
+
+export default App;
+```
+
+### Ready-made template
+
+To start a new project, you can use the [ready-made template on Next.js ](https://github.com/gravity-ui/page-constructor-website-template) which we have prepared.
+
+### Static site builder
+
+[Page Constructor Builder](https://github.com/gravity-ui/page-constructor-builder) - command-line utility for building static pages from YAML configurations using the @gravity-ui/page-constructor
+
+## Guides
+
+- [Data preparation](./guides/data-preparation.md) — This chapter provides documentaion for server utilities for transforming content, including Yandex Flavored Markdown (YFM) to HTML conversion and text processing. Key features include:
+- [Подготовка данных](./guides/data-preparation-ru.md) — Документацию по серверным утилитам для преобразования контента, включая конвертацию Yandex Flavored Markdown (YFM) в HTML и обработку текста. Основные возможности:
+
+## Blocks
+
+- [Banner](./blocks/Banner.md) — Renders a compact promotional card with a title, subtitle, an optional background image or color, and a single call-to-action button. Use it to highlight a feature, announce a release, or drive traffic to a landing page from anywhere in the page flow.
+- [CardLayout](./blocks/CardLayout.md) — Renders a responsive grid of arbitrary cards (children) with an optional header and a decorative background image. Use it whenever you need to lay out a homogeneous set of cards — basic, image, background, price, or layout-item — in a row that adapts to the viewport.
+- [Companies](./blocks/Companies.md) — Renders a heading with a logo strip — a set of responsive images (desktop / tablet / mobile) shown beneath an optional title and description. Use it for "trusted by" or "powered by" logo rows that must adapt per device and theme.
+- [ContentLayout](./blocks/ContentLayout.md) — Renders a single-column content section (title, body text, optional list, links, and buttons) paired with an optional list of downloadable files and a background. Use it for documentation-style sections, terms, descriptions, or anywhere a focused block of text with file attachments is needed.
+- [ExtendedFeatures](./blocks/ExtendedFeatures.md) — 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.
+- [FilterBlock](./blocks/FilterBlock.md) — 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.
+- [FoldableList](./blocks/FoldableList.md) — 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.
+- [Footer](./blocks/Footer.md) — A configurable page footer assembled from optional floors: navigation columns, contacts (social icons), disclaimer, copyright (legal links, language switcher, logo), and an attribution strip.
+- [Form](./blocks/Form.md) — 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.
+- [Header](./blocks/Header.md) — 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.
+- [HeaderSlider](./blocks/HeaderSlider.md) — 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.
+- [Hero](./blocks/Hero.md) — Renders a modern, content-driven hero block: an overtitle, a rich content column (title, body text, list, links, buttons) and a media column (image/video/iframe) that adapts to its intrinsic aspect ratio. Use it as the primary landing block when you want more layout flexibility than the classic Header provides.
+- [Icons](./blocks/Icons.md) — Renders a responsive grid of small icon items, each consisting of an image and a caption. Items can optionally be wrapped in links, turning the grid into a navigable set of icon links.
+- [Info](./blocks/Info.md) — Renders a two-column information section: a left content column and a right content column, each with its own title, text, lists, buttons, and links, placed inside an optional themed background container.
+- [Map](./blocks/Map.md) — A media-and-content block that embeds an interactive Yandex Map inside a card, paired with an optional title, description, links, and buttons.
+- [Media](./blocks/Media.md) — Renders a two-column layout that pairs a content column (title, body, list, links, button) with a media column (image, video, YouTube, iframe, or DataLens embed). Use it for feature or explainer sections where text and a rich media asset need to sit side by side.
+- [PromoFeaturesBlock](./blocks/PromoFeaturesBlock.md) — Renders a masonry layout of promotional feature cards, each pairing a title, YFM text, and an optional media asset, displayed against a full-width background. Use it for marketing sections that showcase several value propositions with rich imagery in a non-uniform grid.
+- [Questions](./blocks/Questions.md) — Renders an FAQ block: a left content panel (title, text, links, buttons) and a list of expandable question/answer rows on the right. Automatically emits FAQPage JSON-LD microdata so search engines can index the answers as rich results.
+- [Share](./blocks/Share.md) — Renders a row of social-network share buttons that share the current page URL.
+- [Slider](./blocks/Slider.md) — 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.
+- [SliderOld](./blocks/SliderOld.md)
+- [Table](./blocks/Table.md) — 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.
+- [Tabs](./blocks/Tabs.md) — 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.
+
+## Sub-blocks
+
+- [BackgroundCard](./sub-blocks/BackgroundCard.md) — 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.
+- [BannerCard](./sub-blocks/BannerCard.md) — A compact banner card with a title, optional subtitle, a single call-to-action button, and a decorative background image. Designed to draw attention inside a card layout.
+- [BasicCard](./sub-blocks/BasicCard.md) — A general-purpose card with an optional icon (image or Gravity UI icon) and text content (title, text, links, buttons, or a content list). The simplest and most versatile card.
+- [Content](./sub-blocks/Content.md) — A text content block rendering a title, body text, additional info, links, buttons, and/or an icon content list. Used on its own as the textual portion of a content layout.
+- [Divider](./sub-blocks/Divider.md) — A spacing/separator element that adds vertical space between sibling items, optionally drawing a horizontal line. Useful for tuning rhythm inside a layout.
+- [HubspotForm](./sub-blocks/HubspotForm.md) — Embeds a HubSpot form inside a page. Loads the HubSpot scripts on demand and renders the form into a container; emits analytics events on submit and supports default field values and form event handlers.
+- [ImageCard](./sub-blocks/ImageCard.md) — A card pairing a foreground image with text content (title, text, links, buttons, or a content list). The image and content can be ordered in either direction.
+- [LayoutItem](./sub-blocks/LayoutItem.md) — Renders a two-part card: a media area (image, video, YouTube, etc.) stacked above a text content area with optional title, body, buttons, links, list, and meta info. Used as the primary content unit inside card-grid blocks.
+- [MediaCard](./sub-blocks/MediaCard.md) — Wraps a single media element (image, image slider, video, YouTube, iframe, or DataLens) inside a card with an optional border. Pure media card — no text content.
+- [PriceCard](./sub-blocks/PriceCard.md) — Renders a pricing card: a title, a price (with optional period and details), a description, a checklist of features, and optional buttons and links. Typically placed in a grid to compare plans.
+- [PriceDetailed](./sub-blocks/PriceDetailed.md)
+- [Quote](./sub-blocks/Quote.md) — Renders a customer testimonial / quote card: a logo, the quote body, an optional author (name + avatar + description), and an optional CTA button. Paired with a large image on the side.

package/build/docs/blocks/Banner.md

@@ -0,0 +1,59 @@
+# Banner
+
+Renders a compact promotional card with a title, subtitle, an optional background image or color, and a single call-to-action button. Use it to highlight a feature, announce a release, or drive traffic to a landing page from anywhere in the page flow.
+
+## Block type
+
+`type: 'banner-block'`
+
+## When to use
+
+- Mid-page promotional card with a clear single CTA.
+- When you need a compact, image-rich block that fits alongside other content.
+- As a stand-alone banner or as a card inside grid-based layouts (also registered as `banner-card`).
+
+## Example
+
+```json
+{
+  "type": "banner-block",
+  "title": "Lorem ipsum dolor sit amet, consectetur adipiscing elit",
+  "subtitle": "Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris.",
+  "image": {
+    "light": "/images/banner-light.png",
+    "dark": "/images/banner-dark.png"
+  },
+  "color": {"light": "#EFF2F8", "dark": "#262626"},
+  "button": {
+    "text": "Learn more",
+    "url": "https://example.com"
+  }
+}
+```
+
+## Properties
+
+| Property            | Type                      | Default | Description                                            |
+| ------------------- | ------------------------- | ------- | ------------------------------------------------------ |
+| `title` _required_  | `string`                  | —       | Banner heading text.                                   |
+| `button` _required_ | `ButtonBlock`             | —       | Single call-to-action button. Requires `text` + `url`. |
+| `subtitle`          | `string`                  | —       | YFM body text rendered under the title.                |
+| `image`             | `string \| {light, dark}` | —       | Background image URL (or themed pair).                 |
+| `mediaView`         | `'fit' \| 'full'`         | —       | How the background image fits the card.                |
+| `disableCompress`   | `boolean`                 | —       | Disables image compression for the background.         |
+| `color`             | `string \| {light, dark}` | —       | Background color of the card.                          |
+| `theme`             | `'light' \| 'dark'`       | —       | Forces a light or dark color scheme.                   |
+| `width`             | `'s' \| 'm' \| 'l'`       | —       | Card width preset.                                     |
+| `animated`          | `boolean`                 | —       | Enables an entrance animation.                         |
+
+### 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` and `color` each accept either a plain value or a `{light, dark}` object resolved against the active runtime theme.
+
+## Storybook
+
+[Banner](https://preview.gravity-ui.com/page-constructor/?path=/docs/blocks-banner--docs)

package/build/docs/blocks/CardLayout.md

@@ -0,0 +1,79 @@
+# CardLayout
+
+Renders a responsive grid of arbitrary cards (children) with an optional header and a decorative background image. Use it whenever you need to lay out a homogeneous set of cards — basic, image, background, price, or layout-item — in a row that adapts to the viewport.
+
+## Block type
+
+`type: 'card-layout-block'`
+
+## When to use
+
+- Displaying a set of cards that should reflow across desktop, tablet, and mobile.
+- When you need a title/description above a card row, optionally centered.
+- When the card row needs a decorative background image (with or without a border/shadow).
+
+## Example
+
+```json
+{
+  "type": "card-layout-block",
+  "title": "Card layout with basic cards",
+  "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.",
+  "colSizes": {"all": 12, "sm": 6, "md": 4},
+  "children": [
+    {
+      "type": "basic-card",
+      "title": "Tell a story and build a narrative",
+      "text": "We are all storytellers. Stories are a powerful way to communicate ideas and share information.",
+      "icon": "/story-assets/icon_1_light.svg"
+    },
+    {
+      "type": "basic-card",
+      "title": "Reach your audience",
+      "text": "The right story can lead to a better understanding of a situation, make us laugh, or even inspire us.",
+      "icon": "/story-assets/icon_2_light.svg"
+    },
+    {
+      "type": "basic-card",
+      "title": "Inspire action",
+      "text": "Use a clear narrative to drive your visitors toward the next step.",
+      "icon": "/story-assets/icon_3_light.svg"
+    }
+  ]
+}
+```
+
+## Properties
+
+| Property      | Type                                                                     | Default                   | Description                                                                                                                          |
+| ------------- | ------------------------------------------------------------------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `title`       | `string \| TitleProps`                                                   | —                         | Block heading (string or Title options). Rendered above the cards.        |
+| `description` | `string`                                                                 | —                         | YFM subtitle shown under the title.                                                                                                  |
+| `colSizes`    | `{all?, sm?, md?, lg?, xl?}` (each `number` 1–12)                        | `{all: 12, sm: 6, md: 4}` | Column width per breakpoint. 12 = full width.                                                                                        |
+| `background`  | `ImageBaseObjectProps \| ImageDeviceProps` (each with optional `border`) | —                         | Decorative background media behind the card row. Supports a `{light, dark}` themed object. `border`: `'none' \| 'shadow' \| 'line'`. |
+| `children`    | `CardBlock[]`                                                            | —                         | Array of card sub-blocks to lay out (see _Children / sub-blocks_).                                                                   |
+| `animated`    | `boolean`                                                                | —                         | Enables entrance animation for the block.                                                                                            |
+
+### 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
+
+`children` accepts an array of any card sub-block registered under the `cards` definition. The following are commonly used:
+
+- `basic-card` — Basic card
+- `image-card` — Image card
+- `background-card` — Background card
+- `price-card` — Price card
+- `layout-item` — Media + content card (used by the `Layout` block)
+
+Each child is rendered inside a grid column sized by `colSizes`.
+
+## Themed values
+
+`background` (and any themed value on children) accepts either a plain value or a `{light, dark}` object resolved against the active runtime theme.
+
+## Storybook
+
+[CardLayout](https://preview.gravity-ui.com/page-constructor/?path=/docs/blocks-cardlayout--docs)

package/build/docs/blocks/Companies.md

@@ -0,0 +1,67 @@
+# Companies
+
+Renders a heading with a logo strip — a set of responsive images (desktop / tablet / mobile) shown beneath an optional title and description. Use it for "trusted by" or "powered by" logo rows that must adapt per device and theme.
+
+## Block type
+
+`type: 'companies-block'`
+
+## When to use
+
+- Showcasing a row of company or partner logos with per-device artwork.
+- "Trusted by" / "powered by" sections that need light and dark theme variants of the same logos.
+- A compact brand strip paired with a short title and optional YFM description.
+
+## Example
+
+```json
+{
+  "type": "companies-block",
+  "title": "Page constructor",
+  "description": "**Ut enim ad minim veniam** [quis nostrud](https://example.com) exercitation ullamco laboris.",
+  "images": {
+    "light": {
+      "desktop": "/images/logo-desktop-light.svg",
+      "tablet": "/images/logo-tablet-light.svg",
+      "mobile": "/images/logo-mobile-light.svg",
+      "alt": "Page constructor"
+    },
+    "dark": {
+      "desktop": "/images/logo-desktop-dark.svg",
+      "tablet": "/images/logo-tablet-dark.svg",
+      "mobile": "/images/logo-mobile-dark.svg",
+      "alt": "Page constructor"
+    }
+  }
+}
+```
+
+## Properties
+
+| Property            | Type                                | Default | Description                             |
+| ------------------- | ----------------------------------- | ------- | --------------------------------------- |
+| `title` _required_  | `string`                            | —       | Section heading (plain text).           |
+| `images` _required_ | `ImageDeviceProps \| {light, dark}` | —       | Responsive logo set. See below.         |
+| `description`       | `string`                            | —       | YFM body text rendered under the title. |
+| `animated`          | `boolean`                           | —       | Enables an entrance animation.          |
+
+### `images`
+
+| Property             | Type     | Default | Description                              |
+| -------------------- | -------- | ------- | ---------------------------------------- |
+| `desktop` _required_ | `string` | —       | Image URL for desktop viewports.         |
+| `tablet` _required_  | `string` | —       | Image URL for tablet viewports.          |
+| `mobile` _required_  | `string` | —       | Image URL for mobile viewports.          |
+| `alt`                | `string` | —       | Alternative text for the rendered image. |
+
+### Common properties
+
+Inherits: `when`, `animated`. See the root README for details. (This block does not expose `anchor`, `visible`, `indent`, `theme`, or `context`.)
+
+## Themed values
+
+`images` accepts either a plain `ImageDeviceProps` object or a `{light, dark}` object resolved against the active runtime theme.
+
+## Storybook
+
+[Companies](https://preview.gravity-ui.com/page-constructor/?path=/docs/blocks-companies--docs)

package/build/docs/blocks/ContentLayout.md

@@ -0,0 +1,54 @@
+# ContentLayout
+
+Renders a single-column content section (title, body text, optional list, links, and buttons) paired with an optional list of downloadable files and a background. Use it for documentation-style sections, terms, descriptions, or anywhere a focused block of text with file attachments is needed.
+
+## Block type
+
+`type: 'content-layout-block'`
+
+## When to use
+
+- Documentation, "about", legal, or descriptive sections where text is the main asset.
+- When you need a list of attached files (PDF, DOC, ZIP, etc.) alongside the text.
+- When you want a centered text column over a colored or image background.
+
+## Example
+
+```json
+{
+  "type": "content-layout-block",
+  "size": "l",
+  "theme": "default",
+  "textWidth": "m",
+  "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.",
+    "buttons": [{"text": "Primary", "theme": "action", "url": "https://example.com"}]
+  },
+  "fileContent": [{"href": "https://example.com/spec.pdf", "text": "Specification (PDF)"}]
+}
+```
+
+## Properties
+
+| Property      | Type                             | Default     | Description                                                                                                                                                                               |
+| ------------- | -------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `textContent` | `ContentBlock`                   | —           | Inner content object: `title` (string or `TitleProps`), `text` (YFM), `additionalInfo` (YFM), `links`, `buttons`, `list`, `theme`, `size`, `controlPosition`, `centered`, and `colSizes`. |
+| `fileContent` | `FileLinkProps[]`                | —           | List of file attachments rendered as horizontal file links. Each item supports `href`, `text`, and other `FileLinkProps`.                                                                 |
+| `size`        | `'s' \| 'm' \| 'l' \| 'xl'`      | `'l'`       | Overall content scale; also drives file-link text size.                                                                                                                                   |
+| `background`  | `BackgroundImageProps`           | —           | Optional background image/color, hidden on mobile.                                                                                                                                        |
+| `centered`    | `boolean`                        | `false`     | Centers the text column and file list.                                                                                                                                                    |
+| `theme`       | `'default' \| 'light' \| 'dark'` | `'default'` | Color scheme; `default` follows the runtime theme.                                                                                                                                        |
+| `textWidth`   | `'s' \| 'm' \| 'l'`              | `'m'`       | Maximum width of the text column on desktop.                                                                                                                                              |
+
+### 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
+
+None of the top-level ContentLayout props accept `{light, dark}` directly; the `background` value is resolved against the runtime theme internally.
+
+## Storybook
+
+[ContentLayout](https://preview.gravity-ui.com/page-constructor/?path=/docs/blocks-contentlayout--docs)

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)