@vanilla-bean/components 1.0.0

package/styled/README.md

@@ -0,0 +1,329 @@
+# 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.

package/styled/appendStyles.js

@@ -0,0 +1,26 @@
+/**
+ * Inject CSS directly into the document head via a style element
+ * @param {string} css - Raw CSS string to inject
+ * @param {string} [id] - Optional element ID for the created style tag (enables later removal/updates)
+ * @returns {HTMLStyleElement | undefined} The created or updated style element, or undefined if no CSS provided
+ */
+export const appendStyles = (css, id) => {
+	if (!css) return undefined;
+	if (id) {
+		const existing = document.getElementById(id);
+
+		if (existing) {
+			existing.textContent = css;
+			return existing;
+		}
+	}
+
+	const style = document.createElement('style');
+
+	style.textContent = css;
+	if (id) style.id = id;
+
+	document.head.append(style);
+
+	return style;
+};

package/styled/appendStyles.test.js

@@ -0,0 +1,45 @@
+/// <reference lib="dom" />
+
+import { appendStyles } from './appendStyles';
+
+afterEach(() => {
+	document.head.querySelectorAll('style').forEach(el => el.remove());
+});
+
+describe('appendStyles', () => {
+	test('creates a style element with CSS content', () => {
+		const css = '.test { margin: 0; }';
+		const style = appendStyles(css);
+
+		expect(style.innerHTML).toContain(css);
+		expect(style.parentElement).toBe(document.head);
+	});
+
+	test('returns undefined for falsy CSS', () => {
+		expect(appendStyles('')).toBeUndefined();
+		expect(appendStyles(null)).toBeUndefined();
+		expect(appendStyles(undefined)).toBeUndefined();
+	});
+
+	test('assigns id when provided', () => {
+		const style = appendStyles('.a { color: red; }', 'my-style');
+
+		expect(style.id).toBe('my-style');
+	});
+
+	test('updates existing element when id matches', () => {
+		const style1 = appendStyles('.a { color: red; }', 'reusable');
+		const style2 = appendStyles('.a { color: blue; }', 'reusable');
+
+		expect(style1).toBe(style2);
+		expect(style2.innerHTML).toContain('color: blue');
+		expect(document.querySelectorAll('#reusable').length).toBe(1);
+	});
+
+	test('creates separate elements without id', () => {
+		appendStyles('.a { color: red; }');
+		appendStyles('.b { color: blue; }');
+
+		expect(document.head.querySelectorAll('style').length).toBe(2);
+	});
+});

package/styled/index.js

@@ -0,0 +1,4 @@
+export * from './appendStyles';
+export * from './shimCSS';
+export * from './styled';
+export * from './themeStyles';

package/styled/shimCSS.js

@@ -0,0 +1,31 @@
+import { appendStyles } from './appendStyles';
+import { themeStyles } from './themeStyles';
+
+let loadQueue = null;
+let loadListener = null;
+
+/**
+ * CSS pipeline: theme hydration → DOM injection.
+ * Batches configs queued before document load and flushes them on window load.
+ * @param {import('./themeStyles').StyleConfig} styleConfig - Configuration object with styles function and optional scope
+ */
+export const shimCSS = styleConfig => {
+	if (document.readyState === 'complete') {
+		appendStyles(themeStyles(styleConfig) || '', styleConfig.scope?.replace(/^\./, ''));
+	} else {
+		loadQueue = loadQueue || [];
+		loadQueue.push(styleConfig);
+
+		if (!loadListener) {
+			loadListener = () => {
+				loadQueue.forEach(config => appendStyles(themeStyles(config) || '', config.scope?.replace(/^\./, '')));
+
+				loadQueue = null;
+				window.removeEventListener('load', loadListener);
+				loadListener = null;
+			};
+
+			window.addEventListener('load', loadListener);
+		}
+	}
+};

package/styled/shimCSS.test.js

@@ -0,0 +1,103 @@
+/// <reference lib="dom" />
+
+import { appendStyles } from './appendStyles';
+import { themeStyles } from './themeStyles';
+
+/**
+ * shimCSS is tested via its internal pipeline because styled.test.js uses
+ * mock.module('./shimCSS') which leaks process-wide in bun, replacing the
+ * real shimCSS with a no-op for all consumers. Rather than fight the
+ * tooling, we test the actual behavior by orchestrating the same pipeline
+ * shimCSS uses: themeStyles → appendStyles.
+ */
+
+describe('shimCSS pipeline', () => {
+	beforeEach(() => {
+		document.head.querySelectorAll('style').forEach(el => el.remove());
+	});
+
+	describe('immediate processing (document complete)', () => {
+		test('themeStyles → appendStyles injects CSS into head', () => {
+			const config = {
+				styles: () => '.child { color: red; }',
+				scope: '.pipeline-test',
+			};
+
+			const style = appendStyles(themeStyles(config) || '', config.scope.replace(/^\./, ''));
+
+			expect(style).toBeTruthy();
+			expect(style.innerHTML).toContain('color: red');
+			expect(style.parentElement).toBe(document.head);
+		});
+
+		test('scope is used as style element id with dot stripped', () => {
+			const config = {
+				styles: () => 'color: blue;',
+				scope: '.scoped-id',
+			};
+
+			appendStyles(themeStyles(config) || '', config.scope.replace(/^\./, ''));
+
+			const style = document.getElementById('scoped-id');
+
+			expect(style).toBeTruthy();
+			expect(style.tagName).toBe('STYLE');
+		});
+
+		test('processes theme function styles through themeStyles', () => {
+			const config = {
+				styles: ({ colors }) => `color: ${colors.red};`,
+				scope: '.themed',
+			};
+
+			const result = themeStyles(config);
+
+			expect(typeof result).toBe('string');
+			expect(result).toContain('color:');
+		});
+	});
+
+	describe('batch processing', () => {
+		test('multiple configs can be processed and injected', () => {
+			const configs = [
+				{ styles: () => '.child { color: red; }', scope: '.batch-1' },
+				{ styles: () => '.child { color: blue; }', scope: '.batch-2' },
+			];
+
+			configs.forEach(config => appendStyles(themeStyles(config) || '', config.scope.replace(/^\./, '')));
+
+			const style1 = document.getElementById('batch-1');
+			const style2 = document.getElementById('batch-2');
+
+			expect(style1).toBeTruthy();
+			expect(style1.innerHTML).toContain('color: red');
+			expect(style2).toBeTruthy();
+			expect(style2.innerHTML).toContain('color: blue');
+		});
+	});
+
+	describe('themeStyles edge cases', () => {
+		test('returns empty string for whitespace-only styles', () => {
+			const result = themeStyles({ styles: () => '   \n\t  ' });
+
+			expect(result).toBe('');
+		});
+
+		test('returns style object directly when styles function returns object', () => {
+			const styleObj = { color: 'red', margin: '10px' };
+			const result = themeStyles({ styles: () => styleObj });
+
+			expect(result).toBe(styleObj);
+		});
+
+		test('wraps CSS in scope selector when provided', () => {
+			const result = themeStyles({
+				styles: () => 'color: red;',
+				scope: '.my-scope',
+			});
+
+			expect(result).toContain('.my-scope');
+			expect(result).toContain('color: red');
+		});
+	});
+});

package/styled/styled.js

@@ -0,0 +1,91 @@
+import { classSafeNanoid } from '../utils';
+import theme from '../theme';
+
+import { shimCSS } from './shimCSS';
+
+/**
+ * Creates Component class with embedded configuration options (no styling applied).
+ * @param {typeof import('../Component').default} BaseComponent - Component class to extend
+ * @param {object} options - Default options merged into all component instances
+ * @returns {typeof import('../Component').default} Extended component class with embedded options
+ */
+export const configured = function (BaseComponent, options = {}) {
+	return class ConfiguredComponent extends BaseComponent {
+		constructor(overlayOptions = {}, ...children) {
+			super({ ...options, ...overlayOptions }, ...children);
+
+			this.addClass(options.addClass, overlayOptions.addClass);
+		}
+	};
+};
+
+/**
+ * Creates Component class with scoped styles and optional configuration.
+ *
+ * Generates unique class identifier, processes styles through the theme system,
+ * and injects as scoped CSS. Supports both function syntax and template literal syntax.
+ * @param {typeof import('../Component').default} BaseComponent - Component class to extend
+ * @param {Function|TemplateStringsArray} [styles] - Theme function returning CSS string, or template literal strings array
+ * @param {object} [options] - Default options embedded in component instances
+ * @returns {typeof import('../Component').default|Function} Extended component class with scoped styling, or template literal function
+ */
+export const styled = function (BaseComponent, styles = () => '', options = {}) {
+	const isTagFunction = Array.isArray(styles) && styles.raw;
+
+	if (arguments.length === 1 && typeof BaseComponent === 'function') {
+		const tagFunction = function (templateLiteral, ...interpolations) {
+			if (Array.isArray(templateLiteral) && templateLiteral.raw) {
+				const styleText = templateLiteral
+					.flatMap((string, index) => {
+						if (index === 0) return string;
+
+						const interpolation = interpolations[index - 1];
+
+						return [typeof interpolation === 'function' ? interpolation(theme) : interpolation, string];
+					})
+					.join('');
+
+				const componentId = classSafeNanoid();
+
+				shimCSS({ scope: `.${componentId}`, styles: () => styleText });
+
+				return configured(BaseComponent, { addClass: [componentId] });
+			}
+
+			return styled(BaseComponent, templateLiteral, ...interpolations);
+		};
+
+		const componentId = classSafeNanoid();
+
+		const StyledComponent = configured(BaseComponent, { addClass: [componentId] });
+
+		Object.setPrototypeOf(tagFunction, StyledComponent.prototype);
+		tagFunction.prototype = StyledComponent.prototype;
+
+		return new Proxy(tagFunction, {
+			construct(target, args) {
+				return new StyledComponent(...args);
+			},
+		});
+	}
+
+	if (isTagFunction) {
+		const [, , ...args] = arguments;
+		const styleText = styles
+			.flatMap((string, index) => {
+				if (index === 0) return string;
+				return [typeof args[index - 1] === 'function' ? args[index - 1](theme) : args[index - 1], string];
+			})
+			.join('');
+
+		styles = () => styleText;
+
+		options = {};
+	}
+
+	const componentId = classSafeNanoid();
+
+	shimCSS({ scope: `.${componentId}`, styles });
+
+	return configured(BaseComponent, { ...options, addClass: [componentId].concat(options.addClass || []) });
+};