{#
  The components that float above the page.

  Basecoat's own JavaScript drives all four, and it is already vendored and
  mounted: it scans for `.popover`, `.dropdown-menu`, `.select` and `.combobox`
  on load and again on `htmx:afterSwap`, so a swapped-in overlay works with
  nothing extra. No macro below registers a handler.

  What they share is id wiring: a trigger and its panel find each other through
  four related ids, and one wrong id fails silently — the panel opens but is
  never announced, or never opens at all. Every macro here takes one `id` and
  derives the rest, which is why they are macros and not snippets to copy.

  `drawer` is the exception: a native `<dialog>` that needs no JS from
  Basecoat, only `showModal()`.

  `multiselect_scripts()` is the one macro here that adds a file to the page,
  and only a page using `multiple=true` calls it. It fixes the wire format
  rather than the widget — see its own comment.
#}
{% from "ui/attrs.html" import attrs %}
{% from "ui/icon.html" import icon %}

{#
  _message(field_id, hint, error) — the paragraph under a scripted control.

  A second copy of the macro `ui/form.html` calls under every field, written
  out here rather than imported. Jinja refuses to import a name beginning with
  an underscore, and renaming that one to make it importable would publish a
  helper no app template should call. It would also change what `fjkit eject`
  does with it: a private helper is copied into the file you own, while a
  public one is re-exported and keeps moving under you. `_GAP` is written out
  twice for the same reason.

  It differs from that copy in one way, and the difference is the point: it
  always renders the paragraph, empty and hidden when there is nothing to say.
  `js/errors.js` reuses the `<p>` a control names in `aria-describedby` and
  creates one where it finds none, inserting it directly after the control. For
  the two macros below, the control carrying `name` is a hidden input at the
  end of a wrapper div, so "after" is inside that wrapper and the 422 would
  draw its red text inside the select box. Reserving the paragraph gives it a
  target in the right place.
#}
{% macro _message(field_id, hint=none, error=none) -%}
  {%- if error %}<p class="text-destructive text-xs" id="{{ field_id }}-hint">{{ error }}</p>
  {%- elif hint %}<p class="text-muted-foreground text-xs" id="{{ field_id }}-hint">{{ hint }}</p>
  {%- else %}<p class="text-muted-foreground text-xs" id="{{ field_id }}-hint" hidden></p>
  {%- endif -%}
{%- endmacro %}

{#
  Panel widths. A popover has to be told how wide to be — its content is out
  of flow, so it has no column to fill — and upstream does that with a utility
  at the call site. A closed lookup instead, for the usual two reasons: an app
  template may not write `w-72` (A2), and an interpolated width renders while
  missing from the stylesheet.
#}
{% set _PANEL_WIDTHS = {
  "auto": "",
  "sm": "w-40",
  "default": "w-56",
  "lg": "w-72",
  "xl": "w-96",
} %}

{#
  popover(id, label, …) — a panel of arbitrary content, anchored to a button.

  Content arrives through `{% call %}`. The trigger is a `button` macro's worth
  of parameters rather than a second slot, because a popover whose trigger is
  not a button is nearly always a `dropdown_menu` or a `tooltip`.

  `aria-expanded` starts false and Basecoat's JS flips it; `aria-hidden` on the
  panel works the same way. Both are written here rather than left off: first
  paint is the state before any JS has run, and a trigger with no
  `aria-expanded` is announced as a plain button.
#}
{% macro popover(id, label, variant="outline", size="", side="bottom", align="center", width="lg", icon_name=none) -%}
  <div id="{{ id }}" class="popover"{% if kwargs %}{{ attrs(kwargs) }}{% endif %}>
    <button type="button" id="{{ id }}-trigger" class="btn"
            data-variant="{{ variant }}"{% if size %} data-size="{{ size }}"{% endif %}
            aria-expanded="false" aria-controls="{{ id }}-popover">
      {%- if icon_name %}{{ icon(icon_name, 16) }}{% endif %}
      {{- label -}}
    </button>
    <div id="{{ id }}-popover" data-popover aria-hidden="true"
         data-side="{{ side }}" data-align="{{ align }}"
         {%- set panel_width = _PANEL_WIDTHS.get(width, "w-72") %}
         {%- if panel_width %} class="{{ panel_width }}"{% endif %}>
      {{- caller() -}}
    </div>
  </div>
{%- endmacro %}

{#
  dropdown_menu(id, label, …) — a menu of commands.

  The panel holds a `role="menu"` labelled by the trigger, and the items are
  `menu_item` / `menu_group` / `menu_separator` below. Three ids have to line
  up for that: trigger, popover and menu. All derived.

  A menu is not a `<select>`. If the items set a value rather than run a
  command, `select_menu` or `select_field` is the component — this one leaves
  nothing behind in a form submission.
#}
{% macro dropdown_menu(id, label, variant="outline", size="", side="bottom", align="start", width="default", icon_name=none) -%}
  <div id="{{ id }}" class="dropdown-menu"{% if kwargs %}{{ attrs(kwargs) }}{% endif %}>
    <button type="button" id="{{ id }}-trigger" class="btn"
            data-variant="{{ variant }}"{% if size %} data-size="{{ size }}"{% endif %}
            aria-haspopup="menu" aria-controls="{{ id }}-menu" aria-expanded="false">
      {%- if icon_name %}{{ icon(icon_name, 16) }}{% endif %}
      {{- label -}}
    </button>
    <div id="{{ id }}-popover" data-popover aria-hidden="true"
         data-side="{{ side }}" data-align="{{ align }}"
         {%- set panel_width = _PANEL_WIDTHS.get(width, "w-56") %}
         {%- if panel_width %} class="{{ panel_width }}"{% endif %}>
      <div role="menu" id="{{ id }}-menu" aria-labelledby="{{ id }}-trigger">
        {{- caller() -}}
      </div>
    </div>
  </div>
{%- endmacro %}

{#
  menu_item(label, …) — one row of a dropdown menu.

  `checked` switches the role from `menuitem` to `menuitemcheckbox`, because
  an item that reports a checked state under the plain role is a contradiction
  a screen reader has no way to resolve. `radio=true` makes it
  `menuitemradio` — same rule, one choice out of several.

  `shortcut` renders a `<kbd>` inside the item. It is decoration: printing
  "⌘S" does not bind ⌘S. Bind it yourself, or leave it out.
#}
{% macro menu_item(label, shortcut=none, variant="", disabled=false, checked=none, radio=false, href=none) -%}
  {%- set role = "menuitemradio" if radio else ("menuitemcheckbox" if checked is not none else "menuitem") -%}
  <{{ "a" if href else "div" }} role="{{ role }}"
    {%- if href %} href="{{ href }}"{% endif %}
    {%- if variant %} data-variant="{{ variant }}"{% endif %}
    {%- if disabled %} aria-disabled="true"{% endif %}
    {%- if checked is not none %} aria-checked="{{ "true" if checked else "false" }}"{% endif %}
    {%- if kwargs %}{{ attrs(kwargs) }}{% endif %}>
    {%- if shortcut %}<span>{{ label }}</span><kbd>{{ shortcut }}</kbd>{% else %}{{ label }}{% endif -%}
  </{{ "a" if href else "div" }}>
{%- endmacro %}

{#
  menu_group(heading) — a labelled run of items.

  The heading is a `role="heading"`, and the group is named after it, so it is
  announced as the group's name rather than read as a menu item nobody can
  activate.

  The name is `aria-label`, not `aria-labelledby` pointing at an id made from
  the heading, for the reason `sidebar_group` gives: a menu rendered once per
  table row repeats every heading, the ids collide, and a colliding reference
  resolves to the first row's heading. Pass `id` to get `aria-labelledby`
  instead; that id is then yours to keep unique.
#}
{% macro menu_group(heading=none, id=none) -%}
  <div role="group"
    {%- if heading and id %} aria-labelledby="{{ id }}"{% elif heading %} aria-label="{{ heading }}"{% endif %}>
    {%- if heading %}<div role="heading"{% if id %} id="{{ id }}"{% endif %}>{{ heading }}</div>{% endif %}
    {{- caller() -}}
  </div>
{%- endmacro %}

{% macro menu_separator() -%}
  <hr role="separator">
{%- endmacro %}

{#
  Multiple selection, shared by `select_menu` and `combobox`.

  Basecoat drives both off one attribute — `aria-multiselectable="true"` on the
  listbox — so `multiple=true` is the whole switch. What it changes here:

  - `selected` becomes a list. It stays a scalar when `multiple` is false, so
    the two are not interchangeable and the macro does not guess.
  - the hidden input carries a JSON array and is marked `data-fjkit-multi`,
    which is what `multiselect_scripts()` looks for.
  - the panel stops closing on each pick. `data-close-on-select` is Basecoat's
    knob and its absence means "stay open", the right default for a control
    whose point is picking more than one thing. `close_on_select` covers the
    list short enough that one pick is the usual case.

  The page must load `multiselect_scripts()`. Without it the field posts
  `labels=["bug","ui"]` — one string, JSON-shaped — instead of `labels=bug&
  labels=ui`, and a route declaring `list[str]` answers 422 while the page
  looks correctly filled in. That is the failure this pair of parameters is
  most likely to produce, so it is stated twice: here and on the script macro.

  An empty selection posts the field zero times, exactly as an untouched
  checkbox group does. Declare `Form([])`, not `Form(...)`, if choosing nothing
  is allowed — otherwise "I cleared it" and "I never opened it" are both a 422.
#}
{#
  _options(options, values) and _hidden_value(…) — the halves `select_menu`
  and `combobox` share. Private, like `_message`: each is only correct inside
  one of those two listboxes.
#}
{% macro _options(options, values) -%}
  {%- for value, option_label in options %}
    <div role="option" data-value="{{ value }}"
         {%- if value in values %} aria-selected="true"{% endif %}>{{ option_label }}</div>
  {%- endfor %}
{%- endmacro %}

{#
  Pre-filled rather than empty: upstream's example ships `value=""` and lets
  its JS write the value on first interaction, so a form submitted without
  touching the control posts nothing — and the round trip that re-renders the
  partial would lose the selection it was given.

  Single-quoted in the multiple case because `tojson` escapes `<`, `>`, `&` and
  `'` but not `"`, and `["a","b"]` inside a double-quoted attribute is a
  truncated value rather than an error.

  `aria-describedby` on the hidden input as well as the visible control, and it
  is not for a screen reader — a hidden input is not exposed to one. It is for
  `js/errors.js`, which finds the control a 422 names by `[name]`, and that is
  this input. Pointed at the reserved paragraph, a rejected `continents` draws
  red text under the field; unpointed, the script builds its own paragraph and
  inserts it inside the widget's box.
#}
{% macro _hidden_value(name, field_id, multiple, values, selected, described) -%}
  {%- if multiple %}
  <input type="hidden" name="{{ name }}" data-fjkit-multi value='{{ values | tojson }}'
         {%- if described %} aria-describedby="{{ field_id }}-hint"{% endif %}>
  {%- else %}
  <input type="hidden" name="{{ name }}" value="{{ selected if selected is not none else "" }}"
         {%- if described %} aria-describedby="{{ field_id }}-hint"{% endif %}>
  {%- endif %}
{%- endmacro %}

{#
  select_menu(name, options, …) — the scripted listbox.

  Prefer `select_field`. A native `<select>` is keyboard- and screen-reader-
  correct for free and costs one element; this one costs ~30 and depends on JS
  being present. Use it only when the rows need markup a native option cannot
  hold — an icon, two lines, a swatch — or when you need `multiple`, which a
  native `<select multiple>` renders as a scrolling box nobody has ever found
  by accident.

  The value reaches the server through the hidden input, which carries `name`;
  the visible trigger is a button and submits nothing. That is why `name` is
  the first parameter and the button has none: a form that posts the button
  posts nothing at all.

      {{ select_menu("labels", options=label_options,
                     selected=task.labels, multiple=true) }}

  `label` is an `aria-label` on the trigger and draws nothing. Pass
  `visible_label` where the control sits in a form beside `text_field` and has
  to look like one: it renders the `.field` wrapper, a real `<label for>` and
  the message paragraph, so the field lines up with its neighbours and a
  rejected submit has somewhere to put red text. `hint` and `error` work as
  they do on every other field, and any one of the three alone is enough to
  make this a field — a hint with no label is still a field.

      {{ select_menu("phase", options=phases, multiple=true,
                     visible_label="Trial phase", hint="Post-filter") }}

  `required` marks the listbox `aria-required`, and beside a `visible_label`
  the label gets the asterisk `fjkit.css` draws for every required field. It
  validates nothing: declare the field without a default on the route's model,
  as for any other field.
#}
{% macro select_menu(name, options=(), selected=none, id=none, placeholder="Select…", width="lg", label=none,
                     multiple=false, close_on_select=false, visible_label=none, hint=none, error=none,
                     required=false) -%}
  {%- set field_id = id or ("s-" ~ name) -%}
  {#
    Any one of the three turns this into a field: the `.field` wrapper, a
    visible `<label>` and the message paragraph, exactly as `text_field`
    renders them. Without them the macro emits the bare control it always did.
  #}
  {%- set as_field = visible_label is not none or hint is not none or error is not none -%}
  {#
    A list either way, so one expression marks the options. `selectattr("0",
    "in", …)` rather than `equalto`: the same test covers both, and for a
    single select it runs over a one-element list.
  #}
  {%- set values = (selected or []) | list if multiple else ([selected] if selected is not none else []) -%}
  {%- set chosen = options | selectattr("0", "in", values) | map(attribute=1) | list -%}
  {%- if as_field %}<div class="field">
    {%- if visible_label %}<label class="label" for="{{ field_id }}-trigger">{{ visible_label }}</label>{% endif %}
  {%- endif %}
  <div id="{{ field_id }}" class="select" data-placeholder="{{ placeholder }}"
       {%- if multiple and close_on_select %} data-close-on-select="true"{% endif %}
       {%- if kwargs %}{{ attrs(kwargs) }}{% endif %}>
    <button type="button" id="{{ field_id }}-trigger"
            {%- set trigger_width = _PANEL_WIDTHS.get(width, "w-72") %}
            {%- if trigger_width %} class="{{ trigger_width }}"{% endif %}
            aria-haspopup="listbox" aria-expanded="false" aria-controls="{{ field_id }}-listbox"
            {#
              Only when nothing visible names the control: a visible `<label
              for>` already names it, and an `aria-label` beside one overrides
              the text on screen with the text in the attribute.
            #}
            {%- if label and not visible_label %} aria-label="{{ label }}"{% endif %}
            {%- if as_field %} aria-describedby="{{ field_id }}-hint"{% endif %}
            {%- if error %} aria-invalid="true"{% endif %}>
      {#
        Comma-joined, which is what Basecoat's JS writes the moment it runs.
        Anything else here would be a visible change at first paint.
      #}
      <span class="truncate">{{ chosen | join(", ") if chosen else placeholder }}</span>
      {{ icon("chevron-down", 16, "text-muted-foreground shrink-0 opacity-50") }}
    </button>
    <div id="{{ field_id }}-popover" data-popover aria-hidden="true">
      {#
        `aria-required` on the listbox, not the trigger: ARIA allows it on a
        listbox and not on a button. Not `required` on the hidden input
        either — the browser validates no hidden input, so it would block
        nothing and announce nothing. The route's model is still what
        refuses an empty submit; this states the rule and draws the marker.
      #}
      <div role="listbox" id="{{ field_id }}-listbox" aria-orientation="vertical"
           {%- if multiple %} aria-multiselectable="true"{% endif %}
           {%- if required %} aria-required="true"{% endif %}
           aria-labelledby="{{ field_id }}-trigger">
        {{- _options(options, values) }}
      </div>
    </div>
    {{ _hidden_value(name, field_id, multiple, values, selected, as_field) }}
  </div>
  {%- if as_field %}
  {{ _message(field_id, hint, error) }}
  </div>
  {%- endif %}
{%- endmacro %}

{#
  combobox(name, options, …) — a select you can type into.

  Same contract as `select_menu` — the hidden input carries the value — with a
  text input in place of the button. `empty` is the message the listbox shows
  when the filter matches nothing. It rides in a `data-empty` attribute because
  Basecoat's JS renders it, and a blank one leaves a filtered-to-nothing list
  looking broken.

  Filtering is client-side over the options rendered here, until `search` is
  given a URL. Then it is the server's: the input carries `hx-get`, the reply
  replaces the listbox, and the root carries `data-filter="manual"`, which is
  the switch in Basecoat's own JS that stops it filtering a second time. Both
  halves of that are load-bearing. Without the swap there is nothing new to
  show; without `manual`, Basecoat re-filters the server's rows against the
  same box and hides every one that matched on a field the label does not
  print — search by email, list by name, see nothing.

  The route is handed `?<search_param>=<what was typed>` and returns option
  rows and nothing else:

      <div role="option" data-value="7">Ada Lovelace</div>

  which is what `innerHTML` on the listbox expects. It is a fragment, so it
  extends no shell, and the empty result is an empty response — `data-empty`
  already draws the message.

  The visible input is deliberately not given a `name`, because a named input
  inside a `<form>` is submitted with it, and the box holds a label while the
  hidden input holds the value. So the typed text reaches the route through
  `hx-vals` instead of through the element's own value.

  `refresh()` is Basecoat's, put on the root when it initialises, and it is
  what re-reads the options after a swap. Nothing calls it for us: htmx fires
  `htmx:afterSwap` on the listbox, and it reaches the root by bubbling, which
  is why the attribute is on the root and not on the input that made the
  request.

  To act on a pick — with or without `search` — listen on the root:

      hx_trigger="change target:#c-jump"

  Basecoat dispatches its own `change` on the root, not on the hidden input,
  carrying `detail.value`. The markup does not say so, and the obvious guess
  (`change from:find input[type=hidden]`) silently never fires. `target:` is
  worth the characters because a native `change` bubbles out of the text box on
  blur as well, and without the filter a pick costs two identical requests.

  `multiple` works here too, and reads better than on `select_menu`: the text
  input sits in a `.combobox-chips` box and Basecoat renders one chip per pick
  into it, so a long selection stays legible instead of becoming a comma-joined
  line that truncates. The box is rendered here rather than left to the script,
  which would wrap the input in one anyway, so the first paint already has the
  shape the script leaves. `fjkit.css` lays that box out for a narrow column:
  the input takes the first line on its own, the chips wrap below it, and the
  list is anchored to the input rather than to the bottom of the box, so a pick
  that adds a chip row moves nothing under the pointer. The chips themselves
  are still the script's, so at first paint a pre-filled multiple combobox
  shows an empty box. Use `select_menu(multiple=true)` where the selection has
  to be visible with JavaScript off, and read the note on
  `multiselect_scripts()` either way.

  `visible_label`, `hint` and `error` behave as on `select_menu`: any one of
  them wraps the control in a `.field` and gives it the label and the message
  paragraph an ordinary field has. `required` is not one of them: it sets
  `aria-required` on the input and, beside a `visible_label`, draws the
  asterisk, exactly as on `select_menu`.
#}
{% macro combobox(name, options=(), selected=none, id=none, placeholder="Select…", empty="No results found.", label=none,
                  multiple=false, close_on_select=false, visible_label=none, hint=none, error=none,
                  search=none, search_param="q", search_delay=250, required=false) -%}
  {%- set field_id = id or ("c-" ~ name) -%}
  {# Same three parameters as `select_menu`, same rule — see its comment. #}
  {%- set as_field = visible_label is not none or hint is not none or error is not none -%}
  {#
    Same normalisation as `select_menu`, and the same reason: `equalto` against
    a list would never match, so the shape of `selected` follows `multiple`.
  #}
  {%- set values = (selected or []) | list if multiple else ([selected] if selected is not none else []) -%}
  {%- set chosen = options | selectattr("0", "in", values) | map(attribute=1) | list -%}
  {%- if as_field %}<div class="field">
    {%- if visible_label %}<label class="label" for="{{ field_id }}-input">{{ visible_label }}</label>{% endif %}
  {%- endif %}
  <div id="{{ field_id }}" class="combobox"
       {%- if multiple and close_on_select %} data-close-on-select="true"{% endif %}
       {%- if search %} data-filter="manual"
       hx-on::after-swap="this.refresh()"{% endif %}
       {%- if kwargs %}{{ attrs(kwargs) }}{% endif %}>
    {#
      Empty when `multiple`: this input is the filter box, not the display. The
      selection lives in the chips beside it, and pre-filling it with a label
      would filter the list down to that one option before anybody typed.
    #}
    {% if multiple %}<div class="combobox-chips">
    {% endif %}
    <input type="text" role="combobox" id="{{ field_id }}-input" placeholder="{{ placeholder }}"
           value="{{ "" if multiple else (chosen | join(", ")) }}"
           {#
             Off, all three: a combobox filters a list the page already holds,
             so the browser's own history dropdown would cover the listbox with
             a competing set of suggestions.
           #}
           autocomplete="off" autocorrect="off" spellcheck="false"
           {#
             `changed` so arrow keys and Tab do not re-ask for what is already
             on screen, and a delay so a typed word is one request rather than
             one per letter.
           #}
           {#
             `hx-push-url="false"` because htmx attributes inherit, and a
             caller who put `hx-push-url` on the root — to make picking an
             option a history entry, which is a reasonable thing to want —
             would otherwise have every keystroke's options request push
             `…/options?q=cac` as well. The back button would then walk the
             letters of a word instead of the searches.
           #}
           {%- if search %} hx-get="{{ search }}"
           hx-trigger="input changed delay:{{ search_delay }}ms"
           hx-target="#{{ field_id }}-listbox" hx-swap="innerHTML"
           hx-push-url="false"
           hx-vals='js:{ {{- search_param | tojson -}} : this.value}'{% endif %}
           aria-autocomplete="list" aria-expanded="false" aria-controls="{{ field_id }}-listbox"
           {#- On the input, which is the `combobox` role ARIA allows it on. #}
           {%- if required %} aria-required="true"{% endif %}
           {%- if label and not visible_label %} aria-label="{{ label }}"{% endif %}
           {%- if as_field %} aria-describedby="{{ field_id }}-hint"{% endif %}
           {%- if error %} aria-invalid="true"{% endif %}>
    {% if multiple %}</div>
    {% endif %}
    {{ icon("chevron-down", 16, "combobox-trigger-icon") }}
    <div id="{{ field_id }}-popover" data-popover aria-hidden="true">
      <div role="listbox" id="{{ field_id }}-listbox" aria-orientation="vertical" data-empty="{{ empty }}"
           {%- if multiple %} aria-multiselectable="true"{% endif %}>
        {{- _options(options, values) }}
      </div>
    </div>
    {{ _hidden_value(name, field_id, multiple, values, selected, as_field) }}
  </div>
  {%- if as_field %}
  {{ _message(field_id, hint, error) }}
  </div>
  {%- endif %}
{%- endmacro %}

{#
  multiselect_scripts() — what a page loads to be allowed `multiple=true`.

      {% block scripts %}{{ multiselect_scripts() }}{% endblock %}

  Per page, never from the shell, for the reason `form_scripts()` is: CHARTER
  §2.2 and §4.2 budget what a page downloads by default, and the answer has to stay
  "htmx and Basecoat".

  It buys one line of wire format. Basecoat serialises a multiple selection as
  `JSON.stringify(values)` in a single hidden input, so without this script the
  route is handed one string:

      labels=%5B%22bug%22%2C%22ui%22%5D        ->  labels: str  == '["bug","ui"]'

  With it, the selection is re-emitted the way HTML has always carried a
  repeated field, and the FastAPI signature is the ordinary one:

      labels=bug&labels=ui                     ->  labels: list[str] = Form([])

  It covers both halves of `form()`: htmx submits are rewritten in
  `htmx:configRequest`, browser submits in a capture-phase `submit` handler,
  and one form is only ever handled by one of the two.

  `encoding="json"` composes, in one direction: this runs first and json-enc
  collects the repeats into an array. One caveat — json-enc collects repeats,
  so a one-item selection arrives as `"bug"`, not `["bug"]`. Give the model a
  `mode="before"` validator that wraps a bare string in a list; `TaskUpdate` in
  `examples/fjkit-demo` is the worked example.

  A page that forgets this macro fails the way every missing-script failure in
  this kit does: no console error, no visual difference, and a 422 naming a
  field that looks correctly filled in.
#}
{% macro multiselect_scripts() -%}
  <script defer src="{{ fjkit_static("js/multiselect.js") }}"></script>
{%- endmacro %}

{#
  drawer(id, …) — a panel that slides in from an edge.

  A native `<dialog>` opened with `showModal()`, not a popover: a drawer is
  modal, and `showModal()` gives it the top layer, the backdrop, the focus trap
  and Esc-to-close without a line of script. `dialog` in this kit is the
  non-modal one, which is why the two do not share a macro.

  Opening one needs `showModal()`, so the trigger carries the only inline
  handler in the kit besides the theme toggle. `drawer_trigger` writes it.
#}
{% macro drawer(id, title=none, description=none, side="bottom", footer=none, dismissible=true) -%}
  <dialog id="{{ id }}" class="drawer" data-side="{{ side }}"
    {%- if title %} aria-labelledby="{{ id }}-title"{% endif %}
    {%- if description %} aria-describedby="{{ id }}-description"{% endif %}
    {%- if kwargs %}{{ attrs(kwargs) }}{% endif %}>
    {#
      Basecoat styles `.drawer > article`, so the wrapper is load-bearing the
      same way the dialog's inner div is: the <dialog> itself is the backdrop
      owner and the positioning context, the <article> is the panel that
      slides.
    #}
    <article>
      {%- if title or description %}
      <header>
        {% if title %}<h2 id="{{ id }}-title">{{ title }}</h2>{% endif %}
        {% if description %}<p id="{{ id }}-description">{{ description }}</p>{% endif %}
      </header>
      {%- endif %}
      <section>{{ caller() }}</section>
      {%- if footer or dismissible %}
      <footer>
        {%- if footer %}{{ footer }}{% endif %}
        {%- if dismissible %}
          {#
            `closest('dialog').close()` rather than the id: the button is
            inside the dialog it closes, so the relationship is structural and
            cannot be broken by a rename.
          #}
          <button type="button" class="btn" data-variant="outline"
                  onclick="this.closest('dialog').close()">Close</button>
        {%- endif %}
      </footer>
      {%- endif %}
    </article>
  </dialog>
{%- endmacro %}

{#
  drawer_trigger(label, target) — the button that opens one.

  Separate from `drawer` because the two live in different places on the page:
  the drawer is usually at the end of the document, the button wherever it
  belongs. Passing the id twice is the price of that — `drawer` takes it as
  `id`, this macro as `target`.

  `onclick` reads the id back from `aria-controls`, for the reason
  `sidebar_trigger` gives: an id written into the script would run as code.
#}
{% macro drawer_trigger(label, target, variant="outline", size="", icon_name=none) -%}
  <button type="button" class="btn" data-variant="{{ variant }}"
          {%- if size %} data-size="{{ size }}"{% endif %}
          aria-haspopup="dialog" aria-controls="{{ target }}"
          onclick="document.getElementById(this.getAttribute('aria-controls')).showModal()"
          {%- if kwargs %}{{ attrs(kwargs) }}{% endif %}>
    {%- if icon_name %}{{ icon(icon_name, 16) }}{% endif %}
    {{- label -}}
  </button>
{%- endmacro %}

{#
  command(id, …) — a filterable command list, and its ⌘K dialog form.

  `dialog=true` swaps the root for a `<dialog class="command-dialog">`,
  upstream's own variant rather than a second component. Everything else — the
  header input, the `role="menu"`, the ids that tie them together — is
  identical, so this is one macro with a flag rather than two that would drift.

  Two things it deliberately does not do:

  * It does not bind ⌘K. A keystroke is application policy — which key, on
    which pages, and whether it beats the browser's own — and a UI kit that
    claims a global shortcut fights the app. Open it with `showModal()` from
    your own listener.
  * It does not search the server. The filter is Basecoat's, over the items
    rendered here. For server-side search this is the wrong component: use an
    `input` with `hx-get` and swap the listbox from the response.
#}
{% macro command(id, placeholder="Type a command or search…", empty="No results found.", label="Command menu", dialog=false, bordered=true) -%}
  <{{ "dialog" if dialog else "div" }} id="{{ id }}"
    class="{{ "command-dialog" if dialog else ("command border" if bordered else "command") }}"
    aria-label="{{ label }}"{% if kwargs %}{{ attrs(kwargs) }}{% endif %}>
    <header>
      {{ icon("search", 16) }}
      {#
        `aria-expanded="true"` is not a mistake: the list below is always
        showing whenever this is on screen, so the combobox is permanently
        expanded. It is the dialog that opens and closes, not the listbox.
      #}
      <input type="text" id="{{ id }}-input" placeholder="{{ placeholder }}"
             autocomplete="off" autocorrect="off" spellcheck="false"
             role="combobox" aria-autocomplete="list" aria-expanded="true"
             aria-controls="{{ id }}-menu">
    </header>
    <div role="menu" id="{{ id }}-menu" aria-orientation="vertical" data-empty="{{ empty }}">
      {{- caller() -}}
    </div>
  </{{ "dialog" if dialog else "div" }}>
{%- endmacro %}

{#
  command_item(label, …) — one row of a command list.

  `data-filter` is what Basecoat matches the typed text against, and it
  defaults to the label. `keywords` extends that with words that are not on
  screen — "date event schedule" for a Calendar row — which is the difference
  between a palette that finds things and one that only confirms what you
  already typed.
#}
{% macro command_item(label, keywords=none, icon_name=none, shortcut=none, disabled=false, filter=none, href=none) -%}
  <{{ "a" if href else "div" }} role="menuitem"
    data-filter="{{ filter if filter is not none else label }}"
    {%- if keywords %} data-keywords="{{ keywords }}"{% endif %}
    {%- if href %} href="{{ href }}"{% endif %}
    {%- if disabled %} aria-disabled="true"{% endif %}
    {%- if kwargs %}{{ attrs(kwargs) }}{% endif %}>
    {%- if icon_name %}{{ icon(icon_name, 16) }}{% endif %}
    <span>{{ label }}</span>
    {%- if shortcut %}<kbd>{{ shortcut }}</kbd>{% endif -%}
  </{{ "a" if href else "div" }}>
{%- endmacro %}

{#
  command_group(heading) — a labelled run of command items.

  A `<span role="heading">`, not the `<div>` `menu_group` uses: that is what
  upstream's command markup does, and its CSS selects on it. Otherwise the
  same shape, naming included.
#}
{% macro command_group(heading=none, id=none) -%}
  <div role="group"
    {%- if heading and id %} aria-labelledby="{{ id }}"{% elif heading %} aria-label="{{ heading }}"{% endif %}>
    {%- if heading %}<span role="heading"{% if id %} id="{{ id }}"{% endif %}>{{ heading }}</span>{% endif %}
    {{- caller() -}}
  </div>
{%- endmacro %}