@colixsystems/widget-sdk 0.133.0 → 0.134.0

package/dist/hooks.js

@@ -188,6 +188,17 @@ export function useHostTheme() {
   return ctx && ctx.workspace ? ctx.workspace.theme : undefined;
 }
 
+// @internal — the navigation counterpart of useHostTheme: reads the host's
+// navigation slice WITHOUT throwing when no provider is mounted, unlike
+// useNavigation() which asserts a widget context. `<RichText>` reads it so a
+// link in formatted content is followable inside a widget yet the component
+// stays renderable anywhere (a Studio preview, a test harness). Not part of the
+// public widget hook surface — not re-exported from index.js.
+export function useHostNavigation() {
+  const ctx = useContext(HostWidgetContext);
+  return ctx ? ctx.navigation : undefined;
+}
+
 /**
  * REQ-THEME-13 — returns the author-set per-widget style values: the object the
  * host delivers under `props.style`, keyed by the style-field names the widget

package/dist/index.d.ts

@@ -2600,6 +2600,8 @@ export function lintSource(
 export interface ContractHookEntry {
   name: string;
   signature: string;
+  /** Arguments and option keys in `signature` that may be omitted (sc-6946). */
+  optionalArgs?: string[];
   returnShape: Record<string, string>;
   requiredContextSlice: string[];
   scopes: string[] | null;

package/dist/index.js

@@ -113,6 +113,8 @@ export {
   isHttpImageSrc,
   isSafeMarkdownImageSrc,
   normaliseMarkdownImageSize,
+  escapeMarkdownLabel,
+  formatMarkdownTable,
   MARKDOWN_IMAGE_SIZES,
 } from "./markdown.js";
 export {

package/dist/index.native.js

@@ -107,6 +107,8 @@ export {
   isHttpImageSrc,
   isSafeMarkdownImageSrc,
   normaliseMarkdownImageSize,
+  escapeMarkdownLabel,
+  formatMarkdownTable,
   MARKDOWN_IMAGE_SIZES,
 } from "./markdown.js";
 export {

package/dist/markdown-edit.js

@@ -5,8 +5,13 @@
 // author's SELECTION rather than appending at the end, and that is a thing
 // tests can pin without a renderer.
 
+import { escapeMarkdownLabel, formatMarkdownTable } from "./markdown.js";
+
 const LINE_RE = /^(\s*)((?:#{1,3}\s)|(?:[-*]\s)|(?:\d+[.)]\s))?([\s\S]*)$/;
 
+// The literal the inserted table skeleton opens with; the caret lands on it.
+const FIRST_HEADING = "Column 1";
+
 const LINE_KINDS = Object.freeze({
   heading2: { marker: "## ", test: /^##\s/ },
   heading3: { marker: "### ", test: /^###\s/ },
@@ -86,6 +91,66 @@ function linePrefix(kind) {
   };
 }
 
+// sc-7349 — a link needs a TARGET, which no selection can supply, so this is
+// the one op that takes a third argument. The target is stored verbatim: the
+// host's `navigation.openLink` is what decides page / external / refuse, so
+// this must not pre-judge it (see markdown.js).
+function linkOp() {
+  return (text, selection, options) => {
+    const { src, start, end } = readRange(text, selection);
+    // A bare string is accepted as the target, so the common case stays terse.
+    const opts =
+      options && typeof options === "object" ? options : { target: options };
+    const href = typeof opts.target === "string" ? opts.target.trim() : "";
+    // Nothing to point at — leave the text exactly as the author left it.
+    if (!href) return { value: src, selection: { start, end } };
+
+    // An explicit label wins, so a dialog can name the link when the author
+    // had nothing selected; otherwise the selection IS the label.
+    const chosen =
+      typeof opts.label === "string" && opts.label.trim()
+        ? opts.label
+        : src.slice(start, end);
+    const label = escapeMarkdownLabel(chosen) || href;
+    const markup = `[${label}](${href})`;
+    return {
+      value: src.slice(0, start) + markup + src.slice(end),
+      // Leaves the LABEL selected, so typing replaces the link text rather
+      // than the markup around it.
+      selection: { start: start + 1, end: start + 1 + label.length },
+    };
+  };
+}
+
+// A table is a block, so it needs its own lines: a blank line before keeps it
+// from fusing with the paragraph the caret was in.
+function tableOp() {
+  return (text, selection) => {
+    const { src, start, end } = readRange(text, selection);
+    const before = src.slice(0, start);
+    const after = src.slice(end);
+    const lead =
+      before.length === 0 || before.endsWith("\n\n")
+        ? ""
+        : before.endsWith("\n")
+          ? "\n"
+          : "\n\n";
+    const trail = after.startsWith("\n") ? "" : "\n";
+
+    const skeleton = formatMarkdownTable();
+    const offset = before.length + lead.length;
+    return {
+      value: before + lead + skeleton + trail + after,
+      // Selects the first header cell, so the author types over "Column 1"
+      // instead of hunting for the caret inside the pipes.
+      selection: {
+        start: offset + 2,
+        end: offset + 2 + FIRST_HEADING.length,
+      },
+    };
+  };
+}
+
 export const markdownEditOps = Object.freeze({
   bold: wrap("**"),
   italic: wrap("*"),
@@ -94,4 +159,6 @@ export const markdownEditOps = Object.freeze({
   heading3: linePrefix("heading3"),
   bullet: linePrefix("bullet"),
   ordered: linePrefix("ordered"),
+  link: linkOp(),
+  table: tableOp(),
 });

package/dist/markdown-input-view.js

@@ -13,6 +13,7 @@ import React from "react";
 import { useHostTheme } from "./hooks.js";
 import { resolveRichTextTokens } from "./richtext-tokens.js";
 import { markdownEditOps } from "./markdown-edit.js";
+import { makeMarkdownLinkDialog } from "./markdown-link-dialog.js";
 
 const TOOLS = Object.freeze([
   { key: "bold", label: "B", accessibilityLabel: "Bold", weight: "700" },
@@ -22,10 +23,20 @@ const TOOLS = Object.freeze([
   { key: "heading3", label: "H3", accessibilityLabel: "Subheading" },
   { key: "bullet", label: "•", accessibilityLabel: "Bulleted list" },
   { key: "ordered", label: "1.", accessibilityLabel: "Numbered list" },
+  { key: "table", label: "Table", accessibilityLabel: "Insert table" },
+  // sc-7349: the one tool a selection cannot complete — a link needs a target,
+  // so this button opens the form instead of editing the string directly.
+  {
+    key: "link",
+    label: "Link",
+    accessibilityLabel: "Insert link",
+    opensDialog: true,
+  },
 ]);
 
-export function makeMarkdownInput(rn, RichText) {
+export function makeMarkdownInput(rn, RichText, Overlay) {
   const { Text, View, Pressable, TextInput } = rn;
+  const MarkdownLinkDialog = makeMarkdownLinkDialog(rn, Overlay);
 
   function MarkdownInput({
     value,
@@ -34,6 +45,7 @@ export function makeMarkdownInput(rn, RichText) {
     previewLabel = "Preview",
     showPreview = true,
     renderImage,
+    pages,
     minHeight = 150,
     maxHeight = 280,
     accessibilityLabel,
@@ -43,6 +55,7 @@ export function makeMarkdownInput(rn, RichText) {
     const theme = useHostTheme();
     const tokens = React.useMemo(() => resolveRichTextTokens(theme), [theme]);
     const [selection, setSelection] = React.useState({ start: 0, end: 0 });
+    const [linkOpen, setLinkOpen] = React.useState(false);
 
     const text = typeof value === "string" ? value : "";
 
@@ -52,17 +65,43 @@ export function makeMarkdownInput(rn, RichText) {
     }, []);
 
     const applyTool = React.useCallback(
-      (toolKey) => {
+      (toolKey, options) => {
         if (typeof onChange !== "function") return;
         const edit = markdownEditOps[toolKey];
         if (!edit) return;
-        const next = edit(text, selection);
+        const next = edit(text, selection, options);
         onChange(next.value);
         setSelection(next.selection);
       },
       [onChange, text, selection],
     );
 
+    const pressTool = React.useCallback(
+      (tool) => {
+        if (tool.opensDialog) {
+          setLinkOpen(true);
+          return;
+        }
+        applyTool(tool.key);
+      },
+      [applyTool],
+    );
+
+    const insertLink = React.useCallback(
+      (result) => {
+        setLinkOpen(false);
+        applyTool("link", result);
+      },
+      [applyTool],
+    );
+
+    // The selection seeds the dialog's Link text, so highlighting a phrase and
+    // pressing Link keeps that phrase as the label.
+    const selected = text.slice(
+      Math.min(selection.start, selection.end),
+      Math.max(selection.start, selection.end),
+    );
+
     const fieldStyle = {
       fontFamily: tokens.bodyFont,
       fontSize: tokens.bodySize,
@@ -96,7 +135,7 @@ export function makeMarkdownInput(rn, RichText) {
             Pressable,
             {
               key: tool.key,
-              onPress: () => applyTool(tool.key),
+              onPress: () => pressTool(tool),
               accessibilityRole: "button",
               accessibilityLabel: tool.accessibilityLabel,
               testID: testID ? `${testID}-${tool.key}` : undefined,
@@ -159,10 +198,23 @@ export function makeMarkdownInput(rn, RichText) {
             React.createElement(RichText, {
               value: text,
               renderImage,
+              // sc-7349: the preview shows the reader's document, but a tap
+              // must NOT leave the page — that would throw away the draft the
+              // author is still writing.
+              followLinks: false,
               testID: testID ? `${testID}-preview` : undefined,
             }),
           )
         : null,
+      React.createElement(MarkdownLinkDialog, {
+        visible: linkOpen,
+        onClose: () => setLinkOpen(false),
+        onSubmit: insertLink,
+        tokens,
+        pages,
+        initialLabel: selected,
+        testID,
+      }),
     );
   }
 

package/dist/markdown-input.js

@@ -5,5 +5,6 @@
 import * as ReactNative from "react-native-web";
 import { makeMarkdownInput } from "./markdown-input-view.js";
 import { RichText } from "./richtext.js";
+import { Overlay } from "./overlay.js";
 
-export const MarkdownInput = makeMarkdownInput(ReactNative, RichText);
+export const MarkdownInput = makeMarkdownInput(ReactNative, RichText, Overlay);

package/dist/markdown-input.native.js

@@ -2,11 +2,15 @@
 // ./markdown-input-view.js to React Native's own primitives and the native
 // `<RichText>`. Only the imports differ from the web mirror.
 
-import { Text, View, Pressable, TextInput } from "react-native";
+import { Text, View, Pressable, TextInput, ScrollView } from "react-native";
 import { makeMarkdownInput } from "./markdown-input-view.js";
 import { RichText } from "./richtext.native.js";
+import { Overlay } from "./overlay.native.js";
 
+// sc-7349: ScrollView joins the set for the link form's page list, which must
+// scroll rather than grow an app's every page past the panel.
 export const MarkdownInput = makeMarkdownInput(
-  { Text, View, Pressable, TextInput },
+  { Text, View, Pressable, TextInput, ScrollView },
   RichText,
+  Overlay,
 );

package/dist/markdown-link-dialog.js

@@ -0,0 +1,284 @@
+// sc-7349 — the link form `<MarkdownInput>`'s Link button opens.
+//
+// A link needs a TARGET, and no selection can supply one: the author has to
+// name either a page in this app or an external address. That is a form, and a
+// form belongs in an `<Overlay>` — the SDK primitive that escapes the widget's
+// own clipping box on both hosts — not in a bespoke absolutely-positioned panel
+// the layout container would crop.
+//
+// Split out of markdown-input-view.js so each file stays one component's worth
+// of markup. Like every view module here it is bound per host by the caller
+// (see markdown-input.js / .native.js), so the two hosts cannot drift.
+
+import React from "react";
+
+// The page list scrolls rather than growing an app's 40 pages past the panel.
+const PAGE_LIST_MAX_HEIGHT = 180;
+
+export function makeMarkdownLinkDialog(rn, Overlay) {
+  const { Text, View, Pressable, TextInput, ScrollView } = rn;
+
+  function Field({ label, tokens, children }) {
+    return React.createElement(
+      View,
+      { style: { marginBottom: tokens.blockGap } },
+      React.createElement(
+        Text,
+        {
+          style: {
+            fontFamily: tokens.bodyFont,
+            fontSize: tokens.codeSize,
+            color: tokens.mutedColor,
+            marginBottom: tokens.markerGap,
+          },
+        },
+        label,
+      ),
+      children,
+    );
+  }
+
+  /**
+   * @param {object} props
+   * @param {boolean} props.visible
+   * @param {() => void} props.onClose
+   * @param {(result: {label: string, target: string}) => void} props.onSubmit
+   * @param {object} props.tokens — resolveRichTextTokens output.
+   * @param {Array<{id: string, name: string}>} props.pages — pickable pages;
+   *   empty means this host offered none, so only the URL mode is shown.
+   * @param {string} props.initialLabel — the author's current selection.
+   * @param {string} [props.testID]
+   */
+  function MarkdownLinkDialog({
+    visible,
+    onClose,
+    onSubmit,
+    tokens,
+    pages,
+    initialLabel,
+    testID,
+  }) {
+    const pageList = Array.isArray(pages) ? pages.filter((p) => p && p.id) : [];
+    const canPickPage = pageList.length > 0;
+
+    const [label, setLabel] = React.useState("");
+    const [url, setUrl] = React.useState("");
+    const [pageId, setPageId] = React.useState("");
+    const [mode, setMode] = React.useState("url");
+
+    // Re-seed on each open: the author's selection and the mode they should
+    // land in are both properties of THIS opening, not of the component.
+    React.useEffect(() => {
+      if (!visible) return;
+      setLabel(typeof initialLabel === "string" ? initialLabel : "");
+      setUrl("");
+      setPageId("");
+      setMode(canPickPage ? "page" : "url");
+    }, [visible, initialLabel, canPickPage]);
+
+    const target = mode === "page" ? pageId : url.trim();
+
+    const submit = () => {
+      if (!target) return;
+      if (typeof onSubmit === "function") onSubmit({ label, target });
+    };
+
+    const inputStyle = {
+      fontFamily: tokens.bodyFont,
+      fontSize: tokens.bodySize,
+      color: tokens.color,
+      backgroundColor: tokens.surface,
+      borderWidth: 1,
+      borderColor: tokens.border,
+      borderRadius: tokens.radius,
+      padding: tokens.markerGap,
+    };
+
+    const tab = (key, text) =>
+      React.createElement(
+        Pressable,
+        {
+          key,
+          onPress: () => setMode(key),
+          accessibilityRole: "button",
+          accessibilityState: { selected: mode === key },
+          testID: testID ? `${testID}-mode-${key}` : undefined,
+          style: {
+            paddingVertical: tokens.markerGap,
+            paddingHorizontal: tokens.padding,
+            marginRight: tokens.markerGap,
+            borderWidth: 1,
+            borderColor: mode === key ? tokens.accent : tokens.border,
+            borderRadius: tokens.radius,
+            ...(mode === key ? { backgroundColor: tokens.accent } : null),
+          },
+        },
+        React.createElement(
+          Text,
+          {
+            style: {
+              fontFamily: tokens.bodyFont,
+              fontSize: tokens.codeSize,
+              fontWeight: "500",
+              color: mode === key ? tokens.onAccent : tokens.color,
+            },
+          },
+          text,
+        ),
+      );
+
+    const action = (key, text, { primary, disabled, onPress }) =>
+      React.createElement(
+        Pressable,
+        {
+          key,
+          onPress,
+          disabled,
+          accessibilityRole: "button",
+          testID: testID ? `${testID}-${key}` : undefined,
+          style: {
+            paddingVertical: tokens.markerGap,
+            paddingHorizontal: tokens.padding,
+            marginLeft: tokens.markerGap,
+            borderWidth: 1,
+            borderColor: primary ? tokens.accent : tokens.border,
+            borderRadius: tokens.radius,
+            opacity: disabled ? 0.5 : 1,
+            ...(primary ? { backgroundColor: tokens.accent } : null),
+          },
+        },
+        React.createElement(
+          Text,
+          {
+            style: {
+              fontFamily: tokens.bodyFont,
+              fontSize: tokens.codeSize,
+              fontWeight: "500",
+              color: primary ? tokens.onAccent : tokens.color,
+            },
+          },
+          text,
+        ),
+      );
+
+    return React.createElement(
+      Overlay,
+      {
+        visible: !!visible,
+        onRequestClose: onClose,
+        size: "sm",
+        accessibilityLabel: "Insert link",
+        testID: testID ? `${testID}-dialog` : undefined,
+      },
+      React.createElement(
+        Field,
+        { label: "Link text", tokens },
+        React.createElement(TextInput, {
+          value: label,
+          onChangeText: setLabel,
+          placeholder: "Text the reader sees",
+          placeholderTextColor: tokens.mutedColor,
+          accessibilityLabel: "Link text",
+          style: inputStyle,
+          testID: testID ? `${testID}-label` : undefined,
+        }),
+      ),
+
+      // With no pages to offer there is nothing to choose between, so the
+      // switcher is hidden rather than shown with one dead option.
+      canPickPage
+        ? React.createElement(
+            View,
+            { style: { flexDirection: "row", marginBottom: tokens.blockGap } },
+            tab("page", "A page in this app"),
+            tab("url", "An external URL"),
+          )
+        : null,
+
+      mode === "page" && canPickPage
+        ? React.createElement(
+            Field,
+            { label: "Page", tokens },
+            React.createElement(
+              ScrollView,
+              {
+                style: {
+                  maxHeight: PAGE_LIST_MAX_HEIGHT,
+                  borderWidth: 1,
+                  borderColor: tokens.border,
+                  borderRadius: tokens.radius,
+                },
+                testID: testID ? `${testID}-pages` : undefined,
+              },
+              pageList.map((page) =>
+                React.createElement(
+                  Pressable,
+                  {
+                    key: page.id,
+                    onPress: () => setPageId(page.id),
+                    accessibilityRole: "button",
+                    accessibilityState: { selected: pageId === page.id },
+                    style: {
+                      padding: tokens.markerGap,
+                      ...(pageId === page.id
+                        ? { backgroundColor: tokens.surface }
+                        : null),
+                    },
+                  },
+                  React.createElement(
+                    Text,
+                    {
+                      style: {
+                        fontFamily: tokens.bodyFont,
+                        fontSize: tokens.bodySize,
+                        color: pageId === page.id ? tokens.accent : tokens.color,
+                        fontWeight: pageId === page.id ? "700" : "400",
+                      },
+                    },
+                    page.name || page.id,
+                  ),
+                ),
+              ),
+            ),
+          )
+        : React.createElement(
+            Field,
+            { label: "Address", tokens },
+            React.createElement(TextInput, {
+              value: url,
+              onChangeText: setUrl,
+              placeholder: "https://example.com",
+              placeholderTextColor: tokens.mutedColor,
+              accessibilityLabel: "Link address",
+              autoCapitalize: "none",
+              autoCorrect: false,
+              keyboardType: "url",
+              style: inputStyle,
+              testID: testID ? `${testID}-url` : undefined,
+            }),
+          ),
+
+      React.createElement(
+        View,
+        {
+          style: {
+            flexDirection: "row",
+            justifyContent: "flex-end",
+            marginTop: tokens.markerGap,
+          },
+        },
+        action("cancel", "Cancel", { onPress: onClose }),
+        // Disabled until there is somewhere to go — an empty target would
+        // write `[text]()`, which reads as a link and goes nowhere.
+        action("insert", "Insert link", {
+          primary: true,
+          disabled: !target,
+          onPress: submit,
+        }),
+      ),
+    );
+  }
+
+  MarkdownLinkDialog.displayName = "MarkdownLinkDialog";
+  return MarkdownLinkDialog;
+}