@ownclouders/design-system
Version:
ownCloud Design System is based on VueDesign Systems and is used to design ownCloud UI components
110 lines (109 loc) • 4.87 kB
TypeScript
/**
* @component OcSearchBar
* @description
* The OcSearchBar component is an input element used for searching server-side resources or filtering local results.
* It supports features like type-ahead search, trimming input, and customizable buttons for search and cancel actions.
*
* @Accessibility
* Landmark role=search**: Communicates its purpose as the main site search to screen readers. Use `isFilter="true"` to disable the landmark role if used as a filter form.
* Submit button**: Ensures a submit button exists, even if visually hidden (`buttonHidden="true"`).
* Loading spinner aria-label**: Set via `loadingAccessibleLabel` or defaults to "Loading results".
*
* @props
* @prop {string|null} [value=null] - The search query value.
* @prop {string} [icon='search'] - The icon to display in the search bar.
* @prop {string} [placeholder=''] - Placeholder text for the input field.
* @prop {string} [label=''] - Aria-label for the input field.
* @prop {boolean} [small=false] - Whether the search bar should be smaller in size.
* @prop {string} [buttonLabel='Search'] - Label for the search button.
* @prop {boolean} [buttonHidden=false] - Whether to hide the search button visually.
* @prop {boolean} [typeAhead=false] - If true, triggers the search event on each character input.
* @prop {boolean} [trimQuery=true] - Automatically trims whitespaces around the search term.
* @prop {boolean} [loading=false] - If true, disables input and shows a loading spinner.
* @prop {boolean} [isFilter=false] - If true, removes the search landmark role.
* @prop {string} [loadingAccessibleLabel=''] - Aria-label for the loading spinner.
* @prop {boolean} [showCancelButton=false] - Whether to show a cancel button.
* @prop {'passive'|'primary'|'danger'|'success'|'warning'|'brand'} [cancelButtonVariation='primary'] - Variation of the cancel button.
* @prop {'outline'|'filled'|'raw'|'raw-inverse'} [cancelButtonAppearance='raw'] - Appearance of the cancel button.
* @prop {Function} [cancelHandler=() => {}] - Handler function for the cancel button click.
*
* @emits
* @event advancedSearch {MouseEvent} - Emitted when the advanced search button is clicked.
* @event clear {Event} - Emitted when the search input is cleared.
* @event input {string} - Emitted on input change.
* @event keyup {KeyboardEvent} - Emitted on keyup event in the input field.
* @event search {string} - Emitted when the search button is clicked or enter is pressed.
*
* @example
* <OcSearchBar
* :value="searchQuery"
* icon="search"
* placeholder="Search for items"
* label="Search"
* :small="false"
* buttonLabel="Search"
* :buttonHidden="false"
* :typeAhead="true"
* :trimQuery="true"
* :loading="isLoading"
* :isFilter="false"
* loadingAccessibleLabel="Loading search results"
* :showCancelButton="true"
* cancelButtonVariation="primary"
* cancelButtonAppearance="outline"
* :cancelHandler="onCancel"
* @search="onSearch"
* @input="onInput"
* />
*/
interface Props {
value?: string | null;
icon?: string;
placeholder?: string;
label?: string;
small?: boolean;
buttonLabel?: string;
buttonHidden?: boolean;
typeAhead?: boolean;
trimQuery?: boolean;
loading?: boolean;
isFilter?: boolean;
loadingAccessibleLabel?: string;
showCancelButton?: boolean;
cancelButtonVariation?: 'passive' | 'primary' | 'danger' | 'success' | 'warning' | 'brand';
cancelButtonAppearance?: 'outline' | 'filled' | 'raw' | 'raw-inverse';
cancelHandler?: () => void;
}
declare function __VLS_template(): {
attrs: Partial<{}>;
slots: {
locationFilter?(_: {}): any;
};
refs: {
searchInput: HTMLInputElement;
};
rootEl: HTMLDivElement;
};
type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
declare const __VLS_component: import('vue').DefineComponent<Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {} & {
input: (event: string) => any;
search: (event: string) => any;
clear: (event: Event) => any;
keyup: (event: KeyboardEvent) => any;
advancedSearch: (event: MouseEvent) => any;
}, string, import('vue').PublicProps, Readonly<Props> & Readonly<{
onInput?: (event: string) => any;
onSearch?: (event: string) => any;
onClear?: (event: Event) => any;
onKeyup?: (event: KeyboardEvent) => any;
onAdvancedSearch?: (event: MouseEvent) => any;
}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {
searchInput: HTMLInputElement;
}, HTMLDivElement>;
declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
export default _default;
type __VLS_WithTemplateSlots<T, S> = T & {
new (): {
$slots: S;
};
};