@jay-framework/component 0.5.0

package/dist/index.d.ts

@@ -0,0 +1,69 @@
+import { JayElement, ContextMarker, PreRenderElement, JayComponent, EventEmitter } from '@jay-framework/runtime';
+import { Getter, Reactive, ValueOrGetter, Setter } from '@jay-framework/reactive';
+import { JSONPatch } from '@jay-framework/json-patch';
+import { HTMLElement } from 'node-html-parser';
+
+type Patcher<T> = (...patch: JSONPatch) => void;
+type hasProps<PropsT> = {
+    props: Getter<PropsT>;
+};
+type Props<PropsT> = hasProps<PropsT> & {
+    [K in keyof PropsT]: K extends string ? Getter<PropsT[K]> : PropsT[K];
+};
+type ViewStateGetters<ViewState> = {
+    [K in keyof ViewState]: ViewState[K] | Getter<ViewState[K]>;
+};
+type UpdatableProps<PropsT> = Props<PropsT> & {
+    update(newProps: PropsT): any;
+};
+interface JayComponentCore<PropsT, ViewState> {
+    render: () => ViewStateGetters<ViewState>;
+}
+type ConcreteJayComponent1<PropsT extends object, ViewState, Refs, CompCore extends JayComponentCore<PropsT, ViewState>, JayElementT extends JayElement<ViewState, Refs>> = Omit<CompCore, 'render'> & JayComponent<PropsT, ViewState, JayElementT>;
+type ConcreteJayComponent<PropsT extends object, ViewState, Refs, CompCore extends JayComponentCore<PropsT, ViewState>, JayElementT extends JayElement<ViewState, Refs>> = ConcreteJayComponent1<PropsT, ViewState, Refs, CompCore, JayElementT>;
+declare function materializeViewState<ViewState extends object>(vsValueOrGetter: ViewStateGetters<ViewState>): ViewState;
+type ComponentConstructor<PropsT extends object, Refs extends object, ViewState extends object, Contexts extends Array<any>, CompCore extends JayComponentCore<PropsT, ViewState>> = (props: Props<PropsT>, refs: Refs, ...contexts: Contexts) => CompCore;
+type ContextMarkers<T extends any[]> = {
+    [K in keyof T]: ContextMarker<T[K]>;
+};
+declare function makeJayComponent<PropsT extends object, ViewState extends object, Refs extends object, JayElementT extends JayElement<ViewState, Refs>, Contexts extends Array<any>, CompCore extends JayComponentCore<PropsT, ViewState>>(preRender: PreRenderElement<ViewState, Refs, JayElementT>, comp: ComponentConstructor<PropsT, Refs, ViewState, Contexts, CompCore>, ...contextMarkers: ContextMarkers<Contexts>): (props: PropsT) => ConcreteJayComponent<PropsT, ViewState, Refs, CompCore, JayElementT>;
+type JsxNode = HTMLElement;
+type JayTsxComponentConstructor<PropsT extends object, CompT extends {
+    render: () => JsxNode;
+}> = (props: Props<PropsT>) => CompT;
+declare function makeJayTsxComponent<PropsT extends object, CompT extends {
+    render: () => JsxNode;
+}>(comp: JayTsxComponentConstructor<PropsT, CompT>): JayComponent<PropsT, any, any>;
+declare function makePropsProxy<PropsT extends object>(reactive: Reactive, props: PropsT): UpdatableProps<PropsT>;
+declare const forTesting: {
+    makePropsProxy: typeof makePropsProxy;
+};
+
+declare const CONTEXT_REACTIVE_SYMBOL_CONTEXT: unique symbol;
+declare function createReactiveContext<T extends object>(mkContext: () => T): T;
+
+type EffectCleanup = () => void;
+declare function createEffect(effect: () => void | EffectCleanup): void;
+declare function createSignal<T>(value: ValueOrGetter<T>): [get: Getter<T>, set: Setter<T>];
+declare function createPatchableSignal<T>(value: ValueOrGetter<T>): [get: Getter<T>, set: Setter<T>, patchFunc: Patcher<T>];
+declare function useReactive(): Reactive;
+declare function createMemo<T>(computation: (prev: T) => T, initialValue?: T): Getter<T>;
+declare function createDerivedArray<T extends object, U>(arrayGetter: Getter<T[]>, mapCallback: (item: Getter<T>, index: Getter<number>, length: Getter<number>) => U): Getter<U[]>;
+declare function createEvent<EventType>(eventEffect?: (emitter: EventEmitter<EventType, any>) => void): EventEmitter<EventType, any>;
+declare function provideContext<ContextType>(marker: ContextMarker<ContextType>, context: ContextType): void;
+declare function provideReactiveContext<ContextType extends object>(marker: ContextMarker<ContextType>, mkContext: () => ContextType): ContextType;
+
+interface HookContext {
+    reactive: Reactive;
+    mountedSignal: [Getter<boolean>, Setter<boolean>];
+    provideContexts: [ContextMarker<any>, any][];
+}
+interface ComponentContext extends HookContext {
+    reactive: Reactive;
+    getComponentInstance: () => JayComponent<any, any, any>;
+    mountedSignal: [Getter<boolean>, Setter<boolean>];
+}
+declare const COMPONENT_CONTEXT: ContextMarker<ComponentContext>;
+declare const CONTEXT_CREATION_CONTEXT: ContextMarker<HookContext>;
+
+export { COMPONENT_CONTEXT, CONTEXT_CREATION_CONTEXT, CONTEXT_REACTIVE_SYMBOL_CONTEXT, type ComponentConstructor, type ComponentContext, type ConcreteJayComponent, type ContextMarkers, type EffectCleanup, type HookContext, type JayComponentCore, type JayTsxComponentConstructor, type JsxNode, type Patcher, type Props, type UpdatableProps, type ViewStateGetters, createDerivedArray, createEffect, createEvent, createMemo, createPatchableSignal, createReactiveContext, createSignal, forTesting, type hasProps, makeJayComponent, makeJayTsxComponent, makePropsProxy, materializeViewState, provideContext, provideReactiveContext, useReactive };

package/dist/index.js

@@ -0,0 +1,322 @@
+import { createJayContext, withContext, findContext, useContext } from "@jay-framework/runtime";
+import { mkReactive, GetterMark, SetterMark, MeasureOfChange } from "@jay-framework/reactive";
+import { patch } from "@jay-framework/json-patch";
+const COMPONENT_CONTEXT = createJayContext();
+const CONTEXT_CREATION_CONTEXT = createJayContext();
+const CONTEXT_REACTIVE_SYMBOL_CONTEXT = Symbol("context-reactive");
+function newContextProxy(reactive, context) {
+  const wrapped = /* @__PURE__ */ new Map();
+  const wrap = (target) => {
+    if (!wrapped.has(target))
+      wrapped.set(
+        target,
+        (...args) => reactive.batchReactions(() => target.apply(context, args))
+      );
+    return wrapped.get(target);
+  };
+  return new Proxy(context, {
+    get(target, p, receiver) {
+      if (p === CONTEXT_REACTIVE_SYMBOL_CONTEXT)
+        return reactive;
+      else if (!target[p][GetterMark] && !target[p][SetterMark] && typeof target[p] === "function")
+        return wrap(target[p]);
+      else
+        return target[p];
+    }
+  });
+}
+function createReactiveContext(mkContext) {
+  const reactive = mkReactive("ctx", mkContext.name);
+  const context = withContext(
+    CONTEXT_CREATION_CONTEXT,
+    { reactive, mountedSignal: reactive.createSignal(true), provideContexts: [] },
+    mkContext
+  );
+  return newContextProxy(reactive, context);
+}
+function currentHookContext() {
+  return findContext((_) => _ === COMPONENT_CONTEXT || _ === CONTEXT_CREATION_CONTEXT);
+}
+function createEffect(effect) {
+  let cleanup = void 0;
+  const clean = () => {
+    if (cleanup !== void 0) {
+      cleanup();
+      cleanup = void 0;
+    }
+  };
+  let lastMounted = false;
+  const mounted = currentHookContext().mountedSignal[0];
+  currentHookContext().reactive.createReaction(() => {
+    if (lastMounted !== mounted()) {
+      if (mounted())
+        cleanup = effect();
+      else
+        clean();
+      lastMounted = mounted();
+    } else if (mounted()) {
+      clean();
+      cleanup = effect();
+    }
+  });
+}
+function createSignal(value) {
+  return currentHookContext().reactive.createSignal(value);
+}
+function createPatchableSignal(value) {
+  const [get, set] = createSignal(value);
+  const patchFunc = (...jsonPatch) => set(patch(get(), jsonPatch));
+  return [get, set, patchFunc];
+}
+function useReactive() {
+  return currentHookContext().reactive;
+}
+function createMemo(computation, initialValue) {
+  let [value, setValue] = currentHookContext().reactive.createSignal(initialValue);
+  currentHookContext().reactive.createReaction(() => {
+    setValue((oldValue) => computation(oldValue));
+  });
+  return value;
+}
+function trackableGetter(value) {
+  let wasUsed = false;
+  return {
+    getter: () => {
+      wasUsed = true;
+      return value;
+    },
+    wasUsed: () => wasUsed
+  };
+}
+function mapItem(item, index, length, force, cached, mapCallback) {
+  const itemGetter = trackableGetter(item);
+  const indexGetter = trackableGetter(index);
+  const lengthGetter = trackableGetter(length);
+  const needToMap = force || !cached || item !== cached.item || index !== cached.index && cached.usedIndex || length !== cached.length && cached.usedLength;
+  if (needToMap) {
+    const mappedItem = mapCallback(itemGetter.getter, indexGetter.getter, lengthGetter.getter);
+    return {
+      item,
+      mappedItem,
+      index,
+      length,
+      usedIndex: indexGetter.wasUsed(),
+      usedLength: lengthGetter.wasUsed()
+    };
+  } else
+    return cached;
+}
+function createDerivedArray(arrayGetter, mapCallback) {
+  let [sourceArray] = currentHookContext().reactive.createSignal(
+    arrayGetter,
+    MeasureOfChange.PARTIAL
+  );
+  let [mappedArray, setMappedArray] = createSignal([]);
+  let mappedItemsCache = /* @__PURE__ */ new WeakMap();
+  currentHookContext().reactive.createReaction((measureOfChange) => {
+    let newMappedItemsCache = /* @__PURE__ */ new WeakMap();
+    setMappedArray((oldValue) => {
+      let length = sourceArray().length;
+      let newMappedArray = sourceArray().map((item, index) => {
+        const force = measureOfChange == MeasureOfChange.FULL;
+        const mappedItemTracking = mapItem(
+          item,
+          index,
+          length,
+          force,
+          mappedItemsCache.get(item),
+          mapCallback
+        );
+        newMappedItemsCache.set(item, mappedItemTracking);
+        return mappedItemTracking.mappedItem;
+      });
+      mappedItemsCache = newMappedItemsCache;
+      return newMappedArray;
+    });
+  });
+  return mappedArray;
+}
+function createEvent(eventEffect) {
+  let handler;
+  let emitter = (h) => handler = h;
+  emitter.emit = (event) => handler && handler({ event });
+  if (eventEffect)
+    createEffect(() => eventEffect(emitter));
+  return emitter;
+}
+function provideContext(marker, context) {
+  currentHookContext().provideContexts.push([marker, context]);
+}
+function provideReactiveContext(marker, mkContext) {
+  const context = createReactiveContext(mkContext);
+  currentHookContext().provideContexts.push([marker, context]);
+  return context;
+}
+function materializeViewState(vsValueOrGetter) {
+  let vs = {};
+  for (let key in vsValueOrGetter) {
+    let value = vsValueOrGetter[key];
+    if (typeof value === "function")
+      value = value();
+    vs[key] = value;
+  }
+  return vs;
+}
+function renderWithContexts(provideContexts, render, viewState, index = 0) {
+  if (provideContexts.length > index) {
+    let [marker, context] = provideContexts[0];
+    return withContext(
+      marker,
+      context,
+      () => renderWithContexts(provideContexts, render, viewState, index + 1)
+    );
+  }
+  return render(viewState);
+}
+function mkMounts(componentContext, element) {
+  const [mounted, setMounted] = componentContext.mountedSignal;
+  componentContext.reactive.createReaction(() => {
+    if (mounted)
+      element.mount();
+    else
+      element.unmount();
+  });
+  const mount = () => {
+    componentContext.reactive.enable();
+    componentContext.reactive.batchReactions(() => setMounted(true));
+  };
+  const unmount = () => {
+    componentContext.reactive.batchReactions(() => setMounted(false));
+    componentContext.reactive.disable();
+  };
+  return [mount, unmount];
+}
+function makeJayComponent(preRender, comp, ...contextMarkers) {
+  return (props) => {
+    let componentInstance = null;
+    const getComponentInstance = () => {
+      return componentInstance;
+    };
+    const reactive = mkReactive();
+    const componentContext = {
+      mountedSignal: reactive.createSignal(true),
+      reactive,
+      provideContexts: [],
+      getComponentInstance
+    };
+    return withContext(COMPONENT_CONTEXT, componentContext, () => {
+      let propsProxy = makePropsProxy(componentContext.reactive, props);
+      let eventWrapper = (orig, event) => {
+        return componentContext.reactive.batchReactions(() => orig(event));
+      };
+      let [refs, render] = preRender({ eventWrapper });
+      let contexts = contextMarkers.map((marker) => {
+        const context = useContext(marker);
+        reactive.enablePairing(context[CONTEXT_REACTIVE_SYMBOL_CONTEXT]);
+        return context;
+      });
+      let coreComp = comp(propsProxy, refs, ...contexts);
+      let { render: renderViewState, ...api } = coreComp;
+      let element;
+      componentContext.provideContexts.forEach(
+        ([marker, context]) => context[CONTEXT_REACTIVE_SYMBOL_CONTEXT] && reactive.enablePairing(context[CONTEXT_REACTIVE_SYMBOL_CONTEXT])
+      );
+      componentContext.reactive.createReaction(() => {
+        let viewStateValueOrGetters = renderViewState();
+        let viewState = materializeViewState(viewStateValueOrGetters);
+        if (!element)
+          element = renderWithContexts(
+            componentContext.provideContexts,
+            render,
+            viewState
+          );
+        else
+          element.update(viewState);
+      });
+      const [mount, unmount] = mkMounts(componentContext, element);
+      let update = (updateProps) => {
+        propsProxy.update(updateProps);
+      };
+      let events = {};
+      let component = {
+        element,
+        update,
+        mount,
+        unmount,
+        addEventListener: (eventType, handler) => events[eventType](handler),
+        removeEventListener: (eventType) => events[eventType](void 0)
+      };
+      for (let key in api) {
+        if (typeof api[key] === "function") {
+          if (api[key].emit) {
+            component[key] = api[key];
+            if (key.indexOf("on") === 0) {
+              let [, , ...rest] = key;
+              events[rest.join("")] = api[key];
+            }
+          } else
+            component[key] = (...args) => componentContext.reactive.batchReactions(() => api[key](...args));
+        } else {
+          component[key] = api[key];
+        }
+      }
+      return componentInstance = component;
+    });
+  };
+}
+function makeJayTsxComponent(comp) {
+  return {};
+}
+function makePropsProxy(reactive, props) {
+  const stateMap = {};
+  const [_props, _setProps] = createSignal(props);
+  const update = (newProps) => {
+    reactive.batchReactions(() => {
+      _setProps(newProps);
+      for (const prop in newProps) {
+        if (!stateMap.hasOwnProperty(prop))
+          stateMap[prop] = reactive.createSignal(newProps[prop]);
+        else
+          stateMap[prop][1](newProps[prop]);
+      }
+    });
+  };
+  const getter = (obj, prop) => {
+    if (!stateMap.hasOwnProperty(prop))
+      stateMap[prop] = reactive.createSignal(obj[prop]);
+    return stateMap[prop][0];
+  };
+  return new Proxy(props, {
+    get: function(obj, prop) {
+      if (prop === "update")
+        return update;
+      else if (prop === "props")
+        return _props;
+      else
+        return getter(obj, prop);
+    }
+  });
+}
+const forTesting = {
+  makePropsProxy
+};
+export {
+  COMPONENT_CONTEXT,
+  CONTEXT_CREATION_CONTEXT,
+  CONTEXT_REACTIVE_SYMBOL_CONTEXT,
+  createDerivedArray,
+  createEffect,
+  createEvent,
+  createMemo,
+  createPatchableSignal,
+  createReactiveContext,
+  createSignal,
+  forTesting,
+  makeJayComponent,
+  makeJayTsxComponent,
+  makePropsProxy,
+  materializeViewState,
+  provideContext,
+  provideReactiveContext,
+  useReactive
+};

package/docs/component.md

@@ -0,0 +1,137 @@
+# Creating Jay Components
+
+Jay Component is defined in the `@jay-framework/runtime` library as anything that implements the interface
+
+```typescript
+interface JayComponent<Props, ViewState, jayElement extends BaseJayElement<ViewState>> {
+  element: jayElement;
+  update: updateFunc<Props>;
+  mount: MountFunc;
+  unmount: MountFunc;
+  addEventListener: (type: string, handler: JayEventHandler<any, ViewState, void>) => void;
+  removeEventListener: (type: string, handler: JayEventHandler<any, ViewState, void>) => void;
+}
+```
+
+the `@jay-framework/component` library defines a reactive and elegant way to create headless Jay-Components.
+
+## Simple Example
+
+```typescript
+import { render, CounterElementRefs } from './counter.jay-html';
+import { createSignal, makeJayComponent, Props } from '@jay-framework/component';
+
+export interface CounterProps {
+  initialValue: number;
+}
+
+function CounterConstructor({ initialValue }: Props<CounterProps>, refs: CounterElementRefs) {
+  const [count, setCount] = createSignal(initialValue);
+
+  refs.subtracter.onclick(() => setCount(count() - 1));
+  refs.adderButton.onclick(() => setCount(count() + 1));
+
+  return {
+    render: () => ({ count }),
+  };
+}
+
+export const Counter = makeJayComponent(render, CounterConstructor);
+```
+
+The full example can be found at [counter.ts](../../../../examples/jay/counter/src/counter.ts)
+
+## The Component Constructor
+
+The `@jay-framework/component` library offers constructing jay components using a component constructor function of the form
+
+```typescript
+interface JayComponentCore<PropsT, ViewState> {
+  render: (props: Props<PropsT>) => ViewStateGetters<ViewState>;
+}
+
+type ComponentConstructor<
+  PropsT extends object,
+  Refs extends object,
+  ViewState extends object,
+  Contexts extends Array<any>,
+  CompCore extends JayComponentCore<PropsT, ViewState>,
+> = (props: Props<PropsT>, refs: Refs, ...contexts: Contexts) => CompCore;
+```
+
+### Parameters:
+
+- `props: Props<PropsT>`: an object holding signals for each of the component properties.
+  The `Props<T>` generic type turns an object of values into an object of signal getters.
+- `refs: Refs`: the refs type from the associated Jay Element of the components
+- `...contexts: Contexts`: The context instances requested by the `makeJayComponent` function
+
+### Returns
+
+The function has to return an object implementing `JayComponentCore` which has to have a render function.
+In addition, the returned object may have exported API functions and exported events of the component.
+
+#### returned object render function
+
+The returned `JayComponentCore` has to have a render function that returns `ViewStateGetters<ViewState>`.
+The `ViewState` is the view state of the jay-element the component is using, and the `ViewStateGetters` allows
+to provide the view state as values or getter functions.
+
+both of the below are valid usages of render:
+
+```typescript
+// as a signal
+const [count, setCount] = createSignal(initialValue);
+return {
+  render: () => ({ count }),
+};
+
+// as a value
+return {
+  render: () => ({ count: count() }),
+};
+```
+
+The render function itself is reactive, allowing to perform calculations as part of the render function.
+
+```typescript
+// using a computation
+const [count, setCount] = createSignal(initialValue);
+return {
+  render: () => ({ count, description: `the count is ${count()}` }),
+};
+```
+
+## The `makeJayComponent` function
+
+The `makeJayComponent` function returns a function that when called with `props`, will create a component instance.
+
+```typescript
+declare function makeJayComponent<
+  PropsT extends object,
+  ViewState extends object,
+  Refs extends object,
+  JayElementT extends JayElement<ViewState, Refs>,
+  Contexts extends Array<any>,
+  CompCore extends JayComponentCore<PropsT, ViewState>,
+>(
+  preRender: PreRenderElement<ViewState, Refs, JayElementT>,
+  comp: ComponentConstructor<PropsT, Refs, ViewState, Contexts, CompCore>,
+  ...contextMarkers: ContextMarkers<Contexts>
+): (props: PropsT) => ConcreteJayComponent<PropsT, ViewState, Refs, CompCore, JayElementT>;
+```
+
+### Parameters:
+
+- `preRender: PreRenderElement<ViewState, Refs, JayElementT>`: The render function from a `JayElement` constructor.
+- `comp: ComponentConstructor<PropsT, Refs, ViewState, Contexts, CompCore>`: the component constructor function.
+- `...contextMarkers: ContextMarkers<Contexts>`: zero or more context markers created using `createJayContext`.
+  read more about providing contexts in [provide-context.md](./provide-context.md) and [provide-reactive-context.md](./provide-reactive-context.md).
+
+### Returns
+
+A function that when called with props creates a component instance.
+
+#### returned function parameters:
+
+- `props: PropsT`: an object holding the properties for the component.

package/docs/create-derived-array.md

@@ -0,0 +1,54 @@
+# createDerivedArray
+
+Creates a derived mapped array that updates whenever the source array or its elements change.
+
+When using immutable state, the `Array.map` function always creates a new array with new items.
+`createDerivedArray` only recreates new items if the original item has changed, or a dependency of the mapping function
+has changed. `createDerivedArray` is the reactive equivalent of `Array.map`.
+
+The mapping function is recalculated if
+
+- the original item has changed
+- the item index has changed, and the mapping function is using the index signal
+- the original array length has changed, and the mapping function is using the length signal
+- any other signal the mapping function depends on has changed
+
+```typescript
+declare function createDerivedArray<T extends object, U>(
+  arrayGetter: Getter<T[]>,
+  mapCallback: (item: Getter<T>, index: Getter<number>, length: Getter<number>) => U,
+): Getter<U[]>;
+```
+
+## Parameters:
+
+- `arrayGetter: Getter<T[]>`: A getter function for the source array.
+- `mapCallback`: A function that maps each item in the source array to a new value.
+  - `item: Getter<T>`: the original array item
+  - `index: Getter<number>`: the index of the original array item
+  - `length: Getter<number>`: the length of the original array
+
+## Returns:
+
+A getter function for the derived array.
+
+## Example
+
+```typescript
+const taskData = createDerivedArray(pillarTasks, (item, index, length) => {
+  let { id, title, description } = item();
+  return {
+    id,
+    taskProps: {
+      title,
+      description,
+      hasNext: hasNext(),
+      hasPrev: hasPrev(),
+      isBottom: index() === length() - 1,
+      isTop: index() === 0,
+    },
+  };
+});
+```
+
+See the full example in [Scrum Board/lib/pillar.ts](../../../../examples/jay/scrum-board/lib/pillar.ts).

package/docs/create-effect.md

@@ -0,0 +1,27 @@
+# createEffect
+
+Creates a side effect that runs after the component renders and cleans up when the component unmounts.
+
+The effect function is called initially on hook creation, as well as if any of the signals it depends on change.
+
+If the `effect` function returns a cleanup function, the cleanup function is called on component unmount or if
+any of the signal the effect function depends on change, before recalling the effect function.
+
+```typescript
+type EffectCleanup = () => void;
+declare function createEffect(effect: () => void | EffectCleanup);
+```
+
+## Parameters:
+
+- `effect`: A function that returns a cleanup function or undefined.
+
+## example:
+
+```typescript
+createEffect(() => {
+  console.log('board', 'pillars:', pillars());
+});
+```
+
+See the full example in [Scrum Board/lib/board.ts](../../../../examples/jay/scrum-board/lib/board.ts).

package/docs/create-event.md

@@ -0,0 +1,78 @@
+# createEvent
+
+Creates a Jay component event emitter.
+
+Jay, unlike React or Solid.js, does not accept callbacks as props. Instead, the component constructor function has to
+return as part of the returned object event emitters. The `createEvent` function is used to create those event emitters.
+
+The event emitter itself is a function to register `JayEventHandler`s and has a member to `emit` events.
+
+`createEvent` can optionally accept an `eventEffect` function which is used to create an effect given the event emitter.
+It makes it simple to create an event that is triggered reactively based on the `eventEffect` effect function.
+
+```typescript
+interface EventEmitter<EventType, ViewState> {
+  (handler: JayEventHandler<EventType, ViewState, void>): void;
+  emit: (event?: EventType) => void;
+}
+
+declare function createEvent<EventType>(
+  eventEffect?: (emitter: EventEmitter<EventType, any>) => void,
+): EventEmitter<EventType, any>;
+```
+
+## Parameters:
+
+- `eventEffect`: An optional effect to run when the event is emitted.
+
+## Returns:
+
+An event emitter object.
+
+## Examples:
+
+A simple event emitter:
+
+```typescript
+function TaskConstructor(props: Props<TaskProps>, refs: TaskElementRefs) {
+  let onNext = createEvent();
+  let onPrev = createEvent();
+  let onUp = createEvent();
+  let onDown = createEvent();
+
+  refs.next.onclick(() => onNext.emit());
+  refs.up.onclick(() => onUp.emit());
+  refs.down.onclick(() => onDown.emit());
+  refs.prev.onclick(() => onPrev.emit());
+
+  return {
+    render: () => props,
+    onNext,
+    onDown,
+    onUp,
+    onPrev,
+  };
+}
+```
+
+See the full example in [Scrum Board/lib/task.ts](../../../../examples/jay/scrum-board/lib/task.ts).
+
+An event emitter with `eventEffect`:
+
+```typescript
+function CounterComponent({}: Props<CounterProps>, refs: CounterRefs) {
+  let [value, setValue] = createSignal(0);
+  refs.inc.onclick(() => setValue(value() + 1));
+  refs.dec.onclick(() => setValue(value() - 1));
+  let onChange = createEvent<CounterChangeEvent>((emitter) => emitter.emit({ value: value() }));
+  return {
+    render: () => ({ value }),
+    onChange,
+  };
+}
+```
+
+In the above example, the `createEffect` parameter of `createEvent` is a function that reads the signal `value`, and
+those the effect will run anytime the `value` signal changes, emitting an event.
+
+See the full example in [component.test.ts](../test/component.test.ts).

package/docs/create-memo.md

@@ -0,0 +1,32 @@
+# createMemo
+
+Creates a memoized value that updates only when its dependencies change.
+
+```typescript
+declare function createMemo<T>(computation: (prev: T) => T, initialValue?: T): Getter<T>;
+```
+
+## Parameters:
+
+- `computation`: A function that calculates the new value based on the previous value.
+- `initialValue`: The initial value of the memo.
+
+## Returns:
+
+A getter function for the memoized value.
+
+## Example:
+
+```typescript
+const activeTodoCount = createMemo(() =>
+  todos().reduce(function (accum: number, todo: ShownTodo) {
+    return todo.isCompleted ? accum : accum + 1;
+  }, 0),
+);
+const noActiveItems = createMemo(() => activeTodoCount() === 0);
+const activeTodoWord = createMemo(() => (activeTodoCount() > 1 ? 'todos' : 'todo'));
+const hasItems = createMemo(() => todos().length > 0);
+const showClearCompleted = createMemo(() => !!todos().find((_) => _.isCompleted));
+```
+
+See the full example in [Todo/lib/todo.ts](../../../../examples/jay/todo/lib/todo.ts).

package/docs/create-patchable-signal.md

@@ -0,0 +1,55 @@
+# createPatchableSignal
+
+Creates a reactive signal that also supports update using `JSONPatch`.
+
+As Jay is using immutable state objects, when we need to update a deep structure of objects, we have to replace
+the updated object and all parent objects. `createPatchableSignal` is a utility that is using the same `patch` from
+`@jay-framework/json-patch` to simplify this update.
+
+```typescript
+declare function createPatchableSignal<T>(
+  value: ValueOrGetter<T>,
+): [get: Getter<T>, set: Setter<T>, patchFunc: Patcher<T>];
+```
+
+## Parameters:
+
+- `value`: The initial value of the signal.
+
+## Returns:
+
+A tuple containing a `getter`, a `setter`, and a `patch` function.
+
+- `getter: Getter<T>` function to get the signal value.
+- `setter: Setter<T>` function to set the signal value. The setter function can receive a value or a `Next` function that
+  given the old signal value will calculate the next signal value.
+- `patch: Patcher<T>` function to patch the signal value using `...JSONPatch` (spread json patch).
+
+## Examples:
+
+```typescript
+const [todos, setTodos, patchTodos] = createPatchableSignal(
+  initialTodos().map((_) => ({ ..._, isEditing: false, editText: '' })),
+);
+
+// in some event handler
+patchTodos(
+  { op: REPLACE, path: [itemIndex, 'title'], value: val },
+  { op: REPLACE, path: [itemIndex, 'isEditing'], value: false },
+);
+
+// in another event handler
+patchTodos({
+  op: ADD,
+  path: [todos().length],
+  value: {
+    id: uuid(),
+    title: val,
+    isEditing: false,
+    editText: '',
+    isCompleted: false,
+  },
+});
+```
+
+See the full example in [todo-one-flat-component/lib/todo.ts](../../../../examples/jay/todo-one-flat-component/lib/todo.ts).

package/docs/create-signal.md

@@ -0,0 +1,44 @@
+# createSignal
+
+Creates a reactive signal. The signal can be initialized using a value or a `Getter`.
+
+If initialized with a Getter, the signal will track the Getter's signal value, useful for signals tracking prop values
+while allowing to update the signal value directly.
+
+```typescript
+declare function createSignal<T>(value: ValueOrGetter<T>): [get: Getter<T>, set: Setter<T>];
+```
+
+## Parameters:
+
+- `value`: The initial value of the signal, or a function that returns a value track.
+
+If the value is a function, createSignal automatically wraps it with Reactive's createReaction
+creating a dependency between any signals read within the function and the created signal.
+
+## Returns:
+
+A tuple containing a `getter` and a `setter` for the signal's value.
+
+- `getter: Getter<T>` function to get the signal value.
+- `setter: Setter<T>` function to set the signal value. The setter function can receive a value or a `Next` function that
+  given the old signal value will calculate the next signal value.
+
+## Examples:
+
+Creating a signal with an initial value
+
+```typescript
+const [count, setCount] = createSignal(initialValue);
+```
+
+Creating a signal that follows two other signal values
+
+```typescript
+const [a, setA] = createSignal(10);
+const [b, setB] = createSignal(20);
+const [c, setC] = createSignal(() => a() + b());
+```
+
+In the above example, the signal `c` can be updated using the `setC` setter, or it is updated automatically
+whenever the signals `a` or `b` are updated.

package/docs/provide-context.md

@@ -0,0 +1,39 @@
+# provideContext
+
+Provides a context value to child components.
+
+A Context created using `provideContext` is injected into child components who declare dependency on it using the same
+context `marker`.
+
+This context is not reactive, and any update to the context values will not trigger updates in any components.
+
+- To trigger changes in components as a context changes, use the `provideReactiveContext` hook instead.
+- This hook is great for dependency injection into child components.
+
+```typescript
+declare function provideContext<ContextType>(
+  marker: ContextMarker<ContextType>,
+  context: ContextType,
+);
+```
+
+## Parameters:
+
+- `marker`: A unique symbol identifying the context, created using `createJayContext`.
+- `context`: The context value to provide.
+
+## Example
+
+```typescript
+const COUNT_CONTEXT = createJayContext<CountContext>();
+
+// in a component constructor
+provideContext(COUNT_CONTEXT, context);
+```
+
+## design log
+
+For additional information on the design decisions of Jay Context API, read
+[16 - context api.md](../../../../design-log/16%20-%20context%20api.md),
+[21 - alternative to context API.md](../../../../design-log/21%20-%20alternative%20to%20context%20API.md),
+[30 - Jay Context API.md](../../../../design-log/30%20-%20Jay%20Context%20API.md)

package/docs/provide-reactive-context.md

@@ -0,0 +1,68 @@
+# provideReactiveContext
+
+Provides a reactive context value to child components.
+
+The reactive context is similar to a Jay Component by having it's own Reactive instance, allowing it to use any
+of Jay Hooks (`createSignal`, `createEffect`, etc.) as well as export API functions.
+
+- Child Components who read reactive context signal getters are said to be paired, and changes to such context signals
+  will trigger updates of components reading those signal values.
+- API functions of reactive context are automatically wrapped by `reactive.batchReactions`.
+- Best practice is to update a context using exported API functions as it ensures optimal computation of dependent effects.
+
+```typescript
+declare function provideReactiveContext<ContextType extends object>(
+  marker: ContextMarker<ContextType>,
+  mkContext: () => ContextType,
+): ContextType;
+```
+
+## Parameters:
+
+- `marker`: A unique symbol identifying the context, created using `createJayContext`.
+- `mkContext`: A function that creates the initial context value.
+  The function may use any of the Jay Hooks and should return an object which represents the context.
+
+## Returns:
+
+The created reactive context value.
+
+## Examples:
+
+```typescript
+export const SCRUM_CONTEXT = createJayContext<ScrumContext>();
+export const provideScrumContext = () =>
+  provideReactiveContext(SCRUM_CONTEXT, () => {
+    let [pillars, setPillars] = createSignal(DEFAULT_PILLARS);
+
+    const moveTaskToNext = (pillarId: string, taskId: string) => {
+      setPillars(moveTask(pillars(), pillarId, taskId, +1, 0));
+    };
+    const moveTaskToPrev = (pillarId: string, taskId: string) => {
+      setPillars(moveTask(pillars(), pillarId, taskId, -1, 0));
+    };
+    const moveTaskUp = (pillarId: string, taskId: string) => {
+      setPillars(moveTask(pillars(), pillarId, taskId, 0, +1));
+    };
+    const moveTaskDown = (pillarId: string, taskId: string) => {
+      setPillars(moveTask(pillars(), pillarId, taskId, 0, -1));
+    };
+
+    return {
+      pillars,
+      moveTaskToNext,
+      moveTaskToPrev,
+      moveTaskDown,
+      moveTaskUp,
+    };
+  });
+```
+
+See the full example in [scrum-context.ts](../../../../examples/jay-context/scrum-board-with-context/lib/scrum-context.ts)
+
+## design log
+
+For additional information on the design decisions of Jay Context API, read
+[16 - context api.md](../../../../design-log/16%20-%20context%20api.md),
+[21 - alternative to context API.md](../../../../design-log/21%20-%20alternative%20to%20context%20API.md),
+[30 - Jay Context API.md](../../../../design-log/30%20-%20Jay%20Context%20API.md)

package/docs/use-reactive.md

@@ -0,0 +1,13 @@
+# useReactive
+
+Gets the current reactive context of the current component or reactive context.
+
+```typescript
+declare function useReactive(): Reactive;
+```
+
+## Returns:
+
+The current reactive context object.
+
+Read more about Jay Reactive in [reactive](..%2F..%2Freactive)

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@jay-framework/component",
+  "version": "0.5.0",
+  "type": "module",
+  "license": "Apache-2.0",
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "docs",
+    "readme.md"
+  ],
+  "scripts": {
+    "build": "npm run build:js && npm run build:types",
+    "build:watch": "npm run build:js -- --watch & npm run build:types -- --watch",
+    "build:js": "vite build",
+    "build:types": "tsup lib/index.ts --dts-only --format esm",
+    "build:check-types": "tsc",
+    "clean": "rimraf dist",
+    "confirm": "npm run clean && npm run build && npm run build:check-types && npm run test",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@jay-framework/json-patch": "workspace:^",
+    "@jay-framework/reactive": "workspace:^",
+    "@jay-framework/runtime": "workspace:^"
+  },
+  "devDependencies": {
+    "@jay-framework/dev-environment": "workspace:^",
+    "@testing-library/jest-dom": "^6.2.0",
+    "@types/node": "^20.11.5",
+    "rimraf": "^5.0.5",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vite": "^5.0.11",
+    "vitest": "^1.2.1"
+  }
+}

package/readme.md

@@ -0,0 +1,33 @@
+# Jay Component
+
+The Jay Component library defines the methods of constructing a Jay Component.
+
+# Creating Components
+
+- [Creating Jay Components](./docs/component.md)
+
+# Jay Component Hooks
+
+hooks to create signals:
+
+- [createSignal](./docs/create-signal.md)
+- [createPatchableSignal](./docs/create-patchable-signal.md)
+
+hooks to create computed values:
+
+- [createMemo](./docs/create-memo.md)
+- [createDerivedArray](./docs/create-derived-array.md)
+
+hooks to create reactions & events:
+
+- [createEffect](./docs/create-effect.md)
+- [createEvent](./docs/create-event.md)
+
+Hooks for providing context:
+
+- [provideContext](./docs/provide-context.md)
+- [provideReactiveContext](./docs/provide-reactive-context.md)
+
+Hooks to get Component Reactive Instance:
+
+- [use-reactive](./docs/use-reactive.md)