Custom widgets (plugins)

class Sketch(Pane):
    kind = "sketch"
    label = "Sketch"
    glyph = "pen"
    family = "author"
    widget = "sketch"  # registered by sketch.js, listed in App.plugins
    tip = "A custom widget shipped as an ES module"

    def initial_state(self, ctx):
        return {"strokes": 0, "points": 0, "hint": "Draw with a finger or the mouse"}

    @event("stroke")
    def stroke(self, ctx, payload):
        st = ctx.pane.state
        return a.patch_state(ctx.cid, strokes=st.get("strokes", 0) + 1, points=st.get("points", 0) + int(payload.get("points", 0)))

class Docs(App):
    plugins = ["sketch.js"]      # relative to the file that defines the App

// sketch.js — the plugin the docs' "Custom widgets" page demonstrates: a canvas
// you draw on; each finished stroke is one event to Python with its point count.
export default function install(pl) {
  const { h, React } = pl;
  pl.css(
    "sketch",
    ".sketch { width: 100%; height: 100%; display: flex; flex-direction: column; gap: 6px; padding: 8px; }" +
      ".sketch canvas { flex: 1; min-height: 120px; width: 100%; border: 1px dashed var(--pl-pane-border); border-radius: 6px; background: var(--pl-pane-bg); touch-action: none; cursor: crosshair; }" +
      ".sketch__bar { color: var(--pl-text-dim); font-size: 12px; display: flex; justify-content: space-between; }",
  );
  pl.registerWidget("sketch", function Sketch({ state, emit }) {
    const ref = React.useRef(null);
    const pts = React.useRef([]);
    const drawing = React.useRef(false);
    function pos(e) {
      const r = ref.current.getBoundingClientRect();
      return { x: e.clientX - r.left, y: e.clientY - r.top };
    }
    function down(e) {
      drawing.current = true;
      pts.current = [pos(e)];
      ref.current.setPointerCapture(e.pointerId);
    }
    function move(e) {
      if (!drawing.current) return;
      const p = pos(e);
      const prev = pts.current[pts.current.length - 1];
      pts.current.push(p);
      const c = ref.current.getContext("2d");
      const r = ref.current.getBoundingClientRect();
      if (ref.current.width !== Math.round(r.width)) {
        ref.current.width = Math.round(r.width);
        ref.current.height = Math.round(r.height);
      }
      c.strokeStyle = getComputedStyle(ref.current).getPropertyValue("--pl-accent") || "#4f8cff";
      c.lineWidth = 2.5;
      c.lineCap = "round";
      c.beginPath();
      c.moveTo(prev.x, prev.y);
      c.lineTo(p.x, p.y);
      c.stroke();
    }
    function up() {
      if (!drawing.current) return;
      drawing.current = false;
      emit("stroke", { points: pts.current.length });
    }
    return h(
      "div",
      { className: "sketch" },
      h("canvas", { ref, onPointerDown: down, onPointerMove: move, onPointerUp: up, onPointerCancel: up }),
      h("div", { className: "sketch__bar" }, h("span", null, state?.hint ?? "Draw with a finger or the mouse"), h("span", null, `${state?.strokes ?? 0} strokes · ${state?.points ?? 0} points`)),
    );
  });
}