From 038c37992fd35f8fa3dd52b157a3e587a94ae57b Mon Sep 17 00:00:00 2001
From: Nanaloveyuki <miaomiao_159@outlook.com>
Date: Sat, 13 Jun 2026 22:11:32 +0800
Subject: [PATCH] :memo: document formatter color and registry methods

---
 docs/api/index.md                             |  2 +
 docs/api/text-formatter-with-color-support.md | 78 +++++++++++++++++++
 docs/api/text-formatter-with-style-tags.md    | 77 ++++++++++++++++++
 3 files changed, 157 insertions(+)
 create mode 100644 docs/api/text-formatter-with-color-support.md
 create mode 100644 docs/api/text-formatter-with-style-tags.md

diff --git a/docs/api/index.md b/docs/api/index.md
index 6468e1c..1753282 100644
--- a/docs/api/index.md
+++ b/docs/api/index.md
@@ -82,6 +82,8 @@ BitLogger API navigation.
 - [text-formatter-without-style-markup.md](./text-formatter-without-style-markup.md)
 - [text-formatter-with-target-style-markup.md](./text-formatter-with-target-style-markup.md)
 - [text-formatter-with-fields-style-markup.md](./text-formatter-with-fields-style-markup.md)
+- [text-formatter-with-color-support.md](./text-formatter-with-color-support.md)
+- [text-formatter-with-style-tags.md](./text-formatter-with-style-tags.md)
 - [format-text.md](./format-text.md)
 - [format-json.md](./format-json.md)
 - [text-formatter-config.md](./text-formatter-config.md)
diff --git a/docs/api/text-formatter-with-color-support.md b/docs/api/text-formatter-with-color-support.md
new file mode 100644
index 0000000..c13ceb6
--- /dev/null
+++ b/docs/api/text-formatter-with-color-support.md
@@ -0,0 +1,78 @@
+---
+name: text-formatter-with-color-support
+group: api
+category: formatter
+update-time: 20260613
+description: Return a TextFormatter with a different color precision setting.
+key-word:
+    - formatter
+    - color
+    - support
+    - public
+---
+
+## Text-formatter-with-color-support
+
+Return a copy of a `TextFormatter` with a different `ColorSupport` setting. This method is the focused way to change color precision for ANSI rendering while preserving the formatter's layout, markup, and registry behavior.
+
+### Interface
+
+```moonbit
+pub fn TextFormatter::with_color_support(self : TextFormatter, color_support : ColorSupport) -> TextFormatter {
+```
+
+#### input
+
+- `self : TextFormatter` - Base formatter to copy.
+- `color_support : ColorSupport` - New color precision policy.
+
+#### output
+
+- `TextFormatter` - A new formatter value carrying the updated color support setting.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This method only changes `color_support`.
+- The returned formatter preserves timestamp, level, target, fields, template, markup settings, and style tags from `self`.
+- The setting only matters when color output is enabled through `ColorMode`.
+- The original formatter value is not mutated.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need To Downgrade To Basic ANSI Colors
+
+When one formatter should stay compatible with terminals that only handle simpler color sequences:
+```moonbit
+let formatter = text_formatter(color_mode=ColorMode::Always)
+  .with_color_support(ColorSupport::Basic)
+```
+
+In this example, the formatter keeps its overall behavior but prefers the basic ANSI color vocabulary.
+
+#### When Need Two Precision Variants Of One Formatter
+
+When the same base formatter should produce basic and truecolor variants:
+```moonbit
+let base = text_formatter(color_mode=ColorMode::Always)
+let basic = base.with_color_support(ColorSupport::Basic)
+let rich = base.with_color_support(ColorSupport::TrueColor)
+```
+
+In this example, both derived formatters keep the same markup and layout settings.
+
+### Error Case
+
+e.g.:
+- There is no separate failure path for valid `TextFormatter` and `ColorSupport` values.
+
+- If `ColorMode::Never` disables color output, changing `color_support` does not produce a visible effect.
+
+### Notes
+
+1. Use this method for color precision changes without rebuilding the whole formatter explicitly.
+
+2. It is useful when one formatter definition should be reused across terminals with different color capabilities.
diff --git a/docs/api/text-formatter-with-style-tags.md b/docs/api/text-formatter-with-style-tags.md
new file mode 100644
index 0000000..0fa5534
--- /dev/null
+++ b/docs/api/text-formatter-with-style-tags.md
@@ -0,0 +1,77 @@
+---
+name: text-formatter-with-style-tags
+group: api
+category: formatter
+update-time: 20260613
+description: Return a TextFormatter with a specific local StyleTagRegistry attached.
+key-word:
+    - formatter
+    - style
+    - registry
+    - public
+---
+
+## Text-formatter-with-style-tags
+
+Return a copy of a `TextFormatter` with a specific local `StyleTagRegistry` attached. This method is the direct way to make one formatter use custom or overridden tag definitions without changing shared global registry state.
+
+### Interface
+
+```moonbit
+pub fn TextFormatter::with_style_tags(self : TextFormatter, style_tags : StyleTagRegistry) -> TextFormatter {
+```
+
+#### input
+
+- `self : TextFormatter` - Base formatter to copy.
+- `style_tags : StyleTagRegistry` - Local registry to attach to the returned formatter.
+
+#### output
+
+- `TextFormatter` - A new formatter value whose `style_tags` field is set to `Some(style_tags)`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This method only changes the formatter's local `style_tags` attachment.
+- The returned formatter preserves timestamp, level, target, field, template, color, and markup settings from `self`.
+- Local style tags take precedence over global registry lookup, which in turn takes precedence over builtin tags.
+- The original formatter value is not mutated.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Custom Tags For One Formatter Only
+
+When one formatter should understand project-specific tag names without touching global state:
+```moonbit
+let tags = style_tag_registry().set_tag("accent", fg=Some("#4cc9f0"), bold=true)
+let formatter = text_formatter(color_mode=ColorMode::Always).with_style_tags(tags)
+```
+
+In this example, the custom registry only affects the returned formatter value.
+
+#### When Need To Override A Built-in Tag Locally
+
+When a formatter should keep the standard tag vocabulary but change one entry:
+```moonbit
+let tags = default_style_tag_registry().set_tag("success", fg=Some("#22cc88"), underline=true)
+let formatter = text_formatter(color_mode=ColorMode::Always).with_style_tags(tags)
+```
+
+In this example, the local registry shadows the built-in or global `success` definition for that formatter.
+
+### Error Case
+
+e.g.:
+- If the relevant markup scopes are disabled, attaching local tags does not produce a visible effect.
+
+- If callers actually want to change shared process-wide tag resolution, `set_global_style_tag_registry(...)` is the better API.
+
+### Notes
+
+1. This is the local, formatter-scoped alternative to editing the global style tag registry.
+
+2. It is the natural companion to `style_tag_registry()` and `default_style_tag_registry()`.