@vanilla-bean/components 1.0.2 → 1.1.1

package/Elem/README.md

@@ -1,373 +0,0 @@
-# Elem
-
-Enhanced DOM element wrapper providing fluent API methods while maintaining direct access to the underlying HTMLElement.
-
-## Basic Usage
-
-### Simple Element Creation
-
-Create DOM elements with enhanced manipulation capabilities:
-
-```js
-import { Elem } from '@vanilla-bean/components';
-
-const button = new Elem({
-	tag: 'button',
-	textContent: 'Click me',
-	className: 'btn btn-primary',
-	onclick: () => alert('Clicked!'),
-	appendTo: document.body,
-});
-```
-
-### Complex Nested Structures
-
-Build complex DOM hierarchies with nested elements:
-
-```js
-const card = new Elem(
-	{
-		tag: 'div',
-		className: 'card',
-		style: { padding: '20px', margin: '10px' },
-	},
-	new Elem({ tag: 'h3', textContent: 'Card Title' }),
-	new Elem({ tag: 'p', textContent: 'Card content goes here.' }),
-);
-```
-
-### Method Chaining
-
-Chain methods for fluent DOM construction:
-
-```js
-const navigation = new Elem({ tag: 'nav' })
-	.addClass('menu', 'horizontal')
-	.setStyle({ display: 'flex', gap: '16px' })
-	.append(
-		new Elem({ tag: 'a', textContent: 'Home', href: '/' }),
-		new Elem({ tag: 'a', textContent: 'About', href: '/about' }),
-		new Elem({ tag: 'a', textContent: 'Contact', href: '/contact' }),
-	)
-	.appendTo(document.body);
-```
-
-### Direct DOM Access
-
-Access the full HTMLElement API when needed:
-
-```js
-const input = new Elem({ tag: 'input', type: 'text' });
-
-// Enhanced methods
-input.addClass('form-control').setStyle({ width: '100%' });
-
-// Direct DOM access
-input.elem.focus();
-input.elem.select();
-input.elem.scrollIntoView({ behavior: 'smooth' });
-```
-
-## Configuration Options
-
-### Constructor Syntax
-
-```js
-new Elem(options?, ...children)
-```
-
-**Parameters:**
-
-- `options` (Object) - Configuration options and HTML properties
-- `children` (...Elem|HTMLElement|string) - Child elements or text content
-
-### Core Options
-
-| Option       | Type                        | Description                        |
-| ------------ | --------------------------- | ---------------------------------- |
-| `tag`        | `string`                    | HTML tag name (default: 'div')     |
-| `style`      | `object`                    | CSS properties as key-value pairs  |
-| `attributes` | `object`                    | HTML attributes as key-value pairs |
-| `content`    | `string\|Elem\|HTMLElement` | Element content                    |
-| `appendTo`   | `Elem\|HTMLElement`         | Parent element to append to        |
-| `prependTo`  | `Elem\|HTMLElement`         | Parent element to prepend to       |
-| `append`     | `Array`                     | Child elements to append           |
-| `prepend`    | `Array`                     | Child elements to prepend          |
-
-### HTML Properties
-
-All standard HTMLElement properties work as options:
-
-```js
-new Elem({
-	// Content properties
-	textContent: 'Button text',
-	innerHTML: '<span>HTML content</span>',
-
-	// Form properties
-	value: 'input value',
-	checked: true,
-	disabled: false,
-
-	// Element properties
-	id: 'unique-id',
-	className: 'btn primary',
-	title: 'Tooltip text',
-
-	// Link properties
-	href: 'https://example.com',
-	target: '_blank',
-
-	// Image properties
-	src: 'image.jpg',
-	alt: 'Image description',
-});
-```
-
-### Event Handler Properties
-
-Event handlers can be assigned directly:
-
-```js
-new Elem({
-	tag: 'button',
-	onclick: event => console.log('clicked'),
-	onmouseover: event => console.log('hover'),
-	onchange: event => console.log('changed'),
-	onfocus: event => console.log('focused'),
-});
-```
-
-## DOM Manipulation
-
-### Content Management
-
-```js
-// Set content (replaces existing)
-elem.content('New text content');
-elem.content(new Elem({ tag: 'span', textContent: 'HTML element' }));
-
-// Clear all content
-elem.empty();
-```
-
-### Child Element Management
-
-```js
-// Add children
-elem.append(child1, child2, 'text content');
-elem.prepend(child1, child2);
-
-// Access children
-const childElements = elem.children; // Array of Elem instances
-const nativeChildren = elem.elem.children; // HTMLCollection
-```
-
-### Hierarchy Management
-
-```js
-// Add to DOM
-elem.appendTo(document.body);
-elem.prependTo(document.querySelector('.container'));
-
-// Navigate hierarchy
-const parentElem = elem.parent; // Parent Elem instance (if exists)
-const nativeParent = elem.parentElem; // Parent HTMLElement
-```
-
-### Style and Attribute Management
-
-```js
-// Set multiple styles
-elem.setStyle({
-	color: 'red',
-	fontSize: '16px',
-	backgroundColor: '#f0f0f0',
-});
-
-// Set multiple attributes
-elem.setAttributes({
-	'data-id': '123',
-	'aria-label': 'Close button',
-	role: 'button',
-});
-```
-
-## Class Management
-
-### Enhanced Class Operations
-
-Elem provides enhanced class manipulation with regular expression support:
-
-```js
-// Check for classes
-elem.hasClass('active'); // Check single class
-elem.hasClass('btn', 'primary'); // Check multiple classes
-elem.hasClass(/^btn-/); // Check with regex pattern
-
-// Add classes
-elem.addClass('new-class');
-elem.addClass('class1', 'class2', 'class3');
-
-// Remove classes
-elem.removeClass('old-class');
-elem.removeClass(/^temp-/); // Remove all classes starting with 'temp-'
-elem.removeClass(/\bmobile-\w+/g); // Remove classes matching pattern
-
-// Toggle class based on a condition (add when true, remove when false)
-elem.toggleClass('active', isActive);
-```
-
-### Class Manipulation Examples
-
-```js
-const button = new Elem({ tag: 'button', className: 'btn btn-primary temp-123' });
-
-// Remove all temporary classes
-button.removeClass(/^temp-/);
-
-// Add state classes
-button.addClass('btn-large', 'btn-rounded');
-
-// Conditional classes
-if (isActive) {
-	button.addClass('active', 'selected');
-}
-
-// Check for button variants
-if (button.hasClass(/^btn-(primary|secondary|danger)$/)) {
-	console.log('Has button variant class');
-}
-```
-
-## Event Handling
-
-### EventTarget Integration
-
-Elem extends EventTarget, providing full event capabilities:
-
-```js
-const button = new Elem({ tag: 'button', textContent: 'Click me' });
-
-// Option-based event handlers
-new Elem({
-	tag: 'input',
-	onchange: event => console.log('Value changed:', event.target.value),
-	onfocus: event => event.target.select(),
-});
-
-// addEventListener method
-button.addEventListener('click', event => {
-	console.log('Button clicked');
-});
-
-// Custom events
-button.addEventListener('customEvent', event => {
-	console.log('Custom event data:', event.detail);
-});
-
-// Dispatch events
-button.dispatchEvent(
-	new CustomEvent('customEvent', {
-		detail: { message: 'Hello' },
-	}),
-);
-```
-
-### Event Handler Options vs Methods
-
-```js
-// Via constructor options (preferred for initial setup)
-const elem = new Elem({
-	tag: 'button',
-	onclick: handleClick,
-	onmouseover: handleHover,
-});
-
-// Via addEventListener (preferred for dynamic binding)
-elem.addEventListener('click', handleClick);
-elem.addEventListener('mouseover', handleHover);
-
-// Via native element
-elem.elem.addEventListener('click', handleClick);
-```
-
-## API Reference
-
-### Constructor
-
-```js
-new Elem(options?, ...children)
-```
-
-### Core Methods
-
-#### Content Methods
-
-```js
-elem.content(content); // Set element content
-elem.empty(); // Remove all child elements
-```
-
-#### Child Management Methods
-
-```js
-elem.append(...children); // Append child elements
-elem.prepend(...children); // Prepend child elements
-elem.appendTo(parent); // Append to parent element
-elem.prependTo(parent); // Prepend to parent element
-```
-
-#### Style and Attribute Methods
-
-```js
-elem.setStyle(styles); // Set CSS properties
-elem.setAttributes(attributes); // Set HTML attributes
-elem.setOptions(options); // Set multiple options at once
-```
-
-#### Class Methods
-
-```js
-elem.hasClass(...classes); // Check for classes (supports regex)
-elem.addClass(...classes); // Add CSS classes
-elem.removeClass(...classes); // Remove CSS classes (supports regex)
-elem.toggleClass(className, condition); // Add when condition is true, remove when false
-```
-
-### Properties
-
-```js
-elem.elem; // Underlying HTMLElement
-elem.parent; // Parent Elem instance (if created by Elem)
-elem.parentElem; // Parent HTMLElement
-elem.children; // Array of child Elem instances
-elem.options; // Configuration options object
-```
-
-### Utility Methods
-
-```js
-elem.toString(); // Returns '[object Elem]'
-```
-
-## Integration with Component
-
-Elem serves as the foundation for the Component class:
-
-```js
-import { Component } from '@vanilla-bean/components';
-
-// Component extends Elem with reactive options
-const component = new Component({
-	tag: 'div',
-	textContent: 'I am reactive!',
-});
-
-// All Elem methods available
-component.addClass('component-class');
-component.setStyle({ padding: '16px' });
-
-// Plus Component-specific features
-component.options.textContent = 'Updated reactively!';
-```

package/styled/README.md

@@ -1,329 +0,0 @@
-# styled
-
-Create Component subclasses with scoped CSS: each `styled()` call generates a unique class, processes the theme, and injects a `<style>` element into `<head>`.
-
-## Basic Usage
-
-### Template Literal Syntax
-
-Create styled components using template literals with theme integration:
-
-```js
-const StyledIcon = styled.Icon`
-	background-color: ${({ colors }) => colors.black};
-	width: 24px;
-	height: 24px;
-
-	&:before {
-		${({ fonts }) => fonts.fontAwesomeSolid}
-		content: "\f015";
-	}
-`;
-```
-
-### Function Syntax with Configuration
-
-Use function syntax when you need to pass component configuration options:
-
-```js
-const ConfiguredComponent = styled(
-	Component,
-	({ colors }) => `
-    background-color: ${colors.black};
-    color: ${colors.lighter(colors.blue)};
-    padding: 12px;
-
-    &:hover {
-      background-color: ${colors.dark(colors.blue)};
-    }
-  `,
-	{
-		tag: 'section',
-		role: 'banner',
-		textContent: 'Default Text',
-	},
-);
-```
-
-### Named Component Shortcuts
-
-All top-level components are available as shorthand methods:
-
-```js
-const StyledButton = styled.Button`
-	background-color: ${({ colors }) => colors.green};
-	border-radius: 8px;
-`;
-
-const StyledInput = styled.Input`
-	${({ fonts }) => fonts.kodeMono}
-	border: 2px solid ${({ colors }) => colors.blue};
-`;
-```
-
-**Note**: Template literal syntax creates components with empty configuration. Use function syntax to pass component options.
-
-## Theme Integration
-
-Style functions receive the complete theme object containing colors, fonts, and component styles:
-
-```js
-const ThemedComponent = styled.Component`
-	${({ button }) => button} /* Apply base button styles */
-  ${({ fonts }) => fonts.kodeMono}
-  background: ${({ colors }) => colors.darker(colors.blue)};
-	color: ${({ colors }) => colors.mostReadable(colors.blue, [colors.white, colors.black])};
-`;
-```
-
-### Runtime Style Override
-
-Override or extend styles when creating component instances:
-
-```js
-const instance = new StyledComponent({
-	styles: ({ colors }) => ({
-		backgroundColor: colors.red,
-		border: `2px solid ${colors.darker(colors.red)}`,
-	}),
-});
-```
-
-Object-based styles apply as inline styles. Function-based styles generate scoped CSS.
-
-## Component Inheritance
-
-### Extending Styled Components
-
-Build component hierarchies by extending existing styled components:
-
-```js
-const BaseButton = styled.Button`
-	padding: 8px 16px;
-	border-radius: 4px;
-`;
-
-const PrimaryButton = styled(BaseButton)`
-	background: ${({ colors }) => colors.blue};
-	color: ${({ colors }) => colors.white};
-`;
-```
-
-### Template Literals with Any Styled Component
-
-Template literal syntax works with any styled component, including those created with function syntax:
-
-```js
-const BaseComponent = styled(Component, () => 'color: red;');
-
-// Extend any styled component with template literals
-const ExtendedComponent = styled(BaseComponent)`
-	background: ${({ colors }) => colors.blue};
-	padding: 16px;
-`;
-
-// Use in class definitions for custom methods
-class MyComponent extends (styled(BaseComponent)`
-	font-weight: bold;
-	border-radius: 4px;
-`) {
-	// Add custom methods here
-}
-```
-
-### Component Functionality Inheritance
-
-Styled components inherit all functionality from their base component:
-
-```js
-const StyledInput = styled.Input`
-	border: 2px solid ${({ colors }) => colors.blue};
-`;
-
-const instance = new StyledInput({
-	value: 'initial value',
-	onChange: event => console.log(event.value),
-	placeholder: 'Enter text...',
-});
-```
-
-## CSS Processing
-
-### Native CSS Nesting
-
-Styles are injected as written, no transformation, no runtime compilation. VBC requires Chrome 112+, Firefox 117+, and Safari 16.5+, all of which support the `&` nesting syntax natively.
-
-```js
-const NestedComponent = styled.Component`
-	padding: 16px;
-
-	& .child {
-		margin: 8px;
-
-		&:hover {
-			background: ${({ colors }) => colors.blue};
-		}
-	}
-
-	@media (max-width: 768px) {
-		padding: 8px;
-	}
-`;
-```
-
-### Automatic Scoping
-
-Each styled component receives a unique class identifier to prevent CSS conflicts:
-
-```js
-const StyledDiv = styled(Component, () => `color: red;`);
-const instance = new StyledDiv();
-
-// Generated CSS: .a1b2c3d4 { color: red; }
-// Component class: "a1b2c3d4"
-```
-
-### Conditional Styles
-
-Apply conditional styles using CSS classes and selectors:
-
-```js
-const ConditionalComponent = styled.Component`
-	padding: 12px;
-	background: ${({ colors }) => colors.white};
-
-	&.active {
-		background: ${({ colors }) => colors.blue};
-		color: ${({ colors }) => colors.white};
-	}
-
-	&.disabled {
-		opacity: 0.5;
-		pointer-events: none;
-	}
-`;
-
-const instance = new ConditionalComponent({
-	addClass: 'active',
-	textContent: 'Active Button',
-});
-```
-
-## Performance
-
-### Processing Pipeline
-
-The styled system processes styles through this pipeline:
-
-1. **Component Creation** - Generates unique class identifier via `classSafeNanoid()`
-2. **Style Processing** - Converts template literals into theme functions
-3. **Theme Application** - Injects complete theme object into style functions
-4. **CSS Processing** - Processes styles through `shimCSS()` pipeline
-5. **DOM Injection** - Injects final CSS via `appendStyles()`
-
-### Load-Time Optimization
-
-Style processing timing depends on document state:
-
-| Document State      | Behavior                                   |
-| ------------------- | ------------------------------------------ |
-| Complete            | Processes and injects immediately          |
-| Loading             | Queues for batch processing on window load |
-| Multiple Components | Batches together for efficiency            |
-
-```js
-// Document loaded - processes immediately
-const StyledComponent = styled(Component, () => 'color: red;');
-
-// Document loading - queued for batch processing
-const AnotherStyled = styled(Component, () => 'color: blue;');
-```
-
-## API Reference
-
-### styled(BaseComponent, styles?, options?)
-
-Creates a styled component class.
-
-**Parameters:**
-
-- `BaseComponent` (Function) - Component class to extend
-- `styles` (Function|String) - Style function or CSS string
-- `options` (Object) - Component configuration options
-
-**Returns:** Extended component class with scoped styling
-
-### configured(BaseComponent, options)
-
-Creates a component with configuration but no styles:
-
-```js
-const ConfiguredComponent = configured(Component, {
-	tag: 'article',
-	role: 'main',
-	textContent: 'Default Content',
-});
-```
-
-### Utility Functions
-
-#### appendStyles(css, id?)
-
-Inject CSS directly into the page:
-
-```js
-appendStyles(
-	`
-  .my-global-class {
-    font-weight: bold;
-    color: red;
-  }
-`,
-	'my-global-styles',
-);
-```
-
-#### themeStyles({ styles, scope })
-
-Generate themed CSS with optional scoping:
-
-```js
-const themedCSS = themeStyles({
-	styles: ({ colors }) => `color: ${colors.white}; background: ${colors.black};`,
-	scope: '.my-component',
-});
-// Returns: ".my-component { color: hsl(0, 0%, 90%); background: hsl(0, 0%, 10%); }"
-```
-
-#### shimCSS(styleConfig)
-
-Complete style processing pipeline:
-
-```js
-shimCSS({
-	styles: ({ colors }) => `
-    display: flex;
-    background: ${colors.blue};
-    & .item { padding: 8px; }
-  `,
-	scope: '.my-scoped-component',
-});
-```
-
-## Development Features
-
-### Debug Class Names
-
-Development mode adds inheritance-based class names for easier debugging:
-
-```js
-// Development classes: "a1b2c3 MyCustomComponent Component Elem"
-class MyCustomComponent extends Component {}
-const StyledCustom = styled(MyCustomComponent, () => 'color: blue;');
-```
-
-### Memory Management
-
-Class-level styles injected by `styled()` persist for the page lifetime. They are scoped to a unique class and do not interfere with other components, but are not removed when instances disconnect.
-
-Per-instance styles set via the `styles` option on a component instance are cleaned up when that component disconnects from the DOM.