Skip to main content
cngx-src documentation

CngxDgaSortHeader

Directivev0.1.0WCAG AA

projects/ui/data-grid-accordion/data-grid-sort-header.directive.ts

Import#

import { CngxDgaSortHeader } from '@cngx/ui/data-grid-accordion'

Description#

Makes a CngxDataGridHeader cell sort the grid it lives in with a single attribute - cngxDgaSortHeader="field" - and no [cngxSortRef] plumbing. It reads the group's hosted CngxSort off CNGX_DATA_GRID_ACCORDION (the seam), so the header cell needs no reference to the sort instance; the group provides it.

The cell becomes an operable control: role="button", tabindex="0", and click / Enter / Space all toggle the column's sort through CngxSort.setSort. When the owning group has [multiSort], Shift-activating adds this column to the sort stack instead of replacing it (mirrors CngxSortHeader). The field/direction logic is not re-implemented: both headers compose the shared createSortHeaderState factory from @cngx/common/data, so the derivation lives in one place. CngxSortHeader cannot be reused as a sibling here (its cngxSortRef is input.required and only template-bindable), so this header composes the same factory and feeds it the sort it reads off the context token.

The component is a disclosure accordion, not a table, so it carries no role="grid" / role="table" and thus no valid context for aria-sort / role="columnheader". The sort state is instead communicated to assistive tech through a visually-hidden description (always in the DOM, content reactive - Pillar 2) referenced by aria-describedby: the accessible name stays the stable column label, the description carries the live sort state. A tinted direction arrow is a CSS ::after cue (pseudo content, so it never doubles the announcement or shifts a ch-based track). On activation the new sort state is also spoken once through the shared CngxLiveAnnouncer polite region - a change announcement worded distinctly from the on-focus description, for SR/browser pairs that do not re-read a mutated aria-describedby on an already-focused control.

<cngx-data-grid-accordion [multiSort]="true">
  <cngx-dga-header>
    <span cngxDgaCell col="sm" cngxDgaSortHeader="id">ID</span>
    <span cngxDgaCell col="grow" cngxDgaSortHeader="name">Name</span>
    <span cngxDgaCell col="md" align="end" cngxDgaSortHeader="amount">Amount</span>
  </cngx-dga-header>
  <!-- rows rendered by the consumer's @for over its own sorted array -->
</cngx-data-grid-accordion>

https://cngxjs.github.io/cngx/examples/#/ui/data-grid-accordion/sortable-ledger https://cngxjs.github.io/cngx/examples/#/ui/data-grid-accordion/bound-sort-filter

Metadata#

Host#

Index#

Inputs#

ascendingAnnouncement#
input()

Live announcement fired when this column becomes sorted ascending. {label} is replaced.

default 'Sorted by {label} ascending', { alias: 'cngxDgaSortAnnounceAscending', }
ascendingLabel#
input()

SR status while sorted ascending. English default; override for other locales.

default SORTED_ASCENDING, { alias: 'cngxDgaSortStatusAscending' }
clearedAnnouncement#
input()

Live announcement fired when this column's sort is cleared. {label} is replaced.

default 'Sorting by {label} cleared', { alias: 'cngxDgaSortAnnounceCleared', }
descendingAnnouncement#
input()

Live announcement fired when this column becomes sorted descending. {label} is replaced.

default 'Sorted by {label} descending', { alias: 'cngxDgaSortAnnounceDescending', }
descendingLabel#
input()

SR status while sorted descending. English default; override for other locales.

default SORTED_DESCENDING, { alias: 'cngxDgaSortStatusDescending' }
field#string
input()Required

The field key this header cell sorts by.

default { alias: 'cngxDgaSortHeader' }
label#string | undefined
input()

Human column name spoken in the live sort announcement ({label} placeholder of the announcement templates). Defaults to the field key.

default undefined, { alias: 'cngxDgaSortLabel' }
notSortedLabel#
input()

SR status while unsorted. English default; override for other locales.

default NOT_SORTED, { alias: 'cngxDgaSortStatusNotSorted' }

Instance Properties#

isActive#unknown
Readonly

true when this column is part of the active sort (primary or secondary).

this.state.isActive
isAsc#unknown
Readonly

true when this column is active and sorted ascending.

this.state.isAsc
isDesc#unknown
Readonly

true when this column is active and sorted descending.

this.state.isDesc
priority#unknown
Readonly

1-based position of this column in the sort stack, or 0 when it is not active. Only meaningful when the owning group has [multiSort] (for sort-order badges).

this.state.priority
statusId#unknown
ProtectedReadonly

Stable id of the visually-hidden status element the host aria-describedby names.

nextUid('cngx-dga-sort-status-')

Methods#

handleActivateKey#void
Protected
handleActivateKey(event: Event)
@parameventEvent
handleSort#void
Protected
handleSort(event?: Event)
@paramevent?Event

HostBindings#

BindingExpression
[attr.aria-describedby]statusId
[class.cngx-dga-sort-header--active]isActive()
[class.cngx-dga-sort-header--asc]isAsc()
[class.cngx-dga-sort-header--desc]isDesc()

HostListeners#

EventHandler
(click)click()
(keydown.enter)keydown.enter()
(keydown.space)keydown.space()