foldkit 0.13.0-canary.0 → 0.13.0-canary.2

package/README.md

@@ -1,11 +1,23 @@
 # Foldkit
 
-> ⚠️ **Experimental**: Foldkit is in canary release for early adopters and experimenters. APIs are incomplete and may change rapidly.
+> ⚠️ Foldkit is in canary release for early adopters and experimenters. APIs are incomplete and may change rapidly.
 
-**Foldkit** is an [Elm](https://elm-lang.org/)-inspired UI framework powered by [Effect](https://effect.website/).
+**Foldkit** is an [Elm](https://elm-lang.org/)-inspired framework for building web applications powered by [Effect](https://effect.website/).
 
 > Like origami: simple parts become intricate when folded together.
 
+---
+
+## Philosophy
+
+Foldkit applies functional programming principles to web application development.
+
+- **Pure updates** — State transitions are deterministic functions: `(model: Model, message: Message): Model` is the only way to change state.
+- **Controlled side effects** — Side effects are described as `Command<Message>` values and executed by the runtime, not performed directly in update functions.
+- **Explicit state transitions** — Every state change is modeled as a specific message type and is captured in the update function.
+
+---
+
 ## Installation
 
 The best way to get started with Foldkit is to use `create-foldkit-app`. This
@@ -16,12 +28,16 @@ package manager and example template.
 npx create-foldkit-app@latest --wizard
 ```
 
-## Counter Example
+---
+
+### Simple Counter Example
+
+See the full example at [examples/counter/src/main.ts](examples/counter/src/main.ts)
 
 ```ts
 import { Match as M, Schema } from 'effect'
 import { Runtime } from 'foldkit'
-import { Class, Html, OnClick, button, div } from 'foldkit/html'
+import { Html, html } from 'foldkit/html'
 import { ts } from 'foldkit/schema'
 
 // MODEL
@@ -41,13 +57,13 @@ type Decrement = typeof Decrement.Type
 type Increment = typeof Increment.Type
 type Reset = typeof Reset.Type
 
-type Message = typeof Message.Type
+export type Message = typeof Message.Type
 
 // UPDATE
 
-const update = (count: Model, message: Message): [Model, Runtime.Command<Message>[]] =>
+const update = (count: Model, message: Message): [Model, ReadonlyArray<Runtime.Command<Message>>] =>
   M.value(message).pipe(
-    M.withReturnType<[Model, Runtime.Command<Message>[]]>(),
+    M.withReturnType<[Model, ReadonlyArray<Runtime.Command<Message>>]>(),
     M.tagsExhaustive({
       Decrement: () => [count - 1, []],
       Increment: () => [count + 1, []],
@@ -61,6 +77,8 @@ const init: Runtime.ElementInit<Model, Message> = () => [0, []]
 
 // VIEW
 
+const { div, button, Class, OnClick } = html<Message>()
+
 const view = (count: Model): Html =>
   div(
     [Class('min-h-screen bg-white flex flex-col items-center justify-center gap-6 p-6')],
@@ -96,4 +114,40 @@ Runtime.run(element)
 
 ---
 
-**📚 Full documentation and examples**: https://github.com/devinjameson/foldkit
+## Development
+
+Explore the examples locally:
+
+```bash
+git clone https://github.com/devinjameson/foldkit.git
+cd foldkit
+pnpm install
+
+# In one terminal - build Foldkit in watch mode
+pnpm dev:core
+
+# In another terminal - run the counter example
+pnpm dev:example:counter
+```
+
+---
+
+## Status
+
+We're building in the open. Feedback, issues, and contributions are welcome.
+
+---
+
+## Roadmap
+
+- [x] Core program loop with ADT-based update
+- [x] DOM rendering
+- [x] Optimized DOM rendering (minimal diffs, efficient updates)
+- [x] Router integration
+- [ ] Devtools + tracing
+
+---
+
+## License
+
+MIT