@vanilla-bean/components 1.1.0 → 2.0.0

package/devTools/createComponent.js

@@ -0,0 +1,155 @@
+import fs from 'fs';
+
+import { capitalize } from '../utils/string';
+
+if (!process.argv[2]) {
+	console.error('Usage: bun run create:component <ComponentName> [optionsJSON]');
+	process.exit(1);
+}
+
+let options = {};
+try {
+	options = process.argv[3] ? JSON.parse(process.argv[3]) : {};
+} catch {
+	console.error('Invalid JSON options:', process.argv[3]);
+	process.exit(1);
+}
+
+const name = capitalize(process.argv[2]);
+const componentFolder = `components/${name}`;
+
+if (fs.existsSync(componentFolder)) {
+	console.error(`Component '${name}' already exists at ${componentFolder}`);
+	process.exit(1);
+}
+
+fs.mkdirSync(componentFolder);
+
+const demoOptions = Object.entries(options)
+	.map(
+		([key, value]) =>
+			`${key}: ${
+				typeof value === 'object'
+					? JSON.stringify(value)
+							.replaceAll(/"(\w+)":/g, ` $1: `)
+							.replaceAll('"', `'`)
+					: value
+			},`,
+	)
+	.join('\n');
+
+const testFile = `import { ${name} } from '.';
+
+describe('${name}', () => {
+	test('renders', () => {
+		new ${name}({ appendTo: container });
+
+		expect(container.firstElementChild).toBeDefined();
+	});
+});
+`;
+
+const demoFile = `import DemoView from '../../demo/DemoView';
+import { ${name} } from '.';
+
+export default class Demo extends DemoView {
+	build() {
+		this.component = new ${name}({
+			${demoOptions}
+		});
+	}
+}
+`;
+
+const readMeFile = `# ${name}
+
+[[extract-description ${name}.js]]
+
+## Usage
+
+\`\`\`js
+[[import ./demo.js]]/^(\\t*).+component = new.+\\(\\s*{(.|\\n)+?\\1}?\\);/gm
+\`\`\`
+
+## Options
+
+[[extract-options ${name}.js]]
+
+## Methods
+
+[[extract-methods ${name}.js]]
+
+## Properties
+
+[[extract-properties ${name}.js]]
+
+## Events
+
+[[extract-events ${name}.js]]
+
+## Dependencies
+
+[[extract-imports ${name}.js]]
+
+## Design
+
+![design](../${name}/design.excalidraw.png)
+`;
+
+const componentFile = `import { Component } from '../../Component';
+
+/**
+ * [Component description - describe what this component does and its primary purpose]
+ *
+ * [Optional: Additional context about when to use this component or special behaviors]
+ *
+ * @param {object} [options={}] - Component configuration options
+ * @param {...(Component|HTMLElement|string)} children - Child elements to append
+ * @returns {${name}} Component instance with reactive options
+ * @example
+ * // Basic usage
+ * new ${name}({
+ *   // Add example options here
+ * });
+ */
+export default class ${name} extends Component {
+	/**
+	 * Creates component structure before options are processed.
+	 * Assign child elements to instance properties here so handlers can reference them.
+	 */
+	build() {
+		// Create child elements here - this runs before options are processed
+	}
+
+	// Declare the option schema once with static schema - what can exist, the defaults,
+	// and how each key routes. Descriptor fields:
+	//   default - initial value, merged automatically (child classes override per-key)
+	//   set(value, next) - change handler; omit next() to own the key, call it to continue
+	//   enum: [...] - valid values; anything else throws
+	//   attribute: true / priority: true - setAttribute routing / processed first
+	//   Declared keys with no DOM match live in this.options silently - a bare {} declares
+	//   a data-only key. data: true exists only to force store-only on DOM-name collisions.
+	//
+	// static schema = {
+	//   label: {
+	//     default: 'Untitled',
+	//     set(value) {
+	//       this.myChild.elem.textContent = value;
+	//     },
+	//   },
+	//   items: {},
+	// };
+	//
+	// Custom events: static events = ['select'];
+	// Computed defaults (no constructor needed): static prepareOptions(options, children) { return options; }
+}
+`;
+
+await Bun.write(`${componentFolder}/${name}.js`, componentFile);
+await Bun.write(`${componentFolder}/.test.js`, testFile);
+await Bun.write(`${componentFolder}/demo.js`, demoFile);
+await Bun.write(`${componentFolder}/README.md`, readMeFile);
+await Bun.write(`${componentFolder}/index.js`, `export { default as ${name} } from './${name}';`);
+
+await Bun.spawn(['bun', 'run', 'build:index']).exited;
+await Bun.spawn(['bun', 'run', 'format']).exited;

package/devTools/extractJSDoc.js

@@ -0,0 +1,395 @@
+import { readFileSync } from 'fs';
+
+/**
+ * Extracts JSDoc information from JavaScript files for documentation generation.
+ *
+ * Parses JSDoc comments and extracts component descriptions, parameters, methods,
+ * properties, and events for automated README generation.
+ * @param {string} filePath - Path to JavaScript file to parse
+ * @returns {object} Extracted JSDoc information structured for documentation templates
+ */
+export function extractJSDoc(filePath) {
+	try {
+		const content = readFileSync(filePath, 'utf8');
+
+		return {
+			description: extractDescription(content),
+			options: extractOptions(content),
+			methods: extractMethods(content),
+			properties: extractProperties(content),
+			events: extractEvents(content),
+			imports: extractImports(content),
+			examples: extractExamples(content),
+		};
+	} catch (error) {
+		console.warn(`Failed to extract JSDoc from ${filePath}:`, error.message);
+		return {
+			description: '',
+			options: [],
+			methods: [],
+			properties: [],
+			events: [],
+			imports: [],
+			examples: [],
+		};
+	}
+}
+
+/**
+ * Extracts component description from class-level JSDoc comment.
+ * @param {string} content - File content to parse
+ * @returns {string} Component description text
+ */
+function extractDescription(content) {
+	// Match class JSDoc comment - handle both export default class and class patterns
+	const classMatches = [
+		content.match(/\/\*\*\s*\n([\s\S]*?)\*\/\s*export\s+default\s+class\s+\w+/),
+		content.match(/\/\*\*\s*\n([\s\S]*?)\*\/\s*(?:export\s+)?class\s+\w+/),
+	];
+
+	const classMatch = classMatches.find(match => match);
+	if (!classMatch) return '';
+
+	const jsdoc = classMatch[1];
+
+	// Extract description (everything before first @tag)
+	const descMatch = jsdoc.match(/^\s*\*\s*(.+?)(?=\s*^\s*\*\s*@|\s*$)/ms);
+
+	if (!descMatch) return '';
+
+	// Clean up the description text - handle multi-line descriptions
+	const lines = descMatch[1].split('\n');
+	const cleanedLines = lines.map(line => line.replace(/^\s*\*\s?/, '')).filter(line => line.trim() !== '');
+
+	return cleanedLines.join(' ').replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * Extracts constructor options from JSDoc `@param` tags.
+ * @param {string} content - File content to parse
+ * @returns {Array} Array of option objects with name, type, description, and default
+ */
+function extractOptions(content) {
+	// Find class-level JSDoc (which contains constructor info) or constructor JSDoc
+	const jsDocMatches = [
+		content.match(/\/\*\*\s*\n([\s\S]*?)\*\/\s*export\s+default\s+class\s+\w+/),
+		content.match(/\/\*\*\s*\n([\s\S]*?)\*\/\s*constructor\s*\(/),
+		content.match(/\/\*\*\s*\n([\s\S]*?)\*\/\s*(?:export\s+)?class\s+\w+/),
+	];
+
+	const jsDocMatch = jsDocMatches.find(match => match);
+	if (!jsDocMatch) return [];
+
+	const jsdoc = jsDocMatch[1];
+
+	// Extract @param tags for options (handle both options.prop and direct param patterns)
+	const paramMatches = [
+		// options.property pattern
+		...jsdoc.matchAll(
+			/^\s*\*\s*@param\s+{([^}]+)}\s+(\[?options\.(\w+)(?:=([^\]]+))?\]?)\s*-\s*(.+?)(?=\s*^\s*\*\s*@|\s*^\s*\*\s*$|\s*\*\/)/gms,
+		),
+		// Direct parameter pattern (for constructor params like options={})
+		...jsdoc.matchAll(
+			/^\s*\*\s*@param\s+{([^}]+)}\s+(\[?(\w+)(?:=([^\]]+))?\]?)\s*-\s*(.+?)(?=\s*^\s*\*\s*@|\s*^\s*\*\s*$|\s*\*\/)/gms,
+		),
+	];
+
+	const codeDefaults = extractDefaultOptionsFromCode(content);
+
+	return paramMatches
+		.filter(match => match[2].includes('options.'))
+		.map(match => {
+			const [, type, fullParam, name, defaultValue, description] = match;
+			const optional = fullParam.startsWith('[') && fullParam.endsWith(']');
+			const optionName = name.replace('options.', '');
+
+			return {
+				name: optionName,
+				type: type.trim(),
+				description: description.trim().replace(/\s+/g, ' '),
+				optional,
+				default: defaultValue || codeDefaults[optionName] || null,
+				isSubProperty: fullParam.includes('options.'),
+			};
+		});
+}
+
+/**
+ * Reads the `defaultOptions` object literal from source and extracts simple key→value pairs.
+ * Only captures string, number, and boolean literals - skips getters and complex values.
+ * @param {string} content - File content
+ * @returns {object} Map of option name → default value string
+ */
+function extractDefaultOptionsFromCode(content) {
+	const defaults = {};
+	const block = content.match(/const\s+defaultOptions\s*=\s*\{([\s\S]*?)\};/);
+	if (!block) return defaults;
+
+	const pairs = [
+		...block[1].matchAll(/\b(\w+):\s*(?:'([^']*)'|"([^"]*)"|(`[^`]*`)|(-?\d+\.?\d*(?:e[+-]?\d+)?)|true|false)/g),
+	];
+
+	pairs.forEach(match => {
+		const [full, key, singleQuoted, doubleQuoted, template, number] = match;
+		if (singleQuoted !== undefined) defaults[key] = `'${singleQuoted}'`;
+		else if (doubleQuoted !== undefined) defaults[key] = `"${doubleQuoted}"`;
+		else if (template !== undefined) defaults[key] = template;
+		else if (number !== undefined) defaults[key] = number;
+		else if (full.endsWith('true')) defaults[key] = 'true';
+		else if (full.endsWith('false')) defaults[key] = 'false';
+	});
+
+	return defaults;
+}
+
+/**
+ * Extracts method information from JSDoc comments.
+ * @param {string} content - File content to parse
+ * @returns {Array} Array of method objects with name, description, parameters, and return info
+ */
+function extractMethods(content) {
+	// Match method JSDoc comments (excluding constructor and private methods)
+	// Match JSDoc comments that are within the class body, not at class level
+
+	// Find class body content (everything between class declaration and closing brace)
+	const classBodyMatch = content.match(/class\s+\w+[^{]*\{([\s\S]*)\}[^}]*$/);
+	if (!classBodyMatch) return [];
+
+	const classBody = classBodyMatch[1];
+
+	// Match each JSDoc block with the method that IMMEDIATELY follows it.
+	// `(?:(?!\/\*\*)[\s\S])*?` - non-greedy content that cannot cross into a new `/**`,
+	// so the captured block can never span multiple JSDoc comments or method bodies.
+	// get/set accessors are excluded; underscore-prefixed names are excluded.
+	const matches = [
+		...classBody.matchAll(
+			/\/\*\*((?:(?!\/\*\*)[\s\S])*?)\*\/[ \t]*\n[ \t]*(?!constructor\b)(?!get\b)(?!set\b)(?!_)(\w+)\s*\([^)]*\)\s*\{/g,
+		),
+	];
+
+	return matches.map(match => {
+		const [, jsdoc, name] = match;
+
+		// Extract description
+		const descMatch = jsdoc.match(/^\s*\*\s*(.+?)(?=\s*^\s*\*\s*@|\s*$)/ms);
+		const description = descMatch
+			? descMatch[1]
+					.split('\n')
+					.map(line => line.replace(/^\s*\*\s?/, ''))
+					.join(' ')
+					.replace(/\s+/g, ' ')
+					.trim()
+			: '';
+
+		// Extract parameters
+		const paramMatches = [
+			...jsdoc.matchAll(
+				/^\s*\*\s*@param\s+{([^}]+)}\s+(\[?(\w+)(?:=([^\]]+))?\]?)\s*-\s*(.+?)(?=\s*^\s*\*\s*@|\s*^\s*\*\s*$)/gms,
+			),
+		];
+
+		const parameters = paramMatches.map(paramMatch => {
+			const [, type, fullParam, name, defaultValue, desc] = paramMatch;
+			const optional = fullParam.startsWith('[') && fullParam.endsWith(']');
+
+			return {
+				name,
+				type: type.trim(),
+				description: desc.trim().replace(/\s+/g, ' '),
+				optional,
+				default: defaultValue || null,
+			};
+		});
+
+		// Extract return information - type only; description is not used in type generation.
+		const returnMatch = jsdoc.match(/^\s*\*\s*@returns?\s+\{([^}]+)\}/m);
+		const returnInfo = returnMatch ? { type: returnMatch[1].trim() } : null;
+
+		return {
+			name,
+			description,
+			parameters,
+			returns: returnInfo,
+		};
+	});
+}
+
+/**
+ * Extracts property information from JSDoc comments and getter methods.
+ * @param {string} content - File content to parse
+ * @returns {Array} Array of property objects with name, type, description, and access info
+ */
+function extractProperties(content) {
+	const properties = [];
+
+	// Extract getter properties - same anti-span pattern as extractMethods.
+	const getterMatches = [
+		...content.matchAll(/\/\*\*((?:(?!\/\*\*)[\s\S])*?)\*\/[ \t]*\n[ \t]*get\s+(\w+)\s*\(\)\s*\{/g),
+	];
+
+	getterMatches.forEach(match => {
+		const [, jsdoc, name] = match;
+
+		const descMatch = jsdoc.match(/^\s*\*\s*(.+?)(?=\s*^\s*\*\s*@|\s*$)/ms);
+		const description = descMatch
+			? descMatch[1]
+					.split('\n')
+					.map(line => line.replace(/^\s*\*\s?/, ''))
+					.join(' ')
+					.replace(/\s+/g, ' ')
+					.trim()
+			: '';
+
+		const returnMatch = jsdoc.match(/^\s*\*\s*@returns?\s+\{([^}]+)\}/m);
+		const type = returnMatch ? returnMatch[1].trim() : 'unknown';
+
+		properties.push({
+			name,
+			type,
+			description,
+			access: 'readonly',
+		});
+	});
+
+	// Extract documented properties (this.property assignments with JSDoc)
+	const propMatches = [...content.matchAll(/\/\*\*((?:(?!\/\*\*)[\s\S])*?)\*\/[ \t]*\n[ \t]*(?:this\.)?(\w+)\s*=/g)];
+
+	propMatches.forEach(match => {
+		const [, jsdoc, name] = match;
+
+		const descMatch = jsdoc.match(/^\s*\*\s*(.+?)(?=\s*^\s*\*\s*@|\s*$)/ms);
+		const description = descMatch
+			? descMatch[1]
+					.split('\n')
+					.map(line => line.replace(/^\s*\*\s?/, ''))
+					.join(' ')
+					.replace(/\s+/g, ' ')
+					.trim()
+			: '';
+
+		const typeMatch = jsdoc.match(/^\s*\*\s*@type\s+{([^}]+)}/m);
+		const type = typeMatch ? typeMatch[1].trim() : 'unknown';
+
+		properties.push({
+			name,
+			type,
+			description,
+			access: 'read-write',
+		});
+	});
+
+	return properties;
+}
+
+/**
+ * Extracts event information from emit() calls and JSDoc `@fires` tags.
+ * @param {string} content - File content to parse
+ * @returns {Array} Array of event objects with name and description
+ */
+function extractEvents(content) {
+	const events = [];
+
+	// Extract from emit() calls
+	const emitMatches = [...content.matchAll(/\.emit\s*\(\s*['"`]([^'"`]+)['"`]/g)];
+
+	emitMatches.forEach(match => {
+		const [, eventName] = match;
+		events.push({
+			name: eventName,
+			description: `Emitted when ${eventName} occurs`,
+		});
+	});
+
+	// Extract from dispatchEvent calls
+	const dispatchMatches = [...content.matchAll(/\.dispatchEvent\s*\(\s*new\s+CustomEvent\s*\(\s*['"`]([^'"`]+)['"`]/g)];
+
+	dispatchMatches.forEach(match => {
+		const [, eventName] = match;
+		if (!events.find(e => e.name === eventName)) {
+			events.push({
+				name: eventName,
+				description: `Custom event: ${eventName}`,
+			});
+		}
+	});
+
+	return events;
+}
+
+/**
+ * Extracts import statements to determine component dependencies.
+ * @param {string} content - File content to parse
+ * @returns {Array} Array of import objects with module and imported items
+ */
+function extractImports(content) {
+	const importMatches = [
+		...content.matchAll(/^import\s+(?:{([^}]+)}|\*\s+as\s+(\w+)|(\w+))\s+from\s+['"`]([^'"`]+)['"`];/gm),
+	];
+
+	return importMatches
+		.filter(([, , , , module]) => /^\.\.\//.test(module)) // external relative only, not same-dir ./
+		.map(match => {
+			const [, namedImports, namespaceImport, defaultImport, module] = match;
+
+			let imports = [];
+
+			if (namedImports) {
+				imports = namedImports.split(',').map(imp => imp.trim());
+			} else if (namespaceImport) {
+				imports = [`* as ${namespaceImport}`];
+			} else if (defaultImport) {
+				imports = [defaultImport];
+			}
+
+			return {
+				module: module.replace(/^(\.\.?\/)+/, ''),
+				imports,
+			};
+		});
+}
+
+/**
+ * Extracts example code from JSDoc `@example` tags.
+ * @param {string} content - File content to parse
+ * @returns {Array} Array of example objects with code and optional description
+ */
+function extractExamples(content) {
+	const examples = [];
+
+	// Find all JSDoc blocks with @example tags
+	const jsdocBlocks = [...content.matchAll(/\/\*\*\s*\n([\s\S]*?)\*\//g)];
+
+	jsdocBlocks.forEach(([, jsdoc]) => {
+		const exampleMatches = [...jsdoc.matchAll(/^\s*\*\s*@example\s*\n([\s\S]*?)(?=^\s*\*\s*@|\s*$)/gms)];
+
+		exampleMatches.forEach(([, exampleContent]) => {
+			const code = exampleContent
+				.split('\n')
+				.map(line => line.replace(/^\s*\*\s?/, ''))
+				.join('\n')
+				.trim();
+
+			if (code) {
+				examples.push({
+					code,
+					description: '', // Could extract description if needed
+				});
+			}
+		});
+	});
+
+	return examples;
+}
+
+// CLI usage
+if (import.meta.main) {
+	const filePath = process.argv[2];
+
+	if (!filePath) {
+		console.error('Usage: bun extractJSDoc.js <path-to-js-file>');
+		process.exit(1);
+	}
+
+	const result = extractJSDoc(filePath);
+	console.log(JSON.stringify(result, null, 2));
+}