@muraldevkit/ui-toolkit 4.75.0 → 4.77.0-dev-yOaq.1

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 (73) hide show
  1. package/dist/cjs/components/file-upload/MrlFileUpload/MrlFileUpload.js +404 -0
  2. package/dist/cjs/components/file-upload/MrlFileUpload/MrlFileUpload.js.map +1 -0
  3. package/dist/cjs/components/file-upload/MrlFileUpload/MrlFileUpload.module.scss.js +8 -0
  4. package/dist/cjs/components/file-upload/MrlFileUpload/MrlFileUpload.module.scss.js.map +1 -0
  5. package/dist/cjs/components/file-upload/constants.js +48 -0
  6. package/dist/cjs/components/file-upload/constants.js.map +1 -0
  7. package/dist/cjs/components/file-upload/helpers.js +67 -0
  8. package/dist/cjs/components/file-upload/helpers.js.map +1 -0
  9. package/dist/cjs/components/grid/MrlCol/MrlCol.js +42 -49
  10. package/dist/cjs/components/grid/MrlCol/MrlCol.js.map +1 -1
  11. package/dist/cjs/components/grid/MrlGrid/MrlGrid.js +4 -6
  12. package/dist/cjs/components/grid/MrlGrid/MrlGrid.js.map +1 -1
  13. package/dist/cjs/components/grid/MrlRow/MrlRow.js +10 -8
  14. package/dist/cjs/components/grid/MrlRow/MrlRow.js.map +1 -1
  15. package/dist/cjs/components/grid/constants.js +27 -8
  16. package/dist/cjs/components/grid/constants.js.map +1 -1
  17. package/dist/cjs/index.js +37 -31
  18. package/dist/cjs/index.js.map +1 -1
  19. package/dist/cjs/version.js +1 -1
  20. package/dist/cjs/version.js.map +1 -1
  21. package/dist/components/file-upload/MrlFileUpload/MrlFileUpload.d.ts +154 -0
  22. package/dist/components/file-upload/MrlFileUpload/index.d.ts +1 -0
  23. package/dist/components/file-upload/constants.d.ts +35 -0
  24. package/dist/components/file-upload/helpers.d.ts +35 -0
  25. package/dist/components/file-upload/index.d.ts +2 -0
  26. package/dist/components/grid/MrlCol/MrlCol.d.ts +4 -6
  27. package/dist/components/grid/MrlCol/index.d.ts +1 -1
  28. package/dist/components/grid/MrlGrid/MrlGrid.d.ts +5 -4
  29. package/dist/components/grid/MrlGrid/index.d.ts +1 -1
  30. package/dist/components/grid/MrlRow/MrlRow.d.ts +7 -7
  31. package/dist/components/grid/MrlRow/index.d.ts +1 -1
  32. package/dist/components/grid/constants.d.ts +20 -6
  33. package/dist/components/index.d.ts +1 -0
  34. package/dist/esm/components/file-upload/MrlFileUpload/MrlFileUpload.js +379 -0
  35. package/dist/esm/components/file-upload/MrlFileUpload/MrlFileUpload.js.map +1 -0
  36. package/dist/esm/components/file-upload/MrlFileUpload/MrlFileUpload.module.scss.js +4 -0
  37. package/dist/esm/components/file-upload/MrlFileUpload/MrlFileUpload.module.scss.js.map +1 -0
  38. package/dist/esm/components/file-upload/constants.js +44 -0
  39. package/dist/esm/components/file-upload/constants.js.map +1 -0
  40. package/dist/esm/components/file-upload/helpers.js +62 -0
  41. package/dist/esm/components/file-upload/helpers.js.map +1 -0
  42. package/dist/esm/components/grid/MrlCol/MrlCol.js +43 -50
  43. package/dist/esm/components/grid/MrlCol/MrlCol.js.map +1 -1
  44. package/dist/esm/components/grid/MrlGrid/MrlGrid.js +4 -6
  45. package/dist/esm/components/grid/MrlGrid/MrlGrid.js.map +1 -1
  46. package/dist/esm/components/grid/MrlRow/MrlRow.js +10 -8
  47. package/dist/esm/components/grid/MrlRow/MrlRow.js.map +1 -1
  48. package/dist/esm/components/grid/constants.js +26 -8
  49. package/dist/esm/components/grid/constants.js.map +1 -1
  50. package/dist/esm/index.js +2 -0
  51. package/dist/esm/index.js.map +1 -1
  52. package/dist/esm/version.js +1 -1
  53. package/dist/esm/version.js.map +1 -1
  54. package/dist/styles/MrlFileUpload/module.scss +136 -0
  55. package/dist/styles/MrlSidebar/module.scss +2 -2
  56. package/dist/styles/file-upload/variables.scss +13 -0
  57. package/dist/styles/grid/global.scss +98 -2
  58. package/dist/styles/grid/variables.scss +2 -18
  59. package/dist/styles.css +2 -6
  60. package/dist/types/components/file-upload/MrlFileUpload/MrlFileUpload.d.ts +154 -0
  61. package/dist/types/components/file-upload/MrlFileUpload/index.d.ts +1 -0
  62. package/dist/types/components/file-upload/constants.d.ts +35 -0
  63. package/dist/types/components/file-upload/helpers.d.ts +35 -0
  64. package/dist/types/components/file-upload/index.d.ts +2 -0
  65. package/dist/types/components/grid/MrlCol/MrlCol.d.ts +4 -6
  66. package/dist/types/components/grid/MrlCol/index.d.ts +1 -1
  67. package/dist/types/components/grid/MrlGrid/MrlGrid.d.ts +5 -4
  68. package/dist/types/components/grid/MrlGrid/index.d.ts +1 -1
  69. package/dist/types/components/grid/MrlRow/MrlRow.d.ts +7 -7
  70. package/dist/types/components/grid/MrlRow/index.d.ts +1 -1
  71. package/dist/types/components/grid/constants.d.ts +20 -6
  72. package/dist/types/components/index.d.ts +1 -0
  73. package/package.json +1 -1
@@ -0,0 +1,154 @@
1
+ import * as React from 'react';
2
+ import { ProgressRange } from '../../loader/constants';
3
+ import { DataQa } from '../../../utils/dataQa';
4
+ import { MrlFileUploadState } from '../constants';
5
+ /**
6
+ * The resting half of the state contract: anything but a reported failure.
7
+ */
8
+ type MrlFileUploadRestingProps = {
9
+ /**
10
+ * Message for a failure the consumer is not currently reporting — kept across
11
+ * a retry, for instance. Rendered only in the error state.
12
+ */
13
+ errorMessage?: string;
14
+ /**
15
+ * The visual state of the zone, owned by the consumer. The component tracks
16
+ * drag state and local validation itself, but never starts, advances or
17
+ * completes an upload — pass 'uploading' with a `percent`, then 'complete'.
18
+ * Reporting 'error' requires an `errorMessage`, so it lives in the other half
19
+ * of this union.
20
+ *
21
+ * 'disabled' blocks all interaction: drag, drop and click handlers return
22
+ * early rather than relying on `pointer-events` alone. Because it is a value
23
+ * of this union rather than a separate flag, it replaces the lifecycle state
24
+ * rather than composing with it — a zone cannot be disabled *and* report
25
+ * progress at the same time.
26
+ */
27
+ state?: Exclude<MrlFileUploadState, 'error'>;
28
+ };
29
+ /**
30
+ * The failure half: reporting an error means saying what went wrong.
31
+ */
32
+ type MrlFileUploadErrorProps = {
33
+ /**
34
+ * Why the upload failed. Required alongside `state="error"`: the failure has
35
+ * to reach people who cannot see the border colour.
36
+ *
37
+ * A retry that fails with the identical message is announced only once — a
38
+ * live region re-set to the text it already holds says nothing, and the
39
+ * component cannot tell a retry from a re-render. Pass through a non-error
40
+ * state between attempts (back to 'idle', or 'uploading' while the retry is
41
+ * in flight) so the second failure is a genuine change.
42
+ */
43
+ errorMessage: string;
44
+ /**
45
+ * Reports a failed upload. A local validation failure supplies its own
46
+ * message and takes precedence over `errorMessage`.
47
+ */
48
+ state: 'error';
49
+ };
50
+ /**
51
+ * The zone's state and, when it reports a failure, the message that explains it.
52
+ *
53
+ * The two are a union rather than two independent props so that `state="error"`
54
+ * without an `errorMessage` does not compile. An errored zone with no text is
55
+ * signalled by border colour alone, which reaches neither assistive technology
56
+ * nor anyone who cannot distinguish the error hue. A consumer holding the state
57
+ * in a variable typed as the whole union has to narrow it before rendering —
58
+ * that is the point, not an accident.
59
+ */
60
+ export type MrlFileUploadStateProps = MrlFileUploadRestingProps | MrlFileUploadErrorProps;
61
+ export type MrlFileUploadProps = {
62
+ /**
63
+ * Accepted file types, in the same format as the native `accept` attribute
64
+ * (e.g. '.gif,.jpg,.jpeg,.png' or 'image/*'). Also enforced on drop, which
65
+ * the native attribute does not cover.
66
+ */
67
+ accept?: string;
68
+ /**
69
+ * Name of the file being uploaded, shown in the progress and completed copy
70
+ * and announced to assistive technology. Falls back to the name of the file
71
+ * the user last selected.
72
+ */
73
+ fileName?: string;
74
+ /**
75
+ * Headline inside the drop zone.
76
+ */
77
+ heading?: string;
78
+ /**
79
+ * Supporting line describing what is accepted.
80
+ */
81
+ helperText?: string;
82
+ /**
83
+ * Field label rendered above the drop zone, and the zone's accessible name.
84
+ */
85
+ label?: string;
86
+ /**
87
+ * Maximum accepted file size in bytes. Omit for no limit.
88
+ */
89
+ maxSizeBytes?: number;
90
+ /**
91
+ * Fired when the user cancels an upload in progress. The consumer owns the
92
+ * abort — the component only returns itself to its resting state.
93
+ */
94
+ onCancel?: () => void;
95
+ /**
96
+ * Fired when a file fails local validation, with the message shown to the
97
+ * user. Transport failures are reported by the consumer through
98
+ * `state="error"` instead.
99
+ */
100
+ onError?: (message: string, file: File) => void;
101
+ /**
102
+ * Fired when a file passes validation and is ready to upload. The consumer
103
+ * performs the upload and drives `state` and `percent` from its result.
104
+ */
105
+ onFilesSelected?: (file: File) => void;
106
+ /**
107
+ * Fired when the user removes a completed upload.
108
+ */
109
+ onRemove?: () => void;
110
+ /**
111
+ * Upload progress, 0–100. Only read while `state` is 'uploading'.
112
+ */
113
+ percent?: ProgressRange;
114
+ /**
115
+ * Shows `helperText` inside the drop zone.
116
+ */
117
+ showHelperText?: boolean;
118
+ /**
119
+ * Repeats `helperText` as an inline message below the drop zone. Off by
120
+ * default — with `showHelperText` on, enabling both prints the same sentence
121
+ * twice. A validation or upload error always renders below the zone
122
+ * regardless of this flag.
123
+ */
124
+ showInlineAlert?: boolean;
125
+ /**
126
+ * Additional validation, run after the built-in `accept` and `maxSizeBytes`
127
+ * checks and only if those pass. Return a message to reject the file — it is
128
+ * shown and reported exactly like a built-in failure — or `null` to accept it.
129
+ */
130
+ validate?: (file: File) => string | null;
131
+ /**
132
+ * Enables interaction tracking for this upload control. Provide a stable,
133
+ * non-PII id (e.g. 'workspace-logo-upload'). When omitted, the component
134
+ * emits no analytics.
135
+ *
136
+ * Note: file names, sizes and types are never emitted — only the fact of a
137
+ * selection and whether it was accepted.
138
+ */
139
+ eventId?: string;
140
+ } & MrlFileUploadStateProps & Omit<React.ComponentPropsWithoutRef<'div'>, 'onError'> & DataQa;
141
+ /**
142
+ * A drag-and-drop file upload zone with a keyboard-accessible browse button.
143
+ *
144
+ * The component owns presentation, drag tracking and local validation
145
+ * (`accept`, `maxSizeBytes`); the consumer owns the upload itself and drives
146
+ * `state` and `percent`. Drag and drop is pointer-only by nature, so the
147
+ * button inside the zone is the equivalent path for everyone else and is the
148
+ * affordance exposed to the accessibility tree.
149
+ *
150
+ * @param props - The component props.
151
+ * @returns The MrlFileUpload component.
152
+ */
153
+ export declare function MrlFileUpload(props: MrlFileUploadProps): React.ReactElement;
154
+ export {};
@@ -0,0 +1 @@
1
+ export { MrlFileUpload, type MrlFileUploadProps } from './MrlFileUpload';
@@ -0,0 +1,35 @@
1
+ export declare const allowedFileUploadValues: {
2
+ states: readonly ["idle", "uploading", "complete", "error", "disabled"];
3
+ };
4
+ /**
5
+ * The visual state of the drop zone, owned by the consumer.
6
+ *
7
+ * `dragging` is deliberately absent — a drag is transient pointer state the
8
+ * component tracks internally, not a state a consumer can meaningfully set.
9
+ */
10
+ export type MrlFileUploadState = (typeof allowedFileUploadValues.states)[number];
11
+ export interface FileUploadDefaults {
12
+ accept: string;
13
+ heading: string;
14
+ showHelperText: boolean;
15
+ showInlineAlert: boolean;
16
+ state: MrlFileUploadState;
17
+ }
18
+ /**
19
+ * Default values for props on the MrlFileUpload component;
20
+ * shared between the component and Storybook.
21
+ *
22
+ * `helperText` is absent on purpose: with no value from the consumer it is
23
+ * derived from the constraints actually enforced, so the copy cannot drift from
24
+ * what `accept` and `maxSizeBytes` reject.
25
+ */
26
+ export declare const fileUploadDefaults: FileUploadDefaults;
27
+ /**
28
+ * Shown when a consumer reports `state="error"` without an `errorMessage`.
29
+ *
30
+ * The types make that combination impossible, but a JavaScript consumer can
31
+ * still reach it — and an errored zone with no text is signalled by border
32
+ * colour alone, which reaches neither assistive technology nor anyone who
33
+ * cannot distinguish the error hue.
34
+ */
35
+ export declare const DEFAULT_ERROR_MESSAGE = "Upload failed";
@@ -0,0 +1,35 @@
1
+ /**
2
+ * Matches a file against an `accept` string (extensions and/or MIME types).
3
+ *
4
+ * The native `accept` attribute only filters the file picker; a dropped file
5
+ * bypasses it entirely, so the same rules have to be applied in code.
6
+ *
7
+ * @param file - the file to test
8
+ * @param accept - native `accept` syntax, e.g. '.png,image/*'
9
+ * @returns whether the file matches the accept rules
10
+ */
11
+ export declare function isAccepted(file: File, accept: string): boolean;
12
+ /**
13
+ * Formats a byte count for display in a validation message.
14
+ *
15
+ * @param bytes - the size in bytes
16
+ * @returns a short human-readable size, e.g. '2.5 MB'
17
+ */
18
+ export declare function formatBytes(bytes: number): string;
19
+ /**
20
+ * Lists the file types an `accept` string permits, for display.
21
+ *
22
+ * @param accept - native `accept` syntax, e.g. '.png,image/*'
23
+ * @returns a comma-separated list, or an empty string if nothing is restricted
24
+ */
25
+ export declare function formatAcceptList(accept: string): string;
26
+ /**
27
+ * Describes the constraints the component actually enforces, for use as helper
28
+ * text. Deriving the sentence from `accept` and `maxSizeBytes` is what keeps it
29
+ * from contradicting what validation rejects.
30
+ *
31
+ * @param accept - native `accept` syntax, e.g. '.png,image/*'
32
+ * @param maxSizeBytes - the size limit in bytes, if there is one
33
+ * @returns a sentence describing what may be uploaded, or an empty string
34
+ */
35
+ export declare function describeConstraints(accept: string, maxSizeBytes?: number): string;
@@ -0,0 +1,2 @@
1
+ export * from './MrlFileUpload';
2
+ export * from './constants';
@@ -1,10 +1,8 @@
1
- import { LayoutComponent } from '../../layout/constants';
2
- import { GridColumns } from '../constants';
3
- type MrlCol = LayoutComponent & GridColumns;
1
+ import { GridBaseProps, GridColumns } from '../constants';
2
+ export type MrlColProps = GridColumns & GridBaseProps;
4
3
  /**
5
- * MrlCol React component.
4
+ * MrlCol React component. Creates a grid column.
6
5
  * @param props - component props
7
6
  * @returns a MrlCol React component.
8
7
  */
9
- export declare function MrlCol(props: MrlCol): JSX.Element;
10
- export {};
8
+ export declare function MrlCol({ children, className, col, lg, md, sm, xl, xs, xxl, ...rest }: MrlColProps): JSX.Element;
@@ -1 +1 @@
1
- export { MrlCol } from './MrlCol';
1
+ export * from './MrlCol';
@@ -1,9 +1,10 @@
1
- import { LayoutComponent } from '../../layout/constants';
1
+ import { GridBaseProps } from '../constants';
2
2
  import '../grid.variables.scss';
3
3
  import '../grid.global.scss';
4
+ export type MrlGridProps = GridBaseProps;
4
5
  /**
5
- * MrlCol React component.
6
+ * MrlGrid React component. Primary container of a grid.
6
7
  * @param props - component props
7
- * @returns a MrlCol React component.
8
+ * @returns a MrlGrid React component.
8
9
  */
9
- export declare function MrlGrid({ children, className, ...rest }: LayoutComponent): JSX.Element;
10
+ 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,21 +1,18 @@
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
- * Available grid sizes
8
- */
9
- export declare const GridSizes: string[];
10
7
  /**
11
8
  * Number of columns that will be span on the grid.
12
9
  */
13
10
  export type NumCols = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
14
11
  /**
15
- * The type of classes that can be configured based on the bootstrap API.
12
+ * The grid classes that can be configured per breakpoint.
16
13
  * Current supported:
17
14
  * - columns "col-<size>-<number>"
18
- * - offsets "offset-<size>-<number>""
15
+ * - offsets "offset-<size>-<number>"
19
16
  */
20
17
  type GridClass = 'col' | 'offset';
21
18
  /**
@@ -43,8 +40,25 @@ export interface GridColumns {
43
40
  xl?: ColumnConfig;
44
41
  xxl?: ColumnConfig;
45
42
  }
43
+ /**
44
+ * Breakpoint keys in ascending order. Drives both class generation and the
45
+ * filtering that keeps grid props from reaching the DOM.
46
+ */
47
+ export declare const GRID_SIZE_KEYS: readonly ["col", "xs", "sm", "md", "lg", "xl", "xxl"];
46
48
  /**
47
49
  * Available gutter sizes for customizing the grid
48
50
  */
49
51
  export type GutterSizes = 0 | 1 | 2;
52
+ /**
53
+ * Gutter size to modifier class. `1` is the default gutter declared on `:root`,
54
+ * so it needs no class.
55
+ */
56
+ export declare const GUTTER_CLASS: Record<GutterSizes, string | undefined>;
57
+ /**
58
+ * Shared props for the grid components. `role` is intentionally omitted: these
59
+ * are generic layout wrappers, and a `role="grid"` would promise interactive
60
+ * grid keyboard semantics that they do not implement. Page landmarks belong to
61
+ * the layout components (MrlMain, MrlPage).
62
+ */
63
+ export type GridBaseProps = Omit<React.ComponentPropsWithoutRef<'div'>, 'role'> & DataQa;
50
64
  export {};
@@ -32,3 +32,4 @@ export * from './rovingTabindex';
32
32
  export * from './toolbar';
33
33
  export * from './filter';
34
34
  export * from './breadcrumb';
35
+ export * from './file-upload';