@gravity-ui/page-constructor 8.14.2 → 8.16.0

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

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

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

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

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

@@ -0,0 +1,57 @@
+# BannerCard
+
+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.
+
+## Sub-block type
+
+`type: 'banner-card'`
+
+> The schema for this sub-block is defined in `src/blocks/Banner/schema.ts` (`BannerCardProps`) and shared with the standalone `banner-block`.
+
+## Used in
+
+Accepted as a child of: `card-layout-block`, `slider-block`, `slider-old-block`.
+
+## Example
+
+```json
+{
+  "type": "banner-card",
+  "title": "Try the new release",
+  "subtitle": "Faster builds, simpler APIs, and improved theming.",
+  "image": {
+    "light": "/story-assets/banner_light.png",
+    "dark": "/story-assets/banner_dark.png"
+  },
+  "color": "#0275d8",
+  "theme": "light",
+  "mediaView": "full",
+  "button": {
+    "text": "Get started",
+    "url": "https://example.com",
+    "target": "_blank",
+    "theme": "raised"
+  }
+}
+```
+
+## Properties
+
+| Property            | Type                      | Default   | Description                                                                                                                                       |
+| ------------------- | ------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `type` _required_   | `'banner-card'`           | —         | Sub-block discriminator.                                                                                                                          |
+| `when`              | `string`                  | —         | Conditional rendering expression.                                                                                                                 |
+| `animated`          | `boolean`                 | —         | Enables entrance animation.                                                                                                                       |
+| `title` _required_  | `string`                  | —         | Banner heading (rendered as `<h2>`, plain text).                                                                                                  |
+| `subtitle`          | `string`                  | —         | Secondary text (YFM supported).                                                                                                                   |
+| `image`             | `string \| {light, dark}` | —         | Decorative background image URL (themed).                                                                                                         |
+| `mediaView`         | `'fit' \| 'full'`         | `'full'`  | How the background media fills the banner.                                                                                                        |
+| `disableCompress`   | `boolean`                 | —         | Disables image compression for `image`.                                                                                                           |
+| `color`             | `string \| {light, dark}` | —         | Background color (CSS value, themed). Applied to the content layer.                                                                               |
+| `theme`             | `'light' \| 'dark'`       | `'light'` | Text color theme.                                                                                                                                 |
+| `width`             | `'s' \| 'm' \| 'l'`       | —         | Banner width.                                                                                                                                     |
+| `button` _required_ | `ButtonProps`             | —         | Single call-to-action button. Uses only `text`, `url`, `target`, `theme` (`'raised'` by default). |
+
+## Themed values
+
+`image` and `color` each accept either a plain value or a `{light, dark}` object resolved against the active runtime theme.

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

@@ -0,0 +1,60 @@
+# BasicCard
+
+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.
+
+## Sub-block type
+
+`type: 'basic-card'`
+
+## Used in
+
+Accepted as a child of: `card-layout-block`, `slider-block`, `slider-old-block`.
+
+## Example
+
+```json
+{
+  "type": "basic-card",
+  "title": "Tell a story",
+  "text": "**Ut enim ad minim veniam** [quis nostrud](https://example.com) exercitation ullamco.",
+  "icon": {
+    "light": "/story-assets/icon_1_light.svg",
+    "dark": "/story-assets/icon_1_dark.svg"
+  },
+  "iconPosition": "top",
+  "url": "https://example.com",
+  "urlTitle": "Opens in a new tab",
+  "buttons": [{"text": "Read more", "theme": "action", "url": "https://example.com"}]
+}
+```
+
+## Properties
+
+| Property               | Type                                         | Default     | Description                                                                                              |
+| ---------------------- | -------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------- |
+| `type` _required_      | `'basic-card'`                               | —           | Sub-block discriminator.                                                                                 |
+| `when`                 | `string`                                     | —           | Conditional rendering expression.                                                                        |
+| `title`                | `string \| TitleProps`                       | —           | Card title (plain string or Title options).   |
+| `text`                 | `string`                                     | —           | Body text (YFM supported).                                                                               |
+| `additionalInfo`       | `string`                                     | —           | Secondary gray text (YFM supported).                                                                     |
+| `size`                 | `'s' \| 'm' \| 'l' \| 'xl'`                  | `'s'`       | Content size; controls font sizes.                                                                       |
+| `links`                | `LinkProps[]`                                | —           | Array of links.                                            |
+| `buttons`              | `ButtonProps[]`                              | —           | Array of buttons.                                        |
+| `list`                 | `ContentItem[]`                              | —           | Array of icon-content items (each requires `icon` or `gravityIcon`).                                     |
+| `border`               | `'line' \| 'shadow' \| 'none'`               | —           | Card border style.                                                                                       |
+| `controlPosition`      | `'content' \| 'footer'`                      | `'content'` | Position of buttons/links inside the card.                                                               |
+| `url`                  | `string`                                     | —           | Wraps the whole card in a link.                                                                          |
+| `urlTitle`             | `string`                                     | —           | `title` attribute for the card link.                                                                     |
+| `target`               | `'_blank' \| '_parent' \| '_top' \| '_self'` | —           | Link target.                                                                                             |
+| `icon`                 | `ImageProps`                                 | —           | Leading icon image (URL string, object, or device-aware object).                                         |
+| `gravityIcon`          | `GravityIconProps`                           | —           | Leading Gravity UI icon (`string` name, or `{name, color?}` where `color` is `'brand' \| 'text-color'`). |
+| `iconPosition`         | `'top' \| 'left'`                            | `'top'`     | Position of the icon relative to the content.                                                            |
+| `hoverBackgroundColor` | `string`                                     | —           | _Deprecated._ Background color/gradient applied on hover.                                                |
+
+## Themed values
+
+`icon` and `gravityIcon` accept either a plain value or a `{light, dark}` object resolved against the active runtime theme.
+
+## Storybook
+
+[BasicCard](https://preview.gravity-ui.com/page-constructor/?path=/docs/components-cards-basiccard--docs)

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

@@ -0,0 +1,58 @@
+# Content
+
+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.
+
+## Sub-block type
+
+`type: 'content'`
+
+## Used in
+
+Accepted as `textContent` of: `content-layout-block`.
+
+## Example
+
+```json
+{
+  "type": "content",
+  "title": "Lorem ipsum",
+  "text": "**Ut enim ad minim veniam** [quis nostrud](https://example.com) exercitation ullamco laboris.",
+  "additionalInfo": "Duis aute irure dolor in reprehenderit.",
+  "size": "l",
+  "centered": false,
+  "links": [{"url": "#", "text": "Link", "theme": "normal", "arrow": true}],
+  "buttons": [{"text": "Button", "theme": "action", "url": "https://example.com"}],
+  "list": [
+    {
+      "icon": {"light": "/story-assets/icon_1_light.svg", "dark": "/story-assets/icon_1_dark.svg"},
+      "title": "Lorem ipsum",
+      "text": "Ut enim ad minim veniam quis nostrud exercitation."
+    }
+  ]
+}
+```
+
+## Properties
+
+| Property          | Type                                              | Default            | Description                                                                                         |
+| ----------------- | ------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------- |
+| `type` _required_ | `'content'`                                       | —                  | Sub-block discriminator.                                                                            |
+| `title`           | `string \| TitleProps`                            | —                  | Heading (plain string or Title options). |
+| `text`            | `string`                                          | —                  | Body text (YFM supported).                                                                          |
+| `additionalInfo`  | `string`                                          | —                  | Secondary gray text (YFM supported).                                                                |
+| `size`            | `'s' \| 'm' \| 'l' \| 'xl'`                       | `'l'`              | Content size; controls font sizes.                                                                  |
+| `centered`        | `boolean`                                         | `false`            | Centers all content horizontally.                                                                   |
+| `theme`           | `'default' \| 'dark' \| 'light'`                  | —                  | Content theme.                                                                                      |
+| `links`           | `LinkProps[]`                                     | —                  | Array of links.                                       |
+| `buttons`         | `ButtonProps[]`                                   | —                  | Array of buttons.                                   |
+| `list`            | `ContentItem[]`                                   | —                  | Array of icon-content items (each requires `icon` or `gravityIcon`).                                |
+| `controlPosition` | `'default' \| 'bottom'`                           | `'default'`        | Position of buttons/links.                                                                          |
+| `colSizes`        | `{all?, sm?, md?, lg?, xl?}` (each `number` 1–12) | `{all: 12, sm: 8}` | Column width per breakpoint.                                                                        |
+
+## Themed values
+
+`icon`/`gravityIcon` inside `list` items accept either a plain value or a `{light, dark}` object resolved against the active runtime theme.
+
+## Storybook
+
+[Content](https://preview.gravity-ui.com/page-constructor/?path=/docs/components-content--docs)

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

@@ -0,0 +1,47 @@
+# Divider
+
+A spacing/separator element that adds vertical space between sibling items, optionally drawing a horizontal line. Useful for tuning rhythm inside a layout.
+
+## Sub-block type
+
+`type: 'divider'`
+
+## Used in
+
+Registered both as a sub-block and as a standalone block; appears in the page `blocks` array.
+
+## Example
+
+```json
+{
+  "type": "divider",
+  "size": "m"
+}
+```
+
+With a horizontal line:
+
+```json
+{
+  "type": "divider",
+  "size": "l",
+  "border": true
+}
+```
+
+## Properties
+
+| Property          | Type                                                                   | Default | Description                                                       |
+| ----------------- | ---------------------------------------------------------------------- | ------- | ----------------------------------------------------------------- |
+| `type` _required_ | `'divider'`                                                            | —       | Sub-block discriminator.                                          |
+| `when`            | `string`                                                               | —       | Conditional rendering expression.                                 |
+| `size`            | `'0' \| 'xxs' \| 'xs' \| 's' \| 'm' \| 'l' \| 'xl' \| 'xxl' \| 'xxxl'` | `'m'`   | Vertical height of the divider. `'0'` collapses spacing entirely. |
+| `border`          | `boolean`                                                              | —       | When `true`, draws a horizontal line across the full width.       |
+
+## Themed values
+
+None — `Divider` has no themed properties.
+
+## Storybook
+
+[Divider](https://preview.gravity-ui.com/page-constructor/?path=/docs/components-divider--docs)

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

@@ -0,0 +1,47 @@
+# HubspotForm
+
+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.
+
+## Sub-block type
+
+`type: 'hubspot-form'`
+
+## Used in
+
+Accepted as `children` by `CardLayout`, `Slider`, `SliderOld`; also usable inside any block that renders sub-blocks (e.g. `FilterBlock` items).
+
+## Example
+
+```json
+{
+  "type": "hubspot-form",
+  "region": "eu1",
+  "portalId": "25764979",
+  "formId": "a3eb06a6-e8ce-45d4-81bd-7fadb7dab313"
+}
+```
+
+## Properties
+
+| Property              | Type             | Default | Description                                                                      |
+| --------------------- | ---------------- | ------- | -------------------------------------------------------------------------------- |
+| `type` _required_     | `'hubspot-form'` | —       | Sub-block discriminator.                                                         |
+| `when`                | `string`         | —       | Conditional rendering expression.                                                |
+| `portalId` _required_ | `string`         | —       | HubSpot portal ID.                                                               |
+| `formId` _required_   | `string`         | —       | HubSpot form ID.                                                                 |
+| `region`              | `string`         | —       | HubSpot region (e.g. `'eu1'`, `'na1'`).                                          |
+| `formInstanceId`      | `string`         | —       | Unique instance ID, required to render the same form multiple times on one page. |
+
+Additional runtime-only props (`className`, `theme`, `isMobile`, `formClassName`, `createDOMElement`, `defaultValues`, `onBeforeLoad` / `onBeforeSubmit` / `onSubmit` / `onLoad` / `hubspotEvents`) are available on the React component but are not part of the JSON schema.
+
+## Setup notes
+
+HubSpot forms require the `formsContext` to be configured on `PageConstructorProvider`. The context wires form event handling and any HubSpot-specific runtime configuration; without it, submit analytics and the `onSubmit` / `onBeforeSubmit` / `onLoad` handlers wired through `useHandleHubspotEvents` will not fire. When the form is rendered inside an iframe, set up the `useLoopBackHubspotEvents` hook on the top-level frame so events propagate.
+
+## Themed values
+
+No themed media fields; theme is taken from the active theme context (or the `theme` runtime prop).
+
+## Storybook
+
+[HubspotForm](https://preview.gravity-ui.com/page-constructor/?path=/docs/components-hubspotform--docs)

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

@@ -0,0 +1,59 @@
+# ImageCard
+
+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.
+
+## Sub-block type
+
+`type: 'image-card'`
+
+## Used in
+
+Accepted as a child of: `card-layout-block`, `slider-block`, `slider-old-block`.
+
+## Example
+
+```json
+{
+  "type": "image-card",
+  "title": "Tell a story and build a narrative",
+  "text": "We are all storytellers. Stories are a powerful way to communicate ideas.",
+  "image": {
+    "dark": "/story-assets/img_8-12_dark.png",
+    "light": "/story-assets/img_8-12_light.png"
+  },
+  "direction": "direct",
+  "border": "shadow"
+}
+```
+
+## Properties
+
+| Property           | Type                                 | Default     | Description                                                                                            |
+| ------------------ | ------------------------------------ | ----------- | ------------------------------------------------------------------------------------------------------ |
+| `type` _required_  | `'image-card'`                       | —           | Sub-block discriminator.                                                                               |
+| `when`             | `string`                             | —           | Conditional rendering expression.                                                                      |
+| `image` _required_ | `ImageProps`                         | —           | Foreground image (URL string, object, or device-aware object).                                         |
+| `title`            | `string \| TitleProps`               | —           | Card title (plain string or Title options). |
+| `text`             | `string`                             | —           | Body text (YFM supported).                                                                             |
+| `additionalInfo`   | `string`                             | —           | Secondary gray text (YFM supported).                                                                   |
+| `size`             | `'s' \| 'm' \| 'l' \| 'xl'`          | `'s'`       | Content size; controls font sizes.                                                                     |
+| `theme`            | `'default' \| 'dark' \| 'light'`     | `'default'` | Content theme.                                                                                         |
+| `links`            | `LinkProps[]`                        | —           | Array of links.                                          |
+| `buttons`          | `ButtonProps[]`                      | —           | Array of buttons.                                      |
+| `list`             | `ContentItem[]`                      | —           | Array of icon-content items (each requires `icon` or `gravityIcon`).                                   |
+| `border`           | `'line' \| 'shadow' \| 'none'`       | `'shadow'`  | Card border style.                                                                                     |
+| `controlPosition`  | `'content' \| 'footer'`              | `'content'` | Position of buttons/links inside the card.                                                             |
+| `direction`        | `'direct' \| 'reverse'`              | `'direct'`  | Image/content order: `direct` = image first, `reverse` = content first.                                |
+| `margins`          | `'s' \| 'm'`                         | —           | Internal margins around the image.                                                                     |
+| `backgroundColor`  | `string`                             | —           | Solid background color (CSS value).                                                                    |
+| `url`              | `string`                             | —           | Wraps the whole card in a link.                                                                        |
+| `urlTitle`         | `string`                             | —           | `title` attribute for the card link.                                                                   |
+| `analyticsEvents`  | `AnalyticsEvent \| AnalyticsEvent[]` | —           | Analytics events fired on card interaction.                                                            |
+
+## Themed values
+
+`image` accepts either a plain value or a `{light, dark}` object resolved against the active runtime theme.
+
+## Storybook
+
+[ImageCard](https://preview.gravity-ui.com/page-constructor/?path=/docs/components-cards-imagecard--docs)