react-pebble 0.1.0

package/src/hooks/index.ts

@@ -0,0 +1,311 @@
+/**
+ * hooks/index.ts — React hooks for react-pebble.
+ *
+ * This set intentionally covers only what the Alloy runtime can support
+ * today. Sensor / connectivity hooks (battery, BT connection, accelerometer,
+ * phone↔watch messaging) used to live here based on a fictional `Pebble`
+ * global; they've been removed until we've identified the real Moddable
+ * module shape for each one.
+ *
+ * See `pebble-render.ts` for the runtime wiring that lets `useTime` and
+ * `useButton` actually fire on-device — hooks publish to registries that the
+ * renderer connects to Moddable's `watch` event source.
+ */
+
+import { createContext } from 'preact';
+import {
+  useCallback,
+  useContext,
+  useEffect,
+  useRef,
+  useState as _preactUseState,
+} from 'preact/hooks';
+
+// Wrap useState so the compiler can swap the implementation at compile time.
+// Direct ESM re-exports are sealed (getter-only), so we use a mutable
+// internal reference that the compiler patches via _setUseStateImpl().
+type UseStateFn = <T>(init: T | (() => T)) => [T, (v: T | ((p: T) => T)) => void];
+let _useStateImpl: UseStateFn = _preactUseState;
+
+export function useState<T>(init: T | (() => T)): [T, (v: T | ((p: T) => T)) => void] {
+  return _useStateImpl(init);
+}
+
+/** @internal — called by the compiler to intercept useState calls. */
+export function _setUseStateImpl(impl: UseStateFn): void {
+  _useStateImpl = impl;
+}
+
+/** @internal — restore original useState after compilation. */
+export function _restoreUseState(): void {
+  _useStateImpl = _preactUseState;
+}
+import type { PebbleApp } from '../pebble-render.js';
+
+// ---------------------------------------------------------------------------
+// Button types
+// ---------------------------------------------------------------------------
+
+export type PebbleButton = 'up' | 'down' | 'select' | 'back';
+export type PebbleButtonHandler = () => void;
+
+// ---------------------------------------------------------------------------
+// App context — provides access to the render app from nested components.
+// ---------------------------------------------------------------------------
+
+export const PebbleAppContext = createContext<PebbleApp | null>(null);
+
+export function useApp(): PebbleApp {
+  const app = useContext(PebbleAppContext);
+  if (!app) {
+    throw new Error('useApp must be used inside a react-pebble render tree');
+  }
+  return app;
+}
+
+// ---------------------------------------------------------------------------
+// Button registry
+//
+// Buttons are delivered to react-pebble two ways:
+//   (a) via props on elements (onUp/onDown/onSelect/onBack), collected and
+//       subscribed to Moddable's `watch` in pebble-render.ts; or
+//   (b) via this hook registry, which the renderer pumps from `watch` events.
+//
+// The registry is the substrate for both `useButton` and `useLongButton`.
+// The exact `watch` event names for buttons are not yet confirmed — the
+// renderer normalizes them into our four logical buttons before emitting.
+// ---------------------------------------------------------------------------
+
+type ButtonRegistryKey = PebbleButton | `long_${PebbleButton}`;
+
+interface ButtonRegistryShape {
+  _listeners: Map<ButtonRegistryKey, Set<PebbleButtonHandler>>;
+  subscribe(button: ButtonRegistryKey, fn: PebbleButtonHandler): void;
+  unsubscribe(button: ButtonRegistryKey, fn: PebbleButtonHandler): void;
+  emit(button: ButtonRegistryKey): void;
+}
+
+export const ButtonRegistry: ButtonRegistryShape = {
+  _listeners: new Map<ButtonRegistryKey, Set<PebbleButtonHandler>>(),
+
+  subscribe(button, fn) {
+    let set = this._listeners.get(button);
+    if (!set) {
+      set = new Set();
+      this._listeners.set(button, set);
+    }
+    set.add(fn);
+  },
+
+  unsubscribe(button, fn) {
+    const set = this._listeners.get(button);
+    if (set) {
+      set.delete(fn);
+      if (set.size === 0) this._listeners.delete(button);
+    }
+  },
+
+  emit(button) {
+    const set = this._listeners.get(button);
+    if (set) {
+      for (const fn of set) fn();
+    }
+  },
+};
+
+export function useButton(button: PebbleButton, handler: PebbleButtonHandler): void {
+  const handlerRef = useRef(handler);
+  handlerRef.current = handler;
+
+  useEffect(() => {
+    const listener: PebbleButtonHandler = () => handlerRef.current();
+    ButtonRegistry.subscribe(button, listener);
+    return () => {
+      ButtonRegistry.unsubscribe(button, listener);
+    };
+  }, [button]);
+}
+
+export function useLongButton(button: PebbleButton, handler: PebbleButtonHandler): void {
+  const handlerRef = useRef(handler);
+  handlerRef.current = handler;
+
+  useEffect(() => {
+    const listener: PebbleButtonHandler = () => handlerRef.current();
+    const key: ButtonRegistryKey = `long_${button}`;
+    ButtonRegistry.subscribe(key, listener);
+    return () => ButtonRegistry.unsubscribe(key, listener);
+  }, [button]);
+}
+
+// ---------------------------------------------------------------------------
+// Time hooks
+//
+// On Alloy, `watch.addEventListener('secondchange'|'minutechange', fn)` is
+// the canonical tick source. In Node mock mode we fall back to setInterval.
+// Both paths are abstracted away by the renderer, which pumps the tick into
+// the hook via React state — here we just use setInterval directly, which
+// works in both XS and Node. (`watch` is used for redraws, not hook state.)
+// ---------------------------------------------------------------------------
+
+export function useTime(intervalMs = 1000): Date {
+  const [time, setTime] = useState<Date>(() => new Date());
+
+  useEffect(() => {
+    const tick = () => setTime(new Date());
+    const id = setInterval(tick, intervalMs);
+    return () => clearInterval(id);
+  }, [intervalMs]);
+
+  return time;
+}
+
+export function useFormattedTime(format = 'HH:mm'): string {
+  const time = useTime(format.includes('ss') ? 1000 : 60000);
+
+  const hours24 = time.getHours();
+  const hours12 = hours24 % 12 || 12;
+  const minutes = time.getMinutes().toString().padStart(2, '0');
+  const seconds = time.getSeconds().toString().padStart(2, '0');
+  const ampm = hours24 < 12 ? 'AM' : 'PM';
+
+  let result = format;
+  result = result.replace('HH', hours24.toString().padStart(2, '0'));
+  result = result.replace('hh', hours12.toString().padStart(2, '0'));
+  result = result.replace('mm', minutes);
+  result = result.replace('ss', seconds);
+  result = result.replace('a', ampm);
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// useInterval
+// ---------------------------------------------------------------------------
+
+export function useInterval(callback: () => void, delay: number | null): void {
+  const savedCallback = useRef(callback);
+  savedCallback.current = callback;
+
+  useEffect(() => {
+    if (delay === null) return;
+
+    const id = setInterval(() => savedCallback.current(), delay);
+    return () => clearInterval(id);
+  }, [delay]);
+}
+
+// ---------------------------------------------------------------------------
+// List navigation
+// ---------------------------------------------------------------------------
+
+export interface ListNavigationOptions {
+  wrap?: boolean;
+}
+
+export interface ListNavigationResult<T> {
+  index: number;
+  item: T | undefined;
+  next: () => void;
+  prev: () => void;
+  setIndex: (index: number) => void;
+}
+
+export function useListNavigation<T>(
+  items: readonly T[],
+  options: ListNavigationOptions = {},
+): ListNavigationResult<T> {
+  const { wrap = false } = options;
+  const [index, setIndex] = useState(0);
+
+  const next = useCallback(() => {
+    setIndex((i) => {
+      if (i >= items.length - 1) return wrap ? 0 : i;
+      return i + 1;
+    });
+  }, [items.length, wrap]);
+
+  const prev = useCallback(() => {
+    setIndex((i) => {
+      if (i <= 0) return wrap ? items.length - 1 : i;
+      return i - 1;
+    });
+  }, [items.length, wrap]);
+
+  useButton('down', next);
+  useButton('up', prev);
+
+  return {
+    index,
+    item: items[index],
+    next,
+    prev,
+    setIndex,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// useMessage — runtime data loading via phone→watch messaging
+// ---------------------------------------------------------------------------
+
+export interface UseMessageOptions<T> {
+  /** Message key name (must match PebbleKit JS sendAppMessage key) */
+  key: string;
+  /** Mock data returned at compile time so the compiler can render the loaded state */
+  mockData: T;
+  /** Delay in ms before mock data appears (for SETTLE_MS) */
+  mockDelay?: number;
+}
+
+export interface UseMessageResult<T> {
+  data: T | null;
+  loading: boolean;
+}
+
+/**
+ * Load data from the phone at runtime via Pebble's Message API.
+ *
+ * At compile time (Node mock mode): returns mockData after mockDelay ms.
+ * At runtime (Alloy): the compiler emits a Message subscription that
+ * populates data when the phone sends it.
+ *
+ * Usage:
+ *   const { data, loading } = useMessage({
+ *     key: 'items',
+ *     mockData: [{ title: 'Fix bug', status: 'Open' }],
+ *   });
+ */
+export function useMessage<T>(options: UseMessageOptions<T>): UseMessageResult<T> {
+  const [data, setData] = useState<T | null>(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    // In mock mode (compile time), simulate async data arrival
+    const timer = setTimeout(() => {
+      setData(options.mockData);
+      setLoading(false);
+    }, options.mockDelay ?? 100);
+    return () => clearTimeout(timer);
+  }, []);
+
+  return { data, loading };
+}
+
+// ---------------------------------------------------------------------------
+// REMOVED HOOKS — reference for future reimplementation
+//
+//   - useBattery         — previously read Pebble.battery (fictional global).
+//                          Alloy equivalent: probably a Moddable power
+//                          module; not yet explored.
+//   - useConnection      — previously Pebble.connection.isConnected().
+//                          Alloy equivalent: `watch.connected` property was
+//                          observed on the watch prototype but its shape is
+//                          unknown.
+//   - useAccelerometer   — previously Pebble.accel. Alloy has Moddable
+//                          sensor modules; specific import path unknown.
+//   - useAppMessage      — previously Pebble.sendAppMessage / addEventListener
+//                          for 'appmessage'. Alloy has no direct equivalent;
+//                          phone↔watch messaging goes through PebbleKit JS on
+//                          the phone side (`src/pkjs/index.js`) and is a
+//                          separate concern.
+// ---------------------------------------------------------------------------

package/src/index.ts

@@ -0,0 +1,126 @@
+/**
+ * react-pebble — A React renderer for Pebble Alloy (Moddable XS / Poco).
+ *
+ * Usage on Alloy:
+ *   import Poco from 'commodetto/Poco';
+ *   import React from 'react';
+ *   import { render, Group, Rect, Text } from 'react-pebble';
+ *   import { useTime } from 'react-pebble/hooks';
+ *
+ *   function WatchFace() {
+ *     const time = useTime();
+ *     return (
+ *       <Group>
+ *         <Rect x={0} y={0} w={200} h={228} fill="black" />
+ *         <Text x={0} y={90} w={200} font="bitham42Bold" color="white" align="center">
+ *           {time.getHours()}:{time.getMinutes().toString().padStart(2, '0')}
+ *         </Text>
+ *       </Group>
+ *     );
+ *   }
+ *
+ *   render(<WatchFace />, { poco: Poco });
+ */
+
+// Platform / screen dimensions
+export { SCREEN, PLATFORMS, _setPlatform } from './platform.js';
+export type { PebblePlatform } from './platform.js';
+
+// Core render API
+export { render } from './pebble-render.js';
+export type {
+  PebbleApp,
+  PebblePlatformInfo,
+  RenderOptions,
+  RenderOptionsExt,
+  DrawCall,
+} from './pebble-render.js';
+
+// Component wrappers
+export {
+  Window,
+  Rect,
+  Circle,
+  Text,
+  Line,
+  Image,
+  Group,
+  StatusBar,
+  ActionBar,
+  Card,
+  Badge,
+} from './components/index.js';
+export type {
+  WindowProps,
+  RectProps,
+  CircleProps,
+  TextProps,
+  LineProps,
+  ImageProps,
+  GroupProps,
+  StatusBarProps,
+  ActionBarProps,
+  CardProps,
+  BadgeProps,
+  PositionProps,
+  SizeProps,
+  ButtonHandlerProps,
+  ColorName,
+  FontName,
+  Alignment,
+} from './components/index.js';
+
+// Hooks
+export {
+  useApp,
+  useButton,
+  useLongButton,
+  useTime,
+  useFormattedTime,
+  useInterval,
+  useListNavigation,
+  ButtonRegistry,
+  PebbleAppContext,
+} from './hooks/index.js';
+export type {
+  PebbleButton,
+  PebbleButtonHandler,
+  ListNavigationOptions,
+  ListNavigationResult,
+} from './hooks/index.js';
+
+// Low-level access (for advanced usage / custom renderers / tests)
+export { default as reconciler } from './pebble-reconciler.js';
+export {
+  ELEMENT_TYPES,
+  appendChildNode,
+  createNode,
+  createTextNode,
+  findRoot,
+  getTextContent,
+  insertBeforeNode,
+  removeChildNode,
+  setAttribute,
+  setTextNodeValue,
+  walkTree,
+} from './pebble-dom.js';
+export type {
+  AnyNode,
+  DOMElement,
+  ElementType,
+  NodeProps,
+  TextNode,
+  Visitor,
+} from './pebble-dom.js';
+export {
+  PocoRenderer,
+  COLOR_PALETTE,
+  FONT_PALETTE,
+  resolveColorName,
+  resolveFontName,
+} from './pebble-output.js';
+export type {
+  RGB,
+  FontSpec,
+  RenderOptions as PocoRenderOptions,
+} from './pebble-output.js';

package/src/pebble-dom-shim.ts

@@ -0,0 +1,266 @@
+/**
+ * pebble-dom-shim.ts — A minimal DOM-like adapter over `pebble-dom` so
+ * Preact's `render(vnode, parentDom)` can drive it.
+ *
+ * Preact's diff loop mutates a tree of DOM-shaped nodes by calling:
+ *   - document.createElement(tag)
+ *   - document.createTextNode(text)
+ *   - parent.appendChild(child), .insertBefore(child, ref), .removeChild(child)
+ *   - element.setAttribute(name, value), .removeAttribute(name)
+ *   - element.addEventListener(name, handler), .removeEventListener(...)
+ *   - element.nodeType, .nodeName, .parentNode, .childNodes, .firstChild,
+ *     .nextSibling
+ *
+ * This file implements the minimum surface Preact actually touches when
+ * rendering into a headless tree. Each "element" carries a reference to the
+ * underlying pebble-dom node so the renderer can walk both views
+ * interchangeably.
+ *
+ * The shim is deliberately NOT a full undom — it only does what Preact 10
+ * needs. If we trip on a missing method, add it here rather than including
+ * undom (which would push the bundle back up).
+ */
+
+import type { AnyNode, DOMElement, ElementType, TextNode } from './pebble-dom.js';
+import {
+  ELEMENT_TYPES,
+  appendChildNode,
+  createNode,
+  createTextNode,
+  insertBeforeNode,
+  removeChildNode,
+  setAttribute,
+  setTextNodeValue,
+} from './pebble-dom.js';
+
+// ---------------------------------------------------------------------------
+// DOM node interfaces the shim exposes to Preact
+// ---------------------------------------------------------------------------
+
+interface ShimNodeBase {
+  readonly nodeType: number;
+  nodeName: string;
+  parentNode: ShimElement | null;
+  childNodes: ShimNode[];
+  firstChild: ShimNode | null;
+  nextSibling: ShimNode | null;
+  /** The backing pebble-dom node. */
+  readonly _pbl: AnyNode;
+}
+
+export interface ShimElement extends ShimNodeBase {
+  readonly nodeType: 1;
+  readonly localName: string;
+  readonly tagName: string;
+  readonly _pbl: DOMElement;
+  attributes: Record<string, unknown>;
+
+  appendChild<T extends ShimNode>(child: T): T;
+  insertBefore<T extends ShimNode>(child: T, ref: ShimNode | null): T;
+  removeChild<T extends ShimNode>(child: T): T;
+  remove(): void;
+
+  setAttribute(name: string, value: unknown): void;
+  removeAttribute(name: string): void;
+  getAttribute(name: string): unknown;
+
+  addEventListener(name: string, handler: (...args: unknown[]) => unknown): void;
+  removeEventListener(name: string, handler: (...args: unknown[]) => unknown): void;
+}
+
+export interface ShimText extends ShimNodeBase {
+  readonly nodeType: 3;
+  readonly _pbl: TextNode;
+  data: string;
+  nodeValue: string;
+  textContent: string;
+}
+
+export type ShimNode = ShimElement | ShimText;
+
+// ---------------------------------------------------------------------------
+// Shim factories
+// ---------------------------------------------------------------------------
+
+function linkSiblings(parent: ShimElement): void {
+  const kids = parent.childNodes;
+  parent.firstChild = kids[0] ?? null;
+  for (let i = 0; i < kids.length; i++) {
+    const node = kids[i]!;
+    node.parentNode = parent;
+    node.nextSibling = kids[i + 1] ?? null;
+  }
+}
+
+export function createShimElement(tag: string): ShimElement {
+  // Accept both 'pbl-rect' and friendly aliases from components. Unknown
+  // tags are rejected loudly so typos surface at render time.
+  const pblType = tag as ElementType;
+  if (!ELEMENT_TYPES.has(pblType)) {
+    throw new Error(`react-pebble: unknown element tag "${tag}"`);
+  }
+
+  const pbl = createNode(pblType);
+
+  const el: ShimElement = {
+    nodeType: 1,
+    nodeName: tag.toUpperCase(),
+    localName: tag,
+    tagName: tag.toUpperCase(),
+    _pbl: pbl,
+    attributes: {},
+    parentNode: null,
+    childNodes: [],
+    firstChild: null,
+    nextSibling: null,
+
+    appendChild(child) {
+      // Detach from any prior parent in the shim view
+      if (child.parentNode) {
+        child.parentNode.removeChild(child);
+      }
+      this.childNodes.push(child);
+      appendChildNode(pbl, child._pbl);
+      linkSiblings(this);
+      return child;
+    },
+
+    insertBefore(child, ref) {
+      if (child.parentNode) {
+        child.parentNode.removeChild(child);
+      }
+      if (ref === null) {
+        return this.appendChild(child);
+      }
+      const idx = this.childNodes.indexOf(ref);
+      if (idx < 0) {
+        return this.appendChild(child);
+      }
+      this.childNodes.splice(idx, 0, child);
+      insertBeforeNode(pbl, child._pbl, ref._pbl);
+      linkSiblings(this);
+      return child;
+    },
+
+    removeChild(child) {
+      const idx = this.childNodes.indexOf(child);
+      if (idx >= 0) {
+        this.childNodes.splice(idx, 1);
+      }
+      removeChildNode(pbl, child._pbl);
+      child.parentNode = null;
+      child.nextSibling = null;
+      linkSiblings(this);
+      return child;
+    },
+
+    remove() {
+      if (this.parentNode) {
+        this.parentNode.removeChild(this);
+      }
+    },
+
+    setAttribute(name, value) {
+      this.attributes[name] = value;
+      setAttribute(pbl, name, value);
+    },
+
+    removeAttribute(name) {
+      delete this.attributes[name];
+      setAttribute(pbl, name, undefined);
+    },
+
+    getAttribute(name) {
+      return this.attributes[name];
+    },
+
+    addEventListener(name, handler) {
+      // Event handlers are stored in props (on* style) so the button wiring
+      // in pebble-render.ts can find them the same way React props do.
+      const key = `on${name[0]?.toUpperCase()}${name.slice(1)}`;
+      this.attributes[key] = handler;
+      setAttribute(pbl, key, handler);
+    },
+
+    removeEventListener(name, _handler) {
+      const key = `on${name[0]?.toUpperCase()}${name.slice(1)}`;
+      delete this.attributes[key];
+      setAttribute(pbl, key, undefined);
+    },
+  };
+
+  return el;
+}
+
+export function createShimText(data: string): ShimText {
+  const pbl = createTextNode(data);
+
+  const node: ShimText = {
+    nodeType: 3,
+    nodeName: '#text',
+    _pbl: pbl,
+    data,
+    nodeValue: data,
+    textContent: data,
+    parentNode: null,
+    childNodes: [],
+    firstChild: null,
+    nextSibling: null,
+  };
+
+  // Keep pebble-dom in sync whenever data/nodeValue/textContent is assigned.
+  // Preact mutates `.data` directly on text updates.
+  Object.defineProperty(node, 'data', {
+    get() {
+      return pbl.value;
+    },
+    set(next: string) {
+      setTextNodeValue(pbl, next);
+    },
+  });
+  Object.defineProperty(node, 'nodeValue', {
+    get() {
+      return pbl.value;
+    },
+    set(next: string) {
+      setTextNodeValue(pbl, next);
+    },
+  });
+  Object.defineProperty(node, 'textContent', {
+    get() {
+      return pbl.value;
+    },
+    set(next: string) {
+      setTextNodeValue(pbl, next);
+    },
+  });
+
+  return node;
+}
+
+// ---------------------------------------------------------------------------
+// Shim "document" — what Preact reaches via `parentDom.ownerDocument` etc.
+// ---------------------------------------------------------------------------
+
+export interface ShimDocument {
+  createElement(tag: string): ShimElement;
+  createElementNS(ns: string | null, tag: string): ShimElement;
+  createTextNode(data: string): ShimText;
+}
+
+export const shimDocument: ShimDocument = {
+  createElement: createShimElement,
+  createElementNS: (_ns, tag) => createShimElement(tag),
+  createTextNode: createShimText,
+};
+
+// ---------------------------------------------------------------------------
+// Root container — the "parent DOM" handed to preact.render().
+// ---------------------------------------------------------------------------
+
+export function createShimRoot(): ShimElement {
+  const root = createShimElement('pbl-root');
+  // Preact reads `ownerDocument` off the parent.
+  (root as unknown as { ownerDocument: ShimDocument }).ownerDocument = shimDocument;
+  return root;
+}