@ringpublishing/mui-components-mcp 1.17.0 → 1.19.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-09-04T08:20:25.504Z",
2
+ "generated": "2026-09-21T10:33:31.810Z",
3
3
  "importPath": "@ringpublishing/mui-components",
4
4
  "componentCount": 35,
5
5
  "components": {
@@ -907,6 +907,21 @@
907
907
  "category": "content",
908
908
  "type": "{ title: string; inputPlaceholder?: string; recentlyUsed?: string; recentlyUsedResults?: string; }"
909
909
  },
910
+ "variant": {
911
+ "description": "Input presentation. Filter mode uses a compact trigger and a popup search field.",
912
+ "control": "radio",
913
+ "category": "appearance",
914
+ "defaultValue": "default",
915
+ "options": [
916
+ "default",
917
+ "filter"
918
+ ]
919
+ },
920
+ "searchTextFieldProps": {
921
+ "description": "Props for the popup search field. Available only when variant is filter.",
922
+ "control": "object",
923
+ "category": "customization"
924
+ },
910
925
  "actions": {
911
926
  "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
927
  "control": false,
@@ -974,9 +989,12 @@
974
989
  "WithFreeSolo",
975
990
  "WithOutlinedTextField",
976
991
  "WithChipActions",
977
- "WithChipDetails"
992
+ "WithChipDetails",
993
+ "FilterDefault",
994
+ "FilterMultiple",
995
+ "FilterControlled"
978
996
  ],
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```"
997
+ "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```\n\n## Filter Variant\n\nUse `variant=\"filter\"` for a compact filter trigger. Selected values are summarized as a count, while an outlined search field is displayed at the top of the options panel. The filter variant supports loading, custom option rendering, and recently used items. It does not render selected values, tags, chips, or trigger actions.\n\nThe popup search field receives focus when opened. Arrow keys, Enter, Escape, Page Up, and Page Down are forwarded to the underlying autocomplete list. Home and End retain their native text-caret behavior.\n\n```tsx\n// FilterDefaultExample.tsx\nimport React from 'react';\nimport { Box } from '@mui/material';\nimport { Autocomplete } from '@ringpublishing/mui-components';\n\nconst options = [\n { id: 1, label: 'Onet' },\n { id: 2, label: 'Fakt' },\n { id: 3, label: 'Newsweek' },\n];\n\nexport default function FilterDefaultExample(): React.JSX.Element {\n return (\n <Box width={240}>\n <Autocomplete\n variant=\"filter\"\n labels={{ title: 'Publications', searchPlaceholder: 'Search publications' }}\n options={options}\n getOptionLabel={(option): string => (option as { label: string }).label}\n isOptionEqualToValue={(option, value): boolean => {\n return (option as { id: number }).id === (value as { id: number }).id;\n }}\n />\n </Box>\n );\n}\n```\n\n### Multiple Selection\n\nMultiple selection keeps the panel open and updates the count in the trigger.\n\n```tsx\n// FilterMultipleExample.tsx\nimport React from 'react';\nimport { Box } from '@mui/material';\nimport { Autocomplete } from '@ringpublishing/mui-components';\n\nconst options = [\n { id: 1, label: 'Onet' },\n { id: 2, label: 'Fakt' },\n { id: 3, label: 'Newsweek' },\n];\n\nexport default function FilterMultipleExample(): React.JSX.Element {\n return (\n <Box width={300}>\n <Autocomplete\n variant=\"filter\"\n labels={{ title: 'Publications', searchPlaceholder: 'Search publications' }}\n multiple={true}\n defaultValue={options.slice(0, 2)}\n options={options}\n getOptionLabel={(option): string => (option as { label: string }).label}\n isOptionEqualToValue={(option, value): boolean => {\n return (option as { id: number }).id === (value as { id: number }).id;\n }}\n />\n </Box>\n );\n}\n```\n\n### Controlled\n\nControl `open` and `inputValue` to show the panel with a prefilled search query. Update `inputValue` in `onInputChange` to keep the popup search field interactive.\n\n```tsx\n// FilterControlledExample.tsx\nimport React, { useState } from 'react';\nimport { Box } from '@mui/material';\nimport { Autocomplete } from '@ringpublishing/mui-components';\n\nconst options = [\n { id: 1, label: 'Onet' },\n { id: 2, label: 'Fakt' },\n { id: 3, label: 'Newsweek' },\n];\n\nexport default function FilterControlledExample(): React.JSX.Element {\n const [inputValue, setInputValue] = useState('Fakt');\n const [open, setOpen] = useState(true);\n\n return (\n <Box width={240}>\n <Autocomplete\n variant=\"filter\"\n labels={{ title: 'Publications', searchPlaceholder: 'Search publications' }}\n inputValue={inputValue}\n open={open}\n options={options}\n getOptionLabel={(option): string => (option as { label: string }).label}\n isOptionEqualToValue={(option, value): boolean => {\n return (option as { id: number }).id === (value as { id: number }).id;\n }}\n onInputChange={(event, nextInputValue): void => {\n void event;\n setInputValue(nextInputValue);\n }}\n onClose={(event): void => {\n void event;\n setOpen(false);\n }}\n onOpen={(event): void => {\n void event;\n setOpen(true);\n }}\n />\n </Box>\n );\n}\n```"
980
998
  },
981
999
  "molecules-chips-group": {
982
1000
  "id": "molecules-chips-group",
@@ -3591,10 +3609,11 @@
3591
3609
  "WithDynamicWidthFilter",
3592
3610
  "WithoutDetailAndFilter",
3593
3611
  "WithMultimediaGrid",
3612
+ "WithAutocompleteFilters",
3594
3613
  "WithSelectionMode",
3595
3614
  "WithBottomBarSelection"
3596
3615
  ],
3597
- "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```"
3616
+ "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 Autocomplete Filters\n\nAn alternate `DataView` presentation that replaces the default search bar with a custom top slot. The top slot groups\nthe page heading, search input, and filter-variant `Autocomplete` controls in one area, with active filter chips below.\nThe search input filters grid titles; each chip can be removed individually, while **Delete all** clears every active\nfilter.\n\nUse a custom `top` slot when the standard `DataView` search bar needs to be combined with page-specific controls:\n\n```tsx\nfunction TopSlot(props: TopSlotProps): React.JSX.Element {\n return (\n <Box>\n <Typography variant=\"headline1\">Content library</Typography>\n <Box>\n <SearchBox {...(props as ControlledSearchBoxProps)} />\n <Autocomplete variant=\"filter\" labels={contentTypeLabels} multiple={true} options={contentTypes} />\n <Autocomplete variant=\"filter\" labels={authorLabels} multiple={true} options={authors} />\n </Box>\n <ChipsGroup chips={activeFilterChips} onDeleteAll={handleClearAll} />\n </Box>\n );\n}\n\n<DataView\n slots={{\n top: TopSlot,\n main: <RingDataGrid rows={filteredRows} columns={columns} totalRowCount={filteredRows.length} />,\n }}\n slotProps={{ top: { value: searchQuery, onChange: setSearchQuery } }}\n/>;\n```\n\n```tsx\n// WithAutocompleteFiltersExample.tsx\nimport React, { useState } from 'react';\nimport { Box, Typography } from '@mui/material';\nimport {\n Autocomplete,\n ChipsGroup,\n type ControlledSearchBoxProps,\n DataView,\n RingDataGrid,\n SearchBox,\n type TopSlotProps,\n} from '@ringpublishing/mui-components';\n\ntype FilterOption = { id: number; label: string };\n\ninterface AutocompleteFiltersContextValue {\n selectedAuthors: FilterOption[];\n selectedContentTypes: FilterOption[];\n setSelectedAuthors: React.Dispatch<React.SetStateAction<FilterOption[]>>;\n setSelectedContentTypes: React.Dispatch<React.SetStateAction<FilterOption[]>>;\n}\n\nconst AutocompleteFiltersContext = React.createContext<AutocompleteFiltersContextValue | null>(null);\n\nconst contentTypes: FilterOption[] = [\n { id: 1, label: 'Article' },\n { id: 2, label: 'Gallery' },\n { id: 3, label: 'Video' },\n];\n\nconst authors: FilterOption[] = [\n { id: 1, label: 'Alex Morgan' },\n { id: 2, label: 'Jordan Lee' },\n { id: 3, label: 'Taylor Kim' },\n];\n\nconst columns = [\n { field: 'title', headerName: 'Title', flex: 1, minWidth: 240 },\n { field: 'contentType', headerName: 'Content type', width: 150 },\n { field: 'author', headerName: 'Author', width: 180 },\n { field: 'updated', headerName: 'Last updated', width: 180 },\n];\n\nconst rows = [\n {\n id: 1,\n title: 'Building a resilient editorial workflow',\n contentType: 'Article',\n author: 'Alex Morgan',\n updated: 'Sep 5, 2026',\n },\n {\n id: 2,\n title: 'Behind the scenes: the autumn collection',\n contentType: 'Gallery',\n author: 'Jordan Lee',\n updated: 'Sep 4, 2026',\n },\n {\n id: 3,\n title: 'How our newsroom plans live coverage',\n contentType: 'Video',\n author: 'Taylor Kim',\n updated: 'Sep 2, 2026',\n },\n {\n id: 4,\n title: 'Five stories readers saved this week',\n contentType: 'Article',\n author: 'Alex Morgan',\n updated: 'Sep 1, 2026',\n },\n];\n\nfunction getOptionLabel(option: FilterOption | string): string {\n return typeof option === 'string' ? option : option.label;\n}\n\nfunction isOptionEqualToValue(option: FilterOption | string, value: FilterOption | string): boolean {\n return typeof option !== 'string' && typeof value !== 'string' && option.id === value.id;\n}\n\nfunction isFilterOption(value: FilterOption | string): value is FilterOption {\n return typeof value !== 'string';\n}\n\nfunction AutocompleteFiltersTopSlot(topSlotProps: TopSlotProps): React.JSX.Element {\n const context = React.useContext(AutocompleteFiltersContext);\n\n if (!context) {\n throw new Error('AutocompleteFiltersTopSlot must be rendered within AutocompleteFiltersContext.');\n }\n\n const { selectedAuthors, selectedContentTypes, setSelectedAuthors, setSelectedContentTypes } = context;\n const selectedFilters = [\n ...selectedContentTypes.map((option) => ({ filter: 'Content type', option })),\n ...selectedAuthors.map((option) => ({ filter: 'Author', option })),\n ];\n\n function handleClearAll(): void {\n setSelectedContentTypes([]);\n setSelectedAuthors([]);\n }\n\n return (\n <Box\n sx={{\n backgroundColor: (theme) => theme.palette.background.paper,\n borderBottom: (theme) => `1px solid ${theme.palette.divider}`,\n display: 'flex',\n flexDirection: 'column',\n gap: 3,\n p: 2,\n }}\n >\n <Typography variant=\"headline1\">Content library</Typography>\n <Box sx={{ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: 2 }}>\n <SearchBox\n {...(topSlotProps as ControlledSearchBoxProps)}\n sx={{ flex: '0 1 360px', minWidth: 0, py: 0 }}\n />\n <Autocomplete\n variant=\"filter\"\n labels={{ title: 'Content type', searchPlaceholder: 'Search content types' }}\n multiple={true}\n options={contentTypes}\n value={selectedContentTypes}\n getOptionLabel={getOptionLabel}\n isOptionEqualToValue={isOptionEqualToValue}\n onChange={(event, value): void => {\n void event;\n setSelectedContentTypes(Array.isArray(value) ? value.filter(isFilterOption) : []);\n }}\n sx={{ minWidth: 150 }}\n />\n <Autocomplete\n variant=\"filter\"\n labels={{ title: 'Author', searchPlaceholder: 'Search authors' }}\n multiple={true}\n options={authors}\n value={selectedAuthors}\n getOptionLabel={getOptionLabel}\n isOptionEqualToValue={isOptionEqualToValue}\n onChange={(event, value): void => {\n void event;\n setSelectedAuthors(Array.isArray(value) ? value.filter(isFilterOption) : []);\n }}\n sx={{ minWidth: 150 }}\n />\n </Box>\n {selectedFilters.length > 0 && (\n <ChipsGroup\n chips={selectedFilters.map(({ filter, option }) => ({\n label: `${filter}: ${option.label}`,\n onDelete: (): void => {\n if (filter === 'Content type') {\n setSelectedContentTypes((values) => values.filter((value) => value.id !== option.id));\n } else {\n setSelectedAuthors((values) => values.filter((value) => value.id !== option.id));\n }\n },\n }))}\n onDeleteAll={handleClearAll}\n customLabels={{ deleteAll: 'Delete all' }}\n />\n )}\n </Box>\n );\n}\n\nexport default function WithAutocompleteFiltersExample(): React.JSX.Element {\n const [selectedContentTypes, setSelectedContentTypes] = useState<FilterOption[]>([]);\n const [selectedAuthors, setSelectedAuthors] = useState<FilterOption[]>([]);\n const [searchQuery, setSearchQuery] = useState('');\n\n const filteredRows = rows.filter((row) => {\n const matchesSearch = row.title.toLowerCase().includes(searchQuery.toLowerCase());\n const matchesContentType =\n selectedContentTypes.length === 0 ||\n selectedContentTypes.some((option) => option.label === row.contentType);\n const matchesAuthor =\n selectedAuthors.length === 0 || selectedAuthors.some((option) => option.label === row.author);\n\n return matchesSearch && matchesContentType && matchesAuthor;\n });\n\n return (\n <AutocompleteFiltersContext.Provider\n value={{ selectedAuthors, selectedContentTypes, setSelectedAuthors, setSelectedContentTypes }}\n >\n <DataView\n sx={{ height: 'calc(100vh - 38px)' }}\n slots={{\n top: AutocompleteFiltersTopSlot,\n main: <RingDataGrid rows={filteredRows} columns={columns} totalRowCount={filteredRows.length} />,\n }}\n slotProps={{\n top: {\n value: searchQuery,\n onChange: (value): void => setSearchQuery(value),\n labels: { placeholder: 'Search content' },\n },\n }}\n />\n </AutocompleteFiltersContext.Provider>\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```"
3598
3617
  }
3599
3618
  }
3600
3619
  }
package/package.json CHANGED
@@ -29,5 +29,5 @@
29
29
  "engines": {
30
30
  "node": "^18||^20||^22||^24"
31
31
  },
32
- "version": "1.17.0"
32
+ "version": "1.19.0"
33
33
  }