Merge branch 'master' into test/add-swap-source-tests

Author: dariomannu

QUICKSTART.md

@@ -0,0 +1,112 @@
+## Quick Start
+
+### Installation
+
+```bash
+# Using npm
+npm install rimmel rxjs
+
+# Using yarn 
+yarn add rimmel rxjs
+
+# Using pnpm
+pnpm add rimmel rxjs
+```
+
+### Basic Usage
+
+```js
+import { BehaviorSubject, scan } from 'rxjs';
+import { rml } from 'rimmel';
+
+const Component = () => {
+  const count = new BehaviorSubject(0).pipe(
+    scan(x=>x+1)
+  );
+  
+  return rml`
+    <button onclick="${count}">
+      click me (${count})
+    </button>
+  `;
+};
+
+const App = () => {
+  return rml`
+    <h1>Hello <img class="icon" src="https://rimmel.js.org/assets/rimmel.png"> World</h1>
+    ${Component()}
+
+    <hr>
+    Starter for <a href="https://github.com/reactivehtml/rimmel" target="_blank">Rimmel.js</a>
+  `;  
+};
+
+document.body.innerHTML = App();
+```
+
+## Key Features
+
+- **Stream-First Architecture**: Everything is a stream - events, data, UI updates
+- **No Virtual DOM**: Direct DOM updates via optimized "sinks"
+- **Tiny Bundle Size**: Core is just 2.5KB, tree-shakeable imports
+- **Zero Build Requirements**: Works with plain JavaScript
+- **Automatic Memory Management**: Handles subscription cleanup
+- **Built-in Suspense**: Automatic loading states with BehaviorSubject
+- **Web Components Support**: Create custom elements easily
+- **TypeScript Support**: Full type definitions included
+
+## Core Concepts
+
+### Sources (Input)
+- DOM Events (`onclick`, `onmousemove`, etc)
+- Promises 
+- RxJS Observables
+- Custom Event Sources
+
+### Sinks (Output)
+- DOM Updates
+- Class Management
+- Style Updates
+- Attribute Changes
+- Custom Sinks
+
+## Available Sinks
+
+The library includes specialized sinks for common UI operations:
+
+- `InnerHTML` - Update element content 
+- `InnerText` - Safe text updates
+- `Class` - Manage CSS classes
+- `Style` - Update styles
+- `Value` - Form input values
+- `Disabled` - Toggle disabled state
+- `Readonly` - Toggle readonly state
+- `Removed` - Remove elements
+- `Sanitize` - Safe HTML rendering
+- `AppendHTML` - Append content
+- `PrependHTML` - Prepend content
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm run test
+
+# Build library
+npm run build
+
+# Run demo app
+npm run kitchen-sink
+```
+
+## Examples
+
+Check out our examples:
+
+- [Basic Demos](https://stackblitz.com/@dariomannu/collections/rimmel-js-getting-started)
+- [Advanced Patterns](https://stackblitz.com/@dariomannu/collections/rimmel-js-experiments) 
+- [Web Components](https://stackblitz.com/@dariomannu/collections/web-components)
+- [Web Workers](https://stackblitz.com/@dariomannu/collections/web-workers)

README.md

@@ -10,6 +10,8 @@ Rimmel is a powerful, fast and lightweight JavaScript UI library for creating we
 
 It implements [RML](https://github.com/ReactiveHTML/reactive-markup), the Reactive Markup which makes your HTML work with Streams in a seamless way.
 
+## To Busy to read?, Check [TL;DR 📜](./QUICKSTART.md)<br>
+
 ## Getting started
 If you are new to reactive streams, there is a [3m crash-course](https://medium.com/@fourtyeighthours/the-mostly-inaccurate-crash-course-for-reactive-ui-development-w-rxjs-ddbb7e5e526e) tailored for UI development with Rimmel, arguably the simplest RxJS introduction around to get you started.
 

src/sources/swap-source.test.ts

@@ -1,21 +1,25 @@
 import type { Observable } from 'rxjs';
 
 import { Subject } from 'rxjs';
-import { Swap, swap } from './swap-source';
 import { MockElement, MockEvent } from '../test-support';
+import { Swap, swap } from './swap-source';
 
 describe('Swap Event Adapter', () => {
+
 	it('Swaps a value from an element with a static string', () => {
 		const oldValue = 'old data';
 		const newValue = 'new data';
+
 		const el = MockElement({
-			tagName: "INPUT",
+            tagName: 'INPUT',
 			type: 'text',
 			value: oldValue,
 		});
+
 		const eventData = MockEvent('input', {
 			target: el as HTMLInputElement
 		});
+
 		const handlerSpy = jest.fn();
 		const source = Swap(newValue, handlerSpy);
 
@@ -24,59 +28,70 @@ describe('Swap Event Adapter', () => {
 		expect(handlerSpy).toHaveBeenCalledWith(oldValue);
 		expect(el.value).toEqual(newValue);
 	})
-})
-
-it('Swaps a value from an element with empty string by default', () => {
-	const oldValue = 'old data';
-	const el = MockElement({
-		tagName: 'INPUT',
-		type: 'text',
-		value: oldValue,
-	});
-	const eventData = MockEvent('input', {
-		target: el as HTMLInputElement
-	});
-    const handlerSpy = jest.fn();
+
+    it('Swaps a value in an element using a function', () => {
+        const oldValue = 'old data';
+
+        const el = MockElement({
+            tagName: 'INPUT',
+            type: 'text',
+            value: oldValue,
+        });
+
+        const eventData = MockEvent('input', {
+            target: el as HTMLInputElement
+        });
+
+        const replaceFn = (v: string) => v.toUpperCase();
+
+        const handlerSpy = jest.fn();
     const source = Swap(undefined, handlerSpy);
 
-	source.next(eventData);
+        source.next(eventData);
 
-	expect(handlerSpy).toHaveBeenCalledWith(oldValue);
-	expect(el.value).toEqual('');
-});
+        expect(handlerSpy).toHaveBeenCalledWith(oldValue);
+        expect(el.value).toEqual('OLD DATA');
+    });
 
-it('Swaps a value using a function that transforms based on the old value', () => {
-	const oldValue = '5';
-	const replacementFn = (v: string) => String(Number(v) * 2);
-	const el = MockElement({
-		tagName: 'INPUT',
-		type: 'text',
-		value: oldValue,
-	});
-	const eventData = MockEvent('input', {
-		target: el as HTMLInputElement
-	});
-	const handlerSpy = jest.fn();
-	const source = Swap(replacementFn, handlerSpy);
+    it('Swaps a value in an element with empty string by default', () => {
+        const oldValue = 'old data';
+
+        const el = MockElement({
+            tagName: 'INPUT',
+            type: 'text',
+            value: oldValue,
+        });
+
+        const eventData = MockEvent('input', {
+            target: el as HTMLInputElement
+        });
 
-	source.next(eventData);
+        const handlerSpy = jest.fn();
+        const source = Swap()(handlerSpy);
+        source.next(eventData);
+
+        expect(handlerSpy).toHaveBeenCalledWith(oldValue);
+        expect(el.value).toEqual('');
+    });
 
-	expect(handlerSpy).toHaveBeenCalledWith(oldValue);
-	expect(el.value).toEqual('10');
 });
 
 describe('swap Event Operator', () => {
+
 	it('Swaps and emits a value from an element with a static string', () => {
 		const oldValue = 'old data';
 		const newValue = 'new data';
+
 		const el = MockElement({
 			tagName: 'INPUT',
 			type: 'text',
 			value: oldValue,
 		});
+
 		const eventData = MockEvent('input', {
 			target: el as HTMLInputElement
 		});
+
 		const handlerSpy = jest.fn();
 		const pipeline = new Subject<typeof eventData>().pipe(swap(newValue)) as Observable<string> & Subject<typeof eventData>;
 
@@ -89,11 +104,13 @@ describe('swap Event Operator', () => {
 
 	it('Swaps and emits a value from an element with empty string', () => {
 		const oldValue = 'old data';
+
 		const el = MockElement({
 			tagName: 'INPUT',
 			type: 'text',
 			value: oldValue,
 		});
+
 		const eventData = MockEvent('input', {
 			target: el as HTMLInputElement
 		});
@@ -107,7 +124,7 @@ describe('swap Event Operator', () => {
 		expect(el.value).toEqual('');
 	});
 
-    
+
 
 	it('Swaps a value using a function that generates new value from old', () => {
 		const oldValue = 'test';
@@ -155,3 +172,4 @@ describe('swap Event Operator', () => {
 		expect(el.value).toEqual('replacement');
 	});
 });
+