@vanilla-bean/components 1.0.0

package/components/TooltipWrapper/TooltipWrapper.lld.md

@@ -0,0 +1,21 @@
+# TooltipWrapper
+
+> ./TooltipWrapper.js
+
+Component that adds a tooltip to whatever it wraps. The Tooltip is created during the first `_setOption('tooltip', ...)` call, which runs during render, so it exists after construction but is only shown on hover after a 700ms delay.
+
+## The tooltip exists after construction with a tooltip option
+
+- the Tooltip component is created when the `tooltip` option is processed during render; after construction it exists as `this._tooltip`
+  - does the Tooltip component exist after construction with a tooltip option?
+
+## Hover shows after a delay — brief mouse-overs do not trigger the tooltip
+
+- pointerover registers a 700ms timer; pointerout cancels it and hides immediately; hovering for longer than 700ms shows the tooltip
+  - does hovering for longer than 700ms show the tooltip?
+  - does leaving before 700ms prevent the tooltip from appearing?
+
+## Cleanup removes the tooltip element — nothing outlives the component
+
+- when the TooltipWrapper is destroyed, the Tooltip component is also destroyed and removed from the DOM
+  - does destroying the wrapper also remove the tooltip from the DOM?

package/components/TooltipWrapper/index.js

@@ -0,0 +1 @@
+export { default as TooltipWrapper } from './TooltipWrapper';

package/components/Whiteboard/Whiteboard.js

@@ -0,0 +1,198 @@
+import { throttle } from '../../utils/data';
+import { Component } from '../../Component';
+
+const defaultOptions = {
+	tag: 'canvas',
+	background: '#FFF',
+	color: '#000',
+	lineWidth: 3,
+	width: '200px',
+	height: '200px',
+	readOnly: false,
+	registeredEvents: new Set(['line', 'draw']),
+};
+
+/**
+ * Interactive drawing canvas component with multi-touch support and line rendering.
+ *
+ * Provides a drawing surface with pointer event handling, configurable drawing settings,
+ * and the ability to render predefined lines. Supports multiple simultaneous drawing pointers.
+ * @param {object} [options={}] - Whiteboard configuration options
+ * @param {string} [options.tag='canvas'] - HTML tag, uses canvas element
+ * @param {string} [options.background='#FFF'] - Canvas background color
+ * @param {string} [options.color='#000'] - Default drawing color
+ * @param {number} [options.lineWidth=3] - Default line width for drawing
+ * @param {string} [options.width='200px'] - Canvas width
+ * @param {string} [options.height='200px'] - Canvas height
+ * @param {boolean} [options.readOnly=false] - Whether drawing is disabled
+ * @param {Array<object>} [options.lines] - Predefined lines to render on the canvas
+ * @param {number} [options.drawThrottle] - Custom throttle delay for draw events
+ * @param {...(Component|HTMLElement|string)} children - Child elements to append
+ * @returns {Whiteboard} Whiteboard component instance
+ */
+export default class Whiteboard extends Component {
+	defaultOptions = { ...super.defaultOptions, ...defaultOptions };
+
+	constructor(options = {}, ...children) {
+		super(
+			{
+				...defaultOptions,
+				...options,
+				style: {
+					cursor: 'crosshair',
+					touchAction: 'none',
+					borderRadius: '3px',
+					...options.style,
+				},
+			},
+			...children,
+		);
+	}
+
+	build() {
+		this.canvas = this.elem.getContext('2d');
+
+		this.pointers = {};
+
+		const boundInteractionInit = this.interactionInit.bind(this);
+		this.elem.addEventListener('pointerdown', boundInteractionInit);
+		this.replaceCleanup('pointerdown', () => this.elem.removeEventListener('pointerdown', boundInteractionInit));
+	}
+
+	static handlers = {
+		width(value) {
+			this.elem.width = Number.parseInt(value);
+			this.elem.style.width = value;
+		},
+		height(value) {
+			this.elem.height = Number.parseInt(value);
+			this.elem.style.height = value;
+		},
+		lines(value) {
+			value.forEach(line => this.drawLine(line));
+		},
+		background(value) {
+			this.elem.style.background = value;
+		},
+	};
+
+	getPosition({ offsetX, offsetY }) {
+		return { x: offsetX.toFixed(3), y: offsetY.toFixed(3) };
+	}
+
+	interactionInit(event) {
+		if (this.options.readOnly) return;
+
+		event.preventDefault();
+
+		const { pointerId } = event;
+		const { x, y } = this.getPosition(event);
+
+		this.pointers[pointerId] = { x, y, line: [{ x, y }] };
+
+		this.activePointerCount = Object.values(this.pointers).filter(_ => !!_).length;
+
+		if (this.pointerInteracting) return;
+
+		this.pointers[pointerId].initiator = true;
+		this.pointerInteracting = true;
+
+		const move = throttle(
+			(event => {
+				if (this.options.readOnly || !this.pointers[event.pointerId]) return;
+
+				event.preventDefault();
+
+				this.drawEvent.call(this, event);
+			}).bind(this),
+			this.options.drawThrottle || Math.max(Math.min(this.options.lineWidth + 3, 24), 6),
+		);
+		const removePointer = event => {
+			if (!this.pointers[event.pointerId]) return;
+
+			event.preventDefault();
+
+			this.emit('line', {
+				event,
+				color: this.options.color,
+				width: this.options.lineWidth,
+				line: this.pointers[event.pointerId].line,
+			});
+
+			if (this.pointers[event.pointerId].line.length === 0) this.drawEvent(event, true);
+
+			delete this.pointers[event.pointerId];
+			this.activePointerCount = Object.values(this.pointers).filter(_ => !!_).length;
+
+			if (this.activePointerCount === 0) {
+				this.pointerInteracting = false;
+
+				document.removeEventListener('pointermove', move);
+				document.removeEventListener('pointerup', removePointer);
+				document.removeEventListener('pointerleave', removePointer);
+				document.removeEventListener('pointercancel', removePointer);
+			}
+		};
+
+		document.addEventListener('pointermove', move);
+		document.addEventListener('pointerup', removePointer);
+		document.addEventListener('pointerleave', removePointer);
+		document.addEventListener('pointercancel', removePointer);
+
+		this.replaceCleanup('gestureListeners', () => {
+			document.removeEventListener('pointermove', move);
+			document.removeEventListener('pointerup', removePointer);
+			document.removeEventListener('pointerleave', removePointer);
+			document.removeEventListener('pointercancel', removePointer);
+		});
+	}
+
+	drawEvent(event, cap = false) {
+		const { pointerId } = event;
+
+		if (!this.pointers[pointerId]) return;
+
+		const to = this.getPosition(event);
+		const { x, y } = this.pointers[pointerId];
+		const from = { x, y };
+
+		this.drawLine({ color: this.options.color, width: this.options.lineWidth, line: [from, to], cap });
+
+		this.pointers[pointerId].line.push(to);
+
+		this.emit('draw', { event, cap, from, to });
+
+		this.pointers[pointerId].x = to.x;
+		this.pointers[pointerId].y = to.y;
+	}
+
+	/**
+	 * Draws a line on the canvas with specified properties.
+	 * @param {object} options - Line drawing options
+	 * @param {string} options.color - Line color
+	 * @param {number} options.width - Line width
+	 * @param {Array<object>} options.line - Array of {x, y} points defining the line
+	 * @param {boolean} [options.cap] - Whether to close the path after drawing
+	 */
+	drawLine({ color, width, line, cap = true }) {
+		if (line.length === 0) return;
+
+		this.canvas.strokeStyle = color;
+		this.canvas.lineWidth = width;
+		this.canvas.lineJoin = 'round';
+		this.canvas.lineCap = 'round';
+
+		this.canvas.beginPath();
+		this.canvas.moveTo(line[0].x, line[0].y);
+		line.forEach(({ x, y }) => this.canvas.lineTo(x, y));
+		this.canvas.stroke();
+		if (cap) this.canvas.closePath();
+	}
+
+	/**
+	 * Clears the entire canvas.
+	 */
+	clearCanvas() {
+		this.canvas.clearRect(0, 0, this.elem.width, this.elem.height);
+	}
+}

package/components/Whiteboard/Whiteboard.lld.md

@@ -0,0 +1,35 @@
+# Whiteboard
+
+> ./Whiteboard.js
+
+Multi-touch drawing canvas that tracks each pointer independently. The design decision: draw throttle adapts to brush size; thicker lines need fewer intermediate points to look smooth, so the throttle rate derives from `lineWidth` rather than being a fixed value.
+
+## Each pointer draws an independent line
+
+- two simultaneous touches produce two independent strokes; neither interferes with the other
+- the whiteboard tracks each active pointer by its ID
+  - does a second finger touching the canvas start a separate line from the first?
+
+## Draw throttle rate adapts to line width — no separate configuration needed
+
+- the throttle delay is derived from `lineWidth + 3` (clamped to a range); thicker lines are visually coarser and tolerate a longer delay
+- callers set `lineWidth` and the draw rate adjusts automatically; they do not configure throttle separately
+- explicitly setting `drawThrottle` overrides the derived rate when the default does not fit the use case
+
+## Completed strokes are emitted as complete lines, not as individual points
+
+- when a pointer lifts, the full array of points recorded during that stroke is emitted as a line event
+- callers receive whole lines for persistence or replay, not a stream of coordinate events
+  - does lifting a pointer emit all the points recorded during that stroke?
+
+## readOnly prevents new strokes without clearing the canvas
+
+- existing content remains visible; only new pointer interactions are blocked
+- the whiteboard is non-destructive in read-only mode; content survives the mode switch
+  - does enabling readOnly prevent a new stroke from starting while preserving existing content?
+
+## clearCanvas wipes content without removing the element
+
+- `clearCanvas()` clears the 2D context and resets stroke state
+- the canvas element itself remains in the DOM, reusable for new drawing
+  - does clearCanvas produce a blank canvas without removing it from the page?

package/components/Whiteboard/index.js

@@ -0,0 +1 @@
+export { default as Whiteboard } from './Whiteboard';

package/components/index.js

@@ -0,0 +1,27 @@
+/* This file is automatically managed (bun build:index) (updateComponentIndex.js), do not edit by hand */
+
+export * from './BottomSheet';
+export * from './Button';
+export * from './Calendar';
+export * from './Code';
+export * from './ColorPicker';
+export * from './Dialog';
+export * from './Form';
+export * from './Icon';
+export * from './Input';
+export * from './Keyboard';
+export * from './Label';
+export * from './Link';
+export * from './List';
+export * from './Menu';
+export * from './Notify';
+export * from './Page';
+export * from './Popover';
+export * from './RadioButton';
+export * from './Router';
+export * from './Select';
+export * from './Table';
+export * from './TagList';
+export * from './Tooltip';
+export * from './TooltipWrapper';
+export * from './Whiteboard';

package/eslint.config.cjs

@@ -0,0 +1,118 @@
+const globals = require('globals');
+const { fixupConfigRules, fixupPluginRules } = require('@eslint/compat');
+const js = require('@eslint/js');
+const jsdoc = require('eslint-plugin-jsdoc');
+
+const compat = require('eslint-plugin-compat');
+const importPlugin = require('eslint-plugin-import');
+const spellcheck = require('eslint-plugin-spellcheck');
+const testingLibrary = require('eslint-plugin-testing-library');
+const writeGoodComments = require('eslint-plugin-write-good-comments');
+
+module.exports = [
+	{
+		ignores: ['**/node_modules', '**/build', '**/.claude'],
+	},
+	js.configs.recommended,
+	jsdoc.configs['flat/recommended'],
+	...fixupConfigRules(compat.configs['flat/recommended']),
+	{
+		languageOptions: {
+			ecmaVersion: 'latest',
+			sourceType: 'module',
+			globals: globals.builtin,
+		},
+	},
+	{
+		files: ['**/*.js', '**/*.mjs', '**/*.cjs'],
+		plugins: {
+			import: importPlugin,
+			'write-good-comments': writeGoodComments,
+			spellcheck,
+		},
+		rules: {
+			'no-console': 'warn',
+			'no-nested-ternary': 'error',
+			'no-var': 'error',
+			'prefer-const': 'error',
+			'comma-dangle': ['error', 'only-multiline'],
+			'no-async-promise-executor': 'off',
+			'no-prototype-builtins': 'off',
+
+			// TODO This rule doesn't work after updating to eslint 9
+			// https://github.com/import-js/eslint-plugin-import/pull/2829
+			// 'import/no-unused-modules': [1, { unusedExports: true }],
+
+			'import/no-unresolved': [1, { ignore: ['bun', 'bun:test', String.raw`\.asText$`] }],
+			'import/no-useless-path-segments': 'error',
+			'import/first': 'warn',
+			'import/order': 'warn',
+
+			'write-good-comments/write-good-comments': 'off',
+
+			'spellcheck/spell-checker': ['warn', require('./spellcheck.config.cjs')],
+			'jsdoc/no-undefined-types': ['warn', { definedTypes: ['Component', 'TemplateStringsArray'] }],
+		},
+	},
+	{
+		files: ['**/*.js', '**/*.mjs'],
+		languageOptions: {
+			globals: {
+				...globals.browser,
+				process: false,
+			},
+		},
+	},
+	{
+		files: ['**/*.cjs'],
+		languageOptions: {
+			globals: globals.node,
+		},
+		rules: {
+			'no-console': 'off',
+		},
+	},
+	{
+		files: ['**/demo.js', 'demo/*', 'demo/**/*'],
+		rules: {
+			'no-console': 'off',
+			'jsdoc/require-jsdoc': 'off',
+		},
+	},
+	{
+		files: ['demo/server.js', 'devTools/*', 'plugins/*'],
+		languageOptions: {
+			globals: {
+				...globals.node,
+				Bun: false,
+			},
+		},
+		rules: {
+			'no-console': 'off',
+		},
+	},
+	{
+		files: ['test-setup.js', '**/*.test.js', 'components/**/.test.js'],
+		languageOptions: {
+			globals: {
+				...globals.browser,
+				...globals.node,
+				...globals.jest,
+				Bun: false,
+				container: false,
+				mock: true,
+				spyOn: true,
+				setSystemTime: true,
+			},
+		},
+		plugins: {
+			'testing-library': fixupPluginRules({ rules: testingLibrary.rules }),
+		},
+		rules: {
+			...testingLibrary.configs.dom.rules,
+			'no-console': 'off',
+			'testing-library/prefer-screen-queries': 'off',
+			'compat/compat': 'off',
+		},
+	},
+];