feat: Add custom option renderer for autosuggest (#4153)

Author: SpyZzey

pages/autosuggest/custom-render-option.page.tsx

@@ -0,0 +1,86 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import React, { useRef, useState } from 'react';
+
+import { Autosuggest, AutosuggestProps, Toggle } from '~components';
+
+import AppContext, { AppContextType } from '../app/app-context';
+import { SimplePage } from '../app/templates';
+
+const empty = <span>Nothing found</span>;
+const options = [
+  { value: 'Option 0', tags: ['tag1', 'tag2'], filteringTags: ['bla', 'opt', 'blauer'], description: 'description1' },
+  { value: 'Option 1', labelTag: 'This is a label tag' },
+  { value: 'Option 2' },
+  {
+    value: 'Option Group',
+    description: 'description2',
+    options: [
+      {
+        value: 'value1',
+        label: 'label1',
+      },
+      {
+        value: 'value1repeated',
+        label: 'label1repeated',
+      },
+    ],
+  },
+];
+type PageContext = React.Context<
+  AppContextType<{
+    virtualScroll?: boolean;
+  }>
+>;
+
+export default function AutosuggestPage() {
+  const [value, setValue] = useState('');
+  const ref = useRef<AutosuggestProps.Ref>(null);
+
+  const renderOption: AutosuggestProps.ItemRenderer = ({ item }) => {
+    if (item.type === 'entered-text') {
+      return <div>Entereted Text: {item.option.value}</div>;
+    } else if (item.type === 'group') {
+      return <div>Group: {item.option.value}</div>;
+    } else if (item.type === 'item') {
+      return <div>Item: {item.option.value}</div>;
+    }
+    return null;
+  };
+  const { urlParams, setUrlParams } = React.useContext(AppContext as PageContext);
+  const virtualScroll = urlParams.virtualScroll ?? false;
+
+  return (
+    <SimplePage
+      title="Autosuggest with custom item renderer"
+      settings={
+        <Toggle
+          checked={!!urlParams.virtualScroll}
+          onChange={({ detail }) => setUrlParams({ virtualScroll: detail.checked })}
+        >
+          Virtual Scroll
+        </Toggle>
+      }
+      screenshotArea={{
+        style: {
+          padding: 10,
+        },
+      }}
+    >
+      <div style={{ maxInlineSize: '400px', blockSize: '650px' }}>
+        <Autosuggest
+          virtualScroll={virtualScroll}
+          renderOption={renderOption}
+          ref={ref}
+          value={value}
+          options={options}
+          onChange={event => setValue(event.detail.value)}
+          placeholder={`Type... ${virtualScroll ? '(virtual)' : ''}`}
+          ariaLabel={'simple autosuggest'}
+          selectedAriaLabel="Selected"
+          empty={empty}
+        />
+      </div>
+    </SimplePage>
+  );
+}

src/__tests__/snapshot-tests/__snapshots__/documenter.test.ts.snap

@@ -3556,6 +3556,56 @@ For more information, see the
       "optional": true,
       "type": "AutosuggestProps.ContainingOptionAndGroupString",
     },
+    {
+      "description": "Specifies a render function to render custom options in the dropdown menu.
+
+The item inside the props has a different shape depending on its type:
+
+
+### item
+
+- \`type\` ('item') - The item type.
+- \`index\` (number) - The item's absolute position in the dropdown.
+- \`option\` (Option) - The original option configuration.
+- \`disabled\` (boolean) - Whether the item is disabled.
+- \`highlighted\` (boolean) - Whether the item is currently highlighted.
+- \`selected\` (boolean) - Whether the item is selected.
+- \`parent\` (OptionGroupRenderItem | null) - The parent group item, if any.
+
+### group
+
+- \`type\` ('group') - The item type.
+- \`index\` (number) - The item's absolute position in the dropdown.
+- \`option\` (OptionGroup) - The original option configuration.
+- \`disabled\` (boolean) - Whether the item is disabled.
+
+### entered-text
+
+- \`type\` ('entered-text') - The item type.
+- \`option\` (Option) - The entered-text option configuration.
+
+When providing a custom \`renderOption\` implementation, it fully replaces the default visual rendering and content for that item.
+The component still manages focus, keyboard interactions, and selection state, but it no longer applies its default item layout or typography.
+
+When returning \`null\`, the default rendering will be applied for that item.",
+      "inlineType": {
+        "name": "AutosuggestProps.ItemRenderer",
+        "parameters": [
+          {
+            "name": "props",
+            "type": "{ item: AutosuggestProps.RenderItem; filterText?: string | undefined; }",
+          },
+        ],
+        "returnType": "React.ReactNode",
+        "type": "function",
+      },
+      "name": "renderOption",
+      "optional": true,
+      "systemTags": [
+        "core",
+      ],
+      "type": "AutosuggestProps.ItemRenderer",
+    },
     {
       "description": "Specifies the localized string that describes an option as being selected.
 This is required to provide a good screen reader experience. For more information, see the