StyledText: capsule background for inline code (design discussion)

[GrandAdmiralBee]

Working Examples

Context

StyledText's inline code (markdown backticks) currently renders as just a
monospace font swap — visually almost indistinguishable from body text. Every
markdown viewer most users see daily (GitHub, Discord, LSP popups, IDE tooltips,
docs sites) renders inline code as a small "capsule": slightly smaller font, a
translucent rounded background, a thin border, padding so the text doesn't sit
flush against the surrounding words.

I have a working implementation that brings StyledText close to that visual
baseline, but a couple of the decisions touch public API or from_markdown's
output, so I'd like to align with maintainers before opening the PR.

Proposed direction

1. Inline code renders with a translucent neutral-gray background, a 1px
   rounded border, and 0.85× font size relative to surrounding text.

2. Vertical geometry is derived from parley::RunMetrics (cap-height,
   descent), so capsule size scales with the font and looks balanced for
   typical content (lowercase + capitals + parens).

3. Theme-adaptive defaults: the border tone is picked from the luma of
   text.color() so the outline stays visible on both light and dark
   backgrounds. The fill is the same gray on both themes.

4. Three new properties on StyledTextItem give users full control:

   • inline-code-background: brush
   • inline-code-border-color: brush
   • inline-code-font-scale: float

   Transparent brushes / scale outside (0, 2] mean "use the default".

5. New GlyphRenderer::fill_rectangle_with_color_radius_and_border method
   with overrides per renderer (Skia/Femtovg/Software) — same primitive will
   be reused for block-quote bars and code-block backgrounds in follow-up
   PRs.

The implementation is complete and tested locally across the three renderers
and on both light and dark themes.

Key design questions for maintainers

1. NBSP injection into StyledTextParagraph.text

The capsule needs horizontal padding inside the rounded background that
survives line wrapping — when wrap puts the code run at the start of a
new line, the padding must come with it, not stay on the previous line.

I tried four approaches before settling on the fifth:

Approach	Why it didn't work
Cosmetic bg extension past glyph extents	At wrap, bg overflows the line into negative x
parley::LetterSpacing on surrounding spaces	Leading whitespace is collapsed at line start; padding evaporates
Line-bounds clamping	Padding visibly shrinks at line edges (UX regression)
parley::InlineBox (InFlow, w=4, h=0)	parley unconditionally calls mark_line_break_opportunity() after every inline box (line_break.rs:531) — wrap separates before-box from code
NBSP \u{00A0} injected into the paragraph text by the parser	Works: NBSP has positive advance but is never a break opportunity, so it stays glued to the code across wraps

Example of warp issue:

With proposed fix:

The trade-off is that StyledTextParagraph.text from from_markdown now
contains NBSP characters around each inline-code span. This leaks into:

• selection (selection_geometry ranges include the NBSPs)
• clipboard (copy of code yields \u{a0}code\u{a0})
• any downstream consumer that introspects paragraph.text

Question: is this trade-off acceptable, or do you see a path I missed?
Alternatives I considered and rejected:

• Inject NBSPs inside LayoutWithoutLineBreaksBuilder::build instead of the
  parser, with a translation map between "original" and "parley" byte
  positions. Doable but fragile — selection ranges, link ranges, hit-testing
  all need translation.
• Forking parley to suppress the break opportunity after specific inline
  boxes. Significant ongoing maintenance cost.

If the NBSP approach is a non-starter, the runner-up is probably
build-level injection with a translation map — happy to explore if needed.

2. New properties on StyledTextItem

Proposed names and types:

in property <brush> inline-code-background;
in property <brush> inline-code-border-color;
in property <float> inline-code-font-scale;

Sub-questions:

• Should these be three properties or one struct? Other Slint elements
  seem to favor flat properties (e.g. default-color, default-font-size,
  default-font-family rather than a default-font: { ... }). I went flat
  for consistency.
• brush vs color for the background/border? I chose brush so a
  user could pass a gradient if they really want. The actual implementation
  resolves it down to a single Color via Brush::color() — the rendering
  primitive paints a solid fill. Should this be color instead to make the
  capability explicit?
• font-scale: float vs font-size: length. Scale is relative to the
  surrounding text size, which feels right for inline code. Absolute size
  would also be reasonable for users who want a fixed code size regardless
  of body text. I picked scale; happy to switch or expose both.
• Should we ship a smaller set first? The minimum that's user-facing
  useful is probably inline-code-background + inline-code-font-scale.
  Border could fall back to a derivation of background. I have all three
  implemented, but happy to trim if maintainers prefer staged API growth.

3. Theme-adaptive default border

When inline-code-border-color is not set, the implementation picks one of
two grays based on 0.299·R + 0.587·G + 0.114·B of text.color():

• text.color() luma > 140 → bright gray (assumed dark theme background)
• otherwise → soft gray (assumed light theme background)

The fill is always the same neutral gray on both themes (overlays well on
either background) — only the border switches.

This is a heuristic. It works for typical light/dark themes but can miss on
unusual palettes (mid-gray text, high-contrast themes). The user can always
override explicitly via the property.

Question: is this kind of implicit theme detection acceptable as a
fallback when the property is unset, or do you prefer to never read
text.color() for this purpose and instead require explicit configuration?

4. Follow-up PRs in the same area

This PR also establishes shared infrastructure that I'd like to reuse for
subsequent markdown features. Specifically:

• GlyphRenderer::fill_rectangle_with_color_radius_and_border — will be
  reused for block-quote accent bars, code-block backgrounds, horizontal
  rules.
• Threading default_text_color: Color through Layout::draw and
  TextParagraph::draw — same plumbing will carry future theme-adaptive
  paragraph decorations.
• TextParagraph.code_ranges: Vec<Range<usize>> — pattern for "this
  paragraph has rendered ranges I need to find again at draw time" that
  could generalize to highlighted text, search results, etc.

Roadmap for the broader series (in case it changes how you'd review this
PR): headings (H1–H6), horizontal rules, blockquotes, code blocks, sub/sup,
HTML aliases, <small>, images. Each as its own small PR.

What I'm asking

Mainly directional sign-off on questions 1 and 2 — the parts that touch
public observable behavior. If the NBSP approach is OK and the property
shape is roughly right, I'll open the PR with the full implementation,
tests, and changelog. If either needs to change, I'd rather adjust now than
after a 1500-line review.

Happy to share the local test app or visual screenshots in either theme
on request.

[ogoffart]

Thanks for raising these question.
I think it is indeed a question of what is the style-text, is it holding style information or semantic information about the text.

For example, markdown is for the semantic information, it tells that something should be code, or link, or table, or title, but it doesn't tell how to represent that, what color or font or anything.

We already have a link-color property on StyledText, but i'd rather avoid having the while stylesheet like inline-code-* and then title-1-color or header-2-font-size and whatnot.
That'd mean that anything that can accept a styled-text (eg, Tooltip) would need all these properties as well.

I wonder if we should have something like @markdown("...." , inline-code-background: #efe) or maybe something like @markdown("...").apply-style({ inline-code-background: #efe, ... })

Or we could also have a property in property <TextStyleSheet> style-sheet on the StyledText element (and Tooltip and anything that takes a styled-text), so that would be only one property and not the full set of possibilities.

I'm just brainstorming my thought here, i don't have a solution at the moment.

[GrandAdmiralBee]

Agreed on the framing — styled-text carries semantic information, and how it gets rendered is a separate concern. That's the right axis to organise around.

Quick read on the three brainstormed options:

• @markdown("...", inline-code-background: #efe) and .apply-style({...}) bake the visual settings into the data-construction site. That doesn't compose well for elements like Tooltip that receive a styled-text value from elsewhere — they can't restyle what they didn't construct.
• A single style: <TextStyleSheet> property is closer, but raises a subtle issue. I tested partial struct literals (style: { inline-code-background: #efe }) — they compile fine, and unset fields take type defaults. The catch is there's no way for the renderer to distinguish "user didn't set this field" from "user explicitly set it to the type default" (e.g. transparent brush, 0.0 float). The "fall back to renderer default" trick relies on transparent == unset, which conflates two semantics.

I'd like to suggest a different shape that leverages Slint's existing two-tier widget architecture — the same split as TextInput (builtin) and TextEdit (std-widgets):

Tier 1 — StyledText (builtin, low-level primitive)

Stays as the bare rendering primitive. Gets individual properties for the visual knobs (inline-code-background, inline-code-border-color, inline-code-font-scale, eventually heading-color, etc.) with concrete defaults — not sentinels:

in property <brush> inline-code-background: #80808011;
in property <brush> inline-code-border-color: #80808038;
in property <float> inline-code-font-scale: 0.85;

Or move all style related fields to a struct, which StyledText will be using for info, for cleaner code (If only slint supported extend pattern for structs, much like rust), for example:

export struct MarkdownStyleSheet {
      // Inline code
      inline-code-background: brush,
      inline-code-border-color: brush,
      inline-code-border-width: length,
      inline-code-font-scale: float,
      // …
  }

Default values are real (a neutral translucent gray that reads OK on both light and dark backgrounds without theme knowledge). transparent actually means transparent — no ambiguity. Property bloat is fine here because using StyledText directly is an opt-in for power users building their own components.

Tier 2 — RichText (std-widgets, per theme)

Thin themed wrapper. Pulls values from the active Palette / StyleMetrics and feeds them to the underlying StyledText:

// widgets/fluent/richtext.slint
export component RichText {
    in property <styled-text> text;
    in property <length> font-size: FluentFontSettings.body.font-size;
    callback link-clicked(string);

    StyledText {
        text: root.text;
        default-color: Palette.foreground;
        default-font-size: root.font-size;
        link-color: Palette.accent-foreground;
        inline-code-background: Palette.alternate-background;
        inline-code-border-color: Palette.border;
        link-clicked(url) => { root.link-clicked(url); }
    }
}

Same shape across themes (fluent/cosmic/cupertino/material). User imports RichText from std-widgets.slint and it looks right out of the box.

Tier 3 — Tooltip and other styled-text consumers

Use RichText internally (themed), not raw StyledText. This is the key piece — it resolves your "Tooltip would need all these properties" concern. Tooltip exposes nothing markdown-specific; it just renders themed via RichText. Users who want a differently-styled tooltip build their own using StyledText directly.

Architecture parallel

This mirrors how TextEdit (themed std-widget) wraps TextInput (low-level builtin) today. No new patterns introduced — just applying the established split to styled-text.

Concrete implementation path

1. Current PR: keeps the 3 individual props on StyledText (builtin), but with concrete defaults instead of the luma-adaptive fallback magic we had in the prototype. NBSP padding, parley wiring, GlyphRenderer extensions all stay below the API surface.
2. Follow-up PR (small, one file per theme): add RichText to fluent/cosmic/cupertino/material.
3. Future PRs (headings, blockquotes, code blocks, …): add low-level properties to StyledText and corresponding bindings to RichText.

Open questions

• Naming: RichText, Markdown, ThemedText, something else? RichText reads naturally to me but happy with whatever fits the convention.
• Should RichText follow the one-file-per-theme pattern (like Button, TextEdit) or be a single file styled via Palette lookups?
• Any concerns on the Tooltip integration angle — should that be folded into the same PR series or kept separate?

Will refactor the existing PR to drop the luma sentinel and ship concrete defaults once you're OK with the direction.

[GrandAdmiralBee]

An update on proof-of-concept RichText

[tronical]

I suggest to leave out the styling API for now and just focus on better default rendering for code fences.

I don't think injecting nbsp is the right way to implement padding on the start and end. We should, in general, not modify the text, to preserve hit testing and (future) cursor navigation. Do I understand correctly that code blocks (single backtick) should not have any padding added, but for code fences you'd like padding like an indentation? Where does the padding idea come from?

[GrandAdmiralBee]

@tronical
Ok, I understand that injecting nbsp is a crutch, but I did it for visual representation of proof of concept RichText.
Code blocks This kind of feature is currently discussed, so I used this crutch for this.
I didn't touch code fences

This kind of feature

yet in my test implementation, but I recon it wouldn't need this kind of padding, because it's a paragraph feature, not inline. It will work the same as blockquotes (see screenshots above).

Where the padding idea came from

The GitHub / Discord / docs-site convention of rendering inline code as a small "capsule" — monospace text inside a translucent rounded background with a few pixels of internal padding. The CSS that drives it is essentially code { padding: 0 4px; background: rgba(...); border-radius: 4px; }. We were modelling against that visual. We can make initial iteration of inline code implementation without this feature and add it later once we decide on the solution.

Iteration 1 plan (this PR)

Reduced scope, no text modification:

• Inline code renders with: monospace font family, ~0.85× font scale, translucent rounded background with a 1px border, all sized from real font metrics (cap-height, descent) so it scales with the surrounding text.
• No internal padding for background capsule.
• Theme-adaptive defaults via the luminance of text.color() (gray fill on both themes, slightly brighter border on dark backgrounds). No API for properties — that's a separate conversation about the architecture (per the discussion above about builtin vs std-widgets split).

Selection, hit-testing, copy/paste, and future cursor navigation all work normally because the underlying text matches what the user typed.

Proposed roadmap if we ever want true padding

For the record: there is a clean way to add padding without touching the text, but it needs a small contribution to parley first. I checked the parley crate and it is quite active.

The reason our InlineBox attempt didn't work is line_break.rs:531:

// We can always line break after an inline box
self.state.mark_line_break_opportunity();

That break-after-every-inline-box is hardcoded. If a [before-padding-box, code, after-padding-box] triplet doesn't fit on the current line, parley wraps between the before-box and the code, leaving the padding stranded on the previous line.

A minimal parley change would fix this for our use case (and others — emoji inside a word, math operators that should stay glued to their operands, etc.):

// parley/src/inline_box.rs
pub struct InlineBox {
    pub id: u64,
    pub kind: InlineBoxKind,
    pub index: usize,
    pub width: f32,
    pub height: f32,
    pub allow_break_after: bool, // default: true (backward compat)
}

// parley/src/layout/line_break.rs
if inline_box.allow_break_after {
    self.state.mark_line_break_opportunity();
}

~10 lines of diff, fully backwards compatible. With that landed, our padding becomes:

builder.push_inline_box(InlineBox {
    width: PAD, height: 0.0,
    allow_break_after: false,  // glue padding to code
    ..
});
// code styling...
builder.push_inline_box(InlineBox {
    width: PAD, height: 0.0,
    allow_break_after: true,   // wrap may happen after code+padding
    ..
});

Layout, hit-testing, selection, and copy/paste all stay correct because the boxes don't add to text length, but they do contribute width to the line.

I can pursue this as a parley contribution separately if/when there's need for the visual upgrade (Personally, I need it) — happy to drive it. For this PR it's not needed; the "no padding" version stands on its own.

PR contents

If we decide on current implementation and arch, I can make PR with the inline code shortle and follow up with PRs for other components (after discussions of course).

Will update the branch with:

• NBSP injection removed from the parser
• The three inline-code-* properties removed from StyledTextItem
• Background drawn tightly around the glyph extents
• Tests updated to expect un-modified text
• CHANGELOG note that inline code now renders with a themed capsule, no user-facing styling props yet pending the broader styling-API discussion

Questions

What do you think about separate components for std-widgets and Visual Elements. The first one is unthemeable, the second one is deeply customizable. I don't have insider info about main use cases for slint and is customizable StyledText is even needed, so it's up to you.

[tronical]

We can make initial iteration of inline code implementation without this feature and add it later once we decide on the solution.

Sounds good :)

Thanks a lot btw for iterating with your plan here. That makes it so much easier to refine the scope and will make code review much easier, too.

What do you think about separate components for std-widgets and Visual Elements

It's tempting, but I think I'm leaning more towards Olivier's in property <TextStyleSheet> style-sheet idea. Makes it easy to build custom styled text components without a huge API surface.

PR contents

👍 I suppose you already have history, but feel free to rewrite it since we haven't seen it. Idea would be a PR with one or two commits, depending on their size, that - if I understand correctly here - basically fixes code rendering to look proper :). BTW, feel free extend the styled text example in the widgets gallery example.