@dextinity/agent-features 10.0.1 → 10.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dextinity/agent-features",
-  "version": "10.0.1",
+  "version": "10.1.0",
   "description": "Agent features (skills and rules) for Dextinity projects",
   "repository": {
     "directory": "packages/agent-features",

package/skills/dextinity-block/references/rich-text.md

@@ -208,6 +208,8 @@ blocktypeMap: {
 
 When `standardBlockType` is set to something other than `"unstyled"`, the `"unstyled"` block type is hidden from the dropdown.
 
+A custom block type that should render as a **list** needs a `renderConfig` with its own `wrapper` element and `element: "li"`. When the field renders into an email, it also needs a matching `list` entry in the mail block's `blockTypes`. See [`dextinity-mail-react/references/rich-text-list-block-types.md`](../../dextinity-mail-react/references/rich-text-list-block-types.md).
+
 ### Relabeling Existing Block Types
 
 Override just `label` to rename existing types without changing behavior:

package/skills/dextinity-mail-react/SKILL.md

@@ -451,11 +451,14 @@ Key behaviors:
     ```
 
 - **Lists** render as a table inside one text component, with a row per item, a marker cell and a text cell — the indent and the marker gap are cell padding, which is the only spacing Outlook on Windows applies reliably.
+- **A block type is a list when it declares a kind**: `{ variant: "copyLarge", list: "unordered" }`. `unordered-list-item` and `ordered-list-item` are draft-js's own list types, and they default to their kind. Every other block type is a paragraph unless it sets `list`. Use it for a list in a second text variant. A draft block has only one block type, so that list needs a custom block type. One `createRichTextBlock` call renders every variant. Two adjacent list block types render as two tables, and the numbered one starts again at `1.` Draft-js indents `unordered-list-item` and `ordered-list-item` only, so an editor cannot nest a custom list block type.
 - **List spacing** comes from the theme's `list.indent` (before the marker), `list.markerGap` (between the marker and the text) and `list.itemSpacing` (between items, and above a nested level's first item), all responsive and all applying to every list the block renders. To override it, register a rule scoped to a list's type, depth or variant modifier with `{ inline: true }`, which has MJML write the declaration into the cell's `style` attribute at compile time so it also reaches Outlook.
 - **List markers** come from the theme's `list.unorderedMarker` and `list.orderedMarker`, each either a fixed node (`unorderedMarker: "▪"`) or a function of the item's `index` and its list's `depth`.
 - Spacing between blocks comes from the theme's `bottomSpacing` (the last block gets none); headings are styled text, not semantic `<h1>` elements.
 - Rendered elements carry `richTextBlock__text`, `richTextBlock__list`, `richTextBlock__listItem`, `richTextBlock__listItemMarker`, `richTextBlock__listItemText`, and `richTextBlock__link` class names for targeting with `registerStyles`. The list table also carries `richTextBlock__list--ordered` or `richTextBlock__list--unordered`, and `richTextBlock__list--depth<Level>` naming its nesting level, counting the outermost as zero, with `richTextBlock__list--nested` on every level below that one. Only the outermost table names the text variant its items render with, such as `richTextBlock__list--variantBody`, and a rule scoped to that modifier applies to the nested levels as well. The rows carry `richTextBlock__listItem--itemSpacing`, or `richTextBlock__listItem--blockSpacing` on the last row when spacing follows the list, and `richTextBlock__listItem--itemSpacingAbove` on a nested level's first row, which carries the item spacing as `padding-top`. The cells restate the text styles inline, so a rule targeting list text needs `!important`.
 
+→ To register a custom list block type across the admin RTE and the mail block, read [`references/rich-text-list-block-types.md`](references/rich-text-list-block-types.md).
+
 ---
 
 ## Custom Components

package/skills/dextinity-mail-react/references/rich-text-list-block-types.md

@@ -0,0 +1,83 @@
+# Rich-text list block types
+
+A list in a second text variant needs a custom block type, for example `unordered-list-item-small`. Register it in the admin RTE and in the mail block.
+
+## 1. Admin RTE
+
+Add the block type to `rte.blocktypeMap` on the CMS `createRichTextBlock`. For the surrounding options, see the `dextinity-block` skill's [rich-text reference](../../dextinity-block/references/rich-text.md).
+
+```tsx
+blocktypeMap: {
+    "unordered-list-item": {
+        label: <FormattedMessage id="…" defaultMessage="Unordered List (Default)" />,
+        group: "dropdown",
+    },
+    "unordered-list-item-small": {
+        label: <FormattedMessage id="…" defaultMessage="Unordered List (Small)" />,
+        renderConfig: { wrapper: <Typography variant="body2" component="ul" className="public-DraftStyleDefault-ul" />, element: "li" },
+    },
+    "ordered-list-item": {
+        label: <FormattedMessage id="…" defaultMessage="Ordered List (Default)" />,
+        group: "dropdown",
+    },
+    "ordered-list-item-small": {
+        label: <FormattedMessage id="…" defaultMessage="Ordered List (Small)" />,
+        renderConfig: { wrapper: <Typography variant="body2" component="ol" className="public-DraftStyleDefault-ol" />, element: "li" },
+    },
+},
+```
+
+- Set `group: "dropdown"` on `unordered-list-item` and `ordered-list-item`. This moves the two built-in toolbar buttons into the block-type select, beside the custom list types. The toolbar keeps no list button.
+- Give each label the list kind and the variant, such as `Ordered List (Default)`. A label that only names the variant hides the kind of list.
+- Keep `unordered-list` and `ordered-list` in `supports`. The select hides a built-in list type without them.
+- Give each block type its own `wrapper` element. Draft-js merges a run of blocks into one list when two block types share one element.
+- Make the `wrapper` a `Typography` with the admin theme variant closest to the mail variant. Set `component` to `ul` or `ol`. Every list looks the same in the editor without it, and the `<li>` elements inherit the styles.
+- Keep the `public-DraftStyleDefault-ul` or `-ol` class on the `wrapper`. It removes the browser's list padding, which draft-js adds again on each `<li>` for the nesting level.
+- Set `element` to the plain string `"li"`. A component in its place loses draft-js's list styling.
+- Do not set `supportedBy` on a custom block type. Its values are a closed union, and a block type without it is always available.
+
+## 2. Mail block
+
+Map the same names in `createRichTextBlock`, each with its list kind and a theme text variant:
+
+```tsx
+const { MjmlRichTextBlock } = createRichTextBlock({
+    blockTypes: {
+        "unordered-list-item": { variant: "copy" },
+        "ordered-list-item": { variant: "copy" },
+        "unordered-list-item-small": { variant: "copySmall", list: "unordered" },
+        "ordered-list-item-small": { variant: "copySmall", list: "ordered" },
+    },
+});
+```
+
+The variant must exist in `text.variants` and in the `TextVariants` module augmentation. `unordered-list-item` and `ordered-list-item` take no `list`.
+
+## Spacing per variant
+
+`theme.list` applies to every list. For one variant, scope a rule to that variant's modifier on the list table:
+
+```tsx
+registerStyles(
+    css`
+        .richTextBlock__list--variantCopySmall .richTextBlock__listItem--itemSpacing > td {
+            padding-bottom: 4px !important;
+        }
+
+        .richTextBlock__list--variantCopySmall .richTextBlock__listItemMarker {
+            padding-right: 8px !important;
+        }
+    `,
+    { inline: true },
+);
+```
+
+- A row with `richTextBlock__listItem--itemSpacing` carries `list.itemSpacing` as `padding-bottom` on both of its cells. Target `> td` to keep the marker level with the text. The last row of a list carries no such class, so the spacing below the list stays with the theme.
+- The marker cell carries `list.markerGap` as `padding-right`, and `list.indent` as `padding-left`.
+- `{ inline: true }` writes the declaration into each cell's `style` attribute at compile time, which Outlook needs. Every rule needs `!important`, because the cells carry their own spacing inline.
+
+## Limits
+
+- An editor cannot indent a custom list block type. Draft-js and the RTE's indent controls handle `unordered-list-item` and `ordered-list-item` only.
+- A nested level takes the font styles of the list that contains it. It cannot have its own variant.
+- A custom ordered list uses the browser's `<ol>` numbering in the editor, not draft-js's counters.