tree-key-manager-strategy.d-XB6M79l-.d.ts 4.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116
  1. import { QueryList } from '@angular/core';
  2. import { Observable, Subject } from 'rxjs';
  3. /** Represents an item within a tree that can be passed to a TreeKeyManager. */
  4. interface TreeKeyManagerItem {
  5. /** Whether the item is disabled. */
  6. isDisabled?: (() => boolean) | boolean;
  7. /** The user-facing label for this item. */
  8. getLabel?(): string;
  9. /** Perform the main action (i.e. selection) for this item. */
  10. activate(): void;
  11. /** Retrieves the parent for this item. This is `null` if there is no parent. */
  12. getParent(): TreeKeyManagerItem | null;
  13. /** Retrieves the children for this item. */
  14. getChildren(): TreeKeyManagerItem[] | Observable<TreeKeyManagerItem[]>;
  15. /** Determines if the item is currently expanded. */
  16. isExpanded: (() => boolean) | boolean;
  17. /** Collapses the item, hiding its children. */
  18. collapse(): void;
  19. /** Expands the item, showing its children. */
  20. expand(): void;
  21. /**
  22. * Focuses the item. This should provide some indication to the user that this item is focused.
  23. */
  24. focus(): void;
  25. /**
  26. * Unfocus the item. This should remove the focus state.
  27. */
  28. unfocus(): void;
  29. /**
  30. * Sets the item to be focusable without actually focusing it.
  31. */
  32. makeFocusable?(): void;
  33. }
  34. /**
  35. * Configuration for the TreeKeyManager.
  36. */
  37. interface TreeKeyManagerOptions<T extends TreeKeyManagerItem> {
  38. /**
  39. * If true, then the key manager will call `activate` in addition to calling `focus` when a
  40. * particular item is focused.
  41. */
  42. shouldActivationFollowFocus?: boolean;
  43. /**
  44. * The direction in which the tree items are laid out horizontally. This influences which key
  45. * will be interpreted as expand or collapse.
  46. */
  47. horizontalOrientation?: 'rtl' | 'ltr';
  48. /**
  49. * If provided, navigation "skips" over items that pass the given predicate.
  50. *
  51. * If the item is to be skipped, predicate function should return false.
  52. */
  53. skipPredicate?: (item: T) => boolean;
  54. /**
  55. * If provided, determines how the key manager determines if two items are equivalent.
  56. *
  57. * It should provide a unique key for each unique tree item. If two tree items are equivalent,
  58. * then this function should return the same value.
  59. */
  60. trackBy?: (treeItem: T) => unknown;
  61. /**
  62. * If a value is provided, enables typeahead mode, which allows users to set the active item
  63. * by typing the visible label of the item.
  64. *
  65. * If a number is provided, this will be the time to wait after the last keystroke before
  66. * setting the active item. If `true` is provided, the default interval of 200ms will be used.
  67. */
  68. typeAheadDebounceInterval?: true | number;
  69. }
  70. interface TreeKeyManagerStrategy<T extends TreeKeyManagerItem> {
  71. /** Stream that emits any time the focused item changes. */
  72. readonly change: Subject<T | null>;
  73. /**
  74. * Cleans up the key manager.
  75. */
  76. destroy(): void;
  77. /**
  78. * Handles a keyboard event on the tree.
  79. *
  80. * @param event Keyboard event that represents the user interaction with the tree.
  81. */
  82. onKeydown(event: KeyboardEvent): void;
  83. /** Index of the currently active item. */
  84. getActiveItemIndex(): number | null;
  85. /** The currently active item. */
  86. getActiveItem(): T | null;
  87. /**
  88. * Focus the provided item by index.
  89. *
  90. * Updates the state of the currently active item. Emits to `change` stream if active item
  91. * Changes.
  92. * @param index The index of the item to focus.
  93. * @param options Additional focusing options.
  94. */
  95. focusItem(index: number, options?: {
  96. emitChangeEvent?: boolean;
  97. }): void;
  98. /**
  99. * Focus the provided item.
  100. *
  101. * Updates the state of the currently active item. Emits to `change` stream if active item
  102. * Changes.
  103. * @param item The item to focus. Equality is determined via the trackBy function.
  104. * @param options Additional focusing options.
  105. */
  106. focusItem(item: T, options?: {
  107. emitChangeEvent?: boolean;
  108. }): void;
  109. focusItem(itemOrIndex: number | T, options?: {
  110. emitChangeEvent?: boolean;
  111. }): void;
  112. }
  113. type TreeKeyManagerFactory<T extends TreeKeyManagerItem> = (items: Observable<T[]> | QueryList<T> | T[], options: TreeKeyManagerOptions<T>) => TreeKeyManagerStrategy<T>;
  114. export type { TreeKeyManagerStrategy as T, TreeKeyManagerItem as a, TreeKeyManagerFactory as b, TreeKeyManagerOptions as c };