@yschimke/compose-design-map 1.19.0 → 1.20.0

package/README.md

@@ -137,6 +137,29 @@ Several modes with **no light among them** is the one case that stays unmapped.
 guessing which of `Dark` and `Coral` the kit drew, so those components are reported
 (`diagnostics.ambiguousMode`, and a `--strict` failure) rather than paired at random.
 
+**A breakpoint fan-out is a size axis, not a mode.** A multipreview that draws one composable at
+several screen sizes — the Wear round breakpoints are the live case — publishes several captures of
+it, told apart by the *same* id segment a themed pair uses. Read as modes they are unresolvable
+(`Light` is nowhere among `wearos_small_round` / `wearos_large_round`), so a full-screen component
+used to drop out of the map entirely the moment it gained a second size.
+
+They are told apart by a fact the id does not carry: each capture names a `device`, and the devices
+have **different widths**. A palette does not change the frame's width, so captures whose modes map
+one-to-one onto distinct device widths are a size axis and one of them can be picked on the merits:
+
+- the **narrowest** is the base by default, because that is the size a kit draws — a kit publishes
+  its screen artwork at one size and leaves adaptation to the implementation, and the narrowest is
+  the one every larger screen is an adaptation *of*;
+- `--base-breakpoint <dp>` moves it, for a kit that draws somewhere else. A named base a given
+  composable does not render falls back to the narrowest rather than dropping it — rendering a
+  subset of the catalog's breakpoints is a legitimate thing for one screen to do;
+- 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.
+
+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.
+
 **`overrides.props` beats `overrides.seeds` where both exist.** They are not the same list. `seeds`
 holds only the values that differ from the composable's defaults; `props` — emitted for a
 `@PreviewAxis` cross product — carries the full axis assignment, defaults included. A cell that

package/design-map.mjs

@@ -113,9 +113,51 @@ export function captureIdentity(preview) {
  * guessing which of `Dark` and `Coral` the kit drew, and pairing the wrong one diffs a whole
  * palette — so it is reported instead (`diagnostics.ambiguousMode`).
  */
-function preferredMode(modes) {
+function preferredMode(modes, widthByMode, baseBreakpointDp) {
   if (modes.has(LIGHT_MODE)) return LIGHT_MODE;
-  return modes.size === 1 ? [...modes][0] : null;
+  if (modes.size === 1) return [...modes][0];
+
+  // A BREAKPOINT FAN-OUT is not an ambiguous mode, and telling them apart is what this arm is for.
+  //
+  // A multipreview that renders one function at several screen sizes produces several captures of
+  // one composable, exactly like a themed pair does — and the id segment they are told apart by is
+  // the same segment. Read as modes they are unresolvable (`Light` is nowhere among
+  // `wearos_small_round` / `wearos_large_round`), so every full-screen component of a Wear catalog
+  // dropped out of the map the moment it gained a second size, and `--strict` failed on it.
+  //
+  // They are distinguishable by a fact the id does not carry: each capture names a `device`, and
+  // the devices have DIFFERENT WIDTHS. A palette does not change the frame's width, so a set of
+  // captures whose modes map one-to-one onto distinct device widths is a size axis rather than a
+  // colour one, and one of them can be picked on the merits.
+  const sized = [...modes].map((mode) => [mode, widthByMode.get(mode)]);
+  const widths = sized.map(([, width]) => width);
+  if (!widths.every((width) => Number.isFinite(width))) return null;
+  if (new Set(widths).size !== widths.length) return null;
+
+  // NARROWEST by default, because that is the size a kit draws: a design kit publishes its screen
+  // artwork at one size and leaves adaptation to the implementation, and the narrowest is the one
+  // every larger screen is an adaptation OF. `baseBreakpointDp` overrides it for a kit that draws
+  // somewhere else. A named base this composable does not render falls back to the narrowest
+  // rather than dropping the component: rendering a subset of the catalog's breakpoints is a
+  // legitimate thing for one screen to do, and it is not a reason to publish no map row for it.
+  sized.sort((a, b) => a[1] - b[1]);
+  const named = Number.isFinite(baseBreakpointDp)
+    ? sized.find(([, width]) => width === baseBreakpointDp)
+    : null;
+  return (named ?? sized[0])[0];
+}
+
+/**
+ * The device width a capture was drawn at, or `null` when it names no device.
+ *
+ * Read from `params.device` rather than `params.widthDp` alone: a device-less preview carries no
+ * width at all, and a `wrapSandbox` bound is not a screen size. Only a capture that names a device
+ * is claiming to be a picture of a screen.
+ */
+function deviceWidthDp(preview) {
+  const params = preview?.params;
+  if (!params?.device) return null;
+  return Number.isFinite(params.widthDp) ? params.widthDp : null;
 }
 
 /**
@@ -124,9 +166,10 @@ function preferredMode(modes) {
  *
  * @returns {{participates: (preview: object) => boolean, ambiguous: Array<object>}}
  */
-export function selectCaptures(previews) {
+export function selectCaptures(previews, { baseBreakpointDp } = {}) {
   const modesBySubject = new Map();
   const componentsBySubject = new Map();
+  const widthsBySubject = new Map();
   for (const preview of previews) {
     if (!preview?.catalog) continue;
     const { subject, mode } = captureIdentity(preview);
@@ -136,12 +179,18 @@ export function selectCaptures(previews) {
     const ids = componentsBySubject.get(subject) ?? new Set();
     if (preview.catalog.componentId) ids.add(preview.catalog.componentId);
     componentsBySubject.set(subject, ids);
+    const widths = widthsBySubject.get(subject) ?? new Map();
+    // A VARIANT capture rides the same device as its base, so it agrees rather than conflicts —
+    // but read the base's width first, since that is the one the fan-out is defined by.
+    if (!widths.has(mode)) widths.set(mode, deviceWidthDp(preview));
+    widthsBySubject.set(subject, widths);
   }
 
   const chosen = new Map();
   const ambiguous = [];
   for (const [subject, modes] of modesBySubject) {
-    const mode = preferredMode(modes);
+    const widths = widthsBySubject.get(subject) ?? new Map();
+    const mode = preferredMode(modes, widths, baseBreakpointDp);
     if (mode === null) {
       ambiguous.push({
         subject,
@@ -160,6 +209,22 @@ export function selectCaptures(previews) {
       const { subject, mode } = captureIdentity(preview);
       return chosen.has(subject) && chosen.get(subject) === mode;
     },
+    /**
+     * The device width of a capture that is a NON-BASE breakpoint of a fan-out, or `null`.
+     *
+     * This is what turns the sizes the base did not take into cells rather than into silence. A
+     * capture qualifies only when its subject resolved to some other mode and both that mode and
+     * this one name a device width — so a `Dark` capture standing beside a chosen `Light` one,
+     * which is a mode and not a size, is never mistaken for a breakpoint.
+     */
+    breakpointOf(preview) {
+      const { subject, mode } = captureIdentity(preview);
+      if (!chosen.has(subject) || chosen.get(subject) === mode) return null;
+      const widths = widthsBySubject.get(subject);
+      const base = widths?.get(chosen.get(subject));
+      const here = widths?.get(mode);
+      return Number.isFinite(base) && Number.isFinite(here) ? here : null;
+    },
   };
 }
 
@@ -375,7 +440,25 @@ export function variantRendersByComponent(previews, selection = selectCaptures(p
     // mode its component's base reference pairs with.
     const isOverrideVariant = catalog.role === "COMPONENT" && isVariantCapture(preview);
     const isCatalogVariant = catalog.role === "VARIANT";
-    if (!isOverrideVariant && !isCatalogVariant) continue;
+
+    // A BREAKPOINT capture is the third form, and it is not an annotation at all — it is the same
+    // composable drawn on a wider screen by a multipreview. It folds under its component like any
+    // other cell, seeded with the width it was drawn at, so the sizes the base did not take are
+    // published rather than discarded.
+    //
+    // Taken BEFORE the `participates` gate, because a non-base breakpoint is by definition the
+    // capture that did not participate. An `@OverrideVariant` cell of a non-base breakpoint is
+    // skipped, though — that is the product of two axes and would multiply the sheet by every
+    // size; the base breakpoint carries the component's matrix.
+    if (!isOverrideVariant && !isCatalogVariant) {
+      const widthDp = catalog.role === "COMPONENT" ? selection.breakpointOf(preview) : null;
+      if (widthDp === null) continue;
+      const seeds = [{ key: "breakpoint", raw: String(widthDp) }];
+      const list = byComponent.get(catalog.componentId) ?? [];
+      list.push({ previewId: preview.id, name: `${widthDp}dp`, seeds });
+      byComponent.set(catalog.componentId, list);
+      continue;
+    }
     if (!selection.participates(preview)) continue;
 
     // A variant that names no axis says only "this is different", which is not enough to look
@@ -401,7 +484,7 @@ export function variantRendersByComponent(previews, selection = selectCaptures(p
  *   fact to report, not a failure.
  */
 export function projectDesignMap(previews, opts = {}) {
-  const selection = selectCaptures(previews);
+  const selection = selectCaptures(previews, { baseBreakpointDp: opts.baseBreakpointDp });
   const variantRenders = variantRendersByComponent(previews, selection);
 
   const components = [];

package/emit-design-map.mjs

@@ -5,6 +5,7 @@
  *     npx @yschimke/compose-design-map [--previews <path>] [--out design-map.json]
  *                                      [--variants design-map-variants.json] [--prefix catalog]
  *                                      [--check] [--strict] [--allow-stated-absence]
+ *                                      [--base-breakpoint <dp>]
  *
  * Run `./gradlew :<module>:composePreviewDiscover` first so the manifest exists.
  *
@@ -60,6 +61,15 @@ const PREFIX = arg("prefix", "catalog");
 const CHECK = process.argv.includes("--check");
 const STRICT = process.argv.includes("--strict");
 const ALLOW_STATED_ABSENCE = process.argv.includes("--allow-stated-absence");
+/**
+ * The screen width, in dp, whose capture is the BASE of a breakpoint fan-out.
+ *
+ * A multipreview that draws one composable at several screen sizes publishes several captures of
+ * it, and exactly one can carry the component's design reference — the rest fold under it as size
+ * cells. Absent this flag the narrowest wins, which is the size a kit usually draws. Pass it when
+ * the kit draws somewhere else, so the base capture and the base reference are the same width.
+ */
+const BASE_BREAKPOINT = Number(arg("base-breakpoint", ""));
 
 if (!fs.existsSync(PREVIEWS)) {
   console.error(
@@ -72,6 +82,9 @@ if (!fs.existsSync(PREVIEWS)) {
 const manifest = JSON.parse(fs.readFileSync(PREVIEWS, "utf8"));
 const { map, variants, diagnostics } = projectDesignMap(manifest.previews ?? [], {
   prefix: PREFIX,
+  ...(Number.isFinite(BASE_BREAKPOINT) && BASE_BREAKPOINT > 0
+    ? { baseBreakpointDp: BASE_BREAKPOINT }
+    : {}),
 });
 
 // Gate BEFORE writing, not after. A run that fails should leave the committed map intact rather

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yschimke/compose-design-map",
-  "version": "1.19.0",
+  "version": "1.20.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",