@colixsystems/widget-sdk 0.130.0 → 0.132.0

package/README.md

@@ -70,11 +70,26 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`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**.
+`v0.132.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.132.0 (contract 1.102.0)
+
+**BREAKING: the top bar has no divider — `resolveTopBarTokens` drops `borderColor` and `borderWidth` (sc-7360).** The bar and its tab row are one surface; a line under the bar ruled it off from its own menu, and a line under the tabs ruled the menu off from the page it navigates. Neither host draws one any more, the Design page offers no colour or width for one, and `TopBarTokens` no longer carries the two fields. A stored `topBar.borderColor` / `borderWidth` is **inert, not migrated** — nothing reads it, and the theme coercer drops it from a saved look or a Mason `set_theme`. The rail's, footer's and site header's dividers are unchanged.
+
+- `resolveSidebarTokens` / `resolveFooterTokens` are unchanged. No `CONTRACT` change.
+
+### 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)` — 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.
+**~~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.

package/dist/contract.cjs

@@ -1878,14 +1878,14 @@ 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.
+  // 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:
-      "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.",
+      "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,
   },
@@ -3841,7 +3841,17 @@ const CONTRACT = deepFreeze({
   //    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",
+  // 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,14 +1878,14 @@ 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.
+  // 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:
-      "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.",
+      "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,
   },
@@ -3841,7 +3841,17 @@ const CONTRACT = deepFreeze({
   //    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",
+  // 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/host.d.ts

@@ -222,13 +222,12 @@ export function resolveSidebarTokens(theme: unknown): SidebarTokens;
 
 /** The top app bar's resolved tokens. `tintColor` and `titleColor` are separate
  *  because an unthemed bar paints its icons slate and its app name in the brand
- *  colour; an authored `topBar.textColor` drives both. */
+ *  colour; an authored `topBar.textColor` drives both. The bar carries NO
+ *  divider (sc-7360): a stored `topBar.borderColor` / `borderWidth` is inert. */
 export interface TopBarTokens {
   backgroundColor: string;
   tintColor: string;
   titleColor: string;
-  borderColor: string | null;
-  borderWidth: number | null;
   /** The current page's mark — the active link's label, and an active tab's
    *  label plus its indicator. Falls back to the RAIL's `activeColor` and then
    *  to the brand, so an app states its navigation colour once. */

package/dist/index.d.ts

@@ -2681,12 +2681,12 @@ export function pressableLift(state?: {
 }): 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")}>`.
+ * @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.
  *
- * `name` must be the EXACT `ui.group` string. A missing or blank name returns
- * `undefined`, so spreading the result is always safe.
+ * A missing or blank name returns `undefined`, so spreading is always safe.
  */
 export function styleGroup(
   name: string,

package/dist/navigation.cjs

@@ -281,7 +281,9 @@ function resolveSidebarTokens(theme) {
 }
 
 /**
- * The top app bar's surface, its two text colours and its opt-in divider.
+ * The top app bar's surface and its two text colours. It has NO divider
+ * (sc-7360): the bar and its tab row sit in one surface, so a stored divider
+ * colour or width on the block is inert on both hosts.
  *
  * `tintColor` and `titleColor` are SEPARATE because the web bar has always
  * painted them differently when the author names nothing: the hamburger and
@@ -295,13 +297,11 @@ function resolveSidebarTokens(theme) {
  * @param {unknown} theme — the whole `theme_config`; the app's
  *   `backgroundColor`/`backgroundGradient` are read because an unset surface
  *   resolves to the page's, as an `attached` tab's already did (sc-6596).
- * @returns {{ backgroundColor: string, tintColor: string, titleColor: string,
- *   borderColor: string|null, borderWidth: number|null }}
+ * @returns {{ backgroundColor: string, tintColor: string, titleColor: string }}
  */
 function resolveTopBarTokens(theme) {
   const config = isPlainObject(theme) ? theme : {};
   const topBar = isPlainObject(config.topBar) ? config.topBar : {};
-  const borderColor = hexOrNull(topBar.borderColor);
   // An explicit colour drives BOTH slots; only the unset case splits.
   const authored = hexOrNull(topBar.textColor);
   return {
@@ -324,13 +324,10 @@ function resolveTopBarTokens(theme) {
       topBar.activeColor,
       hexOr(sidebarBlock(config).activeColor, brandPrimary(config)),
     ),
-    borderColor,
-    borderWidth: borderColor ? borderWidthOr(topBar.borderWidth) : null,
     // REQ-NAV-STRUCTURE: how the tab row marks its current page.
     // `underline` keeps the tab in the bar's surface and marks it with an
     // indicator. `attached` makes it a real folder tab: it takes the CONTENT's
-    // surface and sits over the row's divider, so the tab and the page beneath
-    // read as one plane. Meaningless on a shape that draws no tab row — a host
+    // surface and meets the page beneath it, so the two read as one plane. Meaningless on a shape that draws no tab row — a host
     // reads it only where it has tabs to draw.
     tabStyle: topBar.tabStyle === "attached" ? "attached" : "underline",
     // The surface an `attached` tab AND its content panel share. One value for

package/dist/navigation.js

@@ -272,7 +272,9 @@ export function resolveSidebarTokens(theme) {
 }
 
 /**
- * The top app bar's surface, its two text colours and its opt-in divider.
+ * The top app bar's surface and its two text colours. It has NO divider
+ * (sc-7360): the bar and its tab row sit in one surface, so a stored divider
+ * colour or width on the block is inert on both hosts.
  *
  * `tintColor` and `titleColor` are SEPARATE because the web bar has always
  * painted them differently when the author names nothing: the hamburger and
@@ -286,13 +288,11 @@ export function resolveSidebarTokens(theme) {
  * @param {unknown} theme — the whole `theme_config`; the app's
  *   `backgroundColor`/`backgroundGradient` are read because an unset surface
  *   resolves to the page's, as an `attached` tab's already did (sc-6596).
- * @returns {{ backgroundColor: string, tintColor: string, titleColor: string,
- *   borderColor: string|null, borderWidth: number|null }}
+ * @returns {{ backgroundColor: string, tintColor: string, titleColor: string }}
  */
 export function resolveTopBarTokens(theme) {
   const config = isPlainObject(theme) ? theme : {};
   const topBar = isPlainObject(config.topBar) ? config.topBar : {};
-  const borderColor = hexOrNull(topBar.borderColor);
   // An explicit colour drives BOTH slots; only the unset case splits.
   const authored = hexOrNull(topBar.textColor);
   return {
@@ -315,13 +315,10 @@ export function resolveTopBarTokens(theme) {
       topBar.activeColor,
       hexOr(sidebarBlock(config).activeColor, brandPrimary(config)),
     ),
-    borderColor,
-    borderWidth: borderColor ? borderWidthOr(topBar.borderWidth) : null,
     // REQ-NAV-STRUCTURE: how the tab row marks its current page.
     // `underline` keeps the tab in the bar's surface and marks it with an
     // indicator. `attached` makes it a real folder tab: it takes the CONTENT's
-    // surface and sits over the row's divider, so the tab and the page beneath
-    // read as one plane. Meaningless on a shape that draws no tab row — a host
+    // surface and meets the page beneath it, so the two read as one plane. Meaningless on a shape that draws no tab row — a host
     // reads it only where it has tabs to draw.
     tabStyle: topBar.tabStyle === "attached" ? "attached" : "underline",
     // The surface an `attached` tab AND its content panel share. One value for

package/dist/style-group.js

@@ -1,6 +1,9 @@
-// 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.
+// 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
@@ -16,11 +19,10 @@
 export const STYLE_GROUP_DATA_KEY = "styleGroup";
 
 /**
- * Props marking the element a style group paints. Spread it:
- * `<View {...styleGroup("Card")}>`.
+ * @deprecated (sc-7344) — inert; nothing reads the marker.
  *
- * `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.
+ * 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.130.0",
+  "version": "0.132.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",