@searchcraft/javascript-sdk 0.5.3 → 0.7.0

package/dist/types/components/searchcraft-base-search-results/searchcraft-base-search-results.d.ts

@@ -1,18 +1,86 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { SearchcraftResponse } from '@searchcraft/core';
 import type { SearchResultMappings } from "../../types/index";
+/**
+ * This web component is responsible for displaying the results of a search query.
+ * Once a query is submitted, the component formats and presents an ordered list of the results.
+ *
+ * ## Usage
+ * ```html
+ * <!-- index.html -->
+ * <searchcraft-base-search-results
+ *   ad-interval="4"
+ *   place-ad-at-start="false"
+ *   result-image-placement="right"
+ * />
+ * ```
+ *
+ * ```js
+ * // index.js
+ * const baseSearchResults = document.querySelector('searchcraft-base-search-results');
+ *
+ * baseSearchResults.searchResultMappings = containerHref: {
+ *   fieldNames: [
+ *    {
+ *      fieldName: 'canonical_link',
+ *      dataType: 'text',
+ *    },
+ *  ],
+ * };
+ *
+ * baseSearchResults.addEventListener('noResults', () => {
+ *   console.log('No search results found');
+ * });
+ * ```
+ */
 export declare class SearchcraftBaseSearchResults {
+    /**
+     * How often ads are injected.
+     */
     adInterval: number;
+    /**
+     * A custom styles object.
+     */
     customStylesForResults: string | Record<string, Record<string, string>> | undefined;
+    /**
+     * Formats the content rendered for each result.
+     */
     searchResultMappings: SearchResultMappings | undefined;
+    /**
+     * Should an ad be placed at the end of the results.
+     */
     placeAdAtEnd: boolean;
+    /**
+     * Should an ad be placed at the start of the results.
+     */
     placeAdAtStart: boolean;
+    /**
+     * The placement of the image for each result.
+     */
     resultImagePlacement: 'left' | 'right';
+    /**
+     * The label for the button rendered when containerHref is not present for each result.
+     */
     buttonLabel: string | undefined;
+    /**
+     * Where to open the link for the button rendered when containerHref is not present for each result.
+     */
     buttonTarget: '_blank' | '_self' | '_top' | '_parent';
+    /**
+     * The relationship between the current document and the link for the button rendered when containerHref is not present for each result.
+     */
     buttonRel: 'noreferrer' | 'noopener' | 'nofollow' | undefined;
+    /**
+     * Where to open the link for the containing element for each result.
+     */
     containerTarget: '_blank' | '_self' | '_top' | '_parent';
+    /**
+     * The relationship between the current document and the link for the containing element for each result.
+     */
     containerRel: 'noreferrer' | 'noopener' | 'nofollow' | undefined;
+    /**
+     * When no results are returned.
+     */
     noResults: EventEmitter<void>;
     hasSearched: boolean;
     query: string;

package/dist/types/components/searchcraft-button/searchcraft-button.d.ts

@@ -1,9 +1,29 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
+/**
+ * This web component represents a button to be consumed within the `search-input-form` component.
+ * It provides a clear, interactive way for users to submit search queries or trigger actions in a search interface.
+ * It is consumed within the `searchcraft-input-form` component.
+ */
 export declare class SearchcraftButton {
+    /**
+     * The icon element.
+     */
     iconElement?: Element;
+    /**
+     * Should the button only display an icon.
+     */
     iconOnly: boolean;
+    /**
+     * The position of the icon.
+     */
     iconPosition: string;
+    /**
+     * The label for the button.
+     */
     label: string;
+    /**
+     * When the button is clicked.
+     */
     buttonClick: EventEmitter<void>;
     isRequesting: boolean;
     private handleClick;

package/dist/types/components/searchcraft-error-message/searchcraft-error-message.d.ts

@@ -1,4 +1,16 @@
+/**
+ * This web component is designed to display a user-friendly error message when a search query fails, providing clear feedback to users and enhancing their experience when an issue arises during the search process.
+ *
+ * ## Usage
+ * ```html
+ * <!-- index.html -->
+ * <searchcraft-error-message error-message="No search results found for query" />
+ * ```
+ */
 export declare class SearchcraftErrorMessage {
+    /**
+     * The error message.
+     */
     errorMessage?: string;
     render(): any;
 }

package/dist/types/components/searchcraft-facet-list/searchcraft-facet-list.d.ts

@@ -1,8 +1,33 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { FacetChild, FacetRoot } from '@searchcraft/core';
 import { type SearchcraftState } from "../../provider/store";
+/**
+ * This web component is designed to display facets in a search interface, allowing users to refine their search results by applying filters based on various attributes.
+ * It is consumed within the `searchcraft-filter-panel`.
+ *
+ * ## Usage
+ * ```html
+ * <!-- index.html -->
+ * <searchcraft-facet-list field-name="title" />
+ * ```
+ *
+ * ```js
+ * // index.js
+ * const facetList = document.querySelector('searchcraft-facet-list');
+ *
+ * facetList.addEventListener('facetSelectionUpdated', () => {
+ *   console.log('Facet selection updated');
+ * });
+ * ```
+ */
 export declare class SearchcraftFacetList {
+    /**
+     * The name of the field where facets are applied.
+     */
     fieldName: string;
+    /**
+     * When the facets are updated.
+     */
     facetSelectionUpdated: EventEmitter<{
         paths: string[];
     }>;

package/dist/types/components/searchcraft-filter-panel/searchcraft-filter-panel.d.ts

@@ -1,5 +1,17 @@
 import type { FilterItem } from '../../types/searchcraft-filter-panel.types';
+/**
+ * This web component represents a series of filters that allows users to refine and control their search queries by applying various filter criteria.
+ *
+ * ## Usage
+ * ```html
+ * <!-- index.html -->
+ * <searchcraft-filter-panel />
+ * ```
+ */
 export declare class SearchcraftFilterPanel {
+    /**
+     * The items to filter.
+     */
     items: FilterItem[];
     unsubscribe: (() => void) | undefined;
     lastQuery: string | undefined;

package/dist/types/components/searchcraft-input-form/searchcraft-input-form.d.ts

@@ -4,6 +4,31 @@ export interface ScInputCustomEvent<T> extends CustomEvent<T> {
     detail: T;
     target: HTMLSearchcraftInputFormElement;
 }
+/**
+ * This web component provides a user-friendly interface for querying an indexed dataset, enabling users to easily search large collections of data.
+ * It abstracts the complexities of index-based searching, making it accessible to users of all technical levels.
+ *
+ * ## Usage
+ * ```html
+ * <!-- index.html -->
+ * <searchcraft-input-form placeholder-value="Search here" />
+ * ```
+ *
+ * ```js
+ * // index.js
+ * const searchInputForm = document.querySelector('searchcraft-input-form');
+ *
+ * seardchInputForm.config = {
+ *   index: [],
+ *   readKey: '',
+ *   endpointUrl: '',
+ * };
+ *
+ * searchForm.addEventListener('querySubmit', (event) => {
+ *   console.log('Query submitted', event.detail);
+ * });
+ * ```
+ */
 export declare class SearchcraftInput {
     /**
      * The Searchcraft config object.
@@ -38,33 +63,32 @@ export declare class SearchcraftInput {
      */
     searchTerm: string;
     /**
-     * The duration to debounce the input's `inputChange` event.
-     */
-    debounceDelay: number;
-    /**
-     * Event emitted when the input element has been cleared.
+     * When the input is cleared.
      */
     inputCleared: EventEmitter<void>;
     /**
-     * Event emitted when a query returns with no results received.
+     * When no results are returned.
      */
     noResultsReceived: EventEmitter<void>;
     /**
-     * Event emitted when a new search request has been submitted.
-     */
-    querySubmit: EventEmitter<string>;
-    /**
-     * Event emitted when the input has gained focus.
+     * When the input becomes focused.
      */
     inputFocus: EventEmitter<void>;
     /**
-     * Event emitted when the input has lost focus.
+     * When the input becomes unfocused.
      */
     inputBlur: EventEmitter<void>;
+    /**
+     * Event emitted when input initializes.
+     */
+    inputInit: EventEmitter<void>;
+    /**
+     * Event emitted when a query has been submitted.
+     */
+    querySubmit: EventEmitter<string>;
     inputValue: string;
     error: boolean;
     isSearchcraftInitialized: boolean;
-    private debounceTimeout;
     private searchStore;
     init(): void;
     componentDidLoad(): void;

package/dist/types/components/searchcraft-input-label/searchcraft-input-label.d.ts

@@ -1,5 +1,17 @@
+/**
+ * This web component serves as the input label for the searchcraft-input-form component.
+ *
+ * ## Usage
+ * ```html
+ * <!-- index.html -->
+ * <searchcraft-input-label label="Search" />
+ * ```
+ */
 export declare class SearchcraftInputLabel {
+    /**
+     * The classname applied to the label element.
+     */
     inputLabelClassName?: string;
-    label?: string;
+    label: string;
     render(): any;
 }

package/dist/types/components/searchcraft-popover-button/searchcraft-popover-button.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Renders a button which, when clicked, turns on popover visibility.
+ */
+export declare class SearchcraftPopoverButton {
+    handleOnClick(): void;
+    render(): any;
+}

package/dist/types/components/searchcraft-popover-form/searchcraft-popover-form.d.ts

@@ -1,8 +1,104 @@
-import type { SearchcraftConfig } from '@searchcraft/core';
+import type { SearchcraftConfig, SearchcraftResponse } from '@searchcraft/core';
 import type { PopoverResultMappings } from "../../types/index";
+/**
+ * This web component is designed to display search results in a popover container that dynamically appears when the user interacts with a search input field.
+ *
+ * ## Usage
+ * ```html
+ * <!-- index.html -->
+ * <searchcraft-popover-form type="fullscreen" />
+ * ```
+ *
+ * ```js
+ * // index.js
+ * const popoverForm = document.querySelector('searchcraft-popover-form');
+ *
+ * popoverForm.config = {
+ *   index: [index_name_from_vektron],
+ *   readKey: 'read_key_from_vektron',
+ *   endpointUrl: 'enpoint_url_from_vektron',
+ * };
+ *
+ * popoverForm.popoverResultMappings = {
+ *  containerHref: {
+ *   fieldNames: [
+ *    {
+ *      fieldName: 'canonical_link',
+ *      dataType: 'text',
+ *    },
+ *  ],
+ *  };
+ * ```
+ */
 export declare class SearchcraftPopoverForm {
+    /**
+     * The Searchcraft config object.
+     */
     config: SearchcraftConfig | undefined;
+    /**
+     * The type of popover form to render.
+     *
+     * - `inline` - Renders inline with the rest of the content on the page. The search results pop over the page content.
+     * - `fullscreen` - Renders in fullscreen view. Used together with the `searchcraft-popover-button` component.
+     * - `modal` - Renders in a modal view. Used together with the `searchcraft-popover-button` component.
+     */
     type: 'inline' | 'fullscreen' | 'modal';
+    /**
+     * Formats the content rendered for each result.
+     */
     popoverResultMappings: PopoverResultMappings | undefined;
+    /**
+     * The hotkey that activates the popover.
+     */
+    hotkey: string;
+    /**
+     * The hotkey modifier that activates the popover. Used together with the `hotkey` prop.
+     */
+    hotkeyModifier: 'ctrl' | 'meta' | 'alt' | 'option';
+    isPopoverVisibleInState: boolean;
+    unsubscribe: (() => void) | undefined;
+    searchResults: SearchcraftResponse | undefined;
+    searchTerm: string | undefined;
+    isFocused: boolean;
+    breakpointSm: number;
+    breakpointMd: number;
+    breakpointLg: number;
+    modalElement: any;
+    hostElement: HTMLElement;
+    componentDidLoad(): void;
+    disconnectedCallback(): void;
+    handleDocumentClick: (event: MouseEvent) => void;
+    /**
+     * Handles when popover visibility is changed in state
+     */
+    handlePopoverVisibilityChange(isVisible: boolean): void;
+    /**
+     * Actions to perform when various keys are pressed within the popover form.
+     */
+    handleDocumentKeyDown: (event: KeyboardEvent) => void;
+    handleInputInit: () => void;
+    /**
+     * When popover is `inline` and the viewport is at the smallest breakpoint,
+     * focusing on the input will open a modal version of the popover form.
+     */
+    handleInputFocus(): void;
+    handleModalBackdropClick(_event: MouseEvent): void;
+    /**
+     * When a hotkey is pressed, tests if the modifiers also match.
+     * If modifiers match, toggles visibility of the popover modal.
+     */
+    handleHotkeyPressed(event: KeyboardEvent): void;
+    handleCancelButtonClick(): void;
+    /**
+     * Moves focus to the next/previous list item in the list view. If you are at the top
+     * of the list view, it moves focus back to the input.
+     *
+     * @param direction
+     */
+    focusOnNextListItem(direction: 'ArrowDown' | 'ArrowUp'): void;
+    get hasResultsToShow(): boolean;
+    renderInlinePopover(documents: Record<string, unknown>[]): any;
+    renderModalPopover(documents: Record<string, unknown>[]): any;
+    renderFullscreenPopover(documents: Record<string, unknown>[]): any;
     render(): any;
 }

package/dist/types/components/searchcraft-popover-list-item/searchcraft-popover-list-item.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A single list item rendered in a searchcraft-popover-list-view.
+ */
+export declare class SearchcraftPopoverListItem {
+    /** The result title */
+    titleContent: string | undefined;
+    /** The result subtitle */
+    subtitleContent: string | undefined;
+    /** The source of the image. If not included, no item will be rendered. */
+    imageSrc: string | undefined;
+    /** The image alt tag. */
+    imageAlt: string | undefined;
+    /** The link href */
+    href: string | undefined;
+    /** The document position relative to the search results (For Measure) */
+    documentPosition: number;
+    componentDidLoad(): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    handleButtonClick(): void;
+    render(): any;
+}

package/dist/types/components/searchcraft-popover-list-view/searchcraft-popover-list-view.d.ts

@@ -1,8 +1,24 @@
 import type { PopoverResultMappings } from "../../types/index";
+/**
+ * This web component is designed to display a list of results within a popover interface.
+ * It is consumed within the `searchcraft-popover-form` component.
+ *
+ * ## Usage
+ * ```html
+ * <!-- index.html -->
+ * <searchcraft-popover-list-view />
+ * ```
+ */
 export declare class SearchcraftPopoverListView {
+    /**
+     * The mappings that define how the data in the documents are mapped to the
+     * list-view-item elements.
+     */
     popoverResultMappings: PopoverResultMappings | undefined;
-    componentDidLoad(): void;
-    connectedCallback(): void;
-    disconnectedCallback(): void;
+    /**
+     * The documents to render in the list view.
+     */
+    documents: Record<string, unknown>[] | undefined;
+    renderDocument(document: Record<string, unknown>, index: number): any;
     render(): any;
 }

package/dist/types/components/searchcraft-results-info/searchcraft-results-info.d.ts

@@ -1,3 +1,13 @@
+/**
+ * This web component is designed to display the number of results returned from a search query.
+ * It provides users with real-time feedback on the scale of the results, such as the total number of items found.
+ *
+ * ## Usage
+ * ```html
+ * <!-- index.html -->
+ * <searchcraft-results-info />
+ * ```
+ */
 export declare class SearchcraftResultsInfo {
     isRequesting: boolean;
     resultsCount: number;

package/dist/types/components/searchcraft-slider/searchcraft-slider.d.ts

@@ -1,12 +1,30 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
+/**
+ * This web component is designed to allow users to select a value from a range defined by a minimum and maximum value.
+ * The component renders a slider interface, which can be used to visually choose a value between two boundaries.
+ * It is consumed by the `searchcraft-filter-panel` component.
+ */
 export declare class SearchcraftSlider {
+    /**
+     * The maximum value allowed.
+     */
     max: number;
+    /**
+     * The minimum value allowed.
+     */
     min: number;
+    /**
+     * The granularity that the value must adhere to.
+     */
     granularity: number;
+    /** The type of data allowed. */
     dataType: 'number' | 'date';
     endValue: number;
     startValue: number;
     lastFocusedHandle: 'min' | 'max';
+    /**
+     * When the range has changed.
+     * */
     rangeChanged: EventEmitter<{
         startValue: number;
         endValue: number;

package/dist/types/components/searchcraft-toggle-button/searchcraft-toggle-button.d.ts

@@ -1,12 +1,20 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
+/**
+ * This web component simulates a light switch functionality, providing a simple and intuitive toggle between two states—on and off.
+ * It is consumed within the `searchcraft-filter-panel` component.
+ */
 export declare class SearchcraftToggleButton {
     /**
-     * Type of the toggle - determines what it controls
-     * 'mode': toggles between 'fuzzy' and 'normal'
-     * 'sort': toggles between 'asc' and 'desc'
+     * The label.
      */
     label: string;
+    /**
+     * The secondary label displayed below the main label.
+     */
     subLabel: string | undefined;
+    /**
+     * When the toggle element is changed.
+     */
     toggleUpdated: EventEmitter<boolean>;
     isActive: boolean;
     unsubscribe: (() => void) | undefined;