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

package/docs/column-manager.json

@@ -0,0 +1,486 @@
+{
+  "family": "column-manager",
+  "ui": "column-manager",
+  "binding": "angular",
+  "catalog": {
+    "group": "Data display",
+    "summary": "Shows, hides, orders and pins table columns."
+  },
+  "axes": {
+    "presentation": [
+      "popover",
+      "drawer",
+      "inline"
+    ],
+    "apply": [
+      "live",
+      "confirm"
+    ]
+  },
+  "members": {
+    "columnManager": {
+      "nativeElement": "div",
+      "defaults": {
+        "presentation": "popover",
+        "apply": "live",
+        "open": false
+      },
+      "capabilities": [
+        "columns",
+        "open",
+        "live",
+        "content",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "disabled",
+        "dragging",
+        "drop-target",
+        "open"
+      ],
+      "parts": [
+        "root",
+        "header",
+        "title",
+        "summary",
+        "search",
+        "list",
+        "section",
+        "section-label",
+        "item",
+        "handle",
+        "visibility",
+        "description",
+        "status",
+        "pin",
+        "drop-indicator",
+        "empty",
+        "footer",
+        "show-all",
+        "reset",
+        "cancel",
+        "apply",
+        "trigger",
+        "count"
+      ]
+    }
+  },
+  "docs": {
+    "columnManager": {
+      "imports": {
+        "source": "import { SlColumnManager, SlColumnManagerTrigger, provideColumnManagerDefaults } from '@slotted/angular/column-manager';",
+        "selector": "sl-column-manager, [slColumnManagerTrigger]",
+        "exportAs": "slColumnManager"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "div",
+          "required": true,
+          "purpose": "role=\"group\" named by the title, carrying data-ui=\"column-manager\", data-presentation and data-apply. The popover’s one child, the drawer’s content, or in place under presentation=\"inline\"."
+        },
+        {
+          "part": "header",
+          "element": "div",
+          "required": true,
+          "purpose": "The title and the summary on one line."
+        },
+        {
+          "part": "title",
+          "element": "h2",
+          "required": true,
+          "purpose": "messages.title; names the root."
+        },
+        {
+          "part": "summary",
+          "element": "span",
+          "required": true,
+          "purpose": "messages.visibleCount — “7 of 9 shown”, in tabular figures."
+        },
+        {
+          "part": "search",
+          "element": "div around an slTextField",
+          "required": true,
+          "purpose": "type=\"search\" at size sm, named by messages.search; filters by label and description."
+        },
+        {
+          "part": "list",
+          "element": "div",
+          "required": true,
+          "purpose": "The scroller of the sections, bounded by --slotted-column-manager-list-max-block-size except in a drawer."
+        },
+        {
+          "part": "section",
+          "element": "div",
+          "required": false,
+          "purpose": "One per pin zone that holds a column: start, middle, end. role=\"group\" named by its label, and the drag container of its zone. data-drop-target while a drag hovers it."
+        },
+        {
+          "part": "section-label",
+          "element": "div",
+          "required": false,
+          "purpose": "Pinned to start, Columns, Pinned to end. Read and not shown when the section is the only one."
+        },
+        {
+          "part": "item",
+          "element": "div",
+          "required": false,
+          "purpose": "One column: data-column, data-hidden, data-locked, data-space-hidden, data-pinned, data-dragging. Every column is listed, hidden or not."
+        },
+        {
+          "part": "handle",
+          "element": "button",
+          "required": false,
+          "purpose": "The grip: a pointer drag starts on it, and Alt+ArrowUp/Down moves the column one place in its zone. aria-disabled and data-disabled while a search is typed or for reorderable: false."
+        },
+        {
+          "part": "visibility",
+          "element": "div around an slCheckbox",
+          "required": false,
+          "purpose": "Ticked while the column is shown. Disabled for hideable: false and for the last shown column."
+        },
+        {
+          "part": "description",
+          "element": "p[slCheckboxDescription], the checkbox’s own description",
+          "required": false,
+          "purpose": "GridColumn.description under the label, and the box’s aria-describedby."
+        },
+        {
+          "part": "status",
+          "element": "span inside the label",
+          "required": false,
+          "purpose": "Required for a locked column, Hidden for space for one the grid hid for room, Shown in row for one the grid moved into its rows’ pop-in; heard with the name."
+        },
+        {
+          "part": "pin",
+          "element": "button[slMenuTriggerFor]",
+          "required": false,
+          "purpose": "Opens Pin to start, Pin to end and Unpin. Named messages.pin; data-pinned and the accent ink while the column is pinned."
+        },
+        {
+          "part": "drop-indicator",
+          "element": "div",
+          "required": false,
+          "purpose": "A line of no height where a pointer drop would land. Present only while a drag hovers."
+        },
+        {
+          "part": "empty",
+          "element": "div",
+          "required": false,
+          "purpose": "role=\"status\" with messages.noResults in place of the sections when the search finds nothing."
+        },
+        {
+          "part": "footer",
+          "element": "div",
+          "required": true,
+          "purpose": "The actions. Below 20rem of its own width they stand two by two."
+        },
+        {
+          "part": "show-all",
+          "element": "button[slButton]",
+          "required": true,
+          "purpose": "Asks for every column shown. Disabled while none is hidden."
+        },
+        {
+          "part": "reset",
+          "element": "button[slButton]",
+          "required": true,
+          "purpose": "Asks for defaultColumnState with the reason clear. Disabled while the state already equals it."
+        },
+        {
+          "part": "cancel",
+          "element": "button[slButton]",
+          "required": false,
+          "purpose": "Under apply=\"confirm\": discards the draft and closes the layer."
+        },
+        {
+          "part": "apply",
+          "element": "button[slButton]",
+          "required": false,
+          "purpose": "Under apply=\"confirm\": asks once for the draft with the reason submit and closes the layer. Disabled while nothing changed."
+        },
+        {
+          "part": "trigger",
+          "element": "the consumer’s button carrying [slColumnManagerTrigger]",
+          "required": false,
+          "purpose": "aria-haspopup=\"dialog\", aria-expanded, aria-controls the root while open, data-open and data-column-manager-trigger."
+        },
+        {
+          "part": "count",
+          "element": "span",
+          "required": false,
+          "purpose": "On the trigger after its words: the number of hidden columns, aria-hidden, beside a visually hidden “3 hidden columns” that names the trigger. Absent at zero."
+        }
+      ],
+      "api": [
+        {
+          "name": "columns",
+          "type": "readonly GridColumn[]",
+          "defaultValue": "—",
+          "appliesTo": "sl-column-manager",
+          "description": "The grid’s columns: id, label, description, hideable, reorderable. Every column is listed"
+        },
+        {
+          "name": "columnState",
+          "type": "model<GridColumnState | undefined>",
+          "defaultValue": "—",
+          "appliesTo": "sl-column-manager",
+          "description": "Two-way. Unbound, the manager holds the state itself from defaultColumnState"
+        },
+        {
+          "name": "defaultColumnState",
+          "type": "Partial<GridColumnState>",
+          "defaultValue": "—",
+          "appliesTo": "sl-column-manager",
+          "description": "The start while columnState is unbound, and the target of Restore defaults in both modes"
+        },
+        {
+          "name": "outOfSpace",
+          "type": "GridOutOfSpace",
+          "defaultValue": "{ popin: [], hidden: [] }",
+          "appliesTo": "sl-column-manager",
+          "description": "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"
+        },
+        {
+          "name": "presentation",
+          "type": "'popover' | 'drawer' | 'inline'",
+          "defaultValue": "popover",
+          "appliesTo": "sl-column-manager, provideColumnManagerDefaults",
+          "description": "A popover on the trigger, a drawer at the end, or the panel in place"
+        },
+        {
+          "name": "apply",
+          "type": "'live' | 'confirm'",
+          "defaultValue": "live",
+          "appliesTo": "sl-column-manager, provideColumnManagerDefaults",
+          "description": "live asks for every action; confirm edits a draft that Apply asks for once"
+        },
+        {
+          "name": "open",
+          "type": "model<boolean>",
+          "defaultValue": "false",
+          "appliesTo": "sl-column-manager",
+          "description": "Two-way: whether the layer is open"
+        },
+        {
+          "name": "messages",
+          "type": "Partial<ColumnManagerMessages>",
+          "defaultValue": "—",
+          "appliesTo": "sl-column-manager",
+          "description": "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"
+        },
+        {
+          "name": "show(), hide(), toggleOpen()",
+          "type": "methods",
+          "defaultValue": "—",
+          "appliesTo": "slColumnManager",
+          "description": "Open and close with the reason programmatic, for a grid’s (manageColumns) or any other caller"
+        },
+        {
+          "name": "slColumnManagerTriggerFor",
+          "type": "SlColumnManager",
+          "defaultValue": "—",
+          "appliesTo": "[slColumnManagerTrigger]",
+          "description": "The manager the button opens. The directive writes aria-haspopup, aria-expanded, aria-controls, data-open, data-part=\"trigger\", and appends the count"
+        },
+        {
+          "name": "provideColumnManagerDefaults",
+          "type": "{ presentation, apply }",
+          "defaultValue": "—",
+          "appliesTo": "providers",
+          "description": "The decisions an application takes once. A manager that states either itself still wins; the words come from the language in force (provideSlotted)"
+        }
+      ],
+      "composition": [],
+      "events": [
+        {
+          "name": "columnStateChangeRequest",
+          "payload": "ChangeRequest<GridColumnState> & { change, changes }",
+          "when": "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."
+        },
+        {
+          "name": "columnStateChange",
+          "payload": "GridColumnState",
+          "when": "The model half of [(columnState)], after a request nobody cancelled."
+        },
+        {
+          "name": "openChangeRequest",
+          "payload": "ChangeRequest<boolean>",
+          "when": "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)."
+        },
+        {
+          "name": "openChange",
+          "payload": "boolean",
+          "when": "The model half of [(open)], after a request nobody cancelled."
+        }
+      ],
+      "accessibility": [
+        "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": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "An orders listing’s nine columns behind a trigger. Hide one and watch the count on the trigger; switch presentation and apply in the controls below.",
+      "language": "html",
+      "source": "<button slButton slColumnManagerTrigger [slColumnManagerTriggerFor]=\"manager\" type=\"button\">\n  Columns\n</button>\n<sl-column-manager #manager=\"slColumnManager\" [columns]=\"columns\" [(columnState)]=\"state\" />\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "popover",
+      "title": "In a popover on the trigger",
+      "note": "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.",
+      "language": "html",
+      "source": "<sl-column-manager #manager=\"slColumnManager\" presentation=\"popover\" [columns]=\"columns\" />\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "drawer",
+      "title": "In a drawer at the end",
+      "note": "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.",
+      "language": "html",
+      "source": "<sl-column-manager #manager=\"slColumnManager\" presentation=\"drawer\" [columns]=\"columns\" />\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "confirm",
+      "title": "Apply once",
+      "note": "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.",
+      "language": "html",
+      "source": "<sl-column-manager\n  apply=\"confirm\"\n  [columns]=\"columns\"\n  [(columnState)]=\"state\"\n  (columnStateChangeRequest)=\"log($event.reason, $event.changes)\"\n/>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "search",
+      "title": "Search by name and description",
+      "note": "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.",
+      "language": "ts",
+      "source": "const columns: GridColumn<Order>[] = [\n  {\n    id: 'status',\n    label: 'Status',\n    description: 'Fulfilment stage, updated when the ship date is set',\n  },\n  { id: 'due', label: 'Due date', description: 'The date promised to the customer' },\n];\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "locked",
+      "title": "Required, and the last shown column",
+      "note": "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.",
+      "language": "ts",
+      "source": "const columns = [{ id: 'number', label: 'Order', hideable: false }, ...rest];\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "hidden-by-space",
+      "title": "Hidden for space, shown in row",
+      "note": "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.",
+      "language": "html",
+      "source": "<sl-data-grid #grid=\"slDataGrid\" rowKey=\"id\" [columns]=\"columns\" [rows]=\"orders\" />\n<sl-column-manager [columns]=\"columns\" [outOfSpace]=\"grid.outOfSpace()\" />\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "reorder",
+      "title": "Reorder by pointer and by keyboard",
+      "note": "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.",
+      "language": "html",
+      "source": "<sl-column-manager\n  [columns]=\"columns\"\n  [(columnState)]=\"state\"\n  (columnStateChangeRequest)=\"$event.change === 'order' && saveOrder($event.value.order)\"\n/>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "pinning",
+      "title": "Pinning",
+      "note": "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.",
+      "language": "html",
+      "source": "<sl-column-manager\n  [columns]=\"columns\"\n  [defaultColumnState]=\"{ pinned: { start: ['number'], end: ['actions'] } }\"\n/>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "reset-and-show-all",
+      "title": "Show all and Restore defaults",
+      "note": "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.",
+      "language": "html",
+      "source": "<sl-column-manager\n  [columns]=\"columns\"\n  [defaultColumnState]=\"defaults\"\n  [(columnState)]=\"state\"\n  (columnStateChangeRequest)=\"$event.reason === 'clear' && announceRestored()\"\n/>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "trigger-count",
+      "title": "The count on the trigger",
+      "note": "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.",
+      "language": "html",
+      "source": "<button\n  slButton\n  size=\"sm\"\n  variant=\"ghost\"\n  slColumnManagerTrigger\n  [slColumnManagerTriggerFor]=\"manager\"\n  type=\"button\"\n>\n  Columns\n</button>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "with-data-grid",
+      "title": "With the data grid",
+      "note": "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.",
+      "language": "html",
+      "source": "<button slButton slColumnManagerTrigger [slColumnManagerTriggerFor]=\"manager\" type=\"button\">\n  Columns\n</button>\n<sl-data-grid\n  #grid=\"slDataGrid\"\n  manageable\n  rowKey=\"id\"\n  [columns]=\"columns\"\n  [rows]=\"orders\"\n  [(columnState)]=\"state\"\n  (manageColumns)=\"manager.show()\"\n/>\n<sl-column-manager\n  #manager=\"slColumnManager\"\n  [columns]=\"columns\"\n  [outOfSpace]=\"grid.outOfSpace()\"\n  [(columnState)]=\"state\"\n/>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "Keyboard",
+      "note": "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.",
+      "language": "html",
+      "source": "<sl-column-manager presentation=\"inline\" [columns]=\"columns\" />\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "accessibility",
+      "title": "Names, descriptions and announcements",
+      "note": "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.",
+      "language": "ts",
+      "source": "providers: [provideSlotted({ locale: 'pt-BR', catalogs: { 'pt-BR': PT_BR } })];\n",
+      "verdict": "excerpt"
+    }
+  ]
+}