@instruments/materialgraph 0.5.0 → 0.6.0

package/colour-aggregate-types.d.ts

@@ -8,8 +8,12 @@
  * widened so a new server value still type-checks.
  */
 import type { OpenEnum } from "./types.js";
-/** Which taxonomy tier a colour profile's `categoryKey` names. */
-export type CategoryTier = OpenEnum<"group" | "type">;
+/**
+ * Which taxonomy tier a colour profile's `categoryKey` names — or `"merged"`,
+ * where the key is a composite over a caller-defined key set rather than a
+ * taxonomy node.
+ */
+export type CategoryTier = OpenEnum<"group" | "type" | "merged">;
 /** How the endpoint picks which colours to keep. */
 export type ColourProfileSelect = OpenEnum<"frequency" | "diverse">;
 /** One representative colour bucket of a category. */
@@ -29,6 +33,11 @@ export interface CategoryColourProfile {
     level: CategoryTier;
     name: string;
     path: string;
+    /**
+     * Under `groupBy: "merged"`, the requested keys in composite-key order, so
+     * `categoryKey` never has to be split. Absent on a single-category profile.
+     */
+    members?: string[];
     variantCount: number;
     avgLightness: number;
     avgChroma: number;
@@ -51,8 +60,11 @@ export interface CategoryColourProfilesResponse {
 export interface ColourProfilesParams {
     /** 1–8 category keys, at the tier named by `groupBy`. */
     productTypeIds: readonly string[];
-    /** `"group"` merges each group's leaf product types into one palette. */
-    groupBy?: "group" | "type";
+    /**
+     * `"group"` merges each group's leaf product types into one palette;
+     * `"merged"` merges EVERY key's leaves into a single combined palette.
+     */
+    groupBy?: "group" | "type" | "merged";
     /** Representative colours per category, 1–64. */
     topN?: number;
     /** `"diverse"` maximises visual distinctness instead of frequency. */

package/colours-client.d.ts

@@ -42,6 +42,13 @@ export declare class ColoursClient {
      * cannot recover that spread from a truncated frequency list, which is why it
      * is a server mode rather than a local sort.
      *
+     * `groupBy: "merged"` merges across the KEYS as well and returns ONE profile
+     * over the union of their leaves — the palette of a caller-defined facet such
+     * as "Wood" (`wood_surface` + `wood_flooring`) that the taxonomy holds no
+     * single node for, and that no combination of per-key responses reconstructs.
+     * Its keys may sit at either tier, `categoryKey` is those keys sorted and
+     * joined with `+`, and `members` hands them back so nothing has to split it.
+     *
      * A selected category with no colour data comes back as a zero-count profile,
      * not a missing key.
      */

package/colours-client.js

@@ -15,6 +15,13 @@ export class ColoursClient {
      * cannot recover that spread from a truncated frequency list, which is why it
      * is a server mode rather than a local sort.
      *
+     * `groupBy: "merged"` merges across the KEYS as well and returns ONE profile
+     * over the union of their leaves — the palette of a caller-defined facet such
+     * as "Wood" (`wood_surface` + `wood_flooring`) that the taxonomy holds no
+     * single node for, and that no combination of per-key responses reconstructs.
+     * Its keys may sit at either tier, `categoryKey` is those keys sorted and
+     * joined with `+`, and `members` hands them back so nothing has to split it.
+     *
      * A selected category with no colour data comes back as a zero-count profile,
      * not a missing key.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instruments/materialgraph",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "exports": {
     ".": {