From 9f77238824ce6924a03bb192eeff3110871da9a9 Mon Sep 17 00:00:00 2001 From: devphilip21 Date: Sat, 10 Jan 2026 00:17:43 +0900 Subject: [PATCH 1/3] docs(docs): simplify quick-start guide and clarify core problem statement - Replace custom table/tab HTML with markdown tables and code blocks - Reframe first problem as "No Abstraction for Event Flow" with clearer explanation - Remove implementation details and focus on essential setup steps - Remove "What's Next" section for streamlined guide --- .../core-concepts/the-problem-solves.mdx | 6 +- .../content/getting-started/quick-start.mdx | 126 ++---------------- .../core-concepts/the-problem-solves.astro | 2 +- .../pages/getting-started/quick-start.astro | 1 - 4 files changed, 18 insertions(+), 117 deletions(-) diff --git a/docs/src/content/core-concepts/the-problem-solves.mdx b/docs/src/content/core-concepts/the-problem-solves.mdx index b04e701..9c1d3f1 100644 --- a/docs/src/content/core-concepts/the-problem-solves.mdx +++ b/docs/src/content/core-concepts/the-problem-solves.mdx @@ -2,9 +2,9 @@ > **Note:** These are the problems Cereb solves. -## 1. Event-Driven Code Becomes Spaghetti +## 1. No Abstraction for Event Flow -Traditional event handlers create scattered logic, shared mutable state, and duplicated code. Consider a multi-input zoom implementation: +DOM events are just callbacks—there's no structure for managing state, expressing dependencies between events, or composing multiple inputs. Consider a multi-input zoom implementation: ```typescript // Before: Scattered handlers, shared state, duplicated logic @@ -39,7 +39,7 @@ box.addEventListener('touchend', () => { /* cleanup */ }); Cereb models events as streams, creating readable and composable pipelines: ```typescript -// After: Clear flow, no shared state, composable +// After: Stream abstraction—composable, stateless, explicit import { keydown, keyheld, wheel } from "cereb"; import { zoom, when, extend, spy } from "cereb/operators"; import { pinch } from "@cereb/pinch"; diff --git a/docs/src/content/getting-started/quick-start.mdx b/docs/src/content/getting-started/quick-start.mdx index 10a5691..7dc15ff 100644 --- a/docs/src/content/getting-started/quick-start.mdx +++ b/docs/src/content/getting-started/quick-start.mdx @@ -7,110 +7,24 @@ Let's build it step by step. Cereb is modular—install only what you need. -
- - - - - - - - - - - - - - - - - - - - - -
PackageDescription
cerebStream generators & operators
@cereb/panPan/drag/swipe gesture
@cereb/pinchPinch/zoom gesture
-
+| Package | Description | +|---------|-------------| +| `cereb` | Native events & operators | +| `@cereb/pan` | Pan/drag/swipe gesture | +| `@cereb/pinch` | Pinch/zoom gesture | +| `@cereb/tap` | Tap gesture | For our pinch example: -
-
- - - -
-
- ```bash - npm install @cereb/pinch - ``` -
-
- ```bash - pnpm add @cereb/pinch - ``` -
-
- ```bash - yarn add @cereb/pinch - ``` -
-
- -## 2. Create a Source Stream +```bash +npm install @cereb/pinch +``` -The core `cereb` package provides stream generators for various input types: - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
GeneratorDescription
singlePointer(element)Unified pointer input (mouse/touch/pen)
multiPointer(element)Multiple simultaneous pointers
keyboard(target)Keyboard events
keydown(target)Keydown only
keyheld(target, options)Key hold state
wheel(element)Scroll wheel
domEvent(target, eventName)Any DOM event
-
- -For basic pointer tracking: +> Gesture packages include `cereb` core as a dependency. -```typescript -import { singlePointer } from "cereb"; - -const stream = singlePointer(element); -``` +## 2. Create a Source Stream -For gestures, use the convenience functions from gesture packages. They set up the required stream pipeline internally: +Import `pinch` and create a stream from your target element: ```typescript import { pinch } from "@cereb/pinch"; @@ -120,22 +34,19 @@ const stream = pinch(element); ## 3. Transform with pipe() -Streams can be transformed by chaining operators with `.pipe()`: +Chain operators to add constraints like scale limits: ```typescript import { zoom } from "cereb/operators"; -import { pinch } from "@cereb/pinch"; const stream = pinch(element).pipe( zoom({ minScale: 0.5, maxScale: 3 }), ); ``` -Operators like `filter`, `offset`, `zoom`, `extend`, and more are available from `cereb/operators`. - ## 4. Subscribe with on() -Nothing happens until you subscribe. Call `.on()` to start receiving signals: +Nothing happens until you subscribe: ```typescript stream.on((signal) => { @@ -147,12 +58,3 @@ stream.on((signal) => { } }); ``` - -To stop listening: - -```typescript -const off = stream.on(handler); - -// later: -off(); -``` diff --git a/docs/src/pages/core-concepts/the-problem-solves.astro b/docs/src/pages/core-concepts/the-problem-solves.astro index 759d30b..98d921e 100644 --- a/docs/src/pages/core-concepts/the-problem-solves.astro +++ b/docs/src/pages/core-concepts/the-problem-solves.astro @@ -3,7 +3,7 @@ import DocsLayout from "@/layouts/docs-layout.astro"; import Content from "@/content/core-concepts/the-problem-solves.mdx"; const headings = [ - { depth: 2, slug: "1-event-driven-code-becomes-spaghetti", text: "1. Event-Driven Code Becomes Spaghetti" }, + { depth: 2, slug: "1-no-abstraction-for-event-flow", text: "1. No Abstraction for Event Flow" }, { depth: 2, slug: "2-lightweight-bundle-size", text: "2. Lightweight Bundle Size" }, { depth: 2, slug: "3-performance--resource-efficiency", text: "3. Performance & Resource Efficiency" }, ]; diff --git a/docs/src/pages/getting-started/quick-start.astro b/docs/src/pages/getting-started/quick-start.astro index 2062d37..99f8b75 100644 --- a/docs/src/pages/getting-started/quick-start.astro +++ b/docs/src/pages/getting-started/quick-start.astro @@ -7,7 +7,6 @@ const headings = [ { depth: 2, slug: "2-create-a-source-stream", text: "2. Create a Source Stream" }, { depth: 2, slug: "3-transform-with-pipe", text: "3. Transform with pipe()" }, { depth: 2, slug: "4-subscribe-with-on", text: "4. Subscribe with on()" }, - { depth: 2, slug: "whats-next", text: "What's Next" }, ]; --- From 3bd0b4661a76bf006b2829db19a3bccab9e50f05 Mon Sep 17 00:00:00 2001 From: devphilip21 Date: Sat, 10 Jan 2026 00:18:48 +0900 Subject: [PATCH 2/3] docs(cereb): update documentation and bump patch version - Add @cereb/tap to package tables in README files - Refine core problem statement to emphasize lack of event abstraction - Fix typo in cereb package description - Bump cereb version to 1.0.1 --- README.md | 3 ++- packages/cereb/README.md | 5 +++-- packages/cereb/package.json | 2 +- 3 files changed, 6 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 9f49d3e..368d45f 100644 --- a/README.md +++ b/README.md @@ -37,6 +37,7 @@ For advanced gestures like pan or pinch, install dedicated packages that build o |---------|-------------| | [@cereb/pan](./packages/pan) | Pan/drag gestures with velocity and direction tracking | | [@cereb/pinch](./packages/pinch) | Pinch-to-zoom with distance and scale calculations | +| [@cereb/tap](./packages/tap) | Tap gesture recognition | ### Pinch example @@ -87,7 +88,7 @@ Transform and compose streams with operators like `filter`, `map`, `merge`, `thr ## The Problems Cereb Solves -- **Spaghetti Event Code** — Scattered handlers, shared mutable state, duplicated logic +- **No Abstraction for Event Flow** — DOM events lack structure for state, dependencies, and composition - **Lightweight Bundle** — ~77% smaller than Hammer.js (1.73 KB gzipped for pan gesture) - **Resource Efficiency** — Event listener reuse, single-responsibility operators diff --git a/packages/cereb/README.md b/packages/cereb/README.md index c85be65..a4b8104 100644 --- a/packages/cereb/README.md +++ b/packages/cereb/README.md @@ -1,6 +1,6 @@ # [Cereb](https://cereb.dev) -**User input handling and orchestration** libray, +**User input handling and orchestration** library, From low-level events (keyboard, wheel, pointer, ...) to high-level gestures (pan, pinch, ...) ```bash @@ -41,6 +41,7 @@ For advanced gestures like pan or pinch, install dedicated packages that build o |---------|-------------| | [@cereb/pan](https://www.npmjs.com/package/@cereb/pan) | Pan/drag gestures with velocity and direction tracking | | [@cereb/pinch](https://www.npmjs.com/package/@cereb/pinch) | Pinch-to-zoom with distance and scale calculations | +| [@cereb/tap](https://www.npmjs.com/package/@cereb/tap) | Tap gesture recognition | ### Pinch example @@ -92,7 +93,7 @@ Transform and compose streams with operators like `filter`, `map`, `merge`, `thr ## The Problems Cereb Solves -- **Spaghetti Event Code** — Scattered handlers, shared mutable state, duplicated logic +- **No Abstraction for Event Flow** — DOM events lack structure for state, dependencies, and composition - **Lightweight Bundle** — ~77% smaller than Hammer.js (1.73 KB gzipped for pan gesture) - **Resource Efficiency** — Event listener reuse, single-responsibility operators diff --git a/packages/cereb/package.json b/packages/cereb/package.json index 323ad09..9ef23b6 100644 --- a/packages/cereb/package.json +++ b/packages/cereb/package.json @@ -1,7 +1,7 @@ { "name": "cereb", "description": "User input modeling and orchestration with a lightweight reactive stream library.", - "version": "1.0.0", + "version": "1.0.1", "license": "MIT", "author": "devphilip21 ", "repository": { From 97cf0457023440c169681cfd08885859df83dc85 Mon Sep 17 00:00:00 2001 From: devphilip21 Date: Sat, 10 Jan 2026 00:22:25 +0900 Subject: [PATCH 3/3] docs(cereb): update documentation for tap gesture and coordinate notation - Add @cereb/tap package to documentation and installation guide - Update pan and pinch signal API to use tuple-based coordinates - Update GitHub repository URL --- docs/public/llms-full.txt | 53 +++++++++++++++++++++++++++++++++------ docs/public/llms.txt | 4 ++- 2 files changed, 49 insertions(+), 8 deletions(-) diff --git a/docs/public/llms-full.txt b/docs/public/llms-full.txt index 255c447..77fbf1d 100644 --- a/docs/public/llms-full.txt +++ b/docs/public/llms-full.txt @@ -22,6 +22,7 @@ Cereb provides a unified abstraction for handling pointer/touch/mouse events thr | `cereb` | cereb | Core: Stream primitives, operators | | `@cereb/pan` | @cereb/pan | Pan/drag/swipe gesture | | `@cereb/pinch` | @cereb/pinch | Pinch/zoom gesture | +| `@cereb/tap` | @cereb/tap | Tap gesture | ### Installation @@ -29,6 +30,7 @@ Cereb provides a unified abstraction for handling pointer/touch/mouse events thr npm install cereb npm install @cereb/pan # optional npm install @cereb/pinch # optional +npm install @cereb/tap # optional ``` --- @@ -226,17 +228,19 @@ function pan(target: EventTarget, options?: { threshold?: number; direction?: "h **Signal Value:** - `phase`: "start" | "move" | "end" | "cancel" -- `deltaX`, `deltaY`: displacement from start (px) +- `delta`: [number, number] - displacement from start [deltaX, deltaY] (px) +- `velocity`: [number, number] - [velocityX, velocityY] (px/ms) +- `cursor`: [number, number] - current position (client coordinates) +- `pageCursor`: [number, number] - current position (page coordinates) - `distance`: cumulative distance (px) - `direction`: "up" | "down" | "left" | "right" | "none" -- `velocityX`, `velocityY`: px/ms -- `x`, `y`, `pageX`, `pageY` ```typescript import { pan } from "@cereb/pan"; pan(element).on((signal) => { - const { phase, deltaX, deltaY } = signal.value; + const { phase, delta } = signal.value; + const [deltaX, deltaY] = delta; if (phase === "move") { element.style.transform = `translate(${deltaX}px, ${deltaY}px)`; } @@ -266,19 +270,54 @@ function pinch(target: EventTarget, options?: { threshold?: number }): Stream { - const { phase, ratio, centerX, centerY } = signal.value; + const { phase, ratio, center } = signal.value; + const [centerX, centerY] = center; if (phase === "change") { element.style.transform = `scale(${ratio})`; } }); ``` +### tap (from @cereb/tap) + +Tap gesture recognition with multi-tap support. + +```typescript +function tap(target: EventTarget, options?: { + movementThreshold?: number; + durationThreshold?: number; + chainMovementThreshold?: number; + chainIntervalThreshold?: number; +}): Stream +``` + +**Signal Value:** +- `phase`: "start" | "end" | "cancel" +- `cursor`: [number, number] - tap position (client coordinates) +- `pageCursor`: [number, number] - tap position (page coordinates) +- `tapCount`: number - consecutive tap count (1=single, 2=double, etc.) +- `duration`: number - how long the pointer was pressed (ms) +- `pointerType`: "mouse" | "touch" | "pen" | "unknown" + +```typescript +import { tap } from "@cereb/tap"; + +tap(element).on((signal) => { + const { tapCount, cursor } = signal.value; + const [x, y] = cursor; + if (tapCount === 2) { + console.log(`Double tap at (${x}, ${y})`); + } +}); +``` + ### keyboard Both keydown and keyup events. @@ -695,6 +734,6 @@ pan(container) ## Links -- GitHub: https://github.com/niceplugin/cereb +- GitHub: https://github.com/devphilip21/cereb - Documentation: https://cereb.dev - npm: https://www.npmjs.com/package/cereb diff --git a/docs/public/llms.txt b/docs/public/llms.txt index 2ddd540..501935e 100644 --- a/docs/public/llms.txt +++ b/docs/public/llms.txt @@ -8,6 +8,7 @@ - cereb: Core library with stream primitives and operators - @cereb/pan: Pan/drag/swipe gesture recognition - @cereb/pinch: Pinch/zoom gesture recognition +- @cereb/tap: Tap gesture recognition ## Getting Started @@ -25,6 +26,7 @@ - [multiPointer](https://cereb.dev/stream-api/multi-pointer): Multi-touch tracking - [pan](https://cereb.dev/stream-api/pan): Pan gesture with velocity/direction - [pinch](https://cereb.dev/stream-api/pinch): Two-finger pinch/zoom +- [tap](https://cereb.dev/stream-api/tap): Tap gesture with multi-tap support - [keyboard](https://cereb.dev/stream-api/keyboard): Keyboard events - [keydown](https://cereb.dev/stream-api/keydown): Keydown only - [keyheld](https://cereb.dev/stream-api/keyheld): Key hold state tracking @@ -59,5 +61,5 @@ ## Links -- GitHub: https://github.com/niceplugin/cereb +- GitHub: https://github.com/devphilip21/cereb - npm: https://www.npmjs.com/package/cereb