@mk-kit/ui 0.41.0 → 0.42.0

package/types/mk-kit-ui-dnd.d.ts

@@ -11,29 +11,64 @@ import { TemplateRef } from '@angular/core';
  * Its look (grab cursor, muted colour, `touch-action: none`) ships as the
  * global `.mk-drag-handle` class in the theme stylesheet.
  *
+ * **Decorative grip** — a non-focusable element (`<span>`, `<mk-icon>`): the
+ * item itself stays the keyboard target (`role="button"`, focusable), so the
+ * grip should be `aria-hidden`:
+ *
  * ```html
  * <div mkDrag [mkDragData]="row">
  *   <span mkDragHandle aria-hidden="true">⠿</span>
  *   {{ row.name }}
  * </div>
  * ```
+ *
+ * **Focusable grip** — a `<button>` (or any element with `tabindex`): the
+ * handle becomes the keyboard target instead. The item is then a plain
+ * container (no role, not focusable), so rows may hold inputs, links and
+ * other buttons without nesting interactive controls, and `<li>` items keep
+ * valid list semantics. Give it an accessible name:
+ *
+ * ```html
+ * <li mkDrag [mkDragData]="row">
+ *   <button type="button" mkDragHandle [attr.aria-label]="'Reorder ' + row.name">⠿</button>
+ *   <input mkInput [(ngModel)]="row.name" />
+ * </li>
+ * ```
  */
 declare class MkDragHandle {
     /** The handle's host element. */
     readonly element: HTMLElement;
+    /**
+     * Whether the handle can take keyboard focus itself — a native control
+     * (`<button>`, …), a link with `href`, or any element with a `tabindex`.
+     * A focusable handle carries the keyboard drag for its `[mkDrag]`.
+     */
+    isFocusable(): boolean;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkDragHandle, never>;
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MkDragHandle, "[mkDragHandle]", ["mkDragHandle"], {}, {}, never, never, true, never>;
 }
 
 /**
  * Makes an item inside a `[mkDropList]` draggable — by pointer (mouse / touch /
- * pen) **and** by keyboard (WCAG 2.1.1). The item is focusable, exposes
- * `role="button"` + `aria-roledescription="Draggable item"`, and every move is
- * announced via {@link MkLiveAnnouncer}.
+ * pen) **and** by keyboard (WCAG 2.1.1). Every move is announced via
+ * {@link MkLiveAnnouncer}. Which element carries the keyboard interaction
+ * depends on the handle:
+ *
+ * - **No handle, or a decorative one** (`<span mkDragHandle aria-hidden>`):
+ *   the item itself is focusable and exposes `aria-roledescription="Draggable
+ *   item"` with `role="button"` — or `role="option"` when it is an `<li>` of a
+ *   `<ul mkDropList>`, which then becomes a labelled `listbox` (an `<li>` may
+ *   not take the `button` role).
+ * - **A focusable handle** (`<button mkDragHandle aria-label="…">`, or any
+ *   handle with `tabindex`): the handle is the keyboard target and receives
+ *   the `aria-roledescription` / `aria-pressed` / `aria-grabbed` state; the
+ *   item stays a plain container with no role and no `tabindex`, so it can hold
+ *   inputs, links and buttons of its own (no nested interactive controls) and
+ *   `<li>` items keep their list semantics.
  *
- * Keyboard: focus an item and press **Space/Enter** to pick it up, **Arrow**
- * keys to move it (crossing into connected lists at the ends / across the
- * perpendicular axis), **Space/Enter** to drop, **Escape** to cancel.
+ * Keyboard: focus the item (or its handle) and press **Space/Enter** to pick
+ * it up, **Arrow** keys to move it (crossing into connected lists at the ends /
+ * across the perpendicular axis), **Space/Enter** to drop, **Escape** to cancel.
  *
  * Touch: a swipe scrolls the page as usual — the drag only arms after a
  * long-press ({@link mkDragTouchDelay}, default 300 ms). While armed the item
@@ -46,9 +81,9 @@ declare class MkDragHandle {
  * synchronously on release so drops land exactly where the pointer ended.
  *
  * ```html
- * <li mkDrag [mkDragData]="row" [mkDragDisabled]="row.locked">
+ * <div mkDrag [mkDragData]="row" [mkDragDisabled]="row.locked">
  *   <span mkDragHandle aria-hidden="true">⠿</span> {{ row.title }}
- * </li>
+ * </div>
  * ```
  *
  * @typeParam T item data type.
@@ -82,6 +117,20 @@ declare class MkDrag<T = unknown> {
      * inner handle would start the outer drag and inner dnd would never work.
      */
     protected readonly ownHandles: _angular_core.Signal<MkDragHandle[]>;
+    /**
+     * The handle that carries the keyboard drag — the first of this item's
+     * handles that is focusable on its own (a `<button mkDragHandle>`, say).
+     * `null` when the item itself is the keyboard target.
+     */
+    readonly keyboardHandle: _angular_core.Signal<MkDragHandle | null>;
+    /**
+     * The role the item itself exposes: `null` when a focusable handle carries
+     * the interaction; `option` inside a list that resolved to a `listbox`
+     * (`<ul mkDropList>` / `<li mkDrag>`); `button` otherwise.
+     */
+    protected readonly itemRole: _angular_core.Signal<"button" | "option" | null>;
+    /** The element keyboard events act on: the focusable handle, else the item. */
+    private keyboardTarget;
     /** True while a pointer drag is in progress. */
     protected readonly dragging: _angular_core.WritableSignal<boolean>;
     /** True while the item is "picked up" for keyboard movement. */
@@ -105,6 +154,8 @@ declare class MkDrag<T = unknown> {
     private originLeft;
     private originTop;
     private preview;
+    constructor();
+    private toggleAttr;
     private readonly moveHandler;
     private readonly upHandler;
     private readonly cancelHandler;
@@ -168,7 +219,7 @@ declare class MkDrag<T = unknown> {
     private finishPointer;
     private commitPointer;
     protected onKeyDown(event: Event): void;
-    protected onBlur(): void;
+    protected onFocusOut(event: Event): void;
     private pickUp;
     private stepPrimary;
     private stepList;
@@ -228,14 +279,29 @@ declare class MkDrag<T = unknown> {
  * The array bound to `mkDropListData` is **not** mutated for you — handle
  * `mkDropListDropped` and call {@link mkMoveItemInArray} / {@link mkTransferArrayItem}.
  *
+ * Semantics follow the host element and its items, so the tree is always
+ * valid ARIA:
+ *
+ * - any host other than `<ul>`/`<ol>` is a `role="group"` (named by
+ *   `mkDropListLabel`) of `role="button"` items;
+ * - a `<ul>`/`<ol>` whose `<li mkDrag>` items all carry a *focusable*
+ *   `[mkDragHandle]` stays a plain list — the handles are the controls;
+ * - a `<ul>`/`<ol>` whose items are themselves the keyboard targets becomes a
+ *   `listbox` of `option`s (an `<li>` may not be a `button`); give it a
+ *   `mkDropListLabel`, listboxes need a name.
+ *
+ * A `role` you set in the template is kept, and `aria-orientation` is only
+ * exposed on roles that allow it (`listbox`, `toolbar`, `tree`, …) — the
+ * keyboard model handles both axes regardless.
+ *
  * ```html
- * <ul mkDropList [mkDropListData]="todo()"
- *     mkDropListId="todo" [mkDropListConnectedTo]="['done']"
- *     (mkDropListDropped)="drop($event)">
+ * <div mkDropList [mkDropListData]="todo()" mkDropListLabel="To do"
+ *      mkDropListId="todo" [mkDropListConnectedTo]="['done']"
+ *      (mkDropListDropped)="drop($event)">
  *   @for (t of todo(); track t.id) {
- *     <li mkDrag [mkDragData]="t">{{ t.title }}</li>
+ *     <div mkDrag [mkDragData]="t">{{ t.title }}</div>
  *   }
- * </ul>
+ * </div>
  * ```
  *
  * @typeParam T item data type.
@@ -268,6 +334,22 @@ declare class MkDropList<T = unknown> {
     private readonly autoId;
     /** Announceable name: the label when set, otherwise the resolved id. */
     readonly label: _angular_core.Signal<string>;
+    /** A `role` written in the template — always kept. */
+    private readonly explicitRole;
+    private readonly isNativeList;
+    /**
+     * The role the host exposes. One set in the template wins. A `<ul>`/`<ol>`
+     * keeps its implicit `list` role (`null` — nothing is written) while every
+     * item hands the keyboard drag to a focusable handle, and becomes a
+     * `listbox` (its items `option`s) otherwise. Any other element is a `group`.
+     */
+    readonly role: _angular_core.Signal<string | null>;
+    /** Whether `aria-orientation` is valid on the effective role. */
+    protected readonly orientationAllowed: _angular_core.Signal<boolean>;
+    /** A static `aria-label` written in the template, kept when no label input is set. */
+    private readonly staticAriaLabel;
+    /** Accessible name of the list: `mkDropListLabel`, else the template's own. */
+    protected readonly ariaLabel: _angular_core.Signal<string | null>;
     /** Connected-list ids, normalised to a plain array. */
     readonly connectedTo: _angular_core.Signal<readonly string[]>;
     /** The `mkDrag` items projected into this list, in DOM order. */

package/types/mk-kit-ui-forms.d.ts

@@ -1681,10 +1681,12 @@ declare class MkRepeaterEmpty {
  *
  * With `reorderable`, each row gets a drag handle wired through the dnd
  * module's touch-safe handle-based configuration (a swipe on the row body
- * still scrolls the page). Reordering also works by keyboard: focus the
- * handle (or the row) and press Space/Enter to pick up, arrows to move,
- * Space/Enter to drop, Escape to cancel. Each completed reorder is announced
- * via {@link MkLiveAnnouncer}.
+ * still scrolls the page). The handle button is the only control the dnd
+ * layer adds — rows stay plain list items, so the inputs and buttons inside
+ * them are never nested in an interactive role. Reordering also works by
+ * keyboard: focus the handle and press Space/Enter to pick up, arrows to
+ * move, Space/Enter to drop, Escape to cancel. Each completed reorder is
+ * announced via {@link MkLiveAnnouncer}.
  *
  * ```html
  * <mk-repeater [(items)]="rows" [min]="1" [max]="10" reorderable

package/types/mk-kit-ui-table.d.ts

@@ -178,12 +178,29 @@ interface MkGroupToggle {
     /** Whether the group is now collapsed. */
     collapsed: boolean;
 }
-/** Options for {@link MkTable.exportCsv}. */
-interface MkTableExportOptions extends MkCsvExportOptions {
+/** Options for {@link MkTable.getExportRows} — which rows and columns to export. */
+interface MkTableExportRowsOptions {
     /** Export only the selected rows (default: every row). */
     selectedOnly?: boolean;
     /** Restrict to these column keys, in table order (default: every column). */
     columns?: readonly string[];
+}
+/** What {@link MkTable.getExportRows} returns: the rows and the columns to write them with. */
+interface MkTableExportRows<T> {
+    /**
+     * The rows in display order — sorted the way they are shown, tree children
+     * flattened under their parent (expanded or not), selection applied when
+     * `selectedOnly` was set.
+     */
+    rows: T[];
+    /**
+     * The columns in the table's current (user-reordered) order, restricted to
+     * the requested keys, each with its header and formatter.
+     */
+    columns: MkCsvColumn<T>[];
+}
+/** Options for {@link MkTable.exportCsv}. */
+interface MkTableExportOptions extends MkCsvExportOptions, MkTableExportRowsOptions {
     /** Start the browser download (default `true`); `false` just returns the text. */
     download?: boolean;
 }
@@ -498,11 +515,28 @@ declare class MkTable<T = Record<string, unknown>> {
     expandAllRows(): void;
     /** Collapse every parent row (tree mode). */
     collapseAllRows(): void;
+    /**
+     * The rows and columns an export writes — exactly what {@link exportCsv}
+     * serialises, for other formats (XLSX, PDF, the clipboard, …): rows in
+     * display order with the current sort applied and tree children
+     * (`childrenKey`) flattened under their parent whether or not they are
+     * expanded, optionally only the selected ones; columns in the table's
+     * current order, restricted to `options.columns` when given, each carrying
+     * its header and `format` so what the user saw is what gets written.
+     *
+     * ```ts
+     * const { rows, columns } = table.getExportRows({ selectedOnly: true });
+     * const sheet = rows.map((row) =>
+     *   Object.fromEntries(columns.map((c) => [c.header ?? c.key, c.format ? c.format(row[c.key], row) : row[c.key]])),
+     * );
+     * ```
+     */
+    getExportRows(options?: MkTableExportRowsOptions): MkTableExportRows<T>;
     /**
      * The table's rows as CSV: current column order, column formatters applied,
      * sorted the way they are shown, tree children flattened under their parent
      * whether or not they are expanded. Downloads the file (default name
-     * `table.csv`) and returns the text.
+     * `table.csv`) and returns the text. Built on {@link getExportRows}.
      */
     exportCsv(options?: MkTableExportOptions): string;
     private setTreeExpanded;
@@ -876,4 +910,4 @@ declare class MkTableDataSource<T> {
 }
 
 export { MkSort, MkSortHeader, MkTable, MkTableCell, MkTableDataSource, MkTableRowDetail, mkDownloadText, mkExportCsv, mkToCsv };
-export type { MkCellEdit, MkColumnResize, MkCsvColumn, MkCsvExportOptions, MkCsvOptions, MkDataFetcher, MkDataPage, MkDataRequest, MkGroupToggle, MkSortChange, MkSortDirection, MkSortState, MkSortable, MkTableAlign, MkTableCellContext, MkTableColumn, MkTableDataSourceOptions, MkTableDensity, MkTableExportOptions, MkTableGroup, MkTreeToggle };
+export type { MkCellEdit, MkColumnResize, MkCsvColumn, MkCsvExportOptions, MkCsvOptions, MkDataFetcher, MkDataPage, MkDataRequest, MkGroupToggle, MkSortChange, MkSortDirection, MkSortState, MkSortable, MkTableAlign, MkTableCellContext, MkTableColumn, MkTableDataSourceOptions, MkTableDensity, MkTableExportOptions, MkTableExportRows, MkTableExportRowsOptions, MkTableGroup, MkTreeToggle };