From 29679dc6ddc835b022459b18c077cc24ff06535f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rodrigo=20Jos=C3=A9=20Borba=20Fernandes?= Date: Mon, 6 Jan 2025 12:32:17 -0300 Subject: [PATCH] chore: better document Orama Search Box --- packages/ui-stencil/README.md | 24 ++-- packages/ui-stencil/src/components.d.ts | 132 ++++++++++++++++++ .../orama-search-box/orama-search-box.tsx | 73 +++++++++- .../src/components/orama-search-box/readme.md | 50 +++---- 4 files changed, 241 insertions(+), 38 deletions(-) diff --git a/packages/ui-stencil/README.md b/packages/ui-stencil/README.md index 63747e1..83e2770 100644 --- a/packages/ui-stencil/README.md +++ b/packages/ui-stencil/README.md @@ -32,17 +32,17 @@ Or import it directly in a browser module: ``` + +## Components API Documentation + +[Orama Search Box](src/components/orama-search-box/README.md) +[Orama Chat Box](src/components/orama-chat-box/README.md) +[Orama Search Button](src/components/orama-search-button/README.md) diff --git a/packages/ui-stencil/src/components.d.ts b/packages/ui-stencil/src/components.d.ts index 167da69..2e3f82f 100644 --- a/packages/ui-stencil/src/components.d.ts +++ b/packages/ui-stencil/src/components.d.ts @@ -145,28 +145,94 @@ export namespace Components { "suggestions"?: string[]; } interface OramaSearchBox { + /** + * Callback function used on every AI Chat link + */ "chatMarkdownLinkHref"?: ChatMarkdownLinkHref; + /** + * Callback function used on every AI Chat link target + */ "chatMarkdownLinkTarget"?: ChatMarkdownLinkTarget; + /** + * Callback function used on every AI Chat link title + */ "chatMarkdownLinkTitle"?: ChatMarkdownLinkTitle; + /** + * Placeholder for chat input + */ "chatPlaceholder"?: string; + /** + * Orama Instance + */ "clientInstance"?: OramaClient | AnyOrama; + /** + * Component color schema + */ "colorScheme"?: ColorScheme; + /** + * Disables chat capabilities + */ "disableChat"?: boolean; + /** + * Index result property to + */ "facetProperty"?: string; + /** + * Options for highlights of Search Result descriptions + */ "highlightDescription"?: HighlightOptions | false; + /** + * Options for highlights of Search Result titles + */ "highlightTitle"?: HighlightOptions | false; + /** + * Orama Index configuration note: It will be overrided by clientInstance property + */ "index"?: CloudIndexConfig; + /** + * This component can behave either as Modal or a Embed component. For Modal, a new absolute panel will be displayed on top. For Embed, Orama Search Box will be displayed as a inline component. + */ "layout"?: 'modal' | 'embed'; + /** + * Used to provide linkRel to search result links + */ "linksRel"?: string; + /** + * Used to provide linkRel to search result links + */ "linksTarget"?: string; "open": boolean; + /** + * @deprecated it will be removed on next releases Placeholder for chat input + */ "placeholder"?: string; + /** + * Used to map dataset result properties to the expected SearchBox properties + */ "resultMap"?: Partial; + /** + * Parameters forwarded to Orama Client. + */ "searchParams"?: SearchParams>; + /** + * Placeholder for search input + */ "searchPlaceholder"?: string; + /** + * Used to provide source base URL for the Search Results + */ "sourceBaseUrl"?: string; + /** + * Used to map Chat result sources to expected Orama Chat properties + */ "sourcesMap"?: SourcesMap; + /** + * List of initial questions for Orama Chat + */ "suggestions"?: string[]; + /** + * Component theme customization + */ "themeConfig"?: Partial; } interface OramaSearchButton { @@ -721,19 +787,61 @@ declare namespace LocalJSX { "suggestions"?: string[]; } interface OramaSearchBox { + /** + * Callback function used on every AI Chat link + */ "chatMarkdownLinkHref"?: ChatMarkdownLinkHref; + /** + * Callback function used on every AI Chat link target + */ "chatMarkdownLinkTarget"?: ChatMarkdownLinkTarget; + /** + * Callback function used on every AI Chat link title + */ "chatMarkdownLinkTitle"?: ChatMarkdownLinkTitle; + /** + * Placeholder for chat input + */ "chatPlaceholder"?: string; + /** + * Orama Instance + */ "clientInstance"?: OramaClient | AnyOrama; + /** + * Component color schema + */ "colorScheme"?: ColorScheme; + /** + * Disables chat capabilities + */ "disableChat"?: boolean; + /** + * Index result property to + */ "facetProperty"?: string; + /** + * Options for highlights of Search Result descriptions + */ "highlightDescription"?: HighlightOptions | false; + /** + * Options for highlights of Search Result titles + */ "highlightTitle"?: HighlightOptions | false; + /** + * Orama Index configuration note: It will be overrided by clientInstance property + */ "index"?: CloudIndexConfig; + /** + * This component can behave either as Modal or a Embed component. For Modal, a new absolute panel will be displayed on top. For Embed, Orama Search Box will be displayed as a inline component. + */ "layout"?: 'modal' | 'embed'; + /** + * Used to provide linkRel to search result links + */ "linksRel"?: string; + /** + * Used to provide linkRel to search result links + */ "linksTarget"?: string; /** * Fired when answer generation is successfully completed @@ -756,13 +864,37 @@ declare namespace LocalJSX { */ "onSearchResultClick"?: (event: OramaSearchBoxCustomEvent) => void; "open"?: boolean; + /** + * @deprecated it will be removed on next releases Placeholder for chat input + */ "placeholder"?: string; + /** + * Used to map dataset result properties to the expected SearchBox properties + */ "resultMap"?: Partial; + /** + * Parameters forwarded to Orama Client. + */ "searchParams"?: SearchParams>; + /** + * Placeholder for search input + */ "searchPlaceholder"?: string; + /** + * Used to provide source base URL for the Search Results + */ "sourceBaseUrl"?: string; + /** + * Used to map Chat result sources to expected Orama Chat properties + */ "sourcesMap"?: SourcesMap; + /** + * List of initial questions for Orama Chat + */ "suggestions"?: string[]; + /** + * Component theme customization + */ "themeConfig"?: Partial; } interface OramaSearchButton { diff --git a/packages/ui-stencil/src/components/orama-search-box/orama-search-box.tsx b/packages/ui-stencil/src/components/orama-search-box/orama-search-box.tsx index 25693f8..da7cde6 100644 --- a/packages/ui-stencil/src/components/orama-search-box/orama-search-box.tsx +++ b/packages/ui-stencil/src/components/orama-search-box/orama-search-box.tsx @@ -36,30 +36,99 @@ import type { TThemeOverrides } from '@/config/theme' export class SearchBox { @Element() htmlElement!: HTMLElement + /** + * Component theme customization + */ @Prop() themeConfig?: Partial + /** + * Component color schema + */ @Prop() colorScheme?: ColorScheme = 'light' + /** + * Orama Index configuration + * + * note: It will be overrided by clientInstance property + */ @Prop() index?: CloudIndexConfig + /** + * Orama Instance + */ @Prop() clientInstance?: OramaClient | AnyOrama @Prop({ mutable: true }) open = false + /** + * Index result property to + */ @Prop() facetProperty?: string + /** + * Used to map dataset result properties to the expected SearchBox properties + */ @Prop() resultMap?: Partial = {} + /** + * Used to provide source base URL for the Search Results + */ @Prop() sourceBaseUrl?: string + /** + * Used to provide linkRel to search result links + */ @Prop() linksTarget?: string + /** + * Used to provide linkRel to search result links + */ @Prop() linksRel?: string + /** + * Used to map Chat result sources to expected Orama Chat properties + */ @Prop() sourcesMap?: SourcesMap + /** + * Disables chat capabilities + */ @Prop() disableChat?: boolean = false + /** + * This component can behave either as Modal or a Embed component. + * For Modal, a new absolute panel will be displayed on top. + * For Embed, Orama Search Box will be displayed as a inline component. + */ @Prop() layout?: 'modal' | 'embed' = 'modal' + /** + * Options for highlights of Search Result titles + */ @Prop() highlightTitle?: HighlightOptions | false = false + /** + * Options for highlights of Search Result descriptions + */ @Prop() highlightDescription?: HighlightOptions | false = false - - // TODO: remove it in favor of dictionary + /** + * @deprecated it will be removed on next releases + * Placeholder for chat input + */ @Prop() placeholder?: string + /** + * Placeholder for chat input + */ @Prop() chatPlaceholder?: string + /** + * Placeholder for search input + */ @Prop() searchPlaceholder?: string + /** + * List of initial questions for Orama Chat + */ @Prop() suggestions?: string[] + /** + * Parameters forwarded to Orama Client. + */ @Prop() searchParams?: SearchParams> + /** + * Callback function used on every AI Chat link title + */ @Prop() chatMarkdownLinkTitle?: ChatMarkdownLinkTitle + /** + * Callback function used on every AI Chat link + */ @Prop() chatMarkdownLinkHref?: ChatMarkdownLinkHref + /** + * Callback function used on every AI Chat link target + */ @Prop() chatMarkdownLinkTarget?: ChatMarkdownLinkTarget @State() componentID = generateRandomID('search-box') diff --git a/packages/ui-stencil/src/components/orama-search-box/readme.md b/packages/ui-stencil/src/components/orama-search-box/readme.md index 048652c..8ac8a09 100644 --- a/packages/ui-stencil/src/components/orama-search-box/readme.md +++ b/packages/ui-stencil/src/components/orama-search-box/readme.md @@ -5,31 +5,31 @@ ## Properties -| Property | Attribute | Description | Type | Default | -| ------------------------ | ----------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | -| `chatMarkdownLinkHref` | -- | | `({ text, href }: { text: string; href: string; }) => string` | `undefined` | -| `chatMarkdownLinkTarget` | -- | | `({ text, href }: { text: string; href: string; }) => string` | `undefined` | -| `chatMarkdownLinkTitle` | -- | | `({ text, href }: { text: string; href: string; }) => string` | `undefined` | -| `chatPlaceholder` | `chat-placeholder` | | `string` | `undefined` | -| `clientInstance` | -- | | `FunctionComponents & Internals & ArrayCallbackComponents & OramaID & { plugins: OramaPlugin[]; } \| OramaClient` | `undefined` | -| `colorScheme` | `color-scheme` | | `"dark" \| "light" \| "system"` | `'light'` | -| `disableChat` | `disable-chat` | | `boolean` | `false` | -| `facetProperty` | `facet-property` | | `string` | `undefined` | -| `highlightDescription` | `highlight-description` | | `HighlightOptions \| boolean` | `false` | -| `highlightTitle` | `highlight-title` | | `HighlightOptions \| boolean` | `false` | -| `index` | -- | | `{ api_key: string; endpoint: string; }` | `undefined` | -| `layout` | `layout` | | `"embed" \| "modal"` | `'modal'` | -| `linksRel` | `links-rel` | | `string` | `undefined` | -| `linksTarget` | `links-target` | | `string` | `undefined` | -| `open` | `open` | | `boolean` | `false` | -| `placeholder` | `placeholder` | | `string` | `undefined` | -| `resultMap` | -- | | `{ section?: string \| ResultMapRenderFunction; title?: string \| ResultMapRenderFunction; path?: string \| ResultMapRenderFunction; description?: string \| ResultMapRenderFunction; }` | `{}` | -| `searchParams` | -- | | `SearchParamsFullText>, never> \| SearchParamsHybrid>, never> \| SearchParamsVector>, never>` | `undefined` | -| `searchPlaceholder` | `search-placeholder` | | `string` | `undefined` | -| `sourceBaseUrl` | `source-base-url` | | `string` | `undefined` | -| `sourcesMap` | -- | | `{ title?: string; path?: string; description?: string; }` | `undefined` | -| `suggestions` | -- | | `string[]` | `undefined` | -| `themeConfig` | -- | | `{ typography?: DeepPartial<{ '--font-primary': string; }>; colors?: DeepPartial<{ gray50: string; gray100: string; gray200: string; gray300: string; gray400: string; gray500: string; gray600: string; gray700: string; gray800: string; gray900: string; gray950: string; purple100: string; purple200: string; purple300: string; purple500: string; purple600: string; purple700: string; light: { "--text-color-primary": string; "--text-color-secondary": string; "--text-color-tertiary": string; "--text-color-accent": string; "--text-color-inactive": string; "--text-color-reverse": string; "--background-color-primary": string; "--background-color-secondary": string; "--background-color-tertiary": string; "--background-color-fourth": string; "--background-color-reverse": string; "--background-color-accent": string; "--border-color-primary": string; "--border-color-secondary": string; "--border-color-tertiary": string; "--border-color-accent": string; "--icon-color-primary": string; "--icon-color-secondary": string; "--icon-color-tertiary": string; "--icon-color-inactive": string; "--icon-color-reverse": string; "--shadow-color-primary": string; "--button-text-color-primary": string; "--button-text-color-secondary": string; "--button-background-color-primary": string; "--button-background-color-secondary": string; "--button-background-color-secondary-hover": string; "--button-border-color-secondary": string; "--backdrop-background-color-primary": string; "--chat-button-border-color-gradientOne": string; "--chat-button-border-color-gradientTwo": string; "--chat-button-border-color-gradientThree": string; "--chat-button-border-color-gradientFour": string; "--chat-button-border-color-gradientFive": string; "--chat-button-border-color-gradientSix": string; "--chat-button-background-color-gradientOne": string; "--chat-button-background-color-gradientTwo": string; }; dark: { "--text-color-primary": string; "--text-color-secondary": string; "--text-color-tertiary": string; "--text-color-accent": string; "--text-color-inactive": string; "--text-color-reverse": string; "--background-color-primary": string; "--background-color-secondary": string; "--background-color-tertiary": string; "--background-color-fourth": string; "--background-color-reverse": string; "--background-color-accent": string; "--border-color-primary": string; "--border-color-secondary": string; "--border-color-tertiary": string; "--border-color-accent": string; "--icon-color-primary": string; "--icon-color-secondary": string; "--icon-color-tertiary": string; "--icon-color-inactive": string; "--icon-color-reverse": string; "--shadow-color-primary": string; "--button-text-color-primary": string; "--button-text-color-secondary": string; "--button-background-color-primary": string; "--button-background-color-secondary": string; "--button-background-color-secondary-hover": string; "--button-border-color-secondary": string; "--backdrop-background-color-primary": string; "--chat-button-border-color-gradientOne": string; "--chat-button-border-color-gradientTwo": string; "--chat-button-border-color-gradientThree": string; "--chat-button-border-color-gradientFour": string; "--chat-button-border-color-gradientFive": string; "--chat-button-border-color-gradientSix": string; "--chat-button-background-color-gradientOne": string; "--chat-button-background-color-gradientTwo": string; }; }>; }` | `undefined` | +| Property | Attribute | Description | Type | Default | +| ------------------------ | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | +| `chatMarkdownLinkHref` | -- | Callback function used on every AI Chat link | `({ text, href }: { text: string; href: string; }) => string` | `undefined` | +| `chatMarkdownLinkTarget` | -- | Callback function used on every AI Chat link target | `({ text, href }: { text: string; href: string; }) => string` | `undefined` | +| `chatMarkdownLinkTitle` | -- | Callback function used on every AI Chat link title | `({ text, href }: { text: string; href: string; }) => string` | `undefined` | +| `chatPlaceholder` | `chat-placeholder` | Placeholder for chat input | `string` | `undefined` | +| `clientInstance` | -- | Orama Instance | `FunctionComponents & Internals & ArrayCallbackComponents & OramaID & { plugins: OramaPlugin[]; } \| OramaClient` | `undefined` | +| `colorScheme` | `color-scheme` | Component color schema | `"dark" \| "light" \| "system"` | `'light'` | +| `disableChat` | `disable-chat` | Disables chat capabilities | `boolean` | `false` | +| `facetProperty` | `facet-property` | Index result property to | `string` | `undefined` | +| `highlightDescription` | `highlight-description` | Options for highlights of Search Result descriptions | `HighlightOptions \| boolean` | `false` | +| `highlightTitle` | `highlight-title` | Options for highlights of Search Result titles | `HighlightOptions \| boolean` | `false` | +| `index` | -- | Orama Index configuration note: It will be overrided by clientInstance property | `{ api_key: string; endpoint: string; }` | `undefined` | +| `layout` | `layout` | This component can behave either as Modal or a Embed component. For Modal, a new absolute panel will be displayed on top. For Embed, Orama Search Box will be displayed as a inline component. | `"embed" \| "modal"` | `'modal'` | +| `linksRel` | `links-rel` | Used to provide linkRel to search result links | `string` | `undefined` | +| `linksTarget` | `links-target` | Used to provide linkRel to search result links | `string` | `undefined` | +| `open` | `open` | | `boolean` | `false` | +| `placeholder` | `placeholder` | **[DEPRECATED]** it will be removed on next releases Placeholder for chat input

| `string` | `undefined` | +| `resultMap` | -- | Used to map dataset result properties to the expected SearchBox properties | `{ section?: string \| ResultMapRenderFunction; title?: string \| ResultMapRenderFunction; path?: string \| ResultMapRenderFunction; description?: string \| ResultMapRenderFunction; }` | `{}` | +| `searchParams` | -- | Parameters forwarded to Orama Client. | `SearchParamsFullText>, never> \| SearchParamsHybrid>, never> \| SearchParamsVector>, never>` | `undefined` | +| `searchPlaceholder` | `search-placeholder` | Placeholder for search input | `string` | `undefined` | +| `sourceBaseUrl` | `source-base-url` | Used to provide source base URL for the Search Results | `string` | `undefined` | +| `sourcesMap` | -- | Used to map Chat result sources to expected Orama Chat properties | `{ title?: string; path?: string; description?: string; }` | `undefined` | +| `suggestions` | -- | List of initial questions for Orama Chat | `string[]` | `undefined` | +| `themeConfig` | -- | Component theme customization | `{ typography?: DeepPartial<{ '--font-primary': string; }>; colors?: DeepPartial<{ gray50: string; gray100: string; gray200: string; gray300: string; gray400: string; gray500: string; gray600: string; gray700: string; gray800: string; gray900: string; gray950: string; purple100: string; purple200: string; purple300: string; purple500: string; purple600: string; purple700: string; light: { "--text-color-primary": string; "--text-color-secondary": string; "--text-color-tertiary": string; "--text-color-accent": string; "--text-color-inactive": string; "--text-color-reverse": string; "--background-color-primary": string; "--background-color-secondary": string; "--background-color-tertiary": string; "--background-color-fourth": string; "--background-color-reverse": string; "--background-color-accent": string; "--border-color-primary": string; "--border-color-secondary": string; "--border-color-tertiary": string; "--border-color-accent": string; "--icon-color-primary": string; "--icon-color-secondary": string; "--icon-color-tertiary": string; "--icon-color-inactive": string; "--icon-color-reverse": string; "--shadow-color-primary": string; "--button-text-color-primary": string; "--button-text-color-secondary": string; "--button-background-color-primary": string; "--button-background-color-secondary": string; "--button-background-color-secondary-hover": string; "--button-border-color-secondary": string; "--backdrop-background-color-primary": string; "--chat-button-border-color-gradientOne": string; "--chat-button-border-color-gradientTwo": string; "--chat-button-border-color-gradientThree": string; "--chat-button-border-color-gradientFour": string; "--chat-button-border-color-gradientFive": string; "--chat-button-border-color-gradientSix": string; "--chat-button-background-color-gradientOne": string; "--chat-button-background-color-gradientTwo": string; }; dark: { "--text-color-primary": string; "--text-color-secondary": string; "--text-color-tertiary": string; "--text-color-accent": string; "--text-color-inactive": string; "--text-color-reverse": string; "--background-color-primary": string; "--background-color-secondary": string; "--background-color-tertiary": string; "--background-color-fourth": string; "--background-color-reverse": string; "--background-color-accent": string; "--border-color-primary": string; "--border-color-secondary": string; "--border-color-tertiary": string; "--border-color-accent": string; "--icon-color-primary": string; "--icon-color-secondary": string; "--icon-color-tertiary": string; "--icon-color-inactive": string; "--icon-color-reverse": string; "--shadow-color-primary": string; "--button-text-color-primary": string; "--button-text-color-secondary": string; "--button-background-color-primary": string; "--button-background-color-secondary": string; "--button-background-color-secondary-hover": string; "--button-border-color-secondary": string; "--backdrop-background-color-primary": string; "--chat-button-border-color-gradientOne": string; "--chat-button-border-color-gradientTwo": string; "--chat-button-border-color-gradientThree": string; "--chat-button-border-color-gradientFour": string; "--chat-button-border-color-gradientFive": string; "--chat-button-border-color-gradientSix": string; "--chat-button-background-color-gradientOne": string; "--chat-button-background-color-gradientTwo": string; }; }>; }` | `undefined` | ## Events