@ringpublishing/mui-components-mcp 1.16.5 → 1.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,5 +1,5 @@
1
1
  {
2
- "generated": "2026-08-20T11:58:30.526Z",
2
+ "generated": "2026-09-04T08:20:25.504Z",
3
3
  "importPath": "@ringpublishing/mui-components",
4
4
  "componentCount": 35,
5
5
  "components": {
@@ -913,6 +913,12 @@
913
913
  "category": "content",
914
914
  "type": "Action[]"
915
915
  },
916
+ "menuListActions": {
917
+ "description": "Menu list heading and action labels for stories. The story adds refs and callbacks at render time. Ignored when renderGroup is provided.",
918
+ "control": "object",
919
+ "category": "content",
920
+ "type": "{ label?: string; actions: Array<{ label: string; icon?: ReactNode; ariaLabel?: string; disabled?: boolean; disabledReason?: string }> }"
921
+ },
916
922
  "showRecentlyUsed": {
917
923
  "description": "Show recently used items grouped separately in the dropdown.",
918
924
  "control": "boolean",
@@ -955,6 +961,7 @@
955
961
  "storyNames": [
956
962
  "Default",
957
963
  "WithDropdownActions",
964
+ "WithMenuListAction",
958
965
  "WithMultipleSelection",
959
966
  "WithMultipleDropdownActions",
960
967
  "WithRecentlyUsed",
@@ -969,7 +976,7 @@
969
976
  "WithChipActions",
970
977
  "WithChipDetails"
971
978
  ],
972
- "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 Chip Actions\n\nUse `renderChip` when selected values need their own interactive UI. The callback\nis called separately for each selected option, so every chip can receive different\nactions based on its own data. The returned node can contain the chip and an\n`ActionBox` or any other supporting component.\n\n`chipProps` contains the props provided by MUI Autocomplete, including the default\ndelete handler. Pass these props to the custom `Chip` to preserve chip removal.\n\n`renderValue` takes precedence over `renderTags`, which takes precedence over\n`renderChip`. Therefore, `renderChip` is used only with `multiple={true}` when\nneither of the other callbacks is provided. The component warns in development\nwhen `renderChip` is ignored for one of these reasons.\n\nCustom rendering returns exactly the node from the callback: the default label\ntooltip is not added automatically. Add it explicitly when needed:\n\n```tsx\nrenderChip={({ label, chipProps }) => (\n <Tooltip title={label}>\n <Chip {...chipProps} />\n </Tooltip>\n)}\n```\n\n`chipProps` is already merged as `{ ...muiChipProps, ...slotProps.chip, label }`.\nThe computed `label` is applied last and stays consistent with the `label`\nprovided in the callback context. `slotProps.chip` may still override properties\nsuch as `onDelete` or `disabled`.\n\n```tsx\n// WithChipActionsExample.tsx\nimport React from 'react';\nimport { Box, Chip } from '@mui/material';\nimport { Delete, OpenInNew, Star, StarBorder } from '@mui/icons-material';\nimport { ActionBox, Autocomplete, ActionBoxItem } from '@ringpublishing/mui-components';\n\ninterface Option {\n id: number;\n label: string;\n}\n\nconst options: Option[] = [\n { id: 1, label: 'Onet' },\n { id: 2, label: 'Fakt' },\n { id: 3, label: 'Newsweek' },\n];\n\ninterface OptionChipProps {\n option: Option;\n label: string;\n chipProps: React.ComponentProps<typeof Chip>;\n isMain: boolean;\n onSetMain: () => void;\n}\n\nfunction OptionChip({ option, label, chipProps, isMain, onSetMain }: OptionChipProps): React.JSX.Element {\n const anchorRef = React.useRef<HTMLDivElement>(null);\n const actions: ActionBoxItem[] = [\n {\n label: 'Open portal',\n onClick: (): void => console.info('Details', option),\n icon: <OpenInNew />,\n },\n {\n label: isMain ? 'Unset as main' : 'Set as main',\n onClick: onSetMain,\n icon: isMain ? <StarBorder /> : <Star />,\n hasSeparatorAfter: true,\n },\n {\n label: 'Remove from selection',\n onClick: (event?: React.MouseEvent<Element, MouseEvent>): void =>\n chipProps.onDelete?.(event as React.SyntheticEvent),\n icon: <Delete />,\n },\n ];\n\n return (\n <>\n <Box\n ref={anchorRef}\n onClick={(): void => undefined}\n sx={{\n cursor: 'pointer',\n display: 'inline-flex',\n }}\n >\n <Chip\n {...chipProps}\n label={label}\n color={isMain ? 'primary' : 'default'}\n onClick={(): void => undefined}\n />\n </Box>\n <ActionBox actions={actions} anchorEl={anchorRef} placement=\"bottom-start\" />\n </>\n );\n}\n\nexport default function WithChipActionsExample(): React.JSX.Element {\n const [selectedOptions, setSelectedOptions] = React.useState(options);\n const [mainOptionId, setMainOptionId] = React.useState(options[0].id);\n\n const handleChange = (nextOptions: Option[]): void => {\n setSelectedOptions(nextOptions);\n\n if (!nextOptions.some((option) => option.id === mainOptionId)) {\n setMainOptionId(nextOptions[0]?.id ?? 0);\n }\n };\n\n return (\n <Autocomplete<Option>\n options={options}\n value={selectedOptions}\n onChange={(event, nextValue): void => handleChange(nextValue as Option[])}\n multiple={true}\n labels={{ title: 'Select portals' }}\n renderChip={({ option, label, chipProps }): React.JSX.Element => (\n <OptionChip\n option={option}\n label={label}\n chipProps={chipProps}\n isMain={option.id === mainOptionId}\n onSetMain={(): void =>\n setMainOptionId(\n option.id === mainOptionId\n ? (selectedOptions.find((selectedOption) => selectedOption.id !== option.id)?.id ?? 0)\n : option.id,\n )\n }\n />\n )}\n sx={{ width: 420 }}\n />\n );\n}\n```\n\n## With Chip Details\n\n`renderChip` is not limited to `ActionBox`. A custom renderer can attach a Popper,\ndialog, tooltip, or any other UI containing additional information about the\nselected option.\n\n```tsx\n// WithChipDetailsExample.tsx\nimport { Article, CalendarMonth, OpenInNew, People, Verified } from '@mui/icons-material';\nimport { Box, Button, Chip, ClickAwayListener, Divider, Paper, Popper, Stack, Typography } from '@mui/material';\nimport { Autocomplete } from '@ringpublishing/mui-components';\nimport React from 'react';\n\ninterface Option {\n id: number;\n label: string;\n description: string;\n category: string;\n monthlyReaders: string;\n lastPublished: string;\n status: 'Active' | 'Review pending';\n}\n\nconst options: Option[] = [\n {\n id: 1,\n label: 'Onet',\n description: 'News and information portal covering current events, technology and lifestyle.',\n category: 'General news',\n monthlyReaders: '18.4M',\n lastPublished: 'Today, 09:42',\n status: 'Active',\n },\n {\n id: 2,\n label: 'Fakt',\n description: 'Daily news and opinion portal with a focus on fast, accessible reporting.',\n category: 'Daily news',\n monthlyReaders: '9.8M',\n lastPublished: 'Today, 08:15',\n status: 'Review pending',\n },\n {\n id: 3,\n label: 'Newsweek',\n description: 'Weekly magazine and website with long-form journalism and analysis.',\n category: 'Magazine',\n monthlyReaders: '4.2M',\n lastPublished: 'Yesterday, 17:30',\n status: 'Active',\n },\n];\n\ninterface OptionChipProps {\n option: Option;\n label: string;\n chipProps: React.ComponentProps<typeof Chip>;\n}\n\nfunction OptionChip({ option, label, chipProps }: OptionChipProps): React.JSX.Element {\n const [open, setOpen] = React.useState(false);\n const anchorRef = React.useRef<HTMLDivElement>(null);\n\n return (\n <>\n <Box ref={anchorRef} sx={{ cursor: 'pointer', display: 'inline-flex' }}>\n <Chip {...chipProps} label={label} onClick={(): void => setOpen((currentOpen) => !currentOpen)} />\n </Box>\n <Popper open={open} anchorEl={anchorRef.current} placement=\"bottom-start\">\n <ClickAwayListener onClickAway={(): void => setOpen(false)}>\n <Paper elevation={4} sx={{ p: 2, width: 360 }}>\n <Stack spacing={2}>\n <Box>\n <Stack direction=\"row\" justifyContent=\"space-between\" alignItems=\"flex-start\">\n <Box>\n <Typography variant=\"h6\">{option.label}</Typography>\n <Typography color=\"text.secondary\" variant=\"body2\">\n {option.category}\n </Typography>\n </Box>\n <Stack direction=\"row\" spacing={1} alignItems=\"center\">\n <Verified\n color={option.status === 'Active' ? 'success' : 'warning'}\n fontSize=\"small\"\n />\n <Typography variant=\"caption\">{option.status}</Typography>\n </Stack>\n </Stack>\n <Typography sx={{ mt: 1 }} variant=\"body2\">\n {option.description}\n </Typography>\n </Box>\n\n <Divider />\n\n <Box sx={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 2 }}>\n <Stack direction=\"row\" spacing={1} alignItems=\"center\">\n <People color=\"action\" fontSize=\"small\" />\n <Box>\n <Typography color=\"text.secondary\" variant=\"caption\">\n Monthly readers\n </Typography>\n <Typography variant=\"body2\">{option.monthlyReaders}</Typography>\n </Box>\n </Stack>\n <Stack direction=\"row\" spacing={1} alignItems=\"center\">\n <Article color=\"action\" fontSize=\"small\" />\n <Box>\n <Typography color=\"text.secondary\" variant=\"caption\">\n Content type\n </Typography>\n <Typography variant=\"body2\">{option.category}</Typography>\n </Box>\n </Stack>\n <Stack direction=\"row\" spacing={1} alignItems=\"center\">\n <CalendarMonth color=\"action\" fontSize=\"small\" />\n <Box>\n <Typography color=\"text.secondary\" variant=\"caption\">\n Last published\n </Typography>\n <Typography variant=\"body2\">{option.lastPublished}</Typography>\n </Box>\n </Stack>\n </Box>\n\n <Stack direction=\"row\" spacing={1} justifyContent=\"flex-end\">\n <Button size=\"small\" onClick={(): void => setOpen(false)}>\n Close\n </Button>\n <Button\n endIcon={<OpenInNew />}\n size=\"small\"\n variant=\"contained\"\n onClick={(): void => {\n window.open('https://www.example.com', '_blank', 'noopener,noreferrer');\n }}\n >\n Open portal\n </Button>\n </Stack>\n </Stack>\n </Paper>\n </ClickAwayListener>\n </Popper>\n </>\n );\n}\n\nexport default function WithChipDetailsExample(): React.JSX.Element {\n return (\n <Autocomplete<Option>\n options={options}\n defaultValue={[options[0], options[1]]}\n multiple={true}\n labels={{ title: 'Select portals' }}\n renderChip={({ option, label, chipProps }): React.ReactElement => (\n <OptionChip option={option} label={label} chipProps={chipProps} />\n )}\n sx={{ width: 420 }}\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```"
979
+ "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 Menu List Action\n\nAn autocomplete menu list can render multiple icon buttons after its heading. The `anchorRef` from an action can be passed to `ActionBox` to render a custom action menu below that icon button.\n\nUse the `menuListActions` story control to edit the heading and action labels. The story adds refs and callbacks at render time:\n\n```tsx\n<Autocomplete\n options={options}\n labels={{ title: 'Search by' }}\n menuListActions={{\n label: 'Results',\n actions: [\n { label: 'Configure results', icon: <Tune />, anchorRef: configureRef },\n { label: 'More actions', icon: <MoreVert />, onClick: handleMoreActions },\n {\n label: 'Save results',\n icon: <Save />,\n disabled: true,\n disabledReason: 'Select a result before saving',\n },\n ],\n }}\n/>\n```\n\n```tsx\n// WithMenuListActionExample.tsx\nimport { MoreVert, Save, Tune } from '@mui/icons-material';\nimport React, { useCallback, useRef, useState } from 'react';\nimport { ActionBox, ActionBoxItem, Autocomplete } from '@ringpublishing/mui-components';\n\ninterface Option {\n label: string;\n id: number;\n}\n\nexport default function WithMenuListActionExample(): React.JSX.Element {\n const actionBoxAnchorRef = useRef<HTMLButtonElement>(null);\n const [isAnchorMounted, setIsAnchorMounted] = useState(false);\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 { label: 'LabelWithVeryLongTextThatShouldBeBreakToNextLine', id: 7 },\n ];\n const menuActions: ActionBoxItem[] = [\n {\n label: 'Show active results',\n icon: <Tune />,\n onClick: (): void => undefined,\n },\n {\n label: 'Show all results',\n onClick: (): void => undefined,\n },\n ];\n const configureResultsAction = (): void => undefined;\n const moreResultsActionsAction = (): void => undefined;\n const setAnchorRef = useCallback((element: HTMLButtonElement | null): void => {\n actionBoxAnchorRef.current = element;\n setIsAnchorMounted(Boolean(element));\n }, []);\n\n return (\n <>\n <Autocomplete\n options={options}\n labels={{ title: 'Search by' }}\n menuListActions={{\n label: 'Results',\n actions: [\n {\n label: 'Configure results',\n icon: <Tune />,\n anchorRef: setAnchorRef,\n onClick: configureResultsAction,\n },\n {\n label: 'More results actions',\n icon: <MoreVert />,\n onClick: moreResultsActionsAction,\n },\n {\n label: 'Save results',\n icon: <Save />,\n disabled: true,\n disabledReason: 'Select a result before saving',\n onClick: moreResultsActionsAction,\n },\n ],\n }}\n sx={{ width: 300 }}\n />\n {isAnchorMounted && (\n <ActionBox actions={menuActions} anchorEl={actionBoxAnchorRef} placement=\"bottom-end\" zIndex={1400} />\n )}\n </>\n );\n}\n```\n\n## With Menu List Actions With groupBy and ActionBox\n\nWhen `groupBy` is provided, a single menu list action is rendered next to the first group heading. Its `anchorRef` can be used to open an external `ActionBox` while keeping the Autocomplete options available.\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 Chip Actions\n\nUse `renderChip` when selected values need their own interactive UI. The callback\nis called separately for each selected option, so every chip can receive different\nactions based on its own data. The returned node can contain the chip and an\n`ActionBox` or any other supporting component.\n\n`chipProps` contains the props provided by MUI Autocomplete, including the default\ndelete handler. Pass these props to the custom `Chip` to preserve chip removal.\n\n`renderValue` takes precedence over `renderTags`, which takes precedence over\n`renderChip`. Therefore, `renderChip` is used only with `multiple={true}` when\nneither of the other callbacks is provided. The component warns in development\nwhen `renderChip` is ignored for one of these reasons.\n\nCustom rendering returns exactly the node from the callback: the default label\ntooltip is not added automatically. Add it explicitly when needed:\n\n```tsx\nrenderChip={({ label, chipProps }) => (\n <Tooltip title={label}>\n <Chip {...chipProps} />\n </Tooltip>\n)}\n```\n\n`chipProps` is already merged as `{ ...muiChipProps, ...slotProps.chip, label }`.\nThe computed `label` is applied last and stays consistent with the `label`\nprovided in the callback context. `slotProps.chip` may still override properties\nsuch as `onDelete` or `disabled`.\n\n```tsx\n// WithChipActionsExample.tsx\nimport React from 'react';\nimport { Box, Chip } from '@mui/material';\nimport { Delete, OpenInNew, Star, StarBorder } from '@mui/icons-material';\nimport { ActionBox, Autocomplete, ActionBoxItem } from '@ringpublishing/mui-components';\n\ninterface Option {\n id: number;\n label: string;\n}\n\nconst options: Option[] = [\n { id: 1, label: 'Onet' },\n { id: 2, label: 'Fakt' },\n { id: 3, label: 'Newsweek' },\n];\n\ninterface OptionChipProps {\n option: Option;\n label: string;\n chipProps: React.ComponentProps<typeof Chip>;\n isMain: boolean;\n onSetMain: () => void;\n}\n\nfunction OptionChip({ option, label, chipProps, isMain, onSetMain }: OptionChipProps): React.JSX.Element {\n const anchorRef = React.useRef<HTMLDivElement>(null);\n const actions: ActionBoxItem[] = [\n {\n label: 'Open portal',\n onClick: (): void => console.info('Details', option),\n icon: <OpenInNew />,\n },\n {\n label: isMain ? 'Unset as main' : 'Set as main',\n onClick: onSetMain,\n icon: isMain ? <StarBorder /> : <Star />,\n hasSeparatorAfter: true,\n },\n {\n label: 'Remove from selection',\n onClick: (event?: React.MouseEvent<Element, MouseEvent>): void =>\n chipProps.onDelete?.(event as React.SyntheticEvent),\n icon: <Delete />,\n },\n ];\n\n return (\n <>\n <Box\n ref={anchorRef}\n onClick={(): void => undefined}\n sx={{\n cursor: 'pointer',\n display: 'inline-flex',\n }}\n >\n <Chip\n {...chipProps}\n label={label}\n color={isMain ? 'primary' : 'default'}\n onClick={(): void => undefined}\n />\n </Box>\n <ActionBox actions={actions} anchorEl={anchorRef} placement=\"bottom-start\" />\n </>\n );\n}\n\nexport default function WithChipActionsExample(): React.JSX.Element {\n const [selectedOptions, setSelectedOptions] = React.useState(options);\n const [mainOptionId, setMainOptionId] = React.useState(options[0].id);\n\n const handleChange = (nextOptions: Option[]): void => {\n setSelectedOptions(nextOptions);\n\n if (!nextOptions.some((option) => option.id === mainOptionId)) {\n setMainOptionId(nextOptions[0]?.id ?? 0);\n }\n };\n\n return (\n <Autocomplete<Option>\n options={options}\n value={selectedOptions}\n onChange={(event, nextValue): void => handleChange(nextValue as Option[])}\n multiple={true}\n labels={{ title: 'Select portals' }}\n renderChip={({ option, label, chipProps }): React.JSX.Element => (\n <OptionChip\n option={option}\n label={label}\n chipProps={chipProps}\n isMain={option.id === mainOptionId}\n onSetMain={(): void =>\n setMainOptionId(\n option.id === mainOptionId\n ? (selectedOptions.find((selectedOption) => selectedOption.id !== option.id)?.id ?? 0)\n : option.id,\n )\n }\n />\n )}\n sx={{ width: 420 }}\n />\n );\n}\n```\n\n## With Chip Details\n\n`renderChip` is not limited to `ActionBox`. A custom renderer can attach a Popper,\ndialog, tooltip, or any other UI containing additional information about the\nselected option.\n\n```tsx\n// WithChipDetailsExample.tsx\nimport { Article, CalendarMonth, OpenInNew, People, Verified } from '@mui/icons-material';\nimport { Box, Button, Chip, ClickAwayListener, Divider, Paper, Popper, Stack, Typography } from '@mui/material';\nimport { Autocomplete } from '@ringpublishing/mui-components';\nimport React from 'react';\n\ninterface Option {\n id: number;\n label: string;\n description: string;\n category: string;\n monthlyReaders: string;\n lastPublished: string;\n status: 'Active' | 'Review pending';\n}\n\nconst options: Option[] = [\n {\n id: 1,\n label: 'Onet',\n description: 'News and information portal covering current events, technology and lifestyle.',\n category: 'General news',\n monthlyReaders: '18.4M',\n lastPublished: 'Today, 09:42',\n status: 'Active',\n },\n {\n id: 2,\n label: 'Fakt',\n description: 'Daily news and opinion portal with a focus on fast, accessible reporting.',\n category: 'Daily news',\n monthlyReaders: '9.8M',\n lastPublished: 'Today, 08:15',\n status: 'Review pending',\n },\n {\n id: 3,\n label: 'Newsweek',\n description: 'Weekly magazine and website with long-form journalism and analysis.',\n category: 'Magazine',\n monthlyReaders: '4.2M',\n lastPublished: 'Yesterday, 17:30',\n status: 'Active',\n },\n];\n\ninterface OptionChipProps {\n option: Option;\n label: string;\n chipProps: React.ComponentProps<typeof Chip>;\n}\n\nfunction OptionChip({ option, label, chipProps }: OptionChipProps): React.JSX.Element {\n const [open, setOpen] = React.useState(false);\n const anchorRef = React.useRef<HTMLDivElement>(null);\n\n return (\n <>\n <Box ref={anchorRef} sx={{ cursor: 'pointer', display: 'inline-flex' }}>\n <Chip {...chipProps} label={label} onClick={(): void => setOpen((currentOpen) => !currentOpen)} />\n </Box>\n <Popper open={open} anchorEl={anchorRef.current} placement=\"bottom-start\">\n <ClickAwayListener onClickAway={(): void => setOpen(false)}>\n <Paper elevation={4} sx={{ p: 2, width: 360 }}>\n <Stack spacing={2}>\n <Box>\n <Stack direction=\"row\" justifyContent=\"space-between\" alignItems=\"flex-start\">\n <Box>\n <Typography variant=\"h6\">{option.label}</Typography>\n <Typography color=\"text.secondary\" variant=\"body2\">\n {option.category}\n </Typography>\n </Box>\n <Stack direction=\"row\" spacing={1} alignItems=\"center\">\n <Verified\n color={option.status === 'Active' ? 'success' : 'warning'}\n fontSize=\"small\"\n />\n <Typography variant=\"caption\">{option.status}</Typography>\n </Stack>\n </Stack>\n <Typography sx={{ mt: 1 }} variant=\"body2\">\n {option.description}\n </Typography>\n </Box>\n\n <Divider />\n\n <Box sx={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 2 }}>\n <Stack direction=\"row\" spacing={1} alignItems=\"center\">\n <People color=\"action\" fontSize=\"small\" />\n <Box>\n <Typography color=\"text.secondary\" variant=\"caption\">\n Monthly readers\n </Typography>\n <Typography variant=\"body2\">{option.monthlyReaders}</Typography>\n </Box>\n </Stack>\n <Stack direction=\"row\" spacing={1} alignItems=\"center\">\n <Article color=\"action\" fontSize=\"small\" />\n <Box>\n <Typography color=\"text.secondary\" variant=\"caption\">\n Content type\n </Typography>\n <Typography variant=\"body2\">{option.category}</Typography>\n </Box>\n </Stack>\n <Stack direction=\"row\" spacing={1} alignItems=\"center\">\n <CalendarMonth color=\"action\" fontSize=\"small\" />\n <Box>\n <Typography color=\"text.secondary\" variant=\"caption\">\n Last published\n </Typography>\n <Typography variant=\"body2\">{option.lastPublished}</Typography>\n </Box>\n </Stack>\n </Box>\n\n <Stack direction=\"row\" spacing={1} justifyContent=\"flex-end\">\n <Button size=\"small\" onClick={(): void => setOpen(false)}>\n Close\n </Button>\n <Button\n endIcon={<OpenInNew />}\n size=\"small\"\n variant=\"contained\"\n onClick={(): void => {\n window.open('https://www.example.com', '_blank', 'noopener,noreferrer');\n }}\n >\n Open portal\n </Button>\n </Stack>\n </Stack>\n </Paper>\n </ClickAwayListener>\n </Popper>\n </>\n );\n}\n\nexport default function WithChipDetailsExample(): React.JSX.Element {\n return (\n <Autocomplete<Option>\n options={options}\n defaultValue={[options[0], options[1]]}\n multiple={true}\n labels={{ title: 'Select portals' }}\n renderChip={({ option, label, chipProps }): React.ReactElement => (\n <OptionChip option={option} label={label} chipProps={chipProps} />\n )}\n sx={{ width: 420 }}\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```"
973
980
  },
974
981
  "molecules-chips-group": {
975
982
  "id": "molecules-chips-group",
@@ -1212,7 +1219,7 @@
1212
1219
  "WithNoActions",
1213
1220
  "WithImage"
1214
1221
  ],
1215
- "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 dayjs from 'dayjs';\nimport React from 'react';\n\nconst endDate = dayjs().add(1, 'year').toISOString();\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={endDate}\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={endDate}\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';\nimport dayjs from 'dayjs';\n\nconst endDate = dayjs().add(1, 'year').toISOString();\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={endDate}\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';\nimport dayjs from 'dayjs';\n\nconst endDate = dayjs().add(1, 'year').toISOString();\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={endDate}\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 dayjs from 'dayjs';\nimport React from 'react';\n\nconst IMAGE_URL = 'https://design.ringpublishing.com/images/sea_large.jpg';\n\nconst endDate = dayjs().add(1, 'year').toISOString();\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={endDate}\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={endDate}\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```"
1222
+ "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 dayjs from 'dayjs';\nimport React from 'react';\n\nconst endDate = dayjs().add(1, 'year').toISOString();\n\nconst actions: FeatureTooltipProps['actions'] = [\n { label: 'Default action', href: 'https://ringpublishing.com/' },\n { label: 'Secondary action', onClick: (): void => undefined },\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={endDate}\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={endDate}\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';\nimport dayjs from 'dayjs';\n\nconst endDate = dayjs().add(1, 'year').toISOString();\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={endDate}\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';\nimport dayjs from 'dayjs';\n\nconst endDate = dayjs().add(1, 'year').toISOString();\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={endDate}\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 dayjs from 'dayjs';\nimport React from 'react';\n\nconst IMAGE_URL = 'https://design.ringpublishing.com/images/sea_large.jpg';\n\nconst endDate = dayjs().add(1, 'year').toISOString();\n\nconst actions: FeatureTooltipProps['actions'] = [\n { label: 'Default action', href: 'https://ringpublishing.com/' },\n { label: 'Secondary action', onClick: (): void => undefined },\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={endDate}\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={endDate}\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```"
1216
1223
  },
1217
1224
  "molecules-media": {
1218
1225
  "id": "molecules-media",
@@ -3224,7 +3231,7 @@
3224
3231
  "Default",
3225
3232
  "WithDragHandle"
3226
3233
  ],
3227
- "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```"
3234
+ "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 iconBtnRef = 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 ref={iconBtnRef.setRef}>\n <MoreVert />\n </IconButton>\n <ActionBox\n actions={[\n {\n label: 'Option 1',\n onClick: (): void => undefined,\n },\n ]}\n anchorEl={iconBtnRef}\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```"
3228
3235
  },
3229
3236
  "organisms-text-editor": {
3230
3237
  "id": "organisms-text-editor",
package/package.json CHANGED
@@ -29,5 +29,5 @@
29
29
  "engines": {
30
30
  "node": "^18||^20||^22||^24"
31
31
  },
32
- "version": "1.16.5"
32
+ "version": "1.17.0"
33
33
  }