Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,19 @@ release is cut, and reads *Unreleased* until then. It lists every change a consu
breaks what the release before it allowed says how to migrate, as [Versioning's rules](https://github.com/FormaUI/Versioning/blob/v1.0.0-preview.5/docs/releases.md#the-release-record)
set out. What Forma gained before its first release, month by month, is in [the feature history](FEATURE-HISTORY.md).

## `1.0.0-preview.11`

*November 18, 2026*

- `ToolbarOption.IsTitleVerbatim` marks a title that is a value shown as written, such as a font's name or a size, and
the composer leaves such a title as it is. Its font families, font sizes, line heights, special characters and zoom
levels are verbatim. It looked each of them up as a key, so the rich text editor's toolbar threw under
`RequireMatchingLocalization` in a language other than English, and `Diagnostics` reported every one missing.
- `TypographyPluginOptions.TextColors` and `HighlightColors` are `TypographyColor`s, each a color's English name and
its `CssColor`, and the color menus label each color by its name, which Hebrew and Spanish localize. They labeled
each by its hex code, which a screen reader reads out character by character. To migrate, name each color:
`new TypographyColor("Red", CssColor.FromHex(0xd32f2f))`.

## `1.0.0-preview.10`

*November 17, 2026*
Expand Down
2 changes: 1 addition & 1 deletion Directory.Build.props
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@
<!-- The one version every package ships at; a preview, as the framework it targets is. -->
<PropertyGroup>
<VersionPrefix>1.0.0</VersionPrefix>
<VersionSuffix>preview.10</VersionSuffix>
<VersionSuffix>preview.11</VersionSuffix>
</PropertyGroup>

<!-- Reports the .editorconfig IDE* code-style severities from the compiler, not just the IDE, and fails the build on any warning, the compiler's or MSBuild's. -->
Expand Down
3 changes: 2 additions & 1 deletion docs/composer-design.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ Key bindings come through `IComposerKeyBindingSource`, which every plugin is and

A **view** has the shape of an editor — its own component, rows, items and assets, maximizable like any surface — but shows one editor's document read-only rather than editing it. An editor offers a view by registering it as a child, and a feature registered under that view contributes to its rows exactly as one registered under an editor contributes to the editor's; the layout for a view takes the built-in row, the rows the view declared, and what is registered under the view or at the composer root, and nothing else — so neither an editor's formatting nor a command acting on the document, such as attaching a file, lands on its preview. The switcher lists the active editor's views as trailing tabs after the editors, and those tabs are the only way in: a view is its own surface, not a toolbar toggle. A plugin reports which of its own toggles and options are active through `ActiveStates`, which is how a view's paper size and zoom show in its bar without going through the selection.

`Title` is the **English source string**, not a resolved localized string, and so is every title and row label a plugin contributes; the composer localizes them when it draws them. A plugin never resolves a localizer of its own — one that did would capture whichever culture it was built under, and would have to carry the composer's words for every group it joins. What a plugin does name is **where its localization lives**, through `LocaleSourceType`, the way a component part names its composite's: the composer reads a plugin's titles from that type's locale, so a plugin shipped from another package brings its own strings, and reads those of a plugin naming none from its own. A group the composer provides, named in `ComposerGroups`, takes the composer's title whichever plugin declares it, as a row named in `ComposerRows` takes the composer's label, so a plugin joining one never carries the composer's word for it. Every title is read from one locale, so a title missing from it is a miss the localization's checks report. Localization happens before contributions are merged, since a merged group no longer says which plugin declared each item in it.
`Title` is the **English source string**, not a resolved localized string, and so is every title and row label a plugin contributes; the composer localizes them when it draws them. A menu option whose title is a value rather than words, a font's name, a size, a line height, a character, a zoom level, is marked `IsTitleVerbatim`, and the composer shows it as written; a color is offered by its name. A plugin never resolves a localizer of its own — one that did would capture whichever culture it was built under, and would have to carry the composer's words for every group it joins. What a plugin does name is **where its localization lives**, through `LocaleSourceType`, the way a component part names its composite's: the composer reads a plugin's titles from that type's locale, so a plugin shipped from another package brings its own strings, and reads those of a plugin naming none from its own. A group the composer provides, named in `ComposerGroups`, takes the composer's title whichever plugin declares it, as a row named in `ComposerRows` takes the composer's label, so a plugin joining one never carries the composer's word for it. Every title is read from one locale, so a title missing from it is a miss the localization's checks report. Localization happens before contributions are merged, since a merged group no longer says which plugin declared each item in it.

### 3.1a Composing a composer

Expand Down Expand Up @@ -556,3 +556,4 @@ These are correctness requirements for every Forma component, and the composer i
| C19 | Whose defaults does an editor get? | Its own. The editor builder is typed by its editor, so each editor's package extends it with defaults of its own and one editor's defaults cannot be called on another. The composer's defaults are what belongs on every surface, which is maximizing and the shortcut reference; attaching is each editor's, since a view never edits the document (§4.3a). |
| C20 | How does a capability that joins the composer to another component ship? | As an AddOn of its own, `Forma.AddOns.Composer.Plugins.{Component}` (§9), so neither component's package depends on the other and a host wanting both adds the one package that joins them. |
| C21 | Where does a plugin from another package keep its labels' localization? | With itself. A plugin names the type whose locale files hold its labels through `LocaleSourceType`, and the composer reads its titles from that type's locale alone. A group the composer provides, named in `ComposerGroups`, takes the composer's own title, as a standard row does, so a plugin joining one carries only its own commands' words, and a title read from one locale makes a missing one a miss the localization's checks report (§3.1). |
| C22 | How does a menu option that is a value, a font's name, a size, a character, stay unlocalized? | The plugin marks it `ToolbarOption.IsTitleVerbatim`, false unless set, and the composer shows its title as written, so the plugin that knows it is listing values says so and every title the composer looks up is text a pack can carry. A color is offered by its name, a `TypographyColor`, which localizes and gives a screen reader a word in place of a hex code. A template keeps its `Title`: it is the host's own words, which the host localizes through its own files (§3.1). |
2 changes: 1 addition & 1 deletion docs/features-status.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
| Measure | Now |
| --- | --- |
| Components | 67 implemented and 7 in progress, as [the catalog](component-catalog.md) lists them, and 21 planned, as [the roadmap](component-roadmap.md) orders them |
| Packages | Every project under `src/` but the Showcase, released from `main` by `release.yml` to nuget.org and the organization's GitHub feed, the latest published release `1.0.0-preview.10` |
| Packages | Every project under `src/` but the Showcase, released from `main` by `release.yml` to nuget.org and the organization's GitHub feed, the latest published release `1.0.0-preview.11` |
| Render modes | Interactive Server, WebAssembly and Auto implemented: every call a component makes to a script and every call back checked in each, and on the Server in WebKit, the engine of Safari and of Apple's web views, every runtime on a page following its culture coordinator, a client reading its host's own strings, and a host setting either arrangement up as the README says; static rendering implemented, every check page rendered statically with no enabled control that needs interactivity; Blazor Hybrid implemented on WPF, Windows Forms and MAUI on Windows, every component checked in a web view and each host's application set up as the README says; an inventory holds every component to a check page in every render mode |

The gate runs every check [the verification design](verification-design.md#gates) sets out, each platform's where the machine can run it. It passes locally on Windows and in CI on Linux, on Windows and on an Android emulator.
Expand Down
2 changes: 1 addition & 1 deletion src/Blazor/Forma.Blazor.Composer/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -131,7 +131,7 @@ editor.
| --- | --- | --- |
| `BasicFormattingPlugin` | Bold, italic, underline, strikethrough, inline code, clear formatting, and subscript and superscript where its options include them | `BasicFormattingPluginOptions`: `IncludeSubscriptAndSuperscript` |
| `ParagraphFormatPlugin` | Paragraph, headings 1 to 6, blockquote, lead paragraph | |
| `TypographyPlugin` | Font family, font size, line height, text color, highlight color | `TypographyPluginOptions`: the choices offered, and `FontSizeUnit`, `Rem` or `Points` |
| `TypographyPlugin` | Font family, font size, line height, text color, highlight color | `TypographyPluginOptions`: the choices offered, each color a `TypographyColor` with the English name readers know it by, and `FontSizeUnit`, `Rem` or `Points` |
| `ListPlugin` | Bulleted and numbered lists, indent, outdent | |
| `AlignmentBidiPlugin` | Alignment and paragraph direction | |
| `LinkPlugin` | Links and anchors | |
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,7 @@ public sealed class SpecialCharacterPlugin(
{
Id = $"char-{c}",
Title = c,
IsTitleVerbatim = true,
Command = $"{InsertCharacterPrefix}{c}",
})],
},
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
namespace Forma.Blazor.Components.Composer.RichTextEditor.Plugins;

using Forma.Framework.Css;

/// <summary>A color <see cref="TypographyPlugin"/> offers, with the name a reader knows it by.</summary>
/// <param name="Name">The color's English name, which the composer localizes as its option's label and accessible name.</param>
/// <param name="Color">The color the text or its highlight takes.</param>
public sealed record TypographyColor(string Name, CssColor Color);
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,7 @@ public sealed class TypographyPlugin(
{
Id = $"font-family:{family}",
Title = family,
IsTitleVerbatim = true,
Command = $"{FontFamilyCommand}:{family}",
PreviewStyle = $"font-family:{family}",
})],
Expand All @@ -70,6 +71,7 @@ public sealed class TypographyPlugin(
{
Id = $"font-size:{ToCssSize(size)}",
Title = size,
IsTitleVerbatim = true,
Command = $"{FontSizeCommand}:{ToCssSize(size)}",
})],
},
Expand All @@ -82,6 +84,7 @@ public sealed class TypographyPlugin(
{
Id = $"line-height:{height}",
Title = height,
IsTitleVerbatim = true,
Command = $"{LineHeightCommand}:{height}",
})],
},
Expand All @@ -100,10 +103,10 @@ public sealed class TypographyPlugin(
Icon = Glyph.FontColor,
Options = [.. Options.TextColors.Select(color => new ToolbarOption
{
Id = $"text-color:{color}",
Title = color,
Command = $"{TextColorCommand}:{color}",
Swatch = color,
Id = $"text-color:{color.Color}",
Title = color.Name,
Command = $"{TextColorCommand}:{color.Color}",
Swatch = color.Color.ToString(),
})],
},
new ToolbarMenu
Expand All @@ -113,10 +116,10 @@ public sealed class TypographyPlugin(
Icon = Glyph.Highlight,
Options = [.. Options.HighlightColors.Select(color => new ToolbarOption
{
Id = $"highlight-color:{color}",
Title = color,
Command = $"{HighlightColorCommand}:{color}",
Swatch = color,
Id = $"highlight-color:{color.Color}",
Title = color.Name,
Command = $"{HighlightColorCommand}:{color.Color}",
Swatch = color.Color.ToString(),
})],
},
],
Expand All @@ -143,8 +146,8 @@ public ValueTask ExecuteAsync(string command, ComposerContext context, IComposer
{
FontFamilyCommand => ("fontName", GetFirst(Options.FontFamilies)),
FontSizeCommand => ("fontSize", GetFirst(Options.FontSizes) is { } size ? ToCssSize(size) : null),
TextColorCommand => ("foreColor", GetFirst(Options.TextColors)),
HighlightColorCommand => ("hiliteColor", GetFirst(Options.HighlightColors)),
TextColorCommand => ("foreColor", GetFirstColor(Options.TextColors)),
HighlightColorCommand => ("hiliteColor", GetFirstColor(Options.HighlightColors)),
LineHeightCommand => ("lineHeight", GetFirst(Options.LineHeights)),
_ => (null, null),
};
Expand All @@ -160,6 +163,11 @@ public ValueTask ExecuteAsync(string command, ComposerContext context, IComposer
{
return values.Count > 0 ? values[0] : null;
}

static string? GetFirstColor(IReadOnlyList<TypographyColor> colors)
{
return colors.Count > 0 ? colors[0].Color.ToString() : null;
}
}

// A label is a pixel size at the default 16px root, so its rem is the label divided by 16.
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
namespace Forma.Blazor.Components.Composer.RichTextEditor.Plugins;

using Forma.Framework.Css;

/// <summary>Options configuring font families, sizes, colors, and line heights offered by <see cref="TypographyPlugin"/>.</summary>
public sealed record TypographyPluginOptions
{
Expand All @@ -26,10 +28,25 @@ public sealed record TypographyPluginOptions
["1.0", "1.15", "1.5", "1.6", "2.0"];

/// <summary>The text colors offered in the color picker.</summary>
public IReadOnlyList<string> TextColors { get; set; } =
["#000000", "#d32f2f", "#1976d2", "#388e3c", "#f57c00", "#7b1fa2", "#616161"];
public IReadOnlyList<TypographyColor> TextColors { get; set; } =
[
new("Black", CssColor.FromHex(0x000000)),
new("Red", CssColor.FromHex(0xd32f2f)),
new("Blue", CssColor.FromHex(0x1976d2)),
new("Green", CssColor.FromHex(0x388e3c)),
new("Orange", CssColor.FromHex(0xf57c00)),
new("Purple", CssColor.FromHex(0x7b1fa2)),
new("Gray", CssColor.FromHex(0x616161)),
];

/// <summary>The highlight background colors offered in the highlight picker.</summary>
public IReadOnlyList<string> HighlightColors { get; set; } =
["#ffff00", "#a5d6a7", "#90caf9", "#ffcc80", "#ce93d8", "#e0e0e0"];
public IReadOnlyList<TypographyColor> HighlightColors { get; set; } =
[
new("Yellow", CssColor.FromHex(0xffff00)),
new("Green", CssColor.FromHex(0xa5d6a7)),
new("Blue", CssColor.FromHex(0x90caf9)),
new("Orange", CssColor.FromHex(0xffcc80)),
new("Purple", CssColor.FromHex(0xce93d8)),
new("Gray", CssColor.FromHex(0xe0e0e0)),
];
}
Original file line number Diff line number Diff line change
Expand Up @@ -114,6 +114,7 @@ public sealed class RichTextPreviewViewPlugin : IComposerViewPlugin
{
Id = $"zoom:{zoom}",
Title = zoom.ToString(CultureInfo.InvariantCulture) + "%",
IsTitleVerbatim = true,
Command = ZoomCommandPrefix + zoom.ToString(CultureInfo.InvariantCulture),
})],
},
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,8 @@ public sealed record ComposerToolbarRowLayout(
/// editor's surface, the rows its feature plugins declare. A row holding no items is left out, the built-in row excepted,
/// and an item naming a row the layout does not hold lands on the plugins row where the layout has one. A standard row
/// and a standard group take the composer's own title, localized for the composer, whichever plugin declares them; every
/// other title is localized for the plugin that declared it.
/// other title is localized for the plugin that declared it, an option's title excepted where
/// <see cref="ToolbarOption.IsTitleVerbatim"/> leaves it as written.
/// </remarks>
public sealed class ComposerToolbarLayout
{
Expand Down Expand Up @@ -142,7 +143,7 @@ private static ToolbarItem Localize(ToolbarItem item, IComposerPlugin contributo
ToolbarMenu menu => menu with
{
Title = localize(contributor, menu.Title),
Options = [.. menu.Options.Select(option => option with { Title = localize(contributor, option.Title) })],
Options = [.. menu.Options.Select(option => option.IsTitleVerbatim ? option : option with { Title = localize(contributor, option.Title) })],
},
_ => item with { Title = localize(contributor, item.Title) },
};
Expand Down
2 changes: 1 addition & 1 deletion src/Framework/Forma.Framework.Localization/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -335,7 +335,7 @@ and referencing this package, whose build does the rest:
</PropertyGroup>

<ItemGroup>
<PackageReference Include="formaui-net.Framework.Localization" Version="1.0.0-preview.10" />
<PackageReference Include="formaui-net.Framework.Localization" Version="1.0.0-preview.11" />
</ItemGroup>

</Project>
Expand Down
3 changes: 2 additions & 1 deletion src/Framework/Forma.Framework.Toolbar/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -162,7 +162,8 @@ Every item, through `ToolbarItem`:

`ToolbarToggle` adds `IsActive`, `AlternateTitle` and `AlternateIcon`. `ToolbarMenu` has
`Options`, each a `ToolbarOption` with its own `Id`, `Title`, `Icon` and `Command`, plus
`IsActive` for the option matching the current state, `PreviewStyle`, inline CSS previewing the
`IsActive` for the option matching the current state, `IsTitleVerbatim` for a title that is a value
shown as written, such as a font's name or a size, `PreviewStyle`, inline CSS previewing the
option on its own label, and `Swatch`, a CSS color drawn beside it. `ToolbarReadout` has `Value`
and `IsAnnounced`. `ToolbarCustomItem` has `Component`, the component type, and `Parameters`,
handed to it as given. `ToolbarGroup` has `Items`.
Expand Down
3 changes: 3 additions & 0 deletions src/Framework/Forma.Framework.Toolbar/ToolbarOption.cs
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,9 @@ public sealed record ToolbarOption
/// <summary>The option's label and accessible name, localized by the host.</summary>
public required string Title { get; init; }

/// <summary>Whether <see cref="Title"/> is a value shown as written, such as a font's name or a size, which a host localizing the titles it is handed leaves as it is.</summary>
public bool IsTitleVerbatim { get; init; }

/// <summary>The icon shown beside the option.</summary>
public Icon? Icon { get; init; }

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,14 @@
"Paragraph Style": "סגנון פסקה",
"Typography": "טיפוגרפיה",
"Color": "צבע",
"Black": "שחור",
"Red": "אדום",
"Blue": "כחול",
"Green": "ירוק",
"Orange": "כתום",
"Purple": "סגול",
"Gray": "אפור",
"Yellow": "צהוב",
"History": "היסטוריה",
"Document Status": "מצב המסמך",
"Grouped Commands": "פקודות מקובצות",
Expand Down
Loading
Loading