# `Macaw.Component.Context`
[🔗](https://github.com/dcoai/macaw_component/blob/v0.1.3/lib/macaw/component/context.ex#L1)

The context a component renders in (spec/02 §2): its mode, instance, size, root font
size, heading level, theme, the viewer's preferences, and the holder's now.

The host computes it: on a page the core, elsewhere the adopter. The component never
knows which, and never reads a clock: `now` is the holder's.

    iex> {:ok, ctx} = Macaw.Component.Context.new(mode: :live, instance: "cards-1", size: {640, 400}, now: ~U[2026-10-28 12:00:00Z])
    iex> {Macaw.Component.Context.heading(ctx, 0), Macaw.Component.Context.heading(ctx, 1)}
    {"h2", "h3"}
    iex> Macaw.Component.Context.id(ctx, "item-3")
    "cards-1-item-3"

# `t`

```elixir
@type t() :: %Macaw.Component.Context{
  heading_level: 1..6,
  instance: String.t(),
  measured: boolean(),
  mode: Macaw.Component.Mode.t(),
  now: DateTime.t(),
  preferences: %{zone: String.t(), units: atom(), shortcuts: map()},
  root_font_size: number(),
  size: {number(), number()},
  theme: Macaw.Layers.Theme.t()
}
```

# `fields`

```elixir
@spec fields() :: [atom(), ...]
```

The fields, in the order of spec/02 §2's table.

# `heading`

```elixir
@spec heading(t(), non_neg_integer()) :: String.t()
```

The heading element `depth` levels below the component's top (`0` for its top):
`"h<level + depth>"`, never past `"h6"`.

# `id`

```elixir
@spec id(t(), String.t()) :: String.t()
```

An element id unique to the instance, `"<instance>-<local>"`, stable across renders.
`local` is a non-empty string of letters, digits, `-` and `_`; anything else raises
`ArgumentError`, a programming error in the component.

# `new`

```elixir
@spec new(keyword() | map()) :: {:ok, t()} | {:error, [Macaw.Component.fault(), ...]}
```

A context from a keyword list or a map: `{:ok, context}` or every fault at once, each
`{[field], reason}`, an unknown field `:unknown_key` and a missing required one
`:required`. The theme defaults to `Macaw.Layers.Theme.default()`.

---

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