📝 document formatter mode aliases

docs/api/color-mode.md

@@ -0,0 +1,71 @@
+---
+name: color-mode
+group: api
+category: formatter
+update-time: 20260613
+description: Public color-mode enum alias used by text formatters and formatter config.
+key-word:
+    - color
+    - formatter
+    - alias
+    - public
+---
+
+## Color-mode
+
+`ColorMode` is the public enum that controls when ANSI color rendering is enabled for text formatting. It is a direct alias to the formatter enum used by both `text_formatter(...)` and `TextFormatterConfig::new(...)`.
+
+### Interface
+
+```moonbit
+pub type ColorMode = @utils.ColorMode
+```
+
+#### output
+
+- `ColorMode` - Public formatter color-policy enum with the variants `Never`, `Auto`, and `Always`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This is a type alias, not a wrapper or a separate formatter mode.
+- `ColorMode::Never` disables ANSI color output.
+- `ColorMode::Always` always enables ANSI color rendering.
+- `ColorMode::Auto` currently follows the built-in `NO_COLOR` environment check.
+- The same enum is used by runtime formatters and serializable formatter config objects.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Plain Text Without ANSI Codes
+
+When logs should stay uncolored even if the terminal supports color:
+```moonbit
+let formatter = text_formatter(color_mode=ColorMode::Never)
+```
+
+In this example, rendered text keeps the formatter output readable without ANSI escape sequences.
+
+#### When Need Forced Terminal Colors
+
+When tests or demos should always emit colored output:
+```moonbit
+let formatter = text_formatter(color_mode=ColorMode::Always)
+```
+
+In this example, ANSI color rendering is enabled regardless of `NO_COLOR`.
+
+### Error Case
+
+e.g.:
+- `ColorMode` itself does not have a runtime failure mode.
+
+- `ColorMode::Auto` is policy-based, so the final visible result still depends on environment state such as `NO_COLOR`.
+
+### Notes
+
+1. Use `color_mode_label(...)` when you need a stable string form for diagnostics or tests.
+
+2. This enum controls whether color is used, while `ColorSupport` controls how rich the color encoding can be.

docs/api/color-support.md

@@ -0,0 +1,77 @@
+---
+name: color-support
+group: api
+category: formatter
+update-time: 20260613
+description: Public color-support enum alias used by text formatters and formatter config.
+key-word:
+    - color
+    - formatter
+    - alias
+    - public
+---
+
+## Color-support
+
+`ColorSupport` is the public enum that controls how much color precision a text formatter should use when ANSI color output is enabled. It is a direct alias to the formatter enum used by both runtime formatters and serializable formatter config.
+
+### Interface
+
+```moonbit
+pub type ColorSupport = @utils.ColorSupport
+```
+
+#### output
+
+- `ColorSupport` - Public formatter color-capability enum with the variants `Basic` and `TrueColor`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This is a type alias, not a wrapper or a separate rendering engine.
+- `ColorSupport::Basic` prefers named/basic ANSI color codes.
+- `ColorSupport::TrueColor` allows 24-bit color codes when the style input uses values such as hex colors.
+- This setting only matters when color output is enabled through `ColorMode`.
+- The same enum is used by `text_formatter(...)` and `TextFormatterConfig::new(...)`.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Conservative Basic ANSI Colors
+
+When output should stay within the smaller named ANSI color set:
+```moonbit
+let formatter = text_formatter(
+  color_mode=ColorMode::Always,
+  color_support=ColorSupport::Basic,
+)
+```
+
+In this example, style rendering prefers the basic color vocabulary instead of 24-bit codes.
+
+#### When Need Hex-style Richer Color Rendering
+
+When custom style tags should preserve truecolor output where possible:
+```moonbit
+let formatter = text_formatter(
+  color_mode=ColorMode::Always,
+  color_support=ColorSupport::TrueColor,
+)
+```
+
+In this example, formatter styles can emit richer ANSI color codes for hex-based styles.
+
+### Error Case
+
+e.g.:
+- `ColorSupport` itself does not have a runtime failure mode.
+
+- If `ColorMode::Never` disables ANSI color output, changing `ColorSupport` does not produce a visible effect.
+
+### Notes
+
+1. Use `color_support_label(...)` when you need a stable string form.
+
+2. This enum controls color precision, not whether color rendering is enabled at all.

docs/api/index.md

@@ -61,6 +61,9 @@ BitLogger API navigation.
 
 - [field.md](./field.md)
 - [record-formatter.md](./record-formatter.md)
+- [color-mode.md](./color-mode.md)
+- [color-support.md](./color-support.md)
+- [style-markup-mode.md](./style-markup-mode.md)
 - [text-style.md](./text-style.md)
 - [style-tag-registry.md](./style-tag-registry.md)
 - [default-style-tag-registry.md](./default-style-tag-registry.md)

docs/api/style-markup-mode.md

@@ -0,0 +1,71 @@
+---
+name: style-markup-mode
+group: api
+category: formatter
+update-time: 20260613
+description: Public style-markup enum alias used by text formatter message, target, and field rendering.
+key-word:
+    - style
+    - formatter
+    - alias
+    - public
+---
+
+## Style-markup-mode
+
+`StyleMarkupMode` is the public enum that controls whether inline style tags should be parsed by a text formatter. It is a direct alias to the formatter enum used for message text, target text, and field-value rendering scopes.
+
+### Interface
+
+```moonbit
+pub type StyleMarkupMode = @utils.StyleMarkupMode
+```
+
+#### output
+
+- `StyleMarkupMode` - Public formatter markup-policy enum with the variants `Disabled`, `Builtin`, and `Full`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This is a type alias, not a wrapper or separate parser surface.
+- `StyleMarkupMode::Disabled` treats inline markup as plain text.
+- `StyleMarkupMode::Builtin` limits tag resolution to the built-in tag set.
+- `StyleMarkupMode::Full` allows local style tags, global style tags, and built-in tags to participate in resolution.
+- The same enum is used by `style_markup`, `target_style_markup`, and `fields_style_markup` in formatter APIs.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need To Disable Inline Tag Parsing Entirely
+
+When message text should remain literal even if it contains style-like tags:
+```moonbit
+let formatter = text_formatter(style_markup=StyleMarkupMode::Disabled)
+```
+
+In this example, strings such as `<accent>hello</>` are kept as plain text.
+
+#### When Need Only Built-in Tag Support
+
+When formatters should allow the built-in tag vocabulary without opening custom registry behavior:
+```moonbit
+let formatter = text_formatter(style_markup=StyleMarkupMode::Builtin)
+```
+
+In this example, built-in tags such as `<warning>...</>` can be resolved while custom registry tags are not the source of truth.
+
+### Error Case
+
+e.g.:
+- `StyleMarkupMode` itself does not have a runtime failure mode.
+
+- Unknown or invalid tags do not raise an error; current behavior falls back to plain text handling.
+
+### Notes
+
+1. Use `style_markup_mode_label(...)` when you need a stable string form for logging or assertions.
+
+2. Message, target, and field rendering each have their own markup scope, so one formatter can mix different markup policies deliberately.