@muraldevkit/ui-toolkit 4.82.0 → 4.84.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 (61) hide show
  1. package/dist/cjs/components/multi-filter/MrlMultiFilter/MrlMultiFilter.js +232 -0
  2. package/dist/cjs/components/multi-filter/MrlMultiFilter/MrlMultiFilter.js.map +1 -0
  3. package/dist/cjs/components/multi-filter/MrlMultiFilter/MrlMultiFilter.module.scss.js +8 -0
  4. package/dist/cjs/components/multi-filter/MrlMultiFilter/MrlMultiFilter.module.scss.js.map +1 -0
  5. package/dist/cjs/components/multi-filter/MrlMultiFilterContext/MrlMultiFilterContext.js +302 -0
  6. package/dist/cjs/components/multi-filter/MrlMultiFilterContext/MrlMultiFilterContext.js.map +1 -0
  7. package/dist/cjs/components/multi-filter/MrlMultiFilterField/MrlMultiFilterField.js +123 -0
  8. package/dist/cjs/components/multi-filter/MrlMultiFilterField/MrlMultiFilterField.js.map +1 -0
  9. package/dist/cjs/components/multi-filter/MrlMultiFilterField/MrlMultiFilterField.module.scss.js +8 -0
  10. package/dist/cjs/components/multi-filter/MrlMultiFilterField/MrlMultiFilterField.module.scss.js.map +1 -0
  11. package/dist/cjs/components/multi-filter/MrlMultiFilterTrigger/MrlMultiFilterTrigger.js +83 -0
  12. package/dist/cjs/components/multi-filter/MrlMultiFilterTrigger/MrlMultiFilterTrigger.js.map +1 -0
  13. package/dist/cjs/components/multi-filter/utils.js +30 -0
  14. package/dist/cjs/components/multi-filter/utils.js.map +1 -0
  15. package/dist/cjs/components/notification/MrlInlineMessage/MrlInlineMessage.js +3 -2
  16. package/dist/cjs/components/notification/MrlInlineMessage/MrlInlineMessage.js.map +1 -1
  17. package/dist/cjs/components/popover/MrlPopover/MrlPopover.js +16 -5
  18. package/dist/cjs/components/popover/MrlPopover/MrlPopover.js.map +1 -1
  19. package/dist/cjs/index.js +12 -0
  20. package/dist/cjs/index.js.map +1 -1
  21. package/dist/cjs/version.js +1 -1
  22. package/dist/cjs/version.js.map +1 -1
  23. package/dist/esm/components/multi-filter/MrlMultiFilter/MrlMultiFilter.js +207 -0
  24. package/dist/esm/components/multi-filter/MrlMultiFilter/MrlMultiFilter.js.map +1 -0
  25. package/dist/esm/components/multi-filter/MrlMultiFilter/MrlMultiFilter.module.scss.js +4 -0
  26. package/dist/esm/components/multi-filter/MrlMultiFilter/MrlMultiFilter.module.scss.js.map +1 -0
  27. package/dist/esm/components/multi-filter/MrlMultiFilterContext/MrlMultiFilterContext.js +276 -0
  28. package/dist/esm/components/multi-filter/MrlMultiFilterContext/MrlMultiFilterContext.js.map +1 -0
  29. package/dist/esm/components/multi-filter/MrlMultiFilterField/MrlMultiFilterField.js +98 -0
  30. package/dist/esm/components/multi-filter/MrlMultiFilterField/MrlMultiFilterField.js.map +1 -0
  31. package/dist/esm/components/multi-filter/MrlMultiFilterField/MrlMultiFilterField.module.scss.js +4 -0
  32. package/dist/esm/components/multi-filter/MrlMultiFilterField/MrlMultiFilterField.module.scss.js.map +1 -0
  33. package/dist/esm/components/multi-filter/MrlMultiFilterTrigger/MrlMultiFilterTrigger.js +58 -0
  34. package/dist/esm/components/multi-filter/MrlMultiFilterTrigger/MrlMultiFilterTrigger.js.map +1 -0
  35. package/dist/esm/components/multi-filter/utils.js +28 -0
  36. package/dist/esm/components/multi-filter/utils.js.map +1 -0
  37. package/dist/esm/components/notification/MrlInlineMessage/MrlInlineMessage.js +3 -2
  38. package/dist/esm/components/notification/MrlInlineMessage/MrlInlineMessage.js.map +1 -1
  39. package/dist/esm/components/popover/MrlPopover/MrlPopover.js +16 -5
  40. package/dist/esm/components/popover/MrlPopover/MrlPopover.js.map +1 -1
  41. package/dist/esm/index.js +4 -0
  42. package/dist/esm/index.js.map +1 -1
  43. package/dist/esm/version.js +1 -1
  44. package/dist/esm/version.js.map +1 -1
  45. package/dist/styles/MrlMultiFilter/module.scss +30 -0
  46. package/dist/styles/MrlMultiFilterField/module.scss +7 -0
  47. package/dist/styles.css +2 -0
  48. package/dist/types/components/index.d.ts +1 -0
  49. package/dist/types/components/multi-filter/MrlMultiFilter/MrlMultiFilter.d.ts +166 -0
  50. package/dist/types/components/multi-filter/MrlMultiFilter/index.d.ts +1 -0
  51. package/dist/types/components/multi-filter/MrlMultiFilterContext/MrlMultiFilterContext.d.ts +141 -0
  52. package/dist/types/components/multi-filter/MrlMultiFilterContext/index.d.ts +1 -0
  53. package/dist/types/components/multi-filter/MrlMultiFilterField/MrlMultiFilterField.d.ts +121 -0
  54. package/dist/types/components/multi-filter/MrlMultiFilterField/index.d.ts +1 -0
  55. package/dist/types/components/multi-filter/MrlMultiFilterTrigger/MrlMultiFilterTrigger.d.ts +52 -0
  56. package/dist/types/components/multi-filter/MrlMultiFilterTrigger/index.d.ts +1 -0
  57. package/dist/types/components/multi-filter/index.d.ts +4 -0
  58. package/dist/types/components/multi-filter/utils.d.ts +8 -0
  59. package/dist/types/components/notification/MrlInlineMessage/MrlInlineMessage.d.ts +5 -1
  60. package/dist/types/components/popover/MrlPopover/MrlPopover.d.ts +7 -1
  61. package/package.json +1 -1
@@ -0,0 +1,30 @@
1
+ .MrlMultiFilter {
2
+ width: 22.5rem;
3
+ }
4
+ .MrlMultiFilter-title {
5
+ margin-bottom: var(--mrl-space-stack-controls);
6
+ }
7
+ .MrlMultiFilter-fields {
8
+ --mrl-checkbox-height: var(--mrl-checkbox-input-size);
9
+ display: flex;
10
+ flex-direction: column;
11
+ gap: var(--mrl-spacing-05);
12
+ :global(.MrlCheckbox) {
13
+ > :last-child {
14
+ min-height: auto;
15
+ }
16
+ :global(.MrlLabel-text) {
17
+ padding-top: 0;
18
+ }
19
+ }
20
+ }
21
+ .MrlMultiFilter-actions {
22
+ align-items: center;
23
+ display: flex;
24
+ gap: var(--mrl-space-inline-related);
25
+ justify-content: flex-end;
26
+ margin-top: var(--mrl-space-stack-controls);
27
+ }
28
+ .MrlMultiFilter-reset {
29
+ margin-right: auto;
30
+ }
@@ -0,0 +1,7 @@
1
+ .MrlMultiFilterField {
2
+ display: flex;
3
+ flex-direction: column;
4
+ > .MrlMultiFilterField-error {
5
+ margin-top: var(--mrl-space-stack-related-small);
6
+ }
7
+ }
package/dist/styles.css CHANGED
@@ -1043,6 +1043,8 @@
1043
1043
  0px
1044
1044
  )*-1)}}@keyframes outline-animation--7wBJq{0%{outline:0 solid rgba(0,0,0,0);outline-offset:1px}50%{outline:4px solid var(--mrl-color-focus);outline-offset:1px}100%{outline:2px solid var(--mrl-color-focus);outline-offset:1px}}.MrlFilterItem--yUzim::after,.MrlFilterItem--yUzim:focus-visible::after{border-radius:var(--mrl-border-radius-rounded)}.MrlFilterItem--yUzim .MrlBadge{border-radius:var(--mrl-border-radius-rounded);color:var(--mrl-filter-item-badge-text-color);font-size:.625rem;font-weight:var(--mrl-font-weight-04);height:var(--mrl-spacing-05);line-height:var(--mrl-line-height-02);padding:var(--mrl-spacing-01) var(--mrl-spacing-02);transition:outline-color var(--mrl-duration-04) var(--mrl-timing-m2),background-color var(--mrl-duration-04) var(--mrl-timing-m2),color var(--mrl-duration-04) var(--mrl-timing-m2)}.MrlFilterItem--yUzim:hover{--mrl-filter-item-background: var(--mrl-color-background-emph-active);cursor:pointer}.MrlFilterItem--yUzim[aria-checked=true]{--mrl-filter-item-background: var(--mrl-color-background-inverse);--mrl-filter-item-text-color: var(--mrl-color-text-inverse-selected)}.MrlFilterItem--yUzim[aria-checked=true] .MrlBadge{background-color:var(--mrl-color-background)}.MrlFilterItem-has-count--ApmvA{padding-right:var(--mrl-spacing-03)}
1045
1045
  .MrlFilter--22siM{display:flex;gap:var(--mrl-spacing-02);margin:var(--mrl-spacing-05) 0}
1046
+ .MrlMultiFilterField--lVlxB{display:flex;flex-direction:column}.MrlMultiFilterField--lVlxB>.MrlMultiFilterField-error--jh1El{margin-top:var(--mrl-space-stack-related-small)}
1047
+ .MrlMultiFilter--zqSCS{width:22.5rem}.MrlMultiFilter-title--ogr0l{margin-bottom:var(--mrl-space-stack-controls)}.MrlMultiFilter-fields--T--TL{--mrl-checkbox-height: var(--mrl-checkbox-input-size);display:flex;flex-direction:column;gap:var(--mrl-spacing-05)}.MrlMultiFilter-fields--T--TL .MrlCheckbox>:last-child{min-height:auto}.MrlMultiFilter-fields--T--TL .MrlCheckbox .MrlLabel-text{padding-top:0}.MrlMultiFilter-actions--vFqBP{align-items:center;display:flex;gap:var(--mrl-space-inline-related);justify-content:flex-end;margin-top:var(--mrl-space-stack-controls)}.MrlMultiFilter-reset--tnh1T{margin-right:auto}
1046
1048
  .mrl-u-focus-wrapper--VWXNO{position:relative}.MrlBreadcrumbItem--LZttq{align-items:center;color:var(--mrl-color-text);display:inline-flex;font-size:var(--mrl-font-size-02);font-weight:var(--mrl-font-weight-02);line-height:var(--mrl-line-height-06);min-height:var(--mrl-spacing-05)}.MrlBreadcrumbItem--LZttq:hover{color:var(--mrl-color-text-hover)}.MrlBreadcrumbItem--selected--w6EUT{color:var(--mrl-color-text-selected);font-weight:var(--mrl-font-weight-04)}.MrlBreadcrumbItem--LZttq a{position:relative;color:var(--mrl-color-text);padding-right:var(--mrl-spacing-01);text-decoration:none}.MrlBreadcrumbItem--LZttq a:focus-visible{outline:none}.MrlBreadcrumbItem--LZttq a:focus-visible::after{animation-duration:var(--mrl-duration-03);animation-fill-mode:forwards;animation-iteration-count:1;animation-timing-function:var(--mrl-timing-m3);border:0 solid rgba(0,0,0,0);border-radius:calc(
1047
1049
  var(--mrl-border-radius-functional) + var(--mrl-line-width-focus) + var(--mrl-space-offset-focus)
1048
1050
  );bottom:calc((
@@ -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';
@@ -0,0 +1,52 @@
1
+ import * as React from 'react';
2
+ import { MrlButtonProps } from '../../button/MrlButton/MrlButton';
3
+ import { DataQa } from '../../../utils/dataQa';
4
+ export type MrlMultiFilterTriggerProps = {
5
+ /**
6
+ * Number of active filters. When greater than 0, a numeric badge is shown on the icon.
7
+ */
8
+ activeFiltersCount?: number;
9
+ /**
10
+ * Whether the filter controlled by this trigger is open. Shows the selected toggle style
11
+ * and sets `aria-expanded` on the button. The trigger never toggles this by itself.
12
+ */
13
+ isOpen?: boolean;
14
+ /**
15
+ * Text announced to screen reader users for the badge.
16
+ * Defaults to `${activeFiltersCount} active filters`.
17
+ */
18
+ notificationText?: string;
19
+ /**
20
+ * Interaction state of the trigger button. Only `default` and `disabled` apply.
21
+ */
22
+ state?: Extract<MrlButtonProps['state'], 'default' | 'disabled'>;
23
+ } & Pick<MrlButtonProps, 'className' | 'size' | 'text'> & DataQa;
24
+ /**
25
+ * MrlMultiFilterTrigger component.
26
+ *
27
+ * The button that opens the MrlMultiFilter. Shows the refine icon after the label and,
28
+ * when filters are active, a numeric badge with the active filter count.
29
+ *
30
+ * @param props - The component props.
31
+ * @returns The MrlMultiFilterTrigger component.
32
+ */
33
+ export declare const MrlMultiFilterTrigger: React.ForwardRefExoticComponent<{
34
+ /**
35
+ * Number of active filters. When greater than 0, a numeric badge is shown on the icon.
36
+ */
37
+ activeFiltersCount?: number;
38
+ /**
39
+ * Whether the filter controlled by this trigger is open. Shows the selected toggle style
40
+ * and sets `aria-expanded` on the button. The trigger never toggles this by itself.
41
+ */
42
+ isOpen?: boolean;
43
+ /**
44
+ * Text announced to screen reader users for the badge.
45
+ * Defaults to `${activeFiltersCount} active filters`.
46
+ */
47
+ notificationText?: string;
48
+ /**
49
+ * Interaction state of the trigger button. Only `default` and `disabled` apply.
50
+ */
51
+ state?: Extract<MrlButtonProps["state"], "default" | "disabled">;
52
+ } & Pick<MrlButtonProps, "className" | "text" | "size"> & DataQa & React.RefAttributes<HTMLButtonElement>>;
@@ -0,0 +1 @@
1
+ export * from './MrlMultiFilterTrigger';
@@ -0,0 +1,4 @@
1
+ export * from './MrlMultiFilterContext';
2
+ export * from './MrlMultiFilterField';
3
+ export * from './MrlMultiFilterTrigger';
4
+ export * from './MrlMultiFilter';
@@ -0,0 +1,8 @@
1
+ /**
2
+ * Focuses the first focusable element of the first invalid field, in document order, so it
3
+ * does not depend on the order the fields registered in.
4
+ *
5
+ * @param fields - The registered field elements, keyed by field name.
6
+ * @param errors - The fields that failed validation, keyed by field name.
7
+ */
8
+ export declare const focusFirstInvalidField: <K extends PropertyKey>(fields: Map<K, HTMLElement>, errors: Partial<Record<K, true>>) => void;
@@ -26,6 +26,10 @@ export interface MrlInlineMessageProps {
26
26
  * Children to be rendered within the component, it will be used as the message if message is not provided.
27
27
  */
28
28
  children?: React.ReactNode;
29
+ /**
30
+ * Additional class name(s) applied to the root element, merged with the component's own classes.
31
+ */
32
+ className?: string;
29
33
  /**
30
34
  * The data-qa attribute for testing purposes.
31
35
  */
@@ -36,4 +40,4 @@ export interface MrlInlineMessageProps {
36
40
  * @param props - The properties of the component.
37
41
  * @returns A React component.
38
42
  */
39
- export declare const MrlInlineMessage: ({ children, customIcon, id, kind, message, ["data-qa"]: qa, ...rest }: MrlInlineMessageProps) => React.ReactElement;
43
+ export declare const MrlInlineMessage: ({ children, className, customIcon, id, kind, message, ["data-qa"]: qa, ...rest }: MrlInlineMessageProps) => React.ReactElement;
@@ -97,6 +97,12 @@ export interface MrlPopoverProps {
97
97
  * Configuration for the portal component
98
98
  */
99
99
  portalProps?: Omit<PortalProps, 'children'>;
100
+ /**
101
+ * ARIA role of the popover container, e.g. `dialog` when it holds interactive content.
102
+ * A role that is a valid `aria-haspopup` value (`dialog`, `grid`, `listbox`, `menu`, `tree`)
103
+ * is also announced on the trigger.
104
+ */
105
+ role?: React.AriaRole;
100
106
  /**
101
107
  * Offset in pixels for the popover
102
108
  *
@@ -130,7 +136,7 @@ export interface MrlPopoverProps {
130
136
  * @param {MrlPopoverProps} props - The props for the MrlPopover component
131
137
  * @returns {Element} - rendered MrlPopover component
132
138
  */
133
- export declare function MrlPopover({ alignment, ariaLabel, ariaLabelledBy, children, className, customPosition, disableClickToOpen, disableClickOutside, disableFlipping, disableFocusTrap, hasCloseButton, spacing, id, isSubMenu, actionState, position, point, portalProps, kind, offset, onClose, onOpen, eventId, triggerRef, ...rest }: MrlPopoverProps): JSX.Element;
139
+ export declare function MrlPopover({ alignment, ariaLabel, ariaLabelledBy, children, className, customPosition, disableClickToOpen, disableClickOutside, disableFlipping, disableFocusTrap, hasCloseButton, spacing, id, isSubMenu, actionState, position, point, portalProps, kind, role, offset, onClose, onOpen, eventId, triggerRef, ...rest }: MrlPopoverProps): JSX.Element;
134
140
  export declare namespace MrlPopover {
135
141
  var componentType: string;
136
142
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@muraldevkit/ui-toolkit",
3
- "version": "4.82.0",
3
+ "version": "4.84.0",
4
4
  "description": "Mural's UI Toolkit",
5
5
  "main": "./dist/cjs/index.js",
6
6
  "module": "./dist/esm/index.js",