@notchapp/api 0.1.0 → 0.1.1

package/README.md

@@ -11,27 +11,18 @@ npm install @notchapp/api
 Use it in a widget:
 
 ```tsx
-import { Button, Stack, Text } from "@notchapp/api";
-
-export const initialState = {
-  count: 0,
-};
-
-export const actions = {
-  increment(state) {
-    return {
-      ...state,
-      count: (state?.count ?? 0) + 1,
-    };
-  },
-};
-
-export default function Widget({ environment, state }) {
+import { Button, Stack, Text, useLocalStorage } from "@notchapp/api";
+
+export default function Widget({ environment, logger }) {
+  const [count, setCount] = useLocalStorage("count", 0);
+
+  logger.info(`render hello widget span=${environment.span} count=${count}`);
+
   return (
     <Stack spacing={10}>
       <Text>Hello from NotchApp</Text>
-      <Text tone="secondary">{`Span ${environment.span} • Count ${state.count}`}</Text>
-      <Button title="Increment" action="increment" />
+      <Text tone="secondary">{`Span ${environment.span} • Count ${count}`}</Text>
+      <Button title="Increment" onPress={() => setCount((value) => value + 1)} />
     </Stack>
   );
 }
@@ -41,14 +32,47 @@ Current exports:
 
 - `Stack`
 - `Inline`
-- `Row`
+- `Spacer`
 - `Text`
 - `Icon`
+- `Image`
+- `Button`
+- `Row`
 - `IconButton`
 - `Checkbox`
 - `Input`
-- `Button`
+- `ScrollView`
+- `Divider`
+- `Circle`
+- `RoundedRect`
+- `LocalStorage`
+- `getPreferenceValues`
+- `useLocalStorage`
+- `usePromise`
+- `useFetch`
+- `openURL`
+
+Widget preferences can be declared in your widget manifest under `notch.preferences` and read at runtime:
+
+```tsx
+import { getPreferenceValues } from "@notchapp/api";
+
+export default function Widget() {
+  const preferences = getPreferenceValues();
+  return <Text>{preferences.mailbox ?? "Inbox"}</Text>;
+}
+```
 
 The SDK source and examples live in the main repository:
 
 <https://github.com/itstauq/NotchApp>
+
+Local widget images live under your package `assets/` directory and can be referenced with paths like `src="assets/cover.png"`.
+
+`Image` supports both local package assets and remote image URLs. `contentMode="fill"` is the default, and `contentMode="fit"` keeps the full image visible inside its frame.
+
+Remote image notes:
+
+- widgets use `https://` URLs only
+- remote images are fetched by the host, not inside the widget runtime
+- custom headers, cookies, and auth are not supported yet

package/functions/openURL.js

@@ -0,0 +1,9 @@
+const { callRpc } = require("../runtime");
+
+function openURL(url) {
+  return callRpc("browser.open", { url });
+}
+
+module.exports = {
+  openURL,
+};

package/hooks/useFetch.js

@@ -0,0 +1,22 @@
+const { usePromise } = require("./usePromise");
+
+function useFetch(url, options = {}) {
+  const { parseJson = true, ...requestInit } = options;
+
+  return usePromise(async (signal) => {
+    const response = await fetch(url, {
+      ...requestInit,
+      signal,
+    });
+
+    if (!response.ok) {
+      throw new Error(`Request failed with status ${response.status}`);
+    }
+
+    return parseJson ? response.json() : response.text();
+  }, [url, JSON.stringify(options)]);
+}
+
+module.exports = {
+  useFetch,
+};

package/hooks/useLocalStorage.js

@@ -0,0 +1,36 @@
+const React = require("react");
+
+const { LocalStorage } = require("../runtime");
+
+function useLocalStorage(key, defaultValue) {
+  const [value, setValue] = React.useState(() => {
+    const storedValue = LocalStorage.getItem(key);
+    return storedValue === undefined ? defaultValue : storedValue;
+  });
+
+  React.useEffect(() => {
+    const storedValue = LocalStorage.getItem(key);
+    setValue(storedValue === undefined ? defaultValue : storedValue);
+  }, [key]);
+
+  function setStoredValue(nextValue) {
+    setValue((currentValue) => {
+      const resolvedValue = typeof nextValue === "function"
+        ? nextValue(currentValue)
+        : nextValue;
+
+      if (resolvedValue === undefined) {
+        LocalStorage.removeItem(key);
+        return defaultValue;
+      }
+
+      return LocalStorage.setItem(key, resolvedValue);
+    });
+  }
+
+  return [value, setStoredValue];
+}
+
+module.exports = {
+  useLocalStorage,
+};

package/hooks/usePromise.js

@@ -0,0 +1,96 @@
+const React = require("react");
+
+function areDepsEqual(previousDeps, nextDeps) {
+  if (!previousDeps || !nextDeps || previousDeps.length !== nextDeps.length) {
+    return false;
+  }
+
+  for (let index = 0; index < previousDeps.length; index += 1) {
+    if (!Object.is(previousDeps[index], nextDeps[index])) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+function usePromise(factory, deps = []) {
+  const [state, setState] = React.useState({
+    data: undefined,
+    isLoading: true,
+    error: undefined,
+  });
+  const controllerRef = React.useRef(null);
+  const factoryRef = React.useRef(factory);
+  const depsRef = React.useRef();
+
+  factoryRef.current = factory;
+
+  const revalidate = React.useCallback(() => {
+    controllerRef.current?.abort();
+    const controller = new AbortController();
+    controllerRef.current = controller;
+
+    setState((currentState) => ({
+      data: currentState.data,
+      isLoading: true,
+      error: undefined,
+    }));
+
+    Promise.resolve()
+      .then(() => factoryRef.current(controller.signal))
+      .then((data) => {
+        if (controller.signal.aborted || controllerRef.current !== controller) {
+          return;
+        }
+
+        setState({
+          data,
+          isLoading: false,
+          error: undefined,
+        });
+      })
+      .catch((error) => {
+        if (controller.signal.aborted || controllerRef.current !== controller) {
+          return;
+        }
+
+        if (error?.name === "AbortError") {
+          return;
+        }
+
+        setState({
+          data: undefined,
+          isLoading: false,
+          error,
+        });
+      });
+  }, []);
+
+  React.useEffect(() => {
+    const depsChanged = !areDepsEqual(depsRef.current, deps);
+    depsRef.current = deps;
+    if (!depsChanged) {
+      return;
+    }
+
+    revalidate();
+  });
+
+  React.useEffect(() => {
+    return () => {
+      controllerRef.current?.abort();
+    };
+  }, []);
+
+  return {
+    data: state.data,
+    isLoading: state.isLoading,
+    error: state.error,
+    revalidate,
+  };
+}
+
+module.exports = {
+  usePromise,
+};

package/index.js

@@ -1,139 +1,161 @@
-function flattenChildren(input) {
-  if (input == null || input === false) return [];
-  if (Array.isArray(input)) return input.flatMap(flattenChildren);
-  return [input];
+const React = require("react");
+const { useLocalStorage } = require("./hooks/useLocalStorage");
+const { usePromise } = require("./hooks/usePromise");
+const { useFetch } = require("./hooks/useFetch");
+const { openURL } = require("./functions/openURL");
+const { LocalStorage, getPreferenceValues } = require("./runtime");
+
+const OVERLAY_SLOT_TYPE = "__notch_overlay";
+const LEADING_ACCESSORY_SLOT_TYPE = "__notch_leadingAccessory";
+const TRAILING_ACCESSORY_SLOT_TYPE = "__notch_trailingAccessory";
+
+function slot(type, props, children, key) {
+  return React.createElement(
+    type,
+    key == null ? props : { ...(props ?? {}), key },
+    children
+  );
+}
+
+function normalizeOverlayChildren(overlay) {
+  if (overlay == null || overlay === false) {
+    return [];
+  }
+
+  if (Array.isArray(overlay)) {
+    return overlay.flatMap(normalizeOverlayChildren);
+  }
+
+  if (React.isValidElement(overlay)) {
+    return [slot(OVERLAY_SLOT_TYPE, { alignment: "center" }, overlay, overlay.key)];
+  }
+
+  if (typeof overlay === "object") {
+    const node = overlay.element ?? overlay.node;
+    if (node != null) {
+      return [
+        slot(
+          OVERLAY_SLOT_TYPE,
+          { alignment: typeof overlay.alignment === "string" ? overlay.alignment : "center" },
+          node,
+          overlay.key ?? node.key
+        ),
+      ];
+    }
+  }
+
+  return [];
 }
 
-function extractText(input) {
-  return flattenChildren(input)
-    .map((item) => {
-      if (typeof item === "string" || typeof item === "number") return String(item);
-      if (item && typeof item.text === "string") return item.text;
-      return "";
-    })
-    .join("");
+function normalizeAccessoryChild(type, accessory) {
+  if (accessory == null || accessory === false) {
+    return [];
+  }
+
+  return [slot(type, null, accessory)];
 }
 
-function wrapNode(input) {
-  if (input == null || input === false) return null;
-  const flattened = flattenChildren(input);
-  if (flattened.length === 0) return null;
-  return { node: flattened[0] };
+function createHostElement(type, rawProps = {}) {
+  const {
+    children,
+    overlay,
+    leadingAccessory,
+    trailingAccessory,
+    ...props
+  } = rawProps;
+  const hostChildren = [];
+
+  if (children !== undefined) {
+    hostChildren.push(children);
+  }
+
+  hostChildren.push(...normalizeOverlayChildren(overlay));
+  hostChildren.push(...normalizeAccessoryChild(LEADING_ACCESSORY_SLOT_TYPE, leadingAccessory));
+  hostChildren.push(...normalizeAccessoryChild(TRAILING_ACCESSORY_SLOT_TYPE, trailingAccessory));
+
+  return React.createElement(type, props, ...hostChildren);
 }
 
 function Stack(props = {}) {
-  return {
-    id: props.id ?? undefined,
-    type: "Stack",
-    direction: props.direction ?? "vertical",
-    spacing: props.spacing ?? 8,
-    children: flattenChildren(props.children),
-  };
+  return createHostElement("Stack", props);
 }
 
 function Inline(props = {}) {
-  return {
-    id: props.id ?? undefined,
-    type: "Inline",
-    spacing: props.spacing ?? 8,
-    children: flattenChildren(props.children),
-  };
+  return createHostElement("Inline", props);
 }
 
-function Row(props = {}) {
-  return {
-    id: props.id ?? undefined,
-    type: "Row",
-    action: props.action ?? null,
-    payload: props.payload ?? null,
-    children: flattenChildren(props.children),
-  };
+function Spacer(props = {}) {
+  return createHostElement("Spacer", props);
 }
 
 function Text(props = {}) {
-  return {
-    id: props.id ?? undefined,
-    type: "Text",
-    text: props.text ?? extractText(props.children),
-    role: props.role ?? undefined,
-    tone: props.tone ?? undefined,
-    lineClamp: props.lineClamp ?? undefined,
-    strikethrough: props.strikethrough ?? undefined,
-    children: [],
-  };
+  return createHostElement("Text", props);
 }
 
 function Icon(props = {}) {
-  return {
-    id: props.id ?? undefined,
-    type: "Icon",
-    symbol: props.symbol ?? props.icon ?? props.name ?? undefined,
-    tone: props.tone ?? undefined,
-    children: [],
-  };
+  return createHostElement("Icon", props);
+}
+
+function Image(props = {}) {
+  return createHostElement("Image", props);
+}
+
+function Button(props = {}) {
+  return createHostElement("Button", props);
+}
+
+function Row(props = {}) {
+  return createHostElement("Row", props);
 }
 
 function IconButton(props = {}) {
-  return {
-    id: props.id ?? undefined,
-    type: "IconButton",
-    symbol: props.symbol ?? props.icon ?? props.name ?? undefined,
-    action: props.action ?? null,
-    payload: props.payload ?? null,
-    tone: props.tone ?? undefined,
-    disabled: props.disabled ?? false,
-    children: [],
-  };
+  return createHostElement("IconButton", props);
 }
 
 function Checkbox(props = {}) {
-  return {
-    id: props.id ?? undefined,
-    type: "Checkbox",
-    checked: props.checked ?? false,
-    action: props.action ?? null,
-    payload: props.payload ?? null,
-    children: [],
-  };
+  return createHostElement("Checkbox", props);
 }
 
 function Input(props = {}) {
-  return {
-    id: props.id ?? undefined,
-    type: "Input",
-    value: props.value ?? "",
-    placeholder: props.placeholder ?? "",
-    changeAction: props.changeAction ?? null,
-    submitAction: props.submitAction ?? null,
-    leadingAccessory: wrapNode(props.leadingAccessory),
-    trailingAccessory: wrapNode(props.trailingAccessory),
-    children: [],
-  };
+  return createHostElement("Input", props);
 }
 
-function Button(props = {}) {
-  return {
-    id: props.id ?? undefined,
-    type: "Button",
-    title: props.title ?? extractText(props.children),
-    action: props.action ?? null,
-    payload: props.payload ?? null,
-    children: [],
-  };
+function ScrollView(props = {}) {
+  return createHostElement("ScrollView", props);
+}
+
+function Divider(props = {}) {
+  return createHostElement("Divider", props);
+}
+
+function Circle(props = {}) {
+  return createHostElement("Circle", props);
+}
+
+function RoundedRect(props = {}) {
+  return createHostElement("RoundedRect", props);
 }
 
 module.exports = {
   Stack,
   Inline,
-  Row,
+  Spacer,
   Text,
   Icon,
+  Image,
+  Button,
+  Row,
   IconButton,
   Checkbox,
   Input,
-  Button,
-  __internal: {
-    flattenChildren,
-    extractText,
-  },
+  ScrollView,
+  Divider,
+  Circle,
+  RoundedRect,
+  LocalStorage,
+  getPreferenceValues,
+  useLocalStorage,
+  usePromise,
+  useFetch,
+  openURL,
 };

package/jsx-runtime.js

@@ -1,28 +1,3 @@
-const { __internal } = require("./index.js");
-
-const Fragment = Symbol.for("notch.fragment");
-
-function jsx(type, props, key) {
-  if (type === Fragment) {
-    return __internal.flattenChildren(props?.children);
-  }
-
-  const merged = { ...(props ?? {}) };
-  if (key != null && merged.id == null) {
-    merged.id = String(key);
-  }
-
-  if (typeof type === "function") {
-    return type(merged);
-  }
-
-  throw new Error(`Unsupported JSX type: ${String(type)}`);
-}
-
-const jsxs = jsx;
-
-module.exports = {
-  Fragment,
-  jsx,
-  jsxs,
-};
+// Keep JSX bound to the @notchapp/api namespace so we can evolve this seam
+// later without changing widget build configuration or source imports.
+module.exports = require("react/jsx-runtime");

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@notchapp/api",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Widget component API for building NotchApp widgets",
   "main": "index.js",
   "files": [
     "index.js",
-    "jsx-runtime.js"
+    "jsx-runtime.js",
+    "runtime.js",
+    "hooks",
+    "functions"
   ],
   "keywords": [
     "notchapp",

package/runtime.js

@@ -0,0 +1,34 @@
+function runtime() {
+  if (!globalThis.__NOTCH_RUNTIME__) {
+    throw new Error("@notchapp/api must run inside the Notch widget runtime");
+  }
+
+  return globalThis.__NOTCH_RUNTIME__;
+}
+
+module.exports = {
+  LocalStorage: {
+    getItem(key) {
+      return runtime().localStorage.getItem(key);
+    },
+    setItem(key, value) {
+      return runtime().localStorage.setItem(key, value);
+    },
+    removeItem(key) {
+      return runtime().localStorage.removeItem(key);
+    },
+    allItems() {
+      return runtime().localStorage.allItems();
+    },
+  },
+  getPreferenceValues() {
+    const preferences = runtime().getCurrentProps()?.preferences;
+    if (!preferences || typeof preferences !== "object" || Array.isArray(preferences)) {
+      return {};
+    }
+
+    return structuredClone(preferences);
+  },
+  getCurrentProps: () => runtime().getCurrentProps(),
+  callRpc: (method, params) => runtime().callRpc(method, params),
+};