@base-framework/ui 1.0.2030 → 1.0.2031

package/copilot.md

@@ -2,6 +2,18 @@
 
 This repo is a UI component library for the Base Framework, organized with Atomic Design (atoms → molecules → organisms → pages/templates) and styled with Tailwind CSS v4. It builds to multiple entry points via Vite.
 
+**📚 Full documentation available in `ui.wiki/` folder - refer to it for comprehensive guides.**
+
+## CRITICAL: Before You Start
+This is NOT React, Vue, or standard JSX. This uses Base Framework's declarative atoms/components with specific syntax patterns. **Read the documentation in base.wiki/ and the icon/children sections below carefully to avoid common mistakes.**
+
+### Key Differences from React/Vue
+1. **Children as second argument** - NEVER in props
+2. **Icons passed as children** - Not as icon prop in Icon component
+3. **Lists use map/for props** - Not regular .map()
+4. **Data binding with bind** - Not value + onChange
+5. **Reactive Data object** - Not useState
+
 ## How things fit together
 - Runtime primitives come from external packages:
   - `@base-framework/base` supplies Component, Atom, Data, Jot, Events, router, NavLink, etc.
@@ -34,15 +46,210 @@ This repo is a UI component library for the Base Framework, organized with Atomi
   - Subscriptions: `On('key', callback)` or `OnState/Open` utilities to react to state.
   - Parent context: `UseParent(({ state, ... }) => ...)` to access parent component refs.
 
-### Important: Atom argument patterns
-Atoms created with `Atom()` support flexible argument patterns:
+### CRITICAL: Atom argument patterns
+Atoms support flexible argument patterns. Children MUST be passed as second argument when it's an array:
 - **Props only**: `Div({ class: 'text' })`
 - **Text child only**: `Div('test')`
 - **Array children only**: `Div([Div('test')])`
 - **Props and text**: `Div({ class: 'text' }, 'test')`
-- **Props and array children**: `Div({ class: 'text' }, [Div('test')])`
+- **Props and array children**: `Div({ class: 'text' }, [Div('test'), Div('test2')])`
+
+❌ WRONG: `Div({ class: 'text', children: [...] })` - Never pass children in props
+✅ CORRECT: `Div({ class: 'text' }, [...])`
+
+## Component Types and When to Use
+
+### Use Atom for:
+- Stateless UI elements (buttons, badges, icons, labels)
+- Simple compositions of other atoms
+- Variants of existing atoms
+- Visual-only components without internal state
+
+```javascript
+export const Badge = Atom((props, children) => (
+  Span({
+    ...props,
+    class: `inline-flex rounded-full px-2.5 py-0.5 ${props.class || ''}`
+  }, children)
+));
+```
+
+### Use Component for:
+- Components with internal state (Data or setupStates)
+- Components that need lifecycle methods
+- Complex interactions requiring methods
+- Organisms like DataTable, Calendar, TabGroup
+
+```javascript
+export class Counter extends Component {
+  setData() {
+    return new Data({ count: 0 });
+  }
+
+  increment() {
+    this.data.count++;
+  }
+
+  render() {
+    return Div([
+      Button({ click: () => this.increment() }, '+'),
+      Span([On('count', (count) => count)])
+    ]);
+  }
+}
+```
+
+### Use Jot for:
+- Components with external two-way binding
+- Reusable inputs/controls with value/change pattern
+- Searchable dropdowns, toggles, custom inputs
+
+```javascript
+const Toggle = Jot((checked, setChecked) => (
+  Button({
+    click: () => setChecked(!checked),
+    class: checked ? 'bg-primary' : 'bg-muted'
+  }, checked ? 'ON' : 'OFF')
+));
+```
+
+## Data Management Patterns
+
+### Reactive Data (setData)
+Use for dynamic values that need reactivity:
+
+```javascript
+setData() {
+  return new Data({
+    // Simple values
+    name: '',
+    count: 0,
+
+    // Arrays (use for dynamic lists)
+    items: [],
+    selectedIds: [],
+
+    // Objects
+    user: { name: '', email: '' }
+  });
+}
+
+// Updating data triggers re-render
+this.data.count = 5;
+this.data.items.push(newItem);
+this.data.user.name = 'John';
+```
+
+### Component States (setupStates)
+Use for discrete state values (modes, flags):
+
+```javascript
+setupStates() {
+  return {
+    isOpen: false,           // Boolean flags
+    view: 'list',           // String modes: 'list' | 'grid' | 'table'
+    tab: 'overview'         // Tab selection
+  };
+}
+
+// Toggle state
+this.state.isOpen = !this.state.isOpen;
+```
 
-CRITICAL: When children is an array, pass it as the SECOND argument after props, NOT inside props.
+### Two-Way Binding
+```javascript
+// Simple binding to data
+Input({ bind: 'username' })
+Input({ bind: 'user.email' })
+
+// Binding to external state
+const state = new Data({ value: '' });
+Input({ bind: [state, 'value'] })
+
+// Binding with select
+Select({ bind: 'country', options: countries })
+
+// Binding with checkbox
+Input({ bind: 'accepted', type: 'checkbox' })
+```
+
+### Dynamic Lists
+```javascript
+// map prop - for static/external arrays
+Ul({
+  map: [items, (item) => Li(item.name)]
+})
+
+// for prop - for component data (reactive)
+Div({
+  for: ['items', (item, index) => (
+    ItemCard({ item, index })
+  )]
+})
+
+// NEVER use regular JavaScript .map() for reactive lists
+// ❌ WRONG: Ul([items.map(item => Li(item))])
+// ✅ CORRECT: Ul({ map: [items, (item) => Li(item)] })
+```
+
+## Watchers and Subscriptions
+
+### On - Watch Data Changes
+```javascript
+render() {
+  return Div([
+    // Watch single property
+    On('count', (value) => {
+      console.log('Count changed:', value);
+    }),
+
+    // Watch nested property
+    On('user.name', (name) => {
+      this.updateProfile(name);
+    }),
+
+    // Display watched value
+    Span({ onState: ['count', (count) => `Count: ${count}`] })
+  ]);
+}
+```
+
+### OnState - Watch State Changes
+```javascript
+render() {
+  return Div([
+    OnState('isOpen', (isOpen) => {
+      if (isOpen) {
+        this.loadContent();
+      }
+    })
+  ]);
+}
+```
+
+### OnStateOpen - Run Once When State Becomes True
+```javascript
+render() {
+  return Div([
+    OnStateOpen('isVisible', () => {
+      this.startAnimation();
+    })
+  ]);
+}
+```
+
+### UseParent - Access Parent Component
+```javascript
+const ChildAtom = Atom((props) => (
+  Div([
+    UseParent(({ data, state, panel }) => {
+      // Access parent's data/state
+      panel.selectItem(props.id);
+      return null;
+    })
+  ])
+));
+```
 
 ## File layout to know
 - `src/components/atoms/**`: Base-level atoms and atom variants (e.g., buttons, icons, badges, tooltips, skeleton, veil).
@@ -52,156 +259,115 @@ CRITICAL: When children is an array, pass it as the SECOND argument after props,
 - `src/utils/**`: Utilities (formatting, image-scaler with pointer/zoom/drag helpers).
 - `src/ui.js`: Re-exports public surface used by `vite` lib entries.
 
-## Working with Icons (CRITICAL)
+## Tailwind and theming
+- Tailwind scans `./src/ui.js` and `./src/**/*.{js,ts,jsx,tsx}`. If you add files, keep them under `src` and referenced by exports for purge to include classes.
+- Use semantic tokens configured in `tailwind.config.js`: `primary`, `secondary`, `destructive`, `warning`, `muted`, `accent`, `popover`, `card`, `border`, `foreground`, with `DEFAULT` and `foreground` pairs.
+- Dark mode is `media`. Prefer classes already used (`data-[state=active]:...`, rounded tokens via `--radius`).
 
-Icons in this library come from Heroicons and are defined in `src/components/icons/icons.js`. They are stored as SVG strings in a nested object structure.
+## Working with Icons (READ THIS - Most Common Mistake Area)
 
-### Icon Structure
-- Icons are organized hierarchically: `Icons.home`, `Icons.chat.default`, `Icons.chat.text`, `Icons.arrows.left`, etc.
-- Each icon is a raw SVG string with Heroicon styling
+### Icon Basics
+Icons come from [src/components/icons/icons.js](../src/components/icons/icons.js) (Heroicons library). They're SVG strings organized hierarchically. See [base.wiki/02-Icons.md](../base.wiki/02-Icons.md) for complete guide.
 
-### How to Use Icons (3 methods)
+### Three Ways to Use Icons
 
-#### Method 1: Using the Icon atom (RECOMMENDED)
+**Method 1: Icon atom (RECOMMENDED)**
 ```javascript
 import { Icon } from '@base-framework/ui/atoms';
 import { Icons } from '@base-framework/ui/icons';
 
-// Pass icon SVG string as child
-Icon({ size: 'sm', class: 'text-blue-500' }, Icons.home)
-Icon({ size: 'md' }, Icons.chat.default)
-Icon({ size: 'lg' }, Icons.arrows.left)
-
-// Sizes: xs, sm, md, lg, xl, 2xl, 3xl (default: sm)
+Icon({ size: 'sm' }, Icons.home)  // SVG string as CHILD, not in props
+Icon({ size: 'md', class: 'text-blue-500' }, Icons.chat.default)
 ```
 
-#### Method 2: Using raw I element
+**Method 2: Raw I element**
 ```javascript
 import { I } from '@base-framework/atoms';
 import { Icons } from '@base-framework/ui/icons';
 
-// Use html prop to inject SVG
-I({ html: Icons.home, class: 'w-6 h-6' })
-I({ html: Icons.chat.dots })
+I({ html: Icons.home, class: 'w-6 h-6' })  // Use html prop
 ```
 
-#### Method 3: In Button with icon prop
+**Method 3: In Button**
 ```javascript
 import { Button } from '@base-framework/ui/atoms';
 import { Icons } from '@base-framework/ui/icons';
 
-// Icon appears on left by default
-Button({ variant: 'withIcon', icon: Icons.plus }, 'Add Item')
-
-// Icon on right
+Button({ variant: 'withIcon', icon: Icons.plus }, 'Add')
 Button({ variant: 'withIcon', icon: Icons.arrows.right, position: 'right' }, 'Next')
 ```
 
-### Common Icon Access Patterns
+### Common Icon Paths
 ```javascript
-// Simple icons (top-level)
-Icons.home, Icons.star, Icons.help, Icons.plus
-
-// Nested icons (use dot notation)
-Icons.chat.default, Icons.chat.text, Icons.chat.dots
-Icons.arrows.left, Icons.arrows.right, Icons.arrows.upDown
-Icons.adjustments.vertical, Icons.adjustments.horizontal
-
-// Icons with states
-Icons.locked, Icons.unlocked
-Icons.play, Icons.stop, Icons.playing
+// Simple: Icons.home, Icons.star, Icons.help, Icons.plus
+// Nested: Icons.chat.default, Icons.arrows.left, Icons.adjustments.vertical
 ```
 
-### CRITICAL MISTAKES TO AVOID
-❌ **WRONG**: `Icon(Icons.home)` - Missing props object
-❌ **WRONG**: `Icon({ icon: Icons.home })` - Don't use `icon` prop
-❌ **WRONG**: `I(Icons.home)` - Must use `html` prop
-❌ **WRONG**: `Icons['home']` - Use dot notation, not bracket
-❌ **WRONG**: `Icons.chat` - Incomplete path for nested icons
+### CRITICAL Icon Mistakes
+❌ `Icon(Icons.home)` - Missing props object
+❌ `Icon({ icon: Icons.home })` - Wrong prop name, pass as child
+❌ `I(Icons.home)` - Must use html prop
+❌ `Icons['home']` - Use dot notation
 
-✅ **CORRECT**: `Icon({ size: 'sm' }, Icons.home)`
-✅ **CORRECT**: `I({ html: Icons.home })`
-✅ **CORRECT**: `Icons.chat.default` (for nested icons)
-
-## Tailwind and theming
-- Tailwind scans `./src/ui.js` and `./src/**/*.{js,ts,jsx,tsx}`. If you add files, keep them under `src` and referenced by exports for purge to include classes.
-- Use semantic tokens configured in `tailwind.config.js`: `primary`, `secondary`, `destructive`, `warning`, `muted`, `accent`, `popover`, `card`, `border`, `foreground`, with `DEFAULT` and `foreground` pairs.
-- Dark mode is `media`. Prefer classes already used (`data-[state=active]:...`, rounded tokens via `--radius`).
+✅ `Icon({ size: 'sm' }, Icons.home)`
+✅ `I({ html: Icons.home })`
+✅ `Button({ icon: Icons.plus }, 'Text')`
 
 ## Patterns by example
 
-### Functional Atom (from `molecules/alert.js`)
-Compose small atoms: `Div` containers + `I` for icons + `H5/P` for text. Type variants use lookup table → apply Tailwind classes from map.
-
+### Alert Component (Functional Atom)
 ```javascript
 import { Div, H5, I, P } from '@base-framework/atoms';
 import { Atom } from '@base-framework/base';
 
 const AlertIcon = (icon, iconColor) => (
-  Div({ class: `flex items-center justify-center h-6 w-6 mr-3 ${iconColor}` }, [
-    I({ html: icon })
+  Div({ class: `flex h-6 w-6 mr-3 ${iconColor}` }, [
+    I({ html: icon })  // Icon as SVG string
   ])
 );
 
 export const Alert = Atom(({ title, description, icon, type = 'default' }) => {
-  const { borderColor, bgColor, iconColor } = typeStyles[type];
-  return Div({ class: `flex items-start p-4 border rounded-lg ${bgColor} ${borderColor}` }, [
-    icon && AlertIcon(icon, iconColor),
+  const styles = typeStyles[type];
+  return Div({ class: `flex p-4 border rounded-lg ${styles.bgColor}` }, [
+    icon && AlertIcon(icon, styles.iconColor),
     Div({ class: 'flex flex-col' }, [
       H5({ class: 'font-semibold' }, title),
-      P({ class: 'text-sm text-muted-foreground' }, description)
+      P({ class: 'text-sm' }, description)
     ])
   ]);
 });
 ```
 
-### Variant pattern (from `atoms/buttons/buttons.js`)
-Define variant factories, then export a single `Button` Atom that dispatches by `props.variant`. Icon handling via a shared `IconButton` Atom; support `position: 'right'`.
-
+### Button with Icon (Variant Pattern)
 ```javascript
 import { Button as BaseButton } from '@base-framework/atoms';
 import { Atom } from '@base-framework/base';
 import { Icon } from '../icon.js';
 
 const IconButton = Atom((props, children) => (
-  BaseButton({
-    ...props,
-    class: props.class
-  }, [
+  BaseButton({ ...props }, [
     props.icon && props.position !== 'right' ? Icon({ size: 'sm' }, props.icon) : null,
     ...(children || []),
     props.icon && props.position === 'right' ? Icon({ size: 'sm' }, props.icon) : null
   ])
 ));
 
-const BUTTON_VARIANTS = {
-  primary: DefaultVariant({ class: 'primary' }),
-  withIcon: WithIconVariant({ class: 'with-icon' })
-};
-
 export const Button = Atom((props, children) => {
   const VariantButton = BUTTON_VARIANTS[props.variant] || BUTTON_VARIANTS.primary;
   return VariantButton(props, children);
 });
 ```
 
-### Data-driven lists (from `molecules/dropdowns/dropdown.js`)
-Use `for: ['collectionKey', (item) => ...]` to render nested collections from component state.
-
+### Data-Driven Lists
 ```javascript
-export const Dropdown = (onSelect) => (
-  Div({ class: 'w-full z-10' }, [
-    Div({
-      class: 'max-h-60 border rounded-md',
-      for: ['groups', (group) => Group(group, onSelect)]
-    })
-  ])
-);
-```
+// Using map prop
+Ul({ map: [items, (item) => Li(item.name)] })
 
-### Stateful Component (from `organisms/lists/data-table.js`)
-Use `Component` with `Data` for state management and `declareProps()` for type hints.
+// Using for with state
+Div({ for: ['groups', (group) => Group(group)] })
+```
 
+### Stateful Component
 ```javascript
 import { Component, Data } from '@base-framework/base';
 
@@ -214,77 +380,95 @@ export class DataTable extends Component {
   setData() {
     return new Data({
       selectedRows: [],
-      hasItems: this.rows && this.rows.length > 0
+      hasItems: this.rows?.length > 0
     });
   }
 
   render() {
-    return Div({ class: 'w-full' }, [
-      Table([
-        TableHeader({ headers: this.headers }),
-        DataTableBody({ rows: this.rows })
-      ])
+    return Table([
+      TableHeader({ headers: this.headers }),
+      DataTableBody({ rows: this.rows })
     ]);
   }
 }
 ```
 
-## Import Patterns (CRITICAL)
+## Import Patterns
 
-### External Framework Imports
+### From External Packages
 ```javascript
-// DOM elements and reactive utilities
-import { Div, Button, Input, I, Ul, Li, H5, P } from '@base-framework/atoms';
-import { On, OnState, UseParent } from '@base-framework/atoms';
+// DOM elements
+import { Div, Button, Input, I, Ul, Li, H5, P, Table } from '@base-framework/atoms';
 
-// Core framework classes and utilities
+// Reactive utilities
+import { On, OnState, OnStateOpen, UseParent } from '@base-framework/atoms';
+
+// Framework core
 import { Atom, Component, Data, Jot } from '@base-framework/base';
+
+// Routing
+import { router, NavLink } from '@base-framework/base';
 ```
 
-### Internal Library Imports
+### From This Library
 ```javascript
-// Icons (most common mistake area)
+// Icons (ALWAYS import both)
 import { Icons } from '@base-framework/ui/icons';
 import { Icon } from '@base-framework/ui/atoms';
 
-// Components from this library
-import { Button, Alert } from '@base-framework/ui/atoms';
-import { Form, Dropdown } from '@base-framework/ui/molecules';
-import { DataTable } from '@base-framework/ui/organisms';
+// Atoms
+import { Button, Badge, Alert } from '@base-framework/ui/atoms';
+
+// Molecules
+import { Form, Dropdown, Modal, DatePicker } from '@base-framework/ui/molecules';
+
+// Organisms
+import { DataTable, Calendar, TabGroup } from '@base-framework/ui/organisms';
+
+// Pages
+import { Page, BasicPage, SidebarMenuPage } from '@base-framework/ui/pages';
+
+// Utils
+import { Format, DateTime, ImageScaler } from '@base-framework/ui/utils';
 ```
 
-### Relative Imports (when authoring components IN this library)
+### Relative (when authoring in this repo)
 ```javascript
-// From within src/components/
 import { Icons } from '../../icons/icons.js';
 import { Icon } from '../icon.js';
-import { Button as BaseButton } from '@base-framework/atoms';
 ```
 
 ## Coding rules (do/don't)
 
-### DO:
-- ✅ Import primitives from `@base-framework/atoms` (Div, Button, I, etc.)
-- ✅ Import framework tools from `@base-framework/base` (Atom, Component, Data)
-- ✅ Pass children array as SECOND argument: `Div({ class: 'wrapper' }, [child1, child2])`
-- ✅ Use `Icons` object from `@base-framework/ui/icons` for all icons
-- ✅ Use `Icon` atom with SVG string as child: `Icon({ size: 'sm' }, Icons.home)`
-- ✅ Use `I({ html: iconString })` for raw icon rendering
-- ✅ Export new components from appropriate barrel files
-- ✅ Use Tailwind semantic tokens (primary, muted-foreground, etc.)
-- ✅ Use `map: [array, fn]` or `for: ['key', fn]` for lists
-- ✅ Use `bind: 'path'` or `bind: [state, 'key']` for two-way binding
-
-### DON'T:
-- ❌ Pass children inside props object: `Div({ children: [...] })`
-- ❌ Use `icon` prop on Icon atom: `Icon({ icon: Icons.home })`
-- ❌ Pass icon directly without props: `Icon(Icons.home)`
-- ❌ Use React/Vue/JSX syntax
-- ❌ Mutate DOM directly (use Data bindings instead)
-- ❌ Use raw hex colors (use Tailwind tokens)
-- ❌ Import Icons from wrong path
-- ❌ Create new icon implementations (use existing Icon atom)
-- ❌ Forget to spread props: always use `{ ...defaultProps, ...props }`
+### ✅ DO:
+- Import DOM elements from `@base-framework/atoms`
+- Import Atom, Component, Data from `@base-framework/base`
+- Pass children as SECOND argument: `Div({ class: 'x' }, [children])`
+- Use Icons object: `import { Icons } from '@base-framework/ui/icons'`
+- Use Icon atom: `Icon({ size: 'sm' }, Icons.home)`
+- Use I element for icons: `I({ html: Icons.home })`
+- Spread props: `{ ...defaultProps, ...props }`
+- Use Tailwind semantic tokens (primary, secondary, destructive, warning, muted, accent)
+- Use `map` or `for` for lists: `Ul({ map: [items, fn] })` or `Div({ for: ['items', fn] })`
+- Use `bind` for two-way binding: `Input({ bind: 'username' })`
+- Use `On` for data watchers: `On('count', (val) => ...)`
+- Use `OnState` for state watchers: `OnState('isOpen', (val) => ...)`
+- Use Data for reactive values: `new Data({ count: 0 })`
+- Use setupStates for discrete states: `setupStates() { return { isOpen: false } }`
+- Read documentation in `base.wiki/` for detailed patterns
+
+### ❌ DON'T:
+- Pass children in props: `Div({ children: [...] })`
+- Use icon prop on Icon: `Icon({ icon: Icons.home })`
+- Pass icon without props: `Icon(Icons.home)`
+- Use React/Vue/JSX patterns
+- Mutate DOM directly
+- Use raw hex colors (use Tailwind tokens)
+- Import Icons from wrong path
+- Use regular JS map for reactive lists: `[items.map(...)]`
+- Use value + onChange: use `bind` instead
+- Use plain objects for reactive data: use `Data` instead
+- Use useState hooks: use `Data` and `setupStates` instead
 
 ## Adding a new component (checklist)
 1) Decide Atom vs Component (stateless vs stateful/interactive)
@@ -293,131 +477,112 @@ import { Button as BaseButton } from '@base-framework/atoms';
 4) If it needs data/state, use `Data`/`Jot`, `On`, `bind`, `for` as seen in existing components
 5) Run dev server and verify render; run build to ensure types emit
 
-## Common Mistakes & Troubleshooting
-
-### Issue: Icons not rendering
-**Symptoms**: Icons appear as blank or broken
-**Causes**:
-1. Wrong import path for Icons
-2. Incorrect Icon usage syntax
-3. Missing `html` prop on I element
+## Common Mistakes & Quick Fixes
 
-**Solutions**:
+### Icons Not Rendering
 ```javascript
-// ✅ Correct ways
-import { Icons } from '@base-framework/ui/icons';
+// ❌ Wrong
+Icon(Icons.home)                    // Missing props object
+Icon({ icon: Icons.home })          // Wrong prop name, pass as child
+I(Icons.home)                       // Must use html prop
+Button({ icon: Icons.home })        // Missing variant: 'withIcon'
+
+// ✅ Correct
 Icon({ size: 'sm' }, Icons.home)
 I({ html: Icons.home })
-
-// ❌ Wrong ways
-Icon(Icons.home) // Missing props object
-Icon({ icon: Icons.home }) // Wrong prop name
-I(Icons.home) // Missing html prop
+Button({ variant: 'withIcon', icon: Icons.plus }, 'Text')
 ```
 
-### Issue: Children not rendering
-**Symptoms**: Child components/text not appearing
-**Cause**: Passing children in props object instead of as second argument
-
-**Solution**:
+### Children Not Appearing
 ```javascript
+// ❌ Wrong
+Div({ class: 'wrapper', children: [Div('test')] })  // children in props
+Div({ class: 'wrapper' }, Div('test'))              // Single child must be array or string
+
 // ✅ Correct
-Div({ class: 'wrapper' }, [
-  Div('child 1'),
-  Div('child 2')
-])
+Div({ class: 'wrapper' }, [Div('test')])            // Array of children
+Div({ class: 'wrapper' }, 'text only')              // Single text child
+```
 
+### Lists Not Rendering
+```javascript
 // ❌ Wrong
-Div({
-  class: 'wrapper',
-  children: [Div('child')]
-})
-```
+Ul([items.map(item => Li(item.name))])              // Regular JS map doesn't track reactivity
+Div(items.map(item => ItemCard(item)))              // Missing props object, not reactive
 
-### Issue: Component not reactive
-**Symptoms**: UI doesn't update when data changes
-**Cause**: Not using Data or proper bindings
+// ✅ Correct
+Ul({ map: [items, (item) => Li(item.name)] })      // Static/external arrays
+Div({ for: ['items', (item) => ItemComponent(item)] })  // Component data (reactive)
+```
 
-**Solution**:
+### Not Reactive
 ```javascript
-// ✅ Use Data in Component
+// ❌ Wrong (plain object)
+this.state = { count: 0 };
+this.state.count++;  // Doesn't trigger re-render
+
+// ✅ Correct (use Data)
 setData() {
   return new Data({ count: 0 });
 }
-
-// ✅ Use bind for two-way binding
-Input({ bind: 'username' })
-Input({ bind: [externalState, 'email'] })
+// In method:
+this.data.count++;  // Triggers re-render
 ```
 
-### Issue: List not rendering
-**Symptoms**: Array of items not displaying
-**Cause**: Using regular map instead of Base's reactive patterns
-
-**Solution**:
+### Binding Issues
 ```javascript
-// ✅ Use map prop
-Ul({ map: [items, (item) => Li(item.name)] })
-
-// ✅ Use for with state key
-Div({ for: ['items', (item) => ItemComponent(item)] })
+// ❌ Wrong
+Input({ value: name, change: (e) => setName(e.target.value) })  // React pattern
+Input({ value: this.data.username })  // One-way only, not reactive
 
-// ❌ Wrong - regular JS map
-Ul([items.map(item => Li(item.name))])
+// ✅ Correct
+Input({ bind: 'username' })           // Two-way binding to component data
+Input({ bind: [state, 'email'] })     // Two-way binding to external state
 ```
 
-## Commands reference
-- Dev: `npm run dev`
-- Build: `npm run build`
-- Preview: `npm run preview`
-
-## Quick Reference Card
-
-### Component Creation
+### Event Handling
 ```javascript
-// Atom (stateless)
-export const MyAtom = Atom((props, children) => (
-  Div({ class: props.class }, children)
-));
-
-// Component (stateful)
-export class MyComponent extends Component {
-  declareProps() {
-    this.items = [];
-  }
-
-  setData() {
-    return new Data({ selected: null });
-  }
+// ❌ Wrong
+Button({ onClick: () => this.submit() })  // React pattern
+Button({ onclick: () => this.submit() })  // Wrong casing
 
-  render() {
-    return Div([/* ... */]);
-  }
-}
+// ✅ Correct
+Button({ click: () => this.submit() })    // Use 'click' not 'onClick'
 ```
 
-### Icon Usage Quick Reference
+### State Management
 ```javascript
-// In Button
-Button({ variant: 'withIcon', icon: Icons.plus }, 'Add')
-
-// Standalone
-Icon({ size: 'md', class: 'text-primary' }, Icons.home)
+// ❌ Wrong
+const [isOpen, setIsOpen] = useState(false);  // React hooks
+this.isOpen = false;  // Plain property
 
-// Raw SVG
-I({ html: Icons.check, class: 'w-5 h-5' })
+// ✅ Correct
+setupStates() {
+  return { isOpen: false };
+}
+// Toggle:
+this.state.isOpen = !this.state.isOpen;
 ```
 
-### Event Handlers
+### Watchers
 ```javascript
-// Click
-Button({ click: (e) => console.log('clicked') }, 'Click')
-
-// Submit (in Form)
-Form({ submit: (e, parent) => handleSubmit(e) }, [...])
+// ❌ Wrong
+useEffect(() => { ... }, [count]);  // React pattern
+this.data.count.subscribe(val => ...);  // No such method
 
-// State-based callbacks
-Button({ onState: ['key', { key: 'value' }] }, 'State Button')
+// ✅ Correct
+render() {
+  return Div([
+    On('count', (value) => {
+      console.log('Count changed:', value);
+    })
+  ]);
+}
 ```
 
+## Commands reference
+- Dev: `npm run dev`
+- Build: `npm run build`
+- Preview: `npm run preview`
+
 If anything seems unclear (e.g., preferred binding patterns or where to export), ask for confirmation before large changes.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@base-framework/ui",
-	"version": "1.0.2030",
+	"version": "1.0.2031",
 	"description": "This is a UI package that adds components and atoms that use Tailwind CSS and a theme based on Shadcn.",
 	"main": "./dist/index.es.js",
 	"scripts": {