123
\n456
`. */ +static bool is_layout_whitespace(GumboNode *node) { + if (node->type != GUMBO_NODE_WHITESPACE) + return false; + char buf[64]; + const char *parent_name = get_tag_name(node->parent, buf, sizeof(buf)); + return parent_name && + (has_block_or_bq_child(node->parent) || + (is_table_tag(parent_name) && !is_table_text_tag(parent_name))); +} + /** * Flush buffered inline content as a. Inter-block whitespace (newlines / * spaces between block tags in pretty-printed HTML) is discarded so it does @@ -584,20 +719,22 @@ static bool flush_inline_p(buffer_t *ib, buffer_t *out, return emitted; } -static void flatten_bq_children(GumboNode *node, buffer_t *ib, buffer_t *out) { +static void flatten_bq_children(GumboNode *node, buffer_t *ib, buffer_t *out, + const custom_style_t *inherited) { if (!is_element(node)) return; GumboVector *children = &node->v.element.children; for (unsigned int i = 0; i < children->length; i++) { - flatten_bq_node(children->data[i], ib, out); + flatten_bq_node(children->data[i], ib, out, inherited); } } -static void flatten_bq_node(GumboNode *node, buffer_t *ib, buffer_t *out) { +static void flatten_bq_node(GumboNode *node, buffer_t *ib, buffer_t *out, + const custom_style_t *inherited) { if (!node) return; if (is_text(node)) { - walk_node(node, ib); + walk_node(node, ib, inherited); return; } if (!is_element(node)) { @@ -613,12 +750,12 @@ static void flatten_bq_node(GumboNode *node, buffer_t *ib, buffer_t *out) { } if (is_block_producing(node) || is_blockquote_node(node)) { flush_inline_p(ib, out, NULL); - flatten_bq_children(node, ib, out); + flatten_bq_children(node, ib, out, inherited); // The flattened block becomes a
; carry over its text-align (if any). flush_inline_p(ib, out, &node->v.element); return; } - walk_node(node, ib); + walk_node(node, ib, inherited); } /* ------------------------------------------------------------------ */ @@ -632,6 +769,7 @@ typedef struct { int *nested_count; int max_nested; bool has_emitted; + const custom_style_t *inherited; } li_ctx_t; static void flatten_li_node(GumboNode *node, buffer_t *ib, buffer_t *out, @@ -670,7 +808,7 @@ static void flatten_li_node(GumboNode *node, buffer_t *ib, buffer_t *out, if (!node) return; if (is_text(node)) { - walk_node(node, ib); + walk_node(node, ib, ctx->inherited); return; } if (!is_element(node)) { @@ -705,14 +843,15 @@ static void flatten_li_node(GumboNode *node, buffer_t *ib, buffer_t *out, flush_li_buffer(ib, out, ctx); return; } - walk_node(node, ib); + walk_node(node, ib, ctx->inherited); } /* ------------------------------------------------------------------ */ /* walk_children — the main child-iteration driver */ /* ------------------------------------------------------------------ */ -static void walk_children(GumboNode *node, buffer_t *out) { +static void walk_children(GumboNode *node, buffer_t *out, + const custom_style_t *inherited) { if (!is_element(node)) return; @@ -734,7 +873,7 @@ static void walk_children(GumboNode *node, buffer_t *out) { /* Flatten list-inside-list */ if (parent_is_list && is_list_node(child)) { - walk_children(child, out); + walk_children(child, out, inherited); i++; continue; } @@ -744,7 +883,7 @@ static void walk_children(GumboNode *node, buffer_t *out) { buffer_append_str(out, "
"); buffer_t bq_ib = buffer_create(64); while (i < children->length && is_blockquote_node(children->data[i])) { - flatten_bq_children(children->data[i], &bq_ib, out); + flatten_bq_children(children->data[i], &bq_ib, out, inherited); i++; } flush_inline_p(&bq_ib, out, NULL); @@ -770,11 +909,11 @@ static void walk_children(GumboNode *node, buffer_t *out) { /* Transparent inline wrapper for block/bq children */ if (is_element(child) && has_block_or_bq_child(child)) { flush_inline_p(&ib, out, NULL); - walk_children(child, out); + walk_children(child, out, inherited); i++; continue; } - walk_node(child, &ib); + walk_node(child, &ib, inherited); i++; } flush_inline_p(&ib, out, NULL); @@ -782,7 +921,7 @@ static void walk_children(GumboNode *node, buffer_t *out) { continue; } - walk_node(child, out); + walk_node(child, out, inherited); i++; } } @@ -791,7 +930,8 @@ static void walk_children(GumboNode *node, buffer_t *out) { /* walk_node — process a single DOM node */ /* ------------------------------------------------------------------ */ -static void walk_node(GumboNode *node, buffer_t *out) { +static void walk_node(GumboNode *node, buffer_t *out, + const custom_style_t *inherited) { if (!node) return; @@ -800,6 +940,9 @@ static void walk_node(GumboNode *node, buffer_t *out) { const char *text_raw = node->v.text.text; if (text_raw) { size_t text_len = strlen(text_raw); + bool wrap = inherited && !is_layout_whitespace(node); + if (wrap) + emit_custom_style_open(out, *inherited); for (size_t i = 0; i < text_len; i++) { char c = text_raw[i]; switch (c) { @@ -817,19 +960,21 @@ static void walk_node(GumboNode *node, buffer_t *out) { break; } } + if (wrap) + buffer_append_str(out, ""); } return; } if (!is_element(node)) { - walk_children(node, out); + walk_children(node, out, inherited); return; } GumboElement *el = &node->v.element; char name_buf[64]; if (!get_tag_name(node, name_buf, sizeof(name_buf))) { - walk_children(node, out); + walk_children(node, out, inherited); return; } @@ -841,7 +986,7 @@ static void walk_node(GumboNode *node, buffer_t *out) { /* Google Docs wrapper */ if (is_google_docs_wrapper(el, name_buf)) { - walk_children(node, out); + walk_children(node, out, inherited); return; } @@ -856,9 +1001,47 @@ static void walk_node(GumboNode *node, buffer_t *out) { const char *sval = get_attr(el, "style"); size_t slen = sval ? strlen(sval) : 0; css_styles_t s = parse_css_style(sval, slen); + + // own properties override the inherited ones + custom_style_t own = s.custom; + custom_style_t style = {{NULL, 0}, {NULL, 0}, {NULL, 0}, {NULL, 0}}; + if (inherited) + style = *inherited; + if (own.fg.len) + style.fg = own.fg; + if (own.bg.len) + style.bg = own.bg; + if (own.font_size.len) + style.font_size = own.font_size; + if (own.font_family.len) + style.font_family = own.font_family; + + const custom_style_t *children_style = inherited; + bool wrap = false; + if (!custom_style_is_empty(own)) { + // if there are no nested spans deeper, we can emit a wrapper immediately, + // otherwise we hold off with that and we'll emit span tags deeper, after flattening + if (has_styled_span_descendant(node)) { + children_style = &style; + } else { + wrap = true; + children_style = NULL; + } + } + if (wrap) { + emit_custom_style_open(out, style); + } + + // handle inner formatting (, , etc.) and children emit_styles_open(out, s); - walk_children(node, out); + walk_children(node, out, children_style); emit_styles_close(out, s); + + // close the wrapper span + if (wrap) { + buffer_append_str(out, ""); + } + return; } @@ -887,7 +1070,7 @@ static void walk_node(GumboNode *node, buffer_t *out) { buffer_clear(&pb); continue; } - walk_node(dc, &pb); + walk_node(dc, &pb, inherited); } if (pb.len > 0) { buffer_append_str(out, "
"); @@ -899,20 +1082,16 @@ static void walk_node(GumboNode *node, buffer_t *out) { free(pb.data); } else { emit_styles_open(out, s); - walk_children(node, out); + walk_children(node, out, inherited); emit_styles_close(out, s); } return; } /* --- Table elements --- */ - if (strcmp(name_buf, "table") == 0 || strcmp(name_buf, "thead") == 0 || - strcmp(name_buf, "tbody") == 0 || strcmp(name_buf, "tfoot") == 0 || - strcmp(name_buf, "tr") == 0 || strcmp(name_buf, "td") == 0 || - strcmp(name_buf, "th") == 0 || strcmp(name_buf, "caption") == 0 || - strcmp(name_buf, "colgroup") == 0 || strcmp(name_buf, "col") == 0) { + if (is_table_tag(name_buf)) { if (strcmp(name_buf, "td") == 0 || strcmp(name_buf, "th") == 0) { - walk_children(node, out); + walk_children(node, out, inherited); /* Check if there's a next sibling element */ GumboNode *parent = node->parent; if (parent && is_element(parent)) { @@ -932,7 +1111,7 @@ static void walk_node(GumboNode *node, buffer_t *out) { } } else if (strcmp(name_buf, "tr") == 0) { buffer_t row = buffer_create(64); - walk_children(node, &row); + walk_children(node, &row, inherited); if (row.len > 0) { buffer_append_str(out, "
");
buffer_append(out, row.data, row.len);
@@ -940,7 +1119,7 @@ static void walk_node(GumboNode *node, buffer_t *out) {
}
free(row.data);
} else {
- walk_children(node, out);
+ walk_children(node, out, inherited);
}
return;
}
@@ -949,7 +1128,7 @@ static void walk_node(GumboNode *node, buffer_t *out) {
switch (cls) {
case TAG_CLASS_PASS:
case TAG_CLASS_SKIP:
- walk_children(node, out);
+ walk_children(node, out, inherited);
break;
case TAG_CLASS_SELF_CLOSING:
@@ -970,7 +1149,8 @@ static void walk_node(GumboNode *node, buffer_t *out) {
GumboNode *nested_lists[16];
int nested_count = 0;
buffer_t li_ib = buffer_create(64);
- li_ctx_t ctx = {el, es, nested_lists, &nested_count, 16};
+ li_ctx_t ctx = {el, es, nested_lists, &nested_count,
+ 16, false, inherited};
flatten_li_children(node, &li_ib, out, &ctx);
flush_li_buffer(&li_ib, out, &ctx);
@@ -983,7 +1163,7 @@ static void walk_node(GumboNode *node, buffer_t *out) {
free(li_ib.data);
for (int k = 0; k < nested_count; k++)
- walk_children(nested_lists[k], out);
+ walk_children(nested_lists[k], out, inherited);
break;
}
@@ -993,7 +1173,7 @@ static void walk_node(GumboNode *node, buffer_t *out) {
buffer_append_str(out, " ");
- walk_children(node, out);
+ walk_children(node, out, inherited);
if (wrap)
buffer_append_str(out, " A B A B A \nB\n A B "
+ "C AB tags the same way lists use A B A B A \nB\n A B C AB 123 456 . Inter-block whitespace (newlines /
* spaces between block tags in pretty-printed HTML) is discarded so it does
@@ -382,21 +456,22 @@ function flushInlineP(
function flattenBqChildren(
node: Element,
ib: { buf: string },
- out: { buf: string }
+ out: { buf: string },
+ inherited: CustomStyle | null
): void {
for (const child of Array.from(node.childNodes)) {
- flattenBqNode(child, ib, out);
+ flattenBqNode(child, ib, out, inherited);
}
}
function flattenBqNode(
node: Node,
ib: { buf: string },
- out: { buf: string }
+ out: { buf: string },
+ inherited: CustomStyle | null
): void {
if (isText(node)) {
- const t = node.textContent ?? '';
- ib.buf += escapeText(t);
+ walkNode(node, ib, inherited);
return;
}
if (!isElement(node)) return;
@@ -410,12 +485,12 @@ function flattenBqNode(
}
if (isBlockProducing(node) || isBlockquoteNode(node)) {
flushInlineP(ib, out);
- flattenBqChildren(node, ib, out);
+ flattenBqChildren(node, ib, out, inherited);
// The flattened block becomes a ; carry over its text-align (if any).
flushInlineP(ib, out, emitAlignment(node, 'p'));
return;
}
- walkNode(node, ib);
+ walkNode(node, ib, inherited);
}
// --- List item content flattening ---
@@ -425,6 +500,7 @@ type LiCtx = {
styles: CssStyles;
nestedLists: Element[];
hasEmitted: boolean;
+ inherited: CustomStyle | null;
};
function flushLiBuffer(
@@ -465,7 +541,7 @@ function flattenLiNode(
ctx: LiCtx
): void {
if (isText(node)) {
- ib.buf += escapeText(node.textContent ?? '');
+ walkNode(node, ib, ctx.inherited);
return;
}
if (!isElement(node)) return;
@@ -492,12 +568,16 @@ function flattenLiNode(
flushLiBuffer(ib, out, ctx);
return;
}
- walkNode(node, ib);
+ walkNode(node, ib, ctx.inherited);
}
// --- Main walker ---
-function walkChildren(node: Element, out: { buf: string }): void {
+function walkChildren(
+ node: Element,
+ out: { buf: string },
+ inherited: CustomStyle | null
+): void {
const children = Array.from(node.childNodes);
const parentIsList = isListNode(node);
@@ -515,7 +595,7 @@ function walkChildren(node: Element, out: { buf: string }): void {
// Flatten list-inside-list
if (parentIsList && isElement(child) && isListNode(child)) {
- walkChildren(child, out);
+ walkChildren(child, out, inherited);
i++;
continue;
}
@@ -527,7 +607,7 @@ function walkChildren(node: Element, out: { buf: string }): void {
while (i < children.length) {
const cur = children[i];
if (!cur || !isElement(cur) || !isBlockquoteNode(cur)) break;
- flattenBqChildren(cur, bqIb, out);
+ flattenBqChildren(cur, bqIb, out, inherited);
i++;
}
flushInlineP(bqIb, out);
@@ -562,25 +642,33 @@ function walkChildren(node: Element, out: { buf: string }): void {
// Transparent inline wrapper for block/bq children
if (isElement(cur) && hasBlockOrBqChild(cur)) {
flushInlineP(ib, out);
- walkChildren(cur, out);
+ walkChildren(cur, out, inherited);
i++;
continue;
}
- walkNode(cur, ib);
+ walkNode(cur, ib, inherited);
i++;
}
flushInlineP(ib, out);
continue;
}
- walkNode(child, out);
+ walkNode(child, out, inherited);
i++;
}
}
-function walkNode(node: Node, out: { buf: string }): void {
+function walkNode(
+ node: Node,
+ out: { buf: string },
+ inherited: CustomStyle | null
+): void {
if (isText(node)) {
- out.buf += escapeText(node.textContent ?? '');
+ const text = node.textContent ?? '';
+ const wrap = !!inherited && !isLayoutWhitespace(node);
+ if (wrap) out.buf += emitCustomStyleOpen(inherited);
+ out.buf += escapeText(text);
+ if (wrap) out.buf += ' ${emitStylesOpen(s)}${pb.buf}${emitStylesClose(s)} ${row.buf} ';
- walkChildren(node, out);
+ walkChildren(node, out, inherited);
if (wrap) out.buf += 'x");
+
+ // Foreground color only
+ EXPECT_EQ(GumboParser::normalizeHtml("x"),
+ "x");
+ EXPECT_EQ(
+ GumboParser::normalizeHtml("x"),
+ "x");
+ EXPECT_EQ(GumboParser::normalizeHtml(
+ "x"),
+ "x");
+
+ // Background color only
+ EXPECT_EQ(GumboParser::normalizeHtml(
+ "x"),
+ "x");
+ EXPECT_EQ(GumboParser::normalizeHtml(
+ "x"),
+ "x");
+
+ // Both colors combined
+ EXPECT_EQ(GumboParser::normalizeHtml(
+ "x"),
+ "x");
+ EXPECT_EQ(GumboParser::normalizeHtml(
+ "x"),
+ "x");
+
+ // Color + Single Formatter
+ EXPECT_EQ(GumboParser::normalizeHtml(
+ "x"),
+ "x");
+ EXPECT_EQ(GumboParser::normalizeHtml(
+ "x"),
+ "x");
+ EXPECT_EQ(GumboParser::normalizeHtml(
+ "x"),
+ "x");
+ EXPECT_EQ(GumboParser::normalizeHtml(
+ "x"),
+ "x");
+
+ // Color + Multiple inline styles
+ EXPECT_EQ(GumboParser::normalizeHtml(
+ "x"),
+ "x");
+
+ // Mix of colors and inline styles
+ EXPECT_EQ(
+ GumboParser::normalizeHtml(
+ "x"),
+ "x");
+
+ // Quotes can't break out of the style attribute
+ EXPECT_EQ(GumboParser::normalizeHtml(
+ "x"),
+ "x");
+
+ // Font size
+ EXPECT_EQ(
+ GumboParser::normalizeHtml("x"),
+ "x");
+
+ // Font family: the whole stack is passed through, picking the family is up
+ // to the parsers
+ EXPECT_EQ(GumboParser::normalizeHtml(
+ "x"),
+ "x");
+ EXPECT_EQ(
+ GumboParser::normalizeHtml(
+ "x"),
+ "x");
+ EXPECT_EQ(GumboParser::normalizeHtml(
+ "x"),
+ "x");
+
+ // All custom styles combined, with inline styles
+ EXPECT_EQ(GumboParser::normalizeHtml(
+ "x"),
+ "x");
+
+ // `&` and `"` are escaped
+ EXPECT_EQ(GumboParser::normalizeHtml(
+ "x"),
+ "x");
+ EXPECT_EQ(
+ GumboParser::normalizeHtml("x"),
+ "x");
}
TEST(GumboParserTest, EnrichedTagRemappings) {
@@ -625,3 +723,117 @@ TEST(GumboParserTest, InterBlockWhitespace) {
EXPECT_EQ(GumboParser::normalizeHtml("hello world"),
"hello world");
}
+
+TEST(GumboParserTest, NestedSpans) {
+ // Child overrides the parent
+ EXPECT_EQ(GumboParser::normalizeHtml(
+ "ABC"),
+ "ABC");
+
+ // Child inherits properties it doesn't set
+ EXPECT_EQ(GumboParser::normalizeHtml(
+ "AB"),
+ "AB");
+
+ // Unstyled spans are transparent
+ EXPECT_EQ(GumboParser::normalizeHtml(
+ "ABC"),
+ "ABC");
+
+ // Styles are pushed down through other inline tags
+ EXPECT_EQ(GumboParser::normalizeHtml(
+ "AB"),
+ "AB");
+
+ // A wrapper inside a pushed-down span merges the inherited style, and its
+ // text isn't wrapped again
+ EXPECT_EQ(GumboParser::normalizeHtml(
+ "ABCD"),
+ "ABCD");
+
+ // Styles are inherited across multiple levels
+ EXPECT_EQ(
+ GumboParser::normalizeHtml(
+ "ABC"),
+ "ABC");
+
+ // Transparent background doesn't override the inherited one
+ EXPECT_EQ(GumboParser::normalizeHtml(
+ "AB"),
+ "AB");
+
+ // `inherit` doesn't override the inherited value
+ EXPECT_EQ(
+ GumboParser::normalizeHtml("AB"),
+ "AB");
+
+ // Transparent background alone is treated as no style
+ EXPECT_EQ(GumboParser::normalizeHtml(
+ "A"),
+ "A");
+
+ // Whitespace between blocks is layout and doesn't become a paragraph
+ EXPECT_EQ(GumboParser::normalizeHtml(
+ "\n
"),
+ "\n \nB \n
"),
+ "B C
"),
+ "
");
+ EXPECT_EQ(GumboParser::normalizeHtml(
+ "AB
"),
+ "
");
+}
diff --git a/docs/docs/api-reference/enriched-text-input.md b/docs/docs/api-reference/enriched-text-input.md
index 382e60a39..eb4339d43 100644
--- a/docs/docs/api-reference/enriched-text-input.md
+++ b/docs/docs/api-reference/enriched-text-input.md
@@ -347,6 +347,12 @@ interface OnChangeStateEvent {
mention: StyleState;
checkboxList: StyleState;
alignment: string;
+ customStyle: {
+ foregroundColor: string;
+ backgroundColor: string;
+ fontSize: number;
+ fontFamily: string;
+ };
}
```
@@ -356,6 +362,10 @@ interface OnChangeStateEvent {
- `isConflicting` - toggling the style removes a conflicting active style
- `alignment` - current text alignment of the paragraph at the cursor:
`'left'`, `'center'`, `'right'`, `'justify'`, or `'auto'`
+- `customStyle` - the [custom style](/rich-text-formatting/custom-style) values
+ within the current selection. A field that isn't set, or
+ differs across the selection, is empty - `''` for strings and `0` for
+ `fontSize`. Colors are reported as hex strings (e.g. `#FF0000`)
:::note
@@ -973,6 +983,27 @@ up with natural alignment, the same as `'auto'`.
:::
+### `.setStyle()`
+
+```ts
+setStyle: (customStyle: {
+ foregroundColor?: ColorValue | null;
+ backgroundColor?: ColorValue | null;
+ fontSize?: number | null;
+ fontFamily?: string | null;
+}) => void;
+```
+
+Sets the [custom style](/rich-text-formatting/custom-style) at the current
+selection. Omitting a field leaves the given formatting untouched, whereas passing `null` for a field removes it.
+
+- `foregroundColor` - text color; use a hex (e.g. `#FFE066`) or named (e.g.
+ `'red'`) color
+- `backgroundColor` - text highlight color; use a hex (e.g. `#FFE066`) or named
+ (e.g. `'red'`) color
+- `fontSize` - font size of the text
+- `fontFamily` - font family of the text
+
### `.startMention()`
```ts
diff --git a/docs/docs/fundamentals/core-concepts.md b/docs/docs/fundamentals/core-concepts.md
index 52fd5593b..e391df2b9 100644
--- a/docs/docs/fundamentals/core-concepts.md
+++ b/docs/docs/fundamentals/core-concepts.md
@@ -71,7 +71,7 @@ The HTML format that both components expect is identical, what allows you to int
## The style state model
-Not every style can be combined with every other. For example, a paragraph can't be both a heading and a list item, code blocks don't support inline formatting such as bold or italic. The editor tracks this and reports it through `onChangeState`, which gives each style three booleans:
+Not every style can be combined with every other. For example, a paragraph can't be both a heading and a list item, code blocks don't support inline formatting such as bold or italic. The editor tracks this and reports it through `onChangeState`, which gives the majority of styles three booleans:
- **`isActive`** - whether the style is applied at the current selection. Use it to
highlight a toolbar button.
@@ -82,6 +82,8 @@ Not every style can be combined with every other. For example, a paragraph can't
For example, switching a blockquote paragraph to a heading removes the
blockquote. Use it to hint that the toggle is a swap, not an addition.
+Only [text alignment](/rich-text-formatting/text-alignment) and [custom style](/rich-text-formatting/custom-style) do not expose those three booleans in the `onChangeState` event, as they can be applied on any existing style. Instead, they simply carry their current value. To see the exact shape of the event's payload, see the `onChangeState` [API reference](/api-reference/enriched-text-input#onchangestate).
+
Driving your toolbar from these three flags keeps the UI honest: buttons light
up and grey out according to the editor's state.
diff --git a/docs/docs/fundamentals/html-format-and-supported-tags.md b/docs/docs/fundamentals/html-format-and-supported-tags.md
index 962dae581..ce2488e26 100644
--- a/docs/docs/fundamentals/html-format-and-supported-tags.md
+++ b/docs/docs/fundamentals/html-format-and-supported-tags.md
@@ -32,6 +32,10 @@ Both show up in the [`onChangeState`](/fundamentals/core-concepts#the-style-stat
| Link | `` | ``, ``, `` |
| Mention | `
`, `` | `` |
| Image | `
` | ``, `
` |
+| Custom style | `` | -- | -- |
+
+`` carries the [custom style](/rich-text-formatting/custom-style) in its
+`style` attribute - `color`, `background-color`, `font-size` and `font-family`.
:::note
diff --git a/docs/docs/rich-text-formatting/basic-styles.mdx b/docs/docs/rich-text-formatting/basic-styles.mdx
index ce52600e2..41e9b8395 100644
--- a/docs/docs/rich-text-formatting/basic-styles.mdx
+++ b/docs/docs/rich-text-formatting/basic-styles.mdx
@@ -35,7 +35,7 @@ once.
:::note
-There are two more inline styles, which you cannot toggle quite like the others - **links** and **mentions**. You'll learn about them in their respective sections, once you finish this chapter.
+There are a few more inline styles, which you cannot toggle quite like the others - **custom style**, **links** and **mentions**. You'll learn about them in their respective sections, once you finish this chapter.
:::
diff --git a/docs/docs/rich-text-formatting/custom-style.mdx b/docs/docs/rich-text-formatting/custom-style.mdx
new file mode 100644
index 000000000..4c3789f25
--- /dev/null
+++ b/docs/docs/rich-text-formatting/custom-style.mdx
@@ -0,0 +1,98 @@
+---
+sidebar_position: 2
+---
+
+import InteractiveExample from '@site/src/components/InteractiveExample';
+import CustomStyleEditor from '@site/src/examples/CustomStyleEditor';
+import CustomStyleEditorSrc from '!!raw-loader!@site/src/examples/CustomStyleEditor';
+
+# Custom style
+
+Aside from the predefined [basic styles](/rich-text-formatting/basic-styles)
+you can apply a **custom style**, which consists of four pieces of formatting:
+text color, highlight, font size and font family. Similarly as the style-toggling
+methods, it applies to the current input's selection.
+
+## Setting a custom style
+
+`setStyle` accepts an object with four optional fields:
+
+```tsx
+setStyle(
+ {
+ foregroundColor?: string,
+ backgroundColor?: string,
+ fontSize?: number,
+ fontFamily?: string,
+ }
+);
+```
+
+Each call respects the already present custom style and modifies it with whatever
+fields you pass. For example, if you want to remove a single field, pass `null`:
+
+```tsx
+// Remove the highlight, keep the color, size and font as they are.
+ref.current?.setStyle({ backgroundColor: null });
+```
+
+Custom style doesn't conflict with or block any other style, so it combines
+freely with both inline styles and paragraph styles.
+
+:::note
+
+If a current style modifies the same thing that **custom style** sets, we have the following priority:
+**paragraph style** < **custom style** < **inline style**. E.g. if you try to apply `foregroundColor` custom style to a text with a link (which is an inline style), the link's foreground color stays.
+
+:::
+
+## Reading the current style
+
+Since custom style carries values rather than a simple on/off flag, `onChangeState`
+reports it as a separate `customStyle` object instead of the usual
+`isActive` / `isBlocking` / `isConflicting`
+[booleans](/fundamentals/core-concepts#the-style-state-model):
+
+```ts
+customStyle: {
+ foregroundColor: string;
+ backgroundColor: string;
+ fontSize: number;
+ fontFamily: string;
+}
+```
+
+Each field holds the value at the current selection. When a field isn't set, it comes back
+empty: `''` for strings and `0` for `fontSize`. That makes it easy to check whether a field
+is applied:
+
+```tsx
+const customStyleButtons = [
+ {
+ label: 'Color',
+ isActive: !!state?.customStyle.foregroundColor,
+ onPress: () => ref.current?.setStyle({ foregroundColor: '#e5484d' }),
+ },
+ {
+ label: 'Font size',
+ isActive: !!state?.customStyle.fontSize,
+ onPress: () => ref.current?.setStyle({ fontSize: 26 }),
+ },
+];
+```
+
+:::tip
+
+Pass colors to `setStyle` as hex or named colors (e.g. `'red'`). They are
+always reported as uppercase hex strings - `#RRGGBB`, or `#RRGGBBAA`.
+
+:::
+
+## Try it out
+
+Each button below sets one field of the custom style on the selection, and
+removes it when the field is already applied. Select a word and give it a color,
+then a highlight - notice how the second call doesn't touch the first one. Try
+mixing them with different fonts and sizes.
+
+\n
',
+ '\n \nB \n
',
+ 'B C
',
+ '
',
+ ],
+ [
+ 'AB
',
+ '
',
+ ],
+ ])('%s → %s', (input, expected) => {
+ expect(normalizeHtml(input)).toBe(expected);
+ });
+ });
});
diff --git a/src/web/__tests__/normalizeFontFamily.test.ts b/src/web/__tests__/normalizeFontFamily.test.ts
new file mode 100644
index 000000000..67a55960e
--- /dev/null
+++ b/src/web/__tests__/normalizeFontFamily.test.ts
@@ -0,0 +1,20 @@
+import { normalizeFontFamily } from '../formats/EnrichedCustomStyle';
+
+describe('normalizeFontFamily', () => {
+ it.each([
+ // first family of the stack
+ ['Roboto, sans-serif', 'Roboto'],
+ ['"Open Sans", Arial', 'Open Sans'],
+ ["'Open Sans'", 'Open Sans'],
+ // commas inside quotes are part of the family name
+ ['"SWM, Inc", Arial', 'SWM, Inc'],
+ ["'SWM,Inc', Arial", 'SWM,Inc'],
+ // an empty first family is no family
+ [', Arial', null],
+ ["'", null],
+ ['', null],
+ [null, null],
+ ])('%p → %p', (input, expected) => {
+ expect(normalizeFontFamily(input)).toBe(expected);
+ });
+});
diff --git a/src/web/formats/EnrichedCustomStyle.ts b/src/web/formats/EnrichedCustomStyle.ts
new file mode 100644
index 000000000..fd524c977
--- /dev/null
+++ b/src/web/formats/EnrichedCustomStyle.ts
@@ -0,0 +1,271 @@
+import { Mark } from '@tiptap/core';
+import type { Attrs } from '@tiptap/pm/model';
+import { withBaseFontFamilyFallback } from '../styleConversion/enrichedStyleToCSSVariables';
+import { deleteCharacterBackward } from '../utils/deleteCharacterBackward';
+
+type CustomStyleAttrs = {
+ foregroundColor?: string | null;
+ backgroundColor?: string | null;
+ fontSize?: number | null;
+ fontFamily?: string | null;
+};
+
+function firstInFontFamilyString(value: string): string {
+ let quote = '';
+ for (let i = 0; i < value.length; i++) {
+ const c = value[i];
+ if (quote) {
+ if (c === quote) quote = '';
+ } else if (c === "'" || c === '"') {
+ quote = c;
+ } else if (c === ',') {
+ return value.slice(0, i);
+ }
+ }
+ return value;
+}
+
+export function normalizeFontFamily(
+ value: string | null | undefined
+): string | null {
+ if (!value) return null;
+
+ let fontFamily = firstInFontFamilyString(value.trim()).trim();
+
+ if (
+ (fontFamily.startsWith("'") && fontFamily.endsWith("'")) ||
+ (fontFamily.startsWith('"') && fontFamily.endsWith('"'))
+ ) {
+ fontFamily = fontFamily.slice(1, -1);
+ }
+
+ return fontFamily.length > 0 ? fontFamily : null;
+}
+
+function resolveFontSize(value: number | null | undefined): number | null {
+ if (value == null || value <= 0) return null;
+ return value;
+}
+
+function parseFontSize(value: string | null | undefined): number | null {
+ if (!value) return null;
+ const trimmed = value.trim();
+ const match = /^([0-9.]+)\s*(?:px)?$/i.exec(trimmed);
+ if (!match) return null;
+ const n = parseFloat(match[1]!);
+ return !Number.isNaN(n) && n > 0 ? n : null;
+}
+
+function buildStyle(attrs: Attrs, withFontFamilyFallback = false): string {
+ const parts: string[] = [];
+ if (attrs.foregroundColor) {
+ parts.push(`color: ${attrs.foregroundColor}`);
+ }
+ if (attrs.backgroundColor) {
+ parts.push(`background-color: ${attrs.backgroundColor}`);
+ }
+ if (attrs.fontSize) {
+ parts.push(`font-size: ${attrs.fontSize}px`);
+ }
+ if (attrs.fontFamily) {
+ const fontFamily = attrs.fontFamily as string;
+ // if the font family contains a space or a comma, wrap it in quotes
+ const family = /[\s,]/.test(fontFamily) ? `'${fontFamily}'` : fontFamily;
+ // add a fall-back to the input's inherited font, if needed
+ parts.push(
+ `font-family: ${withFontFamilyFallback ? withBaseFontFamilyFallback(family) : family}`
+ );
+ }
+ return parts.join('; ');
+}
+
+declare module '@tiptap/core' {
+ interface Commands