babavoss 0.0.1 → 0.0.2

package/src/web/hooks.ts

@@ -0,0 +1,135 @@
+// The hooks a view reads the state with, each honest about what it wants:
+// a list is ids, a value is one component of one entity, and a predicate or
+// an order is declared on the select so the table knows what wakes it. Each
+// hook subscribes to the page's store of the baba and re-renders only when
+// its own answer moves; each registers its interest, so the socket carries
+// no more than the page reads. A select is declared once, at module level:
+// the table keeps one live set per select object, and one made in a render
+// is a new one every time.
+import { createContext, useContext, useEffect, useLayoutEffect, useMemo, useSyncExternalStore } from "react";
+import { ScopeContext } from "./core.tsx";
+import { storeFor, type Probe, type StateStore } from "./store.ts";
+import { HandContext, AppStoreContext, UNSET, type Hand, type HookStore } from "./app.tsx";
+import type { Raw } from "../ecs/runtime.ts";
+
+/** What a page's live store gives: the state to read, the calls, the standing. The socket store of the page's baba is one; a simulation in the page, which the Maker provides, is another. */
+export interface LiveStore extends HookStore {
+  ready: boolean;
+  connected: boolean;
+  refused: string | null;
+  fire(name: string, args?: unknown): Promise<unknown>;
+  fireIn(name: string, args?: unknown): Promise<{ value: unknown; round: number | undefined }>;
+  read(name: string, args?: unknown): Promise<unknown>;
+  raw(op: Raw): Promise<unknown>;
+}
+
+/** A live store put over a subtree: every useBaba and useBabaState inside fires into it and reads it. */
+export const LiveStoreContext = createContext<LiveStore | null>(null);
+import type { Component, Entity, Resource, Select, Term, Value } from "../ecs/state.ts";
+
+/** The state the hooks read: a fixed one, when the component is shown over one (a frame); else the live store put over it (the Maker's simulation); else the store of this page's baba, held while the component is mounted. */
+export function useStore(): HookStore {
+  const fixed = useContext(AppStoreContext);
+  const over = useContext(LiveStoreContext);
+  const scope = useContext(ScopeContext);
+  if (!fixed && !over && scope === null) throw new Error("useStore: not inside a baba's page, nor over an app's state");
+  const st: HookStore = fixed ?? over ?? storeFor(scope!);
+  useEffect(() => st.retain(), [st]);
+  return st;
+}
+
+/** The page's own live store: what fires actions, reads queries and knows the socket. An app's state does not replace it; a LiveStoreContext does. */
+export function useLiveStore(): LiveStore {
+  const over = useContext(LiveStoreContext);
+  const scope = useContext(ScopeContext);
+  if (!over && scope === null) throw new Error("useLiveStore: not inside a baba's page");
+  const st: LiveStore = over ?? (storeFor(scope!) as StateStore as LiveStore);
+  useEffect(() => st.retain(), [st]);
+  return st;
+}
+
+/**
+ * The hand a component may act with: the one given over it (none, for a frame that only shows), else the live store's,
+ * the page's baba or the Maker's simulation; undefined outside both. Acting through it, an app never names whose state it is.
+ */
+export function useHand(): Hand | undefined {
+  const given = useContext(HandContext);
+  const over = useContext(LiveStoreContext);
+  const scope = useContext(ScopeContext);
+  return useMemo(() => {
+    if (given !== UNSET) return given;
+    const st = over ?? (scope !== null ? (storeFor(scope) as StateStore as LiveStore) : null);
+    return st ? { fire: (name: string, args?: unknown) => { void st.fire(name, args).catch(() => {}); } } : undefined;
+  }, [given, over, scope]);
+}
+
+/** A store's value, read the same on the server and in the page: a frame rendered once, or a live store followed. */
+function read<T>(st: HookStore, get: () => T): T { return useSyncExternalStore(st.subscribe, get, get); }
+
+function useInterest(st: HookStore, want: () => () => void, deps: unknown[]): void {
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  useEffect(() => want(), [st, ...deps]);
+}
+
+/** The entities a declared select answers, in its order: the same array until an entity enters or leaves, or, for a `.where` or a `.by`, until a value it reads is written on a member. A select with change terms answers what the last round changed. */
+export function useQuery<Cs extends readonly Term[]>(sel: Select<Cs>): readonly Entity[] {
+  const st = useStore();
+  useInterest(st, () => st.wantSelect(sel as never), [sel]);
+  return read(st, () => st.replica.ids(sel));
+}
+
+/** One column of a select: every member's value of `c` as one map, the same until a member comes, goes or is written. For a component that draws a whole layer at once; a row reads `useComponent`. */
+export function useColumn<Cs extends readonly Term[], K extends Component>(sel: Select<Cs>, c: K): ReadonlyMap<Entity, Value<K>> {
+  const st = useStore();
+  useInterest(st, () => { const a = st.wantSelect(sel as never), b = st.wantValues(c); return () => { a(); b(); }; }, [sel, c]);
+  return read(st, () => st.replica.column(sel as never, c));
+}
+
+/** How many entities a select answers. */
+export function useCount<Cs extends readonly Term[]>(sel: Select<Cs>): number { return useQuery(sel).length; }
+
+/** The value of `c` on `e`, or undefined without one: the replica's own object, the same until it is written. */
+export function useComponent<K extends Component>(e: Entity, c: K): Value<K> | undefined {
+  const st = useStore();
+  useInterest(st, () => st.wantPart(e, c), [e, c]);
+  return read(st, () => st.replica.get(e, c));
+}
+
+/** Whether `e` carries `c`. */
+export function useHas(e: Entity, c: Component): boolean {
+  const st = useStore();
+  useInterest(st, () => st.wantPresence(c), [c]);
+  return read(st, () => st.replica.has(e, c));
+}
+
+/** Whether `e` exists, as far as the window holds: an entity none of the page's interests touch is not here. */
+export function useAlive(e: Entity): boolean {
+  const st = useStore();
+  return read(st, () => st.replica.alive(e));
+}
+
+/** A resource's value: the same object until it is written. */
+export function useResource<K extends Resource>(r: K): Value<K> {
+  const st = useStore();
+  useInterest(st, () => st.wantResource(r), [r]);
+  return read(st, () => st.replica.get(r));
+}
+
+/** Whether the state has reached `round`: what a `fireIn` answered, so a row shows pending until its effect is in view. */
+export function useSettled(round: number | undefined): boolean {
+  const st = useStore();
+  return read(st, () => round === undefined || st.replica.round >= round);
+}
+
+/** The round the window holds. */
+export function useRound(): number {
+  const st = useStore();
+  return read(st, () => st.replica.round);
+}
+
+/** What following costs this window, round by round. Reading it also times the page's render after each frame. */
+export function useProbe(): Probe {
+  const st = useStore();
+  useLayoutEffect(() => st.committed());
+  return read(st, () => st.probe);
+}

package/src/web/index.tsx

@@ -0,0 +1,17 @@
+// babavoss/web: what a view file imports, and what voss's pages are built with.
+export { route, matchRoute, type RouteParams, type RouteMatch } from "../desktop/routes.ts";
+export { compose, view, useScope, useManifest, ScopeProvider, api, apiHeaders, configure, ApiError, type AppsDef, type RouteTable, type InterfaceDef, type ViewDef } from "./core.tsx";
+export { objectsOf, instancesOf, ridersOf, looseOf, ObjectMap, ObjectCards, ObjectCard, type ObjectType } from "./objects.tsx";
+export { Maker, Simulation, asProgram, appsFor, type MakerProps, type AppChoice } from "./maker.tsx";
+export { AppState, AppStoreContext, fixedStore, type Hand, type HookStore } from "./app.tsx";
+export type { StepRecord, CheckRecord } from "../test/records.ts";
+export { useBabaState, useBaba, type BabaStateView, type BabaView, type FollowSample, type Probe } from "./state.tsx";
+export { useQuery, useColumn, useCount, useComponent, useHas, useAlive, useResource, useSettled, useRound, useProbe, useHand, LiveStoreContext, type LiveStore } from "./hooks.ts";
+export { select, not, added, changed, removed } from "../ecs/state.ts";
+export { Replica } from "../ecs/replica.ts";
+export type { Manifest } from "../ecs/baba.ts";
+export { formatFailure, placeOf, type ViewFailure, type Stage as FailureStage } from "../build/failure.ts";
+export { Button, Input, Textarea, Select, Kbd, Panel, Rows, Row, Table, Dialog, CommandList, type ButtonVariant } from "./ui.tsx";
+export { plan, collect, tableOf, describeType, FieldError, type Plan, type Field, type Values } from "./form.ts";
+export { filterItems, type Item } from "./list.ts";
+export { Desktop, DesktopFrame, SpecDesktop, LocalDesktop, Eyes, AppIcon, desktopAddress, parseDesktopAddress, parseDesktopHash, routeOf, type DesktopProps, type AppProps, type SurfaceProps } from "../desktop/view.tsx";

package/src/web/list.ts

@@ -0,0 +1,19 @@
+// A command list's filter and its keyboard selection. Pure.
+
+export interface Item { id: string; group: string; label: string; hint?: string }
+
+/** The items every word of the query appears in, by group, label or hint, in their order. */
+export function filterItems<T extends Item>(list: T[], query: string): T[] {
+  const words = query.toLowerCase().split(/\s+/).filter(Boolean);
+  if (words.length === 0) return list;
+  return list.filter((e) => {
+    const hay = `${e.group} ${e.label} ${e.hint ?? ""}`.toLowerCase();
+    return words.every((w) => hay.includes(w));
+  });
+}
+
+/** The selection after an arrow key, wrapping at both ends. */
+export function move(index: number, by: number, length: number): number {
+  if (length === 0) return 0;
+  return (((index + by) % length) + length) % length;
+}