@adres/mgda-ui 0.0.0-stage → 0.0.1

package/knowledge/chat-container.md

@@ -0,0 +1,135 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: chat-container
+  sourceFile: packages/design-system/src/components/chat-container.tsx
+  client: true
+  category: web-app-ai
+  categoryFromBarrel: web-app-ai
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: ChatContainerContent
+      kind: component
+      typeText: "ForwardRefExoticComponent<ChatContainerContentProps & RefAttributes<HTMLDivElement>>"
+    - name: ChatContainerContentProps
+      kind: type
+    - name: ChatContainerRoot
+      kind: component
+      typeText: "ForwardRefExoticComponent<ChatContainerRootProps & RefAttributes<HTMLDivElement>>"
+    - name: ChatContainerRootProps
+      kind: type
+    - name: ChatContainerState
+      kind: type
+    - name: ChatScrollButton
+      kind: component
+      typeText: "ForwardRefExoticComponent<ChatScrollButtonProps & RefAttributes<HTMLButtonElement>>"
+    - name: ChatScrollButtonProps
+      kind: type
+    - name: useChatContainer
+      kind: hook
+      typeText: "() => ChatContainerState"
+  primaryExport: ChatContainerContent
+  subcomponents:
+    - ChatContainerRoot
+    - ChatScrollButton
+  props:
+    ChatScrollButton:
+      - name: asChild
+        type: boolean
+        required: false
+        declaredIn: button
+        doc: "When true, renders the child element instead of a button (e.g. for `<Link>`)."
+      - name: aurora
+        type: boolean
+        required: false
+        declaredIn: button
+        doc: "Decorative \"aurora\" - two soft, blurred orbs (primary + accent) drifting behind the label for a modern, glowing look. Designed for the `primary` variant. Ignored with `asChild` (it needs to inject its own children)."
+  extendsProps:
+    - "React.HTMLAttributes<HTMLDivElement>"
+  variants: {}
+  variantSource: none
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots:
+    - chat-container
+    - chat-container-content
+    - chat-scroll-button
+  dependsOn:
+    internal:
+      - button
+    lib:
+      - cn
+    hooks: []
+    external:
+      - lucide-react
+      - react
+  contexts:
+    - name: ChatContainerContext
+      type: ChatContainerContextValue
+      default: null
+  stories:
+    - exportName: Default
+      id: components-chatcontainer--default
+  storybookTitle: Components/ChatContainer
+  docsId: components-chatcontainer--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "07ffc38de2ee"
+  factsHash: eae438b00211
+# >>> AUTHORED - humans own everything below this line. <<<
+status: beta
+summary: "A conversation log that sticks to the latest message: it follows new and streaming content while the reader is at the bottom, stays put once they scroll up, and offers a button back down."
+useWhen:
+  - "a chat or assistant conversation grows at the bottom and should follow new messages"
+  - "replies stream in and the reader may scroll up to reread earlier turns"
+related:
+  - chat-message
+  - prompt-input
+a11y:
+  notes:
+    - "ChatContainerContent is a focusable role=\"log\" named \"Conversation\" by default, so keyboard users can scroll it and new turns are announced politely."
+    - "ChatScrollButton is aria-hidden and out of the tab order while the reader is at the bottom."
+    - "The icon-only scroll button is labelled \"Scroll to latest\"; with unseen content it reads \"New messages\"."
+  radixHandles: false
+pitfalls:
+  - "Give ChatContainerRoot a bounded height (a fixed height or flex-1 inside a sized column); without one the log never scrolls."
+  - "Call scrollToBottom from useChatContainer when the reader sends a message, so their own turn is always in view."
+  - "Only scrolling up stops following; content changes alone never do."
+  - "ChatScrollButton is not positioned; place it, usually absolute at the bottom centre of the root."
+canonicalSnippet: |
+  import {
+    ChatContainerRoot, ChatContainerContent, ChatScrollButton, ChatMessage,
+  } from "@adres/mgda-ui"
+
+  <ChatContainerRoot className="ax:h-120">
+    <ChatContainerContent className="ax:gap-lg ax:p-md">
+      <ChatMessage from="user">{question}</ChatMessage>
+      <ChatMessage from="assistant">{answer}</ChatMessage>
+    </ChatContainerContent>
+    <ChatScrollButton className="ax:absolute ax:bottom-sm ax:left-1/2 ax:-translate-x-1/2" />
+  </ChatContainerRoot>
+reviewedAt: 2026-10-06
+reviewedAgainstContractHash: "07ffc38de2ee"
+---
+
+## Usage
+
+`ChatContainerRoot` holds the scroll state and positions its children.
+`ChatContainerContent` is the scrolling log that holds the turns; it starts at
+the bottom and follows new and streaming content while the reader is there.
+Once they scroll up it stays put, and `ChatScrollButton` appears: a round
+arrow, which reads "New messages" when content arrived while they were away.
+Clicking it scrolls smoothly back down and resumes following.
+
+`useChatContainer` returns `isAtBottom`, `hasUnseen` and `scrollToBottom` for
+custom controls inside the root. Call `scrollToBottom` when the reader sends a
+message so their turn is always in view.
+
+## Anatomy
+
+- `ChatContainerRoot` - relative column that owns the scroll state.
+- `ChatContainerContent` - the scrolling `role="log"` that holds the turns.
+- `ChatScrollButton` - jump-to-latest button, shown only while scrolled up.
+- `useChatContainer` - scroll state and `scrollToBottom` for custom parts.

package/knowledge/chat-message.md

@@ -0,0 +1,224 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: chat-message
+  sourceFile: packages/design-system/src/components/chat-message.tsx
+  client: true
+  category: web-app-ai
+  categoryFromBarrel: web-app-ai
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: ChatAvatar
+      kind: component
+      typeText: "ForwardRefExoticComponent<ChatAvatarProps & RefAttributes<HTMLSpanElement>>"
+    - name: ChatAvatarProps
+      kind: type
+    - name: ChatDivider
+      kind: component
+      typeText: "ForwardRefExoticComponent<ChatDividerProps & RefAttributes<HTMLDivElement>>"
+    - name: ChatDividerProps
+      kind: type
+    - name: ChatMessage
+      kind: component
+      typeText: "ForwardRefExoticComponent<ChatMessageProps & RefAttributes<HTMLElement>>"
+    - name: ChatMessageFrom
+      kind: type
+    - name: ChatMessageProps
+      kind: type
+    - name: ChatMessageStatus
+      kind: type
+  primaryExport: ChatMessage
+  subcomponents:
+    - ChatAvatar
+    - ChatDivider
+  props:
+    ChatAvatar:
+      - name: children
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Replaces the default bot icon, e.g. with an `AvatarImage`."
+      - name: size
+        type: "\"2xl\" | \"lg\" | \"md\" | \"sm\" | \"xl\" | \"xs\""
+        required: false
+        declaredIn: avatar
+    ChatDivider:
+      - name: label
+        type: string
+        required: true
+        declaredIn: self
+        doc: "Short system note, e.g. \"Today\" or \"Conversation restarted\"."
+    ChatMessage:
+      - name: actions
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Assistant only. Usually `MessageActions`; sits after `meta` in the footer row."
+      - name: attachments
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Content under the bubble, such as listing cards or a sources line."
+      - name: avatar
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Assistant only. None by default; pass `<ChatAvatar />` to show one beside the turn."
+      - name: bare
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Drops the bubble so `children` lay out freely, e.g. steps, tool runs or a cited answer."
+      - name: bodyClassName
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Extra classes for the column that holds the bubble and footer."
+      - name: from
+        type: ChatMessageFrom
+        required: true
+        declaredIn: self
+        doc: "Who wrote it. Named `from` so it never clashes with the ARIA `role` attribute."
+      - name: meta
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Small muted footer text, e.g. the time or \"Delivered · 10:42\"."
+      - name: onRetry
+        type: "(() => void)"
+        required: false
+        declaredIn: self
+      - name: status
+        type: ChatMessageStatus
+        required: false
+        declaredIn: self
+        doc: "User only. `failed` tints the bubble and swaps `meta` for a retry line."
+  extendsProps:
+    - "React.HTMLAttributes<HTMLElement>"
+  variants:
+    from:
+      kind: enum
+      options:
+        - assistant
+        - user
+      default: null
+      on: ChatMessage
+    status:
+      kind: enum
+      options:
+        - sent
+        - failed
+      default: sent
+      on: ChatMessage
+    size:
+      kind: enum
+      options:
+        - sm
+        - md
+        - xs
+        - lg
+        - xl
+        - "2xl"
+      default: sm
+      on: ChatAvatar
+  variantSource: prop-union
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots:
+    - chat-divider
+    - chat-message
+  dependsOn:
+    internal:
+      - avatar
+      - separator
+      - text
+      - text-link
+    lib:
+      - cn
+    hooks: []
+    external:
+      - lucide-react
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-chatmessage--default
+    - exportName: Conversation
+      id: components-chatmessage--conversation
+    - exportName: FailedUserMessage
+      id: components-chatmessage--failed-user-message
+    - exportName: WithAvatar
+      id: components-chatmessage--with-avatar
+    - exportName: CustomContent
+      id: components-chatmessage--custom-content
+  storybookTitle: Components/ChatMessage
+  docsId: components-chatmessage--documentation
+  argTypeOptions:
+    from:
+      - assistant
+      - user
+    status:
+      - sent
+      - failed
+  resolvedCleanly: true
+  contractHash: b63239d6c9a2
+  factsHash: "309973a564c7"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: beta
+summary: "One turn in a chat with an assistant: a primary-tinted bubble with actions for the assistant, a muted end-aligned bubble with delivery and retry for the user."
+useWhen:
+  - "rendering the messages of an assistant or chat conversation"
+  - "an assistant turn holds custom content such as steps, tool runs or a cited answer"
+  - "a system note or date break sits between turns (ChatDivider)"
+useInstead:
+  - id: card
+    when: "the content is not a turn in a conversation"
+related:
+  - message-actions
+  - avatar
+a11y:
+  notes:
+    - "Each turn is an article named \"Assistant message\" or \"Your message\"; wrap the list in role=\"log\" so new turns are announced."
+    - "A failed user turn renders Retry as a real button."
+    - "ChatDivider is role=\"separator\" with its label as the accessible name."
+    - "An avatar is decorative when shown; the article label already names the speaker."
+  radixHandles: false
+pitfalls:
+  - "Use from, not role: role is the ARIA attribute and overrides the article's semantics."
+  - "String children get the message text style; pass your own Text when children are elements."
+  - "Assistant turns have no avatar by default; pass avatar={<ChatAvatar />} to show one."
+  - "meta is hidden on a failed user turn; the retry line takes its place."
+canonicalSnippet: |
+  import { ChatMessage, MessageActions } from "@adres/mgda-ui"
+
+  <ChatMessage from="user" meta="Delivered · 10:41">{question}</ChatMessage>
+  <ChatMessage
+    from="assistant"
+    actions={<MessageActions copyText={answer} />}
+    meta="10:42"
+  >
+    {answer}
+  </ChatMessage>
+reviewedAt: 2026-10-07
+reviewedAgainstContractHash: "b63239d6c9a2"
+---
+
+## Usage
+
+`ChatMessage` renders one turn. Set `from` to `assistant` or `user`. Assistant
+turns sit in a `bg-primary-weaker` bubble at the start of the column, with
+`attachments` underneath and a footer row of `meta` (the time, aligned to the bubble edge) then `actions`; pass `avatar={<ChatAvatar />}` to show
+an avatar beside them. User turns align to the end in a muted 24px rounded
+bubble with a `meta` line such as "Delivered · 10:41"; `status="failed"`
+tints the bubble red and swaps `meta` for "Not delivered" with a Retry button
+calling `onRetry`. `bare` drops the bubble on either side; `bodyClassName` changes the
+assistant column gap. Each turn is a `group/message`, so
+`MessageActions revealOnHover` can show actions on hover.
+
+## Anatomy
+
+- `ChatMessage` - the turn: avatar, bubble or bare content, attachments, footer.
+- `ChatAvatar` - the assistant's mark; a small tinted avatar with a bot icon, opt-in via `avatar`.
+- `ChatDivider` - a labelled rule between turns for system notes and date breaks.

package/knowledge/checkbox-card.md

@@ -0,0 +1,172 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: checkbox-card
+  sourceFile: packages/design-system/src/components/checkbox-card.tsx
+  client: true
+  category: web-app-form-controls
+  categoryFromBarrel: web-app-form-controls
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: CheckboxCard
+      kind: component
+      typeText: "ForwardRefExoticComponent<CheckboxCardProps & RefAttributes<HTMLButtonElement>>"
+    - name: CheckboxCardDescription
+      kind: component
+      typeText: "ForwardRefExoticComponent<HTMLAttributes<HTMLParagraphElement> & RefAttributes<HTMLParagraphElement>>"
+    - name: CheckboxCardGroup
+      kind: component
+      typeText: "ForwardRefExoticComponent<CheckboxCardGroupProps & RefAttributes<HTMLDivElement>>"
+    - name: CheckboxCardGroupProps
+      kind: type
+    - name: CheckboxCardOrientation
+      kind: type
+    - name: CheckboxCardProps
+      kind: type
+    - name: CheckboxCardSize
+      kind: type
+    - name: CheckboxCardTitle
+      kind: component
+      typeText: "ForwardRefExoticComponent<HTMLAttributes<HTMLParagraphElement> & RefAttributes<HTMLParagraphElement>>"
+  primaryExport: CheckboxCard
+  subcomponents:
+    - CheckboxCardDescription
+    - CheckboxCardGroup
+    - CheckboxCardTitle
+  props:
+    CheckboxCard:
+      - name: children
+        type: ReactNode
+        required: false
+        declaredIn: self
+      - name: className
+        type: string
+        required: false
+        declaredIn: self
+      - name: size
+        type: "\"base\" | \"lg\" | \"sm\""
+        required: false
+        declaredIn: self
+        variantKey: true
+    CheckboxCardGroup:
+      - name: compact
+        type: boolean
+        required: false
+        declaredIn: self
+      - name: orientation
+        type: CheckboxCardOrientation
+        required: false
+        declaredIn: self
+      - name: size
+        type: CheckboxCardSize
+        required: false
+        declaredIn: self
+        variantKey: true
+  extendsProps:
+    - "VariantProps<typeof checkboxCardVariants>"
+    - "Pick< React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>, \"checked\" | \"defaultChecked\" | \"onCheckedChange\" | \"disabled\" | \"name\" | \"value\" | \"required\" >"
+  variants:
+    size:
+      kind: enum
+      options:
+        - sm
+        - base
+        - lg
+      default: base
+      on: CheckboxCard
+  variantSource: cva
+  compoundVariants: []
+  sizeMaps:
+    - CHECK_SIZE
+    - COMPACT_LAYOUT
+  dataSlots:
+    - checkbox-card-check
+    - checkbox-card-title
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - "@radix-ui/react-checkbox"
+      - class-variance-authority
+      - lucide-react
+      - react
+  contexts:
+    - name: CheckboxCardGroupContext
+      type: CheckboxCardGroupContextValue
+      default: null
+  stories:
+    - exportName: Default
+      id: components-checkboxcard--default
+  storybookTitle: Components/CheckboxCard
+  docsId: components-checkboxcard--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "82df47acbb1e"
+  factsHash: "8defa7684e0f"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A large clickable card acting as a checkbox - a bordered surface with a title/description and a trailing check indicator, for multi-select option grids."
+useWhen:
+  - "presenting several independently-selectable options as prominent cards rather than plain checkboxes - plan add-ons, feature toggles, settings with a title and description each"
+useInstead:
+  - id: checkbox
+    when: "a compact list of options fits a plain checkbox and label better than a full card"
+  - id: radio-card
+    when: "only one option among several can be selected"
+related:
+  - checkbox
+  - radio-card
+a11y:
+  notes:
+    - "The actual Radix checkbox input is visually hidden (sr-only) inside a real label, so clicking anywhere on the card toggles it, and the accessible name comes from CheckboxCardTitle/CheckboxCardDescription's text content rather than a separate aria-label."
+    - "CheckboxCardGroup sets role=\"group\" for a labeled cluster of related checkboxes - pair it with a visible heading and aria-labelledby when the group's purpose is not obvious from surrounding context."
+  keyboard:
+    - "Native Radix checkbox keyboard behavior on the hidden input - Space toggles the focused card; Tab moves between cards."
+  radixHandles: true
+pitfalls:
+  - "Each CheckboxCard manages its own checked state independently - CheckboxCardGroup only supplies shared size/layout context (size, compact, orientation), not any select-all or shared value logic."
+  - "compact is what collapses the cards into a connected strip (shared borders, only the first/last corners rounded) - size alone does not change this shape."
+  - "CheckboxCardTitle and CheckboxCardDescription rely on their data-slot attributes for the checked-state color styling defined on the parent card - swapping either for a plain paragraph silently drops the selected-state title tint."
+canonicalSnippet: |
+  import { CheckboxCard, CheckboxCardDescription, CheckboxCardGroup, CheckboxCardTitle } from "@adres/mgda-ui"
+
+  <CheckboxCardGroup className="ax:max-w-md">
+    <CheckboxCard defaultChecked>
+      <CheckboxCardTitle>Email alerts</CheckboxCardTitle>
+      <CheckboxCardDescription>Receive updates about your account.</CheckboxCardDescription>
+    </CheckboxCard>
+    <CheckboxCard>
+      <CheckboxCardTitle>SMS alerts</CheckboxCardTitle>
+      <CheckboxCardDescription>Get text messages for urgent events.</CheckboxCardDescription>
+    </CheckboxCard>
+  </CheckboxCardGroup>
+reviewedAt: 2026-08-31
+reviewedAgainstContractHash: "82df47acbb1e"
+---
+
+## Usage
+
+`CheckboxCard` turns a checkbox into a full clickable card - reach for it when
+options deserve more visual weight than a plain `Checkbox` and label row (plan
+add-ons, feature toggles, settings with a title and description each). For a
+single-select version of the same pattern, use `RadioCard` instead.
+
+`CheckboxCardGroup` only supplies shared `size`/`compact`/`orientation` layout
+context - each `CheckboxCard` inside still manages its own checked state
+independently; there is no built-in select-all or shared value.
+
+Set `compact` to collapse the cards into a connected strip with shared
+borders (only the first and last corners rounded) instead of a spaced grid.
+
+## Anatomy
+
+| Part | Role |
+| --- | --- |
+| `CheckboxCardGroup` | Layout wrapper. Owns `size`, `compact`, `orientation`, shared via context. Sets `role="group"`. |
+| `CheckboxCard` | One card. Wraps a visually-hidden Radix checkbox in a real `<label>`, so the whole card is the click target. |
+| `CheckboxCardTitle` | The card's heading. Its `data-slot` drives the checked-state color tint defined on the parent card. |
+| `CheckboxCardDescription` | Supporting text below the title. |

package/knowledge/checkbox.md

@@ -0,0 +1,111 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: checkbox
+  sourceFile: packages/design-system/src/components/checkbox.tsx
+  client: true
+  category: web-app-form-controls
+  categoryFromBarrel: web-app-form-controls
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Checkbox
+      kind: component
+      typeText: "ForwardRefExoticComponent<CheckboxProps & RefAttributes<HTMLButtonElement>>"
+    - name: CheckboxProps
+      kind: type
+  primaryExport: Checkbox
+  subcomponents: []
+  props:
+    Checkbox:
+      - name: size
+        type: "\"base\" | \"lg\" | \"sm\""
+        required: false
+        declaredIn: self
+        variantKey: true
+  extendsProps:
+    - "React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>"
+    - "VariantProps<typeof checkboxVariants>"
+  variants:
+    size:
+      kind: enum
+      options:
+        - sm
+        - base
+        - lg
+      default: base
+      on: Checkbox
+  variantSource: cva
+  compoundVariants: []
+  sizeMaps:
+    - ICON_SIZE
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - "@radix-ui/react-checkbox"
+      - class-variance-authority
+      - lucide-react
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-checkbox--default
+    - exportName: Checked
+      id: components-checkbox--checked
+  storybookTitle: Components/Checkbox
+  docsId: components-checkbox--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "38d59aafd860"
+  factsHash: e579584aec93
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A tri-state (checked, unchecked, indeterminate) checkbox, built on Radix Checkbox."
+useWhen:
+  - "a form-bound boolean or tri-state selection, especially in a list, form, or table row - e.g. a select-all-with-indeterminate pattern"
+useInstead:
+  - id: toggle
+    when: "the control is an immediate on/off setting that takes effect right away, not a form-bound selection to submit"
+  - id: radio-group
+    when: "only one option among several can be selected"
+related:
+  - toggle
+  - radio-group
+a11y:
+  notes:
+    - "checked accepts \"indeterminate\" as well as a boolean - use it for a parent select-all checkbox whose children are partially selected; Radix renders the Minus glyph automatically when checked=\"indeterminate\"."
+    - "Checkbox has no built-in label - pair it with a real label (wrapping both, or htmlFor pointing at the checkbox) so the control has an accessible name and a larger clickable hit target."
+  keyboard:
+    - "Native Radix button semantics - Space toggles the checkbox; it takes part in tab order automatically."
+  radixHandles: true
+pitfalls:
+  - "indeterminate is not a stored value, only a checked state you pass in - usually derived from whether some-but-not-all children are selected. Clicking an indeterminate checkbox always resolves it to checked, never back to indeterminate, on its own."
+  - "size options are sm/base/lg - base, not md, is the name of the default middle size, unlike most other sized components in this system (Button, Input) which use sm/md/lg."
+canonicalSnippet: |
+  import { Checkbox } from "@adres/mgda-ui"
+
+  <label className="ax:flex ax:items-center ax:gap-sm">
+    <Checkbox checked={checked} onCheckedChange={setChecked} />
+    <span>Accept terms</span>
+  </label>
+reviewedAt: 2026-08-31
+reviewedAgainstContractHash: "38d59aafd860"
+---
+
+## Usage
+
+`Checkbox` is for a form-bound boolean or tri-state selection - reach for it
+in lists, forms, or table rows, including select-all patterns where
+`checked="indeterminate"` represents a partially-selected group. Reach for
+`Toggle` instead when the control is an immediate setting rather than
+something submitted with a form.
+
+`Checkbox` renders no label of its own - always pair it with real label text,
+either by wrapping both in a `<label>` (as in the example above) or pointing
+a separate `<label htmlFor>` at it, so the control has an accessible name and
+a larger clickable target than the box itself.