@colixsystems/widget-sdk 0.215.0 → 0.218.0

package/README.md

@@ -83,7 +83,16 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.215.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.218.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.218.0
+
+**Host helpers for the app logo's dark-bar variant.** An app can now carry a second logo for dark navigation bars, stored beside the app logo as `themeConfig.appLogoDarkAssetId` / `appLogoDarkUrl`. Two helpers on `@colixsystems/widget-sdk/host` decide which one a bar draws, and both hosts ask them, so the rail, the drawer, the app header and the site header pick the same logo in the web Player and in the exported app:
+
+- `isDarkSurface({ surface, backdrop, textColor, theme })` — `true` when the bar reads as dark. Pass the colour the bar paints as `surface`; a see-through `#RRGGBBAA` is composited over `backdrop`, or over the page in `theme`, first. A bar that paints nothing passes the `textColor` authored to sit on it instead: light text names a dark backdrop.
+- `resolveAppLogo(logo, darkSurfaceLogo, onDark)` — the logo to draw. The variant is used only beside an app logo; it never stands in for a missing one.
+
+These are host-integration helpers, not something a widget imports. Nothing changes for widget authors.
 
 ### What's new in 0.215.0 (contract 1.174.0)
 

package/dist/host.d.ts

@@ -397,6 +397,25 @@ export interface TopBarTokens {
  */
 export function resolveTopBarTokens(theme: unknown): TopBarTokens;
 
+/**
+ * Whether a chrome surface reads as dark. Pass the colour the bar paints
+ * (`#RRGGBBAA` is composited over `backdrop`, else over the page in `theme`),
+ * or, for a bar that paints nothing, the colour of the text authored to sit on it.
+ */
+export function isDarkSurface(input?: {
+  surface?: string | null;
+  backdrop?: string | null;
+  textColor?: string | null;
+  theme?: unknown;
+} | null): boolean;
+
+/** The logo a surface draws: the dark-surface variant only beside an app logo. */
+export function resolveAppLogo<T>(
+  logo: T | null | undefined,
+  darkSurfaceLogo: T | null | undefined,
+  onDark: boolean,
+): T | null;
+
 /** sc-8023 — the arrangeable contents of the sidebar layout's TOP STRIPE: the
  *  row across the top of the content, outside the panel and above it. */
 export type TopStripeSlot = "back" | "menu" | "brand" | "notifications";

package/dist/host.js

@@ -110,6 +110,8 @@ export {
   resolveSidebarUnfold,
   resolveLocalNavModel,
   drawsLocalNavAnywhere,
+  isDarkSurface,
+  resolveAppLogo,
 } from "./navigation.js";
 
 // sc-5717: the codec behind `useWidgetRoute()` — how a widget's own internal

package/dist/navigation.cjs

@@ -535,6 +535,33 @@ function resolveTopStripeLayout(theme) {
   };
 }
 
+// Whether a chrome surface reads as dark — asked for the app logo's variant
+// and for the status-bar glyphs, so the two can never disagree about a bar.
+// A see-through `surface` is judged by its blend with what is behind it: the
+// given `backdrop`, else the page in `theme`. A bar that paints nothing passes
+// `textColor` instead: light text was authored for a dark backdrop.
+function isDarkSurface(input) {
+  const { surface, backdrop, textColor, theme } = isPlainObject(input) ? input : {};
+  if (isHexColor(surface)) {
+    const alpha = surface.length === 9 ? parseInt(surface.slice(7), 16) / 255 : 1;
+    const behind = isHexColor(backdrop)
+      ? backdrop
+      : chromeSurface(isPlainObject(theme) ? theme : {});
+    const seen = alpha < 1 ? mixHex(behind, surface.slice(0, 7), alpha) : surface;
+    return readableTextColor(seen, "dark", "light") === "light";
+  }
+  if (isHexColor(textColor)) {
+    return readableTextColor(textColor, "dark", "light") === "dark";
+  }
+  return false;
+}
+
+// The dark-surface logo is a VARIANT of the app logo: it never stands alone.
+function resolveAppLogo(logo, darkSurfaceLogo, onDark) {
+  if (!logo) return null;
+  return onDark && darkSurfaceLogo ? darkSurfaceLogo : logo;
+}
+
 const TAB_ALIGNMENTS = ["left", "right"];
 const TAB_ROW_WIDTHS = ["full", "content"];
 
@@ -817,4 +844,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 };
+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 };

package/dist/navigation.js

@@ -526,6 +526,33 @@ export function resolveTopStripeLayout(theme) {
   };
 }
 
+// Whether a chrome surface reads as dark — asked for the app logo's variant
+// and for the status-bar glyphs, so the two can never disagree about a bar.
+// A see-through `surface` is judged by its blend with what is behind it: the
+// given `backdrop`, else the page in `theme`. A bar that paints nothing passes
+// `textColor` instead: light text was authored for a dark backdrop.
+export function isDarkSurface(input) {
+  const { surface, backdrop, textColor, theme } = isPlainObject(input) ? input : {};
+  if (isHexColor(surface)) {
+    const alpha = surface.length === 9 ? parseInt(surface.slice(7), 16) / 255 : 1;
+    const behind = isHexColor(backdrop)
+      ? backdrop
+      : chromeSurface(isPlainObject(theme) ? theme : {});
+    const seen = alpha < 1 ? mixHex(behind, surface.slice(0, 7), alpha) : surface;
+    return readableTextColor(seen, "dark", "light") === "light";
+  }
+  if (isHexColor(textColor)) {
+    return readableTextColor(textColor, "dark", "light") === "dark";
+  }
+  return false;
+}
+
+// The dark-surface logo is a VARIANT of the app logo: it never stands alone.
+export function resolveAppLogo(logo, darkSurfaceLogo, onDark) {
+  if (!logo) return null;
+  return onDark && darkSurfaceLogo ? darkSurfaceLogo : logo;
+}
+
 const TAB_ALIGNMENTS = ["left", "right"];
 const TAB_ROW_WIDTHS = ["full", "content"];
 

package/package.json

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