@instruments/materialgraph 0.6.0 → 0.7.0

package/spec-types.d.ts

@@ -11,12 +11,21 @@
  * class, but with an EPD on record" reaches for a NAMED, typed criterion instead
  * of hand-assembling a magic `attribute:value` string.
  *
- * These criteria drive two operations equally:
- * - `client.search({ filters: [...] })` — spec gates layered onto a ranked
- *   (colour / visual / lexical) search.
- * - `client.bySpec(...)` — the value-anchored, spec-only primitive, which takes
+ * These criteria drive two operations equally, and choosing between them IS the
+ * routing decision:
+ * - `client.search({ filters: [...] })` — spec gates layered onto a RANKED
+ *   (colour / visual / lexical) search. Reach for it when relevance still
+ *   matters: "something like this seed, but Class A".
+ * - `client.bySpec(...)` — the value-anchored, SPEC-ONLY primitive, which takes
  *   the same criteria as `attribute:value` strings (build them with the helpers
- *   in `./specifications`).
+ *   in `./specifications`). Reach for it when the spec is the whole question and
+ *   ranking would be noise.
+ *
+ * Discover the tokens before you spend them: `client.specificationFacets()` for
+ * what is facetable at all, `client.attributeValues()` for one attribute's
+ * values, `client.resolveAttribute()` / `client.resolveAttributeValue()` to turn
+ * a phrase into a canonical pair. A hand-guessed token returns an honest empty
+ * answer, which is the hardest kind of bug to see.
  */
 /**
  * The virtual attribute id that matches a certification PROGRAMME wherever it

package/spec-types.js

@@ -11,12 +11,21 @@
  * class, but with an EPD on record" reaches for a NAMED, typed criterion instead
  * of hand-assembling a magic `attribute:value` string.
  *
- * These criteria drive two operations equally:
- * - `client.search({ filters: [...] })` — spec gates layered onto a ranked
- *   (colour / visual / lexical) search.
- * - `client.bySpec(...)` — the value-anchored, spec-only primitive, which takes
+ * These criteria drive two operations equally, and choosing between them IS the
+ * routing decision:
+ * - `client.search({ filters: [...] })` — spec gates layered onto a RANKED
+ *   (colour / visual / lexical) search. Reach for it when relevance still
+ *   matters: "something like this seed, but Class A".
+ * - `client.bySpec(...)` — the value-anchored, SPEC-ONLY primitive, which takes
  *   the same criteria as `attribute:value` strings (build them with the helpers
- *   in `./specifications`).
+ *   in `./specifications`). Reach for it when the spec is the whole question and
+ *   ranking would be noise.
+ *
+ * Discover the tokens before you spend them: `client.specificationFacets()` for
+ * what is facetable at all, `client.attributeValues()` for one attribute's
+ * values, `client.resolveAttribute()` / `client.resolveAttributeValue()` to turn
+ * a phrase into a canonical pair. A hand-guessed token returns an honest empty
+ * answer, which is the hardest kind of bug to see.
  */
 /**
  * The virtual attribute id that matches a certification PROGRAMME wherever it

package/suggest-types.d.ts

@@ -6,6 +6,11 @@
  * Split out of `types.ts` for the repository's source-file size budget, the same
  * reason `catalog-discovery-types.ts` sits beside it; both are re-exported from
  * `types.ts`, so importers see no difference.
+ *
+ * THE LENS: entity typeahead — it ranks NAMES, not materials. `mg.search()` is
+ * what answers a committed query; `mg.suggestColour()` covers colour names and
+ * `mg.searchVocabulary()` covers attribute/value tokens. Suggestions are a page
+ * of the best matches, never a census of matching entities.
  */
 /** Which kind of entity a suggestion is — and therefore what `refId` means. */
 export type SuggestKind = "product" | "brand" | "category";
@@ -25,8 +30,12 @@ export interface Suggestion {
     brandSlug: string | null;
     brandName: string | null;
     categoryKey: string | null;
-    /** A representative variant, so a client can open a material record directly. */
+    /**
+     * A representative variant, so a client can open a material record directly.
+     * Opaque, and null when none was picked — not a product without variants.
+     */
     variantId: string | null;
+    /** Variants behind this entity IN MATERIALGRAPH — a coverage figure. */
     variantCount: number;
 }
 /** The suggest response: the query as interpreted, plus the ranked suggestions. */

package/suggest-types.js

@@ -6,6 +6,11 @@
  * Split out of `types.ts` for the repository's source-file size budget, the same
  * reason `catalog-discovery-types.ts` sits beside it; both are re-exported from
  * `types.ts`, so importers see no difference.
+ *
+ * THE LENS: entity typeahead — it ranks NAMES, not materials. `mg.search()` is
+ * what answers a committed query; `mg.suggestColour()` covers colour names and
+ * `mg.searchVocabulary()` covers attribute/value tokens. Suggestions are a page
+ * of the best matches, never a census of matching entities.
  */
 /**
  * Shape the query string for a suggest call.