@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 CHANGED
@@ -1,10 +1,10 @@
1
1
  ![config-r](https://user-images.githubusercontent.com/8448/147490475-b4d6d3bd-85a5-4ccd-941e-7f6926cc8089.png)
2
2
 
3
- A react library for a settings UI similar to that of Chrome. Uses formik.
3
+ A React library for a settings UI similar to that of Chrome.
4
4
 
5
- [![Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip)
5
+ [![Project Status: WIP - Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip)
6
6
 
7
- > :warning: This is a side project that I work on once in a while, and isn't ready for use yet.
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
  ![image](https://user-images.githubusercontent.com/8448/147994050-d0087afc-db1f-4a88-9744-f93002535239.png)
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
- yarn install
19
- yarn dev
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>;
@@ -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
- import { ConfigrGroup } from './ContentPane';
4
- export declare const ConfigrPane: React.FunctionComponent<React.PropsWithChildren<{
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: object;
7
- children: React.ReactElement<typeof ConfigrGroup> | React.ReactElement<typeof ConfigrGroup>[];
8
- setValueOnRender?: (currentValues: any) => void;
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>>;
@@ -1,67 +1,84 @@
1
1
  import { SerializedStyles } from '@emotion/react';
2
- import * as React from 'react';
3
2
  import { ReactNode } from 'react';
4
- type valueGetter = () => Object;
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: object;
7
- currentGroupIndex?: number;
8
- children: React.ReactElement<typeof ConfigrGroup> | React.ReactElement<typeof ConfigrGroup>[];
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
- setValueOnRender?: (currentValues: any) => void;
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
- export declare const ConfigrInput: React.FunctionComponent<React.PropsWithChildren<{
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
- getErrorMessage?: (data: any) => string | undefined;
43
+ charactersWide?: number;
44
+ allowNewLines?: boolean;
45
+ minLinesToShow?: number;
46
+ maxLinesToShowBeforeScrolling?: number;
47
+ getErrorMessage?: ConfigrErrorMessageGetter;
28
48
  }>>;
29
- export declare const ConfigrCustomStringInput: React.FunctionComponent<React.PropsWithChildren<{
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?: (data: any) => string | undefined;
37
- }>>;
38
- export declare const ConfigrCustomBooleanInput: React.FunctionComponent<React.PropsWithChildren<{
39
- path: string;
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?: (data: any) => string | undefined;
43
- }>>;
44
- export declare const ConfigrCustomNumberInput: React.FunctionComponent<React.PropsWithChildren<{
45
- path: string;
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?: (data: any) => string | undefined;
52
- }>>;
53
- export declare function ConfigrCustomObjectInput<T>(props: React.PropsWithChildren<{
54
- path: string;
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?: (data: any) => string | undefined;
61
- }>): import("@emotion/react/jsx-runtime").JSX.Element;
62
- export declare const ConfigrSelect: React.FunctionComponent<React.PropsWithChildren<{
63
- path: string;
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
- description?: string;
73
- getErrorMessage?: (data: any) => string | undefined;
74
- }>>;
75
- export declare const ConfigrSubgroup: React.FunctionComponent<React.PropsWithChildren<{
76
- label: string;
77
- path: string;
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?: (data: any) => string | undefined;
97
+ getErrorMessage?: ConfigrErrorMessageGetter;
98
+ inFocussedPage?: boolean;
80
99
  }>>;
81
- export declare const ConfigrSubPage: React.FunctionComponent<React.PropsWithChildren<{
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
- path: string;
85
- getErrorMessage?: (data: any) => string | undefined;
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?: (data: any) => string | undefined;
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
- export declare const ConfigrRadioGroup: React.FunctionComponent<React.PropsWithChildren<{
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
- export declare const ConfigrToggleGroup: React.FunctionComponent<React.PropsWithChildren<{
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 ConfigrToggleGroupRaw: React.FunctionComponent<React.PropsWithChildren<{
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;
@@ -1,6 +1,6 @@
1
1
  import * as React from 'react';
2
2
  export declare const FilterForSearchText: React.FunctionComponent<React.PropsWithChildren<{
3
- label: string;
3
+ label?: string;
4
4
  description?: string | React.ReactNode;
5
5
  kids: React.ReactNode;
6
6
  }>>;
@@ -1,5 +1,5 @@
1
1
  import * as React from 'react';
2
2
  export declare const HighlightSearchTerms: React.FunctionComponent<React.PropsWithChildren<{
3
3
  searchString: string | null;
4
- focussedSubPagePath: any;
4
+ focussedPageKey: any;
5
5
  }>>;