@yschimke/compose-design-map 1.53.1 → 1.55.0

package/README.md

@@ -156,6 +156,23 @@ one-to-one onto distinct device widths are a size axis and one of them can be pi
 - the sizes the base did not take **fold under it as cells**, seeded `breakpoint=<dp>` and named
   `<dp>dp`, so they are published rather than discarded.
 
+A bare `breakpoint=<dp>` is a value no kit vocabulary contains, so such a cell resolves against
+nothing — correctly, for the majority of kits, which draw every screen cell at one size and have no
+size axis at all. Where a kit *does* publish screen size as a variant property, the component says
+so:
+
+```kotlin
+@CatalogComponent(id = "Picker", breakpointKit = ["225=Larger Screen (BP)=Yes"])
+```
+
+and the 225dp cell is seeded `breakpoint=225` with `kitAxis`/`kitValue` attached, pairing with the
+kit node the picture was always there for. It is a per-component declaration rather than a
+per-run flag because it is a property of one component's kit set, not of the catalog; a size the
+component never draws, or a malformed entry, keeps the bare seed and is reported unresolved rather
+than mispaired. A breakpoint capture is the one kind of cell that cannot carry `@OverrideVariant
+(kitAxis = …)` itself — it is not an annotation at all — which is why the mapping lives on the
+component.
+
 Two captures of the *same* width are still a mode, whatever devices they name: nothing orders them,
 so they stay `ambiguousMode`. An `@OverrideVariant` cell rides the base breakpoint only — the
 product of both axes would multiply the sheet by every size, and the base carries the matrix.

package/design-map.mjs

@@ -503,7 +503,61 @@ export function declarationMisses(preview) {
  * this projection, which is why a FAB size axis read as unauthored while `FabSmall`/`FabMedium`/
  * `FabLarge` sat in the catalog all along.
  */
-export function variantRendersByComponent(previews, selection = selectCaptures(previews)) {
+/**
+ * The kit axis/value a component declares for a non-base breakpoint width, or `null`.
+ *
+ * [entries] are `@CatalogComponent.breakpointKit` strings, `"<widthDp>=<kitAxis>=<kitValue>"`. The
+ * `kitValue` half may itself contain `=` (a kit is free to name a cell `Size=Large`), so the split
+ * is on the FIRST TWO separators only — `String.split("=")` with a limit would drop the tail.
+ *
+ * A malformed entry, a non-numeric width or a width this component never renders yields `null`,
+ * which restores the bare `breakpoint=<width>` seed. That is the honest degradation — a mistyped
+ * mapping should cost the pairing, not silently pair the render against the wrong kit cell — but
+ * it must not be *silent*: degrading quietly leaves a typo indistinguishable from a deliberately
+ * undeclared mapping, and the only symptom is a generic pairing miss much further downstream. So
+ * a malformed entry is pushed onto [malformed] and reported as `diagnostics.invalidBreakpointKit`,
+ * the same way an unresolvable mode is reported rather than guessed at.
+ *
+ * "Malformed" is only about the entry's *shape*. An entry that is well-formed but names a width
+ * this particular capture is not — the common case, since one declaration serves every size — is
+ * not a fault and is not reported.
+ */
+export function breakpointKitNames(entries, widthDp, malformed = []) {
+  for (const entry of entries ?? []) {
+    if (typeof entry !== "string") {
+      malformed.push({ entry: String(entry), reason: "not a string" });
+      continue;
+    }
+    const firstEq = entry.indexOf("=");
+    const secondEq = firstEq < 0 ? -1 : entry.indexOf("=", firstEq + 1);
+    if (secondEq < 0) {
+      malformed.push({ entry, reason: "expected <widthDp>=<kitAxis>=<kitValue>" });
+      continue;
+    }
+    const rawWidth = entry.slice(0, firstEq).trim();
+    const width = Number(rawWidth);
+    if (rawWidth === "" || !Number.isFinite(width)) {
+      malformed.push({ entry, reason: `width '${rawWidth}' is not a number` });
+      continue;
+    }
+    const kitAxis = entry.slice(firstEq + 1, secondEq).trim();
+    const kitValue = entry.slice(secondEq + 1).trim();
+    if (!kitAxis || !kitValue) {
+      malformed.push({ entry, reason: "kitAxis and kitValue must both be non-empty" });
+      continue;
+    }
+    // Well-formed but for another size: not a fault, and the overwhelmingly common case.
+    if (width !== widthDp) continue;
+    return { kitAxis, kitValue };
+  }
+  return null;
+}
+
+export function variantRendersByComponent(
+  previews,
+  selection = selectCaptures(previews),
+  invalidBreakpointKit = [],
+) {
   const byComponent = new Map();
   for (const preview of previews) {
     const catalog = preview.catalog;
@@ -535,7 +589,28 @@ export function variantRendersByComponent(previews, selection = selectCaptures(p
     if (!isOverrideVariant && !isCatalogVariant) {
       const widthDp = catalog.role === "COMPONENT" ? selection.breakpointOf(preview) : null;
       if (widthDp === null) continue;
-      const seeds = [{ key: "breakpoint", raw: String(widthDp) }];
+      // `@CatalogComponent(breakpointKit = ["225=Larger Screen (BP)=Yes"])` says what this size
+      // MEANS to the kit. Without it the seed is a bare `breakpoint=225` — a value no kit
+      // vocabulary contains — and the resolver can only report "no counterpart for
+      // `breakpoint=225`", even where the kit publishes the very cells the render would pair with
+      // (issue #4827).
+      //
+      // Opt-in and per component, because most kits draw every screen cell at one size and have no
+      // size axis at all. Declaring nothing keeps the bare seed, so those captures stay honestly
+      // reported as renders with no kit counterpart rather than mispaired.
+      const malformed = [];
+      const kit = breakpointKitNames(catalog.breakpointKit, widthDp, malformed);
+      for (const bad of malformed) {
+        invalidBreakpointKit.push({ componentId: catalog.componentId, ...bad });
+      }
+      const seeds = [
+        {
+          key: "breakpoint",
+          raw: String(widthDp),
+          ...(kit?.kitAxis ? { kitAxis: kit.kitAxis } : {}),
+          ...(kit?.kitValue ? { kitValue: kit.kitValue } : {}),
+        },
+      ];
       const list = byComponent.get(catalog.componentId) ?? [];
       list.push({ previewId: preview.id, name: `${widthDp}dp`, seeds });
       byComponent.set(catalog.componentId, list);
@@ -587,7 +662,8 @@ export function variantRendersByComponent(previews, selection = selectCaptures(p
  */
 export function projectDesignMap(previews, opts = {}) {
   const selection = selectCaptures(previews, { baseBreakpointDp: opts.baseBreakpointDp });
-  const variantRenders = variantRendersByComponent(previews, selection);
+  const invalidBreakpointKit = [];
+  const variantRenders = variantRendersByComponent(previews, selection, invalidBreakpointKit);
 
   const components = [];
   const declarations = [];
@@ -752,6 +828,16 @@ export function projectDesignMap(previews, opts = {}) {
           !referencelessSubjects.has(a.subject) &&
           (!a.componentIds.length || a.componentIds.some((id) => !referencelessIds.has(id))),
       ),
+      // `@CatalogComponent(breakpointKit = …)` entries that do not parse. Reported rather than
+      // dropped: the degradation is to the bare `breakpoint=<dp>` seed, which is exactly what an
+      // undeclared component produces, so a typo would otherwise be invisible until someone
+      // wondered why a kit cell never paired. Deduplicated — one declaration is re-read once per
+      // non-base capture of the component, and the same typo is one fault, not four.
+      invalidBreakpointKit: [
+        ...new Map(
+          invalidBreakpointKit.map((e) => [`${e.componentId}\u0000${e.entry}`, e]),
+        ).values(),
+      ],
       variantRenders: declarations.reduce((n, d) => n + d.renders.length, 0),
       withSet: components.filter((c) => c.refSet).length,
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yschimke/compose-design-map",
-  "version": "1.53.1",
+  "version": "1.55.0",
   "description": "Project a compose-preview discovery manifest into design-parity's design-map.json, plus a sidecar of unresolved variant declarations. Dependency-free.",
   "license": "Apache-2.0",
   "type": "module",