examples.md

Examples

Runnable demo applications, ordered from simplest to most complete. Each entry lists the entry-point class, the port the server binds to, and the concepts the example introduces.

Follow getting started to build the repository once. Then run any entry point from the repository root:

mvn exec:java -pl examples -Dexec.mainClass=<fully.qualified.MainClass>

Or from your IDE, by running the main method of the entry-point class.

Catalog

1. Counter — minimal stateful component

• Entry point: Counter.java
• URL: http://localhost:8080
• Demonstrates: the smallest possible app — a LocalStateComponent<Integer, CounterIntent>, an intent-only ComponentView<Integer, CounterIntent>, and a reducer that owns the count cache.

2. PlainForm — request-driven page with GET/POST

• Entry point: PlainForm.java
• URL: http://localhost:8080
• Demonstrates: branching the initial state on the HTTP method, sealed interface state (EmptyName / FullName), and posting a classic HTML <form> whose query parameters drive the next render.

3. JettyTodos — TODO tracker with form submit

• Entry point: JettyTodos.java
• URL: http://localhost:8080
• Demonstrates: list rendering with of(stream...), an ElementRef to read the text input's value on submit, on("submit", true, ...), and updating immutable state arrays.

4. Life — Conway's Game of Life

• Entry point: Life.java
• URL: http://localhost:8082
• Demonstrates: large grid rendering, click-to-toggle cells, control buttons (Start / Stop / Clear / Random), and the onUpdated / onUnmounted lifecycle hooks driving a ScheduledExecutorService to advance generations. Also shows serving CSS via StaticResources.

5. Counters — multiple components synced to the URL

• Entry point: Counters.java
• URL: http://localhost:8085/16/-1?c4=27
• Demonstrates: a tree of components coordinated by CountersMainComponent, extending AddressBarSyncComponent to map path elements and query parameters to context keys:
  • ContextCounterComponent — ContextStateComponent<Integer> synced to a URL path element or query parameter.
  • CachedCounterComponent — StoredStateComponent<Integer> whose state survives unmount via a shared ConcurrentHashMap.
  • HideableCounterComponent — conditional rendering with when(state, ...) toggled by a checkbox.
  • CountersView — a single reusable view shared by all three counter types.
  • CountersAppComponent — top-level routing between the counters page and a 404 page.

6. CrudApp — full admin panel with AI agent

• Entry point: CrudApp.java

• URL: http://localhost:8085

• Demonstrates the end-to-end compositions stack:

  • Routing — Router mapping /posts, /posts/new, /posts/:id, /comments, /comments/:id to blocks.
  • Blocks + views — direct state-owning list (PostsListBlock, CommentsListBlock) and edit/create form components (PostEditBlock, PostCreateBlock, CommentEditBlock, CommentCreateBlock). DefaultListView is a complete schema-driven grid with exact counts, bounded first/previous/next/last pagination, page-size selection, keyed sorting, global search, per-column filters, guarded row and bulk actions, stable empty/error states, query-preserving edit links, related-comments navigation, responsive overflow, and accessible table metadata. DefaultFormView renders semantic, typed, accessible create/edit forms with dirty and busy states, field-level persistence feedback, a post ID/label relationship selector, not-found handling, and capability-gated actions. Destructive and dirty-discard browser actions use accessible native confirmation dialogs. Both views dispatch typed intents and share CrudSchemas.
  • Groups — nested Group("Admin") → Group("Posts") / Group("Comments"); the tree drives the ExplorerBlock sidebar menu.
  • Telemetry dashboard — DemoDashboards declares an immutable trend and log panel, while DemoTelemetry adapts the live services separately.
  • Layout — DefaultLayout with left sidebar (Explorer), right sidebar (Prompt), header, and a placement policy mapping forms inline and approvals to modals.
  • Auth — a separate Composition for /auth/login using SimpleAuthProvider + LoginBlock; AuthComponent redirects anonymous requests.
  • AI agent — PromptBlock talks to an AgentService, selectable via -Dai.agent=regex|claude|ollama. Backed by ABAC authorization (AccessPolicy, Authorization) and human-in-the-loop approvals via ApprovalSpawner + DelegationApprovalBlock.
  • Domain — PostService and CommentService return typed form outcomes, enforce the comment-to-post relationship, and demonstrate cascading comment deletion when a post is removed. Agent parsing lives in RegexAgentService; records live in entities/.

  Selecting the agent backend:

  # default — deterministic regex stub, no external calls
  mvn exec:java -pl examples -Dexec.mainClass=rsp.app.posts.CrudApp
  
  # Claude (requires ANTHROPIC_API_KEY)
  mvn exec:java -pl examples -Dexec.mainClass=rsp.app.posts.CrudApp -Dai.agent=claude
  
  # local Ollama
  mvn exec:java -pl examples -Dexec.mainClass=rsp.app.posts.CrudApp -Dai.agent=ollama

Concept coverage

Concept	Counter	PlainForm	JettyTodos	Life	Counters	CrudApp
InitialStateComponent	+		+
Custom Component<S> subclass		+		+	+	+
Sealed-interface state		+			+
ElementRef / form submit			+			+
HTTP method / query-param branching		+
Lifecycle hooks (onUpdated / onUnmounted)				+		+
URL ↔ state sync (AddressBarSyncComponent)					+
Persistent state across unmount (StoredStateComponent)					+
Conditional rendering (when(...))			+	+	+	+
Static resources (StaticResources)				+	+	+
Routing (Router + blocks)						+
Layout + composition + groups						+
Schema-driven data grid						+
Auth composition						+
AI agent + ABAC + HITL approval						+