# Components and Styles

Components are imported from `@minidocs/astro/components`. Every component passes attributes it does not list on to the element it renders, and merges `class` with its own classes.

## Components

### Layout components

| Component        | Renders     | Props                                                                       |
| ---------------- | ----------- | --------------------------------------------------------------------------- |
| `Layout.Root`    | `<div>`     | None                                                                        |
| `Layout.Header`  | `<header>`  | The `end` slot sits on the right                                            |
| `Layout.Title`   | `<a>`       | `href`                                                                      |
| `Layout.Sidebar` | `<aside>`   | None                                                                        |
| `Layout.Main`    | `<main>`    | None                                                                        |
| `Layout.Aside`   | `<details>` | `title`: the heading of the column, also the text of the button when folded |
| `Prose`          | `<article>` | None                                                                        |

### Sidebar components

| Component         | Renders                                                          | Props                                                                                                                                                                                                           |
| ----------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Sidebar.Root`    | `<nav>`                                                          | `id`; `label`: the accessible name of the navigation                                                                                                                                                            |
| `Sidebar.List`    | `<ul>`                                                           | None                                                                                                                                                                                                            |
| `Sidebar.Item`    | `<li>`                                                           | None                                                                                                                                                                                                            |
| `Sidebar.Link`    | `<a>`                                                            | `href`; `current`: whether it is the current page                                                                                                                                                               |
| `Sidebar.Label`   | `<span>`                                                         | None                                                                                                                                                                                                            |
| `Sidebar.Group`   | `<details>` without `href` or on its own page, otherwise `<div>` | `open`: whether it starts open; `name`: groups sharing a name open one at a time; `href`: the group’s own page; `current`: whether the group’s own page is the current page. The title goes in the `label` slot |
| `Sidebar.Trigger` | `<button>`                                                       | `target`: the `id` of the `Sidebar.Root` to open and close                                                                                                                                                      |

`Sidebar.Link` also accepts and ignores `open`, so `nav.of(node)` can be spread onto any of these components.

### Table of contents components

| Component  | Renders | Props                         |
| ---------- | ------- | ----------------------------- |
| `Toc.Root` | `<nav>` | `label`                       |
| `Toc.List` | `<ul>`  | None                          |
| `Toc.Item` | `<li>`  | None                          |
| `Toc.Link` | `<a>`   | `slug`: the id of the heading |

### Previous and next components

| Component     | Renders  | Props                           |
| ------------- | -------- | ------------------------------- |
| `Pager.Root`  | `<nav>`  | `label`                         |
| `Pager.Link`  | `<a>`    | `href`; `rel`: `prev` or `next` |
| `Pager.Label` | `<span>` | None                            |
| `Pager.Title` | `<span>` | None                            |

### Callout components

| Component       | Renders             | Props                                                                         |
| --------------- | ------------------- | ----------------------------------------------------------------------------- |
| `Callout.Root`  | `<div role="note">` | `type`: `note`, `tip`, `important`, `warning` or `caution`, `note` by default |
| `Callout.Title` | `<p>`               | None                                                                          |

### Search components

| Component                                           | Renders    | Props                                                                                                        |
| --------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------ |
| `Search.Trigger`                                    | `<button>` | `target`: the `id` of `Search.Root`; `shortcut`: the keyboard shortcut, `Mod+K` by default, `false` for none |
| `Search.Shortcut`                                   | `<kbd>`    | None                                                                                                         |
| `Search.Root`                                       | `<search>` | `id`, required                                                                                               |
| `Search.Dialog`                                     | `<dialog>` | `label`                                                                                                      |
| `Search.Input`                                      | `<input>`  | `label`, `placeholder`                                                                                       |
| `Search.Results`                                    | `<div>`    | `label`                                                                                                      |
| `Search.Idle`, `Loading`, `Found`, `Empty`, `Error` | `<div>`    | None                                                                                                         |
| `Search.Query`, `Search.Count`                      | `<span>`   | None                                                                                                         |

## Behavior functions

Components come with their interactions. When you write your own HTML instead, import the matching function from `@minidocs/astro/behaviors` and attach it to the element. Each function returns a cleanup function.

| Function                                            | What it does                                                                                                                          |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `attachSidebar(root)`                               | Remembers open groups and the scroll position, and restores them on the next page. Groups need `data-md-sidebar-group`                |
| `attachTrigger(button)`                             | Makes the button open and close the element its `aria-controls` names, closing on Esc or a click outside                              |
| `attachToc(root)`                                   | Marks the link of the section being read with `aria-current="true"`. The links are every `<a>` in `root` whose `href` starts with `#` |
| `attachSearch(root, { source, render, debounce? })` | Runs search. `debounce` is how many milliseconds after the last keystroke the search starts, `100` by default                         |
| `splitMarks(html)`                                  | Splits HTML with `<mark>` into `{ text, marked }` pieces, keeping only the text of other tags                                         |

## Events

All of them bubble.

| Event               | Dispatched on | When                                    | `detail`            |
| ------------------- | ------------- | --------------------------------------- | ------------------- |
| `md:sidebar-toggle` | The sidebar   | Opened or closed with `Sidebar.Trigger` | `{ open }`          |
| `md:toc-change`     | `Toc.Root`    | The section being read changed          | `{ link }`          |
| `md:search-open`    | `Search.Root` | The dialog opened                       | None                |
| `md:search-close`   | `Search.Root` | The dialog closed                       | None                |
| `md:search-select`  | `Search.Root` | A result was selected                   | `{ option, query }` |
| `md:search-error`   | `Search.Root` | `source` threw                          | `{ error, query }`  |

## CSS variables

The variables of the default styles are defined on `:root`, and your styles can override them.

| Variable                           | What it sets                                                                        |
| ---------------------------------- | ----------------------------------------------------------------------------------- |
| `--md-color-bg`                    | Background of the page and the drawer                                               |
| `--md-color-heading`               | Headings, bold text and text on hover                                               |
| `--md-color-text`                  | Body text                                                                           |
| `--md-color-muted`                 | Secondary text, such as the table of contents and list markers                      |
| `--md-color-border`                | Rails, borders and dividers                                                         |
| `--md-color-accent`                | The current position and links, the same as `--md-color-heading` by default         |
| `--md-color-hover`                 | Background on hover                                                                 |
| `--md-color-current`               | Background of the current page                                                      |
| `--md-color-code-bg`               | Background of code blocks                                                           |
| `--md-color-note`                  | Color of `note` callouts                                                            |
| `--md-color-tip`                   | Color of `tip` callouts                                                             |
| `--md-color-important`             | Color of `important` callouts                                                       |
| `--md-color-warning`               | Color of `warning` callouts                                                         |
| `--md-color-caution`               | Color of `caution` callouts                                                         |
| `--md-font-sans`                   | Page font with `Layout.Root`                                                        |
| `--md-font-mono`                   | Code font                                                                           |
| `--md-radius`                      | Corner radius of sidebar items, buttons and images                                  |
| `--md-focus-ring`                  | Outline of keyboard focus                                                           |
| `--md-sidebar-font-size`           | Font size of the sidebar                                                            |
| `--md-sidebar-item-padding-block`  | Vertical padding of sidebar items                                                   |
| `--md-sidebar-item-padding-inline` | Horizontal padding of sidebar items                                                 |
| `--md-sidebar-indent`              | Distance of a nested rail from the level above                                      |
| `--md-sidebar-rail-gap`            | Distance between a rail and its items                                               |
| `--md-toc-font-size`               | Font size of the table of contents                                                  |
| `--md-toc-indent`                  | Indent of each level of the table of contents                                       |
| `--md-prose-font-size`             | Font size of the content                                                            |
| `--md-prose-line-height`           | Line height of the content, 1.75 by default                                         |
| `--md-header-height`               | Height of the header, which also sets where the sidebar and table of contents stick |
| `--md-layout-sidebar-width`        | Width of the sidebar column                                                         |
| `--md-layout-main-width`           | Maximum width of the content column                                                 |
| `--md-layout-aside-width`          | Width of the table of contents column                                               |
| `--md-layout-drawer-width`         | Width of the drawer on narrow screens                                               |

## Classes and states

| Class                                                       | Element                                                  |
| ----------------------------------------------------------- | -------------------------------------------------------- |
| `.md-layout`                                                | `Layout.Root`                                            |
| `.md-layout-header`                                         | `Layout.Header`                                          |
| `.md-layout-title`                                          | `Layout.Title`                                           |
| `.md-layout-sidebar`                                        | `Layout.Sidebar`                                         |
| `.md-layout-main`                                           | `Layout.Main`                                            |
| `.md-layout-aside`                                          | `Layout.Aside`                                           |
| `.md-prose`                                                 | `Prose`                                                  |
| `.md-sidebar`                                               | `Sidebar.Root`                                           |
| `.md-sidebar-list`                                          | `Sidebar.List`                                           |
| `.md-sidebar-item`                                          | `Sidebar.Item`                                           |
| `.md-sidebar-link`                                          | `Sidebar.Link`                                           |
| `.md-sidebar-label`                                         | `Sidebar.Label`                                          |
| `.md-sidebar-group`                                         | `Sidebar.Group`                                          |
| `.md-sidebar-group-title`                                   | The title of a group, a link or a `<summary>`            |
| `.md-sidebar-trigger`                                       | `Sidebar.Trigger`                                        |
| `.md-toc`                                                   | `Toc.Root`                                               |
| `.md-toc-list`                                              | `Toc.List`                                               |
| `.md-toc-item`                                              | `Toc.Item`                                               |
| `.md-toc-link`                                              | `Toc.Link`                                               |
| `.md-pager`                                                 | `Pager.Root`                                             |
| `.md-pager-link`                                            | `Pager.Link`                                             |
| `.md-pager-label`                                           | `Pager.Label`                                            |
| `.md-pager-title`                                           | `Pager.Title`                                            |
| `.md-callout`                                               | `Callout.Root`, and the `:::type` and `> [!TYPE]` syntax |
| `.md-callout-title`                                         | `Callout.Title`, and titles of the directive syntax      |
| `.md-search`                                                | `Search.Root`                                            |
| `.md-search-trigger`                                        | `Search.Trigger`                                         |
| `.md-search-shortcut`                                       | `Search.Shortcut`                                        |
| `.md-search-dialog`                                         | `Search.Dialog`                                          |
| `.md-search-input`                                          | `Search.Input`                                           |
| `.md-search-results`                                        | `Search.Results`                                         |
| `.md-search-idle`, `-loading`, `-found`, `-empty`, `-error` | The state components                                     |
| `.md-search-query`, `.md-search-count`                      | `Search.Query`, `Search.Count`                           |

| State                                           | Selector                                                                         |
| ----------------------------------------------- | -------------------------------------------------------------------------------- |
| The current page                                | `[aria-current="page"]`                                                          |
| The heading being read in the table of contents | `.md-toc-link[aria-current="true"]`                                              |
| The item containing the current page            | `.md-sidebar-item:has(> [aria-current])`                                         |
| A group open or closed                          | `.md-sidebar-group[data-state="open"]`, `[data-state="closed"]`                  |
| The sidebar open or closed                      | `.md-sidebar[data-state="open"]`                                                 |
| An external link                                | `.md-sidebar-link[data-external]`                                                |
| Previous or next                                | `.md-pager-link[rel="prev"]`, `[rel="next"]`                                     |
| The type of a callout                           | `.md-callout[data-type="tip"]` and so on                                         |
| The state of search                             | `.md-search[data-status="found"]` and so on, with `aria-busy` while a query runs |
| The selected search result                      | `[role="option"][aria-selected="true"]`                                          |