[API]: Style sortable table headers through aria-sort #147

Proposal

Add an opt-in presentation for sortable table headers built from native table headings, aria-sort, and a native link or button. The component should provide:

• a compact header control that fills the heading's interactive area;
• ascending and descending indicators;
• a visible focus state;
• a non-colour indication of the active sort;
• correct logical placement in RTL.

Cirth should not perform the sort or change aria-sort. A server response, htmx, Datastar, or application code owns that state.

Use Case

Sorting is a basic operation in record tables. Cirth currently styles table headings and buttons independently, but has no contract for a button inside <th> or for the standard aria-sort state. Consumers therefore need custom CSS for every sortable table even when the server performs all behavior.

Markup Or CSS Example

<th scope="col" aria-sort="ascending">
  <button type="submit">Created</button>
</th>

The enclosing form and request mechanism are application concerns.

Fit With Cirth

The proposal styles standard HTML and an accessibility state already authored by the application. It follows Cirth's existing treatment of aria-current, aria-selected, aria-invalid, and aria-busy without shipping behavior.

Compatibility

Prefer an explicit table modifier or another opt-in trigger so an ordinary button in a heading is not silently redefined. Existing tables must remain byte-for-byte or visually unchanged outside that opt-in.

Alternatives

• Leave every sort control as a full primary button.
• Require local CSS for the button and indicator.
• Turn the table into an ARIA grid. Rejected because sorting does not require grid semantics or cell-by-cell keyboard navigation.

Acceptance

• Cover ascending, descending, and unsorted sortable columns.
• Verify keyboard focus, forced colors, RTL, long headings, narrow scroll regions, and all maintained presets.
• Keep sort behavior and state changes outside Cirth.
• Write the required public-behavior spec before implementation.