{#
  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. Four ids have to line
  up for that: trigger, popover, menu, and the group headings. 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"` referenced by the group's
  `aria-labelledby`, so it is announced as the group's name rather than read
  as a menu item nobody can activate.
#}
{% macro menu_group(heading=none, id=none) -%}
  {%- set heading_id = id or ("h-" ~ (heading | replace(" ", "-") | lower) if heading else none) -%}
  <div role="group"{% if heading %} aria-labelledby="{{ heading_id }}"{% endif %}>
    {%- if heading %}<div role="heading" id="{{ heading_id }}">{{ 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.
#}
{#
  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") }}
#}
{% 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) -%}
  {%- 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">
      <div role="listbox" id="{{ field_id }}-listbox" aria-orientation="vertical"
           {%- if multiple %} aria-multiselectable="true"{% endif %}
           aria-labelledby="{{ field_id }}-trigger">
        {%- for value, option_label in options %}
          <div role="option" data-value="{{ value }}"
               {%- if value in values %} aria-selected="true"{% endif %}>{{ option_label }}</div>
        {%- endfor %}
      </div>
    </div>
    {#
      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 select posts nothing — and the round trip that
      re-renders this 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 trigger, 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 here, inside the `.select` box.
    #}
    {%- if multiple %}
    <input type="hidden" name="{{ name }}" data-fjkit-multi value='{{ values | tojson }}'
           {%- if as_field %} aria-describedby="{{ field_id }}-hint"{% endif %}>
    {%- else %}
    <input type="hidden" name="{{ name }}" value="{{ selected if selected is not none else "" }}"
           {%- if as_field %} aria-describedby="{{ field_id }}-hint"{% endif %}>
    {%- endif %}
  </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`: Basecoat
  wraps the text input in a `.combobox-chips` div and renders one chip per
  pick, so a long selection stays legible instead of becoming a comma-joined
  line that truncates. That JS draws the chips, 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.
#}
{% 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) -%}
  {%- 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.
    #}
    <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 }}": this.value}'{% endif %}
           aria-autocomplete="list" aria-expanded="false" aria-controls="{{ field_id }}-listbox"
           {%- 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 %}>
    {{ 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 %}>
        {%- for value, option_label in options %}
          <div role="option" data-value="{{ value }}"
               {%- if value in values %} aria-selected="true"{% endif %}>{{ option_label }}</div>
        {%- endfor %}
      </div>
    </div>
    {# The hidden input carries the 422, same as in `select_menu`. #}
    {%- if multiple %}
    <input type="hidden" name="{{ name }}" data-fjkit-multi value='{{ values | tojson }}'
           {%- if as_field %} aria-describedby="{{ field_id }}-hint"{% endif %}>
    {%- else %}
    <input type="hidden" name="{{ name }}" value="{{ selected if selected is not none else "" }}"
           {%- if as_field %} aria-describedby="{{ field_id }}-hint"{% endif %}>
    {%- endif %}
  </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
  §7 budgets 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`.
#}
{% 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('{{ target }}').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.
#}
{% macro command_group(heading=none, id=none) -%}
  {%- set heading_id = id or ("ch-" ~ (heading | replace(" ", "-") | lower) if heading else none) -%}
  <div role="group"{% if heading %} aria-labelledby="{{ heading_id }}"{% endif %}>
    {%- if heading %}<span role="heading" id="{{ heading_id }}">{{ heading }}</span>{% endif %}
    {{- caller() -}}
  </div>
{%- endmacro %}