@instruments/materialgraph 0.32.0 → 0.33.0

package/search-variants-types.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @module search-variants-types
+ * @description Hand-maintained mirror of `search_variants`'s (MG-2223) input
+ * and output wire shapes. The source of truth is
+ * `packages/products/src/search-variants/search-variants.ts` and
+ * `compose-conditions.ts`; this SDK has no runtime dependency on
+ * `@materialgraph/products`, so the shapes are copied here and
+ * `contract-parity.test.ts` keeps them honest.
+ */
+import type { FilterGroups, ListVariantsOutput, OptionalFilterGroups } from "./list-variants-types.js";
+/** Switches one of a previous answer's `choices`: its `handle`, and the `group` and `id` of the alternative to read it as. */
+export type SearchVariantsSelection = {
+    group: string;
+    handle: string;
+    id: string;
+};
+export type SearchVariantsInput = {
+    /** Attribute ids to project under each item's `specifications`, as `listVariants()` takes. */
+    attributes?: string[];
+    /** The previous page's `pageInfo.endCursor`. Tied to the vocabulary version the query was read against, and not a `listVariants()` cursor. */
+    cursor?: string;
+    /** 1–50; defaults to 10. */
+    limit?: number;
+    /** What to find, in plain words. 1–200 characters. */
+    query: string;
+    /** Up to eight choices to switch, from the previous answer's `choices`. */
+    selections?: SearchVariantsSelection[];
+};
+/**
+ * What became of one phrase of the query. `filter` narrowed the page,
+ * `preference` only ranked it, `not_applied` did neither and `note` says why.
+ */
+export type SearchVariantsUnderstood = {
+    applied: "filter" | "preference" | "not_applied";
+    /** The parser's condition id. */
+    id: string;
+    kind: "category" | "brand" | "term" | "number" | "colour" | "paint";
+    /** What the words were read as. */
+    label: string;
+    note?: string;
+    /** The query words it came from. */
+    text: string;
+};
+/** One reading of an ambiguous phrase. */
+export type SearchVariantsReading = {
+    group: string;
+    id: string;
+    kind: string;
+    label: string;
+};
+/** A phrase with more than one meaning: the reading used, and the others a caller may switch to by `handle`. */
+export type SearchVariantsChoice = {
+    alternatives: SearchVariantsReading[];
+    basis: string;
+    handle: string;
+    reason: string;
+    selected: SearchVariantsReading;
+    text: string;
+};
+/** The `listVariants()` page, with how the words were read beside it. */
+export type SearchVariantsOutput = ListVariantsOutput & {
+    choices?: SearchVariantsChoice[];
+    /** The `listVariants()` filters that ran: send them, with `optionalFilters` and `name`, to `listVariants()` to narrow or widen this search. */
+    filters?: FilterGroups;
+    /** The paint name looked up, as `listVariants()` takes it. */
+    name?: string;
+    /** The `listVariants()` preferences that ran. */
+    optionalFilters?: OptionalFilterGroups;
+    /** One entry per phrase the parser read, in the parser's order. */
+    understood: SearchVariantsUnderstood[];
+    /** Words nothing in the vocabulary could read. */
+    unresolved?: string[];
+};

package/search-variants-types.js

@@ -0,0 +1 @@
+export {};