@colixsystems/widget-sdk 0.85.0 → 0.86.0

package/README.md

@@ -24,7 +24,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useNavigation()` | `{ goTo, goBack, push, replace, back, currentRoute }` | `ctx.navigation` — no scope (external URLs use the `Linking` primitive) |
 | **CORE** | `useRouteParams()` | `{ [paramKey]: value }` | `ctx.navigation.currentRoute.params` — no scope. The nav params the previous page passed via `goTo(pageId, params)`; the flat accessor for master→detail (read `recordId` on a detail page). Empty object when none. |
 | **CORE** | `usePageContext()` | `{ params, records }` | `ctx.pageContext` — no scope. The page's DECLARED parameters, resolved once by the host: `params` are coerced to their declared types, `records` holds the row already fetched for each `record` param (read it instead of fetching again). Both empty when the page declares none. |
-| **CORE** | `useWidgetEvent(name)` | `(payload?) => void` | `ctx.events.emit` — no scope |
+| **CORE** | `useWidgetEvent(name)` | `(payload?) => void` | `ctx.events.emit` — no scope. The hook IS the emitter: `const emitSlot = useWidgetEvent("slotChosen")`, then `emitSlot(payload)`. Never destructure the result — there is no `emit` member. |
 | **CORE** | `useWidgetInput(inputName)` | the published payload, or `undefined` | `ctx.inputs` — no scope. Reads a value ANOTHER widget on the same page published with `useWidgetEvent`. Declare the input in `manifest.inputs`; the page author wires it to one sibling's declared event. The channel retains the last payload, so a widget that mounts later still reads it. `undefined` while unwired or before the first publish — always render a sensible default. Page-scoped and ephemeral: use `useRouteParams()` for state that must survive navigation, the datastore for state that must persist. |
 | **CORE** | `useChildRenderer()` | `{ renderNode(node) }` | `ctx.renderer` — no scope (prefer the `WidgetTree` component) |
 | **CORE** | `useFill()` | `boolean` | `ctx.fill` — no scope. `true` when the host sized this widget to fill its page-grid tile's reserved height (containers + media fill by default; the author can override per tile). Media-style widgets switch to a `flex: 1` / `height: "100%"` layout; others ignore it. Defaults `false`. |
@@ -61,7 +61,20 @@ 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)
+
+**`useWidgetEvent(name)` returns the emitter FUNCTION — the declared contract said otherwise (sc-4753).** `CONTRACT.hooks`'s entry for the hook declared `returnShape: { emit }`, so every surface derived from it — chiefly the Widget Builder Agent's hooks table — told authors the hook resolves to an object. It never did: `useWidgetEvent("slotChosen")` hands back the callable you invoke directly (`emitSlot({ courtId })`), exactly as the typings and the Developer guide have always documented. A widget written against the declared shape destructured a function, got `undefined`, and threw the moment a user interacted — a cross-widget wire that rendered perfectly and only failed on click. The declaration is now a bare callable and the publish-time render harness models the same shape, so a wrong destructure is caught instead of waved through. `CONTRACT.version` → `1.60.1`. Documentation-only correction: no export, signature, or runtime behaviour changed — a widget already calling the result is unaffected.
 
 ### What's new in 0.85.0 (contract 1.60.0)
 

package/dist/contract.cjs

@@ -782,7 +782,16 @@ const HOOKS = [
   {
     name: "useWidgetEvent",
     signature: "useWidgetEvent(eventName)",
-    returnShape: { emit: "(payload?) => void" },
+    // sc-4753 — the hook IS the emitter, so its return is declared as a bare
+    // callable. Naming an `emit` member here made every derived surface tell
+    // authors to destructure a function, which yields undefined at run time.
+    returnShape: {
+      "(returns)":
+        "(payload?) => void  // the hook returns the emitter FUNCTION itself, " +
+        "not a wrapper object. Call it directly: " +
+        "const emitSlot = useWidgetEvent(\"slotChosen\"); " +
+        "emitSlot({ courtId }). Never destructure the result.",
+    },
     requiredContextSlice: ["events.emit"],
     scopes: null,
   },
@@ -2651,7 +2660,13 @@ const CONTRACT = deepFreeze({
   //    `recipient_expr` shape and no recipient column can name them. The member
   //    list stays host-side — a script receives a count, never the ids — and
   //    `exclude_user_id` keeps an author off their own message.
-  version: "1.60.0",
+  // 1.60.1: fix (sc-4753) — `useWidgetEvent`'s declared `returnShape` claimed
+  //    the hook resolves to an object with an `emit` member. It returns the
+  //    emitter FUNCTION itself, exactly as hooks.js, index.d.ts and the
+  //    Developer guide have always said, so a widget written against the
+  //    declared shape destructured a function and threw on first interaction.
+  //    Declared as a bare callable now; no runtime behaviour changed.
+  version: "1.60.1",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -782,7 +782,16 @@ const HOOKS = [
   {
     name: "useWidgetEvent",
     signature: "useWidgetEvent(eventName)",
-    returnShape: { emit: "(payload?) => void" },
+    // sc-4753 — the hook IS the emitter, so its return is declared as a bare
+    // callable. Naming an `emit` member here made every derived surface tell
+    // authors to destructure a function, which yields undefined at run time.
+    returnShape: {
+      "(returns)":
+        "(payload?) => void  // the hook returns the emitter FUNCTION itself, " +
+        "not a wrapper object. Call it directly: " +
+        "const emitSlot = useWidgetEvent(\"slotChosen\"); " +
+        "emitSlot({ courtId }). Never destructure the result.",
+    },
     requiredContextSlice: ["events.emit"],
     scopes: null,
   },
@@ -2651,7 +2660,13 @@ const CONTRACT = deepFreeze({
   //    `recipient_expr` shape and no recipient column can name them. The member
   //    list stays host-side — a script receives a count, never the ids — and
   //    `exclude_user_id` keeps an author off their own message.
-  version: "1.60.0",
+  // 1.60.1: fix (sc-4753) — `useWidgetEvent`'s declared `returnShape` claimed
+  //    the hook resolves to an object with an `emit` member. It returns the
+  //    emitter FUNCTION itself, exactly as hooks.js, index.d.ts and the
+  //    Developer guide have always said, so a widget written against the
+  //    declared shape destructured a function and threw on first interaction.
+  //    Declared as a bare callable now; no runtime behaviour changed.
+  version: "1.60.1",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

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.0",
+  "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-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"