@colixsystems/widget-sdk 0.270.0 → 0.271.0

package/README.md

@@ -86,7 +86,11 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.270.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.271.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.271.0 (contract 1.221.0)
+
+**Basic styling in one call.** Spread `BASIC_STYLE_SCHEMA` into `manifest.styleSchema` and call `basicStyle(style)` in the component: the five basic style fields (`background`, `textColor`, `align`, `padding`, `margin`) are declared and applied without wiring each by hand. See *Basic styling* under *Design & visual polish*.
 
 ### What's new in 0.270.0 (contract 1.220.0)
 
@@ -3345,6 +3349,22 @@ A widget that works but looks unfinished is only half done. `useTheme()` is the
 
 **Decide before you build:** the widget's shape (card, list, form, control), its hierarchy (the one thing the eye lands on first), its single accent moment, and its empty/loading/error look — then compose. Specific decisions make a distinctive widget; leaving them to default makes a generic one.
 
+- **Basic styling: one schema, one call.** Every generated widget offers five whole-widget style fields: `background`, `textColor`, `align`, `padding` and `margin`. Spread `BASIC_STYLE_SCHEMA` into your manifest's `styleSchema`, then apply them with `basicStyle(style)`. It returns `{ root, text }`: spread `root` on the outermost `View` (background, align as `alignItems`, per-side padding and margin) and `text` on each `Text` in a theme text colour. A field the author left unset emits nothing, so your theme-based styles show through. `appstudio-widget lint` counts the call as reading all five. When `submit_widget_source` or the Studio's widget builder publishes a widget that calls `basicStyle()`, any of the five its manifest leaves out is declared for it.
+
+  ```jsx
+  import { View, Text, basicStyle, BASIC_STYLE_SCHEMA } from "@colixsystems/widget-sdk";
+
+  export const manifest = { /* … */ styleSchema: { ...BASIC_STYLE_SCHEMA, titleColor: { type: "color", label: "Title", ui: { group: "Title" } } } };
+
+  export default function Hero({ title, style = {} }) {
+    const basic = basicStyle(style);
+    return (
+      <View style={[styles.root, basic.root]}>
+        <Text style={[styles.title, basic.text, style.titleColor && { color: style.titleColor }]}>{title}</Text>
+      </View>
+    );
+  }
+  ```
 - **Pull spacing and corners from tokens.** Use `theme.spacing` (`xs / sm / md / lg / xl`) for a consistent padding and gap rhythm, and `theme.radii` (`sm / md / lg / pill`) for corners — `radii.lg` for cards and hero surfaces, `radii.md` for controls nested inside one. Don't hardcode raw pixel values.
 - **Build a hierarchy.** A clear title (large, bold, `colors.onSurface`), body text, and muted captions in `colors.onSurfaceMuted` — three weights, not one flat size. Reserve full-strength `colors.primary` (with `colors.onPrimary` for text on it) for the single most important action or metric.
 - **Style text by its ROLE, not by inventing a size and weight.** `theme.typography.roles` carries the workspace's type scale as six semantic tiers — `display`, `title`, `subtitle`, `body`, `caption`, `overline` — each already resolved to a `fontSize`, `fontWeight`, `fontStyle`, `lineHeight` (a MULTIPLE of the size), `letterSpacing`, `textTransform` and a `colorToken`. Pick the tier the text IS, rather than choosing `fontSize: 16, fontWeight: "600"` yourself: your widget's section title is `title`, each card or row title is `subtitle`, running text is `body`, timestamps and helper text are `caption`, a small kicker or column label is `overline`, and a headline stat is `display`. This is what stops one widget rendering a subtitle bold while the widget beside it renders one italic, and it lets the workspace re-tune every subtitle in the app from Theme Settings in one edit. **Two tokens need converting rather than copying** — `lineHeight` is a multiple (React Native wants absolute pixels, so the raw `1.15` gives you a one-pixel line box) and `colorToken` names a colour rather than being one:

package/dist/basic-style.js

@@ -0,0 +1,37 @@
+// The five style fields every generated widget declares, in one call: spread
+// BASIC_STYLE_SCHEMA into `manifest.styleSchema`, apply `basicStyle(style)`.
+// Platform-free, so the web and native entries export this one module.
+
+import { CONTRACT } from "./contract.js";
+import { spacingOverlay } from "./card-style.js";
+
+export const BASIC_STYLE_SCHEMA = CONTRACT.basicStyleSchema;
+
+const ALIGN_ITEMS = Object.freeze({
+  left: "flex-start",
+  center: "center",
+  right: "flex-end",
+});
+
+/**
+ * The basic style fields as React Native styles. Each is emitted only when the
+ * author set it, so the widget's own theme-based styles show through.
+ *
+ * @param {object} [style] the widget's `props.style`
+ * @returns {{ root: object, text: object|null }} `root` for the outermost
+ *   View (backgroundColor, alignItems, padding, margin); `text` (`{ color }`)
+ *   for each Text coloured by a theme text token.
+ */
+export function basicStyle(style) {
+  const s = style || {};
+  const alignItems = ALIGN_ITEMS[s.align];
+  return {
+    root: {
+      ...(s.background ? { backgroundColor: s.background } : null),
+      ...(alignItems ? { alignItems } : null),
+      ...spacingOverlay(s.padding, "padding"),
+      ...spacingOverlay(s.margin, "margin"),
+    },
+    text: s.textColor ? { color: s.textColor } : null,
+  };
+}

package/dist/contract.cjs

@@ -389,6 +389,38 @@ const THEME_SPACING_SCALE = Object.freeze({
   default: 1,
 });
 
+// The style fields every generated widget declares, with the controls the
+// Studio renders for them. One source for `BASIC_STYLE_SCHEMA` /
+// `basicStyle()`, the linter, the publish gate and the Mason plan gate.
+const BASIC_STYLE_GROUP = Object.freeze({ group: "Basics" });
+const BASIC_SPACING_RANGE = Object.freeze({ min: 0, max: 64 });
+const BASIC_STYLE_SCHEMA = Object.freeze({
+  background: Object.freeze({ type: "color", label: "Background", ui: BASIC_STYLE_GROUP }),
+  textColor: Object.freeze({ type: "color", label: "Text color", ui: BASIC_STYLE_GROUP }),
+  align: Object.freeze({
+    type: "select",
+    label: "Align",
+    enum: Object.freeze([
+      Object.freeze({ value: "left", label: "Left" }),
+      Object.freeze({ value: "center", label: "Center" }),
+      Object.freeze({ value: "right", label: "Right" }),
+    ]),
+    ui: BASIC_STYLE_GROUP,
+  }),
+  padding: Object.freeze({
+    type: "spacing",
+    label: "Padding",
+    validation: BASIC_SPACING_RANGE,
+    ui: BASIC_STYLE_GROUP,
+  }),
+  margin: Object.freeze({
+    type: "spacing",
+    label: "Margin",
+    validation: BASIC_SPACING_RANGE,
+    ui: BASIC_STYLE_GROUP,
+  }),
+});
+
 // The card-surface field names shared by every widget that paints its own card
 // (frontend/src/components/widgets/_shared/cardStyle.js CARD_STYLE_SCHEMA).
 const CARD_SURFACE_FIELDS = Object.freeze({
@@ -6508,7 +6540,9 @@ const CONTRACT = deepFreeze({
   //    every query, record, figure and aggregate on that table, app-wide.
   // 1.220.0: additive (sc-14423) — `live: true` on useDatastoreQuery,
   //    useDatastoreRecord, useDatastoreFigure and useDatastoreAggregate.
-  version: "1.220.0",
+  // 1.221.0: additive (sc-14460) — `basicStyleSchema`, exported as
+  //    `BASIC_STYLE_SCHEMA`, and `basicStyle(style)`, which applies it.
+  version: "1.221.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -6533,6 +6567,7 @@ const CONTRACT = deepFreeze({
   themeSpacingScale: THEME_SPACING_SCALE,
   themeMenuTypes: THEME_MENU_TYPES,
   themeWidgetStyles: THEME_WIDGET_STYLES,
+  basicStyleSchema: BASIC_STYLE_SCHEMA,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,
   // sc-10829 — the hook a `badgeCounter: true` entry exports by name.

package/dist/contract.js

@@ -386,6 +386,38 @@ const THEME_SPACING_SCALE = Object.freeze({
   default: 1,
 });
 
+// The style fields every generated widget declares, with the controls the
+// Studio renders for them. One source for `BASIC_STYLE_SCHEMA` /
+// `basicStyle()`, the linter, the publish gate and the Mason plan gate.
+const BASIC_STYLE_GROUP = Object.freeze({ group: "Basics" });
+const BASIC_SPACING_RANGE = Object.freeze({ min: 0, max: 64 });
+const BASIC_STYLE_SCHEMA = Object.freeze({
+  background: Object.freeze({ type: "color", label: "Background", ui: BASIC_STYLE_GROUP }),
+  textColor: Object.freeze({ type: "color", label: "Text color", ui: BASIC_STYLE_GROUP }),
+  align: Object.freeze({
+    type: "select",
+    label: "Align",
+    enum: Object.freeze([
+      Object.freeze({ value: "left", label: "Left" }),
+      Object.freeze({ value: "center", label: "Center" }),
+      Object.freeze({ value: "right", label: "Right" }),
+    ]),
+    ui: BASIC_STYLE_GROUP,
+  }),
+  padding: Object.freeze({
+    type: "spacing",
+    label: "Padding",
+    validation: BASIC_SPACING_RANGE,
+    ui: BASIC_STYLE_GROUP,
+  }),
+  margin: Object.freeze({
+    type: "spacing",
+    label: "Margin",
+    validation: BASIC_SPACING_RANGE,
+    ui: BASIC_STYLE_GROUP,
+  }),
+});
+
 // The card-surface field names shared by every widget that paints its own card
 // (frontend/src/components/widgets/_shared/cardStyle.js CARD_STYLE_SCHEMA).
 const CARD_SURFACE_FIELDS = Object.freeze({
@@ -6505,7 +6537,9 @@ const CONTRACT = deepFreeze({
   //    every query, record, figure and aggregate on that table, app-wide.
   // 1.220.0: additive (sc-14423) — `live: true` on useDatastoreQuery,
   //    useDatastoreRecord, useDatastoreFigure and useDatastoreAggregate.
-  version: "1.220.0",
+  // 1.221.0: additive (sc-14460) — `basicStyleSchema`, exported as
+  //    `BASIC_STYLE_SCHEMA`, and `basicStyle(style)`, which applies it.
+  version: "1.221.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -6530,6 +6564,7 @@ const CONTRACT = deepFreeze({
   themeSpacingScale: THEME_SPACING_SCALE,
   themeMenuTypes: THEME_MENU_TYPES,
   themeWidgetStyles: THEME_WIDGET_STYLES,
+  basicStyleSchema: BASIC_STYLE_SCHEMA,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,
   // sc-10829 — the hook a `badgeCounter: true` entry exports by name.

package/dist/index.d.ts

@@ -5576,6 +5576,27 @@ export function roleColor(tokens: any, colors: any): string | undefined;
  */
 export function textRoleStyle(role: TextRole | string, typography: any, colors?: any): Record<string, any>;
 
+/**
+ * The five style fields every generated widget declares — `background`,
+ * `textColor`, `align`, `padding` and `margin` — as styleSchema entries.
+ * Spread it into `manifest.styleSchema`; `basicStyle()` applies it.
+ */
+export const BASIC_STYLE_SCHEMA: Readonly<WidgetPropertySchema>;
+/**
+ * The basic style fields as React Native styles, each only when set. Spread
+ * `root` on the outermost View and `text` on each Text in a theme text colour.
+ *
+ * @example
+ *   const basic = basicStyle(style);
+ *   <View style={[styles.root, basic.root]}>
+ *     <Text style={[styles.title, basic.text]}>{title}</Text>
+ *   </View>
+ */
+export function basicStyle(style?: Record<string, any> | null): {
+  root: Record<string, any>;
+  text: { color: string } | null;
+};
+
 // ----------------------------------------------------- formatted content
 // sc-6970 — widgets have no HTML path: they render through React Native
 // primitives, which have no `dangerouslySetInnerHTML` on either host. Content

package/dist/index.js

@@ -268,6 +268,8 @@ export {
   gradientProps,
   cardGradientProps,
 } from "./card-style.js";
+// The five style fields every generated widget declares, in one call.
+export { BASIC_STYLE_SCHEMA, basicStyle } from "./basic-style.js";
 // The themed button; follows the theme's button, destructive and ring scopes.
 export { Button, IconButton, BUTTON_VARIANTS } from "./button.js";
 export {

package/dist/index.native.js

@@ -261,6 +261,8 @@ export {
   gradientProps,
   cardGradientProps,
 } from "./card-style.js";
+// The five style fields every generated widget declares, in one call.
+export { BASIC_STYLE_SCHEMA, basicStyle } from "./basic-style.js";
 // The themed button; follows the theme's button, destructive and ring scopes.
 export { Button, IconButton, BUTTON_VARIANTS } from "./button.native.js";
 export {

package/dist/linter.cjs

@@ -1946,11 +1946,15 @@ function lintStyleWiring(manifest, files) {
   const code = sources
     .map((s) => _stripNonCode(s, { keepStrings: true }))
     .join("\n");
+  const appliedByHelper = callsBasicStyle(sources)
+    ? _WHOLE_WIDGET_STYLE_FIELDS
+    : new Set();
   const findings = [];
   for (const field of Object.keys(schema)) {
     // A key that is not a bare identifier cannot be scanned by name; the
     // manifest validator rejects those anyway.
     if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(field)) continue;
+    if (appliedByHelper.has(field)) continue;
     if (new RegExp(`\\b${field}\\b`).test(code)) continue;
     findings.push({
       rule: "style-field-unread",
@@ -1961,7 +1965,8 @@ function lintStyleWiring(manifest, files) {
         `— per instance, and app-wide under Design -> Widget appearance — ` +
         `moves nothing. Read it from props.style and apply it ONLY when ` +
         `set, so the theme still shows through while the author has chosen ` +
-        `none. If it is not styleable, drop it from styleSchema instead.`,
+        `none. If it is not styleable, drop it from styleSchema instead.` +
+        (_WHOLE_WIDGET_STYLE_FIELDS.has(field) ? _BASIC_STYLE_FIX : ""),
       line: 0,
       snippet: field,
     });
@@ -1970,6 +1975,26 @@ function lintStyleWiring(manifest, files) {
   return { ok: !hasErrors, findings };
 }
 
+const _BASIC_STYLE_CALL = /\bbasicStyle\s*\(/;
+
+const _BASIC_STYLE_FIX =
+  ` The one-line fix for every basic field: basicStyle(props.style) from ` +
+  `@colixsystems/widget-sdk — spread its .root on the outermost View and ` +
+  `its .text on each Text in a theme text colour.`;
+
+/**
+ * Whether the bundle calls `basicStyle()`, which applies every basic style
+ * field (`CONTRACT.basicStyleSchema`) in one call.
+ *
+ * @param {object|string[]|string} files bundle sources, as `lintStyleWiring` takes them
+ * @returns {boolean}
+ */
+function callsBasicStyle(files) {
+  return _bundleSources(files).some((s) =>
+    _BASIC_STYLE_CALL.test(_stripNonCode(s)),
+  );
+}
+
 // sc-7799 — a group name that groups everything defeats the rule: one
 // catch-all fieldset reads exactly like the flat list it replaced.
 const _GENERIC_STYLE_GROUPS = new Set([
@@ -1982,16 +2007,9 @@ const _GENERIC_STYLE_GROUPS = new Set([
 ]);
 
 // The five the basic-style gate mandates; they restyle the widget as a whole.
-// Lockstep with BASIC_STYLE_FIELDS (backend/src/core/services/widget-basic-style.ts)
-// — a mandated field missing here reads as per-element coverage the widget does
-// not have, which silently retires this rule for EVERY generated widget.
-const _WHOLE_WIDGET_STYLE_FIELDS = new Set([
-  "background",
-  "textColor",
-  "align",
-  "padding",
-  "margin",
-]);
+const _WHOLE_WIDGET_STYLE_FIELDS = new Set(
+  Object.keys(CONTRACT.basicStyleSchema),
+);
 
 // A second element an author would style apart from the text. Pressable and
 // Button are deliberately absent: a touch target wrapping the only label is
@@ -2385,6 +2403,7 @@ function lintSource(source, options) {
 module.exports = {
   lintSource,
   lintStyleWiring,
+  callsBasicStyle,
   lintEditability,
   bannedIdentifiers,
   narrowManifestForFile,

package/dist/linter.js

@@ -2009,11 +2009,15 @@ export function lintStyleWiring(manifest, files) {
   const code = sources
     .map((s) => _stripNonCode(s, { keepStrings: true }))
     .join("\n");
+  const appliedByHelper = callsBasicStyle(sources)
+    ? _WHOLE_WIDGET_STYLE_FIELDS
+    : new Set();
   const findings = [];
   for (const field of Object.keys(schema)) {
     // A key that is not a bare identifier cannot be scanned by name; the
     // manifest validator rejects those anyway.
     if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(field)) continue;
+    if (appliedByHelper.has(field)) continue;
     if (new RegExp(`\\b${field}\\b`).test(code)) continue;
     findings.push({
       rule: "style-field-unread",
@@ -2024,7 +2028,8 @@ export function lintStyleWiring(manifest, files) {
         `— per instance, and app-wide under Design -> Widget appearance — ` +
         `moves nothing. Read it from props.style and apply it ONLY when ` +
         `set, so the theme still shows through while the author has chosen ` +
-        `none. If it is not styleable, drop it from styleSchema instead.`,
+        `none. If it is not styleable, drop it from styleSchema instead.` +
+        (_WHOLE_WIDGET_STYLE_FIELDS.has(field) ? _BASIC_STYLE_FIX : ""),
       line: 0,
       snippet: field,
     });
@@ -2033,6 +2038,26 @@ export function lintStyleWiring(manifest, files) {
   return { ok: !hasErrors, findings };
 }
 
+const _BASIC_STYLE_CALL = /\bbasicStyle\s*\(/;
+
+const _BASIC_STYLE_FIX =
+  ` The one-line fix for every basic field: basicStyle(props.style) from ` +
+  `@colixsystems/widget-sdk — spread its .root on the outermost View and ` +
+  `its .text on each Text in a theme text colour.`;
+
+/**
+ * Whether the bundle calls `basicStyle()`, which applies every basic style
+ * field (`CONTRACT.basicStyleSchema`) in one call.
+ *
+ * @param {object|string[]|string} files bundle sources, as `lintStyleWiring` takes them
+ * @returns {boolean}
+ */
+export function callsBasicStyle(files) {
+  return _bundleSources(files).some((s) =>
+    _BASIC_STYLE_CALL.test(_stripNonCode(s)),
+  );
+}
+
 // sc-7799 — a group name that groups everything defeats the rule: one
 // catch-all fieldset reads exactly like the flat list it replaced.
 const _GENERIC_STYLE_GROUPS = new Set([
@@ -2045,16 +2070,9 @@ const _GENERIC_STYLE_GROUPS = new Set([
 ]);
 
 // The five the basic-style gate mandates; they restyle the widget as a whole.
-// Lockstep with BASIC_STYLE_FIELDS (backend/src/core/services/widget-basic-style.ts)
-// — a mandated field missing here reads as per-element coverage the widget does
-// not have, which silently retires this rule for EVERY generated widget.
-const _WHOLE_WIDGET_STYLE_FIELDS = new Set([
-  "background",
-  "textColor",
-  "align",
-  "padding",
-  "margin",
-]);
+const _WHOLE_WIDGET_STYLE_FIELDS = new Set(
+  Object.keys(CONTRACT.basicStyleSchema),
+);
 
 // A second element an author would style apart from the text. Pressable and
 // Button are deliberately absent: a touch target wrapping the only label is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.270.0",
+  "version": "0.271.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

@@ -386,6 +386,38 @@ const THEME_SPACING_SCALE = Object.freeze({
   default: 1,
 });
 
+// The style fields every generated widget declares, with the controls the
+// Studio renders for them. One source for `BASIC_STYLE_SCHEMA` /
+// `basicStyle()`, the linter, the publish gate and the Mason plan gate.
+const BASIC_STYLE_GROUP = Object.freeze({ group: "Basics" });
+const BASIC_SPACING_RANGE = Object.freeze({ min: 0, max: 64 });
+const BASIC_STYLE_SCHEMA = Object.freeze({
+  background: Object.freeze({ type: "color", label: "Background", ui: BASIC_STYLE_GROUP }),
+  textColor: Object.freeze({ type: "color", label: "Text color", ui: BASIC_STYLE_GROUP }),
+  align: Object.freeze({
+    type: "select",
+    label: "Align",
+    enum: Object.freeze([
+      Object.freeze({ value: "left", label: "Left" }),
+      Object.freeze({ value: "center", label: "Center" }),
+      Object.freeze({ value: "right", label: "Right" }),
+    ]),
+    ui: BASIC_STYLE_GROUP,
+  }),
+  padding: Object.freeze({
+    type: "spacing",
+    label: "Padding",
+    validation: BASIC_SPACING_RANGE,
+    ui: BASIC_STYLE_GROUP,
+  }),
+  margin: Object.freeze({
+    type: "spacing",
+    label: "Margin",
+    validation: BASIC_SPACING_RANGE,
+    ui: BASIC_STYLE_GROUP,
+  }),
+});
+
 // The card-surface field names shared by every widget that paints its own card
 // (frontend/src/components/widgets/_shared/cardStyle.js CARD_STYLE_SCHEMA).
 const CARD_SURFACE_FIELDS = Object.freeze({
@@ -6505,7 +6537,9 @@ const CONTRACT = deepFreeze({
   //    every query, record, figure and aggregate on that table, app-wide.
   // 1.220.0: additive (sc-14423) — `live: true` on useDatastoreQuery,
   //    useDatastoreRecord, useDatastoreFigure and useDatastoreAggregate.
-  version: "1.220.0",
+  // 1.221.0: additive (sc-14460) — `basicStyleSchema`, exported as
+  //    `BASIC_STYLE_SCHEMA`, and `basicStyle(style)`, which applies it.
+  version: "1.221.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -6530,6 +6564,7 @@ const CONTRACT = deepFreeze({
   themeSpacingScale: THEME_SPACING_SCALE,
   themeMenuTypes: THEME_MENU_TYPES,
   themeWidgetStyles: THEME_WIDGET_STYLES,
+  basicStyleSchema: BASIC_STYLE_SCHEMA,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,
   // sc-10829 — the hook a `badgeCounter: true` entry exports by name.