@base-framework/ui 1.0.2030 → 1.0.2032

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/dist/atoms.es.js

@@ -1,5 +1,5 @@
 import { B as e, C as t, F as o, L as r, P as n, R as p, S as I, a as u, T as i } from "./tooltip-Czvqmxt3.js";
-import { B as d, I as m, L as x } from "./buttons-CHEs54Wl.js";
+import { B as d, I as m, L as x } from "./buttons-uRdH6CMH.js";
 import { C as T, F as g } from "./form-group-BB7dLJir.js";
 import { C as F, d as c, D as f, c as L, E as P, F as R, H as S, I as b, M as h, N as k, P as D, R as V, T as E, a as G, b as H, U as M, W as N } from "./inputs-9udyzkHR.js";
 import { I as W, V as w, a as J } from "./image-BB__4s0g.js";

package/dist/buttons-uRdH6CMH.js

@@ -0,0 +1,94 @@
+import { I as u, Button as r } from "@base-framework/atoms";
+import { Atom as a, Component as g } from "@base-framework/base";
+import { Icons as e } from "./icons.es.js";
+const m = {
+  xs: "w-4 h-4",
+  sm: "w-6 h-6",
+  md: "w-8 h-8",
+  lg: "w-10 h-10",
+  xl: "w-12 h-12",
+  "2xl": "w-14 h-14",
+  "3xl": "w-16 h-16"
+}, c = a((t, s) => {
+  const n = m[t.size || "sm"];
+  return u({
+    ...t,
+    class: `stroke-current icon-size ${n} ${t.class || ""}`,
+    html: s[0]?.textContent
+  });
+}), i = (t) => a((s, n) => r({
+  ...t,
+  ...s,
+  class: `bttn ${t.class} ${s.class || ""}`
+}, n)), h = a(
+  (t, s) => r({
+    ...t,
+    class: t.class
+  }, [
+    t.icon && t.position !== "right" ? c({ size: "sm", class: t.animation ?? null }, t.icon) : null,
+    ...s || [],
+    t.icon && t.position === "right" ? c({ size: "sm", class: t.animation ?? null }, t.icon) : null
+  ])
+), o = (t) => a((s, n) => h({
+  ...t,
+  ...s,
+  class: `bttn ${t.class} ${s.class || ""}`
+}, n));
+class b extends g {
+  /**
+   * This will set the start history length.
+   *
+   * @param {object} props
+   * @param {array} children
+   */
+  constructor(s, n) {
+    super(s, n), this.startHistoryLength = globalThis.history.length;
+  }
+  /**
+   * This will handle the click event.
+   *
+   * @returns {void}
+   */
+  goBack() {
+    if (this.props.allowHistory === !0 && globalThis.history.length > 1) {
+      const s = globalThis.history.length, n = this.startHistoryLength - s - 1;
+      if (n < -1) {
+        globalThis.history.go(n);
+        return;
+      }
+      globalThis.history.back();
+      return;
+    }
+    if (this.props.backUrl) {
+      app.navigate(this.props.backUrl);
+      return;
+    }
+    globalThis.history.back();
+  }
+  /**
+   * This will render the component.
+   *
+   * @returns {object}
+   */
+  render() {
+    const s = { ...this };
+    return s.icon = s.icon || e.chevron.single.left, s.click = s.click || (() => this.goBack()), h(s, this.children);
+  }
+}
+const k = (t) => ((s, n) => new b({ ...t, ...s }, n)), l = {
+  primary: i({ class: "primary" }),
+  secondary: i({ class: "secondary" }),
+  destructive: i({ class: "destructive" }),
+  warning: i({ class: "warning" }),
+  outline: i({ class: "outline" }),
+  ghost: i({ class: "ghost" }),
+  link: i({ class: "link" }),
+  icon: o({ class: "icon" }),
+  withIcon: o({ class: "with-icon" }),
+  back: k({ class: "with-icon back-button" })
+}, w = a((t, s) => (l[t.variant] || l.primary)(t, s)), I = a((t, s) => w({ ...t, variant: "withIcon", icon: e.loading, animation: "animate-spin" }, s));
+export {
+  w as B,
+  c as I,
+  I as L
+};

package/dist/{empty-state-BbkagIqj.js → empty-state-C1cQharY.js}

@@ -1,8 +1,8 @@
 import { Div as n, H5 as Z, P as b, I as x, Li as H, Span as a, Ul as q, Button as f, OnState as T, Label as P, H2 as S, Form as tt, Header as I, Footer as L, A as V, H3 as et, Checkbox as st, Input as m, Img as G, Nav as ot, UseParent as W, OnStateOpen as O, Time as nt, Dialog as rt } from "@base-framework/atoms";
 import { Atom as c, Component as w, Html as A, Dom as it, base as lt, Data as B, Builder as _, Jot as C, Events as p, DateTime as M } from "@base-framework/base";
-import { P as D, b as at, R as ct } from "./range-calendar-6CLMTieN.js";
+import { P as D, b as at, R as ct } from "./range-calendar-BfGmjXMP.js";
 import { C as dt, F as ut } from "./form-group-BB7dLJir.js";
-import { B as h, I as g } from "./buttons-CHEs54Wl.js";
+import { B as h, I as g } from "./buttons-uRdH6CMH.js";
 import { Icons as u } from "./icons.es.js";
 import { Timer as ht, List as mt, DynamicTime as ft } from "@base-framework/organisms";
 import { a as v } from "./image-BB__4s0g.js";

package/dist/index.es.js

@@ -1,14 +1,14 @@
 import { B as s, C as o, F as t, L as r, P as n, R as l, S as i, a as p, T as m } from "./tooltip-Czvqmxt3.js";
-import { B as u, I as g, L as C } from "./buttons-CHEs54Wl.js";
+import { B as u, I as g, L as C } from "./buttons-uRdH6CMH.js";
 import { C as T, F as b } from "./form-group-BB7dLJir.js";
 import { C as D, d as S, D as F, c as B, E as P, F as k, H as M, I as x, M as f, N as v, P as N, R as y, T as h, a as U, b as L, U as W, W as w } from "./inputs-9udyzkHR.js";
 import { I as R, V as A, a as G } from "./image-BB__4s0g.js";
 import { Icons as E } from "./icons.es.js";
-import { A as j, B as q, C as J, x as z, O as K, z as Q, E as _, G as X, H as Y, D as Z, m as $, n as aa, R as ea, Q as sa, w as oa, o as ta, c as ra, a as na, b as la, U as ia, l as pa, g as ma, i as da, h as ua, j as ga, e as Ca, k as ca, F as Ta, d as ba, f as Ia, I as Da, L as Sa, y as Fa, M as Ba, p as Pa, N as ka, P as Ma, t as xa, u as fa, S as va, r as Na, s as ya, T as ha, J as Ua, K as La, q as Wa, v as wa } from "./empty-state-BbkagIqj.js";
-import { A as Ra, b as Aa, C as Ga, D as Oa, a as Ea, F as Va, M as ja, P as qa, R as Ja, c as za, g as Ka, p as Qa } from "./range-calendar-6CLMTieN.js";
-import { B as Xa, p as Ya, C as Za, j as $a, D as ae, m as ee, k as se, H as oe, I as te, N as re, O as ne, P as le, S as ie, n as pe, o as me, x as de, s as ue, q as ge, r as Ce, T as ce, t as Te, w as be, u as Ie, v as De, l as Se, U as Fe, W as Be, f as Pe, h as ke, i as Me, c as xe, d as fe, b as ve, e as Ne, a as ye, g as he } from "./signature-panel-JSfsTsVc.js";
-import { B as Le, I as We, M as we, d as He, e as Re, g as Ae, N as Ge, b as Oe, a as Ee, f as Ve, P as je, c as qe, S as Je, T as ze } from "./mobile-nav-wrapper-Dm9DinRD.js";
-import { B as Qe, a as _e, C as Xe, F as Ye, b as Ze, c as $e, M as as, P as es, S as ss } from "./sidebar-menu-page-D4WMgz5U.js";
+import { A as j, B as q, C as J, x as z, O as K, z as Q, E as _, G as X, H as Y, D as Z, m as $, n as aa, R as ea, Q as sa, w as oa, o as ta, c as ra, a as na, b as la, U as ia, l as pa, g as ma, i as da, h as ua, j as ga, e as Ca, k as ca, F as Ta, d as ba, f as Ia, I as Da, L as Sa, y as Fa, M as Ba, p as Pa, N as ka, P as Ma, t as xa, u as fa, S as va, r as Na, s as ya, T as ha, J as Ua, K as La, q as Wa, v as wa } from "./empty-state-C1cQharY.js";
+import { A as Ra, b as Aa, C as Ga, D as Oa, a as Ea, F as Va, M as ja, P as qa, R as Ja, c as za, g as Ka, p as Qa } from "./range-calendar-BfGmjXMP.js";
+import { B as Xa, p as Ya, C as Za, j as $a, D as ae, m as ee, k as se, H as oe, I as te, N as re, O as ne, P as le, S as ie, n as pe, o as me, x as de, s as ue, q as ge, r as Ce, T as ce, t as Te, w as be, u as Ie, v as De, l as Se, U as Fe, W as Be, f as Pe, h as ke, i as Me, c as xe, d as fe, b as ve, e as Ne, a as ye, g as he } from "./signature-panel-9qDKGR9E.js";
+import { B as Le, I as We, M as we, d as He, e as Re, g as Ae, N as Ge, b as Oe, a as Ee, f as Ve, P as je, c as qe, S as Je, T as ze } from "./mobile-nav-wrapper-v-WRf__8.js";
+import { B as Qe, a as _e, C as Xe, F as Ye, b as Ze, c as $e, M as as, P as es, S as ss } from "./sidebar-menu-page-ClbFsXDG.js";
 import { A as ts, F as rs, M as ns, a as ls, T as is } from "./aside-template-sUm-F2f0.js";
 import { B as ms } from "./bside-template-do_hXebn.js";
 import { F as us, c as gs } from "./format-BmrNQptv.js";

package/dist/{mobile-nav-wrapper-Dm9DinRD.js → mobile-nav-wrapper-v-WRf__8.js}

@@ -1,6 +1,6 @@
 import { Button as S, I as B, Label as N, Span as L, Ul as o, H4 as C, Nav as p, Div as l, Header as y, H1 as P, H3 as h, OnState as I, UseParent as $ } from "@base-framework/atoms";
 import { Component as n, Atom as i, NavLink as H, router as d } from "@base-framework/base";
-import { I as f, B as x } from "./buttons-CHEs54Wl.js";
+import { I as f, B as x } from "./buttons-uRdH6CMH.js";
 import { Icons as r } from "./icons.es.js";
 class M extends n {
   /**

package/dist/molecules.es.js

@@ -1,5 +1,5 @@
-import { A as s, B as t, C as r, x as e, O as i, z as n, E as m, G as l, H as d, D as C, m as p, n as D, R as S, Q as g, w as u, o as c, c as F, a as T, b as P, U as w, l as A, g as I, i as f, h as b, j as y, e as B, k as M, F as U, d as k, f as x, I as L, L as R, y as v, M as E, p as N, N as h, P as G, t as O, u as j, S as q, r as z, s as H, T as J, J as K, K as Q, q as _, v as V } from "./empty-state-BbkagIqj.js";
-import { A as X, P as Y, g as Z } from "./range-calendar-6CLMTieN.js";
+import { A as s, B as t, C as r, x as e, O as i, z as n, E as m, G as l, H as d, D as C, m as p, n as D, R as S, Q as g, w as u, o as c, c as F, a as T, b as P, U as w, l as A, g as I, i as f, h as b, j as y, e as B, k as M, F as U, d as k, f as x, I as L, L as R, y as v, M as E, p as N, N as h, P as G, t as O, u as j, S as q, r as z, s as H, T as J, J as K, K as Q, q as _, v as V } from "./empty-state-C1cQharY.js";
+import { A as X, P as Y, g as Z } from "./range-calendar-BfGmjXMP.js";
 export {
   s as Alert,
   X as Avatar,

package/dist/organisms.es.js

@@ -1,6 +1,6 @@
-import { B as s, p as n, C as t, j as o, D as r, m as l, k as i, H as d, I as b, N as u, O as v, P as g, S as p, n as T, o as D, x as N, s as k, q as C, r as c, T as B, t as M, w as m, u as y, v as W, l as h, U as S, W as H, f as P, h as U, i as x, c as I, d as f, b as L, e as O, a as F, g as G } from "./signature-panel-JSfsTsVc.js";
-import { b as R, C as j, D as q, a as z, F as A, M as E, R as J, c as K, p as Q } from "./range-calendar-6CLMTieN.js";
-import { B as X, I as Y, M as Z, d as _, e as $, g as aa, N as ea, b as sa, a as na, f as ta, P as oa, c as ra, S as la, T as ia } from "./mobile-nav-wrapper-Dm9DinRD.js";
+import { B as s, p as n, C as t, j as o, D as r, m as l, k as i, H as d, I as b, N as u, O as v, P as g, S as p, n as T, o as D, x as N, s as k, q as C, r as c, T as B, t as M, w as m, u as y, v as W, l as h, U as S, W as H, f as P, h as U, i as x, c as I, d as f, b as L, e as O, a as F, g as G } from "./signature-panel-9qDKGR9E.js";
+import { b as R, C as j, D as q, a as z, F as A, M as E, R as J, c as K, p as Q } from "./range-calendar-BfGmjXMP.js";
+import { B as X, I as Y, M as Z, d as _, e as $, g as aa, N as ea, b as sa, a as na, f as ta, P as oa, c as ra, S as la, T as ia } from "./mobile-nav-wrapper-v-WRf__8.js";
 export {
   s as BackButton,
   X as Backdrop,

package/dist/pages.es.js

@@ -1,4 +1,4 @@
-import { B as s, a as P, C as g, F as n, b as l, c as i, M as r, P as c, S as o } from "./sidebar-menu-page-D4WMgz5U.js";
+import { B as s, a as P, C as g, F as n, b as l, c as i, M as r, P as c, S as o } from "./sidebar-menu-page-ClbFsXDG.js";
 export {
   s as BasicPage,
   P as BlankPage,

package/dist/{range-calendar-6CLMTieN.js → range-calendar-BfGmjXMP.js}

@@ -1,7 +1,7 @@
 import { Div as h, Span as H, Button as _, OnState as J, On as z } from "@base-framework/atoms";
 import { Component as Y, Data as B, Atom as j, DateTime as T } from "@base-framework/base";
 import { I as L } from "./image-BB__4s0g.js";
-import { B as f } from "./buttons-CHEs54Wl.js";
+import { B as f } from "./buttons-uRdH6CMH.js";
 import { Icons as P } from "./icons.es.js";
 const U = (e, t) => {
   const n = e ? e.getBoundingClientRect() : { top: 0, bottom: 0, left: 0 }, a = t.getBoundingClientRect(), s = 10, r = globalThis.scrollX, l = globalThis.scrollY;

package/dist/{sidebar-menu-page-D4WMgz5U.js → sidebar-menu-page-ClbFsXDG.js}

@@ -1,7 +1,7 @@
 import { Div as t, Header as n, H1 as d, P as o } from "@base-framework/atoms";
 import { F as l, A as x } from "./aside-template-sUm-F2f0.js";
 import { Component as h, Atom as i } from "@base-framework/base";
-import { c as u, e as p } from "./mobile-nav-wrapper-Dm9DinRD.js";
+import { c as u, e as p } from "./mobile-nav-wrapper-v-WRf__8.js";
 class c extends h {
   /**
    * This will declare the props for the compiler.

package/dist/{signature-panel-JSfsTsVc.js → signature-panel-9qDKGR9E.js}

@@ -1,10 +1,10 @@
 import { Button as w, Div as o, On as C, Span as L, Th as N, UseParent as E, I as Q, Thead as V, Tr as G, Table as B, P as v, Li as y, Time as X, Nav as m, Ul as f, Section as I, Canvas as q } from "@base-framework/atoms";
 import { Atom as d, Component as p, Data as T, DateTime as K, router as k, NavLink as M, DataTracker as U, Jot as _, base as O, Dom as W } from "@base-framework/base";
-import { B as P, I as J } from "./buttons-CHEs54Wl.js";
+import { B as P, I as J } from "./buttons-uRdH6CMH.js";
 import { Icons as S } from "./icons.es.js";
 import { TableBody as Z, DataTableBody as ee, ScrollableTableBody as te, List as se, IntervalTimer as ae } from "@base-framework/organisms";
 import { C as ie, I as ne, H as oe } from "./inputs-9udyzkHR.js";
-import { A as le, P as re } from "./range-calendar-6CLMTieN.js";
+import { A as le, P as re } from "./range-calendar-BfGmjXMP.js";
 import { V as g } from "./image-BB__4s0g.js";
 d((t, e) => ({
   class: "flex items-center px-4 py-2",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@base-framework/ui",
-	"version": "1.0.2030",
+	"version": "1.0.2032",
 	"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": {

package/dist/buttons-CHEs54Wl.js

@@ -1,61 +0,0 @@
-import { I as u, Button as e } from "@base-framework/atoms";
-import { Atom as c } from "@base-framework/base";
-import { Icons as r } from "./icons.es.js";
-const m = {
-  xs: "w-4 h-4",
-  sm: "w-6 h-6",
-  md: "w-8 h-8",
-  lg: "w-10 h-10",
-  xl: "w-12 h-12",
-  "2xl": "w-14 h-14",
-  "3xl": "w-16 h-16"
-}, s = c((n, t) => {
-  const a = m[n.size || "sm"];
-  return u({
-    ...n,
-    class: `stroke-current icon-size ${a} ${n.class || ""}`,
-    html: t[0]?.textContent
-  });
-}), i = (n) => c((t, a) => e({
-  ...n,
-  ...t,
-  class: `bttn ${n.class} ${t.class || ""}`
-}, a)), h = c(
-  (n, t) => e({
-    ...n,
-    class: n.class
-  }, [
-    n.icon && n.position !== "right" ? s({ size: "sm", class: n.animation ?? null }, n.icon) : null,
-    ...t || [],
-    n.icon && n.position === "right" ? s({ size: "sm", class: n.animation ?? null }, n.icon) : null
-  ])
-), l = (n) => c((t, a) => h({
-  ...n,
-  ...t,
-  class: `bttn ${n.class} ${t.class || ""}`
-}, a)), g = (n) => () => {
-  if (n.allowHistory === !0 && globalThis.history.length > 2) {
-    globalThis.history.back();
-    return;
-  }
-  n.backUrl && app.navigate(n.backUrl);
-}, w = (n) => c((t, a) => (t.icon = t.icon || r.chevron.single.left, t.click = t.click || g(t), h({
-  ...n,
-  ...t
-}, a))), o = {
-  primary: i({ class: "primary" }),
-  secondary: i({ class: "secondary" }),
-  destructive: i({ class: "destructive" }),
-  warning: i({ class: "warning" }),
-  outline: i({ class: "outline" }),
-  ghost: i({ class: "ghost" }),
-  link: i({ class: "link" }),
-  icon: l({ class: "icon" }),
-  withIcon: l({ class: "with-icon" }),
-  back: w({ class: "with-icon back-button" })
-}, k = c((n, t) => (o[n.variant] || o.primary)(n, t)), y = c((n, t) => k({ ...n, variant: "withIcon", icon: r.loading, animation: "animate-spin" }, t));
-export {
-  k as B,
-  s as I,
-  y as L
-};