@sillsdev/config-r 1.0.0-alpha.3 → 1.0.0-alpha.31
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 +71 -5
- package/dist/ConfigrColorPicker.d.ts +2 -0
- package/dist/ConfigrLocalizations.d.ts +10 -0
- package/dist/ConfigrPane.d.ts +27 -7
- package/dist/ContentPane.d.ts +82 -75
- package/dist/FilterForSearch.d.ts +1 -1
- package/dist/HighlightSearchTerms.d.ts +1 -1
- package/dist/configr.cjs.js +471 -0
- package/dist/configr.cjs.js.map +1 -0
- package/dist/configr.es.js +24939 -7132
- package/dist/configr.es.js.map +1 -0
- package/dist/index.d.ts +3 -0
- package/dist/validation.d.ts +21 -0
- package/package.json +82 -64
- package/dist/configr.umd.js +0 -231
package/README.md
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|

|
|
2
2
|
|
|
3
|
-
A
|
|
3
|
+
A React library for a settings UI similar to that of Chrome.
|
|
4
4
|
|
|
5
|
-
[](https://www.repostatus.org/#wip)
|
|
6
6
|
|
|
7
|
-
> :warning:
|
|
7
|
+
> :warning: We ship this as part of our [product](https://github.com/BloomBooks/BloomDesktop), but search has not made it to production yet. In addition, we may make visual changes over time. For now, the only documentation is the code and the storybook stories.
|
|
8
8
|
|
|
9
9
|
## Screenshots
|
|
10
10
|
|
|
@@ -12,9 +12,75 @@ A react library for a settings UI similar to that of Chrome. Uses formik.
|
|
|
12
12
|
|
|
13
13
|

|
|
14
14
|
|
|
15
|
+
## Demo
|
|
16
|
+
|
|
17
|
+
You can play around with [the disorganized stories](https://sillsdev.github.io/config-r).
|
|
18
|
+
|
|
15
19
|
## Running
|
|
16
20
|
|
|
17
21
|
```
|
|
18
|
-
|
|
19
|
-
|
|
22
|
+
pnpm install
|
|
23
|
+
pnpm dev
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## Installing
|
|
27
|
+
|
|
28
|
+
```
|
|
29
|
+
npm install @sillsdev/config-r
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## Migration from v1.0.0-alpha.15 to v1.0.0-alpha18
|
|
33
|
+
|
|
34
|
+
Use [src/stories/bloom.stories.tsx](src/stories/bloom.stories.tsx) as the canonical reference for alpha18 API usage. The current codebase enforces several structural rules and new props; the fastest path is to align your code with those patterns.
|
|
35
|
+
|
|
36
|
+
- `ConfigrPane` children must be `ConfigrPage` or `ConfigrArea` elements only. Wrap groups of pages in `ConfigrArea` to get the left-nav section headings.
|
|
37
|
+
- `ConfigrPage` now requires `pageKey` and throws if it is missing. Keep these keys stable and unique within a pane.
|
|
38
|
+
- `ConfigrPage` children are restricted to `ConfigrGroup`, `ConfigrForEach`, or `ConfigrStatic`. Move any custom layout into `ConfigrGroup` or wrap text/UI-only blocks in `ConfigrStatic`.
|
|
39
|
+
- `ConfigrForEach` now uses a render signature of `(pathPrefix, index) => ReactNode`; build full Formik paths from the prefix (see the languages loop in the story).
|
|
40
|
+
- `ConfigrSelect` options accept numbers or `{ label, value, description }` objects; descriptions become tooltips.
|
|
41
|
+
- Override/locking behavior is standardized: most controls accept `overrideValue` + `overrideDescription`; `ConfigrBoolean` adds `locked` and `immediateEffect`.
|
|
42
|
+
- Leaf controls support `required` and `validation`. `validation` receives the current field value and may return `true`, `false`, or a string. `false` renders a generic `Invalid value` message, while a string is shown inline in red.
|
|
43
|
+
- Required fields show a `*` beside the control. The fallback `Required` message for empty required fields is controlled at the pane level with `showRequiredMessage` and defaults to `true`.
|
|
44
|
+
- `ConfigrInput` covers standard text, number, and email fields. It also supports `charactersWide`, `allowNewLines`, `minLinesToShow`, and `maxLinesToShowBeforeScrolling` for compact multiline text entry.
|
|
45
|
+
- `ConfigrPane` adds UI props like `showAppBar`, `showSearch`, `showJson`, `themeOverrides`, `initiallySelectedTopLevelPageKey`, and `localizations`.
|
|
46
|
+
|
|
47
|
+
## Localization
|
|
48
|
+
|
|
49
|
+
To provide languages other than English for the small set of built-in strings, pass `localizations` to `ConfigrPane`:
|
|
50
|
+
|
|
51
|
+
```tsx
|
|
52
|
+
<ConfigrPane
|
|
53
|
+
label="Configuracion"
|
|
54
|
+
initialValues={initialValues}
|
|
55
|
+
showSearch={true}
|
|
56
|
+
localizations={{
|
|
57
|
+
fieldRequiredMessage: 'Requiere un valor',
|
|
58
|
+
invalidValueMessage: 'Valor no valido',
|
|
59
|
+
searchLabel: 'Buscar',
|
|
60
|
+
matchesLabel: (count) => `${count} coincidencias`,
|
|
61
|
+
}}
|
|
62
|
+
>
|
|
63
|
+
{/* pages */}
|
|
64
|
+
</ConfigrPane>
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
`searchLabel` is used for both the visible search placeholder and the input accessibility label.
|
|
68
|
+
|
|
69
|
+
## Knowing and choosing the page
|
|
70
|
+
|
|
71
|
+
`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:
|
|
72
|
+
|
|
73
|
+
```tsx
|
|
74
|
+
const paneRef = React.useRef<ConfigrPaneHandle>(null);
|
|
75
|
+
|
|
76
|
+
<ConfigrPane
|
|
77
|
+
ref={paneRef}
|
|
78
|
+
label="Settings"
|
|
79
|
+
initialValues={initialValues}
|
|
80
|
+
onTopLevelPageChange={(pageKey) => setShownPage(pageKey)}
|
|
81
|
+
>
|
|
82
|
+
{/* pages */}
|
|
83
|
+
</ConfigrPane>;
|
|
84
|
+
|
|
85
|
+
paneRef.current?.selectTopLevelPage('subscription');
|
|
20
86
|
```
|
|
@@ -1,9 +1,11 @@
|
|
|
1
1
|
import * as React from 'react';
|
|
2
2
|
export declare const ConfigrColorPicker: React.FunctionComponent<{
|
|
3
3
|
value: string;
|
|
4
|
+
disabled?: boolean;
|
|
4
5
|
onChange: (value: string) => void;
|
|
5
6
|
}>;
|
|
6
7
|
export declare const SwatchButton: React.FunctionComponent<{
|
|
7
8
|
color: string;
|
|
9
|
+
disabled?: boolean;
|
|
8
10
|
onClick: () => void;
|
|
9
11
|
}>;
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import * as React from 'react';
|
|
2
|
+
export type ConfigrLocalizations = {
|
|
3
|
+
fieldRequiredMessage: string;
|
|
4
|
+
invalidValueMessage: string;
|
|
5
|
+
searchLabel: string;
|
|
6
|
+
matchesLabel: (count: number) => string;
|
|
7
|
+
};
|
|
8
|
+
export type ConfigrLocalizationOverrides = Partial<ConfigrLocalizations>;
|
|
9
|
+
export declare const defaultConfigrLocalizations: ConfigrLocalizations;
|
|
10
|
+
export declare const ConfigrLocalizationContext: React.Context<ConfigrLocalizations>;
|
package/dist/ConfigrPane.d.ts
CHANGED
|
@@ -1,15 +1,35 @@
|
|
|
1
1
|
import { ThemeOptions } from '@mui/material';
|
|
2
|
+
import { ConfigrLocalizationOverrides } from './ConfigrLocalizations';
|
|
3
|
+
import { ConfigrArea, ConfigrPage, ConfigrValues } from './ContentPane';
|
|
2
4
|
import * as React from 'react';
|
|
3
|
-
|
|
4
|
-
export
|
|
5
|
+
/** What a ref on a ConfigrPane can do. */
|
|
6
|
+
export interface ConfigrPaneHandle {
|
|
7
|
+
/**
|
|
8
|
+
* Shows the top-level page with this key, keeping the values being edited. A key that
|
|
9
|
+
* names no page, or a disabled one, is ignored.
|
|
10
|
+
*/
|
|
11
|
+
selectTopLevelPage: (pageKey: string) => void;
|
|
12
|
+
}
|
|
13
|
+
export declare const ConfigrPane: React.ForwardRefExoticComponent<{
|
|
5
14
|
label: string;
|
|
6
|
-
initialValues:
|
|
7
|
-
children: React.ReactElement<typeof
|
|
8
|
-
|
|
15
|
+
initialValues: ConfigrValues;
|
|
16
|
+
children: React.ReactElement<React.ComponentProps<typeof ConfigrPage>> | React.ReactElement<React.ComponentProps<typeof ConfigrArea>> | Array<React.ReactElement<React.ComponentProps<typeof ConfigrPage>> | React.ReactElement<React.ComponentProps<typeof ConfigrArea>>>;
|
|
17
|
+
/** Called with the latest values as a plain object (not a JSON string). */
|
|
18
|
+
onChange?: (currentValues: ConfigrValues) => void;
|
|
9
19
|
showAppBar?: boolean;
|
|
10
20
|
showSearch?: boolean;
|
|
11
|
-
showAllGroups?: boolean;
|
|
12
21
|
themeOverrides?: ThemeOptions;
|
|
13
22
|
showJson?: boolean;
|
|
23
|
+
showRequiredMessage?: boolean;
|
|
24
|
+
localizations?: ConfigrLocalizationOverrides;
|
|
14
25
|
className?: string;
|
|
15
|
-
|
|
26
|
+
initiallySelectedTopLevelPageKey?: string;
|
|
27
|
+
/**
|
|
28
|
+
* Called with the pageKey of the top-level page now showing: once when the pane mounts,
|
|
29
|
+
* and again each time the page changes, by the user or by selectTopLevelPage. It gets
|
|
30
|
+
* undefined while no top-level page is showing (an area's own content, or a search).
|
|
31
|
+
*/
|
|
32
|
+
onTopLevelPageChange?: (pageKey: string | undefined) => void;
|
|
33
|
+
} & {
|
|
34
|
+
children?: React.ReactNode | undefined;
|
|
35
|
+
} & React.RefAttributes<ConfigrPaneHandle>>;
|
package/dist/ContentPane.d.ts
CHANGED
|
@@ -1,67 +1,84 @@
|
|
|
1
1
|
import { SerializedStyles } from '@emotion/react';
|
|
2
|
-
import * as React from 'react';
|
|
3
2
|
import { ReactNode } from 'react';
|
|
4
|
-
|
|
3
|
+
import { ConfigrErrorMessageGetter, ConfigrValidation } from './validation';
|
|
4
|
+
import * as React from 'react';
|
|
5
|
+
export type ConfigrValues = Record<string, unknown>;
|
|
6
|
+
type valueGetter = () => ConfigrValues;
|
|
7
|
+
export declare const ConfigrArea: React.FunctionComponent<React.PropsWithChildren<{
|
|
8
|
+
label: string;
|
|
9
|
+
pageKey?: string;
|
|
10
|
+
disabled?: boolean;
|
|
11
|
+
content?: React.ReactNode;
|
|
12
|
+
}>>;
|
|
5
13
|
export declare const ContentPane: React.FunctionComponent<React.PropsWithChildren<{
|
|
6
|
-
initialValues:
|
|
7
|
-
|
|
8
|
-
|
|
14
|
+
initialValues: ConfigrValues;
|
|
15
|
+
currentTopLevelPageIndex?: number;
|
|
16
|
+
showRequiredMessage?: boolean;
|
|
17
|
+
children: React.ReactElement<React.ComponentProps<typeof ConfigrPage>> | React.ReactElement<React.ComponentProps<typeof ConfigrPage>>[];
|
|
9
18
|
setValueGetter?: (vg: valueGetter) => void;
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
export declare const ConfigrGroup: React.FunctionComponent<React.PropsWithChildren<{
|
|
13
|
-
label: string;
|
|
14
|
-
description?: string | React.ReactNode;
|
|
15
|
-
level?: undefined | 1 | 2;
|
|
19
|
+
/** Called with the latest values as a plain object (not a JSON string). */
|
|
20
|
+
onChange?: (currentValues: ConfigrValues) => void;
|
|
16
21
|
}>>;
|
|
17
22
|
type BooleanEditorComponent = React.FunctionComponent<{
|
|
18
23
|
value: boolean;
|
|
24
|
+
disabled?: boolean;
|
|
19
25
|
onChange: (value: boolean) => void;
|
|
20
26
|
}>;
|
|
21
|
-
|
|
27
|
+
interface IConfigrProps<T> {
|
|
22
28
|
path: string;
|
|
23
29
|
label: string;
|
|
30
|
+
description?: string;
|
|
31
|
+
disabled?: boolean;
|
|
32
|
+
required?: boolean;
|
|
33
|
+
validation?: ConfigrValidation<T>;
|
|
34
|
+
getErrorMessage?: ConfigrErrorMessageGetter;
|
|
35
|
+
overrideValue?: T;
|
|
36
|
+
overrideDescription?: string;
|
|
37
|
+
pageKey?: string;
|
|
38
|
+
}
|
|
39
|
+
export declare const ConfigrInput: React.FunctionComponent<React.PropsWithChildren<IConfigrProps<string | number> & {
|
|
24
40
|
className?: string;
|
|
25
41
|
type?: 'text' | 'number' | 'email';
|
|
26
42
|
units?: string;
|
|
27
|
-
|
|
43
|
+
charactersWide?: number;
|
|
44
|
+
allowNewLines?: boolean;
|
|
45
|
+
minLinesToShow?: number;
|
|
46
|
+
maxLinesToShowBeforeScrolling?: number;
|
|
47
|
+
getErrorMessage?: ConfigrErrorMessageGetter;
|
|
28
48
|
}>>;
|
|
29
|
-
|
|
30
|
-
path: string;
|
|
31
|
-
label: string;
|
|
49
|
+
interface ICustomStringInputProps extends IConfigrProps<string> {
|
|
32
50
|
control: React.FunctionComponent<{
|
|
33
51
|
value: string;
|
|
52
|
+
disabled?: boolean;
|
|
34
53
|
onChange: (value: string) => void;
|
|
35
54
|
}>;
|
|
36
|
-
getErrorMessage?:
|
|
37
|
-
}
|
|
38
|
-
export declare const
|
|
39
|
-
|
|
40
|
-
label: string;
|
|
55
|
+
getErrorMessage?: ConfigrErrorMessageGetter;
|
|
56
|
+
}
|
|
57
|
+
export declare const ConfigrCustomStringInput: React.FunctionComponent<React.PropsWithChildren<ICustomStringInputProps>>;
|
|
58
|
+
interface ICustomBooleanInputProps extends IConfigrProps<boolean> {
|
|
41
59
|
control: BooleanEditorComponent;
|
|
42
|
-
getErrorMessage?:
|
|
43
|
-
}
|
|
44
|
-
export declare const
|
|
45
|
-
|
|
46
|
-
label: string;
|
|
60
|
+
getErrorMessage?: ConfigrErrorMessageGetter;
|
|
61
|
+
}
|
|
62
|
+
export declare const ConfigrCustomBooleanInput: React.FunctionComponent<React.PropsWithChildren<ICustomBooleanInputProps>>;
|
|
63
|
+
interface ICustomNumberInputProps extends IConfigrProps<number> {
|
|
47
64
|
control: React.FunctionComponent<React.PropsWithChildren<{
|
|
48
65
|
value: number;
|
|
66
|
+
disabled?: boolean;
|
|
49
67
|
onChange: (value: number) => void;
|
|
50
68
|
}>>;
|
|
51
|
-
getErrorMessage?:
|
|
52
|
-
}
|
|
53
|
-
export declare
|
|
54
|
-
|
|
55
|
-
label: string;
|
|
69
|
+
getErrorMessage?: ConfigrErrorMessageGetter;
|
|
70
|
+
}
|
|
71
|
+
export declare const ConfigrCustomNumberInput: React.FunctionComponent<React.PropsWithChildren<ICustomNumberInputProps>>;
|
|
72
|
+
interface ICustomObjectInputProps<T> extends IConfigrProps<unknown> {
|
|
56
73
|
control: React.FunctionComponent<React.PropsWithChildren<{
|
|
57
74
|
value: T;
|
|
75
|
+
disabled?: boolean;
|
|
58
76
|
onChange: (value: T) => void;
|
|
59
77
|
}>>;
|
|
60
|
-
getErrorMessage?:
|
|
61
|
-
}
|
|
62
|
-
export declare
|
|
63
|
-
|
|
64
|
-
label: string;
|
|
78
|
+
getErrorMessage?: ConfigrErrorMessageGetter;
|
|
79
|
+
}
|
|
80
|
+
export declare function ConfigrCustomObjectInput<T>(props: React.PropsWithChildren<ICustomObjectInputProps<T>>): import("@emotion/react/jsx-runtime").JSX.Element;
|
|
81
|
+
interface ISelectProps extends IConfigrProps<string> {
|
|
65
82
|
indented?: boolean;
|
|
66
83
|
options: Array<{
|
|
67
84
|
value: string;
|
|
@@ -69,67 +86,57 @@ export declare const ConfigrSelect: React.FunctionComponent<React.PropsWithChild
|
|
|
69
86
|
description?: string;
|
|
70
87
|
} | number>;
|
|
71
88
|
enableWhen?: string | ((currentValues: object) => boolean);
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
export declare const
|
|
76
|
-
|
|
77
|
-
|
|
89
|
+
getErrorMessage?: ConfigrErrorMessageGetter;
|
|
90
|
+
}
|
|
91
|
+
export declare const ConfigrSelect: React.FunctionComponent<React.PropsWithChildren<ISelectProps>>;
|
|
92
|
+
export declare const ConfigrStatic: React.FunctionComponent<React.PropsWithChildren<{}>>;
|
|
93
|
+
export declare const ConfigrGroup: React.FunctionComponent<React.PropsWithChildren<{
|
|
94
|
+
label?: string;
|
|
95
|
+
searchTerms?: string;
|
|
78
96
|
description?: string | React.ReactNode;
|
|
79
|
-
getErrorMessage?:
|
|
97
|
+
getErrorMessage?: ConfigrErrorMessageGetter;
|
|
98
|
+
inFocussedPage?: boolean;
|
|
80
99
|
}>>;
|
|
81
|
-
export
|
|
100
|
+
export type PageChild = React.ReactElement<typeof ConfigrGroup> | false | undefined | null;
|
|
101
|
+
export declare const ConfigrPage: React.FunctionComponent<React.PropsWithChildren<{
|
|
82
102
|
label: string;
|
|
83
103
|
labelCss?: SerializedStyles;
|
|
84
|
-
|
|
85
|
-
|
|
104
|
+
pageKey: string;
|
|
105
|
+
searchTerms?: string;
|
|
106
|
+
topLevel?: boolean;
|
|
107
|
+
getErrorMessage?: ConfigrErrorMessageGetter;
|
|
108
|
+
inFocussedPage?: boolean;
|
|
109
|
+
disabled?: boolean;
|
|
110
|
+
children: PageChild | PageChild[];
|
|
86
111
|
}>>;
|
|
87
112
|
export declare const ConfigrForEach: React.FunctionComponent<React.PropsWithChildren<{
|
|
88
113
|
path: string;
|
|
89
114
|
searchTerms: string;
|
|
115
|
+
inFocussedPage?: boolean;
|
|
90
116
|
render: (pathPrefix: string, index: number) => React.ReactNode;
|
|
91
|
-
getErrorMessage?:
|
|
117
|
+
getErrorMessage?: ConfigrErrorMessageGetter;
|
|
92
118
|
}>>;
|
|
93
|
-
export declare const ConfigrBoolean: React.FunctionComponent<React.PropsWithChildren<{
|
|
94
|
-
path: string;
|
|
95
|
-
label: string;
|
|
96
|
-
description?: string;
|
|
119
|
+
export declare const ConfigrBoolean: React.FunctionComponent<React.PropsWithChildren<IConfigrProps<boolean> & {
|
|
97
120
|
immediateEffect?: boolean;
|
|
121
|
+
locked?: boolean;
|
|
98
122
|
}>>;
|
|
99
|
-
|
|
100
|
-
path: string;
|
|
101
|
-
label: string;
|
|
102
|
-
row?: boolean;
|
|
103
|
-
}>>;
|
|
104
|
-
export declare const ConfigrRadioGroupRaw: React.FunctionComponent<React.PropsWithChildren<{
|
|
105
|
-
path: string;
|
|
106
|
-
label: string;
|
|
123
|
+
interface IRadioGroupProps extends IConfigrProps<string> {
|
|
107
124
|
row?: boolean;
|
|
108
|
-
}
|
|
125
|
+
}
|
|
126
|
+
export declare const ConfigrRadioGroup: React.FunctionComponent<React.PropsWithChildren<IRadioGroupProps>>;
|
|
109
127
|
export declare const ConfigrRadio: React.FunctionComponent<React.PropsWithChildren<{
|
|
110
128
|
value: any;
|
|
111
129
|
label?: string;
|
|
112
130
|
}>>;
|
|
113
|
-
|
|
114
|
-
path: string;
|
|
115
|
-
label: string;
|
|
131
|
+
interface IToggleGroupProps extends IConfigrProps<string> {
|
|
116
132
|
row?: boolean;
|
|
117
133
|
height?: string;
|
|
118
|
-
}
|
|
119
|
-
export declare const
|
|
120
|
-
path: string;
|
|
121
|
-
label: string;
|
|
122
|
-
row?: boolean;
|
|
123
|
-
height?: string;
|
|
124
|
-
}>>;
|
|
134
|
+
}
|
|
135
|
+
export declare const ConfigrToggleGroup: React.FunctionComponent<React.PropsWithChildren<IToggleGroupProps>>;
|
|
125
136
|
export declare function ConfigrMakeToggle(value: any, content: ReactNode): import("@emotion/react/jsx-runtime").JSX.Element;
|
|
126
|
-
export declare const ConfigrChooserButton: React.FunctionComponent<React.PropsWithChildren<{
|
|
127
|
-
path: string;
|
|
128
|
-
label: string;
|
|
129
|
-
description?: string;
|
|
137
|
+
export declare const ConfigrChooserButton: React.FunctionComponent<React.PropsWithChildren<IConfigrProps<string> & {
|
|
130
138
|
buttonLabel: string;
|
|
131
139
|
chooseAction: (currentValue: string) => string;
|
|
132
|
-
disabled?: boolean;
|
|
133
140
|
}>>;
|
|
134
141
|
export declare const ConfigrConditional: React.FunctionComponent<React.PropsWithChildren<{
|
|
135
142
|
enableWhen?: (currentValues: object) => boolean;
|