Skip to content

Commit

Permalink
Merge pull request #71 from oramasearch/documentation
Browse files Browse the repository at this point in the history 
chore: better document Orama Search Box
  • Loading branch information
@rjborba
rjborba authored Jan 16, 2025
2 parents f988260 + 29679dc commit 1257ec9
Show file tree
Hide file tree
Showing 4 changed files with 241 additions and 38 deletions.
24 changes: 13 additions & 11 deletions packages/ui-stencil/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,30 +32,32 @@ Or import it directly in a browser module:
</div>
<script>
let open = false;
Object.assign(document.querySelector("orama-search-box"), {
Object.assign(document.querySelector('orama-search-box'), {
open: open,
index: {
endpoint: "https://cloud.orama.run/v1/indexes/orama-docs-bzo330",
api_key: "NKiqTJnwnKsQCdxN7RyOBJgeoW5hJ594",
endpoint: 'https://cloud.orama.run/v1/indexes/orama-docs-bzo330',
api_key: 'NKiqTJnwnKsQCdxN7RyOBJgeoW5hJ594',
},
facetProperty: 'category',
sourceBaseUrl: "https://docs.orama.com",
sourceBaseUrl: 'https://docs.orama.com',
sourcesMap: {
title: 'title',
description: 'content'
description: 'content',
},
resultMap: {
title: 'title',
description: 'content',
section: 'category',
},
searchPlaceholder: 'Search something...',
chatPlaceholder: "What do you want to learn about Orama?",
suggestions: [
'What is Orama?',
'Does Orama integrate with Shopify?',
'How do I create an answer session?'
]
chatPlaceholder: 'What do you want to learn about Orama?',
suggestions: ['What is Orama?', 'Does Orama integrate with Shopify?', 'How do I create an answer session?'],
});
</script>
```

## 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)
132 changes: 132 additions & 0 deletions packages/ui-stencil/src/components.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<ResultMap>;
/**
* Parameters forwarded to Orama Client.
*/
"searchParams"?: SearchParams<Orama<AnyOrama | OramaClient>>;
/**
* 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<TThemeOverrides>;
}
interface OramaSearchButton {
Expand Down Expand Up @@ -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
Expand All @@ -756,13 +864,37 @@ declare namespace LocalJSX {
*/
"onSearchResultClick"?: (event: OramaSearchBoxCustomEvent<OnSearchResultClickCallbackProps>) => 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<ResultMap>;
/**
* Parameters forwarded to Orama Client.
*/
"searchParams"?: SearchParams<Orama<AnyOrama | OramaClient>>;
/**
* 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<TThemeOverrides>;
}
interface OramaSearchButton {
Expand Down
73 changes: 71 additions & 2 deletions packages/ui-stencil/src/components/orama-search-box/orama-search-box.tsx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,30 +36,99 @@ import type { TThemeOverrides } from '@/config/theme'
export class SearchBox {
@Element() htmlElement!: HTMLElement

/**
* Component theme customization
*/
@Prop() themeConfig?: Partial<TThemeOverrides>
/**
* 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<ResultMap> = {}
/**
* 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<Orama<AnyOrama | OramaClient>>
/**
* 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')
Expand Down
Loading

0 comments on commit 1257ec9

Please sign in to comment.