# 06 — Components and templates

Two layers with different jobs. Components are single UI elements. Templates
are compositions of components that solve a recurring product problem, with the
design decisions already made.

The practical value of the template layer is that it settles arguments. When a
team debates how a wizard should behave or where a destructive confirmation
goes, there is an HPE answer already written down.

## Components

48 documented component pages, plus an `all-components` index. Grouped by what
they do:

**Layout and structure**
`box`, `grid`, `page`, `main`, `header`, `footer`, `pageheader`, `toolbar`,
`layer`

**Input**
`textinput`, `textarea`, `maskedinput`, `dateinput`, `fileinput`, `rangeinput`,
`search`, `select`, `selectmultiple`, `checkbox`, `checkboxgroup`,
`radiobuttongroup`, `togglegroup`

**Action and navigation**
`button`, `anchor`, `menu`, `tabs`, `pagination`

**Content display**
`card` (with `call-to-action-card` and `navigational-card` variants),
`accordion`, `avatar`, `namevaluelist`, `tag`, `tip`

**Feedback and state**
`notification`, `spinner`, `skeleton`

**Data**
This is the largest family and the one most relevant to any management or
operations UI:
`data`, `datatable`, `datatablecolumns`, `datatablegroupby`, `dataview`,
`datafilter`, `datafilters`, `datasearch`, `datasort`, `datasummary`

The `data` component is the container that wires the others together, giving
you search, filter, sort, and summary against one dataset without hand-wiring
state. Worth knowing before anyone builds a filterable table from scratch.

## Templates

27 template pages covering 26 topics.

**Navigation** (five separate patterns, each for a different information shape)
- `navigation` (the overview)
- `ascending-navigation` — moving up a hierarchy
- `drill-down-navigation` — moving down into detail
- `side-to-side-navigation` — moving between peers
- `matrix-navigation` — moving across two dimensions
- `global-header`

**Layout**
- `page-layouts`
- `content-layouts`
- `dashboards`

**Data interaction**
- `filtering`
- `lists`
- `selector`
- `datatable-customization`
- `scrolling-and-pagination`

**Forms and flows**
- `forms`, with a sub-page on `managing-child-objects`
- `wizard`
- `double-confirmation` — the pattern for destructive actions
- `empty-state`

**Notifications** (three placements, three different jobs)
- `global-notifications` — system-wide, persistent
- `inline-notifications` — attached to content
- `toast-notifications` — transient

**Other**
- `status-indicator`
- `popover`
- `code-blocks`
- `internationalization`
- `user-feedback-collection`

## Which layer to reach for

The stated token rule applies here by analogy: **start with the most specific
thing that exists.**

1. Is there a template for this problem? Use it. The composition decisions are
   made.
2. No template but components exist? Compose them.
3. Neither? Build from tokens, and consider raising it in
   `#hpe-design-system`, since a gap that affects you likely affects others.

## Learn

Four tutorials, aimed at people new to Grommet rather than at design decisions:

- `grid-fundamentals-part-one`
- `the-box-model-part-one`
- `how-to-add-additional-controls-to-a-toolbar`
- `how-to-add-search-and-filter-to-datatable-with-data`

The "part one" naming on two of them with no part two suggests this section was
started and not finished. Treat it as a bonus, not a curriculum.

## Reading component docs without the website

The site renders in the browser and returns no useful content to `curl`. To
read a component's guidance programmatically, go to the MDX source:

```
https://github.com/grommet/hpe-design-system
  → apps/docs/src/pages/components/<name>.mdx
  → apps/docs/src/pages/templates/<name>.mdx
```

Raw file access works over `raw.githubusercontent.com`. The MDX carries the
prose and the best-practice do/don't pairs; the live examples are React
components imported from `apps/docs/src/examples/`.

Component API reference (props) lives on Grommet's own site,
`v2.grommet.io/<component>?theme=hpe`, not in the design system docs. The
design system says *when and why*; Grommet says *what the props are*.

## Open questions

- How much of the component set is HPE-specific versus plain Grommet with a
  theme applied? This decides how much of the Grommet ecosystem transfers.
- Are the data components performant at the row counts a real usage dashboard
  needs, or do they assume paged server-side data?
- Is there a template for the case of an application embedded inside another
  HPE console, where the global header is owned by the host?