@colixsystems/widget-sdk 0.231.0 → 0.232.0

package/README.md

@@ -84,7 +84,11 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.231.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.232.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.232.0 (contract 1.187.0)
+
+**The app's bottom navigation bar floats by default (host side only).** `resolveFooterTokens` from `@colixsystems/widget-sdk/host` now also resolves the bar's shape: `shape` is `"floating"` (a rounded bar inset from the screen's sides, with the page visible around and beneath it) unless the theme's `footer.shape` is `"docked"` (the edge-to-edge strip). `radius` (0–40, default 28), `sideMargin` (0–48, default 12) and `bottomSpacing` (0–32, default 8) are px, clamped onto their ranges, and `itemRadius` is a tab's corner radius inside that bar. `FOOTER_SIZES` exports each measurement's bound and default, `clampFooterSize(value, key)` clamps one onto it, and `FOOTER_HOME_LINE_CLEARANCE_PX` (14) is how much of the iOS bottom inset a bar keeps clear. Nothing a widget imports changes.
 
 ### What's new in 0.231.0 (contract 1.186.0)
 

package/dist/contract.cjs

@@ -6040,7 +6040,11 @@ const CONTRACT = deepFreeze({
   //    `fitScreenFoot` host hint: a self-scrolling Fit to screen surface that
   //    calls it runs under the bottom safe area on native and pads its
   //    controls by it. Hosts without the hint read zeros.
-  version: "1.186.0",
+  // 1.187.0: additive (sc-11678) — `resolveFooterTokens` gains the bottom
+  //    bar's `shape` (unset floats), `radius`, `itemRadius`, `sideMargin` and
+  //    `bottomSpacing`; host exports `FOOTER_SIZES`, `clampFooterSize` and
+  //    `FOOTER_HOME_LINE_CLEARANCE_PX`. No widget-facing surface changes.
+  version: "1.187.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -6036,7 +6036,11 @@ const CONTRACT = deepFreeze({
   //    `fitScreenFoot` host hint: a self-scrolling Fit to screen surface that
   //    calls it runs under the bottom safe area on native and pads its
   //    controls by it. Hosts without the hint read zeros.
-  version: "1.186.0",
+  // 1.187.0: additive (sc-11678) — `resolveFooterTokens` gains the bottom
+  //    bar's `shape` (unset floats), `radius`, `itemRadius`, `sideMargin` and
+  //    `bottomSpacing`; host exports `FOOTER_SIZES`, `clampFooterSize` and
+  //    `FOOTER_HOME_LINE_CLEARANCE_PX`. No widget-facing surface changes.
+  version: "1.187.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/host.d.ts

@@ -265,8 +265,36 @@ export interface FooterTokens {
   /** The active tab's surface, or `null` for none — which is what "accent"
    *  resolves to unless the author names one. */
   activeSurface: string | null;
+  /** sc-11678: a rounded bar inset from the screen's sides, the page showing
+   *  around and beneath it, or the edge-to-edge strip. Unset is "floating". */
+  shape: "floating" | "docked";
+  /** A floating bar's corner radius, px (0–40). */
+  radius: number;
+  /** A tab's corner radius, px: a floating bar's curve one row inset in
+   *  (min 6) for a filled tab; 6 for an accent tab or a docked bar. */
+  itemRadius: number;
+  /** A floating bar's distance from the screen's sides, px (0–48). */
+  sideMargin: number;
+  /** Space below the tabs, px (0–32), on top of the system's clearance. */
+  bottomSpacing: number;
 }
 
+/** sc-11678: each bar measurement's upper bound and default, px (min 0). */
+export const FOOTER_SIZES: Readonly<
+  Record<"radius" | "sideMargin" | "bottomSpacing", Readonly<{ max: number; fallback: number }>>
+>;
+
+/** sc-11678: one bar measurement clamped onto its `FOOTER_SIZES` range, or
+ *  `undefined` when the value is not a finite number. */
+export function clampFooterSize(
+  value: unknown,
+  key: "radius" | "sideMargin" | "bottomSpacing",
+): number | undefined;
+
+/** sc-11678: the part of the iOS bottom inset a bar keeps clear (the home
+ *  line's band), px. Android's inset is cleared whole. */
+export const FOOTER_HOME_LINE_CLEARANCE_PX: number;
+
 /**
  * Resolves the footer strip's tokens from a whole `theme_config`. It reads
  * `theme.footer` and NOTHING else (sc-8033): the colours used to fall back to

package/dist/host.js

@@ -92,6 +92,9 @@ export {
   normaliseNavigation,
   menuItemCap,
   resolveFooterTokens,
+  FOOTER_SIZES,
+  clampFooterSize,
+  FOOTER_HOME_LINE_CLEARANCE_PX,
   resolveSidebarTokens,
   resolveTopStripeLayout,
   resolveTopBarTokens,

package/dist/navigation.cjs

@@ -83,10 +83,10 @@ function menuItemCap(menuType) {
 // what each workspace was inheriting, so no shipped app lost its look when the
 // chain went (migration `20260918000000_footer_tokens_uncouple`).
 //
-// The eight authorable keys are the eight controls the Design panel offers, one
-// for one: `backgroundColor`, `textColor`, `tabActiveBackgroundColor`,
+// The authorable keys are the controls the Design panel offers, one for one:
+// `backgroundColor`, `textColor`, `tabActiveBackgroundColor`,
 // `tabActiveTextColor`, `borderColor`, `borderWidth`, `activeStyle`,
-// `tabLayout`.
+// `tabLayout`, and (sc-11678) `shape`, `radius`, `sideMargin`, `bottomSpacing`.
 function resolveFooterTokens(theme) {
   const config = isPlainObject(theme) ? theme : {};
   const footer = isPlainObject(config.footer) ? config.footer : {};
@@ -103,6 +103,8 @@ function resolveFooterTokens(theme) {
   // draw nothing.
   const borderWidth = borderColor ? footerBorderWidthOr(footer.borderWidth) : 0;
   const divider = borderWidth > 0;
+  const floats = footer.shape !== "docked";
+  const radius = footerSizeOr(footer, "radius");
   return {
     backgroundColor: hexOr(footer.backgroundColor, DEFAULT_FOOTER_SURFACE),
     textColor: hexOr(footer.textColor, DEFAULT_CHROME_TEXT),
@@ -128,9 +130,40 @@ function resolveFooterTokens(theme) {
       footer.tabActiveTextColor,
       accent ? brandPrimary(config) : FILLED_TAB_LABEL,
     ),
+    // sc-11678: unset floats, so every app gets the rounded, inset bar.
+    shape: floats ? "floating" : "docked",
+    radius,
+    // A filled tab follows a floating bar's curve one row inset (8px) in,
+    // never sharper than the docked 6px chip. An accent tab paints no surface,
+    // and a curved top edge would bend its marker into an arc.
+    itemRadius:
+      floats && !accent ? Math.max(DOCKED_TAB_RADIUS, radius - 8) : DOCKED_TAB_RADIUS,
+    sideMargin: footerSizeOr(footer, "sideMargin"),
+    bottomSpacing: footerSizeOr(footer, "bottomSpacing"),
   };
 }
 
+// sc-11678: the bar's measurements, in px. `bottomSpacing` sits ABOVE what the
+// system needs (see FOOTER_HOME_LINE_CLEARANCE_PX). Clamped, never dropped.
+const FOOTER_SIZES = Object.freeze({
+  radius: Object.freeze({ max: 40, fallback: 28 }),
+  sideMargin: Object.freeze({ max: 48, fallback: 12 }),
+  bottomSpacing: Object.freeze({ max: 32, fallback: 8 }),
+});
+const DOCKED_TAB_RADIUS = 6;
+function clampFooterSize(value, key) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return undefined;
+  return Math.min(Math.max(Math.round(value), 0), FOOTER_SIZES[key].max);
+}
+function footerSizeOr(footer, key) {
+  return clampFooterSize(footer[key], key) ?? FOOTER_SIZES[key].fallback;
+}
+
+// sc-11678: of the iOS bottom inset, only the home line's band is kept clear;
+// a bar may sit in the rest of it, as Apple's and most apps' tab bars do.
+// Android's inset is its navigation bar, so there the whole inset is cleared.
+const FOOTER_HOME_LINE_CLEARANCE_PX = 14;
+
 // REQ-THEME-14 — the rail's and the app bar's tokens, resolved once for both
 // hosts.
 //
@@ -844,4 +877,4 @@ function borderWidthOr(...values) {
   return BORDER_WIDTH_MIN;
 }
 
-module.exports = { normaliseNavigation, menuItemCap, resolveFooterTokens, resolveSidebarTokens, resolveTopStripeLayout, resolveTopBarTokens, topStripeShowKey, TOP_STRIPE_ALWAYS_SHOWN_SLOTS, TOP_STRIPE_SLOTS, MIN_TOP_STRIPE_HEIGHT_PX, MAX_TOP_STRIPE_HEIGHT_PX, MIN_TOP_STRIPE_PADDING_X_PX, MAX_TOP_STRIPE_PADDING_X_PX, MAX_TOP_STRIPE_OFFSET_Y_PX, DEFAULT_TOP_STRIPE_HEIGHT_PX, DEFAULT_TOP_STRIPE_PADDING_X_PX, resolveSidebarUnfold, resolveLocalNavModel, drawsLocalNavAnywhere, isDarkSurface, resolveAppLogo };
+module.exports = { normaliseNavigation, menuItemCap, resolveFooterTokens, FOOTER_SIZES, clampFooterSize, FOOTER_HOME_LINE_CLEARANCE_PX, resolveSidebarTokens, resolveTopStripeLayout, resolveTopBarTokens, topStripeShowKey, TOP_STRIPE_ALWAYS_SHOWN_SLOTS, TOP_STRIPE_SLOTS, MIN_TOP_STRIPE_HEIGHT_PX, MAX_TOP_STRIPE_HEIGHT_PX, MIN_TOP_STRIPE_PADDING_X_PX, MAX_TOP_STRIPE_PADDING_X_PX, MAX_TOP_STRIPE_OFFSET_Y_PX, DEFAULT_TOP_STRIPE_HEIGHT_PX, DEFAULT_TOP_STRIPE_PADDING_X_PX, resolveSidebarUnfold, resolveLocalNavModel, drawsLocalNavAnywhere, isDarkSurface, resolveAppLogo };

package/dist/navigation.js

@@ -74,10 +74,10 @@ export function menuItemCap(menuType) {
 // what each workspace was inheriting, so no shipped app lost its look when the
 // chain went (migration `20260918000000_footer_tokens_uncouple`).
 //
-// The eight authorable keys are the eight controls the Design panel offers, one
-// for one: `backgroundColor`, `textColor`, `tabActiveBackgroundColor`,
+// The authorable keys are the controls the Design panel offers, one for one:
+// `backgroundColor`, `textColor`, `tabActiveBackgroundColor`,
 // `tabActiveTextColor`, `borderColor`, `borderWidth`, `activeStyle`,
-// `tabLayout`.
+// `tabLayout`, and (sc-11678) `shape`, `radius`, `sideMargin`, `bottomSpacing`.
 export function resolveFooterTokens(theme) {
   const config = isPlainObject(theme) ? theme : {};
   const footer = isPlainObject(config.footer) ? config.footer : {};
@@ -94,6 +94,8 @@ export function resolveFooterTokens(theme) {
   // draw nothing.
   const borderWidth = borderColor ? footerBorderWidthOr(footer.borderWidth) : 0;
   const divider = borderWidth > 0;
+  const floats = footer.shape !== "docked";
+  const radius = footerSizeOr(footer, "radius");
   return {
     backgroundColor: hexOr(footer.backgroundColor, DEFAULT_FOOTER_SURFACE),
     textColor: hexOr(footer.textColor, DEFAULT_CHROME_TEXT),
@@ -119,9 +121,40 @@ export function resolveFooterTokens(theme) {
       footer.tabActiveTextColor,
       accent ? brandPrimary(config) : FILLED_TAB_LABEL,
     ),
+    // sc-11678: unset floats, so every app gets the rounded, inset bar.
+    shape: floats ? "floating" : "docked",
+    radius,
+    // A filled tab follows a floating bar's curve one row inset (8px) in,
+    // never sharper than the docked 6px chip. An accent tab paints no surface,
+    // and a curved top edge would bend its marker into an arc.
+    itemRadius:
+      floats && !accent ? Math.max(DOCKED_TAB_RADIUS, radius - 8) : DOCKED_TAB_RADIUS,
+    sideMargin: footerSizeOr(footer, "sideMargin"),
+    bottomSpacing: footerSizeOr(footer, "bottomSpacing"),
   };
 }
 
+// sc-11678: the bar's measurements, in px. `bottomSpacing` sits ABOVE what the
+// system needs (see FOOTER_HOME_LINE_CLEARANCE_PX). Clamped, never dropped.
+export const FOOTER_SIZES = Object.freeze({
+  radius: Object.freeze({ max: 40, fallback: 28 }),
+  sideMargin: Object.freeze({ max: 48, fallback: 12 }),
+  bottomSpacing: Object.freeze({ max: 32, fallback: 8 }),
+});
+const DOCKED_TAB_RADIUS = 6;
+export function clampFooterSize(value, key) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return undefined;
+  return Math.min(Math.max(Math.round(value), 0), FOOTER_SIZES[key].max);
+}
+function footerSizeOr(footer, key) {
+  return clampFooterSize(footer[key], key) ?? FOOTER_SIZES[key].fallback;
+}
+
+// sc-11678: of the iOS bottom inset, only the home line's band is kept clear;
+// a bar may sit in the rest of it, as Apple's and most apps' tab bars do.
+// Android's inset is its navigation bar, so there the whole inset is cleared.
+export const FOOTER_HOME_LINE_CLEARANCE_PX = 14;
+
 // REQ-THEME-14 — the rail's and the app bar's tokens, resolved once for both
 // hosts.
 //

package/package.json

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

@@ -6036,7 +6036,11 @@ const CONTRACT = deepFreeze({
   //    `fitScreenFoot` host hint: a self-scrolling Fit to screen surface that
   //    calls it runs under the bottom safe area on native and pads its
   //    controls by it. Hosts without the hint read zeros.
-  version: "1.186.0",
+  // 1.187.0: additive (sc-11678) — `resolveFooterTokens` gains the bottom
+  //    bar's `shape` (unset floats), `radius`, `itemRadius`, `sideMargin` and
+  //    `bottomSpacing`; host exports `FOOTER_SIZES`, `clampFooterSize` and
+  //    `FOOTER_HOME_LINE_CLEARANCE_PX`. No widget-facing surface changes.
+  version: "1.187.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,