@colixsystems/widget-sdk 0.74.0 → 0.76.0

package/README.md

@@ -54,7 +54,28 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.74.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.76.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.76.0
+
+**`themeDefault` publishes the value a style field falls back to (sc-4164).** An unset `styleSchema` field rendered as an empty box, so an author adjusting `Title size` could not see the size they were changing. `WidgetPropertyDef` now documents the key the Studio has read since sc-1807:
+
+- **`themeDefault: "<dotted path into the resolved widget theme>"`** — e.g. `"typography.sizes.lg"`, `"radii.md"`, `"colors.onSurface"`. The Studio renders it as greyed placeholder text, resolved against the **workspace's** theme, so the hint stays truthful after a rebrand. Prefer it over a literal `default` whenever your fallback is a theme token — which it usually is, since you style from `useTheme()`.
+- **A literal `default`** still works and is the right choice for a hard-coded constant your code carries (`default: 1.4` for a line height you wrote yourself).
+- **Both are DISPLAY-ONLY.** Neither is ever written into `props.style`, so a style field keeps its only-when-set contract and continues to inherit the theme. Declare the value your code actually applies — a baseline that disagrees with the render is worse than none.
+- **Optional.** A field whose fallback has no fixed value (a `background` that inherits whatever the container paints) declares neither and renders blank.
+
+Types-only addition: no export, runtime behaviour, or `CONTRACT` field changed; `CONTRACT.version` stays `1.51.0`.
+
+### What's new in 0.75.0
+
+**`ui.group: "Basics"` marks a widget's quick style knobs (sc-4100).** A `styleSchema` field has always accepted the `propertySchema` `ui.group` key; the Studio now reads one reserved group name from it, so a widget with several styleable elements can expose per-element controls without burying the two or three an author reaches for first.
+
+- **Group every style field, or none of them.** In a grouped `styleSchema`, put the whole-widget basics (`background`, `textColor`, `align`) under the exact group `"Basics"` and each per-element field under a group named for the element it styles (`"Card"`, `"Title"`, `"Chip"`, …). Keep the total under about 12 fields.
+- **Where each surface renders.** The Builder's Properties panel renders **every** group. Agent Mode's in-preview edit panel — a quick-tweak surface — renders **only** `"Basics"` and points the author at the Builder for the rest.
+- **Nothing changes for an ungrouped `styleSchema`.** A flat schema (no `ui.group` anywhere) renders in full in both surfaces exactly as before, so every already-published widget is unaffected. A grouped schema that declares no `"Basics"` group also renders in full — the trim needs a group to trim *to*.
+
+No export, type, hook, or `CONTRACT` field changed; `CONTRACT.version` stays `1.51.0`. This is an additive host convention over an existing manifest key.
 
 ### What's new in 0.74.0
 

package/dist/index.d.ts

@@ -73,6 +73,15 @@ export interface WidgetPropertyDef {
   enum?: Array<{ value: unknown; label: string }>;
   items?: WidgetPropertyDef;
   properties?: Record<string, WidgetPropertyDef>;
+  // sc-1807 / sc-4164 — the value the widget falls back to when this field is
+  // unset, as a dotted path into the resolved widget theme
+  // (`"typography.sizes.lg"`, `"radii.md"`, `"colors.onSurface"`). The Studio
+  // shows it as greyed placeholder text so the author can see what they are
+  // adjusting from; it resolves against the WORKSPACE's theme, so the hint stays
+  // truthful after a rebrand. DISPLAY-ONLY — never written into props.style, so
+  // a styleSchema field keeps its only-when-set contract. Prefer this over a
+  // literal `default` whenever the fallback is a theme token.
+  themeDefault?: string;
   ui?: {
     widget?: "textarea" | "slider" | "code";
     group?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.74.0",
+  "version": "0.76.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",