@layer components {
  /* Hints — the explanation a control needs and the screen has no room for.
   *
   * A hint and a tooltip look alike and are not the same thing, and the
   * difference is the whole reason this exists. A tooltip repeats what a
   * control is already called, so losing it costs nothing; a hint carries
   * something that appears nowhere else on the page, so it cannot be reachable
   * by hover alone — a touch screen has no hover to give, and the information
   * would simply be missing there. This one is pressed.
   *
   * Which makes it a .popover, and it composes with one rather than restating
   * it: the wrapper carries both classes, so the anchoring, the flipping, the
   * fade, Escape, an outside click and focus leaving are all the ones already
   * in the app. This file adds a small ⓘ to press and a surface measured for
   * prose instead of for a list.
   *
   * Pointing at it on a mouse opens it too — that is hint_controller, and it is
   * a shortcut rather than the way in. Everything works with it switched off.
   *
   * Past a paragraph or two, stop reaching for this. A long explanation with
   * headings or a table wants a .dialog, which is the same controller again
   * with modal: true; give its trigger .hint__trigger and it still reads as
   * the same ⓘ. COMPONENTS.md has that call.
   */
  .hint {
    /* Aligned to the text it explains rather than to the middle of the line, so
       an ⓘ after a label sits on the same optical row as the label. */
    vertical-align: middle;
  }

  /* Measured in em against whatever it stands beside, like every other control
     in the app, so an ⓘ after a field label and one after a table heading are
     each the size of their own line without either call site naming a size. */
  .hint__trigger {
    --hint-trigger-size: 1.5em;

    display: inline-flex;
    align-items: center;
    justify-content: center;
    inline-size: var(--hint-trigger-size);
    block-size: var(--hint-trigger-size);
    padding: 0;
    border: 0;
    border-radius: var(--radius-circle);
    background: none;
    color: var(--color-ink-soft);
    cursor: pointer;
    transition: color var(--transition-fast), background var(--transition-fast);

    @media (any-hover: hover) {
      &:hover {
        background: var(--color-highlight);
        color: var(--color-accent);
      }
    }

    /* Open is a state worth showing: with the surface anchored below, the ⓘ is
       the only part of the control still in the operator's eyeline. */
    &[aria-expanded="true"] {
      background: var(--color-highlight);
      color: var(--color-accent);
    }
  }

  /* Sized for prose, which max-content is not: a paragraph left to size itself
     comes out one line the width of the window.
   *
   * Scoped through .hint to outrank .popover__surface, which is one class in
   * the same layer — a tie source order would settle, and source order here is
   * the alphabet, where hint.css loses to popover.css. Written flat, every
   * declaration below did nothing. combobox.css carries the same note for the
   * same reason. */
  .hint .hint__surface {
    --hint-surface-width: 20rem;

    inline-size: var(--hint-surface-width);
    max-inline-size: min(var(--hint-surface-width), calc(100dvw - var(--space-double)));
    padding: var(--space-three-quarters) var(--space);
  }

  .hint--wide .hint__surface {
    --hint-surface-width: 27rem;
  }

  .hint__text {
    margin: 0;
    color: var(--color-ink);
    font-size: var(--text-small);
    line-height: var(--leading-loose);
    text-wrap: pretty;

    /* Two paragraphs is the ceiling this is comfortable at; past that the
       answer is a dialog. The gap is here so a caller writing the second one
       doesn't reach for a margin of its own. */
    + .hint__text {
      margin-block-start: var(--space-half);
    }
  }
}