@colixsystems/widget-sdk 0.97.0 → 0.99.0

package/dist/host.d.ts

@@ -133,3 +133,52 @@ export function resolveToastTokens(
 export function createToastController(
   opts?: ToastControllerOptions,
 ): ToastController;
+
+// REQ-NAV-STRUCTURE — the navigation SHAPE a host draws its chrome in. The
+// vocabulary is closed by `CONTRACT.themeMenuTypes`; these are the resolvers
+// both hosts switch on.
+
+export type ThemeMenuType = "sidebar" | "top-bar" | "bottom-tabs";
+
+export interface ResolvedNavigation {
+  menuType: ThemeMenuType;
+}
+
+/**
+ * Resolves a stored `theme_config.navigation` block. Always returns a usable
+ * shape — a junk, partial, or absent input yields the default sidebar, so a
+ * host never has to guard the value it switches on.
+ */
+export function normaliseNavigation(navigation: unknown): ResolvedNavigation;
+
+/**
+ * How many menu pages this shape may draw at once, or `null` for no cap. The
+ * cap's meaning differs per type: the sidebar's quick bar may drop a page past
+ * it, a bottom-tabs strip must move its surplus behind a More sheet.
+ */
+export function menuItemCap(menuType: string): number | null;
+
+/**
+ * How many pages the SECONDARY mobile quick bar draws, or `null` where the shape
+ * draws none (only `sidebar` has one). Unlike `menuItemCap` this cap MAY drop a
+ * page: the rail and drawer still list every menu page.
+ */
+export function quickBarCap(menuType: string): number | null;
+
+/** The footer strip's resolved tokens. A `null` colour means the host keeps its
+ *  own default; a `null` `borderColor` means no divider is drawn at all. */
+export interface FooterTokens {
+  backgroundColor: string | null;
+  textColor: string | null;
+  activeColor: string | null;
+  borderColor: string | null;
+  borderWidth: number | null;
+  activeStyle: "filled" | "accent";
+}
+
+/**
+ * Resolves the footer strip's tokens from a whole `theme_config`. Every field
+ * falls back to the sidebar's, so a workspace that never opens the Footer panel
+ * renders exactly as it did before the block existed.
+ */
+export function resolveFooterTokens(theme: unknown): FooterTokens;

package/dist/host.js

@@ -39,3 +39,19 @@ export {
   normalizeToastKind,
   TOAST_DEFAULTS,
 } from "./toast-host.js";
+
+// REQ-NAV-STRUCTURE: the navigation-shape resolver both hosts draw their chrome
+// from. `normaliseNavigation` turns a stored `theme_config.navigation` block into
+// the resolved `{ menuType }` the chrome switches on; `menuItemCap` states how
+// many menu pages that shape may draw at once. One implementation, so a menu
+// type cannot mean one thing in the Player and another in the Expo export.
+// `resolveFooterTokens` is the footer strip's own token set, falling back to
+// the sidebar's so an untouched workspace keeps the appearance it has. It
+// exists because the strip IS the menu under `bottom-tabs`, where the sidebar
+// panel is hidden and those tokens can no longer be set at all.
+export {
+  normaliseNavigation,
+  menuItemCap,
+  quickBarCap,
+  resolveFooterTokens,
+} from "./navigation.js";

package/dist/index.d.ts

@@ -385,6 +385,27 @@ export interface DatastoreClient {
     get(tableIdOrName: string): Promise<unknown>;
   };
   schema(tableId: string): Promise<unknown>;
+  /**
+   * sc-5206 — REQ-ACL-COMPOSER-GATING: the caller's effective table-level
+   * (+ optional per-record) permissions. Backs `useCanWrite`.
+   */
+  myPermissions(
+    tableId: string,
+    options?: { recordId?: string },
+  ): Promise<{
+    can_read_schema: boolean;
+    can_create: boolean;
+    can_read_records: boolean;
+    can_read: boolean;
+    can_write: boolean;
+    can_delete: boolean;
+    record?: {
+      can_read: boolean;
+      can_write: boolean;
+      can_delete: boolean;
+      can_grant: boolean;
+    };
+  }>;
   records(tableId: string): {
     list(query?: Query): Promise<ListEnvelope>;
     get(recordId: string): Promise<unknown>;
@@ -971,6 +992,52 @@ export function useDatastoreSchema(
   tableId: string | null | undefined,
 ): SchemaResult;
 
+/** sc-5206 — one prop key `useBoundColumns` resolves to a schema column. */
+export interface BoundColumnSpec {
+  dataType?: string | string[];
+  /** When true, an unresolved key is omitted from `missing`. */
+  optional?: boolean;
+}
+
+export type BoundColumnShape = Record<string, BoundColumnSpec>;
+
+export interface BoundColumnsResult {
+  /** Resolved column NAME per key — drop-in for `record[props.titleField]`. */
+  columns: Record<string, string | undefined>;
+  /** The full Column object per key, as `useDatastoreSchema` returns it. */
+  resolved: Record<string, DatastoreSchemaColumn | undefined>;
+  /** Keys whose spec is not `optional: true` and did not resolve. */
+  missing: string[];
+  loading: boolean;
+  error: DatastoreError | null;
+}
+
+/**
+ * sc-5206 — resolve author-bound column NAMES from a widget's own props,
+ * built on `useDatastoreSchema`. Falls back name -> case-insensitive name ->
+ * first unclaimed column matching `dataType`, so a column an author renamed
+ * after install still resolves. Never throws for a missing column — an
+ * unresolved key reads `undefined` and, when not `optional: true`, is named
+ * in `missing`. Falsy `tableId` collapses to `{ columns: {}, resolved: {},
+ * missing: Object.keys(shape), loading: false, error: null }`.
+ */
+export function useBoundColumns<TProps = Record<string, unknown>>(
+  tableId: string | null | undefined,
+  shape: BoundColumnShape,
+  props: TProps,
+): BoundColumnsResult;
+
+/**
+ * sc-5206 — keep whatever `buildQuery()` returns at a STABLE reference across
+ * renders when its (JSON-serialised) content hasn't changed, so it can be
+ * passed straight into `useDatastoreQuery`'s second argument instead of a
+ * hand-rolled `useMemo` with an easy-to-get-wrong deps array. Pure React
+ * state — no host / WidgetContext required. Never throws: a `buildQuery`
+ * that throws degrades to a stable `undefined`; a result that can't be
+ * diffed (e.g. circular) degrades to "always a new reference".
+ */
+export function useStableQuery<T = unknown>(buildQuery: () => T): T | undefined;
+
 /** sc-4932 — one field a draft may target, with a dropdown's closed option set. */
 export interface InterpretDraftField {
   column: string;
@@ -1852,6 +1919,34 @@ export function useRecordPermissions(
   recordId: string | null | undefined,
 ): RecordPermissionsResult;
 
+export interface CanWriteOptions {
+  recordId?: string;
+}
+
+export interface CanWriteResult {
+  canWrite: boolean;
+  loading: boolean;
+  error: DatastoreError | null;
+  refetch(): Promise<void>;
+}
+
+/**
+ * sc-5206 — is the signed-in caller permitted to write to `tableId` (or, with
+ * `options.recordId`, to that one row)? A FLOOR, not a full replacement for
+ * domain-specific write rules: a widget whose rule is more specific than the
+ * table ACL (e.g. "only the assigned user may edit this row") must still
+ * hand-check that in addition to this hook. Answers "signed in AND
+ * permitted" — pair with `useUser()` to also tell "not signed in" apart from
+ * "signed in but forbidden". Falsy `tableId`, or a host that has not
+ * injected `ctx.datastore.myPermissions`, collapses to `{ canWrite: false,
+ * loading: false, error: null, refetch: async () => undefined }` rather than
+ * throwing.
+ */
+export function useCanWrite(
+  tableId: string | null | undefined,
+  options?: CanWriteOptions,
+): CanWriteResult;
+
 export function WidgetContextProvider(props: {
   value: WidgetContext;
   children?: ReactNode;

package/dist/index.js

@@ -15,6 +15,9 @@ export {
   useDatastoreQuery,
   useDatastoreRecord,
   useDatastoreSchema,
+  useBoundColumns,
+  useStableQuery,
+  useCanWrite,
   useInterpretDraft,
   useAsset,
   useAssetsByTag,

package/dist/index.native.js

@@ -15,6 +15,9 @@ export {
   useDatastoreQuery,
   useDatastoreRecord,
   useDatastoreSchema,
+  useBoundColumns,
+  useStableQuery,
+  useCanWrite,
   useInterpretDraft,
   useAsset,
   useAssetsByTag,

package/dist/linter.cjs

@@ -944,6 +944,71 @@ function _datastoreErrorHandlingRules(source) {
   ];
 }
 
+// sc-5206 — soft warning: a `useDatastoreQuery` argument built from a raw
+// `const q = useMemo(() => ({...}), [...])` re-fetches in a loop the moment
+// the deps array is wrong (sc-1579's volatile-query gate exists because of
+// exactly this mistake). Flags only when the file has NOT already reached
+// for `useStableQuery`, the hook that removes the deps array entirely.
+function _rawUseMemoIntoDatastoreQueryRules(source) {
+  const code = _stripNonCode(source);
+  if (/\buseStableQuery\s*\(/.test(code)) return [];
+  const callRe = /\buseDatastoreQuery\s*\(\s*[^,()]+,\s*([A-Za-z_$][\w$]*)\s*[,)]/g;
+  const findings = [];
+  const sourceLines = source.split(/\r?\n/);
+  const seen = new Set();
+  let m;
+  while ((m = callRe.exec(code))) {
+    const varName = m[1];
+    if (seen.has(varName)) continue;
+    const memoRe = new RegExp(`\\bconst\\s+${varName}\\s*=\\s*useMemo\\s*\\(`);
+    const memoMatch = memoRe.exec(code);
+    if (!memoMatch || memoMatch.index >= m.index) continue;
+    seen.add(varName);
+    const line = code.slice(0, memoMatch.index).split(/\r?\n/).length;
+    findings.push({
+      rule: "raw-useMemo-into-datastore-query",
+      severity: "warning",
+      label:
+        `Pass useStableQuery(() => ({...})) as the query argument instead ` +
+        `of hand-rolling useMemo — it removes the wrong-deps-array failure ` +
+        `mode.`,
+      line,
+      snippet: (sourceLines[line - 1] || "").trim().slice(0, 200),
+    });
+  }
+  return findings;
+}
+
+// sc-5206 — soft warning, the write-gate twin of `write-not-gated-on-user`.
+// A widget that hand-derives write permission from `useUser().groupIds` /
+// `.roles` re-implements the table ACL client-side and drifts from it the
+// moment the ACL changes; `useCanWrite(tableId)` reads the same rule the
+// write endpoint enforces. Flags only when the file has NOT already reached
+// for it.
+function _handRolledWriteGateRules(source) {
+  const code = _stripNonCode(source);
+  if (/\buseCanWrite\s*\(/.test(code)) return [];
+  const userCall = /\buseUser\s*\(\s*\)/.exec(code);
+  if (!userCall) return [];
+  if (!/\.(groupIds|roles)\b/.test(code)) return [];
+  const hasWrite =
+    /\.(create|update)\s*\(/.test(code) ||
+    /\buseDatastoreMutation\s*\(/.test(code);
+  if (!hasWrite) return [];
+  const line = code.slice(0, userCall.index).split(/\r?\n/).length;
+  return [
+    {
+      rule: "hand-rolled-write-gate",
+      severity: "warning",
+      label:
+        `Gate this write on useCanWrite(tableId) as the permission FLOOR — ` +
+        `IN ADDITION TO (never instead of) a narrower roles/groupIds rule.`,
+      line,
+      snippet: (source.split(/\r?\n/)[line - 1] || "").trim().slice(0, 200),
+    },
+  ];
+}
+
 function _imagePercentHeightRules(source) {
   const findings = [];
   const code = _stripNonCode(source, { keepStrings: true });
@@ -1113,6 +1178,9 @@ function lintSource(source, options) {
   findings.push(..._hardcodedCurrencyLabelRules(source));
   findings.push(..._paymentErrorHandlingRules(source));
   findings.push(..._datastoreErrorHandlingRules(source));
+  // sc-5206 — soft warnings steering a widget toward the two new hooks.
+  findings.push(..._rawUseMemoIntoDatastoreQueryRules(source));
+  findings.push(..._handRolledWriteGateRules(source));
   findings.push(
     ..._scopeRules(source, options && options.manifest).map((f) => ({
       ...f,

package/dist/linter.js

@@ -1077,6 +1077,71 @@ function _datastoreErrorHandlingRules(source) {
   ];
 }
 
+// sc-5206 — soft warning: a `useDatastoreQuery` argument built from a raw
+// `const q = useMemo(() => ({...}), [...])` re-fetches in a loop the moment
+// the deps array is wrong (sc-1579's volatile-query gate exists because of
+// exactly this mistake). Flags only when the file has NOT already reached
+// for `useStableQuery`, the hook that removes the deps array entirely.
+function _rawUseMemoIntoDatastoreQueryRules(source) {
+  const code = _stripNonCode(source);
+  if (/\buseStableQuery\s*\(/.test(code)) return [];
+  const callRe = /\buseDatastoreQuery\s*\(\s*[^,()]+,\s*([A-Za-z_$][\w$]*)\s*[,)]/g;
+  const findings = [];
+  const sourceLines = source.split(/\r?\n/);
+  const seen = new Set();
+  let m;
+  while ((m = callRe.exec(code))) {
+    const varName = m[1];
+    if (seen.has(varName)) continue;
+    const memoRe = new RegExp(`\\bconst\\s+${varName}\\s*=\\s*useMemo\\s*\\(`);
+    const memoMatch = memoRe.exec(code);
+    if (!memoMatch || memoMatch.index >= m.index) continue;
+    seen.add(varName);
+    const line = code.slice(0, memoMatch.index).split(/\r?\n/).length;
+    findings.push({
+      rule: "raw-useMemo-into-datastore-query",
+      severity: "warning",
+      label:
+        `Pass useStableQuery(() => ({...})) as the query argument instead ` +
+        `of hand-rolling useMemo — it removes the wrong-deps-array failure ` +
+        `mode.`,
+      line,
+      snippet: (sourceLines[line - 1] || "").trim().slice(0, 200),
+    });
+  }
+  return findings;
+}
+
+// sc-5206 — soft warning, the write-gate twin of `write-not-gated-on-user`.
+// A widget that hand-derives write permission from `useUser().groupIds` /
+// `.roles` re-implements the table ACL client-side and drifts from it the
+// moment the ACL changes; `useCanWrite(tableId)` reads the same rule the
+// write endpoint enforces. Flags only when the file has NOT already reached
+// for it.
+function _handRolledWriteGateRules(source) {
+  const code = _stripNonCode(source);
+  if (/\buseCanWrite\s*\(/.test(code)) return [];
+  const userCall = /\buseUser\s*\(\s*\)/.exec(code);
+  if (!userCall) return [];
+  if (!/\.(groupIds|roles)\b/.test(code)) return [];
+  const hasWrite =
+    /\.(create|update)\s*\(/.test(code) ||
+    /\buseDatastoreMutation\s*\(/.test(code);
+  if (!hasWrite) return [];
+  const line = code.slice(0, userCall.index).split(/\r?\n/).length;
+  return [
+    {
+      rule: "hand-rolled-write-gate",
+      severity: "warning",
+      label:
+        `Gate this write on useCanWrite(tableId) as the permission FLOOR — ` +
+        `IN ADDITION TO (never instead of) a narrower roles/groupIds rule.`,
+      line,
+      snippet: (source.split(/\r?\n/)[line - 1] || "").trim().slice(0, 200),
+    },
+  ];
+}
+
 function _imagePercentHeightRules(source) {
   const findings = [];
   // Comments are blanked (string contents kept) so a commented-out example —
@@ -1276,6 +1341,9 @@ export function lintSource(source, options) {
   findings.push(..._hardcodedCurrencyLabelRules(source));
   findings.push(..._paymentErrorHandlingRules(source));
   findings.push(..._datastoreErrorHandlingRules(source));
+  // sc-5206 — soft warnings steering a widget toward the two new hooks.
+  findings.push(..._rawUseMemoIntoDatastoreQueryRules(source));
+  findings.push(..._handRolledWriteGateRules(source));
   // REQ-USERMGMT / REQ-ACL-SYS M3 — scope-aware rules. Run after the
   // line-by-line scan so banned-identifier findings stay first in the
   // output.

package/dist/navigation.cjs

@@ -0,0 +1,124 @@
+// CommonJS mirror of navigation.js — the CJS compiler and the Mason build runner
+// resolve a `theme_config.navigation` block with the SAME rules the web host
+// applies, so an app's menu type cannot mean one thing on web and another in the
+// exported Expo app.
+//
+// The BODY below is copied VERBATIM from navigation.js; only the module syntax
+// differs. navigation-parity.test.js pins both facts — identical bodies AND
+// identical behaviour over a shared case table — so drift fails CI.
+
+// REQ-NAV-STRUCTURE — the host side of an app's navigation SHAPE and the
+// tokens its footer strip is painted with.
+//
+// Host-integration surface, re-exported from `host.js`: consumed by the platform
+// hosts that draw an app's chrome (the web PlayerChrome, the compiler that emits
+// the exported Expo app's navigator) and by the Studio surface that authors it —
+// never by a widget author.
+//
+// Living here — one implementation both hosts import — is what makes a menu type
+// behave identically in the Player and the export (widget-parity skill). The
+// alternative, a resolver copied per host, is the drift this file exists to
+// prevent.
+//
+// `CONTRACT.themeMenuTypes` is the single source of the vocabulary: which shapes
+// exist and each one's item cap. Mason's `set_theme` coercion validates against
+// the SAME literal, so what a planner may persist and what a host draws cannot
+// diverge.
+
+const { CONTRACT } = require("./contract.cjs");
+
+// Absent or unknown resolves here, so every app authored before menu types
+// existed renders and compiles byte-identically.
+const DEFAULT_MENU_TYPE = "sidebar";
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Resolve a `theme_config.navigation` block to the shape both hosts read.
+ *
+ * Always returns a fully resolved object — a junk, partial, or absent input
+ * yields the default sidebar rather than something a host has to guard against.
+ *
+ * @param {unknown} navigation — the raw `theme_config.navigation` value.
+ * @returns {{ menuType: string }} the resolved navigation structure.
+ */
+function normaliseNavigation(navigation) {
+  const raw = isPlainObject(navigation) ? navigation.menuType : undefined;
+  const menuType =
+    typeof raw === "string" && Object.hasOwn(CONTRACT.themeMenuTypes, raw)
+      ? raw
+      : DEFAULT_MENU_TYPE;
+  return { menuType };
+}
+
+/**
+ * How many MENU pages the chrome may draw at once, or `null` for no cap.
+ *
+ * Where the chrome IS the menu (`bottom-tabs`) this cap must never drop a page:
+ * the surplus moves behind a More sheet. Contrast `quickBarCap` below.
+ *
+ * @param {string} menuType — a resolved menu type.
+ * @returns {number|null}
+ */
+function menuItemCap(menuType) {
+  const entry = CONTRACT.themeMenuTypes[menuType];
+  return entry ? entry.maxItems : null;
+}
+
+/**
+ * How many pages the SECONDARY mobile quick bar draws, or `null` where that
+ * shape draws none. Only the `sidebar` shape has one.
+ *
+ * This cap MAY drop a page, and that is the difference from `menuItemCap`: the
+ * rail and the drawer still list every menu page, so the bar is a shortcut
+ * rather than the menu. It lived as a constant on one host and a literal on the
+ * other before this, which is exactly how the two would have drifted.
+ *
+ * @param {string} menuType — a resolved menu type.
+ * @returns {number|null}
+ */
+function quickBarCap(menuType) {
+  const entry = CONTRACT.themeMenuTypes[menuType];
+  return entry ? entry.quickBarMaxItems : null;
+}
+
+// The strip's surface was hard-coded white on BOTH hosts and its items read the
+// sidebar's tokens — which is fine while it is the sidebar's secondary quick bar
+// and fatal once it IS the menu (`bottom-tabs` hides the sidebar panel, so those
+// tokens have nowhere to be set). `footer` gives it tokens of its own.
+//
+// Every field falls back to the sidebar's, so a workspace that never opens the
+// Footer panel keeps exactly the appearance it has today; only an explicit
+// `footer` value moves anything.
+function resolveFooterTokens(theme) {
+  const config = isPlainObject(theme) ? theme : {};
+  const footer = isPlainObject(config.footer) ? config.footer : {};
+  const sidebar = isPlainObject(config.sidebar) ? config.sidebar : {};
+  const pick = (key) => footer[key] || sidebar[key] || null;
+  const borderColor = pick("borderColor");
+  const activeStyle = footer.activeStyle || sidebar.activeStyle;
+  return {
+    backgroundColor: pick("backgroundColor"),
+    textColor: pick("textColor"),
+    // Unlike the others this has no null state on either host: an unset active
+    // colour resolves to the brand primary, which the caller supplies.
+    activeColor: pick("activeColor"),
+    // REQ-THEME-LOOK: the divider's COLOUR is its switch. Unset draws no line at
+    // all — which the native quick bar did not honour before this, ruling a
+    // hairline across a tinted strip that had asked for none.
+    borderColor,
+    borderWidth: borderColor ? borderWidthOr(footer.borderWidth, sidebar.borderWidth) : null,
+    activeStyle: activeStyle === "accent" ? "accent" : "filled",
+  };
+}
+
+function borderWidthOr(...values) {
+  for (const value of values) {
+    if (typeof value === "number" && Number.isFinite(value)) return value;
+  }
+  return 1;
+}
+
+module.exports = { normaliseNavigation, menuItemCap, quickBarCap, resolveFooterTokens };

package/dist/navigation.js

@@ -0,0 +1,113 @@
+// REQ-NAV-STRUCTURE — the host side of an app's navigation SHAPE and the
+// tokens its footer strip is painted with.
+//
+// Host-integration surface, re-exported from `host.js`: consumed by the platform
+// hosts that draw an app's chrome (the web PlayerChrome, the compiler that emits
+// the exported Expo app's navigator) and by the Studio surface that authors it —
+// never by a widget author.
+//
+// Living here — one implementation both hosts import — is what makes a menu type
+// behave identically in the Player and the export (widget-parity skill). The
+// alternative, a resolver copied per host, is the drift this file exists to
+// prevent.
+//
+// `CONTRACT.themeMenuTypes` is the single source of the vocabulary: which shapes
+// exist and each one's item cap. Mason's `set_theme` coercion validates against
+// the SAME literal, so what a planner may persist and what a host draws cannot
+// diverge.
+
+import { CONTRACT } from "./contract.js";
+
+// Absent or unknown resolves here, so every app authored before menu types
+// existed renders and compiles byte-identically.
+const DEFAULT_MENU_TYPE = "sidebar";
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Resolve a `theme_config.navigation` block to the shape both hosts read.
+ *
+ * Always returns a fully resolved object — a junk, partial, or absent input
+ * yields the default sidebar rather than something a host has to guard against.
+ *
+ * @param {unknown} navigation — the raw `theme_config.navigation` value.
+ * @returns {{ menuType: string }} the resolved navigation structure.
+ */
+export function normaliseNavigation(navigation) {
+  const raw = isPlainObject(navigation) ? navigation.menuType : undefined;
+  const menuType =
+    typeof raw === "string" && Object.hasOwn(CONTRACT.themeMenuTypes, raw)
+      ? raw
+      : DEFAULT_MENU_TYPE;
+  return { menuType };
+}
+
+/**
+ * How many MENU pages the chrome may draw at once, or `null` for no cap.
+ *
+ * Where the chrome IS the menu (`bottom-tabs`) this cap must never drop a page:
+ * the surplus moves behind a More sheet. Contrast `quickBarCap` below.
+ *
+ * @param {string} menuType — a resolved menu type.
+ * @returns {number|null}
+ */
+export function menuItemCap(menuType) {
+  const entry = CONTRACT.themeMenuTypes[menuType];
+  return entry ? entry.maxItems : null;
+}
+
+/**
+ * How many pages the SECONDARY mobile quick bar draws, or `null` where that
+ * shape draws none. Only the `sidebar` shape has one.
+ *
+ * This cap MAY drop a page, and that is the difference from `menuItemCap`: the
+ * rail and the drawer still list every menu page, so the bar is a shortcut
+ * rather than the menu. It lived as a constant on one host and a literal on the
+ * other before this, which is exactly how the two would have drifted.
+ *
+ * @param {string} menuType — a resolved menu type.
+ * @returns {number|null}
+ */
+export function quickBarCap(menuType) {
+  const entry = CONTRACT.themeMenuTypes[menuType];
+  return entry ? entry.quickBarMaxItems : null;
+}
+
+// The strip's surface was hard-coded white on BOTH hosts and its items read the
+// sidebar's tokens — which is fine while it is the sidebar's secondary quick bar
+// and fatal once it IS the menu (`bottom-tabs` hides the sidebar panel, so those
+// tokens have nowhere to be set). `footer` gives it tokens of its own.
+//
+// Every field falls back to the sidebar's, so a workspace that never opens the
+// Footer panel keeps exactly the appearance it has today; only an explicit
+// `footer` value moves anything.
+export function resolveFooterTokens(theme) {
+  const config = isPlainObject(theme) ? theme : {};
+  const footer = isPlainObject(config.footer) ? config.footer : {};
+  const sidebar = isPlainObject(config.sidebar) ? config.sidebar : {};
+  const pick = (key) => footer[key] || sidebar[key] || null;
+  const borderColor = pick("borderColor");
+  const activeStyle = footer.activeStyle || sidebar.activeStyle;
+  return {
+    backgroundColor: pick("backgroundColor"),
+    textColor: pick("textColor"),
+    // Unlike the others this has no null state on either host: an unset active
+    // colour resolves to the brand primary, which the caller supplies.
+    activeColor: pick("activeColor"),
+    // REQ-THEME-LOOK: the divider's COLOUR is its switch. Unset draws no line at
+    // all — which the native quick bar did not honour before this, ruling a
+    // hairline across a tinted strip that had asked for none.
+    borderColor,
+    borderWidth: borderColor ? borderWidthOr(footer.borderWidth, sidebar.borderWidth) : null,
+    activeStyle: activeStyle === "accent" ? "accent" : "filled",
+  };
+}
+
+function borderWidthOr(...values) {
+  for (const value of values) {
+    if (typeof value === "number" && Number.isFinite(value)) return value;
+  }
+  return 1;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.97.0",
+  "version": "0.99.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -48,7 +48,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-invites.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-payments.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-section-empty.test.js src/__tests__/hooks-widget-event.test.js src/__tests__/hooks-widget-input.test.js src/__tests__/hooks-identification.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-translation-api.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-measured-padding.test.js src/__tests__/linter-payment-error.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/hooks-translate.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/theme-components-parity.test.js src/__tests__/theme-depth-tokens.test.js src/__tests__/toast-host.test.js src/__tests__/hooks-domain-error-mapping.test.js src/__tests__/linter-datastore-error.test.js src/__tests__/linter-write-gating.test.js src/__tests__/hooks-speech-to-text.test.js"
+    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-invites.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-payments.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-section-empty.test.js src/__tests__/hooks-widget-event.test.js src/__tests__/hooks-widget-input.test.js src/__tests__/hooks-identification.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-translation-api.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-measured-padding.test.js src/__tests__/linter-payment-error.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/hooks-translate.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/theme-components-parity.test.js src/__tests__/navigation-parity.test.js src/__tests__/theme-depth-tokens.test.js src/__tests__/toast-host.test.js src/__tests__/hooks-domain-error-mapping.test.js src/__tests__/linter-datastore-error.test.js src/__tests__/linter-write-gating.test.js src/__tests__/hooks-speech-to-text.test.js src/__tests__/hooks-bound-columns.test.js src/__tests__/hooks-stable-query.test.js src/__tests__/hooks-can-write.test.js"
   },
   "engines": {
     "node": ">=18"