Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(docsite): add example and usage guidance for BaseTypeahead (#2679) (#3284)

mohitWeb-lab20ae2bc6e9b4
diff --git a/packages/cli/templates/blocks/components/BaseTypeahead/BaseTypeaheadCustomSearch.doc.mjs b/packages/cli/templates/blocks/components/BaseTypeahead/BaseTypeaheadCustomSearch.doc.mjs
new file mode 100644
index 0000000000..0770fbf2bd
--- /dev/null
+++ b/packages/cli/templates/blocks/components/BaseTypeahead/BaseTypeaheadCustomSearch.doc.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'BaseTypeahead',
+ name: 'BaseTypeahead — Custom Search Bar',
+ displayName: 'BaseTypeahead — Custom Search Bar',
+ description:
+ 'BaseTypeahead embedded inside a custom-styled wrapper. The wrapper provides its own border and icon chrome; anchorRef positions the dropdown relative to it. Use this pattern when Typeahead\'s built-in field layout does not fit your composition.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['BaseTypeahead', 'Icon', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/BaseTypeahead/BaseTypeaheadCustomSearch.tsx b/packages/cli/templates/blocks/components/BaseTypeahead/BaseTypeaheadCustomSearch.tsx
new file mode 100644
index 0000000000..4412ea42ee
--- /dev/null
+++ b/packages/cli/templates/blocks/components/BaseTypeahead/BaseTypeaheadCustomSearch.tsx
@@ -0,0 +1,58 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useRef, useState} from 'react';
+import {BaseTypeahead, createStaticSource} from '@astryxdesign/core/Typeahead';
+import type {SearchableItem} from '@astryxdesign/core/Typeahead';
+import {Icon} from '@astryxdesign/core/Icon';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+import {MagnifyingGlassIcon} from '@heroicons/react/24/outline';
+
+const frameworks: SearchableItem[] = [
+ {id: 'react', label: 'React'},
+ {id: 'vue', label: 'Vue'},
+ {id: 'angular', label: 'Angular'},
+ {id: 'svelte', label: 'Svelte'},
+ {id: 'solid', label: 'SolidJS'},
+ {id: 'remix', label: 'Remix'},
+ {id: 'next', label: 'Next.js'},
+ {id: 'nuxt', label: 'Nuxt'},
+];
+
+const source = createStaticSource(frameworks);
+
+export default function BaseTypeaheadCustomSearch() {
+ const [value, setValue] = useState<SearchableItem | null>(null);
+ const wrapperRef = useRef<HTMLElement>(null);
+
+ return (
+ <VStack gap={3} style={{width: 320}}>
+ <HStack
+ ref={wrapperRef}
+ gap={2}
+ vAlign="center"
+ style={{
+ border: '1px solid var(--color-border)',
+ borderRadius: 'var(--radius-control)',
+ padding: '6px 10px',
+ background: 'var(--color-surface)',
+ }}>
+ <Icon icon={MagnifyingGlassIcon} size="sm" color="secondary" />
+ <BaseTypeahead
+ searchSource={source}
+ value={value}
+ onChange={setValue}
+ anchorRef={wrapperRef}
+ placeholder="Search frameworks…"
+ hasEntriesOnFocus
+ debounceMs={0}
+ />
+ </HStack>
+ <Text type="supporting" color="secondary">
+ {value != null ? `Selected: ${value.label}` : 'No selection'}
+ </Text>
+ </VStack>
+ );
+}
diff --git a/packages/core/src/Typeahead/BaseTypeahead.doc.mjs b/packages/core/src/Typeahead/BaseTypeahead.doc.mjs
index 2a93ae0a13..70c3c7d448 100644
--- a/packages/core/src/Typeahead/BaseTypeahead.doc.mjs
+++ b/packages/core/src/Typeahead/BaseTypeahead.doc.mjs
@@ -8,6 +8,16 @@ export const docs = {
displayName: 'Base Typeahead',
isHiddenFromOverview: true,
description: 'Unstyled combobox engine providing input, search, keyboard navigation, and dropdown. No wrapper div, no border styling, no token rendering. Used by Typeahead and Tokenizer for custom compositions.',
+ usage: {
+ description: 'Unstyled combobox engine providing input, search, keyboard navigation, and dropdown. No wrapper div, no border styling, no token rendering. Used by Typeahead and Tokenizer for custom compositions.',
+ bestPractices: [
+ { guidance: true, description: 'Use Typeahead or Tokenizer for standard fields — they wrap BaseTypeahead with the wrapper div, border styling, and token rendering it intentionally omits.' },
+ { guidance: true, description: 'Provide your own wrapper div with border and layout when composing directly — BaseTypeahead renders no visual chrome of its own.' },
+ { guidance: true, description: 'Pass anchorRef pointing to your wrapper so the dropdown positions against your custom input chrome, not just the bare input element.' },
+ { guidance: false, description: 'Expect a wrapper div, border, or token rendering — BaseTypeahead is an engine only; all visual chrome is the caller\'s responsibility.' },
+ { guidance: false, description: 'Use BaseTypeahead when Typeahead or Tokenizer would suffice — the extra wrapper and styling work is only justified for truly custom compositions.' },
+ ],
+ },
props: [
{
name: 'searchSource',