@colixsystems/widget-sdk 0.250.0 → 0.251.0

package/README.md

@@ -84,7 +84,14 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.250.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.251.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.251.0 (contract 1.205.0)
+
+**A text property's default is real, editable text in the Studio.** The Properties panel used to show a `string` property's `default` as a grey placeholder, so authors took it for a hint and never edited the text the widget actually rendered. It now shows the default as the field's own value. It is still not written until the author edits, so an untouched field keeps following the manifest. Clearing a field that shows a default stores `""`. Your widget gets an empty string and should render it as empty, so read text props with `??`, not `||`. Two `ui` hints are now typed:
+
+- `ui.placeholder` — a grey hint shown while the field is empty.
+- `ui.clearRestoresDefault: true` — clearing brings the default back instead of storing `""`. Use it for a caption that must never render blank, such as a button label.
 
 ### What's new in 0.250.0 (contract 1.204.0)
 
@@ -2089,7 +2096,7 @@ const style = useWidgetStyle();
 <View style={[styles.card, style.cardBackground && { backgroundColor: style.cardBackground }]}>
 ```
 
-Keep `themeDefault` for a fallback that IS a theme token: it stays display-only (a greyed placeholder in the Style panel) so the field tracks the workspace theme. Use `default` for a literal constant your code genuinely falls back to — that value now reaches `props.style`, so it must match what your code applies.
+Keep `themeDefault` for a fallback that IS a theme token: it stays display-only (shown in the Style panel field, never written) so the field tracks the workspace theme. Use `default` for a literal constant your code genuinely falls back to — that value now reaches `props.style`, so it must match what your code applies.
 
 ### What's new in 0.117.0 (contract 1.89.0)
 
@@ -2609,7 +2616,7 @@ Docs-only correction of documented host behaviour: no export, type, runtime, or
 
 **`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()`.
+- **`themeDefault: "<dotted path into the resolved widget theme>"`** — e.g. `"typography.sizes.lg"`, `"radii.md"`, `"colors.onSurface"`. The Studio shows it in the field, 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.

package/dist/contract.cjs

@@ -6332,7 +6332,10 @@ const CONTRACT = deepFreeze({
   //    `field-in-bordered-row`, `field-trailing-press-unnamed`.
   // 1.204.0: additive (sc-12244) — `<DataTable showHeader>` (default true);
   //    false drops the wide layout's header row and its sticky index.
-  version: "1.204.0",
+  // 1.205.0: additive (sc-11840) — a string property's `default` shows as the
+  //    field's editable text and clearing stores ""; `ui.placeholder` and
+  //    `ui.clearRestoresDefault` are typed.
+  version: "1.205.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -6328,7 +6328,10 @@ const CONTRACT = deepFreeze({
   //    `field-in-bordered-row`, `field-trailing-press-unnamed`.
   // 1.204.0: additive (sc-12244) — `<DataTable showHeader>` (default true);
   //    false drops the wide layout's header row and its sticky index.
-  version: "1.204.0",
+  // 1.205.0: additive (sc-11840) — a string property's `default` shows as the
+  //    field's editable text and clearing stores ""; `ui.placeholder` and
+  //    `ui.clearRestoresDefault` are typed.
+  version: "1.205.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/index.d.ts

@@ -87,8 +87,8 @@ export interface 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
+  // shows it in the field (a greyed hint for colours) 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.
@@ -106,6 +106,11 @@ export interface WidgetPropertyDef {
     // a static `default`). Today: `"tabId"` → seed a unique stable id
     // for newly added Tab Layout tabs.
     defaultFactory?: "tabId";
+    // string: a grey hint shown while the field is empty.
+    placeholder?: string;
+    // string: clearing restores `default` instead of storing "" — for a
+    // caption that must never render blank (a button label).
+    clearRestoresDefault?: boolean;
   };
   validation?: { min?: number; max?: number; pattern?: string };
 }

package/package.json

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

package/src/contract.js

@@ -6328,7 +6328,10 @@ const CONTRACT = deepFreeze({
   //    `field-in-bordered-row`, `field-trailing-press-unnamed`.
   // 1.204.0: additive (sc-12244) — `<DataTable showHeader>` (default true);
   //    false drops the wide layout's header row and its sticky index.
-  version: "1.204.0",
+  // 1.205.0: additive (sc-11840) — a string property's `default` shows as the
+  //    field's editable text and clearing stores ""; `ui.placeholder` and
+  //    `ui.clearRestoresDefault` are typed.
+  version: "1.205.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,