@base-framework/base 3.5.7 → 3.5.9

package/copilot.md

@@ -3,57 +3,114 @@
 Purpose: concise, project-specific guidance so AI agents are instantly productive in this codebase.
 
 ## Architecture (what to know first)
-- Render UI from plain JS objects ("layouts")—no templates. Parser turns objects into DOM (browser) or HTML strings (server).
-- Public API re-exported by `src/base.js` (e.g., `Builder`, `Component`, `Atom`, `Data`, `SimpleData`, `Model`, `Import`, `NavLink`, `router`, `Html`, `Directives`).
-- Runtime renderer switch: `modules/layout/render/*` via `RenderController.setup()` → `BrowserRender` in browser, `ServerRender` otherwise.
-- Component stack: `Unit` → `Component`. `Unit` handles lifecycle/context; `Component` adds state (`StateTracker`) and events.
-- Reactive data: `modules/data` provides `Data` (deep), `SimpleData` (shallow), `Model` (server-backed). `WatcherHelper` powers `[[prop.path]]` in strings/arrays.
+- **Render UI from plain JS objects** ("layouts")—no templates, no JSX. Parser turns objects into DOM (browser) or HTML strings (server).
+- **Public API** re-exported by `src/base.js`: `Builder`, `Component`, `Unit`, `Jot`, `Pod`, `Atom`, `Data`, `SimpleData`, `Model`, `StateTracker`, `Import`, `NavLink`, `router`, `Html`, `Directives`, `Ajax`.
+- **Runtime renderer switch**: `modules/layout/render/*` via `RenderController.setup()` → `BrowserRender` in browser, `ServerRender` for SSR.
+- **Component hierarchy**: `Unit` (lifecycle/context) → `Component` (adds state via `StateTracker` and events).
+- **Shorthand APIs**: `Jot` (functional components), `Pod` (stateful functional), `Atom` (reusable layouts).
+- **Reactive data**: `Data` (deep proxy), `SimpleData` (shallow proxy), `Model` (server-backed). `WatcherHelper` powers `[[prop.path]]` bindings.
+- **State management**: `StateTracker` for global state, component-level states via `setupStates()`.
+- **Routing**: Client-side with History API, reactive `router.data.path`, automatic route parameters.
+- **HTTP requests**: `Ajax` module with shorthand methods (`Ajax.get()`, `Ajax.post()`).
+- **Dynamic imports**: `Import` wrapper for lazy loading with dependencies.
 
 ## CRITICAL: Common Mistakes to Avoid
 1. **DON'T use templates or JSX** - Base uses plain JavaScript objects for layouts
 2. **DON'T call `render()` directly** - Components call it internally; you return layout objects from `render()`
 3. **DON'T mutate props** - Props are read-only; use `this.data` or `this.state` for mutable values
 4. **DON'T use `this.setState()`** - Use `this.state.set('key', value)` or `this.state.increment('key')`
-5. **DON'T forget `new` with Components** - Always: `new MyComponent()`, never just `MyComponent()`
-6. **DON'T use `new` with Atoms** - Always: `Button()`, never `new Button()`
-7. **DON'T mix data initialization locations** - Use `setData()` for initial setup, not `beforeSetup` or constructor
+5. **DON'T forget `new` with Components** - Always: `new MyComponent()`, `new Component()`, never just `MyComponent()`
+6. **DON'T use `new` with Atoms** - Always: `Button()`, never `new Button()`. Atoms are functions, not classes
+7. **DON'T use `new` with Jot/Pod** - Call the returned class: `const MyJot = Jot({...}); new MyJot()` not `new Jot({})`
+8. **DON'T mix data initialization locations** - Use `setData()` for initial setup, not `beforeSetup` or constructor
+9. **DON'T bind without data** - `bind` directive requires `this.data` to be initialized via `setData()`
+10. **DON'T use wrong state methods** - State keys must be defined in `setupStates()` before using `increment`, `decrement`, `toggle`
+11. **DON'T forget Import function form** - Use `Import(() => import('./file.js'))` not `Import('./file.js')` for bundler support
+12. **DON'T use element.remove()** - Use `Html.removeElement(element)` or `Builder.removeNode(element)` for proper cleanup
+13. **DON'T access DOM before afterSetup** - `this.panel` and `this.elem` are only available after `afterSetup()` lifecycle hook
+14. **DON'T return arrays from render()** - Wrap multiple elements: `return { children: [elem1, elem2] }` not `return [elem1, elem2]`
+15. **DON'T use `await` in render()** - Load data in lifecycle hooks, render() must be synchronous
 
 ## Authoring layouts (house rules)
-- Shape: `{ tag: 'div', class: 'name', children: [...] }`. Shorthands: `nest` → `children`; `text` creates text node; `html|innerHTML` sets raw HTML; buttons default `type: 'button'`.
+- **Shape**: `{ tag: 'div', class: 'name', children: [...] }`. Shorthands: `nest` → `children`; `text` creates text node; `html|innerHTML` sets raw HTML.
 - **Default tag is 'div'** - Omit `tag` for divs: `{ class: 'container' }` renders as `<div class="container"></div>`
-- Events on elements receive `(event, parentComponent)` and are bound on the element: `{ click(e, parent) { parent.doThing(); } }`.
-- **Event names are lowercase** - Use `click`, `mouseover`, `change`, not `onClick` or `CLICK`
-- Watchers become `watch` directives automatically:
-  - **PREFERRED**: Current component data: `{ class: 'counter-[[count]]' }` (simplest, use this by default)
+- **Button default** - Buttons default to `type: 'button'` (not 'submit')
+- **Events on elements** receive `(event, parentComponent)` and are bound on the element: `{ click(e, parent) { parent.doThing(); } }`
+- **Event names are lowercase** - Use `click`, `mouseover`, `change`, `input`, `submit`, not `onClick` or `CLICK`
+- **Watchers** become `watch` directives automatically:
+  - **PREFERRED**: Current component data: `{ class: 'counter-[[count]]' }` (simplest, watches `this.data` or `this.state`)
   - Specific data source: `{ value: ['[[path]]', data] }` (when you need different data than `this.data`)
   - Multi-source with callback: `{ class: ['[[a]] [[b]]', [dataA, dataB], ([a,b]) => `${a}-${b}`] }` (advanced use)
-- Directives are just attrs mapped in `modules/layout/directives/core/default-directives.js` (e.g., `bind`, `watch`, `map`, `for`, `route`, `switch`, `useState`, `useData`, `onCreated`, `onDestroyed`).
 - **Null/undefined props are ignored** - Use `{ class: condition ? 'active' : null }` to conditionally add attributes
+- **Arrays in children** - Flatten automatically: `{ children: [elem1, [elem2, elem3], elem4] }` works
+- **Function children** - Return layout objects: `{ children: [() => ({ tag: 'span', text: 'Dynamic' })] }`
+- **Conditional rendering** - Use logical operators: `{ children: [condition && element, other || fallback] }`
 
 ## Common directives (quick cookbook)
 - **bind** (two-way by default, binds to `this.data` in component):
   - Text input: `{ tag: 'input', type: 'text', bind: 'form.name' }` (binds to `this.data.form.name`)
   - Checkbox: `{ tag: 'input', type: 'checkbox', bind: 'form.accepted' }` (binds to boolean)
+  - Radio: `{ tag: 'input', type: 'radio', name: 'color', value: 'red', bind: 'form.color' }`
   - Select + options: `{ tag: 'select', bind: 'form.color', children: [{ map: ['[[colors]]', data, (c) => ({ tag:'option', value:c, text:c })] }] }`
   - **IMPORTANT**: `bind` requires the component to have `this.data` set via `setData()`
   - Custom attribute: `{ tag: 'a', bind: 'href:link.url' }` (binds to href instead of value)
   - With filter: `{ bind: ['count', (v) => Math.round(v)] }` (transform displayed value)
+  - One-way: `{ oneway: 'propPath' }` (element → data only)
 
 - **map** (render lists from arrays, signature: `[watcherString, dataSource, callback]`):
   - Basic: `{ tag: 'ul', children: [{ map: ['[[items]]', data, (item, i) => ({ tag:'li', text:item.name })] }] }`
   - Callback receives: `(item, index)` - use both for keyed lists
   - **IMPORTANT**: The callback must return a layout object, not a string
+  - With keys: Use `key: item.id` in returned layout for better performance
+
+- **for** (repeat element N times):
+  - Basic: `{ for: [5, (i) => ({ tag: 'div', text: `Item ${i}` })] }`
+  - With data: `{ for: [['[[count]]', data], (i) => ({ tag: 'span', text: i })] }`
+
+- **if** (conditional rendering):
+  - Basic: `{ if: [() => condition, { tag: 'div', text: 'Shown' }] }`
+  - With data: `{ if: [['[[isVisible]]', data], { tag: 'div', text: 'Visible' }] }`
+  - **NOTE**: Use regular JavaScript `condition && layout` for simpler cases
 
 - **Watchers** (one-way binding, auto-updates when data changes):
-  - Simple: `{ class: 'status-[[status]]' }` (watches `this.data.status`)
+  - Simple: `{ class: 'status-[[status]]' }` (watches `this.data.status` or `this.state.status`)
   - Multiple: `{ text: 'User: [[name]] Age: [[age]]' }` (watches multiple props)
   - Deep paths: `{ text: '[[user.profile.name]]' }` (nested object access)
+  - In arrays: `{ class: ['theme-[[theme]]', 'page'] }` (combines static and dynamic)
 
 - **Lifecycle hooks** (element-level, different from component lifecycle):
   - `{ onCreated: (el, parent) => {/* el is DOM node, parent is component */} }`
   - `{ onDestroyed: (el, parent) => {/* cleanup before removal */} }`
   - **IMPORTANT**: These fire for each element, not once per component
 
+- **State/Data hooks** (access parent state/data):
+  - `{ useData: data }` - use specific data source for watchers in this subtree
+  - `{ useState: state }` - use specific state source for watchers in this subtree
+  - `{ useContext: context }` - use specific context for this subtree
+  - `{ useParent: component }` - explicitly set parent component reference
+  - **NOTE**: These propagate to child elements
+
+- **onSet** (reactive callback for data changes):
+  - Basic: `{ onSet: ['propPath', (value, oldValue) => ({ tag: 'div', text: value })] }`
+  - Multiple props: `{ onSet: [['prop1', 'prop2'], ([val1, val2]) => layout] }`
+  - With data source: `{ onSet: ['propPath', data, (value) => layout] }`
+
+- **Component integration**:
+  - `{ addState: { count: 0 } }` - add state properties to component
+  - `{ addEvent: { myEvent: (data) => {} } }` - add event to component
+  - `{ addContext: { theme: 'dark' } }` - add context to component
+
+- **Animation**:
+  - Enter: `{ animateEnter: 'fadeIn' }` or `{ animateEnter: { name: 'slide', duration: 300 } }`
+  - Exit: `{ animateExit: 'fadeOut' }`
+  - Move: `{ animateMove: 'slide' }`
+
+- **Accessibility**:
+  - `{ a11yHide: true }` - hide from screen readers
+  - `{ a11yLabel: 'descriptive text' }` - set aria-label
+  - `{ a11yRole: 'button' }` - set role
+  - `{ a11yDescribe: 'longer description' }` - set aria-describedby
+
 - **Cache/persist**:
   - `cache: 'propName'` - stores DOM element in `this.propName` (use for later access)
   - `persist: true` on parent preserves child component instances across re-renders
@@ -63,6 +120,10 @@ Purpose: concise, project-specific guidance so AI agents are instantly productiv
 - Extend `Component` and implement `render()` - return layout object (never call `render()` manually)
 - Root element auto-cached as `this.panel` - access after `afterSetup()` lifecycle hook
 - Use `this.getId('child')` for stable DOM IDs across re-renders
+- Helper methods available on Component instances:
+  - `this.if(condition, layout)` - conditional rendering helper
+  - `this.map(array, callback)` - array mapping helper
+  - `this.declareProps(schema)` - prop validation and defaults
 
 ### State Management
 - Override `setupStates()` to define reactive state properties:
@@ -70,44 +131,310 @@ Purpose: concise, project-specific guidance so AI agents are instantly productiv
   setupStates() {
       return {
           count: 0,  // Initial value
-          active: { state: false, callBack: (val) => {/* fires on change */} }
+          active: { state: false, callBack: (val) => {/* fires on change */} },
+          items: []  // Arrays work too
       };
   }
   ```
 - Access via `this.state.count` or `this.state.get('count')`
-- Update methods: `this.state.set('count', 5)`, `this.state.increment('count')`, `this.state.toggle('active')`
+- Update methods:
+  - `this.state.set('count', 5)` or `this.state.set({ count: 5, active: true })`
+  - `this.state.increment('count', amount?)` - add to number (default +1)
+  - `this.state.decrement('count', amount?)` - subtract from number (default -1)
+  - `this.state.toggle('active')` - flip boolean
+  - `this.state.push('items', item)` - add to array
+  - `this.state.splice('items', index, count)` - remove from array
 - **NEVER** use `this.setState()` - that method doesn't exist
+- **IMPORTANT**: State keys must be defined in `setupStates()` before using helper methods
+
+### Global State (StateTracker)
+- Create global state with `StateTracker.create(id, initialState)`:
+  ```javascript
+  import { StateTracker } from '@base-framework/base';
+  const appState = StateTracker.create('app', { user: null, theme: 'light' });
+  ```
+- Access in components:
+  ```javascript
+  setupStateTarget() {
+      this.state = StateTracker.get('app');
+  }
+  ```
+- All state methods work on global state: `this.state.set('theme', 'dark')`
+- Use `useState` directive to connect elements to global state
 
 ### Data Management
 - Override `setData()` to attach reactive data (runs during component initialization):
   ```javascript
   setData() {
       this.data = new Data({ name: '', items: [] });
+      // Optional: local storage persistence
+      this.data.setKey('MY_STORAGE_KEY');
+      this.data.resume({ name: '', items: [] });  // Load or use defaults
   }
   ```
 - **CRITICAL**: Initialize data in `setData()`, NOT in `beforeSetup()` or constructor
 - Use `Data` for deep nested objects, `SimpleData` for flat objects, `Model` for server-backed data
-- Access/modify: `this.data.name = 'test'` or `this.data.set('name', 'test')`
-- Components with `route`/`switch` directives automatically receive `this.route` (a bindable Data object)
+- Access/modify: `this.data.name = 'test'` or `this.data.set('name', 'test')` or `this.data.set({ name: 'test', items: [] })`
+- Components with `route`/`switch` directives automatically receive `this.route` (a bindable Data object with route params)
+- Array methods: `push`, `pop`, `shift`, `unshift`, `splice` (all trigger reactivity)
+- Other methods:
+  - `this.data.get('nested.path')` - get nested value
+  - `this.data.refresh('key')` - trigger watchers without changing value
+  - `this.data.delete('key')` - remove property
+  - `this.data.ifNull('key', defaultValue)` - return default if null/undefined
+  - `this.data.getIndex('array', predicate)` - find array index
+  - `this.data.concat('array', items)` - append to array
+  - `this.data.on('change', callback)` - subscribe to changes
+  - `this.data.off('change', callback)` - unsubscribe
+  - `this.data.store()` - save to local storage (if key set)
+  - `this.data.resume(defaults)` - load from local storage
+  - `this.data.revert()` - undo changes (Data only, not SimpleData)
+  - `this.data.link(otherData, 'prop')` - two-way sync with another data source
 
 ### Lifecycle Execution Order
 1. `onCreated()` - component instance created, props available, NO DOM yet
 2. `beforeSetup()` - before render, good for computed props
-3. `render()` - return layout object (called automatically)
-4. `afterSetup()` - DOM created but not in document, `this.panel` available
-5. `afterLayout()` - DOM in document, safe for measurements/animations
-6. `beforeDestroy()` - cleanup before removal
+3. `setData()` - initialize reactive data (runs automatically)
+4. `setupStates()` - define state properties (runs automatically)
+5. `setupStateTarget()` - connect to global state (runs automatically if defined)
+6. `render()` - return layout object (called automatically, NEVER call manually)
+7. `afterSetup()` - DOM created but not in document, `this.panel` available
+8. `afterRender()` - alias for afterSetup
+9. `afterLayout()` - DOM in document, safe for measurements/animations
+10. `beforeDestroy()` - cleanup before removal
+11. `onDestroyed()` - final cleanup after removal
+
+### Atoms (Reusable Layouts)
+- Create with `Atom((props, children) => layoutObject)`:
+  ```javascript
+  const Button = Atom((props, children) => ({
+      tag: 'button',
+      type: 'button',
+      ...props,
+      children
+  }));
+  ```
+- Call without `new`: `Button({ class: 'primary', click: handler }, 'Click Me')`
+- Support flexible argument order: `Button('text')`, `Button({ class: 'btn' })`, `Button({ class: 'btn' }, 'text')`
+- **DON'T** use `new` with Atoms - they are functions, not classes
+- Atoms can merge props, children, and have watchers: `Button({ class: 'btn-[[size]]' }, 'Text')`
+
+### Jot (Functional Components)
+- Create lightweight components: `const MyJot = Jot({ render() { return { tag: 'div' }; } })`
+- Returns a Component class: `new MyJot()` to instantiate
+- Supports all component features: `setData()`, `setupStates()`, lifecycle hooks
+- Auto-wrapped for non-Component objects in `Builder.render()`
+- **DON'T** use `new Jot({})` - call the returned class: `const MyJot = Jot({}); new MyJot()`
+
+### Pod (Stateful Functional Components)
+- Like Jot but with built-in state setup:
+  ```javascript
+  const Counter = Pod({
+      states: { count: 0 },
+      render() {
+          return { tag: 'div', text: 'Count: [[count]]' };
+      }
+  });
+  ```
+- Use `states` property to define state (equivalent to `setupStates()`)
+- Instantiate: `new Counter()`
+
+### Persistence & Component Reuse
+- Parent `persist: true` keeps child component instances alive during re-renders
+- Child can opt-out: `persist: false`
+- **WARNING**: Data initialized in `beforeSetup` can cause issues with persistence
+
+## HTTP Requests (Ajax Module)
+- **Shorthand methods** (recommended for simple requests):
+  ```javascript
+  import { Ajax } from '@base-framework/base';
+
+  // GET request
+  Ajax.get('/api/users').then(data => console.log(data));
+
+  // POST request
+  Ajax.post('/api/users', { name: 'John' }).then(data => console.log(data));
+
+  // PUT request
+  Ajax.put('/api/users/123', { name: 'Jane' });
+
+  // DELETE request
+  Ajax.delete('/api/users/123');
+
+  // HEAD request
+  Ajax.head('/api/status');
+  ```
+
+- **Object syntax** (for advanced options):
+  ```javascript
+  Ajax({
+      url: '/api/users',
+      method: 'POST',
+      data: { name: 'John' },
+      responseType: 'json',  // 'json', 'text', 'blob', 'arraybuffer'
+      headers: { 'X-Custom': 'value' },
+      success: (data) => console.log('Success:', data),
+      error: (xhr) => console.error('Error:', xhr.status),
+      progress: (e) => console.log('Progress:', e.loaded / e.total)
+  });
+  ```
+
+- **Response types**:
+  - `'json'` (default) - auto-parse JSON response
+  - `'text'` - get response as string
+  - `'blob'` - for binary data (files, images)
+  - `'arraybuffer'` - for raw binary data
+
+- **Global configuration**:
+  ```javascript
+  // Add fixed params to all requests
+  Ajax.addFixedParams({ apiKey: 'abc123' });
+
+  // Pre-request hook
+  Ajax.beforeSend((xhr) => {
+      xhr.setRequestHeader('Authorization', 'Bearer token');
+  });
+
+  // Default settings
+  Ajax.ajaxSettings({
+      baseURL: '/api',
+      timeout: 5000,
+      withCredentials: true
+  });
+  ```
+
+- **In components**:
+  ```javascript
+  class UserList extends Component {
+      onCreated() {
+          Ajax.get('/api/users').then(users => {
+              this.data.set('users', users);
+          });
+      }
+  }
+  ```
+
+## Dynamic Module Loading (Import)
+- **Basic usage** (lazy load components/modules):
+  ```javascript
+  import { Import } from '@base-framework/base';
+
+  // In layouts (function form - works with bundlers)
+  { children: [Import(() => import('./components/heavy.js'))] }
+
+  // String path (for non-bundler scenarios)
+  { children: [Import('./components/simple.js')] }
+  ```
+
+- **With dependencies** (load CSS/JS before module):
+  ```javascript
+  Import({
+      src: () => import('./components/Chart.js'),
+      depends: [
+          './styles/chart.css',
+          './vendor/chart-lib.js'
+      ],
+      callback: (module) => console.log('Chart loaded:', module)
+  });
+  ```
+
+- **Route-based lazy loading**:
+  ```javascript
+  {
+      switch: [
+          { uri: '/dashboard', component: Import(() => import('./pages/Dashboard.js')) },
+          { uri: '/profile', component: Import(() => import('./pages/Profile.js')) },
+          { uri: '/settings', component: Import(() => import('./pages/Settings.js')) }
+      ]
+  }
+  ```
+
+- **Persistent modules** (keep loaded after parent destroyed):
+  ```javascript
+  Import({
+      src: () => import('./services/Analytics.js'),
+      persist: true  // Stays loaded globally
+  });
+  ```
+
+- **CRITICAL**: Always use function form `() => import()` for bundler support (Vite, Webpack)
+- **DON'T** use string paths with bundlers: `Import('./file.js')` won't code-split
+- **DO** use function form: `Import(() => import('./file.js'))` enables code-splitting
 
-### Persistence
+### Persistence & Component Reuse
 - Parent `persist: true` keeps child component instances alive during re-renders
 - Child can opt-out: `persist: false`
 - **WARNING**: Data initialized in `beforeSetup` can cause issues with persistence
 
-### Jot (Lightweight Components)
-- Wrap objects/functions as components: `Jot({ render() { return {...}; } })`
-- Non-Unit inputs to `Builder.render()` auto-wrapped with Jot
+### Component Helper Methods (Available in all Components)
+```javascript
+class MyComponent extends Component {
+    someMethod() {
+        // Conditional rendering helper
+        this.if(this.state.show, { tag: 'div', text: 'Visible' });
+
+        // Array mapping helper
+        const items = this.map([1, 2, 3], (num) => ({ tag: 'span', text: num }));
+
+        // Get stable DOM ID
+        const id = this.getId('element-name');  // 'component-123-element-name'
 
-### Useful state/data ops
+        // Prop validation (optional)
+        this.declareProps({
+            title: { type: 'string', required: true },
+            count: { type: 'number', default: 0 }
+        });
+    }
+}
+```
+
+### Lifecycle Execution Order
+1. `onCreated()` - component instance created, props available, NO DOM yet
+2. `beforeSetup()` - before render, good for computed props
+3. `setData()` - initialize reactive data (runs automatically)
+4. `setupStates()` - define state properties (runs automatically)
+5. `setupStateTarget()` - connect to global state (runs automatically if defined)
+6. `render()` - return layout object (called automatically, NEVER call manually)
+7. `afterSetup()` - DOM created but not in document, `this.panel` available
+8. `afterRender()` - alias for afterSetup
+9. `afterLayout()` - DOM in document, safe for measurements/animations
+10. `beforeDestroy()` - cleanup before removal
+11. `onDestroyed()` - final cleanup after removal
+
+### Atoms (Reusable Layouts)
+- Create with `Atom((props, children) => layoutObject)`:
+  ```javascript
+  const Button = Atom((props, children) => ({
+      tag: 'button',
+      type: 'button',
+      ...props,
+      children
+  }));
+  ```
+- Call without `new`: `Button({ class: 'primary', click: handler }, 'Click Me')`
+- Support flexible argument order: `Button('text')`, `Button({ class: 'btn' })`, `Button({ class: 'btn' }, 'text')`
+- **DON'T** use `new` with Atoms - they are functions, not classes
+- Atoms can merge props, children, and have watchers: `Button({ class: 'btn-[[size]]' }, 'Text')`
+
+### Jot (Functional Components)
+- Create lightweight components: `const MyJot = Jot({ render() { return { tag: 'div' }; } })`
+- Returns a Component class: `new MyJot()` to instantiate
+- Supports all component features: `setData()`, `setupStates()`, lifecycle hooks
+- Auto-wrapped for non-Component objects in `Builder.render()`
+- **DON'T** use `new Jot({})` - call the returned class: `const MyJot = Jot({}); new MyJot()`
+
+### Pod (Stateful Functional Components)
+- Like Jot but with built-in state setup:
+  ```javascript
+  const Counter = Pod({
+      states: { count: 0 },
+      render() {
+          return { tag: 'div', text: 'Count: [[count]]' };
+      }
+  });
+  ```
+- Use `states` property to define state (equivalent to `setupStates()`)
+- Instantiate: `new Counter()`
 - **State helpers** (only work on keys defined in `setupStates()`):
   - `this.state.set('key', value)` - set any value
   - `this.state.toggle('key')` - flip boolean