@searchcraft/react-sdk 0.1.0 → 0.1.1

package/README.md

@@ -1 +1,154 @@
-# Searchcraft React SDK
+# Searchcraft's React SDK
+
+This kit provides basic tools for building out a simple search interface using the Searchcraft API. Searching, tracking the request state, and displaying results are all available in this kit.
+
+## Usage
+
+Install with Yarn:
+
+```bash
+$ yarn add @searchcraft/react-sdk
+```
+
+Install with NPM:
+
+```bash
+$ npm install @searchcraft/react-sdk
+```
+
+Wrap your app or target a specific interface and wrap them with the `SearchcraftProvider` to expose the functionalities of the SDK.
+
+```jsx
+
+import { useMemo } from 'react'
+
+import { SearchcraftProvider, Searchcraft } from '@searchcraft/react-sdk'
+
+// values are created via the Searchcraft Vektron Customer Portal
+const searchcraftConfig = {
+  index: ['test_data'],
+  apiKey: '1234.909.jmk',
+  endpointURL: 'http://127.0.0.1:8000',
+}
+
+const Main = () => {
+  // initialize and pass an instance of Searchcraft into the provider
+  const searchcraft = useMemo(() => new Searchcraft(searchcraftConfig),[]);
+  return (
+    <SearchcraftProvider {...{ searchcraft }}>
+      <YourApplicationOrScreenGoHere />
+    </SearchcraftProvider>
+  )
+}
+
+```
+### Quickstart with useSearchcraft hook
+
+Once your app is wrapped in the `SearchcraftProvider`, the `useSearchcraft` hook functionalities are available for use.
+
+```jsx
+import {
+  useSearchcraft
+} from '@searchcraft/react-sdk';
+
+// import the styles from the SDK
+import '../node_modules/@searchcraft/react-sdk/dist/style.css'
+
+const SearchWithResultsComponent = () => {
+const { isRequesting, query, search, searchResults } = useSearchcraft()
+
+const handleClearInput = () => {
+  setQuery('')
+};
+
+  return (
+    <>
+      <AutoSearchForm
+        handleSubmit={handleSubmitForm}
+        inputCaptionValue="Search here"
+        onClearedInput={handleClearInput}
+        rightToLeftOrientation
+      />
+      <BaseSearchResults />
+    </>
+  )
+};
+```
+
+## UI Components
+
+The SDK provides 4 pre-built UI components with data provided to them via the `SearchcraftProvider` and `useSearchcraft` hook.
+
+```jsx
+import {
+  // Search input without submit button
+  AutoSearchForm,
+  // Search input with submit button
+  BasicSearchForm,
+  // Single Search Result component that can be customized while iterating over SearchResults
+  BasicSearchResult,
+  // Fully encapsulated list of search results with no iteration required
+  BasicSearchResults,
+  useSearchcraft
+} from '@searchcraft/react-sdk';
+
+const AutoSearchImplementation = () => {
+  const { query, search, searchResults } = useSearchcraft()
+
+  const handleSubmitForm = async () =>  await search(query, 'fuzzy')
+
+  const handleClearInput = () => setQuery('');
+
+  return (
+    <>
+      <AutoSearchForm
+        handleSubmit={handleSubmitForm}
+        inputCaptionValue="Search here"
+        onClearedInput={handleClearInput}
+        rightToLeftOrientation={true}
+      />
+    </>
+  )
+};
+
+const BasicSearchAndResultsImplementation = () => {
+  const { query, search, searchResults } = useSearchcraft();
+
+  const handleSubmitForm = async () => await search(query, 'fuzzy');
+
+  return (
+    <>
+      <BaseSearchForm
+        rightToLeftOrientation={false}
+        handleSubmit={handleSubmitForm}
+      />
+      {searchResults?.hits ? (
+        searchResults?.hits?.map((document, index) => {
+          const { doc: result } = document;
+          const callback = () => {
+            console.log('interactive');
+          };
+          const buttonCallback = () => {
+            console.log('button callback');
+          };
+          return (
+            <BaseSearchResult
+              key={`${result?.id}-${index}`}
+              buttonLabel='View More'
+              buttonCallbackFn={buttonCallback}
+              callbackFn={callback}
+              interactiveResult
+              imageSrc={result?.poster}
+              resultBodyContent={result?.overview}
+              resultHeading={result?.title}
+              resultSubheading={result?.release_date}
+            />
+          );
+        })
+      ) : (
+        <div>no search results found</div>
+      )}
+    </>
+  );
+}
+```

package/dist/index.d.ts

@@ -4,21 +4,26 @@ import { FC } from 'react';
 import { JSX as JSX_2 } from 'react/jsx-runtime';
 import { PropsWithChildren } from 'react';
 import { ReactNode } from 'react';
-import { SearchcraftDocument } from '@searchcraft-sdk/core';
+import { CoreSDK as Searchcraft } from '@searchcraft/core';
+import { SearchcraftInstance } from '@searchcraft/core';
+import { SearchError } from '@searchcraft/core';
+import { SearchResult } from '@searchcraft/core';
 import { SetStateAction } from 'react';
 
 /**
- * * Buttonless form used to submit the search query with a timing configurable debounced function.
+ * * Button-less form used to submit the search query with a timing configurable debounced function.
  */
 export declare const AutoSearchForm: FC<AutoSearchFormProps>;
 
 declare interface AutoSearchFormProps {
+    autoSearchFormClass?: string;
     handleSubmit: (query: string) => void;
     inputCaptionValue?: string;
     labelForInput?: string;
     onClearedInput?: () => void;
     placeholderValue?: string;
     rightToLeftOrientation?: boolean;
+    searchContainerClass?: string;
 }
 
 /**
@@ -49,11 +54,12 @@ declare interface BaseSearchResultProps {
     resultSubheading?: string;
 }
 
+export declare const BaseSearchResults: FC;
+
 export declare const Button: FC<ButtonProps>;
 
 declare type ButtonProps = {
     className?: string;
-    isRequesting?: boolean;
     iconElement?: ReactNode;
     iconOnly?: boolean;
     iconPosition?: string;
@@ -83,7 +89,6 @@ declare type InputProps = {
     inputCaptionClassName?: string;
     inputCaptionValue?: string;
     inputClassName?: string;
-    isRequesting?: boolean;
     onClearInput?: () => void;
     onSearchInputChange: ChangeEventHandler<HTMLInputElement>;
     placeholderValue?: string;
@@ -91,14 +96,14 @@ declare type InputProps = {
     query: string;
 };
 
-export declare const SearchcraftProvider: ({ children, config, }: PropsWithChildren & SearchcraftProviderConfig) => JSX_2.Element;
+export { Searchcraft }
+
+export declare const SearchcraftProvider: ({ children, searchcraft, }: PropsWithChildren & SearchcraftInstance) => JSX_2.Element;
 
 export declare interface SearchcraftProviderConfig {
-    config: {
-        index: string;
-        apiKey: string;
-        endpointPath: string;
-    };
+    index: string[];
+    apiKey: string;
+    endpointURL: string;
 }
 
 /** The context provided by the Searchcraft React SDK */
@@ -108,9 +113,9 @@ export declare interface SearchcraftProviderContext {
      */
     error: Error | null;
     /**
-     * The db name created in Vektron to query.
+     * The db name(s) created in Vektron to query.
      */
-    index: string;
+    index: string[];
     /**
      * Value exposed when a search is in progress.
      */
@@ -130,12 +135,11 @@ export declare interface SearchcraftProviderContext {
     /**
      * Function for searching that requires search mode and search type.
      */
-    search: <T>(query: string, mode: 'fuzzy' | 'normal') => Promise<T[] | null>;
-    searchResult?: {
-        count: number;
-        hits: SearchcraftDocument[];
-        time_taken: number;
-    } | null;
+    search: (query: string, mode: 'fuzzy' | 'normal') => void;
+    /**
+     * Object that is returned from the Searchcraft API when a search request has resolved
+     */
+    searchResults?: SearchResult | SearchError | null;
 }
 
 export declare const useSearchcraft: () => SearchcraftProviderContext;