@ringpublishing/mui-components-mcp 1.15.2-alpha.4 → 1.15.2-alpha.5
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 +1 -1
- package/package.json +3 -6
- package/data/knowledge.json +0 -3585
- package/dist/index.d.ts +0 -2
- package/dist/index.js +0 -156
- package/dist/index.js.map +0 -1
- package/dist/types.d.ts +0 -44
- package/dist/types.js +0 -2
- package/dist/types.js.map +0 -1
package/data/knowledge.json
DELETED
|
@@ -1,3585 +0,0 @@
|
|
|
1
|
-
{
|
|
2
|
-
"generated": "2026-07-31T09:42:22.011Z",
|
|
3
|
-
"importPath": "@ringpublishing/mui-components",
|
|
4
|
-
"componentCount": 35,
|
|
5
|
-
"components": {
|
|
6
|
-
"atoms-alert": {
|
|
7
|
-
"id": "atoms-alert",
|
|
8
|
-
"name": "Alert",
|
|
9
|
-
"category": "Atoms",
|
|
10
|
-
"title": "Components/Atoms/Alert",
|
|
11
|
-
"description": "Alert is a structured wrapper over MUI Alert. It uses explicit `title` and `description`, a controlled action button config, and supports both `outline` and `inline` frame variants.",
|
|
12
|
-
"argTypes": {
|
|
13
|
-
"title": {
|
|
14
|
-
"description": "Alert title rendered as the primary line of content.",
|
|
15
|
-
"control": "text",
|
|
16
|
-
"category": "content",
|
|
17
|
-
"type": "ReactNode"
|
|
18
|
-
},
|
|
19
|
-
"description": {
|
|
20
|
-
"description": "Optional description rendered below the title.",
|
|
21
|
-
"control": "text",
|
|
22
|
-
"category": "content",
|
|
23
|
-
"type": "ReactNode"
|
|
24
|
-
},
|
|
25
|
-
"severity": {
|
|
26
|
-
"description": "Severity state used by MUI to choose the visual tone and icon.",
|
|
27
|
-
"control": "select",
|
|
28
|
-
"category": "appearance",
|
|
29
|
-
"type": "AlertProps[\"severity\"]",
|
|
30
|
-
"defaultValue": "info",
|
|
31
|
-
"options": [
|
|
32
|
-
"info",
|
|
33
|
-
"success",
|
|
34
|
-
"warning",
|
|
35
|
-
"error"
|
|
36
|
-
]
|
|
37
|
-
},
|
|
38
|
-
"action": {
|
|
39
|
-
"description": "Action button configuration rendered after the message. Use onClick for actions or href for navigation.",
|
|
40
|
-
"control": false,
|
|
41
|
-
"category": "content",
|
|
42
|
-
"type": "{ label: string; buttonProps?: ButtonProps & { target?: string; rel?: string } } & ({ onClick: (event: React.MouseEvent<HTMLButtonElement>) => void; href?: never } | { href: string; onClick?: never })"
|
|
43
|
-
},
|
|
44
|
-
"actionsPlacement": {
|
|
45
|
-
"description": "Placement of the action button relative to the content.",
|
|
46
|
-
"control": "select",
|
|
47
|
-
"category": "appearance",
|
|
48
|
-
"type": "'right' | 'bottom'",
|
|
49
|
-
"defaultValue": "right",
|
|
50
|
-
"options": [
|
|
51
|
-
"right",
|
|
52
|
-
"bottom"
|
|
53
|
-
]
|
|
54
|
-
},
|
|
55
|
-
"layoutVariant": {
|
|
56
|
-
"description": "Controls the Alert frame treatment.",
|
|
57
|
-
"control": "select",
|
|
58
|
-
"category": "appearance",
|
|
59
|
-
"type": "'outline' | 'inline'",
|
|
60
|
-
"defaultValue": "outline",
|
|
61
|
-
"options": [
|
|
62
|
-
"outline",
|
|
63
|
-
"inline"
|
|
64
|
-
]
|
|
65
|
-
},
|
|
66
|
-
"onClose": {
|
|
67
|
-
"description": "Callback fired when the close button is clicked. Renders the shared X icon.",
|
|
68
|
-
"control": false,
|
|
69
|
-
"category": "callbacks",
|
|
70
|
-
"type": "(event: React.SyntheticEvent) => void"
|
|
71
|
-
},
|
|
72
|
-
"closeText": {
|
|
73
|
-
"description": "ARIA label for the close button.",
|
|
74
|
-
"control": "text",
|
|
75
|
-
"category": "customization",
|
|
76
|
-
"type": "string",
|
|
77
|
-
"defaultValue": "Close"
|
|
78
|
-
},
|
|
79
|
-
"role": {
|
|
80
|
-
"description": "ARIA role for the alert root.",
|
|
81
|
-
"control": "text",
|
|
82
|
-
"category": "customization",
|
|
83
|
-
"type": "string"
|
|
84
|
-
},
|
|
85
|
-
"icon": {
|
|
86
|
-
"description": "Overrides the default severity icon.",
|
|
87
|
-
"control": false,
|
|
88
|
-
"category": "appearance",
|
|
89
|
-
"type": "ReactNode | false"
|
|
90
|
-
},
|
|
91
|
-
"sx": {
|
|
92
|
-
"description": "MUI sx prop for custom styling.",
|
|
93
|
-
"control": "object",
|
|
94
|
-
"category": "customization",
|
|
95
|
-
"type": "SxProps<Theme>"
|
|
96
|
-
},
|
|
97
|
-
"className": {
|
|
98
|
-
"description": "Additional class name applied to the root element.",
|
|
99
|
-
"control": "text",
|
|
100
|
-
"category": "customization",
|
|
101
|
-
"type": "string"
|
|
102
|
-
},
|
|
103
|
-
"dataTestIdSuffix": {
|
|
104
|
-
"description": "Suffix appended to the root data-testid.",
|
|
105
|
-
"control": "text",
|
|
106
|
-
"category": "testing",
|
|
107
|
-
"type": "string"
|
|
108
|
-
}
|
|
109
|
-
},
|
|
110
|
-
"storyNames": [
|
|
111
|
-
"Default",
|
|
112
|
-
"ContentVariants",
|
|
113
|
-
"Severities",
|
|
114
|
-
"LayoutVariants",
|
|
115
|
-
"WithAction",
|
|
116
|
-
"WithLinkAction",
|
|
117
|
-
"WithClose",
|
|
118
|
-
"WithActionAndClose"
|
|
119
|
-
],
|
|
120
|
-
"docs": "# Alert\n\nAlert is a structured wrapper over MUI Alert. It uses explicit `title` and `description`, a controlled action button config, and supports both `outline` and `inline` frame variants.\n\n## Key Features\n\n- `title` and `description` are first-class content props\n- action is a controlled button config, not an arbitrary node\n- the close X is rendered from `onClose`\n- supports `actionsPlacement=\"right\" | \"bottom\"`\n- supports `layoutVariant=\"outline\" | \"inline\"`\n\n## Default\n\n```tsx\n// DefaultExample.tsx\nimport { Alert } from '@ringpublishing/mui-components';\n\nexport default function DefaultExample(): React.JSX.Element {\n return <Alert severity=\"info\" title=\"Alert title\" description=\"This is an alert description.\" />;\n}\n```\n\n## Content Variants\n\n```tsx\n// ContentVariantsExample.tsx\nimport { Stack } from '@mui/material';\n\nimport { Alert } from '@ringpublishing/mui-components';\n\nexport default function ContentVariantsExample(): React.JSX.Element {\n return (\n <Stack spacing={2}>\n <Alert title=\"Title only\" />\n <Alert description=\"Description only\" />\n <Alert title=\"Title and description\" description=\"Description under the title\" />\n </Stack>\n );\n}\n```\n\n## Severities\n\n```tsx\n// SeveritiesExample.tsx\nimport { Stack } from '@mui/material';\n\nimport { Alert } from '@ringpublishing/mui-components';\n\nexport default function SeveritiesExample(): React.JSX.Element {\n const handleActionClick = (): void => undefined;\n\n return (\n <Stack spacing={2}>\n <Alert\n severity=\"info\"\n title=\"Info\"\n description=\"Info description\"\n action={{ label: 'Label', onClick: handleActionClick }}\n onClose={(): void => undefined}\n />\n <Alert\n severity=\"success\"\n title=\"Success\"\n description=\"Success description\"\n action={{ label: 'Label', onClick: handleActionClick }}\n onClose={(): void => undefined}\n />\n <Alert\n severity=\"warning\"\n title=\"Warning\"\n description=\"Warning description\"\n action={{ label: 'Label', onClick: handleActionClick }}\n onClose={(): void => undefined}\n />\n <Alert\n severity=\"error\"\n title=\"Error\"\n description=\"Error description\"\n action={{ label: 'Label', onClick: handleActionClick }}\n onClose={(): void => undefined}\n />\n </Stack>\n );\n}\n```\n\n## With Action\n\n```tsx\n// WithActionExample.tsx\nimport { Alert } from '@ringpublishing/mui-components';\n\nconst handleActionClick = (): void => undefined;\n\nexport default function WithActionExample(): React.JSX.Element {\n return (\n <Alert\n title=\"Alert title\"\n description=\"This is an alert description.\"\n action={{ label: 'Action', onClick: handleActionClick }}\n />\n );\n}\n```\n\n## With Close\n\n```tsx\n// WithCloseExample.tsx\nimport { Alert } from '@ringpublishing/mui-components';\n\nexport default function WithCloseExample(): React.JSX.Element {\n return <Alert title=\"Alert title\" description=\"This is an alert description.\" onClose={(): void => undefined} />;\n}\n```\n\n## With Action And Close\n\n```tsx\n// WithActionAndCloseExample.tsx\nimport { Alert } from '@ringpublishing/mui-components';\n\nconst handleActionClick = (): void => undefined;\n\nexport default function WithActionAndCloseExample(): React.JSX.Element {\n return (\n <Alert\n title=\"Alert title\"\n description=\"This is an alert description.\"\n action={{ label: 'Action', onClick: handleActionClick }}\n onClose={(): void => undefined}\n />\n );\n}\n```\n\n## Layout Variants\n\n```tsx\n// LayoutVariantsExample.tsx\nimport { Stack } from '@mui/material';\n\nimport { Alert } from '@ringpublishing/mui-components';\n\nexport default function LayoutVariantsExample(): React.JSX.Element {\n const handleActionClick = (): void => undefined;\n\n return (\n <Stack spacing={2}>\n <Alert\n layoutVariant=\"outline\"\n actionsPlacement=\"right\"\n title=\"Outline right\"\n description=\"Description\"\n action={{ label: 'Label', onClick: handleActionClick }}\n onClose={(): void => undefined}\n />\n <Alert\n layoutVariant=\"outline\"\n actionsPlacement=\"bottom\"\n title=\"Outline bottom\"\n description=\"Description\"\n action={{ label: 'Label', onClick: handleActionClick }}\n onClose={(): void => undefined}\n />\n <Alert\n layoutVariant=\"inline\"\n actionsPlacement=\"right\"\n title=\"Inline right\"\n description=\"Description\"\n action={{ label: 'Label', onClick: handleActionClick }}\n onClose={(): void => undefined}\n />\n <Alert\n layoutVariant=\"inline\"\n actionsPlacement=\"bottom\"\n title=\"Inline bottom\"\n description=\"Description\"\n action={{ label: 'Label', onClick: handleActionClick }}\n onClose={(): void => undefined}\n />\n </Stack>\n );\n}\n```"
|
|
121
|
-
},
|
|
122
|
-
"atoms-dates-date-picker": {
|
|
123
|
-
"id": "atoms-dates-date-picker",
|
|
124
|
-
"name": "DatePicker",
|
|
125
|
-
"category": "Atoms",
|
|
126
|
-
"title": "Components/Atoms/Dates/DatePicker",
|
|
127
|
-
"description": "A date selection component that wraps MUI's [DatePicker](https://mui.com/x/react-date-pickers/date-picker/) with Ring Design System styling. Provides a calendar popup for selecting a single date with built-in support for clearable input, custom actions, and a \"Now\" shortcut button.",
|
|
128
|
-
"argTypes": {
|
|
129
|
-
"sx": {
|
|
130
|
-
"description": "MUI System properties to customize the component style.",
|
|
131
|
-
"control": "object",
|
|
132
|
-
"category": "customization",
|
|
133
|
-
"type": "SxProps<Theme>"
|
|
134
|
-
},
|
|
135
|
-
"slotProps": {
|
|
136
|
-
"description": "Props passed to internal sub-components (field, textField, openPickerButton, clearButton, etc.). Use `textField.variant` to switch between \"standard\" and \"outlined\".",
|
|
137
|
-
"control": "object",
|
|
138
|
-
"category": "customization",
|
|
139
|
-
"type": "object"
|
|
140
|
-
},
|
|
141
|
-
"className": {
|
|
142
|
-
"description": "CSS class name applied to the root element.",
|
|
143
|
-
"control": "text",
|
|
144
|
-
"category": "customization",
|
|
145
|
-
"type": "string"
|
|
146
|
-
},
|
|
147
|
-
"dataTestIdSuffix": {
|
|
148
|
-
"description": "Optional suffix for the generated test id (base: ring-date-picker).",
|
|
149
|
-
"control": "text",
|
|
150
|
-
"category": "customization",
|
|
151
|
-
"type": "string"
|
|
152
|
-
},
|
|
153
|
-
"label": {
|
|
154
|
-
"description": "Floating label text displayed above the input field.",
|
|
155
|
-
"control": "text",
|
|
156
|
-
"category": "content",
|
|
157
|
-
"type": "string"
|
|
158
|
-
},
|
|
159
|
-
"currentDateLabel": {
|
|
160
|
-
"description": "Label for the \"Now\" shortcut button in the calendar popup. When set, a button appears that selects the current date.",
|
|
161
|
-
"control": "text",
|
|
162
|
-
"category": "content",
|
|
163
|
-
"type": "string"
|
|
164
|
-
},
|
|
165
|
-
"actions": {
|
|
166
|
-
"description": "Custom action buttons displayed at the end of the input field.",
|
|
167
|
-
"control": "object",
|
|
168
|
-
"category": "behavior",
|
|
169
|
-
"type": "Action[]"
|
|
170
|
-
},
|
|
171
|
-
"disabled": {
|
|
172
|
-
"description": "Disables the date picker input and calendar button.",
|
|
173
|
-
"control": "boolean",
|
|
174
|
-
"category": "behavior",
|
|
175
|
-
"type": "boolean",
|
|
176
|
-
"defaultValue": "false"
|
|
177
|
-
},
|
|
178
|
-
"defaultValue": {
|
|
179
|
-
"description": "Initial date value. Accepts a dayjs instance.",
|
|
180
|
-
"control": false,
|
|
181
|
-
"category": "state",
|
|
182
|
-
"type": "Dayjs"
|
|
183
|
-
},
|
|
184
|
-
"value": {
|
|
185
|
-
"description": "Controlled date value. Use with `onChange` for controlled mode.",
|
|
186
|
-
"control": false,
|
|
187
|
-
"category": "state",
|
|
188
|
-
"type": "Dayjs"
|
|
189
|
-
},
|
|
190
|
-
"onChange": {
|
|
191
|
-
"description": "Callback fired when the date value changes.",
|
|
192
|
-
"category": "callbacks",
|
|
193
|
-
"type": "(value: Dayjs | null) => void"
|
|
194
|
-
},
|
|
195
|
-
"onAccept": {
|
|
196
|
-
"description": "Callback fired when the date is accepted (calendar closed or date selected).",
|
|
197
|
-
"category": "callbacks",
|
|
198
|
-
"type": "(value: Dayjs | null) => void"
|
|
199
|
-
},
|
|
200
|
-
"onOpen": {
|
|
201
|
-
"description": "Callback fired when the calendar popup opens.",
|
|
202
|
-
"category": "callbacks",
|
|
203
|
-
"type": "() => void"
|
|
204
|
-
},
|
|
205
|
-
"onClose": {
|
|
206
|
-
"description": "Callback fired when the calendar popup closes.",
|
|
207
|
-
"category": "callbacks",
|
|
208
|
-
"type": "() => void"
|
|
209
|
-
}
|
|
210
|
-
},
|
|
211
|
-
"storyNames": [
|
|
212
|
-
"Default",
|
|
213
|
-
"Disabled",
|
|
214
|
-
"CustomStyles",
|
|
215
|
-
"DefaultValue",
|
|
216
|
-
"Label",
|
|
217
|
-
"Actions",
|
|
218
|
-
"NowButton",
|
|
219
|
-
"Outlined"
|
|
220
|
-
],
|
|
221
|
-
"docs": "# DatePicker\n\nA date selection component that wraps MUI's [DatePicker](https://mui.com/x/react-date-pickers/date-picker/) with Ring Design System styling. Provides a calendar popup for selecting a single date with built-in support for clearable input, custom actions, and a \"Now\" shortcut button.\n\n- Clearable input with calendar icon\n- Configurable label\n- Custom action buttons (e.g., copy, share) via the `actions` prop\n- Quick-select \"Now\" button via `currentDateLabel`\n- Extends all MUI DatePicker props\n- Supports `sx` and `className` for custom styling\n\n## Prerequisites\n\nDatePicker requires a `LocalizationProvider` wrapper with a date adapter. Set this up once at the root of your application:\n\n```tsx\n\nfunction App() {\n return (\n <LocalizationProvider dateAdapter={AdapterDayjs} adapterLocale=\"en\">\n {/* Your app content */}\n </LocalizationProvider>\n );\n}\n```\n\n## Default\n\nBasic date picker with clearable input.\n\n```tsx\n// DefaultExample.tsx\nimport React from 'react';\nimport { DatePicker } from '@ringpublishing/mui-components';\n\nexport default function DefaultExample(): React.JSX.Element {\n return <DatePicker />;\n}\n```\n\n## Disabled\n\nUse the `disabled` prop to prevent user interaction. The picker input and calendar button become non-interactive.\n\n```tsx\n// DisabledExample.tsx\nimport React from 'react';\nimport { DatePicker } from '@ringpublishing/mui-components';\n\nexport default function DisabledExample(): React.JSX.Element {\n return <DatePicker disabled={true} />;\n}\n```\n\n## Custom Styles\n\nApply custom styles using the `sx` prop. The component accepts all MUI system properties for flexible styling.\n\n```tsx\n// CustomStylesExample.tsx\nimport React from 'react';\nimport { DatePicker } from '@ringpublishing/mui-components';\n\nexport default function CustomStylesExample(): React.JSX.Element {\n return (\n <DatePicker\n sx={{\n backgroundColor: 'lightgray',\n padding: '8px',\n borderRadius: '4px',\n }}\n />\n );\n}\n```\n\n## Default Value\n\nSet an initial date using `defaultValue` with a `dayjs` instance. The user can still change or clear the value.\n\n```tsx\n// DefaultValueExample.tsx\nimport React from 'react';\nimport { DatePicker } from '@ringpublishing/mui-components';\nimport dayjs from 'dayjs';\n\nexport default function DefaultValueExample(): React.JSX.Element {\n return <DatePicker defaultValue={dayjs()} />;\n}\n```\n\n## Label\n\nUse the `label` prop to add a floating label above the input. This helps users understand what the date field represents in a form context.\n\n```tsx\n// LabelExample.tsx\nimport React from 'react';\nimport { DatePicker } from '@ringpublishing/mui-components';\n\nexport default function LabelExample(): React.JSX.Element {\n return <DatePicker label=\"Date\" />;\n}\n```\n\n## Actions\n\nAdd custom action buttons next to the input using the `actions` prop. Each action requires a `label` and an `onClick` handler. Actions appear as icon buttons at the end of the input field.\n\n```tsx\n<DatePicker\n actions={[\n { label: 'Copy', onClick: () => handleCopy() },\n { label: 'Share', onClick: () => handleShare() },\n ]}\n/>\n```\n\n```tsx\n// ActionsExample.tsx\nimport React from 'react';\nimport { DatePicker } from '@ringpublishing/mui-components';\n\nexport default function ActionsExample(): React.JSX.Element {\n return (\n <DatePicker\n actions={[\n {\n label: 'Copy',\n onClick: () => {\n // Handle copy action\n },\n },\n {\n label: 'Share',\n onClick: () => {\n // Handle share action\n },\n },\n ]}\n />\n );\n}\n```\n\n## Now Button\n\nSet `currentDateLabel` to display a shortcut button in the calendar popup that selects the current date. Useful for forms where \"today\" is a common selection.\n\n```tsx\n<DatePicker currentDateLabel=\"Now\" />\n```\n\n```tsx\n// NowButtonExample.tsx\nimport React from 'react';\nimport { DatePicker } from '@ringpublishing/mui-components';\n\nexport default function NowButtonExample(): React.JSX.Element {\n return <DatePicker currentDateLabel=\"Now\" />;\n}\n```\n\n## Outlined\n\nUse the `outlined` variant via `slotProps.textField` for a bordered input style. The floating label appears inside the border and moves to the top edge when focused or when a value is present.\n\n```tsx\n<DatePicker\n label=\"Date\"\n slotProps={{\n textField: {\n variant: 'outlined',\n },\n }}\n/>\n```\n\n```tsx\n// OutlinedExample.tsx\nimport React from 'react';\nimport { DatePicker } from '@ringpublishing/mui-components';\n\nexport default function OutlinedExample(): React.JSX.Element {\n return (\n <DatePicker\n label=\"Date\"\n slotProps={{\n textField: {\n variant: 'outlined',\n },\n }}\n />\n );\n}\n```\n\n## Related Components\n\n- **DateTimePicker** — for selecting both date and time\n- **TimePicker** — for selecting time only"
|
|
222
|
-
},
|
|
223
|
-
"atoms-dates-date-time-picker": {
|
|
224
|
-
"id": "atoms-dates-date-time-picker",
|
|
225
|
-
"name": "DateTimePicker",
|
|
226
|
-
"category": "Atoms",
|
|
227
|
-
"title": "Components/Atoms/Dates/DateTimePicker",
|
|
228
|
-
"description": "A combined date and time selection component that wraps MUI's [DateTimePicker](https://mui.com/x/react-date-pickers/date-time-picker/) with Ring Design System styling. Allows users to pick both a date and time in a single input with a unified popup.",
|
|
229
|
-
"argTypes": {
|
|
230
|
-
"sx": {
|
|
231
|
-
"description": "MUI System properties to customize the component style.",
|
|
232
|
-
"control": "object",
|
|
233
|
-
"category": "customization",
|
|
234
|
-
"type": "SxProps<Theme>"
|
|
235
|
-
},
|
|
236
|
-
"slotProps": {
|
|
237
|
-
"description": "Props passed to internal sub-components (field, textField, openPickerButton, clearButton, etc.). Use `textField.variant` to switch between \"standard\" and \"outlined\".",
|
|
238
|
-
"control": "object",
|
|
239
|
-
"category": "customization",
|
|
240
|
-
"type": "object"
|
|
241
|
-
},
|
|
242
|
-
"className": {
|
|
243
|
-
"description": "CSS class name applied to the root element.",
|
|
244
|
-
"control": "text",
|
|
245
|
-
"category": "customization",
|
|
246
|
-
"type": "string"
|
|
247
|
-
},
|
|
248
|
-
"dataTestIdSuffix": {
|
|
249
|
-
"description": "Optional suffix for the generated test id (base: ring-date-time-picker).",
|
|
250
|
-
"control": "text",
|
|
251
|
-
"category": "customization",
|
|
252
|
-
"type": "string"
|
|
253
|
-
},
|
|
254
|
-
"label": {
|
|
255
|
-
"description": "Floating label text displayed above the input field.",
|
|
256
|
-
"control": "text",
|
|
257
|
-
"category": "content",
|
|
258
|
-
"type": "string"
|
|
259
|
-
},
|
|
260
|
-
"actions": {
|
|
261
|
-
"description": "Custom action buttons displayed at the end of the input field.",
|
|
262
|
-
"control": "object",
|
|
263
|
-
"category": "behavior",
|
|
264
|
-
"type": "Action[]"
|
|
265
|
-
},
|
|
266
|
-
"disabled": {
|
|
267
|
-
"description": "Disables the date-time picker input and calendar button.",
|
|
268
|
-
"control": "boolean",
|
|
269
|
-
"category": "behavior",
|
|
270
|
-
"type": "boolean",
|
|
271
|
-
"defaultValue": "false"
|
|
272
|
-
},
|
|
273
|
-
"defaultValue": {
|
|
274
|
-
"description": "Initial date-time value. Accepts a dayjs instance.",
|
|
275
|
-
"control": false,
|
|
276
|
-
"category": "state",
|
|
277
|
-
"type": "Dayjs"
|
|
278
|
-
},
|
|
279
|
-
"value": {
|
|
280
|
-
"description": "Controlled date-time value. Use with `onChange` for controlled mode.",
|
|
281
|
-
"control": false,
|
|
282
|
-
"category": "state",
|
|
283
|
-
"type": "Dayjs"
|
|
284
|
-
},
|
|
285
|
-
"onChange": {
|
|
286
|
-
"description": "Callback fired when the date-time value changes.",
|
|
287
|
-
"category": "callbacks",
|
|
288
|
-
"type": "(value: Dayjs | null) => void"
|
|
289
|
-
},
|
|
290
|
-
"onAccept": {
|
|
291
|
-
"description": "Callback fired when the date-time is accepted (popup closed or value selected).",
|
|
292
|
-
"category": "callbacks",
|
|
293
|
-
"type": "(value: Dayjs | null) => void"
|
|
294
|
-
},
|
|
295
|
-
"onOpen": {
|
|
296
|
-
"description": "Callback fired when the calendar popup opens.",
|
|
297
|
-
"category": "callbacks",
|
|
298
|
-
"type": "() => void"
|
|
299
|
-
},
|
|
300
|
-
"onClose": {
|
|
301
|
-
"description": "Callback fired when the calendar popup closes.",
|
|
302
|
-
"category": "callbacks",
|
|
303
|
-
"type": "() => void"
|
|
304
|
-
}
|
|
305
|
-
},
|
|
306
|
-
"storyNames": [
|
|
307
|
-
"Default",
|
|
308
|
-
"Disabled",
|
|
309
|
-
"CustomStyles",
|
|
310
|
-
"DefaultValue",
|
|
311
|
-
"Label",
|
|
312
|
-
"Actions",
|
|
313
|
-
"Outlined"
|
|
314
|
-
],
|
|
315
|
-
"docs": "# DateTimePicker\n\nA combined date and time selection component that wraps MUI's [DateTimePicker](https://mui.com/x/react-date-pickers/date-time-picker/) with Ring Design System styling. Allows users to pick both a date and time in a single input with a unified popup.\n\n- Clearable input with calendar icon\n- Combined date and time selection in one popup\n- Configurable label\n- Custom action buttons via the `actions` prop\n- Extends all MUI DateTimePicker props\n- Supports `sx` and `className` for custom styling\n\n## Prerequisites\n\nDateTimePicker requires a `LocalizationProvider` wrapper with a date adapter. Set this up once at the root of your application:\n\n```tsx\n\nfunction App() {\n return (\n <LocalizationProvider dateAdapter={AdapterDayjs} adapterLocale=\"en\">\n {/* Your app content */}\n </LocalizationProvider>\n );\n}\n```\n\n## Default\n\nBasic date-time picker with clearable input.\n\n```tsx\n// DefaultExample.tsx\nimport React from 'react';\nimport { DateTimePicker } from '@ringpublishing/mui-components';\n\nexport default function DefaultExample(): React.JSX.Element {\n return <DateTimePicker />;\n}\n```\n\n## Disabled\n\nUse the `disabled` prop to prevent user interaction. The picker input and calendar button become non-interactive.\n\n```tsx\n// DisabledExample.tsx\nimport React from 'react';\nimport { DateTimePicker } from '@ringpublishing/mui-components';\n\nexport default function DisabledExample(): React.JSX.Element {\n return <DateTimePicker disabled={true} />;\n}\n```\n\n## Custom Styles\n\nApply custom styles using the `sx` prop. The component accepts all MUI system properties for flexible styling.\n\n```tsx\n// CustomStylesExample.tsx\nimport React from 'react';\nimport { DateTimePicker } from '@ringpublishing/mui-components';\n\nexport default function CustomStylesExample(): React.JSX.Element {\n return (\n <DateTimePicker\n sx={{\n backgroundColor: 'lightgray',\n padding: '8px',\n borderRadius: '4px',\n }}\n />\n );\n}\n```\n\n## Default Value\n\nSet an initial date and time using `defaultValue` with a `dayjs` instance. The user can still change or clear the value.\n\n```tsx\n// DefaultValueExample.tsx\nimport React from 'react';\nimport { DateTimePicker } from '@ringpublishing/mui-components';\nimport dayjs from 'dayjs';\n\nexport default function DefaultValueExample(): React.JSX.Element {\n return <DateTimePicker defaultValue={dayjs()} />;\n}\n```\n\n## Label\n\nUse the `label` prop to add a floating label above the input. This helps users understand what the field represents in a form context.\n\n```tsx\n// LabelExample.tsx\nimport React from 'react';\nimport { DateTimePicker } from '@ringpublishing/mui-components';\n\nexport default function LabelExample(): React.JSX.Element {\n return <DateTimePicker label=\"Date and time\" />;\n}\n```\n\n## Actions\n\nAdd custom action buttons next to the input using the `actions` prop. Each action requires a `label` and an `onClick` handler. Actions appear as icon buttons at the end of the input field.\n\n```tsx\n<DateTimePicker\n actions={[\n { label: 'Copy', onClick: () => handleCopy() },\n { label: 'Share', onClick: () => handleShare() },\n ]}\n/>\n```\n\n```tsx\n// ActionsExample.tsx\nimport React from 'react';\nimport { DateTimePicker } from '@ringpublishing/mui-components';\n\nexport default function ActionsExample(): React.JSX.Element {\n return (\n <DateTimePicker\n actions={[\n {\n label: 'Copy',\n onClick: () => {\n // Handle copy action\n },\n },\n {\n label: 'Share',\n onClick: () => {\n // Handle share action\n },\n },\n ]}\n />\n );\n}\n```\n\n## Outlined\n\nUse the `outlined` variant via `slotProps.textField` for a bordered input style. The floating label appears inside the border and moves to the top edge when focused or when a value is present.\n\n```tsx\n<DateTimePicker\n label=\"Date & Time\"\n slotProps={{\n textField: {\n variant: 'outlined',\n },\n }}\n/>\n```\n\n```tsx\n// OutlinedExample.tsx\nimport React from 'react';\nimport { DateTimePicker } from '@ringpublishing/mui-components';\n\nexport default function OutlinedExample(): React.JSX.Element {\n return (\n <DateTimePicker\n label=\"Date & Time\"\n slotProps={{\n textField: {\n variant: 'outlined',\n },\n }}\n />\n );\n}\n```\n\n## Related Components\n\n- **DatePicker** — for selecting date only (also supports a \"Now\" shortcut button)\n- **TimePicker** — for selecting time only"
|
|
316
|
-
},
|
|
317
|
-
"atoms-dates-time-picker": {
|
|
318
|
-
"id": "atoms-dates-time-picker",
|
|
319
|
-
"name": "TimePicker",
|
|
320
|
-
"category": "Atoms",
|
|
321
|
-
"title": "Components/Atoms/Dates/TimePicker",
|
|
322
|
-
"description": "A time selection component that wraps MUI's [TimePicker](https://mui.com/x/react-date-pickers/time-picker/) with Ring Design System styling. Provides a clock popup for selecting hours and minutes with built-in support for clearable input.",
|
|
323
|
-
"argTypes": {
|
|
324
|
-
"sx": {
|
|
325
|
-
"description": "MUI System properties to customize the component style.",
|
|
326
|
-
"control": "object",
|
|
327
|
-
"category": "customization",
|
|
328
|
-
"type": "SxProps<Theme>"
|
|
329
|
-
},
|
|
330
|
-
"slotProps": {
|
|
331
|
-
"description": "Props passed to internal sub-components (field, textField, openPickerButton, clearButton, etc.). Use `textField.variant` to switch between \"standard\" and \"outlined\".",
|
|
332
|
-
"control": "object",
|
|
333
|
-
"category": "customization",
|
|
334
|
-
"type": "object"
|
|
335
|
-
},
|
|
336
|
-
"className": {
|
|
337
|
-
"description": "CSS class name applied to the root element.",
|
|
338
|
-
"control": "text",
|
|
339
|
-
"category": "customization",
|
|
340
|
-
"type": "string"
|
|
341
|
-
},
|
|
342
|
-
"dataTestIdSuffix": {
|
|
343
|
-
"description": "Optional suffix for the generated test id (base: ring-time-picker).",
|
|
344
|
-
"control": "text",
|
|
345
|
-
"category": "customization",
|
|
346
|
-
"type": "string"
|
|
347
|
-
},
|
|
348
|
-
"label": {
|
|
349
|
-
"description": "Floating label text displayed above the input field.",
|
|
350
|
-
"control": "text",
|
|
351
|
-
"category": "content",
|
|
352
|
-
"type": "string"
|
|
353
|
-
},
|
|
354
|
-
"disabled": {
|
|
355
|
-
"description": "Disables the time picker input and clock button.",
|
|
356
|
-
"control": "boolean",
|
|
357
|
-
"category": "behavior",
|
|
358
|
-
"type": "boolean",
|
|
359
|
-
"defaultValue": "false"
|
|
360
|
-
},
|
|
361
|
-
"defaultValue": {
|
|
362
|
-
"description": "Initial time value. Accepts a dayjs instance.",
|
|
363
|
-
"control": false,
|
|
364
|
-
"category": "state",
|
|
365
|
-
"type": "Dayjs"
|
|
366
|
-
},
|
|
367
|
-
"value": {
|
|
368
|
-
"description": "Controlled time value. Use with `onChange` for controlled mode.",
|
|
369
|
-
"control": false,
|
|
370
|
-
"category": "state",
|
|
371
|
-
"type": "Dayjs"
|
|
372
|
-
},
|
|
373
|
-
"onChange": {
|
|
374
|
-
"description": "Callback fired when the time value changes.",
|
|
375
|
-
"category": "callbacks",
|
|
376
|
-
"type": "(value: Dayjs | null) => void"
|
|
377
|
-
},
|
|
378
|
-
"onAccept": {
|
|
379
|
-
"description": "Callback fired when the time is accepted (popup closed or value selected).",
|
|
380
|
-
"category": "callbacks",
|
|
381
|
-
"type": "(value: Dayjs | null) => void"
|
|
382
|
-
},
|
|
383
|
-
"onOpen": {
|
|
384
|
-
"description": "Callback fired when the clock popup opens.",
|
|
385
|
-
"category": "callbacks",
|
|
386
|
-
"type": "() => void"
|
|
387
|
-
},
|
|
388
|
-
"onClose": {
|
|
389
|
-
"description": "Callback fired when the clock popup closes.",
|
|
390
|
-
"category": "callbacks",
|
|
391
|
-
"type": "() => void"
|
|
392
|
-
}
|
|
393
|
-
},
|
|
394
|
-
"storyNames": [
|
|
395
|
-
"Default",
|
|
396
|
-
"Disabled",
|
|
397
|
-
"CustomStyles",
|
|
398
|
-
"DefaultValue",
|
|
399
|
-
"Label",
|
|
400
|
-
"Outlined",
|
|
401
|
-
"Comparison"
|
|
402
|
-
],
|
|
403
|
-
"docs": "# TimePicker\n\nA time selection component that wraps MUI's [TimePicker](https://mui.com/x/react-date-pickers/time-picker/) with Ring Design System styling. Provides a clock popup for selecting hours and minutes with built-in support for clearable input.\n\n- Clearable input with clock icon\n- Configurable label\n- Extends all MUI TimePicker props\n- Supports `sx` and `className` for custom styling\n\n## Prerequisites\n\nTimePicker requires a `LocalizationProvider` wrapper with a date adapter. Set this up once at the root of your application:\n\n```tsx\n\nfunction App() {\n return (\n <LocalizationProvider dateAdapter={AdapterDayjs} adapterLocale=\"en\">\n {/* Your app content */}\n </LocalizationProvider>\n );\n}\n```\n\n## Default\n\nBasic time picker with clearable input.\n\n```tsx\n// DefaultExample.tsx\nimport React from 'react';\nimport { TimePicker } from '@ringpublishing/mui-components';\n\nexport default function DefaultExample(): React.JSX.Element {\n return <TimePicker />;\n}\n```\n\n## Disabled\n\nUse the `disabled` prop to prevent user interaction. The picker input and clock button become non-interactive.\n\n```tsx\n// DisabledExample.tsx\nimport React from 'react';\nimport { TimePicker } from '@ringpublishing/mui-components';\n\nexport default function DisabledExample(): React.JSX.Element {\n return <TimePicker disabled={true} />;\n}\n```\n\n## Custom Styles\n\nApply custom styles using the `sx` prop. The component accepts all MUI system properties for flexible styling.\n\n```tsx\n// CustomStylesExample.tsx\nimport React from 'react';\nimport { TimePicker } from '@ringpublishing/mui-components';\n\nexport default function CustomStylesExample(): React.JSX.Element {\n return (\n <TimePicker\n sx={{\n backgroundColor: 'lightgray',\n padding: '8px',\n borderRadius: '4px',\n }}\n />\n );\n}\n```\n\n## Default Value\n\nSet an initial time using `defaultValue` with a `dayjs` instance. The user can still change or clear the value.\n\n```tsx\n// DefaultValueExample.tsx\nimport React from 'react';\nimport { TimePicker } from '@ringpublishing/mui-components';\nimport dayjs from 'dayjs';\n\nexport default function DefaultValueExample(): React.JSX.Element {\n return <TimePicker defaultValue={dayjs()} />;\n}\n```\n\n## Label\n\nUse the `label` prop to add a floating label above the input. This helps users understand what the time field represents in a form context.\n\n```tsx\n// LabelExample.tsx\nimport React from 'react';\nimport { TimePicker } from '@ringpublishing/mui-components';\n\nexport default function LabelExample(): React.JSX.Element {\n return <TimePicker label=\"Time\" />;\n}\n```\n\n## Outlined\n\nUse the `outlined` variant via `slotProps.textField` for a bordered input style. The floating label appears inside the border and moves to the top edge when focused or when a value is present.\n\n```tsx\n<TimePicker\n label=\"Time\"\n slotProps={{\n textField: {\n variant: 'outlined',\n },\n }}\n/>\n```\n\n```tsx\n// OutlinedExample.tsx\nimport React from 'react';\nimport { TimePicker } from '@ringpublishing/mui-components';\n\nexport default function OutlinedExample(): React.JSX.Element {\n return (\n <TimePicker\n label=\"Time\"\n slotProps={{\n textField: {\n variant: 'outlined',\n },\n }}\n />\n );\n}\n```\n\n## Related Components\n\n- **DatePicker** — for selecting date only (also supports custom actions and a \"Now\" shortcut button)\n- **DateTimePicker** — for selecting both date and time"
|
|
404
|
-
},
|
|
405
|
-
"atoms-editable-text": {
|
|
406
|
-
"id": "atoms-editable-text",
|
|
407
|
-
"name": "EditableText",
|
|
408
|
-
"category": "Atoms",
|
|
409
|
-
"title": "Components/Atoms/EditableText",
|
|
410
|
-
"description": "An inline editable text component that renders as plain text with an edit button, and switches to a text field when the user activates edit mode.",
|
|
411
|
-
"argTypes": {
|
|
412
|
-
"text": {
|
|
413
|
-
"description": "The initial text to be displayed.",
|
|
414
|
-
"control": "text",
|
|
415
|
-
"category": "content",
|
|
416
|
-
"type": "string"
|
|
417
|
-
},
|
|
418
|
-
"label": {
|
|
419
|
-
"description": "Optional label for the TextField shown in edit mode.",
|
|
420
|
-
"control": "text",
|
|
421
|
-
"category": "content",
|
|
422
|
-
"type": "string"
|
|
423
|
-
},
|
|
424
|
-
"onSubmit": {
|
|
425
|
-
"description": "Callback invoked when the user submits the edited text. Should return a Promise resolving to true on success or false on failure. On failure, the text reverts to its previous value.",
|
|
426
|
-
"category": "callbacks",
|
|
427
|
-
"type": "(value: string) => Promise<boolean>"
|
|
428
|
-
},
|
|
429
|
-
"slotProps": {
|
|
430
|
-
"description": "Props to customize internal component slots. `typography` accepts MUI TypographyProps (except `children`) and is applied to the text in display mode. `textField` accepts MUI TextFieldProps (except `value`, `onChange`, `autoFocus`) and is applied to the input in edit mode.",
|
|
431
|
-
"control": "object",
|
|
432
|
-
"category": "customization",
|
|
433
|
-
"type": "EditableTextSlotProps"
|
|
434
|
-
},
|
|
435
|
-
"sx": {
|
|
436
|
-
"description": "MUI sx prop for custom styling of the root element.",
|
|
437
|
-
"control": "object",
|
|
438
|
-
"category": "customization",
|
|
439
|
-
"type": "SxProps"
|
|
440
|
-
},
|
|
441
|
-
"className": {
|
|
442
|
-
"description": "CSS class name applied to the root element.",
|
|
443
|
-
"control": "text",
|
|
444
|
-
"category": "customization",
|
|
445
|
-
"type": "string"
|
|
446
|
-
},
|
|
447
|
-
"dataTestIdSuffix": {
|
|
448
|
-
"description": "Suffix appended to the data-testid attribute.",
|
|
449
|
-
"control": "text",
|
|
450
|
-
"category": "customization",
|
|
451
|
-
"type": "string"
|
|
452
|
-
}
|
|
453
|
-
},
|
|
454
|
-
"storyNames": [
|
|
455
|
-
"Default",
|
|
456
|
-
"WithLabel",
|
|
457
|
-
"WithSubmitFailure"
|
|
458
|
-
],
|
|
459
|
-
"docs": "# EditableText\n\nAn inline editable text component that renders as plain text with an edit button, and switches to a text field when the user activates edit mode.\n\n**Key Features:**\n\n- Toggle between display and edit mode with a single click\n- Submit changes on click away or Enter key\n- Cancel changes with the Escape key\n- Automatic revert on failed submission\n- Optional label for the input field in edit mode\n- Customizable internal slots via `slotProps` (Typography and TextField)\n\n**Keyboard shortcuts (in edit mode):**\n\n- `Enter` — submit changes\n- `Escape` — cancel and revert to previous value\n\n## Default\n\nBasic usage: click the edit icon to enter edit mode, modify the text, then click away or press Enter to save.\n\n```tsx\n// DefaultExample.tsx\nimport React, { useState } from 'react';\nimport { EditableText } from '@ringpublishing/mui-components';\n\nexport default function DefaultExample(): React.JSX.Element {\n const [text, setText] = useState('Editable text value');\n\n const handleSubmit = (value: string): Promise<boolean> => {\n setText(value);\n\n return Promise.resolve(true);\n };\n\n return <EditableText text={text} onSubmit={handleSubmit} />;\n}\n```\n\n## With Label\n\nThe optional `label` prop adds a floating label to the input field in edit mode, providing additional context to the user.\n\n```tsx\n// WithLabelExample.tsx\nimport React, { useState } from 'react';\nimport { EditableText } from '@ringpublishing/mui-components';\n\nexport default function WithLabelExample(): React.JSX.Element {\n const [text, setText] = useState('Editable text value');\n\n const handleSubmit = (value: string): Promise<boolean> => {\n setText(value);\n\n return Promise.resolve(true);\n };\n\n return <EditableText text={text} label=\"Article title\" onSubmit={handleSubmit} />;\n}\n```\n\n## With Submit Failure\n\nWhen `onSubmit` returns `false`, the component automatically reverts the text to its previous value. This demonstrates how the component handles API errors or validation failures.\n\n```tsx\n// WithSubmitFailureExample.tsx\nimport React from 'react';\nimport { EditableText } from '@ringpublishing/mui-components';\nimport { Box } from '@mui/material';\n\nexport default function WithSubmitFailureExample(): React.JSX.Element {\n const handleSubmit = (_value: string): Promise<boolean> => {\n // Simulate a failed submission — text will revert to the previous value\n return Promise.resolve(false);\n };\n\n return (\n <Box sx={{ width: 300 }}>\n <EditableText\n text=\"Try editing me, changes will not be saved\"\n onSubmit={handleSubmit}\n slotProps={{\n textField: {\n fullWidth: true,\n },\n }}\n />\n </Box>\n );\n}\n```"
|
|
460
|
-
},
|
|
461
|
-
"atoms-text-field": {
|
|
462
|
-
"id": "atoms-text-field",
|
|
463
|
-
"name": "TextField",
|
|
464
|
-
"category": "Atoms",
|
|
465
|
-
"title": "Components/Atoms/TextField",
|
|
466
|
-
"description": "TextField extends [MUI Text Field](https://mui.com/material-ui/react-text-field) component and supports all its properties. It adds support for contextual **actions** rendered as icon buttons in the field's end adornment.",
|
|
467
|
-
"argTypes": {
|
|
468
|
-
"actions": {
|
|
469
|
-
"description": "Array of actions rendered as icon buttons in the end adornment. A single action shows a standalone button with tooltip; multiple actions collapse into a MoreVert menu.",
|
|
470
|
-
"control": "object",
|
|
471
|
-
"category": "content",
|
|
472
|
-
"type": "Action[]"
|
|
473
|
-
},
|
|
474
|
-
"sx": {
|
|
475
|
-
"description": "The system prop that allows defining system overrides as well as additional CSS styles.",
|
|
476
|
-
"control": "object",
|
|
477
|
-
"category": "customization",
|
|
478
|
-
"type": "SxProps<Theme>"
|
|
479
|
-
},
|
|
480
|
-
"className": {
|
|
481
|
-
"description": "CSS class name applied to the root element.",
|
|
482
|
-
"control": "text",
|
|
483
|
-
"category": "customization",
|
|
484
|
-
"type": "string"
|
|
485
|
-
},
|
|
486
|
-
"InputProps": {
|
|
487
|
-
"description": "Props applied to the Input element.",
|
|
488
|
-
"control": false,
|
|
489
|
-
"category": "customization",
|
|
490
|
-
"type": "Partial<OutlinedInputProps>"
|
|
491
|
-
},
|
|
492
|
-
"InputLabelProps": {
|
|
493
|
-
"description": "Props applied to the InputLabel element.",
|
|
494
|
-
"control": false,
|
|
495
|
-
"category": "customization",
|
|
496
|
-
"type": "Partial<InputLabelProps>"
|
|
497
|
-
},
|
|
498
|
-
"variant": {
|
|
499
|
-
"description": "The variant to use.",
|
|
500
|
-
"control": "select",
|
|
501
|
-
"category": "appearance",
|
|
502
|
-
"type": "'outlined' | 'filled' | 'standard'",
|
|
503
|
-
"defaultValue": "outlined",
|
|
504
|
-
"options": [
|
|
505
|
-
"outlined",
|
|
506
|
-
"filled",
|
|
507
|
-
"standard"
|
|
508
|
-
]
|
|
509
|
-
},
|
|
510
|
-
"size": {
|
|
511
|
-
"description": "The size of the component.",
|
|
512
|
-
"control": "select",
|
|
513
|
-
"category": "appearance",
|
|
514
|
-
"type": "'small' | 'medium'",
|
|
515
|
-
"defaultValue": "medium",
|
|
516
|
-
"options": [
|
|
517
|
-
"small",
|
|
518
|
-
"medium"
|
|
519
|
-
]
|
|
520
|
-
},
|
|
521
|
-
"disabled": {
|
|
522
|
-
"description": "If true, the component is disabled.",
|
|
523
|
-
"control": "boolean",
|
|
524
|
-
"category": "state",
|
|
525
|
-
"type": "boolean",
|
|
526
|
-
"defaultValue": "false"
|
|
527
|
-
},
|
|
528
|
-
"placeholder": {
|
|
529
|
-
"description": "The short hint displayed in the input before the user enters a value.",
|
|
530
|
-
"control": "text",
|
|
531
|
-
"category": "content",
|
|
532
|
-
"type": "string"
|
|
533
|
-
},
|
|
534
|
-
"dataTestIdSuffix": {
|
|
535
|
-
"description": "Suffix appended to the data-testid attribute. Results in ring-textfield-{suffix}.",
|
|
536
|
-
"control": "text",
|
|
537
|
-
"category": "testing",
|
|
538
|
-
"type": "string"
|
|
539
|
-
}
|
|
540
|
-
},
|
|
541
|
-
"storyNames": [
|
|
542
|
-
"Default",
|
|
543
|
-
"WithMultipleActions",
|
|
544
|
-
"Controlled"
|
|
545
|
-
],
|
|
546
|
-
"docs": "# TextField\n\nTextField extends [MUI Text Field](https://mui.com/material-ui/react-text-field) component and supports all its properties. It adds support for contextual **actions** rendered as icon buttons in the field's end adornment.\n\n**Key Features:**\n\n- Single action rendered as a standalone icon button with tooltip\n- Multiple actions collapsed into a `MoreVert` menu via `ActionBox`\n- Full MUI TextField API support (variants, sizes, states, etc.)\n- Controlled and uncontrolled usage patterns\n\n## Default\n\nBasic usage with a single action button displayed in the end adornment.\n\n```tsx\n// DefaultExample.tsx\nimport React from 'react';\nimport { TextField } from '@ringpublishing/mui-components';\nimport { ManageSearch } from '@mui/icons-material';\n\nexport default function DefaultExample(): React.JSX.Element {\n return (\n <TextField\n label=\"Search\"\n sx={{ minWidth: '180px' }}\n actions={[\n {\n icon: <ManageSearch />,\n onClick: () => {},\n label: 'Settings',\n },\n ]}\n />\n );\n}\n```\n\n## With Multiple Actions\n\nWhen more than one action is provided, they are collapsed into a `MoreVert` dropdown menu.\n\n```tsx\n// WithMultipleActionsExample.tsx\nimport React from 'react';\nimport { TextField } from '@ringpublishing/mui-components';\nimport { InfoOutlined, ManageSearch } from '@mui/icons-material';\n\nexport default function WithMultipleActionsExample(): React.JSX.Element {\n return (\n <TextField\n label=\"Search\"\n sx={{ minWidth: '180px' }}\n actions={[\n {\n icon: <ManageSearch />,\n onClick: () => {},\n label: 'Settings',\n },\n {\n icon: <InfoOutlined />,\n onClick: () => {},\n label: 'Info',\n },\n ]}\n />\n );\n}\n```\n\n## Controlled\n\nA controlled TextField that dynamically shows a clear button when the field has a value.\n\n```tsx\n// ControlledExample.tsx\nimport React, { ChangeEvent, useState } from 'react';\nimport { TextField } from '@ringpublishing/mui-components';\nimport { ClearOutlined } from '@mui/icons-material';\n\nexport default function ControlledExample(): React.JSX.Element {\n const [value, setValue] = useState('');\n\n function handleOnChange(event: ChangeEvent<HTMLInputElement>): void {\n setValue(event.target.value);\n }\n\n return (\n <TextField\n label=\"Search\"\n value={value}\n onChange={handleOnChange}\n sx={{ minWidth: '180px' }}\n actions={\n value\n ? [\n {\n icon: <ClearOutlined />,\n onClick: () => setValue(''),\n label: 'Clear',\n },\n ]\n : []\n }\n />\n );\n}\n```"
|
|
547
|
-
},
|
|
548
|
-
"atoms-tooltip": {
|
|
549
|
-
"id": "atoms-tooltip",
|
|
550
|
-
"name": "Tooltip",
|
|
551
|
-
"category": "Atoms",
|
|
552
|
-
"title": "Components/Atoms/Tooltip",
|
|
553
|
-
"description": "An enhanced tooltip component built on MUI Tooltip that supports structured content with a title, optional subtitle, and optional hint.",
|
|
554
|
-
"argTypes": {
|
|
555
|
-
"title": {
|
|
556
|
-
"description": "The main title text displayed inside the tooltip.",
|
|
557
|
-
"control": "text",
|
|
558
|
-
"category": "content",
|
|
559
|
-
"type": "string | React.ReactNode"
|
|
560
|
-
},
|
|
561
|
-
"subTitle": {
|
|
562
|
-
"description": "Optional subtitle displayed below the title.",
|
|
563
|
-
"control": "text",
|
|
564
|
-
"category": "content",
|
|
565
|
-
"type": "string"
|
|
566
|
-
},
|
|
567
|
-
"hint": {
|
|
568
|
-
"description": "Optional hint displayed next to tooltip title.",
|
|
569
|
-
"control": "text",
|
|
570
|
-
"category": "content",
|
|
571
|
-
"type": "string"
|
|
572
|
-
},
|
|
573
|
-
"children": {
|
|
574
|
-
"description": "The element that triggers the tooltip on hover.",
|
|
575
|
-
"control": false,
|
|
576
|
-
"category": "content",
|
|
577
|
-
"type": "React.ReactElement"
|
|
578
|
-
},
|
|
579
|
-
"placement": {
|
|
580
|
-
"description": "Tooltip placement relative to the anchor element.",
|
|
581
|
-
"control": "select",
|
|
582
|
-
"category": "appearance",
|
|
583
|
-
"type": "TooltipProps[\"placement\"]",
|
|
584
|
-
"defaultValue": "'bottom'",
|
|
585
|
-
"options": [
|
|
586
|
-
"bottom-end",
|
|
587
|
-
"bottom-start",
|
|
588
|
-
"bottom",
|
|
589
|
-
"left-end",
|
|
590
|
-
"left-start",
|
|
591
|
-
"left",
|
|
592
|
-
"right-end",
|
|
593
|
-
"right-start",
|
|
594
|
-
"right",
|
|
595
|
-
"top-end",
|
|
596
|
-
"top-start",
|
|
597
|
-
"top"
|
|
598
|
-
]
|
|
599
|
-
},
|
|
600
|
-
"arrow": {
|
|
601
|
-
"description": "If true, adds an arrow pointing to the anchor element.",
|
|
602
|
-
"control": "boolean",
|
|
603
|
-
"category": "appearance",
|
|
604
|
-
"type": "boolean",
|
|
605
|
-
"defaultValue": "false"
|
|
606
|
-
},
|
|
607
|
-
"open": {
|
|
608
|
-
"description": "Controls the open state of the tooltip (controlled mode).",
|
|
609
|
-
"control": "boolean",
|
|
610
|
-
"category": "state",
|
|
611
|
-
"type": "boolean"
|
|
612
|
-
},
|
|
613
|
-
"disableHoverListener": {
|
|
614
|
-
"description": "If true, the tooltip will not open on hover.",
|
|
615
|
-
"control": "boolean",
|
|
616
|
-
"category": "behavior",
|
|
617
|
-
"type": "boolean",
|
|
618
|
-
"defaultValue": "false"
|
|
619
|
-
},
|
|
620
|
-
"disableFocusListener": {
|
|
621
|
-
"description": "If true, the tooltip will not open on focus.",
|
|
622
|
-
"control": "boolean",
|
|
623
|
-
"category": "behavior",
|
|
624
|
-
"type": "boolean",
|
|
625
|
-
"defaultValue": "false"
|
|
626
|
-
},
|
|
627
|
-
"disableTouchListener": {
|
|
628
|
-
"description": "If true, the tooltip will not open on touch.",
|
|
629
|
-
"control": "boolean",
|
|
630
|
-
"category": "behavior",
|
|
631
|
-
"type": "boolean",
|
|
632
|
-
"defaultValue": "false"
|
|
633
|
-
},
|
|
634
|
-
"enterDelay": {
|
|
635
|
-
"description": "Delay in milliseconds before the tooltip appears.",
|
|
636
|
-
"control": "number",
|
|
637
|
-
"category": "behavior",
|
|
638
|
-
"type": "number",
|
|
639
|
-
"defaultValue": "100"
|
|
640
|
-
},
|
|
641
|
-
"leaveDelay": {
|
|
642
|
-
"description": "Delay in milliseconds before the tooltip disappears.",
|
|
643
|
-
"control": "number",
|
|
644
|
-
"category": "behavior",
|
|
645
|
-
"type": "number",
|
|
646
|
-
"defaultValue": "0"
|
|
647
|
-
},
|
|
648
|
-
"onOpen": {
|
|
649
|
-
"description": "Callback fired when the tooltip opens.",
|
|
650
|
-
"category": "callbacks",
|
|
651
|
-
"type": "(event: React.SyntheticEvent) => void"
|
|
652
|
-
},
|
|
653
|
-
"onClose": {
|
|
654
|
-
"description": "Callback fired when the tooltip closes.",
|
|
655
|
-
"category": "callbacks",
|
|
656
|
-
"type": "(event: React.SyntheticEvent) => void"
|
|
657
|
-
},
|
|
658
|
-
"sx": {
|
|
659
|
-
"description": "MUI sx prop for custom styling of the root element.",
|
|
660
|
-
"control": "object",
|
|
661
|
-
"category": "customization",
|
|
662
|
-
"type": "SxProps"
|
|
663
|
-
},
|
|
664
|
-
"className": {
|
|
665
|
-
"description": "CSS class name applied to the root element.",
|
|
666
|
-
"control": "text",
|
|
667
|
-
"category": "customization",
|
|
668
|
-
"type": "string"
|
|
669
|
-
},
|
|
670
|
-
"dataTestIdSuffix": {
|
|
671
|
-
"description": "Suffix appended to the data-testid attribute.",
|
|
672
|
-
"control": "text",
|
|
673
|
-
"category": "customization",
|
|
674
|
-
"type": "string"
|
|
675
|
-
}
|
|
676
|
-
},
|
|
677
|
-
"storyNames": [
|
|
678
|
-
"Default",
|
|
679
|
-
"WithSubtitle",
|
|
680
|
-
"WithHint",
|
|
681
|
-
"WithCustomTitle"
|
|
682
|
-
],
|
|
683
|
-
"docs": "# Tooltip\n\nAn enhanced tooltip component built on MUI Tooltip that supports structured content with a title, optional subtitle, and optional hint.\n\n**Key Features:**\n\n- Structured content with title, subtitle, and hint sections\n- Full MUI Tooltip API compatibility (placement, arrow, delay, etc.)\n- Keyboard hint display for discoverability\n\n## Default\n\nBasic tooltip with a title displayed on hover.\n\n```tsx\n// DefaultExample.tsx\nimport React from 'react';\nimport { Button } from '@mui/material';\nimport { Tooltip } from '@ringpublishing/mui-components';\n\nexport default function DefaultExample(): React.JSX.Element {\n return (\n <Tooltip title=\"Title\" arrow={true}>\n <Button variant={'outlined'}>Hover me</Button>\n </Tooltip>\n );\n}\n```\n\n## With Subtitle\n\nUse the `subTitle` prop to provide additional descriptive text below the title.\n\n```tsx\n// WithSubtitleExample.tsx\nimport React from 'react';\nimport { Button } from '@mui/material';\nimport { Tooltip } from '@ringpublishing/mui-components';\n\nexport default function WithSubtitleExample(): React.JSX.Element {\n return (\n <Tooltip title=\"Title\" subTitle=\"Tooltip Subtitle\" arrow={true}>\n <Button variant={'outlined'}>Hover me</Button>\n </Tooltip>\n );\n}\n```\n\n## With Hint\n\nUse the `hint` prop to display a keyboard hint next to tooltip title.\n\n```tsx\n// WithHintExample.tsx\nimport React from 'react';\nimport { Button } from '@mui/material';\nimport { Tooltip } from '@ringpublishing/mui-components';\n\nexport default function WithHintExample(): React.JSX.Element {\n return (\n <Tooltip title=\"Title\" hint=\"⌘+K\" arrow={true}>\n <Button variant={'outlined'}>Hover me</Button>\n </Tooltip>\n );\n}\n```\n\n## With Custom Title\n\nPass a `ReactNode` as `title` to render fully custom content in place of the default string title.\n\n```tsx\n// WithCustomTitleExample.tsx\nimport React from 'react';\nimport { Button } from '@mui/material';\nimport { Tooltip } from '@ringpublishing/mui-components';\n\nexport default function WithCustomTitleExample(): React.JSX.Element {\n return (\n <Tooltip\n title={\n <span>\n Custom <strong>rich</strong> title\n </span>\n }\n arrow={true}\n >\n <Button variant={'outlined'}>Hover me</Button>\n </Tooltip>\n );\n}\n```"
|
|
684
|
-
},
|
|
685
|
-
"atoms-typography": {
|
|
686
|
-
"id": "atoms-typography",
|
|
687
|
-
"name": "Typography",
|
|
688
|
-
"category": "Atoms",
|
|
689
|
-
"title": "Components/Atoms/Typography",
|
|
690
|
-
"description": "Typography component with overflow handling and tooltip support. This component extends MUI's Typography component and adds intelligent overflow handling with tooltips.",
|
|
691
|
-
"argTypes": {
|
|
692
|
-
"enableOverflow": {
|
|
693
|
-
"description": "Enable overflow handling with ellipsis and tooltip",
|
|
694
|
-
"control": "boolean",
|
|
695
|
-
"category": "behavior",
|
|
696
|
-
"type": "boolean",
|
|
697
|
-
"defaultValue": "false"
|
|
698
|
-
},
|
|
699
|
-
"alwaysShowTooltip": {
|
|
700
|
-
"description": "Always render the tooltip on hover, regardless of whether the text overflows",
|
|
701
|
-
"control": "boolean",
|
|
702
|
-
"category": "behavior",
|
|
703
|
-
"type": "boolean",
|
|
704
|
-
"defaultValue": "false"
|
|
705
|
-
},
|
|
706
|
-
"tooltipTitle": {
|
|
707
|
-
"description": "Custom tooltip content. When omitted, the tooltip shows the Typography children.",
|
|
708
|
-
"control": false,
|
|
709
|
-
"category": "content",
|
|
710
|
-
"type": "React.ReactNode"
|
|
711
|
-
}
|
|
712
|
-
},
|
|
713
|
-
"storyNames": [
|
|
714
|
-
"Default",
|
|
715
|
-
"WithOverflowAndTooltip",
|
|
716
|
-
"WithCustomTooltip"
|
|
717
|
-
],
|
|
718
|
-
"docs": "# Typography\n\nTypography component with overflow handling and tooltip support. This component extends MUI's Typography component and adds intelligent overflow handling with tooltips.\n\n**Key Features:**\n\n- Automatic text overflow detection\n- Ellipsis display for overflowing text\n- Tooltip with full text on hover when overflowed\n- All MUI Typography variants supported\n- Customizable tooltip behavior\n\n**Use Cases:**\n\n- Display text in constrained spaces\n- Show user-generated content with unknown length\n- Create consistent text styling across the application\n- Provide accessible text overflow handling\n\n**Extends:** [MUI Typography](https://mui.com/material-ui/react-typography) - supports all MUI Typography properties.\n\n## Default\n\nThe default Typography component displays text that wraps naturally within its container. When `enableOverflow` is false (default), text wraps normally without truncation.\n\n```tsx\n// DefaultExample.tsx\nimport React from 'react';\nimport { Typography } from '@ringpublishing/mui-components';\nimport { Box } from '@mui/material';\n\nexport default function DefaultExample(): React.JSX.Element {\n return (\n <>\n <Box sx={{ width: '300px', border: '1px solid #ccc', padding: 2, mb: 4 }}>\n <Typography variant=\"body1\">\n This is a very long text that will be wrapped within the container without overflow.\n </Typography>\n </Box>\n <Box sx={{ width: '300px', border: '1px solid #ccc', padding: 2 }}>\n <Typography variant=\"body1\" enableOverflow={true}>\n This is a very long text that will overflow and show ellipsis. Hover over it to see the full text in\n a tooltip.\n </Typography>\n </Box>\n </>\n );\n}\n```\n\n## With Overflow and Tooltip\n\nWhen `enableOverflow` is enabled, the component automatically detects text overflow and displays an ellipsis. Hovering over the truncated text shows a tooltip with the full content.\n\n### Key Features:\n\n- Automatic overflow detection using layout effects\n- Single-line text with ellipsis\n- Interactive tooltip on hover\n- Customizable tooltip appearance via `tooltipProps`\n\n### Usage:\n\n```typescript\n<Typography enableOverflow={true} sx={{ width: '300px' }}>\n This is a very long text that will overflow and show ellipsis.\n</Typography>\n```\n\n```tsx\n// WithOverflowAndTooltipExample.tsx\nimport React from 'react';\nimport { Typography } from '@ringpublishing/mui-components';\nimport { Box } from '@mui/material';\n\nexport default function WithOverflowAndTooltipExample(): React.JSX.Element {\n return (\n <Box sx={{ width: '300px', border: '1px solid #ccc', padding: 2 }}>\n <Typography enableOverflow={true}>\n This is a very long text that will overflow and show ellipsis. Hover over it to see the full text in a\n tooltip.\n </Typography>\n </Box>\n );\n}\n```"
|
|
719
|
-
},
|
|
720
|
-
"molecules-accordion": {
|
|
721
|
-
"id": "molecules-accordion",
|
|
722
|
-
"name": "Accordion",
|
|
723
|
-
"category": "Molecules",
|
|
724
|
-
"title": "Components/Molecules/Accordion",
|
|
725
|
-
"description": "A collapsible content container that extends MUI's Accordion component with additional features like integrated action buttons and customizable labels. Perfect for organizing content sections that can be expanded or collapsed by users.",
|
|
726
|
-
"argTypes": {
|
|
727
|
-
"label": {
|
|
728
|
-
"description": "Label of the accordion displayed in the header",
|
|
729
|
-
"control": "text",
|
|
730
|
-
"category": "content",
|
|
731
|
-
"type": "string",
|
|
732
|
-
"defaultValue": "Test"
|
|
733
|
-
},
|
|
734
|
-
"children": {
|
|
735
|
-
"description": "Content displayed when accordion is expanded",
|
|
736
|
-
"control": false,
|
|
737
|
-
"category": "content",
|
|
738
|
-
"type": "ReactNode"
|
|
739
|
-
},
|
|
740
|
-
"buttonLabel": {
|
|
741
|
-
"description": "Label for the action button in accordion header",
|
|
742
|
-
"control": "text",
|
|
743
|
-
"category": "action",
|
|
744
|
-
"type": "string"
|
|
745
|
-
},
|
|
746
|
-
"buttonOnClick": {
|
|
747
|
-
"description": "Click handler for the action button",
|
|
748
|
-
"control": false,
|
|
749
|
-
"category": "action",
|
|
750
|
-
"type": "React.MouseEventHandler<HTMLButtonElement>"
|
|
751
|
-
},
|
|
752
|
-
"variant": {
|
|
753
|
-
"description": "Accordion variant style",
|
|
754
|
-
"control": "select",
|
|
755
|
-
"category": "style",
|
|
756
|
-
"type": "'elevation' | 'outlined' | 'borderless'",
|
|
757
|
-
"defaultValue": "borderless",
|
|
758
|
-
"options": [
|
|
759
|
-
"elevation",
|
|
760
|
-
"outlined",
|
|
761
|
-
"borderless"
|
|
762
|
-
]
|
|
763
|
-
},
|
|
764
|
-
"expanded": {
|
|
765
|
-
"description": "If true, the accordion is expanded",
|
|
766
|
-
"control": "boolean",
|
|
767
|
-
"category": "behavior",
|
|
768
|
-
"type": "boolean"
|
|
769
|
-
},
|
|
770
|
-
"defaultExpanded": {
|
|
771
|
-
"description": "If true, the accordion is expanded by default",
|
|
772
|
-
"control": "boolean",
|
|
773
|
-
"category": "behavior",
|
|
774
|
-
"type": "boolean"
|
|
775
|
-
},
|
|
776
|
-
"disabled": {
|
|
777
|
-
"description": "If true, the accordion is disabled",
|
|
778
|
-
"control": "boolean",
|
|
779
|
-
"category": "behavior",
|
|
780
|
-
"type": "boolean"
|
|
781
|
-
},
|
|
782
|
-
"onChange": {
|
|
783
|
-
"description": "Callback fired when the expand/collapse state changes",
|
|
784
|
-
"control": false,
|
|
785
|
-
"category": "behavior",
|
|
786
|
-
"type": "(event: SyntheticEvent, expanded: boolean) => void"
|
|
787
|
-
},
|
|
788
|
-
"dataTestIdSuffix": {
|
|
789
|
-
"description": "Optional suffix added to data-testid attributes for testing",
|
|
790
|
-
"control": "text",
|
|
791
|
-
"category": "testing",
|
|
792
|
-
"type": "string"
|
|
793
|
-
},
|
|
794
|
-
"sx": {
|
|
795
|
-
"description": "Custom styles using MUI sx prop",
|
|
796
|
-
"control": "object",
|
|
797
|
-
"category": "customization",
|
|
798
|
-
"type": "SxProps<Theme>"
|
|
799
|
-
},
|
|
800
|
-
"className": {
|
|
801
|
-
"description": "CSS class name applied to the root element",
|
|
802
|
-
"control": "text",
|
|
803
|
-
"category": "customization",
|
|
804
|
-
"type": "string"
|
|
805
|
-
}
|
|
806
|
-
},
|
|
807
|
-
"storyNames": [
|
|
808
|
-
"Default",
|
|
809
|
-
"WithBorder",
|
|
810
|
-
"WithButton",
|
|
811
|
-
"Multiple"
|
|
812
|
-
],
|
|
813
|
-
"docs": "# Accordion\n\nA collapsible content container that extends MUI's Accordion component with additional features like integrated action buttons and customizable labels. Perfect for organizing content sections that can be expanded or collapsed by users.\n\n## Key Features\n\n- **Custom labels**: Set custom header text for each accordion\n- **Action button**: Optional button in the header for quick actions\n- **Multiple accordions**: Seamless styling for stacked accordions\n- **Expandable icon**: Built-in expand/collapse indicator\n- **Accessible**: Follows ARIA patterns for keyboard navigation\n- **MUI integration**: Extends all MUI Accordion properties\n\n## Default\n\nBasic accordion with a text field as content. Shows the simplest use case with default label and standard styling.\n\n```tsx\n// DefaultExample.tsx\nimport React from 'react';\nimport { TextField } from '@mui/material';\nimport { Accordion } from '@ringpublishing/mui-components';\n\nexport default function DefaultExample(): React.JSX.Element {\n return (\n <Accordion label=\"Accordion\">\n <TextField required={true} id=\"outlined-required\" label=\"Required\" defaultValue=\"Hello World\" />\n </Accordion>\n );\n}\n```\n\n## With Border\n\nAccordion using the outlined/bordered variant to provide clear visual separation from surrounding content or between stacked items. Ideal when you want the accordion to stand out more than the borderless version.\n\n```tsx\n// WithBorderExample.tsx\nimport React from 'react';\nimport { Accordion } from '@ringpublishing/mui-components';\n\nexport default function WithBorderExample(): React.JSX.Element {\n return (\n <Accordion label=\"With Border\" variant=\"outlined\">\n <div>Opened accordion</div>\n </Accordion>\n );\n}\n```\n\n## With Button\n\nAccordion with an integrated action button in the header. The button click event is isolated from the expand/collapse action, allowing for additional functionality without expanding the accordion.\n\n### Key Features:\n\n- Button appears in the header next to the label\n- Button click doesn't trigger accordion expansion\n- Useful for quick actions like \"Edit\", \"Delete\", or \"Add\"\n\n```tsx\n// WithButtonExample.tsx\nimport React from 'react';\nimport { Accordion } from '@ringpublishing/mui-components';\n\nexport default function WithButtonExample(): React.JSX.Element {\n return (\n <Accordion label=\"Accordion\" buttonLabel=\"Button\" buttonOnClick={() => alert('Button clicked')}>\n <div>Opened accordion</div>\n </Accordion>\n );\n}\n```\n\n## Multiple\n\nMultiple accordions stacked with the borderless variant for a seamless appearance. Ideal for creating grouped content sections without visual separation.\n\n### Key Features:\n\n- No borders between stacked accordions\n- Creates a unified appearance\n- Perfect for settings panels or FAQ sections\n\n```tsx\n// MultipleExample.tsx\nimport React from 'react';\nimport { Stack } from '@mui/material';\nimport { Accordion } from '@ringpublishing/mui-components';\n\nexport default function MultipleExample(): React.JSX.Element {\n return (\n <Stack direction={'column'}>\n <Accordion label=\"Accordion\">\n <div>Opened accordion</div>\n </Accordion>\n <Accordion label=\"Accordion\">\n <div>Opened accordion</div>\n </Accordion>\n <Accordion label=\"Accordion\">\n <div>Opened accordion</div>\n </Accordion>\n </Stack>\n );\n}\n```\n\n## Usage Example\n\n```typescript\n\nfunction MyComponent() {\n return (\n <Accordion\n label=\"Personal Information\"\n buttonLabel=\"Edit\"\n buttonOnClick={() => console.log('Edit clicked')}\n >\n <TextField label=\"Name\" fullWidth />\n <TextField label=\"Email\" fullWidth />\n </Accordion>\n );\n}\n```\n\n### Label and Content\n\n- **`label`**: Header text displayed in the accordion summary (default: \"Test\")\n- **`children`**: Content displayed when accordion is expanded (required)\n\n### Action Button\n\n- **`buttonLabel`**: Text shown on the action button in header\n- **`buttonOnClick`**: Click handler for the action button (receives React MouseEvent)\n\nThe action button is optional and only appears when `buttonLabel` is provided. The button click event is stopped from propagating to prevent triggering the accordion expansion.\n\n### Styling\n\n- **`variant`**: MUI Accordion variant ('elevation' | 'outlined' | 'borderless')\n- **`sx`**: Custom styles using MUI's sx prop\n- **`className`**: CSS class name applied to root element\n\n### Testing\n\n- **`dataTestIdSuffix`**: Suffix for data-testid attributes (e.g., \"ring-accordion-\\{suffix\\}\")"
|
|
814
|
-
},
|
|
815
|
-
"molecules-action-box": {
|
|
816
|
-
"id": "molecules-action-box",
|
|
817
|
-
"name": "ActionBox",
|
|
818
|
-
"category": "Molecules",
|
|
819
|
-
"title": "Components/Molecules/ActionBox",
|
|
820
|
-
"description": "ActionBox displays a list of actions in a compact dropdown menu anchored to a trigger element.\nIt supports icons, separators, disabled state handling, and tooltips for disabled reasons.",
|
|
821
|
-
"argTypes": {
|
|
822
|
-
"actions": {
|
|
823
|
-
"description": "Actions list shown in Action Box",
|
|
824
|
-
"control": false,
|
|
825
|
-
"category": "data",
|
|
826
|
-
"type": "ActionBoxItem[]",
|
|
827
|
-
"defaultValue": "[]"
|
|
828
|
-
},
|
|
829
|
-
"placement": {
|
|
830
|
-
"description": "Placement of the Action Box relative to the anchor element",
|
|
831
|
-
"category": "positioning",
|
|
832
|
-
"type": "PopperProps[\"placement\"]",
|
|
833
|
-
"defaultValue": "bottom-end"
|
|
834
|
-
},
|
|
835
|
-
"tooltipPlacement": {
|
|
836
|
-
"description": "Placement of the disabled reason for the action tooltip",
|
|
837
|
-
"category": "positioning",
|
|
838
|
-
"type": "TooltipProps[\"placement\"]",
|
|
839
|
-
"defaultValue": "right"
|
|
840
|
-
},
|
|
841
|
-
"hasScroll": {
|
|
842
|
-
"description": "If true, Action Box will have a scroll if actions exceed visibleActionsCount",
|
|
843
|
-
"category": "behavior",
|
|
844
|
-
"type": "boolean",
|
|
845
|
-
"defaultValue": "true"
|
|
846
|
-
},
|
|
847
|
-
"visibleActionsCount": {
|
|
848
|
-
"description": "Number of actions visible without scrolling",
|
|
849
|
-
"category": "behavior",
|
|
850
|
-
"type": "number",
|
|
851
|
-
"defaultValue": "actions.length"
|
|
852
|
-
},
|
|
853
|
-
"zIndex": {
|
|
854
|
-
"description": "Z-index of the Action Box",
|
|
855
|
-
"category": "customization",
|
|
856
|
-
"type": "number",
|
|
857
|
-
"defaultValue": "theme.zIndex.modal"
|
|
858
|
-
},
|
|
859
|
-
"anchorEl": {
|
|
860
|
-
"description": "Ref to the anchor element used to position the Action Box",
|
|
861
|
-
"control": false,
|
|
862
|
-
"category": "data",
|
|
863
|
-
"type": "RefObject<HTMLElement>"
|
|
864
|
-
},
|
|
865
|
-
"sx": {
|
|
866
|
-
"description": "Overrides the Paper styles for the Action Box",
|
|
867
|
-
"control": false,
|
|
868
|
-
"category": "customization",
|
|
869
|
-
"type": "SxProps<Theme>"
|
|
870
|
-
},
|
|
871
|
-
"dataTestIdSuffix": {
|
|
872
|
-
"description": "Optional suffix added to data-testid attributes",
|
|
873
|
-
"control": "text",
|
|
874
|
-
"category": "testing",
|
|
875
|
-
"type": "string"
|
|
876
|
-
}
|
|
877
|
-
},
|
|
878
|
-
"storyNames": [
|
|
879
|
-
"Default",
|
|
880
|
-
"PopperPlacement",
|
|
881
|
-
"CustomStyling"
|
|
882
|
-
],
|
|
883
|
-
"docs": "# ActionBox\n\nActionBox displays a list of actions in a compact dropdown menu anchored to a trigger element.\nIt supports icons, separators, disabled state handling, and tooltips for disabled reasons.\n\n**Main use cases:**\n\n- Context menus with additional options\n- Multiple actions in a compact form\n- Conditional actions with disabled state and reasons\n- Organizing functions with separators\n\nActionBox extends [Popper](https://mui.com/material-ui/react-popper/), so all Popper props are supported.\n\n## Default\n\nA basic ActionBox anchored to a button with multiple actions, icons, and separators.\n\n```tsx\n// DefaultExample.tsx\nimport React, { useRef } from 'react';\nimport { Button } from '@mui/material';\nimport { DoNotDisturb, ImportExport, RocketLaunch } from '@mui/icons-material';\n\nimport { ActionBox, ActionBoxItem } from '@ringpublishing/mui-components';\n\nexport default function DefaultExample(): React.JSX.Element {\n const ref = useRef<HTMLButtonElement | null>(null);\n\n const actions: ActionBoxItem[] = [\n {\n label: 'Action 1',\n onClick: () => null,\n icon: <RocketLaunch />,\n hasSeparatorAfter: true,\n },\n {\n label: 'Action 2',\n onClick: () => null,\n disabled: true,\n disabledReason: 'Disabled because of some reason',\n icon: <DoNotDisturb />,\n },\n {\n label: 'Action 3',\n onClick: () => null,\n },\n {\n label: 'Action 4',\n onClick: () => null,\n icon: <ImportExport />,\n hasSeparatorBefore: true,\n },\n ];\n\n return (\n <div\n style={{\n display: 'flex',\n justifyContent: 'center',\n alignItems: 'center',\n }}\n >\n <Button data-testid=\"action-box-trigger\" variant=\"outlined\" color=\"primary\" ref={ref}>\n Click me!\n </Button>\n <ActionBox\n actions={actions}\n anchorEl={ref}\n placement=\"bottom-end\"\n tooltipPlacement=\"right\"\n className=\"custom-class-name\"\n />\n </div>\n );\n}\n```\n\n## Popper Placement\n\nCustomize the position and portal behavior of the ActionBox using Popper API props.\n\n```tsx\n// PopperPlacementExample.tsx\nimport React, { useRef } from 'react';\nimport { Button } from '@mui/material';\nimport { DoNotDisturb, RocketLaunch } from '@mui/icons-material';\n\nimport { ActionBox, ActionBoxItem } from '@ringpublishing/mui-components';\n\nexport default function PopperPlacementExample(): React.JSX.Element {\n const ref = useRef<HTMLButtonElement | null>(null);\n\n const actions: ActionBoxItem[] = [\n {\n label: 'Action 1',\n onClick: () => null,\n icon: <RocketLaunch />,\n },\n {\n label: 'Action 2',\n onClick: () => null,\n disabled: true,\n disabledReason: 'Disabled because of some reason',\n icon: <DoNotDisturb />,\n },\n ];\n\n return (\n <div\n style={{\n display: 'flex',\n justifyContent: 'center',\n alignItems: 'center',\n }}\n >\n <Button data-testid=\"action-box-trigger\" variant=\"outlined\" color=\"primary\" ref={ref}>\n Click me!\n </Button>\n <ActionBox\n actions={actions}\n anchorEl={ref}\n placement=\"left-start\"\n tooltipPlacement=\"left\"\n disablePortal={true}\n />\n </div>\n );\n}\n```\n\n## Custom Styling\n\nApply custom colors and background using the `sx` prop for theme-aware styling.\n\n```tsx\n// CustomStylingExample.tsx\nimport React, { useRef } from 'react';\nimport { DoNotDisturb, RocketLaunch } from '@mui/icons-material';\nimport { Button, Theme } from '@mui/material';\nimport { ActionBox, ActionBoxItem } from '@ringpublishing/mui-components';\n\nexport default function CustomStylingExample(): React.JSX.Element {\n const ref = useRef<HTMLButtonElement | null>(null);\n\n const actions: ActionBoxItem[] = [\n {\n label: 'Action 1',\n onClick: () => null,\n icon: <RocketLaunch />,\n },\n {\n label: 'Action 2',\n onClick: () => null,\n disabled: true,\n disabledReason: 'Disabled because of some reason',\n icon: <DoNotDisturb />,\n },\n {\n label: 'Styled last action',\n onClick: () => null,\n icon: <RocketLaunch />,\n sx: (theme: Theme) => ({\n color: theme.palette.common.white,\n backgroundColor: theme.palette.error.main,\n '&:hover': {\n backgroundColor: theme.palette.error.dark,\n },\n }),\n },\n ];\n\n return (\n <div\n style={{\n display: 'flex',\n justifyContent: 'center',\n alignItems: 'center',\n }}\n >\n <Button data-testid=\"action-box-trigger\" variant=\"outlined\" color=\"primary\" ref={ref}>\n Click me!\n </Button>\n <ActionBox\n actions={actions}\n anchorEl={ref}\n sx={(theme: Theme) => ({\n color: theme.palette.common.white,\n backgroundColor: theme.palette.success.main,\n })}\n />\n </div>\n );\n}\n```"
|
|
884
|
-
},
|
|
885
|
-
"molecules-autocomplete": {
|
|
886
|
-
"id": "molecules-autocomplete",
|
|
887
|
-
"name": "Autocomplete",
|
|
888
|
-
"category": "Molecules",
|
|
889
|
-
"title": "Components/Molecules/Autocomplete",
|
|
890
|
-
"description": "Autocomplete extends [MUI Autocomplete](https://mui.com/material-ui/react-autocomplete/) component and supports all its properties.",
|
|
891
|
-
"argTypes": {
|
|
892
|
-
"sx": {
|
|
893
|
-
"description": "MUI System properties to customize the main element style.",
|
|
894
|
-
"control": "object",
|
|
895
|
-
"category": "customization",
|
|
896
|
-
"type": "SxProps<Theme>"
|
|
897
|
-
},
|
|
898
|
-
"className": {
|
|
899
|
-
"description": "CSS class name applied to the main element.",
|
|
900
|
-
"control": "text",
|
|
901
|
-
"category": "customization",
|
|
902
|
-
"type": "string"
|
|
903
|
-
},
|
|
904
|
-
"labels": {
|
|
905
|
-
"description": "Labels configuration for the autocomplete (required). Includes title, inputPlaceholder, recentlyUsed, and recentlyUsedResults.",
|
|
906
|
-
"control": "object",
|
|
907
|
-
"category": "content",
|
|
908
|
-
"type": "{ title: string; inputPlaceholder?: string; recentlyUsed?: string; recentlyUsedResults?: string; }"
|
|
909
|
-
},
|
|
910
|
-
"actions": {
|
|
911
|
-
"description": "Array of actions displayed as buttons/menu in the autocomplete input. Single action shows as icon button, multiple actions show as menu with MoreVert icon.",
|
|
912
|
-
"control": false,
|
|
913
|
-
"category": "content",
|
|
914
|
-
"type": "Action[]"
|
|
915
|
-
},
|
|
916
|
-
"showRecentlyUsed": {
|
|
917
|
-
"description": "Show recently used items grouped separately in the dropdown.",
|
|
918
|
-
"control": "boolean",
|
|
919
|
-
"category": "behavior",
|
|
920
|
-
"type": "boolean",
|
|
921
|
-
"defaultValue": "false"
|
|
922
|
-
},
|
|
923
|
-
"recentlyLocalStorageKey": {
|
|
924
|
-
"description": "Local storage key for recently used items. Required when showRecentlyUsed is true.",
|
|
925
|
-
"control": "text",
|
|
926
|
-
"category": "behavior",
|
|
927
|
-
"type": "string"
|
|
928
|
-
},
|
|
929
|
-
"recentlyUsedLimit": {
|
|
930
|
-
"description": "Maximum number of recently used items to store.",
|
|
931
|
-
"control": "number",
|
|
932
|
-
"category": "behavior",
|
|
933
|
-
"type": "number",
|
|
934
|
-
"defaultValue": "3"
|
|
935
|
-
},
|
|
936
|
-
"slotProps": {
|
|
937
|
-
"description": "Props for slot components including textField and chip. Extends MUI Autocomplete slotProps.",
|
|
938
|
-
"control": "object",
|
|
939
|
-
"category": "customization",
|
|
940
|
-
"type": "{ textField?: TextFieldProps; chip?: ChipProps; } & MuiAutocompleteProps[\"slotProps\"]"
|
|
941
|
-
},
|
|
942
|
-
"dataTestIdSuffix": {
|
|
943
|
-
"description": "Suffix for data-testid attribute. Results in data-testid=\"ring-Autocomplete-{suffix}\".",
|
|
944
|
-
"control": "text",
|
|
945
|
-
"category": "testing",
|
|
946
|
-
"type": "string"
|
|
947
|
-
}
|
|
948
|
-
},
|
|
949
|
-
"storyNames": [
|
|
950
|
-
"Default",
|
|
951
|
-
"WithDropdownActions",
|
|
952
|
-
"WithMultipleSelection",
|
|
953
|
-
"WithMultipleDropdownActions",
|
|
954
|
-
"WithRecentlyUsed",
|
|
955
|
-
"WithCaption",
|
|
956
|
-
"WithAvatar",
|
|
957
|
-
"WithCustomisedAvatar",
|
|
958
|
-
"WithAsynchronousRequests",
|
|
959
|
-
"WithCustomisedChips",
|
|
960
|
-
"WithCustomisedRenderOption",
|
|
961
|
-
"WithFreeSolo",
|
|
962
|
-
"WithOutlinedTextField"
|
|
963
|
-
],
|
|
964
|
-
"docs": "# Autocomplete\n\nAutocomplete extends [MUI Autocomplete](https://mui.com/material-ui/react-autocomplete/) component and supports all its properties.\n\nThe Autocomplete component provides a text input enhanced with a panel of suggested options. It's useful for:\n\n- Single or multiple value selection from a predefined list\n- Free text input with suggestions (freeSolo mode)\n- Asynchronous data loading\n- Recently used items tracking\n- Custom option rendering with captions and avatars\n\n## Default\n\nBasic usage of the Autocomplete component with a predefined list of options.\n\n```tsx\n// DefaultExample.tsx\nimport React from 'react';\nimport { Autocomplete } from '@ringpublishing/mui-components';\n\ninterface Option {\n label: string;\n id: number;\n}\n\nexport default function DefaultExample(): React.JSX.Element {\n const options: Option[] = [\n { label: 'Onet', id: 1 },\n { label: 'Fakt', id: 2 },\n { label: 'Komputer świat', id: 3 },\n { label: 'Newsweek', id: 4 },\n { label: 'Forbes', id: 5 },\n { label: 'Business insider', id: 6 },\n ];\n\n return (\n <Autocomplete options={options} defaultValue={options[0]} labels={{ title: 'search by' }} sx={{ width: 300 }} />\n );\n}\n```\n\n## With Dropdown Actions\n\nAdd action buttons to the Autocomplete input. Actions appear as icon buttons inside the input field and can trigger custom callbacks.\n\n### Key Features:\n\n- Single action button displayed in the input\n- Supports icon and click handler\n- Can be disabled with optional disabled reason\n\n```tsx\n// WithDropdownActionsExample.tsx\nimport React from 'react';\nimport { Autocomplete, Action } from '@ringpublishing/mui-components';\nimport { ManageSearch } from '@mui/icons-material';\n\ninterface Option {\n label: string;\n id: number;\n}\n\nexport default function WithDropdownActionsExample(): React.JSX.Element {\n const options: Option[] = [\n { label: 'Onet', id: 1 },\n { label: 'Fakt', id: 2 },\n { label: 'Komputer świat', id: 3 },\n { label: 'Newsweek', id: 4 },\n { label: 'Forbes', id: 5 },\n { label: 'Business insider', id: 6 },\n ];\n\n const actions: Action[] = [\n {\n icon: <ManageSearch />,\n onClick: () => console.log('Settings clicked'),\n disabled: false,\n label: 'Settings',\n },\n ];\n\n return (\n <Autocomplete\n options={options}\n actions={actions}\n defaultValue={options[0]}\n labels={{ title: 'search by' }}\n sx={{ width: 300 }}\n />\n );\n}\n```\n\n## With Multiple Selection\n\nDemonstrates multiple selection mode where users can select multiple options from the list. Selected options are displayed as chips in the input field.\n\n### Key Features:\n\n- Multiple value selection using `multiple` prop\n- Selected values displayed as chips\n- Chips can be removed by clicking the X icon\n- Default value can be an array of options\n\n### Usage:\n\n```typescript\n<Autocomplete\n options={options}\n multiple\n defaultValue={[options[0], options[1]]}\n labels={{ title: 'search by' }}\n/>\n```\n\n```tsx\n// WithMultipleSelectionExample.tsx\nimport React from 'react';\nimport { Autocomplete } from '@ringpublishing/mui-components';\n\ninterface Option {\n label: string;\n id: number;\n}\n\nexport default function WithMultipleSelectionExample(): React.JSX.Element {\n const options: Option[] = [\n { label: 'Onet', id: 1 },\n { label: 'Fakt', id: 2 },\n { label: 'Komputer świat', id: 3 },\n { label: 'Newsweek', id: 4 },\n { label: 'Forbes', id: 5 },\n { label: 'Business insider', id: 6 },\n ];\n\n return (\n <Autocomplete\n options={options}\n defaultValue={[options[0], options[1]]}\n multiple\n labels={{ title: 'search by' }}\n sx={{ width: 300 }}\n />\n );\n}\n```\n\n## With Multiple Dropdown Actions\n\nWhen multiple actions are provided, they are displayed in a dropdown menu accessible via a \"more\" button (MoreVert icon).\n\n### Key Features:\n\n- Multiple actions in a dropdown menu\n- Actions grouped under MoreVert icon button\n- Each action has its own icon and handler\n- Works with single or multiple selection mode\n\n### Usage:\n\n```typescript\nactions={[\n {\n icon: <ManageSearch />,\n onClick: handleSettings,\n label: 'Settings',\n },\n {\n icon: <InfoOutlined />,\n onClick: handleInfo,\n label: 'Info',\n },\n]}\n```\n\n```tsx\n// WithMultipleDropdownActionsExample.tsx\nimport React from 'react';\nimport { Autocomplete, Action } from '@ringpublishing/mui-components';\nimport { ManageSearch, InfoOutlined } from '@mui/icons-material';\n\ninterface Option {\n label: string;\n id: number;\n}\n\nexport default function WithMultipleDropdownActionsExample(): React.JSX.Element {\n const options: Option[] = [\n { label: 'Onet', id: 1 },\n { label: 'Fakt', id: 2 },\n { label: 'Komputer świat', id: 3 },\n { label: 'Newsweek', id: 4 },\n { label: 'Forbes', id: 5 },\n { label: 'Business insider', id: 6 },\n ];\n\n const actions: Action[] = [\n {\n icon: <ManageSearch />,\n onClick: () => console.log('Settings clicked'),\n label: 'Settings',\n },\n {\n icon: <InfoOutlined />,\n onClick: () => console.log('Info clicked'),\n label: 'Info',\n },\n ];\n\n return (\n <Autocomplete\n options={options}\n actions={actions}\n defaultValue={options[0]}\n labels={{ title: 'search by' }}\n sx={{ width: 300 }}\n />\n );\n}\n```\n\n## With Recently Used\n\nTrack and display recently selected items in a separate group. Items are stored in localStorage and persist across sessions.\n\n### Key Features:\n\n- Automatic grouping of recently used items\n- Configurable limit for stored items (default: 3)\n- Requires `recentlyLocalStorageKey` for persistence\n\n### Configuration:\n\n```typescript\nlabels={{\n title: 'search by',\n recentlyUsed: 'Recently used',\n recentlyUsedResults: 'Results',\n}}\nshowRecentlyUsed={true}\nrecentlyLocalStorageKey=\"recentlyUsed\"\nrecentlyUsedLimit={3}\n```\n\n```tsx\n// WithRecentlyUsedExample.tsx\nimport React from 'react';\nimport { Autocomplete } from '@ringpublishing/mui-components';\n\ninterface Option {\n label: string;\n id: number;\n}\n\nexport default function WithRecentlyUsedExample(): React.JSX.Element {\n const options: Option[] = [\n { label: 'Onet', id: 1 },\n { label: 'Fakt', id: 2 },\n { label: 'Komputer świat', id: 3 },\n { label: 'Newsweek', id: 4 },\n { label: 'Forbes', id: 5 },\n { label: 'Business insider', id: 6 },\n ];\n\n return (\n <Autocomplete\n options={options}\n defaultValue={options[0]}\n labels={{\n title: 'search by',\n recentlyUsed: 'Recently used',\n recentlyUsedResults: 'Results',\n }}\n showRecentlyUsed={true}\n recentlyLocalStorageKey=\"recentlyUsed\"\n recentlyUsedLimit={3}\n sx={{ width: 300 }}\n />\n );\n}\n```\n\n## With Caption\n\nDisplay additional caption text below each option label. Useful for providing extra context about each option.\n\n### Key Features:\n\n- Secondary text displayed below the main label\n- Automatic text overflow handling\n- Caption is part of the option object\n\n```tsx\n// WithCaptionExample.tsx\nimport React from 'react';\nimport { Autocomplete } from '@ringpublishing/mui-components';\n\ninterface OptionWithCaption {\n label: string;\n id: number;\n caption: string;\n}\n\nexport default function WithCaptionExample(): React.JSX.Element {\n const optionsWithCaption: OptionWithCaption[] = [\n { label: 'Onet', id: 1, caption: 'Onet portal' },\n { label: 'Fakt', id: 2, caption: 'Fakt o tym się mówi' },\n { label: 'Komputer świat', id: 3, caption: 'Porozmawiajmy o komputerach / O telefonach / O technologii' },\n { label: 'Newsweek', id: 4, caption: 'Newsweek' },\n { label: 'Forbes', id: 5, caption: 'Pieniądze' },\n { label: 'Business insider', id: 6, caption: 'O pieniądzach' },\n ];\n\n return (\n <Autocomplete\n options={optionsWithCaption}\n defaultValue={optionsWithCaption[0]}\n labels={{ title: 'search by' }}\n sx={{ width: 300 }}\n />\n );\n}\n```\n\n## With Avatar\n\nShow a leading avatar or image before each option label in the default renderer, without having to override `renderOption`.\n\n### Key Features:\n\n- Avatar is part of the option object (the `avatar` field)\n- A string is treated as an image URL and rendered inside a circular `Avatar`\n- A `ReactNode` (custom `Avatar`, icon or `img`) is rendered as-is\n- Customize the string avatar (border, size, variant, …) via `slotProps.avatar`\n- Works alongside `caption`\n\n```tsx\n// WithAvatarExample.tsx\nimport React from 'react';\nimport { Autocomplete } from '@ringpublishing/mui-components';\n\ninterface OptionWithAvatar {\n label: string;\n id: number;\n avatar: string;\n}\n\nexport default function WithAvatarExample(): React.JSX.Element {\n const optionsWithAvatar: OptionWithAvatar[] = [\n { label: 'Onet', id: 1, avatar: 'https://picsum.photos/seed/onet/48' },\n { label: 'Fakt', id: 2, avatar: 'https://picsum.photos/seed/fakt/48' },\n { label: 'Komputer świat', id: 3, avatar: 'https://picsum.photos/seed/komputer/48' },\n { label: 'Newsweek', id: 4, avatar: 'https://picsum.photos/seed/newsweek/48' },\n { label: 'Forbes', id: 5, avatar: 'https://picsum.photos/seed/forbes/48' },\n { label: 'Business insider', id: 6, avatar: 'https://picsum.photos/seed/business/48' },\n ];\n\n return (\n <Autocomplete\n options={optionsWithAvatar}\n defaultValue={optionsWithAvatar[0]}\n labels={{ title: 'search by' }}\n sx={{ width: 300 }}\n />\n );\n}\n```\n\n## With Customised Avatar\n\nCustomize the string (URL) option avatar — border, size, variant, etc. — via `slotProps.avatar`, without overriding `renderOption`.\n\n### Key Features:\n\n- `slotProps.avatar` accepts standard MUI `Avatar` props\n- `sx` is merged on top of the default sizing, so it can override size or add a border\n- Applies to string avatars only; a `ReactNode` avatar is styled directly on the node\n\n```tsx\n// WithCustomisedAvatarExample.tsx\nimport React from 'react';\nimport { Autocomplete } from '@ringpublishing/mui-components';\n\ninterface OptionWithAvatar {\n label: string;\n id: number;\n avatar: string;\n}\n\nexport default function WithCustomisedAvatarExample(): React.JSX.Element {\n const optionsWithAvatar: OptionWithAvatar[] = [\n { label: 'Onet', id: 1, avatar: 'https://picsum.photos/seed/onet/48' },\n { label: 'Fakt', id: 2, avatar: 'https://picsum.photos/seed/fakt/48' },\n { label: 'Komputer świat', id: 3, avatar: 'https://picsum.photos/seed/komputer/48' },\n { label: 'Newsweek', id: 4, avatar: 'https://picsum.photos/seed/newsweek/48' },\n { label: 'Forbes', id: 5, avatar: 'https://picsum.photos/seed/forbes/48' },\n { label: 'Business insider', id: 6, avatar: 'https://picsum.photos/seed/business/48' },\n ];\n\n return (\n <Autocomplete\n options={optionsWithAvatar}\n defaultValue={optionsWithAvatar[0]}\n labels={{ title: 'search by' }}\n sx={{ width: 300 }}\n slotProps={{\n avatar: {\n variant: 'rounded',\n sx: { border: '2px solid', borderColor: 'primary.main' },\n },\n }}\n />\n );\n}\n```\n\n## With Asynchronous Requests\n\nLoad options dynamically when the dropdown opens. Shows a loading indicator while data is being fetched.\n\n### Key Features:\n\n- Lazy loading of options on dropdown open\n- Built-in loading state and indicator\n- Options are cached after first load\n\n```tsx\n// WithAsynchronousRequestsExample.tsx\nimport React, { useState } from 'react';\nimport { Autocomplete } from '@ringpublishing/mui-components';\n\ninterface Option {\n label: string;\n id: number;\n}\n\nconst options: Option[] = [\n { label: 'Onet', id: 1 },\n { label: 'Fakt', id: 2 },\n { label: 'Komputer świat', id: 3 },\n { label: 'Newsweek', id: 4 },\n { label: 'Forbes', id: 5 },\n { label: 'Business insider', id: 6 },\n];\n\nfunction delaySleep(delay = 0): Promise<Option[]> {\n return new Promise((resolve) => {\n setTimeout(() => resolve(options), delay);\n });\n}\n\nexport default function WithAsynchronousRequestsExample(): React.JSX.Element {\n const [open, setOpen] = useState(false);\n const [items, setItems] = useState<Option[]>([]);\n const [loading, setLoading] = useState(false);\n\n const handleOpen = async (): Promise<void> => {\n setOpen(true);\n\n if (items.length > 0) {\n return;\n }\n\n setLoading(true);\n\n try {\n const data = await delaySleep(1000);\n setItems(data);\n } catch (error) {\n console.error(error);\n } finally {\n setLoading(false);\n }\n };\n\n return (\n <Autocomplete\n labels={{ title: 'search by' }}\n open={(!loading && open) || (open && items.length > 0)}\n onOpen={handleOpen}\n onClose={() => setOpen(false)}\n loading={loading}\n options={items}\n sx={{ width: 300 }}\n />\n );\n}\n```\n\n## With Customised Chips\n\nCustomize the appearance of selected value chips in multiple selection mode using `slotProps.chip`.\n\n### Key Features:\n\n- Custom chip color and size\n- Chips show tooltips with full label on hover\n- Uses MUI Chip props\n\n### Configuration:\n\n```typescript\nslotProps={{\n chip: {\n color: 'primary',\n size: 'small',\n },\n}}\n```\n\n```tsx\n// WithCustomisedChipsExample.tsx\nimport React from 'react';\nimport { Autocomplete } from '@ringpublishing/mui-components';\n\ninterface Option {\n label: string;\n id: number;\n}\n\nexport default function WithCustomisedChipsExample(): React.JSX.Element {\n const options: Option[] = [\n { label: 'Onet', id: 1 },\n { label: 'Fakt', id: 2 },\n { label: 'Komputer świat', id: 3 },\n { label: 'Newsweek', id: 4 },\n { label: 'Forbes', id: 5 },\n { label: 'Business insider', id: 6 },\n ];\n\n return (\n <Autocomplete\n options={options}\n defaultValue={[options[0], options[1]]}\n multiple\n slotProps={{\n chip: {\n color: 'primary',\n size: 'small',\n },\n }}\n labels={{ title: 'filter by' }}\n sx={{ width: 300 }}\n />\n );\n}\n```\n\n## With Customised Render Option\n\nFully customize how each option is rendered in the dropdown using the `renderOption` prop.\n\n### Key Features:\n\n- Complete control over option rendering\n- Can include icons, multiple text lines, or custom layouts\n- Receives option data and props for accessibility\n\n```tsx\n// WithCustomisedRenderOptionExample.tsx\nimport React from 'react';\nimport { Autocomplete } from '@ringpublishing/mui-components';\nimport { Box, Typography } from '@mui/material';\nimport { InfoOutlined } from '@mui/icons-material';\n\ninterface Option {\n label: string;\n id: number;\n}\n\nexport default function WithCustomisedRenderOptionExample(): React.JSX.Element {\n const options: Option[] = [\n { label: 'Onet', id: 1 },\n { label: 'Fakt', id: 2 },\n { label: 'Komputer świat', id: 3 },\n { label: 'Newsweek', id: 4 },\n { label: 'Forbes', id: 5 },\n { label: 'Business insider', id: 6 },\n ];\n\n return (\n <Autocomplete\n options={options}\n defaultValue={options[0]}\n labels={{ title: 'search by' }}\n sx={{ width: 300 }}\n renderOption={(props: React.HTMLAttributes<HTMLLIElement>, option: unknown): React.ReactNode => {\n const typedOption = option as Option;\n return (\n <li {...props}>\n <Box\n sx={{\n display: 'flex',\n alignItems: 'center',\n justifyContent: 'space-between',\n width: '100%',\n overflow: 'hidden',\n wordBreak: 'break-all',\n }}\n >\n <Typography>{typedOption.label}</Typography>\n <InfoOutlined />\n </Box>\n </li>\n );\n }}\n />\n );\n}\n```\n\n## With Free Solo\n\nAllow users to enter custom values that are not in the predefined options list. New values are added to the selection when the user types and confirms.\n\n### Key Features:\n\n- Users can type custom values\n- New values are converted to option objects\n- Combined with multiple selection mode\n\n```tsx\n// WithFreeSoloExample.tsx\nimport React, { useState } from 'react';\nimport { Autocomplete, AutocompleteChangeReason } from '@ringpublishing/mui-components';\n\ninterface Option {\n label: string;\n id: number;\n}\n\nexport default function WithFreeSoloExample(): React.JSX.Element {\n const options: Option[] = [\n { label: 'Onet', id: 1 },\n { label: 'Fakt', id: 2 },\n { label: 'Komputer świat', id: 3 },\n { label: 'Newsweek', id: 4 },\n { label: 'Forbes', id: 5 },\n { label: 'Business insider', id: 6 },\n ];\n\n const [value, setValue] = useState<Option[]>([options[0]]);\n\n return (\n <Autocomplete\n options={options}\n multiple\n freeSolo\n value={value}\n onChange={(event: React.SyntheticEvent, newValue: unknown, reason: AutocompleteChangeReason): void => {\n if (reason === 'createOption') {\n const newOption = (newValue as string[]).slice(-1)[0];\n newValue = [...value, { label: newOption, id: value.length + 1 }];\n }\n setValue(newValue as Option[]);\n }}\n labels={{ title: 'Free solo' }}\n sx={{ width: 300 }}\n />\n );\n}\n```\n\n## With Outlined TextField\n\nUse the outlined variant of the text field instead of the default filled variant.\n\n### Key Features:\n\n- Alternative text field design with border outline\n- Supports all other Autocomplete features\n- Uses MUI's `outlined` variant\n\n### Configuration:\n\n```typescript\n<Autocomplete\n options={options}\n labels={{ title: 'search by' }}\n slotProps={{\n textField: {\n variant: 'outlined'\n }\n }}\n/>\n```\n\n```tsx\n// WithOutlinedTextFieldExample.tsx\nimport { Autocomplete } from '@ringpublishing/mui-components';\nimport { InfoOutlined, ManageSearch } from '@mui/icons-material';\n\nexport default () => {\n const options = [\n { label: 'Onet', id: 1 },\n { label: 'Fakt', id: 2 },\n { label: 'Komputer świat', id: 3 },\n { label: 'Newsweek', id: 4 },\n { label: 'Forbes', id: 5 },\n { label: 'Business insider', id: 6 },\n ];\n\n const actions = [\n {\n icon: <ManageSearch />,\n onClick: () => null,\n label: 'Settings',\n },\n {\n icon: <InfoOutlined />,\n onClick: () => null,\n label: 'Info',\n },\n ];\n\n return (\n <div\n style={{\n display: 'flex',\n justifyContent: 'center',\n alignItems: 'center',\n }}\n >\n <Autocomplete\n actions={actions}\n options={options}\n multiple={true}\n defaultValue={options.slice(0, 5)}\n labels={{ title: 'search by' }}\n sx={{ width: 300 }}\n slotProps={{\n textField: {\n variant: 'outlined',\n },\n }}\n />\n </div>\n );\n};\n```"
|
|
965
|
-
},
|
|
966
|
-
"molecules-chips-group": {
|
|
967
|
-
"id": "molecules-chips-group",
|
|
968
|
-
"name": "ChipsGroup",
|
|
969
|
-
"category": "Molecules",
|
|
970
|
-
"title": "Components/Molecules/ChipsGroup",
|
|
971
|
-
"description": "The ChipsGroup component displays a collection of Chip components with intelligent automatic overflow handling. When chips don't fit in the available space, the component shows a \"+N\" indicator for hidden chips.",
|
|
972
|
-
"argTypes": {
|
|
973
|
-
"sx": {
|
|
974
|
-
"description": "MUI System properties to customize the main element style.",
|
|
975
|
-
"control": "object",
|
|
976
|
-
"category": "customization",
|
|
977
|
-
"type": "SxProps<Theme>"
|
|
978
|
-
},
|
|
979
|
-
"className": {
|
|
980
|
-
"description": "CSS class name applied to the main element.",
|
|
981
|
-
"control": "text",
|
|
982
|
-
"category": "customization",
|
|
983
|
-
"type": "string"
|
|
984
|
-
},
|
|
985
|
-
"dataTestIdSuffix": {
|
|
986
|
-
"description": "Suffix appended to the data-testid attribute for testing purposes.",
|
|
987
|
-
"control": "text",
|
|
988
|
-
"category": "testing",
|
|
989
|
-
"type": "string"
|
|
990
|
-
},
|
|
991
|
-
"chips": {
|
|
992
|
-
"description": "Array of MUI ChipProps defining the chips to display. Each chip can have custom properties like label, color, variant, onClick, and onDelete.",
|
|
993
|
-
"control": "object",
|
|
994
|
-
"category": "state",
|
|
995
|
-
"type": "ChipProps[]"
|
|
996
|
-
},
|
|
997
|
-
"expandable": {
|
|
998
|
-
"description": "When true, clicking \"+N\" expands hidden chips inline. When false, shows chips in a dropdown menu.",
|
|
999
|
-
"control": "boolean",
|
|
1000
|
-
"category": "behavior",
|
|
1001
|
-
"type": "boolean",
|
|
1002
|
-
"defaultValue": "false"
|
|
1003
|
-
},
|
|
1004
|
-
"collapsable": {
|
|
1005
|
-
"description": "When true and chips are expanded, shows a \"Show less\" button to collapse back. Only works when expandable is true.",
|
|
1006
|
-
"control": "boolean",
|
|
1007
|
-
"category": "behavior",
|
|
1008
|
-
"type": "boolean",
|
|
1009
|
-
"defaultValue": "false"
|
|
1010
|
-
},
|
|
1011
|
-
"customLabels": {
|
|
1012
|
-
"description": "Custom text labels for actions.",
|
|
1013
|
-
"control": "object",
|
|
1014
|
-
"category": "content",
|
|
1015
|
-
"type": "{ deleteAll?: string; showLess?: string }",
|
|
1016
|
-
"defaultValue": "{ deleteAll: \"Clear\", showLess: \"Show less\" }"
|
|
1017
|
-
},
|
|
1018
|
-
"onDeleteAll": {
|
|
1019
|
-
"description": "Callback fired when \"Clear\" button is clicked. When provided, displays a delete all button at the end of the chips group.",
|
|
1020
|
-
"control": false,
|
|
1021
|
-
"category": "callbacks",
|
|
1022
|
-
"type": "() => void"
|
|
1023
|
-
}
|
|
1024
|
-
},
|
|
1025
|
-
"storyNames": [
|
|
1026
|
-
"Default",
|
|
1027
|
-
"ChipsExpandable",
|
|
1028
|
-
"ChipsExpandableAndCollapsable",
|
|
1029
|
-
"DeleteAll",
|
|
1030
|
-
"CustomLabels"
|
|
1031
|
-
],
|
|
1032
|
-
"docs": "# ChipsGroup\n\nThe ChipsGroup component displays a collection of Chip components with intelligent automatic overflow handling. When chips don't fit in the available space, the component shows a \"+N\" indicator for hidden chips.\n\n## Features\n\n- **Automatic overflow handling**: Dynamically calculates visible chips and shows \"+N\" button for hidden ones\n- **Flexible display modes**:\n - Default mode shows hidden chips in a dropdown menu\n - Expandable mode displays hidden chips inline when \"+N\" is clicked\n - Collapsable mode allows returning to the compact view after expansion\n- **Delete all functionality**: Optional button to clear all chips at once\n- **Customizable labels**: Override default text for \"Clear\" and \"Show less\" buttons\n- **Responsive**: Adapts to container width changes\n- **Individual chip actions**: Each chip can have its own click, delete, and styling\n\n## Default\n\nThe basic usage shows chips in a container with automatic overflow handling. When chips exceed the container width, a dropdown menu displays hidden chips.\n\n```tsx\n// DefaultExample.tsx\nimport React from 'react';\nimport { ChipsGroup } from '@ringpublishing/mui-components';\n\nexport default function DefaultExample(): React.JSX.Element {\n const chips = [\n {\n id: '1',\n label: 'Chip 1',\n color: 'error' as const,\n variant: 'outlined' as const,\n },\n {\n id: '2',\n label: 'Chip 2',\n color: 'primary' as const,\n variant: 'filled' as const,\n onClick: (): null => null,\n },\n {\n id: '3',\n label: 'Chip 3',\n color: 'secondary' as const,\n variant: 'filled' as const,\n },\n {\n id: '4',\n label: 'Chip 4',\n color: 'secondary' as const,\n variant: 'filled' as const,\n },\n {\n id: '5',\n label: 'Chip 5',\n color: 'primary' as const,\n variant: 'outlined' as const,\n onClick: (): null => null,\n },\n {\n id: '6',\n label: 'Chip 6',\n color: 'secondary' as const,\n variant: 'filled' as const,\n },\n ];\n\n return (\n <div style={{ width: '250px' }}>\n <ChipsGroup chips={chips} />\n </div>\n );\n}\n```\n\n## Chips Expandable\n\nEnable inline expansion of hidden chips by setting `expandable={true}`. When the user clicks the \"+N\" button, all hidden chips are displayed inline rather than in a dropdown menu.\n\n### Key Features:\n\n- Click \"+N\" to expand and show all chips inline\n- Useful when you want all chips visible at once\n- Better for scenarios where users need to see all options simultaneously\n\n```tsx\n// ChipsExpandableExample.tsx\nimport React, { useState } from 'react';\nimport { ChipsGroup } from '@ringpublishing/mui-components';\n\nexport default function ChipsExpandableExample(): React.JSX.Element {\n const initialChips = [\n {\n id: '1',\n label: 'Chip 1',\n color: 'error' as const,\n variant: 'outlined' as const,\n },\n {\n id: '2',\n label: 'Chip 2',\n color: 'primary' as const,\n variant: 'filled' as const,\n onClick: (): null => null,\n onDelete: () => {\n setChips((prevChips) => prevChips.filter((chip) => chip.id !== '2'));\n },\n },\n {\n id: '3',\n label: 'Chip 3',\n color: 'secondary' as const,\n variant: 'filled' as const,\n },\n {\n id: '4',\n label: 'Chip 4',\n color: 'secondary' as const,\n variant: 'filled' as const,\n },\n {\n id: '5',\n label: 'Chip 5',\n color: 'primary' as const,\n variant: 'outlined' as const,\n onClick: (): null => null,\n },\n {\n id: '6',\n label: 'Chip 6',\n color: 'secondary' as const,\n variant: 'filled' as const,\n },\n ];\n\n const [chips, setChips] = useState(initialChips);\n\n return (\n <div style={{ width: '250px' }}>\n <ChipsGroup chips={chips} expandable={true} />\n </div>\n );\n}\n```\n\n## Chips Expandable and Collapsable\n\nCombine `expandable` and `collapsable` props to allow users to toggle between compact and expanded views. After expanding, a \"Show less\" button appears to collapse the chips back to the original state.\n\n### Key Features:\n\n- Expand chips inline with \"+N\" button\n- Collapse back with \"Show less\" button\n- Gives users control over the view density\n\n```tsx\n// ChipsExpandableAndCollapsableExample.tsx\nimport React, { useState } from 'react';\nimport { ChipsGroup } from '@ringpublishing/mui-components';\n\nexport default function ChipsExpandableAndCollapsableExample(): React.JSX.Element {\n const initialChips = [\n {\n id: '1',\n label: 'Chip 1',\n color: 'error' as const,\n variant: 'outlined' as const,\n },\n {\n id: '2',\n label: 'Chip 2',\n color: 'primary' as const,\n variant: 'filled' as const,\n onClick: (): null => null,\n onDelete: () => {\n setChips((prevChips) => prevChips.filter((chip) => chip.id !== '2'));\n },\n },\n {\n id: '3',\n label: 'Chip 3',\n color: 'secondary' as const,\n variant: 'filled' as const,\n },\n {\n id: '4',\n label: 'Chip 4',\n color: 'secondary' as const,\n variant: 'filled' as const,\n },\n {\n id: '5',\n label: 'Chip 5',\n color: 'primary' as const,\n variant: 'outlined' as const,\n onClick: (): null => null,\n },\n {\n id: '6',\n label: 'Chip 6',\n color: 'secondary' as const,\n variant: 'filled' as const,\n },\n ];\n\n const [chips, setChips] = useState(initialChips);\n\n return (\n <div style={{ width: '250px' }}>\n <ChipsGroup chips={chips} expandable={true} collapsable={true} />\n </div>\n );\n}\n```\n\n## Delete All\n\nAdd a delete all button by providing the `onDeleteAll` callback. This displays a \"Clear\" button at the end of the chips group, allowing users to remove all chips with a single click.\n\n### Usage:\n\n```typescript\n<ChipsGroup\n chips={chips}\n onDeleteAll={() => handleClearAll()}\n/>\n```\n\n```tsx\n// DeleteAllExample.tsx\nimport React, { useState } from 'react';\nimport { ChipsGroup } from '@ringpublishing/mui-components';\n\nexport default function DeleteAllExample(): React.JSX.Element {\n const initialChips = [\n {\n id: '1',\n label: 'Chip 1',\n color: 'error' as const,\n variant: 'outlined' as const,\n onDelete: () => {\n setChips((prevChips) => prevChips.filter((chip) => chip.id !== '1'));\n },\n },\n {\n id: '2',\n label: 'Chip 2',\n color: 'primary' as const,\n variant: 'filled' as const,\n onClick: (): null => null,\n onDelete: () => {\n setChips((prevChips) => prevChips.filter((chip) => chip.id !== '2'));\n },\n },\n ];\n\n const [chips, setChips] = useState(initialChips);\n\n return (\n <div style={{ width: '250px' }}>\n <ChipsGroup chips={chips} onDeleteAll={() => setChips([])} />\n </div>\n );\n}\n```\n\n## Custom Labels\n\nCustomize the text for action buttons using the `customLabels` prop. This is useful for internationalization or matching your application's terminology.\n\n### Available Labels:\n\n- `deleteAll`: Text for the delete all button (default: \"Clear\")\n- `showLess`: Text for the collapse button (default: \"Show less\")\n\n### Usage:\n\n```typescript\n<ChipsGroup\n chips={chips}\n expandable\n collapsable\n onDeleteAll={handleClearAll}\n customLabels={{\n deleteAll: 'Delete all chips',\n showLess: 'Hide'\n }}\n/>\n```\n\n```tsx\n// CustomLabelsExample.tsx\nimport React, { useState } from 'react';\nimport { ChipsGroup } from '@ringpublishing/mui-components';\n\nexport default function CustomLabelsExample(): React.JSX.Element {\n const initialChips = [\n {\n id: '1',\n label: 'Chip 1',\n color: 'error' as const,\n variant: 'outlined' as const,\n },\n {\n id: '2',\n label: 'Chip 2',\n color: 'primary' as const,\n variant: 'filled' as const,\n onClick: (): null => null,\n },\n {\n id: '3',\n label: 'Chip 3',\n color: 'secondary' as const,\n variant: 'filled' as const,\n },\n {\n id: '4',\n label: 'Chip 4',\n color: 'secondary' as const,\n variant: 'filled' as const,\n },\n {\n id: '5',\n label: 'Chip 5',\n color: 'primary' as const,\n variant: 'outlined' as const,\n onClick: (): null => null,\n },\n {\n id: '6',\n label: 'Chip 6',\n color: 'secondary' as const,\n variant: 'filled' as const,\n onDelete: () => {\n setChips((prevChips) => prevChips.filter((chip) => chip.id !== '6'));\n },\n },\n ];\n\n const [chips, setChips] = useState(initialChips);\n\n return (\n <div style={{ width: '250px' }}>\n <ChipsGroup\n chips={chips}\n expandable\n collapsable\n onDeleteAll={() => setChips([])}\n customLabels={{\n deleteAll: 'Delete all chips',\n showLess: 'Hide',\n }}\n />\n </div>\n );\n}\n```"
|
|
1033
|
-
},
|
|
1034
|
-
"molecules-chips-input": {
|
|
1035
|
-
"id": "molecules-chips-input",
|
|
1036
|
-
"name": "ChipsInput",
|
|
1037
|
-
"category": "Molecules",
|
|
1038
|
-
"title": "Components/Molecules/ChipsInput",
|
|
1039
|
-
"description": "ChipsInput is an interactive input component that allows users to create and manage a collection of chips (tags). Users can add new chips by typing and pressing Enter, or by pasting values. Each chip can be individually removed, and the component supports validation and duplicate detection.",
|
|
1040
|
-
"argTypes": {
|
|
1041
|
-
"sx": {
|
|
1042
|
-
"description": "MUI System properties to customize the main element style.",
|
|
1043
|
-
"control": "object",
|
|
1044
|
-
"category": "customization",
|
|
1045
|
-
"type": "SxProps<Theme>"
|
|
1046
|
-
},
|
|
1047
|
-
"className": {
|
|
1048
|
-
"description": "CSS class name applied to the main element.",
|
|
1049
|
-
"control": "text",
|
|
1050
|
-
"category": "customization",
|
|
1051
|
-
"type": "string"
|
|
1052
|
-
},
|
|
1053
|
-
"dataTestIdSuffix": {
|
|
1054
|
-
"description": "Test ID suffix for testing purposes.",
|
|
1055
|
-
"control": "text",
|
|
1056
|
-
"category": "testing",
|
|
1057
|
-
"type": "string"
|
|
1058
|
-
},
|
|
1059
|
-
"labels": {
|
|
1060
|
-
"description": "Text labels for the component (required). Includes title, inputPlaceholder, and alreadyOnList message.",
|
|
1061
|
-
"control": "object",
|
|
1062
|
-
"category": "content",
|
|
1063
|
-
"type": "{ title?: string; inputPlaceholder?: string; alreadyOnList: string }"
|
|
1064
|
-
},
|
|
1065
|
-
"validationFunction": {
|
|
1066
|
-
"description": "Optional function to validate chip values. Return true for valid chips, false for invalid. Invalid chips are displayed with error color.",
|
|
1067
|
-
"control": false,
|
|
1068
|
-
"category": "validation",
|
|
1069
|
-
"type": "(value: AutocompleteChip) => boolean"
|
|
1070
|
-
},
|
|
1071
|
-
"onChange": {
|
|
1072
|
-
"description": "Callback fired when chips are added or removed. Receives the updated array of chips.",
|
|
1073
|
-
"control": false,
|
|
1074
|
-
"category": "callbacks",
|
|
1075
|
-
"type": "(value: AutocompleteChip[]) => void"
|
|
1076
|
-
},
|
|
1077
|
-
"value": {
|
|
1078
|
-
"description": "Controlled value for the chips. When provided, component works in controlled mode.",
|
|
1079
|
-
"control": "object",
|
|
1080
|
-
"category": "state",
|
|
1081
|
-
"type": "AutocompleteChip[]"
|
|
1082
|
-
},
|
|
1083
|
-
"chipsColors": {
|
|
1084
|
-
"description": "Custom colors for chips. Configure colors for valid (default) and invalid (error) states.",
|
|
1085
|
-
"control": "object",
|
|
1086
|
-
"category": "customization",
|
|
1087
|
-
"type": "{ default: ChipColor; error: ChipColor }",
|
|
1088
|
-
"defaultValue": "{ default: ChipColor.DEFAULT, error: ChipColor.ERROR }"
|
|
1089
|
-
}
|
|
1090
|
-
},
|
|
1091
|
-
"storyNames": [
|
|
1092
|
-
"Default",
|
|
1093
|
-
"CustomColors",
|
|
1094
|
-
"NoValidation"
|
|
1095
|
-
],
|
|
1096
|
-
"docs": "# ChipsInput\n\nChipsInput is an interactive input component that allows users to create and manage a collection of chips (tags). Users can add new chips by typing and pressing Enter, or by pasting values. Each chip can be individually removed, and the component supports validation and duplicate detection.\n\n**Key Features:**\n\n- **Easy Input**: Add chips by typing and pressing Enter or by pasting values\n- **Validation Support**: Optional validation function to mark invalid chips\n- **Duplicate Detection**: Prevents adding duplicate values with user feedback\n- **Custom Colors**: Configure chip colors for valid and invalid states\n- **Controlled/Uncontrolled**: Works with both controlled and uncontrolled value patterns\n- **Accessible**: Built on MUI Autocomplete with full keyboard support\n\n**Common Use Cases:**\n\n- Tag input for categorization\n- ID or value filters\n- Email address lists\n- Keyword management\n\n## Default\n\nThe default story shows ChipsInput with numeric validation. Only numeric values are accepted as valid chips, and invalid chips are displayed with an error color.\n\nTry adding both valid numbers (e.g., \"123\") and invalid text (e.g., \"abc\") to see the validation in action.\n\n```tsx\n// DefaultExample.tsx\nimport React from 'react';\nimport { Box } from '@mui/material';\nimport { ChipsInput, AutocompleteChip } from '@ringpublishing/mui-components';\n\nexport default function DefaultExample(): React.JSX.Element {\n return (\n <Box sx={{ width: '300px' }}>\n <ChipsInput\n labels={{\n title: 'Chips input',\n inputPlaceholder: 'Insert value and press enter',\n alreadyOnList: 'Already on list',\n }}\n validationFunction={(value: AutocompleteChip) => {\n return !isNaN(parseInt(value.label));\n }}\n onChange={(value: AutocompleteChip[]) => console.log(value)}\n />\n </Box>\n );\n}\n```\n\n## Custom Colors\n\nThis story demonstrates how to customize chip colors for different validation states. In this example, the component validates email addresses and uses custom colors: green (success) for valid emails and orange (warning) for invalid ones.\n\n### Usage:\n\n```typescript\n<ChipsInput\n labels={{\n title: 'Email validation',\n inputPlaceholder: 'Enter email address',\n alreadyOnList: 'Email already added'\n }}\n validationFunction={(value) => {\n const emailRegex = /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/;\n return emailRegex.test(value.label);\n }}\n chipsColors={{\n default: ChipColor.SUCCESS,\n error: ChipColor.WARNING\n }}\n onChange={(value) => console.log(value)}\n/>\n```\n\n```tsx\n// CustomColorsExample.tsx\nimport React from 'react';\nimport { Box } from '@mui/material';\nimport { ChipsInput, AutocompleteChip, ChipColor } from '@ringpublishing/mui-components';\n\nexport default function CustomColorsExample(): React.JSX.Element {\n return (\n <Box sx={{ width: '300px' }}>\n <ChipsInput\n labels={{\n title: 'Email validation',\n inputPlaceholder: 'Enter email address',\n alreadyOnList: 'Email already added',\n }}\n validationFunction={(value: AutocompleteChip) => {\n const emailRegex = /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/;\n\n return emailRegex.test(value.label);\n }}\n chipsColors={{\n default: ChipColor.SUCCESS,\n error: ChipColor.WARNING,\n }}\n onChange={(value: AutocompleteChip[]) => console.log(value)}\n />\n </Box>\n );\n}\n```\n\n## No Validation\n\nThis story demonstrates ChipsInput without any validation. All entered values are accepted as valid chips with the default color scheme. This is useful when you want to accept any user input without restrictions.\n\n### Key Features:\n\n- No validation function provided\n- All chips use the default color\n- Simplest configuration\n- Still prevents duplicates\n\n### Usage:\n\n```typescript\n<ChipsInput\n labels={{\n title: 'Tags',\n inputPlaceholder: 'Add any tag',\n alreadyOnList: 'Tag already exists'\n }}\n onChange={(value) => console.log(value)}\n/>\n```\n\n```tsx\n// NoValidationExample.tsx\nimport { Box } from '@mui/material';\nimport { ChipsInput, AutocompleteChip } from '@ringpublishing/mui-components';\nimport React from 'react';\n\nexport default function NoValidationExample(): React.JSX.Element {\n return (\n <Box sx={{ width: '300px' }}>\n <ChipsInput\n labels={{\n title: 'Tags',\n inputPlaceholder: 'Add any tag',\n alreadyOnList: 'Tag already exists',\n }}\n onChange={(value: AutocompleteChip[]) => console.log(value)}\n />\n </Box>\n );\n}\n```"
|
|
1097
|
-
},
|
|
1098
|
-
"molecules-feature-tooltip": {
|
|
1099
|
-
"id": "molecules-feature-tooltip",
|
|
1100
|
-
"name": "FeatureTooltip",
|
|
1101
|
-
"category": "Molecules",
|
|
1102
|
-
"title": "Components/Molecules/FeatureTooltip",
|
|
1103
|
-
"description": "A feature announcement tooltip that automatically manages its display state using `localStorage`. It extends MUI's [Tooltip](https://mui.com/material-ui/react-tooltip/) with a rich card layout, supporting media content, configurable action buttons, and frequency-capping logic.",
|
|
1104
|
-
"argTypes": {
|
|
1105
|
-
"title": {
|
|
1106
|
-
"description": "Feature tooltip title displayed in the header of the tooltip card.",
|
|
1107
|
-
"control": "text",
|
|
1108
|
-
"category": "content",
|
|
1109
|
-
"type": "string"
|
|
1110
|
-
},
|
|
1111
|
-
"message": {
|
|
1112
|
-
"description": "Feature tooltip message body. Not required if `videoEmbed` is passed.",
|
|
1113
|
-
"control": "text",
|
|
1114
|
-
"category": "content",
|
|
1115
|
-
"type": "string"
|
|
1116
|
-
},
|
|
1117
|
-
"actions": {
|
|
1118
|
-
"description": "Action buttons for the tooltip footer. Accepts up to two actions: `[primaryAction, secondaryAction?]`. Each action can have `label`, `href`, `onClick`, and `icon` fields.",
|
|
1119
|
-
"control": "object",
|
|
1120
|
-
"category": "content",
|
|
1121
|
-
"type": "[{ label: string; href?: string; onClick?: (e) => void; icon?: ReactNode }, ...?]"
|
|
1122
|
-
},
|
|
1123
|
-
"videoEmbed": {
|
|
1124
|
-
"description": "URL to embed a video (e.g. YouTube). Ensure the URL contains `/embed/`. Not required if `message` is passed. Takes priority over `image`.",
|
|
1125
|
-
"control": "text",
|
|
1126
|
-
"category": "content",
|
|
1127
|
-
"type": "ReactNode"
|
|
1128
|
-
},
|
|
1129
|
-
"image": {
|
|
1130
|
-
"description": "URL to an image displayed in the tooltip card. Not shown if `videoEmbed` is also provided.",
|
|
1131
|
-
"control": "text",
|
|
1132
|
-
"category": "content",
|
|
1133
|
-
"type": "string"
|
|
1134
|
-
},
|
|
1135
|
-
"children": {
|
|
1136
|
-
"description": "The element that triggers and anchors the tooltip. Must be a single React element (e.g. a `<div>` or `<Button>`).",
|
|
1137
|
-
"category": "content",
|
|
1138
|
-
"type": "React.ReactElement"
|
|
1139
|
-
},
|
|
1140
|
-
"id": {
|
|
1141
|
-
"description": "Unique identifier for the tooltip instance. Used to track and persist display state in `localStorage`. Must be unique across all tooltip instances in your application.",
|
|
1142
|
-
"control": "text",
|
|
1143
|
-
"category": "behavior",
|
|
1144
|
-
"type": "string"
|
|
1145
|
-
},
|
|
1146
|
-
"endDate": {
|
|
1147
|
-
"description": "ISO date string after which the tooltip will no longer be shown. Example: `\"2026-12-31T00:00:00.000Z\"`.",
|
|
1148
|
-
"control": "text",
|
|
1149
|
-
"category": "behavior",
|
|
1150
|
-
"type": "string"
|
|
1151
|
-
},
|
|
1152
|
-
"capping": {
|
|
1153
|
-
"description": "Maximum number of times the tooltip can be shown to the user. The display count is persisted in `localStorage`.",
|
|
1154
|
-
"control": "number",
|
|
1155
|
-
"category": "behavior",
|
|
1156
|
-
"type": "number",
|
|
1157
|
-
"defaultValue": "1"
|
|
1158
|
-
},
|
|
1159
|
-
"showDelay": {
|
|
1160
|
-
"description": "Delay in milliseconds before the tooltip appears after mounting.",
|
|
1161
|
-
"control": "number",
|
|
1162
|
-
"category": "behavior",
|
|
1163
|
-
"type": "number",
|
|
1164
|
-
"defaultValue": "0"
|
|
1165
|
-
},
|
|
1166
|
-
"offset": {
|
|
1167
|
-
"description": "Positional offset applied to the tooltip: `[x-offset, y-offset]`.",
|
|
1168
|
-
"control": "object",
|
|
1169
|
-
"category": "appearance",
|
|
1170
|
-
"type": "[number, number]"
|
|
1171
|
-
},
|
|
1172
|
-
"onShow": {
|
|
1173
|
-
"description": "Callback fired when the tooltip becomes visible.",
|
|
1174
|
-
"category": "callbacks",
|
|
1175
|
-
"type": "() => void"
|
|
1176
|
-
},
|
|
1177
|
-
"onClose": {
|
|
1178
|
-
"description": "Callback fired when the user dismisses the tooltip by clicking the '×' close button.",
|
|
1179
|
-
"category": "callbacks",
|
|
1180
|
-
"type": "() => void"
|
|
1181
|
-
},
|
|
1182
|
-
"sx": {
|
|
1183
|
-
"description": "MUI System properties to customize the root element style.",
|
|
1184
|
-
"control": "object",
|
|
1185
|
-
"category": "customization",
|
|
1186
|
-
"type": "SxProps<Theme>"
|
|
1187
|
-
},
|
|
1188
|
-
"className": {
|
|
1189
|
-
"description": "CSS class name applied to the root element.",
|
|
1190
|
-
"control": "text",
|
|
1191
|
-
"category": "customization",
|
|
1192
|
-
"type": "string"
|
|
1193
|
-
},
|
|
1194
|
-
"dataTestIdSuffix": {
|
|
1195
|
-
"description": "Optional suffix appended to the generated `data-testid` attribute (base: `ring-featuretooltip`).",
|
|
1196
|
-
"control": "text",
|
|
1197
|
-
"category": "customization",
|
|
1198
|
-
"type": "string"
|
|
1199
|
-
}
|
|
1200
|
-
},
|
|
1201
|
-
"storyNames": [
|
|
1202
|
-
"Default",
|
|
1203
|
-
"WithOneAction",
|
|
1204
|
-
"WithNoActions",
|
|
1205
|
-
"WithImage"
|
|
1206
|
-
],
|
|
1207
|
-
"docs": "# FeatureTooltip\n\nA feature announcement tooltip that automatically manages its display state using `localStorage`. It extends MUI's [Tooltip](https://mui.com/material-ui/react-tooltip/) with a rich card layout, supporting media content, configurable action buttons, and frequency-capping logic.\n\n- Displays automatically on mount based on `capping` count and `endDate` expiration\n- Persists display history in `localStorage` to control re-display frequency\n- Supports text messages, embedded videos (`videoEmbed`), and images (`image`)\n- Configurable action buttons — up to two: primary and optional secondary\n- Close button always available for the user\n\n## Default\n\nShows two tooltip configurations side by side: a **standard tooltip** (displayed only once per user) and a **capping tooltip** (displayed up to 3 times). Both use `localStorage` to track display history.\n\n> **Note:** If you don't see the tooltip, click **Clear tooltip data** to reset the `localStorage` state and reload the page.\n\n```tsx\n// DefaultExample.tsx\nimport { Box, Button } from '@mui/material';\nimport { FeatureTooltip, FeatureTooltipProps } from '@ringpublishing/mui-components';\nimport React from 'react';\n\nconst actions: FeatureTooltipProps['actions'] = [\n { label: 'Default action', href: 'https://ringpublishing.com/' },\n { label: 'Secondary action', onClick: (): void => console.log('Secondary action clicked') },\n];\n\nexport default function DefaultExample(): React.JSX.Element {\n const clearTooltipData = (): void => {\n try {\n localStorage.removeItem('FeatureTooltips');\n location.reload();\n } catch (error) {\n console.warn(error);\n }\n };\n\n return (\n <Box sx={{ width: '80%' }}>\n <Box sx={{ display: 'flex', justifyContent: 'space-between' }}>\n <FeatureTooltip\n id=\"ring-feature-tooltip-1\"\n title=\"Standard tooltip\"\n message=\"There are many variations of passages of Lorem Ipsum available, but the majority have suffered alteration in some form\"\n actions={actions}\n endDate=\"2026-06-24T10:49:20.823Z\"\n >\n <div style={{ width: '200px' }}>Tooltip shown only once, after closing not visible</div>\n </FeatureTooltip>\n\n <FeatureTooltip\n id=\"ring-feature-tooltip-capping\"\n title=\"Tooltip with capping\"\n capping={3}\n message=\"\"\n videoEmbed=\"https://www.youtube.com/embed/KRphOlc8tKg?si=xUR6gOpAPDcR74Dk\"\n actions={actions}\n endDate=\"2026-06-24T10:49:20.823Z\"\n >\n <div style={{ width: '200px' }}>Tooltip with capping (should be visible 3 times)</div>\n </FeatureTooltip>\n </Box>\n\n <Box sx={{ display: 'flex', justifyContent: 'center', alignItems: 'center', mt: 2 }}>\n If you do not see tooltip:\n <Button onClick={clearTooltipData} variant=\"outlined\" color=\"primary\" sx={{ ml: 1 }}>\n Clear tooltip data\n </Button>\n </Box>\n </Box>\n );\n}\n```\n\n## With One Action\n\nA tooltip with a **single primary action** button and an embedded YouTube video. Use this when you want to direct users to a specific resource without offering a secondary option.\n\n```tsx\n// WithOneActionExample.tsx\nimport React from 'react';\nimport { Box, Button } from '@mui/material';\nimport { FeatureTooltip } from '@ringpublishing/mui-components';\n\nexport default function WithOneActionExample(): React.JSX.Element {\n const clearTooltipData = (): void => {\n try {\n localStorage.removeItem('FeatureTooltips');\n location.reload();\n } catch (error) {\n console.warn(error);\n }\n };\n\n return (\n <Box sx={{ width: '80%' }}>\n <FeatureTooltip\n id=\"ring-feature-tooltip-2\"\n title=\"Tooltip with one action\"\n message=\"There are many variations of passages of Lorem Ipsum available, but the majority have suffered alteration in some form\"\n actions={[{ label: 'Default action', href: 'https://ringpublishing.com/' }]}\n videoEmbed=\"https://www.youtube.com/embed/KRphOlc8tKg?si=xUR6gOpAPDcR74Dk\"\n endDate=\"2026-06-24T10:49:20.823Z\"\n >\n <div style={{ width: '200px' }}>Tooltip with one action and video embed</div>\n </FeatureTooltip>\n\n <Box sx={{ display: 'flex', justifyContent: 'center', alignItems: 'center', mt: 2 }}>\n If you do not see tooltip:\n <Button onClick={clearTooltipData} variant=\"outlined\" color=\"primary\" sx={{ ml: 1 }}>\n Clear tooltip data\n </Button>\n </Box>\n </Box>\n );\n}\n```\n\n## With No Actions\n\nA tooltip displaying only a title and message body — without any action buttons. Ideal for purely informational announcements where no user interaction is needed beyond dismissal.\n\n```tsx\n// WithNoActionsExample.tsx\nimport React from 'react';\nimport { Box, Button } from '@mui/material';\nimport { FeatureTooltip } from '@ringpublishing/mui-components';\n\nexport default function WithNoActionsExample(): React.JSX.Element {\n const clearTooltipData = (): void => {\n try {\n localStorage.removeItem('FeatureTooltips');\n location.reload();\n } catch (error) {\n console.warn(error);\n }\n };\n\n return (\n <Box sx={{ width: '80%' }}>\n <FeatureTooltip\n id=\"ring-feature-tooltip-3\"\n title=\"Tooltip with no actions\"\n message=\"There are many variations of passages of Lorem Ipsum available, but the majority have suffered alteration in some form\"\n endDate=\"2026-06-24T10:49:20.823Z\"\n >\n <div style={{ width: '200px' }}>Tooltip without action buttons</div>\n </FeatureTooltip>\n\n <Box sx={{ display: 'flex', justifyContent: 'center', alignItems: 'center', mt: 2 }}>\n If you do not see tooltip:\n <Button onClick={clearTooltipData} variant=\"outlined\" color=\"primary\" sx={{ ml: 1 }}>\n Clear tooltip data\n </Button>\n </Box>\n </Box>\n );\n}\n```\n\n## With Image\n\nA tooltip enriched with an **image**. Shown side by side: one variant with two action buttons, another without actions — both using the same image URL.\n\n> **Note:** If both `image` and `videoEmbed` are passed, the **video takes priority** and the image is not rendered.\n\n```tsx\n// WithImageExample.tsx\nimport { Box, Button } from '@mui/material';\nimport { FeatureTooltip, FeatureTooltipProps } from '@ringpublishing/mui-components';\nimport React from 'react';\n\nconst IMAGE_URL = 'https://design.ringpublishing.com/images/sea_large.jpg';\n\nconst actions: FeatureTooltipProps['actions'] = [\n { label: 'Default action', href: 'https://ringpublishing.com/' },\n { label: 'Secondary action', onClick: (): void => console.log('Secondary action clicked') },\n];\n\nexport default function WithImageExample(): React.JSX.Element {\n const clearTooltipData = (): void => {\n try {\n localStorage.removeItem('FeatureTooltips');\n location.reload();\n } catch (error) {\n console.warn(error);\n }\n };\n\n return (\n <Box sx={{ width: '80%' }}>\n <Box sx={{ display: 'flex', justifyContent: 'space-between' }}>\n <FeatureTooltip\n id=\"ring-feature-tooltip-4\"\n title=\"Tooltip with image and actions\"\n message=\"\"\n image={IMAGE_URL}\n actions={actions}\n endDate=\"2026-06-24T10:49:20.823Z\"\n >\n <div style={{ width: '200px' }}>Tooltip with image and two actions</div>\n </FeatureTooltip>\n\n <FeatureTooltip\n id=\"ring-feature-tooltip-4b\"\n title=\"Tooltip with image, no actions\"\n message=\"\"\n image={IMAGE_URL}\n endDate=\"2026-06-24T10:49:20.823Z\"\n >\n <div style={{ width: '200px' }}>Tooltip with image and no actions</div>\n </FeatureTooltip>\n </Box>\n\n <Box sx={{ display: 'flex', justifyContent: 'center', alignItems: 'center', mt: 2 }}>\n If you do not see tooltip:\n <Button onClick={clearTooltipData} variant=\"outlined\" color=\"primary\" sx={{ ml: 1 }}>\n Clear tooltip data\n </Button>\n </Box>\n </Box>\n );\n}\n```"
|
|
1208
|
-
},
|
|
1209
|
-
"molecules-media": {
|
|
1210
|
-
"id": "molecules-media",
|
|
1211
|
-
"name": "Media",
|
|
1212
|
-
"category": "Molecules",
|
|
1213
|
-
"title": "Components/Molecules/Media",
|
|
1214
|
-
"description": "Renders multimedia content (images, video, and audio) in a card container with configurable overlays and interactive elements.",
|
|
1215
|
-
"argTypes": {
|
|
1216
|
-
"sx": {
|
|
1217
|
-
"description": "MUI System properties to customize the card container style.",
|
|
1218
|
-
"control": "object",
|
|
1219
|
-
"category": "customization",
|
|
1220
|
-
"type": "SxProps<Theme>",
|
|
1221
|
-
"defaultValue": "{}"
|
|
1222
|
-
},
|
|
1223
|
-
"className": {
|
|
1224
|
-
"description": "CSS class name applied to the root element.",
|
|
1225
|
-
"control": "text",
|
|
1226
|
-
"category": "customization",
|
|
1227
|
-
"type": "string"
|
|
1228
|
-
},
|
|
1229
|
-
"image": {
|
|
1230
|
-
"description": "Image source. Accepts a URL string or an Image object with `src`, `thumbnailSrc`, and `title`. When not provided, an icon placeholder is shown.",
|
|
1231
|
-
"control": "object",
|
|
1232
|
-
"category": "content",
|
|
1233
|
-
"type": "string | { src: string; thumbnailSrc: string; title: string }"
|
|
1234
|
-
},
|
|
1235
|
-
"title": {
|
|
1236
|
-
"description": "Caption text displayed in the bottom left corner below the media.",
|
|
1237
|
-
"control": "text",
|
|
1238
|
-
"category": "content",
|
|
1239
|
-
"type": "string"
|
|
1240
|
-
},
|
|
1241
|
-
"description": {
|
|
1242
|
-
"description": "Secondary text displayed below the title.",
|
|
1243
|
-
"control": "text",
|
|
1244
|
-
"category": "content",
|
|
1245
|
-
"type": "string"
|
|
1246
|
-
},
|
|
1247
|
-
"type": {
|
|
1248
|
-
"description": "Media type label displayed in the top left corner above the image.",
|
|
1249
|
-
"control": "text",
|
|
1250
|
-
"category": "content",
|
|
1251
|
-
"type": "'image' | 'video' | 'embed'"
|
|
1252
|
-
},
|
|
1253
|
-
"statusLabels": {
|
|
1254
|
-
"description": "Collection of Chip labels overlaid on the top-left corner of the media. Each entry accepts `label`, `color`, and `icon` (MUI ChipProps).",
|
|
1255
|
-
"control": "object",
|
|
1256
|
-
"category": "content",
|
|
1257
|
-
"type": "{ label: ReactNode; color?: ChipProps['color']; icon?: ReactElement }[]"
|
|
1258
|
-
},
|
|
1259
|
-
"actions": {
|
|
1260
|
-
"description": "Context menu actions accessible via the three-dot icon button in the top-right corner. When empty, the icon button is not rendered.",
|
|
1261
|
-
"control": "object",
|
|
1262
|
-
"category": "content",
|
|
1263
|
-
"type": "{ label: string; icon?: ReactNode }[]"
|
|
1264
|
-
},
|
|
1265
|
-
"bottomTooltips": {
|
|
1266
|
-
"description": "Tooltip icon buttons displayed in the bottom-left corner over the media.",
|
|
1267
|
-
"control": "object",
|
|
1268
|
-
"category": "content",
|
|
1269
|
-
"type": "{ title: string; icon: ReactNode }[]"
|
|
1270
|
-
},
|
|
1271
|
-
"disableFullScreenPreview": {
|
|
1272
|
-
"description": "Disables the LightBox full-screen preview when the image is clicked. The `image` prop must be set for this to have effect.",
|
|
1273
|
-
"control": "boolean",
|
|
1274
|
-
"category": "behavior",
|
|
1275
|
-
"type": "boolean",
|
|
1276
|
-
"defaultValue": "false"
|
|
1277
|
-
},
|
|
1278
|
-
"onTitleSubmit": {
|
|
1279
|
-
"description": "Callback invoked when the title is submitted in edit mode. When provided, the title becomes editable via EditableText. Should return a Promise resolving to true on success or false on failure.",
|
|
1280
|
-
"category": "callbacks",
|
|
1281
|
-
"type": "(value: string) => Promise<boolean>"
|
|
1282
|
-
},
|
|
1283
|
-
"onDescriptionSubmit": {
|
|
1284
|
-
"description": "Callback invoked when the description is submitted in edit mode. When provided, the description becomes editable via EditableText. Should return a Promise resolving to true on success or false on failure.",
|
|
1285
|
-
"category": "callbacks",
|
|
1286
|
-
"type": "(value: string) => Promise<boolean>"
|
|
1287
|
-
},
|
|
1288
|
-
"ratio": {
|
|
1289
|
-
"description": "Aspect ratio of the media container (e.g. `\"4/3\"`, `\"16/9\"`, `\"18/1\"`). Accepts a CSS aspect-ratio string or a number.",
|
|
1290
|
-
"control": "text",
|
|
1291
|
-
"category": "appearance",
|
|
1292
|
-
"type": "string",
|
|
1293
|
-
"defaultValue": "\"4/3\""
|
|
1294
|
-
},
|
|
1295
|
-
"objectFit": {
|
|
1296
|
-
"description": "CSS `object-fit` value applied to the media element.",
|
|
1297
|
-
"control": "select",
|
|
1298
|
-
"category": "appearance",
|
|
1299
|
-
"type": "'cover' | 'contain' | 'fill'",
|
|
1300
|
-
"defaultValue": "\"contain\"",
|
|
1301
|
-
"options": [
|
|
1302
|
-
"contain",
|
|
1303
|
-
"cover",
|
|
1304
|
-
"fill",
|
|
1305
|
-
"none",
|
|
1306
|
-
"scale-down"
|
|
1307
|
-
]
|
|
1308
|
-
},
|
|
1309
|
-
"height": {
|
|
1310
|
-
"description": "Height for the media area. When provided, the media area renders at this height. The image height matches the container and its width is derived from the `ratio` prop, producing gray bars on the sides where the image does not fill the container. Accepts any valid CSS length value (e.g. `\"200px\"`, `\"50vh\"`).",
|
|
1311
|
-
"control": "text",
|
|
1312
|
-
"category": "appearance",
|
|
1313
|
-
"type": "React.CSSProperties[\"height\"]"
|
|
1314
|
-
},
|
|
1315
|
-
"slots": {
|
|
1316
|
-
"description": "The components used for each slot inside. See the **Slots** section below.",
|
|
1317
|
-
"control": "object",
|
|
1318
|
-
"category": "customization",
|
|
1319
|
-
"type": "object"
|
|
1320
|
-
},
|
|
1321
|
-
"slotProps": {
|
|
1322
|
-
"description": "The props used for each slot inside. See the **Slot props** section below.",
|
|
1323
|
-
"control": "object",
|
|
1324
|
-
"category": "customization",
|
|
1325
|
-
"type": "object",
|
|
1326
|
-
"defaultValue": "{}"
|
|
1327
|
-
},
|
|
1328
|
-
"dataTestIdSuffix": {
|
|
1329
|
-
"description": "Suffix appended to the `data-testid` attribute for test targeting.",
|
|
1330
|
-
"control": "text",
|
|
1331
|
-
"category": "customization",
|
|
1332
|
-
"type": "string"
|
|
1333
|
-
},
|
|
1334
|
-
"slots.media": {
|
|
1335
|
-
"description": "Custom React node rendered in place of the default `<CardMedia>`. Wrapped in `<AspectRatio>` so `ratio` and `objectFit` still apply to the surrounding box.",
|
|
1336
|
-
"control": false,
|
|
1337
|
-
"category": "slots",
|
|
1338
|
-
"type": "ReactNode"
|
|
1339
|
-
},
|
|
1340
|
-
"slotProps.media": {
|
|
1341
|
-
"description": "Props applied to the default `<CardMedia>`. Lets you switch the underlying element (`component: \"video\" | \"audio\" | \"img\"`), tweak `src`, attach native media attributes (`controls`, `autoPlay`, `muted`, `playsInline`, etc.). When `slots.media` replaces the default render, only `component: \"audio\"` is still consulted for audio-specific wrapper styling.",
|
|
1342
|
-
"control": false,
|
|
1343
|
-
"category": "slotProps",
|
|
1344
|
-
"type": "CardMediaProps & VideoHTMLAttributes & AudioHTMLAttributes"
|
|
1345
|
-
},
|
|
1346
|
-
"slotProps.card": {
|
|
1347
|
-
"description": "Props applied to the root MUI `<Card>`. **Recommended channel for DOM events** (`onMouseEnter`, `onMouseLeave`, `onFocus`, `onKeyDown`, `aria-*`, `data-*`, …). Top-level MediaProps (`sx`) take precedence and are merged on top.",
|
|
1348
|
-
"control": false,
|
|
1349
|
-
"category": "slotProps",
|
|
1350
|
-
"type": "Omit<CardProps, \"children\" | \"variant\" | \"square\" | \"tabIndex\" | \"elevation\" | \"onClick\">"
|
|
1351
|
-
}
|
|
1352
|
-
},
|
|
1353
|
-
"storyNames": [
|
|
1354
|
-
"Default",
|
|
1355
|
-
"NoImageUrl",
|
|
1356
|
-
"Video",
|
|
1357
|
-
"Audio",
|
|
1358
|
-
"AudioWithBackground",
|
|
1359
|
-
"CardEvents",
|
|
1360
|
-
"WithEditableCaption",
|
|
1361
|
-
"WithMaxHeight"
|
|
1362
|
-
],
|
|
1363
|
-
"docs": "# Media\n\nRenders multimedia content (images, video, and audio) in a card container with configurable overlays and interactive elements.\n\n- Displays images, video, and audio with consistent styling\n- Supports status labels, context menu actions, and bottom tooltips overlaid on media\n- Clicking an image opens a full-screen LightBox preview (can be disabled)\n- Falls back to an icon placeholder when media fails to load or no source is provided\n- Configurable aspect ratio and object-fit via `ratio` and `objectFit` props\n\n## Default\n\nFull example with an image, status labels, actions, and bottom tooltips. Clicking the image opens a LightBox full-screen preview.\n\n```tsx\n// DefaultExample.tsx\nimport React from 'react';\nimport { ImageRounded, AcUnit, AccessAlarm } from '@mui/icons-material';\nimport { Media } from '@ringpublishing/mui-components';\nimport { getImagePath, TestImage, ImageSize } from 'RingDemoImages';\n\nexport default function DefaultExample(): React.JSX.Element {\n const image = {\n src: getImagePath(TestImage.BEACH, ImageSize.LARGE),\n thumbnailSrc: getImagePath(TestImage.BEACH, ImageSize.LARGE),\n title: TestImage.BEACH,\n };\n const title = 'The Cat Takes a Long and Peaceful Nap in a Warm Patch of Afternoon Sunlight.';\n const description = '(James Veysey / Shutterstock)';\n const type = 'Image Type Title';\n const ratio = '4/3';\n const statusLabels = [\n {\n label: 'Label 1',\n color: 'primary' as const,\n icon: <AccessAlarm />,\n },\n {\n label: 'Label 2, with a longer text',\n color: 'error' as const,\n icon: <ImageRounded />,\n },\n ];\n const actions = [\n {\n label: 'Action 1',\n icon: <AcUnit />,\n },\n {\n label: 'Action 2',\n icon: <AccessAlarm />,\n },\n ];\n const bottomTooltips = [\n {\n title: 'Tooltip text 1',\n icon: <AcUnit />,\n },\n {\n title: 'Tooltip text 2',\n icon: <AccessAlarm />,\n },\n ];\n\n return (\n <Media\n image={image}\n title={title}\n description={description}\n type={type}\n ratio={ratio}\n statusLabels={statusLabels}\n actions={actions}\n bottomTooltips={bottomTooltips}\n />\n );\n}\n```\n\n## No Image URL\n\nWhen no `image` prop is provided (or the image fails to load), the component displays an icon placeholder that matches the media type.\n\n```tsx\n// NoImageUrlExample.tsx\nimport React from 'react';\nimport { AccessAlarm } from '@mui/icons-material';\nimport { Media } from '@ringpublishing/mui-components';\n\nexport default function NoImageUrlExample(): React.JSX.Element {\n return (\n <Media\n title=\"No image title\"\n type=\"Image type name\"\n ratio=\"16/9\"\n statusLabels={[{ label: 'Label 1', color: 'primary', icon: <AccessAlarm /> }]}\n />\n );\n}\n```\n\n## Video\n\nUse `slotProps.media` with `component: 'video'` to embed a video element. Full-screen preview is disabled automatically for non-image media types.\n\n```typescript\n<Media\n title=\"Big Buck Bunny\"\n ratio=\"16/9\"\n slotProps={{\n media: {\n component: 'video',\n src: 'https://example.com/video.mp4',\n controls: true,\n autoPlay: true,\n muted: true\n }\n }}\n/>\n```\n\n```tsx\n// VideoExample.tsx\nimport React from 'react';\nimport { Media } from '@ringpublishing/mui-components';\n\nexport default function VideoExample(): React.JSX.Element {\n return (\n <Media\n title=\"Big Buck Bunny\"\n ratio=\"16/9\"\n slotProps={{\n media: {\n component: 'video',\n src: 'https://www.w3schools.com/html/mov_bbb.mp4',\n controls: true,\n autoPlay: true,\n muted: true,\n },\n }}\n />\n );\n}\n```\n\n## Audio\n\nUse `slotProps.media` with `component: 'audio'` to embed an audio player. Set a narrow ratio (e.g. `'18/1'`) to give the audio bar a suitable height.\n\n```typescript\n<Media\n title=\"Audio example\"\n ratio=\"18/1\"\n slotProps={{\n media: {\n component: 'audio',\n src: 'https://example.com/audio.mp3',\n controls: true,\n }\n }}\n/>\n```\n\n```tsx\n// AudioExample.tsx\nimport React from 'react';\nimport { Media } from '@ringpublishing/mui-components';\n\nexport default function AudioExample(): React.JSX.Element {\n return (\n <Media\n title=\"Audio example\"\n ratio=\"18/1\"\n slotProps={{\n media: {\n component: 'audio',\n src: 'https://cdn.pixabay.com/audio/2024/03/07/audio_5f609b17c4.mp3',\n controls: true,\n },\n }}\n />\n );\n}\n```\n\n## Audio with Background\n\nAudio player with a custom pastel background color applied via `slotProps.media.sx.backgroundColor`.\n\n```typescript\n<Media\n title=\"Audio example\"\n ratio=\"18/1\"\n slotProps={{\n media: {\n component: 'audio',\n src: 'https://example.com/audio.mp3',\n controls: true,\n sx: {\n backgroundColor: '#E8D5F5',\n },\n }\n }}\n/>\n```\n\n```tsx\n// AudioWithBackgroundExample.tsx\nimport React from 'react';\nimport { Media } from '@ringpublishing/mui-components';\n\nexport default function AudioWithBackgroundExample(): React.JSX.Element {\n return (\n <Media\n title=\"Audio example\"\n ratio=\"18/1\"\n slotProps={{\n media: {\n component: 'audio',\n src: 'https://cdn.pixabay.com/audio/2024/03/07/audio_5f609b17c4.mp3',\n controls: true,\n sx: {\n backgroundColor: '#e5e5e5',\n },\n },\n }}\n />\n );\n}\n```\n\n## Slots\n\nThe `Media` component exposes a slot system that lets you replace the default media element with your own implementation.\n\n### Available Slots\n\n| Slot | Type | Default | Description |\n| ------- | ----------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `media` | `ReactNode` | `CardMedia` | Custom React node rendered in place of the default `<CardMedia>`. Wrapped in `<AspectRatio>` so `ratio` and `objectFit` still apply to the surrounding box. |\n\n### Using `slots.media`\n\nUse the `media` slot when you need full control over the rendered element — for example a custom video player, an interactive preview component, or a third-party library wrapper. When `slots.media` is provided, `slotProps.media` is ignored and the LightBox full-screen preview is suppressed.\n\n```jsx\n<Media\n ratio=\"16/9\"\n slots={{\n media: <CustomPlayer src=\"https://example.com/clip.mp4\" />,\n }}\n/>\n```\n\n## Slot props\n\nThe `slotProps` prop forwards arbitrary props to internal sub-components without redefining each one as a top-level Media prop. It mirrors the [MUI `slotProps` convention](https://mui.com/material-ui/customization/slots-and-classes/).\n\n| Slot prop | Type | Description |\n| --------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `media` | `CardMediaProps & AudioHTMLAttributes & VideoHTMLAttributes` | Props applied to the default `<CardMedia>`. Lets you switch the underlying element (`component: \"video\" \\| \"audio\" \\| \"img\"`), tweak `src`, attach native media attributes (`controls`, `autoPlay`, `muted`, `playsInline`, etc.). When `slots.media` replaces the default render, only `component: 'audio'` is still consulted to apply audio-specific wrapper styling (transparent background); other props on `slotProps.media` are not forwarded to the custom slot node. |\n| `card` | `Omit<CardProps, \"children\" \\| \"variant\" \\| \"square\" \\| \"tabIndex\" \\| \"elevation\" \\| \"onClick\">` | Props applied to the root MUI `<Card>`. **Recommended channel for native DOM events** (`onMouseEnter`, `onMouseLeave`, `onFocus`, `onKeyDown`, `aria-*`, `data-*`, …). Top-level Media props (`sx`) take precedence and are merged on top. `onClick` is excluded — Media is not designed as a clickable container; use `slotProps.media.onClick` for clicks scoped to the default `<CardMedia>` element, or wrap Media in your own click handler. `elevation` is excluded — Media always renders as `elevation={0}`. |\n\n### Precedence rules\n\nWhen the same prop can be supplied through more than one channel:\n\n- **`elevation`, `variant`, `square`, `tabIndex`** — managed internally by `Media` (the root `<Card>` is always rendered with `elevation={0}`). Excluded from `slotProps.card` typing to prevent accidental override.\n- **`onClick`** — excluded. `Media` is not designed as a clickable container, and exposing both `slotProps.card.onClick` (whole card) and `slotProps.media.onClick` (default `<CardMedia>` only) at once would create two competing click channels for similar interactions. If you need a click handler on the rendered media element, use `slotProps.media.onClick`. If you need a click handler on the entire card, wrap `<Media>` in your own click container.\n- **`sx`** — additive: top-level `sx` is **merged on top of** `slotProps.card.sx` (they form an array layer for MUI).\n- **All other props** — supplied through `slotProps.card` are forwarded to `<Card>` directly.\n\n```jsx\n<Media\n slots={{ media: <video ref={videoRef} muted /> }}\n slotProps={{\n card: {\n onMouseEnter: () => videoRef.current?.play(),\n onMouseLeave: () => videoRef.current?.pause(),\n 'aria-label': 'Hover to preview',\n },\n }}\n/>\n```\n\n## Card Events\n\n`Media` forwards the underlying MUI `<Card>` element through the `slotProps.card` channel. Any prop that the `Card` component accepts is forwarded to the root element — including all native DOM event handlers.\n\n### Common Use-Cases\n\n- **Hover-driven interactions** — `onMouseEnter` / `onMouseLeave` to trigger a video preview, fetch on demand, or update tooltips.\n- **Keyboard accessibility** — `onKeyDown` / `onFocus` / `onBlur` to integrate the media into custom keyboard navigation.\n- **Right-click menus** — `onContextMenu` for custom action menus.\n- **Accessibility attributes** — `aria-*`, `role`, `aria-describedby`, etc.\n- **Test hooks** — `data-*` attributes beyond the built-in `dataTestIdSuffix`.\n\nThe example below combines `slots.media` (custom native `<video>`) with `slotProps.card` (`onMouseEnter` / `onMouseLeave`) to play the video while the user is hovering the card.\n\n```tsx\n// CardEventsExample.tsx\nimport React, { useEffect, useRef, useState } from 'react';\nimport { Media } from '@ringpublishing/mui-components';\n\nconst VIDEO_SRC = 'https://test-videos.co.uk/vids/bigbuckbunny/mp4/h264/1080/Big_Buck_Bunny_1080_10s_1MB.mp4';\n\nexport default function CardEventsExample(): React.JSX.Element {\n const [isHovered, setIsHovered] = useState(false);\n const videoRef = useRef<HTMLVideoElement>(null);\n\n useEffect(() => {\n const video = videoRef.current;\n if (!video) return;\n\n if (isHovered) {\n void video.play().catch(() => {\n // autoplay can be blocked; ignored for the example\n });\n } else {\n video.pause();\n video.currentTime = 0;\n }\n }, [isHovered]);\n\n return (\n <Media\n sx={{ width: '320px' }}\n title=\"Hover the card to play\"\n ratio=\"16/9\"\n objectFit=\"cover\"\n disableFullScreenPreview={true}\n slots={{\n media: (\n <video\n ref={videoRef}\n muted={true}\n playsInline={true}\n style={{ width: '100%', height: '100%', objectFit: 'cover', display: 'block' }}\n >\n <source src={VIDEO_SRC} type=\"video/mp4\" />\n </video>\n ),\n }}\n slotProps={{\n card: {\n onMouseEnter: (): void => setIsHovered(true),\n onMouseLeave: (): void => setIsHovered(false),\n },\n }}\n />\n );\n}\n```\n\n## Editable Caption\n\nPass `onTitleSubmit` and/or `onDescriptionSubmit` to enable inline editing of the caption fields. Each prop is independent — you can make only one of them editable.\n\nWhen a callback is provided, the field renders via `EditableText`: a pencil icon appears next to the text, and clicking it activates an inline input. Press **Enter** or click away to submit. Press **Escape** to cancel. On submit failure the value reverts to its previous state.\n\n```typescript\nconst [title, setTitle] = useState('Image title');\nconst [description, setDescription] = useState('(Author / Source)');\n\n<Media\n image={image}\n title={title}\n description={description}\n onTitleSubmit={async (value) => { setTitle(value); return true; }}\n onDescriptionSubmit={async (value) => { setDescription(value); return true; }}\n/>\n```\n\n```tsx\n// WithEditableCaptionExample.tsx\nimport React, { useState } from 'react';\nimport { Media } from '@ringpublishing/mui-components';\nimport { getImagePath, TestImage, ImageSize } from 'RingDemoImages';\n\nexport default function WithEditableCaptionExample(): React.JSX.Element {\n const [title, setTitle] = useState('The Cat Takes a Long and Peaceful Nap in a Warm Patch of Afternoon Sunlight.');\n const [description, setDescription] = useState('(James Veysey / Shutterstock)');\n\n const handleTitleSubmit = (value: string): Promise<boolean> => {\n setTitle(value);\n\n return Promise.resolve(true);\n };\n\n const handleDescriptionSubmit = (value: string): Promise<boolean> => {\n setDescription(value);\n\n return Promise.resolve(true);\n };\n\n return (\n <Media\n image={{\n src: getImagePath(TestImage.BEACH, ImageSize.LARGE),\n thumbnailSrc: getImagePath(TestImage.BEACH, ImageSize.LARGE),\n title: TestImage.BEACH,\n }}\n type=\"Image Type Title\"\n ratio=\"4/3\"\n disableFullScreenPreview={true}\n title={title}\n description={description}\n onTitleSubmit={handleTitleSubmit}\n onDescriptionSubmit={handleDescriptionSubmit}\n />\n );\n}\n```"
|
|
1364
|
-
},
|
|
1365
|
-
"molecules-placeholder": {
|
|
1366
|
-
"id": "molecules-placeholder",
|
|
1367
|
-
"name": "Placeholder",
|
|
1368
|
-
"category": "Molecules",
|
|
1369
|
-
"title": "Components/Molecules/Placeholder",
|
|
1370
|
-
"description": "`Placeholder` displays an empty/error-like state with an icon and contextual text to help users understand what happened and what they can do next.",
|
|
1371
|
-
"argTypes": {
|
|
1372
|
-
"labels": {
|
|
1373
|
-
"description": "Labels object used to override default text for the selected variant and language.",
|
|
1374
|
-
"control": "object",
|
|
1375
|
-
"category": "content",
|
|
1376
|
-
"type": "{ header?: string; description?: string; footer?: string }"
|
|
1377
|
-
},
|
|
1378
|
-
"variant": {
|
|
1379
|
-
"description": "Controls which predefined placeholder variant is rendered.",
|
|
1380
|
-
"control": "radio",
|
|
1381
|
-
"category": "behavior",
|
|
1382
|
-
"type": "'error' | 'error_list' | 'not_found' | 'empty' | 'empty_box'"
|
|
1383
|
-
},
|
|
1384
|
-
"language": {
|
|
1385
|
-
"description": "Language used for default labels. When omitted, the current theme locale is used.",
|
|
1386
|
-
"control": false,
|
|
1387
|
-
"category": "behavior",
|
|
1388
|
-
"type": "CommonLanguages",
|
|
1389
|
-
"defaultValue": "'enUS' (or current theme locale)"
|
|
1390
|
-
},
|
|
1391
|
-
"buttons": {
|
|
1392
|
-
"description": "Optional list of MUI button props rendered below the main content.",
|
|
1393
|
-
"control": "object",
|
|
1394
|
-
"category": "actions",
|
|
1395
|
-
"type": "ButtonProps[]",
|
|
1396
|
-
"defaultValue": "[]"
|
|
1397
|
-
},
|
|
1398
|
-
"img": {
|
|
1399
|
-
"description": "Custom icon/image element. When provided, built-in variant icons are not used.",
|
|
1400
|
-
"control": false,
|
|
1401
|
-
"category": "content",
|
|
1402
|
-
"type": "React.JSX.Element"
|
|
1403
|
-
},
|
|
1404
|
-
"dataTestIdSuffix": {
|
|
1405
|
-
"description": "Optional suffix for generated test id (base: ring-placeholder-{variant}).",
|
|
1406
|
-
"control": "text",
|
|
1407
|
-
"category": "testing",
|
|
1408
|
-
"type": "string"
|
|
1409
|
-
},
|
|
1410
|
-
"sx": {
|
|
1411
|
-
"description": "MUI System properties to customize the main element style.",
|
|
1412
|
-
"control": "object",
|
|
1413
|
-
"category": "customization",
|
|
1414
|
-
"type": "SxProps<Theme>",
|
|
1415
|
-
"defaultValue": "{}"
|
|
1416
|
-
},
|
|
1417
|
-
"className": {
|
|
1418
|
-
"description": "CSS class name applied to the main element.",
|
|
1419
|
-
"control": "text",
|
|
1420
|
-
"category": "customization",
|
|
1421
|
-
"type": "string"
|
|
1422
|
-
}
|
|
1423
|
-
},
|
|
1424
|
-
"storyNames": [
|
|
1425
|
-
"Default",
|
|
1426
|
-
"NotFound",
|
|
1427
|
-
"Empty",
|
|
1428
|
-
"WithButtonsCustomIconAndCustomLabels"
|
|
1429
|
-
],
|
|
1430
|
-
"docs": "# Placeholder\n\n`Placeholder` displays an empty/error-like state with an icon and contextual text to help users understand what happened and what they can do next.\n\n- Supports predefined variants for common scenarios (error, not found, empty)\n- Supports custom labels for localized or domain-specific messaging\n- Supports optional action buttons and a custom image/icon\n- Uses theme locale for localized defaults\n\n## Default\n\nThe default variant presents a generic error state with built-in labels.\n\n```tsx\n// DefaultExample.tsx\nimport React from 'react';\nimport { Placeholder } from '@ringpublishing/mui-components';\n\nexport default function DefaultExample(): React.JSX.Element {\n return <Placeholder />;\n}\n```\n\n## Not Found\n\nUse the `not_found` variant when search/filter actions return no results.\n\n```tsx\n// NotFoundExample.tsx\nimport React from 'react';\nimport { Placeholder, PlaceholderVariant } from '@ringpublishing/mui-components';\n\nexport default function NotFoundExample(): React.JSX.Element {\n return <Placeholder variant={PlaceholderVariant.NOT_FOUND} />;\n}\n```\n\n## Empty\n\nUse the `empty` variant when no item is selected yet or when details are not available.\n\n```tsx\n// EmptyExample.tsx\nimport React from 'react';\nimport { Placeholder, PlaceholderVariant } from '@ringpublishing/mui-components';\n\nexport default function EmptyExample(): React.JSX.Element {\n return <Placeholder variant={PlaceholderVariant.EMPTY} />;\n}\n```\n\n## With Buttons, Custom Icon and Labels\n\nThis example shows how to fully customize:\n\n- labels (`header`, `description`, `footer`)\n- action buttons (`buttons`)\n- visual icon (`img`)\n\n```tsx\n// WithButtonsCustomIconAndCustomLabelsExample.tsx\nimport React from 'react';\nimport { ButtonProps } from '@mui/material';\nimport { Placeholder } from '@ringpublishing/mui-components';\nimport CustomIcon from 'CustomIcon';\n\nconst labels = {\n header: 'Failed to load the list',\n description: 'Refresh the page and try again. If the problem persists, please contact our technical support.',\n footer: 'Error 4009',\n};\n\nconst buttons: ButtonProps[] = [\n {\n children: 'Try again',\n variant: 'outlined',\n },\n {\n children: 'Close',\n variant: 'contained',\n color: 'primary',\n },\n];\n\nexport default function WithButtonsCustomIconAndCustomLabelsExample(): React.JSX.Element {\n const img = <img src={CustomIcon} alt=\"icon\" />;\n\n return <Placeholder labels={labels} buttons={buttons} img={img} />;\n}\n```"
|
|
1431
|
-
},
|
|
1432
|
-
"molecules-ranges": {
|
|
1433
|
-
"id": "molecules-ranges",
|
|
1434
|
-
"name": "Ranges",
|
|
1435
|
-
"category": "Molecules",
|
|
1436
|
-
"title": "Components/Molecules/Ranges",
|
|
1437
|
-
"description": "Ranges is a component for creating and managing multiple range filters. It allows users to select a metric and define its value range — either as free-form numeric input with optional min/max bounds, or using predefined select options.",
|
|
1438
|
-
"argTypes": {
|
|
1439
|
-
"rangeDefinitions": {
|
|
1440
|
-
"description": "Object defining available ranges with their configurations. Each range can have bounds (min/max) or predefined options.",
|
|
1441
|
-
"category": "Data",
|
|
1442
|
-
"type": "RangeDefinitions"
|
|
1443
|
-
},
|
|
1444
|
-
"onChange": {
|
|
1445
|
-
"description": "Callback function triggered when ranges change and all values are valid (respecting bounds and from <= to constraint)",
|
|
1446
|
-
"control": false,
|
|
1447
|
-
"category": "Events",
|
|
1448
|
-
"type": "(ranges: Ranges) => void"
|
|
1449
|
-
},
|
|
1450
|
-
"labels": {
|
|
1451
|
-
"description": "Labels object for all UI texts including buttons, inputs, placeholders and error messages",
|
|
1452
|
-
"category": "Content",
|
|
1453
|
-
"type": "RangesLabels"
|
|
1454
|
-
},
|
|
1455
|
-
"maxAppliedRanges": {
|
|
1456
|
-
"description": "Maximum number of ranges that can be applied simultaneously. Add range button is hidden when limit is reached.",
|
|
1457
|
-
"category": "Behavior",
|
|
1458
|
-
"type": "number",
|
|
1459
|
-
"defaultValue": "Infinity"
|
|
1460
|
-
},
|
|
1461
|
-
"initialState": {
|
|
1462
|
-
"description": "Initial state of the ranges. If not provided, component starts with one empty range.",
|
|
1463
|
-
"category": "Data",
|
|
1464
|
-
"type": "Ranges"
|
|
1465
|
-
},
|
|
1466
|
-
"apiRef": {
|
|
1467
|
-
"description": "Ref to the Ranges component instance. Provides methods: getRanges(), setRanges(ranges), resetRanges()",
|
|
1468
|
-
"control": false,
|
|
1469
|
-
"category": "Advanced",
|
|
1470
|
-
"type": "React.RefObject<RangesApiRef>"
|
|
1471
|
-
},
|
|
1472
|
-
"sx": {
|
|
1473
|
-
"description": "MUI sx prop for custom styling",
|
|
1474
|
-
"category": "Styling",
|
|
1475
|
-
"type": "SxProps"
|
|
1476
|
-
},
|
|
1477
|
-
"className": {
|
|
1478
|
-
"description": "Additional CSS class name",
|
|
1479
|
-
"category": "Styling",
|
|
1480
|
-
"type": "string"
|
|
1481
|
-
},
|
|
1482
|
-
"dataTestIdSuffix": {
|
|
1483
|
-
"description": "Suffix for data-testid attribute",
|
|
1484
|
-
"category": "Testing",
|
|
1485
|
-
"type": "string"
|
|
1486
|
-
}
|
|
1487
|
-
},
|
|
1488
|
-
"storyNames": [
|
|
1489
|
-
"Default",
|
|
1490
|
-
"WithInitialState",
|
|
1491
|
-
"WithApiRef"
|
|
1492
|
-
],
|
|
1493
|
-
"docs": "# Ranges\n\nRanges is a component for creating and managing multiple range filters. It allows users to select a metric and define its value range — either as free-form numeric input with optional min/max bounds, or using predefined select options.\n\nKey features:\n\n- Add and remove multiple range filters dynamically\n- Supports numeric input ranges with configurable min/max bounds\n- Supports select-based ranges with predefined ordered options\n- Configurable maximum number of applied ranges\n- Pre-populate ranges via `initialState`\n- Programmatic control via `apiRef` (get, set, reset)\n- Built-in validation: boundary checks, required fields, and from ≤ to constraint\n\n## Default\n\nThe default Ranges configuration showing all three metric types: numeric ranges with bounds (`imagesCount`, `authorsCount`) and a select-based range with predefined options (`charactersCount`). Users can add up to 3 ranges and remove them individually.\n\n```tsx\n// DefaultExample.tsx\nimport React from 'react';\nimport { Box } from '@mui/material';\nimport { Ranges, RangeDefinitions, RangesLabels } from '@ringpublishing/mui-components';\n\nconst rangeDefinitions: RangeDefinitions = {\n imagesCount: {\n label: 'Images Count',\n rangeBounds: { min: 0, max: 100 },\n },\n authorsCount: {\n label: 'Authors Count',\n rangeBounds: { min: 1, max: 50 },\n },\n charactersCount: {\n label: 'Characters Count',\n rangeOptions: [\n { value: 1000, label: '1K', order: 0 },\n { value: 5000, label: '5K', order: 1 },\n { value: 10000, label: '10K', order: 2 },\n ],\n },\n};\n\nconst labels: RangesLabels = {\n rangeSelect: 'Select Metric',\n addRangeButton: 'Add range',\n removeRangeButton: 'Remove',\n rangeSelectPlaceholder: 'Choose metric',\n fromInput: 'From',\n toInput: 'To',\n valueTooHighError: 'Maximum value is ',\n valueTooLowError: 'Minimum value is ',\n valueRequiredError: 'Field is required',\n invalidRangeError: 'Invalid range',\n};\n\nexport default function DefaultExample(): React.JSX.Element {\n return (\n <Box display=\"flex\" justifyContent=\"center\" minHeight=\"300px\">\n <Box width=\"200px\">\n <Ranges\n rangeDefinitions={rangeDefinitions}\n maxAppliedRanges={3}\n labels={labels}\n onChange={(ranges) => console.log(ranges)}\n />\n </Box>\n </Box>\n );\n}\n```\n\n## With Initial State\n\nRanges pre-populated with an initial state. In this example, the `imagesCount` range is pre-set to 10–50 and `charactersCount` starts from 1K. Use the `initialState` prop to restore previously saved filter configurations.\n\n```tsx\n// WithInitialStateExample.tsx\nimport React from 'react';\nimport { Box } from '@mui/material';\nimport { Ranges, RangeDefinitions, RangesLabels } from '@ringpublishing/mui-components';\n\nconst rangeDefinitions: RangeDefinitions = {\n imagesCount: {\n label: 'Images Count',\n rangeBounds: { min: 0, max: 100 },\n },\n authorsCount: {\n label: 'Authors Count',\n rangeBounds: { min: 1, max: 50 },\n },\n charactersCount: {\n label: 'Characters Count',\n rangeOptions: [\n { value: 1000, label: '1K', order: 0 },\n { value: 5000, label: '5K', order: 1 },\n { value: 10000, label: '10K', order: 2 },\n ],\n },\n};\n\nconst labels: RangesLabels = {\n rangeSelect: 'Select Metric',\n addRangeButton: 'Add range',\n removeRangeButton: 'Remove',\n rangeSelectPlaceholder: 'Choose metric',\n fromInput: 'From',\n toInput: 'To',\n valueTooHighError: 'Maximum value is ',\n valueTooLowError: 'Minimum value is ',\n valueRequiredError: 'Field is required',\n invalidRangeError: 'Invalid range',\n};\n\nexport default function WithInitialStateExample(): React.JSX.Element {\n return (\n <Box display=\"flex\" justifyContent=\"center\" minHeight=\"300px\">\n <Box width=\"200px\">\n <Ranges\n rangeDefinitions={rangeDefinitions}\n maxAppliedRanges={3}\n labels={labels}\n onChange={(ranges) => console.log(ranges)}\n initialState={{\n imagesCount: {\n order: 0,\n from: 10,\n to: 50,\n },\n charactersCount: {\n order: 1,\n from: 1000,\n },\n }}\n />\n </Box>\n </Box>\n );\n}\n```\n\n## With Api Ref\n\nDemonstrates programmatic control of the Ranges component via the `apiRef` prop. The `RangesApiRef` interface exposes three methods:\n\n- `getRanges()` — returns the current ranges state\n- `setRanges(ranges)` — replaces the current state with the provided ranges\n- `resetRanges()` — resets ranges back to `initialState` (or empty if not set)\n\nThe Reset button in this story calls `apiRef.current?.resetRanges()` to clear all applied ranges.\n\n```tsx\n// WithApiRefExample.tsx\nimport React, { useRef } from 'react';\nimport { Box, Button } from '@mui/material';\nimport { Ranges, RangeDefinitions, RangesLabels, RangesApiRef } from '@ringpublishing/mui-components';\n\nconst rangeDefinitions: RangeDefinitions = {\n imagesCount: {\n label: 'Images Count',\n rangeBounds: { min: 0, max: 100 },\n },\n authorsCount: {\n label: 'Authors Count',\n rangeBounds: { min: 1, max: 50 },\n },\n charactersCount: {\n label: 'Characters Count',\n rangeOptions: [\n { value: 1000, label: '1K', order: 0 },\n { value: 5000, label: '5K', order: 1 },\n { value: 10000, label: '10K', order: 2 },\n ],\n },\n};\n\nconst labels: RangesLabels = {\n rangeSelect: 'Select Metric',\n addRangeButton: 'Add range',\n removeRangeButton: 'Remove',\n rangeSelectPlaceholder: 'Choose metric',\n fromInput: 'From',\n toInput: 'To',\n valueTooHighError: 'Maximum value is ',\n valueTooLowError: 'Minimum value is ',\n valueRequiredError: 'Field is required',\n invalidRangeError: 'Invalid range',\n};\n\nexport default function WithApiRefExample(): React.JSX.Element {\n const apiRef = useRef<RangesApiRef>(null);\n\n return (\n <Box display=\"flex\" justifyContent=\"center\" minHeight=\"300px\">\n <Box width=\"200px\">\n <Button sx={{ marginBottom: '8px' }} onClick={() => apiRef.current?.resetRanges()}>\n Reset Ranges\n </Button>\n <Ranges\n rangeDefinitions={rangeDefinitions}\n maxAppliedRanges={2}\n labels={labels}\n onChange={(ranges) => console.log(ranges)}\n apiRef={apiRef}\n />\n </Box>\n </Box>\n );\n}\n```"
|
|
1494
|
-
},
|
|
1495
|
-
"molecules-search-bar": {
|
|
1496
|
-
"id": "molecules-search-bar",
|
|
1497
|
-
"name": "SearchBar",
|
|
1498
|
-
"category": "Molecules",
|
|
1499
|
-
"title": "Components/Molecules/SearchBar",
|
|
1500
|
-
"description": "SearchBar is a comprehensive search component that combines a search input field with customizable action buttons and controls. It supports both controlled and uncontrolled modes, debounced search functionality, and a clearable input option.",
|
|
1501
|
-
"argTypes": {
|
|
1502
|
-
"value": {
|
|
1503
|
-
"description": "The value of the input element, required for a controlled component.",
|
|
1504
|
-
"control": "text",
|
|
1505
|
-
"category": "controlled",
|
|
1506
|
-
"type": "string"
|
|
1507
|
-
},
|
|
1508
|
-
"onChange": {
|
|
1509
|
-
"description": "Callback fired when the value is changed, required for a controlled component.",
|
|
1510
|
-
"category": "controlled",
|
|
1511
|
-
"type": "(value: string) => void"
|
|
1512
|
-
},
|
|
1513
|
-
"defaultValue": {
|
|
1514
|
-
"description": "The default value, required for an uncontrolled component.",
|
|
1515
|
-
"control": "text",
|
|
1516
|
-
"category": "uncontrolled",
|
|
1517
|
-
"type": "string"
|
|
1518
|
-
},
|
|
1519
|
-
"searchFunc": {
|
|
1520
|
-
"description": "Search function called after input change, required for an uncontrolled component.",
|
|
1521
|
-
"category": "uncontrolled",
|
|
1522
|
-
"type": "(query: string) => void"
|
|
1523
|
-
},
|
|
1524
|
-
"debounceTime": {
|
|
1525
|
-
"description": "Delay of calling searchFunc in milliseconds, only for uncontrolled component.",
|
|
1526
|
-
"control": "number",
|
|
1527
|
-
"category": "uncontrolled",
|
|
1528
|
-
"type": "number",
|
|
1529
|
-
"defaultValue": "500"
|
|
1530
|
-
},
|
|
1531
|
-
"withClearButton": {
|
|
1532
|
-
"description": "Show/hide clear button.",
|
|
1533
|
-
"control": "boolean",
|
|
1534
|
-
"category": "behavior",
|
|
1535
|
-
"type": "boolean",
|
|
1536
|
-
"defaultValue": "false"
|
|
1537
|
-
},
|
|
1538
|
-
"labels": {
|
|
1539
|
-
"description": "Labels for placeholder and clear button tooltip.",
|
|
1540
|
-
"control": "object",
|
|
1541
|
-
"category": "labels",
|
|
1542
|
-
"type": "{ placeholder?: string; clear?: string; }"
|
|
1543
|
-
},
|
|
1544
|
-
"className": {
|
|
1545
|
-
"description": "CSS class name for custom styling.",
|
|
1546
|
-
"control": "text",
|
|
1547
|
-
"category": "customization",
|
|
1548
|
-
"type": "string"
|
|
1549
|
-
},
|
|
1550
|
-
"sx": {
|
|
1551
|
-
"description": "Material-UI sx prop for advanced styling.",
|
|
1552
|
-
"control": "object",
|
|
1553
|
-
"category": "customization",
|
|
1554
|
-
"type": "SxProps<Theme>"
|
|
1555
|
-
},
|
|
1556
|
-
"dataTestIdSuffix": {
|
|
1557
|
-
"description": "Suffix for data-testid attribute for testing purposes.",
|
|
1558
|
-
"control": "text",
|
|
1559
|
-
"category": "testing",
|
|
1560
|
-
"type": "string"
|
|
1561
|
-
},
|
|
1562
|
-
"children": {
|
|
1563
|
-
"description": "Action buttons, controls, or other elements to display alongside the search input.",
|
|
1564
|
-
"category": "content",
|
|
1565
|
-
"type": "React.ReactNode"
|
|
1566
|
-
}
|
|
1567
|
-
},
|
|
1568
|
-
"storyNames": [
|
|
1569
|
-
"Default",
|
|
1570
|
-
"ClassSelectorChildrenStack",
|
|
1571
|
-
"Controlled"
|
|
1572
|
-
],
|
|
1573
|
-
"docs": "# SearchBar\n\nSearchBar is a comprehensive search component that combines a search input field with customizable action buttons and controls. It supports both controlled and uncontrolled modes, debounced search functionality, and a clearable input option.\n\n- Flexible search input with debouncing support\n- Customizable action buttons and controls\n- Clear button for quick input reset\n- Supports both controlled and uncontrolled modes\n- Built on Material-UI with flexible styling\n\n## Default\n\nThe default SearchBar configuration, combining search input with a set of practical actions, a dropdown selector, and multiple action buttons.\n\n```tsx\n// DefaultExample.tsx\nimport React from 'react';\nimport { IconButton, MenuItem, Select } from '@mui/material';\nimport { List, MoreTime, RocketLaunch } from '@mui/icons-material';\nimport { SearchBar, SplitButton } from '@ringpublishing/mui-components';\n\nfunction SelectExample(): React.JSX.Element {\n return (\n <Select\n key={0}\n defaultValue={1}\n labelId=\"demo-simple-select-label\"\n id=\"demo-simple-select\"\n label=\"Age\"\n variant=\"standard\"\n disableUnderline={true}\n >\n <MenuItem value={1}>Newest</MenuItem>\n <MenuItem value={2}>Oldest</MenuItem>\n <MenuItem value={3}>Most popular</MenuItem>\n </Select>\n );\n}\n\nexport default function DefaultExample(): React.JSX.Element {\n return (\n <SearchBar\n defaultValue=\"\"\n searchFunc={() => null}\n withClearButton={true}\n debounceTime={500}\n labels={{\n placeholder: 'Search',\n clear: 'Clear',\n }}\n className=\"custom-class-name\"\n sx={{ border: '1px solid #d9d9d9' }}\n >\n <SelectExample key={0} />\n <SplitButton key={1} actions={[{ label: 'Main Action', onClick: () => null }]} sx={{ height: '36px' }} />\n <SplitButton\n key={2}\n variant=\"outlined\"\n actions={[\n { label: 'Main Action', onClick: () => null },\n {\n label: 'Additional Action 1',\n onClick: () => null,\n icon: <RocketLaunch />,\n },\n {\n label: 'Additional Action 2',\n onClick: () => null,\n icon: <MoreTime />,\n },\n ]}\n sx={{ height: '36px' }}\n />\n <IconButton key={3}>\n <List />\n </IconButton>\n </SearchBar>\n );\n}\n```\n\n## Controlled Mode\n\nA controlled SearchBar implementation, where the input value and its changes are managed by the parent component. This pattern is recommended for scenarios requiring validation, state synchronization, or integration with complex business logic.\n\n```tsx\n// ControlledExample.tsx\nimport React from 'react';\nimport { IconButton } from '@mui/material';\nimport { MoreVert } from '@mui/icons-material';\nimport { SearchBar } from '@ringpublishing/mui-components';\n\nexport default function ControlledSearchBarExample(): React.JSX.Element {\n const [value, setValue] = React.useState('');\n\n return (\n <SearchBar value={value} onChange={setValue} sx={{ border: '1px solid #d9d9d9', width: '450px' }}>\n <IconButton key={1}>\n <MoreVert />\n </IconButton>\n </SearchBar>\n );\n}\n```\n\n## Custom Styling\n\nDemonstrates advanced customization of the SearchBar's action area using CSS classes (`ring-search-bar-children-stack`). This example is useful when you need to control the alignment and spacing of child elements, such as icons and buttons.\n\n```tsx\n// ClassSelectorChildrenStackExample.tsx\nimport React from 'react';\nimport { IconButton } from '@mui/material';\nimport { FilterList, MoreVert } from '@mui/icons-material';\nimport { SearchBar } from '@ringpublishing/mui-components';\n\nexport default function ClassSelectorChildrenStackExample(): React.JSX.Element {\n return (\n <SearchBar\n defaultValue=\"\"\n searchFunc={() => null}\n sx={{\n width: '450px',\n border: '1px solid #d9d9d9',\n '.ring-search-bar-children-stack': {\n justifyContent: 'space-between',\n width: '50%',\n },\n }}\n >\n <IconButton key={0}>\n <FilterList sx={{ color: 'primary.main' }} />\n </IconButton>\n <IconButton key={1}>\n <MoreVert />\n </IconButton>\n </SearchBar>\n );\n}\n```"
|
|
1574
|
-
},
|
|
1575
|
-
"molecules-search-box": {
|
|
1576
|
-
"id": "molecules-search-box",
|
|
1577
|
-
"name": "SearchBox",
|
|
1578
|
-
"category": "Molecules",
|
|
1579
|
-
"title": "Components/Molecules/SearchBox",
|
|
1580
|
-
"description": "SearchBox is a lightweight search component that provides a simple search input field with customizable styling and behavior. It supports both controlled and uncontrolled modes, debounced search functionality, and a clearable input option. The component is built on top of Material-UI and provides flexible styling options through className and sx props.",
|
|
1581
|
-
"argTypes": {
|
|
1582
|
-
"value": {
|
|
1583
|
-
"description": "The value of the input element, required for a controlled component.",
|
|
1584
|
-
"control": "text",
|
|
1585
|
-
"category": "controlled",
|
|
1586
|
-
"type": "string"
|
|
1587
|
-
},
|
|
1588
|
-
"onChange": {
|
|
1589
|
-
"description": "Callback fired when the value is changed, required for a controlled component.",
|
|
1590
|
-
"category": "controlled",
|
|
1591
|
-
"type": "(value: string) => void"
|
|
1592
|
-
},
|
|
1593
|
-
"defaultValue": {
|
|
1594
|
-
"description": "The default value, required for an uncontrolled component.",
|
|
1595
|
-
"control": "text",
|
|
1596
|
-
"category": "uncontrolled",
|
|
1597
|
-
"type": "string"
|
|
1598
|
-
},
|
|
1599
|
-
"searchFunc": {
|
|
1600
|
-
"description": "Search function called after input change, required for an uncontrolled component.",
|
|
1601
|
-
"category": "uncontrolled",
|
|
1602
|
-
"type": "(query: string) => void"
|
|
1603
|
-
},
|
|
1604
|
-
"debounceTime": {
|
|
1605
|
-
"description": "Delay of calling searchFunc in milliseconds, only for uncontrolled component.",
|
|
1606
|
-
"control": "number",
|
|
1607
|
-
"category": "uncontrolled",
|
|
1608
|
-
"type": "number",
|
|
1609
|
-
"defaultValue": "500"
|
|
1610
|
-
},
|
|
1611
|
-
"withClearButton": {
|
|
1612
|
-
"description": "Show/hide clear button.",
|
|
1613
|
-
"control": "boolean",
|
|
1614
|
-
"category": "behavior",
|
|
1615
|
-
"type": "boolean",
|
|
1616
|
-
"defaultValue": "false"
|
|
1617
|
-
},
|
|
1618
|
-
"labels": {
|
|
1619
|
-
"description": "Labels for placeholder and clear button tooltip.",
|
|
1620
|
-
"control": "object",
|
|
1621
|
-
"category": "labels",
|
|
1622
|
-
"type": "{ placeholder?: string; clear?: string; }"
|
|
1623
|
-
},
|
|
1624
|
-
"className": {
|
|
1625
|
-
"description": "CSS class name for custom styling.",
|
|
1626
|
-
"control": "text",
|
|
1627
|
-
"category": "customization",
|
|
1628
|
-
"type": "string"
|
|
1629
|
-
},
|
|
1630
|
-
"sx": {
|
|
1631
|
-
"description": "Material-UI sx prop for advanced styling.",
|
|
1632
|
-
"control": "object",
|
|
1633
|
-
"category": "customization",
|
|
1634
|
-
"type": "SxProps<Theme>"
|
|
1635
|
-
},
|
|
1636
|
-
"dataTestIdSuffix": {
|
|
1637
|
-
"description": "Suffix for data-testid attribute for testing purposes.",
|
|
1638
|
-
"control": "text",
|
|
1639
|
-
"category": "testing",
|
|
1640
|
-
"type": "string"
|
|
1641
|
-
}
|
|
1642
|
-
},
|
|
1643
|
-
"storyNames": [
|
|
1644
|
-
"Default",
|
|
1645
|
-
"Controlled"
|
|
1646
|
-
],
|
|
1647
|
-
"docs": "# SearchBox\n\nSearchBox is a lightweight search component that provides a simple search input field with customizable styling and behavior. It supports both controlled and uncontrolled modes, debounced search functionality, and a clearable input option. The component is built on top of Material-UI and provides flexible styling options through className and sx props.\n\n- Debounced search input with customizable delay\n- Clearable input with optional clear button\n- Supports both controlled and uncontrolled modes\n- Customizable labels and styling\n\n## Default\n\nThe default SearchBox configuration with debounced search functionality and clear button.\n\n```tsx\n// DefaultExample.tsx\nimport React from 'react';\nimport { SearchBox } from '@ringpublishing/mui-components';\n\nexport default function DefaultExample(): React.JSX.Element {\n return (\n <SearchBox\n defaultValue=\"\"\n searchFunc={() => null}\n debounceTime={500}\n withClearButton={true}\n labels={{\n placeholder: 'Search',\n clear: 'Clear',\n }}\n className=\"custom-class-name\"\n />\n );\n}\n```\n\n## Controlled Mode\n\nA controlled SearchBox implementation, where the input value and its changes are managed by the parent component. This pattern is recommended for scenarios requiring validation, state synchronization, or integration with complex business logic.\n\n```tsx\n// ControlledExample.tsx\nimport React from 'react';\nimport { SearchBox } from '@ringpublishing/mui-components';\n\nexport default function ControlledExample(): React.JSX.Element {\n const [value, setValue] = React.useState('');\n\n return (\n <SearchBox\n value={value}\n onChange={setValue}\n withClearButton={true}\n labels={{\n placeholder: 'Search',\n clear: 'Clear',\n }}\n className=\"custom-class-name\"\n />\n );\n}\n```"
|
|
1648
|
-
},
|
|
1649
|
-
"molecules-split-button": {
|
|
1650
|
-
"id": "molecules-split-button",
|
|
1651
|
-
"name": "SplitButton",
|
|
1652
|
-
"category": "Molecules",
|
|
1653
|
-
"title": "Components/Molecules/SplitButton",
|
|
1654
|
-
"description": "SplitButton is a specialized button component that combines a primary action with a dropdown menu of additional actions. It extends the MUI ButtonGroup component with enhanced functionality for managing multiple related actions.",
|
|
1655
|
-
"argTypes": {
|
|
1656
|
-
"actions": {
|
|
1657
|
-
"description": "Array of action objects defining the main action and additional dropdown actions. Each action object includes label, onClick callback, optional disabled state, disabled reason for tooltips, and optional icon.",
|
|
1658
|
-
"category": "content",
|
|
1659
|
-
"type": "{ label: string; onClick: () => void; disabled?: boolean; disabledReason?: string; icon?: React.JSX.Element; }[]"
|
|
1660
|
-
},
|
|
1661
|
-
"size": {
|
|
1662
|
-
"description": "The size of the button group. Applies to both main action and dropdown trigger buttons.",
|
|
1663
|
-
"control": "select",
|
|
1664
|
-
"category": "customization",
|
|
1665
|
-
"type": "'small' | 'medium' | 'large'",
|
|
1666
|
-
"defaultValue": "medium",
|
|
1667
|
-
"options": [
|
|
1668
|
-
"small",
|
|
1669
|
-
"medium",
|
|
1670
|
-
"large"
|
|
1671
|
-
]
|
|
1672
|
-
},
|
|
1673
|
-
"variant": {
|
|
1674
|
-
"description": "The variant style of the button group. Inherited from MUI ButtonGroup API.",
|
|
1675
|
-
"control": "select",
|
|
1676
|
-
"category": "customization",
|
|
1677
|
-
"type": "'contained' | 'outlined' | 'text'",
|
|
1678
|
-
"defaultValue": "outlined",
|
|
1679
|
-
"options": [
|
|
1680
|
-
"text",
|
|
1681
|
-
"outlined",
|
|
1682
|
-
"contained"
|
|
1683
|
-
]
|
|
1684
|
-
},
|
|
1685
|
-
"color": {
|
|
1686
|
-
"description": "The color of the button group. Inherited from MUI ButtonGroup API.",
|
|
1687
|
-
"control": "select",
|
|
1688
|
-
"category": "customization",
|
|
1689
|
-
"type": "'primary' | 'secondary'",
|
|
1690
|
-
"defaultValue": "primary",
|
|
1691
|
-
"options": [
|
|
1692
|
-
"inherit",
|
|
1693
|
-
"primary",
|
|
1694
|
-
"secondary",
|
|
1695
|
-
"success",
|
|
1696
|
-
"error",
|
|
1697
|
-
"info",
|
|
1698
|
-
"warning"
|
|
1699
|
-
]
|
|
1700
|
-
},
|
|
1701
|
-
"orientation": {
|
|
1702
|
-
"description": "The orientation of the button group layout. Inherited from MUI ButtonGroup API.",
|
|
1703
|
-
"control": "select",
|
|
1704
|
-
"category": "customization",
|
|
1705
|
-
"type": "'horizontal' | 'vertical'",
|
|
1706
|
-
"defaultValue": "horizontal",
|
|
1707
|
-
"options": [
|
|
1708
|
-
"horizontal",
|
|
1709
|
-
"vertical"
|
|
1710
|
-
]
|
|
1711
|
-
},
|
|
1712
|
-
"className": {
|
|
1713
|
-
"description": "Custom CSS class name to apply to the root element.",
|
|
1714
|
-
"control": "text",
|
|
1715
|
-
"category": "customization",
|
|
1716
|
-
"type": "string"
|
|
1717
|
-
},
|
|
1718
|
-
"sx": {
|
|
1719
|
-
"description": "MUI sx prop for applying custom styles to the root element.",
|
|
1720
|
-
"category": "customization",
|
|
1721
|
-
"type": "SxProps"
|
|
1722
|
-
},
|
|
1723
|
-
"dataTestIdSuffix": {
|
|
1724
|
-
"description": "Suffix for the data-testid attribute used in testing.",
|
|
1725
|
-
"control": "text",
|
|
1726
|
-
"category": "testing",
|
|
1727
|
-
"type": "string"
|
|
1728
|
-
}
|
|
1729
|
-
},
|
|
1730
|
-
"storyNames": [
|
|
1731
|
-
"Default",
|
|
1732
|
-
"CustomizationFromButtonGroupAPI",
|
|
1733
|
-
"MainActionDisabled",
|
|
1734
|
-
"WithOneAction"
|
|
1735
|
-
],
|
|
1736
|
-
"docs": "# SplitButton\n\nSplitButton is a specialized button component that combines a primary action with a dropdown menu of additional actions. It extends the MUI ButtonGroup component with enhanced functionality for managing multiple related actions.\n\n- Primary action button with optional disabled state\n- Dropdown menu for additional actions with icons and tooltips\n- Tooltip support for disabled action reasons\n- Customizable sizing and styling via ButtonGroup API\n- Support for single or multiple additional actions\n\n## Default\n\nThe standard SplitButton configuration featuring a main action button with multiple additional actions in a dropdown menu. This story demonstrates the component with various action states, including disabled actions with tooltips and icon support.\n\n```tsx\n// DefaultExample.tsx\nimport React from 'react';\nimport { DoNotDisturb, RocketLaunch } from '@mui/icons-material';\nimport { SplitButton } from '@ringpublishing/mui-components';\n\nexport default function DefaultExample(): React.JSX.Element {\n return (\n <SplitButton\n actions={[\n {\n label: 'Main Action',\n onClick: () => null,\n disabled: false,\n },\n {\n label: 'Additional Action 1',\n onClick: () => null,\n icon: <RocketLaunch />,\n },\n {\n label: 'Additional Action 2',\n onClick: () => null,\n disabled: true,\n disabledReason: 'Disabled because of some reason',\n icon: <DoNotDisturb />,\n },\n ]}\n className=\"custom-class-name\"\n size=\"large\"\n />\n );\n}\n```\n\n## Customization from ButtonGroup API\n\nSplitButton inherits all styling and layout properties from the MUI ButtonGroup API, allowing for flexible customization of appearance, size, variant, color, and orientation. This example shows how to apply ButtonGroup customizations to achieve different visual styles.\n\n```tsx\n// CustomizationExample.tsx\nimport React from 'react';\nimport { SplitButton } from '@ringpublishing/mui-components';\n\nexport default function CustomizationExample(): React.JSX.Element {\n return (\n <SplitButton\n actions={[\n {\n label: 'Main Action',\n onClick: () => null,\n disabled: false,\n },\n {\n label: 'Extra Action',\n onClick: () => null,\n },\n ]}\n size=\"medium\"\n variant=\"contained\"\n color=\"warning\"\n orientation=\"horizontal\"\n />\n );\n}\n```\n\n## Main Action Disabled\n\nDemonstrates a SplitButton where the primary action is disabled with a disabled reason tooltip. The additional actions in the dropdown remain functional, allowing users to access alternative actions when the main action is unavailable.\n\n```tsx\n// MainActionDisabledExample.tsx\nimport React from 'react';\nimport { SplitButton } from '@ringpublishing/mui-components';\n\nexport default function MainActionDisabledExample(): React.JSX.Element {\n return (\n <SplitButton\n actions={[\n {\n label: 'Main Action',\n onClick: () => null,\n disabled: true,\n disabledReason: 'Disabled because of some reason',\n },\n {\n label: 'Additional Action',\n onClick: () => null,\n disabled: false,\n },\n ]}\n />\n );\n}\n```\n\n## With One Action\n\nA simplified SplitButton variant containing only a single main action. In this configuration, the dropdown toggle button is not displayed, resulting in a standard button appearance.\n\n```tsx\n// WithOneActionExample.tsx\nimport React from 'react';\nimport { SplitButton } from '@ringpublishing/mui-components';\n\nexport default function WithOneActionExample(): React.JSX.Element {\n return (\n <SplitButton\n actions={[\n {\n label: 'Main Action',\n onClick: () => null,\n disabled: false,\n },\n ]}\n />\n );\n}\n```"
|
|
1737
|
-
},
|
|
1738
|
-
"organisms-comments": {
|
|
1739
|
-
"id": "organisms-comments",
|
|
1740
|
-
"name": "Comments",
|
|
1741
|
-
"category": "Organisms",
|
|
1742
|
-
"title": "Components/Organisms/Comments",
|
|
1743
|
-
"description": "The Comments component provides a complete interface for displaying, creating, editing, and deleting comments. It handles loading states during async operations and includes error handling.",
|
|
1744
|
-
"argTypes": {
|
|
1745
|
-
"labels": {
|
|
1746
|
-
"description": "Labels for fields and buttons in the Comments component. Supported keys:\n- `placeholder`: Placeholder text in the comment field.\n- `editing`: Label for the edit comment field.\n- `modified`: Label for the modified comment.\n- `add`: Label for the add comment button.\n- `cancel`: Label for the cancel button.\n- `update`: Label for the update comment button.",
|
|
1747
|
-
"control": "object",
|
|
1748
|
-
"category": "content",
|
|
1749
|
-
"type": "{ placeholder: string; editing: string; modified: string; add: string; cancel: string; update: string }"
|
|
1750
|
-
},
|
|
1751
|
-
"initialComments": {
|
|
1752
|
-
"description": "Array of comments to be displayed. Each comment should have the following properties:\n- `id`: Unique identifier for the comment (`string` or `number`).\n- `text`: Text content of the comment.\n- `author`: Author of the comment.\n- `creationTime`: Date/time value of when the comment was created (will be displayed as a formatted string).\n- `isOwner`: Boolean indicating if the current user is the owner of the comment.\n- `isModified`: Boolean indicating if the comment has been modified.\nThe component will display the comments in the order they are provided in the array.",
|
|
1753
|
-
"control": "object",
|
|
1754
|
-
"category": "content",
|
|
1755
|
-
"type": "CommentProps[]"
|
|
1756
|
-
},
|
|
1757
|
-
"minLength": {
|
|
1758
|
-
"description": "Minimum number of characters required for the text field input to enable the submit button.",
|
|
1759
|
-
"control": "number",
|
|
1760
|
-
"category": "validation",
|
|
1761
|
-
"type": "number"
|
|
1762
|
-
},
|
|
1763
|
-
"disableCreatePanel": {
|
|
1764
|
-
"description": "Comment panel will be hidden.",
|
|
1765
|
-
"control": "boolean",
|
|
1766
|
-
"category": "behavior",
|
|
1767
|
-
"type": "boolean"
|
|
1768
|
-
},
|
|
1769
|
-
"onAdd": {
|
|
1770
|
-
"description": "**Event**\nTriggered when a new comment is submitted. The callback receives two arguments:\n- `text`: The text of the submitted comment.\n- `api`: An object providing methods to update the UI after processing the comment.\n\nThe callback is expected to return a `Promise` to handle asynchronous operations, such as sending the comment to a server. While the `Promise` is pending, the input field and action buttons are disabled until the `Promise` resolves or rejects.\nThe `api` object includes the following methods:\n- `addComment(comment)`: Appends the new comment to the UI and re-enables the input and buttons. Call this when the server operation succeeds.\n- `setError(message)`: Displays an error message and re-enables the input and buttons. Call this when the server operation fails.\n\n**Important**: You must call either `addComment` or `setError` in the `Promise` resolution or rejection handlers to update the UI and ensure the controls are re-enabled.",
|
|
1771
|
-
"control": false,
|
|
1772
|
-
"category": "callbacks",
|
|
1773
|
-
"type": "(text: string, api: OnAddApi) => Promise<void>"
|
|
1774
|
-
},
|
|
1775
|
-
"onUpdate": {
|
|
1776
|
-
"description": "**Event**\nTriggered when a comment is updated. The callback receives three arguments:\n- `id`: The ID of the comment being updated.\n- `text`: The new text of the comment.\n- `api`: An object providing methods to update the UI after processing the comment.\n\nThe callback is expected to return a `Promise` to handle asynchronous operations, such as sending the updated comment to a server. While the `Promise` is pending, the input field and action buttons are disabled until the `Promise` resolves or rejects.\nThe `api` object includes the following methods:\n- `updateComment(comment)`: Updates the comment in the UI and re-enables the input and buttons. Call this when the server operation succeeds.\n- `setError(message)`: Displays an error message and re-enables the input and buttons. Call this when the server operation fails.\n\n**Important**: You must call either `updateComment` or `setError` in the `Promise` resolution or rejection handlers to update the UI and ensure the controls are re-enabled.",
|
|
1777
|
-
"control": false,
|
|
1778
|
-
"category": "callbacks",
|
|
1779
|
-
"type": "(id: CommentIdProp, text: string, api: OnUpdateApi) => Promise<void>"
|
|
1780
|
-
},
|
|
1781
|
-
"onDelete": {
|
|
1782
|
-
"description": "**Event**\nTriggered when a comment is deleted. The callback receives two arguments:\n- `id`: The ID of the comment being deleted.\n- `api`: An object providing methods to update the UI after processing the comment.\n\nThe callback is expected to return a `Promise` to handle asynchronous operations, such as sending the delete request to a server. While the `Promise` is pending, the action buttons are disabled until the `Promise` resolves or rejects.\nThe `api` object includes the following methods:\n- `deleteComment()`: Removes the comment from the UI and re-enables the buttons. Call this when the server operation succeeds.\n- `setError(message)`: Displays an error message and re-enables the buttons. Call this when the server operation fails.\n\n**Important**: You must call either `deleteComment` or `setError` in the `Promise` resolution or rejection handlers to update the UI and ensure the controls are re-enabled.",
|
|
1783
|
-
"control": false,
|
|
1784
|
-
"category": "callbacks",
|
|
1785
|
-
"type": "(id: CommentIdProp, api: OnDeleteApi) => Promise<void>"
|
|
1786
|
-
},
|
|
1787
|
-
"sx": {
|
|
1788
|
-
"description": "MUI System properties for customizing the style of the root element.",
|
|
1789
|
-
"category": "common",
|
|
1790
|
-
"type": "SxProps<Theme>"
|
|
1791
|
-
},
|
|
1792
|
-
"className": {
|
|
1793
|
-
"description": "CSS class name applied to the root element.",
|
|
1794
|
-
"category": "common",
|
|
1795
|
-
"type": "string"
|
|
1796
|
-
}
|
|
1797
|
-
},
|
|
1798
|
-
"storyNames": [
|
|
1799
|
-
"Default",
|
|
1800
|
-
"ErrorHandling"
|
|
1801
|
-
],
|
|
1802
|
-
"docs": "# Comments\n\nThe Comments component provides a complete interface for displaying, creating, editing, and deleting comments. It handles loading states during async operations and includes error handling.\n\n- Display a list of comments with author, timestamp, and ownership indicators\n- Add new comments via a dedicated create panel\n- Edit and delete owned comments with inline editing\n- Async operation support with loading states and error messages\n- Customizable labels, minimum text length, and comment ownership display\n\n## Default\n\nThe default story demonstrates the Comments component with full CRUD functionality. Adding, updating, and deleting comments are simulated with a short delay to showcase loading states. Owned comments display edit and delete actions on hover.\n\n```tsx\n// DefaultExample.tsx\nimport React from 'react';\nimport { Box } from '@mui/material';\nimport { Comments, CommentsLabels } from '@ringpublishing/mui-components';\n\ninterface CommentData {\n id: string | number;\n text: string;\n creationTime: string;\n author: string;\n isOwner: boolean;\n isModified?: boolean;\n}\n\nconst labels: CommentsLabels = {\n placeholder: 'Add a comment',\n editing: 'Edit comment',\n modified: 'modified',\n add: 'Add',\n cancel: 'Cancel',\n update: 'Update',\n};\n\nconst initialComments: CommentData[] = [\n {\n id: '1',\n isOwner: true,\n text: 'Intro needs more historical context.',\n creationTime: '15:45 | 26-10-2020',\n author: 'Anna Kowalska',\n },\n {\n id: '2',\n isOwner: false,\n text: 'Fixed typos in research section, check it.',\n creationTime: '09:12 | 27-10-2020',\n author: 'Jan Nowak',\n },\n {\n id: '3',\n isOwner: false,\n text: 'Stats para needs a source, no?',\n creationTime: '14:30 | 27-10-2020',\n author: 'Katarzyna Wisniewska',\n },\n {\n id: '4',\n isOwner: true,\n text: 'Cut last chapter, was too long. Thoughts?',\n creationTime: '18:20 | 28-10-2020',\n isModified: true,\n author: 'Anna Kowalska',\n },\n {\n id: '5',\n isOwner: false,\n text: 'Added data table, could use better visuals.',\n creationTime: '11:15 | 29-10-2020',\n author: 'Piotr Malinowski',\n },\n];\n\nfunction formatCreationTime(): string {\n return (\n new Date().toLocaleString('pl-PL', { hour: '2-digit', minute: '2-digit' }).replace(',', '') +\n ' | ' +\n new Date().toLocaleString('pl-PL', { day: '2-digit', month: '2-digit', year: 'numeric' }).split('.').join('-')\n );\n}\n\nconst simulateServer = {\n delete(id: string): Promise<{ status: string; id: string }> {\n return new Promise((resolve) => {\n setTimeout(() => {\n resolve({ status: 'success', id });\n }, 1000);\n });\n },\n\n add(text: string): Promise<CommentData> {\n return new Promise((resolve) => {\n setTimeout(() => {\n resolve({\n id: crypto.randomUUID(),\n text,\n isOwner: true,\n creationTime: formatCreationTime(),\n author: 'Anna Kowalska',\n });\n }, 1000);\n });\n },\n\n update(id: string, text: string): Promise<{ status: string; id: string; text: string; creationTime: string }> {\n return new Promise((resolve) => {\n setTimeout(() => {\n resolve({ text, status: 'success', id, creationTime: formatCreationTime() });\n }, 1000);\n });\n },\n};\n\nexport default function DefaultExample(): React.JSX.Element {\n const handleDelete: React.ComponentProps<typeof Comments>['onDelete'] = async (id, { setError, deleteComment }) => {\n try {\n await simulateServer.delete(String(id));\n deleteComment();\n } catch (error) {\n setError('Server error: Failed to delete comment');\n }\n };\n\n const handleAdd: React.ComponentProps<typeof Comments>['onAdd'] = async (text, { addComment, setError }) => {\n try {\n const newComment = await simulateServer.add(text);\n addComment(newComment);\n } catch (error) {\n setError('Error adding comment.');\n }\n };\n\n const handleUpdate: React.ComponentProps<typeof Comments>['onUpdate'] = async (\n id,\n text,\n { updateComment, setError },\n ) => {\n try {\n const { creationTime } = await simulateServer.update(String(id), text);\n updateComment({ text, isModified: true, creationTime });\n } catch (error) {\n setError('Error updating comment.');\n }\n };\n\n return (\n <Box display=\"flex\" justifyContent=\"center\">\n <Box width=\"420px\">\n <Comments\n onDelete={handleDelete}\n onUpdate={handleUpdate}\n onAdd={handleAdd}\n labels={labels}\n initialComments={initialComments}\n />\n </Box>\n </Box>\n );\n}\n```\n\n## Error Handling\n\nDemonstrates how the Comments component handles errors returned from async operations. All callbacks (`onAdd`, `onUpdate`, `onDelete`) call `setError` instead of the success method, showing inline error messages for each action.\n\n### Key Features:\n\n- Error messages displayed inline below the affected comment or input\n- Controls are re-enabled after an error, allowing the user to retry\n- Each operation (add, update, delete) can show independent error messages\n\n```tsx\n// ErrorHandlingExample.tsx\nimport React from 'react';\nimport { Box } from '@mui/material';\nimport { Comments, CommentsLabels } from '@ringpublishing/mui-components';\n\ninterface CommentData {\n id: string | number;\n text: string;\n creationTime: string;\n author: string;\n isOwner: boolean;\n isModified?: boolean;\n}\n\nconst initialComments: CommentData[] = [\n {\n id: '1',\n isOwner: true,\n text: 'Intro needs more historical context.',\n creationTime: '15:45 | 26-10-2020',\n author: 'Anna Kowalska',\n },\n];\n\nconst labels: CommentsLabels = {\n placeholder: 'Add a comment',\n editing: 'Edit comment',\n modified: 'modified',\n add: 'Add',\n cancel: 'Cancel',\n update: 'Update',\n};\n\nexport default function ErrorHandlingExample(): React.JSX.Element {\n return (\n <Box display=\"flex\" justifyContent=\"center\">\n <Box width=\"420px\">\n <Comments\n labels={labels}\n initialComments={initialComments}\n onAdd={async (text, { addComment, setError }): Promise<void> => {\n await new Promise((resolve) => setTimeout(resolve, 700));\n setError('Unable to add comment. Please try again later.');\n }}\n onUpdate={async (id, text, { updateComment, setError }): Promise<void> => {\n await new Promise((resolve) => setTimeout(resolve, 700));\n setError('Unable to update comment. Please try again later.');\n }}\n onDelete={async (id, { deleteComment, setError }): Promise<void> => {\n await new Promise((resolve) => setTimeout(resolve, 700));\n setError('Unable to delete comment. Please try again later.');\n }}\n />\n </Box>\n </Box>\n );\n}\n```"
|
|
1803
|
-
},
|
|
1804
|
-
"organisms-content-list": {
|
|
1805
|
-
"id": "organisms-content-list",
|
|
1806
|
-
"name": "ContentList",
|
|
1807
|
-
"category": "Organisms",
|
|
1808
|
-
"title": "Components/Organisms/ContentList",
|
|
1809
|
-
"description": "A vertical navigation layout component that displays a list of section headers on the left side with corresponding content on the right. Ideal for settings pages, profile forms, or any content that needs organized sectioning with easy navigation.",
|
|
1810
|
-
"argTypes": {
|
|
1811
|
-
"inputData": {
|
|
1812
|
-
"description": "Array of objects containing header, children, and optional metadata for each content section",
|
|
1813
|
-
"control": "object",
|
|
1814
|
-
"category": "content",
|
|
1815
|
-
"type": "InputDataProps[]"
|
|
1816
|
-
},
|
|
1817
|
-
"listHeader": {
|
|
1818
|
-
"description": "Additional header element rendered above the navigation list on the left side. Accepts JSX element, string, or React node",
|
|
1819
|
-
"control": false,
|
|
1820
|
-
"category": "content",
|
|
1821
|
-
"type": "ReactNode | JSX.Element | string"
|
|
1822
|
-
},
|
|
1823
|
-
"selectedItemIndex": {
|
|
1824
|
-
"description": "The index of the selected item",
|
|
1825
|
-
"control": "number",
|
|
1826
|
-
"category": "behavior",
|
|
1827
|
-
"type": "number",
|
|
1828
|
-
"defaultValue": "0"
|
|
1829
|
-
},
|
|
1830
|
-
"onHeaderClick": {
|
|
1831
|
-
"description": "Function called after clicking on the header on the left side",
|
|
1832
|
-
"control": false,
|
|
1833
|
-
"category": "behavior",
|
|
1834
|
-
"type": "(item: InputDataProps, index: number) => void"
|
|
1835
|
-
},
|
|
1836
|
-
"containerSx": {
|
|
1837
|
-
"description": "Custom styles for the content container on the right side",
|
|
1838
|
-
"control": "object",
|
|
1839
|
-
"category": "customization",
|
|
1840
|
-
"type": "SxProps<Theme>"
|
|
1841
|
-
},
|
|
1842
|
-
"dataTestIdSuffix": {
|
|
1843
|
-
"description": "Optional suffix added to data-testid attributes for E2E testing. Results in data-testid=\"ring-contentlist-{suffix}\"",
|
|
1844
|
-
"control": "text",
|
|
1845
|
-
"category": "testing",
|
|
1846
|
-
"type": "string"
|
|
1847
|
-
},
|
|
1848
|
-
"sx": {
|
|
1849
|
-
"description": "Custom MUI sx prop for styling the root container",
|
|
1850
|
-
"control": "object",
|
|
1851
|
-
"category": "customization",
|
|
1852
|
-
"type": "SxProps<Theme>"
|
|
1853
|
-
},
|
|
1854
|
-
"className": {
|
|
1855
|
-
"description": "CSS class name to be applied to the root container",
|
|
1856
|
-
"control": "text",
|
|
1857
|
-
"category": "customization",
|
|
1858
|
-
"type": "string"
|
|
1859
|
-
}
|
|
1860
|
-
},
|
|
1861
|
-
"storyNames": [
|
|
1862
|
-
"Default"
|
|
1863
|
-
],
|
|
1864
|
-
"docs": "# ContentList\n\nA vertical navigation layout component that displays a list of section headers on the left side with corresponding content on the right. Ideal for settings pages, profile forms, or any content that needs organized sectioning with easy navigation.\n\n## Key Features\n\n- **Synchronized navigation**: Left sidebar automatically tracks visible content sections\n- **Flexible content**: Accepts any React component or HTML as section content\n- **Header customization**: Add icons, badges, or custom elements to section headers\n- **Action support**: Place action buttons or menus in section headers\n- **Alert banners**: Show notifications or warnings above specific sections\n- **Custom styling**: Full control over container and item styles via `sx` props\n- **Keyboard accessible**: Navigate sections via click or programmatic control\n\n## Default\n\nThe default example demonstrates a complete content list with various section types including form fields, media upload, text content, and empty sections. Each section shows different capabilities like header actions, additional header data (icons/badges), and before-header content (alerts).\n\n```tsx\n// DefaultExample.tsx\nimport React from 'react';\nimport {\n IconButton,\n Box,\n Alert,\n TextField,\n Tooltip,\n Typography,\n Switch,\n FormHelperText,\n Stack,\n Button,\n} from '@mui/material';\nimport { RocketLaunch, RemoveDone, Delete, Crop, Add, PeopleAltOutlined, PhotoOutlined } from '@mui/icons-material';\nimport { ContentList, Media } from '@ringpublishing/mui-components';\n\nconst BasicInfoComponent = () => {\n return (\n <Stack spacing={1}>\n <Box>\n <TextField\n label=\"Basic info\"\n fullWidth={true}\n helperText=\"This name will be visible on author's pages and articles.\"\n />\n </Box>\n <Box sx={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between', mb: 1 }}>\n <TextField\n label=\"Disambiguation\"\n fullWidth={true}\n helperText=\"Use this field when the author name is already taken. This will help you easily distinguish similarly named authors.\"\n />\n <Tooltip title=\"Delete\">\n <IconButton>\n <RemoveDone />\n </IconButton>\n </Tooltip>\n </Box>\n <Box>\n <Box sx={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}>\n <Typography variant=\"body2\">Active</Typography>\n <Switch />\n </Box>\n <FormHelperText>Include in suggestions</FormHelperText>\n </Box>\n </Stack>\n );\n};\n\nconst ImageComponent = () => {\n return (\n <Stack spacing={1}>\n <Typography>Here you can change your image</Typography>\n <Media\n sx={{ maxWidth: '400px' }}\n image=\"https://example.com/image.jpg\"\n type=\"Image\"\n ratio={'16/9'}\n actions={[\n {\n label: 'Crop',\n onClick: () => console.log('Crop clicked'),\n icon: <Crop />,\n },\n {\n label: 'Delete',\n onClick: () => console.log('Delete clicked'),\n icon: <Delete />,\n },\n ]}\n />\n </Stack>\n );\n};\n\nconst SocialProfilesComponent = () => {\n return (\n <Stack spacing={2}>\n <Box sx={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}>\n <TextField fullWidth={true} label=\"Facebook\" onChange={() => console.log('Facebook changed')} />\n <Tooltip title=\"Delete profile\">\n <IconButton onClick={() => console.log('Delete Facebook')}>\n <Delete />\n </IconButton>\n </Tooltip>\n </Box>\n <Box sx={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}>\n <TextField fullWidth={true} label=\"Instagram\" onChange={() => console.log('Instagram changed')} />\n <Tooltip title=\"Delete profile\">\n <IconButton onClick={() => console.log('Delete Instagram')}>\n <Delete />\n </IconButton>\n </Tooltip>\n </Box>\n </Stack>\n );\n};\n\nexport default function DefaultExample(): React.JSX.Element {\n return (\n <ContentList\n listHeader={\n <Box sx={{ display: 'flex', alignItems: 'flex-start', justifyContent: 'flex-start' }}>\n <RocketLaunch sx={{ mr: 2 }} />\n <Typography variant=\"h6\">List header slot example</Typography>\n </Box>\n }\n inputData={[\n {\n header: 'Basic info',\n beforeHeaderContent: (\n <Box sx={{ maxWidth: '640px', margin: '0 auto' }}>\n <Alert severity=\"info\">There are unpublished changes</Alert>\n </Box>\n ),\n additionalHeaderData: <PeopleAltOutlined />,\n children: <BasicInfoComponent />,\n },\n {\n header: 'Image',\n additionalHeaderData: <PhotoOutlined />,\n children: <ImageComponent />,\n },\n {\n header: 'Section with text',\n children: (\n <Box sx={{ width: '100%', mt: 2 }}>\n Lorem ipsum, dolor sit amet consectetur adipisicing elit. Repudiandae harum facere commodi\n sed. Veritatis qui sunt ullam repellendus fuga eligendi deleniti animi quibusdam. Animi\n quasi facere inventore laudantium pariatur aperiam. Consectetur illum itaque expedita\n eveniet repudiandae eaque dolorum temporibus officiis aliquam maxime, ducimus esse soluta.\n Officia dicta ipsam earum voluptatibus ipsa unde asperiores. Corrupti est voluptate a.\n Perspiciatis, harum assumenda?\n </Box>\n ),\n },\n {\n header: 'Social profiles',\n children: <SocialProfilesComponent />,\n additionalHeaderData: <span style={{ width: '24px' }}>2</span>,\n contentHeaderAction: (\n <Button onClick={() => console.log('Add profile clicked')} variant=\"text\">\n <Add />\n Add profile\n </Button>\n ),\n },\n {\n header: 'Empty section',\n children: (\n <div\n style={{ height: '400px', width: '100%', border: '1px solid lightgray', marginTop: '20px' }}\n />\n ),\n },\n {\n header: 'Section with another text',\n children: (\n <Box sx={{ width: '100%', mt: 2 }}>\n Lorem ipsum, dolor sit amet consectetur adipisicing elit. Repudiandae harum facere commodi\n sed. Veritatis qui sunt ullam repellendus fuga eligendi deleniti animi quibusdam. Animi\n quasi facere inventore laudantium pariatur aperiam. Consectetur illum itaque expedita\n eveniet repudiandae eaque dolorum temporibus officiis aliquam maxime, ducimus esse soluta.\n Officia dicta ipsam earum voluptatibus ipsa unde asperiores. Corrupti est voluptate a.\n Perspiciatis, harum assumenda?\n </Box>\n ),\n },\n ]}\n />\n );\n}\n```\n\n## Usage Example\n\n```typescript\n\nfunction SettingsPage() {\n const [selectedSection, setSelectedSection] = React.useState(0);\n\n return (\n <ContentList\n selectedItemIndex={selectedSection}\n onHeaderClick={(item, index) => setSelectedSection(index)}\n listHeader={\n <Box sx={{ display: 'flex', alignItems: 'center' }}>\n <Settings sx={{ mr: 1 }} />\n <Typography variant=\"h6\">Settings</Typography>\n </Box>\n }\n inputData={[\n {\n header: 'Profile',\n additionalHeaderData: <Profile />,\n children: <div>Profile settings content</div>\n },\n {\n header: 'Security',\n additionalHeaderData: <Security />,\n children: <div>Security settings content</div>\n }\n ]}\n />\n );\n}\n```\n\n### inputData Structure\n\nThe `inputData` prop accepts an array of objects with the following structure:\n\n| Property | Type | Description |\n| ---------------------- | ----------- | ----------------------------------------------------------- |\n| `header` | `string` | Section header text (required) |\n| `children` | `ReactNode` | Content displayed in the right panel (required) |\n| `additionalHeaderData` | `ReactNode` | Icon, badge, or element shown next to header in left nav |\n| `contentHeaderAction` | `ReactNode` | Action button or menu shown in section header on right side |\n| `beforeHeaderContent` | `ReactNode` | Alert or banner shown above the section content |\n| `itemSx` | `SxProps` | Custom styles for the content box |\n\n### Navigation Behavior\n\n- The component automatically scrolls the selected section into view\n- Clicking a header in the left nav selects that section and scrolls to it\n- The left nav highlights the currently visible section as you scroll\n- Use `selectedItemIndex` prop to control section selection programmatically\n- Use `onHeaderClick` callback to respond to section changes\n\n### Styling Options\n\n- **`sx`**: Style the root container\n- **`containerSx`**: Style the right-side content container specifically\n- **`itemSx`**: Style individual content boxes (per section via inputData)\n- **`className`**: Apply CSS class to root element"
|
|
1865
|
-
},
|
|
1866
|
-
"organisms-data-grid": {
|
|
1867
|
-
"id": "organisms-data-grid",
|
|
1868
|
-
"name": "DataGrid",
|
|
1869
|
-
"category": "Organisms",
|
|
1870
|
-
"title": "Components/Organisms/DataGrid",
|
|
1871
|
-
"description": "An enhanced data grid component built on top of MUI X DataGrid.\n**Features:**",
|
|
1872
|
-
"argTypes": {
|
|
1873
|
-
"showRingToolbar": {
|
|
1874
|
-
"description": "Displays the custom Ring toolbar with sorting, refresh and bulk actions controls.",
|
|
1875
|
-
"control": "boolean",
|
|
1876
|
-
"category": "toolbar",
|
|
1877
|
-
"type": "boolean",
|
|
1878
|
-
"defaultValue": "false"
|
|
1879
|
-
},
|
|
1880
|
-
"labels": {
|
|
1881
|
-
"description": "Labels used within the toolbar component.",
|
|
1882
|
-
"control": "object",
|
|
1883
|
-
"category": "toolbar",
|
|
1884
|
-
"type": "{ results: string; refresh?: string; enableAutoRefresh?: string; disableAutoRefresh?: string; selectAll?: string; deselectAll?: string }"
|
|
1885
|
-
},
|
|
1886
|
-
"sortableFields": {
|
|
1887
|
-
"description": "Fields available for sorting in the toolbar dropdown.",
|
|
1888
|
-
"control": "object",
|
|
1889
|
-
"category": "toolbar",
|
|
1890
|
-
"type": "{ name: string; key: string; onSortingChange: (key: string) => void }[]"
|
|
1891
|
-
},
|
|
1892
|
-
"sortField": {
|
|
1893
|
-
"description": "Key of the currently sorted field. Overrides the internally held value.",
|
|
1894
|
-
"control": "text",
|
|
1895
|
-
"category": "toolbar",
|
|
1896
|
-
"type": "string"
|
|
1897
|
-
},
|
|
1898
|
-
"additionalComponent": {
|
|
1899
|
-
"description": "Additional component rendered in the toolbar (right side, after the refresh icon).",
|
|
1900
|
-
"category": "toolbar",
|
|
1901
|
-
"type": "React.ReactNode"
|
|
1902
|
-
},
|
|
1903
|
-
"totalRowCount": {
|
|
1904
|
-
"description": "Total row count displayed in the toolbar.",
|
|
1905
|
-
"control": "number",
|
|
1906
|
-
"category": "toolbar",
|
|
1907
|
-
"type": "number"
|
|
1908
|
-
},
|
|
1909
|
-
"filterChips": {
|
|
1910
|
-
"description": "Filter chips displayed above the data grid.",
|
|
1911
|
-
"control": "object",
|
|
1912
|
-
"category": "toolbar",
|
|
1913
|
-
"type": "{ chips: { filter: string; value: string; onDelete: () => void }[]; onDeleteAll?: () => void }"
|
|
1914
|
-
},
|
|
1915
|
-
"autoRefresh": {
|
|
1916
|
-
"description": "Enables the auto-refresh functionality.",
|
|
1917
|
-
"control": "boolean",
|
|
1918
|
-
"category": "auto refresh",
|
|
1919
|
-
"type": "boolean",
|
|
1920
|
-
"defaultValue": "false"
|
|
1921
|
-
},
|
|
1922
|
-
"refreshRate": {
|
|
1923
|
-
"description": "Auto-refresh interval in milliseconds.",
|
|
1924
|
-
"control": "number",
|
|
1925
|
-
"category": "auto refresh",
|
|
1926
|
-
"type": "number",
|
|
1927
|
-
"defaultValue": "60000"
|
|
1928
|
-
},
|
|
1929
|
-
"refreshItems": {
|
|
1930
|
-
"description": "Function called on refresh icon click and during auto-refresh.",
|
|
1931
|
-
"category": "auto refresh",
|
|
1932
|
-
"type": "() => void"
|
|
1933
|
-
},
|
|
1934
|
-
"refreshCallback": {
|
|
1935
|
-
"description": "Callback fired when the refresh icon is clicked (e.g. for analytics).",
|
|
1936
|
-
"category": "auto refresh",
|
|
1937
|
-
"type": "() => void"
|
|
1938
|
-
},
|
|
1939
|
-
"autoRefreshCallback": {
|
|
1940
|
-
"description": "Callback fired when the auto-refresh toggle is clicked.",
|
|
1941
|
-
"category": "auto refresh",
|
|
1942
|
-
"type": "(autoRefreshMode: boolean) => void"
|
|
1943
|
-
},
|
|
1944
|
-
"disableAutoRefreshOnUserInteraction": {
|
|
1945
|
-
"description": "Pauses auto-refresh on user interaction (mouseover, touchmove, scroll).",
|
|
1946
|
-
"control": "boolean",
|
|
1947
|
-
"category": "auto refresh",
|
|
1948
|
-
"type": "boolean",
|
|
1949
|
-
"defaultValue": "true"
|
|
1950
|
-
},
|
|
1951
|
-
"userInteractionDebounceDelay": {
|
|
1952
|
-
"description": "Debounce delay in milliseconds for user interaction events that pause auto-refresh.",
|
|
1953
|
-
"control": "number",
|
|
1954
|
-
"category": "auto refresh",
|
|
1955
|
-
"type": "number",
|
|
1956
|
-
"defaultValue": "250"
|
|
1957
|
-
},
|
|
1958
|
-
"enableBulkActions": {
|
|
1959
|
-
"description": "Enables the bulk actions toolbar. Automatically enables checkbox selection.",
|
|
1960
|
-
"control": "boolean",
|
|
1961
|
-
"category": "bulk actions",
|
|
1962
|
-
"type": "boolean",
|
|
1963
|
-
"defaultValue": "false"
|
|
1964
|
-
},
|
|
1965
|
-
"bulkActions": {
|
|
1966
|
-
"description": "Bulk operation action buttons shown in the toolbar when rows are selected.",
|
|
1967
|
-
"control": "object",
|
|
1968
|
-
"category": "bulk actions",
|
|
1969
|
-
"type": "{ icon: ReactNode; tooltip: string; onClick: (params: BulkOperationCallbackParams, event: MouseEvent) => void }[]"
|
|
1970
|
-
},
|
|
1971
|
-
"onBulkActionsClose": {
|
|
1972
|
-
"description": "Callback fired when the bulk actions bar is closed.",
|
|
1973
|
-
"category": "bulk actions",
|
|
1974
|
-
"type": "React.MouseEventHandler"
|
|
1975
|
-
},
|
|
1976
|
-
"maxSelectedRowsCount": {
|
|
1977
|
-
"description": "Maximum number of rows that can be selected at once.",
|
|
1978
|
-
"control": "number",
|
|
1979
|
-
"category": "bulk actions",
|
|
1980
|
-
"type": "number",
|
|
1981
|
-
"defaultValue": "5000"
|
|
1982
|
-
},
|
|
1983
|
-
"checkboxSelection": {
|
|
1984
|
-
"description": "Shows a checkbox column for row selection.",
|
|
1985
|
-
"control": "boolean",
|
|
1986
|
-
"category": "selection",
|
|
1987
|
-
"type": "boolean",
|
|
1988
|
-
"defaultValue": "false"
|
|
1989
|
-
},
|
|
1990
|
-
"disableSelectAllCheckbox": {
|
|
1991
|
-
"description": "Removes the select-all checkbox from the header.",
|
|
1992
|
-
"control": "boolean",
|
|
1993
|
-
"category": "selection",
|
|
1994
|
-
"type": "boolean",
|
|
1995
|
-
"defaultValue": "false"
|
|
1996
|
-
},
|
|
1997
|
-
"rowSelectionModel": {
|
|
1998
|
-
"description": "Controlled row selection state.",
|
|
1999
|
-
"control": "object",
|
|
2000
|
-
"category": "selection",
|
|
2001
|
-
"type": "{ type: 'include' | 'exclude'; ids: Set<GridRowId> }"
|
|
2002
|
-
},
|
|
2003
|
-
"onRowSelectionModelChange": {
|
|
2004
|
-
"description": "Callback fired when the row selection changes.",
|
|
2005
|
-
"category": "selection",
|
|
2006
|
-
"type": "(model: GridRowSelectionModel, details: GridCallbackDetails) => void"
|
|
2007
|
-
},
|
|
2008
|
-
"clearSelectionOnRefresh": {
|
|
2009
|
-
"description": "Clears row selection when the list refreshes.",
|
|
2010
|
-
"control": "boolean",
|
|
2011
|
-
"category": "selection",
|
|
2012
|
-
"type": "boolean",
|
|
2013
|
-
"defaultValue": "true"
|
|
2014
|
-
},
|
|
2015
|
-
"error": {
|
|
2016
|
-
"description": "Shows error placeholder when rows are empty instead of the no-results placeholder.",
|
|
2017
|
-
"control": "boolean",
|
|
2018
|
-
"category": "states",
|
|
2019
|
-
"type": "boolean",
|
|
2020
|
-
"defaultValue": "false"
|
|
2021
|
-
},
|
|
2022
|
-
"placeholderLabels": {
|
|
2023
|
-
"description": "Custom labels for the error and empty state placeholders. When omitted, default localized labels are used.",
|
|
2024
|
-
"control": "object",
|
|
2025
|
-
"category": "states",
|
|
2026
|
-
"type": "{ error?: { header?: string; description?: string; footer?: string }; empty?: { header?: string; description?: string; footer?: string }; tryAgainButton?: string }"
|
|
2027
|
-
},
|
|
2028
|
-
"loading": {
|
|
2029
|
-
"description": "Shows a linear progress bar loading overlay.",
|
|
2030
|
-
"control": "boolean",
|
|
2031
|
-
"category": "states",
|
|
2032
|
-
"type": "boolean",
|
|
2033
|
-
"defaultValue": "false"
|
|
2034
|
-
},
|
|
2035
|
-
"rows": {
|
|
2036
|
-
"description": "The data rows to display in the grid.",
|
|
2037
|
-
"control": "object",
|
|
2038
|
-
"category": "data",
|
|
2039
|
-
"type": "GridRowsProp"
|
|
2040
|
-
},
|
|
2041
|
-
"columns": {
|
|
2042
|
-
"description": "Column definitions for the grid.",
|
|
2043
|
-
"control": "object",
|
|
2044
|
-
"category": "data",
|
|
2045
|
-
"type": "GridColDef[]"
|
|
2046
|
-
},
|
|
2047
|
-
"rowHeight": {
|
|
2048
|
-
"description": "Fixed height in pixels for each row.",
|
|
2049
|
-
"control": "number",
|
|
2050
|
-
"category": "layout",
|
|
2051
|
-
"type": "number",
|
|
2052
|
-
"defaultValue": "52"
|
|
2053
|
-
},
|
|
2054
|
-
"columnHeaderHeight": {
|
|
2055
|
-
"description": "Height in pixels of the column headers.",
|
|
2056
|
-
"control": "number",
|
|
2057
|
-
"category": "layout",
|
|
2058
|
-
"type": "number",
|
|
2059
|
-
"defaultValue": "56"
|
|
2060
|
-
},
|
|
2061
|
-
"getRowHeight": {
|
|
2062
|
-
"description": "Function to calculate row height. Return 'auto' for dynamic height.",
|
|
2063
|
-
"category": "layout",
|
|
2064
|
-
"type": "(params: GridRowHeightParams) => GridRowHeightReturnValue"
|
|
2065
|
-
},
|
|
2066
|
-
"initialState": {
|
|
2067
|
-
"description": "Initial state for the grid, extends MUI GridInitialState with autoRefreshEnabled for the auto-refresh button initial state.",
|
|
2068
|
-
"control": "object",
|
|
2069
|
-
"category": "data",
|
|
2070
|
-
"type": "RingGridInitialState"
|
|
2071
|
-
},
|
|
2072
|
-
"apiRef": {
|
|
2073
|
-
"description": "API reference for direct grid manipulation. If not provided, one is created internally.",
|
|
2074
|
-
"category": "data",
|
|
2075
|
-
"type": "MutableRefObject<GridApiPro>"
|
|
2076
|
-
},
|
|
2077
|
-
"slots": {
|
|
2078
|
-
"description": "Override internal grid components. The toolbar slot is managed by showRingToolbar.",
|
|
2079
|
-
"control": "object",
|
|
2080
|
-
"category": "customization",
|
|
2081
|
-
"type": "DataGridProProps[\"slots\"]"
|
|
2082
|
-
},
|
|
2083
|
-
"slotProps": {
|
|
2084
|
-
"description": "Properties passed to slot components.",
|
|
2085
|
-
"control": "object",
|
|
2086
|
-
"category": "customization",
|
|
2087
|
-
"type": "DataGridProProps[\"slotProps\"]"
|
|
2088
|
-
},
|
|
2089
|
-
"sx": {
|
|
2090
|
-
"description": "MUI System properties to customize the grid style.",
|
|
2091
|
-
"control": "object",
|
|
2092
|
-
"category": "customization",
|
|
2093
|
-
"type": "SxProps<Theme>",
|
|
2094
|
-
"defaultValue": "{}"
|
|
2095
|
-
}
|
|
2096
|
-
},
|
|
2097
|
-
"storyNames": [
|
|
2098
|
-
"CustomCells",
|
|
2099
|
-
"CustomToolbar",
|
|
2100
|
-
"BulkActions",
|
|
2101
|
-
"NoResults",
|
|
2102
|
-
"NoResultsCustomLabels",
|
|
2103
|
-
"Error",
|
|
2104
|
-
"ErrorCustomLabels",
|
|
2105
|
-
"AutoRefreshActive",
|
|
2106
|
-
"AutoRefreshIgnoreInteraction",
|
|
2107
|
-
"AutoRefreshInitiallyDisabled",
|
|
2108
|
-
"AutoRefreshDisabled",
|
|
2109
|
-
"ClassicSelection"
|
|
2110
|
-
],
|
|
2111
|
-
"docs": "# DataGrid\n\nAn enhanced data grid component built on top of MUI X DataGrid.\n**Features:**\n\n- Custom toolbar with refresh, auto-refresh toggle, sorting, and additional components\n- Bulk actions mode with select all/deselect all and configurable max selection\n- Built-in custom cell renderers: combo cell, link cell, action cell, and spacer rows\n- Auto-refresh with configurable rate, user interaction debounce, and initial state\n- Filter chips group for active filter display\n- Checkbox selection with optional disabled select-all header\n- Error and no-results placeholder states\n\n## Custom Cells\n\nDemonstrates custom cell renderers (`renderComboCell`, `renderLinkCell`, `renderActionCell`) together with spacer rows (`createSpacerItem`), bulk actions, sorting, auto-refresh, and the custom toolbar. Also includes combo cells with `showPlaceholder` enabled to display image placeholders when the image URL is missing or broken.\n\n```tsx\n// CustomCellsExample.tsx\nimport React from 'react';\nimport { GridColDef, GridRowsProp } from '@mui/x-data-grid';\nimport { Remove, Edit, MoreVert } from '@mui/icons-material';\nimport { IconButton } from '@mui/material';\nimport {\n renderActionCell,\n renderComboCell,\n renderLinkCell,\n createSpacerItem,\n RingDataGrid,\n Action,\n} from '@ringpublishing/mui-components';\nimport { getImagePath, TestImage, ImageSize } from 'RingDemoImages';\n\nexport default function CustomCellsExample(): React.JSX.Element {\n const actions: Action[] = [\n {\n label: 'Change name',\n onClick: (): void => undefined,\n icon: <Edit />,\n },\n {\n label: 'Remove',\n onClick: (): void => undefined,\n disabled: true,\n disabledReason: 'You cannot use this action',\n icon: <Remove />,\n },\n ];\n\n const rows: GridRowsProp = [\n {\n ...createSpacerItem({\n title: 'In progress',\n color: 'primary',\n id: 0,\n icon: <Edit fontSize=\"small\" color=\"primary\" />,\n }),\n },\n {\n id: 1,\n combo: {\n label: 'Ada i Michał z \"Rolnika...\" odliczają dni do ślubu.',\n caption: 'Ada i Michał z \"Rolnik szuka żony\" odliczają dni do ślubu.',\n imageUrl: getImagePath(TestImage.MOUNTAINS, ImageSize.MEDIUM),\n chips: ['chip1', { label: 'chip1', color: 'primary' }, 'long chip with very long description'],\n withComment: true,\n commentIconColor: 'primary',\n badge: 1,\n },\n link: { href: 'https://ringpublishing.com', text: 'ringpublishing.com', target: '_blank' },\n actions,\n },\n {\n ...createSpacerItem({ title: 'Test', id: 0 }),\n },\n {\n id: 2,\n combo: {\n label: 'John Adams',\n caption: 'Administrator',\n imageUrl: getImagePath(TestImage.BEACH, ImageSize.MEDIUM),\n chips: 'chip1',\n },\n link: { href: 'https://ringpublishing.com', text: 'ringpublishing.com', target: '_blank' },\n actions,\n },\n {\n id: 3,\n combo: {\n label: 'Thomas Jefferson',\n badge: 1,\n },\n link: { href: 'https://ringpublishing.com', text: 'ringpublishing.com', target: '_blank' },\n actions,\n },\n {\n ...createSpacerItem({\n title: 'With placeholders',\n color: 'primary',\n id: 0,\n icon: <Edit fontSize=\"small\" color=\"primary\" />,\n }),\n },\n {\n id: 4,\n combo: {\n label: 'Ada i Michał z \"Rolnika...\" odliczają dni do ślubu.',\n caption: 'Ada i Michał z \"Rolnik szuka żony\" odliczają dni do ślubu.',\n chips: ['chip1', { label: 'chip1', color: 'primary' }, 'long chip with very long description'],\n withComment: true,\n commentIconColor: 'primary',\n badge: 1,\n showPlaceholder: true,\n },\n link: { href: 'https://ringpublishing.com', text: 'ringpublishing.com', target: '_blank' },\n actions,\n },\n ];\n\n const columns: GridColDef[] = [\n { field: 'combo', headerName: 'Combo', width: 600, renderCell: renderComboCell },\n { field: 'link', headerName: 'Link', width: 150, renderCell: renderLinkCell },\n { field: 'actions', headerName: 'Action', width: 150, renderCell: renderActionCell },\n ];\n\n const sortableFields = [\n { name: 'Publication date', key: 'publicationDate', onSortingChange: (): void => undefined },\n { name: 'Created date', key: 'createdDate', onSortingChange: (): void => undefined },\n ];\n\n const labels = {\n results: 'Results',\n refresh: 'Refresh',\n enableAutoRefresh: 'Enable auto refresh',\n disableAutoRefresh: 'Disable auto refresh',\n };\n\n return (\n <div style={{ padding: '20px', height: '450px' }}>\n <RingDataGrid\n rows={rows}\n columns={columns}\n getRowHeight={(): 'auto' => 'auto'}\n showRingToolbar={true}\n labels={labels}\n sortableFields={sortableFields}\n autoRefresh={true}\n refreshCallback={(): void => undefined}\n refreshItems={(): void => undefined}\n additionalComponent={\n <IconButton onClick={(): void => undefined}>\n <MoreVert />\n </IconButton>\n }\n rowHeight={35}\n columnHeaderHeight={40}\n totalRowCount={rows.length}\n />\n </div>\n );\n}\n```\n\n## Custom Toolbar\n\nShows the RingDataGrid toolbar with sorting fields, refresh controls, auto-refresh toggle, and an additional custom component slot.\n\n```tsx\n// CustomToolbarExample.tsx\nimport React from 'react';\nimport { GridColDef, GridRowsProp } from '@mui/x-data-grid';\nimport { MoreVertOutlined } from '@mui/icons-material';\nimport { IconButton } from '@mui/material';\nimport { RingDataGrid } from '@ringpublishing/mui-components';\n\nexport default function CustomToolbarExample(): React.JSX.Element {\n const rows: GridRowsProp = [\n { id: 0, title: 'Article 1', publicationDate: '10/16/2003, 7:11:27 PM', createdDate: '6/23/1979, 10:49:45 AM' },\n { id: 1, title: 'Article 2', publicationDate: '7/13/2022, 9:39:01 AM', createdDate: '2/14/2010, 1:58:50 PM' },\n { id: 2, title: 'Article 3', publicationDate: '3/12/2011, 1:51:17 AM', createdDate: '12/16/1995, 12:41:50 PM' },\n { id: 3, title: 'Article 4', publicationDate: '10/14/2017, 3:34:42 PM', createdDate: '8/3/1991, 8:54:26 AM' },\n { id: 4, title: 'Article 5', publicationDate: '2/22/1974, 2:57:38 PM', createdDate: '6/9/2021, 4:51:03 PM' },\n { id: 5, title: 'Article 6', publicationDate: '3/11/1989, 5:08:24 AM', createdDate: '11/13/2011, 3:42:29 AM' },\n { id: 6, title: 'Article 7', publicationDate: '1/26/2016, 6:59:18 AM', createdDate: '5/18/2004, 3:07:56 AM' },\n { id: 7, title: 'Article 8', publicationDate: '6/1/2006, 2:33:56 PM', createdDate: '7/1/1991, 11:53:42 AM' },\n {\n id: 8,\n title: 'Article 9',\n publicationDate: '11/10/1996, 11:55:32 AM',\n createdDate: '10/31/1998, 9:59:05 AM',\n },\n { id: 9, title: 'Article 10', publicationDate: '1/7/2021, 8:09:34 PM', createdDate: '10/21/1974, 8:53:11 PM' },\n ];\n\n const columns: GridColDef[] = [\n { field: 'title', headerName: 'Title', flex: 1 },\n { field: 'publicationDate', headerName: 'Publication date', width: 200 },\n { field: 'createdDate', headerName: 'Created date', width: 200 },\n ];\n\n const sortableFields = [\n { name: 'Publication date', key: 'publicationDate', onSortingChange: (): void => undefined },\n { name: 'Created date', key: 'createdDate', onSortingChange: (): void => undefined },\n ];\n\n const labels = {\n results: 'Results',\n refresh: 'Refresh',\n enableAutoRefresh: 'Enable auto refresh',\n disableAutoRefresh: 'Disable auto refresh',\n };\n\n return (\n <div style={{ padding: '20px', height: '300px' }}>\n <RingDataGrid\n rows={rows}\n columns={columns}\n labels={labels}\n showRingToolbar={true}\n sortableFields={sortableFields}\n autoRefresh={true}\n refreshCallback={(): void => undefined}\n refreshItems={(): void => undefined}\n additionalComponent={\n <IconButton onClick={(): void => undefined}>\n <MoreVertOutlined />\n </IconButton>\n }\n rowHeight={35}\n columnHeaderHeight={40}\n totalRowCount={rows.length}\n />\n </div>\n );\n}\n```\n\n## Bulk Actions\n\nEnables bulk operation mode with checkbox selection, select all/deselect all, and configurable bulk action buttons (e.g., Delete, Edit). The `maxSelectedRowsCount` limits the number of selectable rows.\n\n```tsx\n// BulkActionsExample.tsx\nimport React, { useState } from 'react';\nimport { GridColDef, GridRowsProp } from '@mui/x-data-grid';\nimport { Button } from '@mui/material';\nimport { Delete, Edit } from '@mui/icons-material';\nimport { RingDataGrid } from '@ringpublishing/mui-components';\nimport { dataGridRowsGenerator } from 'RingDataGridHelpers';\n\nexport default function BulkActionsExample(): React.JSX.Element {\n const [rows] = useState<GridRowsProp>(dataGridRowsGenerator(10));\n const [bulkActionsMode, setBulkActionsMode] = useState<boolean>(true);\n\n const columns: GridColDef[] = [\n { field: 'title', headerName: 'Title', flex: 1 },\n { field: 'publicationDate', headerName: 'Publication date', width: 200 },\n { field: 'createdDate', headerName: 'Created date', width: 200 },\n ];\n\n const sortableFields = [\n { name: 'Publication date', key: 'publicationDate', onSortingChange: (): void => undefined },\n { name: 'Created date', key: 'createdDate', onSortingChange: (): void => undefined },\n ];\n\n const labels = {\n results: 'Results',\n refresh: 'Refresh',\n enableAutoRefresh: 'Enable auto refresh',\n disableAutoRefresh: 'Disable auto refresh',\n selectAll: 'Select all',\n deselectAll: 'Deselect all',\n };\n\n return (\n <div style={{ padding: '20px', width: '100%', height: '400px' }}>\n <RingDataGrid\n rows={rows}\n columns={columns}\n labels={labels}\n sortableFields={sortableFields}\n autoRefresh={false}\n refreshCallback={(): void => undefined}\n showRingToolbar={true}\n enableBulkActions={bulkActionsMode}\n bulkActions={[\n {\n tooltip: 'Delete',\n onClick: (params): void => {\n void params;\n },\n icon: <Delete />,\n },\n {\n tooltip: 'Edit',\n onClick: (params): void => {\n void params;\n },\n icon: <Edit />,\n },\n ]}\n additionalComponent={\n <Button variant=\"outlined\" size=\"small\" onClick={(): void => setBulkActionsMode(true)}>\n Enable bulk actions\n </Button>\n }\n totalRowCount={6400}\n maxSelectedRowsCount={5000}\n onBulkActionsClose={(): void => setBulkActionsMode(false)}\n columnHeaderHeight={40}\n />\n </div>\n );\n}\n```\n\n## No Results\n\nDisplays the built-in \"no results\" placeholder when `rows` is an empty array.\n\n```tsx\n// NoResultsExample.tsx\nimport React from 'react';\nimport { GridColDef } from '@mui/x-data-grid';\nimport { RingDataGrid } from '@ringpublishing/mui-components';\n\nexport default function NoResultsExample(): React.JSX.Element {\n const columns: GridColDef[] = [\n { field: 'title', headerName: 'Title', flex: 1 },\n { field: 'publicationDate', headerName: 'Publication date', width: 200 },\n { field: 'createdDate', headerName: 'Created date', width: 200 },\n ];\n\n const labels = {\n results: 'Results',\n };\n\n return (\n <div style={{ padding: '20px', height: '500px' }}>\n <RingDataGrid\n rows={[]}\n columns={columns}\n labels={labels}\n rowHeight={35}\n columnHeaderHeight={40}\n totalRowCount={0}\n />\n </div>\n );\n}\n```\n\n## Error State\n\nDisplays the error placeholder when `error` is set to `true` and `rows` is empty.\n\n```tsx\n// ErrorExample.tsx\nimport React from 'react';\nimport { GridColDef } from '@mui/x-data-grid';\nimport { RingDataGrid } from '@ringpublishing/mui-components';\n\nexport default function ErrorExample(): React.JSX.Element {\n const columns: GridColDef[] = [\n { field: 'title', headerName: 'Title', flex: 1 },\n { field: 'publicationDate', headerName: 'Publication date', width: 200 },\n { field: 'createdDate', headerName: 'Created date', width: 200 },\n ];\n\n const labels = {\n results: 'Results',\n };\n\n return (\n <div style={{ padding: '20px', height: '500px' }}>\n <RingDataGrid\n rows={[]}\n error={true}\n columns={columns}\n labels={labels}\n rowHeight={35}\n columnHeaderHeight={40}\n totalRowCount={0}\n />\n </div>\n );\n}\n```\n\n## Auto Refresh — Active\n\nAuto-refresh enabled with a 5-second interval. User interactions (mouse, touch, scroll) temporarily pause refresh with a configurable debounce delay.\n\n```tsx\n// AutoRefreshActiveExample.tsx\nimport React from 'react';\nimport { RingDataGrid } from '@ringpublishing/mui-components';\nimport { storiesColumns, getInitialColumnVisibilityModel } from 'RingDataGridColumnsAndRows';\nimport { useRingDataGridDemoData } from 'RingDemoData';\n\nexport default function AutoRefreshActiveExample(): React.JSX.Element {\n const { items, loading, hasMore, nextData, totalCount, refresh } = useRingDataGridDemoData({\n initialCount: 40,\n });\n\n return (\n <div style={{ minWidth: '100%', width: '100%', padding: '20px', height: '600px' }}>\n <RingDataGrid\n autoRefresh={true}\n refreshRate={5000}\n userInteractionDebounceDelay={250}\n columnHeaderHeight={40}\n columns={storiesColumns}\n showRingToolbar={true}\n getRowHeight={(): 'auto' => 'auto'}\n labels={{\n results: 'Results',\n refresh: 'Refresh',\n enableAutoRefresh: 'Enable auto refresh',\n disableAutoRefresh: 'Disable auto refresh',\n }}\n disableColumnFilter={true}\n rows={items}\n totalRowCount={totalCount}\n onRowsScrollEnd={(): void => {\n if (hasMore) {\n nextData(30);\n }\n }}\n loading={loading}\n refreshItems={(): void => refresh()}\n initialState={{\n columns: {\n columnVisibilityModel: getInitialColumnVisibilityModel(true),\n },\n }}\n />\n </div>\n );\n}\n```\n\n## Auto Refresh — Ignore User Interaction\n\nAuto-refresh with `disableAutoRefreshOnUserInteraction` set to `false` — the grid continues refreshing regardless of user interaction.\n\n```tsx\n// AutoRefreshIgnoreInteractionExample.tsx\nimport React from 'react';\nimport { RingDataGrid } from '@ringpublishing/mui-components';\nimport { storiesColumns, getInitialColumnVisibilityModel } from 'RingDataGridColumnsAndRows';\nimport { useRingDataGridDemoData } from 'RingDemoData';\n\nexport default function AutoRefreshIgnoreInteractionExample(): React.JSX.Element {\n const { items, loading, hasMore, nextData, totalCount, refresh } = useRingDataGridDemoData({\n initialCount: 40,\n });\n\n return (\n <div style={{ minWidth: '100%', width: '100%', padding: '20px', height: '600px' }}>\n <RingDataGrid\n autoRefresh={true}\n refreshRate={5000}\n disableAutoRefreshOnUserInteraction={false}\n columnHeaderHeight={40}\n columns={storiesColumns}\n showRingToolbar={true}\n getRowHeight={(): 'auto' => 'auto'}\n labels={{\n results: 'Results',\n refresh: 'Refresh',\n enableAutoRefresh: 'Enable auto refresh',\n disableAutoRefresh: 'Disable auto refresh',\n }}\n disableColumnFilter={true}\n rows={items}\n totalRowCount={totalCount}\n onRowsScrollEnd={(): void => {\n if (hasMore) {\n nextData(30);\n }\n }}\n loading={loading}\n refreshItems={(): void => refresh()}\n initialState={{\n columns: {\n columnVisibilityModel: getInitialColumnVisibilityModel(true),\n },\n }}\n />\n </div>\n );\n}\n```\n\n## Auto Refresh — Initially Disabled\n\nAuto-refresh is configured but starts disabled via `initialState.autoRefreshEnabled: false`. The user can enable it manually via the toolbar toggle.\n\n```tsx\n// AutoRefreshInitiallyDisabledExample.tsx\nimport React from 'react';\nimport { RingDataGrid } from '@ringpublishing/mui-components';\nimport { storiesColumns, getInitialColumnVisibilityModel } from 'RingDataGridColumnsAndRows';\nimport { useRingDataGridDemoData } from 'RingDemoData';\n\nexport default function AutoRefreshInitiallyDisabledExample(): React.JSX.Element {\n const { items, loading, hasMore, nextData, totalCount, refresh } = useRingDataGridDemoData({\n initialCount: 40,\n });\n\n return (\n <div style={{ minWidth: '100%', width: '100%', padding: '20px', height: '600px' }}>\n <RingDataGrid\n autoRefresh={true}\n refreshRate={5000}\n userInteractionDebounceDelay={250}\n columnHeaderHeight={40}\n columns={storiesColumns}\n showRingToolbar={true}\n getRowHeight={(): 'auto' => 'auto'}\n labels={{\n results: 'Results',\n refresh: 'Refresh',\n enableAutoRefresh: 'Enable auto refresh',\n disableAutoRefresh: 'Disable auto refresh',\n }}\n disableColumnFilter={true}\n rows={items}\n totalRowCount={totalCount}\n onRowsScrollEnd={(): void => {\n if (hasMore) {\n nextData(30);\n }\n }}\n loading={loading}\n refreshItems={(): void => refresh()}\n initialState={{\n autoRefreshEnabled: false,\n columns: {\n columnVisibilityModel: getInitialColumnVisibilityModel(true),\n },\n }}\n />\n </div>\n );\n}\n```\n\n## Auto Refresh — Disabled\n\nNo auto-refresh configuration — the grid only refreshes on manual user action.\n\n```tsx\n// AutoRefreshDisabledExample.tsx\nimport React from 'react';\nimport { RingDataGrid } from '@ringpublishing/mui-components';\nimport { storiesColumns, getInitialColumnVisibilityModel } from 'RingDataGridColumnsAndRows';\nimport { useRingDataGridDemoData } from 'RingDemoData';\n\nexport default function AutoRefreshDisabledExample(): React.JSX.Element {\n const { items, loading, hasMore, nextData, totalCount, refresh } = useRingDataGridDemoData({\n initialCount: 40,\n });\n\n return (\n <div style={{ minWidth: '100%', width: '100%', padding: '20px', height: '600px' }}>\n <RingDataGrid\n columnHeaderHeight={40}\n columns={storiesColumns}\n showRingToolbar={true}\n getRowHeight={(): 'auto' => 'auto'}\n labels={{\n results: 'Results',\n refresh: 'Refresh',\n enableAutoRefresh: 'Enable auto refresh',\n disableAutoRefresh: 'Disable auto refresh',\n }}\n disableColumnFilter={true}\n rows={items}\n totalRowCount={totalCount}\n onRowsScrollEnd={(): void => {\n if (hasMore) {\n nextData(30);\n }\n }}\n loading={loading}\n refreshItems={(): void => refresh()}\n initialState={{\n columns: {\n columnVisibilityModel: getInitialColumnVisibilityModel(true),\n },\n }}\n />\n </div>\n );\n}\n```\n\n## Classic Selection\n\nCheckbox selection with `disableSelectAllCheckbox` set to `true`, removing the header checkbox. Uses a controlled `rowSelectionModel` with `clearSelectionOnRefresh` disabled.\n\n```tsx\n// ClassicSelectionExample.tsx\nimport React, { useState } from 'react';\nimport { GridRowSelectionModel } from '@mui/x-data-grid-pro';\nimport { RingDataGrid } from '@ringpublishing/mui-components';\nimport { dataGridRowsGenerator, columnsForDataGridRowsGenerator } from 'RingDataGridHelpers';\n\nexport default function ClassicSelectionExample(): React.JSX.Element {\n const rows = dataGridRowsGenerator(10, 0, false);\n const columns = columnsForDataGridRowsGenerator;\n\n const [selectedRows, setSelectedRows] = useState<GridRowSelectionModel>({\n type: 'include',\n ids: new Set([1, 2]),\n });\n\n return (\n <div style={{ minWidth: '100%', width: '100%', padding: '20px', height: '600px' }}>\n <RingDataGrid\n columnHeaderHeight={40}\n columns={columns}\n rows={rows}\n getRowHeight={(): 'auto' => 'auto'}\n labels={{\n results: 'Results',\n refresh: 'Refresh',\n enableAutoRefresh: 'Enable auto refresh',\n disableAutoRefresh: 'Disable auto refresh',\n }}\n totalRowCount={10}\n disableSelectAllCheckbox={true}\n checkboxSelection={true}\n rowSelectionModel={selectedRows}\n onRowSelectionModelChange={(newSelection): void => {\n setSelectedRows(newSelection);\n }}\n clearSelectionOnRefresh={false}\n />\n </div>\n );\n}\n```"
|
|
2112
|
-
},
|
|
2113
|
-
"organisms-data-tree": {
|
|
2114
|
-
"id": "organisms-data-tree",
|
|
2115
|
-
"name": "DataTree",
|
|
2116
|
-
"category": "Organisms",
|
|
2117
|
-
"title": "Components/Organisms/DataTree",
|
|
2118
|
-
"description": "A tree component that displays hierarchical data with support for columns, checkboxes, drag-and-drop, search, dynamic loading, and controlled selection.",
|
|
2119
|
-
"argTypes": {
|
|
2120
|
-
"sx": {
|
|
2121
|
-
"description": "MUI System properties.",
|
|
2122
|
-
"control": "object",
|
|
2123
|
-
"category": "customization",
|
|
2124
|
-
"type": "SxProps<Theme>",
|
|
2125
|
-
"defaultValue": "{}"
|
|
2126
|
-
},
|
|
2127
|
-
"className": {
|
|
2128
|
-
"description": "CSS class name.",
|
|
2129
|
-
"control": "text",
|
|
2130
|
-
"category": "customization",
|
|
2131
|
-
"type": "string"
|
|
2132
|
-
},
|
|
2133
|
-
"dataTestIdSuffix": {
|
|
2134
|
-
"description": "Suffix for data-testid.",
|
|
2135
|
-
"control": "text",
|
|
2136
|
-
"category": "testing",
|
|
2137
|
-
"type": "string"
|
|
2138
|
-
},
|
|
2139
|
-
"items": {
|
|
2140
|
-
"description": "Tree items to display.",
|
|
2141
|
-
"control": "object",
|
|
2142
|
-
"category": "content",
|
|
2143
|
-
"type": "DataTreeItem[]"
|
|
2144
|
-
},
|
|
2145
|
-
"columns": {
|
|
2146
|
-
"description": "Column definitions with name, width, and header.",
|
|
2147
|
-
"control": "object",
|
|
2148
|
-
"category": "content",
|
|
2149
|
-
"type": "DataTreeColumn[]"
|
|
2150
|
-
},
|
|
2151
|
-
"showColumnHeaders": {
|
|
2152
|
-
"description": "Show column headers row.",
|
|
2153
|
-
"control": "boolean",
|
|
2154
|
-
"category": "appearance",
|
|
2155
|
-
"type": "boolean",
|
|
2156
|
-
"defaultValue": "false"
|
|
2157
|
-
},
|
|
2158
|
-
"itemsLabelColumnHeader": {
|
|
2159
|
-
"description": "Header text for the label column.",
|
|
2160
|
-
"control": "text",
|
|
2161
|
-
"category": "content",
|
|
2162
|
-
"type": "string",
|
|
2163
|
-
"defaultValue": "''"
|
|
2164
|
-
},
|
|
2165
|
-
"withSearch": {
|
|
2166
|
-
"description": "Show search box.",
|
|
2167
|
-
"control": "boolean",
|
|
2168
|
-
"category": "behavior",
|
|
2169
|
-
"type": "boolean",
|
|
2170
|
-
"defaultValue": "false"
|
|
2171
|
-
},
|
|
2172
|
-
"searchDebounceTime": {
|
|
2173
|
-
"description": "Search debounce time (ms).",
|
|
2174
|
-
"control": "number",
|
|
2175
|
-
"category": "behavior",
|
|
2176
|
-
"type": "number",
|
|
2177
|
-
"defaultValue": "500"
|
|
2178
|
-
},
|
|
2179
|
-
"searchPlaceholder": {
|
|
2180
|
-
"description": "Search placeholder text.",
|
|
2181
|
-
"control": "text",
|
|
2182
|
-
"category": "content",
|
|
2183
|
-
"type": "string"
|
|
2184
|
-
},
|
|
2185
|
-
"selectedItems": {
|
|
2186
|
-
"description": "Controlled selected item IDs.",
|
|
2187
|
-
"control": "object",
|
|
2188
|
-
"category": "state",
|
|
2189
|
-
"type": "string[]"
|
|
2190
|
-
},
|
|
2191
|
-
"onSelectedItemsChange": {
|
|
2192
|
-
"description": "Selection change callback.",
|
|
2193
|
-
"control": false,
|
|
2194
|
-
"category": "callbacks",
|
|
2195
|
-
"type": "(itemIds: string[]) => void"
|
|
2196
|
-
},
|
|
2197
|
-
"onExpand": {
|
|
2198
|
-
"description": "Expand/collapse callback.",
|
|
2199
|
-
"control": false,
|
|
2200
|
-
"category": "callbacks",
|
|
2201
|
-
"type": "(itemId: string) => void"
|
|
2202
|
-
},
|
|
2203
|
-
"onClickRow": {
|
|
2204
|
-
"description": "Row click callback.",
|
|
2205
|
-
"control": false,
|
|
2206
|
-
"category": "callbacks",
|
|
2207
|
-
"type": "(itemId: string) => void"
|
|
2208
|
-
},
|
|
2209
|
-
"onCheckboxChange": {
|
|
2210
|
-
"description": "Checkbox change callback.",
|
|
2211
|
-
"control": false,
|
|
2212
|
-
"category": "callbacks",
|
|
2213
|
-
"type": "(itemId: string, checked: boolean) => void"
|
|
2214
|
-
},
|
|
2215
|
-
"onDragAndDropEnd": {
|
|
2216
|
-
"description": "Drag-and-drop end callback.",
|
|
2217
|
-
"control": false,
|
|
2218
|
-
"category": "callbacks",
|
|
2219
|
-
"type": "(sourcePos: number[], destPos: number[]) => void"
|
|
2220
|
-
},
|
|
2221
|
-
"onDropIn": {
|
|
2222
|
-
"description": "Drop-in callback.",
|
|
2223
|
-
"control": false,
|
|
2224
|
-
"category": "callbacks",
|
|
2225
|
-
"type": "(itemId: string, dropInItemId: string) => void"
|
|
2226
|
-
},
|
|
2227
|
-
"dragAndDropTooltipTitle": {
|
|
2228
|
-
"description": "Tooltip for expanded items during drag.",
|
|
2229
|
-
"control": "text",
|
|
2230
|
-
"category": "content",
|
|
2231
|
-
"type": "string"
|
|
2232
|
-
},
|
|
2233
|
-
"dragAndDropTooltipPlacement": {
|
|
2234
|
-
"description": "Tooltip placement.",
|
|
2235
|
-
"control": "select",
|
|
2236
|
-
"category": "appearance",
|
|
2237
|
-
"type": "PopperProps['placement']",
|
|
2238
|
-
"defaultValue": "'top'",
|
|
2239
|
-
"options": [
|
|
2240
|
-
"top",
|
|
2241
|
-
"bottom",
|
|
2242
|
-
"left",
|
|
2243
|
-
"right"
|
|
2244
|
-
]
|
|
2245
|
-
},
|
|
2246
|
-
"persistence": {
|
|
2247
|
-
"description": "Enable localStorage persistence. Provide `cacheKey` to cache dynamic items, `restoreExpandedItems` to restore expanded state, and `restoreSelectedItem` to restore the last selected item.",
|
|
2248
|
-
"control": "object",
|
|
2249
|
-
"category": "behavior",
|
|
2250
|
-
"type": "{ cacheKey: string; restoreExpandedItems?: boolean; restoreSelectedItem?: boolean }"
|
|
2251
|
-
},
|
|
2252
|
-
"queryClient": {
|
|
2253
|
-
"description": "Optional app `QueryClient` so tree queries use your cache / DevTools.",
|
|
2254
|
-
"control": false,
|
|
2255
|
-
"category": "behavior",
|
|
2256
|
-
"type": "QueryClient"
|
|
2257
|
-
}
|
|
2258
|
-
},
|
|
2259
|
-
"storyNames": [
|
|
2260
|
-
"Default",
|
|
2261
|
-
"WithSearch",
|
|
2262
|
-
"WithDragAndDrop",
|
|
2263
|
-
"WithDropIn",
|
|
2264
|
-
"WithDynamicLoading",
|
|
2265
|
-
"ControlledSelection",
|
|
2266
|
-
"WithPersistence",
|
|
2267
|
-
"WithExternalQueryClient"
|
|
2268
|
-
],
|
|
2269
|
-
"docs": "# DataTree\n\nA tree component that displays hierarchical data with support for columns, checkboxes, drag-and-drop, search, dynamic loading, and controlled selection.\n\n- Renders nested tree items with expand/collapse behavior\n- Supports additional columns alongside the item label\n- Checkbox selection with per-item control (enable, disable, hide)\n- Drag-and-drop reordering and drop-in nesting via callbacks\n- Built-in search with debounce and label highlighting\n- Dynamic child loading powered by TanStack Query\n- Controlled or uncontrolled item selection\n- localStorage persistence for dynamic items and last selection\n\n## Optional peer dependency\n\n`@tanstack/react-query` (v4 or v5) is declared as an **optional** peer dependency. You only need to install it if you use `loadItems` on any tree item to fetch children dynamically:\n\n```bash\n# Only required if your tree uses loadItems\nnpm install @tanstack/react-query\n```\n\nIf your tree is fully static (`items` is the only source of children, no `loadItems`), you do **not** need to install `@tanstack/react-query` — the component will work without it. When dynamic loading is in use, the component manages its own internal `QueryClient` and `QueryClientProvider`, so you do not need to set up a provider in your app.\n\nIf your app already runs TanStack Query, you can pass your existing client through the `queryClient` prop instead of letting the tree create its own — see [With External QueryClient](#with-external-queryclient). This keeps tree queries visible in React Query DevTools, lets you invalidate / prefetch them programmatically, and shares cache policies (retry, staleTime, error handlers) with the rest of your app.\n\n## Default\n\nBasic tree with columns, checkboxes, and row actions. Items can be expanded/collapsed and checked individually.\n\n```tsx\n// DefaultExample.tsx\nimport React, { useState } from 'react';\nimport { DataTree, DataTreeItem } from '@ringpublishing/mui-components';\nimport { EditOutlined } from '@mui/icons-material';\n\nconst exampleItems: DataTreeItem[] = [\n {\n itemId: '0',\n label: 'Item 0',\n column1: 'Column1 0',\n column2: 'Column2 0',\n expanded: true,\n rowActions: [{ label: 'Edit', icon: <EditOutlined /> }],\n checkboxDisabled: true,\n items: [\n {\n itemId: '0.0',\n label: 'Item 0.0',\n column1: 'Column1 0.0',\n column2: 'Column2 0.0',\n checked: true,\n },\n {\n itemId: '0.1',\n label: 'Item 0.1',\n column1: 'Column1 0.1',\n column2: 'Column2 0.1',\n checked: true,\n items: [\n {\n itemId: '0.1.0',\n label: 'Item 0.1.0',\n column1: 'Column1 0.1.0',\n column2: 'Column2 0.1.0',\n },\n {\n itemId: '0.1.1',\n label: 'Item 0.1.1',\n column1: 'Column1 0.1.1',\n column2: 'Column2 0.1.1',\n },\n ],\n },\n {\n itemId: '0.2',\n label: 'Item 0.2',\n column1: 'Column1 0.2',\n column2: 'Column2 0.2',\n withCheckbox: false,\n },\n {\n itemId: '0.3',\n label: 'Item 0.3',\n column1: 'Column1 0.3',\n column2: 'Column2 0.3',\n withCheckbox: false,\n },\n ],\n },\n {\n itemId: '1',\n label: 'Item 1',\n column1: 'Column1 1',\n column2: 'Column2 1',\n rowActions: [{ label: 'Edit', icon: <EditOutlined /> }],\n items: [\n {\n itemId: '1.0',\n label: 'Item 1.0',\n column1: 'Column1 1.0',\n column2: 'Column2 1.0',\n },\n {\n itemId: '1.1',\n label: 'Item 1.1',\n column1: 'Column1 1.1',\n column2: 'Column2 1.1',\n },\n ],\n },\n {\n itemId: '2',\n label: 'Item 2',\n column1: 'Column1 2',\n column2: 'Column2 2',\n items: [\n {\n itemId: '2.0',\n label: 'Item 2.0',\n column1: 'Column1 2.0',\n column2: 'Column2 2.0',\n },\n {\n itemId: '2.1',\n label: 'Item 2.1',\n column1: 'Column1 2.1',\n column2: 'Column2 2.1',\n },\n ],\n },\n {\n itemId: '3',\n label: 'Item 3',\n column1: 'Column1 3',\n column2: 'Column2 3',\n rowActions: [{ label: 'Edit', icon: <EditOutlined /> }],\n checked: true,\n },\n];\n\nfunction checkItem(items: DataTreeItem[], itemId: string, checked: boolean): DataTreeItem[] {\n const newItems: DataTreeItem[] = [];\n\n items.forEach((item) => {\n if (item.itemId === itemId) {\n newItems.push({ ...item, checked });\n } else if (item.items) {\n newItems.push({ ...item, items: checkItem(item.items, itemId, checked) });\n } else {\n newItems.push(item);\n }\n });\n\n return newItems;\n}\n\nexport default function DefaultExample(): React.JSX.Element {\n const [items, setItems] = useState(exampleItems);\n\n return (\n <DataTree\n items={items}\n onExpand={(itemId) => console.log('Expanded:', itemId)}\n onClickRow={(itemId) => console.log('Clicked:', itemId)}\n showColumnHeaders={true}\n itemsLabelColumnHeader={'Name'}\n columns={[\n { name: 'column1', width: 100, header: 'First Column' },\n { name: 'column2', width: 100, header: 'Second Column' },\n ]}\n onCheckboxChange={(itemId, checked) => {\n setItems(checkItem(items, itemId, checked));\n }}\n />\n );\n}\n```\n\n## With Search\n\nEnables the built-in search box. The tree filters items by label as you type, with configurable debounce.\n\n```tsx\n// WithSearchExample.tsx\nimport React, { useState } from 'react';\nimport { DataTree, DataTreeItem } from '@ringpublishing/mui-components';\nimport { EditOutlined } from '@mui/icons-material';\n\nconst exampleItems: DataTreeItem[] = [\n {\n itemId: '0',\n label: 'Item 0',\n column1: 'Column1 0',\n column2: 'Column2 0',\n expanded: true,\n rowActions: [{ label: 'Edit', icon: <EditOutlined /> }],\n items: [\n {\n itemId: '0.0',\n label: 'Item 0.0',\n column1: 'Column1 0.0',\n column2: 'Column2 0.0',\n },\n {\n itemId: '0.1',\n label: 'Item 0.1',\n column1: 'Column1 0.1',\n column2: 'Column2 0.1',\n items: [\n {\n itemId: '0.1.0',\n label: 'Item 0.1.0',\n column1: 'Column1 0.1.0',\n column2: 'Column2 0.1.0',\n },\n {\n itemId: '0.1.1',\n label: 'Item 0.1.1',\n column1: 'Column1 0.1.1',\n column2: 'Column2 0.1.1',\n },\n ],\n },\n {\n itemId: '0.2',\n label: 'Item 0.2',\n column1: 'Column1 0.2',\n column2: 'Column2 0.2',\n },\n {\n itemId: '0.3',\n label: 'Item 0.3',\n column1: 'Column1 0.3',\n column2: 'Column2 0.3',\n },\n ],\n },\n {\n itemId: '1',\n label: 'Item 1',\n column1: 'Column1 1',\n column2: 'Column2 1',\n rowActions: [{ label: 'Edit', icon: <EditOutlined /> }],\n items: [\n {\n itemId: '1.0',\n label: 'Item 1.0',\n column1: 'Column1 1.0',\n column2: 'Column2 1.0',\n },\n {\n itemId: '1.1',\n label: 'Item 1.1',\n column1: 'Column1 1.1',\n column2: 'Column2 1.1',\n },\n ],\n },\n {\n itemId: '2',\n label: 'Item 2',\n column1: 'Column1 2',\n column2: 'Column2 2',\n items: [\n {\n itemId: '2.0',\n label: 'Item 2.0',\n column1: 'Column1 2.0',\n column2: 'Column2 2.0',\n },\n {\n itemId: '2.1',\n label: 'Item 2.1',\n column1: 'Column1 2.1',\n column2: 'Column2 2.1',\n },\n ],\n },\n {\n itemId: '3',\n label: 'Item 3',\n column1: 'Column1 3',\n column2: 'Column2 3',\n rowActions: [{ label: 'Edit', icon: <EditOutlined /> }],\n },\n];\n\nexport default function WithSearchExample(): React.JSX.Element {\n const [items] = useState(exampleItems);\n\n return (\n <DataTree\n items={items}\n onExpand={(itemId) => console.log('Expanded:', itemId)}\n onClickRow={(itemId) => console.log('Clicked:', itemId)}\n withSearch={true}\n searchPlaceholder=\"Search items...\"\n showColumnHeaders={true}\n itemsLabelColumnHeader={'Name'}\n columns={[\n { name: 'column1', width: 100, header: 'First Column' },\n { name: 'column2', width: 100, header: 'Second Column' },\n ]}\n />\n );\n}\n```\n\n## With Drag and Drop\n\nProvides the `onDragAndDropEnd` callback to enable drag-and-drop reordering. Items can be moved within and across nesting levels. A tooltip warns users to collapse expanded items before dragging.\n\n```tsx\n// WithDragAndDropExample.tsx\nimport React, { useState } from 'react';\nimport { DataTree, DataTreeItem } from '@ringpublishing/mui-components';\nimport { EditOutlined } from '@mui/icons-material';\n\nconst exampleItems: DataTreeItem[] = [\n {\n itemId: '0',\n label: 'Item 0',\n column1: 'Column1 0',\n column2: 'Column2 0',\n expanded: true,\n rowActions: [{ label: 'Edit', icon: <EditOutlined /> }],\n checkboxDisabled: true,\n items: [\n {\n itemId: '0.0',\n label: 'Item 0.0',\n column1: 'Column1 0.0',\n column2: 'Column2 0.0',\n checked: true,\n },\n {\n itemId: '0.1',\n label: 'Item 0.1',\n column1: 'Column1 0.1',\n column2: 'Column2 0.1',\n checked: true,\n items: [\n {\n itemId: '0.1.0',\n label: 'Item 0.1.0',\n column1: 'Column1 0.1.0',\n column2: 'Column2 0.1.0',\n },\n {\n itemId: '0.1.1',\n label: 'Item 0.1.1',\n column1: 'Column1 0.1.1',\n column2: 'Column2 0.1.1',\n },\n ],\n },\n {\n itemId: '0.2',\n label: 'Item 0.2',\n column1: 'Column1 0.2',\n column2: 'Column2 0.2',\n withCheckbox: false,\n },\n {\n itemId: '0.3',\n label: 'Item 0.3',\n column1: 'Column1 0.3',\n column2: 'Column2 0.3',\n withCheckbox: false,\n },\n ],\n },\n {\n itemId: '1',\n label: 'Item 1',\n column1: 'Column1 1',\n column2: 'Column2 1',\n rowActions: [{ label: 'Edit', icon: <EditOutlined /> }],\n items: [\n {\n itemId: '1.0',\n label: 'Item 1.0',\n column1: 'Column1 1.0',\n column2: 'Column2 1.0',\n },\n {\n itemId: '1.1',\n label: 'Item 1.1',\n column1: 'Column1 1.1',\n column2: 'Column2 1.1',\n },\n ],\n },\n {\n itemId: '2',\n label: 'Item 2',\n column1: 'Column1 2',\n column2: 'Column2 2',\n items: [\n {\n itemId: '2.0',\n label: 'Item 2.0',\n column1: 'Column1 2.0',\n column2: 'Column2 2.0',\n },\n {\n itemId: '2.1',\n label: 'Item 2.1',\n column1: 'Column1 2.1',\n column2: 'Column2 2.1',\n },\n ],\n },\n {\n itemId: '3',\n label: 'Item 3',\n column1: 'Column1 3',\n column2: 'Column2 3',\n rowActions: [{ label: 'Edit', icon: <EditOutlined /> }],\n checked: true,\n },\n];\n\nfunction moveItems(\n items: DataTreeItem[],\n sourceAbsolutePosition: number[],\n destinationAbsolutePosition: number[],\n): DataTreeItem[] {\n const newItems = [...items];\n\n function getArrayAndIndex(path: number[]): { array: DataTreeItem[] | undefined; index: number } {\n let array: DataTreeItem[] | undefined = newItems;\n let index = path[0];\n\n for (let i = 0; i < path.length - 1; i++) {\n const currentIndex = path[i];\n\n if (!array?.[currentIndex]?.items) {\n return { array: undefined, index: -1 };\n }\n\n array = array[currentIndex].items;\n index = path[i + 1];\n }\n\n return { array, index };\n }\n\n const { array: sourceArray, index: sourceIndex } = getArrayAndIndex(sourceAbsolutePosition);\n const { array: destinationArray, index: destinationIndex } = getArrayAndIndex(destinationAbsolutePosition);\n\n if (!sourceArray || sourceIndex === -1 || !sourceArray[sourceIndex]) {\n throw new Error('Invalid source position');\n }\n\n const [movedItem] = sourceArray.splice(sourceIndex, 1);\n\n if (!destinationArray) {\n throw new Error('Invalid destination position');\n }\n\n destinationArray.splice(destinationIndex, 0, movedItem);\n\n return newItems;\n}\n\nfunction checkItem(items: DataTreeItem[], itemId: string, checked: boolean): DataTreeItem[] {\n const newItems: DataTreeItem[] = [];\n\n items.forEach((item) => {\n if (item.itemId === itemId) {\n newItems.push({ ...item, checked });\n } else if (item.items) {\n newItems.push({ ...item, items: checkItem(item.items, itemId, checked) });\n } else {\n newItems.push(item);\n }\n });\n\n return newItems;\n}\n\nexport default function WithDragAndDropExample(): React.JSX.Element {\n const [items, setItems] = useState(exampleItems);\n\n return (\n <DataTree\n items={items}\n onDragAndDropEnd={(sourceAbsolutePosition, destinationAbsolutePosition) => {\n setItems((prevItems) => moveItems(prevItems, sourceAbsolutePosition, destinationAbsolutePosition));\n }}\n showColumnHeaders={true}\n itemsLabelColumnHeader={'Name'}\n columns={[\n { name: 'column1', width: 100, header: 'First Column' },\n { name: 'column2', width: 100, header: 'Second Column' },\n ]}\n dragAndDropTooltipTitle={'To drag and drop collapse the item first'}\n onCheckboxChange={(itemId, checked) => {\n setItems(checkItem(items, itemId, checked));\n }}\n />\n );\n}\n```\n\n## With Drop In\n\nExtends drag-and-drop with the `onDropIn` callback, allowing items to be dropped inside other items to create new parent-child relationships.\n\n```tsx\n// WithDropInExample.tsx\nimport React, { useState } from 'react';\nimport { DataTree, DataTreeItem } from '@ringpublishing/mui-components';\nimport { EditOutlined } from '@mui/icons-material';\n\nconst exampleItems: DataTreeItem[] = [\n {\n itemId: '0',\n label: 'Item 0',\n column1: 'Column1 0',\n column2: 'Column2 0',\n expanded: true,\n rowActions: [{ label: 'Edit', icon: <EditOutlined /> }],\n checkboxDisabled: true,\n items: [\n {\n itemId: '0.0',\n label: 'Item 0.0',\n column1: 'Column1 0.0',\n column2: 'Column2 0.0',\n checked: true,\n },\n {\n itemId: '0.1',\n label: 'Item 0.1',\n column1: 'Column1 0.1',\n column2: 'Column2 0.1',\n checked: true,\n items: [\n {\n itemId: '0.1.0',\n label: 'Item 0.1.0',\n column1: 'Column1 0.1.0',\n column2: 'Column2 0.1.0',\n },\n {\n itemId: '0.1.1',\n label: 'Item 0.1.1',\n column1: 'Column1 0.1.1',\n column2: 'Column2 0.1.1',\n },\n ],\n },\n {\n itemId: '0.2',\n label: 'Item 0.2',\n column1: 'Column1 0.2',\n column2: 'Column2 0.2',\n withCheckbox: false,\n },\n {\n itemId: '0.3',\n label: 'Item 0.3',\n column1: 'Column1 0.3',\n column2: 'Column2 0.3',\n withCheckbox: false,\n },\n ],\n },\n {\n itemId: '1',\n label: 'Item 1',\n column1: 'Column1 1',\n column2: 'Column2 1',\n rowActions: [{ label: 'Edit', icon: <EditOutlined /> }],\n items: [\n {\n itemId: '1.0',\n label: 'Item 1.0',\n column1: 'Column1 1.0',\n column2: 'Column2 1.0',\n },\n {\n itemId: '1.1',\n label: 'Item 1.1',\n column1: 'Column1 1.1',\n column2: 'Column2 1.1',\n },\n ],\n },\n {\n itemId: '2',\n label: 'Item 2',\n column1: 'Column1 2',\n column2: 'Column2 2',\n items: [\n {\n itemId: '2.0',\n label: 'Item 2.0',\n column1: 'Column1 2.0',\n column2: 'Column2 2.0',\n },\n {\n itemId: '2.1',\n label: 'Item 2.1',\n column1: 'Column1 2.1',\n column2: 'Column2 2.1',\n },\n ],\n },\n {\n itemId: '3',\n label: 'Item 3',\n column1: 'Column1 3',\n column2: 'Column2 3',\n rowActions: [{ label: 'Edit', icon: <EditOutlined /> }],\n checked: true,\n },\n];\n\nfunction moveItems(\n items: DataTreeItem[],\n sourceAbsolutePosition: number[],\n destinationAbsolutePosition: number[],\n): DataTreeItem[] {\n const newItems = [...items];\n\n function getArrayAndIndex(path: number[]): { array: DataTreeItem[] | undefined; index: number } {\n let array: DataTreeItem[] | undefined = newItems;\n let index = path[0];\n\n for (let i = 0; i < path.length - 1; i++) {\n const currentIndex = path[i];\n\n if (!array?.[currentIndex]?.items) {\n return { array: undefined, index: -1 };\n }\n\n array = array[currentIndex].items;\n index = path[i + 1];\n }\n\n return { array, index };\n }\n\n const { array: sourceArray, index: sourceIndex } = getArrayAndIndex(sourceAbsolutePosition);\n const { array: destinationArray, index: destinationIndex } = getArrayAndIndex(destinationAbsolutePosition);\n\n if (!sourceArray || sourceIndex === -1 || !sourceArray[sourceIndex]) {\n throw new Error('Invalid source position');\n }\n\n const [movedItem] = sourceArray.splice(sourceIndex, 1);\n\n if (!destinationArray) {\n throw new Error('Invalid destination position');\n }\n\n destinationArray.splice(destinationIndex, 0, movedItem);\n\n return newItems;\n}\n\nfunction dropInItem(items: DataTreeItem[], itemId: string, dropInItemId: string): DataTreeItem[] {\n let movedItem: DataTreeItem | null = null;\n\n function removeItem(arr: DataTreeItem[]): DataTreeItem[] {\n return arr.reduce<DataTreeItem[]>((acc, item) => {\n if (item.itemId === itemId) {\n movedItem = item;\n\n return acc;\n }\n\n if (item.items) {\n acc.push({ ...item, items: removeItem(item.items) });\n } else {\n acc.push(item);\n }\n\n return acc;\n }, []);\n }\n\n function insertItem(arr: DataTreeItem[]): DataTreeItem[] {\n return arr.map((item) => {\n if (item.itemId === dropInItemId) {\n const children = item.items ? [...item.items] : [];\n\n if (movedItem) {\n children.push({ ...movedItem, items: movedItem.items ?? undefined });\n }\n\n return { ...item, items: children };\n }\n\n if (item.items) {\n return { ...item, items: insertItem(item.items) };\n }\n\n return item;\n });\n }\n\n const withoutItem = removeItem(items);\n\n if (!movedItem) {\n return items;\n }\n\n return insertItem(withoutItem);\n}\n\nfunction checkItem(items: DataTreeItem[], itemId: string, checked: boolean): DataTreeItem[] {\n const newItems: DataTreeItem[] = [];\n\n items.forEach((item) => {\n if (item.itemId === itemId) {\n newItems.push({ ...item, checked });\n } else if (item.items) {\n newItems.push({ ...item, items: checkItem(item.items, itemId, checked) });\n } else {\n newItems.push(item);\n }\n });\n\n return newItems;\n}\n\nexport default function WithDropInExample(): React.JSX.Element {\n const [items, setItems] = useState(exampleItems);\n\n return (\n <DataTree\n items={items}\n onDragAndDropEnd={(sourceAbsolutePosition, destinationAbsolutePosition) => {\n setItems((prevItems) => moveItems(prevItems, sourceAbsolutePosition, destinationAbsolutePosition));\n }}\n onDropIn={(itemId, dropInItemId) => {\n setItems((prevItems) => dropInItem(prevItems, itemId, dropInItemId));\n }}\n showColumnHeaders={true}\n itemsLabelColumnHeader={'Name'}\n columns={[\n { name: 'column1', width: 100, header: 'First Column' },\n { name: 'column2', width: 100, header: 'Second Column' },\n ]}\n dragAndDropTooltipTitle={'To drag and drop collapse the item first'}\n onCheckboxChange={(itemId, checked) => {\n setItems(checkItem(items, itemId, checked));\n }}\n />\n );\n}\n```\n\n## With Dynamic Loading\n\n**Requires `@tanstack/react-query`** (v4 or v5) — this story, and any tree that uses `loadItems`, will fail to render if the package is not installed (`npm install @tanstack/react-query`).\n\nUses `loadItems` on tree items to fetch children asynchronously when expanded. Powered by TanStack Query — the component manages its own `QueryClient` internally.\n\n```tsx\n// WithDynamicLoadingExample.tsx\nimport React from 'react';\nimport { DataTree, DataTreeItem } from '@ringpublishing/mui-components';\n\ntype FsNode = { label: string; ext: string } & ({ type: 'folder'; children: string[] } | { type: 'file' });\n\nconst filesystem: Record<string, FsNode> = {\n documents: { label: 'Documents', type: 'folder', children: ['reports', 'templates'], ext: '—' },\n reports: { label: 'Reports', type: 'folder', children: ['q1', 'q2', 'q3'], ext: '—' },\n templates: { label: 'Templates', type: 'folder', children: ['invoice', 'contract'], ext: '—' },\n projects: { label: 'Projects', type: 'folder', children: ['alpha', 'beta'], ext: '—' },\n alpha: { label: 'Alpha', type: 'folder', children: ['src', 'alpha-readme'], ext: '—' },\n beta: { label: 'Beta', type: 'folder', children: ['beta-main', 'beta-config'], ext: '—' },\n src: { label: 'src', type: 'folder', children: ['index', 'utils'], ext: '—' },\n archives: { label: 'Archives', type: 'folder', children: ['y2023', 'y2024'], ext: '—' },\n y2023: { label: '2023', type: 'folder', children: ['backup2023', 'data2023'], ext: '—' },\n y2024: { label: '2024', type: 'folder', children: ['backup2024', 'data2024'], ext: '—' },\n q1: { label: 'Q1 Report.pdf', type: 'file', ext: '.pdf' },\n q2: { label: 'Q2 Report.pdf', type: 'file', ext: '.pdf' },\n q3: { label: 'Q3 Report.pdf', type: 'file', ext: '.pdf' },\n invoice: { label: 'Invoice.docx', type: 'file', ext: '.docx' },\n contract: { label: 'Contract.docx', type: 'file', ext: '.docx' },\n 'alpha-readme': { label: 'README.md', type: 'file', ext: '.md' },\n 'beta-main': { label: 'main.py', type: 'file', ext: '.py' },\n 'beta-config': { label: 'config.yml', type: 'file', ext: '.yml' },\n index: { label: 'index.ts', type: 'file', ext: '.ts' },\n utils: { label: 'utils.ts', type: 'file', ext: '.ts' },\n backup2023: { label: 'backup.zip', type: 'file', ext: '.zip' },\n data2023: { label: 'data.csv', type: 'file', ext: '.csv' },\n backup2024: { label: 'backup.zip', type: 'file', ext: '.zip' },\n data2024: { label: 'data.csv', type: 'file', ext: '.csv' },\n};\n\nconst loadItems = async (item: DataTreeItem): Promise<DataTreeItem[]> => {\n await new Promise((r) => setTimeout(r, 600));\n const node = filesystem[item.itemId];\n if (!node || node.type !== 'folder') return [];\n return node.children.map((childId) => {\n const child = filesystem[childId];\n return {\n itemId: childId,\n label: child.label,\n column1: child.type === 'folder' ? 'Folder' : 'File',\n column2: child.ext,\n ...(child.type === 'folder' ? { loadItems } : {}),\n };\n });\n};\n\nconst items: DataTreeItem[] = [\n {\n itemId: 'root',\n label: 'Root',\n column1: 'Folder',\n column2: '—',\n items: [\n { itemId: 'documents', label: 'Documents', column1: 'Folder', column2: '—', loadItems },\n { itemId: 'projects', label: 'Projects', column1: 'Folder', column2: '—', loadItems },\n { itemId: 'archives', label: 'Archives', column1: 'Folder', column2: '—', loadItems },\n ],\n },\n];\n\nexport default function WithDynamicLoadingExample(): React.JSX.Element {\n return (\n <DataTree\n items={items}\n withSearch\n searchPlaceholder=\"Search...\"\n showColumnHeaders\n itemsLabelColumnHeader=\"Name\"\n columns={[\n { name: 'column1', width: 100, header: 'Type' },\n { name: 'column2', width: 100, header: 'Extension' },\n ]}\n onExpand={(itemId) => console.log('Expanded:', itemId)}\n onClickRow={(itemId) => console.log('Clicked:', itemId)}\n />\n );\n}\n```\n\n## With External QueryClient\n\n**Requires `@tanstack/react-query`** (v4 or v5).\n\nPass an external `QueryClient` via the `queryClient` prop to share the cache with the rest of your app, inspect tree queries in React Query DevTools, or apply custom retry / staleTime / error handlers globally. Combine with `queryKeyPrefix` when multiple tree instances on the same page share a single client to avoid query-key collisions.\n\n```tsx\n// WithExternalQueryClientExample.tsx\nimport React, { useState } from 'react';\nimport { QueryClient } from '@tanstack/react-query';\nimport { DataTree, DataTreeItem } from '@ringpublishing/mui-components';\n\nconst items: DataTreeItem[] = [\n {\n itemId: 'root',\n label: 'Root',\n column1: 'A',\n column2: 'B',\n items: [\n {\n itemId: 'lazy',\n label: 'Loads children on expand',\n column1: 'A',\n column2: 'B',\n loadItems: async (): Promise<DataTreeItem[]> => {\n await new Promise((r) => setTimeout(r, 400));\n\n return [{ itemId: 'child-1', label: 'Loaded child', column1: 'A', column2: 'B' }];\n },\n },\n ],\n },\n];\n\nexport default function WithExternalQueryClientExample(): React.JSX.Element {\n const [queryClient] = useState(\n () =>\n new QueryClient({\n defaultOptions: { queries: { staleTime: Infinity, retry: false } },\n }),\n );\n\n return (\n <DataTree\n items={items}\n queryClient={queryClient}\n columns={[\n { name: 'column1', width: 120, header: 'Col 1' },\n { name: 'column2', width: 120, header: 'Col 2' },\n ]}\n showColumnHeaders\n itemsLabelColumnHeader=\"Name\"\n />\n );\n}\n```\n\n## Controlled Selection\n\nDemonstrates controlled selection via `selectedItems` and `onSelectedItemsChange`. External buttons programmatically change which items are selected.\n\n```tsx\n// ControlledSelectionExample.tsx\nimport React, { useState } from 'react';\nimport { Box } from '@mui/material';\nimport { DataTree, DataTreeItem } from '@ringpublishing/mui-components';\n\nconst items: DataTreeItem[] = [\n {\n itemId: '0',\n label: 'Item 0',\n column1: 'Column1 0',\n column2: 'Column2 0',\n expanded: true,\n items: [\n {\n itemId: '0.0',\n label: 'Item 0.0',\n column1: 'Column1 0.0',\n column2: 'Column2 0.0',\n },\n {\n itemId: '0.1',\n label: 'Item 0.1',\n column1: 'Column1 0.1',\n column2: 'Column2 0.1',\n items: [\n {\n itemId: '0.1.0',\n label: 'Item 0.1.0',\n column1: 'Column1 0.1.0',\n column2: 'Column2 0.1.0',\n },\n {\n itemId: '0.1.1',\n label: 'Item 0.1.1',\n column1: 'Column1 0.1.1',\n column2: 'Column2 0.1.1',\n },\n ],\n },\n {\n itemId: '0.2',\n label: 'Item 0.2',\n column1: 'Column1 0.2',\n column2: 'Column2 0.2',\n },\n ],\n },\n {\n itemId: '1',\n label: 'Item 1',\n column1: 'Column1 1',\n column2: 'Column2 1',\n items: [\n {\n itemId: '1.0',\n label: 'Item 1.0',\n column1: 'Column1 1.0',\n column2: 'Column2 1.0',\n },\n {\n itemId: '1.1',\n label: 'Item 1.1',\n column1: 'Column1 1.1',\n column2: 'Column2 1.1',\n },\n ],\n },\n {\n itemId: '2',\n label: 'Item 2',\n column1: 'Column1 2',\n column2: 'Column2 2',\n items: [\n {\n itemId: '2.0',\n label: 'Item 2.0',\n column1: 'Column1 2.0',\n column2: 'Column2 2.0',\n },\n {\n itemId: '2.1',\n label: 'Item 2.1',\n column1: 'Column1 2.1',\n column2: 'Column2 2.1',\n },\n ],\n },\n {\n itemId: '3',\n label: 'Item 3',\n column1: 'Column1 3',\n column2: 'Column2 3',\n },\n];\n\nexport default function ControlledSelectionExample(): React.JSX.Element {\n const [selectedItems, setSelectedItems] = useState<string[]>([]);\n\n return (\n <Box>\n <Box sx={{ mb: 2, display: 'flex', gap: 1 }}>\n <button onClick={() => setSelectedItems([])}>Unselect All</button>\n <button onClick={() => setSelectedItems(['0.0', '0.1', '0.2', '0.1.0', '1.0', '1.1', '2.0', '2.1'])}>\n Select Nested Items\n </button>\n <button onClick={() => setSelectedItems(['0', '1', '2', '3'])}>Select Parent Items</button>\n </Box>\n <Box sx={{ mb: 2 }}>\n <strong>Selected Items:</strong> {selectedItems.length > 0 ? selectedItems.join(', ') : 'None'}\n </Box>\n <DataTree\n items={items}\n columns={[\n { name: 'column1', width: 100, header: 'First Column' },\n { name: 'column2', width: 100, header: 'Second Column' },\n ]}\n showColumnHeaders={true}\n itemsLabelColumnHeader={'Name'}\n selectedItems={selectedItems}\n onSelectedItemsChange={(itemIds) => setSelectedItems(itemIds)}\n onClickRow={(itemId) => console.log('Row clicked:', itemId)}\n />\n </Box>\n );\n}\n```\n\n## With Persistence\n\nThe cache-key half of persistence (caching of dynamically-loaded items) only does work when `loadItems` is used and therefore requires `@tanstack/react-query`. The `restoreExpandedItems` / `restoreSelectedItem` flags work without it.\n\nPass a `persistence` object with a `cacheKey` to enable localStorage caching of dynamically loaded items. Use `restoreExpandedItems` and `restoreSelectedItem` to restore the tree state across page reloads.\n\n```tsx\n<DataTree\n items={items}\n persistence={{\n cacheKey: 'my-data-tree',\n restoreExpandedItems: true,\n restoreSelectedItem: true,\n }}\n/>\n```\n\n- **`cacheKey`** (required): Unique key used to namespace the localStorage entries. Use different keys for different tree instances.\n- **`restoreExpandedItems`** (optional): When `true`, the expanded items are persisted and restored on mount.\n- **`restoreSelectedItem`** (optional): When `true`, the selected item(s) are persisted and restored on mount. Only applies in uncontrolled mode (when `selectedItems` prop is not provided).\n\n```tsx\n// WithPersistenceExample.tsx\nimport React from 'react';\nimport { DataTree, DataTreeItem } from '@ringpublishing/mui-components';\n\nconst dynamicItems: DataTreeItem[] = [\n {\n itemId: 'mixed-content',\n label: 'Mixed: Static + Dynamic Children',\n column1: 'Static',\n column2: 'Parent',\n items: [\n {\n itemId: 'static-folder',\n label: 'Static Folder',\n column1: 'Static',\n column2: 'Folder',\n items: [\n { itemId: 'static-file1', label: 'Static File 1.txt', column1: 'Static', column2: 'File' },\n { itemId: 'static-file2', label: 'Static File 2.txt', column1: 'Static', column2: 'File' },\n ],\n },\n {\n itemId: 'dynamic-folder',\n label: 'Dynamic Folder (click to load)',\n column1: 'Dynamic',\n column2: 'Folder',\n loadItems: async (parent): Promise<DataTreeItem[]> => {\n await new Promise((resolve) => setTimeout(resolve, 1000));\n return [\n {\n itemId: `${parent.itemId}-loaded-1`,\n label: 'Loaded Report A',\n column1: 'Dynamic',\n column2: 'Loaded',\n },\n {\n itemId: `${parent.itemId}-loaded-2`,\n label: 'Loaded Report B',\n column1: 'Dynamic',\n column2: 'Loaded',\n },\n {\n itemId: `${parent.itemId}-loaded-3`,\n label: 'Loaded Report C',\n column1: 'Dynamic',\n column2: 'Loaded',\n },\n ];\n },\n },\n ],\n },\n];\n\nexport default function WithPersistenceExample(): React.JSX.Element {\n return (\n <DataTree\n items={dynamicItems}\n withSearch={true}\n searchPlaceholder=\"Search dynamic items...\"\n showColumnHeaders={true}\n itemsLabelColumnHeader={'Name'}\n columns={[\n { name: 'column1', width: 100, header: 'First Column' },\n { name: 'column2', width: 100, header: 'Second Column' },\n ]}\n persistence={{ cacheKey: 'data-tree-demo', restoreExpandedItems: true, restoreSelectedItem: true }}\n onExpand={(itemId) => console.log('Expanded:', itemId)}\n onClickRow={(itemId) => console.log('Clicked:', itemId)}\n />\n );\n}\n```"
|
|
2270
|
-
},
|
|
2271
|
-
"organisms-detail": {
|
|
2272
|
-
"id": "organisms-detail",
|
|
2273
|
-
"name": "Detail",
|
|
2274
|
-
"category": "Organisms",
|
|
2275
|
-
"title": "Components/Organisms/Detail",
|
|
2276
|
-
"description": "A rich detail panel component for displaying item information with media, sections, editable fields, and action buttons. Commonly used as a side panel in DataView.",
|
|
2277
|
-
"argTypes": {
|
|
2278
|
-
"sx": {
|
|
2279
|
-
"description": "MUI System properties to customize the main element style.",
|
|
2280
|
-
"control": "object",
|
|
2281
|
-
"category": "customization",
|
|
2282
|
-
"type": "SxProps<Theme>"
|
|
2283
|
-
},
|
|
2284
|
-
"className": {
|
|
2285
|
-
"description": "CSS class name applied to the main element.",
|
|
2286
|
-
"control": "text",
|
|
2287
|
-
"category": "customization",
|
|
2288
|
-
"type": "string"
|
|
2289
|
-
},
|
|
2290
|
-
"main": {
|
|
2291
|
-
"description": "Main section of the detail — contains title, Media props and bottom icons. Bottom icons can be either all of type \"chip\" or all of type \"icon\".",
|
|
2292
|
-
"control": "object",
|
|
2293
|
-
"category": "content",
|
|
2294
|
-
"type": "{ mediaProps?: DetailMediaProps; title?: string | { value: string } | TitleEditable; onCloseClick?: () => void }"
|
|
2295
|
-
},
|
|
2296
|
-
"descriptionItems": {
|
|
2297
|
-
"description": "Description items section of the detail — fields in four types: default, chips, description, and editable.",
|
|
2298
|
-
"control": "object",
|
|
2299
|
-
"category": "content",
|
|
2300
|
-
"type": "DetailDescriptionItem[]"
|
|
2301
|
-
},
|
|
2302
|
-
"bottomActions": {
|
|
2303
|
-
"description": "Bottom actions section of the detail — actions with url or onClick handler.",
|
|
2304
|
-
"control": "object",
|
|
2305
|
-
"category": "content",
|
|
2306
|
-
"type": "DetailBottomAction[]"
|
|
2307
|
-
},
|
|
2308
|
-
"empty": {
|
|
2309
|
-
"description": "If true, shows a placeholder for the empty state.",
|
|
2310
|
-
"control": "boolean",
|
|
2311
|
-
"category": "behavior",
|
|
2312
|
-
"type": "boolean",
|
|
2313
|
-
"defaultValue": "false"
|
|
2314
|
-
},
|
|
2315
|
-
"placeholderLabels": {
|
|
2316
|
-
"description": "Custom labels for the empty state placeholder. Only `placeholderLabels.empty` is supported. When omitted, default localized labels are used.",
|
|
2317
|
-
"control": "object",
|
|
2318
|
-
"category": "behavior",
|
|
2319
|
-
"type": "{ empty?: { header?: string; description?: string; footer?: string } }"
|
|
2320
|
-
},
|
|
2321
|
-
"slots": {
|
|
2322
|
-
"description": "The components used for each slot inside. See the **Slots** section below.",
|
|
2323
|
-
"control": "object",
|
|
2324
|
-
"category": "customization",
|
|
2325
|
-
"type": "object"
|
|
2326
|
-
},
|
|
2327
|
-
"dataTestIdSuffix": {
|
|
2328
|
-
"description": "Optional suffix for the generated test id (base: ring-detail).",
|
|
2329
|
-
"control": "text",
|
|
2330
|
-
"category": "customization",
|
|
2331
|
-
"type": "string"
|
|
2332
|
-
},
|
|
2333
|
-
"slots.afterMain": {
|
|
2334
|
-
"description": "Custom React node rendered after the main media/title section.",
|
|
2335
|
-
"control": false,
|
|
2336
|
-
"category": "slots",
|
|
2337
|
-
"type": "React.JSX.Element"
|
|
2338
|
-
},
|
|
2339
|
-
"slots.afterDescriptionItems": {
|
|
2340
|
-
"description": "Custom React node rendered after the description items sections.",
|
|
2341
|
-
"control": false,
|
|
2342
|
-
"category": "slots",
|
|
2343
|
-
"type": "React.JSX.Element"
|
|
2344
|
-
},
|
|
2345
|
-
"slots.afterBottomActions": {
|
|
2346
|
-
"description": "Custom React node rendered after the bottom action buttons.",
|
|
2347
|
-
"control": false,
|
|
2348
|
-
"category": "slots",
|
|
2349
|
-
"type": "React.JSX.Element"
|
|
2350
|
-
},
|
|
2351
|
-
"main.mediaProps.slots.media": {
|
|
2352
|
-
"description": "Custom React node rendered in place of the default `<CardMedia>` in the media area. Wrapped in `<AspectRatio>` so `mediaProps.ratio` and `mediaProps.objectFit` still apply. When provided, the built-in LightBox / fullscreen preview is suppressed.",
|
|
2353
|
-
"control": false,
|
|
2354
|
-
"category": "slots",
|
|
2355
|
-
"type": "ReactNode"
|
|
2356
|
-
},
|
|
2357
|
-
"main.mediaProps.slotProps.media": {
|
|
2358
|
-
"description": "Props applied to the default `<CardMedia>` in the media area. Used by the default render path (replaced when `main.mediaProps.slots.media` is set). Lets you switch the underlying element (`component: \"video\" | \"audio\" | \"img\"`), tweak `src`, attach native media attributes.",
|
|
2359
|
-
"control": false,
|
|
2360
|
-
"category": "slotProps",
|
|
2361
|
-
"type": "CardMediaProps & AudioHTMLAttributes & VideoHTMLAttributes"
|
|
2362
|
-
},
|
|
2363
|
-
"main.mediaProps.slotProps.card": {
|
|
2364
|
-
"description": "Props applied to the root MUI `<Card>` rendered inside `<Media>`. **Recommended channel for native DOM events** (`onMouseEnter`, `onMouseLeave`, `onFocus`, `onKeyDown`, `aria-*`, `data-*`, …) on the media area.",
|
|
2365
|
-
"control": false,
|
|
2366
|
-
"category": "slotProps",
|
|
2367
|
-
"type": "Omit<CardProps, \"children\" | \"variant\" | \"square\" | \"tabIndex\" | \"elevation\" | \"onClick\">"
|
|
2368
|
-
}
|
|
2369
|
-
},
|
|
2370
|
-
"storyNames": [
|
|
2371
|
-
"Default",
|
|
2372
|
-
"EmptyState",
|
|
2373
|
-
"EmptyStateCustomLabels",
|
|
2374
|
-
"WithCustomSlots",
|
|
2375
|
-
"WithBottomIconButtons",
|
|
2376
|
-
"WithBottomChips",
|
|
2377
|
-
"WithCustomMediaSlot",
|
|
2378
|
-
"WithMediaToolbarHandlers"
|
|
2379
|
-
],
|
|
2380
|
-
"docs": "# Detail\n\nA rich detail panel component for displaying item information with media, sections, editable fields, and action buttons. Commonly used as a side panel in DataView.\n\n- Displays media with image preview, light box, and download support\n- Supports multiple field types: default, description, chips, and editable\n- Customizable bottom actions\n- Configurable slots for injecting custom content after main, description items, and bottom actions\n- Bottom icons on media section as icon buttons or chips\n- Empty state placeholder support\n\nFor migration from the old component version please refer to Detail Migration guide in Migration FAQ -> Moving From Legacy Components section.\n\n## Default\n\nThe default story demonstrates all major features of the Detail component including an editable title, media with icon buttons, multiple description sections with various field types (description, icons, date formatting, editable text, editable select, strings, links, chips with colors), sub-values, and bottom actions.\n\n```tsx\n// DefaultExample.tsx\nimport React from 'react';\nimport {\n Detail,\n DetailDescriptionItemFieldLayout,\n DetailDescriptionItemFieldType,\n EditableFieldType,\n} from '@ringpublishing/mui-components';\nimport type { DetailDescriptionItem, DetailBottomAction } from '@ringpublishing/mui-components';\nimport {\n ContentCopy,\n Download,\n EditOutlined,\n InfoOutlined,\n PrintOutlined,\n Public,\n UploadOutlined,\n Web,\n} from '@mui/icons-material';\nimport { Box } from '@mui/material';\nimport { getImagePath, TestImage, ImageSize } from 'RingDemoImages';\n\nexport default function DefaultExample(): React.JSX.Element {\n const bottomActions: DetailBottomAction[] = [\n {\n name: 'ACTION WITH URL',\n url: 'https://video.onet.pl/',\n icon: <Web />,\n },\n {\n name: 'ACTION WITH ON CLICK',\n onClick: (): void => undefined,\n icon: <Download />,\n },\n {\n name: 'ACTION WITHOUT ICON',\n onClick: (): void => undefined,\n },\n ];\n\n const descriptionItems: DetailDescriptionItem[] = [\n {\n sectionTitle: 'SECTION ONE',\n fields: [\n {\n name: 'DESCRIPTION',\n type: DetailDescriptionItemFieldType.DESCRIPTION,\n maxLength: 100,\n layout: DetailDescriptionItemFieldLayout.VERTICAL,\n showMoreLabel: 'Show more',\n showLessLabel: 'Show less',\n value:\n 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ' +\n 'ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.',\n },\n {\n icon: <Public />,\n name: 'WITH ICON',\n value: 'Published',\n },\n {\n formatDate: true,\n name: 'DATE FORMATTED',\n value: '2023-07-27T09:32:09Z',\n },\n {\n formatDate: false,\n name: 'DATE NOT FORMATTED',\n value: '2023-08-31T21:59:59Z',\n },\n {\n name: 'ICONS',\n value: '',\n icon: [<Web key={'0'} />, <Public key={'1'} />],\n },\n {\n name: 'EDITABLE',\n value: 'Editable value',\n type: DetailDescriptionItemFieldType.EDITABLE,\n onSubmit: (): Promise<boolean> => Promise.resolve(true),\n },\n {\n name: 'EDITABLE SELECT',\n value: 'option2',\n type: DetailDescriptionItemFieldType.EDITABLE,\n fieldType: EditableFieldType.SELECT,\n options: [\n { value: 'option1', label: 'First Option' },\n { value: 'option2', label: 'Second Option' },\n { value: 'option3', label: 'Third Option' },\n ],\n onSubmit: (): Promise<boolean> => Promise.resolve(true),\n },\n ],\n },\n {\n fields: [\n {\n name: 'LIST OF STRINGS',\n value: ['string 1', 'string 2'],\n },\n {\n name: 'SINGLE STRING',\n value: 'string value',\n },\n {\n name: 'NO VALUE',\n value: '',\n },\n {\n name: 'WITH LINK',\n value: '#Learn_more',\n url: 'https://design.ringpublishing.com/',\n },\n {\n name: 'NUMBER',\n value: '10',\n },\n {\n name: 'SINGLE CHIP',\n type: DetailDescriptionItemFieldType.CHIPS,\n value: 'chip value',\n },\n {\n name: 'LIST OF CHIPS',\n type: DetailDescriptionItemFieldType.CHIPS,\n value: ['chip 1', 'chip 2', 'chip 3'],\n collapsable: true,\n },\n {\n layout: DetailDescriptionItemFieldLayout.VERTICAL,\n name: 'LIST OF CUSTOMISED CHIPS',\n type: DetailDescriptionItemFieldType.CHIPS,\n value: [\n {\n onClick: (): void => undefined,\n value: 'chip with onClick',\n },\n {\n badgeColor: '#00a7ee',\n value: 'chip with color',\n },\n ],\n },\n ],\n sectionTitle: 'SECTION TWO',\n },\n {\n fields: [\n {\n name: 'WITH SUBVALUE',\n subValue: {\n label: '',\n value: 'John Doe',\n },\n value: '2023-07-27T09:32:08Z',\n },\n {\n layout: DetailDescriptionItemFieldLayout.VERTICAL,\n name: 'IDENTIFIER (UUID)',\n value: '1234-5432-2334-1234-5432-2334',\n icon: (\n <ContentCopy\n onClick={(): void => undefined}\n sx={{\n color: '#00A7EE',\n fontSize: '1.7rem',\n cursor: 'pointer',\n }}\n />\n ),\n },\n ],\n sectionTitle: 'SECTION THREE',\n },\n ];\n\n const main = {\n mediaProps: {\n bottomIcons: [\n {\n type: 'icon' as const,\n icon: <InfoOutlined />,\n onClick: (): void => undefined,\n tooltip: 'Info',\n },\n {\n type: 'icon' as const,\n icon: <EditOutlined />,\n onClick: (): void => undefined,\n tooltip: 'Edit',\n },\n {\n type: 'icon' as const,\n icon: <PrintOutlined />,\n onClick: (): void => undefined,\n tooltip: 'Print',\n },\n {\n type: 'icon' as const,\n icon: <UploadOutlined />,\n onClick: (): void => undefined,\n tooltip: 'Upload',\n },\n ],\n imageFullScreenPreview: true,\n image: {\n src: getImagePath(TestImage.CAR, ImageSize.LARGE),\n title: TestImage.CAR,\n },\n objectFit: 'cover' as const,\n ratio: '4/3',\n },\n title: {\n value: 'Test title lorem ipsum',\n editable: true,\n onSubmit: (): Promise<boolean> => Promise.resolve(true),\n label: 'Title',\n },\n onCloseClick: (): void => undefined,\n };\n\n return (\n <Box display={'flex'} justifyContent={'center'}>\n <Detail bottomActions={bottomActions} descriptionItems={descriptionItems} main={main} />\n </Box>\n );\n}\n```\n\n## Empty State\n\nWhen no data is available, the Detail component can display an empty state placeholder by setting the `empty` prop to `true`.\n\n```tsx\n// EmptyStateExample.tsx\nimport React from 'react';\nimport { Detail } from '@ringpublishing/mui-components';\nimport { Box } from '@mui/material';\n\nexport default function EmptyStateExample(): React.JSX.Element {\n return (\n <Box display={'flex'} justifyContent={'center'} height={600}>\n <Detail empty={true} />\n </Box>\n );\n}\n```\n\n## Empty State Custom Labels\n\nThe empty state placeholder labels can be overridden with `placeholderLabels.empty`. Other placeholder label keys are not used by `Detail`.\n\n```tsx\n// EmptyStateCustomLabelsExample.tsx\nimport React from 'react';\nimport { Detail } from '@ringpublishing/mui-components';\nimport { Box } from '@mui/material';\n\nexport default function EmptyStateCustomLabelsExample(): React.JSX.Element {\n return (\n <Box display={'flex'} justifyContent={'center'} height={600}>\n <Detail\n empty={true}\n placeholderLabels={{\n empty: {\n header: 'No item selected',\n description: 'Choose one of the entries from the list to inspect its details.',\n footer: 'Need help? Contact your administrator.',\n },\n }}\n />\n </Box>\n );\n}\n```\n\n## With Custom Slots\n\nThe Detail component provides three customizable slots for injecting additional content:\n\n| Slot | Description |\n| ----------------------- | --------------------------------------------- |\n| `afterMain` | Rendered after the main media/title section |\n| `afterDescriptionItems` | Rendered after the description items sections |\n| `afterBottomActions` | Rendered after the bottom action buttons |\n\n```tsx\n// WithCustomSlotsExample.tsx\nimport React from 'react';\nimport {\n Detail,\n DetailDescriptionItemFieldType,\n DetailDescriptionItem,\n DetailBottomAction,\n} from '@ringpublishing/mui-components';\nimport { Box } from '@mui/material';\nimport { Download, EditOutlined, InfoOutlined, PrintOutlined, Public, UploadOutlined, Web } from '@mui/icons-material';\nimport { getImagePath, TestImage, ImageSize } from 'RingDemoImages';\n\nexport default function WithCustomSlotsExample(): React.JSX.Element {\n const bottomActions: DetailBottomAction[] = [\n {\n name: 'ACTION WITH URL',\n url: 'https://video.onet.pl/',\n icon: <Web />,\n },\n {\n name: 'ACTION WITH ON CLICK',\n onClick: (): void => undefined,\n icon: <Download />,\n },\n ];\n\n const descriptionItems: DetailDescriptionItem[] = [\n {\n sectionTitle: 'SECTION ONE',\n fields: [\n {\n icon: <Public />,\n name: 'WITH ICON',\n value: 'Published',\n },\n {\n formatDate: true,\n name: 'DATE FORMATTED',\n value: '2023-07-27T09:32:09Z',\n },\n ],\n },\n {\n fields: [\n {\n name: 'LIST OF CHIPS',\n type: DetailDescriptionItemFieldType.CHIPS,\n value: ['chip 1', 'chip 2', 'chip 3'],\n },\n {\n name: 'LIST OF STRINGS',\n value: ['string 1', 'string 2'],\n },\n ],\n sectionTitle: 'SECTION TWO',\n },\n ];\n\n const main = {\n mediaProps: {\n bottomIcons: [\n {\n type: 'icon' as const,\n icon: <InfoOutlined />,\n onClick: (): void => undefined,\n tooltip: 'Info',\n },\n {\n type: 'icon' as const,\n icon: <EditOutlined />,\n onClick: (): void => undefined,\n tooltip: 'Edit',\n },\n {\n type: 'icon' as const,\n icon: <PrintOutlined />,\n onClick: (): void => undefined,\n tooltip: 'Print',\n },\n {\n type: 'icon' as const,\n icon: <UploadOutlined />,\n onClick: (): void => undefined,\n tooltip: 'Upload',\n },\n ],\n imageFullScreenPreview: true,\n image: getImagePath(TestImage.BEACH, ImageSize.LARGE),\n objectFit: 'cover' as const,\n },\n title: {\n value: 'Test title lorem ipsum',\n editable: true,\n onSubmit: (): Promise<boolean> => Promise.resolve(true),\n label: 'Title',\n },\n onCloseClick: (): void => undefined,\n };\n\n return (\n <Box display={'flex'} justifyContent={'center'}>\n <Detail\n bottomActions={bottomActions}\n descriptionItems={descriptionItems}\n main={main}\n slots={{\n afterMain: (\n <Box sx={{ backgroundColor: (theme) => theme.palette.common.grey, py: 1, textAlign: 'center' }}>\n Custom slot after main\n </Box>\n ),\n afterDescriptionItems: (\n <Box sx={{ backgroundColor: (theme) => theme.palette.common.grey, py: 1, textAlign: 'center' }}>\n Custom slot after description items\n </Box>\n ),\n afterBottomActions: (\n <Box sx={{ backgroundColor: (theme) => theme.palette.common.grey, py: 1, textAlign: 'center' }}>\n Custom slot after bottom actions\n </Box>\n ),\n }}\n />\n </Box>\n );\n}\n```\n\n## With Bottom Icon Buttons\n\nDisplay icon buttons at the bottom of the media section. Each button supports tooltips and click handlers. Bottom icons must be all of type `'icon'` or all of type `'chip'` — mixing types is not supported.\n\n```tsx\n// WithBottomIconButtonsExample.tsx\nimport React from 'react';\nimport { Detail } from '@ringpublishing/mui-components';\nimport { Box } from '@mui/material';\nimport { EditOutlined, InfoOutlined, PrintOutlined, UploadOutlined } from '@mui/icons-material';\nimport { getImagePath, TestImage, ImageSize } from 'RingDemoImages';\n\nexport default function WithBottomIconButtonsExample(): React.JSX.Element {\n const main = {\n mediaProps: {\n bottomIcons: [\n {\n type: 'icon' as const,\n icon: <InfoOutlined />,\n onClick: (): void => undefined,\n tooltip: 'Information',\n },\n {\n type: 'icon' as const,\n icon: <EditOutlined />,\n onClick: (): void => undefined,\n tooltip: 'Edit',\n },\n {\n type: 'icon' as const,\n icon: <PrintOutlined />,\n onClick: (): void => undefined,\n tooltip: 'Print',\n },\n {\n type: 'icon' as const,\n icon: <UploadOutlined />,\n onClick: (): void => undefined,\n tooltip: 'Upload',\n },\n ],\n imageFullScreenPreview: true,\n image: getImagePath(TestImage.APARTMENT, ImageSize.LARGE),\n objectFit: 'cover' as const,\n ratio: '4/3',\n },\n title: 'Detail with Icon Buttons',\n onCloseClick: (): void => undefined,\n };\n\n const descriptionItems = [\n {\n sectionTitle: 'INFORMATION',\n fields: [\n {\n name: 'Description',\n value: 'This example showcases icon buttons at the bottom of the media section.',\n },\n ],\n },\n ];\n return (\n <Box display={'flex'} justifyContent={'center'}>\n <Detail main={main} descriptionItems={descriptionItems} />\n </Box>\n );\n}\n```\n\n## With Bottom Chips\n\nDisplay colored chip labels at the bottom of the media section. Each chip supports custom background colors with automatic text color contrast calculation.\n\n```tsx\n// WithBottomChipsExample.tsx\nimport React from 'react';\nimport { Detail } from '@ringpublishing/mui-components';\nimport { Box } from '@mui/material';\nimport { getImagePath, TestImage, ImageSize } from 'RingDemoImages';\n\nexport default function WithBottomChipsExample(): React.JSX.Element {\n const main = {\n mediaProps: {\n bottomIcons: [\n {\n type: 'chip' as const,\n chip: {\n label: 'Category',\n variant: 'filled' as const,\n size: 'small' as const,\n },\n },\n {\n type: 'chip' as const,\n chip: {\n label: 'Status: Active',\n variant: 'filled' as const,\n size: 'small' as const,\n },\n color: '#4CAF50',\n },\n {\n type: 'chip' as const,\n chip: {\n label: 'Priority',\n variant: 'filled' as const,\n size: 'small' as const,\n },\n color: '#2196F3',\n },\n {\n type: 'chip' as const,\n chip: {\n label: 'Default',\n variant: 'filled' as const,\n size: 'small' as const,\n },\n },\n {\n type: 'chip' as const,\n chip: {\n label: 'Warning',\n variant: 'filled' as const,\n size: 'small' as const,\n },\n color: '#FFC107',\n },\n ],\n imageFullScreenPreview: true,\n image: getImagePath(TestImage.STAIRS, ImageSize.LARGE),\n objectFit: 'cover' as const,\n ratio: '4/3',\n },\n title: 'Detail with Chips',\n onCloseClick: (): void => undefined,\n };\n\n const descriptionItems = [\n {\n sectionTitle: 'INFORMATION',\n fields: [\n {\n name: 'Description',\n value: 'This example showcases chips at the bottom of the media section with custom colors.',\n },\n ],\n },\n ];\n\n return (\n <Box display={'flex'} justifyContent={'center'}>\n <Detail main={main} descriptionItems={descriptionItems} />\n </Box>\n );\n}\n```\n\n## With Custom Media Slot\n\nThe `mediaProps.slots.media` slot lets consumers replace the default `<CardMedia>` with any React node — for example a custom video player with overlay controls, an interactive preview component, or a third-party library wrapper. The slot is wrapped in `<AspectRatio>` so `mediaProps.ratio` and `mediaProps.objectFit` still apply to the surrounding box.\n\nWhen `slots.media` is provided, the built-in LightBox / fullscreen preview is suppressed (the slot replaces the default media render and `<LightBox>` only handles still images, not arbitrary React nodes). Detail's zoom/download bottom-icons row is also suppressed in this case.\n\nUse `mediaProps.slotProps.card` to attach DOM events (e.g. hover-driven `play()` / `pause()` for a video preview).\n\n```tsx\n// WithCustomMediaSlotExample.tsx\nimport React, { useEffect, useRef, useState } from 'react';\nimport { Box } from '@mui/material';\nimport { Detail, DetailDescriptionItemFieldType } from '@ringpublishing/mui-components';\n\nconst VIDEO_SRC = 'https://test-videos.co.uk/vids/bigbuckbunny/mp4/h264/1080/Big_Buck_Bunny_1080_10s_1MB.mp4';\n\ninterface HoverVideoPreviewProps {\n src: string;\n isPlaying: boolean;\n objectFit?: React.CSSProperties['objectFit'];\n}\n\nfunction HoverVideoPreview({\n src,\n isPlaying,\n objectFit = 'cover',\n ...rest\n}: HoverVideoPreviewProps): React.JSX.Element {\n const videoRef = useRef<HTMLVideoElement>(null);\n const [progress, setProgress] = useState(0);\n\n useEffect(() => {\n const video = videoRef.current;\n if (!video) return;\n\n if (isPlaying) {\n void video.play().catch(() => {\n // autoplay can be blocked; ignored for POC\n });\n } else {\n video.pause();\n video.currentTime = 0;\n setProgress(0);\n }\n }, [isPlaying]);\n\n const handleTimeUpdate = (): void => {\n const video = videoRef.current;\n if (!video?.duration) return;\n setProgress(video.currentTime / video.duration);\n };\n\n return (\n <Box {...rest} sx={{ position: 'relative', width: '100%', height: '100%' }}>\n <video\n ref={videoRef}\n muted={true}\n playsInline={true}\n onTimeUpdate={handleTimeUpdate}\n style={{ width: '100%', height: '100%', objectFit, display: 'block' }}\n >\n <source src={src} type=\"video/mp4\" />\n </video>\n <Box\n sx={{\n position: 'absolute',\n bottom: 0,\n left: 0,\n right: 0,\n height: '4px',\n backgroundColor: 'rgba(255, 255, 255, 0.3)',\n pointerEvents: 'none',\n }}\n >\n <Box\n sx={{\n height: '100%',\n width: `${progress * 100}%`,\n backgroundColor: 'primary.main',\n transition: 'width 0.1s linear',\n }}\n />\n </Box>\n </Box>\n );\n}\n\nexport default function WithCustomMediaSlotExample(): React.JSX.Element {\n const [isHovered, setIsHovered] = useState(false);\n\n return (\n <Box display={'flex'} justifyContent={'center'}>\n <Detail\n main={{\n title: 'Big Buck Bunny — sample clip',\n onCloseClick: (): void => undefined,\n mediaProps: {\n ratio: '16/9',\n objectFit: 'cover',\n slots: {\n media: <HoverVideoPreview src={VIDEO_SRC} isPlaying={isHovered} />,\n },\n slotProps: {\n card: {\n onMouseEnter: (): void => setIsHovered(true),\n onMouseLeave: (): void => setIsHovered(false),\n },\n },\n },\n }}\n descriptionItems={[\n {\n sectionTitle: 'METADATA',\n fields: [\n { name: 'DURATION', value: '00:10' },\n { name: 'FORMAT', value: '1080p · H.264' },\n {\n name: 'TAGS',\n type: DetailDescriptionItemFieldType.CHIPS,\n value: ['preview', 'sample', 'animated'],\n },\n ],\n },\n ]}\n />\n </Box>\n );\n}\n```\n\n## Slots\n\nDetail exposes slots on two levels: top-level slots for injecting content around the body, and nested slots on `main.mediaProps` that mirror the [Media](?path=/docs/components-molecules-media--docs) molecule's own slot system.\n\n| Slot | Type | Default | Description |\n| ----------------------------- | ------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `slots.afterMain` | `React.JSX.Element` | — | Rendered after the main media/title section. |\n| `slots.afterDescriptionItems` | `React.JSX.Element` | — | Rendered after the description items sections. |\n| `slots.afterBottomActions` | `React.JSX.Element` | — | Rendered after the bottom action buttons. |\n| `main.mediaProps.slots.media` | `ReactNode` | `CardMedia` | Custom React node rendered in place of the default `<CardMedia>` in the media area. Wrapped in `<AspectRatio>` so `mediaProps.ratio` and `mediaProps.objectFit` still apply. When provided, the built-in LightBox / fullscreen preview is suppressed. |\n\n## Slot props\n\nDetail does not expose `slotProps` at the root level. The `main.mediaProps.slotProps` channel forwards directly to the inner `<Media>` molecule.\n\n| Slot prop | Type | Description |\n| --------------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `main.mediaProps.slotProps.media` | `CardMediaProps & AudioHTMLAttributes & VideoHTMLAttributes` | Props applied to the default `<CardMedia>` in the media area. Used by the default render path (replaced when `main.mediaProps.slots.media` is set). Lets you switch the underlying element (`component: \"video\" \\| \"audio\" \\| \"img\"`), tweak `src`, attach native media attributes. |\n| `main.mediaProps.slotProps.card` | `Omit<CardProps, \"children\" \\| \"variant\" \\| \"square\" \\| \"tabIndex\" \\| \"elevation\" \\| \"onClick\">` | Props applied to the root MUI `<Card>` rendered inside `<Media>`. **Recommended channel for native DOM events** (`onMouseEnter`, `onMouseLeave`, `onFocus`, `onKeyDown`, `aria-*`, `data-*`, …) on the media area. `onClick` is excluded for the same reason as in `Media` — Media is not a clickable container; use `main.mediaProps.slotProps.media.onClick` for clicks scoped to `<CardMedia>`, or attach a handler outside Detail. |\n\n> Detail uses the [Media](?path=/docs/components-molecules-media--docs) molecule under the hood — `mediaProps.slots` and `mediaProps.slotProps` mirror Media's API one-to-one. See the Media docs for full precedence rules and additional details."
|
|
2381
|
-
},
|
|
2382
|
-
"organisms-file-uploader": {
|
|
2383
|
-
"id": "organisms-file-uploader",
|
|
2384
|
-
"name": "FileUploader",
|
|
2385
|
-
"category": "Organisms",
|
|
2386
|
-
"title": "Components/Organisms/FileUploader",
|
|
2387
|
-
"description": "A flexible drag-and-drop file upload component with progress tracking, error handling, and customizable slots for actions and URL uploads.",
|
|
2388
|
-
"argTypes": {
|
|
2389
|
-
"sx": {
|
|
2390
|
-
"description": "MUI System properties to customize the main element style.",
|
|
2391
|
-
"control": "object",
|
|
2392
|
-
"category": "customization",
|
|
2393
|
-
"type": "SxProps<Theme>",
|
|
2394
|
-
"defaultValue": "{}"
|
|
2395
|
-
},
|
|
2396
|
-
"className": {
|
|
2397
|
-
"description": "CSS class name applied to the main element.",
|
|
2398
|
-
"control": "text",
|
|
2399
|
-
"category": "customization",
|
|
2400
|
-
"type": "string"
|
|
2401
|
-
},
|
|
2402
|
-
"headline": {
|
|
2403
|
-
"description": "Optional headline text",
|
|
2404
|
-
"control": "text",
|
|
2405
|
-
"category": "content",
|
|
2406
|
-
"type": "string"
|
|
2407
|
-
},
|
|
2408
|
-
"labels": {
|
|
2409
|
-
"description": "Text labels for the component (required)",
|
|
2410
|
-
"control": "object",
|
|
2411
|
-
"category": "content",
|
|
2412
|
-
"type": "{ dropzone: string; hint?: string; uploadButton: string; description?: string; filesUploaded?: string }"
|
|
2413
|
-
},
|
|
2414
|
-
"errorMessage": {
|
|
2415
|
-
"description": "Error message to display. When set, dropzone shows error state with red background and solid border",
|
|
2416
|
-
"control": "text",
|
|
2417
|
-
"category": "content",
|
|
2418
|
-
"type": "string"
|
|
2419
|
-
},
|
|
2420
|
-
"maxFileSize": {
|
|
2421
|
-
"description": "Maximum file size in bytes",
|
|
2422
|
-
"control": "number",
|
|
2423
|
-
"category": "validation",
|
|
2424
|
-
"type": "number"
|
|
2425
|
-
},
|
|
2426
|
-
"accept": {
|
|
2427
|
-
"description": "Accepted file types (e.g., \"image/*\", \".pdf\")",
|
|
2428
|
-
"control": "text",
|
|
2429
|
-
"category": "validation",
|
|
2430
|
-
"type": "string"
|
|
2431
|
-
},
|
|
2432
|
-
"multiple": {
|
|
2433
|
-
"description": "Allow multiple file selection",
|
|
2434
|
-
"control": "boolean",
|
|
2435
|
-
"category": "behavior",
|
|
2436
|
-
"type": "boolean",
|
|
2437
|
-
"defaultValue": "false"
|
|
2438
|
-
},
|
|
2439
|
-
"initiallyCollapsed": {
|
|
2440
|
-
"description": "Whether files list is initially collapsed (for multiple files)",
|
|
2441
|
-
"control": "boolean",
|
|
2442
|
-
"category": "behavior",
|
|
2443
|
-
"type": "boolean",
|
|
2444
|
-
"defaultValue": "false"
|
|
2445
|
-
},
|
|
2446
|
-
"size": {
|
|
2447
|
-
"description": "Size of the dropzone and other components. Available options: Small (compact, horizontal layout), Medium (balanced, vertical layout), Large (spacious, prominent)",
|
|
2448
|
-
"control": "radio",
|
|
2449
|
-
"category": "appearance",
|
|
2450
|
-
"type": "FileUploaderSize"
|
|
2451
|
-
},
|
|
2452
|
-
"onFilesSelected": {
|
|
2453
|
-
"description": "Callback fired when files are selected (via drag & drop or file browser). Receives an array of File objects containing file metadata (name, size, type) and binary data for upload.",
|
|
2454
|
-
"category": "callbacks",
|
|
2455
|
-
"type": "(files: File[]) => void"
|
|
2456
|
-
},
|
|
2457
|
-
"onRemove": {
|
|
2458
|
-
"description": "Callback fired when a file is removed from the list",
|
|
2459
|
-
"category": "callbacks",
|
|
2460
|
-
"type": "(fileId: string) => void"
|
|
2461
|
-
},
|
|
2462
|
-
"onRetry": {
|
|
2463
|
-
"description": "Callback fired when user clicks retry on a failed upload item",
|
|
2464
|
-
"category": "callbacks",
|
|
2465
|
-
"type": "(fileId: string) => void"
|
|
2466
|
-
},
|
|
2467
|
-
"files": {
|
|
2468
|
-
"description": "List of files for controlled component mode. Each file uses the FileUploaderFile model — no native File object required.",
|
|
2469
|
-
"control": "object",
|
|
2470
|
-
"category": "state",
|
|
2471
|
-
"type": "FileUploaderFile[]"
|
|
2472
|
-
},
|
|
2473
|
-
"slotProps": {
|
|
2474
|
-
"description": "Props for internal components. See [URL Upload](#url-upload) section above for detailed usage and examples.",
|
|
2475
|
-
"control": "object",
|
|
2476
|
-
"category": "customization",
|
|
2477
|
-
"type": "{ urlUploadSection?: UrlUploadSectionProps }"
|
|
2478
|
-
},
|
|
2479
|
-
"action": {
|
|
2480
|
-
"description": "Slot for custom React node to display next to the upload button. See [Action Slot](#custom-action) section above for usage examples.",
|
|
2481
|
-
"control": false,
|
|
2482
|
-
"category": "customization",
|
|
2483
|
-
"type": "React.ReactNode"
|
|
2484
|
-
},
|
|
2485
|
-
"dataTestIdSuffix": {
|
|
2486
|
-
"description": "Optional suffix for generated test id (base: ring-file-uploader).",
|
|
2487
|
-
"control": "text",
|
|
2488
|
-
"category": "customization",
|
|
2489
|
-
"type": "string"
|
|
2490
|
-
}
|
|
2491
|
-
},
|
|
2492
|
-
"storyNames": [
|
|
2493
|
-
"Default",
|
|
2494
|
-
"UploadFileStates",
|
|
2495
|
-
"UrlUpload",
|
|
2496
|
-
"CustomAction"
|
|
2497
|
-
],
|
|
2498
|
-
"docs": "# FileUploader\n\nA flexible drag-and-drop file upload component with progress tracking, error handling, and customizable slots for actions and URL uploads.\n\n- Supports multiple file selection\n- Shows upload progress, completion, and error states\n- Supports backend/pre-existing files via `Idle` status — no native `File` object required\n- Allows custom actions and URL upload integration\n\n## Component Sizes\n\nThe FileUploader comes in three size variants to fit different use cases:\n\n```typescript\n\n// Small - Compact horizontal layout for inline forms\n<FileUploader size={FileUploaderSize.Small} />\n\n// Medium - Balanced vertical layout (default)\n<FileUploader size={FileUploaderSize.Medium} />\n\n// Large - Spacious layout for prominent upload areas\n<FileUploader size={FileUploaderSize.Large} />\n```\n\n**Available sizes**: `Small`, `Medium`, `Large`\n\n## Default\n\n```tsx\n// DefaultExample.tsx\nimport React from 'react';\nimport { FileUploader, FileUploaderSize } from '@ringpublishing/mui-components';\n\nexport default function DefaultExample(): React.JSX.Element {\n const handleFilesSelected = (files: File[]): void => {\n void files;\n };\n\n return (\n <FileUploader\n headline=\"Upload File\"\n labels={{\n dropzone: 'Drag and drop file to add or',\n hint: 'PDF, DOC, DOCX (max. 10MB)',\n uploadButton: 'upload from disk',\n description: 'You can upload PDF, DOC and DOCX file formats.',\n }}\n maxFileSize={10 * 1024 * 1024}\n accept=\".pdf,.doc,.docx\"\n slotProps={{\n urlUploadSection: {\n enabled: false,\n onSubmit: (url: string): void => {\n void url;\n },\n title: 'Or from URL',\n placeholder: 'Paste URL here',\n submitButton: 'Send',\n textFieldProps: { error: false, helperText: 'Enter valid URL' },\n },\n }}\n size={FileUploaderSize.Medium}\n files={[]}\n onFilesSelected={handleFilesSelected}\n sx={{ maxWidth: 600, margin: '0 auto' }}\n />\n );\n}\n```\n\n## Upload File States\n\nEach file in the `files` array uses the `FileUploaderFile` model. A native `File` object is **not required** — use `name` and `size` fields instead.\n\n### Statuses\n\n| Status | Description | Visual |\n| ----------- | -------------------------------------------------------- | --------------------------------------- |\n| `Idle` | Neutral / backend file. Default when no status provided. | Grey icon, no progress bar |\n| `Uploading` | Upload in progress | Blue spinner + progress bar + % |\n| `Completed` | Upload completed and finalized | Green checkmark + progress bar |\n| `Success` | Upload completed successfully | Green checkmark + progress bar |\n| `Error` | Upload failed | Red icon + error message + retry button |\n\n### FileUploaderFile model\n\n```typescript\n\n// Backend / pre-existing file (no File object needed)\nconst backendFile: FileUploaderFile = {\n id: 'doc-1',\n name: 'report.pdf',\n size: 2.1 * 1024 * 1024,\n status: FileUploaderStatus.Idle,\n showRemove: true,\n};\n\n// Browser upload in progress\nconst uploadingFile: FileUploaderFile = {\n id: 'upload-1',\n name: 'photo.jpg',\n size: 4 * 1024 * 1024,\n status: FileUploaderStatus.Uploading,\n progress: 42,\n uploadedBytes: 1.68 * 1024 * 1024,\n file: nativeFileObject, // optional — only for browser uploads\n};\n```\n\n### Action Modes\n\n1. **Replace File** (`action.label` only) — opens file picker\n2. **Custom Action** (`action.label` + `action.onClick`) — executes custom handler\n\n```tsx\n// UploadFileStatesExample.tsx\nimport React from 'react';\nimport { FileUploader, FileUploaderSize, FileUploaderStatus } from '@ringpublishing/mui-components';\n\nexport default function UploadFileStatesExample(): React.JSX.Element {\n const handleRemove = (): void => {\n void 0;\n };\n\n const handleRetry = (): void => {\n void 0;\n };\n\n return (\n <FileUploader\n headline=\"File Upload - All States Demo\"\n multiple={true}\n size={FileUploaderSize.Small}\n accept={'.pdf,.doc,.docx,.txt, .jpg'}\n maxFileSize={10 * 1024 * 1024}\n initiallyCollapsed={false}\n slotProps={{\n urlUploadSection: {\n enabled: false,\n onSubmit: (url: string): void => {\n void url;\n },\n title: 'Or from URL',\n placeholder: 'Paste URL here',\n submitButton: 'Send',\n textFieldProps: { error: false, helperText: 'Enter valid URL' },\n },\n }}\n labels={{\n dropzone: 'Drag and drop file to add or',\n hint: 'PDF, DOC, DOCX (max. 10MB)',\n uploadButton: 'upload from disk',\n description: 'You can upload PDF, DOC and DOCX file formats.',\n }}\n files={[\n {\n id: '0',\n name: 'backend-document.pdf',\n size: 2.1 * 1024 * 1024,\n type: 'application/pdf',\n status: FileUploaderStatus.Idle,\n showRemove: true,\n },\n {\n id: '1',\n name: 'uploading-25.pdf',\n size: 3.5 * 1024 * 1024,\n type: 'application/pdf',\n progress: 5,\n status: FileUploaderStatus.Uploading,\n uploadedBytes: 0.875 * 1024 * 1024,\n showRemove: true,\n },\n {\n id: '2',\n name: 'completed.pdf',\n size: 4.7 * 1024 * 1024,\n type: 'application/pdf',\n progress: 100,\n status: FileUploaderStatus.Success,\n showRemove: true,\n },\n {\n id: '3',\n name: 'error.csv',\n size: 3 * 1024 * 1024,\n type: 'text/csv',\n status: FileUploaderStatus.Error,\n errorMessage: 'Network error: Connection lost',\n },\n {\n id: '4',\n name: 'uploading-no-progressbar.pdf',\n size: 3.5 * 1024 * 1024,\n type: 'application/pdf',\n progress: 25,\n status: FileUploaderStatus.Uploading,\n uploadedBytes: 0.875 * 1024 * 1024,\n showProgressBar: false,\n },\n {\n id: '5',\n name: 'completed-no-progressbar.pdf',\n size: 4.7 * 1024 * 1024,\n type: 'application/pdf',\n progress: 100,\n status: FileUploaderStatus.Success,\n showProgressBar: false,\n },\n {\n id: '6',\n name: 'error-no-progressbar.csv',\n size: 3 * 1024 * 1024,\n type: 'text/csv',\n status: FileUploaderStatus.Error,\n errorMessage: 'Network error: Connection lost',\n showProgressBar: false,\n },\n {\n id: '7',\n name: 'changed-action.pdf',\n size: 3.5 * 1024 * 1024,\n type: 'application/pdf',\n progress: 25,\n status: FileUploaderStatus.Uploading,\n uploadedBytes: 0.875 * 1024 * 1024,\n showProgressBar: false,\n showRemove: false,\n action: {\n label: 'CHANGE',\n },\n },\n ]}\n onRemove={handleRemove}\n onRetry={handleRetry}\n sx={{ maxWidth: 600, margin: '0 auto' }}\n />\n );\n}\n```\n\n## URL Upload\n\nEnable URL upload functionality to allow users to provide file URLs instead of uploading from their device. Perfect for importing files from external sources, cloud storage, or direct links.\n\n### Configuration\n\nConfigure the URL upload section via `slotProps.urlUploadSection`:\n\n| Property | Type | Description |\n| ---------------- | ------------------------- | ------------------------------------------------- |\n| `enabled` | `boolean` | Enable/disable the URL upload section |\n| `onSubmit` | `(url: string) => void` | **Required** - Callback when URL is submitted |\n| `loading` | `boolean` | Shows spinner and disables controls during upload |\n| `onClear` | `() => void` | Optional callback when URL input is cleared |\n| `title` | `string` | Custom section title (default: \"or enter URL\") |\n| `placeholder` | `string` | TextField placeholder (default: \"https://...\") |\n| `submitButton` | `string` | Submit button text (default: \"Upload\") |\n| `textFieldProps` | `Partial<TextFieldProps>` | Additional props for the TextField component |\n\n```tsx\n// UrlUploadExample.tsx\nimport React, { useState } from 'react';\nimport { FileUploader } from '@ringpublishing/mui-components';\n\nexport default function UrlUploadExample(): React.JSX.Element {\n const [isUploading, setIsUploading] = useState(false);\n\n const handleUrlSubmit = async (url: string): Promise<void> => {\n setIsUploading(true);\n\n try {\n // Simulate API call\n await new Promise((resolve) => setTimeout(resolve, 2000));\n\n // Handle URL upload\n void url;\n\n // Here you would typically:\n // const response = await fetch(url);\n // const blob = await response.blob();\n // Upload blob to your server...\n } catch (error) {\n void error;\n } finally {\n setIsUploading(false);\n }\n };\n\n const handleClear = (): void => {\n void 0;\n };\n\n return (\n <FileUploader\n sx={{ maxWidth: 600, margin: '0 auto' }}\n headline=\"Upload Your Files\"\n labels={{\n dropzone: 'Drag and drop files here or',\n uploadButton: 'Browse files',\n hint: 'PDF, DOC (max. 10MB)',\n description: 'Upload multiple files from your computer or from a URL',\n }}\n multiple={true}\n maxFileSize={10 * 1024 * 1024}\n accept=\".pdf,.doc,.docx\"\n slotProps={{\n urlUploadSection: {\n enabled: true,\n title: 'Or upload from URL',\n placeholder: 'Enter file URL',\n submitButton: 'Upload',\n onSubmit: handleUrlSubmit,\n loading: isUploading,\n onClear: handleClear,\n textFieldProps: { error: false, helperText: 'Enter valid URL' },\n },\n }}\n />\n );\n}\n```\n\n## Custom Action\n\nAdd custom actions next to the upload button using the `action` slot. Perfect for integrating external file pickers, cloud storage, or any custom upload source.\n\n| Property | Type | Description |\n| -------- | ----------------- | ----------------------------------------------------- |\n| `action` | `React.ReactNode` | Custom component to display next to the upload button |\n\n```tsx\n// CustomActionExample.tsx\nimport React from 'react';\nimport { Button } from '@mui/material';\nimport { FileUploader } from '@ringpublishing/mui-components';\n\nexport default function CustomActionExample(): React.JSX.Element {\n const handleCustomAction = (): void => {\n // Add your custom logic here\n };\n\n return (\n <FileUploader\n sx={{ maxWidth: 600, margin: '0 auto' }}\n headline=\"Upload Your Files\"\n labels={{\n dropzone: 'Drag and drop file here or',\n uploadButton: 'Browse file',\n hint: 'PDF, DOC (max. 10MB)',\n description: 'Upload files from your computer or from an external source',\n }}\n maxFileSize={10 * 1024 * 1024}\n accept=\".pdf,.doc,.docx\"\n action={\n <Button variant=\"outlined\" onClick={handleCustomAction}>\n From Source\n </Button>\n }\n />\n );\n}\n```"
|
|
2499
|
-
},
|
|
2500
|
-
"organisms-filters-filters-wrapper": {
|
|
2501
|
-
"id": "organisms-filters-filters-wrapper",
|
|
2502
|
-
"name": "FiltersWrapper",
|
|
2503
|
-
"category": "Organisms",
|
|
2504
|
-
"title": "Components/Organisms/Filters/FiltersWrapper",
|
|
2505
|
-
"description": "A themed wrapper component for organizing filter controls with an optional clear button and customizable styling. It provides consistent theming for child form elements.",
|
|
2506
|
-
"argTypes": {
|
|
2507
|
-
"label": {
|
|
2508
|
-
"description": "Label of the component displayed at the top.",
|
|
2509
|
-
"control": "text",
|
|
2510
|
-
"category": "content",
|
|
2511
|
-
"type": "string"
|
|
2512
|
-
},
|
|
2513
|
-
"withClearButton": {
|
|
2514
|
-
"description": "Flag indicating whether the clear button should be displayed.",
|
|
2515
|
-
"control": "boolean",
|
|
2516
|
-
"category": "behavior",
|
|
2517
|
-
"type": "boolean",
|
|
2518
|
-
"defaultValue": "false"
|
|
2519
|
-
},
|
|
2520
|
-
"clearButtonLabel": {
|
|
2521
|
-
"description": "Label for the clear button.",
|
|
2522
|
-
"control": "text",
|
|
2523
|
-
"category": "content",
|
|
2524
|
-
"type": "string"
|
|
2525
|
-
},
|
|
2526
|
-
"onClear": {
|
|
2527
|
-
"description": "Callback function called when clear button is clicked. Required together with `withClearButton` for the clear button to render.",
|
|
2528
|
-
"control": false,
|
|
2529
|
-
"category": "callbacks",
|
|
2530
|
-
"type": "() => void"
|
|
2531
|
-
},
|
|
2532
|
-
"variant": {
|
|
2533
|
-
"description": "Variant of child input elements. Applied via MUI ThemeProvider to override default props for TextField, Select, Autocomplete, and other child components.",
|
|
2534
|
-
"control": "radio",
|
|
2535
|
-
"category": "appearance",
|
|
2536
|
-
"type": "'outlined' | 'standard'"
|
|
2537
|
-
},
|
|
2538
|
-
"size": {
|
|
2539
|
-
"description": "Size of child elements. Applied via MUI ThemeProvider to override default props for child components.",
|
|
2540
|
-
"control": "radio",
|
|
2541
|
-
"category": "appearance",
|
|
2542
|
-
"type": "'small' | 'medium'"
|
|
2543
|
-
},
|
|
2544
|
-
"buttonStyle": {
|
|
2545
|
-
"description": "Style configuration for all MUI Button instances inside the wrapper (size and variant). Applied via MUI ThemeProvider.",
|
|
2546
|
-
"control": "object",
|
|
2547
|
-
"category": "appearance",
|
|
2548
|
-
"type": "Pick<ButtonOwnProps, 'size' | 'variant'>",
|
|
2549
|
-
"defaultValue": "{ size: 'small', variant: 'contained' }"
|
|
2550
|
-
},
|
|
2551
|
-
"sx": {
|
|
2552
|
-
"description": "MUI System properties to customize the main element style.",
|
|
2553
|
-
"control": "object",
|
|
2554
|
-
"category": "customization",
|
|
2555
|
-
"type": "SxProps<Theme>"
|
|
2556
|
-
},
|
|
2557
|
-
"className": {
|
|
2558
|
-
"description": "CSS class name applied to the main element.",
|
|
2559
|
-
"control": "text",
|
|
2560
|
-
"category": "customization",
|
|
2561
|
-
"type": "string"
|
|
2562
|
-
},
|
|
2563
|
-
"children": {
|
|
2564
|
-
"description": "Filter controls to render inside the wrapper.",
|
|
2565
|
-
"control": false,
|
|
2566
|
-
"category": "content",
|
|
2567
|
-
"type": "React.ReactNode"
|
|
2568
|
-
},
|
|
2569
|
-
"dataTestIdSuffix": {
|
|
2570
|
-
"description": "Inherited from CommonComponentProps. Not yet implemented in FiltersWrapper.",
|
|
2571
|
-
"control": false,
|
|
2572
|
-
"category": "customization",
|
|
2573
|
-
"type": "string"
|
|
2574
|
-
}
|
|
2575
|
-
},
|
|
2576
|
-
"storyNames": [
|
|
2577
|
-
"Default"
|
|
2578
|
-
],
|
|
2579
|
-
"docs": "# FiltersWrapper\n\nA themed wrapper component for organizing filter controls with an optional clear button and customizable styling. It provides consistent theming for child form elements.\n\n- Configurable label and clear button with callback\n- Themed child elements via `variant` and `size` props\n- Supports standard, outlined, and filled input variants\n- Customizable button styling via `buttonStyle` prop\n- Works with Accordion, DatePicker, TextField, Checkbox, Switch, Radio, Select, Slider, and custom inputs\n\n## Default\n\nThe default example demonstrates FiltersWrapper with various filter controls organized in Accordion sections, including date pickers, text fields, checkboxes, switches, autocompletes, radio groups, selects, sliders, and custom inputs.\n\n```tsx\n// DefaultExample.tsx\nimport React, { useState, ChangeEvent } from 'react';\nimport {\n Autocomplete as MuiAutocomplete,\n Checkbox,\n FormControlLabel,\n MenuItem,\n Radio,\n RadioGroup,\n Select,\n Slider,\n Switch,\n TextField,\n SelectChangeEvent,\n} from '@mui/material';\nimport { LocalizationProvider } from '@mui/x-date-pickers-pro';\nimport { AdapterDayjs } from '@mui/x-date-pickers-pro/AdapterDayjs';\nimport { Settings } from '@mui/icons-material';\nimport { Accordion, Autocomplete, DatePicker, FiltersWrapper } from '@ringpublishing/mui-components';\n\nexport default function DefaultExample(): React.JSX.Element {\n const emptyFilters = {\n basicDatePicker: null,\n text: '',\n text2: '',\n checkbox: false,\n switch: false,\n radio: '',\n select: '',\n slider: 0,\n autocomplete: null,\n autocomplete2: [] as { label: string; id: number }[],\n custom: '',\n };\n const [filters, setFilters] = useState(emptyFilters);\n\n const options = [\n { label: 'Onet', id: 1 },\n { label: 'Fakt', id: 2 },\n { label: 'Komputer swiat', id: 3 },\n { label: 'Newsweek', id: 4 },\n { label: 'Forbes', id: 5 },\n { label: 'Business insider', id: 6 },\n ];\n\n function handleOnClear(): void {\n setFilters(emptyFilters);\n }\n\n // eslint-disable-next-line @typescript-eslint/no-explicit-any\n function onChange(fieldName: string, value: any): void {\n setFilters({ ...filters, [fieldName]: value });\n }\n\n return (\n <FiltersWrapper label=\"Filters\" withClearButton={true} clearButtonLabel=\"Clear\" onClear={handleOnClear}>\n <Accordion label=\"Basic\" defaultExpanded={true}>\n <LocalizationProvider dateAdapter={AdapterDayjs} adapterLocale={'en'}>\n <DatePicker\n onChange={(value): void => onChange('basicDatePicker', value)}\n label=\"Basic date picker\"\n value={filters.basicDatePicker}\n />\n </LocalizationProvider>\n\n <TextField\n label={'Text'}\n value={filters.text}\n onChange={(event: ChangeEvent<HTMLInputElement>): void => onChange('text', event.target.value)}\n />\n <TextField\n sx={{ marginTop: 1 }}\n label={'Text2'}\n value={filters.text2}\n onChange={(event: ChangeEvent<HTMLInputElement>): void => onChange('text2', event.target.value)}\n />\n\n <FormControlLabel\n label=\"Checkbox\"\n control={\n <Checkbox\n onChange={(event): void => onChange('checkbox', event.target.checked)}\n checked={filters.checkbox}\n />\n }\n />\n <FormControlLabel\n label=\"Switch\"\n control={\n <Switch\n onChange={(event): void => onChange('switch', event.target.checked)}\n checked={filters.switch}\n />\n }\n />\n\n <Autocomplete\n labels={{ title: 'Autocomplete2' }}\n options={options}\n actions={[\n {\n onClick: (): null => null,\n label: 'Settings',\n icon: <Settings />,\n },\n ]}\n onChange={(event, value): void => onChange('autocomplete2', value)}\n multiple={true}\n value={filters.autocomplete2}\n />\n\n <MuiAutocomplete\n options={options}\n value={filters.autocomplete}\n onChange={(event, value): void => onChange('autocomplete', value)}\n renderInput={(params): React.JSX.Element => <TextField {...params} label=\"Autocomplete\" />}\n />\n </Accordion>\n\n <Accordion label=\"Radio\">\n <RadioGroup\n onChange={(event): void => onChange('radio', (event.target as HTMLInputElement).value)}\n value={filters.radio}\n >\n <FormControlLabel value=\"opt1\" control={<Radio />} label=\"Option 1\" />\n <FormControlLabel value=\"opt2\" control={<Radio />} label=\"Option 2\" />\n </RadioGroup>\n </Accordion>\n\n <Accordion label=\"Select\">\n <FormControlLabel\n control={\n <Select\n onChange={(event: SelectChangeEvent<string>): void =>\n onChange('select', event.target.value)\n }\n value={filters.select}\n >\n <MenuItem value={10}>Ten</MenuItem>\n <MenuItem value={20}>Twenty</MenuItem>\n <MenuItem value={30}>Thirty</MenuItem>\n </Select>\n }\n label=\"units\"\n />\n </Accordion>\n\n <Accordion label=\"Slider\">\n <Slider\n valueLabelDisplay=\"auto\"\n max={10}\n step={1}\n value={filters.slider}\n onChange={(event, value): void => onChange('slider', value)}\n />\n </Accordion>\n\n <Accordion label=\"Custom\">\n <input onChange={(event): void => onChange('custom', event.target.value)} value={filters.custom} />\n </Accordion>\n </FiltersWrapper>\n );\n}\n```\n\n## How Theming Works\n\nFiltersWrapper uses a MUI `ThemeProvider` to override default props for child MUI components. The `variant` and `size` props apply to **all nested MUI form elements** (TextField, Select, Autocomplete, Checkbox, Radio, Switch, Slider, and Button), not to the wrapper itself. The `buttonStyle` prop similarly configures default size and variant for all `MuiButton` instances within the wrapper."
|
|
2580
|
-
},
|
|
2581
|
-
"organisms-light-box": {
|
|
2582
|
-
"id": "organisms-light-box",
|
|
2583
|
-
"name": "LightBox",
|
|
2584
|
-
"category": "Organisms",
|
|
2585
|
-
"title": "Components/Organisms/LightBox",
|
|
2586
|
-
"description": "A full-featured image viewer dialog with carousel navigation, zoom controls, and fullscreen support. Displays images in a separate dialog/gallery with smooth transitions and touch gesture support.",
|
|
2587
|
-
"argTypes": {
|
|
2588
|
-
"images": {
|
|
2589
|
-
"description": "An array of images with their source URLs, optional thumbnail URLs for carousel, and titles.",
|
|
2590
|
-
"control": "object",
|
|
2591
|
-
"category": "data",
|
|
2592
|
-
"type": "(Image & { id?: string | number })[]"
|
|
2593
|
-
},
|
|
2594
|
-
"open": {
|
|
2595
|
-
"description": "Whether the LightBox dialog is open.",
|
|
2596
|
-
"control": "boolean",
|
|
2597
|
-
"category": "behavior",
|
|
2598
|
-
"type": "boolean",
|
|
2599
|
-
"defaultValue": "false"
|
|
2600
|
-
},
|
|
2601
|
-
"onClose": {
|
|
2602
|
-
"description": "Callback function called when the LightBox is closed.",
|
|
2603
|
-
"control": false,
|
|
2604
|
-
"category": "callbacks",
|
|
2605
|
-
"type": "(event: object, reason?: 'escapeKeyDown' | 'backdropClick') => void"
|
|
2606
|
-
},
|
|
2607
|
-
"enableCarousel": {
|
|
2608
|
-
"description": "Whether to show the carousel of images at the bottom of the LightBox.",
|
|
2609
|
-
"control": "boolean",
|
|
2610
|
-
"category": "behavior",
|
|
2611
|
-
"type": "boolean",
|
|
2612
|
-
"defaultValue": "true"
|
|
2613
|
-
},
|
|
2614
|
-
"enableDownloadIcon": {
|
|
2615
|
-
"description": "Whether to show the download icon in the toolbar.",
|
|
2616
|
-
"control": "boolean",
|
|
2617
|
-
"category": "behavior",
|
|
2618
|
-
"type": "boolean",
|
|
2619
|
-
"defaultValue": "true"
|
|
2620
|
-
},
|
|
2621
|
-
"onImagesScrollEnd": {
|
|
2622
|
-
"description": "Callback function called when user scrolls to the end of the images for loading more.",
|
|
2623
|
-
"control": false,
|
|
2624
|
-
"category": "callbacks",
|
|
2625
|
-
"type": "() => void"
|
|
2626
|
-
},
|
|
2627
|
-
"moreImagesLoading": {
|
|
2628
|
-
"description": "Whether more images are currently being loaded and a loading indicator should be shown.",
|
|
2629
|
-
"control": "boolean",
|
|
2630
|
-
"category": "state",
|
|
2631
|
-
"type": "boolean"
|
|
2632
|
-
},
|
|
2633
|
-
"handleImageDownload": {
|
|
2634
|
-
"description": "Custom callback for the download button. Overrides default download behavior.",
|
|
2635
|
-
"control": false,
|
|
2636
|
-
"category": "callbacks",
|
|
2637
|
-
"type": "(image: Image) => void"
|
|
2638
|
-
},
|
|
2639
|
-
"onImageChange": {
|
|
2640
|
-
"description": "Callback function called when the displayed image changes.",
|
|
2641
|
-
"control": false,
|
|
2642
|
-
"category": "callbacks",
|
|
2643
|
-
"type": "(image?: Image & { id?: string | number }) => void"
|
|
2644
|
-
},
|
|
2645
|
-
"initialImageId": {
|
|
2646
|
-
"description": "Initial image ID to display when the LightBox is opened.",
|
|
2647
|
-
"control": "text",
|
|
2648
|
-
"category": "behavior",
|
|
2649
|
-
"type": "string | number"
|
|
2650
|
-
},
|
|
2651
|
-
"detail": {
|
|
2652
|
-
"description": "Detail panel props to show alongside the image with metadata, actions, and editable title.",
|
|
2653
|
-
"control": "object",
|
|
2654
|
-
"category": "content",
|
|
2655
|
-
"type": "DetailProps"
|
|
2656
|
-
},
|
|
2657
|
-
"sx": {
|
|
2658
|
-
"description": "MUI System properties to customize the main element style.",
|
|
2659
|
-
"control": "object",
|
|
2660
|
-
"category": "customization",
|
|
2661
|
-
"type": "SxProps<Theme>"
|
|
2662
|
-
},
|
|
2663
|
-
"className": {
|
|
2664
|
-
"description": "CSS class name applied to the main element.",
|
|
2665
|
-
"control": "text",
|
|
2666
|
-
"category": "customization",
|
|
2667
|
-
"type": "string"
|
|
2668
|
-
},
|
|
2669
|
-
"dataTestIdSuffix": {
|
|
2670
|
-
"description": "Optional suffix for generated test id (base: ring-light-box).",
|
|
2671
|
-
"control": "text",
|
|
2672
|
-
"category": "customization",
|
|
2673
|
-
"type": "string"
|
|
2674
|
-
}
|
|
2675
|
-
},
|
|
2676
|
-
"storyNames": [
|
|
2677
|
-
"Default",
|
|
2678
|
-
"SingleImage",
|
|
2679
|
-
"WithInfiniteScroll",
|
|
2680
|
-
"WithCustomDownloadImage",
|
|
2681
|
-
"WithHideDownloadIcon",
|
|
2682
|
-
"WithDetail",
|
|
2683
|
-
"WithInitialImageId"
|
|
2684
|
-
],
|
|
2685
|
-
"docs": "# LightBox\n\nA full-featured image viewer dialog with carousel navigation, zoom controls, and fullscreen support. Displays images in a separate dialog/gallery with smooth transitions and touch gesture support.\n\n- Navigate through multiple images with arrow keys or carousel\n- Zoom in/out with mouse wheel or pinch gestures\n- Fullscreen mode support\n- Image download capability with custom handler option\n- Optional detail panel with metadata, actions, and editable title\n- Infinite scroll for loading additional images on demand\n- Keyboard navigation (arrow keys, Escape to close)\n\n## Default\n\nThe default LightBox with multiple images and a carousel at the bottom. Click the button to open the viewer, then navigate with arrows or the carousel thumbnails.\n\n```tsx\n// DefaultExample.tsx\nimport React from 'react';\nimport { Button } from '@mui/material';\nimport { LightBox } from '@ringpublishing/mui-components';\nimport { getImagePath, TestImage, ImageSize } from 'RingDemoImages';\n\nexport default function DefaultExample(): React.JSX.Element {\n const [open, setOpen] = React.useState(false);\n const images = [\n {\n src: getImagePath(TestImage.MOUNTAINS, ImageSize.LARGE),\n thumbnailSrc: getImagePath(TestImage.MOUNTAINS, ImageSize.LARGE),\n title: TestImage.MOUNTAINS,\n },\n {\n src: getImagePath(TestImage.STAIRS, ImageSize.LARGE),\n thumbnailSrc: getImagePath(TestImage.STAIRS, ImageSize.LARGE),\n title: TestImage.STAIRS,\n },\n {\n src: getImagePath(TestImage.ISLAND, ImageSize.SMALL),\n thumbnailSrc: getImagePath(TestImage.ISLAND, ImageSize.SMALL),\n title: TestImage.ISLAND,\n },\n {\n src: getImagePath(TestImage.RIVER, ImageSize.LARGE),\n thumbnailSrc: getImagePath(TestImage.RIVER, ImageSize.LARGE),\n title: TestImage.RIVER,\n },\n {\n src: getImagePath(TestImage.FOREST_2, ImageSize.LARGE),\n thumbnailSrc: getImagePath(TestImage.FOREST_2, ImageSize.LARGE),\n title: TestImage.FOREST_2,\n },\n {\n src: getImagePath(TestImage.APARTMENT, ImageSize.MEDIUM),\n thumbnailSrc: getImagePath(TestImage.APARTMENT, ImageSize.MEDIUM),\n title: TestImage.APARTMENT,\n },\n {\n src: getImagePath(TestImage.CAR, ImageSize.LARGE),\n thumbnailSrc: getImagePath(TestImage.CAR, ImageSize.LARGE),\n title: TestImage.CAR,\n },\n {\n src: getImagePath(TestImage.ORCHARD, ImageSize.LARGE),\n thumbnailSrc: getImagePath(TestImage.ORCHARD, ImageSize.LARGE),\n title: TestImage.ORCHARD,\n },\n ];\n\n return (\n <div style={{ display: 'flex', justifyContent: 'center', alignItems: 'center' }}>\n <Button variant=\"outlined\" color=\"primary\" disableRipple={true} onClick={(): void => setOpen(true)}>\n Click me!\n </Button>\n <LightBox images={images} onClose={(): void => setOpen(false)} open={open} />\n </div>\n );\n}\n```\n\n## Single Image\n\nLightBox with a single image. When only one image is provided, the carousel and navigation arrows are hidden.\n\n```tsx\n// SingleImageExample.tsx\nimport React from 'react';\nimport { Button } from '@mui/material';\nimport { LightBox } from '@ringpublishing/mui-components';\nimport { getImagePath, TestImage, ImageSize } from 'RingDemoImages';\n\nexport default function SingleImageExample(): React.JSX.Element {\n const [open, setOpen] = React.useState(false);\n const images = [\n {\n src: getImagePath(TestImage.MOUNTAINS, ImageSize.LARGE),\n thumbnailSrc: getImagePath(TestImage.MOUNTAINS, ImageSize.LARGE),\n title: TestImage.MOUNTAINS,\n },\n ];\n\n return (\n <div style={{ display: 'flex', justifyContent: 'center', alignItems: 'center' }}>\n <Button variant=\"outlined\" color=\"primary\" disableRipple={true} onClick={(): void => setOpen(true)}>\n Click me!\n </Button>\n <LightBox images={images} onClose={(): void => setOpen(false)} open={open} />\n </div>\n );\n}\n```\n\n## With Infinite Scroll\n\nDemonstrates lazy loading of additional images when the user scrolls to the end of the carousel. Uses `onImagesScrollEnd` callback and `moreImagesLoading` indicator.\n\n```tsx\n// WithInfiniteScrollExample.tsx\nimport React from 'react';\nimport { Button } from '@mui/material';\nimport { LightBox, Image } from '@ringpublishing/mui-components';\nimport { getImagePath, TestImage, ImageSize, getRandomImage, getRandomImageSize } from 'RingDemoImages';\n\nfunction generateImages(count: number): Image[] {\n return Array.from({ length: count }, (): Image => {\n const image = getRandomImage();\n const size = getRandomImageSize();\n\n return {\n src: getImagePath(image, size),\n thumbnailSrc: getImagePath(image, size),\n title: image,\n };\n });\n}\n\nexport default function WithInfiniteScrollExample(): React.JSX.Element {\n const [open, setOpen] = React.useState(false);\n const [currentImages, setCurrentImages] = React.useState<Image[]>([\n {\n src: getImagePath(TestImage.MOUNTAINS, ImageSize.LARGE),\n thumbnailSrc: getImagePath(TestImage.MOUNTAINS, ImageSize.LARGE),\n title: TestImage.MOUNTAINS,\n },\n {\n src: getImagePath(TestImage.STAIRS, ImageSize.LARGE),\n thumbnailSrc: getImagePath(TestImage.STAIRS, ImageSize.LARGE),\n title: TestImage.STAIRS,\n },\n {\n src: getImagePath(TestImage.ISLAND, ImageSize.SMALL),\n thumbnailSrc: getImagePath(TestImage.ISLAND, ImageSize.SMALL),\n title: TestImage.ISLAND,\n },\n {\n src: getImagePath(TestImage.RIVER, ImageSize.LARGE),\n thumbnailSrc: getImagePath(TestImage.RIVER, ImageSize.LARGE),\n title: TestImage.RIVER,\n },\n {\n src: getImagePath(TestImage.FOREST_2, ImageSize.LARGE),\n thumbnailSrc: getImagePath(TestImage.FOREST_2, ImageSize.LARGE),\n title: TestImage.FOREST_2,\n },\n {\n src: getImagePath(TestImage.APARTMENT, ImageSize.MEDIUM),\n thumbnailSrc: getImagePath(TestImage.APARTMENT, ImageSize.MEDIUM),\n title: TestImage.APARTMENT,\n },\n {\n src: getImagePath(TestImage.CAR, ImageSize.LARGE),\n thumbnailSrc: getImagePath(TestImage.CAR, ImageSize.LARGE),\n title: TestImage.CAR,\n },\n {\n src: getImagePath(TestImage.ORCHARD, ImageSize.LARGE),\n thumbnailSrc: getImagePath(TestImage.ORCHARD, ImageSize.LARGE),\n title: TestImage.ORCHARD,\n },\n ]);\n const [moreImagesLoading, setMoreImagesLoading] = React.useState(false);\n\n return (\n <div style={{ display: 'flex', justifyContent: 'center', alignItems: 'center' }}>\n <Button variant=\"outlined\" color=\"primary\" disableRipple={true} onClick={(): void => setOpen(true)}>\n Click me!\n </Button>\n <LightBox\n images={currentImages}\n onClose={(): void => setOpen(false)}\n open={open}\n moreImagesLoading={moreImagesLoading}\n onImagesScrollEnd={(): void => {\n setMoreImagesLoading(true);\n setTimeout((): void => {\n const newImages = generateImages(currentImages.length);\n setCurrentImages([...currentImages, ...newImages]);\n setMoreImagesLoading(false);\n }, 1500);\n }}\n />\n </div>\n );\n}\n```\n\n## With Custom Download Image\n\nOverrides the default download behavior with a custom `handleImageDownload` callback. Useful when images need to be downloaded from a different source or require authentication.\n\n```tsx\n// WithCustomDownloadImageExample.tsx\nimport React from 'react';\nimport { Button } from '@mui/material';\nimport { LightBox } from '@ringpublishing/mui-components';\nimport { getImagePath, TestImage, ImageSize } from 'RingDemoImages';\n\nexport default function WithCustomDownloadImageExample(): React.JSX.Element {\n const [open, setOpen] = React.useState(false);\n const images = [\n {\n src: getImagePath(TestImage.MOUNTAINS, ImageSize.LARGE),\n thumbnailSrc: getImagePath(TestImage.MOUNTAINS, ImageSize.LARGE),\n title: TestImage.MOUNTAINS,\n },\n {\n src: getImagePath(TestImage.STAIRS, ImageSize.LARGE),\n thumbnailSrc: getImagePath(TestImage.STAIRS, ImageSize.LARGE),\n title: TestImage.STAIRS,\n },\n {\n src: getImagePath(TestImage.ISLAND, ImageSize.SMALL),\n thumbnailSrc: getImagePath(TestImage.ISLAND, ImageSize.SMALL),\n title: TestImage.ISLAND,\n },\n {\n src: getImagePath(TestImage.RIVER, ImageSize.LARGE),\n thumbnailSrc: getImagePath(TestImage.RIVER, ImageSize.LARGE),\n title: TestImage.RIVER,\n },\n {\n src: getImagePath(TestImage.FOREST_2, ImageSize.LARGE),\n thumbnailSrc: getImagePath(TestImage.FOREST_2, ImageSize.LARGE),\n title: TestImage.FOREST_2,\n },\n {\n src: getImagePath(TestImage.APARTMENT, ImageSize.MEDIUM),\n thumbnailSrc: getImagePath(TestImage.APARTMENT, ImageSize.MEDIUM),\n title: TestImage.APARTMENT,\n },\n {\n src: getImagePath(TestImage.CAR, ImageSize.LARGE),\n thumbnailSrc: getImagePath(TestImage.CAR, ImageSize.LARGE),\n title: TestImage.CAR,\n },\n {\n src: getImagePath(TestImage.ORCHARD, ImageSize.LARGE),\n thumbnailSrc: getImagePath(TestImage.ORCHARD, ImageSize.LARGE),\n title: TestImage.ORCHARD,\n },\n ];\n\n return (\n <div style={{ display: 'flex', justifyContent: 'center', alignItems: 'center' }}>\n <Button variant=\"outlined\" color=\"primary\" disableRipple={true} onClick={(): void => setOpen(true)}>\n Click me!\n </Button>\n <LightBox\n images={images}\n handleImageDownload={(image) => {\n console.log('Download image', image);\n }}\n onClose={(): void => setOpen(false)}\n open={open}\n />\n </div>\n );\n}\n```\n\n## With Hide Download Icon\n\nHides the download button in the toolbar by setting `enableDownloadIcon` to `false`.\n\n```tsx\n// WithHideDownloadIconExample.tsx\nimport React from 'react';\nimport { Button } from '@mui/material';\nimport { LightBox } from '@ringpublishing/mui-components';\nimport { getImagePath, TestImage, ImageSize } from 'RingDemoImages';\n\nexport default function WithHideDownloadIconExample(): React.JSX.Element {\n const [open, setOpen] = React.useState(false);\n const images = [\n {\n src: getImagePath(TestImage.MOUNTAINS, ImageSize.LARGE),\n thumbnailSrc: getImagePath(TestImage.MOUNTAINS, ImageSize.LARGE),\n title: TestImage.MOUNTAINS,\n },\n {\n src: getImagePath(TestImage.STAIRS, ImageSize.LARGE),\n thumbnailSrc: getImagePath(TestImage.STAIRS, ImageSize.LARGE),\n title: TestImage.STAIRS,\n },\n {\n src: getImagePath(TestImage.ISLAND, ImageSize.SMALL),\n thumbnailSrc: getImagePath(TestImage.ISLAND, ImageSize.SMALL),\n title: TestImage.ISLAND,\n },\n {\n src: getImagePath(TestImage.RIVER, ImageSize.LARGE),\n thumbnailSrc: getImagePath(TestImage.RIVER, ImageSize.LARGE),\n title: TestImage.RIVER,\n },\n ];\n\n return (\n <div style={{ display: 'flex', justifyContent: 'center', alignItems: 'center' }}>\n <Button variant=\"outlined\" color=\"primary\" disableRipple={true} onClick={(): void => setOpen(true)}>\n Click me!\n </Button>\n <LightBox images={images} enableDownloadIcon={false} onClose={(): void => setOpen(false)} open={open} />\n </div>\n );\n}\n```\n\n## With Detail\n\nShows a detail panel alongside the image with metadata sections, action buttons, and an editable title. The detail panel supports description items with various field types (text, chips, dates) and bottom action buttons.\n\n### Key Features:\n\n- Editable title field\n- Description items organized in sections\n- Action buttons with icons and URLs or click handlers\n- Collapsable chip fields for tags\n\n```tsx\n// WithDetailExample.tsx\nimport React from 'react';\nimport { Button } from '@mui/material';\nimport { Download, Public, Web } from '@mui/icons-material';\nimport {\n DetailDescriptionItemFieldLayout,\n DetailDescriptionItemFieldType,\n LightBox,\n LightBoxProps,\n} from '@ringpublishing/mui-components';\nimport { getImagePath, TestImage, ImageSize } from 'RingDemoImages';\n\nexport default function WithDetailExample(): React.JSX.Element {\n const [open, setOpen] = React.useState(false);\n const images = [\n {\n src: getImagePath(TestImage.MOUNTAINS, ImageSize.LARGE),\n thumbnailSrc: getImagePath(TestImage.MOUNTAINS, ImageSize.LARGE),\n title: TestImage.MOUNTAINS,\n },\n {\n src: getImagePath(TestImage.STAIRS, ImageSize.LARGE),\n thumbnailSrc: getImagePath(TestImage.STAIRS, ImageSize.LARGE),\n title: TestImage.STAIRS,\n },\n {\n src: getImagePath(TestImage.ISLAND, ImageSize.SMALL),\n thumbnailSrc: getImagePath(TestImage.ISLAND, ImageSize.SMALL),\n title: TestImage.ISLAND,\n },\n {\n src: getImagePath(TestImage.RIVER, ImageSize.LARGE),\n thumbnailSrc: getImagePath(TestImage.RIVER, ImageSize.LARGE),\n title: TestImage.RIVER,\n },\n ];\n\n const detail = {\n bottomActions: [\n {\n name: 'ACTION WITH URL',\n url: 'https://video.onet.pl/',\n icon: <Web />,\n },\n {\n name: 'ACTION WITH ON CLICK',\n onClick: () => console.log('Action clicked'),\n icon: <Download />,\n },\n {\n name: 'ACTION WITHOUT ICON',\n onClick: () => console.log('Action clicked'),\n },\n ],\n descriptionItems: [\n {\n sectionTitle: 'IMAGE DETAILS',\n fields: [\n {\n name: 'DESCRIPTION',\n type: DetailDescriptionItemFieldType.DESCRIPTION,\n maxLength: 100,\n layout: DetailDescriptionItemFieldLayout.VERTICAL,\n showMoreLabel: 'Show more',\n showLessLabel: 'Show less',\n value:\n 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.' +\n ' Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.',\n },\n {\n icon: <Public />,\n name: 'STATUS',\n value: 'Published',\n },\n {\n formatDate: true,\n name: 'CREATED',\n value: '2023-07-27T09:32:09Z',\n },\n {\n formatDate: true,\n name: 'MODIFIED',\n value: '2023-08-31T21:59:59Z',\n },\n ],\n },\n {\n fields: [\n {\n name: 'TAGS',\n type: DetailDescriptionItemFieldType.CHIPS,\n value: ['photography', 'landscape', 'nature'],\n collapsable: true,\n },\n {\n name: 'PHOTOGRAPHER',\n value: 'John Doe',\n },\n {\n name: 'LOCATION',\n value: 'New York, USA',\n },\n ],\n sectionTitle: 'METADATA',\n },\n ],\n main: {\n title: {\n value: 'Test title lorem ipsum',\n editable: true,\n onSubmit: function cb(): Promise<boolean> {\n return new Promise((resolve) => {\n resolve(true);\n });\n },\n label: 'Title',\n },\n },\n };\n\n return (\n <div style={{ display: 'flex', justifyContent: 'center', alignItems: 'center' }}>\n <Button variant=\"outlined\" color=\"primary\" disableRipple={true} onClick={(): void => setOpen(true)}>\n Click me!\n </Button>\n <LightBox\n images={images}\n onClose={(): void => setOpen(false)}\n open={open}\n detail={detail as LightBoxProps['detail']}\n onImageChange={(image) => {\n console.log('Image changed:', image);\n }}\n />\n </div>\n );\n}\n```\n\n## With Initial Image Id\n\nOpens the LightBox at a specific image by providing `initialImageId`. Each image must have a unique `id` field for this to work.\n\n```tsx\n// WithInitialImageIdExample.tsx\nimport React from 'react';\nimport { Button } from '@mui/material';\nimport { LightBox } from '@ringpublishing/mui-components';\nimport { getImagePath, TestImage, ImageSize } from 'RingDemoImages';\n\nexport default function WithInitialImageIdExample(): React.JSX.Element {\n const [open, setOpen] = React.useState(false);\n const images = [\n {\n id: 'image-1',\n src: getImagePath(TestImage.MOUNTAINS, ImageSize.LARGE),\n thumbnailSrc: getImagePath(TestImage.MOUNTAINS, ImageSize.LARGE),\n title: TestImage.MOUNTAINS,\n },\n {\n id: 'image-2',\n src: getImagePath(TestImage.STAIRS, ImageSize.LARGE),\n thumbnailSrc: getImagePath(TestImage.STAIRS, ImageSize.LARGE),\n title: TestImage.STAIRS,\n },\n {\n id: 'image-3',\n src: getImagePath(TestImage.ISLAND, ImageSize.SMALL),\n thumbnailSrc: getImagePath(TestImage.ISLAND, ImageSize.SMALL),\n title: TestImage.ISLAND,\n },\n {\n id: 'image-4',\n src: getImagePath(TestImage.RIVER, ImageSize.LARGE),\n thumbnailSrc: getImagePath(TestImage.RIVER, ImageSize.LARGE),\n title: TestImage.RIVER,\n },\n {\n id: 'image-5',\n src: getImagePath(TestImage.FOREST_2, ImageSize.LARGE),\n thumbnailSrc: getImagePath(TestImage.FOREST_2, ImageSize.LARGE),\n title: TestImage.FOREST_2,\n },\n {\n id: 'image-6',\n src: getImagePath(TestImage.APARTMENT, ImageSize.MEDIUM),\n thumbnailSrc: getImagePath(TestImage.APARTMENT, ImageSize.MEDIUM),\n title: TestImage.APARTMENT,\n },\n {\n id: 'image-7',\n src: getImagePath(TestImage.CAR, ImageSize.LARGE),\n thumbnailSrc: getImagePath(TestImage.CAR, ImageSize.LARGE),\n title: TestImage.CAR,\n },\n {\n id: 'image-8',\n src: getImagePath(TestImage.ORCHARD, ImageSize.LARGE),\n thumbnailSrc: getImagePath(TestImage.ORCHARD, ImageSize.LARGE),\n title: TestImage.ORCHARD,\n },\n ];\n\n return (\n <div style={{ display: 'flex', justifyContent: 'center', alignItems: 'center' }}>\n <Button variant=\"outlined\" color=\"primary\" disableRipple={true} onClick={(): void => setOpen(true)}>\n Click me!\n </Button>\n <LightBox images={images} onClose={(): void => setOpen(false)} open={open} initialImageId=\"image-5\" />\n </div>\n );\n}\n```"
|
|
2686
|
-
},
|
|
2687
|
-
"organisms-media-card": {
|
|
2688
|
-
"id": "organisms-media-card",
|
|
2689
|
-
"name": "MediaCard",
|
|
2690
|
-
"category": "Organisms",
|
|
2691
|
-
"title": "Components/Organisms/MediaCard",
|
|
2692
|
-
"description": "MediaCard is a versatile component for displaying multimedia resources such as photos, videos, podcasts along with additional information and actions.",
|
|
2693
|
-
"argTypes": {
|
|
2694
|
-
"title": {
|
|
2695
|
-
"description": "Title for the resource card.",
|
|
2696
|
-
"control": "text",
|
|
2697
|
-
"category": "content",
|
|
2698
|
-
"type": "string"
|
|
2699
|
-
},
|
|
2700
|
-
"image": {
|
|
2701
|
-
"description": "URL of the image. When not provided, an empty image placeholder is displayed.",
|
|
2702
|
-
"control": "text",
|
|
2703
|
-
"category": "content",
|
|
2704
|
-
"type": "string"
|
|
2705
|
-
},
|
|
2706
|
-
"fields": {
|
|
2707
|
-
"description": "Fields describing the card.",
|
|
2708
|
-
"control": "object",
|
|
2709
|
-
"category": "content",
|
|
2710
|
-
"type": "MediaCardFieldsItem[]"
|
|
2711
|
-
},
|
|
2712
|
-
"iconPlaceholder": {
|
|
2713
|
-
"description": "Icon for the placeholder.",
|
|
2714
|
-
"control": "text",
|
|
2715
|
-
"category": "content",
|
|
2716
|
-
"type": "ReactNode",
|
|
2717
|
-
"defaultValue": "<PhotoOutlined />"
|
|
2718
|
-
},
|
|
2719
|
-
"actions": {
|
|
2720
|
-
"description": "Actions list shown in Action Box.",
|
|
2721
|
-
"control": "object",
|
|
2722
|
-
"category": "content",
|
|
2723
|
-
"type": "Action[]"
|
|
2724
|
-
},
|
|
2725
|
-
"statusLabels": {
|
|
2726
|
-
"description": "Collection of status labels displayed over the image in the left top corner.",
|
|
2727
|
-
"control": "object",
|
|
2728
|
-
"category": "content",
|
|
2729
|
-
"type": "StatusLabelProps[]"
|
|
2730
|
-
},
|
|
2731
|
-
"variant": {
|
|
2732
|
-
"description": "The variant to use.",
|
|
2733
|
-
"control": "select",
|
|
2734
|
-
"category": "appearance",
|
|
2735
|
-
"type": "'outlined' | 'elevation'",
|
|
2736
|
-
"defaultValue": "outlined",
|
|
2737
|
-
"options": [
|
|
2738
|
-
"outlined",
|
|
2739
|
-
"elevation"
|
|
2740
|
-
]
|
|
2741
|
-
},
|
|
2742
|
-
"square": {
|
|
2743
|
-
"description": "If true, rounded corners are disabled.",
|
|
2744
|
-
"control": "boolean",
|
|
2745
|
-
"category": "appearance",
|
|
2746
|
-
"type": "boolean",
|
|
2747
|
-
"defaultValue": "false"
|
|
2748
|
-
},
|
|
2749
|
-
"ratio": {
|
|
2750
|
-
"description": "Aspect ratio of the image (e.g., \"16/9\", \"4/3\", \"1/1\").",
|
|
2751
|
-
"control": "text",
|
|
2752
|
-
"category": "appearance",
|
|
2753
|
-
"type": "string | number",
|
|
2754
|
-
"defaultValue": "4/3"
|
|
2755
|
-
},
|
|
2756
|
-
"objectFit": {
|
|
2757
|
-
"description": "How the image should fit.",
|
|
2758
|
-
"control": "select",
|
|
2759
|
-
"category": "appearance",
|
|
2760
|
-
"type": "'contain' | 'cover' | 'fill' | 'none' | 'scale-down'",
|
|
2761
|
-
"defaultValue": "cover",
|
|
2762
|
-
"options": [
|
|
2763
|
-
"contain",
|
|
2764
|
-
"cover",
|
|
2765
|
-
"fill",
|
|
2766
|
-
"none",
|
|
2767
|
-
"scale-down"
|
|
2768
|
-
]
|
|
2769
|
-
},
|
|
2770
|
-
"hoverable": {
|
|
2771
|
-
"description": "Specifies whether the component is hoverable.",
|
|
2772
|
-
"control": "boolean",
|
|
2773
|
-
"category": "state",
|
|
2774
|
-
"type": "boolean",
|
|
2775
|
-
"defaultValue": "false"
|
|
2776
|
-
},
|
|
2777
|
-
"active": {
|
|
2778
|
-
"description": "Specifies whether the component is active (visually highlighted).",
|
|
2779
|
-
"control": "boolean",
|
|
2780
|
-
"category": "state",
|
|
2781
|
-
"type": "boolean",
|
|
2782
|
-
"defaultValue": "false"
|
|
2783
|
-
},
|
|
2784
|
-
"onClick": {
|
|
2785
|
-
"description": "Callback fired when the component is clicked.",
|
|
2786
|
-
"category": "callbacks",
|
|
2787
|
-
"type": "() => void"
|
|
2788
|
-
},
|
|
2789
|
-
"slots": {
|
|
2790
|
-
"description": "The components used for each slot inside. See the **Slots** section below.",
|
|
2791
|
-
"control": "object",
|
|
2792
|
-
"category": "customization",
|
|
2793
|
-
"type": "object"
|
|
2794
|
-
},
|
|
2795
|
-
"slotProps": {
|
|
2796
|
-
"description": "The props used for each slot inside. See the **Slot props** section below.",
|
|
2797
|
-
"control": "object",
|
|
2798
|
-
"category": "customization",
|
|
2799
|
-
"type": "object"
|
|
2800
|
-
},
|
|
2801
|
-
"slots.mediaCard": {
|
|
2802
|
-
"description": "Custom React node rendered in place of the default `<CardMedia>`. Wrapped in `<AspectRatio>` so `ratio` and `objectFit` still apply to the surrounding box.",
|
|
2803
|
-
"control": false,
|
|
2804
|
-
"category": "slots",
|
|
2805
|
-
"type": "ReactNode"
|
|
2806
|
-
},
|
|
2807
|
-
"slots.footer": {
|
|
2808
|
-
"description": "Optional custom footer rendered below the card content (inside `<CardActions>`).",
|
|
2809
|
-
"control": false,
|
|
2810
|
-
"category": "slots",
|
|
2811
|
-
"type": "ReactNode"
|
|
2812
|
-
},
|
|
2813
|
-
"slotProps.card": {
|
|
2814
|
-
"description": "Props applied to the root MUI `<Card>`. **Recommended channel for DOM events** (`onMouseEnter`, `onMouseLeave`, `onFocus`, `onKeyDown`, `aria-*`, `data-*`, …). Top-level MediaCardProps (`variant`, `square`, `onClick`, `tabIndex`, `className`, `sx`) take precedence and are merged on top.",
|
|
2815
|
-
"control": false,
|
|
2816
|
-
"category": "slotProps",
|
|
2817
|
-
"type": "Omit<CardProps, \"children\" | \"variant\" | \"square\" | \"onClick\" | \"tabIndex\" | \"elevation\">"
|
|
2818
|
-
},
|
|
2819
|
-
"slotProps.cardMedia": {
|
|
2820
|
-
"description": "Props applied to the default `<CardMedia>`. Used only when `slots.mediaCard` is **not** provided. Lets you switch the underlying element (`component: \"video\" | \"audio\" | \"img\"`), tweak `src`, etc.",
|
|
2821
|
-
"control": false,
|
|
2822
|
-
"category": "slotProps",
|
|
2823
|
-
"type": "CardMediaProps"
|
|
2824
|
-
},
|
|
2825
|
-
"slotProps.checkbox": {
|
|
2826
|
-
"description": "Props applied to the selection `<Checkbox>`. The custom `showOnHover` flag hides the checkbox until the card is hovered (useful for grids). When `undefined`, the checkbox is not rendered.",
|
|
2827
|
-
"control": false,
|
|
2828
|
-
"category": "slotProps",
|
|
2829
|
-
"type": "CheckboxProps & { showOnHover?: boolean }"
|
|
2830
|
-
},
|
|
2831
|
-
"slotProps.footer": {
|
|
2832
|
-
"description": "Props applied to the `<CardActions>` element wrapping `slots.footer` (e.g. `sx`, `disableSpacing`).",
|
|
2833
|
-
"control": false,
|
|
2834
|
-
"category": "slotProps",
|
|
2835
|
-
"type": "CardActionsProps"
|
|
2836
|
-
}
|
|
2837
|
-
},
|
|
2838
|
-
"storyNames": [
|
|
2839
|
-
"Default",
|
|
2840
|
-
"AspectRatio",
|
|
2841
|
-
"Placeholder",
|
|
2842
|
-
"Actions",
|
|
2843
|
-
"StatusLabels",
|
|
2844
|
-
"Hoverable",
|
|
2845
|
-
"Checkbox",
|
|
2846
|
-
"Slots",
|
|
2847
|
-
"CardEvents",
|
|
2848
|
-
"AdvancedExample",
|
|
2849
|
-
"CustomTooltips"
|
|
2850
|
-
],
|
|
2851
|
-
"docs": "# MediaCard\n\nMediaCard is a versatile component for displaying multimedia resources such as photos, videos, podcasts along with additional information and actions.\n\n- **Media Display** - handles images, videos, and custom elements\n- **Customization** - configurable appearance with different aspect ratios and fitting methods\n- **Status Labels** - ability to display status labels over the image and control their visibility on hover\n- **Actions** - set of actions available to the user\n- **Selection** - optional checkbox for card selection\n- **Focus Management** - visual effects when focusing and interacting\n- **Information Fields** - ability to add descriptions below the image\n\nThe component is built with flexibility in mind and can be used in various scenarios - from photo galleries to advanced asset management interfaces.\n\n## Default\n\nBasic configuration of the MediaCard component with the most commonly used properties.\n\n### Available Variants\n\nMediaCard supports the following main variants:\n\n- **outlined** (default) - card with a border\n- **elevation** - card with a shadow\n\n### Basic Properties\n\n| Property | Type | Default | Description |\n| ----------- | ---------------------------------------------------------- | ------------ | ------------------------------- |\n| `title` | `string` | - | Title of the card |\n| `variant` | `'outlined' \\| 'elevation'` | `'outlined'` | Style of the card |\n| `square` | `boolean` | `false` | Disable rounded corners |\n| `ratio` | `string \\| number` | `'4/3'` | Aspect ratio of the image |\n| `objectFit` | `'contain' \\| 'cover' \\| 'fill' \\| 'none' \\| 'scale-down'` | `'cover'` | How the image should fit |\n| `image` | `string` | - | URL of the image |\n| `fields` | `MediaCardFieldsItem[]` | - | List of fields with information |\n\n```jsx\n<MediaCard\n title=\"Resource title\"\n variant=\"outlined\"\n square={false}\n image=\"https://example.com/image.jpg\"\n ratio=\"16/9\"\n objectFit=\"cover\"\n fields={[{ value: 'Author / Source' }, { value: 'Brief description or summary of the content' }]}\n sx={{ width: '300px' }}\n/>\n```\n\n```tsx\n// DefaultExample.tsx\nimport React, { useState } from 'react';\nimport { MediaCard } from '@ringpublishing/mui-components';\nimport { Download, Link } from '@mui/icons-material';\nimport { getImagePath, TestImage, ImageSize } from 'RingDemoImages';\n\nexport default function DefaultExample(): React.JSX.Element {\n const [active, setActive] = useState(false);\n const handleSelectChange = (): void => setActive(!active);\n const [checked, setChecked] = useState(false);\n const handleCheckboxChange = (event: React.MouseEvent): void => {\n setChecked(!checked);\n event.stopPropagation();\n };\n const actions = [\n {\n label: 'Action 1',\n icon: <Download />,\n },\n {\n label: 'Action 2',\n icon: <Link />,\n },\n ];\n const fields = [\n { value: 'Source / Author' },\n { value: 'Brief description or summary of the content' },\n { value: 'Space for comments or additional information that may take up more space' },\n ];\n\n return (\n <MediaCard\n sx={{ width: '300px' }}\n title=\"Title / name\"\n fields={fields}\n actions={actions}\n image={getImagePath(TestImage.ISLAND, ImageSize.MEDIUM)}\n ratio=\"16/9\"\n objectFit=\"fill\"\n hoverable={true}\n active={active}\n onClick={handleSelectChange}\n slotProps={{\n checkbox: {\n checked,\n onClick: handleCheckboxChange,\n },\n }}\n statusLabels={[\n {\n label: 'downloaded',\n color: 'success',\n icon: <Download />,\n },\n ]}\n />\n );\n}\n```\n\n## Aspect Ratio\n\nThe MediaCard component allows you to control the aspect ratio of the displayed image using the `ratio` prop.\n\n- Default aspect ratio is `4/3`\n- You can change the ratio by providing a custom value, e.g., `9/16`, `4/3`, `1/1`, etc.\n\n### Image Fitting (objectFit)\n\nThe `objectFit` prop determines how the image should be fitted within the MediaCard dimensions.\n\n| Parameter | Description |\n| ------------ | ------------------------------------------------------------------------------------------- |\n| `contain` | The image will fit entirely within the space while maintaining its aspect ratio |\n| `cover` | The image will fill the entire space while maintaining its aspect ratio, but may be cropped |\n| `fill` | The image will fill the space without maintaining aspect ratio |\n| `none` | The image will retain its original dimensions |\n| `scale-down` | Similar to contain, but never enlarges the image beyond its natural size |\n\n### Image Behavior\n\n- If the image aspect ratio differs from the MediaCard's set ratio, the image will be adjusted according to the `objectFit` value\n- With `objectFit: \"cover\"`, the image may be cropped to fill the entire space\n- With `objectFit: \"contain\"`, the entire image will be visible, but there may be empty spaces\n\n```jsx\n<MediaCard ratio=\"9/16\" objectFit=\"cover\" />\n<MediaCard ratio={1} objectFit=\"contain\" />\n<MediaCard ratio=\"4/3\" objectFit=\"fill\" />\n```\n\n```tsx\n// AspectRatioExample.tsx\nimport React from 'react';\nimport { MediaCard } from '@ringpublishing/mui-components';\nimport { getImagePath, TestImage, ImageSize } from 'RingDemoImages';\n\nexport default function AspectRatioExample(): React.JSX.Element {\n const fields = [{ value: 'Source / Author' }];\n\n return (\n <MediaCard\n sx={{ width: '300px' }}\n title=\"Title / name\"\n fields={fields}\n image={getImagePath(TestImage.STREET_3, ImageSize.MEDIUM)}\n objectFit=\"contain\"\n ratio=\"4/3\"\n />\n );\n}\n```\n\n## Placeholder\n\nThe MediaCard component displays a placeholder when the media source is unavailable.\n\nBy default, it shows the MUI `PhotoOutlined` icon as a placeholder.\nYou can customize the placeholder icon by passing a different icon through the `iconPlaceholder` property.\n\n```jsx\n\n<MediaCard iconPlaceholder={<VideocamOutlined />} />;\n```\n\nThis feature ensures that the MediaCard always has a visual representation, even when media content is not available, improving the user experience and maintaining layout consistency.\n\n```tsx\n// PlaceholderExample.tsx\nimport React from 'react';\nimport { MediaCard } from '@ringpublishing/mui-components';\n\nexport default function PlaceholderExample(): React.JSX.Element {\n const fields = [{ value: 'Source / Author' }];\n\n return <MediaCard sx={{ width: '300px' }} title=\"Title / name\" fields={fields} />;\n}\n```\n\n## Actions\n\nThe MediaCard component has been extended with a \"show more\" button functionality. This additional option allows for displaying extra actions related to the card's content.\n\nThe \"show more\" functionality utilizes the `ActionBox` component, which accepts an array of actions conforming to the `Action` interface.\n\n### Notes\n\n- Actions are rendered in the order they are defined in the array.\n- Disabled actions are still visible but cannot be clicked.\n- Icons are optional and can be omitted if not needed.\n\n```tsx\n// ActionsExample.tsx\nimport React from 'react';\nimport { MediaCard } from '@ringpublishing/mui-components';\nimport { Download, Link } from '@mui/icons-material';\nimport { getImagePath, TestImage, ImageSize } from 'RingDemoImages';\n\nexport default function ActionsExample(): React.JSX.Element {\n const actions = [\n {\n label: 'Action 1',\n icon: <Download />,\n },\n {\n label: 'Action 2',\n icon: <Link />,\n },\n ];\n const fields = [\n { value: 'Source / Author' },\n { value: 'Brief description or summary of the content' },\n { value: 'Space for comments or additional information that may take up more space' },\n ];\n\n return (\n <MediaCard\n sx={{ width: '300px' }}\n title=\"Title / name\"\n fields={fields}\n actions={actions}\n image={getImagePath(TestImage.ISLAND, ImageSize.MEDIUM)}\n ratio=\"16/9\"\n objectFit=\"fill\"\n />\n );\n}\n```\n\n## Status Labels\n\nThe MediaCard component is designed to display status labels with various configurations.\n\nAn array of objects representing the status labels to be displayed.\n\nEach object in the array can have the following properties:\n\n| Property | Type | Description |\n| ------------- | ----------------- | --------------------------------------------------------------- |\n| `label` | `string` | The text to be displayed on the status label |\n| `color` | `string` | The color of the label, chosen from a predefined color palette |\n| `icon` | `React.ReactNode` | (Optional) An icon to be displayed alongside the label |\n| `showOnHover` | `boolean` | (Optional) If true, the label will only be visible on hover |\n| `tip` | `string` | (Optional) Tooltip text for the label |\n| `key` | `string` | (Optional) Unique key for the label, useful for React rendering |\n\n```tsx\n// StatusLabelsExample.tsx\nimport React from 'react';\nimport { MediaCard } from '@ringpublishing/mui-components';\nimport { DeleteOutlined, LockOpenOutlined } from '@mui/icons-material';\nimport { getImagePath, TestImage, ImageSize } from 'RingDemoImages';\n\nexport default function StatusLabelsExample(): React.JSX.Element {\n const statusLabels = [\n {\n label: 'Deleted',\n color: 'error' as const,\n icon: <DeleteOutlined />,\n key: 'test-deleted',\n },\n {\n label: 'Inactive',\n color: 'default' as const,\n key: 'test-inactive',\n },\n {\n label: 'J. Zatrzymałowski',\n color: 'error' as const,\n icon: <LockOpenOutlined />,\n tip: 'This resource is locked by J. Zatrzymałowski',\n },\n {\n label: 'New',\n color: 'primary' as const,\n icon: <LockOpenOutlined />,\n showOnHover: true,\n },\n ];\n const fields = [\n { value: 'Source / Author' },\n { value: 'Brief description or summary of the content' },\n { value: 'Space for comments or additional information that may take up more space' },\n ];\n\n return (\n <MediaCard\n sx={{ width: '300px' }}\n title=\"Title / name\"\n fields={fields}\n statusLabels={statusLabels}\n image={getImagePath(TestImage.ISLAND, ImageSize.MEDIUM)}\n ratio=\"16/9\"\n objectFit=\"fill\"\n />\n );\n}\n```\n\n## Hoverable\n\nThe `MediaCard` component includes an optional hoverable functionality that enhances user interaction and provides visual feedback. When enabled, this feature allows for dynamic color changes based on the hover state and utilizes the MUI `CardActionArea` for improved accessibility.\n\n### Props\n\n| Prop | Type | Default | Description |\n| ----------- | ---------- | ------- | -------------------------------------------------------------------------- |\n| `hoverable` | `boolean` | `false` | Enables the hoverable functionality |\n| `active` | `boolean` | `false` | Indicates the current active/highlighted state |\n| `onClick` | `function` | - | Callback function that will be called after clicking on the card component |\n\n### Functionality\n\nWhen the hoverable feature is enabled (`hoverable={true}`):\n\n1. **Color Change**: The component can change its color based on the hover state. This is achieved through the `onClick` callback.\n2. **Interactive Area**: The entire card becomes interactive using hover effect. This provides visual feedback to the user about possible actions.\n3. **Focus Management**: The parent component is responsible for managing the focus state. The `MediaCard` only receives the current state through props and reports changes via the callback.\n\n```jsx\nconst [active, setActive] = useState(false);\n\n<MediaCard hoverable={true} active={active} onClick={() => setActive(!active)} />;\n```\n\n### Important Notes\n\n- The `MediaCard` component itself does not manage the hover state. It relies on the parent component to control this.\n- When `hoverable` is `false`, the component behaves as a standard, non-interactive `MediaCard`.\n\n```tsx\n// HoverableExample.tsx\nimport React, { useState } from 'react';\nimport { MediaCard } from '@ringpublishing/mui-components';\nimport { Download, Link } from '@mui/icons-material';\nimport { getImagePath, TestImage, ImageSize } from 'RingDemoImages';\n\nexport default function HoverableExample(): React.JSX.Element {\n const [active, setActive] = useState(false);\n const handleSelectChange = (): void => setActive(!active);\n const actions = [\n {\n label: 'Action 1',\n icon: <Download />,\n },\n {\n label: 'Action 2',\n icon: <Link />,\n },\n ];\n const fields = [\n { value: 'Source / Author' },\n { value: 'Brief description or summary of the content' },\n { value: 'Space for comments or additional information that may take up more space' },\n ];\n\n return (\n <MediaCard\n hoverable={true}\n active={active}\n onClick={handleSelectChange}\n image={getImagePath(TestImage.ISLAND, ImageSize.MEDIUM)}\n ratio=\"16/9\"\n objectFit=\"fill\"\n sx={{ width: '300px' }}\n title=\"Title / name\"\n fields={fields}\n actions={actions}\n />\n );\n}\n```\n\n## Checkbox\n\nMediaCard includes checkbox functionality implemented using the Checkbox component from the Material-UI (MUI) library.\n\n### Notes\n\n1. The parent component should manage the checkbox's `checked` state.\n2. The implementation uses an `onClick` callback, which provides information about state changes to the parent component.\n3. In the click event handler, `event.stopPropagation()` should be called to prevent the event from bubbling up to parent elements.\n4. The parent component should also manage the `showOnHover` property for status labels to control checkbox visibility based on hover or active state.\n\n```jsx\nconst [checked, setChecked] = useState(false);\nconst handleCheckboxChange = (event) => {\n setChecked(!checked);\n event.stopPropagation();\n};\n\n<MediaCard\n slotProps={{\n checkbox: {\n checked,\n onClick: handleCheckboxChange,\n showOnHover: !checked,\n },\n }}\n statusLabels={[\n {\n label: 'New Feature',\n },\n ]}\n/>;\n```\n\n```tsx\n// CheckboxExample.tsx\nimport React, { useState } from 'react';\nimport { MediaCard } from '@ringpublishing/mui-components';\nimport { getImagePath, TestImage, ImageSize } from 'RingDemoImages';\n\nexport default function CheckboxExample(): React.JSX.Element {\n const [checked, setChecked] = useState(false);\n const handleCheckboxChange = (event: React.MouseEvent): void => {\n setChecked(!checked);\n event.stopPropagation();\n };\n\n return (\n <MediaCard\n sx={{ width: '300px' }}\n title=\"Title / name\"\n image={getImagePath(TestImage.ISLAND, ImageSize.MEDIUM)}\n ratio=\"16/9\"\n objectFit=\"fill\"\n slotProps={{\n checkbox: {\n checked,\n onClick: handleCheckboxChange,\n showOnHover: !checked,\n },\n }}\n />\n );\n}\n```\n\n## Slots\n\nThe MediaCard component offers a slot system that allows for advanced customization by replacing default parts of the component with your own implementations.\n\n### Available Slots\n\n| Slot | Type | Default | Description |\n| ----------- | ----------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `mediaCard` | `ReactNode` | `CardMedia` | Custom React node rendered in place of the default `<CardMedia>`. Wrapped in `<AspectRatio>` so `ratio` and `objectFit` still apply to the surrounding box. |\n| `footer` | `ReactNode` | — | Optional custom footer rendered below the card content (inside `<CardActions>`). |\n\n### Using Slots\n\nSlots provide full control over the behavior and appearance of specific parts of the component while maintaining the overall style and functionality of the MediaCard. This is particularly useful when you need to:\n\n1. **Replace the default image display element** with your own, such as a video player, interactive visualization, or other React component.\n2. **Add advanced features** that are not available in the default implementation.\n\n```jsx\n<MediaCard\n slots={{\n mediaCard: (\n <video controls autoPlay muted>\n <source src=\"path/to/your/video.mp4\" type=\"video/mp4\" />\n Your browser does not support video playback.\n </video>\n ),\n }}\n ratio=\"16/9\"\n title=\"My video\"\n/>\n```\n\n```tsx\n// SlotsExample.tsx\nimport React from 'react';\nimport { MediaCard } from '@ringpublishing/mui-components';\nimport { VideocamOutlined } from '@mui/icons-material';\n\nexport default function SlotsExample(): React.JSX.Element {\n return (\n <MediaCard\n sx={{ width: '300px' }}\n title=\"Title / name\"\n slots={{\n mediaCard: (\n <video controls={true}>\n <source\n src=\"https://test-videos.co.uk/vids/bigbuckbunny/mp4/h264/1080/Big_Buck_Bunny_1080_10s_1MB.mp4\"\n type=\"video/mp4\"\n />\n </video>\n ),\n }}\n iconPlaceholder={<VideocamOutlined />}\n ratio=\"16/9\"\n objectFit=\"cover\"\n />\n );\n}\n```\n\n## Slot props\n\nThe `slotProps` prop lets you forward arbitrary props to the internal sub-components without redefining each one as a top-level MediaCard prop. It mirrors the [MUI `slotProps` convention](https://mui.com/material-ui/customization/slots-and-classes/).\n\n| Slot prop | Type | Description |\n| ----------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `card` | `Omit<CardProps, \"children\" \\| \"variant\" \\| \"square\" \\| \"onClick\" \\| \"tabIndex\" \\| \"elevation\">` | Props applied to the root MUI `<Card>`. **Recommended channel for native DOM events** (`onMouseEnter`, `onMouseLeave`, `onFocus`, `onKeyDown`, `aria-*`, `data-*`, …). Top-level MediaCardProps (`variant`, `square`, `onClick`, `tabIndex`, `className`, `sx`) take precedence and are merged on top. `elevation` is excluded because MediaCard manages it implicitly via `variant` (`outlined` → 0, `elevation` → 1) — overriding it would diverge from the design system. |\n| `cardMedia` | `CardMediaProps` | Props applied to the default `<CardMedia>`. Used **only** when `slots.mediaCard` is not provided. Lets you switch the underlying element (`component: \"video\" \\| \"audio\" \\| \"img\"`), tweak `src`, etc. |\n| `checkbox` | `CheckboxProps & { showOnHover?: boolean }` | Props applied to the selection `<Checkbox>`. The custom `showOnHover` flag hides the checkbox until the card is hovered (useful for grid scenarios). When `undefined`, the checkbox is not rendered. |\n| `footer` | `CardActionsProps` | Props applied to the `<CardActions>` element wrapping `slots.footer` (e.g. `sx`, `disableSpacing`). |\n\n### Precedence rules\n\nWhen the same prop can be supplied through more than one channel:\n\n- **`variant`, `square`, `onClick`, `tabIndex`** — only top-level MediaCardProps. Excluded from `slotProps.card` typing to prevent accidental override.\n- **`className`, `sx`** — additive: top-level value is **merged on top of** `slotProps.card` value (for `className` they are concatenated, for `sx` they form an array layer).\n- **All other props** — supplied through `slotProps.card` are forwarded to `<Card>` directly.\n\n```jsx\n<MediaCard\n slotProps={{\n card: {\n onMouseEnter: () => setHovered(true),\n onMouseLeave: () => setHovered(false),\n onContextMenu: (e) => {\n e.preventDefault();\n openMenu();\n },\n 'aria-label': 'Open detail view',\n },\n checkbox: { checked, onClick: toggle, showOnHover: !checked },\n }}\n/>\n```\n\n## Card Events\n\n`MediaCard` exposes the underlying MUI `<Card>` element through the `slotProps.card` channel. Any prop that the `Card` component accepts is forwarded to the root element — including all native DOM event handlers.\n\n### Common Use-Cases\n\n- **Hover-driven interactions** — `onMouseEnter` / `onMouseLeave` to trigger a video preview, fetch on demand, or update tooltips.\n- **Keyboard accessibility** — `onKeyDown` / `onFocus` / `onBlur` to integrate the card into custom keyboard navigation.\n- **Right-click menus** — `onContextMenu` for custom action menus.\n- **Accessibility attributes** — `aria-*`, `role`, `aria-describedby`, etc.\n- **Test hooks** — `data-*` attributes beyond the built-in `dataTestIdSuffix`.\n\n### Precedence\n\nTop-level `MediaCardProps` (`variant`, `square`, `tabIndex`, `onClick`, `className`, `sx`) take precedence over values supplied through `slotProps.card`. They are merged on top — top-level wins. Use `slotProps.card` for everything that is not already exposed at the top level. `elevation` is excluded from `slotProps.card` because MediaCard manages it implicitly via `variant` — overriding would diverge from the design system.\n\n```jsx\n<MediaCard\n slotProps={{\n card: {\n onMouseEnter: () => setHovered(true),\n onMouseLeave: () => setHovered(false),\n onContextMenu: (e) => {\n e.preventDefault();\n openMenu();\n },\n 'aria-label': 'Open detail view',\n },\n }}\n/>\n```\n\nThe example below combines `slots.mediaCard` (custom native `<video>`) with `slotProps.card` (`onMouseEnter` / `onMouseLeave`) to play the video while the user is hovering the card.\n\n```tsx\n// CardEventsExample.tsx\nimport React, { useEffect, useRef, useState } from 'react';\nimport { MediaCard } from '@ringpublishing/mui-components';\nimport { OndemandVideoOutlined } from '@mui/icons-material';\n\nconst VIDEO_SRC = 'https://test-videos.co.uk/vids/bigbuckbunny/mp4/h264/1080/Big_Buck_Bunny_1080_10s_1MB.mp4';\n\nexport default function CardEventsExample(): React.JSX.Element {\n const [isHovered, setIsHovered] = useState(false);\n const videoRef = useRef<HTMLVideoElement>(null);\n\n useEffect(() => {\n const video = videoRef.current;\n if (!video) return;\n\n if (isHovered) {\n void video.play().catch(() => {\n // autoplay can be blocked; ignored for the example\n });\n } else {\n video.pause();\n video.currentTime = 0;\n }\n }, [isHovered]);\n\n return (\n <MediaCard\n sx={{ width: '320px' }}\n title=\"Hover the card to play\"\n slots={{\n mediaCard: (\n <video\n ref={videoRef}\n muted={true}\n playsInline={true}\n style={{ width: '100%', height: '100%', objectFit: 'cover', display: 'block' }}\n >\n <source src={VIDEO_SRC} type=\"video/mp4\" />\n </video>\n ),\n }}\n iconPlaceholder={<OndemandVideoOutlined />}\n ratio=\"16/9\"\n hoverable={true}\n slotProps={{\n card: {\n onMouseEnter: (): void => setIsHovered(true),\n onMouseLeave: (): void => setIsHovered(false),\n },\n }}\n />\n );\n}\n```\n\n## Advanced Example\n\nThis example shows how to combine different features of the MediaCard component to create a rich user interface.\n\n### Combined Features\n\n- Image with specific aspect ratio and fitting\n- Status labels with hover effects\n- Selection capability (checkbox)\n- Focus capability (hover effect and color change)\n- Action list\n- Information fields with different styles\n- Custom slots for footer content\n\nNote that both the checkbox state and focus state are managed by the parent component.\n\n```tsx\n// AdvancedExampleCode.tsx\nimport React, { useState } from 'react';\nimport { MediaCard } from '@ringpublishing/mui-components';\nimport { Download, Link, Share, Favorite, InfoOutlined } from '@mui/icons-material';\nimport { Box, IconButton } from '@mui/material';\nimport { getImagePath, TestImage, ImageSize } from 'RingDemoImages';\n\nexport default function AdvancedExampleCode(): React.JSX.Element {\n const [isActive, setIsActive] = useState(false);\n const handleCardClick = (): void => {\n setIsActive(!isActive);\n };\n\n const [isCheckboxChecked, setIsCheckboxChecked] = useState(false);\n const handleCheckboxClick = (event: React.MouseEvent): void => {\n event.stopPropagation();\n setIsCheckboxChecked(!isCheckboxChecked);\n };\n\n const handleDownloadClick = (event: React.MouseEvent): void => {\n event.stopPropagation();\n console.log('Footer Download button clicked');\n };\n\n const handleShareClick = (event: React.MouseEvent): void => {\n event.stopPropagation();\n console.log('Footer Share button clicked');\n };\n\n const handleFavoriteClick = (event: React.MouseEvent): void => {\n event.stopPropagation();\n console.log('Footer Favorite button clicked');\n };\n\n return (\n <MediaCard\n title=\"Advanced Example\"\n image={getImagePath(TestImage.ISLAND, ImageSize.MEDIUM)}\n ratio=\"16/9\"\n objectFit=\"cover\"\n sx={{ width: '300px' }}\n hoverable={true}\n active={isActive}\n onClick={handleCardClick}\n slotProps={{\n checkbox: {\n checked: isCheckboxChecked,\n onClick: handleCheckboxClick,\n showOnHover: !isCheckboxChecked,\n },\n }}\n slots={{\n footer: (\n <Box sx={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', width: '100%' }}>\n <Box sx={{ display: 'flex', alignItems: 'center', ml: 1 }}>\n <InfoOutlined sx={{ fontSize: 16, color: '#BC1828' }} />\n <InfoOutlined sx={{ fontSize: 16, color: '#BC1828' }} />\n <InfoOutlined sx={{ fontSize: 16, color: '#BC1828' }} />\n <Box\n sx={{\n width: 16,\n height: 16,\n ml: 1,\n borderRadius: '50%',\n backgroundColor: '#FFD21E',\n }}\n />\n </Box>\n <Box>\n <IconButton size=\"small\" onClick={handleDownloadClick}>\n <Download />\n </IconButton>\n <IconButton size=\"small\" onClick={handleShareClick}>\n <Share />\n </IconButton>\n <IconButton size=\"small\" onClick={handleFavoriteClick}>\n <Favorite />\n </IconButton>\n </Box>\n </Box>\n ),\n }}\n statusLabels={[\n {\n label: 'Premium',\n color: 'success',\n icon: <Download />,\n },\n {\n label: 'New Feature',\n color: 'primary',\n icon: <Download />,\n showOnHover: !isActive,\n tip: 'This feature is available for premium users',\n },\n {\n label: 'ASG',\n color: 'secondary',\n icon: <Link />,\n showOnHover: !isActive,\n },\n ]}\n actions={[\n {\n label: 'Download',\n icon: <Download />,\n onClick: () => console.log('Downloading...'),\n },\n {\n label: 'Share',\n icon: <Link />,\n onClick: () => console.log('Sharing...'),\n },\n ]}\n fields={[\n { value: 'Jane Doe / Example', fontWeight: 'bold' },\n { value: 'Demonstration of new features in MediaCard', color: 'success.main', fontStyle: 'italic' },\n { value: 'This card showcases the latest enhancements and capabilities', color: 'text.secondary' },\n ]}\n />\n );\n}\n```"
|
|
2852
|
-
},
|
|
2853
|
-
"organisms-multimedia-grid": {
|
|
2854
|
-
"id": "organisms-multimedia-grid",
|
|
2855
|
-
"name": "MultimediaGrid",
|
|
2856
|
-
"category": "Organisms",
|
|
2857
|
-
"title": "Components/Organisms/MultimediaGrid",
|
|
2858
|
-
"description": "MultimediaGrid is a component for displaying media elements (photos and videos) in a responsive grid layout. It serves as an alternative to DataGrid, optimized for visual content presentation.",
|
|
2859
|
-
"argTypes": {
|
|
2860
|
-
"labels": {
|
|
2861
|
-
"description": "Labels used in the toolbar component.",
|
|
2862
|
-
"control": "object",
|
|
2863
|
-
"category": "data toolbar",
|
|
2864
|
-
"type": "DataToolbarLabels"
|
|
2865
|
-
},
|
|
2866
|
-
"sortableFields": {
|
|
2867
|
-
"description": "Fields by which grid elements can be sorted.",
|
|
2868
|
-
"control": "object",
|
|
2869
|
-
"category": "data toolbar",
|
|
2870
|
-
"type": "DataToolbarSortableFields[]"
|
|
2871
|
-
},
|
|
2872
|
-
"totalRowCount": {
|
|
2873
|
-
"description": "Total number of items to display in the toolbar.",
|
|
2874
|
-
"control": "number",
|
|
2875
|
-
"category": "data toolbar",
|
|
2876
|
-
"type": "number",
|
|
2877
|
-
"defaultValue": "1"
|
|
2878
|
-
},
|
|
2879
|
-
"loading": {
|
|
2880
|
-
"description": "Determines whether the component is in loading state.",
|
|
2881
|
-
"control": "boolean",
|
|
2882
|
-
"category": "data toolbar",
|
|
2883
|
-
"type": "boolean",
|
|
2884
|
-
"defaultValue": "false"
|
|
2885
|
-
},
|
|
2886
|
-
"error": {
|
|
2887
|
-
"description": "If true, displays error message instead of grid.",
|
|
2888
|
-
"control": "boolean",
|
|
2889
|
-
"category": "states",
|
|
2890
|
-
"type": "boolean",
|
|
2891
|
-
"defaultValue": "false"
|
|
2892
|
-
},
|
|
2893
|
-
"placeholderLabels": {
|
|
2894
|
-
"description": "Custom labels for the error and empty state placeholders. When omitted, default localized labels are used.",
|
|
2895
|
-
"control": "object",
|
|
2896
|
-
"category": "states",
|
|
2897
|
-
"type": "{ error?: { header?: string; description?: string; footer?: string }; empty?: { header?: string; description?: string; footer?: string }; tryAgainButton?: string }"
|
|
2898
|
-
},
|
|
2899
|
-
"columns": {
|
|
2900
|
-
"description": "Number of columns. Can be a number or a responsive object.",
|
|
2901
|
-
"control": "object",
|
|
2902
|
-
"category": "layout",
|
|
2903
|
-
"type": "ResponsiveValue<number>"
|
|
2904
|
-
},
|
|
2905
|
-
"cellRatio": {
|
|
2906
|
-
"description": "Cell proportions in \"width/height\" format. Can be responsive.",
|
|
2907
|
-
"control": "object",
|
|
2908
|
-
"category": "layout",
|
|
2909
|
-
"type": "ResponsiveValue<string>"
|
|
2910
|
-
},
|
|
2911
|
-
"refreshItems": {
|
|
2912
|
-
"description": "Function called when refresh icon is clicked or during auto-refresh.",
|
|
2913
|
-
"category": "data toolbar",
|
|
2914
|
-
"type": "() => void"
|
|
2915
|
-
},
|
|
2916
|
-
"showRingToolbar": {
|
|
2917
|
-
"description": "Determines whether the toolbar should be visible.",
|
|
2918
|
-
"control": "boolean",
|
|
2919
|
-
"category": "data toolbar",
|
|
2920
|
-
"type": "boolean",
|
|
2921
|
-
"defaultValue": "false"
|
|
2922
|
-
},
|
|
2923
|
-
"spacing": {
|
|
2924
|
-
"description": "Spacing for both rows and columns (in theme.spacing() units). Can be responsive.",
|
|
2925
|
-
"control": "number",
|
|
2926
|
-
"category": "layout",
|
|
2927
|
-
"type": "ResponsiveValue<number>",
|
|
2928
|
-
"defaultValue": "0"
|
|
2929
|
-
},
|
|
2930
|
-
"rowSpacing": {
|
|
2931
|
-
"description": "Vertical spacing between rows (in theme.spacing() units). Can be responsive.",
|
|
2932
|
-
"control": "number",
|
|
2933
|
-
"category": "layout",
|
|
2934
|
-
"type": "ResponsiveValue<number>"
|
|
2935
|
-
},
|
|
2936
|
-
"columnSpacing": {
|
|
2937
|
-
"description": "Horizontal spacing between columns (in theme.spacing() units). Can be responsive.",
|
|
2938
|
-
"control": "number",
|
|
2939
|
-
"category": "layout",
|
|
2940
|
-
"type": "ResponsiveValue<number>"
|
|
2941
|
-
},
|
|
2942
|
-
"items": {
|
|
2943
|
-
"description": "Media elements to display in the grid. Each item should contain data needed to display a media card.",
|
|
2944
|
-
"control": "object",
|
|
2945
|
-
"category": "data",
|
|
2946
|
-
"type": "MultimediaGridItem[]"
|
|
2947
|
-
},
|
|
2948
|
-
"sx": {
|
|
2949
|
-
"description": "MUI System properties to customize the main element style.",
|
|
2950
|
-
"control": "object",
|
|
2951
|
-
"category": "customization",
|
|
2952
|
-
"type": "SxProps<Theme>",
|
|
2953
|
-
"defaultValue": "{}"
|
|
2954
|
-
},
|
|
2955
|
-
"className": {
|
|
2956
|
-
"description": "CSS class name applied to the main element.",
|
|
2957
|
-
"control": "text",
|
|
2958
|
-
"category": "customization",
|
|
2959
|
-
"type": "string"
|
|
2960
|
-
},
|
|
2961
|
-
"slots": {
|
|
2962
|
-
"description": "Allows overriding default components. Available slots: `mediaCard` - replaces the default MediaCard component.",
|
|
2963
|
-
"control": "object",
|
|
2964
|
-
"category": "customization",
|
|
2965
|
-
"type": "MultimediaGridSlots"
|
|
2966
|
-
},
|
|
2967
|
-
"slotProps": {
|
|
2968
|
-
"description": "Properties passed to slots. Available: `mediaCard` - props for the mediaCard slot.",
|
|
2969
|
-
"control": "object",
|
|
2970
|
-
"category": "customization",
|
|
2971
|
-
"type": "MultimediaGridSlotProps",
|
|
2972
|
-
"defaultValue": "{}"
|
|
2973
|
-
},
|
|
2974
|
-
"onLoadMore": {
|
|
2975
|
-
"description": "Function called when the user approaches the end of the list. Used to implement infinite scrolling.",
|
|
2976
|
-
"category": "infinite scroll",
|
|
2977
|
-
"type": "() => void | Promise<void>"
|
|
2978
|
-
},
|
|
2979
|
-
"hasMore": {
|
|
2980
|
-
"description": "Determines if there is more data to load. Controls whether `onLoadMore` should be called.",
|
|
2981
|
-
"control": "boolean",
|
|
2982
|
-
"category": "infinite scroll",
|
|
2983
|
-
"type": "boolean",
|
|
2984
|
-
"defaultValue": "false"
|
|
2985
|
-
},
|
|
2986
|
-
"overscan": {
|
|
2987
|
-
"description": "Number of additional items rendered outside the visible area for performance optimization during scrolling.",
|
|
2988
|
-
"category": "performance",
|
|
2989
|
-
"type": "number",
|
|
2990
|
-
"defaultValue": "1"
|
|
2991
|
-
},
|
|
2992
|
-
"selectionModel": {
|
|
2993
|
-
"description": "Set of selected items with type include/exclude. Can be controlled or uncontrolled.",
|
|
2994
|
-
"control": "object",
|
|
2995
|
-
"category": "selection",
|
|
2996
|
-
"type": "GridRowSelectionModel"
|
|
2997
|
-
},
|
|
2998
|
-
"onSelectionModelChange": {
|
|
2999
|
-
"description": "Callback fired when the selection changes.",
|
|
3000
|
-
"category": "selection",
|
|
3001
|
-
"type": "(model: GridRowSelectionModel, details: GridCallbackDetails<any>) => void"
|
|
3002
|
-
},
|
|
3003
|
-
"disableSelection": {
|
|
3004
|
-
"description": "If true, the selection functionality is disabled.",
|
|
3005
|
-
"control": "boolean",
|
|
3006
|
-
"category": "selection",
|
|
3007
|
-
"type": "boolean",
|
|
3008
|
-
"defaultValue": "false"
|
|
3009
|
-
},
|
|
3010
|
-
"disableSelectionOnClick": {
|
|
3011
|
-
"description": "If true, clicking on items will not trigger selection. Only checkbox clicks will work.",
|
|
3012
|
-
"control": "boolean",
|
|
3013
|
-
"category": "selection",
|
|
3014
|
-
"type": "boolean",
|
|
3015
|
-
"defaultValue": "false"
|
|
3016
|
-
},
|
|
3017
|
-
"checkboxSelection": {
|
|
3018
|
-
"description": "If true, checkbox for selection is shown for each item.",
|
|
3019
|
-
"control": "boolean",
|
|
3020
|
-
"category": "selection",
|
|
3021
|
-
"type": "boolean",
|
|
3022
|
-
"defaultValue": "false"
|
|
3023
|
-
},
|
|
3024
|
-
"dynamicLayout": {
|
|
3025
|
-
"description": "Enables dynamic layout calculation. Automatically calculates optimal column count and card dimensions.",
|
|
3026
|
-
"control": "boolean",
|
|
3027
|
-
"category": "dynamic layout",
|
|
3028
|
-
"type": "boolean",
|
|
3029
|
-
"defaultValue": "false"
|
|
3030
|
-
},
|
|
3031
|
-
"dynamicCardWidth": {
|
|
3032
|
-
"description": "Target card width in pixels. Reference size for optimal layout calculation. Only applies when dynamicLayout is true.",
|
|
3033
|
-
"category": "dynamic layout",
|
|
3034
|
-
"type": "number",
|
|
3035
|
-
"defaultValue": "200"
|
|
3036
|
-
},
|
|
3037
|
-
"dynamicCardHeight": {
|
|
3038
|
-
"description": "Target card height in pixels. Reference size for optimal layout calculation. Only applies when dynamicLayout is true.",
|
|
3039
|
-
"category": "dynamic layout",
|
|
3040
|
-
"type": "number",
|
|
3041
|
-
"defaultValue": "300"
|
|
3042
|
-
}
|
|
3043
|
-
},
|
|
3044
|
-
"storyNames": [
|
|
3045
|
-
"Default",
|
|
3046
|
-
"InfiniteScroll",
|
|
3047
|
-
"Slots",
|
|
3048
|
-
"Selection",
|
|
3049
|
-
"EmptyState",
|
|
3050
|
-
"EmptyStateCustomLabels",
|
|
3051
|
-
"ErrorState",
|
|
3052
|
-
"ErrorStateCustomLabels",
|
|
3053
|
-
"DynamicLayout",
|
|
3054
|
-
"WithFilterChips"
|
|
3055
|
-
],
|
|
3056
|
-
"docs": "# MultimediaGrid\n\nMultimediaGrid is a component for displaying media elements (photos and videos) in a responsive grid layout. It serves as an alternative to DataGrid, optimized for visual content presentation.\n\n## Component Features:\n\n- **Responsive grid layout** - configurable parameters for different container breakpoints (xs, sm, md, lg)\n- **Flexible aspect ratios** - support for various cell aspect ratios with responsive configuration\n- **Virtualized rendering** - efficient handling of large media collections\n- **Infinite scrolling**\n- **Configurable spacing** - responsive spacing between elements (spacing, rowSpacing, columnSpacing)\n- **Toolbar integration** - filtering and sorting capabilities\n- **Loading state handling** - built-in loading indicators\n- **Separator support** - spacer elements for visual organization\n- **Slots system** - customizable appearance through replaceable components\n- **Auto-scroll to active card on container resize** - maintains visibility of selected items when grid width changes\n\n## Default\n\nBasic usage of MultimediaGrid with toolbar, sorting, and responsive columns. This demonstrates the standard configuration with demo data.\n\n```tsx\n// DefaultExample.tsx\nimport React from 'react';\nimport { MultimediaGrid } from '@ringpublishing/mui-components';\nimport { sortableFields, useMultimediaGridDemoData } from 'RingDemoData';\n\nconst labels = {\n results: 'Results',\n refresh: 'Refresh',\n enableAutoRefresh: 'Enable auto refresh',\n disableAutoRefresh: 'Disable auto refresh',\n selectAll: 'Select all',\n deselectAll: 'Deselect all',\n};\n\nexport default function DefaultExample(): React.JSX.Element {\n const { items, totalCount, loading } = useMultimediaGridDemoData({});\n\n return (\n <MultimediaGrid\n showRingToolbar={true}\n labels={labels}\n sortableFields={sortableFields}\n items={items}\n totalRowCount={totalCount}\n loading={loading}\n sx={{ width: '100%', height: '80vh' }}\n />\n );\n}\n```\n\n## Slots\n\nMultimediaGrid offers a slot system that allows replacing default components with your own implementations. This enables complete customization of card appearance and behavior while maintaining the grid's performance and features.\n\n### Available Slots\n\n| Slot name | Default component | Description |\n| ----------- | ----------------- | --------------------------------------------------------------- |\n| `mediaCard` | `MediaCard` | Component that replaces the default MediaCard for grid elements |\n\n### Properties of the mediaCard Slot\n\nThe `mediaCard` slot receives the following context properties:\n\n- `item` - element data\n- `itemWidth` - element width in pixels\n- `itemHeight` - element height in pixels\n- `globalIndex` - global index of the element\n- `indexInRow` - element index in the row\n- `rowIndex` - row index\n- `isFirstInRow` - whether it's the first element in the row\n- `isLastInRow` - whether it's the last element in the row\n- `isFirstRow` - whether it's the first row\n- `isLastRow` - whether it's the last row\n- `breakpoint` - current container breakpoint (xs, sm, md, lg)\n- `isSelected` - whether the item is selected\n\n### Using slotProps\n\nYou can pass additional properties to slots using `slotProps`:\n\n```typescript\n<MultimediaGrid\n slots={{\n mediaCard: MyCustomMediaCard\n }}\n slotProps={{\n mediaCard: {\n // additional props for MyCustomMediaCard\n customProp: 'value'\n }\n }}\n/>\n```\n\n### Functional slotProps - Access to Context\n\nThe `slotProps` can also use **functions** that receive context information, allowing dynamic styling based on item state:\n\n```typescript\n<MultimediaGrid\n slotProps={{\n mediaCard: {\n // Function that receives context with item data and state\n sx: (context) => ({\n height: '100%',\n // Dynamic styling based on selection state\n ...(context.isSelected && {\n border: '2px solid blue',\n borderRadius: 1\n }),\n // Different styling based on item position\n ...(context.isFirstInRow && {\n marginLeft: 0\n })\n }),\n // You can also use functions for other props\n tabIndex: (context) => context.isSelected ? 0 : -1\n }\n }}\n/>\n```\n\n### Context Properties Available in Functions:\n\n- `item` - element data\n- `isSelected` - whether the item is selected\n- `itemWidth`, `itemHeight` - element dimensions\n- `globalIndex` - global position in the grid\n- `indexInRow`, `rowIndex` - position within row and row number\n- `isFirstInRow`, `isLastInRow` - row position flags\n- `isFirstRow`, `isLastRow` - grid position flags\n- `breakpoint` - current responsive breakpoint\n\nThe slot system provides full control over the appearance and behavior of elements in the grid while maintaining interface consistency and performance.\n\n```tsx\n// SlotsExample.tsx\nimport React from 'react';\nimport { Box, Typography, SxProps } from '@mui/material';\nimport { MultimediaGrid } from '@ringpublishing/mui-components';\nimport { useMultimediaGridDemoData } from 'RingDemoData';\n\nconst CustomMediaCard = ({ context, sx, foo }: { context: any; sx: SxProps; foo: number }) => (\n <Box\n sx={{\n width: context.itemWidth,\n height: context.itemHeight,\n position: 'relative',\n padding: '3px',\n background: 'linear-gradient(135deg, #8B5CF6 0%, #3B82F6 25%, #EC4899 50%, #10B981 75%, #F59E0B 100%)',\n borderRadius: 2,\n boxShadow: '0 4px 20px rgba(0, 0, 0, 0.1)',\n ...sx,\n }}\n >\n <Box\n sx={{\n width: '100%',\n height: '100%',\n backgroundColor: '#FFFFFF',\n borderRadius: 1.5,\n display: 'flex',\n flexDirection: 'column',\n alignItems: 'center',\n justifyContent: 'center',\n p: 2,\n }}\n >\n <Typography\n variant=\"h5\"\n sx={{\n color: '#6B46C1',\n fontWeight: 700,\n textAlign: 'center',\n mb: 1,\n }}\n >\n {(context.item as { title?: string }).title?.slice(0, 50) || 'Python on the loose'}\n </Typography>\n {context.breakpoint !== 'xs' ? (\n <Typography\n variant=\"caption\"\n sx={{\n color: '#94A3B8',\n fontSize: '14px',\n fontWeight: 400,\n }}\n >\n Size: {context.itemWidth}x{context.itemHeight}px | foo: {foo}\n </Typography>\n ) : null}\n </Box>\n </Box>\n);\n\nexport default function SlotsExample(): React.JSX.Element {\n const { items, totalCount, loading } = useMultimediaGridDemoData();\n\n const slotProps = {\n mediaCard: {\n foo: 42,\n sx: {\n boxShadow: '0 4px 20px rgba(0, 0, 0, 0.1)',\n },\n },\n };\n\n return (\n <MultimediaGrid\n slots={{\n mediaCard: CustomMediaCard,\n }}\n slotProps={slotProps}\n items={items}\n loading={loading}\n totalRowCount={totalCount}\n showRingToolbar={false}\n columns={{ xs: 2, sm: 3, md: 4, lg: 5 }}\n cellRatio=\"1/1\"\n spacing={2}\n sx={{ width: '100%', height: '80vh' }}\n />\n );\n}\n```\n\n## Infinite Scroll\n\nThis story demonstrates infinite scrolling functionality in MultimediaGrid, allowing seamless loading of additional content as the user scrolls.\n\n### Features:\n\n- **Automatic loading** - new data loads when the user scrolls near the end\n- **Loading state** - the component shows a loading indicator while fetching data\n- **`hasMore` control** - prevents unnecessary calls when there is no more data\n- **Smooth operation** - seamless integration with existing grid functionality\n\n### Key Points:\n\n- Infinite scroll only works when `hasMore` is `true`\n- The component automatically detects when the user approaches the end of the list and calls the `onLoadMore` function\n- The `onLoadMore` function is automatically protected against multiple calls\n\n### Usage Tips:\n\n- Scroll down to see automatic loading of new elements\n- Notice how the loading state is handled during data fetching\n- The `overscan` prop controls how many off-screen items are pre-rendered for smooth scrolling\n\n```tsx\n// InfiniteScrollExample.tsx\nimport React from 'react';\nimport { MultimediaGrid } from '@ringpublishing/mui-components';\nimport { useMultimediaGridDemoData } from 'RingDemoData';\n\nconst labels = {\n results: 'Results',\n refresh: 'Refresh',\n enableAutoRefresh: 'Enable auto refresh',\n disableAutoRefresh: 'Disable auto refresh',\n selectAll: 'Select all',\n deselectAll: 'Deselect all',\n};\n\nexport default function InfiniteScrollExample(): React.JSX.Element {\n const { items, totalCount, loading, hasMore, nextData } = useMultimediaGridDemoData({\n initialCount: 30,\n });\n\n const handleLoadMore = async (): Promise<void> => {\n await nextData(30); // Load 30 more items each time\n };\n\n return (\n <MultimediaGrid\n items={items}\n totalRowCount={totalCount}\n loading={loading}\n onLoadMore={handleLoadMore}\n hasMore={hasMore}\n showRingToolbar={true}\n labels={labels}\n sx={{ width: '100%', height: '80vh' }}\n />\n );\n}\n```\n\n## Selection\n\nMultimediaGrid provides comprehensive selection functionality with checkboxes, mirroring the DataGrid selection API for consistency across components.\n\n### Features:\n\n- **checkboxSelection** - displays a checkbox on each item for selection\n- **Controlled mode** - selection state managed by parent component\n- **Card click selection** - clicking on cards can also select/deselect items\n- **disableSelectionOnClick** - set to `true` to disable card click selection (only checkboxes work)\n\n### Usage:\n\n- Click on checkboxes OR on cards to select/deselect items (depending on `disableSelectionOnClick`)\n- Use toolbar \"Select all\" / \"Deselect all\" buttons\n- Use the Controls panel to toggle selection features:\n - Toggle `checkboxSelection` to show/hide checkboxes\n - Toggle `disableSelection` to disable all selection\n - Toggle `disableSelectionOnClick` to disable card click selection\n- Check the Actions panel to see selection state changes\n\n### API Consistency:\n\nThis functionality mirrors the DataGrid selection API for consistency across components. The same props and patterns work in both components.\n\n```tsx\n// CheckboxSelectionExample.tsx\nimport React from 'react';\nimport { MultimediaGrid } from '@ringpublishing/mui-components';\nimport { useMultimediaGridDemoData } from 'RingDemoData';\nimport { GridRowSelectionModel } from '@mui/x-data-grid-pro';\n\nconst labels = {\n results: 'Results',\n refresh: 'Refresh',\n enableAutoRefresh: 'Enable auto refresh',\n disableAutoRefresh: 'Disable auto refresh',\n selectAll: 'Select all',\n deselectAll: 'Deselect all',\n};\n\nexport default function CheckboxSelectionExample(): React.JSX.Element {\n const { items, totalCount, loading, getItemIdsByIndices } = useMultimediaGridDemoData();\n\n const handleSelectionChange = (newSelection: GridRowSelectionModel): void => {\n console.log('Selection changed:', newSelection);\n };\n\n return (\n <MultimediaGrid\n checkboxSelection={true}\n disableSelection={false}\n showRingToolbar={true}\n labels={labels}\n items={items}\n totalRowCount={totalCount}\n loading={loading}\n selectionModel={{ type: 'include', ids: new Set(getItemIdsByIndices([0, 1])) }}\n onSelectionModelChange={handleSelectionChange}\n slotProps={{\n mediaCard: {\n slotProps: {\n checkbox: {\n showOnHover: true, // Checkbox shows on hover when unselected\n },\n },\n },\n }}\n sx={{ width: '100%', height: '80vh' }}\n />\n );\n}\n```\n\n## Empty State\n\nThis story demonstrates the empty state that appears when there are no items to display in the grid.\n\n### Features:\n\n- **Automatic display** - shown only when not loading and no error\n- **Language support** - respects the theme locale setting\n\n### Usage:\n\nThe empty state is displayed when:\n\n- `items` array is empty\n- `loading` is `false`\n- `error` is `false`\n\n## Error State\n\nThis story demonstrates the error state that appears when an error occurs while loading data.\n\n### Features:\n\n- **Priority over empty state** - error state takes precedence when both conditions are met\n- **Retry action** - displays a \"Try again\" button if `refreshItems` is provided\n- **Language support** - respects the theme locale setting\n\n### Usage:\n\nError state is displayed when:\n\n- `error` is `true`\n- `loading` is `false`\n\nToggle the `error` prop in Controls to show/hide error state.\n\n## Dynamic Layout\n\nDynamic layout automatically calculates optimal card dimensions and column count based on container width, providing the best visual experience across different screen sizes.\n\n### How it Works:\n\nFor each candidate column count, the algorithm:\n\n1. Calculates effective width (accounting for gaps)\n2. Computes scale factor relative to target dimensions\n3. Selects the count with scale closest to 1.0 to minimize distortion\n\n### Props:\n\n- `dynamicLayout` (boolean, default: `false`) - enables the feature\n- `dynamicCardWidth` (number, default: `200`) - target card width in pixels\n- `dynamicCardHeight` (number, default: `300`) - target card height in pixels\n\n### Features:\n\n- **Responsive** - recalculates on container resize\n- **Spacing-aware** - accounts for column gaps in calculations\n- **Overrides** - automatically overrides `columns` and `cellRatio` when enabled\n- **Performance** - uses memoization to avoid unnecessary recalculations\n\n```tsx\n// DynamicLayoutExample.tsx\nimport React from 'react';\nimport { MultimediaGrid } from '@ringpublishing/mui-components';\nimport { useMultimediaGridDemoData } from 'RingDemoData';\n\nexport default function DynamicLayoutExample(): React.JSX.Element {\n const { items } = useMultimediaGridDemoData();\n\n return (\n <MultimediaGrid\n dynamicLayout={true}\n dynamicCardWidth={260}\n dynamicCardHeight={300}\n showRingToolbar={true}\n spacing={1}\n items={items}\n sx={{ width: '100%', height: '80vh' }}\n />\n );\n}\n```"
|
|
3057
|
-
},
|
|
3058
|
-
"organisms-simple-tree": {
|
|
3059
|
-
"id": "organisms-simple-tree",
|
|
3060
|
-
"name": "SimpleTree",
|
|
3061
|
-
"category": "Organisms",
|
|
3062
|
-
"title": "Components/Organisms/SimpleTree",
|
|
3063
|
-
"description": "A compact, lightweight tree component for displaying hierarchical data with minimal styling.",
|
|
3064
|
-
"argTypes": {
|
|
3065
|
-
"sx": {
|
|
3066
|
-
"description": "MUI System properties for custom styling.",
|
|
3067
|
-
"control": "object",
|
|
3068
|
-
"category": "customization",
|
|
3069
|
-
"type": "SxProps<Theme>",
|
|
3070
|
-
"defaultValue": "{}"
|
|
3071
|
-
},
|
|
3072
|
-
"className": {
|
|
3073
|
-
"description": "CSS class name applied to the root element.",
|
|
3074
|
-
"control": "text",
|
|
3075
|
-
"category": "customization",
|
|
3076
|
-
"type": "string"
|
|
3077
|
-
},
|
|
3078
|
-
"dataTestIdSuffix": {
|
|
3079
|
-
"description": "Suffix for data-testid attributes.",
|
|
3080
|
-
"control": "text",
|
|
3081
|
-
"category": "testing",
|
|
3082
|
-
"type": "string"
|
|
3083
|
-
},
|
|
3084
|
-
"items": {
|
|
3085
|
-
"description": "Tree items to display.",
|
|
3086
|
-
"control": "object",
|
|
3087
|
-
"category": "content",
|
|
3088
|
-
"type": "SimpleTreeItem[]"
|
|
3089
|
-
},
|
|
3090
|
-
"withSearch": {
|
|
3091
|
-
"description": "Show search box for filtering items by label.",
|
|
3092
|
-
"control": "boolean",
|
|
3093
|
-
"category": "behavior",
|
|
3094
|
-
"type": "boolean",
|
|
3095
|
-
"defaultValue": "false"
|
|
3096
|
-
},
|
|
3097
|
-
"searchDebounceTime": {
|
|
3098
|
-
"description": "Debounce time for search in milliseconds.",
|
|
3099
|
-
"control": "number",
|
|
3100
|
-
"category": "behavior",
|
|
3101
|
-
"type": "number",
|
|
3102
|
-
"defaultValue": "500"
|
|
3103
|
-
},
|
|
3104
|
-
"searchPlaceholder": {
|
|
3105
|
-
"description": "Placeholder text for the search input.",
|
|
3106
|
-
"control": "text",
|
|
3107
|
-
"category": "content",
|
|
3108
|
-
"type": "string"
|
|
3109
|
-
},
|
|
3110
|
-
"selectedItems": {
|
|
3111
|
-
"description": "Controlled selected item IDs.",
|
|
3112
|
-
"control": "object",
|
|
3113
|
-
"category": "state",
|
|
3114
|
-
"type": "string[]"
|
|
3115
|
-
},
|
|
3116
|
-
"onSelectedItemsChange": {
|
|
3117
|
-
"description": "Callback fired when selection changes.",
|
|
3118
|
-
"control": false,
|
|
3119
|
-
"category": "callbacks",
|
|
3120
|
-
"type": "(itemIds: string[]) => void"
|
|
3121
|
-
},
|
|
3122
|
-
"onExpand": {
|
|
3123
|
-
"description": "Callback fired when an item is expanded or collapsed.",
|
|
3124
|
-
"control": false,
|
|
3125
|
-
"category": "callbacks",
|
|
3126
|
-
"type": "(itemId: string) => void"
|
|
3127
|
-
},
|
|
3128
|
-
"onClickRow": {
|
|
3129
|
-
"description": "Callback fired when a row is clicked.",
|
|
3130
|
-
"control": false,
|
|
3131
|
-
"category": "callbacks",
|
|
3132
|
-
"type": "(itemId: string) => void"
|
|
3133
|
-
},
|
|
3134
|
-
"persistence": {
|
|
3135
|
-
"description": "Enable localStorage persistence. Provide `cacheKey` to cache dynamic items, `restoreExpandedItems` to restore expanded state, and `restoreSelectedItem` to restore the last selected item.",
|
|
3136
|
-
"control": "object",
|
|
3137
|
-
"category": "behavior",
|
|
3138
|
-
"type": "{ cacheKey: string; restoreExpandedItems?: boolean; restoreSelectedItem?: boolean }"
|
|
3139
|
-
},
|
|
3140
|
-
"queryClient": {
|
|
3141
|
-
"description": "Optional app `QueryClient` so tree queries use your cache / DevTools.",
|
|
3142
|
-
"control": false,
|
|
3143
|
-
"category": "behavior",
|
|
3144
|
-
"type": "QueryClient"
|
|
3145
|
-
}
|
|
3146
|
-
},
|
|
3147
|
-
"storyNames": [
|
|
3148
|
-
"Default",
|
|
3149
|
-
"WithSearch",
|
|
3150
|
-
"WithDynamicLoading",
|
|
3151
|
-
"WithCustomElements",
|
|
3152
|
-
"ControlledSelection",
|
|
3153
|
-
"WithPersistence",
|
|
3154
|
-
"WithExternalQueryClient"
|
|
3155
|
-
],
|
|
3156
|
-
"docs": "# SimpleTree\n\nA compact, lightweight tree component for displaying hierarchical data with minimal styling.\n\n## Key Features\n\n- **Compact spacing**: 8px nesting indentation, 18px icons\n- **Single-item selection**: Click to select individual items\n- **Search filtering**: Filter items by label with matching text highlighted\n- **Dynamic child loading**: Load children on expand via TanStack Query\n- **Custom element rendering**: Render custom elements per item (badges, chips, etc.)\n- **localStorage persistence**: Cache dynamic items and restore last selection across sessions\n\nFor a full-featured tree with checkboxes, columns, drag-and-drop, and row actions, use `DataTree`.\n\n## Optional peer dependency\n\n`@tanstack/react-query` (v4 or v5) is declared as an **optional** peer dependency. You only need to install it if you use `loadItems` on any tree item to fetch children dynamically:\n\n```bash\n# Only required if your tree uses loadItems\nnpm install @tanstack/react-query\n```\n\nIf your tree is fully static (`items` is the only source of children, no `loadItems`), you do **not** need to install `@tanstack/react-query` — the component will work without it. When dynamic loading is in use, the component manages its own internal `QueryClient` and `QueryClientProvider`, so you do not need to set up a provider in your app.\n\nIf your app already runs TanStack Query, you can pass your existing client through the `queryClient` prop instead of letting the tree create its own — see [With External QueryClient](#with-external-queryclient). This keeps tree queries visible in React Query DevTools, lets you invalidate / prefetch them programmatically, and shares cache policies (retry, staleTime, error handlers) with the rest of your app.\n\n## Default\n\nBasic tree with static items and expand/collapse.\n\n```tsx\n// DefaultExample.tsx\nimport React from 'react';\nimport { SimpleTree, SimpleTreeItem } from '@ringpublishing/mui-components';\n\nconst items: SimpleTreeItem[] = [\n {\n itemId: '0',\n label: 'Documents',\n expanded: true,\n items: [\n { itemId: '0.0', label: 'Report.pdf' },\n {\n itemId: '0.1',\n label: 'Presentations',\n items: [\n { itemId: '0.1.0', label: 'Q1 Review.pptx' },\n { itemId: '0.1.1', label: 'Q2 Review.pptx' },\n ],\n },\n { itemId: '0.2', label: 'Notes.txt' },\n ],\n },\n {\n itemId: '1',\n label: 'Images',\n items: [\n { itemId: '1.0', label: 'photo.jpg' },\n { itemId: '1.1', label: 'diagram.png' },\n ],\n },\n { itemId: '2', label: 'README.md' },\n];\n\nexport default function DefaultExample(): React.JSX.Element {\n return (\n <div>\n <SimpleTree\n items={items}\n onExpand={(itemId) => console.log('Expanded:', itemId)}\n onClickRow={(itemId) => console.log('Clicked:', itemId)}\n />\n </div>\n );\n}\n```\n\n## With Search\n\nEnable search filtering with `withSearch`. Items are filtered by label with matching text highlighted.\n\n```tsx\n// WithSearchExample.tsx\nimport React from 'react';\nimport { SimpleTree, SimpleTreeItem } from '@ringpublishing/mui-components';\n\nconst items: SimpleTreeItem[] = [\n {\n itemId: '0',\n label: 'Documents',\n expanded: true,\n items: [\n { itemId: '0.0', label: 'Report.pdf' },\n {\n itemId: '0.1',\n label: 'Presentations',\n items: [\n { itemId: '0.1.0', label: 'Q1 Review.pptx' },\n { itemId: '0.1.1', label: 'Q2 Review.pptx' },\n ],\n },\n { itemId: '0.2', label: 'Notes.txt' },\n ],\n },\n {\n itemId: '1',\n label: 'Images',\n items: [\n { itemId: '1.0', label: 'photo.jpg' },\n { itemId: '1.1', label: 'diagram.png' },\n ],\n },\n { itemId: '2', label: 'README.md' },\n];\n\nexport default function WithSearchExample(): React.JSX.Element {\n return (\n <div>\n <SimpleTree\n items={items}\n withSearch\n searchPlaceholder=\"Search files...\"\n searchDebounceTime={500}\n onExpand={(itemId) => console.log('Expanded:', itemId)}\n onClickRow={(itemId) => console.log('Clicked:', itemId)}\n />\n </div>\n );\n}\n```\n\n## With Dynamic Loading\n\n**Requires `@tanstack/react-query`** (v4 or v5) — this story, and any tree that uses `loadItems`, will fail to render if the package is not installed (`npm install @tanstack/react-query`).\n\nItems with a `loadItems` function load children dynamically when expanded. Powered by TanStack Query for automatic caching and error handling. The component manages its own `QueryClient` internally.\n\n```tsx\n// WithDynamicLoadingExample.tsx\nimport React from 'react';\nimport { SimpleTree, SimpleTreeItem } from '@ringpublishing/mui-components';\n\ntype FsNode = { label: string } & ({ type: 'folder'; children: string[] } | { type: 'file' });\n\nconst filesystem: Record<string, FsNode> = {\n documents: { label: 'Documents', type: 'folder', children: ['reports', 'templates'] },\n reports: { label: 'Reports', type: 'folder', children: ['q1', 'q2', 'q3'] },\n templates: { label: 'Templates', type: 'folder', children: ['invoice', 'contract'] },\n projects: { label: 'Projects', type: 'folder', children: ['alpha', 'beta'] },\n alpha: { label: 'Alpha', type: 'folder', children: ['src', 'alpha-readme'] },\n beta: { label: 'Beta', type: 'folder', children: ['beta-main', 'beta-config'] },\n src: { label: 'src', type: 'folder', children: ['index', 'utils'] },\n archives: { label: 'Archives', type: 'folder', children: ['y2023', 'y2024'] },\n y2023: { label: '2023', type: 'folder', children: ['backup2023', 'data2023'] },\n y2024: { label: '2024', type: 'folder', children: ['backup2024', 'data2024'] },\n q1: { label: 'Q1 Report.pdf', type: 'file' },\n q2: { label: 'Q2 Report.pdf', type: 'file' },\n q3: { label: 'Q3 Report.pdf', type: 'file' },\n invoice: { label: 'Invoice.docx', type: 'file' },\n contract: { label: 'Contract.docx', type: 'file' },\n 'alpha-readme': { label: 'README.md', type: 'file' },\n 'beta-main': { label: 'main.py', type: 'file' },\n 'beta-config': { label: 'config.yml', type: 'file' },\n index: { label: 'index.ts', type: 'file' },\n utils: { label: 'utils.ts', type: 'file' },\n backup2023: { label: 'backup.zip', type: 'file' },\n data2023: { label: 'data.csv', type: 'file' },\n backup2024: { label: 'backup.zip', type: 'file' },\n data2024: { label: 'data.csv', type: 'file' },\n};\n\nconst loadItems = async (item: SimpleTreeItem): Promise<SimpleTreeItem[]> => {\n await new Promise((r) => setTimeout(r, 600));\n const node = filesystem[item.itemId];\n if (!node || node.type !== 'folder') return [];\n return node.children.map((childId) => {\n const child = filesystem[childId];\n return {\n itemId: childId,\n label: child.label,\n ...(child.type === 'folder' ? { loadItems } : {}),\n };\n });\n};\n\nconst items: SimpleTreeItem[] = [\n {\n itemId: 'root',\n label: 'Root',\n items: [\n { itemId: 'documents', label: 'Documents', loadItems },\n { itemId: 'projects', label: 'Projects', loadItems },\n { itemId: 'archives', label: 'Archives', loadItems },\n ],\n },\n];\n\nexport default function WithDynamicLoadingExample(): React.JSX.Element {\n return (\n <div>\n <SimpleTree\n items={items}\n withSearch\n searchPlaceholder=\"Search...\"\n onExpand={(itemId) => console.log('Expanded:', itemId)}\n onClickRow={(itemId) => console.log('Clicked:', itemId)}\n />\n </div>\n );\n}\n```\n\n## With External QueryClient\n\n**Requires `@tanstack/react-query`** (v4 or v5).\n\nPass an external `QueryClient` via the `queryClient` prop to share the cache with the rest of your app, inspect tree queries in React Query DevTools, or apply custom retry / staleTime / error handlers globally. Combine with `queryKeyPrefix` when multiple tree instances on the same page share a single client to avoid query-key collisions.\n\n```tsx\n// WithExternalQueryClientExample.tsx\nimport React, { useState } from 'react';\nimport { QueryClient } from '@tanstack/react-query';\nimport { SimpleTree, SimpleTreeItem } from '@ringpublishing/mui-components';\n\nconst items: SimpleTreeItem[] = [\n {\n itemId: 'root',\n label: 'Root',\n items: [\n {\n itemId: 'lazy',\n label: 'Loads children on expand',\n loadItems: async (): Promise<SimpleTreeItem[]> => {\n await new Promise((r) => setTimeout(r, 400));\n\n return [{ itemId: 'child-1', label: 'Loaded child' }];\n },\n },\n ],\n },\n];\n\nexport default function WithExternalQueryClientExample(): React.JSX.Element {\n const [queryClient] = useState(\n () =>\n new QueryClient({\n defaultOptions: { queries: { staleTime: Infinity, retry: false } },\n }),\n );\n\n return <SimpleTree items={items} queryClient={queryClient} />;\n}\n```\n\n## With Custom Elements\n\nEach item can render a custom `element` on the right side, such as badges or chips.\n\n```tsx\n// WithCustomElementsExample.tsx\nimport React from 'react';\nimport { Chip } from '@mui/material';\nimport { SimpleTree, SimpleTreeItem } from '@ringpublishing/mui-components';\n\nconst items: SimpleTreeItem[] = [\n {\n itemId: '0',\n label: 'Categories',\n expanded: true,\n element: <Chip color=\"primary\" label={3} size=\"small\" sx={{ height: '18px' }} />,\n items: [\n {\n itemId: '0.0',\n label: 'Electronics',\n element: <Chip color=\"success\" label=\"New\" size=\"small\" sx={{ height: '18px' }} />,\n items: [\n { itemId: '0.0.0', label: 'Laptops' },\n { itemId: '0.0.1', label: 'Phones' },\n ],\n },\n {\n itemId: '0.1',\n label: 'Clothing',\n element: <Chip color=\"warning\" label=\"Sale\" size=\"small\" sx={{ height: '18px' }} />,\n items: [\n { itemId: '0.1.0', label: 'Shirts' },\n { itemId: '0.1.1', label: 'Pants' },\n ],\n },\n {\n itemId: '0.2',\n label: 'Books',\n element: <Chip color=\"info\" label={42} size=\"small\" sx={{ height: '18px' }} />,\n },\n ],\n },\n {\n itemId: '1',\n label: 'Archived',\n element: <Chip color=\"default\" label=\"Disabled\" size=\"small\" sx={{ height: '18px' }} />,\n },\n];\n\nexport default function WithCustomElementsExample(): React.JSX.Element {\n return (\n <div>\n <SimpleTree\n items={items}\n onExpand={(itemId) => console.log('Expanded:', itemId)}\n onClickRow={(itemId) => console.log('Clicked:', itemId)}\n />\n </div>\n );\n}\n```\n\n## Controlled Selection\n\nControl selected items externally via `selectedItems` and `onSelectedItemsChange`.\n\n```tsx\n// ControlledSelectionExample.tsx\nimport React, { useState } from 'react';\nimport { Box, Button } from '@mui/material';\nimport { SimpleTree, SimpleTreeItem } from '@ringpublishing/mui-components';\n\nconst items: SimpleTreeItem[] = [\n {\n itemId: '0',\n label: 'Documents',\n expanded: true,\n items: [\n { itemId: '0.0', label: 'Report.pdf' },\n {\n itemId: '0.1',\n label: 'Presentations',\n items: [\n { itemId: '0.1.0', label: 'Q1 Review.pptx' },\n { itemId: '0.1.1', label: 'Q2 Review.pptx' },\n ],\n },\n { itemId: '0.2', label: 'Notes.txt' },\n ],\n },\n {\n itemId: '1',\n label: 'Images',\n items: [\n { itemId: '1.0', label: 'photo.jpg' },\n { itemId: '1.1', label: 'diagram.png' },\n ],\n },\n { itemId: '2', label: 'README.md' },\n];\n\nexport default function ControlledSelectionExample(): React.JSX.Element {\n const [selectedItems, setSelectedItems] = useState<string[]>([]);\n\n return (\n <Box>\n <Box sx={{ mb: 2, display: 'flex', gap: 1 }}>\n <Button variant=\"outlined\" size=\"small\" onClick={() => setSelectedItems([])}>\n Clear Selection\n </Button>\n <Button variant=\"outlined\" size=\"small\" onClick={() => setSelectedItems(['0.0'])}>\n Select Report.pdf\n </Button>\n <Button variant=\"outlined\" size=\"small\" onClick={() => setSelectedItems(['2'])}>\n Select README.md\n </Button>\n </Box>\n <Box sx={{ mb: 2 }}>\n <strong>Selected:</strong> {selectedItems.length > 0 ? selectedItems.join(', ') : 'None'}\n </Box>\n <SimpleTree\n items={items}\n selectedItems={selectedItems}\n onSelectedItemsChange={(itemIds) => {\n console.log('Selection changed:', itemIds);\n setSelectedItems(itemIds);\n }}\n onClickRow={(itemId) => console.log('Clicked:', itemId)}\n />\n </Box>\n );\n}\n```\n\n## With Persistence\n\nThe cache-key half of persistence (caching of dynamically-loaded items) only does work when `loadItems` is used and therefore requires `@tanstack/react-query`. The `restoreExpandedItems` / `restoreSelectedItem` flags work without it.\n\nPass a `persistence` object with a `cacheKey` to enable localStorage caching of dynamically loaded items. Use `restoreExpandedItems` and `restoreSelectedItem` to restore the tree state across page reloads.\n\n```tsx\n<SimpleTree\n items={items}\n persistence={{\n cacheKey: 'my-tree',\n restoreExpandedItems: true,\n restoreSelectedItem: true,\n }}\n/>\n```\n\n- **`cacheKey`** (required): Unique key used to namespace the localStorage entries. Use different keys for different tree instances.\n- **`restoreExpandedItems`** (optional): When `true`, the expanded items are persisted and restored on mount.\n- **`restoreSelectedItem`** (optional): When `true`, the selected item is persisted and restored on mount. Only applies in uncontrolled mode (when `selectedItems` prop is not provided).\n\n```tsx\n// WithPersistenceExample.tsx\nimport React from 'react';\nimport { SimpleTree, SimpleTreeItem } from '@ringpublishing/mui-components';\n\nconst items: SimpleTreeItem[] = [\n {\n itemId: 'root',\n label: 'Dynamic Root',\n items: [\n {\n itemId: 'static-folder',\n label: 'Static Folder',\n items: [\n { itemId: 'static-1', label: 'Static File 1.txt' },\n { itemId: 'static-2', label: 'Static File 2.txt' },\n ],\n },\n {\n itemId: 'dynamic-folder',\n label: 'Dynamic Folder (click to load)',\n loadItems: async (parent): Promise<SimpleTreeItem[]> => {\n await new Promise((resolve) => setTimeout(resolve, 1000));\n return [\n { itemId: `${parent.itemId}-loaded-1`, label: 'Loaded File 1.txt' },\n { itemId: `${parent.itemId}-loaded-2`, label: 'Loaded File 2.txt' },\n { itemId: `${parent.itemId}-loaded-3`, label: 'Loaded File 3.txt' },\n ];\n },\n },\n ],\n },\n];\n\nexport default function WithPersistenceExample(): React.JSX.Element {\n return (\n <div>\n <SimpleTree\n items={items}\n persistence={{\n cacheKey: 'simple-tree-demo',\n restoreExpandedItems: true,\n restoreSelectedItem: true,\n }}\n onClickRow={(itemId) => console.log('Clicked:', itemId)}\n />\n </div>\n );\n}\n```"
|
|
3157
|
-
},
|
|
3158
|
-
"organisms-sortable-list": {
|
|
3159
|
-
"id": "organisms-sortable-list",
|
|
3160
|
-
"name": "SortableList",
|
|
3161
|
-
"category": "Organisms",
|
|
3162
|
-
"title": "Components/Organisms/SortableList",
|
|
3163
|
-
"description": "A drag-and-drop sortable list component built on top of the [@dnd-kit/core](https://docs.dndkit.com/) library. It provides a container that manages drag-and-drop functionality while leaving item rendering to the developer.",
|
|
3164
|
-
"argTypes": {
|
|
3165
|
-
"items": {
|
|
3166
|
-
"description": "List of items to be sorted. Each item must have a unique `id` field.",
|
|
3167
|
-
"control": "object",
|
|
3168
|
-
"category": "data",
|
|
3169
|
-
"type": "T[]"
|
|
3170
|
-
},
|
|
3171
|
-
"renderItem": {
|
|
3172
|
-
"description": "Function that renders an element of the list.",
|
|
3173
|
-
"control": false,
|
|
3174
|
-
"category": "rendering",
|
|
3175
|
-
"type": "(item: T) => React.ReactNode"
|
|
3176
|
-
},
|
|
3177
|
-
"onChange": {
|
|
3178
|
-
"description": "Callback called when the order of items changes. Receives the reordered list.",
|
|
3179
|
-
"control": false,
|
|
3180
|
-
"category": "callbacks",
|
|
3181
|
-
"type": "(items: T[]) => void"
|
|
3182
|
-
},
|
|
3183
|
-
"grabByDragHandle": {
|
|
3184
|
-
"description": "If true, items can be grabbed only by the drag handles. Developers need to incorporate `SortableList.DragHandle` component in their item's children. **Warning:** Setting this to `true` without rendering `<SortableList.DragHandle />` inside items will make the list un-draggable.",
|
|
3185
|
-
"control": "boolean",
|
|
3186
|
-
"category": "behavior",
|
|
3187
|
-
"type": "boolean",
|
|
3188
|
-
"defaultValue": "false"
|
|
3189
|
-
},
|
|
3190
|
-
"children": {
|
|
3191
|
-
"description": "Inherited from CommonComponentProps but not used. Item rendering is controlled via `renderItem`.",
|
|
3192
|
-
"control": false,
|
|
3193
|
-
"category": "content",
|
|
3194
|
-
"type": "React.ReactNode"
|
|
3195
|
-
},
|
|
3196
|
-
"sx": {
|
|
3197
|
-
"description": "MUI System properties to customize the main element style.",
|
|
3198
|
-
"control": "object",
|
|
3199
|
-
"category": "customization",
|
|
3200
|
-
"type": "SxProps<Theme>"
|
|
3201
|
-
},
|
|
3202
|
-
"className": {
|
|
3203
|
-
"description": "CSS class name applied to the main element.",
|
|
3204
|
-
"control": "text",
|
|
3205
|
-
"category": "customization",
|
|
3206
|
-
"type": "string"
|
|
3207
|
-
},
|
|
3208
|
-
"dataTestIdSuffix": {
|
|
3209
|
-
"description": "Inherited from CommonComponentProps. Not yet implemented in SortableList.",
|
|
3210
|
-
"control": false,
|
|
3211
|
-
"category": "customization",
|
|
3212
|
-
"type": "string"
|
|
3213
|
-
}
|
|
3214
|
-
},
|
|
3215
|
-
"storyNames": [
|
|
3216
|
-
"Default",
|
|
3217
|
-
"WithDragHandle"
|
|
3218
|
-
],
|
|
3219
|
-
"docs": "# SortableList\n\nA drag-and-drop sortable list component built on top of the [@dnd-kit/core](https://docs.dndkit.com/) library. It provides a container that manages drag-and-drop functionality while leaving item rendering to the developer.\n\n- Two dragging modes: grab anywhere (default) or grab by drag handle\n- Supports clickable elements inside list items without interfering with drag behavior\n- Provides `useNonDraggableRef` hook to prevent drag on specific elements (e.g., buttons, context menus)\n- Built-in `<SortableList.DragHandle />` component for explicit drag handles\n\n## Default\n\nBy default, the entire list item is draggable. The drag event is triggered only after the user moves the mouse by a small number of pixels, so clickable elements like buttons still work correctly. Use the `useNonDraggableRef` hook to prevent drag behavior on specific interactive elements.\n\n```tsx\n// DefaultExample.tsx\nimport React from 'react';\nimport { Card, CardContent, GridLegacy as Grid, IconButton, Paper, useTheme } from '@mui/material';\nimport { MoreVert } from '@mui/icons-material';\nimport { ActionBox, SortableList, useNonDraggableRef } from '@ringpublishing/mui-components';\n\ninterface Item {\n id: number;\n field: string;\n}\n\nconst initialItems: Item[] = [\n { id: 1, field: 'Pizza' },\n { id: 2, field: 'Cheeseburger' },\n { id: 3, field: 'Pasta' },\n];\n\nfunction CustomListItem(props: { item: Item }): React.JSX.Element {\n const ref = useNonDraggableRef();\n const theme = useTheme();\n\n return (\n <Paper sx={{ marginY: theme.spacing(2) }}>\n <Card>\n <CardContent>\n <Grid container={true} spacing={2} alignItems={'center'}>\n <Grid item={true} xs={11}>\n <span>\n Field (id: {props.item.id}) - {props.item.field}\n </span>\n </Grid>\n <Grid item={true} xs={1}>\n <IconButton\n ref={ref.setRef}\n onClick={(event): void => {\n event.stopPropagation();\n }}\n >\n <MoreVert />\n </IconButton>\n <ActionBox\n actions={[\n {\n label: 'Option 1',\n onClick: () => console.log('Option 1 clicked'),\n },\n ]}\n anchorEl={ref}\n />\n </Grid>\n </Grid>\n </CardContent>\n </Card>\n </Paper>\n );\n}\n\nexport default function DefaultExample(): React.JSX.Element {\n const [items, setItems] = React.useState(initialItems);\n\n const onChange = (newItems: Item[]): void => {\n setItems(newItems);\n };\n\n const renderItem = (item: Item): React.JSX.Element => <CustomListItem item={item} />;\n\n return <SortableList items={items} onChange={onChange} renderItem={renderItem} />;\n}\n```\n\n## With DragHandle\n\nWhen `grabByDragHandle` is set to `true`, items can only be dragged by clicking and dragging the `<SortableList.DragHandle />` component. You must incorporate the `DragHandle` component in your item's children for this mode to work.\n\n### Key Features:\n\n- Items are only draggable via the dedicated drag handle icon\n- Other interactive elements work without interference\n- Provides a clear visual affordance for drag interaction\n\n### Usage:\n\n```typescript\n<SortableList\n items={items}\n onChange={handleChange}\n renderItem={(item) => (\n <div>\n <SortableList.DragHandle />\n <span>{item.field}</span>\n </div>\n )}\n grabByDragHandle={true}\n/>\n```\n\n```tsx\n// WithDragHandleExample.tsx\nimport React from 'react';\nimport { Card, CardContent, Chip, GridLegacy as Grid, IconButton, Paper, useTheme } from '@mui/material';\nimport { MoreVert } from '@mui/icons-material';\nimport { ActionBox, SortableList } from '@ringpublishing/mui-components';\n\ninterface Item {\n id: number;\n field: string;\n}\n\nconst initialItems: Item[] = [\n { id: 1, field: 'Pizza' },\n { id: 2, field: 'Cheeseburger' },\n { id: 3, field: 'Pasta' },\n];\n\nfunction CustomListItemWithDragHandle(props: { item: Item }): React.JSX.Element {\n const anchorRef = React.useRef<HTMLButtonElement>(null);\n const theme = useTheme();\n\n return (\n <Paper sx={{ marginY: theme.spacing(2) }}>\n <Card>\n <CardContent>\n <Grid container={true} spacing={2} alignItems={'center'}>\n <Grid item={true} xs={2}>\n <SortableList.DragHandle />\n </Grid>\n <Grid item={true} xs={6}>\n <span>\n Field (id: {props.item.id}) - {props.item.field}\n </span>\n </Grid>\n <Grid item={true} xs={3}>\n <Chip label={'Available'} />\n </Grid>\n <Grid item={true} xs={1}>\n <IconButton\n ref={anchorRef}\n onClick={(): void => {\n /* noop */\n }}\n >\n <MoreVert />\n </IconButton>\n <ActionBox\n actions={[\n {\n label: 'Option 1',\n onClick: () => console.log('Option 1 clicked'),\n },\n ]}\n anchorEl={anchorRef}\n />\n </Grid>\n </Grid>\n </CardContent>\n </Card>\n </Paper>\n );\n}\n\nexport default function WithDragHandleExample(): React.JSX.Element {\n const [items, setItems] = React.useState(initialItems);\n\n const onChange = (newItems: Item[]): void => {\n setItems(newItems);\n };\n\n const renderItem = (item: Item): React.JSX.Element => <CustomListItemWithDragHandle item={item} />;\n\n return <SortableList items={items} onChange={onChange} renderItem={renderItem} grabByDragHandle={true} />;\n}\n```"
|
|
3220
|
-
},
|
|
3221
|
-
"organisms-text-editor": {
|
|
3222
|
-
"id": "organisms-text-editor",
|
|
3223
|
-
"name": "TextEditor",
|
|
3224
|
-
"category": "Organisms",
|
|
3225
|
-
"title": "Components/Organisms/TextEditor",
|
|
3226
|
-
"description": "A rich text editor component built on top of [TipTap](https://tiptap.dev/), providing WYSIWYG editing capabilities with a customizable toolbar and extensible plugin system.",
|
|
3227
|
-
"argTypes": {
|
|
3228
|
-
"content": {
|
|
3229
|
-
"description": "The initial content to be rendered in the editor. Can be provided as HTML or JSON.",
|
|
3230
|
-
"control": "text",
|
|
3231
|
-
"category": "content",
|
|
3232
|
-
"type": "Content"
|
|
3233
|
-
},
|
|
3234
|
-
"onUpdate": {
|
|
3235
|
-
"description": "Callback function triggered when the editor's state is updated.",
|
|
3236
|
-
"control": false,
|
|
3237
|
-
"category": "callbacks",
|
|
3238
|
-
"type": "(editor: Editor, transaction: Transaction) => void"
|
|
3239
|
-
},
|
|
3240
|
-
"ref": {
|
|
3241
|
-
"description": "Ref to the TipTap editor instance.",
|
|
3242
|
-
"control": false,
|
|
3243
|
-
"category": "behavior",
|
|
3244
|
-
"type": "React.Ref<Editor | null>"
|
|
3245
|
-
},
|
|
3246
|
-
"onLinkClick": {
|
|
3247
|
-
"description": "Handler for adding/editing links. Receives the current link attributes and expects new attributes or null to remove. If not provided, the link menu button will not be rendered.",
|
|
3248
|
-
"control": false,
|
|
3249
|
-
"category": "callbacks",
|
|
3250
|
-
"type": "(link: TextEditorLinkAttributes) => Promise<TextEditorLinkAttributes | null>"
|
|
3251
|
-
},
|
|
3252
|
-
"onImageClick": {
|
|
3253
|
-
"description": "Handler for adding images. Expects new image attributes as a return value. If not provided, the image menu button will not be rendered.",
|
|
3254
|
-
"control": false,
|
|
3255
|
-
"category": "callbacks",
|
|
3256
|
-
"type": "() => Promise<TextEditorImageAttributes | null>"
|
|
3257
|
-
},
|
|
3258
|
-
"extensions": {
|
|
3259
|
-
"description": "Additional TipTap extensions for the editor (e.g., Heading, Code).",
|
|
3260
|
-
"control": false,
|
|
3261
|
-
"category": "behavior",
|
|
3262
|
-
"type": "(Extension | Mark)[]"
|
|
3263
|
-
},
|
|
3264
|
-
"menuControls": {
|
|
3265
|
-
"description": "Additional menu controls - TextEditorMenuToggleButtons, TextEditorMenuSelectHeading, or custom controls.",
|
|
3266
|
-
"control": false,
|
|
3267
|
-
"category": "behavior",
|
|
3268
|
-
"type": "React.JSX.Element[]"
|
|
3269
|
-
},
|
|
3270
|
-
"floatingMenu": {
|
|
3271
|
-
"description": "Floating editor menu - imported from tiptap/react (refer to TipTap documentation).",
|
|
3272
|
-
"control": false,
|
|
3273
|
-
"category": "behavior",
|
|
3274
|
-
"type": "React.JSX.Element"
|
|
3275
|
-
},
|
|
3276
|
-
"bubbleMenu": {
|
|
3277
|
-
"description": "Bubble editor menu - imported from tiptap/react (refer to TipTap documentation).",
|
|
3278
|
-
"control": false,
|
|
3279
|
-
"category": "behavior",
|
|
3280
|
-
"type": "React.JSX.Element"
|
|
3281
|
-
},
|
|
3282
|
-
"limit": {
|
|
3283
|
-
"description": "The maximum number of characters allowed in the editor.",
|
|
3284
|
-
"control": "number",
|
|
3285
|
-
"category": "validation",
|
|
3286
|
-
"type": "number"
|
|
3287
|
-
},
|
|
3288
|
-
"allowExceedLimit": {
|
|
3289
|
-
"description": "If true, the editor will allow the content to exceed the defined limit.",
|
|
3290
|
-
"control": "boolean",
|
|
3291
|
-
"category": "validation",
|
|
3292
|
-
"type": "boolean",
|
|
3293
|
-
"defaultValue": "true"
|
|
3294
|
-
},
|
|
3295
|
-
"sx": {
|
|
3296
|
-
"description": "MUI System properties to customize the main element style.",
|
|
3297
|
-
"control": "object",
|
|
3298
|
-
"category": "customization",
|
|
3299
|
-
"type": "SxProps<Theme>"
|
|
3300
|
-
},
|
|
3301
|
-
"className": {
|
|
3302
|
-
"description": "CSS class name applied to the main element.",
|
|
3303
|
-
"control": "text",
|
|
3304
|
-
"category": "customization",
|
|
3305
|
-
"type": "string"
|
|
3306
|
-
},
|
|
3307
|
-
"dataTestIdSuffix": {
|
|
3308
|
-
"description": "Optional suffix for generated test id (base: ring-text-editor).",
|
|
3309
|
-
"control": "text",
|
|
3310
|
-
"category": "customization",
|
|
3311
|
-
"type": "string"
|
|
3312
|
-
}
|
|
3313
|
-
},
|
|
3314
|
-
"storyNames": [
|
|
3315
|
-
"Default",
|
|
3316
|
-
"WithAdditionalExtensions",
|
|
3317
|
-
"WithTwoTexts"
|
|
3318
|
-
],
|
|
3319
|
-
"docs": "# TextEditor\n\nA rich text editor component built on top of [TipTap](https://tiptap.dev/), providing WYSIWYG editing capabilities with a customizable toolbar and extensible plugin system.\n\n- Built-in support for bold, italic, lists (ordered and unordered), links, and images\n- Extensible via TipTap extensions (headings, code, custom marks)\n- Customizable menu controls with `TextEditorMenuToggleButton` and `TextEditorMenuSelectHeading`\n- Character limit with visual counter\n- Link and image insertion via custom dialog callbacks\n- Supports floating menu and bubble menu via TipTap\n- Optional disable of list autoformat (`- ` / `1. `) with `disableListInputRules`\n\n## Default\n\nBasic text editor with built-in formatting options: bold, italic, ordered/unordered lists, links, and images. Includes a character limit counter.\n\n```tsx\n// DefaultExample.tsx\nimport React from 'react';\nimport { TextEditor } from '@ringpublishing/mui-components';\nimport { getImagePath, TestImage, ImageSize } from 'RingDemoImages';\n\nconst sampleText = `\n <p>Lorem ipsum <i>dolor sit</i> <b>amet</b>, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea</p>\n <p>Link: <a href=\"https://en.wikipedia.org/wiki/Lorem_ipsum\" rel=\"noopener noreferrer\" title=\"Lorem ipsum\">Lorem ipsum </a></p>\n <img src='${getImagePath(TestImage.DESERT, ImageSize.LARGE)}' alt=\"Lorem ipsum\" title=\"Image title\" />\n <ol>\n <li>First item</li>\n <li>Second item</li>\n </ol>\n <ul>\n <li>First item</li>\n <li>Second item</li>\n </ul>\n`;\n\nexport default function DefaultExample(): React.JSX.Element {\n return (\n <div style={{ width: '600px' }}>\n <TextEditor\n content={sampleText}\n onUpdate={(editor): void => {\n console.log('Content updated:', JSON.stringify(editor.storage.characterCount?.characters()));\n }}\n limit={1000}\n />\n </div>\n );\n}\n```\n\n## With Additional Extensions\n\nDemonstrates how to extend the editor with additional TipTap extensions. This example adds heading selection (h1-h6) and inline code formatting via custom menu controls.\n\n### Key Features:\n\n- `TextEditorMenuSelectHeading` for heading level selection\n- `TextEditorMenuToggleButton` for toggling code formatting\n- Custom extensions passed via the `extensions` prop\n\n### Usage:\n\n```typescript\n\n<TextEditor\n content={content}\n extensions={[Heading, Code]}\n menuControls={[\n <TextEditorMenuSelectHeading levels={[1, 2, 3, 4, 5, 6]} />,\n <TextEditorMenuToggleButton\n icon={<CodeOutlined />}\n onClick={(editor) => editor.chain().focus().toggleCode().run()}\n active={(editor) => editor.isActive('code')}\n disabled={(editor) => !editor.can().chain().focus().toggleCode().run()}\n />,\n ]}\n onUpdate={(editor, transaction) => { /* handle update */ }}\n/>\n```\n\n```tsx\n// WithAdditionalExtensionsExample.tsx\nimport React, { useState } from 'react';\nimport {\n TextEditor,\n TextEditorImageAttributes,\n TextEditorLinkAttributes,\n TextEditorMenuToggleButton,\n TextEditorMenuSelectHeading,\n TextField,\n} from '@ringpublishing/mui-components';\nimport { Button, Dialog, DialogActions, DialogContent, DialogTitle } from '@mui/material';\nimport { CodeOutlined } from '@mui/icons-material';\nimport { Extension } from '@tiptap/react';\nimport { Heading } from '@tiptap/extension-heading';\nimport { Code } from '@tiptap/extension-code';\nimport { getImagePath, TestImage, ImageSize } from 'RingDemoImages';\n\nconst sampleText = `\n <h1>Heading 1</h1>\n <p>Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the</p>\n\n <h2>Heading 2</h2>\n <p>Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the</p>\n\n <h3>Heading 3</h3>\n <p>Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the</p>\n\n <h4>Heading 4</h4>\n <p>Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the</p>\n\n <h5>Heading 5</h5>\n <p>Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the</p>\n\n <h6>Heading 6</h6>\n <p>Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the</p>\n\n <ol>\n <li>First item</li>\n <li>Second item</li>\n </ol>\n <ul>\n <li>First item</li>\n <ul>\n <li>Subitem 1</li>\n </ul>\n <li>Second item</li>\n </ul>\n\n <p>Link: <a href=\"https://en.wikipedia.org/wiki/Lorem_ipsum\" rel=\"noopener noreferrer\" title=\"Lorem ipsum\">Lorem ipsum </a></p>\n\n <img src='${getImagePath(TestImage.DESERT, ImageSize.LARGE)}' alt=\"Lorem ipsum\" title=\"Image title\" />\n`;\n\nexport default function WithAdditionalExtensionsExample(): React.JSX.Element {\n const [linkDialogOpen, setLinkDialogOpen] = useState(false);\n const [imageDialogOpen, setImageDialogOpen] = useState(false);\n\n const [linkDialogCallback, setLinkDialogCallback] = useState<\n (link: TextEditorLinkAttributes | null) => void\n // eslint-disable-next-line @typescript-eslint/no-empty-function\n >(() => () => {});\n const [imageDialogCallback, setImageDialogCallback] = useState<\n (link: TextEditorImageAttributes | null) => void\n // eslint-disable-next-line @typescript-eslint/no-empty-function\n >(() => () => {});\n\n const [link, setLink] = useState<TextEditorLinkAttributes>({\n text: '',\n href: '',\n title: '',\n role: 'data-link-role-code',\n });\n const [image, setImage] = useState<TextEditorImageAttributes>({ src: '', alt: '', title: '' });\n\n return (\n <div style={{ width: '600px' }}>\n <TextEditor\n content={sampleText}\n extensions={[Heading as Extension, Code]}\n menuControls={[\n <TextEditorMenuSelectHeading levels={[1, 2, 3, 4, 5, 6]} key={'heading'} />,\n <TextEditorMenuToggleButton\n key={'code'}\n icon={<CodeOutlined />}\n onClick={(editor): boolean => editor.chain().focus().toggleCode().run()}\n active={(editor): boolean => editor.isActive('code')}\n disabled={(editor): boolean => !editor.can().chain().focus().toggleCode().run()}\n />,\n ]}\n onUpdate={(): null => {\n return null;\n }}\n onLinkClick={(link: TextEditorLinkAttributes): Promise<TextEditorLinkAttributes | null> => {\n setLink(link);\n setLinkDialogOpen(true);\n\n return new Promise<TextEditorLinkAttributes | null>((resolve) => {\n setLinkDialogCallback(() => (link: TextEditorLinkAttributes | null) => {\n resolve(link);\n setLinkDialogOpen(false);\n });\n });\n }}\n onImageClick={(): Promise<TextEditorImageAttributes | null> => {\n setImageDialogOpen(true);\n\n return new Promise<TextEditorImageAttributes | null>((resolve) => {\n setImageDialogCallback(() => (image: TextEditorImageAttributes | null) => {\n resolve(image);\n setImageDialogOpen(false);\n });\n });\n }}\n />\n\n <Dialog open={linkDialogOpen} onClose={(): void => linkDialogCallback(null)}>\n <DialogTitle>Set link</DialogTitle>\n <DialogContent sx={{ '.MuiTextField-root': { margin: 1 } }}>\n <TextField\n label={'Text'}\n value={link.text}\n onChange={(e): void => setLink({ ...link, text: e.target.value })}\n />\n <TextField\n label={'Href'}\n value={link.href}\n onChange={(e): void => setLink({ ...link, href: e.target.value })}\n />\n <TextField\n label={'Title'}\n value={link.title}\n onChange={(e): void => setLink({ ...link, title: e.target.value })}\n />\n </DialogContent>\n <DialogActions>\n <Button\n onClick={(): void => {\n linkDialogCallback(null);\n }}\n >\n {link.href === '' ? 'Cancel' : 'Remove'}\n </Button>\n <Button\n onClick={(): void => {\n linkDialogCallback(link);\n }}\n >\n Submit\n </Button>\n </DialogActions>\n </Dialog>\n\n <Dialog open={imageDialogOpen} onClose={(): void => imageDialogCallback(null)}>\n <DialogTitle>Set image</DialogTitle>\n <DialogContent sx={{ '.MuiTextField-root': { margin: 1 } }}>\n <TextField\n label={'Src'}\n value={image.src}\n onChange={(e): void => setImage({ ...image, src: e.target.value })}\n />\n <TextField\n label={'Alt'}\n value={image.alt}\n onChange={(e): void => setImage({ ...image, alt: e.target.value })}\n />\n <TextField\n label={'Title'}\n value={image.title}\n onChange={(e): void => setImage({ ...image, title: e.target.value })}\n />\n </DialogContent>\n <DialogActions>\n <Button\n onClick={(): void => {\n imageDialogCallback(null);\n }}\n >\n Cancel\n </Button>\n <Button\n onClick={(): void => {\n imageDialogCallback(image);\n }}\n >\n Submit\n </Button>\n </DialogActions>\n </Dialog>\n </div>\n );\n}\n```\n\n## With Two Texts\n\nDemonstrates switching between two different text contents in the same editor instance. Use the buttons above the editor to switch between Text #1 and Text #2.\n\n```tsx\n// DefaultExample.tsx\nimport React from 'react';\nimport { TextEditor } from '@ringpublishing/mui-components';\nimport { getImagePath, TestImage, ImageSize } from 'RingDemoImages';\n\nconst sampleText = `\n <p>Lorem ipsum <i>dolor sit</i> <b>amet</b>, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea</p>\n <p>Link: <a href=\"https://en.wikipedia.org/wiki/Lorem_ipsum\" rel=\"noopener noreferrer\" title=\"Lorem ipsum\">Lorem ipsum </a></p>\n <img src='${getImagePath(TestImage.DESERT, ImageSize.LARGE)}' alt=\"Lorem ipsum\" title=\"Image title\" />\n <ol>\n <li>First item</li>\n <li>Second item</li>\n </ol>\n <ul>\n <li>First item</li>\n <li>Second item</li>\n </ul>\n`;\n\nexport default function DefaultExample(): React.JSX.Element {\n return (\n <div style={{ width: '600px' }}>\n <TextEditor\n content={sampleText}\n onUpdate={(editor): void => {\n console.log('Content updated:', JSON.stringify(editor.storage.characterCount?.characters()));\n }}\n limit={1000}\n />\n </div>\n );\n}\n```"
|
|
3320
|
-
},
|
|
3321
|
-
"organisms-tree-view": {
|
|
3322
|
-
"id": "organisms-tree-view",
|
|
3323
|
-
"name": "TreeView",
|
|
3324
|
-
"category": "Organisms",
|
|
3325
|
-
"title": "Components/Organisms/TreeView",
|
|
3326
|
-
"description": "The TreeView component displays hierarchical data in an expandable/collapsible tree structure. It supports two variants: **default** (with columns, checkboxes, row actions, and drag-and-drop) and **compact** (a minimal layout with custom elements).",
|
|
3327
|
-
"argTypes": {
|
|
3328
|
-
"variant": {
|
|
3329
|
-
"description": "Presentation variant.",
|
|
3330
|
-
"control": "select",
|
|
3331
|
-
"category": "behavior",
|
|
3332
|
-
"type": "'default' | 'compact'",
|
|
3333
|
-
"options": [
|
|
3334
|
-
"default",
|
|
3335
|
-
"compact"
|
|
3336
|
-
]
|
|
3337
|
-
},
|
|
3338
|
-
"items": {
|
|
3339
|
-
"description": "Tree items: itemId, label, items (children), expanded, rowActions, withCheckbox, checked, columns, loadItems, etc.",
|
|
3340
|
-
"control": "object",
|
|
3341
|
-
"category": "content",
|
|
3342
|
-
"type": "TreeViewItem[]"
|
|
3343
|
-
},
|
|
3344
|
-
"withSearch": {
|
|
3345
|
-
"description": "Show label search.",
|
|
3346
|
-
"control": "boolean",
|
|
3347
|
-
"category": "behavior",
|
|
3348
|
-
"type": "boolean",
|
|
3349
|
-
"defaultValue": "false"
|
|
3350
|
-
},
|
|
3351
|
-
"searchDebounceTime": {
|
|
3352
|
-
"description": "Debounce time for search input in milliseconds.",
|
|
3353
|
-
"control": "number",
|
|
3354
|
-
"category": "behavior",
|
|
3355
|
-
"type": "number",
|
|
3356
|
-
"defaultValue": "500"
|
|
3357
|
-
},
|
|
3358
|
-
"searchPlaceholder": {
|
|
3359
|
-
"description": "Placeholder text for the search input.",
|
|
3360
|
-
"control": "text",
|
|
3361
|
-
"category": "content",
|
|
3362
|
-
"type": "string"
|
|
3363
|
-
},
|
|
3364
|
-
"selectedItems": {
|
|
3365
|
-
"description": "Controlled selected item IDs. When set, internal selection state is ignored.",
|
|
3366
|
-
"control": "object",
|
|
3367
|
-
"category": "state",
|
|
3368
|
-
"type": "string[]"
|
|
3369
|
-
},
|
|
3370
|
-
"onSelectedItemsChange": {
|
|
3371
|
-
"description": "Callback fired when selection changes. Receives array of selected item IDs.",
|
|
3372
|
-
"control": false,
|
|
3373
|
-
"category": "callbacks",
|
|
3374
|
-
"type": "(itemIds: string[]) => void"
|
|
3375
|
-
},
|
|
3376
|
-
"onExpand": {
|
|
3377
|
-
"description": "Callback fired when an item is expanded or collapsed.",
|
|
3378
|
-
"control": false,
|
|
3379
|
-
"category": "callbacks",
|
|
3380
|
-
"type": "(itemId: string) => void"
|
|
3381
|
-
},
|
|
3382
|
-
"onClickRow": {
|
|
3383
|
-
"description": "Callback fired when a row is clicked.",
|
|
3384
|
-
"control": false,
|
|
3385
|
-
"category": "callbacks",
|
|
3386
|
-
"type": "(itemId: string) => void"
|
|
3387
|
-
},
|
|
3388
|
-
"columns": {
|
|
3389
|
-
"description": "Default variant: column definitions (name, width, header).",
|
|
3390
|
-
"control": "object",
|
|
3391
|
-
"category": "content",
|
|
3392
|
-
"type": "TreeViewColumn[]"
|
|
3393
|
-
},
|
|
3394
|
-
"showColumnHeaders": {
|
|
3395
|
-
"description": "If true, shows column headers row. Default variant only.",
|
|
3396
|
-
"control": "boolean",
|
|
3397
|
-
"category": "appearance",
|
|
3398
|
-
"type": "boolean"
|
|
3399
|
-
},
|
|
3400
|
-
"itemsLabelColumnHeader": {
|
|
3401
|
-
"description": "Header text for the items label column.",
|
|
3402
|
-
"control": "text",
|
|
3403
|
-
"category": "content",
|
|
3404
|
-
"type": "string"
|
|
3405
|
-
},
|
|
3406
|
-
"onCheckboxChange": {
|
|
3407
|
-
"description": "Callback fired when a checkbox is toggled.",
|
|
3408
|
-
"control": false,
|
|
3409
|
-
"category": "callbacks",
|
|
3410
|
-
"type": "(itemId: string, checked: boolean) => void"
|
|
3411
|
-
},
|
|
3412
|
-
"onDragAndDropEnd": {
|
|
3413
|
-
"description": "Default variant: reorder callback.",
|
|
3414
|
-
"control": false,
|
|
3415
|
-
"category": "callbacks",
|
|
3416
|
-
"type": "(sourcePos: number[], destPos: number[]) => void"
|
|
3417
|
-
},
|
|
3418
|
-
"onDropIn": {
|
|
3419
|
-
"description": "Default variant: nest-under-target callback.",
|
|
3420
|
-
"control": false,
|
|
3421
|
-
"category": "callbacks",
|
|
3422
|
-
"type": "(itemId: string, dropInItemId: string) => void"
|
|
3423
|
-
},
|
|
3424
|
-
"dragAndDropTooltipTitle": {
|
|
3425
|
-
"description": "Tooltip text shown on expanded items during drag.",
|
|
3426
|
-
"control": "text",
|
|
3427
|
-
"category": "content",
|
|
3428
|
-
"type": "string"
|
|
3429
|
-
},
|
|
3430
|
-
"dragAndDropTooltipPlacement": {
|
|
3431
|
-
"description": "Tooltip placement for drag-and-drop hints.",
|
|
3432
|
-
"control": "text",
|
|
3433
|
-
"category": "appearance",
|
|
3434
|
-
"type": "PopperProps['placement']",
|
|
3435
|
-
"defaultValue": "top"
|
|
3436
|
-
},
|
|
3437
|
-
"dataTestIdSuffix": {
|
|
3438
|
-
"description": "Optional suffix for data-testid attributes.",
|
|
3439
|
-
"control": "text",
|
|
3440
|
-
"category": "testing",
|
|
3441
|
-
"type": "string"
|
|
3442
|
-
},
|
|
3443
|
-
"sx": {
|
|
3444
|
-
"description": "MUI System properties for custom styling.",
|
|
3445
|
-
"control": "object",
|
|
3446
|
-
"category": "customization",
|
|
3447
|
-
"type": "SxProps<Theme>"
|
|
3448
|
-
},
|
|
3449
|
-
"className": {
|
|
3450
|
-
"description": "CSS class name applied to the root element.",
|
|
3451
|
-
"control": "text",
|
|
3452
|
-
"category": "customization",
|
|
3453
|
-
"type": "string"
|
|
3454
|
-
}
|
|
3455
|
-
},
|
|
3456
|
-
"storyNames": [
|
|
3457
|
-
"Default",
|
|
3458
|
-
"CompactViewVariant",
|
|
3459
|
-
"WithSearch",
|
|
3460
|
-
"WithDragAndDrop",
|
|
3461
|
-
"WithDropIn",
|
|
3462
|
-
"WithDynamicLoading",
|
|
3463
|
-
"ControlledSelection"
|
|
3464
|
-
],
|
|
3465
|
-
"docs": "# TreeView\n\nThe TreeView component displays hierarchical data in an expandable/collapsible tree structure. It supports two variants: **default** (with columns, checkboxes, row actions, and drag-and-drop) and **compact** (a minimal layout with custom elements).\n\n**Key Features:**\n\n- Two layout variants: `default` (tabular with columns) and `compact` (minimal)\n- Expandable/collapsible nested items\n- Search and filter with word-based matching and highlighting\n- Checkbox selection with disable capability (default variant)\n- Drag and drop reordering (default variant)\n- Drop-in nesting to create new hierarchy levels (default variant)\n- Dynamic/lazy loading of child items with error handling and retry\n- Row action buttons (default variant)\n- Controlled and uncontrolled selection modes\n\n## Default\n\nBasic TreeView with columns, checkboxes, and row actions in the default variant.\n\n```tsx\n// DefaultExample.tsx\nimport React, { useState } from 'react';\nimport { TreeView, TreeViewItem } from '@ringpublishing/mui-components';\nimport { EditOutlined } from '@mui/icons-material';\n\nconst exampleItems: TreeViewItem[] = [\n {\n itemId: '0',\n label: 'Item 0',\n column1: 'Column1 0',\n column2: 'Column2 0',\n expanded: true,\n rowActions: [{ label: 'Edit', icon: <EditOutlined /> }],\n checkboxDisabled: true,\n items: [\n {\n itemId: '0.0',\n label: 'Item 0.0',\n column1: 'Column1 0.0',\n column2: 'Column2 0.0',\n checked: true,\n },\n {\n itemId: '0.1',\n label: 'Item 0.1',\n column1: 'Column1 0.1',\n column2: 'Column2 0.1',\n checked: true,\n\n items: [\n {\n itemId: '0.1.0',\n label: 'Item 0.1.0',\n column1: 'Column1 0.1.0',\n column2: 'Column2 0.1.0',\n },\n {\n itemId: '0.1.1',\n label: 'Item 0.1.1',\n column1: 'Column1 0.1.1',\n column2: 'Column2 0.1.1',\n },\n ],\n },\n {\n itemId: '0.2',\n label: 'Item 0.2',\n column1: 'Column1 0.2',\n column2: 'Column2 0.2',\n withCheckbox: false,\n },\n {\n itemId: '0.3',\n label: 'Item 0.3',\n column1: 'Column1 0.3',\n column2: 'Column2 0.3',\n withCheckbox: false,\n },\n ],\n },\n {\n itemId: '1',\n label: 'Item 1',\n column1: 'Column1 1',\n column2: 'Column2 1',\n rowActions: [{ label: 'Edit', icon: <EditOutlined /> }],\n\n items: [\n {\n itemId: '1.0',\n label: 'Item 1.0',\n column1: 'Column1 1.0',\n column2: 'Column2 1.0',\n },\n {\n itemId: '1.1',\n label: 'Item 1.1',\n column1: 'Column1 1.1',\n column2: 'Column2 1.1',\n },\n ],\n },\n {\n itemId: '2',\n label: 'Item 2',\n column1: 'Column1 2',\n column2: 'Column2 2',\n items: [\n {\n itemId: '2.0',\n label: 'Item 2.0',\n column1: 'Column1 2.0',\n column2: 'Column2 2.0',\n },\n {\n itemId: '2.1',\n label: 'Item 2.1',\n column1: 'Column1 2.1',\n column2: 'Column2 2.1',\n },\n ],\n },\n {\n itemId: '3',\n label: 'Item 3',\n column1: 'Column1 3',\n column2: 'Column2 3',\n rowActions: [{ label: 'Edit', icon: <EditOutlined /> }],\n checked: true,\n },\n];\n\nexport default function DefaultExample(): React.JSX.Element {\n const [items, setItems] = useState(exampleItems);\n\n const handleExpand = (itemId: string): void => {\n setItems((prevItems) =>\n prevItems.map((item) => (item.itemId === itemId ? { ...item, expanded: !item.expanded } : item)),\n );\n };\n\n function checkItem(items: TreeViewItem[], itemId: string, checked: boolean): TreeViewItem[] {\n const newItems: TreeViewItem[] = [];\n\n items.forEach((item) => {\n if (item.itemId === itemId) {\n newItems.push({ ...item, checked });\n } else if (item.items) {\n newItems.push({ ...item, items: checkItem(item.items, itemId, checked) });\n } else {\n newItems.push(item);\n }\n });\n\n return newItems;\n }\n\n return (\n <TreeView\n items={items}\n onExpand={handleExpand}\n showColumnHeaders={true}\n itemsLabelColumnHeader={'Name'}\n columns={[\n { name: 'column1', width: 100, header: 'First Column' },\n { name: 'column2', width: 100, header: 'Second Column' },\n ]}\n onCheckboxChange={(itemId, checked): void => {\n setItems(checkItem(items, itemId, checked));\n }}\n variant=\"default\"\n />\n );\n}\n```\n\n## Compact View Variant\n\nA compact layout variant with custom elements (Chip badges) and search functionality. Ideal for simpler tree structures that don't require columns or row actions.\n\n```tsx\n// CompactViewVariantExample.tsx\nimport React, { useState } from 'react';\nimport { TreeView, TreeViewItem } from '@ringpublishing/mui-components';\nimport { Chip } from '@mui/material';\n\nconst exampleItems: TreeViewItem[] = [\n {\n itemId: '0',\n label: 'Item 0',\n expanded: true,\n checkboxDisabled: true,\n element: <Chip label=\"4\" size=\"small\" />,\n items: [\n {\n itemId: '0.0',\n label: 'Item 0.0',\n checked: true,\n },\n {\n itemId: '0.1',\n label: 'Item 0.1',\n checked: true,\n element: <Chip label=\"2\" size=\"small\" />,\n items: [\n {\n itemId: '0.1.0',\n label: 'Item 0.1.0',\n },\n {\n itemId: '0.1.1',\n label: 'Item 0.1.1',\n },\n ],\n },\n {\n itemId: '0.2',\n label: 'Item 0.2',\n withCheckbox: false,\n },\n {\n itemId: '0.3',\n label: 'Item 0.3',\n withCheckbox: false,\n },\n ],\n },\n {\n itemId: '1',\n label: 'Item 1',\n element: <Chip label=\"2\" size=\"small\" />,\n items: [\n {\n itemId: '1.0',\n label: 'Item 1.0',\n },\n {\n itemId: '1.1',\n label: 'Item 1.1',\n },\n ],\n },\n {\n itemId: '2',\n label: 'Item 2',\n element: <Chip label=\"2\" size=\"small\" />,\n items: [\n {\n itemId: '2.0',\n label: 'Item 2.0',\n },\n {\n itemId: '2.1',\n label: 'Item 2.1',\n },\n ],\n },\n {\n itemId: '3',\n label: 'Item 3',\n checked: true,\n },\n];\n\nexport default function CompactViewVariantExample(): React.JSX.Element {\n const [items, setItems] = useState(exampleItems);\n\n const handleExpand = (itemId: string): void => {\n setItems((prevItems) =>\n prevItems.map((item) => (item.itemId === itemId ? { ...item, expanded: !item.expanded } : item)),\n );\n };\n\n return (\n <TreeView\n variant=\"compact\"\n items={items}\n onExpand={handleExpand}\n withSearch={true}\n searchPlaceholder=\"Search\"\n />\n );\n}\n```\n\n## With Search\n\nTreeView with search/filter functionality enabled. Items are filtered by matching words in their labels, with matched text highlighted.\n\n```tsx\n// WithSearchExample.tsx\nimport React, { useState } from 'react';\nimport { TreeView, TreeViewItem } from '@ringpublishing/mui-components';\nimport { EditOutlined } from '@mui/icons-material';\n\nconst exampleItems: TreeViewItem[] = [\n {\n itemId: '0',\n label: 'Item 0',\n column1: 'Column1 0',\n column2: 'Column2 0',\n expanded: true,\n rowActions: [{ label: 'Edit', icon: <EditOutlined /> }],\n items: [\n {\n itemId: '0.0',\n label: 'Item 0.0',\n column1: 'Column1 0.0',\n column2: 'Column2 0.0',\n },\n {\n itemId: '0.1',\n label: 'Item 0.1',\n column1: 'Column1 0.1',\n column2: 'Column2 0.1',\n items: [\n {\n itemId: '0.1.0',\n label: 'Item 0.1.0',\n column1: 'Column1 0.1.0',\n column2: 'Column2 0.1.0',\n },\n {\n itemId: '0.1.1',\n label: 'Item 0.1.1',\n column1: 'Column1 0.1.1',\n column2: 'Column2 0.1.1',\n },\n ],\n },\n {\n itemId: '0.2',\n label: 'Item 0.2',\n column1: 'Column1 0.2',\n column2: 'Column2 0.2',\n },\n {\n itemId: '0.3',\n label: 'Item 0.3',\n column1: 'Column1 0.3',\n column2: 'Column2 0.3',\n },\n ],\n },\n {\n itemId: '1',\n label: 'Item 1',\n column1: 'Column1 1',\n column2: 'Column2 1',\n rowActions: [{ label: 'Edit', icon: <EditOutlined /> }],\n items: [\n {\n itemId: '1.0',\n label: 'Item 1.0',\n column1: 'Column1 1.0',\n column2: 'Column2 1.0',\n },\n {\n itemId: '1.1',\n label: 'Item 1.1',\n column1: 'Column1 1.1',\n column2: 'Column2 1.1',\n },\n ],\n },\n {\n itemId: '2',\n label: 'Item 2',\n column1: 'Column1 2',\n column2: 'Column2 2',\n items: [\n {\n itemId: '2.0',\n label: 'Item 2.0',\n column1: 'Column1 2.0',\n column2: 'Column2 2.0',\n },\n {\n itemId: '2.1',\n label: 'Item 2.1',\n column1: 'Column1 2.1',\n column2: 'Column2 2.1',\n },\n ],\n },\n {\n itemId: '3',\n label: 'Item 3',\n column1: 'Column1 3',\n column2: 'Column2 3',\n rowActions: [{ label: 'Edit', icon: <EditOutlined /> }],\n },\n];\n\nexport default function WithSearchExample(): React.JSX.Element {\n const [items, setItems] = useState(exampleItems);\n\n const handleExpand = (itemId: string): void => {\n setItems((prevItems) =>\n prevItems.map((item) => (item.itemId === itemId ? { ...item, expanded: !item.expanded } : item)),\n );\n };\n\n return (\n <TreeView\n items={items}\n onExpand={handleExpand}\n withSearch={true}\n showColumnHeaders={true}\n itemsLabelColumnHeader={'Name'}\n columns={[\n { name: 'column1', width: 100, header: 'First Column' },\n { name: 'column2', width: 100, header: 'Second Column' },\n ]}\n variant=\"default\"\n />\n );\n}\n```\n\n## With Drag And Drop\n\nTreeView with drag and drop support for reordering items. Expanded items must be collapsed before they can be dragged.\n\n```tsx\n// WithDragAndDropExample.tsx\nimport React, { useState } from 'react';\nimport { TreeView, TreeViewItem } from '@ringpublishing/mui-components';\nimport { EditOutlined } from '@mui/icons-material';\n\nconst exampleItems: TreeViewItem[] = [\n {\n itemId: '0',\n label: 'Item 0',\n column1: 'Column1 0',\n column2: 'Column2 0',\n expanded: true,\n rowActions: [{ label: 'Edit', icon: <EditOutlined /> }],\n checkboxDisabled: true,\n items: [\n {\n itemId: '0.0',\n label: 'Item 0.0',\n column1: 'Column1 0.0',\n column2: 'Column2 0.0',\n checked: true,\n },\n {\n itemId: '0.1',\n label: 'Item 0.1',\n column1: 'Column1 0.1',\n column2: 'Column2 0.1',\n checked: true,\n\n items: [\n {\n itemId: '0.1.0',\n label: 'Item 0.1.0',\n column1: 'Column1 0.1.0',\n column2: 'Column2 0.1.0',\n },\n {\n itemId: '0.1.1',\n label: 'Item 0.1.1',\n column1: 'Column1 0.1.1',\n column2: 'Column2 0.1.1',\n },\n ],\n },\n {\n itemId: '0.2',\n label: 'Item 0.2',\n column1: 'Column1 0.2',\n column2: 'Column2 0.2',\n withCheckbox: false,\n },\n {\n itemId: '0.3',\n label: 'Item 0.3',\n column1: 'Column1 0.3',\n column2: 'Column2 0.3',\n withCheckbox: false,\n },\n ],\n },\n {\n itemId: '1',\n label: 'Item 1',\n column1: 'Column1 1',\n column2: 'Column2 1',\n rowActions: [{ label: 'Edit', icon: <EditOutlined /> }],\n items: [\n {\n itemId: '1.0',\n label: 'Item 1.0',\n column1: 'Column1 1.0',\n column2: 'Column2 1.0',\n },\n {\n itemId: '1.1',\n label: 'Item 1.1',\n column1: 'Column1 1.1',\n column2: 'Column2 1.1',\n },\n ],\n },\n {\n itemId: '2',\n label: 'Item 2',\n column1: 'Column1 2',\n column2: 'Column2 2',\n items: [\n {\n itemId: '2.0',\n label: 'Item 2.0',\n column1: 'Column1 2.0',\n column2: 'Column2 2.0',\n },\n {\n itemId: '2.1',\n label: 'Item 2.1',\n column1: 'Column1 2.1',\n column2: 'Column2 2.1',\n },\n ],\n },\n {\n itemId: '3',\n label: 'Item 3',\n column1: 'Column1 3',\n column2: 'Column2 3',\n rowActions: [{ label: 'Edit', icon: <EditOutlined /> }],\n checked: true,\n },\n];\n\nfunction moveItems(\n items: TreeViewItem[],\n sourceAbsolutePosition: number[],\n destinationAbsolutePosition: number[],\n): TreeViewItem[] {\n const newItems = [...items];\n\n function getArrayAndIndex(path: number[]): { array: TreeViewItem[] | undefined; index: number } {\n let array: TreeViewItem[] | undefined = newItems;\n let index = path[0];\n\n for (let i = 0; i < path.length - 1; i++) {\n const currentIndex = path[i];\n\n if (!array?.[currentIndex]?.items) {\n return { array: undefined, index: -1 };\n }\n\n array = array[currentIndex].items;\n index = path[i + 1];\n }\n\n return { array, index };\n }\n\n const { array: sourceArray, index: sourceIndex } = getArrayAndIndex(sourceAbsolutePosition);\n const { array: destinationArray, index: destinationIndex } = getArrayAndIndex(destinationAbsolutePosition);\n\n if (!sourceArray || sourceIndex === -1 || !sourceArray[sourceIndex]) {\n throw new Error('Invalid source position');\n }\n\n const [movedItem] = sourceArray.splice(sourceIndex, 1);\n\n if (!destinationArray) {\n throw new Error('Invalid destination position');\n }\n\n destinationArray.splice(destinationIndex, 0, movedItem);\n\n return newItems;\n}\n\nexport default function WithDragAndDropExample(): React.JSX.Element {\n const [items, setItems] = useState(exampleItems);\n\n const handleDragEnd = (sourceAbsolutePosition: number[], destinationAbsolutePosition: number[]): void => {\n setItems((prevItems) => moveItems(prevItems, sourceAbsolutePosition, destinationAbsolutePosition));\n };\n\n const checkItem = (items: TreeViewItem[], itemId: string, checked: boolean): TreeViewItem[] => {\n const newItems: TreeViewItem[] = [];\n\n items.forEach((item) => {\n if (item.itemId === itemId) {\n newItems.push({ ...item, checked });\n } else if (item.items) {\n newItems.push({ ...item, items: checkItem(item.items, itemId, checked) });\n } else {\n newItems.push(item);\n }\n });\n\n return newItems;\n };\n\n return (\n <TreeView\n items={items}\n onDragAndDropEnd={handleDragEnd}\n showColumnHeaders={true}\n itemsLabelColumnHeader={'Name'}\n columns={[\n { name: 'column1', width: 100, header: 'First Column' },\n { name: 'column2', width: 100, header: 'Second Column' },\n ]}\n dragAndDropTooltipTitle={'To drag and drop collapse the item first'}\n onCheckboxChange={(itemId, checked): void => {\n setItems(checkItem(items, itemId, checked));\n }}\n variant=\"default\"\n />\n );\n}\n```\n\n## With Drop In\n\nExtends drag and drop with drop-in functionality, allowing items to be dropped into other items to create new nesting levels.\n\n```tsx\n// WithDropInExample.tsx\nimport React, { useState } from 'react';\nimport { TreeView, TreeViewItem } from '@ringpublishing/mui-components';\nimport { EditOutlined } from '@mui/icons-material';\n\nconst exampleItems: TreeViewItem[] = [\n {\n itemId: '0',\n label: 'Item 0',\n column1: 'Column1 0',\n column2: 'Column2 0',\n expanded: true,\n rowActions: [{ label: 'Edit', icon: <EditOutlined /> }],\n checkboxDisabled: true,\n items: [\n {\n itemId: '0.0',\n label: 'Item 0.0',\n column1: 'Column1 0.0',\n column2: 'Column2 0.0',\n checked: true,\n },\n {\n itemId: '0.1',\n label: 'Item 0.1',\n column1: 'Column1 0.1',\n column2: 'Column2 0.1',\n checked: true,\n\n items: [\n {\n itemId: '0.1.0',\n label: 'Item 0.1.0',\n column1: 'Column1 0.1.0',\n column2: 'Column2 0.1.0',\n },\n {\n itemId: '0.1.1',\n label: 'Item 0.1.1',\n column1: 'Column1 0.1.1',\n column2: 'Column2 0.1.1',\n },\n ],\n },\n {\n itemId: '0.2',\n label: 'Item 0.2',\n column1: 'Column1 0.2',\n column2: 'Column2 0.2',\n withCheckbox: false,\n },\n {\n itemId: '0.3',\n label: 'Item 0.3',\n column1: 'Column1 0.3',\n column2: 'Column2 0.3',\n withCheckbox: false,\n },\n ],\n },\n {\n itemId: '1',\n label: 'Item 1',\n column1: 'Column1 1',\n column2: 'Column2 1',\n rowActions: [{ label: 'Edit', icon: <EditOutlined /> }],\n items: [\n {\n itemId: '1.0',\n label: 'Item 1.0',\n column1: 'Column1 1.0',\n column2: 'Column2 1.0',\n },\n {\n itemId: '1.1',\n label: 'Item 1.1',\n column1: 'Column1 1.1',\n column2: 'Column2 1.1',\n },\n ],\n },\n {\n itemId: '2',\n label: 'Item 2',\n column1: 'Column1 2',\n column2: 'Column2 2',\n items: [\n {\n itemId: '2.0',\n label: 'Item 2.0',\n column1: 'Column1 2.0',\n column2: 'Column2 2.0',\n },\n {\n itemId: '2.1',\n label: 'Item 2.1',\n column1: 'Column1 2.1',\n column2: 'Column2 2.1',\n },\n ],\n },\n {\n itemId: '3',\n label: 'Item 3',\n column1: 'Column1 3',\n column2: 'Column2 3',\n rowActions: [{ label: 'Edit', icon: <EditOutlined /> }],\n checked: true,\n },\n];\n\nfunction moveItems(\n items: TreeViewItem[],\n sourceAbsolutePosition: number[],\n destinationAbsolutePosition: number[],\n): TreeViewItem[] {\n const newItems = [...items];\n\n function getArrayAndIndex(path: number[]): { array: TreeViewItem[] | undefined; index: number } {\n let array: TreeViewItem[] | undefined = newItems;\n let index = path[0];\n\n for (let i = 0; i < path.length - 1; i++) {\n const currentIndex = path[i];\n\n if (!array?.[currentIndex]?.items) {\n return { array: undefined, index: -1 };\n }\n\n array = array[currentIndex].items;\n index = path[i + 1];\n }\n\n return { array, index };\n }\n\n const { array: sourceArray, index: sourceIndex } = getArrayAndIndex(sourceAbsolutePosition);\n const { array: destinationArray, index: destinationIndex } = getArrayAndIndex(destinationAbsolutePosition);\n\n if (!sourceArray || sourceIndex === -1 || !sourceArray[sourceIndex]) {\n throw new Error('Invalid source position');\n }\n\n const [movedItem] = sourceArray.splice(sourceIndex, 1);\n\n if (!destinationArray) {\n throw new Error('Invalid destination position');\n }\n\n destinationArray.splice(destinationIndex, 0, movedItem);\n\n return newItems;\n}\n\nfunction dropInItem(items: TreeViewItem[], itemId: string, dropInItemId: string): TreeViewItem[] {\n let movedItem: TreeViewItem | null = null;\n\n function removeItem(arr: TreeViewItem[]): TreeViewItem[] {\n return arr.reduce<TreeViewItem[]>((acc, item) => {\n if (item.itemId === itemId) {\n movedItem = item;\n\n return acc;\n }\n\n if (item.items) {\n acc.push({ ...item, items: removeItem(item.items) });\n } else {\n acc.push(item);\n }\n\n return acc;\n }, []);\n }\n\n function insertItem(arr: TreeViewItem[]): TreeViewItem[] {\n return arr.map((item) => {\n if (item.itemId === dropInItemId) {\n const children = item.items ? [...item.items] : [];\n\n if (movedItem) {\n children.push({ ...movedItem, items: movedItem.items ?? undefined });\n }\n\n return { ...item, items: children };\n }\n\n if (item.items) {\n return { ...item, items: insertItem(item.items) };\n }\n\n return item;\n });\n }\n\n const withoutItem = removeItem(items);\n\n if (!movedItem) {\n return items;\n }\n\n return insertItem(withoutItem);\n}\n\nexport default function WithDropInExample(): React.JSX.Element {\n const [items, setItems] = useState(exampleItems);\n\n const handleDragEnd = (sourceAbsolutePosition: number[], destinationAbsolutePosition: number[]): void => {\n setItems((prevItems) => moveItems(prevItems, sourceAbsolutePosition, destinationAbsolutePosition));\n };\n\n const handleDropIn = (itemId: string, dropInItemId: string): void => {\n setItems((prevItems) => dropInItem(prevItems, itemId, dropInItemId));\n };\n\n const checkItem = (items: TreeViewItem[], itemId: string, checked: boolean): TreeViewItem[] => {\n const newItems: TreeViewItem[] = [];\n\n items.forEach((item) => {\n if (item.itemId === itemId) {\n newItems.push({ ...item, checked });\n } else if (item.items) {\n newItems.push({ ...item, items: checkItem(item.items, itemId, checked) });\n } else {\n newItems.push(item);\n }\n });\n\n return newItems;\n };\n\n return (\n <TreeView\n items={items}\n onDragAndDropEnd={handleDragEnd}\n onDropIn={handleDropIn}\n showColumnHeaders={true}\n itemsLabelColumnHeader={'Name'}\n columns={[\n { name: 'column1', width: 100, header: 'First Column' },\n { name: 'column2', width: 100, header: 'Second Column' },\n ]}\n dragAndDropTooltipTitle={'To drag and drop collapse the item first'}\n onCheckboxChange={(itemId, checked): void => {\n setItems(checkItem(items, itemId, checked));\n }}\n variant=\"default\"\n />\n );\n}\n```\n\n## With Dynamic Loading\n\nDemonstrates lazy loading of child items when a parent is expanded. The `loadItems` function is called on demand and supports error handling with retry.\n\n```tsx\n// WithDynamicLoadingExample.tsx\nimport React from 'react';\nimport { TreeView, TreeViewItem } from '@ringpublishing/mui-components';\nimport { Chip } from '@mui/material';\n\nconst dynamicItems: TreeViewItem[] = [\n {\n itemId: 'mixed-content',\n label: 'Mixed: Static + Dynamic Children',\n items: [\n {\n itemId: 'static-folder',\n label: 'Static Folder',\n items: [\n { itemId: 'static-file1', label: 'Static File 1.txt' },\n { itemId: 'static-file2', label: 'Static File 2.txt' },\n ],\n },\n {\n itemId: 'dynamic-folder',\n label: 'Dynamic Folder',\n loadItems: async (item: TreeViewItem): Promise<TreeViewItem[]> => {\n await new Promise((resolve) => setTimeout(resolve, 1000));\n\n const randomId = Math.floor(Math.random() * 1000);\n const childrenCount = Math.floor(Math.random() * 5) + 1;\n\n const randomCount = Array.from({ length: childrenCount }, () => Math.floor(Math.random() * 1000));\n\n if (randomId % 5 === 0) {\n throw new Error('Random error loading dynamic folder');\n }\n\n return Array.from({ length: childrenCount }, (unused, index) => ({\n itemId: 'parent' + item.itemId + '-child-' + randomId + '-' + index,\n label: 'Dynamic File ' + randomId + '-' + index + '.txt',\n element: (\n <Chip color=\"primary\" label={randomCount[index]} size=\"small\" sx={{ height: '18px' }} />\n ),\n }));\n },\n },\n ],\n },\n];\n\nexport default function WithDynamicLoadingExample(): React.JSX.Element {\n return (\n <TreeView\n items={dynamicItems}\n variant=\"default\"\n withSearch={true}\n searchPlaceholder=\"Search dynamic items...\"\n />\n );\n}\n```\n\n## Controlled Selection\n\nExternally controlled item selection using `selectedItems` and `onSelectedItemsChange` props. Buttons allow programmatic selection of different item groups.\n\n```tsx\n// ControlledSelectionExample.tsx\nimport React, { useState } from 'react';\nimport { TreeView, TreeViewItem } from '@ringpublishing/mui-components';\nimport { Box } from '@mui/material';\n\nconst items: TreeViewItem[] = [\n {\n itemId: '0',\n label: 'Item 0',\n column1: 'Column1 0',\n column2: 'Column2 0',\n expanded: true,\n items: [\n {\n itemId: '0.0',\n label: 'Item 0.0',\n column1: 'Column1 0.0',\n column2: 'Column2 0.0',\n },\n {\n itemId: '0.1',\n label: 'Item 0.1',\n column1: 'Column1 0.1',\n column2: 'Column2 0.1',\n items: [\n {\n itemId: '0.1.0',\n label: 'Item 0.1.0',\n column1: 'Column1 0.1.0',\n column2: 'Column2 0.1.0',\n },\n {\n itemId: '0.1.1',\n label: 'Item 0.1.1',\n column1: 'Column1 0.1.1',\n column2: 'Column2 0.1.1',\n },\n ],\n },\n {\n itemId: '0.2',\n label: 'Item 0.2',\n column1: 'Column1 0.2',\n column2: 'Column2 0.2',\n },\n ],\n },\n {\n itemId: '1',\n label: 'Item 1',\n column1: 'Column1 1',\n column2: 'Column2 1',\n items: [\n {\n itemId: '1.0',\n label: 'Item 1.0',\n column1: 'Column1 1.0',\n column2: 'Column2 1.0',\n },\n {\n itemId: '1.1',\n label: 'Item 1.1',\n column1: 'Column1 1.1',\n column2: 'Column2 1.1',\n },\n ],\n },\n {\n itemId: '2',\n label: 'Item 2',\n column1: 'Column1 2',\n column2: 'Column2 2',\n items: [\n {\n itemId: '2.0',\n label: 'Item 2.0',\n column1: 'Column1 2.0',\n column2: 'Column2 2.0',\n },\n {\n itemId: '2.1',\n label: 'Item 2.1',\n column1: 'Column1 2.1',\n column2: 'Column2 2.1',\n },\n ],\n },\n {\n itemId: '3',\n label: 'Item 3',\n column1: 'Column1 3',\n column2: 'Column2 3',\n },\n];\n\nexport default function ControlledSelectionExample(): React.JSX.Element {\n const [selectedItems, setSelectedItems] = useState<string[]>([]);\n\n return (\n <Box sx={{ width: '400px' }}>\n <Box sx={{ mb: 2, display: 'flex', gap: 1 }}>\n <button onClick={() => setSelectedItems([])}>Unselect All</button>\n <button onClick={() => setSelectedItems(['0.0', '0.1', '0.2', '0.1.0', '1.0', '1.1', '2.0', '2.1'])}>\n Select Nested Items\n </button>\n <button onClick={() => setSelectedItems(['0', '1', '2', '3'])}>Select Parent Items</button>\n </Box>\n <Box sx={{ mb: 2 }}>\n <strong>Selected Items:</strong> {selectedItems.length > 0 ? selectedItems.join(', ') : 'None'}\n </Box>\n <TreeView\n items={items}\n variant=\"default\"\n selectedItems={selectedItems}\n onSelectedItemsChange={(itemIds) => setSelectedItems(itemIds)}\n onClickRow={(itemId) => console.log('Row clicked:', itemId)}\n />\n </Box>\n );\n}\n```"
|
|
3466
|
-
},
|
|
3467
|
-
"templates-data-view": {
|
|
3468
|
-
"id": "templates-data-view",
|
|
3469
|
-
"name": "DataView",
|
|
3470
|
-
"category": "Templates",
|
|
3471
|
-
"title": "Components/Templates/DataView",
|
|
3472
|
-
"description": "`DataView` is a layout component that provides a structured interface for Ring applications.\nIt organizes content into configurable slots — a main content area, optional left filter panel, optional right detail panel,\na top search bar, and a bottom bar.",
|
|
3473
|
-
"argTypes": {
|
|
3474
|
-
"slots": {
|
|
3475
|
-
"description": "Allows composing the DataView layout with custom components. Required slot is main, which is meant for DataGrid or MultimediaGrid. Left, right, and bottom slots are optional. Top slot can be used to override the default SearchBar component.",
|
|
3476
|
-
"control": "object",
|
|
3477
|
-
"category": "customization",
|
|
3478
|
-
"type": "{ main: React.JSX.Element; left?: React.JSX.Element; right?: React.JSX.Element; bottom?: React.JSX.Element; top?: React.JSX.Element; }"
|
|
3479
|
-
},
|
|
3480
|
-
"slotProps": {
|
|
3481
|
-
"description": "Allows passing props to the slot components. Top slot accepts children, menuActions and openSlotsOnMobileLabels. Bottom slot accepts BottomBarSlotProps.",
|
|
3482
|
-
"control": "object",
|
|
3483
|
-
"category": "customization",
|
|
3484
|
-
"type": "{ top?: { children?: React.JSX.Element[]; menuActions?: Action[]; openSlotsOnMobileLabels?: { leftSlot?: string; rightSlot?: string; }; }; bottom?: BottomBarSlotProps; }"
|
|
3485
|
-
},
|
|
3486
|
-
"rightSlotOpen": {
|
|
3487
|
-
"description": "State indicating whether the right slot component is open.",
|
|
3488
|
-
"control": "boolean",
|
|
3489
|
-
"category": "right",
|
|
3490
|
-
"type": "boolean"
|
|
3491
|
-
},
|
|
3492
|
-
"setRightSlotOpen": {
|
|
3493
|
-
"description": "Callback function to set the rightSlotOpen state.",
|
|
3494
|
-
"category": "right",
|
|
3495
|
-
"type": "(open: boolean) => void"
|
|
3496
|
-
},
|
|
3497
|
-
"isMobileRightSlotOpen": {
|
|
3498
|
-
"description": "Whether the mobile right slot drawer is open. Optional - if not provided, state is managed internally.",
|
|
3499
|
-
"control": "boolean",
|
|
3500
|
-
"category": "right",
|
|
3501
|
-
"type": "boolean"
|
|
3502
|
-
},
|
|
3503
|
-
"onMobileRightSlotOpen": {
|
|
3504
|
-
"description": "Callback when mobile right slot drawer open state changes. Use with isMobileRightSlotOpen for controlled mode.",
|
|
3505
|
-
"category": "right",
|
|
3506
|
-
"type": "(open: boolean) => void"
|
|
3507
|
-
},
|
|
3508
|
-
"leftSlotOpen": {
|
|
3509
|
-
"description": "State indicating whether the left slot component is open.",
|
|
3510
|
-
"control": "boolean",
|
|
3511
|
-
"category": "left",
|
|
3512
|
-
"type": "boolean"
|
|
3513
|
-
},
|
|
3514
|
-
"setLeftSlotOpen": {
|
|
3515
|
-
"description": "Callback function to set the leftSlotOpen state.",
|
|
3516
|
-
"category": "left",
|
|
3517
|
-
"type": "(open: boolean) => void"
|
|
3518
|
-
},
|
|
3519
|
-
"leftSlotWidth": {
|
|
3520
|
-
"description": "Width of the left slot component. If left slot dynamic width is enabled, it will be read from localStorage.",
|
|
3521
|
-
"category": "left",
|
|
3522
|
-
"type": "number",
|
|
3523
|
-
"defaultValue": "220"
|
|
3524
|
-
},
|
|
3525
|
-
"leftSlotDynamicWidth": {
|
|
3526
|
-
"description": "Configurations for dynamic left slot width. By default it is disabled.",
|
|
3527
|
-
"control": "object",
|
|
3528
|
-
"category": "left",
|
|
3529
|
-
"type": "{ enabled?: boolean; minWidth?: number; maxWidth?: number; onChange?: (width: number) => void; }"
|
|
3530
|
-
},
|
|
3531
|
-
"showLeftSlotToggleButton": {
|
|
3532
|
-
"description": "Whether to show the left slot toggle button in toolbars.",
|
|
3533
|
-
"control": "boolean",
|
|
3534
|
-
"category": "left",
|
|
3535
|
-
"type": "boolean",
|
|
3536
|
-
"defaultValue": "true"
|
|
3537
|
-
},
|
|
3538
|
-
"isMobileLeftSlotOpen": {
|
|
3539
|
-
"description": "Whether the mobile left slot drawer is open. Optional - if not provided, state is managed internally.",
|
|
3540
|
-
"control": "boolean",
|
|
3541
|
-
"category": "left",
|
|
3542
|
-
"type": "boolean"
|
|
3543
|
-
},
|
|
3544
|
-
"onMobileLeftSlotOpen": {
|
|
3545
|
-
"description": "Callback when mobile left slot drawer open state changes. Use with isMobileLeftSlotOpen for controlled mode.",
|
|
3546
|
-
"category": "left",
|
|
3547
|
-
"type": "(open: boolean) => void"
|
|
3548
|
-
},
|
|
3549
|
-
"mainSlotMinWidth": {
|
|
3550
|
-
"description": "Minimum width of the grid container.",
|
|
3551
|
-
"category": "main",
|
|
3552
|
-
"type": "number",
|
|
3553
|
-
"defaultValue": "500"
|
|
3554
|
-
},
|
|
3555
|
-
"onScreenSizeChange": {
|
|
3556
|
-
"description": "Callback function to be called when the screen size changes.",
|
|
3557
|
-
"category": "main",
|
|
3558
|
-
"type": "(isMobile: boolean) => void"
|
|
3559
|
-
},
|
|
3560
|
-
"sx": {
|
|
3561
|
-
"description": "MUI System properties to customize the main element style.",
|
|
3562
|
-
"control": "object",
|
|
3563
|
-
"category": "customization",
|
|
3564
|
-
"type": "SxProps<Theme>",
|
|
3565
|
-
"defaultValue": "{}"
|
|
3566
|
-
},
|
|
3567
|
-
"className": {
|
|
3568
|
-
"description": "CSS class name applied to the main element.",
|
|
3569
|
-
"control": "text",
|
|
3570
|
-
"category": "customization",
|
|
3571
|
-
"type": "string"
|
|
3572
|
-
}
|
|
3573
|
-
},
|
|
3574
|
-
"storyNames": [
|
|
3575
|
-
"Default",
|
|
3576
|
-
"WithDynamicWidthFilter",
|
|
3577
|
-
"WithoutDetailAndFilter",
|
|
3578
|
-
"WithMultimediaGrid",
|
|
3579
|
-
"WithSelectionMode",
|
|
3580
|
-
"WithBottomBarSelection"
|
|
3581
|
-
],
|
|
3582
|
-
"docs": "# DataView\n\n`DataView` is a layout component that provides a structured interface for Ring applications.\nIt organizes content into configurable slots — a main content area, optional left filter panel, optional right detail panel,\na top search bar, and a bottom bar.\n\nKey features:\n\n- **Slot-based architecture**: Compose the layout with `slots.main`, `slots.left`, `slots.right`, `slots.top`, and `slots.bottom`\n- **Responsive design**: Automatically switches to mobile drawer-based layout on smaller screens\n- **Resizable left panel**: Optional dynamic width with drag-to-resize support\n- **Detail panel toggle**: Show/hide the right detail panel with controlled or uncontrolled state\n- **Search bar integration**: Built-in `SearchBar` or custom top slot component\n- **BottomBar support**: Integrated bottom bar for selection management and bulk actions\n- **Mobile support**: Left and right panels render as drawers on mobile with controlled/uncontrolled open state\n\n## Default\n\nBasic `DataView` layout with a `DataGrid` in the main slot, a filter panel on the left, and a `Detail` panel on the right.\nClicking a row in the grid opens the detail panel with the selected item's information.\n\n```tsx\n// DefaultExample.tsx\nimport React, { useState } from 'react';\nimport { DataView, RingDataGrid } from '@ringpublishing/mui-components';\n\nexport default function DefaultExample(): React.JSX.Element {\n const sampleRows = [\n { id: 1, name: 'Sample Item 1', status: 'Active' },\n { id: 2, name: 'Sample Item 2', status: 'Inactive' },\n { id: 3, name: 'Sample Item 3', status: 'Active' },\n ];\n\n const sampleColumns = [\n { field: 'name', headerName: 'Name', width: 200 },\n { field: 'status', headerName: 'Status', width: 120 },\n ];\n\n const [detailOpen, setDetailOpen] = useState(true);\n\n const Filters = (): React.JSX.Element => (\n <div style={{ padding: '16px' }}>\n <h3>Filters</h3>\n <div style={{ marginBottom: '12px' }}>\n <label>\n <input type=\"checkbox\" /> Active Items\n </label>\n </div>\n <div style={{ marginBottom: '12px' }}>\n <label>\n <input type=\"checkbox\" /> Inactive Items\n </label>\n </div>\n <div>\n <input type=\"text\" placeholder=\"Search...\" style={{ width: '100%', padding: '8px' }} />\n </div>\n </div>\n );\n\n const DetailPanel = (): React.JSX.Element => (\n <div style={{ padding: '16px' }}>\n <h3>Item Details</h3>\n <p>\n <strong>Name:</strong> Sample Item Details\n </p>\n <p>\n <strong>Status:</strong> Active\n </p>\n <p>\n <strong>Description:</strong> This is a detailed view of the selected item.\n </p>\n <p>\n <strong>Created:</strong> 2024-01-01\n </p>\n <p>\n <strong>Modified:</strong> 2024-01-15\n </p>\n </div>\n );\n\n return (\n <DataView\n sx={{ width: '100%', height: '300px' }}\n slots={{\n main: <RingDataGrid rows={sampleRows} columns={sampleColumns} totalRowCount={sampleRows.length} />,\n left: <Filters />,\n right: <DetailPanel />,\n }}\n slotProps={{\n top: {\n defaultValue: '',\n searchFunc: (): void => {\n /* noop */\n },\n },\n }}\n rightSlotOpen={detailOpen}\n setRightSlotOpen={setDetailOpen}\n />\n );\n}\n```\n\n## Example Slots Usage\n\n```jsx\n<DataView\n slots={{\n main: <RingDataGrid rows={rows} columns={columns} totalRowCount={rows.length} />,\n left: (\n <FiltersWrapper onClear={handleClear} label=\"Filters\">\n <Accordion label=\"Status\" defaultExpanded={true}>\n <FormControlLabel label=\"Active\" control={<Checkbox />} />\n <FormControlLabel label=\"Archived\" control={<Checkbox />} />\n </Accordion>\n </FiltersWrapper>\n ),\n right: (\n <Detail\n main={{\n title: { value: selectedItem?.name },\n mediaProps: { image: selectedItem?.image, objectFit: 'cover' },\n }}\n />\n ),\n }}\n slotProps={{\n top: {\n defaultValue: '',\n searchFunc: (query) => handleSearch(query),\n children: [\n <SplitButton key=\"action\" size=\"small\" actions={[{ label: 'Publish', onClick: handlePublish }]} />,\n ],\n menuActions: [\n { label: 'Edit', icon: <EditOutlined />, onClick: handleEdit },\n { label: 'Delete', icon: <DeleteOutline />, onClick: handleDelete },\n ],\n openSlotsOnMobileLabels: {\n leftSlot: 'Filters',\n rightSlot: 'Detail',\n },\n },\n bottom: {\n labels: { selected: 'selected' },\n showVisibilityToggle: true,\n fieldMap: { name: 'title', image: 'image' },\n },\n }}\n rightSlotOpen={detailOpen}\n setRightSlotOpen={setDetailOpen}\n leftSlotOpen={filterOpen}\n setLeftSlotOpen={setFilterOpen}\n/>\n```\n\n## With Dynamic Width Filter\n\nDemonstrates the resizable left slot panel. Users can drag the right edge of the left panel to change its width\nwithin the defined `minWidth` and `maxWidth` range.\n\n### Key Properties:\n\n- `leftSlotDynamicWidth.enabled: true` — enables width resizing capability\n- `leftSlotDynamicWidth.minWidth: 200` — minimum left slot width in pixels\n- `leftSlotDynamicWidth.maxWidth: 500` — maximum left slot width in pixels\n- `leftSlotDynamicWidth.onChange` — callback function triggered when width changes\n\n### How to Test:\n\n1. Hover over the right edge of the filter panel\n2. The cursor changes to a resize cursor (↔)\n3. Click and drag to resize the filter width\n4. Width is constrained between 200–500px\n5. New width value is automatically saved to localStorage\n\n```tsx\n// WithDynamicWidthFilterExample.tsx\nimport React from 'react';\nimport { DataView, RingDataGrid } from '@ringpublishing/mui-components';\n\nexport default function WithDynamicWidthFilterExample(): React.JSX.Element {\n const sampleRows = [\n { id: 1, name: 'Sample Item 1', status: 'Active' },\n { id: 2, name: 'Sample Item 2', status: 'Inactive' },\n { id: 3, name: 'Sample Item 3', status: 'Active' },\n ];\n\n const sampleColumns = [\n { field: 'name', headerName: 'Name', width: 200 },\n { field: 'status', headerName: 'Status', width: 120 },\n ];\n\n const Filters = (): React.JSX.Element => (\n <div style={{ padding: '16px' }}>\n <h3>Filters</h3>\n <div style={{ marginBottom: '12px' }}>\n <label>\n <input type=\"checkbox\" /> Active Items\n </label>\n </div>\n <div style={{ marginBottom: '12px' }}>\n <label>\n <input type=\"checkbox\" /> Inactive Items\n </label>\n </div>\n <div>\n <input type=\"text\" placeholder=\"Search...\" style={{ width: '100%', padding: '8px' }} />\n </div>\n </div>\n );\n\n return (\n <DataView\n sx={{ width: '100%' }}\n slots={{\n left: <Filters />,\n main: <RingDataGrid rows={sampleRows} columns={sampleColumns} totalRowCount={sampleRows.length} />,\n }}\n slotProps={{\n top: {\n defaultValue: '',\n searchFunc: (): void => {\n /* noop */\n },\n },\n }}\n leftSlotOpen={true}\n leftSlotWidth={300}\n leftSlotDynamicWidth={{\n enabled: true,\n minWidth: 200,\n maxWidth: 500,\n onChange: (width) => {\n console.log('Filter width changed to:', width);\n },\n }}\n />\n );\n}\n```\n\n## Without Detail And Filter\n\n`DataView` in its minimal configuration — without left and right slots. Only the search bar and main grid content\nare displayed.\n\n```tsx\n// WithoutDetailAndFilterExample.tsx\nimport React from 'react';\nimport { DataView, RingDataGrid } from '@ringpublishing/mui-components';\n\nexport default function WithoutDetailAndFilterExample(): React.JSX.Element {\n const sampleRows = [\n { id: 1, name: 'Sample Item 1', status: 'Active' },\n { id: 2, name: 'Sample Item 2', status: 'Inactive' },\n { id: 3, name: 'Sample Item 3', status: 'Active' },\n ];\n\n const sampleColumns = [\n { field: 'name', headerName: 'Name', width: 200 },\n { field: 'status', headerName: 'Status', width: 120 },\n ];\n\n return (\n <DataView\n sx={{ width: '100%' }}\n slots={{\n main: <RingDataGrid rows={sampleRows} columns={sampleColumns} totalRowCount={sampleRows.length} />,\n }}\n slotProps={{\n top: {\n defaultValue: '',\n searchFunc: (): void => {\n /* noop */\n },\n },\n }}\n />\n );\n}\n```\n\n## With Multimedia Grid\n\n`DataView` with an embedded `MultimediaGrid` in the main slot.\n\n```tsx\n// WithMultimediaGridExample.tsx\nimport React, { useState } from 'react';\nimport {\n DataView,\n MultimediaGrid,\n Detail,\n useGridApiRef,\n useActiveCardChange,\n type MediaGridItemsProps,\n type DetailProps,\n} from '@ringpublishing/mui-components';\nimport { getImagePath, TestImage, ImageSize } from 'RingDemoImages';\n\nexport default function WithMultimediaGridExample(): React.JSX.Element {\n const [detailProps, setDetailProps] = useState<DetailProps | null>(null);\n const externalApiRef = useGridApiRef();\n\n const items: MediaGridItemsProps = [\n {\n id: 0,\n title: 'Breaking News',\n image: getImagePath(TestImage.RIVER, ImageSize.LARGE),\n fields: [{ value: 'News' }, { value: '15 minutes ago' }],\n },\n {\n id: 1,\n title: 'Technology Review',\n image: getImagePath(TestImage.APARTMENT, ImageSize.MEDIUM),\n fields: [{ value: 'Tech' }, { value: '2 hours ago' }],\n },\n {\n id: 2,\n title: 'Sports Update',\n image: getImagePath(TestImage.CAMERA, ImageSize.MEDIUM),\n fields: [{ value: 'Sports' }, { value: '4 hours ago' }],\n },\n ];\n\n useActiveCardChange(externalApiRef, ({ activeCardId }) => {\n if (activeCardId === null) {\n setDetailProps(null);\n return;\n }\n\n const item = externalApiRef.current?.getItem(activeCardId);\n setDetailProps({\n main: {\n title: { value: item?.title ?? '' },\n mediaProps: {\n image: item?.image ?? '',\n objectFit: 'cover',\n },\n },\n });\n });\n\n return (\n <DataView\n sx={{ height: 'calc(100vh - 38px)' }}\n slots={{\n main: (\n <MultimediaGrid\n apiRef={externalApiRef}\n items={items}\n totalRowCount={items.length}\n checkboxSelection={true}\n disableSelectionOnClick={true}\n slotProps={{\n mediaCard: {\n slotProps: {\n checkbox: { showOnHover: true },\n },\n },\n }}\n />\n ),\n right: <Detail empty={detailProps === null} {...detailProps} />,\n }}\n slotProps={{\n top: {\n defaultValue: '',\n searchFunc: (): void => {\n /* noop */\n },\n openSlotsOnMobileLabels: {\n rightSlot: 'Detail',\n },\n },\n }}\n rightSlotOpen={false}\n />\n );\n}\n```\n\n## With Selection Mode\n\nDemonstrates `DataView` with `MultimediaGrid` checkbox selection and bottom bar integration for tracking selected items.\nSelection state is managed via `checkboxSelection` and `disableSelectionOnClick` props on MultimediaGrid.\n\n```tsx\n// WithSelectionModeExample.tsx\nimport React, { useState } from 'react';\nimport { DataView, MultimediaGrid, type MediaGridItemProps } from '@ringpublishing/mui-components';\nimport { getImagePath, TestImage, ImageSize } from 'RingDemoImages';\n\nexport default function WithSelectionModeExample(): React.JSX.Element {\n const [detailOpen, setDetailOpen] = useState(true);\n const [filterOpen, setFilterOpen] = useState(true);\n\n const items: MediaGridItemProps[] = [\n {\n id: '1',\n title: 'Sample Item 1',\n image: getImagePath(TestImage.ANIMAL, ImageSize.MEDIUM),\n },\n {\n id: '2',\n title: 'Sample Item 2',\n image: getImagePath(TestImage.BIRD, ImageSize.MEDIUM),\n },\n {\n id: '3',\n title: 'Sample Item 3',\n image: getImagePath(TestImage.FARM, ImageSize.MEDIUM),\n },\n ];\n\n const Filters = (): React.JSX.Element => (\n <div style={{ padding: '16px' }}>\n <h3>Filters</h3>\n </div>\n );\n\n const DetailPanel = (): React.JSX.Element => (\n <div style={{ padding: '16px' }}>\n <h3>Item Details</h3>\n </div>\n );\n\n return (\n <DataView\n sx={{ width: '100%', height: '500px' }}\n slots={{\n main: (\n <MultimediaGrid\n items={items}\n totalRowCount={items.length}\n checkboxSelection={true}\n disableSelectionOnClick={true}\n slotProps={{\n mediaCard: {\n slotProps: {\n checkbox: {\n showOnHover: true,\n },\n },\n },\n }}\n />\n ),\n left: <Filters />,\n right: <DetailPanel />,\n }}\n slotProps={{\n top: {\n defaultValue: '',\n searchFunc: (): void => {\n /* noop */\n },\n openSlotsOnMobileLabels: {\n rightSlot: 'Detail',\n leftSlot: 'Filters',\n },\n },\n bottom: {\n labels: {\n selected: 'selected',\n },\n showVisibilityToggle: true,\n showImagePlaceholder: true,\n fieldMap: {\n name: 'title',\n image: 'image',\n },\n },\n }}\n rightSlotOpen={detailOpen}\n setRightSlotOpen={setDetailOpen}\n leftSlotOpen={filterOpen}\n setLeftSlotOpen={setFilterOpen}\n />\n );\n}\n```\n\n## With BottomBar Selection\n\nFull-featured `DataView` with `MultimediaGrid` and bottom bar for managing multi-item selection.\n\n### Selection Features\n\n**MultimediaGrid Configuration**\n\n- `checkboxSelection={true}` — enables checkbox-based multi-select mode\n- `disableSelectionOnClick={true}` — cards open detail view; only checkboxes toggle selection\n- `showOnHover={true}` — checkboxes appear on hover for a cleaner interface\n\n```tsx\n// WithBottomBarSelectionExample.tsx\nimport React, { useState } from 'react';\nimport {\n DataView,\n MultimediaGrid,\n useGridApiRef,\n useActiveCardChange,\n Detail,\n SplitButton,\n type MediaGridItemsProps,\n type MediaGridItemProps,\n type DetailProps,\n} from '@ringpublishing/mui-components';\nimport type { GridRowId, GridRowSelectionModel } from '@mui/x-data-grid-pro';\nimport { getImagePath, TestImage, ImageSize } from 'RingDemoImages';\n\nexport default function WithBottomBarSelectionExample(): React.JSX.Element {\n const items: MediaGridItemsProps = [\n {\n id: 0,\n title: 'Breaking News: Election Results',\n image: getImagePath(TestImage.RIVER, ImageSize.LARGE),\n fields: [\n { value: 'Redakcja Polityczna' },\n { value: 'Najważniejsze wyniki wyborów samorządowych 2024' },\n { value: '15 minut temu' },\n ],\n },\n {\n id: 1,\n title: 'Wywiad z ekspertem ekonomicznym',\n image: getImagePath(TestImage.PEOPLE, ImageSize.MEDIUM),\n fields: [\n { value: 'Anna Kowalska' },\n { value: 'Analiza sytuacji na rynku nieruchomości' },\n { value: '2 godziny temu' },\n ],\n },\n {\n id: 2,\n title: 'Relacja z meczu Polska - Niemcy',\n image: getImagePath(TestImage.CAMERA, ImageSize.MEDIUM),\n fields: [\n { value: 'Sport24' },\n { value: 'Dramatyczny mecz zakończony w dogrywce' },\n { value: '4 godziny temu' },\n ],\n },\n ];\n\n const [detailProps, setDetailProps] = useState<DetailProps | null>(null);\n const [detailOpen, setDetailOpen] = useState(false);\n const externalApiRef = useGridApiRef();\n const [rowSelectionModel, setRowSelectionModel] = useState<GridRowSelectionModel>({\n type: 'include',\n ids: new Set(),\n });\n\n useActiveCardChange(externalApiRef, ({ activeCardId }) => {\n if (activeCardId === null) {\n setDetailProps(null);\n\n return;\n }\n\n const item = externalApiRef.current?.getItem(activeCardId);\n setDetailProps({\n main: {\n title: { value: item?.title ?? '' },\n mediaProps: {\n image: item?.image ?? '',\n objectFit: 'cover',\n },\n },\n });\n });\n\n const selectableItems = items.filter((item): item is MediaGridItemProps => !('separator' in item));\n const selectableItemIds = selectableItems.map((item) => item.id as GridRowId);\n const isAllSelected = selectableItemIds.length > 0 && rowSelectionModel.ids.size === selectableItemIds.length;\n\n const handleSelectAll = (): void => {\n if (!externalApiRef.current) return;\n const selectionModel: GridRowSelectionModel = {\n type: 'include',\n ids: new Set(selectableItemIds),\n };\n externalApiRef.current.setSelectionModel(selectionModel);\n setRowSelectionModel(selectionModel);\n };\n\n const handleClearSelection = (): void => {\n if (!externalApiRef.current) return;\n externalApiRef.current.clearSelection();\n setRowSelectionModel({ type: 'include', ids: new Set() });\n };\n\n const detail = <Detail empty={detailProps === null} {...detailProps} />;\n\n return (\n <DataView\n sx={{ height: 'calc(100vh - 38px)' }}\n slots={{\n main: (\n <MultimediaGrid\n onSelectionModelChange={(newSelection): void => setRowSelectionModel(newSelection)}\n selectionModel={rowSelectionModel}\n apiRef={externalApiRef}\n items={items}\n totalRowCount={items.length}\n checkboxSelection={true}\n disableSelectionOnClick={true}\n slotProps={{\n mediaCard: {\n slotProps: {\n checkbox: { showOnHover: true },\n },\n },\n }}\n />\n ),\n right: detail,\n }}\n slotProps={{\n top: {\n defaultValue: '',\n searchFunc: (): void => {\n /* noop */\n },\n openSlotsOnMobileLabels: {\n rightSlot: 'Detail',\n },\n children: [\n <SplitButton\n key=\"selection-actions\"\n variant=\"contained\"\n size=\"small\"\n actions={[\n {\n label: 'Select all',\n onClick: handleSelectAll,\n disabled: isAllSelected,\n },\n {\n label: 'Clear selection',\n onClick: handleClearSelection,\n disabled: rowSelectionModel.ids.size === 0,\n },\n ]}\n />,\n ],\n },\n bottom: {\n labels: {\n selected: 'selected',\n },\n showVisibilityToggle: true,\n showImagePlaceholder: true,\n fieldMap: {\n name: 'title',\n image: 'image',\n },\n // custom multiline tooltip per selected item; falls back to the label when omitted\n getTooltip: (row: Record<string, unknown>): React.ReactNode => {\n const fields = (row.fields as { value: string }[] | undefined) ?? [];\n\n return (\n <>\n <strong>{row.title as string}</strong>\n {fields[0] && (\n <>\n <br />\n {fields[0].value}\n </>\n )}\n </>\n );\n },\n },\n }}\n rightSlotOpen={detailOpen}\n setRightSlotOpen={setDetailOpen}\n />\n );\n}\n```"
|
|
3583
|
-
}
|
|
3584
|
-
}
|
|
3585
|
-
}
|