Werkbank

Werkbank 2026-01-20T18:07:20+0100 https://werkbank.dev Building a Resizable Grid 2026-01-18T00:00:00+0000 https://werkbank.dev/blog/building-resizable-grid/ It starts with a layout. It always starts with a layout. "I want an IDE," I tell myself. "I want something that feels like Sublime Text. I want a sidebar. I want a terminal at the bottom. I want a main editor area. And I want to resize them all." I want to build rich user interfaces that feel like *applications*, not websites. So I look at the tools. <code>react-resizable-panels</code> is great, but it's 1-dimensional. To get a grid, you have to nest panels inside panels. You have a Row, and inside that Row, you have two Columns. And inside one of those Columns, you have another Row. It's a tree. But I don't want a tree. I want a grid. And then I try to use it on my tablet. I try to grab that 6px wide border with my thumb. I fail. I try again. I fail. Why is this so hard? I look at <code>react-grid-layout</code>. It's powerful. But it feels like a dashboard. It wants me to drag widgets around. It wants to manage "items." I just want to move a line. I just want to say "this column is now wider." I realized I was fighting the abstractions. I was trying to force a tree structure to behave like a grid, or a dashboard engine to behave like a layout engine. <h3 id="the-epiphany-css-grid-is-already-the-answer">The Epiphany: CSS Grid is Already the Answer</h3> I stopped looking at React libraries and looked at CSS. <ul> <li><code>grid-template-columns: 200px 1fr 300px;</code></li> <li><code>grid-template-rows: 1fr 200px;</code></li> </ul> That's it. That's the API I want. CSS Grid already solves the layout problem perfectly. It handles the alignment, the spacing, the responsiveness. All I need is a way to change those numbers when I drag a mouse. And what is a drag? It's not state. It's not a value. It's a stream. It's <code>pointerdown</code>. Then a flurry of <code>pointermove</code> events. Then <code>pointerup</code>. It's a sequence of events over time. And when you say "sequence of events over time," there is only one tool that should come to mind. RxJS. <h3 id="how-it-works-the-architecture">How it Works: The Architecture</h3> I decided to build a single component. No nested providers. No recursive structures. Just one <code>&lt;ResizeableGrid /&gt;</code>. But how do you resize a grid gap? You can't catch events on a gap. So I cheated. I injected columns. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="typescript">// utils.ts export let getGridTemplateColumns = ( groups: Columns, handleSize: string = &quot;1rem&quot;, ) =&gt; { let lastIndex = groups.length - 1; return groups .map((g, index) =&gt; { // [Content] [Handle] [Content] return `${getLength(g.size)} ${lastIndex !== index ? handleSize : &quot;&quot;}`; }) .join(&quot; &quot;); };</code></pre> My grid isn't just content. It's content interleaved with "handles." If I have 3 columns of content, I actually have 5 columns in the CSS Grid. Column 1. Handle 1. Column 2. Handle 2. Column 3. <h3 id="the-invisible-skeleton">The Invisible Skeleton</h3> There was a problem. If I defined a 3x3 grid, but only put one item in the top-left corner, the rest of the grid collapsed. CSS Grid tries to be smart. It shrinks empty tracks. But I needed the grid to be rigid. I needed it to exist even if it was empty. So I filled it with ghosts. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="tsx">// grid.tsx let areas = useMemo(() =&gt; { return Array(columns * rows) .fill(null) .map((_, arrayindex) =&gt; { // ... calculate row and column ... return ( &lt;div key={gridArea} className={`row-${row} col-${column}`} style={{ gridArea, width: &quot;100%&quot;, height: &quot;100%&quot; }} /&gt; ); }); }, [columns, rows]);</code></pre> I generate a <code>div</code> for every single cell in the grid. These divs are invisible. They have no content. But they force the grid to respect the <code>grid-template-rows</code> and <code>grid-template-columns</code> I defined. They hold the structure open so the resize handles have somewhere to live. "But wait," I hear you ask. "Doesn't that create a lot of DOM nodes?" Yes, it does. But for an application layout, we are talking about maybe 12 to 20 divs max. We aren't rendering a data grid with 10,000 rows. We are rendering the skeleton of the page. The cost is negligible compared to the stability it buys us. <h3 id="the-fat-finger-problem">The "Fat Finger" Problem</h3> Speaking of handles, have you ever tried to grab a 6px border on a touch screen? It's miserable. I wanted a thin, elegant line. But I wanted a big, chunky hit area. CSS to the rescue again. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="typescript">// grid.css.ts export let dragHandelButton = style({ // ... position: &quot;absolute&quot;, width: &quot;100%&quot;, height: &quot;100%&quot;, // ... }); export let dragHandelButtonVariant = styleVariants({ vertical: [ dragHandelButton, { cursor: &quot;ew-resize&quot;, paddingLeft: &quot;0.5rem&quot;, paddingRight: &quot;0.5rem&quot;, left: &quot;-0.5rem&quot;, // Center the padding over the line }, ], // ... });</code></pre> The button is transparent. It has <code>0.5rem</code> padding on both sides. It's positioned negatively so that the padding centers exactly over the visible line. To the eye, it's a pixel. To the finger, it's a highway. <h3 id="accessibility-not-just-for-mouse-users">Accessibility: Not Just for Mouse Users</h3> But what if you can't use a mouse? What if you can't use a touchscreen? A resize handle is an interactive element. It must be focusable. It must be operable with a keyboard. I made each handle a <code>&lt;button&gt;</code>. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="tsx">// dragHandle.tsx &lt;button {...props} tabIndex={0} onKeyDown={handleKeyDown} // ... /&gt;</code></pre> And I implemented the arrow keys. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="typescript">// dragHandle.tsx let handleKeyDown: KeyboardEventHandler&lt;HTMLElement&gt; = (event) =&gt; { if (![&quot;ArrowLeft&quot;, &quot;ArrowRight&quot;, &quot;ArrowUp&quot;, &quot;ArrowDown&quot;].includes(event.key)) { return; } let movementX = event.key === &quot;ArrowLeft&quot; ? -8 : event.key === &quot;ArrowRight&quot; ? 8 : 0; // ... onResize({ movementX, ... }); };</code></pre> If you tab to a vertical handle, you can use Left/Right arrows to move it by 8px. If you tab to a horizontal handle, you can use Up/Down. It uses the exact same <code>onResize</code> stream as the mouse interaction. This isn't just "nice to have." It's essential. If your tool is for developers, you have to assume some of them are power users who hate leaving the keyboard. <h3 id="the-missing-piece-usedrag">The Missing Piece: useDrag</h3> I keep mentioning "the stream," but where does it come from? I built a hook called <code>useDrag</code>. Its job is to normalize the chaos of browser events. We use Pointer Events. They are the modern standard that unifies mouse, touch, and pen interactions into a single API. <code>useDrag</code> abstracts this away. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="typescript">// useDrag.ts (Conceptual) export function useDrag() { // ... // Listen for pointer events let move$ = fromEvent(document, &quot;pointermove&quot;); // Calculate deltas return move$.pipe( map(event =&gt; ({ movementX: event.movementX, // ... })) ); }</code></pre> It returns a <code>drag$</code> observable that emits clean, normalized <code>{ movementX, movementY }</code> objects. The grid component doesn't care if you are using a mouse, a trackpad, or an Apple Pencil. It just consumes the delta. <h3 id="the-unit-problem-pixels-vs-fractions">The Unit Problem: Pixels vs. Fractions</h3> One of the trickiest parts of building a grid is units. CSS Grid loves <code>fr</code> (fraction) units. <code>1fr 2fr</code> means the second column is twice as wide as the first. But pointer events are in pixels. You drag <code>10px</code> to the right. If you try to mix them, you go insane. "Add 10px to 1fr." What does that even mean? So I normalize everything. When a drag starts, I read the current computed pixel width of the columns. I do all the math in pixels. <code>200px + 10px = 210px</code>. But then, before I save the state, I convert it back to relative units. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="typescript">// utils.ts export function toPercent(sizePx: number, parent: HTMLElement, orientation: &quot;vertical&quot; | &quot;horizontal&quot;) { let parentSize = orientation === &quot;vertical&quot; ? parent.clientWidth : parent.clientHeight; return `${(sizePx / parentSize) * 100}fr`; };</code></pre> Why <code>fr</code> and not <code>%</code>? Because <code>fr</code> handles the "available space" better when you have fixed-size tracks mixed in. By converting the pixel result into a fraction of the container, the grid remains responsive. If you resize the window, the columns scale proportionally. <h3 id="collapsing-panels">Collapsing Panels</h3> "But what if I want to hide the sidebar?" In an IDE, you often want to collapse a panel completely. My grid supports this natively via constraints. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="typescript">// grid.stories.tsx defaultValue={{ columns: [ { size: 200, minSize: 0, maxSize: 500 }, // Sidebar &quot;1fr&quot; // Main content ] }}</code></pre> If you drag the sidebar to the left, it shrinks. If you hit 0px, it vanishes. Because we are using CSS Grid, <code>0fr</code> or <code>0px</code> effectively hides the column. The content inside is still there (so state is preserved), but it takes up no space. <h3 id="persistence-remembering-the-state">Persistence: Remembering the State</h3> There is nothing more annoying than an IDE that forgets your layout when you refresh the page. Because I'm using RxJS, I can tap into the state stream easily. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="typescript">// grid.tsx let [gridState, setGridState] = useGridState({ defaultColumns: [&quot;auto&quot;, &quot;auto&quot;, &quot;auto&quot;], defaultRows: [&quot;auto&quot;, &quot;auto&quot;], persist: &quot;my-grid-layout&quot; // Auto-save to localStorage });</code></pre> I built a custom hook <code>useGridState</code> that wraps the RxJS behavior subject. It has built-in persistence. When the <code>gridState</code> updates (which happens on <code>mouseup</code>), it automatically writes to <code>localStorage</code>. When the component mounts, it rehydrates from storage. It's one line of code, but it makes the grid feel "pro." <h3 id="the-api-controlled-vs-uncontrolled">The API: Controlled vs Uncontrolled</h3> One of the biggest challenges in building reusable components is deciding who owns the state. Should the component manage itself? Or should the parent control it? I decided to follow the Web Platform. Just like a native <code>&lt;input&gt;</code>, the grid supports both modes. You can let it manage itself (Uncontrolled) or you can take the wheel (Controlled). It feels familiar because it mirrors the API you've been using since HTML 1.0. Uncontrolled Mode is great for simple layouts where you just want it to work. You give it a <code>defaultValue</code>, and it handles the rest. This follows the same philosophy as our <a href="/blog/building-custom-react-inputs/">Building Custom React Inputs</a> approach: let the component manage its own state when possible. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="tsx">&lt;ResizeableGrid persist=&quot;my-layout&quot; defaultValue={{ columns: [200, &quot;1fr&quot;, { size: 200, minSize: 100, maxSize: 300 }], rows: [&quot;auto&quot;, &quot;auto&quot;], }} &gt; &lt;GridArea column={{ start: 1, end: 2 }} row={{ start: 1, end: 2 }}&gt; Sidebar &lt;/GridArea&gt; {/* ... */} &lt;/ResizeableGrid&gt;</code></pre> Controlled Mode is for when you need full power. Maybe you want a button that toggles the sidebar. Maybe you want to save the layout to a database instead of localStorage. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="tsx">let [state, setState] = useGridState({ columns: 3, rows: 2, defaultColumns: [{ size: 200, mode: &quot;static&quot; }, &quot;1fr&quot;, &quot;auto&quot;], defaultRows: [&quot;auto&quot;, 200], }); let toggleSidebar = () =&gt; { setState(current =&gt; { // ... logic to toggle column size ... }) } return ( &lt;&gt; &lt;button onClick={toggleSidebar}&gt;Toggle Sidebar&lt;/button&gt; &lt;ResizeableGrid value={state} onChange={setState} &gt; {/* ... */} &lt;/ResizeableGrid&gt; &lt;/&gt; );</code></pre> By exposing both <code>value</code>/<code>onChange</code> and <code>defaultValue</code>, we get the flexibility of a controlled component with the ease of use of an uncontrolled one. <h3 id="is-rxjs-overkill">Is RxJS Overkill?</h3> I know what you're thinking. "You imported the entire RxJS library just to drag a div?" First, RxJS is tree-shakeable. I'm only importing <code>merge</code>, <code>map</code>, <code>share</code>, <code>tap</code>, and <code>sample</code>. Second, try writing this in vanilla JS. You need <code>pointerdown</code> handlers. You need <code>pointermove</code> handlers attached to <code>document</code> (so you don't lose the drag if the mouse moves fast). You need <code>keydown</code> handlers for accessibility. You need to clean them all up when the component unmounts. You need to throttle the updates to 60fps. With RxJS, I just say: <code>merge(pointer$, key$).pipe(...)</code> It's declarative. It handles the cleanup. It handles the race conditions. It's not overkill; it's the right tool for the job. <h3 id="the-stream-rxjs-in-action">The Stream: RxJS in Action</h3> Now for the engine. I didn't want to manage <code>isDragging</code> state in React. I didn't want to trigger re-renders 60 times a second just to update a width. I wanted to bypass React entirely during the drag. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="typescript">// grid.tsx useEffect(() =&gt; { // ... let dragEvent$ = merge(drag$, resize$).pipe(share()); let xSubscription = dragEvent$.pipe(onDrag(&quot;col&quot;)).subscribe((columns) =&gt; { setColumns(columns); }); let ySubscription = dragEvent$.pipe(onDrag(&quot;row&quot;)).subscribe((rows) =&gt; { setRows(rows); }); return () =&gt; { xSubscription.unsubscribe(); ySubscription.unsubscribe(); }; }, ...);</code></pre> Wait, <code>setColumns</code>? That triggers a re-render! Yes, but look at <code>onDrag</code>. Inside the <code>onDrag</code> operator pipeline, I do something unconventional. I talk directly to the DOM. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="typescript">// grid.tsx tap((next) =&gt; { if (type === &quot;col&quot;) { parent.style.gridTemplateColumns = getGridTemplateColumns( next, dragHandleSize, ); } // ... }), sample(dragEnd$), // Only emit to React when the drag stops!</code></pre> I update the <code>style</code> property of the grid container directly in the stream. The browser repaints instantly. React knows nothing about it. Only when the user lifts their mouse (<code>sample(dragEnd$)</code>) do I let the value pass through to <code>setColumns</code>. React wakes up, sees the new state, and reconciles. But by then, the heavy lifting is done. <h3 id="the-safety-valve">The Safety Valve</h3> "But isn't direct DOM manipulation dangerous?" It can be. If you modify the DOM and then React tries to modify it, you get conflicts. But here, React owns the structure (the divs), and I only touch the style of the container. Also, notice the cleanup in <code>useEffect</code>. When the component unmounts, <code>xSubscription.unsubscribe()</code> is called. This kills the stream. Even if a drag event is pending, it won't fire. We are safe. <h3 id="the-logic-push-and-pull">The Logic: Push and Pull</h3> Resizing a grid is a zero-sum game. If I make the sidebar wider, the main content must get narrower. I can't just change one number. I have to steal from Han to pay Chewie. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="typescript">// utils.ts function applyConstrained(...) { let total = currentEntry.size + nextEntry.size; // Clamp current currentEntry.size = clamp(currentEntry.size, current.min, current.max); // Adjust next nextEntry.size = total - currentEntry.size; // Clamp next nextEntry.size = clamp(nextEntry.size, next.min, next.max); // Adjust current again (in case next hit a constraint) currentEntry.size = total - nextEntry.size; }</code></pre> It's a dance. I push right. The current column grows. The next column shrinks. But wait! The next column has a <code>minSize</code> of <code>200px</code>. It refuses to shrink further. So I have to stop growing the current column. This logic happens in the stream, on every frame. It feels solid. It feels physical. <h3 id="conclusion">Conclusion</h3> I could have used a library. I could have accepted the nested divs. I could have lived with the bad touch support. But sometimes, you just want the thing to feel right. <ul> <li>I wanted a grid. So I used CSS Grid.</li> <li>I wanted a stream of events. So I used RxJS.</li> <li>I wanted it to be fast. So I bypassed React for the hot path.</li> </ul> It’s not a generic "Dashboard Builder." It’s not a "Panel Manager." It’s just a grid. And it resizes. This is just the beginning. With this foundation, we can build anything. Collapsible sidebars, tabbed interfaces, complex data grids. The primitives are there. The performance is there. The only limit is the layout you can imagine. TypeScript Meta-programming and Proxies 2026-01-17T00:00:00+0000 https://werkbank.dev/blog/typescript-meta-programming-and-proxies/ We all want our code to read like a sentence. There is a certain beauty in an API that just flows, where the intent is obvious and the boilerplate is non-existent. In languages like Rust, we have powerful tools to achieve this. We have Macros. Macros allow us to write code that writes other code at compile time. It's meta-programming in its truest sense. You can define a <code>derive</code> macro and suddenly your struct has JSON serialization, database mapping, and a CLI interface, all without you writing a single extra line of logic. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="rust">// In Rust, this one line generates a ton of code for us #[derive(Debug, Serialize, Deserialize)] struct User { id: u32, name: String, }</code></pre> But we aren't in Rust. We are in TypeScript. And TypeScript, for all its structural typing glory, does not have macros. We can't hook into the compilation process to generate code on the fly (well, not easily). So when we want to build complex abstractions, we often find ourselves stuck between two bad options: writing verbose boilerplate or setting up fragile code-generation scripts. But JavaScript gives us something else. It gives us a different kind of superpower. It gives us Proxies. <h2 id="enter-the-proxy">Enter the Proxy</h2> If you haven't used a <a rel="external" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy">Proxy</a> before, it's exactly what it sounds like. It's a wrapper around an object that intercepts operations. You can intercept a property read, a function call, an assignment—pretty much anything. It allows for what I like to call "Runtime Meta-programming." Instead of generating code at compile time, we can define behavior for properties that don't even exist yet. We can make an object that replies "Yes!" to any question you ask it, or an array that logs every time you try to touch its elements. Now, I can hear the performance purists sharpening their pitchforks. "Proxies are slow! Runtime interception is expensive!" And you're right. Compared to a raw property access, a Proxy is slower. But we have to ask: what are we optimizing for? In many cases, especially when dealing with I/O, network requests, or IPC (Inter-Process Communication), the bottleneck is not the property access. It's the operation itself. The microsecond cost of a Proxy is negligible compared to the millisecond latency of a network round-trip. For the developer experience (DX) gains? It's often a trade worth making. <h2 id="the-problem-a-magic-rpc-client">The Problem: A Magic RPC Client</h2> I ran into this while building the RPC system for Werkbank. I wanted to communicate between the main thread and a Web Worker. Usually, this involves a lot of <code>postMessage</code> calls and event listeners. It's messy, it's verbose, and it breaks the flow we desire. Most importantly, it's not type-safe. I wanted an API that felt local. I wanted to be able to write this: <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="typescript">// I want this to call the worker, wait for the result, and return it. const user = await client.users.getUser(123);</code></pre> But I didn't want to manually write a <code>getUser</code> method on the client for every single function in my worker. That's the boilerplate trap. And I didn't want to run a script to generate a client file every time I changed the worker code. That's the code-gen trap. I wanted it to just work. I wanted the client to magically know that <code>client.users.getUser</code> maps to a specific function in the worker, without me ever explicitly defining it. <h2 id="the-solution-recursive-proxies">The Solution: Recursive Proxies</h2> This is where the Proxy shines. We can create a "Recursive Proxy"—a proxy that, when you access a property on it, returns another proxy. Here is the core of the implementation from <code>werkbank/src/rpc/client/proxy.ts</code>. I've simplified it slightly for clarity, but the recursive structure is the real deal. Note: I'm using RxJS here for handling the event streams because it makes filtering, mapping, timeouts, and cancellation easier. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="typescript">export function createRpcProxy&lt;Config&gt;( postMessage: PostMessage, incoming$: Observable&lt;Event&lt;unknown&gt;&gt;, ): RpcClient&lt;Config&gt; { // We keep a cache of proxies to avoid creating new ones for the same path repeatedly. // This helps with memory and ensures object identity stability for the same path. let proxies = new Map&lt;string, any&gt;(); function createProxyHandler(scope: Array&lt;string&gt; = []) { let handler: ProxyHandler&lt;any&gt; = { get(_target, prop) { let key = prop.toString(); // Important: Don&#39;t proxy &#39;then&#39; if you don&#39;t want the proxy itself to be awaitable. // In our case, only the function call returns a Promise. if (key === &#39;then&#39;) return undefined; let proxyPath = [...scope, key].join(&quot;.&quot;); // Return cached proxy if it exists let currentProxy = proxies.get(proxyPath); if (currentProxy) { return currentProxy; } // This is the function that will eventually be called // e.g. client.users.getUser(123) let fn: ProxyFn = (...rawArgs: Array&lt;unknown&gt;) =&gt; { let id = crypto.randomUUID(); // Use standard UUID generation // We automatically scan arguments for Transferable objects (like ArrayBuffers) // to ensure zero-copy transfer to the worker. This traverses the args recursively. let { args, transfer } = extractTransferables(rawArgs); // Send the request to the worker postMessage( REQUEST({ id, args, path: [...scope, key], // e.g. [&#39;users&#39;, &#39;getUser&#39;] }), transfer, ); // ... logic to wait for the response (we&#39;ll get to this) ... } // Return a new Proxy for the next level of the chain // We wrap &#39;fn&#39; so that if the user calls it, our &#39;fn&#39; executes. // If they access a property on it, the &#39;get&#39; trap fires again. let proxy = new Proxy(fn, createProxyHandler([...scope, key])); proxies.set(proxyPath, proxy); return proxy; } } return handler; } // We cast the result to RpcClient&lt;Config&gt; to make TypeScript happy. // The runtime object is just a Proxy, but we promise the compiler it behaves like Config. return new Proxy({}, createProxyHandler([])) as RpcClient&lt;Config&gt;; }</code></pre> Let's break down what happens when we call <code>client.users.getUser(123)</code>: <ol> <li><code>client.users</code>: The first proxy intercepts the <code>get</code> for "users". It doesn't find it on the target object (which is empty), so it returns a new Proxy, remembering the path <code>['users']</code>.</li> <li><code>.getUser</code>: That new proxy intercepts the <code>get</code> for "getUser". It returns another new Proxy, now with the path <code>['users', 'getUser']</code>.</li> <li><code>(123)</code>: Finally, we call the function. The proxy wraps our <code>fn</code>, so we can intercept the call. Inside that function, we take the accumulated path (<code>['users', 'getUser']</code>) and the arguments (<code>[123]</code>), and we fire off a <code>postMessage</code>.</li> </ol> <h3 id="bridging-the-gap-from-postmessage-to-promise">Bridging the Gap: From <code>postMessage</code> to Promise</h3> The trickiest part of any RPC system is mapping the asynchronous response back to the original request. <code>postMessage</code> is fire-and-forget. It returns <code>void</code>. But our client function needs to return a <code>Promise</code>. We solve this with a unique ID and RxJS streams. One of the huge benefits of using RxJS here is how easily we can add robustness, like timeouts and cancellation. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="typescript">// Inside the &#39;fn&#39; above... let response$ = incoming$.pipe( // Only listen for a REPLY matching our specific request ID filter((e) =&gt; REPLY.match(e) &amp;&amp; e.payload.id === id), take(1), // We only expect one response // Add a timeout! If the worker doesn&#39;t reply in 5s, fail. timeout(5000), map((e) =&gt; { if (e.payload.reject) { throw e.payload.reject; } return e.payload.resolve; }), // If the consumer unsubscribes (e.g. React useEffect cleanup), // we tell the worker to cancel the task. finalize(() =&gt; { postMessage(UNSUBSCRIBE({ id }), []); }) ); // Convert the Observable to a Promise so the user can &#39;await&#39; it return firstValueFrom(response$);</code></pre> This effectively pauses the execution on the main thread (via <code>await</code>) until the worker processes the task and sends back a message with the matching ID, or until the timeout fires. <h2 id="but-is-it-type-safe">But is it Type Safe?</h2> I promised type safety. And this is where TypeScript's generics come in. Notice the <code>&lt;Config&gt;</code> generic in <code>createRpcProxy&lt;Config&gt;</code>. We can define our worker's API as a standard TypeScript interface. Note that on the worker side, these functions might return direct values, but on the client side, we need them to be Promises. We achieve this with a recursive mapped type. We use <code>Awaited&lt;R&gt;</code> to ensure we don't accidentally create <code>Promise&lt;Promise&lt;T&gt;&gt;</code> if the worker function is already async. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="typescript">// Recursively traverse the type T. // If it&#39;s a function, wrap the return type in a Promise. // If it&#39;s an object, recurse into it. type Promisify&lt;T&gt; = { [K in keyof T]: T[K] extends (...args: infer A) =&gt; infer R ? (...args: A) =&gt; Promise&lt;Awaited&lt;R&gt;&gt; : Promisify&lt;T[K]&gt;; }; // Define the shape of your worker API interface WorkerApi { users: { getUser(id: number): User; // Worker returns User synchronously createUser(name: string): User; }; } // The RpcClient type magically wraps everything in Promises const client = createRpcProxy&lt;WorkerApi&gt;(postMessage, incoming$); // Now client.users.getUser returns Promise&lt;User&gt; const user = await client.users.getUser(123);</code></pre> Now, when you type <code>client.</code>, TypeScript knows exactly what properties exist. It knows <code>client.users</code> exists. It knows <code>client.users.getUser</code> takes a <code>number</code> and returns a <code>Promise&lt;User&gt;</code>. If you try to type <code>client.users.deleteUser(123)</code>, TypeScript will yell at you. Even though the runtime proxy would happily accept that call and send a message to the worker (which would then fail), the compiler stops you before you even run the code. <h2 id="trade-offs">Trade-offs</h2> No solution is perfect, and Proxies are no exception. Here is what you are trading: <ul> <li>Pros: <ul> <li>Zero Boilerplate: No manual client definitions.</li> <li>Type Safety: Full TypeScript support with generics.</li> <li>Refactoring Safety: Renaming a method in the worker interface immediately flags errors in the client code.</li> <li>Flexibility: The API can evolve on the worker side without breaking the client (as long as types match).</li> </ul> </li> <li>Cons: <ul> <li>Runtime Overhead: Proxies are slower than direct property access (though usually negligible for RPC).</li> <li>Debugging: <code>console.log(client)</code> just shows a Proxy object, which can be confusing.</li> <li>Browser Support: Proxies cannot be polyfilled. They are supported in all modern browsers, but if you need to support very old environments, this won't work.</li> </ul> </li> </ul> <h2 id="conclusion">Conclusion</h2> We might not have macros in TypeScript, but we have something that fits the dynamic nature of JavaScript perfectly. Proxies allow us to build "Magic" APIs—interfaces that adapt and respond to how we use them, rather than how they were defined. They bridge the gap between the static world of types and the dynamic world of runtime execution. And sometimes, that's even better than a macro. Beyond the Main Thread 2026-01-16T00:00:00+0000 https://werkbank.dev/blog/beyond-the-main-thread/ I am typing this and the cursor blinks. It blinks because the main thread is free. But for how long? We are building apps that are too big for the browser. Not "big" like "lots of HTML". Big like "video editor", "IDE", "database". We are parsing syntax trees. We are processing audio buffers. We are running SQL queries against a WASM Postgres instance. And every time we do one of those things, the cursor stops blinking. You paste 10,000 lines of JSON into a text area. The frame drops. The scroll stutters. The user sighs. We know the solution. It’s been there since 2009. Web Workers. The browser is multi-threaded! We can spawn threads! We can run code in parallel! We can have our cake and eat it too! So why aren't we doing it? <h2 id="the-postmessage-problem">The postMessage Problem</h2> Because <code>postMessage</code> is awful. It is the assembly language of the web. It's like sending smoke signals in binary. You send a message. Maybe it’s a string. Maybe it’s an object. You lose your prototypes. You lose your functions. You lose your types. And then you wait. You add an event listener. <code>onmessage</code>. You get an event. <code>e.data</code>. What is <code>data</code>? Who knows. It’s <code>any</code>. You have to invent a protocol. "Okay, I'll send <code>{ type: 'REQUEST', id: 1, payload: ... }</code>". And the worker will send back <code>{ type: 'RESPONSE', id: 1, payload: ... }</code>. Now you have to match the IDs. You have to manage the state. You have to handle errors. What if the worker throws? The error doesn't cross the boundary. It just dies silently in the console. It is friction. It is mental overhead. It is enough to make you say, "I'll just put it in a <code>useEffect</code> and hope nobody notices the jank." <h2 id="the-dream-of-the-invisible-worker">The Dream of the Invisible Worker</h2> I don't want to think about workers. I don't want to think about serialization. I want to call a function. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="typescript">// I want this const result = await api.heavyComputation(data);</code></pre> I want to interact with a stateful system. I want to increment counters, update documents, and subscribe to real-time streams of events. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="typescript">// I want to call methods on nested modules await api.Counter.inc(1); // I want to subscribe to streams api.seconds().subscribe(tick =&gt; { console.log(tick); });</code></pre><h2 id="enter-werkbank-rpc">Enter werkbank/rpc</h2> So I built it. It is a bridge. A transparent, type-safe bridge between the main thread and the worker. It starts with a Proxy. When you create a client, we give you a ghost. It looks like your API. It has the same methods. It has the same types. But it is hollow. When you call a method on this ghost, it intercepts the call. It packages the arguments. It generates a UUID. It sends a <code>REQUEST</code> message to the worker. And then it waits. But it doesn't just wait for a promise. It waits for an Observable. <h2 id="why-rxjs">Why RxJS?</h2> In most RPC libraries, everything is a Promise. <code>async/await</code>. You ask a question, you get an answer. But sometimes, a function isn't just a question. Sometimes it's a conversation. Imagine a file upload. You don't just want to know when it's done. You want to know the progress. "10%... 20%... 50%...". A Promise can't do that. A Promise resolves once. But an Observable can emit many values over time. With <code>werkbank/rpc</code>, if your worker function returns an Observable, the client receives an Observable. You can subscribe to progress updates, real-time data feeds, or log streams. And the best part? Cancellation is free. One of the biggest pain points with Promises is that you can't cancel them. If the user navigates away while a heavy calculation is running, that calculation keeps running. It eats CPU. It drains battery. But you can unsubscribe from an Observable. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="typescript">// React Component Example useEffect(() =&gt; { const sub = api.search(query).subscribe(results =&gt; { setResults(results); }); // Cleanup function: runs when component unmounts or query changes return () =&gt; sub.unsubscribe(); }, [query]);</code></pre> When you unsubscribe on the main thread, we send an <code>UNSUBSCRIBE</code> signal to the worker. The worker tears down the operation instantly. No more zombie computations. <h2 id="the-best-of-both-worlds">The Best of Both Worlds</h2> "But I don't want to use RxJS for everything!" I hear you. Sometimes you just want <code>await</code>. So I built a hybrid. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="typescript">function observablePromise(observable, promise) { let hybrid = observable as any; hybrid.then = promise.then.bind(promise); // It acts like a Promise return hybrid; }</code></pre> You can <code>await</code> it. You can <code>.subscribe()</code> to it. It adapts to you. Note: This is pragmatic magic. "Thenables" are a known pattern in JS, and mixing them with Observables gives us the best of both worlds. You get the simplicity of <code>await</code> for single values, and the power of RxJS for streams, without changing your API surface. <h2 id="the-cost-of-serialization">The Cost of Serialization</h2> Speaking of performance, let's talk about the elephant in the room. "But wait," I hear you say. "What about serialization? Isn't <code>postMessage</code> slow?" Yes, it can be. If you send a 10MB JSON object, the browser has to clone it. That takes time. But <code>werkbank/rpc</code> doesn't solve this by magic. It solves it by letting you use Transferables. If you pass an <code>ArrayBuffer</code>, we transfer it. Zero copy. Instant. And for everything else? The cost of cloning a few kilobytes is measured in microseconds. The cost of blocking the main thread for 50ms is measured in user frustration. I will take the serialization cost over the jank any day. <h2 id="shared-workers-yes">Shared Workers? Yes.</h2> We didn't stop at dedicated workers. We also support SharedWorkers. Why? Because if you have 10 tabs open, you don't want 10 database connections. You want one. <code>werkbank/rpc</code> detects if you are connecting to a SharedWorker and handles the port negotiation automatically. The API remains exactly the same. You just change <code>new Worker()</code> to <code>new SharedWorker()</code>. This is huge for things like local-first apps. You can run a full SQL database (like PGlite) in a SharedWorker. If you ran that on the main thread, every query would freeze the UI. In a worker, it's seamless. Your UI just subscribes to the queries. <h2 id="the-worker-side">The Worker Side</h2> Okay, the client is magic. But what about the worker? Is it a mess of boilerplate? No. It is just code. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="typescript">// worker.ts import { interval } from &quot;rxjs&quot;; let count = 0; const api = { // Nested modules? No problem. Counter: { inc(val: number) { count += val; }, get() { return count; } }, // Streaming function seconds() { return interval(1000).pipe(map(i =&gt; `Tick ${i}`)); } }; createWorker({ mod: api });</code></pre> That's it. No message handlers. No switch statements. Just functions. The <code>createWorker</code> function wraps your API. It listens for those <code>REQUEST</code> messages. It finds the right function. It runs it. If it throws, we catch it. We serialize the error. We send it back. The client promise rejects. The <code>try/catch</code> block on the main thread works exactly as you expect. <h2 id="type-safety-the-secret-sauce">Type Safety (The Secret Sauce)</h2> But the real magic is the types. We use TypeScript's mapped types to project the worker's types onto the client. It acts like a mirror. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="typescript">// packages/werkbank/src/rpc/client/index.ts type RpcClient&lt;Config&gt; = { [Key in keyof Config]: Config[Key] extends (...args: any[]) =&gt; any ? Fn&lt;Parameters&lt;Config[Key]&gt;, ReturnType&lt;Config[Key]&gt;&gt; // It matches! : RpcClient&lt;Config[Key]&gt;; // It recurses! };</code></pre> This isn't just flat mapping. It's recursive. If your API has nested objects (e.g., <code>api.users.create(...)</code>), the type mapper follows them. It builds a deep proxy structure that mirrors your exact API shape, all the way down. The experience is magical. You type <code>api.</code>, and your IDE shows you <code>Counter</code>. You type <code>Counter.</code>, and it shows <code>inc</code>. You hover over <code>inc</code>, and it tells you it expects a <code>number</code>. If I change the <code>add</code> function in the worker to take a string, the client code turns red. Instantly. Across the thread boundary. <h2 id="conclusion">Conclusion</h2> The main thread is for the UI. It is for the user. It is sacred. Everything else—parsing, calculating, searching, filtering—belongs in a worker. With <code>werkbank/rpc</code>, the barrier is gone. The friction is gone. You can treat the worker as just another module. Just another import. Stop blocking the main thread. It's rude. Build the app you want to build, not the one the main thread lets you build. <h2 id="related-post">Related Post</h2> <ul> <li><a href="/blog/typescript-meta-programming-and-proxies/">TypeScript Meta-programming and Proxies</a></li> </ul> <h2 id="getting-started">Getting Started</h2> <ul> <li><a rel="external" href="https://docs.werkbank.dev/documents/Getting_Started.html">Getting Started</a></li> <li><a rel="external" href="https://docs.werkbank.dev/documents/Getting_Started.Worker_RPC.html">Worker RPC Guide</a></li> </ul> <h2 id="disclaimer">Disclaimer</h2> This is a Proof of Concept (PoC). It's running in my personal workspace. It's not on GitHub yet. It's not battle-tested in a million-user app. It's an experiment in "What if?". I plan to open source this properly at a later date, once I've ironed out the kinks and written some actual documentation. But for now, I just wanted to share the idea. Because sometimes, the best way to move forward is to look at what we're doing and ask: "Does it have to be this hard?" Building Custom React Inputs 2026-01-15T00:00:00+0000 https://werkbank.dev/blog/building-custom-react-inputs/ It starts with a design. It always starts with a design. "We need a tag selector," the designer says. "But not a boring select box. We want chips. We want them to animate. We want a little 'x' button on each one." So you build it. You create a <code>div</code>. You map over an array of strings. You add some <code>onClick</code> handlers. It looks beautiful. It's perfect. Then you try to use it in a form. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="tsx">&lt;form onSubmit={handleSubmit}&gt; &lt;ChipsInput /&gt; {/* The Zombie */} &lt;button&gt;Submit&lt;/button&gt; &lt;/form&gt;</code></pre> <ul> <li>You hit enter. Nothing happens.</li> <li>You try to tab to it. You tab right past it.</li> <li>You try to read the <code>FormData</code>. It's empty.</li> </ul> And suddenly, you realize you've built a zombie. It looks like an input, but it's dead inside. It has no soul. It has no <code>value</code>. It has no <code>name</code>. Why are we still doing this? We do it because native inputs are notoriously hard to style. You can't put a chip inside a text input. You can't animate the caret. So we abandon the native element and rebuild the world from scratch with <code>div</code>s. I look at the ecosystem. There are a thousand "React Select" libraries. They all have their own state management. They all have their own <code>onChange</code> signature that returns some custom object instead of an event. They all require you to manually wire them up to your form library. I didn't want a "React Component." I wanted an <code>input</code>. I wanted something that passes the Duck Test. If it walks like a duck, and quacks like a duck, it's a native input. Even if it's actually three raccoons in a trench coat. <h3 id="the-epiphany-the-trojan-horse">The Epiphany: The Trojan Horse</h3> I realized I was fighting the browser. I was trying to re-implement <code>focus</code>, <code>blur</code>, <code>validation</code>, and <code>form submission</code> in JavaScript. Why? The browser already does this. It's been doing it for 30 years. So I stopped fighting. I decided to cheat. I decided to build a Trojan Horse. On the outside, it's a beautiful, animated, interactive React component. But inside? Deep inside the DOM where the user can't see? It's just a boring, standard HTML string. <h3 id="how-it-works-the-chipsinput">How it Works: The ChipsInput</h3> Let's look at the <code>ChipsInput</code>. The goal is to let the user type multiple values, hit enter, and see them appear as "chips." But to the form, this should just be a comma-separated string. So, I hide the truth. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="tsx">// 1. The Hidden Messenger &lt;input aria-hidden style={{ position: &quot;absolute&quot;, opacity: 0, pointerEvents: &quot;none&quot;, width: 0, height: 0, }} ref={hiddenInputRef} name={name} value={currentValues.join(&quot;,&quot;)} // &quot;react,javascript,css&quot; onChange={validationHandlers.onChange} onBlur={validationHandlers.onBlur} required={required} /&gt;</code></pre> This is the soul of the component. It's invisible. It takes up no space. But it holds the <code>name</code>. It holds the <code>value</code>. It holds the <code>required</code> attribute. When the form looks for data, it finds this input. When the browser checks for validity, it checks this input. <h3 id="syncing-the-state-here-be-dragons">Syncing the State: Here Be Dragons</h3> Now we just need to keep the visual state in sync with this hidden truth. When you add a chip, I don't just update React state. I update the DOM. But you can't just set <code>input.value = "foo"</code>. React tracks the input's value internally. If you modify the DOM directly, React's internal state gets out of sync with the DOM, and the next render might wipe out your changes. We have to be sneaky. We have to bypass React's tracker by calling the native value setter from the prototype. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="typescript">let setChange = (values: Array&lt;string&gt;) =&gt; { // inputRef points to the hidden &lt;input&gt; element if (inputRef.current) { let value = values.join(separator); // 2. The Manual Override // We steal the setter from the HTMLInputElement prototype // This allows us to set the value *without* React intercepting it immediately let valueSetter = Object.getOwnPropertyDescriptor( window.HTMLInputElement.prototype, &quot;value&quot; )?.set; // Call the native setter with our DOM node as &#39;this&#39; valueSetter?.call(inputRef.current, value); // 3. The Fake Event // Dispatch a change event so React (and the world) knows the value changed inputRef.current.dispatchEvent(new Event(&quot;change&quot;, { bubbles: true })); // Finally, update our local React state to match setState(values); } };</code></pre> I manually set the value on the DOM node using the prototype. This is crucial because it updates the value without React knowing immediately, but then the <code>change</code> event brings everyone back in sync. This tells the world (and any other listeners) that something happened. The form sees the update. The validation logic runs. <h3 id="the-forgotten-lifecycle-reset">The Forgotten Lifecycle: Reset</h3> There is one event that React developers almost always forget: <code>reset</code>. When you click <code>&lt;button type="reset"&gt;</code>, the browser restores all inputs to their <code>defaultValue</code>. But since our "state" is in React <code>useState</code>, the browser's reset doesn't touch it. The hidden input reverts, but the chips stay on screen. The fix? We listen to the form. But we have to wait. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="typescript">useEffect(() =&gt; { let form = wrapper.current.closest(&quot;form&quot;); if (!form) return; let handleReset = () =&gt; { // Wait for the browser to finish its reset requestAnimationFrame(() =&gt; { setState(getValues(defaultValue)); }); }; form.addEventListener(&quot;reset&quot;, handleReset); return () =&gt; form.removeEventListener(&quot;reset&quot;, handleReset); }, [defaultValue]);</code></pre> Why <code>requestAnimationFrame</code>? Because the <code>reset</code> event fires before the browser actually clears the inputs. If we read the value immediately, we'd get the old value. We have to let the browser finish its work, tick the frame, and then sync our React state to the new reality. (You could use <code>setTimeout(..., 0)</code> here too, but <code>rAF</code> is generally cleaner for visual updates). <h3 id="the-focus-relay-formerly-faking-the-focus">The Focus Relay (formerly "Faking the Focus")</h3> The hardest part isn't the data. It's the feel. A native input is a single focusable element. My component is a list of chips, a delete button for each chip, and a text input for adding new ones. If I tab from a chip to the delete button, have I "blurred" the field? Technically, yes. The focus left the container. But to the user? No. They are still "in" the input. So we have to fake it. We have to simulate the focus cycle. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="typescript">let handleInputBlur: FocusEventHandler&lt;HTMLInputElement&gt; = (e) =&gt; { // ... logic to check if we moved to another element inside the same wrapper ... setInputFocus(false); simulateFocusCycle(inputRef.current); };</code></pre> We wait. We check <code>document.activeElement</code>. If the focus just moved to a neighbor, we do nothing. If it truly left the component, then we fire the <code>onBlur</code> event. But we don't just fire a React handler. We go deeper. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="typescript">export function simulateFocusCycle(elm: ValidateElement | null) { if (elm) { elm.dispatchEvent(new Event(&quot;focusin&quot;, { bubbles: true })); elm.dispatchEvent(new Event(&quot;focusout&quot;, { bubbles: true })); } }</code></pre> We manually dispatch <code>focusin</code> and <code>focusout</code> events on the hidden input. Why? Because validation libraries (and our own code) often listen for these specific events to mark a field as "touched" or to trigger error messages. By manually firing them, we ensure that any external code watching our component sees a valid focus lifecycle, even though the user never actually touched that hidden input. <h3 id="the-elephant-in-the-room-accessibility">The Elephant in the Room: Accessibility</h3> "But wait," I hear you say. "You have an invisible input with <code>aria-hidden</code>. If validation fails, the browser focuses that input. Won't the user be lost?" Yes. That is the danger. If the browser focuses an <code>opacity: 0</code> element, the user's focus ring disappears. They are tabbed into the void. To fix this, we have to listen for the <code>invalid</code> event on the hidden input and manually shift focus back to our visible input. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="typescript">hiddenInput.addEventListener(&#39;invalid&#39;, (e) =&gt; { e.preventDefault(); // Stop the native browser bubble if it&#39;s confusing visibleInputRef.current?.focus(); // Show our custom error UI });</code></pre> It's a trade-off. We get the native form behavior, but we have to manage the edge cases where the "native" behavior (focusing the invalid field) conflicts with our "custom" reality (the field is invisible). I chose <code>aria-hidden</code> intentionally. The hidden input is for data, not for humans. The screen reader should interact with the list of chips and the text input, not the comma-separated string in the background. If we didn't hide it, the screen reader would announce the field twice: once for the custom UI, and once for the hidden value. <h3 id="advanced-moves-the-dateinput">Advanced Moves: The DateInput</h3> This pattern scales. Take a Date Input. Designers love splitting dates: Day, Month, Year. Browsers love ISO strings: <code>YYYY-MM-DD</code>. So we do the same trick, but with a coordinator. We render three visible inputs and one invisible master. But how do they talk to each other? We use React Context to create a mini-state machine. <ol> <li>The Coordinator (<code>DateInput</code>): This component holds the single source of truth—the ISO string. It parses this string into <code>day</code>, <code>month</code>, and <code>year</code> integers and exposes them via a Context Provider.</li> <li>The Players (<code>Day</code>, <code>Month</code>, <code>Year</code>): These are dumb components. They don't know about the ISO string. They just consume the Context. <ul> <li><code>&lt;Day /&gt;</code> reads <code>ctx.day</code> and calls <code>ctx.setDay(12)</code>.</li> <li><code>&lt;MonthSelect /&gt;</code> reads <code>ctx.month</code> and calls <code>ctx.setMonth(1)</code>.</li> </ul> </li> <li>The Sync: When you change the Day, the <code>DateInput</code> intercepts the update. <ul> <li>It takes the new Day.</li> <li>It combines it with the existing Month and Year.</li> <li>It constructs a new ISO string: <code>2024-02-12</code>.</li> <li>It updates the hidden <code>&lt;input type="date" /&gt;</code>.</li> <li>It dispatches the <code>change</code> event.</li> </ul> </li> </ol> But what about February 31st? This is where the browser saves us again. If I manually construct the string <code>2024-02-31</code> and set it on the hidden input, the browser's native validation kicks in. <code>&lt;input type="date"&gt;</code> knows that February 31st doesn't exist. It marks the field as invalid. I don't have to write leap year logic. I don't have to import <code>date-fns</code> just to check if a day is valid. I just pass the string to the browser, and if the browser rejects it, my CSS <code>:user-invalid</code> styles light up. <h3 id="the-mobile-bonus">The Mobile Bonus</h3> There is one more huge benefit to this approach, specifically for the <code>DateInput</code>. If you use a custom JavaScript date picker, you are forcing mobile users to tap tiny little <code>&lt;div&gt;</code>s on a tiny calendar. It's miserable. But because we are using <code>&lt;input type="date"&gt;</code> under the hood, we can choose to expose that to mobile users. <ul> <li>On desktop, we show our fancy split inputs.</li> <li>On mobile, we can show the native date picker.</li> </ul> Because the data format is standard (ISO string), we can swap the UI without changing the logic. The browser handles the complex touch interactions, the scrolling pickers, and the localization. We just handle the value. <h3 id="the-payoff-styling-with-has">The Payoff: Styling with :has()</h3> I mentioned getting CSS powers for free. This is where it gets fun. Because our hidden input is inside our wrapper, and because it receives the browser's native validation state (<code>:invalid</code>, <code>:user-invalid</code>), we can style our entire custom component based on the hidden input's health. No more passing <code>isError</code> props down three levels. No more <code>className={cx(styles.input, error &amp;&amp; styles.error)}</code>. Just pure CSS: <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="css">/* When the hidden input is invalid... */ .wrapper:has(input:user-invalid) { border-color: red; animation: shake 0.2s; } /* When the hidden input is required but empty... */ .wrapper:has(input:placeholder-shown:required) .label::after { content: &quot;*&quot;; color: red; }</code></pre> We are letting the browser manage the state of the UI. The React component just renders the structure; the CSS reacts to the truth of the DOM. (Note: <code>:has()</code> is now supported in all major browsers as of late 2023). <h3 id="conclusion">Conclusion</h3> I stopped trying to build "Form Components." I started building "Input Wrappers." It sounds like a semantic difference, but it changed everything. By respecting the native <code>&lt;input&gt;</code> as the source of truth, I got so much for free. <ul> <li>I got <code>FormData</code> support.</li> <li>I got native validation.</li> <li>I got Server Action compatibility.</li> <li>I got CSS selectors like <code>:has(:user-invalid)</code> to style my custom UI when the hidden input is unhappy.</li> </ul> It’s a bit of a magic trick. It’s a bit of a lie. But if it submits like an input, validates like an input, and focuses like an input... It’s an input. Don't build zombies. Build inputs. The Invisible Work of a Focus Trap 2026-01-15T00:00:00+0000 https://werkbank.dev/blog/invisible-work-focus-trap/ You don't notice it when it works. You only notice it when it breaks. You open a modal. You hit Tab. The focus moves to the "Cancel" button. You hit Tab again. It moves to "Confirm". You hit Tab again. And suddenly you are in the URL bar. Or worse, you are highlighting some random link in the footer behind the gray overlay. The illusion is broken. You aren't in a "dialog" anymore. You are just looking at a <code>div</code> with a high z-index. <h3 id="the-problem">The Problem</h3> Building a Focus Trap sounds easy. "Just listen for the Tab key," you say. "If they are on the last element, move them to the first." I tried that. It works for about 5 minutes. Then you realize: <ol> <li>What if the user Shift+Tabs (goes backwards)?</li> <li>What if the user clicks outside the modal?</li> <li>What if the DOM changes and the "last element" isn't the last element anymore?</li> <li>What if the first element is disabled?</li> <li>What if there is an iframe? (The black hole of focus).</li> </ol> It turns into a nightmare of edge cases. <h3 id="the-rxjs-solution">The RxJS Solution</h3> In Werkbank, I use <code>useFocusTrap</code>. And yes, I use RxJS. "Why not just use <code>react-focus-lock</code>?" It's a great library. But I want to reduce the number of dependencies and I wanted full control over the behavior. I wanted to integrate it with our other hooks like <code>useOnEscape</code> and <code>useOutsideClick</code>. "Why not just use the <code>inert</code> attribute?" <code>inert</code> is amazing. It lets you disable the entire document except your modal. But to use it, you have to find all the siblings of your modal (and your modal's parents' siblings) and mark them as inert. You have to walk the DOM tree up and down. It's expensive. Trapping focus is often cheaper than excluding everything else. "Why not use the native <code>&lt;dialog&gt;</code> element?" You should! <code>&lt;dialog&gt;</code> is fantastic. It handles focus trapping natively when you call <code>.showModal()</code>. But sometimes you need a custom implementation. Maybe you need a specific animation that <code>&lt;dialog&gt;</code> makes hard. Maybe you are building a complex panel system that isn't quite a dialog. When you do need to roll your own, you need <code>useFocusTrap</code>. It's not just for modals. In a complex, multi-panel layout (like the one you can build with <code>werkbank/component/grid</code>), you might want to "trap" focus inside the active panel. If I'm editing code in the left pane, pressing Tab shouldn't jump me to the terminal in the bottom pane. It should indent my code. Focus management is about context, not just blocking the user. Why RxJS? Because focus is a stream. It's not just about trapping the key. It's about trapping the event. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="typescript">useEffect(() =&gt; { let subscription = focusin$ .pipe( filter((target) =&gt; !currentDialog.contains(target)) ) .subscribe((target) =&gt; { // Shadow DOM support? Use composedPath() here. // You tried to leave? Nice try. focusFirstDescendant(currentDialog); }); return () =&gt; subscription.unsubscribe(); }, [currentDialog]);</code></pre> We listen to <code>focusin</code> globally. If the focus lands anywhere outside our trap, we yank it back. Immediately. And because it's RxJS, cleanup is trivial. When the component unmounts, we unsubscribe. No dangling listeners. No memory leaks. This handles the "click outside" case. It handles the "programmatic focus" case. It handles the "screen reader navigation" case. A Note on Accessibility: Yanking focus is aggressive. It can be confusing. That's why your modal must have <code>role="dialog"</code> and <code>aria-modal="true"</code>. This tells the screen reader, "Hey, I'm a modal, I'm trapping you on purpose." Our JS is just the enforcement mechanism for browsers that don't fully respect that contract yet. <h3 id="the-algorithm">The Algorithm</h3> But where do we yank it back to? We need to find the "First Descendant". But not just the first child. The first focusable child. And "focusable" is a messy concept in HTML. <ul> <li>Is it an <code>&lt;a&gt;</code> tag? Only if it has an <code>href</code>.</li> <li>Is it a <code>&lt;button&gt;</code>? Only if it's not <code>disabled</code>.</li> <li>Is it hidden? <code>aria-hidden</code>? <code>display: none</code>?</li> <li>Does it have <code>tabindex="-1"</code>?</li> </ul> We have to traverse the tree. We have to check attributes. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="typescript">function getFocusable(element: HTMLElement) { let focusable = element.querySelectorAll( &#39;a[href], button, input, textarea, ...&#39; ); // ... filter out disabled and hidden ... }</code></pre> "Wait, isn't <code>querySelectorAll</code> slow?" Yes, if you run it on every keypress. But we don't. We run it lazily, and we can use <code>MutationObserver</code> (another hook!) to invalidate the cache if the DOM changes. <h3 id="why-it-matters">Why It Matters</h3> This is the kind of code that nobody wants to write. It's unglamorous. It's "plumbing". It has zero visual impact. But it's the difference between a "React Component" and a "User Interface Element". A native OS dialog traps focus. A native OS menu manages arrow keys. If we want the web to feel like an app, we have to respect these rules. We can't just slap a <code>position: fixed</code> on a div and call it a day. We are talking about Modal dialogs here. Modeless dialogs (like a find bar) shouldn't trap focus. But if you block the UI with an overlay, you must block the focus too. We have to do the invisible work. Type-Safe Routing Without the Build Step 2026-01-14T00:00:00+0000 https://werkbank.dev/blog/schema-first-router/ It always starts with a string. <code>const { id } = useParams()</code>. And right there, I'm already annoyed. What is <code>id</code>? It's a string. But my database says it's a number. So now I have to parse it. <code>parseInt(id, 10)</code>. But wait, what if it's undefined? What if the user typed "banana" into the URL bar? Now I'm writing <code>isNaN</code> checks inside my component. I'm doing validation logic inside my view layer. Again. Why are we still doing this in 2026? I look around at the ecosystem and everything is... loud. Everyone is shouting about Server Side Rendering. Hydration. Edge functions. File-based routing where the file system is the API. And I get it, I do, SEO is important, performance is key. But sometimes I just want to build an app. A real, rich, thick-client Single Page App. I don't want a server process watching my files. I don't want a build step that generates a 5,000 line <code>routes.d.ts</code> file that I have to gitignore (or worse, commit). I just want TypeScript to know what my URL is. I remember looking at <a rel="external" href="https://www.servant.dev/">Servant</a>. It's this Haskell web framework that treats APIs differently. In Servant, you don't write a route handler and then hope it matches the URL. You define the API as a Type. The type is the spec. The implementation is just a function that has to satisfy that type. If you change the type, the compiler screams at you until you fix the implementation. In Servant, that same route looks like this: <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="haskell">type UserAPI = &quot;users&quot; :&gt; Capture &quot;userId&quot; Int :&gt; &quot;posts&quot; :&gt; Capture &quot;postId&quot; String :&gt; Get &#39;[JSON] Post</code></pre> It was beautiful. It was strict. It was... correct. It inspired me to ask: Why can't I have that in React? So I started hacking. I didn't want "paths" like <code>/users/:id</code>. That's just a string with a colon in it. It's weak. I wanted a schema. I wanted to say: "This route consists of the static segment 'users', followed by a Number, followed by 'posts', followed by a String." I wanted this: <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="typescript">path: [&quot;users&quot;, number(), &quot;posts&quot;, string()]</code></pre> That's not a string. That's a tuple. That's data. And because it's data, I can infer things from it. <h3 id="the-magic-type-inference-without-codegen">The "Magic": Type Inference Without Codegen</h3> But how do you get TypeScript to understand that <code>number()</code> in the array means the prop passed to your component should be a <code>number</code>? This is where I went down the rabbit hole. Recursive types. I spent nights staring at <code>infer</code> keywords until my eyes blurred. I wanted to avoid code generation at all costs. I wanted the IDE to just know. I ended up with something like this. It looks scary, but it's actually kind of elegant if you squint: <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="typescript">type Params&lt;Arr, Acc extends Array&lt;any&gt; = []&gt; = Arr extends readonly [ infer Head, ...infer Tail, ] ? Head extends BaseSchema&lt;any, any, any&gt; ? Params&lt;Tail, [...Acc, InferOutput&lt;Head&gt;]&gt; : Params&lt;Tail, Acc&gt; : Acc;</code></pre> It walks the array. Is this item a Schema? Yes? Extract its type. No? Ignore it. And suddenly, it worked. I could hover over <code>props.params</code> in my component and see <code>[number, string]</code>. No <code>any</code>. No <code>string | undefined</code>. Just the raw, validated types. It felt like magic, but it wasn't. It was just inference. The best part? It's basically OpenAPI for your internal routes. You define the contract first. "This page requires a number." The router enforces it. If the URL doesn't match the schema (like if someone types <code>/users/banana</code>), the router doesn't even try to render the component. It blocks it at the door. My components became pure. They didn't have to worry about parsing or validation anymore. They just received data. I know, I know. "Another router?" But this one feels different. It feels like what we should have had all along if we hadn't gotten so distracted by making the server do everything. It treats the URL as a source of truth, not just a string of characters. I built this because I was tired of guessing. I was tired of <code>as string</code>. I was tired of runtime errors that should have been compile-time errors. I built it because I wanted to trust my code again. <h2 id="how-it-works">How it works</h2> So, how do you actually use this thing? It's a two-step process: define the schema, then implement the router. First, you define your routes. This is your contract. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="typescript">import * as v from &quot;valibot&quot;; // 1. Define your custom types // The router works with ANY Valibot schema. // Want a number from the URL? Transform the string. let Num = v.pipe( v.string(), v.transform((input) =&gt; Number.parseInt(input, 10)), ); // Want a UUID? Validate it. let Uuid = v.pipe(v.string(), v.uuid()); // 2. Define your routes let todoConfig = { app: { path: [&quot;/&quot;], children: { home: [&quot;home&quot;], // A route with search params for filtering todos: { path: [&quot;todos&quot;], searchParams: v.object({ filter: v.optional(v.enum([&quot;active&quot;, &quot;completed&quot;])), }), }, // A route with a UUID path parameter todo: [&quot;todo/&quot;, Uuid], // A route with a Number path parameter (e.g. /archive/2023) archive: [&quot;archive/&quot;, Num], }, }, } as const;</code></pre> Then, you create the router. This is where the magic happens. The <code>createRouter</code> function takes your config and forces you to provide components that match the schema. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="tsx">import { createRouter } from &quot;werkbank/router&quot;; let routerConfig = createRouter(todoConfig, { app: { // The parent component receives &#39;children&#39; - this is your Outlet! component: ({ children }) =&gt; &lt;main&gt;{children}&lt;/main&gt;, children: { home: { component: () =&gt; &lt;div&gt;Home&lt;/div&gt;, }, todos: { // Supports Code Splitting! // Just pass a dynamic import as &#39;preload&#39; and a Lazy component component: React.lazy(() =&gt; import(&quot;./TodosList&quot;)), preload: () =&gt; import(&quot;./TodosList&quot;), }, todo: { // params is inferred as [string] automatically! component: ({ params }) =&gt; { return &lt;h1&gt;Todo: {params[0]}&lt;/h1&gt;; }, }, archive: { // params is inferred as [number] automatically! component: ({ params }) =&gt; { return &lt;h1&gt;Archive Year: {params[0]}&lt;/h1&gt;; }, }, }, }, });</code></pre> A Note on Tuples vs. Named Parameters: You might notice <code>params[0]</code>. "Wait, I have to access params by index? That's fragile!" Actually, it's the opposite. It's robust. By using tuples, we get instant, zero-config type inference without a build step. If I were to swap the order in the schema—putting the string before the number—TypeScript would immediately flag every usage of <code>params[0]</code> in my component. It would say: "Type 'string' is not assignable to type 'number'". It's strict, but it's safe. It forces you to respect the order of data as defined in your source of truth. And finally, you render it: <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="tsx">import { Router } from &quot;werkbank/router&quot;; function App() { return &lt;Router config={routerConfig} /&gt;; }</code></pre> Links are also type-safe. You can't link to a route that doesn't exist, and you can't forget a parameter. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="tsx">import { createLinks } from &quot;werkbank/router&quot;; let links = createLinks(todoConfig); // This works &lt;Link href={links.app().todos({ searchParams: { filter: &quot;active&quot; } })}&gt;Active Todos&lt;/Link&gt; // This works (Type-safe UUID!) &lt;Link href={links.app().todo({ params: [&quot;550e8400-e29b-41d4-a716-446655440000&quot;] })}&gt;View Todo&lt;/Link&gt; // This errors at compile time! (Missing params) &lt;Link href={links.app().todo()}&gt;View Todo&lt;/Link&gt;</code></pre><h3 id="is-the-verbosity-worth-it">Is the verbosity worth it?</h3> I hear you. <code>&lt;Link href={links.app().todo(...)}&gt;</code> is longer than <code>&lt;Link to="/todo/123"&gt;</code>. But ask yourself: how many times have you broken a link because you renamed a route? Or forgot a required query parameter? With this approach, a route rename is a simple "Rename Symbol" in your IDE. Every link updates automatically. The verbosity buys you confidence. <h2 id="getting-started">Getting Started</h2> <ul> <li><a rel="external" href="https://docs.werkbank.dev/documents/Getting_Started.html">Getting Started</a></li> <li><a rel="external" href="https://docs.werkbank.dev/documents/Getting_Started.Router.html">Router Guide</a></li> </ul> <h2 id="disclaimer">Disclaimer</h2> This is a Proof of Concept (PoC). It's running in my personal workspace. It's not on GitHub yet. It's not battle-tested in a million-user app. It's an experiment in "What if?". I plan to open source this properly at a later date, once I've ironed out the kinks and written some actual documentation. But for now, I just wanted to share the idea. Because sometimes, the best way to move forward is to look at what we're doing and ask: "Does it have to be this hard?" Type-Safe React Forms 2026-01-14T00:00:00+0000 https://werkbank.dev/blog/type-safe-react-forms/ It starts with a schema. It always starts with a schema. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="typescript">// Define the rule once const password = string([minLength(8)])</code></pre> I define my validation rule: "Password must be at least 8 characters." Simple enough. Then I switch context to my component. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="tsx">&lt;input type=&quot;password&quot; /&gt;</code></pre> And I pause. I look at the schema. I look at the input. And I sigh. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="tsx">&lt;input type=&quot;password&quot; minLength={8} /&gt;</code></pre> I have to type it again. I have to manually tell the browser what I just told my validator. And right there, the drift begins. Two weeks later, security comes in. "Passwords need to be 10 characters now." I update the schema. <code>minLength(10)</code>. I push the code. And then I get a bug report. "The error message says 10 characters, but the browser let me submit 8." I forgot the input. Of course I forgot the input. Why wouldn't I? It's a completely separate file, a completely separate line of code, disconnected from the source of truth. Why are we still doing this? I look at <code>react-hook-form</code>. It's great. It's powerful. But it feels... manual. <code>register("password", { minLength: 8 })</code>. I'm still defining the rules in the UI layer. I'm still shifting gears manually. I wanted something else. I wanted an Orchestrator. <h3 id="the-idea">The Idea</h3> What if the schema wasn't just a gatekeeper? What if it was the blueprint? I didn't want to write validation logic and UI logic. I wanted to write the definition of the data, and have the UI just... happen. <ul> <li>If I say <code>string([email()])</code>, the input should know it's <code>type="email"</code>.</li> <li>If I say <code>number()</code>, the input should be <code>type="number"</code>.</li> <li>If I say <code>minLength(8)</code>, the input should have <code>minLength={8}</code>.</li> </ul> I wanted to define the rules once, in Valibot, and have them ripple through the entire application. <h3 id="the-solution-the-schema-as-the-orchestrator">The Solution: The Schema as the Orchestrator</h3> So I built it. A form library where the schema drives the UI. It looks like this: <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="tsx">import * as v from &quot;valibot&quot;; import { Form, useFormFields, type SubmitHandler } from &quot;werkbank/component/form&quot;; // 1. Define the Single Source of Truth const LoginSchema = v.object({ email: v.pipe(v.string(), v.email()), password: v.pipe(v.string(), v.minLength(8)), }); function LoginForm() { // 2. Let the Orchestrator do the work // The schema acts as the conductor, determining props for every field. const formFields = useFormFields(LoginSchema); // 3. Typed Submit Handler // &#39;payload&#39; is inferred as { email: string; password: string } const handleSubmit: SubmitHandler&lt;typeof LoginSchema&gt; = (payload) =&gt; { console.log(&quot;Login with:&quot;, payload.email); }; return ( &lt;Form schema={LoginSchema} onSubmit={handleSubmit}&gt; &lt;label htmlFor={formFields.email.id}&gt;Email&lt;/label&gt; {/* 4. Spread the props. That&#39;s it. */} {/* This input now has type=&quot;email&quot;, required, and id */} &lt;input {...formFields.email} /&gt; &lt;label htmlFor={formFields.password.id}&gt;Password&lt;/label&gt; {/* This input now has minLength={8}, required, and id */} &lt;input {...formFields.password} type=&quot;password&quot; /&gt; &lt;button type=&quot;submit&quot;&gt;Login&lt;/button&gt; &lt;/Form&gt; ); }</code></pre> Do you see what happened there? <ul> <li><code>formFields.email</code> isn't just <code>name="email"</code>. It's <code>type="email"</code>. It's <code>required</code>.</li> <li><code>formFields.password</code> has <code>minLength={8}</code>.</li> </ul> If I change the schema to <code>minLength(10)</code>, the input updates. Automatically. No drift. No "double maintenance." <h3 id="why-not-just-use-the-dom">Why Not Just Use the DOM?</h3> I hear the web purists. "Just use <code>FormData</code>! The DOM is the ultimate source of truth!" And they have a point. The DOM is excellent at holding state. But the DOM is terrible at types. To the DOM, everything is a string. <ul> <li>"123" is a string.</li> <li>"true" is a string.</li> <li>"2023-01-01" is a string.</li> </ul> If I rely solely on the DOM, I'm back to parsing strings manually in my submit handler. <code>parseInt(data.get('age'))</code>. <code>data.get('isAdmin') === 'on'</code>. This is where "Schema-First" shines. The schema bridges the gap. It tells the DOM how to behave (attributes), but it also tells the code how to interpret the result (parsing). When <code>werkbank</code> hands you the data in <code>onSubmit</code>, it's not a bag of strings. It's numbers. It's booleans. It's Dates. It's real, typed data. The schema handles the transformation layer so you don't have to. <h3 id="performance-the-uncontrolled-advantage">Performance: The Uncontrolled Advantage</h3> "But does this re-render my whole app on every keystroke?" No. This is an uncontrolled form library. We are not binding <code>value</code> and <code>onChange</code> to React state for every character you type. The <code>useFormFields</code> hook uses <code>useMemo</code> to compute the attributes once (memoized based on the schema). The returned object is stable. When you type in the input, React stays out of the way. The browser handles the update. We only touch React state when: <ol> <li>You submit the form.</li> <li>A validation error occurs (and we need to show UI).</li> </ol> This means you can have a form with 500 inputs, and typing in the 500th one feels just as fast as typing in the first. Zero lag. Zero unnecessary re-renders. <h3 id="it-goes-deeper-enums-and-automatic-ui">It Goes Deeper: Enums and Automatic UI</h3> But why stop at simple attributes? What about the annoying stuff? Selects. Radio groups. Defining a dropdown in React is usually a chore. You have to map over options, manage keys, handle values. But if I have an Enum in my schema, I already know what the options are. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="typescript">const MonsterEnum = { Kraken: &quot;K&quot;, Sasquatch: &quot;S&quot;, Mothman: &quot;M&quot;, // ... }; const schema = object({ monster: v.enum(MonsterEnum), });</code></pre> The library sees this. It knows it's an Enum. So <code>useFormFields</code> gives me everything I need to render a radio group or a select, without me typing the options again. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="tsx">const fields = useFormFields(schema); // It gives me the options array automatically! &lt;select {...fields.monster.select}&gt; {fields.monster.options.map(opt =&gt; ( &lt;option key={opt.name} value={opt.value}&gt;{opt.name}&lt;/option&gt; ))} &lt;/select&gt;</code></pre> When you submit the form, <code>werkbank</code> just reads the hidden input. It doesn't care about your fancy UI. It just cares about the data. This avoids the fragile dance of syncing React state back to the DOM manually. We let the DOM hold the state, even for custom components. <h3 id="what-about-dynamic-forms">What about Dynamic Forms?</h3> "This is cool for static forms," you say. "But I have a list of users that I can add and remove. I need <code>useFieldArray</code>." Dynamic forms are where many libraries fall apart. They force you into complex state management just to add a row. Because we rely on the DOM structure, handling arrays is surprisingly simple. You just render the inputs. If your schema expects an array of strings, you just render inputs with the same <code>name</code>. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="tsx">// Schema: emails: array(string([email()])) // DOM: &lt;input name=&quot;emails&quot; type=&quot;email&quot; /&gt; &lt;input name=&quot;emails&quot; type=&quot;email&quot; /&gt;</code></pre> When you submit, <code>werkbank</code> sees multiple inputs with the name "emails", collects them into an array, and validates them against the array schema. Since the DOM order is the array order, reordering items is just reordering the rendered components. You don't need a complex <code>append</code> or <code>remove</code> API. You just render React components. If you want to add a row? Just update your local state to render another <code>&lt;input&gt;</code>. The form library doesn't care how the inputs got there, only that they exist when you hit submit. <h3 id="bring-your-own-components">Bring Your Own Components</h3> "But I have my own component library!" I hear you. You don't want to rewrite your <code>FancyInput</code>. You just want it to validate. That's where <code>useInputValidation</code> comes in. It's the low-level hook that powers everything else. It connects any component to the Form Context. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="tsx">import { useInputValidation } from &quot;werkbank/hook/useInputValidation&quot;; function MyFancyInput({ name, ...props }) { // Hooks into the parent &lt;Form&gt;, finds the schema for &#39;name&#39;, // and gives you validation handlers. const { onChange, onBlur, validate } = useInputValidation({ name }); return ( &lt;div className=&quot;fancy-wrapper&quot;&gt; &lt;input name={name} onChange={onChange} onBlur={onBlur} {...props} /&gt; &lt;/div&gt; ); }</code></pre> Now <code>MyFancyInput</code> participates in the form lifecycle. It validates on blur. It validates on submit. It reports errors. And you didn't have to write a single <code>setState</code>. And because we spread <code>...props</code> last, you can still override anything manually if you have a weird edge case. <h3 id="closer-to-the-platform-but-not-too-close">Closer to the Platform (But Not Too Close)</h3> The best part? This isn't re-inventing validation. It's using the platform. We extract these attributes so we can leverage the browser's built-in <a rel="external" href="https://developer.mozilla.org/en-US/docs/Web/HTML/Guides/Constraint_validation">Constraint Validation API</a>. When you click submit, we don't run a heavy JS validation suite immediately. We let the browser check the <code>type="email"</code>. We let the browser check the <code>minLength</code>. We get the red outlines and the tooltips for free. We also get the correct mobile keyboards (email, numeric) for free, just by using the right standard attributes. "But wait," I hear you say. "Native validation UI is ugly and inconsistent." You're right. The default browser bubbles are terrible. That's why we use the API (<code>reportValidity</code>, <code>setCustomValidity</code>) for the logic, but you can still render your own UI. The library exposes <code>onSchemaIssues</code> and <code>onValidationError</code> so you can suppress the default bubbles and show your own beautiful, accessible error messages. We use the browser as the engine, not necessarily the paint. <h3 id="accessibility-is-not-optional">Accessibility is Not Optional</h3> One thing that often gets lost in "magic" form libraries is accessibility. When an error happens, does the screen reader know? Because <code>useFormFields</code> generates unique IDs for every field, we can automatically link inputs to their error messages. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="tsx">// The hook provides the IDs you need for ARIA &lt;input {...formFields.email} aria-describedby={`${formFields.email.id}-error`} aria-invalid={!!errors.email} /&gt; &lt;span id={`${formFields.email.id}-error`}&gt;{errors.email}&lt;/span&gt;</code></pre> We also handle focus management. When validation fails on submit, we automatically focus the first invalid field, ensuring keyboard users aren't left stranded. It feels native. It feels fast. It feels like we're working with the browser, not fighting it. <h3 id="internationalization-i18n">Internationalization (i18n)</h3> "What about translations? My users don't all speak English." Because we're just using Valibot, we can use any i18n solution you like. You just pass the translated string (or a function) to the schema. <pre class="giallo" style="color: #C6D0F5; background-color: #303446;"><code data-lang="typescript">import { t } from &quot;./i18n&quot;; const schema = object({ password: pipe( string(), minLength(8, () =&gt; t(&quot;errors.passwordTooShort&quot;)) ), });</code></pre> The schema is just code. It runs at runtime. So your error messages are always up to date with the user's locale. <h3 id="why-valibot">Why Valibot?</h3> "Why not Zod?" you ask. "Zod is the standard." I love Zod. But we're already using Valibot for our <a href="/blog/schema-first-router/">Schema-First Router</a>. It's tiny. It's modular. And most importantly, for a library that might end up in a client-side bundle, every kilobyte counts. Valibot's modular design means you only bundle what you use. For many forms, the validation logic adds less than 1kb to your bundle. While we built this implementation for Valibot to get that tight integration, the pattern—Schema as Source of Truth—works with Zod, ArkType, or any other schema library. We just chose the lightest one. <h3 id="related-work">Related Work</h3> We didn't build this in a vacuum. We looked at the landscape and learned from the best. <ul> <li>Formik: The pioneer. It taught us how to handle form state in React.</li> <li>react-hook-form: The gold standard. We love it. But it's imperative. You <code>register</code> fields. We wanted to be declarative: you <code>define</code> schemas.</li> <li>remix-validated-form: Very similar philosophy! But tied to Remix. We wanted something that works in any React app (SPA or SSR).</li> <li>auto-form / uniforms: These libraries generate the entire UI for you. We don't. We generate the props. You still own the render. You still write the JSX. We just fill in the blanks.</li> </ul> <h2 id="getting-started">Getting Started</h2> <ul> <li><a rel="external" href="https://docs.werkbank.dev/documents/Getting_Started.html">Getting Started</a></li> <li><a rel="external" href="https://docs.werkbank.dev/documents/Getting_Started.Form.html">Form Guide</a></li> </ul> <h2 id="related-post">Related Post</h2> <ul> <li><a href="/blog/building-custom-react-inputs/">Building Custom React Inputs</a></li> </ul> <h3 id="conclusion">Conclusion</h3> I deleted so much code. I deleted manual <code>minLength</code> props. I deleted manual <code>pattern</code> regexes that were copied from StackOverflow. I deleted <code>type="number"</code> declarations. I just write the schema. And the form follows. The Orchestrator has done its job. It joins the Router in our suite of schema-first tools. A world where the "Type" isn't just a static check—it's the engine that drives the application. It’s not for everyone. If you love writing boilerplate, you’ll hate this. But if you want to trust your forms again? Stop syncing state. Start defining truth.