@slotted/angular 0.0.0-stage → 0.1.0-beta.1

package/docs/column-manager.md

@@ -0,0 +1,277 @@
+<!-- index: ./index.md -->
+# column-manager
+
+`data-ui="column-manager"` · Shows, hides, orders and pins table columns.
+
+## Import
+
+```ts
+import { SlColumnManager, SlColumnManagerTrigger, provideColumnManagerDefaults } from '@slotted/angular/column-manager';
+```
+
+Selector: `sl-column-manager, [slColumnManagerTrigger]` · exportAs: `slColumnManager`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<button slButton slColumnManagerTrigger [slColumnManagerTriggerFor]="manager" type="button">
+  Columns
+</button>
+<sl-column-manager #manager="slColumnManager" [columns]="columns" [(columnState)]="state" />
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div | yes |
+| `header` | div | yes |
+| `title` | h2 | yes |
+| `summary` | span | yes |
+| `search` | div around an slTextField | yes |
+| `list` | div | yes |
+| `section` | div | no |
+| `section-label` | div | no |
+| `item` | div | no |
+| `handle` | button | no |
+| `visibility` | div around an slCheckbox | no |
+| `description` | p[slCheckboxDescription], the checkbox’s own description | no |
+| `status` | span inside the label | no |
+| `pin` | button[slMenuTriggerFor] | no |
+| `drop-indicator` | div | no |
+| `empty` | div | no |
+| `footer` | div | yes |
+| `show-all` | button[slButton] | yes |
+| `reset` | button[slButton] | yes |
+| `cancel` | button[slButton] | no |
+| `apply` | button[slButton] | no |
+| `trigger` | the consumer’s button carrying [slColumnManagerTrigger] | no |
+| `count` | span | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `columns` | `readonly GridColumn[]` | — | sl-column-manager | The grid’s columns: id, label, description, hideable, reorderable. Every column is listed |
+| `columnState` | `model<GridColumnState \| undefined>` | — | sl-column-manager | Two-way. Unbound, the manager holds the state itself from defaultColumnState |
+| `defaultColumnState` | `Partial<GridColumnState>` | — | sl-column-manager | The start while columnState is unbound, and the target of Restore defaults in both modes |
+| `outOfSpace` | `GridOutOfSpace` | { popin: [], hidden: [] } | sl-column-manager | The columns the grid took out for room — grid.outOfSpace() — listed with Shown in row for popin and Hidden for space for hidden, never written to the state |
+| `presentation` | `'popover' \| 'drawer' \| 'inline'` | popover | sl-column-manager, provideColumnManagerDefaults | A popover on the trigger, a drawer at the end, or the panel in place |
+| `apply` | `'live' \| 'confirm'` | live | sl-column-manager, provideColumnManagerDefaults | live asks for every action; confirm edits a draft that Apply asks for once |
+| `open` | `model<boolean>` | false | sl-column-manager | Two-way: whether the layer is open |
+| `messages` | `Partial<ColumnManagerMessages>` | — | sl-column-manager | Words laid over the language in force, key by key: title, search, noResults, showAll, reset, apply, cancel, pinnedStart, unpinned, pinnedEnd, pin, pinStart, pinEnd, unpin, reorder, moved, required, hiddenBySpace, inRow, hiddenCount, visibleCount |
+| `show(), hide(), toggleOpen()` | `methods` | — | slColumnManager | Open and close with the reason programmatic, for a grid’s (manageColumns) or any other caller |
+| `slColumnManagerTriggerFor` | `SlColumnManager` | — | [slColumnManagerTrigger] | The manager the button opens. The directive writes aria-haspopup, aria-expanded, aria-controls, data-open, data-part="trigger", and appends the count |
+| `provideColumnManagerDefaults` | `{ presentation, apply }` | — | providers | The decisions an application takes once. A manager that states either itself still wins; the words come from the language in force (provideSlotted) |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `columnStateChangeRequest` | `ChangeRequest<GridColumnState> & { change, changes }` | Before the state moves: a box (pointer, keyboard), a move (pointer, keyboard), a pin, Show all, Restore defaults (clear), or Apply under confirm (submit). change is changes[0]; changes lists every key that differs. cancel() refuses it. |
+| `columnStateChange` | `GridColumnState` | The model half of [(columnState)], after a request nobody cancelled. |
+| `openChangeRequest` | `ChangeRequest<boolean>` | Before the layer opens or closes: the trigger (pointer, keyboard), Escape, a press outside, the back gesture in a drawer, Apply and Cancel, or show() and hide() (programmatic). |
+| `openChange` | `boolean` | The model half of [(open)], after a request nobody cancelled. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `presentation` | `popover`, `drawer`, `inline` | `popover` |
+| `apply` | `live`, `confirm` | `live` |
+
+## Rules
+
+- No WAI-ARIA pattern names a column chooser, so the rows are native controls in document order: an slCheckbox, a grip button and a pin button that opens an sl-menu. Tab gives three stops a row and the search shortens the list first; the inspected AG Grid and MUI X panels make the same choice, and a layout grid would give one stop at the price of a cursor model of its own.
+- The root is a group named by its heading and each zone a group named by its label, so a reader hears Pinned to start before the columns in it. A checkbox is named by the column and its status — “Order Required”, “Região Hidden for space” — and described by the column’s description through slCheckboxDescription.
+- Alt+ArrowUp/Down on a grip is the rearrangeable listbox’s move: the column moves one place within its zone, focus stays on the grip, and the live announcer says “Customer moved to position 3”. A pointer drag runs through @slotted/core/drag, whose Escape cancels the drag before the layer sees it.
+- The trigger says aria-haspopup="dialog", aria-expanded and aria-controls; its count is aria-hidden and a visually hidden sentence carries it, so the name is “Columns 3 hidden columns” and the number is never read as a bare digit.
+
+## Tokens
+
+`--slotted-border-subtle`, `--slotted-border-width-thick`, `--slotted-border-width-thin`, `--slotted-column-manager-inline-size`, `--slotted-column-manager-list-max-block-size`, `--slotted-control-font-size-md`, `--slotted-control-gap-md`, `--slotted-control-gap-sm`, `--slotted-control-icon-size-sm`, `--slotted-control-inner-size-md`, `--slotted-control-padding-inline-md`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-foreground`, `--slotted-focus-ring-color`, `--slotted-focus-ring-width`, `--slotted-font-family-heading`, `--slotted-font-family-sans`, `--slotted-font-size-md`, `--slotted-font-size-sm`, `--slotted-font-size-xs`, `--slotted-font-weight-medium`, `--slotted-font-weight-semibold`, `--slotted-line-height-md`, `--slotted-line-height-sm`, `--slotted-line-height-xs`, `--slotted-radius-full`, `--slotted-radius-sm`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-8`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-solid`, `--slotted-tone-accent-surface`, `--slotted-tone-accent-text`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-tone-warning-text`
+
+## Examples
+
+### In a popover on the trigger
+
+The default presentation: a popover anchored on the trigger, 22rem wide, the search focused on open. Escape and a press outside close it and focus returns to the trigger.
+
+Excerpt — not a complete module
+
+```html
+<sl-column-manager #manager="slColumnManager" presentation="popover" [columns]="columns" />
+```
+
+### In a drawer at the end
+
+The same panel as the drawer family at side end, size sm, for a grid with many columns: the list takes the drawer’s height and is not capped.
+
+Excerpt — not a complete module
+
+```html
+<sl-column-manager #manager="slColumnManager" presentation="drawer" [columns]="columns" />
+```
+
+### Apply once
+
+Under apply="confirm" every action edits a draft: hide two columns and move one, and the log stays empty until Apply asks once with the reason submit and every key that moved. Cancel discards the draft.
+
+Excerpt — not a complete module
+
+```html
+<sl-column-manager
+  apply="confirm"
+  [columns]="columns"
+  [(columnState)]="state"
+  (columnStateChangeRequest)="log($event.reason, $event.changes)"
+/>
+```
+
+### Search by name and description
+
+Type “date”: Due date matches by its name and Status by its description. “regiao” finds Região — case and accents fall away. While a query stands every grip is disabled, because a place in a subset is not a place in the list.
+
+Excerpt — not a complete module
+
+```ts
+const columns: GridColumn<Order>[] = [
+  {
+    id: 'status',
+    label: 'Status',
+    description: 'Fulfilment stage, updated when the ship date is set',
+  },
+  { id: 'due', label: 'Due date', description: 'The date promised to the customer' },
+];
+```
+
+### Required, and the last shown column
+
+Order is hideable: false — ticked, disabled and marked Required. With every other column hidden, the last shown one is disabled too: the manager never asks for a grid with no column.
+
+Excerpt — not a complete module
+
+```ts
+const columns = [{ id: 'number', label: 'Order', hideable: false }, ...rest];
+```
+
+### Hidden for space, shown in row
+
+The grid moved Owner into its rows’ pop-in and hid Região for room. Their boxes keep the reader’s value and their status says where they are; the sets never enter the state.
+
+Excerpt — not a complete module
+
+```html
+<sl-data-grid #grid="slDataGrid" rowKey="id" [columns]="columns" [rows]="orders" />
+<sl-column-manager [columns]="columns" [outOfSpace]="grid.outOfSpace()" />
+```
+
+### Reorder by pointer and by keyboard
+
+Drag a grip: the row dims and a line marks where it lands, inside its zone only. Or focus a grip and press Alt+ArrowDown: the column moves one place, “Customer moved to position 3” is announced, and focus stays on the grip.
+
+Excerpt — not a complete module
+
+```html
+<sl-column-manager
+  [columns]="columns"
+  [(columnState)]="state"
+  (columnStateChangeRequest)="$event.change === 'order' && saveOrder($event.value.order)"
+/>
+```
+
+### Pinning
+
+Order is pinned to the start and Actions to the end, each in its section. Open a row’s pin to move it between zones; a pinned column’s pin is in the accent ink, and a move never crosses a zone.
+
+Excerpt — not a complete module
+
+```html
+<sl-column-manager
+  [columns]="columns"
+  [defaultColumnState]="{ pinned: { start: ['number'], end: ['actions'] } }"
+/>
+```
+
+### Show all and Restore defaults
+
+Four columns hidden against a default of one. Show all asks for none hidden; Restore defaults asks for defaultColumnState with the reason clear. Each is disabled while it would change nothing.
+
+Excerpt — not a complete module
+
+```html
+<sl-column-manager
+  [columns]="columns"
+  [defaultColumnState]="defaults"
+  [(columnState)]="state"
+  (columnStateChangeRequest)="$event.reason === 'clear' && announceRestored()"
+/>
+```
+
+### The count on the trigger
+
+No count at zero, a chip at one and at twelve. The chip is aria-hidden and a visually hidden sentence names the trigger — “Columns 12 hidden columns” — so the number is heard once, as words.
+
+Excerpt — not a complete module
+
+```html
+<button
+  slButton
+  size="sm"
+  variant="ghost"
+  slColumnManagerTrigger
+  [slColumnManagerTriggerFor]="manager"
+  type="button"
+>
+  Columns
+</button>
+```
+
+### With the data grid
+
+The grid and the manager share one column state. Manage columns… in any column menu opens the manager the toolbar trigger opens; narrow the room and the grid’s outOfSpace reaches the list as Shown in row and Hidden for space.
+
+Excerpt — not a complete module
+
+```html
+<button slButton slColumnManagerTrigger [slColumnManagerTriggerFor]="manager" type="button">
+  Columns
+</button>
+<sl-data-grid
+  #grid="slDataGrid"
+  manageable
+  rowKey="id"
+  [columns]="columns"
+  [rows]="orders"
+  [(columnState)]="state"
+  (manageColumns)="manager.show()"
+/>
+<sl-column-manager
+  #manager="slColumnManager"
+  [columns]="columns"
+  [outOfSpace]="grid.outOfSpace()"
+  [(columnState)]="state"
+/>
+```
+
+### Keyboard
+
+Tab walks the search, then each row’s checkbox, grip and pin, then the footer. Space toggles a box; Alt+ArrowUp/Down on a grip moves the column; Enter on a pin opens its menu; Escape during a drag cancels it.
+
+Excerpt — not a complete module
+
+```html
+<sl-column-manager presentation="inline" [columns]="columns" />
+```
+
+### Names, descriptions and announcements
+
+The panel is a group named Columns and each zone a group named by its label. A box is named by the column and its status and described by its description; a keyboard move is announced politely with the new position.
+
+Excerpt — not a complete module
+
+```ts
+providers: [provideSlotted({ locale: 'pt-BR', catalogs: { 'pt-BR': PT_BR } })];
+```