# `Kotoba.Nodes.Text`
[🔗](https://github.com/hattoriai/kotoba/blob/v0.5.0/lib/kotoba/nodes/text.ex#L1)

A run of text (Lexical type `"text"`).

`format` is a bitmask of text formats. Use `formats/1` and `format?/2` to
read it:

| Format           | Bit   |
| ---------------- | ----- |
| `:bold`          | `1`   |
| `:italic`        | `2`   |
| `:strikethrough` | `4`   |
| `:underline`     | `8`   |
| `:code`          | `16`  |
| `:subscript`     | `32`  |
| `:superscript`   | `64`  |
| `:highlight`     | `128` |
| `:lowercase`     | `256` |
| `:uppercase`     | `512` |
| `:capitalize`    | `1024` |

In HTML, the formats become `strong`, `em`, `s`, `u`, `code`, `sub`,
`sup` and `mark`, and the three text transforms become `span` elements
with the classes `kotoba-lowercase`, `kotoba-uppercase` and
`kotoba-capitalize`. The `style` of the run is not rendered, but for its
colors (see `colors/1`).

## Colors

A run has a text color and a highlight color from a palette (the
`highlight` feature of `Kotoba.Features`): `red`, `orange`, `yellow`,
`green`, `blue`, `purple` and `gray` (`palette/0`). The editor stores them
in the `style`, as the custom properties of the theme:

    color: var(--kotoba-color-red);background-color: var(--kotoba-highlight-green);

A highlight color goes with the `:highlight` format. The format with no
color is the default highlight, `yellow`. In HTML, a text color is a
`span` with the class `kotoba-color-<name>`, and a highlight color is the
class `kotoba-highlight-<name>` of the `mark` (the default highlight is a
`mark` with no class). Any other `style` is ignored: a color that is not
in the palette, or a declaration that is not one of these two, renders
nothing. `kotoba.css` has the classes.

`mode` is `"normal"`, `"token"` or `"segmented"`. `detail` is a bitmask
that Lexical uses for special characters. `style` is an inline CSS text
that Lexical keeps for the run.

# `format`

```elixir
@type format() ::
  :bold
  | :italic
  | :strikethrough
  | :underline
  | :code
  | :subscript
  | :superscript
  | :highlight
  | :lowercase
  | :uppercase
  | :capitalize
```

A text format.

# `t`

```elixir
@type t() :: %Kotoba.Nodes.Text{
  detail: term(),
  extra: term(),
  format: term(),
  mode: term(),
  style: term(),
  text: term(),
  version: term()
}
```

# `bitmask`

```elixir
@spec bitmask([format()]) :: non_neg_integer()
```

Returns the format bitmask for a list of formats.

## Examples

    iex> Kotoba.Nodes.Text.bitmask([:bold, :code])
    17

# `colors`

```elixir
@spec colors(%{
  :format =&gt; integer(),
  :style =&gt; String.t() | nil,
  optional(atom()) =&gt; any()
}) :: %{
  text: String.t() | nil,
  highlight: String.t() | nil
}
```

Returns the colors of a text node: its text color and its highlight
color, each a name of `palette/0` or `nil`.

The highlight color is `nil` without the `:highlight` format, and
`"yellow"` (the default) for the format with no color.

## Examples

    iex> Kotoba.Nodes.Text.colors(%Kotoba.Nodes.Text{
    ...>   text: "x",
    ...>   format: 128,
    ...>   style: "color: var(--kotoba-color-red);background-color: var(--kotoba-highlight-green);"
    ...> })
    %{text: "red", highlight: "green"}

    iex> Kotoba.Nodes.Text.colors(%Kotoba.Nodes.Text{text: "x", format: 128, style: "color: red"})
    %{text: nil, highlight: "yellow"}

# `format?`

```elixir
@spec format?(integer() | %{format: integer()}, format()) :: boolean()
```

Returns `true` when the format is set in a format bitmask, or in the
bitmask of a text node.

## Examples

    iex> Kotoba.Nodes.Text.format?(1, :bold)
    true

    iex> Kotoba.Nodes.Text.format?(1, :italic)
    false

# `formats`

```elixir
@spec formats(integer() | %{:format =&gt; integer(), optional(atom()) =&gt; term()}) :: [
  format()
]
```

Returns the formats that are set in a format bitmask, or in the bitmask of
a text node.

## Examples

    iex> Kotoba.Nodes.Text.formats(3)
    [:bold, :italic]

    iex> Kotoba.Nodes.Text.formats(%Kotoba.Nodes.Text{text: "x", format: 16})
    [:code]

# `markdown_body`

```elixir
@spec markdown_body(t()) :: String.t()
```

Returns the Markdown of the text with no format markers: a code span for
inline code, else the escaped text.

# `markdown_formats`

```elixir
@spec markdown_formats(t()) :: [atom()]
```

Returns the formats of the text that Markdown has markers for, in the
order of their markers: `:bold`, `:italic`, `:underline`,
`:strikethrough` and `:highlight`. Inline code is the body itself (see
`markdown_body/1`). A text color, and the color of a highlight, have no
Markdown: the text keeps its words and the default highlight.

# `markdown_marker`

```elixir
@spec markdown_marker(atom()) :: String.t()
```

Returns the Markdown marker of a format of `markdown_formats/1`.

# `palette`

```elixir
@spec palette() :: [String.t()]
```

Returns the names of the palette, in order.

## Examples

    iex> "green" in Kotoba.Nodes.Text.palette()
    true

---

*Consult [api-reference.md](api-reference.md) for complete listing*