fluentui-svelte 0.1.0

package/dist/components/auto-suggest-box/docs/llms.md

@@ -0,0 +1,73 @@
+# AutoSuggestBox
+
+The AutoSuggestBox component provides an input field with dynamic suggestions as users type. It enhances user experience by offering relevant suggestions, improving efficiency in form inputs and searches.
+
+## Usage
+
+```svelte
+<script>
+	import { AutoSuggestBox, AutoSuggestBoxOption } from 'fluentui-svelte';
+</script>
+
+<AutoSuggestBox placeholder="Type a fruit...">
+	<AutoSuggestBoxOption index={0} value="Apple">Apple</AutoSuggestBoxOption>
+	<AutoSuggestBoxOption index={1} value="Banana">Banana</AutoSuggestBoxOption>
+	<AutoSuggestBoxOption index={2} value="Cherry">Cherry</AutoSuggestBoxOption>
+</AutoSuggestBox>
+```
+
+## Examples
+
+### Virtualized Suggestions
+
+Long lists can be windowed. Pass a `virtualizer` describing the _whole_ list — `size` is the
+total number of suggestions, not the number rendered — and the box drives your list component
+when the cursor walks past what is on screen. Options keep their real `index`, which is what
+ties a rendered row back to the data.
+
+```svelte
+<script>
+	import SvelteVirtualList from '@humanspeak/svelte-virtual-list';
+
+	let items = $state(fruits);
+	let listRef;
+</script>
+
+<AutoSuggestBox
+	placeholder="Type a fruit..."
+	virtualizer={{
+		size: items.length,
+		scrollToTop: () => listRef.scroll({ index: 0, align: 'top', smoothScroll: false }),
+		scrollToBottom: () => listRef.scroll({ index: items.length - 1, align: 'bottom', smoothScroll: false }),
+		scrollToIndex: (index) => listRef.scroll({ index, align: 'auto', smoothScroll: false })
+	}}
+	textChanged={(e, val) => (items = fruits.filter((item) => item.name.toLowerCase().includes(val.toLowerCase())))}
+>
+	<SvelteVirtualList {items} bind:this={listRef} defaultEstimatedItemHeight={30}>
+		{#snippet renderItem(item, index)}
+			<AutoSuggestBoxOption {index} id={item.id} value={item.name} text={item.name}>
+				{item.name}
+			</AutoSuggestBoxOption>
+		{/snippet}
+	</SvelteVirtualList>
+</AutoSuggestBox>
+```
+
+Filtering is yours to do in `textChanged`: a windowed list renders from your data, so the
+built-in filter that a plain option list applies is skipped.
+
+## Component Props
+
+| Name               | Type                                                      | Description                                                            |
+| ------------------ | --------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `placeholder`      | `string`                                                  | Placeholder text shown in the input.                                   |
+| `value`            | `string`                                                  | The current value of the input field.                                  |
+| `open`             | `boolean`                                                 | Whether the suggestion flyout is open. Default: `false`.               |
+| `multiselect`      | `boolean`                                                 | Allow selecting multiple suggestions.                                  |
+| `selectOnFocus`    | `boolean`                                                 | Select a suggestion as it is focused during keyboard navigation.       |
+| `notFoundText`     | `string`                                                  | Text shown when no suggestions match. Default: `No results found`.     |
+| `maxItemsInView`   | `number`                                                  | Number of suggestions visible before the flyout scrolls. Default: `6`. |
+| `ref`              | `HTMLElement`                                             | The DOM reference of the auto-suggest box element.                     |
+| `suggestionChosen` | `(e: Event, selection: string) => void`                   | Event triggered when a suggestion is chosen.                           |
+| `querySubmitted`   | `(e: MouseEvent \| KeyboardEvent, query: string) => void` | Event triggered when a query is submitted.                             |
+| `virtualizer`      | `{ size, scrollToIndex?, scrollToTop?, scrollToBottom? }` | Bridge to a windowed list. `size` is the total suggestion count.       |

package/dist/components/auto-suggest-box/option.svelte

@@ -0,0 +1,82 @@
+<script lang="ts">
+	import { PREFIX } from '../../internal/constants.js';
+	import ListViewItem from '../list-view/list-view-item.svelte';
+	import { getAutoSuggestBoxContext } from './auto-suggest-box.js';
+	import type { AutoSuggestOptionProps } from './types.js';
+
+	const FALLBACK_ID = $props.id();
+	const ID = `${PREFIX}-${FALLBACK_ID}`;
+
+	let {
+		disabled,
+		ref = $bindable(),
+		id = ID,
+		value = id!,
+		text,
+		index,
+		children,
+		...attributes
+	}: AutoSuggestOptionProps = $props();
+
+	const context = getAutoSuggestBoxContext();
+
+	if (!context) throw new Error('AutoSuggestOption must be used within an AutoSuggestBox');
+
+	const { config, state: _state, methods } = context;
+	const { selectOnFocus, virtualized } = config;
+	const { setOption, deleteOption, toggleSelection } = methods;
+
+	let isVisible = $derived(
+		value.toLowerCase().includes((_state.lastTypedValue || '').toLowerCase()) ||
+			text?.toLowerCase().includes((_state.lastTypedValue || '').toLowerCase())
+	);
+
+	function handleClick(e: MouseEvent) {
+		if (disabled) return;
+
+		toggleSelection?.(e, id);
+
+		if (!config.multiselect) _state.open = false;
+	}
+
+	// An option counts only while it is on screen: that is what makes the empty
+	// list detectable when a query filters everything out, and it keeps keyboard
+	// navigation off options nobody can see. The effect also covers the virtualizer
+	// remounting the same component instance with new data.
+	$effect(() => {
+		if (!isVisible && !virtualized) return;
+
+		// Capture current values to avoid them being stale in the callback
+		const _id = id;
+
+		setOption?.({ id, index, value, text, disabled });
+
+		return () => deleteOption?.(_id);
+	});
+</script>
+
+{#if isVisible || virtualized}
+	<ListViewItem
+		{id}
+		role="option"
+		{value}
+		tabindex={-1}
+		data-index={index}
+		class={['fs-autosuggest-option', selectOnFocus && 'no-outline']}
+		onclick={handleClick}
+		bind:ref
+		{disabled}
+		{...attributes}
+	>
+		{@render children?.()}
+	</ListViewItem>
+{/if}
+
+<style>
+	/* Tabspot marks the option under the cursor with `data-active`, which
+	   ListViewItem already outlines. With selectOnFocus the text box mirrors that
+	   option instead, so the outline would be noise. */
+	:global(.fs-autosuggest-option.no-outline) {
+		outline: 0 !important;
+	}
+</style>

package/dist/components/auto-suggest-box/option.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { AutoSuggestOptionProps } from './types.ts';
+declare const Option: import("svelte").Component<AutoSuggestOptionProps, {}, "ref">;
+type Option = ReturnType<typeof Option>;
+export default Option;

package/dist/components/auto-suggest-box/types.d.ts

@@ -0,0 +1,140 @@
+import type { FSContext } from '../../internal/index.js';
+import type { TextBoxProps } from '../text-box/types.ts';
+import type { ListViewItemProps } from '../list-view/types.ts';
+import type { FlyoutProps } from '../flyout/types.ts';
+import type { HTMLAttributes } from 'svelte/elements';
+/** @propsmith AutoSuggestBoxProps */
+export type AutoSuggestBoxProps = {
+    /** The DOM reference of the wrapper element.
+     * @bindable
+     */
+    ref?: HTMLElement;
+    /** The DOM reference of the text box element.
+     * @bindable
+     */
+    inputRef?: HTMLInputElement;
+    /** The current text of the box.
+     * @default ''
+     * @bindable
+     */
+    value?: string;
+    /** Controls the open state of the suggestion list.
+     * @default false
+     * @bindable
+     */
+    open?: boolean;
+    /** Lets more than one suggestion be chosen, and keeps the list open after each one. */
+    multiselect?: boolean;
+    /** Mirrors the suggestion under the cursor into the text box as it is walked over.
+     * Not supported together with `multiselect`.
+     */
+    selectOnFocus?: boolean;
+    /** Lists every chosen suggestion in the text box, comma separated. Multiselect only. */
+    showTextualMultiselect?: boolean;
+    /** The message shown in place of the list when nothing matches.
+     * @default 'No results found'
+     */
+    notFoundText?: string;
+    /** The suggestions currently chosen.
+     * @default []
+     * @bindable
+     */
+    selectedOptions?: {
+        id: string;
+        value: string;
+    }[];
+    /** Called when a suggestion is chosen: by clicking it, by pressing Enter on it, or by
+     * walking onto it while `selectOnFocus` is set.
+     */
+    suggestionChosen?: (e: Event, selection: string) => void;
+    /** Called when Enter is pressed with no suggestion under the cursor, or when the search
+     * button is clicked. This is where a fresh set of suggestions is fetched.
+     */
+    querySubmitted?: (e: MouseEvent | KeyboardEvent, query: string) => void;
+    /** Bridge to a windowed list, for suggestion sets too long to render whole.
+     * @type AutoSuggestVirtualizer
+     */
+    virtualizer?: AutoSuggestVirtualizer;
+    /** How many suggestions are visible before the list scrolls.
+     * @default 6
+     */
+    maxItemsInView?: number;
+    /** The DOM reference of the underlying text box input.
+     * @bindable
+     */
+    textBoxRef?: HTMLInputElement;
+    /** The props to spread on the text box.
+     * @type TextBoxProps
+     */
+    textBoxProps?: Omit<TextBoxProps, 'type' | 'ref' | 'placeholder' | 'hideActionButtons' | 'textChanged'>;
+    /** The DOM reference of the flyout holding the suggestion list.
+     * @bindable
+     */
+    flyoutRef?: HTMLElement;
+    /** The props to spread on the flyout.
+     * @type FlyoutProps
+     */
+    flyoutProps?: Omit<FlyoutProps, 'children' | 'ref'>;
+    /** The DOM reference of the suggestion list.
+     * @bindable
+     */
+    listViewRef?: HTMLUListElement;
+    /** The props to spread on the suggestion list.
+     * @type ListViewItemProps
+     */
+    listViewProps?: Omit<ListViewItemProps, 'as' | 'role' | 'ref' | 'navigationMode' | 'selectedItems'>;
+} & Pick<TextBoxProps, 'type' | 'placeholder' | 'hideActionButtons' | 'textChanged'> & HTMLAttributes<HTMLDivElement>;
+/**
+ * Bridge to a windowed list. `size` is the total number of suggestions, not the
+ * number currently rendered — it is how the box knows where the list really ends
+ * and which index to scroll to when the cursor walks past the rendered window.
+ */
+export type AutoSuggestVirtualizer = {
+    size: number;
+    scrollToIndex?: (index: number) => void | Promise<void>;
+    scrollToTop?: () => void | Promise<void>;
+    scrollToBottom?: () => void | Promise<void>;
+};
+export type AutoSuggestBoxContext = FSContext<{
+    readonly selectOnFocus?: boolean;
+    readonly virtualized?: AutoSuggestVirtualizer;
+    multiselect?: boolean;
+}, {
+    readonly searchValue?: string;
+    readonly textBoxRef?: HTMLInputElement;
+    readonly lastTypedValue?: string;
+    open?: boolean;
+    activeOption?: OptionType | null;
+}, null, {
+    setOption: (item: OptionType) => void;
+    deleteOption: (id: string) => void;
+    toggleSelection: (e: Event, id: string) => void;
+}>;
+export type OptionType = {
+    id: string;
+    index: number;
+    value: string;
+    text?: string;
+    disabled?: boolean;
+};
+/** @propsmith AutoSuggestOptionProps */
+export type AutoSuggestOptionProps = {
+    /** The value reported to the box when the suggestion is chosen. Falls back to the id. */
+    value?: string;
+    /** The text shown in the box once the suggestion is chosen. Falls back to `value`. */
+    text?: string;
+    /** The id of the option element, referenced by the box through `aria-activedescendant`.
+     * Falls back to a generated id.
+     */
+    id?: string;
+    /** The DOM reference of the option element.
+     * @bindable
+     */
+    ref?: HTMLLIElement;
+    /** Takes the suggestion out of reach: it is shown, but the cursor steps over it. */
+    disabled?: boolean;
+    /** Where the suggestion sits in the whole set. A windowed list needs the real index,
+     * not the position within the rendered slice.
+     */
+    index: number;
+} & Omit<ListViewItemProps<'li'>, 'as' | 'value'>;

package/dist/components/auto-suggest-box/types.js

@@ -0,0 +1 @@
+export {};

package/dist/components/avatar/avatar.svelte

@@ -0,0 +1,269 @@
+<script lang="ts">
+	import { BadgeIcon } from '../../index.js';
+	import { pickColorByWord } from '../../css/utils.js';
+	import { getInitials, pxToRem, RenderSoC } from '../../internal/index.js';
+	import type { AvatarProps } from './type.js';
+
+	let {
+		size = 48,
+		name = 'Avatar',
+		image,
+		initials = name && getInitials(name),
+		shape = 'circular',
+		icon: Icon,
+		active,
+		color = 'attention',
+		style,
+		activeAppearance = 'ring',
+		ref = $bindable(),
+		idForColor,
+		badge,
+		...attributes
+	}: AvatarProps = $props();
+
+	const avatarStyle = $derived(
+		`--av-size: ${pxToRem(size)}; ${color === 'colorful' ? '--av-color: ' + pickColorByWord(idForColor ?? name) + ';' : ''}`
+	);
+
+	const badgeSize = $derived((size / 2).toFixed(0) + 'px');
+
+	let hideBg = $state(false);
+</script>
+
+<!-- 
+@component
+
+  This is a implementation of Fluen UI Avatar component. 
+
+  An Avatar is a graphical representation of a user, team, or entity.
+
+  Avatar can display an image, icon, or initials, and supports various sizes and shapes.
+
+- Usage:
+  ```tsx
+  <script>
+    import { Avatar } from 'fluentui-svelte';
+  </script>
+
+  <Avatar name="John Doe" size={48} />
+  ```
+-->
+<div
+	role="img"
+	aria-label={name}
+	bind:this={ref}
+	style="{avatarStyle} {style}"
+	class={[
+		'fs-avatar',
+		color,
+		activeAppearance,
+		active,
+		shape,
+		hideBg && 'hide-bg',
+		(badge?.status || badge?.icon) && 'mask'
+	]}
+	{...attributes}
+>
+	<span class="content">
+		{#if image}
+			<img
+				class="fs-avatar-image {shape}"
+				src={image.src}
+				width={size}
+				height={size}
+				alt={name}
+				onload={() => (hideBg = true)}
+			/>
+		{/if}
+		{#if Icon}
+			<RenderSoC SoC={Icon} args={[{ width: badgeSize, height: badgeSize }]} width={badgeSize} height={badgeSize} />
+		{:else}
+			{initials}
+		{/if}
+	</span>
+	{#if badge}
+		<BadgeIcon
+			size={Number((size / 3.25).toFixed(0))}
+			icon={badge?.icon || undefined}
+			status={badge?.status}
+			outOfOffice={badge?.outOfOffice}
+		/>
+	{/if}
+</div>
+
+<style>
+	.fs-avatar {
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		position: relative;
+		width: var(--av-size);
+		height: var(--av-size);
+		font-size: calc(var(--av-size) / 2.4);
+		line-height: 1.4em;
+		font-weight: 500;
+		z-index: 0;
+		& :global(.fs-avatar-image) {
+			position: absolute;
+			inset: 0;
+			z-index: 1;
+		}
+		& > :global(.fs-badge-icon),
+		& > :global(.fs-badge),
+		& > :global(svg) {
+			position: absolute;
+			bottom: 0;
+			right: 0;
+			z-index: 1;
+		}
+		& .content {
+			display: flex;
+			align-items: center;
+			justify-content: center;
+			font-size: inherit;
+			width: 100%;
+			height: 100%;
+			z-index: 1;
+			color: var(--fs-text-on-accent-primary);
+		}
+		&::before {
+			content: '';
+			position: absolute;
+			top: 0;
+			left: 0;
+			width: 100%;
+			height: 100%;
+			border-radius: inherit;
+		}
+		&.ring::after,
+		&.ring-shadow::after {
+			font-size: calc(var(--av-size) / 4);
+			content: '';
+			position: absolute;
+			top: 50%;
+			left: 50%;
+			width: calc(100% + 1em);
+			height: calc(100% + 1em);
+			transform: translate(-50%, -50%);
+			border: max(1px, 0.3em) solid transparent;
+			opacity: 0;
+			transition: opacity 0.1s;
+			z-index: 0;
+		}
+		&.circular,
+		& :global(.circular),
+		&.circular::after {
+			border-radius: 9999rem;
+		}
+		&.rounded {
+			border-radius: var(--fs-control-border-radius);
+		}
+		&.rounded::after {
+			border-radius: calc(var(--fs-control-border-radius) + 0.325rem);
+		}
+		&.shadow,
+		&.ring-shadow {
+			filter: drop-shadow(var(--fs-shadow-flyout));
+		}
+		&.information {
+			color: var(--fs-system-neutral-text);
+			&::before {
+				background: var(--fs-system-neutral);
+			}
+			&:after {
+				border-color: var(--fs-system-neutral);
+			}
+		}
+		&.attention {
+			color: var(--fs-system-attention-text);
+			&::before {
+				background: var(--fs-system-attention);
+			}
+			&:after {
+				border-color: var(--fs-system-attention);
+			}
+		}
+		&.warning {
+			color: var(--fs-system-caution-text);
+			&::before {
+				background: var(--fs-system-caution);
+			}
+			&:after {
+				border-color: var(--fs-system-caution);
+			}
+		}
+		&.success {
+			color: var(--fs-system-success-text);
+			&::before {
+				background: var(--fs-system-success);
+			}
+			&:after {
+				border-color: var(--fs-system-success);
+			}
+		}
+		&.critical {
+			color: var(--fs-system-critical-text);
+			&::before {
+				background: var(--fs-system-critical);
+			}
+			&:after {
+				border-color: var(--fs-system-critical);
+			}
+		}
+		&.colorful {
+			& .content {
+				color: color-mix(in srgb, var(--av-color), contrast-color(var(--av-color)) 60%);
+			}
+			&::before {
+				background: var(--av-color);
+			}
+			&:after {
+				border-color: var(--av-color);
+			}
+		}
+		&.active {
+			&.ring::after,
+			&.ring-shadow::after {
+				opacity: 1;
+			}
+		}
+		&.inactive {
+			transform: scale(0.875);
+		}
+		&.mask {
+			/* Crop center */
+			--pos: calc(var(--av-size) / 6.1);
+			/* Transparent cutout radius */
+			--cut: calc(var(--av-size) * 0.228);
+			/* Border gradient width (fake anti-aliasing) */
+			--feather: max(1%, calc(var(--av-size) * 0.01));
+			& .content,
+			&::before,
+			& :global(.fs-avatar-image) {
+				--fs-mask: radial-gradient(
+					circle at right var(--pos) bottom var(--pos),
+					rgba(0, 0, 0, 0) var(--cut),
+					rgb(255, 255, 255) calc(var(--cut) + var(--feather))
+				);
+				-webkit-mask-image: var(--fs-mask);
+				mask-image: var(--fs-mask);
+			}
+			&::after {
+				--after-pos: calc(var(--pos) + (var(--av-size) / 4) / 2);
+				--after-cut: calc(var(--av-size) * 0.236);
+				--fs-mask: radial-gradient(
+					circle at right var(--after-pos) bottom var(--after-pos),
+					rgba(0, 0, 0, 0) var(--after-cut),
+					rgb(255, 255, 255) calc(var(--after-cut) + var(--feather))
+				);
+				-webkit-mask-image: var(--fs-mask);
+				mask-image: var(--fs-mask);
+			}
+		}
+		&.hide-bg {
+			&::before {
+				background: transparent;
+			}
+		}
+	}
+</style>

package/dist/components/avatar/avatar.svelte.d.ts

@@ -0,0 +1,20 @@
+import type { AvatarProps } from './type.ts';
+/**
+ * This is a implementation of Fluen UI Avatar component.
+ *
+ * An Avatar is a graphical representation of a user, team, or entity.
+ *
+ * Avatar can display an image, icon, or initials, and supports various sizes and shapes.
+ *
+ * - Usage:
+ * ```tsx
+ * <script>
+ *   import { Avatar } from 'fluentui-svelte';
+ * </script>
+ *
+ * <Avatar name="John Doe" size={48} />
+ * ```
+ */
+declare const Avatar: import("svelte").Component<AvatarProps, {}, "ref">;
+type Avatar = ReturnType<typeof Avatar>;
+export default Avatar;

package/dist/components/avatar/docs/llms.md

@@ -0,0 +1,92 @@
+# Avatar
+
+An Avatar is a graphical representation of a user, team, or entity.
+
+Avatar can display an image, icon, or initials, and supports different sizes, shapes, and status indicators.
+
+## Usage
+
+```svelte
+<script>
+	import { Avatar } from 'fluentui-svelte';
+</script>
+
+<Avatar size={40} name="FluentUI Svelte" />
+```
+
+## Component API
+
+A brief explanation of the props that really need explaining. You can see the rest of the props in the Component Props table below.
+
+## Examples
+
+### Image
+
+An avatar can display an image. It is recommended to also include a name in addition to the image: the initials from the name are displayed while the image is loading, and the name makes the Avatar accessible to screen readers.
+
+```svelte
+<Avatar
+	active="active"
+	size={56}
+	name="FluentUI Svelte"
+	image={{ src: 'https://placehold.co/120x120/jpeg' }}
+	badge={{ status: 'do-not-disturb' }}
+/>
+```
+
+### Icon
+
+An avatar can display an icon. The icon will only be shown when there is no image or initials available.
+
+```svelte
+<script>
+	import { ClockRegular } from 'fluentui-icons-svelte';
+</script>
+
+<Avatar active="active" size={56} name="FluentUI Svelte" icon={ClockRegular} color="information" />
+```
+
+### Badge
+
+An avatar can have a badge to indicate presence status. See the PresenceBadge component for more info.
+
+```svelte
+<Avatar active="active" size={56} name="FluentUI Svelte" badge={{ status: 'available' }} />
+```
+
+### Shape
+
+An avatar can have a square, circular, or rounded shape.
+
+```svelte
+<Avatar active="active" size={56} name="FluentUI Svelte" badge={{ status: 'available' }} />
+<Avatar active="active" size={56} name="FluentUI Svelte" badge={{ status: 'available' }} shape="rounded" />
+<Avatar active="active" size={56} name="FluentUI Svelte" badge={{ status: 'available' }} shape="square" />
+```
+
+### Color: colorful
+
+An avatar can have its color automatically picked based on the name prop, or idForColor can be used if a name is not available.
+
+```svelte
+<Avatar active="active" size={56} name="FluentUI Svelte" color="colorful" />
+<Avatar active="active" size={56} name="FluentUI Svelte" color="colorful" />
+<Avatar active="active" size={56} name="FluentUI Svelte" color="colorful" />
+```
+
+## Component Props
+
+| Name               | Type                     | Description                                                                                                                                                                              |
+| ------------------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`             | `string`                 | The name of the person or entity represented by this Avatar. Used to determine initials and for accessibility tools.                                                                     |
+| `image`            | `{ src: string }`        | The Avatar image. It can only be a single image URL.                                                                                                                                     |
+| `ref`              | `HTMLDivElement`         | The DOM reference of the avatar element.                                                                                                                                                 |
+| `size`             | `number`                 | Size of the avatar in pixels.                                                                                                                                                            |
+| `shape`            | `string`                 | The shape of the avatar. Possible values: 'circular', 'rounded', 'square'.                                                                                                               |
+| `color`            | `string`                 | The color used when displaying either an icon or initials. Supports system colors. Possible values: 'information', 'attention', 'warning', 'success', 'critical', 'colorful'.            |
+| `active`           | `string`                 | Optional activity indicator. Possible values: 'active', 'inactive'. Active decorates the avatar according to activeAppearance. Inactive reduces size and makes it partially transparent. |
+| `activeAppearance` | `string`                 | The appearance used when active is set to active. Possible values: 'ring', 'shadow', 'ring-shadow'.                                                                                      |
+| `initials`         | `string`                 | Custom initials. By default, initials are derived from the name prop using the getInitials function. They are displayed when there is no image.                                          |
+| `idForColor`       | `string`                 | A string used instead of the name to determine the color when color is set to colorful. Useful when a name is unavailable but another unique identifier exists.                          |
+| `icon`             | `Snippet` \| `Component` | The icon to display when the avatar does not have an image or initials.                                                                                                                  |
+| `badge`            | `object`                 | The badge to display as a status indicator. It can include a custom icon.                                                                                                                |