diff --git a/README.md b/README.md index 81b36d51b..f7e10160e 100644 --- a/README.md +++ b/README.md @@ -5,15 +5,15 @@
-

UI components library for Elasticsearch: Available for React and Vue

+

UI components library for Elasticsearch, OpenSearch, Solr, MongoDB: Available for React and Vue

Read how to build an e-commerce search UI

a.) with React, or b.) with Vue

- web - vue + web + vue

Check out [Searchbox](https://opensource.appbase.io/searchbox/) if you're building search UIs for other JS frameworks, React Native or Flutter. @@ -59,22 +59,22 @@ Check out [Searchbox](https://opensource.appbase.io/searchbox/) if you're buildi ## 1. ReactiveSearch: Intro -ReactiveSearch is an Elasticsearch UI components library for React and React Native. It has 25+ components consisting of Lists, Ranges, Search UIs, Result displays and a way to bring any existing UI component into the library. +ReactiveSearch is a UI components library for React and Vue, designed to work with ReactiveSearch cloud. It has over 20 UI components consisting of Lists, Ranges, Search UIs, Result displays, AI Answer, Charts, and a way to bring an existing UI component into the library. -The library is conceptually divided into two parts: +A UI component can be used for filtering or searching on the index. For example: -1. Sensor components and -2. Actuator components. +- A [`SingleList`](https://docs.reactivesearch.io/docs/reactivesearch/react/list/singlelist/) sensor component applies an exact match filter based on the selected item. +- A [`RangeSlider`](https://docs.reactivesearch.io/docs/reactivesearch/react/range/rangeslider/) component applies a numeric range query based on the values selected from the UI. +- A [`SearchBox`](https://docs.reactivesearch.io/docs/reactivesearch/react/search/searchbox/) component applies a suggestions and search query based on the search term typed by the user. -Each sensor component is built for applying a specific filter on the data. For example: +UI components can be used together (`react` prop allows configuring this on a per-component level) and render the matching results via a result display UI component. -- A [`SingleList`](https://docs.appbase.io/docs/reactivesearch/v3/list/singlelist/) sensor component applies an exact match filter based on the selected item. -- A [`RangeSlider`](https://docs.appbase.io/docs/reactivesearch/v3/range/rangeslider/) component applies a numeric range query based on the values selected from the UI. -- A [`DataSearch`](https://docs.appbase.io/docs/reactivesearch/v3/search/datasearch/) component applies a suggestions and search query based on the search term typed by the user. +**ReactiveSearch** supports the following built-in display components for displaying results (aka hits): +1. [ReactiveList](https://docs.reactivesearch.io/docs/reactivesearch/react/result/reactivelist/) - ReactiveList supports list and card display formats as well as allows custom rendering at both item and component level, +2. [ReactiveMap](https://docs.reactivesearch.io/docs/reactivesearch/react/map/reactivegooglemap/) - ReactiveMap offers choice of Google Maps and OpenStreetMaps for map rendering, +3. [AIAnswer](https://docs.reactivesearch.io/docs/reactivesearch/react/search/aianswer/) - AIAnswer offers Retrieval Augmented Generation (RAG) via search engine and OpenAI models, and +4. [ReactiveChart](https://docs.reactivesearch.io/docs/reactivesearch/react/chart/reactivechart/) - Powered by Apache E-Charts, ReactiveChart offers 5 built-in chart types: pie, bar, histogram, line, scatter, and additional charts in the Apache E-Charts format. ReactiveChart is only supported for React at this time. -Sensor components can be configured to create a combined query context and render the matching results via an actuator component. - -**ReactiveSearch** primarily comes with two actuators: `ResultCard` and `ResultList`. ResultCard displays the results in a card interface whereas ResultList displays them in a list. Both provide built-in support for pagination and infinite scroll views. Besides these, the library also provides low level actuators (ReactiveComponent and ReactiveList) to render in a more customized fashion.
@@ -82,31 +82,25 @@ Sensor components can be configured to create a combined query context and rende ### Design -- The sensor / actuator design pattern allows creating complex UIs where any number of sensors can be chained together to reactively update an actuator (or even multiple actuators). -- The library handles the transformation of the UI interactions into database queries. You only need to include the components and associate each with a DB field. -- Built in live updates - Actuators can be set to update results even when the underlying data changes in the DB. -- Comes with scoped and styled components. Doesn't require any external CSS library import, comes with className and innerClass support. -- Is themable via [`ThemeProvider`](https://docs.appbase.io/docs/reactivesearch/v3/theming/overview/). +- The UI components's query generation and ability to `react` allows for creating complex UIs where a number of UI components can reactively update based on user interaction. +- The library handles the transformation of the UI interactions into search intent queries. +- Comes with scoped and styled components with `className`` and `innerClass` prop support. +- Is themable via [`ThemeProvider`](https://docs.reactivesearch.io/docs/reactivesearch/react/theming/overview/). ### Ease of Use -- One step installation with [npm i @appbaseio/reactivesearch](https://docs.appbase.io/docs/reactivesearch/v3/overview/quickstart/), -- A UMD build that works directly in the browser. Installation steps [here](https://docs.appbase.io/docs/reactivesearch/v3/overview/quickstart/#step-5-reactivesearch-as-umd), +- One step installation with [npm i @appbaseio/reactivesearch](https://docs.reactivesearch.io/docs/reactivesearch/react/overview/quickstart/), - Styled and scoped components that can be easily extended, -- See the [reactivesearch starter app](https://github.com/appbaseio-apps/reactivesearch-starter-app). +- See the [reactivesearch starter app](https://github.com/awesome-reactivesearch/reactivesearch-starter-app). -### 🆕 ReactiveSearch API: Secure your ElasticSearch Queries +### 🆕 ReactiveSearch API: Secure your Search Queries -Based on a popular request, we have implemented support for a declarative API based on ReactiveSearch. The API is called [ReactiveSearch API](https://docs.appbase.io/docs/search/reactivesearch-api/). It moves the query DSL generation logic to a backend system (an appbase.io service) instead of exposing it directly on the client-side. By strictly enabling only ReactiveSearch API use, you can also prevent script injections. +Starting ReactiveSearch v4 (current major release), the library only sends the search intent, specification for this is here - [ReactiveSearch API ref](https://docs.reactivesearch.io/docs/search/reactivesearch-api/). Based on the choice of search engine you configure in ReactiveSearch cloud, the search query DSL is then generated by ReactiveSearch cloud. This approach is both more secure as well as allows transfering the search business logic on the server-side. -The main advantages of using it over the ElasticSearch Query DSL are: -- Query generation happens on the server-side - addressing the primary security concern around query injection. -- Easy recording of analytics events for search and clicks. [Read more](https://docs.appbase.io/docs/reactivesearch/v3/advanced/analytics/) -- Application of query rules and functions for search queries. [Read more](https://docs.appbase.io/docs/search/rules/) -Using ReactiveSearch API instead of ElasticSearch's query DSL is an opt-in feature. You need to set the `enableAppbase` prop as `true` in your `ReactiveBase` component. This assumes that you are using appbase.io for your backend. +If you're using ReactiveSearch v3 (last major release), use of ReactiveSearch API over ElasticSearch's query DSL is an opt-in feature. You need to set the `enableAppbase` prop as `true` in your `ReactiveBase` component. This assumes that you are using appbase.io for your backend. -We recommend checking out this [KitchenSink App](https://codesandbox.io/s/eager-sky-cnt66) that demonstrates the use of the `ReactiveSearch API` for all the ReactiveSearch components. +We recommend checking out this [KitchenSink App](https://codesandbox.io/s/loving-margulis-p8rd6z) that demonstrates the use of the `ReactiveSearch API` for all the ReactiveSearch components. [⬆ Back to Top](#------reactive-search--) @@ -114,7 +108,7 @@ We recommend checking out this [KitchenSink App](https://codesandbox.io/s/eager- ## 3. Component Playground -Try the live component playground at [playground](https://opensource.appbase.io/playground/?filterBy=ReactiveSearch&selectedKind=Range%20components%2FRatingsFilter). Look out for the knobs section in the playground part of the stories to tweak each prop and see the effects. +Try the live component playground stories at [playground](https://opensource.appbase.io/playground/?filterBy=ReactiveSearch&selectedKind=Range%20components%2FRatingsFilter). Look out for the knobs section in the playground part of the stories to tweak each prop and see the effects.
@@ -124,20 +118,13 @@ A set of live demos inspired by real world apps, built with ReactiveSearch. ### Web -- [demos/airbeds](https://opensource.appbase.io/reactivesearch/demos/airbeds/) - An airbnb-like booking search experience. -- [demos/technews](https://opensource.appbase.io/reactivesearch/demos/technews/) - A full-text search app on the Hacker News dataset. -- [demos/gitxplore](https://opensource.appbase.io/reactivesearch/demos/gitxplore/) - Explore all the popular Github repositories. -- [demos/productsearch](https://opensource.appbase.io/reactivesearch/demos/producthunt/) - Filtered feed of products based on a small Product Hunt dataset. -- [demos/booksearch](https://opensource.appbase.io/reactivesearch/demos/goodbooks/) - An book search app based on a goodbooks dataset. -- [demos/ecommerce](https://opensource.appbase.io/reactivesearch/demos/ecommerce/) - An e-commerce car store app. - -You can check all of them on the [examples section of website](https://opensource.appbase.io/reactivesearch/#examples). +- [demos/booksearch](https://opensource.appbase.io/reactivesearch/demos/goodbooks/) - An book search app based on a goodbooks dataset. +- [BookSearch with Antd](https://antd-booksearch.reactiveapps.io/) - A demo showing use of Ant design's theming and UI components with ReactiveSearch +- [E-commerce Movie Search](https://movies-ecommerce-demo.reactiveapps.io/) - A demo showing an e-commerce movie search UI +- [Dashboard search and charts](https://dashboard-app.reactiveapps.io/) - A demo with user authentication: login, search and charts UIs. -### Mobile +You can check all of them on the [examples section of website](https://opensource.reactivesearch.io/#examples). -- [Booksearch on Play Store](https://play.google.com/store/apps/details?id=com.booksnative): A booksearch app showing a searchable collection of over 10k books built with ReactiveSearch. Also available as a snack. -- [Gitxplore on Play Store](https://play.google.com/store/apps/details?id=com.appbaseio.gitxplore): A Github repository explorer app to search over the 25k+ most popular github repos. -- [ReactiveTodos on App Store](https://itunes.apple.com/us/app/reactivetodos/id1347926945?mt=8): A shared collaborative to-do list app to showcase the capability of Reactivesearch. [⬆ Back to Top](#------reactive-search--) @@ -149,7 +136,7 @@ Here, we share how `ReactiveSearch` compares with other projects that have simil | **#** | **ReactiveSearch** | **SearchKit** | **InstantSearch** | | -----------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------: | -| **Backend** | Any Elasticsearch index hosted on any Elasticsearch cluster. | Any Elasticsearch index hosted on any Elasticsearch cluster. | Custom-built for Algolia, a proprietary search engine. | +| **Backend** | Elasticsearch, OpenSearch, Solr, MongoDB, OpenAI | Any Elasticsearch index hosted on any Elasticsearch cluster. | Custom-built for Algolia, a proprietary search engine. | | **Development** | Actively developed and maintained. | Active issue responses, some development and maintenance. | Actively developed and maintained. | | **Onboarding Experience** | Starter apps, Live interactive tutorial, getting started guide, component playground, every component has a live working demo with codesandbox. | Getting started tutorial, no live component demos, sparse reference spec for many components. | Starter apps, getting started guide, component playground. | | **Styling Support** | Styled and scoped components. No external CSS import required. Rich theming supported as React props. | CSS based styles with BEM, not scoped to components. Theming supported with SCSS. | CSS based styles, requires external style import. Theming supported by manipulating CSS. | @@ -166,7 +153,7 @@ We welcome contributions to this section. If you are building a project or you k Installing ReactiveSearch is just one command. -- If you're using reactivesearch for web +- If you're using reactivesearch for React ```javascript npm install @appbaseio/reactivesearch @@ -174,28 +161,30 @@ npm install @appbaseio/reactivesearch You can check out the quickstart guide with React [here](https://docs.reactivesearch.io/docs/reactivesearch/react/overview/quickstart/). -- If you're using reactivesearch for mobile (native) +- If you're using reactivesearch for Vue ```javascript -npm install @appbaseio/reactivesearch-native +npm install @appbaseio/reactivesearch-vue ``` -You can check out the quickstart guide with React Native [here](https://docs.appbase.io/docs/reactivesearch/native/overview/QuickStart/). +You can check out the quickstart guide with Vue [here](https://docs.reactivesearch.io/docs/reactivesearch/vue/overview/quickstart/).
## 7. Docs Manual -The official docs for the Web library are at [docs.appbase.io/docs/reactivesearch/v3](https://docs.appbase.io/docs/reactivesearch/v3/overview/quickstart/). +The official docs for the React library are at [docs.reactivesearch.io/docs/reactivesearch/react](https://docs.reactivesearch.io/docs/reactivesearch/react/overview/quickstart/). The components are divided into four sections: -- List based UI components are at [reactivesearch/v3/list](https://docs.appbase.io/docs/reactivesearch/v3/list/singlelist/). -- Range based UI components are at [reactivesearch/v3/range](https://docs.appbase.io/docs/reactivesearch/v3/range/singlerange/). -- Search UI components are at [reactivesearch/v3/search](https://docs.appbase.io/docs/reactivesearch/v3/search/datasearch/). -- Result components are at [reactivesearch/v3/result](https://docs.appbase.io/docs/reactivesearch/v3/result/reactivelist/). +- List based UI components are at [reactivesearch/react/list](https://docs.reactivesearch.io/docs/reactivesearch/react/list/singlelist/). +- Range based UI components are at [reactivesearch/react/range](https://docs.reactivesearch.io/docs/reactivesearch/react/range/singlerange/). +- Search UI components are at [reactivesearch/react/search](https://docs.reactivesearch.io/docs/reactivesearch/react/search/datasearch/). +- Result components are at [reactivesearch/react/result](https://docs.reactivesearch.io/docs/reactivesearch/react/result/reactivelist/). +- Map components are at [reactivesearch/react/map](https://docs.reactivesearch.io/docs/reactivesearch/react/map/geodistanceslider/). +- Chart components are at [reactivesearch/react/chart](https://docs.reactivesearch.io/docs/reactivesearch/react/chart/piechart/). -Docs for React Native version of the library are available at [docs.appbase.io/docs/reactivesearch/native](https://docs.appbase.io/docs/reactivesearch/native/overview/QuickStart/). +Docs for Vue version of the library are available at [docs.reactivesearch.io/docs/reactivesearch/vue](https://docs.reactivesearch.io/docs/reactivesearch/vue/overview/quickstart/). [⬆ Back to Top](#------reactive-search--) @@ -209,21 +198,16 @@ Please check the [contribution guide](.github/CONTRIBUTING.md). ## 9. Other Projects You Might Like -- [**arc**](https://github.com/appbaseio/arc) API Gateway for ElasticSearch (Out of the box Security, Rate Limit Features, Record Analytics and Request Logs). - -- [**searchbox**](https://github.com/appbaseio/searchbox) A lightweight and performance focused searchbox UI libraries to query and display results from your ElasticSearch app (aka index). - - **Vanilla JS** - (~16kB Minified + Gzipped) - - **React** - (~30kB Minified + Gzipped) - - **Vue** - (~22kB Minified + Gzipped) - -- [**dejavu**](https://github.com/appbaseio/dejavu) allows viewing raw data within an appbase.io (or Elasticsearch) app. **Soon to be released feature:** An ability to import custom data from CSV and JSON files, along with a guided walkthrough on applying data mappings. +- [**ReactiveSearch API**](https://github.com/appbaseio/reactivesearch-api) API Gateway for ElasticSearch, OpenSearch, Solr, MongoDB, OpenAI (Out of the box Security, Rate Limit Features, Record Analytics and Request Logs). -- [**mirage**](https://github.com/appbaseio/mirage) ReactiveSearch components can be extended using custom Elasticsearch queries. For those new to Elasticsearch, Mirage provides an intuitive GUI for composing queries. +- [**searchbox**](https://github.com/appbaseio/searchbox) A lightweight and performance focused searchbox UI libraries to query and display results with ReactiveSearch Cloud. + - [**Vanilla JS**](https://github.com/appbaseio/searchbox) + - [**Flutter**](https://github.com/appbaseio/flutter-searchbox) -- [**ReactiveMaps**](https://github.com/appbaseio/reactivesearch/tree/next/packages/maps) is a similar project to Reactive Search that allows building realtime maps easily. +- [**dejavu**](https://github.com/appbaseio/dejavu) Elasticsearch / OpenSearch data viewer and editor -- [**appbase-js**](https://github.com/appbaseio/appbase-js) While building search UIs is dandy with Reactive Search, you might also need to add some input forms. **appbase-js** comes in handy there. +- [**appbase-js**](https://github.com/appbaseio/appbase-js) For when you need to index data in addition to UI components [⬆ Back to Top](#------reactive-search--) - +