@colixsystems/widget-sdk 0.85.1 → 0.86.0

package/README.md

@@ -61,7 +61,16 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.77.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.86.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### What's new in 0.86.0 (contract unchanged)
+
+**New linter rule `measured-width-ignores-padding` — a measured width includes the measuring element's own padding (sc-4913).**
+
+- **`measured-width-ignores-padding` (severity `warning`, non-blocking).** A widget that puts `onLayout` on an element which sets its own `padding` (or `paddingHorizontal`/`Left`/`Right`), and then sizes grid cells from the measured number, is flagged. `onLayout` reports the element's **frame** width and padding sits inside that frame, so the space the children really get is `width - paddingLeft - paddingRight`. Cells sized to fill the raw measurement overflow the content box, the last one wraps, and the widget ships a whole empty column of whitespace beside its cards — on both the web Player and the native Expo export, with nothing in the console. Author fix: spread `onLayout` on an **unpadded** element (keep the padding on a parent, or measure an inner `<View>` inside the padded root) so the number you hold is the usable width. Better still for content-sized cells: skip the measurement entirely and wrap with flex — a `{ flexDirection: "row", flexWrap: "wrap", gap }` row whose cards take `{ flexGrow: 1, flexBasis: CARD_MIN }` splits the row's real content width itself and can never leave a leftover band.
+- **Why a warning.** The rule fires only when the measured value feeds sizing arithmetic — a padded box measured just to pick a wide/narrow form (`isNarrowWidth(width)`) is off by one padding pair and stays silent. A widget that already subtracts its own padding by hand matches too, because no text scan can verify the subtraction; that is deliberate — the remediation is correct for it as well and retires the arithmetic. Comments are not scanned, so documenting the anti-pattern is safe.
+
+`CONTRACT` is unchanged (no new field), and no export changed signature.
 
 ### What's new in 0.85.1 (contract 1.60.1)
 

package/dist/linter.cjs

@@ -877,6 +877,72 @@ function _imagePercentHeightRules(source) {
   return findings;
 }
 
+// sc-4913 — a measured frame INCLUDES the element's own padding, so cells sized
+// from it overflow the content box and the last one wraps into an empty column.
+// Mirror of linter.js (see there for the full rationale).
+const _JSX_TAG_RE = /<([A-Z][\w.]*)\b/g;
+const _ON_LAYOUT_ATTR_RE = /\bonLayout\s*=/;
+const _OWN_PADDING_RE = /\bpadding(?:Horizontal|Left|Right|Start|End)?\s*:/;
+const _WIDTH_HOLDER_RE =
+  /const\s*\[\s*([\w$]+)\s*,\s*([\w$]+)\s*\]\s*=\s*(useState|useContainerWidth)\b/g;
+const _LAYOUT_FEED_WINDOW = 80;
+
+function _measuredWidthNames(code) {
+  const names = [];
+  _WIDTH_HOLDER_RE.lastIndex = 0;
+  let held;
+  while ((held = _WIDTH_HOLDER_RE.exec(code))) {
+    const [, value, setter, hook] = held;
+    if (hook === "useContainerWidth") {
+      names.push(value);
+      continue;
+    }
+    const fedByLayout = new RegExp(
+      `\\b${setter}\\s*\\([\\s\\S]{0,${_LAYOUT_FEED_WINDOW}}?\\blayout\\.width\\b`,
+    );
+    if (fedByLayout.test(code)) names.push(value);
+  }
+  return names;
+}
+
+function _sizesFromMeasuredWidth(code, names) {
+  return names.some((name) =>
+    new RegExp(`\\b${name}\\s*[-/*]|[-/*]\\s*\\b${name}\\b`).test(code),
+  );
+}
+
+function _measuredPaddingRules(source) {
+  const code = _stripNonCode(source, { keepStrings: true });
+  const measured = _measuredWidthNames(code);
+  if (!_sizesFromMeasuredWidth(code, measured)) return [];
+  const sourceLines = source.split(/\r?\n/);
+  const findings = [];
+  _JSX_TAG_RE.lastIndex = 0;
+  let tag;
+  while ((tag = _JSX_TAG_RE.exec(code))) {
+    const end = _jsxOpenTagEnd(code, tag.index + tag[0].length);
+    const attrs = code.slice(tag.index, end);
+    _JSX_TAG_RE.lastIndex = end;
+    if (!_ON_LAYOUT_ATTR_RE.test(attrs)) continue;
+    const padded = _OWN_PADDING_RE.exec(attrs);
+    if (!padded) continue;
+    const line = code
+      .slice(0, tag.index + padded.index)
+      .split(/\r?\n/).length;
+    findings.push({
+      rule: "measured-width-ignores-padding",
+      severity: "warning",
+      label:
+        `<${tag[1]}> has onLayout AND its own padding: the measured width ` +
+        `INCLUDES that padding, so cells sized from it overflow and the last ` +
+        `wraps, leaving an empty column. Measure an unpadded inner View.`,
+      line,
+      snippet: (sourceLines[line - 1] || "").trim().slice(0, 200),
+    });
+  }
+  return findings;
+}
+
 // Narrow a split-impl widget's manifest to the platform a single bundle file
 // ships to, so `import-platform-mismatch` lints each file against what it
 // actually targets. Mirror of linter.js.
@@ -939,6 +1005,9 @@ function lintSource(source, options) {
   findings.push(..._lucideIconRules(source));
   findings.push(..._reactInScopeRules(source));
   findings.push(..._imagePercentHeightRules(source));
+  // sc-4913 — soft warning: a measured width that includes the widget's own
+  // padding wraps the last grid column into an empty one.
+  findings.push(..._measuredPaddingRules(source));
   // sc-4650 — soft warning: every payment refusal reported as "try again".
   findings.push(..._paymentCurrencyRules(source));
   findings.push(..._hardcodedCurrencyLabelRules(source));

package/dist/linter.js

@@ -1013,6 +1013,90 @@ function _imagePercentHeightRules(source) {
   return findings;
 }
 
+// sc-4913 — a measured frame INCLUDES the element's own padding.
+//
+// `onLayout` reports the frame width, and padding sits inside that frame. A
+// widget that measures its padded root and then sizes fixed-pixel grid columns
+// to fill the measured number overflows its own content box by left+right
+// padding, so the last column wraps: a whole empty column of whitespace beside
+// the cards, on both hosts. Nothing else catches it — the widget renders and
+// every other gate passes.
+//
+// Fires only when the measurement feeds sizing arithmetic. A padded box
+// measured just to branch narrow/wide is off by one padding pair and correct
+// enough; `isNarrowWidth` is the sanctioned reader for that. A widget that DID
+// subtract its own padding matches too — no text scan can verify the
+// subtraction — and that is deliberate: the remediation (measure an unpadded
+// inner View) is correct for it as well, and retires the arithmetic entirely.
+const _JSX_TAG_RE = /<([A-Z][\w.]*)\b/g;
+const _ON_LAYOUT_ATTR_RE = /\bonLayout\s*=/;
+const _OWN_PADDING_RE = /\bpadding(?:Horizontal|Left|Right|Start|End)?\s*:/;
+const _WIDTH_HOLDER_RE =
+  /const\s*\[\s*([\w$]+)\s*,\s*([\w$]+)\s*\]\s*=\s*(useState|useContainerWidth)\b/g;
+// A setter fed a layout width within this many chars of the call is measuring:
+// covers `setW(e.nativeEvent.layout.width)` and `setW(Math.round(…))` alike.
+const _LAYOUT_FEED_WINDOW = 80;
+
+function _measuredWidthNames(code) {
+  const names = [];
+  _WIDTH_HOLDER_RE.lastIndex = 0;
+  let held;
+  while ((held = _WIDTH_HOLDER_RE.exec(code))) {
+    const [, value, setter, hook] = held;
+    if (hook === "useContainerWidth") {
+      names.push(value);
+      continue;
+    }
+    const fedByLayout = new RegExp(
+      `\\b${setter}\\s*\\([\\s\\S]{0,${_LAYOUT_FEED_WINDOW}}?\\blayout\\.width\\b`,
+    );
+    if (fedByLayout.test(code)) names.push(value);
+  }
+  return names;
+}
+
+function _sizesFromMeasuredWidth(code, names) {
+  return names.some((name) =>
+    new RegExp(`\\b${name}\\s*[-/*]|[-/*]\\s*\\b${name}\\b`).test(code),
+  );
+}
+
+function _measuredPaddingRules(source) {
+  // Comments are blanked so this rule's own documented anti-pattern, and a
+  // commented-out draft, never fire.
+  const code = _stripNonCode(source, { keepStrings: true });
+  const measured = _measuredWidthNames(code);
+  if (!_sizesFromMeasuredWidth(code, measured)) return [];
+  const sourceLines = source.split(/\r?\n/);
+  const findings = [];
+  _JSX_TAG_RE.lastIndex = 0;
+  let tag;
+  while ((tag = _JSX_TAG_RE.exec(code))) {
+    const end = _jsxOpenTagEnd(code, tag.index + tag[0].length);
+    const attrs = code.slice(tag.index, end);
+    _JSX_TAG_RE.lastIndex = end;
+    if (!_ON_LAYOUT_ATTR_RE.test(attrs)) continue;
+    const padded = _OWN_PADDING_RE.exec(attrs);
+    if (!padded) continue;
+    // Report the padding, not the tag: on a multi-line open tag the style line
+    // is the actionable one.
+    const line = code
+      .slice(0, tag.index + padded.index)
+      .split(/\r?\n/).length;
+    findings.push({
+      rule: "measured-width-ignores-padding",
+      severity: "warning",
+      label:
+        `<${tag[1]}> has onLayout AND its own padding: the measured width ` +
+        `INCLUDES that padding, so cells sized from it overflow and the last ` +
+        `wraps, leaving an empty column. Measure an unpadded inner View.`,
+      line,
+      snippet: (sourceLines[line - 1] || "").trim().slice(0, 200),
+    });
+  }
+  return findings;
+}
+
 /**
  * Narrow a split-impl widget's manifest to the platform a single bundle file
  * ships to, so `import-platform-mismatch` lints each file against what it
@@ -1083,6 +1167,9 @@ export function lintSource(source, options) {
   findings.push(..._reactInScopeRules(source));
   // sc-3493 — soft warning: percentage height on an <Image> collapses to 0.
   findings.push(..._imagePercentHeightRules(source));
+  // sc-4913 — soft warning: a measured width that includes the widget's own
+  // padding wraps the last grid column into an empty one.
+  findings.push(..._measuredPaddingRules(source));
   // sc-4650 — soft warning: every payment refusal reported as "try again".
   findings.push(..._paymentCurrencyRules(source));
   findings.push(..._hardcodedCurrencyLabelRules(source));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.85.1",
+  "version": "0.86.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -48,7 +48,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-payments.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-section-empty.test.js src/__tests__/hooks-widget-event.test.js src/__tests__/hooks-widget-input.test.js src/__tests__/hooks-identification.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-translation-api.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-payment-error.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/hooks-translate.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/theme-components-parity.test.js src/__tests__/theme-depth-tokens.test.js"
+    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-payments.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-section-empty.test.js src/__tests__/hooks-widget-event.test.js src/__tests__/hooks-widget-input.test.js src/__tests__/hooks-identification.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-translation-api.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-measured-padding.test.js src/__tests__/linter-payment-error.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/hooks-translate.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/theme-components-parity.test.js src/__tests__/theme-depth-tokens.test.js"
   },
   "engines": {
     "node": ">=18"