native-document 1.0.14 → 1.0.16-8.1

package/docs/extending-native-document-element.md

@@ -0,0 +1,259 @@
+---
+title: Extending NDElement
+description: Add custom methods to NDElement to create reusable, domain-specific APIs across your application
+---
+
+# Extending NDElement
+
+NDElement is designed to be extensible. You can add custom methods to make your code more expressive, reduce boilerplate, and create a consistent API across your application.
+
+## Two Ways to Extend
+
+### `NDElement.extend()` - App-wide methods
+
+Use `NDElement.extend()` to add methods to **all NDElement instances**. This is the recommended public API:
+
+```javascript
+import { NDElement } from 'native-document';
+
+NDElement.extend({
+    onEnter(callback) {
+        this.$element.addEventListener('keyup', e => {
+            if (e.key === 'Enter') callback(e);
+        });
+        return this;
+    }
+});
+
+// Now available on every element
+Input({ type: 'text' }).nd.onEnter(e => console.log('Enter pressed'));
+```
+
+### `.nd.with()` - Instance-level methods
+
+Use `.nd.with()` to add methods to a **single element instance** only. See [NDElement](./native-document-element.md) for the full explanation and the `Counter` use case.
+
+```javascript
+const card = Div({ class: 'card' })
+    .nd.with({
+        highlight() {
+            this.$element.style.outline = '2px solid blue';
+            return this;
+        }
+    })
+    .highlight();
+```
+
+> Always `return this` at the end of every method to enable chaining.
+
+---
+
+## Common Extension Examples
+
+### Keyboard shortcuts
+
+```javascript
+NDElement.extend({
+    onEnter(callback) {
+        this.$element.addEventListener('keyup', e => {
+            if (e.key === 'Enter') callback(e);
+        });
+        return this;
+    },
+    onEscape(callback) {
+        this.$element.addEventListener('keyup', e => {
+            if (e.key === 'Escape') callback(e);
+        });
+        return this;
+    },
+    onArrowKey(callback) {
+        this.$element.addEventListener('keydown', e => {
+            if (['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight'].includes(e.key)) {
+                callback(e, e.key);
+            }
+        });
+        return this;
+    }
+});
+
+// Usage
+Input({ type: 'text' })
+    .nd
+    .onEnter(e => console.log('Submitted'))
+    .onEscape(e => e.target.blur())
+    .onArrowKey((e, direction) => console.log('Arrow:', direction));
+```
+
+### Form validation
+
+```javascript
+NDElement.extend({
+    required(message = 'This field is required') {
+        this.$element.addEventListener('blur', e => {
+            e.target.value.trim() ? this.clearError() : this.showError(message);
+        });
+        return this;
+    },
+    email(message = 'Please enter a valid email') {
+        this.$element.addEventListener('blur', e => {
+            const value = e.target.value.trim();
+            const valid = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
+            value && !valid ? this.showError(message) : this.clearError();
+        });
+        return this;
+    },
+    minLength(length, message) {
+        message = message || `Minimum ${length} characters required`;
+        this.$element.addEventListener('input', e => {
+            const len = e.target.value.length;
+            len > 0 && len < length ? this.showError(message) : this.clearError();
+        });
+        return this;
+    },
+    showError(message) {
+        this.clearError();
+        this.$element.parentNode.appendChild(
+            Span({ class: 'error-message', style: 'color: red; font-size: 0.8rem' }, message)
+        );
+        this.$element.classList.add('error');
+        return this;
+    },
+    clearError() {
+        this.$element.parentNode.querySelector('.error-message')?.remove();
+        this.$element.classList.remove('error');
+        return this;
+    }
+});
+
+// Usage
+Input({ type: 'email', placeholder: 'Email' })
+    .nd
+    .required()
+    .email();
+
+Input({ type: 'password', placeholder: 'Password' })
+    .nd
+    .required()
+    .minLength(8, 'Password must be at least 8 characters');
+```
+
+### Animations
+
+```javascript
+NDElement.extend({
+    fadeIn(duration = 300) {
+        duration = Math.max(0, parseInt(duration) || 300);
+        this.$element.style.opacity = '0';
+        this.$element.style.transition = `opacity ${duration}ms ease-in-out`;
+        requestAnimationFrame(() => {
+            this.$element.style.opacity = '1';
+        });
+        return this;
+    },
+    fadeOut(duration = 300, callback) {
+        duration = Math.max(0, parseInt(duration) || 300);
+        this.$element.style.transition = `opacity ${duration}ms ease-in-out`;
+        this.$element.style.opacity = '0';
+        setTimeout(() => { if (callback) callback(); }, duration);
+        return this;
+    },
+    slideDown(duration = 300) {
+        const el = this.$element;
+        el.style.maxHeight = '0';
+        el.style.overflow = 'hidden';
+        el.style.transition = `max-height ${duration}ms ease-in-out`;
+        requestAnimationFrame(() => {
+            el.style.maxHeight = el.scrollHeight + 'px';
+        });
+        return this;
+    }
+});
+
+// Usage
+Div('Animated content').nd.onClick(function() {
+    this.nd.fadeOut(300, () => this.nd.remove());
+});
+```
+
+---
+
+## Best Practices
+
+### Always return `this`
+
+Every method must return `this` to keep the chain alive:
+
+```javascript
+NDElement.extend({
+    myMethod() {
+        // your logic
+        return this; // required
+    }
+});
+```
+
+### Use descriptive names
+
+```javascript
+// Good
+NDElement.extend({ onEnter(cb) { ... } });
+NDElement.extend({ fadeIn(duration) { ... } });
+
+// Avoid
+NDElement.extend({ ke(cb) { ... } });     // unclear
+NDElement.extend({ doStuff() { ... } });  // too vague
+```
+
+### Guard against edge cases
+
+```javascript
+NDElement.extend({
+    fadeIn(duration = 300) {
+        if (!this.$element) return this;
+        duration = Math.max(0, parseInt(duration) || 300);
+        // animation logic
+        return this;
+    }
+});
+```
+
+### Document your extensions
+
+```javascript
+/**
+ * Fires callback when the Enter key is pressed
+ * @param {Function} callback - receives the KeyboardEvent
+ * @returns {NDElement} this - for chaining
+ * @example
+ * Input().nd.onEnter(e => submitForm());
+ */
+NDElement.extend({
+    onEnter(callback) {
+        this.$element.addEventListener('keyup', e => {
+            if (e.key === 'Enter') callback(e);
+        });
+        return this;
+    }
+});
+```
+
+### Respect protected methods
+
+The following names cannot be used - attempting to extend with them throws a `NativeDocumentError`:
+
+`constructor`, `valueOf`, `$element`, `$observer`, `ref`, `remove`, `cleanup`, `with`, `extend`, `attach`, `lifecycle`, `mounted`, `unmounted`, `unmountChildren`
+
+---
+
+## Next Steps
+
+- **[NDElement](./native-document-element.md)** - Full NDElement API reference
+- **[Lifecycle Events](./lifecycle-events.md)** - Lifecycle in depth
+- **[Args Validation](./validation.md)** - Function argument validation
+- **[Memory Management](./memory-management.md)** - Memory management
+
+## Utilities
+
+- **[Cache](./cache.md)** - Lazy initialization and singleton patterns
+- **[NativeFetch](./native-fetch.md)** - HTTP client with interceptors
+- **[Filters](./filters.md)** - Data filtering helpers

package/docs/filters.md

@@ -0,0 +1,247 @@
+---
+title: Filters
+description: Composable, reactive filter helpers for ObservableArray.where() - comparison, string, date, array, and logical operators
+---
+
+# Filters
+
+Filter helpers enable reactive, composable filtering on `ObservableArray` via `.where()`, `.whereSome()`, and `.whereEvery()`. Filters update automatically when observable values change.
+
+```javascript
+import { utils } from 'native-document';
+const { filters } = utils;
+
+// Or
+import { filters } from 'native-document/utils';
+
+// Or named imports
+import { equals, greaterThan, between, match, and, or, not } from 'native-document/filters';
+```
+
+> All filters are for **`ObservableArray` only** - see [Observables](./observables.md) for `.where()` usage.
+
+---
+
+## Comparison
+
+```javascript
+const products = Observable.array([
+    { name: 'Phone',  price: 599, stock: 10 },
+    { name: 'Laptop', price: 999, stock: 0  },
+    { name: 'Tablet', price: 399, stock: 5  },
+]);
+
+products.where({ price: equals(599) })              // Phone
+products.where({ name:  notEquals('Phone') })       // Laptop, Tablet
+products.where({ price: greaterThan(500) })         // Phone, Laptop
+products.where({ price: greaterThanOrEqual(399) })  // all
+products.where({ price: lessThan(600) })            // Tablet
+products.where({ price: lessThanOrEqual(399) })     // Tablet
+products.where({ price: between(400, 700) })        // Phone
+products.where({ stock: equals(0) })                // Laptop
+```
+
+All accept observables as arguments - filters update automatically when they change:
+
+```javascript
+const minPrice = Observable(300);
+const maxPrice = Observable(800);
+
+const filtered = products.where({
+    price: between(minPrice, maxPrice)
+});
+
+minPrice.set(500); // filtered updates automatically
+```
+
+---
+
+## String
+
+```javascript
+const users = Observable.array([
+    { name: 'Alice Johnson' },
+    { name: 'Bob Smith' },
+    { name: 'Charlie Wilson' }
+]);
+
+users.where({ name: includes('alice') })      // Alice Johnson (case-insensitive)
+users.where({ name: includes('smith', true) }) // Bob Smith (case-sensitive)
+users.where({ name: startsWith('A') })         // Alice Johnson
+users.where({ name: endsWith('son') })         // Alice Johnson, Charlie Wilson
+users.where({ name: match(/^[A-C]/) })         // Alice, Bob, Charlie (regex)
+users.where({ name: match('bob', false) })     // Bob Smith (plain text)
+```
+
+Reactive search:
+
+```javascript
+const search = Observable('');
+const results = users.where({ name: includes(search) });
+
+search.set('ali'); // Alice Johnson
+search.set('');    // all users
+```
+
+---
+
+## Array membership
+
+```javascript
+const allowed = Observable.array(['electronics', 'books']);
+
+products.where({ category: inArray(allowed) })       // reactive
+products.where({ category: inArray(['books']) })     // static
+products.where({ status:   notIn(['banned', 'deleted']) })
+```
+
+---
+
+## Logical operators
+
+`and`, `or`, `not` operate **within a single field**. For cross-field logic use the `_` key:
+
+```javascript
+// and - field must pass ALL conditions
+products.where({ price: and(greaterThan(100), lessThan(800)) })
+
+// or - field must pass AT LEAST ONE
+products.where({ category: or(equals('electronics'), equals('books')) })
+
+// not - inverts
+products.where({ status: not(equals('banned')) })
+
+// cross-field - plain function with _ key
+products.where({
+    _: item => item.stock > 0 && item.price < 500
+})
+```
+
+`all` is an alias for `and`, `any` is an alias for `or`.
+
+---
+
+## Custom filter
+
+```javascript
+const minRating = Observable(4);
+
+products.where({
+    _: custom((item, min) => {
+        return item.rating >= min && item.reviews > 10;
+    }, minRating) // observables as extra dependencies
+})
+```
+
+---
+
+## Date and time filters
+
+All date/time values are automatically converted to `Date` objects.
+
+### Date (ignores time)
+
+```javascript
+import { dateEquals, dateBefore, dateAfter, dateBetween } from 'native-document/filters';
+
+const today = Observable(new Date());
+
+events.where({ date: dateEquals('2024-03-15') })
+events.where({ date: dateAfter(new Date()) })
+events.where({ date: dateBefore(today) })
+events.where({ date: dateBetween('2024-06-01', '2024-08-31') })
+```
+
+### Time (ignores date)
+
+```javascript
+import { timeBefore, timeAfter, timeBetween } from 'native-document/filters';
+
+// Only the time portion is compared - date is ignored
+calls.where({ time: timeBetween('09:00:00', '17:00:00') }) // business hours
+calls.where({ time: timeAfter('18:00:00') })                // evening
+```
+
+### DateTime (date + time)
+
+```javascript
+import { dateTimeAfter, dateTimeBetween } from 'native-document/filters';
+
+logs.where({ timestamp: dateTimeAfter(new Date(Date.now() - 86400000)) }) // last 24h
+logs.where({ timestamp: dateTimeBetween(start, end) })
+```
+
+---
+
+## Filter Reference
+
+### Comparison
+| Filter | Alias | Description |
+|---|---|---|
+| `equals(value)` | `eq` | Exact match |
+| `notEquals(value)` | `neq` | Not equal |
+| `greaterThan(value)` | `gt` | > value |
+| `greaterThanOrEqual(value)` | `gte` | >= value |
+| `lessThan(value)` | `lt` | < value |
+| `lessThanOrEqual(value)` | `lte` | <= value |
+| `between(min, max)` | - | min <= value <= max |
+
+### String
+| Filter | Description |
+|---|---|
+| `includes(text, caseSensitive?)` | Contains substring |
+| `startsWith(text, caseSensitive?)` | Starts with |
+| `endsWith(text, caseSensitive?)` | Ends with |
+| `match(pattern, asRegex?, flags?)` | Regex or plain text match |
+
+### Array
+| Filter | Description |
+|---|---|
+| `inArray(array)` | Value is in array (observable-aware) |
+| `notIn(array)` | Value is not in array |
+
+### Logical
+| Filter | Alias | Description |
+|---|---|---|
+| `and(...filters)` | `all` | All conditions pass |
+| `or(...filters)` | `any` | At least one passes |
+| `not(filter)` | - | Inverts the filter |
+
+### Custom
+| Filter | Description |
+|---|---|
+| `custom(fn, ...observables)` | Custom logic with reactive dependencies |
+
+### Date
+| Filter | Description |
+|---|---|
+| `dateEquals(date)` | Same date (ignores time) |
+| `dateBefore(date)` | Before date |
+| `dateAfter(date)` | After date |
+| `dateBetween(start, end)` | Date range |
+| `timeEquals(time)` | Same time (ignores date) |
+| `timeBefore(time)` | Before time |
+| `timeAfter(time)` | After time |
+| `timeBetween(start, end)` | Time range |
+| `dateTimeEquals(dt)` | Exact timestamp |
+| `dateTimeBefore(dt)` | Before timestamp |
+| `dateTimeAfter(dt)` | After timestamp |
+| `dateTimeBetween(start, end)` | Timestamp range |
+
+---
+
+## Best Practices
+
+1. Prefer property-specific filters over `_` + plain function when possible - they are more efficient
+2. Combine multiple field conditions in a single `.where()` call - not chained `.where()` calls
+3. Reuse observable filter values across multiple arrays - they all update together
+4. Use `custom()` for complex logic that involves external observables
+
+---
+
+## Next Steps
+
+- **[Observables](./observables.md)** - Full `.where()`, `.whereSome()`, `.whereEvery()` reference
+- **[List Rendering](./list-rendering.md)** - ForEach with filtered arrays
+- **[Cache](./cache.md)** - Lazy initialization and singleton patterns
+- **[NativeFetch](./native-fetch.md)** - HTTP client with interceptors