ctrl-fx 0.0.1 → 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { D as Dimensions, P as Permission, U as Uuid, i as isState, m as manageApplication, p as permission, t as toComponent, u as uuidFromString } from './index-fpCmXVEu.js';
+import './db/index.js';

package/dist/index.js

@@ -0,0 +1,18 @@
+import {
+  isState,
+  manageApplication,
+  permission,
+  toComponent,
+  uuidFromString
+} from "./chunk-DZAR6PTR.js";
+import "./chunk-NSWOTCDU.js";
+import "./chunk-KNHJPAIU.js";
+import "./chunk-XICUXW4T.js";
+import "./chunk-PKBMQBKP.js";
+export {
+  isState,
+  manageApplication,
+  permission,
+  toComponent,
+  uuidFromString
+};

package/dist/router.d.ts

@@ -0,0 +1,39 @@
+import { I as InternalLocation, E as Effect, a as EventActions } from './index-fpCmXVEu.js';
+import './db/index.js';
+
+/** Named path-segment parameters extracted from a matched route. */
+type Params = Record<string, string>;
+/** A map of URL patterns to handler functions. Pattern keys use `:param` syntax for named path segments. */
+type RouteMap<Route> = {
+    [pattern: string]: (params: Params) => Route;
+};
+/**
+ * Creates a route-matching function from a pattern map. Pattern keys use `:param` syntax for
+ * named path segments. Returns `null` when no pattern matches.
+ *
+ * ```ts
+ * const match = router({ '/': () => 'home', '/users/:id': ({ id }) => `user-${id}` })
+ * ```
+ */
+declare function router<Route>(routes: RouteMap<Route>): (location: InternalLocation) => Route | null;
+/**
+ * An effect describing a `history.pushState` to `path`, suitable for use as an `onClick` handler on an `<a>` element.
+ * Produces `{ preventDefault: true }` to suppress the default browser navigation.
+ */
+declare function link<State, Event>(path: string): Effect<State, Event, EventActions>;
+/** An effect describing a `history.pushState` to `path`. Use in effect chains or button handlers. */
+declare function navigate<State, Event>(path: string): Effect<State, Event, void>;
+/**
+ * Bundled router that strips `options.basePath` before matching and prepends it before navigating.
+ * Use when your app is mounted at a sub-path (e.g. a GitHub Pages subdirectory).
+ * Returns a `{ match, link, navigate }` object.
+ */
+declare function createRouter<Route>(routes: RouteMap<Route>, options?: {
+    basePath?: string;
+}): {
+    match(location: InternalLocation): Route | null;
+    link<State, Event>(path: string): Effect<State, Event, EventActions>;
+    navigate<State, Event>(path: string): Effect<State, Event, void>;
+};
+
+export { EventActions, InternalLocation, type Params, type RouteMap, createRouter, link, navigate, router };

package/dist/router.js

@@ -0,0 +1,66 @@
+import {
+  async,
+  parseInternalLocation,
+  pushState
+} from "./chunk-KNHJPAIU.js";
+import "./chunk-PKBMQBKP.js";
+
+// src/router.ts
+function compile(routes) {
+  return Object.entries(routes).map(([pattern, handler]) => ({
+    segments: pattern.split("/"),
+    handler
+  }));
+}
+function matchRoute(compiled, location) {
+  const pathSegs = location.path.elems;
+  for (const { segments, handler } of compiled) {
+    if (segments.length !== pathSegs.length) continue;
+    const params = {};
+    let matched = true;
+    for (let i = 0; i < segments.length; i++) {
+      const seg = segments[i];
+      if (seg.startsWith(":")) {
+        params[seg.slice(1)] = pathSegs[i];
+      } else if (seg.toLowerCase() !== pathSegs[i].toLowerCase()) {
+        matched = false;
+        break;
+      }
+    }
+    if (matched) return handler(params);
+  }
+  return null;
+}
+function router(routes) {
+  const compiled = compile(routes);
+  return (location) => matchRoute(compiled, location);
+}
+function link(path) {
+  return async(pushState(parseInternalLocation(path)), 0).as({
+    preventDefault: true
+  });
+}
+function navigate(path) {
+  return pushState(parseInternalLocation(path));
+}
+function createRouter(routes, options) {
+  const compiled = compile(routes);
+  const base = options?.basePath ?? "";
+  return {
+    match(location) {
+      if (!base) return matchRoute(compiled, location);
+      const fullPath = location.path.elems.join("/");
+      if (!fullPath.startsWith(base)) return null;
+      const relative = fullPath.slice(base.length) || "/";
+      return matchRoute(compiled, parseInternalLocation(relative));
+    },
+    link: (path) => link(base + path),
+    navigate: (path) => navigate(base + path)
+  };
+}
+export {
+  createRouter,
+  link,
+  navigate,
+  router
+};

package/dist/testing.d.ts

@@ -0,0 +1,254 @@
+import { A as Attr, H as HttpRequest, R as Result, b as HttpResponse, c as RequestError, d as HttpError, I as InternalLocation, S as ScrollOptions, N as NodeGroup, e as Node, E as Effect, C as Component } from './index-fpCmXVEu.js';
+import { KeyPath, JsonValue, DbName, ObjectStore } from './db/index.js';
+
+type NonEmptyArray<A> = [A, ...A[]];
+
+type DbStoreSnapshot = {
+    readonly keyPath: KeyPath;
+    readonly records: ReadonlyMap<string, JsonValue>;
+    readonly autoIncrementCounter: number;
+};
+declare class TestDatabaseData {
+    readonly _databases: ReadonlyMap<string, ReadonlyMap<string, DbStoreSnapshot>>;
+    constructor(databases: ReadonlyMap<string, ReadonlyMap<string, DbStoreSnapshot>>);
+    records(db: DbName, store: ObjectStore): readonly JsonValue[];
+    getByKey(db: DbName, store: ObjectStore, key: IDBValidKey): JsonValue | undefined;
+    size(db: DbName, store: ObjectStore): number;
+    hasDatabase(db: DbName): boolean;
+    hasStore(db: DbName, store: ObjectStore): boolean;
+}
+
+type DownloadRecord = {
+    readonly filename: string;
+    readonly content: string;
+    readonly contentType: string;
+};
+type BroadcastSentRecord = {
+    readonly channel: string;
+    readonly message: unknown;
+};
+type SetAppBadge = {
+    _type: 'SetAppBadge';
+    count: number;
+};
+type ClearAppBadge = {
+    _type: 'ClearAppBadge';
+};
+type AppBadgeOperation = SetAppBadge | ClearAppBadge;
+declare const clearAppBadge: ClearAppBadge;
+declare function setAppBadge(count: number): SetAppBadge;
+declare function appBadgeCount(operations: readonly AppBadgeOperation[]): number;
+type HttpInteraction = {
+    readonly request: HttpRequest;
+    readonly response: Result<HttpResponse, RequestError | HttpError>;
+};
+type HttpHandler = (request: HttpRequest, prior: readonly HttpInteraction[]) => Result<HttpResponse, RequestError | HttpError>;
+/** Configuration passed to `testApplication`/`testComponent` to control how side effects behave during tests. */
+type TestConfig = {
+    readonly http: {
+        /** Called for each HTTP request. Throw or return a failure Result to simulate errors. */
+        readonly handler: HttpHandler;
+    };
+    readonly clock: {
+        /** Scripted return values for `getTime()`, consumed in order. When exhausted, returns `new Date(0)`. */
+        readonly values: readonly Date[];
+    };
+    readonly random: {
+        /** Scripted return values for `getRandom()`, consumed in order. When exhausted, uses a deterministic seeded PRNG. */
+        readonly values: readonly number[];
+    };
+};
+/** Creates a TestConfig that throws on any HTTP request. */
+declare function defaultTestConfig(): TestConfig;
+type ConfirmInteraction = {
+    message: string;
+    response: boolean;
+};
+type PromptInteraction = {
+    message: string;
+    default: string | undefined;
+    response: string | null;
+};
+/** Snapshot of every observable side effect that occurred during a test run. */
+type TestData<Custom = {}> = {
+    readonly window: {
+        readonly alerts: readonly any[];
+        readonly confirms: readonly ConfirmInteraction[];
+        readonly confirmResponses: readonly boolean[];
+        readonly prompts: readonly PromptInteraction[];
+        readonly promptResponses: readonly (string | null)[];
+    };
+    readonly navigator: {
+        readonly appBadgeOperations: readonly AppBadgeOperation[];
+    };
+    readonly clipboard: {
+        readonly content: string;
+        readonly writes: readonly string[];
+    };
+    readonly document: {
+        readonly title: string | null;
+    };
+    readonly http: {
+        readonly interactions: readonly HttpInteraction[];
+    };
+    readonly clock: {
+        /** Values returned by each `getTime()` call, in order. */
+        readonly calls: readonly Date[];
+    };
+    readonly random: {
+        /** Values returned by each `getRandom()` call, in order. */
+        readonly calls: readonly number[];
+    };
+    readonly console: {
+        readonly logs: readonly any[];
+    };
+    readonly db: TestDatabaseData;
+    readonly storage: {
+        readonly local: ReadonlyMap<string, string>;
+        readonly session: ReadonlyMap<string, string>;
+    };
+    readonly navigation: {
+        readonly locationHistory: readonly InternalLocation[];
+    };
+    readonly scroll: {
+        readonly windowScrolls: readonly ScrollOptions[];
+        readonly elementScrolls: readonly {
+            selector: string;
+            options: ScrollOptions;
+        }[];
+    };
+    readonly downloads: readonly DownloadRecord[];
+    readonly broadcasts: {
+        readonly sent: readonly BroadcastSentRecord[];
+    };
+    readonly custom: Custom;
+};
+/** Creates an empty TestData, optionally initialising the `custom` field. */
+declare function newTestData<Custom = {}>(custom?: Custom): TestData<Custom>;
+type TestInput<State, Params, Custom = {}> = {
+    state?: State;
+    params?: Params;
+    testData?: TestData<Custom>;
+};
+type Click = {
+    type: 'Click';
+    selector: QuerySelector;
+};
+/** Simulates a click on the element(s) matching `selector`. */
+declare function click(selector: QuerySelector): Click;
+type AdvanceTime = {
+    _type: 'AdvanceTime';
+    milliseconds: number;
+};
+/** Advances the test scheduler clock by `milliseconds`, firing any scheduled tasks that come due. */
+declare function advanceTime(milliseconds: number): AdvanceTime;
+type ReceiveBroadcast = {
+    _type: 'ReceiveBroadcast';
+    channel: string;
+    message: unknown;
+};
+/** Delivers a BroadcastChannel message to any active subscriber on `channel`. */
+declare function receiveBroadcast(channel: string, message: unknown): ReceiveBroadcast;
+type FireCustomEvent = {
+    _type: 'FireCustomEvent';
+    selector: QuerySelector;
+    eventName: string;
+    detail: unknown;
+};
+/** Dispatches a custom DOM event on the element matching `selector`, invoking any `onEvent` handler. */
+declare function fireCustomEvent(selector: QuerySelector, eventName: string, detail?: unknown): FireCustomEvent;
+type Submit = {
+    _type: 'Submit';
+    selector: QuerySelector;
+};
+/** Simulates a form submit event on the element(s) matching `selector`. */
+declare function submit(selector: QuerySelector): Submit;
+type TextInput = {
+    _type: 'TextInput';
+    selector: QuerySelector;
+    value: string;
+};
+/** Simulates an `input` event on the element(s) matching `selector`. */
+declare function textInput(selector: QuerySelector, value: string): TextInput;
+/** Creates an attribute object `{ name, value }` for use with `findOne(...).attrs.toContainEqual(attr(...))`. */
+declare function attr(name: string, value: string): {
+    name: string;
+    value: string;
+};
+type Interaction = Click | AdvanceTime | ReceiveBroadcast | FireCustomEvent | Submit | TextInput;
+
+type DomElement = {
+    readonly tag: string;
+    readonly attrs: readonly Attr[];
+    readonly childNodes: readonly DomNode[];
+};
+type DomNode = DomElement | string;
+type TestableDom = {
+    head: DomElement;
+    body: DomElement;
+};
+/**
+ * The result of mounting a component for testing. Supports running interactions
+ * and querying the virtual DOM. Each call to `run` returns a new
+ * `TestableComponent` reflecting the state after those interactions, so tests
+ * can chain calls to build up complex scenarios step by step.
+ */
+type TestableComponent<State, Params, Event, Custom = {}> = {
+    readonly config: TestConfig;
+    readonly state: State;
+    readonly data: TestData<Custom>;
+    /** Returns a copy with the given TestConfig. */
+    withConfig(config: TestConfig): TestableComponent<State, Params, Event, Custom>;
+    /** Returns a copy with the given TestData as the starting data. */
+    withData(data: TestData<Custom>): TestableComponent<State, Params, Event, Custom>;
+    readonly dom: TestableDom;
+    /**
+     * Applies one or more interactions in order and returns a new
+     * `TestableComponent` reflecting the resulting state and DOM. The original
+     * instance is unchanged, so you can branch from the same starting point to
+     * test different sequences.
+     */
+    run(...interactions: Interaction[]): TestableComponent<State, Params, Event, Custom>;
+    /** Returns all elements matching `selector`. */
+    find(selector: string): readonly DomElement[];
+    /** Returns the single element matching `selector`. Throws if not exactly one match. */
+    findOne(selector: string): DomElement;
+    /** Returns all elements matching `selector`. Throws if no match. */
+    findOneOrMore(selector: string): NonEmptyArray<DomElement>;
+    /** Returns the element matching `selector`, or undefined. */
+    findMaybeOne(selector: string): DomElement | undefined;
+};
+/**
+ * Creates a testable wrapper around a `Component`. Use this when testing a
+ * component that was created with `component()`. For testing a top-level view
+ * function directly, use `testApplication` instead.
+ */
+declare function testComponent<State, Params, Event, Custom = {}>(component: Component<State, Params, Event>, config?: TestConfig, data?: TestData<Custom>): TestableComponent<State, Params, Event, Custom>;
+/**
+ * The main entry point for testing a ctrl-fx application. Wraps a view
+ * function and initial state into a `TestableComponent`. Call `.run(...)`
+ * with interactions to simulate user actions, then inspect `.state`, `.data`,
+ * and the `findOne`/`find` DOM query methods on the result.
+ */
+declare function testApplication<State, Custom = {}>(app: (state: State) => NodeGroup<State, never> | Node<State, never>, initialState: State | Effect<State, never, State>, config?: TestConfig, data?: TestData<Custom>): TestableComponent<State, void, never, Custom>;
+type ExactlyOne = {
+    _type: 'ExactlyOne';
+    selector: string;
+};
+type ZeroOrMore = {
+    _type: 'ZeroOrMore';
+    selector: string;
+};
+type ZeroOrOne = {
+    _type: 'ZeroOrOne';
+    selector: string;
+};
+type OneOrMore = {
+    _type: 'OneOrMore';
+    selector: string;
+};
+/** Selects elements matching `selector`; throws during `run` if none are found. */
+declare function one(selector: string): OneOrMore;
+type QuerySelector = ExactlyOne | OneOrMore | ZeroOrMore | ZeroOrOne;
+
+export { type AdvanceTime, type AppBadgeOperation, type BroadcastSentRecord, type ClearAppBadge, type Click, type ConfirmInteraction, type DbStoreSnapshot, type DomElement, type DomNode, type DownloadRecord, type ExactlyOne, type FireCustomEvent, HttpError, type HttpHandler, type HttpInteraction, HttpRequest, HttpResponse, type Interaction, InternalLocation, type NonEmptyArray, type OneOrMore, type PromptInteraction, type QuerySelector, type ReceiveBroadcast, RequestError, type SetAppBadge, type Submit, type TestConfig, type TestData, TestDatabaseData, type TestInput, type TestableComponent, type TestableDom, type TextInput, type ZeroOrMore, type ZeroOrOne, advanceTime, appBadgeCount, attr, clearAppBadge, click, defaultTestConfig, fireCustomEvent, newTestData, one, receiveBroadcast, setAppBadge, submit, testApplication, testComponent, textInput };

package/dist/testing.js

@@ -0,0 +1,40 @@
+import {
+  TestDatabaseData,
+  advanceTime,
+  appBadgeCount,
+  attr,
+  clearAppBadge,
+  click,
+  defaultTestConfig,
+  fireCustomEvent,
+  newTestData,
+  one,
+  receiveBroadcast,
+  setAppBadge,
+  submit,
+  testApplication,
+  testComponent,
+  textInput
+} from "./chunk-DZAR6PTR.js";
+import "./chunk-NSWOTCDU.js";
+import "./chunk-KNHJPAIU.js";
+import "./chunk-XICUXW4T.js";
+import "./chunk-PKBMQBKP.js";
+export {
+  TestDatabaseData,
+  advanceTime,
+  appBadgeCount,
+  attr,
+  clearAppBadge,
+  click,
+  defaultTestConfig,
+  fireCustomEvent,
+  newTestData,
+  one,
+  receiveBroadcast,
+  setAppBadge,
+  submit,
+  testApplication,
+  testComponent,
+  textInput
+};

package/dist/webcomponent.d.ts

@@ -0,0 +1,18 @@
+import { C as Component } from './index-fpCmXVEu.js';
+import './db/index.js';
+
+/** Options for `defineWebComponent`. */
+type WebComponentOptions<Event> = {
+    /** Maps a typed component event to a DOM custom-event name. */
+    events?: (event: Event) => string;
+};
+/**
+ * Registers a ctrl-fx Component as a native custom element. Component events are dispatched as
+ * CustomEvents using the name returned by `options.events`.
+ * @param tagName the custom element tag name (must contain a hyphen)
+ * @param component the ctrl-fx component to mount
+ * @param options optional configuration
+ */
+declare function defineWebComponent<State, Event>(tagName: string, component: Component<State, void, Event>, options?: WebComponentOptions<Event>): void;
+
+export { type WebComponentOptions, defineWebComponent };

package/dist/webcomponent.js

@@ -0,0 +1,51 @@
+import {
+  ComponentManager,
+  domInterpreter,
+  realStyleRegistry
+} from "./chunk-DZAR6PTR.js";
+import "./chunk-NSWOTCDU.js";
+import "./chunk-KNHJPAIU.js";
+import "./chunk-XICUXW4T.js";
+import {
+  __publicField
+} from "./chunk-PKBMQBKP.js";
+
+// src/webcomponent.ts
+function defineWebComponent(tagName, component, options) {
+  class CtrlFxElement extends HTMLElement {
+    constructor() {
+      super(...arguments);
+      __publicField(this, "_mgr", null);
+    }
+    connectedCallback() {
+      const shadow = this.attachShadow({ mode: "open" });
+      const mount = document.createElement("div");
+      shadow.appendChild(mount);
+      this._mgr = new ComponentManager(
+        component,
+        mount,
+        globalThis.window,
+        domInterpreter,
+        realStyleRegistry(),
+        (event) => {
+          const eventName = options?.events ? options.events(event) : "event";
+          this.dispatchEvent(
+            new CustomEvent(eventName, {
+              detail: event,
+              bubbles: true,
+              composed: true
+            })
+          );
+        }
+      );
+    }
+    disconnectedCallback() {
+      this._mgr?.destroy();
+      this._mgr = null;
+    }
+  }
+  customElements.define(tagName, CtrlFxElement);
+}
+export {
+  defineWebComponent
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ctrl-fx",
-  "version": "0.0.1",
+  "version": "0.1.1",
   "description": "A no-dependency, purely functional TypeScript framework for building web applications",
   "type": "module",
   "license": "Apache-2.0",
@@ -27,7 +27,7 @@
     "dev": "vite --host",
     "clean": "rm -rf dist",
     "build": "tsc && vite build --config doc/examples/vite.config.ts doc/examples",
-    "build:lib": "tsc -p tsconfig.build.json",
+    "build:lib": "tsup",
     "preview": "vite preview",
     "test": "vitest run",
     "test:watch": "vitest --watch",
@@ -74,12 +74,13 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "typedoc": "^0.28.19",
     "eslint": "^10.4.1",
     "highlight.js": "^11.11.1",
     "prettier": "^3.8.3",
     "ts-node": "^10.9.2",
+    "tsup": "^8.5.1",
     "tsx": "^4.20.6",
+    "typedoc": "^0.28.19",
     "typescript": "~5.8.3",
     "typescript-eslint": "^8.60.0",
     "vitest": "^3.2.4"