@riviai/smart-sort-almatar 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +9 -8
- package/docs/from-angular.md +68 -68
- package/docs/install.md +15 -19
- package/docs/integration.md +33 -23
- package/docs/troubleshooting.md +33 -31
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -73,14 +73,15 @@ render([]);
|
|
|
73
73
|
|
|
74
74
|
## Documentation
|
|
75
75
|
|
|
76
|
-
The
|
|
76
|
+
The Smart Sort documentation, from the overview and concepts to every page below, is at
|
|
77
|
+
[partner-resources.rivi.co](https://partner-resources.rivi.co/ask-ai/overview).
|
|
77
78
|
|
|
78
|
-
1. [Install](
|
|
79
|
-
2. [Quickstart](
|
|
80
|
-
3. [Integration guide](
|
|
79
|
+
1. [Install](https://partner-resources.rivi.co/ask-ai/web/sdk/install): requirements, install, registering the elements.
|
|
80
|
+
2. [Quickstart](https://partner-resources.rivi.co/ask-ai/web/sdk/quickstart): the smallest page that shows a ranking.
|
|
81
|
+
3. [Integration guide](https://partner-resources.rivi.co/ask-ai/web/sdk/integration): the steps, with React, Vue, Svelte, Angular and
|
|
81
82
|
plain JavaScript examples.
|
|
82
|
-
4. [SDK reference](
|
|
83
|
+
4. [SDK reference](https://partner-resources.rivi.co/ask-ai/web/sdk/reference): every element, property, event and type, what Smart Sort
|
|
83
84
|
does on its own, timings, tokens and strings.
|
|
84
|
-
5. [Styling guide](
|
|
85
|
-
6. [Troubleshooting](
|
|
86
|
-
7. [From Angular](
|
|
85
|
+
5. [Styling guide](https://partner-resources.rivi.co/ask-ai/web/sdk/styling): tokens, parts, language and direction.
|
|
86
|
+
6. [Troubleshooting](https://partner-resources.rivi.co/ask-ai/web/sdk/troubleshooting): symptoms, errors and console messages.
|
|
87
|
+
7. [From Angular](https://partner-resources.rivi.co/ask-ai/web/sdk/from-angular): moving from the legacy Angular SDK.
|
package/docs/from-angular.md
CHANGED
|
@@ -12,59 +12,59 @@ connection to manage.
|
|
|
12
12
|
|
|
13
13
|
## 1. Swap the package
|
|
14
14
|
|
|
15
|
-
| Angular SDK
|
|
16
|
-
|
|
|
17
|
-
| `npm install @riviai/riviai-ui-angular-sdk`
|
|
18
|
-
| SDK stylesheet in `angular.json` `styles`, Tailwind CSS | Remove both. The elements carry your theme in shadow DOM ([Styling guide](styling.md))
|
|
19
|
-
| `provideHttpClient()` for the SDK
|
|
20
|
-
| `RIVIAI_CONFIG` provider
|
|
21
|
-
| `providers: [RiviaiProviderService]`
|
|
22
|
-
| `imports: [AskAIComponent, SearchChipsComponent, …]`
|
|
15
|
+
| Angular SDK | Now |
|
|
16
|
+
| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
|
|
17
|
+
| `npm install @riviai/riviai-ui-angular-sdk` | `npm install @riviai/smart-sort-almatar` ([Install](install.md)) |
|
|
18
|
+
| SDK stylesheet in `angular.json` `styles`, Tailwind CSS | Remove both. The elements carry your theme in shadow DOM ([Styling guide](styling.md)) |
|
|
19
|
+
| `provideHttpClient()` for the SDK | Not needed: the elements make their own requests |
|
|
20
|
+
| `RIVIAI_CONFIG` provider | Remove it. The package has the gateway address, token and tenant built in (see [Configuration](#2-move-the-configuration)) |
|
|
21
|
+
| `providers: [RiviaiProviderService]` | Remove it |
|
|
22
|
+
| `imports: [AskAIComponent, SearchChipsComponent, …]` | `imports: [RIVI_SMART_SORT]` and `schemas: [CUSTOM_ELEMENTS_SCHEMA]`, from `@riviai/smart-sort-almatar/angular` |
|
|
23
23
|
|
|
24
24
|
## 2. Move the configuration
|
|
25
25
|
|
|
26
|
-
| `RiviaiConfig` field
|
|
27
|
-
|
|
|
28
|
-
| `baseUrl`
|
|
29
|
-
| `authToken`
|
|
30
|
-
| `tenantName`, `tenantTier` | Built into the package
|
|
31
|
-
| `metadata`
|
|
32
|
-
| `explainAiDebounceMs`
|
|
26
|
+
| `RiviaiConfig` field | Now |
|
|
27
|
+
| -------------------------- | -------------------------------------------------------------------------------------------------------------------- |
|
|
28
|
+
| `baseUrl` | Built into the package, per environment. Pick one with `env="production"` or `env="staging"` |
|
|
29
|
+
| `authToken` | Built into the package. To supply your own, set [`auth`](reference.md#rivi-smart-sort) to a function that returns it |
|
|
30
|
+
| `tenantName`, `tenantTier` | Built into the package |
|
|
31
|
+
| `metadata` | The `metadata` property, an object sent as a header (keep it ASCII) |
|
|
32
|
+
| `explainAiDebounceMs` | Fixed at 500 ms ([Timing and limits](reference.md#timing-and-limits)) |
|
|
33
33
|
|
|
34
34
|
## 3. Replace the search parameters
|
|
35
35
|
|
|
36
36
|
`FilterSearchParams` becomes [`RiviSearch`](reference.md#types), set as the `search` property.
|
|
37
37
|
`filter_query` is gone: the user types the query into `<rivi-sort-input>`.
|
|
38
38
|
|
|
39
|
-
| `FilterSearchParams`
|
|
40
|
-
|
|
|
41
|
-
| `search_id`
|
|
42
|
-
| `query_type: 'flight' \| 'hotel'`
|
|
43
|
-
| `is_round: true` with `return_date`
|
|
44
|
-
| `is_round: false`
|
|
45
|
-
| `origin`, `destination`
|
|
46
|
-
| `departure_date: '2025-05-23T18:30:00.000Z'`
|
|
47
|
-
| `cabin_type: 'Economy'`
|
|
48
|
-
| `adults`, `children`, `infant` (or `adult`, `child`) | `pax: { adults, children, infants }` (hotels: `pax: { adults, children }`)
|
|
49
|
-
| `checkin`, `checkout`, `rooms`
|
|
50
|
-
| `currency`
|
|
51
|
-
| `language`
|
|
52
|
-
| `user_persona`
|
|
39
|
+
| `FilterSearchParams` | `RiviSearch` |
|
|
40
|
+
| ---------------------------------------------------- | ------------------------------------------------------------------------------------ |
|
|
41
|
+
| `search_id` | `searchId`. Every new search needs a new one |
|
|
42
|
+
| `query_type: 'flight' \| 'hotel'` | `product: 'flight' \| 'hotel'` |
|
|
43
|
+
| `is_round: true` with `return_date` | `tripType: 'round'` with `returnDate` |
|
|
44
|
+
| `is_round: false` | `tripType: 'oneway'` (hotels: always `'oneway'`) |
|
|
45
|
+
| `origin`, `destination` | `origin`, `destination` |
|
|
46
|
+
| `departure_date: '2025-05-23T18:30:00.000Z'` | `departureDate: '2025-05-23'` (`YYYY-MM-DD`; Smart Sort converts it for the gateway) |
|
|
47
|
+
| `cabin_type: 'Economy'` | `cabin: 'economy' \| 'premium' \| 'business' \| 'first'` |
|
|
48
|
+
| `adults`, `children`, `infant` (or `adult`, `child`) | `pax: { adults, children, infants }` (hotels: `pax: { adults, children }`) |
|
|
49
|
+
| `checkin`, `checkout`, `rooms` | `checkin`, `checkout` (`YYYY-MM-DD`), `rooms` |
|
|
50
|
+
| `currency` | The `currency` attribute on `<rivi-smart-sort>` |
|
|
51
|
+
| `language` | The `locale` attribute (`en` or `ar`) |
|
|
52
|
+
| `user_persona` | No equivalent |
|
|
53
53
|
|
|
54
54
|
## 4. Replace the components
|
|
55
55
|
|
|
56
56
|
Put every element inside one `<rivi-smart-sort>` and keep it mounted while the user changes tabs
|
|
57
57
|
or filters.
|
|
58
58
|
|
|
59
|
-
| Angular SDK
|
|
60
|
-
|
|
|
61
|
-
| `<riviai-ask-ai [searchId] [searchParams]>`
|
|
62
|
-
| `<riviai-search-chips>`
|
|
63
|
-
| `<riviai-explain-ai-banner>`
|
|
64
|
-
| `<riviai-search-results>`
|
|
65
|
-
| `<riviai-sort-by-best [searchId] [queryType] [isRound]>` | No button. Setting `search` requests the Best order; set `sort` to `'best'` on your Best tab and `'other'` on the rest
|
|
66
|
-
| `<riviai-clear-filters>`
|
|
67
|
-
| —
|
|
59
|
+
| Angular SDK | Now |
|
|
60
|
+
| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
|
61
|
+
| `<riviai-ask-ai [searchId] [searchParams]>` | `<rivi-sort-input>`, inside `<rivi-smart-sort [search]="search">` |
|
|
62
|
+
| `<riviai-search-chips>` | `<rivi-chips>` |
|
|
63
|
+
| `<riviai-explain-ai-banner>` | `<rivi-explain>`. It also shows errors, parameter-change notices and hidden matches |
|
|
64
|
+
| `<riviai-search-results>` | Your own result list, reordered on `rivi-ranking`. Put `<rivi-match-badge result-id="…">` on each card in place of `allPreferencesMet` |
|
|
65
|
+
| `<riviai-sort-by-best [searchId] [queryType] [isRound]>` | No button. Setting `search` requests the Best order; set `sort` to `'best'` on your Best tab and `'other'` on the rest |
|
|
66
|
+
| `<riviai-clear-filters>` | The "Clear all" button in `<rivi-chips>` |
|
|
67
|
+
| — | New: `<rivi-spotlight>`, `<rivi-best-info>` and `<rivi-prompt>` ([Elements](reference.md#elements)) |
|
|
68
68
|
|
|
69
69
|
### Results you rendered with `<riviai-search-results>`
|
|
70
70
|
|
|
@@ -75,44 +75,44 @@ apply `ranking` to them.
|
|
|
75
75
|
|
|
76
76
|
### Inputs and templates
|
|
77
77
|
|
|
78
|
-
| Angular SDK input
|
|
79
|
-
|
|
|
80
|
-
| `maxInputLength`
|
|
81
|
-
| `placeholder`, `buttonText`, `loadingText` (ask)
|
|
82
|
-
| `errorText`, `timeoutText`
|
|
83
|
-
| `loadingText` (banner)
|
|
84
|
-
| `buttonText`, `loadingText` (clear filters)
|
|
85
|
-
| `containerClass`, `inputClass`, `buttonClass`, `chipClass`, `errorClass`, `iconClass`, `textClass`…
|
|
86
|
-
| `customIconTemplate` (banner)
|
|
78
|
+
| Angular SDK input | Now |
|
|
79
|
+
| ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
|
|
80
|
+
| `maxInputLength` | Fixed at 500 characters |
|
|
81
|
+
| `placeholder`, `buttonText`, `loadingText` (ask) | [`strings`](styling.md#language-and-direction): `sortInput.placeholder`, `sortInput.submit`, `sortInput.loading` |
|
|
82
|
+
| `errorText`, `timeoutText` | `strings`: `error.server`, `error.timeout` (and the other [`error.*` keys](reference.md#strings)) |
|
|
83
|
+
| `loadingText` (banner) | `strings`: `explain.loading` |
|
|
84
|
+
| `buttonText`, `loadingText` (clear filters) | `strings`: `chips.clearAll` |
|
|
85
|
+
| `containerClass`, `inputClass`, `buttonClass`, `chipClass`, `errorClass`, `iconClass`, `textClass`… | Tokens and `::part()` ([Styling guide](styling.md)) |
|
|
86
|
+
| `customIconTemplate` (banner) | The `icon` slot of `<rivi-explain>` |
|
|
87
87
|
| `customHeaderTemplate`, `customInputTemplate`, `customButtonTemplate`, `customErrorTemplate`, `customChipsTemplate`, `customTextTemplate` | No equivalent: restyle the built-in markup with tokens and parts. `<rivi-sort-input>` has `heading` and `icon` slots |
|
|
88
|
-
| `text`, `isLoading` overrides (banner), `isLoading`, `submitDisabled`
|
|
88
|
+
| `text`, `isLoading` overrides (banner), `isLoading`, `submitDisabled` | No equivalent: each element decides what to show |
|
|
89
89
|
|
|
90
90
|
## 5. Replace the service
|
|
91
91
|
|
|
92
|
-
| `RiviaiProviderService`
|
|
93
|
-
|
|
|
94
|
-
| `filterSearch(params)`
|
|
95
|
-
| `connectToSSE()`, `disconnect()`
|
|
92
|
+
| `RiviaiProviderService` | Now |
|
|
93
|
+
| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
|
|
94
|
+
| `filterSearch(params)` | The user submits in `<rivi-sort-input>`. Set `search`; there is no method that submits a query |
|
|
95
|
+
| `connectToSSE()`, `disconnect()` | Automatic. Removing `<rivi-smart-sort>` ends the session |
|
|
96
96
|
| `configureSSERetry()`, `reconnectSSE()`, `isSSEConnected()`, `connectionStatus$`, `checkConnectionHealth()` | Fixed reconnect policy ([Timing and limits](reference.md#timing-and-limits)); a lost stream shows an error with Try again |
|
|
97
|
-
| `searchResults$`
|
|
98
|
-
| `activeChips$`, `addChip()`, `removeChip()`
|
|
99
|
-
| `clearAllChips()`, `clearNotification$`
|
|
100
|
-
| `sortByBest()`
|
|
101
|
-
| `explainAiText$`, `explainAiIsLoading$`
|
|
102
|
-
| `explainAiError$`, `connectionError$`, `timeoutError$`
|
|
103
|
-
| `parameterChangeNotice$`
|
|
104
|
-
| `resetProviderState()`
|
|
105
|
-
| `isLoading$`, `setLoading()`, `currentQuery$`, `getCurrentState()`, `getCurrentSearchId()`
|
|
97
|
+
| `searchResults$` | `rivi-ranking` |
|
|
98
|
+
| `activeChips$`, `addChip()`, `removeChip()` | Chips come only from the query; the user removes them in `<rivi-chips>` |
|
|
99
|
+
| `clearAllChips()`, `clearNotification$` | "Clear all" in `<rivi-chips>`; you get `rivi-ranking-cleared` |
|
|
100
|
+
| `sortByBest()` | Automatic: setting `search` requests the Best order, and returning to Best restores it |
|
|
101
|
+
| `explainAiText$`, `explainAiIsLoading$` | Shown by `<rivi-explain>` |
|
|
102
|
+
| `explainAiError$`, `connectionError$`, `timeoutError$` | [`rivi-error`](reference.md#rivi-error) (`kind: 'timeout'` for timeouts). The user already sees it |
|
|
103
|
+
| `parameterChangeNotice$` | Shown by `<rivi-explain>` |
|
|
104
|
+
| `resetProviderState()` | Set `search` with a new `searchId` |
|
|
105
|
+
| `isLoading$`, `setLoading()`, `currentQuery$`, `getCurrentState()`, `getCurrentSearchId()` | No equivalent |
|
|
106
106
|
|
|
107
107
|
### Outputs
|
|
108
108
|
|
|
109
|
-
| Angular SDK output
|
|
110
|
-
|
|
|
111
|
-
| `(resultsUpdated)` on `riviai-ask-ai` | `(rivi-ranking)` on `<rivi-smart-sort>`
|
|
112
|
-
| `(errorOccurred)`
|
|
113
|
-
| `(sortComplete)`
|
|
114
|
-
| `(clearComplete)`
|
|
115
|
-
| `(afterSubmit)`
|
|
109
|
+
| Angular SDK output | Now |
|
|
110
|
+
| ------------------------------------- | -------------------------------------------------------- |
|
|
111
|
+
| `(resultsUpdated)` on `riviai-ask-ai` | `(rivi-ranking)` on `<rivi-smart-sort>` |
|
|
112
|
+
| `(errorOccurred)` | `(rivi-error)` |
|
|
113
|
+
| `(sortComplete)` | `(rivi-ranking)` with `$event.detail.status === 'final'` |
|
|
114
|
+
| `(clearComplete)` | `(rivi-ranking-cleared)` |
|
|
115
|
+
| `(afterSubmit)` | No equivalent |
|
|
116
116
|
|
|
117
117
|
## 6. What behaves differently
|
|
118
118
|
|
package/docs/install.md
CHANGED
|
@@ -21,17 +21,13 @@ in each, so everything in these docs applies to yours.
|
|
|
21
21
|
constructable stylesheets (Safari before 16.4), a strict `style-src` also needs
|
|
22
22
|
`window.litNonce` set to your nonce.
|
|
23
23
|
|
|
24
|
-
## 1.
|
|
25
|
-
|
|
26
|
-
The package is on the public npm registry, so no registry setup or login is needed.
|
|
27
|
-
|
|
28
|
-
## 2. Install
|
|
24
|
+
## 1. Install
|
|
29
25
|
|
|
30
26
|
```bash
|
|
31
27
|
npm install @riviai/smart-sort-almatar # or: pnpm add / yarn add
|
|
32
28
|
```
|
|
33
29
|
|
|
34
|
-
##
|
|
30
|
+
## 2. Register the elements
|
|
35
31
|
|
|
36
32
|
Import the package once, before the elements render:
|
|
37
33
|
|
|
@@ -39,11 +35,11 @@ Import the package once, before the elements render:
|
|
|
39
35
|
import '@riviai/smart-sort-almatar';
|
|
40
36
|
```
|
|
41
37
|
|
|
42
|
-
| App
|
|
43
|
-
|
|
|
38
|
+
| App | Where to import |
|
|
39
|
+
| ------------------------------------ | ---------------------------------------------------------------------- |
|
|
44
40
|
| Plain JavaScript, React, Vue, Svelte | Your entry file, or the top of the component that renders the elements |
|
|
45
|
-
| Next.js
|
|
46
|
-
| Angular
|
|
41
|
+
| Next.js | The client component (`'use client'`) that renders the elements |
|
|
42
|
+
| Angular | Nothing extra: `@riviai/smart-sort-almatar/angular` registers them |
|
|
47
43
|
|
|
48
44
|
The import is safe during server-side rendering: nothing happens until it runs in a browser.
|
|
49
45
|
|
|
@@ -54,7 +50,7 @@ module (the language files are in `standalone/chunks/`):
|
|
|
54
50
|
<script type="module" src="/vendor/smart-sort/standalone/index.js"></script>
|
|
55
51
|
```
|
|
56
52
|
|
|
57
|
-
##
|
|
53
|
+
## 3. Pick the environment
|
|
58
54
|
|
|
59
55
|
The package holds a gateway address and token for production and for staging. Production is the
|
|
60
56
|
default; set `env="staging"` on `<rivi-smart-sort>` while you test against Rivi's staging gateway:
|
|
@@ -63,20 +59,20 @@ default; set `env="staging"` on `<rivi-smart-sort>` while you test against Rivi'
|
|
|
63
59
|
<rivi-smart-sort env="staging"></rivi-smart-sort>
|
|
64
60
|
```
|
|
65
61
|
|
|
66
|
-
##
|
|
62
|
+
## 4. Check it works
|
|
67
63
|
|
|
68
64
|
In the browser console on your page, `customElements.get('rivi-smart-sort')` returns a class, not
|
|
69
65
|
`undefined`. If it is `undefined`, the import has not run on that page.
|
|
70
66
|
|
|
71
67
|
## What's in the package
|
|
72
68
|
|
|
73
|
-
| Import
|
|
74
|
-
|
|
|
75
|
-
| `@riviai/smart-sort-almatar`
|
|
76
|
-
| `…/react`, `…/vue`, `…/svelte`
|
|
77
|
-
| `…/angular`
|
|
78
|
-
| `…/standalone/index.js`
|
|
79
|
-
| `…/custom-elements.json`, `…/vscode.html-custom-data.json` | Editor and tooling metadata
|
|
69
|
+
| Import | What it is |
|
|
70
|
+
| ---------------------------------------------------------- | ----------------------------------------------------- |
|
|
71
|
+
| `@riviai/smart-sort-almatar` | The elements and their TypeScript types |
|
|
72
|
+
| `…/react`, `…/vue`, `…/svelte` | Template typings for each framework |
|
|
73
|
+
| `…/angular` | Angular directives |
|
|
74
|
+
| `…/standalone/index.js` | Everything in one module, for pages without a bundler |
|
|
75
|
+
| `…/custom-elements.json`, `…/vscode.html-custom-data.json` | Editor and tooling metadata |
|
|
80
76
|
|
|
81
77
|
## Updating
|
|
82
78
|
|
package/docs/integration.md
CHANGED
|
@@ -14,15 +14,20 @@ Framework-specific code is at the [end of this page](#frameworks).
|
|
|
14
14
|
|
|
15
15
|
```html
|
|
16
16
|
<rivi-smart-sort locale="en" currency="SAR">
|
|
17
|
-
<rivi-spotlight></rivi-spotlight>
|
|
18
|
-
|
|
19
|
-
<rivi-
|
|
17
|
+
<rivi-spotlight></rivi-spotlight>
|
|
18
|
+
<!-- one-time introduction -->
|
|
19
|
+
<rivi-sort-input></rivi-sort-input>
|
|
20
|
+
<!-- the query box -->
|
|
21
|
+
<rivi-chips></rivi-chips>
|
|
22
|
+
<!-- the preferences it understood -->
|
|
20
23
|
|
|
21
24
|
<button data-tab="best">Best</button>
|
|
22
|
-
<rivi-best-info></rivi-best-info>
|
|
25
|
+
<rivi-best-info></rivi-best-info>
|
|
26
|
+
<!-- "what is Best?", next to the tab, not inside it -->
|
|
23
27
|
<button data-tab="cheapest">Cheapest</button>
|
|
24
28
|
|
|
25
|
-
<rivi-explain></rivi-explain>
|
|
29
|
+
<rivi-explain></rivi-explain>
|
|
30
|
+
<!-- why the list is in this order -->
|
|
26
31
|
|
|
27
32
|
<ul id="results">
|
|
28
33
|
<li>… your card … <rivi-match-badge result-id="IT-1"></rivi-match-badge></li>
|
|
@@ -59,14 +64,14 @@ rivi.pool = { size: results.length, complete: !loading }; // if results load in
|
|
|
59
64
|
rivi.visible = shown.map(r => r.id); // optional: ids you render after filters and paging
|
|
60
65
|
```
|
|
61
66
|
|
|
62
|
-
| Property
|
|
63
|
-
|
|
|
64
|
-
| `search`
|
|
65
|
-
| `sort`
|
|
66
|
-
| `filters` | The filters the user applied. Sent with the next query; a change alone sends nothing
|
|
67
|
-
| `pool`
|
|
68
|
-
| `visible` | The ids you actually render. Lets Smart Sort point out top matches the user can't see
|
|
69
|
-
| `stage`
|
|
67
|
+
| Property | Set it to | Needed |
|
|
68
|
+
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------- |
|
|
69
|
+
| `search` | The current search. **Every new search needs a new `searchId`**: the id Rivi receives your results under, or a new `crypto.randomUUID()` if Rivi runs the search for you | Always |
|
|
70
|
+
| `sort` | `'best'` on your Best tab, `'other'` on every other tab | If you have tabs |
|
|
71
|
+
| `filters` | The filters the user applied. Sent with the next query; a change alone sends nothing | If you have filters |
|
|
72
|
+
| `pool` | How many results have loaded (before your filters) and whether loading is done. Reset to `{ size: 0, complete: false }` with each new search | If results load in chunks |
|
|
73
|
+
| `visible` | The ids you actually render. Lets Smart Sort point out top matches the user can't see | Optional |
|
|
74
|
+
| `stage` | `'onward'` or `'return'` | Round trips shown one leg at a time |
|
|
70
75
|
|
|
71
76
|
Setting a value equal to the current one does nothing, so it's fine to set everything on every
|
|
72
77
|
render.
|
|
@@ -119,10 +124,15 @@ export function applyRanking<T>(
|
|
|
119
124
|
|
|
120
125
|
```js
|
|
121
126
|
// The query was cleared: show your own order.
|
|
122
|
-
rivi.addEventListener('rivi-ranking-cleared', () => {
|
|
127
|
+
rivi.addEventListener('rivi-ranking-cleared', () => {
|
|
128
|
+
ranking = [];
|
|
129
|
+
render();
|
|
130
|
+
});
|
|
123
131
|
|
|
124
132
|
// Select the Best tab: after a query from another tab, or a cancelled sort change.
|
|
125
|
-
rivi.addEventListener('rivi-sort-change', e => {
|
|
133
|
+
rivi.addEventListener('rivi-sort-change', e => {
|
|
134
|
+
if (e.detail.sort === 'best') selectTab('best');
|
|
135
|
+
});
|
|
126
136
|
|
|
127
137
|
// The user asked to see top matches you are not showing (needs `visible`).
|
|
128
138
|
rivi.addEventListener('rivi-show-hidden', () => clearFilters());
|
|
@@ -145,14 +155,14 @@ The query box, chips, explanation and the "clear your query?" dialog need no cod
|
|
|
145
155
|
|
|
146
156
|
## Frameworks
|
|
147
157
|
|
|
148
|
-
|
|
|
149
|
-
|
|
|
150
|
-
| HTML / JS | `el.search = …`
|
|
151
|
-
| React 19
|
|
152
|
-
| React 18
|
|
153
|
-
| Vue 3
|
|
154
|
-
| Svelte 5
|
|
155
|
-
| Angular
|
|
158
|
+
| | Pass an object | Listen for an event | Typings |
|
|
159
|
+
| --------- | ------------------------ | -------------------------------------------------- | ----------------------------------------------------------- |
|
|
160
|
+
| HTML / JS | `el.search = …` | `el.addEventListener('rivi-ranking', …)` | built in |
|
|
161
|
+
| React 19 | `search={search}` | `onrivi-ranking={…}` | `import type {} from '@riviai/smart-sort-almatar/react'` |
|
|
162
|
+
| React 18 | `ref.current.search = …` | `ref.current.addEventListener('rivi-ranking', …)` | `import type {} from '@riviai/smart-sort-almatar/react'` |
|
|
163
|
+
| Vue 3 | `:search="search"` | `@rivi-ranking="…"` | `import type {} from '@riviai/smart-sort-almatar/vue'` |
|
|
164
|
+
| Svelte 5 | `search={search}` | `onrivi-ranking={…}` (Svelte 4: `on:rivi-ranking`) | `import type {} from '@riviai/smart-sort-almatar/svelte'` |
|
|
165
|
+
| Angular | `[search]="search"` | `(rivi-ranking)="…"` | the `/angular` directives |
|
|
156
166
|
|
|
157
167
|
Each framework's example below is type-checked in the SDK's tests.
|
|
158
168
|
|
package/docs/troubleshooting.md
CHANGED
|
@@ -5,16 +5,16 @@ message in the console. Set up first with the [Integration guide](integration.md
|
|
|
5
5
|
|
|
6
6
|
## Symptoms
|
|
7
7
|
|
|
8
|
-
| Symptom
|
|
9
|
-
|
|
|
10
|
-
| Nothing renders
|
|
11
|
-
| An attribute reads `"[object Object]"`
|
|
12
|
-
| The list never reorders
|
|
13
|
-
| Results disappear
|
|
14
|
-
| The query is lost when switching tabs
|
|
15
|
-
| After cancelling the dialog it comes back | Your Best tab isn't selected again
|
|
16
|
-
| Your content turns left-to-right
|
|
17
|
-
| Every query says "unavailable"
|
|
8
|
+
| Symptom | Cause | Fix |
|
|
9
|
+
| ----------------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
10
|
+
| Nothing renders | The package isn't imported, an element is outside `<rivi-smart-sort>`, or `search` isn't set | Import the package, put the elements inside `<rivi-smart-sort>`, and set `search`. Multi-city searches and the return leg show nothing by design |
|
|
11
|
+
| An attribute reads `"[object Object]"` | The object was set before the elements were registered, so it became an attribute | Import the package before the first render (Vue: add `isCustomElement`; React 18: set it through a ref) |
|
|
12
|
+
| The list never reorders | The ranking's ids don't match your result ids, or `sort` isn't `'best'` | Log `event.detail.ranking` and compare its ids with yours; set `sort` to `'best'` on your Best tab |
|
|
13
|
+
| Results disappear | Your list keeps only the ranked results | Keep results the ranking doesn't mention, after the ranked ones |
|
|
14
|
+
| The query is lost when switching tabs | `<rivi-smart-sort>` is removed and added again per tab, which ends the session | Keep `<rivi-smart-sort>` mounted on every tab |
|
|
15
|
+
| After cancelling the dialog it comes back | Your Best tab isn't selected again | Handle `rivi-sort-change` and select Best |
|
|
16
|
+
| Your content turns left-to-right | `dir` follows `locale` | Set `locale="ar"`, or `dir` on `<rivi-smart-sort>` |
|
|
17
|
+
| Every query says "unavailable" | Your API key changed | Upgrade the package, or set `auth` to return the new token ([Updating](install.md#updating)) |
|
|
18
18
|
|
|
19
19
|
## Errors
|
|
20
20
|
|
|
@@ -22,32 +22,34 @@ Each failed request fires [`rivi-error`](reference.md#rivi-error) with one of th
|
|
|
22
22
|
user already sees it.
|
|
23
23
|
|
|
24
24
|
<!-- generated:errors -->
|
|
25
|
-
|
|
26
|
-
|
|
|
27
|
-
|
|
|
28
|
-
| `
|
|
29
|
-
| `timeout` | `No
|
|
30
|
-
| `
|
|
31
|
-
| `auth`
|
|
32
|
-
| `
|
|
33
|
-
| `server` |
|
|
34
|
-
| `
|
|
35
|
-
| `stream`
|
|
25
|
+
|
|
26
|
+
| `kind` | `message` | Retry button | When | What the user sees |
|
|
27
|
+
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
|
|
28
|
+
| `network` | `Network request failed` | yes | The request could not be sent or received (offline, DNS, blocked by CORS or CSP) | Connection error. Please try again. |
|
|
29
|
+
| `timeout` | `No response within 30 s` | yes | A ranking request or an explanation stream sent nothing for 30 s | Request timed out. Please try again. |
|
|
30
|
+
| `timeout` | `No ranking within 30 s` | yes | A ranking request succeeded but no ranking arrived within 30 s | Request timed out. Please try again. |
|
|
31
|
+
| `auth` | `The gateway rejected the token twice (HTTP 401). A bundled token that is rejected has been rotated: rebuild the tenant package, or set .auth to supply the new token.` | no | The gateway answered `401` twice: the bundled token was rotated | Smart sort is unavailable right now. Please try again later. |
|
|
32
|
+
| `auth` | `auth() did not return a token` | yes | Your `auth` function threw, or returned something other than a non-empty string | Smart sort is unavailable right now. Please try again later. |
|
|
33
|
+
| `server` | `HTTP <status>` | yes | The gateway answered with an error status. Retryable for `5xx` and `429`; `4xx` is not | An error occurred. Please try again. |
|
|
34
|
+
| `server` | `The ask response was not JSON` | yes | The response to a query was not JSON | An error occurred. Please try again. |
|
|
35
|
+
| `stream` | `The ranking stream failed 5 times in a row` | yes | The ranking stream failed 5 times in a row | Lost the connection to live results. Please try again. |
|
|
36
|
+
| `stream` | the gateway's text | yes | The ranking stream sent an error frame | Lost the connection to live results. Please try again. |
|
|
37
|
+
|
|
36
38
|
<!-- /generated:errors -->
|
|
37
39
|
|
|
38
40
|
"Try again" ranks again; typing dismisses the error.
|
|
39
41
|
|
|
40
42
|
## Console messages
|
|
41
43
|
|
|
42
|
-
| Message starts with
|
|
43
|
-
|
|
|
44
|
-
| `[rivi] env="…" is not production or staging`
|
|
45
|
-
| `[rivi] .filters must be plain JSON data`
|
|
46
|
-
| `[rivi] rivi-match-badge must be a descendant`
|
|
47
|
-
| `[rivi] The gateway rejected the token`
|
|
48
|
-
| `[rivi] Could not load the … strings`
|
|
49
|
-
| `[rivi] base-url is honoured only in the dev build` | Remove `base-url`
|
|
50
|
-
| `[rivi] The dev build needs base-url and .auth`
|
|
51
|
-
| `[rivi] Theme token …`, `[rivi] [smart-sort] …`
|
|
44
|
+
| Message starts with | Meaning |
|
|
45
|
+
| --------------------------------------------------- | ------------------------------------------------------------------------------ |
|
|
46
|
+
| `[rivi] env="…" is not production or staging` | Use `production` or `staging` |
|
|
47
|
+
| `[rivi] .filters must be plain JSON data` | `filters` holds a function or similar; it was ignored |
|
|
48
|
+
| `[rivi] rivi-match-badge must be a descendant` | Move the badge inside `<rivi-smart-sort>` |
|
|
49
|
+
| `[rivi] The gateway rejected the token` | Your API key changed: upgrade the package |
|
|
50
|
+
| `[rivi] Could not load the … strings` | A language file failed to load (check your server serves the package's chunks) |
|
|
51
|
+
| `[rivi] base-url is honoured only in the dev build` | Remove `base-url` |
|
|
52
|
+
| `[rivi] The dev build needs base-url and .auth` | You installed Rivi's development build, not your company's package |
|
|
53
|
+
| `[rivi] Theme token …`, `[rivi] [smart-sort] …` | Unexpected data from Rivi: tell Rivi, with the `searchId` |
|
|
52
54
|
|
|
53
55
|
Elements, events and types: [SDK reference](reference.md).
|
package/package.json
CHANGED