@colixsystems/widget-sdk 0.129.0 → 0.130.0

package/README.md

@@ -70,7 +70,14 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.129.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.130.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.130.0 (contract 1.101.0)
+
+**New primitive `styleGroup(name)` — mark which element a style group paints (sc-7282).** A widget's `styleSchema` already names the element each field belongs to via `ui.group` ("Card", "Title", "Value"), and the Studio renders those as labelled fieldsets. But a group name says which *fieldset* a control sits in, not which *element on screen* it moves — so clicking a button in the Widget Builder preview could only ever open the whole schema.
+
+- **Spread it on the element each non-Basics group paints:** `<View {...styleGroup("Card")}>`. Pass the EXACT `ui.group` string; a mismatch marks an element no group owns. Mark each group ONCE, on the outermost element an author would point at — never the `"Basics"` group (it paints the whole widget) and never a child of an already-marked element. On a list that repeats a marked element per row, mark every row.
+- **One module, both hosts.** It rides the existing `dataSet` prop: `react-native-web` maps it to a `data-*` attribute, and real react-native drops it, so the marker is inert on the device rather than a second implementation. It is a marker, not a style — it changes nothing about how a widget renders.
 
 ### What's new in 0.129.0 (contract 1.100.0)
 

package/dist/contract.cjs

@@ -1878,6 +1878,17 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  // sc-7282 — the element marker. A FUNCTION primitive like pressableLift: it
+  // returns props to spread, so ONE declaration marks the element on both
+  // hosts. Inert on native (react-native drops `dataSet`), so it costs the
+  // device nothing.
+  {
+    name: "styleGroup",
+    description:
+      "Marks WHICH rendered element a styleSchema `ui.group` paints. Spread it on the element: `<View {...styleGroup(\"Card\")}>`. Pass the EXACT group name from your styleSchema `ui.group` — character for character, or the click resolves to nothing. The Widget Builder preview reads it to map a clicked element back to its group and show only that group's style fields. Mark the OUTERMOST element of each non-Basics group ONCE; never mark the \"Basics\" group (it paints the whole widget) and never mark a child of an already-marked element. On a list that repeats a marked element per row, mark EVERY row. It is a marker, not a style: it changes nothing about how the widget renders.",
+    rnComponent: null,
+    docsUrl: null,
+  },
   // sc-6607 — the SCREEN-level overlay. Widgets could previously only paint an
   // overlay inside their own box, so a preview or dialog was clipped by the
   // layout container the widget sits in; this is the one primitive that leaves
@@ -3820,7 +3831,17 @@ const CONTRACT = deepFreeze({
   //    preview useCamera already owns, so this is full parity wherever the
   //    browser ships the API and a declared `supported:false` where it does not
   //    (Safari, Firefox) — a genuine browser gap per CLAUDE.md §8.
-  version: "1.100.0",
+  // 1.101.0: additive (sc-7282) — a new `styleGroup(name)` primitive marking
+  //    WHICH rendered element a styleSchema `ui.group` paints, so the Widget
+  //    Builder preview can map a clicked node back to its group and show only
+  //    that group's style fields instead of the whole schema. It returns props
+  //    to spread (`<View {...styleGroup("Card")}>`) and rides the existing
+  //    `dataSet` prop: react-native-web maps it to `data-*`, real react-native
+  //    drops it, so ONE module serves both hosts and the marker is inert on the
+  //    device — no §8 native-only case and no paired implementation. Purely a
+  //    marker: it changes nothing about how a widget renders. Minor bump on the
+  //    pre-1.0 channel.
+  version: "1.101.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1878,6 +1878,17 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  // sc-7282 — the element marker. A FUNCTION primitive like pressableLift: it
+  // returns props to spread, so ONE declaration marks the element on both
+  // hosts. Inert on native (react-native drops `dataSet`), so it costs the
+  // device nothing.
+  {
+    name: "styleGroup",
+    description:
+      "Marks WHICH rendered element a styleSchema `ui.group` paints. Spread it on the element: `<View {...styleGroup(\"Card\")}>`. Pass the EXACT group name from your styleSchema `ui.group` — character for character, or the click resolves to nothing. The Widget Builder preview reads it to map a clicked element back to its group and show only that group's style fields. Mark the OUTERMOST element of each non-Basics group ONCE; never mark the \"Basics\" group (it paints the whole widget) and never mark a child of an already-marked element. On a list that repeats a marked element per row, mark EVERY row. It is a marker, not a style: it changes nothing about how the widget renders.",
+    rnComponent: null,
+    docsUrl: null,
+  },
   // sc-6607 — the SCREEN-level overlay. Widgets could previously only paint an
   // overlay inside their own box, so a preview or dialog was clipped by the
   // layout container the widget sits in; this is the one primitive that leaves
@@ -3820,7 +3831,17 @@ const CONTRACT = deepFreeze({
   //    preview useCamera already owns, so this is full parity wherever the
   //    browser ships the API and a declared `supported:false` where it does not
   //    (Safari, Firefox) — a genuine browser gap per CLAUDE.md §8.
-  version: "1.100.0",
+  // 1.101.0: additive (sc-7282) — a new `styleGroup(name)` primitive marking
+  //    WHICH rendered element a styleSchema `ui.group` paints, so the Widget
+  //    Builder preview can map a clicked node back to its group and show only
+  //    that group's style fields instead of the whole schema. It returns props
+  //    to spread (`<View {...styleGroup("Card")}>`) and rides the existing
+  //    `dataSet` prop: react-native-web maps it to `data-*`, real react-native
+  //    drops it, so ONE module serves both hosts and the marker is inert on the
+  //    device — no §8 native-only case and no paired implementation. Purely a
+  //    marker: it changes nothing about how a widget renders. Minor bump on the
+  //    pre-1.0 channel.
+  version: "1.101.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/index.d.ts

@@ -2679,3 +2679,15 @@ export function pressableLift(state?: {
   hovered?: boolean;
   pressed?: boolean;
 }): Array<Record<string, unknown> | null>;
+
+/**
+ * sc-7282 — marks WHICH rendered element a styleSchema `ui.group` paints, so
+ * the Widget Builder preview can show only that group's style fields when the
+ * element is clicked. Spread it: `<View {...styleGroup("Card")}>`.
+ *
+ * `name` must be the EXACT `ui.group` string. A missing or blank name returns
+ * `undefined`, so spreading the result is always safe.
+ */
+export function styleGroup(
+  name: string,
+): { dataSet: Record<string, string> } | undefined;

package/dist/index.js

@@ -155,3 +155,4 @@ export {
 } from "./contract.js";
 export { normalizeLucideIconName } from "./lucideIconName.js";
 export { pressableLift } from "./interaction.js";
+export { styleGroup } from "./style-group.js";

package/dist/index.native.js

@@ -149,3 +149,4 @@ export {
 } from "./contract.js";
 export { normalizeLucideIconName } from "./lucideIconName.js";
 export { pressableLift } from "./interaction.native.js";
+export { styleGroup } from "./style-group.js";

package/dist/style-group.js

@@ -0,0 +1,33 @@
+// sc-7282 — marks WHICH rendered element a styleSchema `ui.group` paints, so
+// the Widget Builder preview can map a clicked node back to its group and show
+// only that group's style fields.
+//
+// ONE file, no `.native.js` twin: `react-native-web` maps `dataSet` to `data-*`
+// attributes while real react-native drops the prop, so the marker is inert on
+// the device rather than a second implementation (CLAUDE.md §3). The paired
+// modules in this package (interaction.js, overlay.js) exist because their
+// behaviour genuinely differs per host; this one's does not.
+//
+// Not a primitive wrapper either — primitives.js re-exports react-native-web
+// directly, and its header records that the hand-written paired wrappers were
+// removed on purpose.
+
+/** The `dataSet` key, surfacing in the DOM as `data-style-group`. */
+export const STYLE_GROUP_DATA_KEY = "styleGroup";
+
+/**
+ * Props marking the element a style group paints. Spread it:
+ * `<View {...styleGroup("Card")}>`.
+ *
+ * `name` must be the EXACT `ui.group` string from the widget's styleSchema — a
+ * mismatch marks an element no group owns, and the click resolves to nothing.
+ *
+ * Returns `undefined` for a missing or blank name so `{...styleGroup(x)}` stays
+ * safe when `x` is absent: spreading `undefined` is a no-op in JSX.
+ */
+export function styleGroup(name) {
+  if (typeof name !== "string") return undefined;
+  const trimmed = name.trim();
+  if (!trimmed) return undefined;
+  return { dataSet: { [STYLE_GROUP_DATA_KEY]: trimmed } };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.129.0",
+  "version": "0.130.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",
@@ -49,7 +49,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "node --test src/__tests__/contract.test.js src/__tests__/vetted-imports-audit.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-invites.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-page-url.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-flex-basis-percent.test.js src/__tests__/linter-hardcoded-design.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__/flatten-entry.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/corner-radius.test.js src/__tests__/theme-components-parity.test.js src/__tests__/navigation-parity.test.js src/__tests__/theme-depth-tokens.test.js src/__tests__/interaction-lift.test.js src/__tests__/toast-host.test.js src/__tests__/overlay-tokens.test.js src/__tests__/hooks-domain-error-mapping.test.js src/__tests__/linter-datastore-error.test.js src/__tests__/linter-write-gating.test.js src/__tests__/hooks-speech-to-text.test.js src/__tests__/hooks-camera.test.js src/__tests__/hooks-barcode.test.js src/__tests__/hooks-image-editor.test.js src/__tests__/hooks-bound-columns.test.js src/__tests__/hooks-stable-query.test.js src/__tests__/hooks-can-write.test.js src/__tests__/widget-route.test.js src/__tests__/linter-html-in-content.test.js src/__tests__/markdown.test.js src/__tests__/markdown-edit.test.js src/__tests__/richtext-tokens.test.js"
+    "test": "node --test src/__tests__/contract.test.js src/__tests__/vetted-imports-audit.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-invites.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-page-url.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-flex-basis-percent.test.js src/__tests__/linter-hardcoded-design.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__/flatten-entry.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/corner-radius.test.js src/__tests__/theme-components-parity.test.js src/__tests__/navigation-parity.test.js src/__tests__/theme-depth-tokens.test.js src/__tests__/interaction-lift.test.js src/__tests__/toast-host.test.js src/__tests__/overlay-tokens.test.js src/__tests__/hooks-domain-error-mapping.test.js src/__tests__/linter-datastore-error.test.js src/__tests__/linter-write-gating.test.js src/__tests__/hooks-speech-to-text.test.js src/__tests__/hooks-camera.test.js src/__tests__/hooks-barcode.test.js src/__tests__/hooks-image-editor.test.js src/__tests__/hooks-bound-columns.test.js src/__tests__/hooks-stable-query.test.js src/__tests__/hooks-can-write.test.js src/__tests__/widget-route.test.js src/__tests__/linter-html-in-content.test.js src/__tests__/markdown.test.js src/__tests__/markdown-edit.test.js src/__tests__/richtext-tokens.test.js src/__tests__/style-group.test.js"
   },
   "engines": {
     "node": ">=18"