Merge pull request #46 from bombshell-dev/proper-example-folder

move to examples folder with readme

Author: jbolda

README.md

@@ -21,7 +21,7 @@ computation.
 will run anywhere JavaScript runs with no native dependencies, and no build step
 for consumers.
 
-### Demo
+### Examples
 
 The application in this demo uses Clayterm for all layout and input parsing
 
@@ -30,14 +30,14 @@ The application in this demo uses Clayterm for all layout and input parsing
 The input parser decodes raw terminal bytes into structured events. Here you can
 see each key event as the string "hello world" is typed.
 
-![Keyboard events demo](demo/keyboard-key-events.gif)
+![Keyboard events demo](examples/keyboard/keyboard-key-events.gif)
 
 #### Pointer Events
 
 Here we see hover styles applied to UI elements in response to the pointer
 state. Clay drives the hit testing; no manual coordinate math required.
 
-![Pointer events demo](demo/keyboard-pointer-events.gif)
+![Pointer events demo](examples/keyboard/keyboard-pointer-events.gif)
 
 ## Architecture
 

deno.json

@@ -7,7 +7,6 @@
     "fmt:check": "deno fmt --check && clang-format --dry-run --Werror src/*.c src/*.h",
     "build:npm": "deno run -A tasks/build-npm.ts",
     "build:jsr": "deno run -A tasks/build-jsr.ts",
-    "demo": "deno run demo/keyboard.ts",
     "bench": "deno run -A bench/mod.ts"
   },
   "imports": {

examples/README.md

@@ -0,0 +1,63 @@
+# examples
+
+This directory contains runnable example applications that exercise different
+features of libs. If any of these examples are not working, please open an issue
+with information about your terminal, shell, operating system and any other
+information that could be pertinent to reproducing the issue.
+
+> [!NOTE]
+> Run the commands in this document from the repository root.
+
+## Prerequisites
+
+Build the generated WebAssembly bundle before running the examples:
+
+```sh
+make
+```
+
+## Keyboard
+
+Path: `examples/keyboard/index.ts`
+
+Run it with:
+
+```sh
+deno run examples/keyboard/index.ts
+```
+
+What it shows:
+
+- raw keyboard input decoded into structured key events
+- progressive keyboard protocol support
+- pointer tracking and hover/click-driven UI updates
+- terminal mode configuration such as alternate buffer, hidden cursor, and mouse
+  reporting
+
+Related files:
+
+- `examples/keyboard/use-input.ts` wraps the input parser as a stream of decoded
+  events
+- `examples/keyboard/use-stdin.ts` adapts stdin into a byte stream for the demo
+
+## Inline Regions
+
+Path: `examples/inline-regions/index.ts`
+
+Run it with:
+
+```sh
+deno run examples/inline-regions/index.ts
+```
+
+What it shows:
+
+- rendering animated regions into normal terminal scrollback
+- querying cursor position with DSR to place later frames correctly
+- updating a previously allocated region without taking over the whole screen
+- small animated demos including a spinner, a progress bar, and a nyan-cat-style
+  sequence
+
+This example is useful if you want to embed transient or animated UI output into
+a normal command-line workflow instead of switching to a full-screen alternate
+buffer interface.

demo/inline-region.ts examples/inline-regions/index.tsdemo/inline-region.ts renamed to examples/inline-regions/index.ts

@@ -24,9 +24,9 @@ import {
   rgba,
   SHOWCURSOR,
   text,
-} from "../mod.ts";
-import { cursor, settings } from "../settings.ts";
-import { validated } from "../validate.ts";
+} from "../../mod.ts";
+import { cursor, settings } from "../../settings.ts";
+import { validated } from "../../validate.ts";
 
 const encode = (s: string) => new TextEncoder().encode(s);
 const write = (b: Uint8Array) => Deno.stdout.writeSync(b);

demo/keyboard.ts examples/keyboard/index.tsdemo/keyboard.ts renamed to examples/keyboard/index.ts

@@ -21,15 +21,15 @@ import {
   type PointerEvent,
   rgba,
   text,
-} from "../mod.ts";
+} from "../../mod.ts";
 import {
   alternateBuffer,
   cursor,
   mouseTracking,
   progressiveInput,
   type Setting,
   settings,
-} from "../settings.ts";
+} from "../../settings.ts";
 import { useInput } from "./use-input.ts";
 import { useStdin } from "./use-stdin.ts";
 

demo/keyboard-key-events.gif examples/keyboard/keyboard-key-events.gifdemo/keyboard-key-events.gif renamed to examples/keyboard/keyboard-key-events.gif

@@ -11,7 +11,7 @@ import {
   suspend,
   until,
 } from "effection";
-import { createInput, type InputEvent, type InputOptions } from "../mod.ts";
+import { createInput, type InputEvent, type InputOptions } from "../../mod.ts";
 
 function nothing() {
   return suspend() as unknown as Operation<