@base-framework/atoms 1.0.64 → 1.0.66

package/README.md

@@ -207,6 +207,152 @@ The callback function will be called when the data property changes. The callbac
 }
 ```
 
+### OnLoad and OnStateLoad Atoms
+The OnLoad and OnStateLoad atoms are specialized versions that automatically watch for a 'loaded' property. OnLoad watches component data/context/state, while OnStateLoad specifically watches component state.
+
+```javascript
+// OnLoad - watches for 'loaded' property in component data/context/state
+Div({ class: "content-container" }, [
+    H1('My Content'),
+
+    // Shows content when loaded is true, nothing when false
+    OnLoad((loaded, element, parent) =>
+        Div({ class: "loaded-content" }, [
+            P('Content has been loaded!')
+        ])
+    ),
+
+    // With a fallback for when not loaded
+    OnLoad(
+        (loaded, element, parent) =>
+            Div({ class: "loaded-content" }, [
+                P('Content loaded successfully!')
+            ]),
+        // Fallback content when not loaded
+        Div({ class: "loading-spinner" }, 'Loading...')
+    )
+])
+
+// OnStateLoad - specifically watches component state
+Div({ class: "dashboard" }, [
+    OnStateLoad((loaded, element, parent) =>
+        Dashboard({ data: parent.state.dashboardData })
+    )
+])
+```
+
+### OnOpen and OnStateOpen Atoms
+The OnOpen and OnStateOpen atoms watch for an 'open' property to show/hide content. Useful for modals, dropdowns, and collapsible content.
+
+```javascript
+// OnOpen - watches for 'open' property in component data/context/state
+Div({ class: "modal-container" }, [
+    Button({
+        click: (e, parent) => parent.data.open = true
+    }, 'Open Modal'),
+
+    // Modal only shows when open is true
+    OnOpen((open, element, parent) =>
+        Div({ class: "modal-overlay" }, [
+            Div({ class: "modal-content" }, [
+                H2('Modal Title'),
+                P('Modal content goes here'),
+                Button({
+                    click: (e, parent) => parent.data.open = false
+                }, 'Close')
+            ])
+        ])
+    )
+])
+
+// OnStateOpen - specifically watches component state
+Nav({ class: "navigation" }, [
+    Button({
+        click: (e, parent) => parent.state.open = !parent.state.open
+    }, 'Toggle Menu'),
+
+    OnStateOpen((open, element, parent) =>
+        Ul({ class: "nav-menu" }, [
+            Li(A({ href: "/home" }, 'Home')),
+            Li(A({ href: "/about" }, 'About')),
+            Li(A({ href: "/contact" }, 'Contact'))
+        ])
+    )
+])
+```
+
+### If and IfState Atoms
+The If and IfState atoms allow conditional rendering based on exact value matches. They take a property name, expected value, and callback function.
+
+```javascript
+// If - watches component data/context/state for exact value match
+Div({ class: "user-profile" }, [
+    H1('User Profile'),
+
+    // Show admin panel only when role equals 'admin'
+    If('role', 'admin', (role, element, parent) =>
+        Div({ class: "admin-panel" }, [
+            H2('Admin Controls'),
+            Button('Manage Users'),
+            Button('System Settings')
+        ])
+    ),
+
+    // Show different content based on subscription status
+    If('subscription', 'premium', (subscription, element, parent) =>
+        Div({ class: "premium-features" }, [
+            P('Premium Features Available'),
+            Button('Advanced Analytics'),
+            Button('Priority Support')
+        ])
+    ),
+
+    If('subscription', 'basic', (subscription, element, parent) =>
+        Div({ class: "upgrade-prompt" }, [
+            P('Upgrade to Premium for more features'),
+            Button('Upgrade Now')
+        ])
+    )
+])
+
+// IfState - specifically watches component state for exact matches
+Div({ class: "game-interface" }, [
+    IfState('gameStatus', 'playing', (status, element, parent) =>
+        Div({ class: "game-controls" }, [
+            Button('Pause Game'),
+            Button('Save Progress')
+        ])
+    ),
+
+    IfState('gameStatus', 'paused', (status, element, parent) =>
+        Div({ class: "pause-menu" }, [
+            Button('Resume Game'),
+            Button('Main Menu'),
+            Button('Quit Game')
+        ])
+    ),
+
+    IfState('gameStatus', 'gameOver', (status, element, parent) =>
+        Div({ class: "game-over" }, [
+            H2('Game Over!'),
+            P(`Final Score: ${parent.state.score}`),
+            Button('Play Again'),
+            Button('Main Menu')
+        ])
+    )
+])
+
+// If with custom data source
+Div({ class: "weather-widget" }, [
+    If(parent.weatherData, 'condition', 'sunny', (condition, element, parent) =>
+        Div({ class: "sunny-weather" }, [
+            Icon('sun'),
+            P('Perfect weather for outdoor activities!')
+        ])
+    )
+])
+```
+
 ### Use Parent Atom
 
 The UseParent atom allows for the parent component to be accessed in a child atom. This atom is useful when a child atom needs to access the parent component.

package/copilot.md

@@ -0,0 +1,103 @@
+# Base Atoms - AI Coding Instructions
+
+## Architecture Overview
+This is an npm package that provides atomic HTML components for the Base Framework. It exports reusable, composable atoms that serve as building blocks for component-based architecture.
+
+**Key Dependencies:**
+- `@base-framework/base`: Core framework providing `Atom`, `Builder`, and `dataBinder`
+- Built as ESM module with TypeScript declarations generated from JSDoc
+
+## Core Patterns
+
+### Atom Creation Patterns
+Two primary patterns for creating atoms:
+
+1. **Simple Function Atoms** (for basic HTML elements):
+```javascript
+const Meta = (props) => ({ ...props, tag: 'meta' });
+```
+
+2. **Atom Wrapper Functions** (for composable atoms):
+```javascript
+const Div = Atom((props, children) => Tag(props, children));
+```
+
+### Component Composition
+Atoms use composition over inheritance. Children are passed as arrays:
+```javascript
+const SecondaryButton = Atom((props, children) => Button({
+    ...props,
+    class: 'secondary-btn',
+    children
+}));
+```
+
+### Special Atoms Architecture
+Located in `/src/on/` and `/src/use/` directories:
+
+- **On Atoms**: Conditional rendering based on data binding (`On`, `OnState`, `OnRoute`)
+- **UseParent**: Provides access to parent component context
+- Use **comment placeholders** to maintain DOM position during dynamic updates
+
+## Development Workflows
+
+### Build Process
+```bash
+npm run build        # Builds dist/ with esbuild + generates TypeScript declarations
+npm run prepublishOnly  # Pre-publish build step
+```
+
+### File Structure
+- `src/atoms.js`: Main export file with all HTML element atoms
+- `src/on/on.js`: Dynamic conditional rendering atoms
+- `src/use/use.js`: Parent component access utilities
+- `src/comment.js`: Comment placeholder utility
+
+## Code Conventions
+
+### JSDoc Documentation
+All atoms require comprehensive JSDoc with proper type annotations:
+```javascript
+/**
+ * Creates a button element.
+ *
+ * @param {object} props - Properties for the element.
+ * @param {array} children - Children elements.
+ * @returns {object} - Returns an object representing the element.
+ */
+```
+
+### Event Handling Pattern
+Event callbacks receive `(event, parent)` parameters for parent component access:
+```javascript
+Button({
+    click(event, parent) {
+        // Access parent component here
+    }
+})
+```
+
+### Flexible Argument Handling
+Atoms support multiple call patterns:
+- Props only: `Div({class: 'text'})`
+- Children only: `Div('text')` or `Div([childrenArray])`
+- Both: `Div({class: 'text'}, children)`
+
+## Critical Implementation Details
+
+### Dynamic Rendering (On Atoms)
+- Use comment placeholders to maintain DOM insertion points
+- Handle previous element cleanup in `updateLayout` functions
+- Support data binding to component data, context, or state
+
+### Base Framework Integration
+- Always import `Atom` from `@base-framework/base`
+- Use `Builder.build()` and `Builder.removeNode()` for DOM manipulation
+- Leverage `dataBinder` for reactive data connections
+
+### TypeScript Support
+- Enable `allowJs: true` and `checkJs: true` in tsconfig.json
+- Generate declarations with `emitDeclarationOnly: true`
+- Map Base Framework types in `paths` configuration
+
+When working with this codebase, focus on maintaining the established patterns for atom creation, JSDoc documentation, and the flexible argument handling that allows atoms to work seamlessly within the Base Framework ecosystem.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@base-framework/atoms",
-	"version": "1.0.64",
+	"version": "1.0.66",
 	"description": "This will add default atoms to the base framework.",
 	"main": "./dist/atoms.js",
 	"scripts": {
@@ -35,7 +35,8 @@
 	"files": [
 		"package.json",
 		"readme.md",
-		"dist"
+		"dist",
+		"copilot.md"
 	],
 	"exports": {
 		"./package.json": "./package.json",