# `A2UI.Surface`
[🔗](https://github.com/23min/ex_a2ui/blob/main/lib/a2ui/surface.ex#L1)

An A2UI surface — a canvas holding a flat list of components.

A surface is the top-level container for A2UI components. It has a unique `id`,
a list of components (flat adjacency list, not nested tree), an optional
`root_component_id` that identifies the entry point for rendering, and an
optional `data` map for initial data model values.

## Why flat?

A2UI uses a flat adjacency list rather than nested component trees. This makes
surfaces LLM-friendly (flat lists are easier to generate incrementally than
nested trees) and enables efficient streaming updates (add, modify, or remove
individual components without rebuilding the whole structure).

Parent-child relationships are expressed via `children` property on container
components (Card, Row, Column, etc.), which reference other component IDs.

## Examples

    %A2UI.Surface{
      id: "dashboard",
      root_component_id: "main-card",
      components: [
        %A2UI.Component{id: "title", type: :text, properties: %{...}},
        %A2UI.Component{id: "main-card", type: :card, properties: %{
          children: ["title"]
        }}
      ]
    }

# `t`

```elixir
@type t() :: %A2UI.Surface{
  catalog_id: String.t() | nil,
  components: [A2UI.Component.t()],
  data: map(),
  id: String.t(),
  root_component_id: String.t() | nil
}
```

# `add_component`

```elixir
@spec add_component(t(), A2UI.Component.t()) :: t()
```

Adds a component to the surface.

# `component_count`

```elixir
@spec component_count(t()) :: non_neg_integer()
```

Returns the number of components in the surface.

# `get_component`

```elixir
@spec get_component(t(), String.t()) :: A2UI.Component.t() | nil
```

Finds a component by ID.

# `new`

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

Creates a new empty surface.

# `put_data`

```elixir
@spec put_data(t(), String.t(), term()) :: t()
```

Sets a value in the surface's data model.

# `set_root`

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

Sets the root component ID for rendering.

---

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