@sillsdev/config-r 1.0.0-alpha.2 → 1.0.0-alpha.21

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,32 @@ 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
22
  yarn install
19
23
  yarn dev
20
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
+ - Custom inputs use `ConfigrCustomStringInput`, `ConfigrCustomNumberInput`, or `ConfigrCustomObjectInput` with a `control` component that receives `value`, `onChange`, and `disabled`.
43
+ - `ConfigrPane` adds UI props like `showAppBar`, `showSearch`, `showJson`, `themeOverrides`, and `initiallySelectedTopLevelPageIndex`.
@@ -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
  }>;
@@ -1,15 +1,16 @@
1
1
  import { ThemeOptions } from '@mui/material';
2
+ import { ConfigrArea, ConfigrPage, ConfigrValues } from './ContentPane';
2
3
  import * as React from 'react';
3
- import { ConfigrGroup } from './ContentPane';
4
4
  export declare const ConfigrPane: React.FunctionComponent<React.PropsWithChildren<{
5
5
  label: string;
6
- initialValues: object;
7
- children: React.ReactElement<typeof ConfigrGroup> | React.ReactElement<typeof ConfigrGroup>[];
8
- setValueOnRender?: (currentValues: any) => void;
6
+ initialValues: ConfigrValues;
7
+ 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>>>;
8
+ /** Called with the latest values as a plain object (not a JSON string). */
9
+ onChange?: (currentValues: ConfigrValues) => void;
9
10
  showAppBar?: boolean;
10
11
  showSearch?: boolean;
11
- showAllGroups?: boolean;
12
12
  themeOverrides?: ThemeOptions;
13
13
  showJson?: boolean;
14
14
  className?: string;
15
+ initiallySelectedTopLevelPageIndex?: number;
15
16
  }>>;
@@ -1,67 +1,75 @@
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 * as React from 'react';
4
+ export type ConfigrValues = Record<string, unknown>;
5
+ type valueGetter = () => ConfigrValues;
6
+ export declare const ConfigrArea: React.FunctionComponent<React.PropsWithChildren<{
7
+ label: string;
8
+ pageKey?: string;
9
+ disabled?: boolean;
10
+ content?: React.ReactNode;
11
+ }>>;
5
12
  export declare const ContentPane: React.FunctionComponent<React.PropsWithChildren<{
6
- initialValues: object;
7
- currentGroupIndex?: number;
8
- children: React.ReactElement<typeof ConfigrGroup> | React.ReactElement<typeof ConfigrGroup>[];
13
+ initialValues: ConfigrValues;
14
+ currentTopLevelPageIndex?: number;
15
+ children: React.ReactElement<React.ComponentProps<typeof ConfigrPage>> | React.ReactElement<React.ComponentProps<typeof ConfigrPage>>[];
9
16
  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;
17
+ /** Called with the latest values as a plain object (not a JSON string). */
18
+ onChange?: (currentValues: ConfigrValues) => void;
16
19
  }>>;
17
20
  type BooleanEditorComponent = React.FunctionComponent<{
18
21
  value: boolean;
22
+ disabled?: boolean;
19
23
  onChange: (value: boolean) => void;
20
24
  }>;
21
- export declare const ConfigrInput: React.FunctionComponent<React.PropsWithChildren<{
25
+ interface IConfigrProps<T> {
22
26
  path: string;
23
27
  label: string;
28
+ description?: string;
29
+ disabled?: boolean;
30
+ overrideValue?: T;
31
+ overrideDescription?: string;
32
+ pageKey?: string;
33
+ }
34
+ export declare const ConfigrInput: React.FunctionComponent<React.PropsWithChildren<IConfigrProps<string | number> & {
24
35
  className?: string;
25
36
  type?: 'text' | 'number' | 'email';
26
37
  units?: string;
27
38
  getErrorMessage?: (data: any) => string | undefined;
28
39
  }>>;
29
- export declare const ConfigrCustomStringInput: React.FunctionComponent<React.PropsWithChildren<{
30
- path: string;
31
- label: string;
40
+ interface ICustomStringInputProps extends IConfigrProps<string> {
32
41
  control: React.FunctionComponent<{
33
42
  value: string;
43
+ disabled?: boolean;
34
44
  onChange: (value: string) => void;
35
45
  }>;
36
46
  getErrorMessage?: (data: any) => string | undefined;
37
- }>>;
38
- export declare const ConfigrCustomBooleanInput: React.FunctionComponent<React.PropsWithChildren<{
39
- path: string;
40
- label: string;
47
+ }
48
+ export declare const ConfigrCustomStringInput: React.FunctionComponent<React.PropsWithChildren<ICustomStringInputProps>>;
49
+ interface ICustomBooleanInputProps extends IConfigrProps<boolean> {
41
50
  control: BooleanEditorComponent;
42
51
  getErrorMessage?: (data: any) => string | undefined;
43
- }>>;
44
- export declare const ConfigrCustomNumberInput: React.FunctionComponent<React.PropsWithChildren<{
45
- path: string;
46
- label: string;
52
+ }
53
+ export declare const ConfigrCustomBooleanInput: React.FunctionComponent<React.PropsWithChildren<ICustomBooleanInputProps>>;
54
+ interface ICustomNumberInputProps extends IConfigrProps<number> {
47
55
  control: React.FunctionComponent<React.PropsWithChildren<{
48
56
  value: number;
57
+ disabled?: boolean;
49
58
  onChange: (value: number) => void;
50
59
  }>>;
51
60
  getErrorMessage?: (data: any) => string | undefined;
52
- }>>;
53
- export declare const ConfigrCustomObjectInput: React.FunctionComponent<React.PropsWithChildren<{
54
- path: string;
55
- label: string;
61
+ }
62
+ export declare const ConfigrCustomNumberInput: React.FunctionComponent<React.PropsWithChildren<ICustomNumberInputProps>>;
63
+ interface ICustomObjectInputProps<T> extends IConfigrProps<unknown> {
56
64
  control: React.FunctionComponent<React.PropsWithChildren<{
57
- value: object;
58
- onChange: (value: object) => void;
65
+ value: T;
66
+ disabled?: boolean;
67
+ onChange: (value: T) => void;
59
68
  }>>;
60
69
  getErrorMessage?: (data: any) => string | undefined;
61
- }>>;
62
- export declare const ConfigrSelect: React.FunctionComponent<React.PropsWithChildren<{
63
- path: string;
64
- label: string;
70
+ }
71
+ export declare function ConfigrCustomObjectInput<T>(props: React.PropsWithChildren<ICustomObjectInputProps<T>>): import("@emotion/react/jsx-runtime").JSX.Element;
72
+ interface ISelectProps extends IConfigrProps<string> {
65
73
  indented?: boolean;
66
74
  options: Array<{
67
75
  value: string;
@@ -69,67 +77,57 @@ export declare const ConfigrSelect: React.FunctionComponent<React.PropsWithChild
69
77
  description?: string;
70
78
  } | number>;
71
79
  enableWhen?: string | ((currentValues: object) => boolean);
72
- description?: string;
73
80
  getErrorMessage?: (data: any) => string | undefined;
74
- }>>;
75
- export declare const ConfigrSubgroup: React.FunctionComponent<React.PropsWithChildren<{
76
- label: string;
77
- path: string;
81
+ }
82
+ export declare const ConfigrSelect: React.FunctionComponent<React.PropsWithChildren<ISelectProps>>;
83
+ export declare const ConfigrStatic: React.FunctionComponent<React.PropsWithChildren<{}>>;
84
+ export declare const ConfigrGroup: React.FunctionComponent<React.PropsWithChildren<{
85
+ label?: string;
86
+ searchTerms?: string;
78
87
  description?: string | React.ReactNode;
79
88
  getErrorMessage?: (data: any) => string | undefined;
89
+ inFocussedPage?: boolean;
80
90
  }>>;
81
- export declare const ConfigrSubPage: React.FunctionComponent<React.PropsWithChildren<{
91
+ export type PageChild = React.ReactElement<typeof ConfigrGroup> | false | undefined | null;
92
+ export declare const ConfigrPage: React.FunctionComponent<React.PropsWithChildren<{
82
93
  label: string;
83
94
  labelCss?: SerializedStyles;
84
- path: string;
95
+ pageKey: string;
96
+ searchTerms?: string;
97
+ topLevel?: boolean;
85
98
  getErrorMessage?: (data: any) => string | undefined;
99
+ inFocussedPage?: boolean;
100
+ disabled?: boolean;
101
+ children: PageChild | PageChild[];
86
102
  }>>;
87
103
  export declare const ConfigrForEach: React.FunctionComponent<React.PropsWithChildren<{
88
104
  path: string;
89
105
  searchTerms: string;
106
+ inFocussedPage?: boolean;
90
107
  render: (pathPrefix: string, index: number) => React.ReactNode;
91
108
  getErrorMessage?: (data: any) => string | undefined;
92
109
  }>>;
93
- export declare const ConfigrBoolean: React.FunctionComponent<React.PropsWithChildren<{
94
- path: string;
95
- label: string;
96
- description?: string;
110
+ export declare const ConfigrBoolean: React.FunctionComponent<React.PropsWithChildren<IConfigrProps<boolean> & {
97
111
  immediateEffect?: boolean;
112
+ locked?: boolean;
98
113
  }>>;
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;
114
+ interface IRadioGroupProps extends IConfigrProps<string> {
107
115
  row?: boolean;
108
- }>>;
116
+ }
117
+ export declare const ConfigrRadioGroup: React.FunctionComponent<React.PropsWithChildren<IRadioGroupProps>>;
109
118
  export declare const ConfigrRadio: React.FunctionComponent<React.PropsWithChildren<{
110
119
  value: any;
111
120
  label?: string;
112
121
  }>>;
113
- export declare const ConfigrToggleGroup: React.FunctionComponent<React.PropsWithChildren<{
114
- path: string;
115
- label: string;
116
- row?: boolean;
117
- height?: string;
118
- }>>;
119
- export declare const ConfigrToggleGroupRaw: React.FunctionComponent<React.PropsWithChildren<{
120
- path: string;
121
- label: string;
122
+ interface IToggleGroupProps extends IConfigrProps<string> {
122
123
  row?: boolean;
123
124
  height?: string;
124
- }>>;
125
+ }
126
+ export declare const ConfigrToggleGroup: React.FunctionComponent<React.PropsWithChildren<IToggleGroupProps>>;
125
127
  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;
128
+ export declare const ConfigrChooserButton: React.FunctionComponent<React.PropsWithChildren<IConfigrProps<string> & {
130
129
  buttonLabel: string;
131
130
  chooseAction: (currentValue: string) => string;
132
- disabled?: boolean;
133
131
  }>>;
134
132
  export declare const ConfigrConditional: React.FunctionComponent<React.PropsWithChildren<{
135
133
  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
  }>>;