ctrl-fx 0.0.1

package/LICENSE

@@ -0,0 +1,184 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but not
+      limited to compiled object code, generated documentation, and
+      conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under the
+      License, as indicated by a copyright notice that is included in or
+      attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other
+      transformations represent, as a whole, an original work of authorship.
+      For the purposes of this License, Derivative Works shall not include
+      works that remain separable from, or merely link (or bind by name) to
+      the interfaces of, the Work and interfaces of, the Work and Derivative
+      Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the
+      purposes of this definition, "submitted" means any form of electronic,
+      verbal, or written communication sent to the Licensor or its
+      representatives, including but not limited to communication on
+      electronic mailing lists, source code control systems, and issue
+      tracking systems that are managed by, or on behalf of, the Licensor
+      for the purpose of discussing and improving the Work, but excluding
+      communication that is conspicuously marked or designated in writing by
+      the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and incorporated
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of, publicly
+      display, publicly perform, sublicense, and distribute the Work and
+      such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of this
+      License, each Contributor hereby grants to You a perpetual, worldwide,
+      non-exclusive, no-charge, royalty-free, irrevocable (except as stated
+      in this section) patent license to make, have made, use, offer to
+      sell, sell, import, and otherwise transfer the Work, where such
+      license applies only to those patent claims licensable by such
+      Contributor that are necessarily infringed by their Contribution(s)
+      alone or by the combination of their Contribution(s) with the Work to
+      which such Contribution(s) was submitted. If You institute patent
+      litigation against any entity (including a cross-claim or counterclaim
+      in a lawsuit) alleging that the Work or any Contribution incorporated
+      within the Work constitutes direct or contributory patent infringement,
+      then any and all patent licenses granted to You under this License for
+      that Work shall terminate as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the Work
+      or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You meet
+      the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative Works
+          a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works that
+          You distribute, all copyright, patent, trademark, and attribution
+          notices from the Source form of the Work, excluding those notices
+          that do not pertain to any part of the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the attribution
+          notices contained within such NOTICE file, in at least one of the
+          following places: within a NOTICE text file distributed as part of
+          the Derivative Works; within the Source form or documentation, if
+          provided along with the Derivative Works; or, within a display
+          generated by the Derivative Works, if and wherever such third-party
+          notices normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License. You may
+          add Your own attribution notices within Derivative Works that You
+          distribute, alongside or as an addendum to the NOTICE text from
+          the Work, provided that such additional attribution notices cannot
+          be construed as modifying the License.
+
+      You may add Your own license statement for Your modifications and may
+      provide additional grant of rights to use, reproduce, modify, prepare
+      Derivative Works of, publicly display, publicly perform, sublicense,
+      and distribute those modifications and Derivative Works, subject to
+      the terms and conditions of this License, or under a different
+      license, provided that Your use of the Work complies with the terms
+      and conditions of this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work by
+      You to the Licensor shall be under the terms and conditions of this
+      License, without any additional terms or conditions. Notwithstanding
+      the above, nothing herein shall supersede or modify the terms of any
+      separate license agreement you may have executed with Licensor
+      regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or agreed
+      to in writing, Licensor provides the Work (and each Contributor
+      provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES
+      OR CONDITIONS OF ANY KIND, either express or implied, including,
+      without limitation, any warranties or conditions of TITLE,
+      NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR
+      PURPOSE. You are solely responsible for determining the appropriateness
+      of using or reproducing the Work and assume any risks associated with
+      Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise, unless
+      required by applicable law (such as deliberate and grossly negligent
+      acts) or agreed to in writing, shall any Contributor be liable to You
+      for damages, including any direct, indirect, special, incidental, or
+      exemplary damages of any character arising as a result of this License
+      or out of the use or inability to use the Work (including but not
+      limited to damages for loss of goodwill, work stoppage, computer
+      failure or malfunction, or all other commercial damages or losses),
+      even if such Contributor has been advised of the possibility of such
+      damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing the
+      Work or Derivative Works thereof, You may choose to offer, and charge
+      a fee for, acceptance of support, warranty, indemnity, or other
+      liability obligations and/or rights consistent with this License.
+      However, in accepting such obligations, You may offer such obligations
+      only on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify, defend,
+      and hold each Contributor harmless for any liability incurred by, or
+      claims asserted against, such Contributor by reason of your accepting
+      any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025 Christopher Carroll
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,124 @@
+# ctrl-fx
+
+Ctrl-fx is a no-dependency, purely functional TypeScript framework for writing
+web applications and web components. Like many front end frameworks, it is
+inspired by [Elm](https://elm-lang.org).
+
+All side effects are managed by the framework. Users of the framework specify
+data structures that represent effects. These data structures are associated
+with a DOM element's event types. At runtime, when an event occurs, an
+interpreter reads these data structures and actually performs the effects. A
+different interpreter is used for testing, where the state of the world can be
+specified and inspected by the application author.
+
+State is managed by the framework. Unlike Elm, there is no top-level update
+function, updating state is itself an effect.
+
+An application is a function that takes state and returns a virtual DOM.
+
+## A very minimal example
+
+```ts
+import { manageApplication } from 'ctrl-fx'
+import { makeDom } from 'ctrl-fx/dom'
+import { makeEffects } from 'ctrl-fx/effects'
+
+// This is a very simple example of a stateful application. The application
+// state is of type `number`.
+
+// We import the dom elements functions with `makeDom()`, passing it the
+// application state type, and `never` for the Event type, since this is a top
+// level application and won't be firing any events upward in the component
+// tree.
+const { button_, div_, p_ } = makeDom<number, never>()
+
+// Same thing for the effects we'll use, we pass the application state type and
+// event type to `makeEffects()` to import versions of the Effects that are
+// typed correctly for this application.
+const { updateState } = makeEffects<number, never>()
+
+// The application itself is a function that takes the current count returns a
+// view that displays it, and allows more clicks by attaching the `updateState`
+// effect to the button.
+const application = (count: number) =>
+  div_(
+    p_(`Click count: ${count}`),
+    button_('Click Me').onClick(updateState(count => count + 1)),
+  )
+
+// The manageApplication() function creates a ComponentManager that will manage
+//  application state. Whenever application state changes, the view is
+// re-rendered application the DOM is updated.  This function takes our
+// application and the initial state of 0.
+manageApplication(application, 0)
+```
+
+## Testing
+
+One of the main goals of Ctrl-fx is to facilitate comprehensive testing. Because
+side effects are modeled with data structures, application logic can easily be
+tested with a purely functional effect interpreter that is distinct from the
+runtime effect interpreter.
+
+Here's a quick example.
+
+```typescript
+import { describe, expect, it } from 'vitest'
+import { makeDom, typeAttr } from 'ctrl-fx/dom'
+import { makeEffects } from 'ctrl-fx/effects'
+import { click, one, testApplication, textInput } from 'ctrl-fx/testing'
+
+type State = string
+
+// `_` is a fragment helper — it groups children without adding a DOM wrapper
+// element.
+const { _, button_, input, p_ } = makeDom<State, never>()
+
+const { alert, getState, updateState } = makeEffects<State, never>()
+
+// The application takes the user's name as state and says hello when the
+// button is clicked. The text field updates state on each keystroke.
+const application = (state: State) =>
+  _(
+    p_('Name'),
+    input(typeAttr('text'))
+      .prop('value', state)
+      .onTextInput(textState => updateState(_prev => textState.value)),
+    button_('Say Hello').onClick(
+      getState().flatMap(state => alert(`Hello, ${state}`)),
+    ),
+  )
+
+describe('shows alert', () => {
+  it('says hello to user', () => {
+    // `testApplication` runs the app with a simulated environment.
+    // `one('selector')` queries the virtual DOM and asserts exactly one match.
+    const app = testApplication(application, '')
+      // type "world" into the text field
+      .run(textInput(one('input'), 'world'))
+      // click the button
+      .run(click(one('button')))
+
+    // `app.data` exposes the simulated environment — window, storage, etc.
+    expect(app.data.window.alerts.length).toBe(1)
+    expect(app.data.window.alerts[0]).toBe('Hello, world')
+  })
+})
+```
+
+## Installation
+
+```sh
+npm install ctrl-fx
+```
+
+## Learn more
+
+See the [guide](doc/guide.md) (which is currently a work in progress) for a more
+in-depth view of the framework.
+
+If you clone this repository, you can run examples:
+
+```
+npm install && npm run examples
+```

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "ctrl-fx",
+  "version": "0.0.1",
+  "description": "A no-dependency, purely functional TypeScript framework for building web applications",
+  "type": "module",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chris24carroll/ctrl-fx.git"
+  },
+  "keywords": [
+    "framework",
+    "functional",
+    "typescript",
+    "virtual-dom",
+    "effects",
+    "web",
+    "spa",
+    "frontend",
+    "component",
+    "state-management"
+  ],
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "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",
+    "preview": "vite preview",
+    "test": "vitest run",
+    "test:watch": "vitest --watch",
+    "test:coverage": "vitest --coverage",
+    "deploy": "./tools/archive.sh && ./tools/deploy.sh",
+    "format": "prettier --write src",
+    "format:check": "prettier --check src",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "typecheck": "tsc --noEmit",
+    "examples": "vite doc/examples --open",
+    "docs": "typedoc --entryPoints src/index.ts src/effects.ts src/testing.ts src/dom/index.ts src/dom/components.ts src/db/index.ts src/db/errors.ts src/router.ts src/webcomponent.ts src/utils/result.ts src/utils/lens.ts src/utils/match.ts --tsconfig tsconfig.json",
+    "prepublishOnly": "npm run build:lib"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./db": {
+      "types": "./dist/db/index.d.ts",
+      "import": "./dist/db/index.js"
+    },
+    "./dom": {
+      "types": "./dist/dom/index.d.ts",
+      "import": "./dist/dom/index.js"
+    },
+    "./effects": {
+      "types": "./dist/effects.d.ts",
+      "import": "./dist/effects.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    },
+    "./router": {
+      "types": "./dist/router.d.ts",
+      "import": "./dist/router.js"
+    },
+    "./webcomponent": {
+      "types": "./dist/webcomponent.d.ts",
+      "import": "./dist/webcomponent.js"
+    }
+  },
+  "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",
+    "tsx": "^4.20.6",
+    "typescript": "~5.8.3",
+    "typescript-eslint": "^8.60.0",
+    "vitest": "^3.2.4"
+  }
+}