@colixsystems/widget-sdk 0.75.0 → 0.77.0

package/README.md

@@ -54,14 +54,36 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.75.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.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**.
+
+### What's new in 0.77.0
+
+**`ui.group` is a layout hint, not a visibility rule (sc-4176).** 0.75.0 gave `"Basics"` a reserved meaning: Agent Mode's in-preview edit panel rendered only that group and pointed the author at the Builder for the rest. That withheld styling from an author already editing the widget in front of them, so the reserved behaviour is **retired**.
+
+- **Both Style surfaces now render your whole `styleSchema`** — the Builder's Properties panel and the in-preview edit panel show the same fields, as one labelled fieldset per group.
+- **Keep grouping.** It is what makes a 10–12 field Style section readable: "Basics / Card / Title" is three scannable decisions where a flat list is a wall of inputs. Group all your fields or none, name each group after an element the author can see, and keep `"Basics"` for the three whole-widget fields so they read first.
+- **No group name is special any more.** Nothing you put in — or leave out of — a group changes whether an author can reach a field. Do not try to hide an advanced knob by grouping it.
+- **Nothing else changes.** `themeDefault` / `default` placeholders (0.76.0) apply to every field in every group, and an ungrouped `styleSchema` renders exactly as it always has.
+
+Docs-only correction of documented host behaviour: no export, type, runtime, or `CONTRACT` field changed; `CONTRACT.version` stays `1.51.0`.
+
+### 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.
+- **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.~~ **Superseded in 0.77.0:** both surfaces render every group. `ui.group` is a layout hint, not a visibility rule.
 - **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.

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.75.0",
+  "version": "0.77.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",