@colixsystems/widget-sdk 0.267.1 → 0.268.1

package/README.md

@@ -86,7 +86,15 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.267.1` — 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.268.1` — 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.268.1 (contract 1.218.0)
+
+**The web `DateTimePicker`'s hour and minute columns no longer look broken.** The browser drew its scrollbar inside each narrow column, which cut the chosen hour and minute off on one side. The columns now hide the scrollbar and fade their top and bottom edges to show they scroll. The keyboard focus ring is drawn in full, and a row reached with the arrow keys stops clear of the fade. No API change; native keeps the operating system's picker.
+
+### What's new in 0.268.0 (contract 1.218.0)
+
+**`useAction().available` tells the truth about the Action.** It used to be true whenever an Action was bound, so a widget offered a run that could never happen. It now turns false once the server says a run would not reach the script: the Action is switched off or paused, not allowed from the app, gone, or the viewer is not a signed-in app user (signed-out visitors and anonymous accounts can't run Actions). It is asked again when the binding or the signed-in user changes, and stays true while no answer has come. The actions client (`@colixsystems/actions-client` 0.2.0) gains `status(actionId)` for it.
 
 ### What's new in 0.267.1 (contract 1.217.0)
 

package/dist/contract.cjs

@@ -2184,7 +2184,12 @@ const HOOKS = [
       "`actionRef` is an Action id an author bound through an `actionRef` " +
       "property — when it is missing, or the host brokers no actions client, " +
       "`available` is false and run() rejects UNAVAILABLE; render a visible " +
-      "'pick an action' state, NEVER a blank box. A changed binding clears " +
+      "'pick an action' state, NEVER a blank box. sc-14224: `available` also " +
+      "turns false once the server says a run would not reach the script — " +
+      "the Action is switched off or paused, not allowed from the app, gone, " +
+      "or the viewer is not a signed-in app user (signed-out visitors and " +
+      "anonymous accounts can't run Actions) — so render an 'isn't available' " +
+      "state then too. It stays true while no answer has come. A changed binding clears " +
       "`result` and `error`, and a run that settles after the binding changed " +
       "(or after unmount) writes nothing. ActionError.code: " +
       "INVALID_ACTION_INPUT (400) — the input was refused; " +
@@ -2195,7 +2200,7 @@ const HOOKS = [
       "MARKDOWN, so render it with <RichText value={result} />, not <Text>. " +
       "Reads ctx.actions.",
     returnShape: {
-      available: "boolean  // false when no Action is bound, or the host brokers none",
+      available: "boolean  // false when no Action is bound, the host brokers none, or the server says a run would not reach the script",
       run: "(input) => Promise<unknown>  // input is optional; resolves with the Action's respond() value, or null; rejects with ActionError",
       running: "boolean  // true while any run is in flight",
       result: "unknown  // the last successful run's result; null before the first run",
@@ -4150,13 +4155,14 @@ const WIDGET_CONTEXT_SHAPE = {
   actions: {
     description:
       "sc-13843 — injected @colixsystems/actions-client instance. " +
-      "{ run(actionId, input?) -> Promise<{ ok, result }> }. Backs useAction(). " +
+      "{ run(actionId, input?) -> Promise<{ ok, result }>, status(actionId) -> " +
+      "Promise<{ available, reason }> }. Backs useAction(). " +
       "Runs one Action as the signed-in caller; the server refuses an Action " +
       "without the app trigger. Errors carry the server's `code` and `status`. " +
       "Absent on a host that brokers no actions client, where useAction() " +
       "degrades to available: false rather than throwing.",
     required: false,
-    fields: { run: "function" },
+    fields: { run: "function", status: "function" },
   },
   linkPreviews: {
     description:
@@ -6472,7 +6478,10 @@ const CONTRACT = deepFreeze({
   // 1.217.0: additive (sc-4747) — `TextInput` documents `keyboardType`,
   //    `autoCapitalize`, `autoCorrect`, `autoComplete`, `secureTextEntry`;
   //    `useDatastoreSchema` columns document `text_format` (snake_case wire).
-  version: "1.217.0",
+  // 1.218.0: additive (sc-14224) — the actions client's `status(actionId)`;
+  //    `useAction().available` turns false when the server says a run would
+  //    not reach the script.
+  version: "1.218.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -2181,7 +2181,12 @@ const HOOKS = [
       "`actionRef` is an Action id an author bound through an `actionRef` " +
       "property — when it is missing, or the host brokers no actions client, " +
       "`available` is false and run() rejects UNAVAILABLE; render a visible " +
-      "'pick an action' state, NEVER a blank box. A changed binding clears " +
+      "'pick an action' state, NEVER a blank box. sc-14224: `available` also " +
+      "turns false once the server says a run would not reach the script — " +
+      "the Action is switched off or paused, not allowed from the app, gone, " +
+      "or the viewer is not a signed-in app user (signed-out visitors and " +
+      "anonymous accounts can't run Actions) — so render an 'isn't available' " +
+      "state then too. It stays true while no answer has come. A changed binding clears " +
       "`result` and `error`, and a run that settles after the binding changed " +
       "(or after unmount) writes nothing. ActionError.code: " +
       "INVALID_ACTION_INPUT (400) — the input was refused; " +
@@ -2192,7 +2197,7 @@ const HOOKS = [
       "MARKDOWN, so render it with <RichText value={result} />, not <Text>. " +
       "Reads ctx.actions.",
     returnShape: {
-      available: "boolean  // false when no Action is bound, or the host brokers none",
+      available: "boolean  // false when no Action is bound, the host brokers none, or the server says a run would not reach the script",
       run: "(input) => Promise<unknown>  // input is optional; resolves with the Action's respond() value, or null; rejects with ActionError",
       running: "boolean  // true while any run is in flight",
       result: "unknown  // the last successful run's result; null before the first run",
@@ -4147,13 +4152,14 @@ const WIDGET_CONTEXT_SHAPE = {
   actions: {
     description:
       "sc-13843 — injected @colixsystems/actions-client instance. " +
-      "{ run(actionId, input?) -> Promise<{ ok, result }> }. Backs useAction(). " +
+      "{ run(actionId, input?) -> Promise<{ ok, result }>, status(actionId) -> " +
+      "Promise<{ available, reason }> }. Backs useAction(). " +
       "Runs one Action as the signed-in caller; the server refuses an Action " +
       "without the app trigger. Errors carry the server's `code` and `status`. " +
       "Absent on a host that brokers no actions client, where useAction() " +
       "degrades to available: false rather than throwing.",
     required: false,
-    fields: { run: "function" },
+    fields: { run: "function", status: "function" },
   },
   linkPreviews: {
     description:
@@ -6469,7 +6475,10 @@ const CONTRACT = deepFreeze({
   // 1.217.0: additive (sc-4747) — `TextInput` documents `keyboardType`,
   //    `autoCapitalize`, `autoCorrect`, `autoComplete`, `secureTextEntry`;
   //    `useDatastoreSchema` columns document `text_format` (snake_case wire).
-  version: "1.217.0",
+  // 1.218.0: additive (sc-14224) — the actions client's `status(actionId)`;
+  //    `useAction().available` turns false when the server says a run would
+  //    not reach the script.
+  version: "1.218.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/datetimepicker-time-columns.js

@@ -14,6 +14,9 @@ const COLUMN_WIDTH = 64;
 const HOURS = Array.from({ length: 24 }, (_, i) => i);
 const MINUTES = Array.from({ length: 60 }, (_, i) => i);
 const LIST_KEYS = ["ArrowDown", "ArrowUp", "Home", "End"];
+// Fades the edges in place of a scrollbar, which would clip cells.
+const FADE = 24;
+const EDGE_FADE = `linear-gradient(to bottom, transparent, #000 ${FADE}px, #000 calc(100% - ${FADE}px), transparent)`;
 
 /** @param {{View: any, Text: any, Pressable: any, ScrollView: any, Platform: any}} rn */
 export function makeTimeColumns(rn) {
@@ -27,7 +30,7 @@ export function makeTimeColumns(rn) {
     React.useEffect(() => {
       if (!mounted.current) {
         mounted.current = true;
-        const top = values.indexOf(chosen) * (ITEM_HEIGHT + ITEM_GAP) - (height - ITEM_HEIGHT) / 2;
+        const top = FADE + values.indexOf(chosen) * (ITEM_HEIGHT + ITEM_GAP) - (height - ITEM_HEIGHT) / 2;
         if (scroller.current && typeof scroller.current.scrollTo === "function") {
           scroller.current.scrollTo({ y: Math.max(0, top), animated: false });
         }
@@ -76,7 +79,7 @@ export function makeTimeColumns(rn) {
           "aria-selected": selected,
           disabled: option.disabled,
           testID: testID ? `${testID}-${field}-${twoDigits(option.value)}` : undefined,
-          style: cellStyle(t, { selected, current: false, disabled: option.disabled, width: COLUMN_WIDTH, height: ITEM_HEIGHT, round: true }),
+          style: cellStyle(t, { selected, current: false, disabled: option.disabled, width: COLUMN_WIDTH - 2 * ITEM_GAP, height: ITEM_HEIGHT, round: true }),
         },
         h(Text, { style: cellText(t, { selected }) }, twoDigits(option.value)),
       );
@@ -87,7 +90,15 @@ export function makeTimeColumns(rn) {
       h(Text, { "aria-hidden": true, style: { textAlign: "center", fontFamily: t.fontFamily, fontSize: t.helperSize, fontWeight: "500", color: t.helperColor } }, name),
       h(
         ScrollView,
-        { ref: scroller, role: "listbox", accessibilityLabel: name, style: { height }, contentContainerStyle: { gap: ITEM_GAP, paddingVertical: ITEM_GAP } },
+        {
+          ref: scroller,
+          role: "listbox",
+          accessibilityLabel: name,
+          showsVerticalScrollIndicator: false,
+          style: { height, maskImage: EDGE_FADE, WebkitMaskImage: EDGE_FADE, scrollPaddingBlock: FADE },
+          // The first and last rows can scroll clear of the fade.
+          contentContainerStyle: { gap: ITEM_GAP, paddingVertical: FADE, paddingHorizontal: ITEM_GAP },
+        },
         ...options.map(item),
       ),
     );

package/dist/hooks.js

@@ -3893,18 +3893,46 @@ function toActionError(err) {
  * `available` is false and `run` rejects UNAVAILABLE rather than throwing at
  * render — the widget must render a visible unbound state (CLAUDE.md §8).
  *
+ * sc-14224 — `available` also turns false once the server says a run would
+ * not reach the script: the Action is switched off, paused, not allowed from
+ * the app, gone, or the viewer is not a signed-in app user. It is asked again
+ * when the binding or the signed-in user changes. With no answer (offline, an
+ * older host) it stays true and `run` reports the refusal.
+ *
  * Routes through the injected `@colixsystems/actions-client` at `ctx.actions`,
  * so the Player and the Expo export resolve against the identical client.
  */
 export function useAction(actionRef) {
   const ctx = useWidgetContextOrThrow("useAction");
-  const available =
+  const bound =
     Boolean(actionRef) &&
     Boolean(ctx.actions) &&
     typeof ctx.actions.run === "function";
+  const canAsk = bound && typeof ctx.actions.status === "function";
+  const askedAs = `${actionRef}|${(ctx.user && ctx.user.id) || ""}`;
 
   const clientRef = useRef(null);
-  clientRef.current = available ? ctx.actions : null;
+  clientRef.current = bound ? ctx.actions : null;
+
+  // The binding and viewer the server last refused, so a rebind starts fresh.
+  const [refusedAs, setRefusedAs] = useState(null);
+  useEffect(() => {
+    const client = clientRef.current;
+    if (!canAsk || !client) return undefined;
+    let live = true;
+    client.status(actionRef).then(
+      (answer) => {
+        if (live) setRefusedAs(answer && answer.available === false ? askedAs : null);
+      },
+      // No answer is not a refusal: keep offering the run.
+      () => {},
+    );
+    return () => {
+      live = false;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [askedAs, canAsk]);
+  const available = bound && refusedAs !== askedAs;
   const actionIdRef = useRef(actionRef);
   actionIdRef.current = actionRef;
 

package/dist/index.d.ts

@@ -890,6 +890,8 @@ export interface WidgetContext<TProps = unknown> {
   /** sc-13843 — injected @colixsystems/actions-client backing useAction(). */
   actions?: {
     run(actionId: string, input?: Record<string, unknown> | null): Promise<{ ok: boolean; result: unknown }>;
+    /** sc-14224 — whether a run would reach the script; optional on older hosts. */
+    status?(actionId: string): Promise<{ available: boolean; reason: string | null }>;
   };
   /** Injected @colixsystems/link-preview-client backing useLinkPreview(). */
   linkPreviews?: { get(url: string): Promise<LinkPreview> };
@@ -1893,7 +1895,11 @@ export interface AgentApi {
 export function useAgent(agentRef: string | null | undefined): AgentApi;
 
 export interface ActionApi {
-  /** False when no Action is bound, or the host brokers no actions client. */
+  /**
+   * False when no Action is bound, the host brokers no actions client, or the
+   * server says a run would not reach the script (switched off, not allowed
+   * from the app, or the viewer is not a signed-in app user).
+   */
   available: boolean;
   /**
    * Imperative — call from an event handler, never on mount. Resolves with the

package/package.json

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

@@ -2181,7 +2181,12 @@ const HOOKS = [
       "`actionRef` is an Action id an author bound through an `actionRef` " +
       "property — when it is missing, or the host brokers no actions client, " +
       "`available` is false and run() rejects UNAVAILABLE; render a visible " +
-      "'pick an action' state, NEVER a blank box. A changed binding clears " +
+      "'pick an action' state, NEVER a blank box. sc-14224: `available` also " +
+      "turns false once the server says a run would not reach the script — " +
+      "the Action is switched off or paused, not allowed from the app, gone, " +
+      "or the viewer is not a signed-in app user (signed-out visitors and " +
+      "anonymous accounts can't run Actions) — so render an 'isn't available' " +
+      "state then too. It stays true while no answer has come. A changed binding clears " +
       "`result` and `error`, and a run that settles after the binding changed " +
       "(or after unmount) writes nothing. ActionError.code: " +
       "INVALID_ACTION_INPUT (400) — the input was refused; " +
@@ -2192,7 +2197,7 @@ const HOOKS = [
       "MARKDOWN, so render it with <RichText value={result} />, not <Text>. " +
       "Reads ctx.actions.",
     returnShape: {
-      available: "boolean  // false when no Action is bound, or the host brokers none",
+      available: "boolean  // false when no Action is bound, the host brokers none, or the server says a run would not reach the script",
       run: "(input) => Promise<unknown>  // input is optional; resolves with the Action's respond() value, or null; rejects with ActionError",
       running: "boolean  // true while any run is in flight",
       result: "unknown  // the last successful run's result; null before the first run",
@@ -4147,13 +4152,14 @@ const WIDGET_CONTEXT_SHAPE = {
   actions: {
     description:
       "sc-13843 — injected @colixsystems/actions-client instance. " +
-      "{ run(actionId, input?) -> Promise<{ ok, result }> }. Backs useAction(). " +
+      "{ run(actionId, input?) -> Promise<{ ok, result }>, status(actionId) -> " +
+      "Promise<{ available, reason }> }. Backs useAction(). " +
       "Runs one Action as the signed-in caller; the server refuses an Action " +
       "without the app trigger. Errors carry the server's `code` and `status`. " +
       "Absent on a host that brokers no actions client, where useAction() " +
       "degrades to available: false rather than throwing.",
     required: false,
-    fields: { run: "function" },
+    fields: { run: "function", status: "function" },
   },
   linkPreviews: {
     description:
@@ -6469,7 +6475,10 @@ const CONTRACT = deepFreeze({
   // 1.217.0: additive (sc-4747) — `TextInput` documents `keyboardType`,
   //    `autoCapitalize`, `autoCorrect`, `autoComplete`, `secureTextEntry`;
   //    `useDatastoreSchema` columns document `text_format` (snake_case wire).
-  version: "1.217.0",
+  // 1.218.0: additive (sc-14224) — the actions client's `status(actionId)`;
+  //    `useAction().available` turns false when the server says a run would
+  //    not reach the script.
+  version: "1.218.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,