@colixsystems/widget-sdk 0.129.0 → 0.131.0

package/README.md

@@ -70,7 +70,23 @@ 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.131.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.131.0 (contract 1.102.0)
+
+**`styleGroup(name)` is deprecated and now inert (sc-7344).** The Widget Builder preview's click-to-select mode — the primitive's only reader — has been removed, so nothing maps a clicked element back to its style group any more. Style fields are edited through the whole-widget style editor the gear button opens.
+
+- **No migration needed.** `styleGroup()` is still exported and still returns the same props, so existing `<View {...styleGroup("Card")}>` spreads keep building and rendering exactly as before — they are simply no-ops now. It was always a marker that changed nothing about how a widget renders.
+- **Don't add it to new widgets.** The AI widget agent no longer emits it.
+
+### What's new in 0.130.0 (contract 1.101.0)
+
+**~~New primitive `styleGroup(name)`~~ — superseded by 0.131.0, see above (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.
+
+*(Historical — the guidance below no longer applies; see 0.131.0 above.)*
+
+- **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. sc-7344 removed its only reader (the Widget
+  // Builder preview's click-to-select), so it is now DEPRECATED and inert on
+  // both hosts. Kept exported because it is published API: dropping it would
+  // break widgets already spreading it, and it is a no-op marker either way.
+  {
+    name: "styleGroup",
+    description:
+      "DEPRECATED (sc-7344) — do not add it to new widgets. It marked which rendered element a styleSchema `ui.group` painted, for a Widget Builder preview click-to-select that no longer exists. Nothing reads the marker now, so it has no effect on either host. It remains exported and safe: widgets that already spread it keep working — the call is a no-op now — so no migration is needed. Style fields are edited through the whole-widget style editor.",
+    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,27 @@ 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.
+  // 1.102.0: deprecation (sc-7344) — `styleGroup(name)` is now inert. Its only
+  //    reader, the Widget Builder preview's click-to-select mode (sc-7209) and
+  //    the per-element style narrowing it fed (sc-7282), is removed: two
+  //    controls opened one drawer, and arming the overlay stopped the author
+  //    exercising the widget they were previewing. The primitive stays
+  //    EXPORTED and unchanged — it is published API and a pure no-op marker, so
+  //    widgets already spreading it keep building with no migration (CLAUDE.md
+  //    §7: a breaking change to a shipped package needs a reason, and there is
+  //    none here). Only the MANDATE to emit it is gone, from the AI widget
+  //    agent prompt and the designer skill. Minor bump: nothing removed.
+  version: "1.102.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. sc-7344 removed its only reader (the Widget
+  // Builder preview's click-to-select), so it is now DEPRECATED and inert on
+  // both hosts. Kept exported because it is published API: dropping it would
+  // break widgets already spreading it, and it is a no-op marker either way.
+  {
+    name: "styleGroup",
+    description:
+      "DEPRECATED (sc-7344) — do not add it to new widgets. It marked which rendered element a styleSchema `ui.group` painted, for a Widget Builder preview click-to-select that no longer exists. Nothing reads the marker now, so it has no effect on either host. It remains exported and safe: widgets that already spread it keep working — the call is a no-op now — so no migration is needed. Style fields are edited through the whole-widget style editor.",
+    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,27 @@ 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.
+  // 1.102.0: deprecation (sc-7344) — `styleGroup(name)` is now inert. Its only
+  //    reader, the Widget Builder preview's click-to-select mode (sc-7209) and
+  //    the per-element style narrowing it fed (sc-7282), is removed: two
+  //    controls opened one drawer, and arming the overlay stopped the author
+  //    exercising the widget they were previewing. The primitive stays
+  //    EXPORTED and unchanged — it is published API and a pure no-op marker, so
+  //    widgets already spreading it keep building with no migration (CLAUDE.md
+  //    §7: a breaking change to a shipped package needs a reason, and there is
+  //    none here). Only the MANDATE to emit it is gone, from the AI widget
+  //    agent prompt and the designer skill. Minor bump: nothing removed.
+  version: "1.102.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>;
+
+/**
+ * @deprecated (sc-7344) — inert; nothing reads the marker. It marked which
+ * rendered element a styleSchema `ui.group` painted, for a Widget Builder
+ * preview click-to-select that no longer exists. Still exported and safe:
+ * existing spreads keep working as no-ops, so no migration is needed.
+ *
+ * A missing or blank name returns `undefined`, so spreading 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,35 @@
+// sc-7282 — marked WHICH rendered element a styleSchema `ui.group` paints.
+//
+// DEPRECATED (sc-7344): its only reader, the Widget Builder preview's
+// click-to-select, is gone, so the marker is now inert. Kept exported because
+// it is published API and a no-op — widgets already spreading it need no
+// migration (CLAUDE.md §7). Do not add it to new widgets.
+//
+// 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";
+
+/**
+ * @deprecated (sc-7344) — inert; nothing reads the marker.
+ *
+ * Props marking the element a style group paints. Still returns the same shape,
+ * so existing spreads keep working as no-ops.
+ *
+ * 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.131.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"