@sillsdev/config-r 1.0.0-alpha.35 → 1.0.0-alpha.37

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.
package/README.md CHANGED
@@ -23,6 +23,8 @@ pnpm install
23
23
  pnpm dev
24
24
  ```
25
25
 
26
+ `pnpm test` runs the unit tests. `pnpm test:e2e` runs the Playwright tests in `tests/` against the demo app, which it starts with the vite dev server; the first time, install the browser with `pnpm exec playwright install chromium`.
27
+
26
28
  ## Installing
27
29
 
28
30
  ```
@@ -58,6 +60,8 @@ To provide languages other than English for the small set of built-in strings, p
58
60
  fieldRequiredMessage: 'Requiere un valor',
59
61
  invalidValueMessage: 'Valor no valido',
60
62
  searchLabel: 'Buscar',
63
+ clearSearchLabel: 'Borrar la busqueda',
64
+ noSearchMatchesLabel: 'No hay coincidencias',
61
65
  matchesLabel: (count) => `${count} coincidencias`,
62
66
  }}
63
67
  >
@@ -67,6 +71,28 @@ To provide languages other than English for the small set of built-in strings, p
67
71
 
68
72
  `searchLabel` is used for both the visible search placeholder and the input accessibility label.
69
73
 
74
+ ## Search
75
+
76
+ `showAppBar={true}` together with `showSearch={true}` puts a search box in the pane's app bar. While it holds text, the pane shows every setting, on any enabled page or sub-page, whose label, description, `searchTerms`, or select option (its label, or its value when it has no label, and its description) contains that text, ignoring case, and highlights the matches. A page or group whose own label, description or `searchTerms` match shows all of its settings. The search ignores pages that are disabled or in a disabled area. When nothing matches, the pane says so (`noSearchMatchesLabel`). Clearing the search returns to the first enabled page, and clicking a page ends the search and opens that page.
77
+
78
+ To show the search box somewhere of your own, such as your dialog's title bar, pass that element as `searchBoxContainer`. The pane then needs no app bar.
79
+
80
+ The search box takes its border color, corner radius and text color from the MUI theme. To style it and other parts of the pane further, target these class names, which config-r keeps stable:
81
+
82
+ | Class name | Element |
83
+ | --------------------------- | ------------------------------------------------------------------------------------------------ |
84
+ | `configr-search-box` | the search box, around the next three |
85
+ | `configr-search-icon` | the wrapper around the magnifying glass |
86
+ | `configr-search-input` | the `<input>` itself (its width, font and padding) |
87
+ | `configr-search-clear` | the wrapper around the clear button, present only while the box holds text |
88
+ | `configr-search-match` | each `<mark>` around matching text in the pane (the browser draws it yellow unless you style it) |
89
+ | `configr-subpage-back` | the button at the top of a sub-page that goes back, holding the arrow and the sub-page's label |
90
+ | `configr-subpage-back-icon` | the arrow in that button |
91
+
92
+ Config-R's own rules use two class selectors, so a host rule needs at least three to win, e.g. `.my-title .configr-search-box .configr-search-input`.
93
+
94
+ Search reads the props of the elements you pass, so text that a custom component renders for itself is found only through that component's `label`, `description` or `searchTerms` props.
95
+
70
96
  ## Knowing and choosing the page
71
97
 
72
98
  `onTopLevelPageChange` is called with the `pageKey` of the top-level page showing, when the pane mounts and whenever the page changes. To show a page from outside the pane, put a ref on it and call `selectTopLevelPage`, which shows that page and keeps the values being edited:
@@ -1,4 +1,8 @@
1
1
  import * as React from 'react';
2
+ export declare const ConfigrSearchBox: React.FunctionComponent<{
3
+ searchValue: string | null;
4
+ setSearchString: (s: string) => void;
5
+ }>;
2
6
  export declare const ConfigrAppBar: React.FunctionComponent<React.PropsWithChildren<{
3
7
  label: string;
4
8
  showSearch?: boolean;
@@ -3,6 +3,8 @@ export type ConfigrLocalizations = {
3
3
  fieldRequiredMessage: string;
4
4
  invalidValueMessage: string;
5
5
  searchLabel: string;
6
+ clearSearchLabel: string;
7
+ noSearchMatchesLabel: string;
6
8
  matchesLabel: (count: number) => string;
7
9
  };
8
10
  export type ConfigrLocalizationOverrides = Partial<ConfigrLocalizations>;
@@ -18,6 +18,11 @@ export declare const ConfigrPane: React.ForwardRefExoticComponent<{
18
18
  onChange?: (currentValues: ConfigrValues) => void;
19
19
  showAppBar?: boolean;
20
20
  showSearch?: boolean;
21
+ /**
22
+ * An element of the host's, such as its dialog's title bar, to show the search box
23
+ * in. The pane then needs neither showAppBar nor showSearch to offer search.
24
+ */
25
+ searchBoxContainer?: HTMLElement | null;
21
26
  themeOverrides?: ThemeOptions;
22
27
  showJson?: boolean;
23
28
  showRequiredMessage?: boolean;
@@ -35,6 +35,19 @@ interface IConfigrProps<T> {
35
35
  overrideValue?: T;
36
36
  overrideDescription?: string;
37
37
  pageKey?: string;
38
+ /**
39
+ * This row says what its group is about, e.g. which language a group of language settings is
40
+ * for. Wherever config-r shows the group's settings without this row (search results, and the
41
+ * group's sub-pages), it adds this row's text to the group's heading. Searching also matches
42
+ * that text, finding the whole group.
43
+ */
44
+ identifiesGroup?: boolean;
45
+ /**
46
+ * The text of this row's value, for identifiesGroup. Needed for a custom control, whose value
47
+ * config-r cannot show as text by itself. (Method syntax, so that a row with a narrower value
48
+ * type can declare it.)
49
+ */
50
+ valueText?(value: T): string | undefined;
38
51
  }
39
52
  export declare const ConfigrInput: React.FunctionComponent<React.PropsWithChildren<IConfigrProps<string | number> & {
40
53
  className?: string;
@@ -71,6 +84,7 @@ interface ICustomNumberInputProps extends IConfigrProps<number> {
71
84
  }
72
85
  export declare const ConfigrCustomNumberInput: React.FunctionComponent<React.PropsWithChildren<ICustomNumberInputProps>>;
73
86
  interface ICustomObjectInputProps<T> extends IConfigrProps<unknown> {
87
+ valueText?(value: T): string | undefined;
74
88
  control: React.FunctionComponent<React.PropsWithChildren<{
75
89
  value: T;
76
90
  disabled?: boolean;
@@ -99,6 +113,8 @@ export declare const ConfigrGroup: React.FunctionComponent<React.PropsWithChildr
99
113
  getErrorMessage?: ConfigrErrorMessageGetter;
100
114
  inFocussedPage?: boolean;
101
115
  headerAction?: React.ReactNode;
116
+ parentPageLabel?: string;
117
+ ancestorGroupLabel?: string;
102
118
  }>>;
103
119
  export type PageChild = React.ReactElement<typeof ConfigrGroup> | false | undefined | null;
104
120
  export declare const ConfigrPage: React.FunctionComponent<React.PropsWithChildren<{
@@ -110,6 +126,7 @@ export declare const ConfigrPage: React.FunctionComponent<React.PropsWithChildre
110
126
  getErrorMessage?: ConfigrErrorMessageGetter;
111
127
  inFocussedPage?: boolean;
112
128
  disabled?: boolean;
129
+ ancestorGroupLabel?: string;
113
130
  children: PageChild | PageChild[];
114
131
  }>>;
115
132
  export declare const ConfigrForEach: React.FunctionComponent<React.PropsWithChildren<{