@codual/react-native-ui 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (141) hide show
  1. package/LICENSE +202 -0
  2. package/NOTICE +2 -0
  3. package/README.md +18 -2
  4. package/dist/announce.d.ts +2 -0
  5. package/dist/announce.js +8 -0
  6. package/dist/charts/data.d.ts +32 -0
  7. package/dist/charts/data.js +13 -0
  8. package/dist/charts/labels.d.ts +54 -0
  9. package/dist/charts/labels.js +91 -0
  10. package/dist/charts/machine.d.ts +62 -0
  11. package/dist/charts/machine.js +144 -0
  12. package/dist/charts/points.d.ts +23 -0
  13. package/dist/charts/points.js +46 -0
  14. package/dist/charts/summary.d.ts +29 -0
  15. package/dist/charts/summary.js +45 -0
  16. package/dist/charts/use-chart-interaction.d.ts +62 -0
  17. package/dist/charts/use-chart-interaction.js +79 -0
  18. package/dist/forms/async-checks.d.ts +34 -0
  19. package/dist/forms/async-checks.js +77 -0
  20. package/dist/forms/field-errors.d.ts +8 -0
  21. package/dist/forms/field-errors.js +16 -0
  22. package/dist/forms/form-types.d.ts +43 -0
  23. package/dist/forms/form-types.js +2 -0
  24. package/dist/forms/machine.d.ts +63 -0
  25. package/dist/forms/machine.js +251 -0
  26. package/dist/forms/numbers.d.ts +5 -0
  27. package/dist/forms/numbers.js +83 -0
  28. package/dist/forms/rules.d.ts +47 -0
  29. package/dist/forms/rules.js +72 -0
  30. package/dist/forms/server-errors.d.ts +17 -0
  31. package/dist/forms/server-errors.js +22 -0
  32. package/dist/forms/use-form.d.ts +49 -0
  33. package/dist/forms/use-form.js +61 -0
  34. package/dist/index.d.ts +50 -0
  35. package/dist/index.js +94 -0
  36. package/dist/lists/PagedList.d.ts +47 -0
  37. package/dist/lists/PagedList.js +81 -0
  38. package/dist/lists/controller.d.ts +23 -0
  39. package/dist/lists/controller.js +20 -0
  40. package/dist/lists/inverted-list.d.ts +23 -0
  41. package/dist/lists/inverted-list.js +60 -0
  42. package/dist/lists/machine.d.ts +81 -0
  43. package/dist/lists/machine.js +252 -0
  44. package/dist/lists/newest-end.d.ts +30 -0
  45. package/dist/lists/newest-end.js +58 -0
  46. package/dist/lists/paged-content.d.ts +46 -0
  47. package/dist/lists/paged-content.js +65 -0
  48. package/dist/lists/paged-list-types.d.ts +56 -0
  49. package/dist/lists/paged-list-types.js +2 -0
  50. package/dist/lists/system-footer.d.ts +28 -0
  51. package/dist/lists/system-footer.js +50 -0
  52. package/dist/lists/use-paged-list.d.ts +25 -0
  53. package/dist/lists/use-paged-list.js +34 -0
  54. package/dist/permissions/access.d.ts +30 -0
  55. package/dist/permissions/access.js +2 -0
  56. package/dist/permissions/android-permission.d.ts +52 -0
  57. package/dist/permissions/android-permission.js +143 -0
  58. package/dist/permissions/permission.d.ts +69 -0
  59. package/dist/permissions/permission.js +201 -0
  60. package/dist/permissions/setup.d.ts +25 -0
  61. package/dist/permissions/setup.js +41 -0
  62. package/dist/permissions/status.d.ts +29 -0
  63. package/dist/permissions/status.js +18 -0
  64. package/dist/permissions/use-permission.d.ts +23 -0
  65. package/dist/permissions/use-permission.js +29 -0
  66. package/dist/purchases/Paywall.d.ts +27 -0
  67. package/dist/purchases/Paywall.js +28 -0
  68. package/dist/purchases/paywall-content.d.ts +20 -0
  69. package/dist/purchases/paywall-content.js +34 -0
  70. package/dist/purchases/purchases.d.ts +92 -0
  71. package/dist/purchases/purchases.js +236 -0
  72. package/dist/purchases/status.d.ts +62 -0
  73. package/dist/purchases/status.js +25 -0
  74. package/dist/purchases/store.d.ts +71 -0
  75. package/dist/purchases/store.js +2 -0
  76. package/dist/purchases/system-views.d.ts +49 -0
  77. package/dist/purchases/system-views.js +91 -0
  78. package/dist/purchases/use-purchases.d.ts +3 -0
  79. package/dist/purchases/use-purchases.js +8 -0
  80. package/dist/react-native-iap/iap-purchases.d.ts +24 -0
  81. package/dist/react-native-iap/iap-purchases.js +90 -0
  82. package/dist/react-native-iap/iap-store.d.ts +56 -0
  83. package/dist/react-native-iap/iap-store.js +249 -0
  84. package/dist/react-native-iap/iap-types.d.ts +12 -0
  85. package/dist/react-native-iap/iap-types.js +11 -0
  86. package/dist/react-native-iap/index.d.ts +31 -0
  87. package/dist/react-native-iap/index.js +24 -0
  88. package/dist/react-native-permissions/index.d.ts +24 -0
  89. package/dist/react-native-permissions/index.js +88 -0
  90. package/dist/screen-states/ScreenStates.d.ts +38 -0
  91. package/dist/screen-states/ScreenStates.js +69 -0
  92. package/dist/screen-states/errors.d.ts +9 -0
  93. package/dist/screen-states/errors.js +24 -0
  94. package/dist/screen-states/machine.d.ts +97 -0
  95. package/dist/screen-states/machine.js +172 -0
  96. package/dist/screen-states/system-views.d.ts +40 -0
  97. package/dist/screen-states/system-views.js +66 -0
  98. package/dist/screen-states/use-screen-states.d.ts +23 -0
  99. package/dist/screen-states/use-screen-states.js +41 -0
  100. package/dist/search/SearchResults.d.ts +22 -0
  101. package/dist/search/SearchResults.js +25 -0
  102. package/dist/search/announcements.d.ts +17 -0
  103. package/dist/search/announcements.js +31 -0
  104. package/dist/search/labels.d.ts +15 -0
  105. package/dist/search/labels.js +14 -0
  106. package/dist/search/machine.d.ts +65 -0
  107. package/dist/search/machine.js +241 -0
  108. package/dist/search/recent-search-sync.d.ts +32 -0
  109. package/dist/search/recent-search-sync.js +87 -0
  110. package/dist/search/recent-searches.d.ts +22 -0
  111. package/dist/search/recent-searches.js +40 -0
  112. package/dist/search/system-views.d.ts +11 -0
  113. package/dist/search/system-views.js +16 -0
  114. package/dist/search/types.d.ts +51 -0
  115. package/dist/search/types.js +2 -0
  116. package/dist/search/use-search.d.ts +73 -0
  117. package/dist/search/use-search.js +123 -0
  118. package/dist/selection/config.d.ts +34 -0
  119. package/dist/selection/config.js +13 -0
  120. package/dist/selection/labels.d.ts +19 -0
  121. package/dist/selection/labels.js +23 -0
  122. package/dist/selection/machine.d.ts +80 -0
  123. package/dist/selection/machine.js +274 -0
  124. package/dist/selection/snapshot.d.ts +54 -0
  125. package/dist/selection/snapshot.js +45 -0
  126. package/dist/selection/state.d.ts +25 -0
  127. package/dist/selection/state.js +24 -0
  128. package/dist/selection/system-views.d.ts +11 -0
  129. package/dist/selection/system-views.js +22 -0
  130. package/dist/selection/use-selection.d.ts +73 -0
  131. package/dist/selection/use-selection.js +100 -0
  132. package/dist/sheets/machine.d.ts +101 -0
  133. package/dist/sheets/machine.js +213 -0
  134. package/dist/sheets/use-sheet.d.ts +78 -0
  135. package/dist/sheets/use-sheet.js +103 -0
  136. package/dist/victory-native/index.d.ts +37 -0
  137. package/dist/victory-native/index.js +41 -0
  138. package/package.json +94 -4
  139. package/react-native-iap/package.json +4 -0
  140. package/react-native-permissions/package.json +4 -0
  141. package/victory-native/package.json +4 -0
@@ -0,0 +1,11 @@
1
+ import type { SearchLabels } from "./labels";
2
+ import type { RecentSearches } from "./recent-searches";
3
+ export declare function SystemNoResultsView({ query, labels, }: {
4
+ readonly query: string;
5
+ readonly labels: SearchLabels;
6
+ }): import("react").JSX.Element;
7
+ /** The recent searches, each picking the search, with a Remove button each and a Clear button. Nothing when empty. */
8
+ export declare function SystemRecentSearches({ recent, labels, }: {
9
+ readonly recent: RecentSearches;
10
+ readonly labels: SearchLabels;
11
+ }): import("react").JSX.Element | null;
@@ -0,0 +1,16 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.SystemNoResultsView = SystemNoResultsView;
4
+ exports.SystemRecentSearches = SystemRecentSearches;
5
+ const jsx_runtime_1 = require("react/jsx-runtime");
6
+ const react_native_1 = require("react-native");
7
+ // System components only, with no styles of their own.
8
+ function SystemNoResultsView({ query, labels, }) {
9
+ return ((0, jsx_runtime_1.jsxs)(react_native_1.View, { children: [(0, jsx_runtime_1.jsx)(react_native_1.Text, { accessibilityRole: "header", children: labels.noResults(query) }), (0, jsx_runtime_1.jsx)(react_native_1.Text, { children: labels.noResultsMessage })] }));
10
+ }
11
+ /** The recent searches, each picking the search, with a Remove button each and a Clear button. Nothing when empty. */
12
+ function SystemRecentSearches({ recent, labels, }) {
13
+ if (recent.searches.length === 0)
14
+ return null;
15
+ return ((0, jsx_runtime_1.jsxs)(react_native_1.View, { children: [(0, jsx_runtime_1.jsx)(react_native_1.Text, { accessibilityRole: "header", children: labels.recentSearches }), (0, jsx_runtime_1.jsx)(react_native_1.Button, { title: labels.clear, onPress: recent.clear }), recent.searches.map((search) => ((0, jsx_runtime_1.jsxs)(react_native_1.View, { children: [(0, jsx_runtime_1.jsx)(react_native_1.Button, { title: search, onPress: () => recent.pick(search) }), (0, jsx_runtime_1.jsx)(react_native_1.Button, { title: "\u00D7", accessibilityLabel: labels.remove(search), onPress: () => recent.remove(search) })] }, search)))] }));
16
+ }
@@ -0,0 +1,51 @@
1
+ import type { PagedListController } from "../lists/controller";
2
+ import type { PagedListAnnouncement } from "../lists/machine";
3
+ import type { Page } from "../lists/paged-content";
4
+ import type { SearchAnnouncement } from "./announcements";
5
+ /**
6
+ * Searches the trimmed query in the scope, for the page with this token (`undefined` for the first). Abort the work
7
+ * when `signal` aborts: the query changed or the screen went away, and the result is dropped.
8
+ */
9
+ export type SearchFunction<Item, Token, Scope> = (query: string, request: SearchRequest<Token, Scope>) => Promise<Page<Item, Token>>;
10
+ /** What a search function gets besides the query: the page token, the scope, and the signal that aborts it. */
11
+ export interface SearchRequest<Token, Scope> {
12
+ readonly token: Token | undefined;
13
+ readonly scope: Scope | undefined;
14
+ readonly signal: AbortSignal;
15
+ }
16
+ /** A search of a remote source, in pages, or of items already in memory, filtered at once. */
17
+ type SearchMode<Item, Token, Scope> = {
18
+ readonly kind: "remote";
19
+ readonly search: SearchFunction<Item, Token, Scope>;
20
+ } | {
21
+ readonly kind: "local";
22
+ readonly items: readonly Item[];
23
+ readonly matches: (item: Item, query: string) => boolean;
24
+ };
25
+ export interface SearchSource<Item, Token, Scope> {
26
+ readonly mode: SearchMode<Item, Token, Scope>;
27
+ readonly keyExtractor: (item: Item) => string;
28
+ readonly isOffline: (error: unknown) => boolean;
29
+ readonly debounceMs: number;
30
+ readonly minimumLength: number;
31
+ readonly maxRecentSearches: number;
32
+ readonly announce: (announcement: SearchAnnouncement) => void;
33
+ readonly announcePage: (announcement: PagedListAnnouncement) => void;
34
+ }
35
+ /** The results of one query: its paged list, and the query and scope it searched. */
36
+ export interface QueryResults<Item, Scope> {
37
+ /** New for each query's list: a `key` for its views, so the old one's go with it. */
38
+ readonly key: number;
39
+ readonly query: string;
40
+ readonly scope: Scope | undefined;
41
+ readonly list: PagedListController<Item>;
42
+ }
43
+ export interface SearchSnapshot<Item, Scope> {
44
+ /** The field's text, exactly as typed. What is searched is this, trimmed. */
45
+ readonly query: string;
46
+ readonly scope: Scope | undefined;
47
+ readonly recentSearches: readonly string[];
48
+ /** The latest query's results, or `undefined` while the suggestions show. */
49
+ readonly results: QueryResults<Item, Scope> | undefined;
50
+ }
51
+ export {};
@@ -0,0 +1,2 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
@@ -0,0 +1,73 @@
1
+ import { type PagedListLabels } from "../lists/system-footer";
2
+ import { type SearchLabels } from "./labels";
3
+ import { type RecentSearches, type RecentSearchStore } from "./recent-searches";
4
+ import type { SearchFunction, SearchSnapshot } from "./types";
5
+ interface SearchCommonOptions<Item, Scope> {
6
+ /** The identity of a result: one whose key is already in the list is dropped. `FlatList` uses it too. */
7
+ readonly keyExtractor: (item: Item) => string;
8
+ /** How long typing must stop before a query is searched (in local mode, before the results are announced). */
9
+ readonly debounceMs?: number;
10
+ /** How many characters a trimmed query needs to be searched: at least 1. */
11
+ readonly minimumLength?: number;
12
+ /** A query searched at once on mount (a deep link, the screen before), not saved as a recent search. */
13
+ readonly initialQuery?: string;
14
+ readonly initialScope?: Scope;
15
+ /** Where recent searches are kept, read once on mount. By default, in memory for this screen only. */
16
+ readonly recentSearches?: RecentSearchStore;
17
+ readonly maxRecentSearches?: number;
18
+ /** Whether a failed search shows the offline view. By default, `fetch`'s "Network request failed". */
19
+ readonly isOffline?: (error: unknown) => boolean;
20
+ /** The text of the announcements, and of the views `SearchResults` draws. */
21
+ readonly labels?: Partial<SearchLabels & PagedListLabels>;
22
+ }
23
+ /** A search of a remote source, in pages. */
24
+ export interface RemoteSearchOptions<Item, Token, Scope> extends SearchCommonOptions<Item, Scope> {
25
+ readonly search: SearchFunction<Item, Token, Scope>;
26
+ }
27
+ /** A search of items already in memory: every change of the query filters them at once, with no loading. */
28
+ export interface LocalSearchOptions<Item, Scope> extends SearchCommonOptions<Item, Scope> {
29
+ readonly items: readonly Item[];
30
+ /** Whether an item matches the trimmed query. */
31
+ readonly matches: (item: Item, query: string) => boolean;
32
+ }
33
+ export type SearchOptions<Item, Token, Scope> = RemoteSearchOptions<Item, Token, Scope> | LocalSearchOptions<Item, Scope>;
34
+ /** Props for the app's `TextInput`: the query, submit on the keyboard's search key, and no autocorrect. */
35
+ export interface SearchInputProps {
36
+ readonly value: string;
37
+ readonly onChangeText: (text: string) => void;
38
+ readonly onSubmitEditing: () => void;
39
+ readonly returnKeyType: "search";
40
+ readonly enterKeyHint: "search";
41
+ readonly autoCorrect: false;
42
+ readonly autoCapitalize: "none";
43
+ readonly clearButtonMode: "while-editing";
44
+ }
45
+ /** Props for the `FlatList` or `ScrollView` of the results and suggestions: scrolling dismisses the keyboard. */
46
+ export interface SearchListProps {
47
+ readonly keyboardDismissMode: "on-drag";
48
+ readonly keyboardShouldPersistTaps: "handled";
49
+ }
50
+ export interface SearchController<Item, Scope> extends Omit<SearchSnapshot<Item, Scope>, "recentSearches"> {
51
+ readonly setQuery: (query: string) => void;
52
+ readonly setScope: (scope: Scope | undefined) => void;
53
+ /** The keyboard's search key, or, with `query`, a recent search or suggestion picked: searches at once. */
54
+ readonly submit: (query?: string) => void;
55
+ /** Clears the query, cancels the search and dismisses the keyboard. */
56
+ readonly cancel: () => void;
57
+ readonly retry: () => void;
58
+ /** The recent searches, most recent first, with the actions to pick, remove and clear them. */
59
+ readonly recent: RecentSearches;
60
+ readonly inputProps: SearchInputProps;
61
+ readonly listProps: SearchListProps;
62
+ /** The identity of a result, as given in the options: `SearchResults` uses it. */
63
+ readonly keyExtractor: (item: Item) => string;
64
+ /** The text of the views `SearchResults` draws: the defaults with the `labels` option over them. */
65
+ readonly labels: SearchLabels & PagedListLabels;
66
+ }
67
+ /**
68
+ * A screen that searches as the person types, for the app's own `TextInput` (pass it `inputProps`) and results
69
+ * (`SearchResults`, or draw `results` yourself). Searches on mount if there is an initial query, aborts on unmount,
70
+ * and always uses the latest options.
71
+ */
72
+ export declare function useSearch<Item, Token = never, Scope = undefined>(options: SearchOptions<Item, Token, Scope>): SearchController<Item, Scope>;
73
+ export {};
@@ -0,0 +1,123 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.useSearch = useSearch;
4
+ const react_1 = require("react");
5
+ const react_native_1 = require("react-native");
6
+ const announce_1 = require("../announce");
7
+ const system_footer_1 = require("../lists/system-footer");
8
+ const errors_1 = require("../screen-states/errors");
9
+ const announcements_1 = require("./announcements");
10
+ const labels_1 = require("./labels");
11
+ const machine_1 = require("./machine");
12
+ const recent_searches_1 = require("./recent-searches");
13
+ const DEFAULT_DEBOUNCE_MS = 300;
14
+ const DEFAULT_MINIMUM_LENGTH = 1;
15
+ const DEFAULT_MAX_RECENT_SEARCHES = 10;
16
+ const SEARCH_LIST_PROPS = {
17
+ keyboardDismissMode: "on-drag",
18
+ keyboardShouldPersistTaps: "handled",
19
+ };
20
+ function checkOptions(debounceMs, minimumLength) {
21
+ if (!(Number.isInteger(minimumLength) && minimumLength >= 1)) {
22
+ throw new RangeError(`useSearch's minimumLength must be a whole number of 1 or more, not ${minimumLength}.`);
23
+ }
24
+ if (!(debounceMs >= 0))
25
+ throw new RangeError(`useSearch's debounceMs must be 0 or more, not ${debounceMs}.`);
26
+ }
27
+ function isSameItems(one, other) {
28
+ if (one === other)
29
+ return true;
30
+ if (one === undefined || other === undefined || one.length !== other.length)
31
+ return false;
32
+ return one.every((item, index) => item === other[index]);
33
+ }
34
+ function resolvedLabels(labels) {
35
+ return { ...labels_1.defaultSearchLabels, ...system_footer_1.defaultPagedListLabels, ...labels };
36
+ }
37
+ function sourceOf(options) {
38
+ const debounceMs = options.debounceMs ?? DEFAULT_DEBOUNCE_MS;
39
+ const minimumLength = options.minimumLength ?? DEFAULT_MINIMUM_LENGTH;
40
+ checkOptions(debounceMs, minimumLength);
41
+ const labels = resolvedLabels(options.labels);
42
+ return {
43
+ mode: "search" in options
44
+ ? { kind: "remote", search: options.search }
45
+ : { kind: "local", items: options.items, matches: options.matches },
46
+ keyExtractor: options.keyExtractor,
47
+ isOffline: options.isOffline ?? errors_1.isOfflineError,
48
+ debounceMs,
49
+ minimumLength,
50
+ maxRecentSearches: options.maxRecentSearches ?? DEFAULT_MAX_RECENT_SEARCHES,
51
+ announce: (announcement) => (0, announce_1.announce)((0, announcements_1.searchAnnouncementText)(announcement, labels)),
52
+ announcePage: (announcement) => (0, announce_1.announce)((0, system_footer_1.announcementText)(announcement, labels)),
53
+ };
54
+ }
55
+ /**
56
+ * A screen that searches as the person types, for the app's own `TextInput` (pass it `inputProps`) and results
57
+ * (`SearchResults`, or draw `results` yourself). Searches on mount if there is an initial query, aborts on unmount,
58
+ * and always uses the latest options.
59
+ */
60
+ function useSearch(options) {
61
+ const source = sourceOf(options);
62
+ const latest = (0, react_1.useRef)(source);
63
+ (0, react_1.useLayoutEffect)(() => {
64
+ latest.current = source;
65
+ });
66
+ const [machine] = (0, react_1.useState)(() => new machine_1.SearchMachine(() => latest.current, options.recentSearches ?? (0, recent_searches_1.createInMemoryRecentSearches)(), {
67
+ query: options.initialQuery ?? "",
68
+ scope: options.initialScope,
69
+ }));
70
+ const snapshot = (0, react_1.useSyncExternalStore)(machine.subscribe, machine.getSnapshot);
71
+ (0, react_1.useEffect)(() => {
72
+ machine.appear();
73
+ return machine.disappear;
74
+ }, [machine]);
75
+ const items = "items" in options ? options.items : undefined;
76
+ const filteredItems = (0, react_1.useRef)(items);
77
+ (0, react_1.useEffect)(() => {
78
+ // An app often passes a new array with the same items on every render (`items.filter(…)`).
79
+ if (isSameItems(filteredItems.current, items))
80
+ return;
81
+ filteredItems.current = items;
82
+ machine.itemsChanged();
83
+ }, [machine, items]);
84
+ const { labels } = options;
85
+ // Stable across renders, and always the latest option.
86
+ const [keyExtractor] = (0, react_1.useState)(() => (item) => latest.current.keyExtractor(item));
87
+ return (0, react_1.useMemo)(() => controllerOf(machine, snapshot, { labels: resolvedLabels(labels), keyExtractor }), [machine, snapshot, labels, keyExtractor]);
88
+ }
89
+ function controllerOf(machine, snapshot, { labels, keyExtractor }) {
90
+ const cancel = () => {
91
+ machine.cancel();
92
+ react_native_1.Keyboard.dismiss();
93
+ };
94
+ return {
95
+ query: snapshot.query,
96
+ scope: snapshot.scope,
97
+ results: snapshot.results,
98
+ setQuery: machine.setQuery,
99
+ setScope: machine.setScope,
100
+ submit: machine.submit,
101
+ cancel,
102
+ retry: machine.retry,
103
+ recent: {
104
+ searches: snapshot.recentSearches,
105
+ pick: machine.submit,
106
+ remove: machine.removeRecentSearch,
107
+ clear: machine.clearRecentSearches,
108
+ },
109
+ inputProps: {
110
+ value: snapshot.query,
111
+ onChangeText: machine.setQuery,
112
+ onSubmitEditing: () => machine.submit(),
113
+ returnKeyType: "search",
114
+ enterKeyHint: "search",
115
+ autoCorrect: false,
116
+ autoCapitalize: "none",
117
+ clearButtonMode: "while-editing",
118
+ },
119
+ listProps: SEARCH_LIST_PROPS,
120
+ labels,
121
+ keyExtractor,
122
+ };
123
+ }
@@ -0,0 +1,34 @@
1
+ /** Whether any number of items can be selected (up to `max`), or at most one. */
2
+ export type SelectionKind = "multiple" | "single";
3
+ /** Whether the selection mode is entered on demand (an edit screen), or is always on (a picker). */
4
+ export type SelectionActivation = "onDemand" | "always";
5
+ export interface SelectionConfig {
6
+ readonly kind: SelectionKind;
7
+ readonly max: number | undefined;
8
+ readonly activation: SelectionActivation;
9
+ }
10
+ /** A bulk action on the selected items' keys, in the order they were selected. */
11
+ export type SelectionAction = (keys: readonly string[], context: SelectionActionContext) => Promise<void>;
12
+ /** What else a bulk action needs to know, as it was when the action started. */
13
+ export interface SelectionActionContext {
14
+ /** The selection stands for every item on the server, not only the keys loaded. */
15
+ readonly isAllOnServer: boolean;
16
+ }
17
+ /** What a screen reader hears after a change the person makes. */
18
+ export type SelectionAnnouncement = {
19
+ readonly kind: "count";
20
+ readonly count: number;
21
+ readonly total: number;
22
+ } | {
23
+ readonly kind: "limit";
24
+ readonly max: number;
25
+ };
26
+ export interface SelectionSource<Item> {
27
+ readonly keyExtractor: (item: Item) => string;
28
+ readonly isDisabled: (item: Item) => boolean;
29
+ /** How many items the server has, for select all on the server; `undefined` when the app doesn't say. */
30
+ readonly serverTotal: number | undefined;
31
+ readonly announce: (announcement: SelectionAnnouncement) => void;
32
+ }
33
+ /** Throws a `RangeError` for a `max` that a selection can't have. */
34
+ export declare function checkConfig({ kind, max }: SelectionConfig): void;
@@ -0,0 +1,13 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.checkConfig = checkConfig;
4
+ /** Throws a `RangeError` for a `max` that a selection can't have. */
5
+ function checkConfig({ kind, max }) {
6
+ if (max === undefined)
7
+ return;
8
+ if (kind === "single")
9
+ throw new RangeError("A single selection has no max: it is one item at most.");
10
+ if (!Number.isInteger(max) || max < 1) {
11
+ throw new RangeError(`A selection's max must be a whole number of items, 1 or more, not ${max}.`);
12
+ }
13
+ }
@@ -0,0 +1,19 @@
1
+ import type { SelectionAnnouncement } from "./config";
2
+ /** The text of the Select and Select All buttons, the count title and the announcements. */
3
+ export interface SelectionLabels {
4
+ readonly select: string;
5
+ readonly done: string;
6
+ readonly selectAll: string;
7
+ readonly deselectAll: string;
8
+ /** "3 Selected", with the plural your language needs. */
9
+ readonly title: (count: number) => string;
10
+ /** "3 Selected, 1 Hidden": the title while a filter or search hides selected items. */
11
+ readonly titleWithHidden: (count: number, hidden: number) => string;
12
+ /** "3 of 10 selected.", announced after each change. */
13
+ readonly selectedCount: (count: number, total: number) => string;
14
+ /** "You can select up to 5 items.", announced when selecting one more would pass the maximum. */
15
+ readonly limit: (max: number) => string;
16
+ }
17
+ export declare const defaultSelectionLabels: SelectionLabels;
18
+ /** The words of an announcement, in the app's labels. */
19
+ export declare function announcementText(announcement: SelectionAnnouncement, labels: SelectionLabels): string;
@@ -0,0 +1,23 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.defaultSelectionLabels = void 0;
4
+ exports.announcementText = announcementText;
5
+ exports.defaultSelectionLabels = {
6
+ select: "Select",
7
+ done: "Done",
8
+ selectAll: "Select All",
9
+ deselectAll: "Deselect All",
10
+ title: (count) => `${count} Selected`,
11
+ titleWithHidden: (count, hidden) => `${count} Selected, ${hidden} Hidden`,
12
+ selectedCount: (count, total) => `${count} of ${total} selected.`,
13
+ limit: (max) => (max === 1 ? "You can select up to 1 item." : `You can select up to ${max} items.`),
14
+ };
15
+ /** The words of an announcement, in the app's labels. */
16
+ function announcementText(announcement, labels) {
17
+ switch (announcement.kind) {
18
+ case "count":
19
+ return labels.selectedCount(announcement.count, announcement.total);
20
+ case "limit":
21
+ return labels.limit(announcement.max);
22
+ }
23
+ }
@@ -0,0 +1,80 @@
1
+ import { type SelectionAction, type SelectionConfig, type SelectionSource } from "./config";
2
+ import { type SelectionSnapshot } from "./snapshot";
3
+ /**
4
+ * The state machine behind `useSelection`: which items are selected, by key, and the selection mode. `source` is
5
+ * read on every change, so it can change between renders. Updates that change nothing shown publish nothing.
6
+ */
7
+ export declare class SelectionMachine<Item> {
8
+ private readonly source;
9
+ readonly config: SelectionConfig;
10
+ private state;
11
+ private snapshot;
12
+ private selectedSet;
13
+ /** The current item for each key, so an old copy of an item a row still holds never decides. */
14
+ private itemsByKey;
15
+ private visibleByKey;
16
+ /** The items became none while an action ran: the mode ends when it does. */
17
+ private endsWhenActionEnds;
18
+ private readonly listeners;
19
+ constructor(source: () => SelectionSource<Item>, config: SelectionConfig);
20
+ readonly subscribe: (listener: () => void) => (() => void);
21
+ readonly getSnapshot: () => SelectionSnapshot;
22
+ readonly isSelected: (item: Item) => boolean;
23
+ /** The items and visible items last given, or `undefined` for a list not given yet. */
24
+ get knownLists(): {
25
+ readonly items: readonly Item[] | undefined;
26
+ readonly visible: readonly Item[] | undefined;
27
+ };
28
+ /** The Select action: turns the mode on with nothing selected. */
29
+ readonly enter: () => void;
30
+ /** Done or Cancel: turns the mode off and clears the selection. Does nothing while an action runs. */
31
+ readonly exit: () => void;
32
+ /** Back: leaves the mode first, and returns whether it handled back, so the screen stays. */
33
+ readonly back: () => boolean;
34
+ /** A tap in the mode: selects the item, or deselects it (ending all on the server) if it is selected. */
35
+ readonly toggle: (item: Item) => void;
36
+ /** A long press: turns the mode on with this item selected, or toggles it in the mode. */
37
+ readonly longPress: (item: Item) => void;
38
+ /** Selects every visible item that isn't disabled, in list order, up to the maximum. Never loads more. */
39
+ readonly selectAll: () => void;
40
+ /** Clears the selection, all on the server too, and stays in the mode. */
41
+ readonly deselectAll: () => void;
42
+ /** Makes the selection stand for every item on the server, once `canSelectAllOnServer`. */
43
+ readonly selectAllOnServer: () => void;
44
+ /**
45
+ * The data, once loaded: drops every selected item that is gone or now disabled, and ends the mode when there
46
+ * are none (once any running action ends). All on the server, new items arrive selected.
47
+ */
48
+ readonly updateItems: (items: readonly Item[]) => void;
49
+ /**
50
+ * What a filter or search shows: a selected item missing from it is hidden, not dropped. Drops only visible
51
+ * selected items that are now disabled, and never ends the mode. `undefined` clears the filter.
52
+ */
53
+ readonly updateVisibleItems: (visible: readonly Item[] | undefined) => void;
54
+ /** Runs `action` on the selection once; clears it if it succeeds, keeps it and reports the error if it fails. */
55
+ readonly perform: (action: SelectionAction) => void;
56
+ /** Asks for a confirmation before `action`: nothing runs until `confirmPendingAction()`. */
57
+ readonly performAfterConfirmation: (action: SelectionAction) => void;
58
+ /** Runs the action waiting for confirmation on the selection as it is now; with nothing selected, runs nothing. */
59
+ readonly confirmPendingAction: () => void;
60
+ readonly cancelPendingAction: () => void;
61
+ readonly dismissActionError: () => void;
62
+ /** Publishes what a changed `source` (a new `serverTotal`, say) changes. */
63
+ readonly sourceChanged: () => void;
64
+ private actionFailed;
65
+ /**
66
+ * Not disabled and in the items once they are known (they decide), or else in the visible items: a row left from
67
+ * a removed item selects nothing.
68
+ */
69
+ private isSelectable;
70
+ /** What select all and the total cover: the data's copies of the visible items still in it, or else either list. */
71
+ private shownItems;
72
+ private selectableKeys;
73
+ private canChange;
74
+ private canStartAction;
75
+ /** A change the person makes, announced; any deselection ends all on the server. */
76
+ private changeSelection;
77
+ private announceCount;
78
+ private update;
79
+ private derive;
80
+ }