Files
bible/rules/patterns/controls-selection/contract.md
T
Mikhail ChusavitinandClaude Opus 5.5 714447aa06 Add modal backdrop-close, scroll-lock and dropdown placement rules
modal-workflows 1.3: a backdrop close needs the press and the release on the
backdrop; the page behind an open modal does not scroll.
controls-selection 1.4: dropdowns open upward when there is no room below and
never leave the viewport.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-02 17:01:12 +03:00

3.9 KiB

Contract: Controls + Selection

Version: 1.4

Shared Base

  • This pattern inherits the shared table-management contract.
  • Visual styling comes from web-visual-baseline.
  • Reuse shared toolbar/table/icon geometry from the base contract first, then define only controls-specific additions below.

Buttons

  • Use a small stable button taxonomy: primary, secondary, ghost, danger, disabled.
  • Destructive actions (archive, delete, remove) must use danger styling and explicit labels.
  • Button text should describe the action outcome, not implementation detail.
  • Inside a data-table row action column, buttons are icon-only. Each one must have a deterministic title and aria-label; text labels belong in toolbars, forms and confirmation dialogs, not repeated in every row.
  • Buttons are text-first; icons are optional and must not replace labels on primary/danger actions.
  • Base examples must show both disabled and loading states.
  • Any control that triggers a network or database call must show a visible busy state for the whole duration of that call (spinner on the control, disabled control, or an equivalent indicator), and must not be re-triggerable while busy. Without it, "slow" is indistinguishable from "broken".
  • This applies to every call, not only to long-running background tasks. The server-side half of the rule — a bounded timeout on the call itself — is owned by go-api.
  • Do not use a hyperlink (<a>/link-styled text) to open a modal, drawer, detail view, or any other in-page element. Use a button (or button-styled control) instead, unless the user explicitly asks for a hyperlink. Hyperlinks are reserved for navigation to another URL/page.

Dropdowns and Popups

Applies to every floating panel anchored to a control: autocomplete/combobox lists, custom selects, multiselect filters, menus, date pickers.

  • A panel opens below its control by default. When it does not fit below and there is more room above, it opens upward. Decide on every open and on scroll/resize while open, from the control's actual position in the viewport; never hardcode a direction.
  • A panel must never extend past the viewport edge. If it fits neither way, cap its height to the room available on the chosen side and let it scroll.
  • A panel must not be clipped by an ancestor's overflow (modal body, table wrapper). Position it against the viewport (position: fixed or a body-level layer), not inside the clipping container.
  • Implement placement once in the shared dropdown code; do not re-derive it per control.

Checkbox Selection

  • Row checkboxes support bulk actions from a shared action bar.
  • Header checkbox semantics must be explicit:
    • select visible rows only, or
    • select all rows in query scope (must be clearly labeled)
  • In paginated views, the UI should distinguish selection on the current page from selection across the filtered/query scope.
  • Selection state should survive pagination/filter navigation via explicit state (query params, server session, or another deterministic mechanism).
  • Same-page interactions should preserve reading position (module anchor pattern is preferred in canonical server-rendered flows).

Segmented Filters

  • Segment/toggle filters are allowed for small enumerations (status, active/archived).
  • Segmented controls are grouped joined-buttons:
    • one shared outer shell,
    • rounded corners only on the first/last segment,
    • straight internal separators between middle segments.
  • Active segment color may vary by context (for example blue preset selector vs dark status scope tabs), but geometry must remain consistent.
  • Segment changes should preserve other active filters where possible.

Bulk Action Safety

  • Bulk action click should preview count and target scope before execution.
  • Destructive bulk actions require confirmation.
  • Dense bulk action bars may move rare actions into an explicit overflow menu (More actions) while keeping primary actions visible.