Redo Events

Written for AI agents. See Log Methodology Note below for details.

Reminder

---

Reminder from Events we have chosen to create events using the ref object

refs.dec.onclick = (event) => dec();

The event parameter is the native DOM event object.

For events on elements under a forEach construct, we also get the data item

refs.label.onclick = (event, viewState) => dec(viewState);

Again, the event is the native DOM event object, while the viewState is the current data object from the latest forEach relative to the element.

New Requirements

Incorporating into the requirements for events the needs from secure architecture we need to change the events model a bit different

1. Support secure context, which means event handler does not have access to the DOM
2. Support scoped access to the DOM, which enables
   1. secure and custom logic
   2. reading values from the DOM
   3. returning values to the event handler
   4. conditionally invoke 'APIs gated by user activation'
3. Unify the event handler for static and forEach elements
4. Getting the element coordinate to facilitate main to sandbox communication

The New (low level) API

presented are 4 variants of the API (the compiler can introduce higher level abstractions over the API, making it more user friendly)

// with native handler (which can be secure)

refs.dec.onclick
  .nativeHandler((event, viewState) => {
    return event.target.value;
  })
  .handler((value, viewState, coordinate) => {});

refs.dec
  .onclickNative((event, viewState) => {
    return event.target.value;
  })
  .then((value, viewState, coordinate) => {});

refs.dec.onclick = native((event, viewState) => {
  return event.target.value;
}).then((value, viewState, coordinate) => {});

refs.dec.onclick = createNativeEvent((event, viewState) => {
  return event.target.value;
}).then((value, viewState, coordinate) => {});

// without native handler

refs.dec.onclick.handler((viewState, coordinate) => {});

refs.dec.onclick((viewState, coordinate) => {});

refs.dec.onclick = (viewState, coordinate) => {};

refs.dec.onclick = createEvent((viewState, coordinate) => {});

Investigating code completion for the event type and view state types, we see that the 3rd and 4th options do not work. We can see an example here.

The 2nd option works - we can see that here

Final API

refs.el.onclick((viewState, coordinate) => {});
refs.el
  .$onclick((event, viewState) => {
    return 17;
  })
  .then((eventData, viewState, coordiate) => {});

formally, we generate Refs elements as

interface JayNativeEventBuilder<ViewState, EventData> {
  then(handler: (eventData: EventData, viewState: ViewState, coordinate: string) => void): void;
}

interface Element<ViewState> {
  onclick(handler: (viewState: ViewState, coordinate: string) => void): void;
  $onclick<EventData>(
    nativeHandler: (event: MouseEvent, viewState: ViewState) => EventData,
  ): JayNativeEventBuilder<ViewState, EventData>;
}

How it works

The two events patterns are

1. onclick events when there is no need to access the native event, or use APIs gated by user action.
2. $onclick enabling access to the native event.

with regular (non-secure) runtime, the first pattern is trivial, while the second just runs the nativeHandler and then the handler.

For sandbox (secure) components, a few things happen

refs.dec
  .$onclick((event, viewState) => {
    return event.target.value;
  })
  .then((value, viewState, coordinate) => {
    console.log(value);
  });

transforms into

// main window / secure context
import { f12 } from 'native-handlers';

refs.dec.onclick((event, viewState, coordinate) => {
  channel.invokeEvent(f12(event, viewState), componentId, coordinate);
});

// secure context / component
refs.dec.onclick((value, viewState, coordinate) => {
  console.log(value);
});

1. The compiler detects $onclick in the component
2. For the component bridge, it creates an equivalent onclick, with code compiled from the native handler
3. For the component itself, it replaces $onclick with onclick running the second function

---

Log Methodology Note

Note: These design logs are written primarily for AI agents as part of the Design Log methodology and made accessible here for human readers. The language and structure are optimized for machine consumption — expect precise, specification-style prose rather than narrative documentation.