@muraldevkit/ui-toolkit 4.81.0 → 4.83.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 (83) hide show
  1. package/dist/cjs/components/grid/MrlCol/MrlCol.js +61 -55
  2. package/dist/cjs/components/grid/MrlCol/MrlCol.js.map +1 -1
  3. package/dist/cjs/components/grid/MrlGrid/MrlGrid.js +8 -5
  4. package/dist/cjs/components/grid/MrlGrid/MrlGrid.js.map +1 -1
  5. package/dist/cjs/components/grid/MrlRow/MrlRow.js +10 -8
  6. package/dist/cjs/components/grid/MrlRow/MrlRow.js.map +1 -1
  7. package/dist/cjs/components/grid/constants.js +47 -9
  8. package/dist/cjs/components/grid/constants.js.map +1 -1
  9. package/dist/cjs/components/multi-filter/MrlMultiFilter/MrlMultiFilter.js +232 -0
  10. package/dist/cjs/components/multi-filter/MrlMultiFilter/MrlMultiFilter.js.map +1 -0
  11. package/dist/cjs/components/multi-filter/MrlMultiFilter/MrlMultiFilter.module.scss.js +8 -0
  12. package/dist/cjs/components/multi-filter/MrlMultiFilter/MrlMultiFilter.module.scss.js.map +1 -0
  13. package/dist/cjs/components/multi-filter/MrlMultiFilterContext/MrlMultiFilterContext.js +302 -0
  14. package/dist/cjs/components/multi-filter/MrlMultiFilterContext/MrlMultiFilterContext.js.map +1 -0
  15. package/dist/cjs/components/multi-filter/MrlMultiFilterField/MrlMultiFilterField.js +122 -0
  16. package/dist/cjs/components/multi-filter/MrlMultiFilterField/MrlMultiFilterField.js.map +1 -0
  17. package/dist/cjs/components/multi-filter/MrlMultiFilterField/MrlMultiFilterField.module.scss.js +8 -0
  18. package/dist/cjs/components/multi-filter/MrlMultiFilterField/MrlMultiFilterField.module.scss.js.map +1 -0
  19. package/dist/cjs/components/multi-filter/MrlMultiFilterTrigger/MrlMultiFilterTrigger.js +83 -0
  20. package/dist/cjs/components/multi-filter/MrlMultiFilterTrigger/MrlMultiFilterTrigger.js.map +1 -0
  21. package/dist/cjs/components/multi-filter/utils.js +30 -0
  22. package/dist/cjs/components/multi-filter/utils.js.map +1 -0
  23. package/dist/cjs/components/popover/MrlPopover/MrlPopover.js +16 -5
  24. package/dist/cjs/components/popover/MrlPopover/MrlPopover.js.map +1 -1
  25. package/dist/cjs/index.js +12 -0
  26. package/dist/cjs/index.js.map +1 -1
  27. package/dist/cjs/version.js +1 -1
  28. package/dist/cjs/version.js.map +1 -1
  29. package/dist/esm/components/grid/MrlCol/MrlCol.js +62 -56
  30. package/dist/esm/components/grid/MrlCol/MrlCol.js.map +1 -1
  31. package/dist/esm/components/grid/MrlGrid/MrlGrid.js +8 -5
  32. package/dist/esm/components/grid/MrlGrid/MrlGrid.js.map +1 -1
  33. package/dist/esm/components/grid/MrlRow/MrlRow.js +10 -8
  34. package/dist/esm/components/grid/MrlRow/MrlRow.js.map +1 -1
  35. package/dist/esm/components/grid/constants.js +46 -9
  36. package/dist/esm/components/grid/constants.js.map +1 -1
  37. package/dist/esm/components/multi-filter/MrlMultiFilter/MrlMultiFilter.js +207 -0
  38. package/dist/esm/components/multi-filter/MrlMultiFilter/MrlMultiFilter.js.map +1 -0
  39. package/dist/esm/components/multi-filter/MrlMultiFilter/MrlMultiFilter.module.scss.js +4 -0
  40. package/dist/esm/components/multi-filter/MrlMultiFilter/MrlMultiFilter.module.scss.js.map +1 -0
  41. package/dist/esm/components/multi-filter/MrlMultiFilterContext/MrlMultiFilterContext.js +276 -0
  42. package/dist/esm/components/multi-filter/MrlMultiFilterContext/MrlMultiFilterContext.js.map +1 -0
  43. package/dist/esm/components/multi-filter/MrlMultiFilterField/MrlMultiFilterField.js +97 -0
  44. package/dist/esm/components/multi-filter/MrlMultiFilterField/MrlMultiFilterField.js.map +1 -0
  45. package/dist/esm/components/multi-filter/MrlMultiFilterField/MrlMultiFilterField.module.scss.js +4 -0
  46. package/dist/esm/components/multi-filter/MrlMultiFilterField/MrlMultiFilterField.module.scss.js.map +1 -0
  47. package/dist/esm/components/multi-filter/MrlMultiFilterTrigger/MrlMultiFilterTrigger.js +58 -0
  48. package/dist/esm/components/multi-filter/MrlMultiFilterTrigger/MrlMultiFilterTrigger.js.map +1 -0
  49. package/dist/esm/components/multi-filter/utils.js +28 -0
  50. package/dist/esm/components/multi-filter/utils.js.map +1 -0
  51. package/dist/esm/components/popover/MrlPopover/MrlPopover.js +16 -5
  52. package/dist/esm/components/popover/MrlPopover/MrlPopover.js.map +1 -1
  53. package/dist/esm/index.js +4 -0
  54. package/dist/esm/index.js.map +1 -1
  55. package/dist/esm/version.js +1 -1
  56. package/dist/esm/version.js.map +1 -1
  57. package/dist/styles/MrlMultiFilter/module.scss +30 -0
  58. package/dist/styles/MrlMultiFilterField/module.scss +7 -0
  59. package/dist/styles/MrlSidebar/module.scss +2 -2
  60. package/dist/styles/grid/global.scss +97 -2
  61. package/dist/styles.css +3 -7
  62. package/dist/types/components/grid/MrlCol/MrlCol.d.ts +4 -6
  63. package/dist/types/components/grid/MrlCol/index.d.ts +1 -1
  64. package/dist/types/components/grid/MrlGrid/MrlGrid.d.ts +9 -4
  65. package/dist/types/components/grid/MrlGrid/index.d.ts +1 -1
  66. package/dist/types/components/grid/MrlRow/MrlRow.d.ts +7 -7
  67. package/dist/types/components/grid/MrlRow/index.d.ts +1 -1
  68. package/dist/types/components/grid/constants.d.ts +56 -13
  69. package/dist/types/components/grid/index.d.ts +1 -1
  70. package/dist/types/components/index.d.ts +1 -0
  71. package/dist/types/components/multi-filter/MrlMultiFilter/MrlMultiFilter.d.ts +166 -0
  72. package/dist/types/components/multi-filter/MrlMultiFilter/index.d.ts +1 -0
  73. package/dist/types/components/multi-filter/MrlMultiFilterContext/MrlMultiFilterContext.d.ts +141 -0
  74. package/dist/types/components/multi-filter/MrlMultiFilterContext/index.d.ts +1 -0
  75. package/dist/types/components/multi-filter/MrlMultiFilterField/MrlMultiFilterField.d.ts +121 -0
  76. package/dist/types/components/multi-filter/MrlMultiFilterField/index.d.ts +1 -0
  77. package/dist/types/components/multi-filter/MrlMultiFilterTrigger/MrlMultiFilterTrigger.d.ts +52 -0
  78. package/dist/types/components/multi-filter/MrlMultiFilterTrigger/index.d.ts +1 -0
  79. package/dist/types/components/multi-filter/index.d.ts +4 -0
  80. package/dist/types/components/multi-filter/utils.d.ts +8 -0
  81. package/dist/types/components/popover/MrlPopover/MrlPopover.d.ts +7 -1
  82. package/package.json +1 -1
  83. package/dist/styles/grid/variables.scss +0 -26
@@ -1 +1 @@
1
- export { MrlCol } from './MrlCol';
1
+ export * from './MrlCol';
@@ -1,9 +1,14 @@
1
- import { LayoutComponent } from '../../layout/constants';
2
- import '../grid.variables.scss';
1
+ import { GridBaseProps } from '../constants';
3
2
  import '../grid.global.scss';
3
+ export type MrlGridProps = GridBaseProps;
4
4
  /**
5
- * MrlGrid React component.
5
+ * MrlGrid React component. Primary container of a 12-column grid built from
6
+ * MrlRow and MrlCol.
7
+ *
8
+ * Breakpoints come from the foundation tokens: sm 600px, md 834px, lg 1024px,
9
+ * xl 1280px and xxl 1440px. The gutter defaults to `--mrl-spacing-07` and can
10
+ * be overridden by setting `--mrl-grid-gutter` on any ancestor.
6
11
  * @param props - component props
7
12
  * @returns a MrlGrid React component.
8
13
  */
9
- export declare function MrlGrid({ children, className, ...rest }: LayoutComponent): JSX.Element;
14
+ export declare function MrlGrid({ children, className, ...rest }: MrlGridProps): JSX.Element;
@@ -1 +1 @@
1
- export { MrlGrid } from './MrlGrid';
1
+ export * from './MrlGrid';
@@ -1,12 +1,13 @@
1
- import { LayoutComponent } from '../../layout/constants';
2
- import { AlignOptions, GutterSizes, JustifyOptions } from '../constants';
3
- interface MrlRow extends LayoutComponent {
1
+ import { AlignOptions, GridBaseProps, GutterSizes, JustifyOptions } from '../constants';
2
+ export interface MrlRowProps extends GridBaseProps {
4
3
  /**
5
4
  * Flex alignment of the children within the component.
6
5
  */
7
6
  align?: AlignOptions;
8
7
  /**
9
- * Gutter size for columns within the row
8
+ * Gutter size for columns within the row.
9
+ *
10
+ * @default 1
10
11
  */
11
12
  gutter?: GutterSizes;
12
13
  /**
@@ -15,9 +16,8 @@ interface MrlRow extends LayoutComponent {
15
16
  justify?: JustifyOptions;
16
17
  }
17
18
  /**
18
- * MrlRow React component.
19
+ * MrlRow React component. Creates a grid row.
19
20
  * @param props - component props
20
21
  * @returns a MrlRow React component.
21
22
  */
22
- export declare function MrlRow({ align, children, className, justify, ...rest }: MrlRow): JSX.Element;
23
- export {};
23
+ export declare function MrlRow({ align, children, className, gutter, justify, ...rest }: MrlRowProps): JSX.Element;
@@ -1 +1 @@
1
- export { MrlRow } from './MrlRow';
1
+ export * from './MrlRow';
@@ -1,25 +1,26 @@
1
+ import { DataQa } from '../../utils/dataQa';
1
2
  /**
2
3
  * Alignment & justification options for grid containers
3
4
  */
4
5
  export type AlignOptions = 'start' | 'center' | 'end';
5
6
  export type JustifyOptions = 'start' | 'center' | 'end' | 'between' | 'around';
6
7
  /**
7
- * Available grid sizes
8
+ * Number of columns a `col` can span. There is no `col-0` class — a column
9
+ * always occupies at least one of the twelve tracks.
8
10
  */
9
- export declare const GridSizes: string[];
11
+ export type ColSpan = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
10
12
  /**
11
- * Number of columns that will be span on the grid.
13
+ * Number of columns an `offset` can skip. `0` is meaningful here: it is how a
14
+ * larger breakpoint cancels an offset inherited from a smaller one.
12
15
  */
13
- export type NumCols = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
16
+ export type OffsetSpan = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11;
14
17
  /**
15
- * The type of classes that can be configured based on the bootstrap API.
16
- * Current supported:
17
- * - columns "col-<size>-<number>"
18
- * - offsets "offset-<size>-<number>""
18
+ * @deprecated Use `ColSpan` for spans or `OffsetSpan` for offsets. This union
19
+ * allowed `col={0}`, which never produced a class.
19
20
  */
20
- type GridClass = 'col' | 'offset';
21
+ export type NumCols = 0 | ColSpan;
21
22
  /**
22
- * Interface of available class selectors based on GridClass
23
+ * Interface of available class selectors per breakpoint.
23
24
  *
24
25
  * Example interface:
25
26
  * {
@@ -28,19 +29,23 @@ type GridClass = 'col' | 'offset';
28
29
  * }
29
30
  */
30
31
  type GridClassConfig = {
31
- [key in GridClass]?: NumCols;
32
+ col?: ColSpan;
33
+ offset?: OffsetSpan;
32
34
  };
33
35
  /**
34
36
  * Options to configure the number of columns to span on different screen sizes.
35
37
  */
36
- type ColumnConfig = NumCols | 'auto' | GridClassConfig | undefined;
38
+ type ColumnConfig = ColSpan | 'auto' | GridClassConfig | undefined;
37
39
  export interface GridColumns {
38
40
  /**
39
41
  * Columns that are the same from the smallest of devices to the largest.
40
42
  */
41
43
  col?: ColumnConfig;
42
44
  /**
43
- * @deprecated xs maps to col. Bootstrap grid removed xs in favor of col.
45
+ * @deprecated Alias of `col`, kept for backwards compatibility. It resolves
46
+ * to the same un-prefixed tier, so passing both `col` and `xs` emits two
47
+ * competing classes and the larger span wins on CSS source order rather
48
+ * than the one you wrote last. Pass only one.
44
49
  */
45
50
  xs?: ColumnConfig;
46
51
  /**
@@ -64,8 +69,46 @@ export interface GridColumns {
64
69
  */
65
70
  xxl?: ColumnConfig;
66
71
  }
72
+ /**
73
+ * Breakpoint keys in ascending order. Drives both class generation and the
74
+ * filtering that keeps grid props from reaching the DOM.
75
+ */
76
+ export declare const GRID_SIZE_KEYS: readonly ["col", "xs", "sm", "md", "lg", "xl", "xxl"];
67
77
  /**
68
78
  * Available gutter sizes for customizing the grid
69
79
  */
70
80
  export type GutterSizes = 0 | 1 | 2;
81
+ /**
82
+ * Gutter size to modifier class. `1` is the default declared on `.row`, so it
83
+ * needs no class.
84
+ */
85
+ export declare const GUTTER_CLASS: Record<GutterSizes, string | undefined>;
86
+ /**
87
+ * Roles a generic layout wrapper may safely carry.
88
+ *
89
+ * Composite widget roles (`grid`, `row`, `gridcell`, `listbox`, `tablist`, …)
90
+ * are deliberately excluded: they promise an APG keyboard contract — roving
91
+ * tabindex or `aria-activedescendant`, arrow-key navigation, selection state —
92
+ * that these divs do not implement. The roles below are structural only and
93
+ * carry no interaction contract, so they are safe to forward.
94
+ *
95
+ * `list`/`listitem` in particular is how a row of columns is announced as
96
+ * "list, N items", and is the standard workaround for Safari/VoiceOver
97
+ * dropping implicit list semantics. `region` needs an accessible name to be
98
+ * exposed as a landmark; the type cannot enforce that.
99
+ *
100
+ * Page landmarks belong to the layout components (MrlMain, MrlPage).
101
+ */
102
+ export type SafeLayoutRole = 'group' | 'list' | 'listitem' | 'none' | 'presentation' | 'region';
103
+ /**
104
+ * Shared props for the grid components: every `div` attribute, with `role`
105
+ * narrowed to {@link SafeLayoutRole}.
106
+ */
107
+ export type GridBaseProps = Omit<React.ComponentPropsWithoutRef<'div'>, 'role'> & DataQa & {
108
+ /**
109
+ * Structural role for the wrapper. Composite widget roles are not
110
+ * accepted — see {@link SafeLayoutRole}.
111
+ */
112
+ role?: SafeLayoutRole;
113
+ };
71
114
  export {};
@@ -1,4 +1,4 @@
1
1
  export * from './MrlGrid';
2
2
  export * from './MrlRow';
3
3
  export * from './MrlCol';
4
- export type { NumCols } from './constants';
4
+ export type { AlignOptions, ColSpan, GridColumns, GutterSizes, JustifyOptions, NumCols, OffsetSpan, SafeLayoutRole } from './constants';
@@ -31,5 +31,6 @@ export * from './panel';
31
31
  export * from './rovingTabindex';
32
32
  export * from './toolbar';
33
33
  export * from './filter';
34
+ export * from './multi-filter';
34
35
  export * from './breadcrumb';
35
36
  export * from './file-upload';
@@ -0,0 +1,166 @@
1
+ import * as React from 'react';
2
+ import { MrlPopoverProps } from '../../popover/MrlPopover/MrlPopover';
3
+ import { MrlMultiFilterTriggerProps } from '../MrlMultiFilterTrigger/MrlMultiFilterTrigger';
4
+ import { MrlMultiFilterDraft, MrlMultiFilterValues } from '../MrlMultiFilterContext/MrlMultiFilterContext';
5
+ import { MrlMultiFilterFieldBinding } from '../MrlMultiFilterField/MrlMultiFilterField';
6
+ import { LevelType } from '../../text/constants';
7
+ import { DataQa } from '../../../utils/dataQa';
8
+ export type MrlMultiFilterRenderProps<T extends MrlMultiFilterValues> = {
9
+ /**
10
+ * Validates the draft, then does what the Apply button does. Required fields cannot be
11
+ * skipped.
12
+ */
13
+ apply: () => void;
14
+ /**
15
+ * Closes the popover and returns focus to the trigger. Unapplied edits are dropped.
16
+ */
17
+ closeMenu: () => void;
18
+ /**
19
+ * The draft being edited.
20
+ */
21
+ draft: MrlMultiFilterDraft<T>;
22
+ /**
23
+ * Returns the binding of one field, to pass to MrlMultiFilterField's `field`. Its value is
24
+ * typed from the field name.
25
+ */
26
+ getField: <K extends keyof T>(name: K) => MrlMultiFilterFieldBinding<T[K]>;
27
+ /**
28
+ * Does what the Reset button does.
29
+ */
30
+ reset: () => void;
31
+ /**
32
+ * Updates one field's value in the draft. Call it from event handlers, not during render.
33
+ */
34
+ setFieldValue: <K extends keyof T>(name: K, value: T[K]) => void;
35
+ /**
36
+ * Marks one field as required or not. Call it from event handlers, not during render.
37
+ */
38
+ setRequired: (name: keyof T, required: boolean) => void;
39
+ };
40
+ /**
41
+ * Without `transform`, `onApply` receives the draft.
42
+ *
43
+ * Docgen merges the JSDoc of both union members (this one first), so each comment below is
44
+ * written to read on its own and as the first half of the merged description.
45
+ */
46
+ type MrlMultiFilterApplyDraftProps<T extends MrlMultiFilterValues> = {
47
+ /**
48
+ * Called when Apply is pressed and every required field has a value, before the popover
49
+ * closes. Receives the draft, which becomes the applied draft.
50
+ */
51
+ onApply: (draft: MrlMultiFilterDraft<T>) => void;
52
+ /**
53
+ * Reshapes the draft before it is passed to `onApply`, e.g. `getDraftValues`.
54
+ */
55
+ transform?: undefined;
56
+ };
57
+ /**
58
+ * With `transform`, `onApply` receives its result.
59
+ */
60
+ type MrlMultiFilterApplyTransformedProps<T extends MrlMultiFilterValues, R> = {
61
+ /**
62
+ * With `transform`, it receives the transformed draft instead.
63
+ */
64
+ onApply: (result: R) => void;
65
+ /**
66
+ * Its result is what `onApply` receives.
67
+ */
68
+ transform: (draft: MrlMultiFilterDraft<T>) => R;
69
+ };
70
+ export type MrlMultiFilterProps<T extends MrlMultiFilterValues, R = MrlMultiFilterDraft<T>> = {
71
+ /**
72
+ * Makes the applied filters controlled: pass the applied draft and store the draft that
73
+ * `onApply` receives (so leave out `transform`). When it changes, e.g. when the filters are
74
+ * cleared from outside the popover, the draft and the badge follow it. When omitted, the
75
+ * component keeps the applied draft itself.
76
+ */
77
+ appliedDraft?: MrlMultiFilterDraft<T>;
78
+ /**
79
+ * Label of the Apply button.
80
+ */
81
+ applyText?: string;
82
+ /**
83
+ * Label of the Cancel button.
84
+ */
85
+ cancelText?: string;
86
+ /**
87
+ * Content of the popover, usually MrlMultiFilterField elements. Pass a function to read and
88
+ * edit the draft: it receives `getField` to bind the fields, plus `draft`, `setFieldValue`,
89
+ * `setRequired`, `apply`, `reset` and `closeMenu`. It only runs while the popover is open.
90
+ */
91
+ children: React.ReactNode | ((renderProps: MrlMultiFilterRenderProps<T>) => React.ReactNode);
92
+ /**
93
+ * Counts the filters shown on the trigger badge. It runs on the applied draft, so the count
94
+ * only changes on Apply. Defaults to the fields with a value set (not empty and not `false`).
95
+ */
96
+ countActiveFilters?: (applied: MrlMultiFilterDraft<T>) => number;
97
+ /**
98
+ * Heading shown at the top of the popover. It is also the popover's accessible name.
99
+ */
100
+ heading: string;
101
+ /**
102
+ * Semantic level of the heading, based on where the filter sits in the page hierarchy.
103
+ */
104
+ headingLevel?: LevelType;
105
+ /**
106
+ * The filters the component starts from, unless `appliedDraft` is given: a `value` and an
107
+ * optional `required` flag per field. The filter values type is inferred from it. Later
108
+ * changes are ignored. Also what Reset goes back to, unless `resetDraft` is given.
109
+ */
110
+ initialDraft: MrlMultiFilterDraft<T>;
111
+ /**
112
+ * Called when the Cancel button is pressed, after the draft is set back to the applied
113
+ * draft and before the popover closes.
114
+ */
115
+ onCancel?: () => void;
116
+ /**
117
+ * Draft set by the Reset button, or a function that returns it from the current draft.
118
+ * Defaults to `initialDraft`. The popover stays open and nothing is applied until Apply.
119
+ */
120
+ resetDraft?: MrlMultiFilterDraft<T> | ((draft: MrlMultiFilterDraft<T>) => MrlMultiFilterDraft<T>);
121
+ /**
122
+ * Label of the Reset button.
123
+ */
124
+ resetText?: string;
125
+ /**
126
+ * Message shown below a required field left empty on Apply. A field can override it.
127
+ */
128
+ requiredMessage?: string;
129
+ /**
130
+ * Size of the trigger button.
131
+ */
132
+ triggerSize?: MrlMultiFilterTriggerProps['size'];
133
+ /**
134
+ * Interaction state of the trigger button. Only `default` and `disabled` apply.
135
+ */
136
+ triggerState?: MrlMultiFilterTriggerProps['state'];
137
+ /**
138
+ * Visible label of the trigger button.
139
+ */
140
+ triggerText: MrlMultiFilterTriggerProps['text'];
141
+ } & (MrlMultiFilterApplyDraftProps<T> | MrlMultiFilterApplyTransformedProps<T, R>) & Pick<MrlPopoverProps, 'alignment' | 'className' | 'offset' | 'position'> & Pick<MrlMultiFilterTriggerProps, 'notificationText'> & DataQa;
142
+ /**
143
+ * MrlMultiFilter component.
144
+ *
145
+ * A MrlMultiFilterTrigger that opens a MrlPopover holding a heading and several filter
146
+ * fields, followed by a Reset / Cancel / Apply footer. Changes only take effect on Apply: the
147
+ * fields edit a draft, which starts from the applied filters each time the popover opens, so
148
+ * closing without Apply drops unapplied edits, and the trigger badge counts the applied
149
+ * filters. Apply hands the draft to `onApply` (through `transform`, if given) and makes it the
150
+ * applied one; Cancel sets it back to the applied filters; Reset sets it to `resetDraft` and
151
+ * keeps the popover open. Apply is blocked, and the first empty required field focused, while
152
+ * a required field is empty.
153
+ *
154
+ * Uncontrolled by default: the component keeps the applied draft. Pass `appliedDraft` and
155
+ * update it in `onApply` to control it, e.g. to clear or restore the filters from outside.
156
+ *
157
+ * Bind each field with `field={getField('name')}` from the render prop. The popover is a
158
+ * non-modal dialog named by the heading through `aria-labelledby`. It sets
159
+ * `aria-haspopup="dialog"` and `aria-expanded` on the trigger; the latter drives its toggle style. Cancel and Apply return focus to the trigger. Checkboxes inside the
160
+ * fields drop their default checkbox-group spacing.
161
+ *
162
+ * @param props - The component props.
163
+ * @returns The MrlMultiFilter component.
164
+ */
165
+ export declare function MrlMultiFilter<T extends MrlMultiFilterValues, R = MrlMultiFilterDraft<T>>(props: MrlMultiFilterProps<T, R>): React.ReactElement;
166
+ export {};
@@ -0,0 +1 @@
1
+ export * from './MrlMultiFilter';
@@ -0,0 +1,141 @@
1
+ import * as React from 'react';
2
+ /**
3
+ * Values of the filters, keyed by field name.
4
+ */
5
+ export type MrlMultiFilterValues = Record<string, unknown>;
6
+ /**
7
+ * One field of the draft.
8
+ */
9
+ export type MrlMultiFilterDraftField<V> = {
10
+ /**
11
+ * Whether Apply is blocked while the value is empty (`null`, `undefined`, `''` or `[]`;
12
+ * `false` is not empty). Defaults to `false`. Change it at runtime with `setRequired`.
13
+ */
14
+ required?: boolean;
15
+ /**
16
+ * The field's value.
17
+ */
18
+ value: V;
19
+ };
20
+ /**
21
+ * Filters as a value and a required flag per field. Used for the draft being edited and for
22
+ * the applied filters.
23
+ */
24
+ export type MrlMultiFilterDraft<T extends MrlMultiFilterValues> = {
25
+ [K in keyof T]: MrlMultiFilterDraftField<T[K]>;
26
+ };
27
+ /**
28
+ * Fields that failed validation, keyed by field name.
29
+ */
30
+ export type MrlMultiFilterErrors<T extends MrlMultiFilterValues> = Partial<Record<keyof T, true>>;
31
+ type MrlMultiFilterState<T extends MrlMultiFilterValues> = {
32
+ /**
33
+ * The last applied draft. Cancel sets the draft back to it. When controlled, it follows
34
+ * `appliedDraft`.
35
+ */
36
+ applied: MrlMultiFilterDraft<T>;
37
+ /**
38
+ * The draft being edited. MrlMultiFilter sets it back to the applied draft on each open.
39
+ */
40
+ draft: MrlMultiFilterDraft<T>;
41
+ /**
42
+ * Fields that failed validation.
43
+ */
44
+ errors: MrlMultiFilterErrors<T>;
45
+ };
46
+ /**
47
+ * Whether a value counts as empty. `false` is a value, so it is not empty.
48
+ *
49
+ * @param value - The field value.
50
+ * @returns Whether the value is empty.
51
+ */
52
+ export declare const isMrlMultiFilterValueEmpty: (value: unknown) => boolean;
53
+ /**
54
+ * Returns the plain values of a draft, without the required flags. A common `transform`.
55
+ *
56
+ * @param draft - The draft.
57
+ * @returns The values, keyed by field name.
58
+ */
59
+ export declare const getDraftValues: <T extends MrlMultiFilterValues>(draft: MrlMultiFilterDraft<T>) => T;
60
+ /**
61
+ * The context value. Every function keeps its identity across renders, so it can be passed to
62
+ * effects and callbacks without changing on each draft edit. `getDraft` and `validate` read the
63
+ * latest draft, including edits made earlier in the same event handler.
64
+ */
65
+ export type MrlMultiFilterContextValue<T extends MrlMultiFilterValues> = MrlMultiFilterState<T> & {
66
+ /**
67
+ * Saves the draft as the applied one and clears the errors. Call `validate` first.
68
+ */
69
+ commit: () => void;
70
+ /**
71
+ * Sets the draft back to the last applied draft and clears the errors.
72
+ */
73
+ discard: () => void;
74
+ /**
75
+ * Returns the latest draft. Unlike `draft`, it includes edits made earlier in the same event
76
+ * handler, before React re-renders.
77
+ */
78
+ getDraft: () => MrlMultiFilterDraft<T>;
79
+ /**
80
+ * Registers a field's element, so validation can focus it. Returns a function that
81
+ * unregisters it.
82
+ */
83
+ registerField: (name: keyof T, element: HTMLElement) => () => void;
84
+ /**
85
+ * Replaces the draft and clears the errors.
86
+ */
87
+ reset: (draft: MrlMultiFilterDraft<T>) => void;
88
+ /**
89
+ * Updates one field's value in the draft and clears its error.
90
+ */
91
+ setFieldValue: <K extends keyof T>(name: K, value: T[K]) => void;
92
+ /**
93
+ * Updates one field's required flag in the draft. Turning it off clears the field's error.
94
+ */
95
+ setRequired: (name: keyof T, required: boolean) => void;
96
+ /**
97
+ * Checks the required fields of the latest draft. Marks the empty ones and focuses the first
98
+ * of them.
99
+ *
100
+ * @returns Whether the draft is valid.
101
+ */
102
+ validate: () => boolean;
103
+ };
104
+ type MrlMultiFilterContextProviderProps<T extends MrlMultiFilterValues> = {
105
+ /**
106
+ * Controls the applied draft. When it changes, the draft is replaced by it, dropping any
107
+ * unapplied edits. When omitted, the provider keeps the applied draft itself.
108
+ */
109
+ appliedDraft?: MrlMultiFilterDraft<T>;
110
+ children: React.ReactNode;
111
+ /**
112
+ * The draft and the applied draft start from it, unless `appliedDraft` is given. Later
113
+ * changes are ignored.
114
+ */
115
+ initialDraft: MrlMultiFilterDraft<T>;
116
+ };
117
+ /**
118
+ * MrlMultiFilterContextProvider component.
119
+ *
120
+ * @param props - The component props.
121
+ * @returns The MrlMultiFilterContextProvider component.
122
+ */
123
+ export declare function MrlMultiFilterContextProvider<T extends MrlMultiFilterValues>(props: MrlMultiFilterContextProviderProps<T>): JSX.Element;
124
+ /**
125
+ * Custom hook to use the MrlMultiFilterContext.
126
+ *
127
+ * This hook provides access to the MrlMultiFilterContext value. React context cannot be
128
+ * generic, so pass the filter values type to get a typed draft.
129
+ *
130
+ * @returns The MrlMultiFilterContext value.
131
+ * @throws Will throw an error if used outside of a MrlMultiFilterContextProvider.
132
+ */
133
+ export declare const useMrlMultiFilterContext: <T extends MrlMultiFilterValues = MrlMultiFilterValues>() => MrlMultiFilterContextValue<T>;
134
+ /**
135
+ * Same as useMrlMultiFilterContext, but returns `undefined` outside a provider, so
136
+ * MrlMultiFilterField also works on its own.
137
+ *
138
+ * @returns The MrlMultiFilterContext value, or `undefined`.
139
+ */
140
+ export declare const useOptionalMrlMultiFilterContext: () => MrlMultiFilterContextValue<MrlMultiFilterValues> | undefined;
141
+ export {};
@@ -0,0 +1 @@
1
+ export * from './MrlMultiFilterContext';
@@ -0,0 +1,121 @@
1
+ import * as React from 'react';
2
+ import { DataQa } from '../../../utils/dataQa';
3
+ export type MrlMultiFilterFieldRenderProps = {
4
+ /**
5
+ * Id of the rendered error message, or `undefined` when there is no error. Pass it to the
6
+ * form element's `aria-errormessage` (with `aria-invalid`) or `aria-describedby` so the
7
+ * error is announced with the field.
8
+ */
9
+ errorId?: string;
10
+ /**
11
+ * Whether the field is showing an error. Pass it to the form element's `hasError` (or
12
+ * `aria-invalid`) so its error styles and invalid state match the message.
13
+ */
14
+ hasError: boolean;
15
+ };
16
+ /**
17
+ * A field of the MrlMultiFilter draft, returned by `getField` from its render prop.
18
+ */
19
+ export type MrlMultiFilterFieldBinding<V> = {
20
+ /**
21
+ * The required error message, set while the field is required and empty after Apply.
22
+ */
23
+ error?: string;
24
+ /**
25
+ * Name of the field in the draft.
26
+ */
27
+ name: string;
28
+ /**
29
+ * Whether the field is required.
30
+ */
31
+ required: boolean;
32
+ /**
33
+ * Updates the field's value in the draft.
34
+ */
35
+ setValue: (value: V) => void;
36
+ /**
37
+ * The field's value in the draft.
38
+ */
39
+ value: V;
40
+ };
41
+ export type MrlMultiFilterFieldBoundRenderProps<V> = MrlMultiFilterFieldRenderProps & Pick<MrlMultiFilterFieldBinding<V>, 'required' | 'setValue' | 'value'>;
42
+ /**
43
+ * A field that never shows an error: plain children, no `errorMessage`.
44
+ *
45
+ * Docgen merges the JSDoc of the union members (this one first), so each comment below is
46
+ * written to read on its own and as the first part of the merged description.
47
+ */
48
+ type MrlMultiFilterFieldWithoutErrorProps = {
49
+ /**
50
+ * The field content, usually a label and a form element.
51
+ */
52
+ children?: React.ReactNode;
53
+ /**
54
+ * Error message shown below the field. When omitted, no error is rendered.
55
+ */
56
+ errorMessage?: never;
57
+ /**
58
+ * Binds the field to the MrlMultiFilter draft. Pass `getField('name')` from the
59
+ * MrlMultiFilter render prop.
60
+ */
61
+ field?: never;
62
+ /**
63
+ * Message shown when the field is required and empty on Apply. Defaults to the
64
+ * MrlMultiFilter `requiredMessage`.
65
+ */
66
+ requiredMessage?: never;
67
+ };
68
+ /**
69
+ * A field that can show an error: `children` must be a function so the consumer can link the
70
+ * error message to the form element.
71
+ */
72
+ type MrlMultiFilterFieldWithErrorProps = Omit<MrlMultiFilterFieldWithoutErrorProps, 'children' | 'errorMessage'> & {
73
+ /**
74
+ * To show an error, pass a function instead. It receives `errorId` and `hasError`: pass
75
+ * them to the form element's `aria-errormessage` and `hasError` (or `aria-invalid`).
76
+ */
77
+ children: (renderProps: MrlMultiFilterFieldRenderProps) => React.ReactNode;
78
+ /**
79
+ * Requires `children` to be a function, so the message can be linked to the form element.
80
+ */
81
+ errorMessage?: string;
82
+ };
83
+ /**
84
+ * A field bound to the MrlMultiFilter draft through `field`.
85
+ */
86
+ type MrlMultiFilterFieldBoundProps<V> = {
87
+ /**
88
+ * With `field`, the function also receives `value`, `setValue` and `required`.
89
+ */
90
+ children: (renderProps: MrlMultiFilterFieldBoundRenderProps<V>) => React.ReactNode;
91
+ /**
92
+ * Takes precedence over the required error.
93
+ */
94
+ errorMessage?: string;
95
+ /**
96
+ * Must come from the same MrlMultiFilter.
97
+ */
98
+ field: MrlMultiFilterFieldBinding<V>;
99
+ /**
100
+ * Overrides it for this field.
101
+ */
102
+ requiredMessage?: string;
103
+ };
104
+ type MrlMultiFilterFieldBaseProps = Omit<React.ComponentPropsWithoutRef<'div'>, 'children'> & DataQa;
105
+ export type MrlMultiFilterFieldProps<V = unknown> = (MrlMultiFilterFieldWithoutErrorProps | MrlMultiFilterFieldWithErrorProps | MrlMultiFilterFieldBoundProps<V>) & MrlMultiFilterFieldBaseProps;
106
+ /**
107
+ * MrlMultiFilterField component.
108
+ *
109
+ * Wraps a single filter control of the MrlMultiFilter and shows an inline error message
110
+ * below it when `errorMessage` is set. `errorMessage` requires `children` to be a render
111
+ * function, which receives `errorId` and `hasError` so the error is always linked to the form
112
+ * element and its invalid state matches the message. Pass `field={getField('name')}` from the
113
+ * MrlMultiFilter render prop to bind the field to the draft: the function then also receives
114
+ * the typed `value`, `setValue` and `required`, and the required error is shown on Apply.
115
+ *
116
+ * @param props - The component props.
117
+ * @returns The MrlMultiFilterField component.
118
+ */
119
+ export declare function MrlMultiFilterField<V>(props: MrlMultiFilterFieldBoundProps<V> & MrlMultiFilterFieldBaseProps): React.ReactElement;
120
+ export declare function MrlMultiFilterField(props: (MrlMultiFilterFieldWithoutErrorProps | MrlMultiFilterFieldWithErrorProps) & MrlMultiFilterFieldBaseProps): React.ReactElement;
121
+ export {};
@@ -0,0 +1 @@
1
+ export * from './MrlMultiFilterField';