Jay Element vs Jay Component

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

Basic Definitions

A Jay Element is a function of ViewState to a certain DOM setup. The Jay Element can be represented as a Jay HTML file or other file formats, and it fully declarative, avoid of logic and safe. Jay Elements are transformed into safe JS code for a render function, update, mount and unmount functions.

A Jay Component is a function of Props to a ViewState. A Component can handle internal state, react to Props change, expose an API or events. A Jay Component is rendered to DOM using a Jay Element.

a Jay Element can contain other Jay Components or event other Jay Elements directly.

Overview

The Jay system consists of two main entities - the Jay Component and the Jay Element.

Jay Element

The Jay Element is a pure declarative design, including data and states that is represented as an HTML + CSS files. The Jay File consists of, in addition to HTML and CSS, an addition of special Jay tags and a data script that represent the inputs of the JayElement.

An example Jay Element looks like (non final syntax)

<html>
  <head>
    <script type="application/yaml-jay">
      data:
        count: number
    </script>
  </head>
  <body>
    <div>
      <button ref="subtracter">-</button>
      <span style="margin: 0 16px">{count}</span>
      <button ref="adder">+</button>
    </div>
  </body>
</html>

It is compiled into a declaration file (.d.ts) and a runtime file

The definition file:

import { JayElement } from 'jay-runtime';

export interface ViewState {
  count: number;
}

export interface CounterElement extends JayElement<ViewState> {
  subtracter: HTMLElement;
  adder: HTMLElement;
}

export declare function render(viewState: ViewState): CounterElement;

The runtime file:

import { JayElement, element as e, dynamicText as dt, ConstructContext } from 'jay-runtime';

interface ViewState {
  count: number;
}

export interface CounterElement extends JayElement<ViewState> {
  subtracter: HTMLElement;
  adder: HTMLElement;
}

export function render(viewState: ViewState): CounterElement {
  return ConstructContext.withRootContext(viewState, () =>
    e('div', {}, [
      e('button', { ref: 'subtracter' }, ['-']),
      e('span', { style: { cssText: 'margin: 0 16px' } }, [dt((vs) => vs.count)]),
      e('button', { ref: 'adder' }, ['+']),
    ]),
  ) as CounterElement;
}

Jay Component

The Jay Component adds logic to the Jay Element by composing over it, and looks like (non final syntax - we are still not sure about events syntax and if it will extend JayElement or maybe JayComponent)

A Jay Component without any state management

import { JayElement } from 'jay-runtime';
import { render, ViewState } from './counter.jay';

export function Counter(initial: number): JayElement<ViewState> {
  let count = initial;
  let element = render({ count });

  function inc() {
    count += 1;
    element.update({ count });
  }

  function dec() {
    count -= 1;
    element.update({ count });
  }

  // non final event binding syntax
  element.subtracter.onclick((_) => dec());
  element.adder.onclick((_) => inc());

  let update = (viewState: ViewState) => {
    count = viewState.count;
    element.update({ count });
  };

  return {
    dom: element.dom,
    update: update,
  };
}

The same component with state management

import { JayElement } from 'jay-runtime';
import { makeJayComponent } from 'jay-component';
import { render, ViewState } from './counter.jay';

export interface CounterProps {
  initial: number;
}

export function Counter(
  { initial }: Props<CounterProps>,
  element: CounterElement,
): JayElement<ViewState> {
  let [count, setCount] = createState(initial());

  element.subtracter.onclick((_) => setCount(count() - 1));
  element.adder.onclick((_) => setCount(count() + 1));

  return {
    render: {
      count,
    },
  };
}

export default makeJayComponent(render, Counter);

Secure running model

The model is based on Jay Elements and Jay Components who are working in conjunction to create a secure solution

Security Model

The programming model is described in Jay Element vs Component. It can run with the same runtime model as the programming model all on the same main window, or it can run as in the diagram above where elements run in the main window, and the components which are unsafe, run in a secure IFrame.

The bridge elements and components enable the system to work with a single postMessage for each update cycle that can call the update method of all components in the secure context, then call update of all elements in the main window.

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.

Jay Element Vs Component

Jay Element vs Jay Component

Jay Element

Jay Component

Secure running model

Log Methodology Note