ruscus 0.0.0-stage → 0.0.2

package/dist/index.mjs

@@ -0,0 +1,661 @@
+//#region src/types/ids.ts
+const ELEMENT_ROOT = "root";
+//#endregion
+//#region src/projection/elements.ts
+/**
+* Project a root node and its children
+*/
+function projectTree(namespace, elements, { format, hasVariants, name }) {
+	return {
+		...projectElements(namespace, elements, {
+			format,
+			name
+		}),
+		[ELEMENT_ROOT]: projectNode(name.forClass(namespace), {
+			format,
+			hasVariants,
+			name
+		})
+	};
+}
+/**
+* Project elements under a namespace
+*/
+function projectElements(namespace, elements, { format, name }) {
+	return Object.entries(elements).reduce((previous, [key, element]) => {
+		if (element) previous[key] = projectElement([...namespace, key], element, {
+			format,
+			name
+		});
+		return previous;
+	}, {});
+}
+/**
+* Project an element as a class name, selector, or child tree
+*/
+function projectElement(path, element, options) {
+	const { children } = element;
+	const hasVariants = element.variants !== void 0;
+	return Object.keys(children).length ? projectTree(path, children, {
+		...options,
+		hasVariants
+	}) : projectNode(options.name.forClass(path), {
+		...options,
+		hasVariants
+	});
+}
+/**
+* Project a node as a class name or variant projector
+*/
+function projectNode(className, { format, hasVariants, name }) {
+	const root = formatClass(className, format);
+	return hasVariants ? createVariantProjector(root, format, name) : root;
+}
+/**
+* Format a class name
+*/
+function formatClass(name, format) {
+	return format === "selectors" ? `.${name}` : name;
+}
+/**
+* Create a variant projector anchored to a compile-time root
+*/
+function createVariantProjector(anchor, format, name) {
+	const joiner = format === "selectors" ? "" : " ";
+	return (...vs) => {
+		return [anchor, ...vs.filter(Boolean).map((v) => formatClass(name.forVariant(v), format))].join(joiner);
+	};
+}
+//#endregion
+//#region src/styles.ts
+/**
+* Convert a camel-cased value to kebab case
+*/
+function camelToKebab(camel) {
+	return camel.replace(/[A-Z]/g, (l) => `-${l.toLowerCase()}`);
+}
+/**
+* Merge multiple styles on top of a base
+*/
+function mergeStyles(base, ...others) {
+	const merged = { ...base };
+	for (const other of others) Object.assign(merged, other);
+	return merged;
+}
+var PropertyProjector = class {
+	names;
+	/**
+	* Create a mapper of camel-cased values to CSS properties
+	*/
+	constructor() {
+		this.names = /* @__PURE__ */ new Map();
+	}
+	/**
+	* Project a camel-cased value as a CSS property
+	*/
+	project(camel) {
+		let prop = this.names.get(camel);
+		if (prop === void 0) {
+			prop = camelToKebab(camel);
+			this.names.set(camel, prop);
+		}
+		return prop;
+	}
+};
+//#endregion
+//#region src/projection/identifiers.ts
+/**
+* Project a component's identifiers as a map of labels to values
+*/
+function projectIdentifiers(component) {
+	return Object.fromEntries(Object.entries(component.identifiers).map(([key, type]) => {
+		const scoped = `${component.id}--${camelToKebab(key)}`;
+		return [key, type === "variable" ? `--${scoped}` : scoped];
+	}));
+}
+//#endregion
+//#region src/contexts.ts
+/**
+* Build a context for derived component styles
+*/
+function buildComponentContext(component, { name }) {
+	return {
+		els: projectTree([component.id], component.elements, {
+			format: "selectors",
+			hasVariants: component.variants !== void 0,
+			name
+		}),
+		ids: projectIdentifiers(component),
+		variants: createVariantProjector("&", "selectors", name)
+	};
+}
+/**
+* Build a context for derived element styles
+*/
+function buildElementContext(namespace, element, { name }) {
+	return {
+		els: projectTree(namespace, element.children, {
+			format: "selectors",
+			hasVariants: element.variants !== void 0,
+			name
+		}),
+		variants: createVariantProjector("&", "selectors", name)
+	};
+}
+//#endregion
+//#region src/fragments.ts
+/**
+* Create a fragment factory
+*/
+function createFactory(scope) {
+	const factory = ((styles = {}) => ({
+		nested: (definitions) => {
+			const nested = factory(styles);
+			for (const fragment of Object.values(definitions)) fragment.scope = "relative";
+			nested.styles.nested = { ...definitions };
+			return nested;
+		},
+		scope,
+		styles: {
+			nested: {},
+			root: styles
+		}
+	}));
+	factory.rules = (definitions) => factory().nested(definitions);
+	return factory;
+}
+const defineAbsoluteFragment = createFactory("absolute");
+const defineRelativeFragment = createFactory("relative");
+//#endregion
+//#region src/naming/shared.ts
+var Naming = class {
+	component;
+	/**
+	* Create a naming strategy for a component
+	*/
+	constructor(component) {
+		this.component = component;
+	}
+	/**
+	* Produce the class name for a variant
+	*/
+	forVariant(name) {
+		return `is-${name}`;
+	}
+};
+//#endregion
+//#region src/naming/compact.ts
+const SEPARATOR = "\0";
+var CompactNaming = class extends Naming {
+	prefix;
+	suffixes;
+	/**
+	* Build compact suffixes for all element paths
+	*/
+	constructor(component) {
+		super(component);
+		this.prefix = `r${hash(component.id)}`;
+		this.suffixes = this.buildSuffixes(component.elements);
+	}
+	/**
+	* Produce a compact class name
+	*/
+	forClass(levels) {
+		if (levels.length <= 1) return this.prefix;
+		const suffix = this.suffixes.get(levels.slice(1).join(SEPARATOR));
+		if (suffix === void 0) throw new Error(`Unknown element path for compact naming: ${levels.join(" > ")}`);
+		return `${this.prefix}_${suffix}`;
+	}
+	/**
+	* Map each element path to a compact suffix
+	*/
+	buildSuffixes(elements) {
+		const paths = this.collectElementPaths(elements).sort((alfa, bravo) => alfa.localeCompare(bravo));
+		const suffixes = /* @__PURE__ */ new Map();
+		for (const [index, path] of paths.entries()) suffixes.set(path, index.toString(36));
+		return suffixes;
+	}
+	/**
+	* Collect element paths in depth-first order
+	*/
+	collectElementPaths(elements, base = "") {
+		const paths = [];
+		for (const name of Object.keys(elements).sort()) {
+			const element = elements[name];
+			if (element === void 0) continue;
+			const path = base.length === 0 ? name : `${base}${SEPARATOR}${name}`;
+			paths.push(path);
+			paths.push(...this.collectElementPaths(element.children, path));
+		}
+		return paths;
+	}
+};
+/**
+* Build a short hash for a value using a 32-bit FNV-1a algorithm
+*/
+function hash(value, length = 6) {
+	let hash = 2166136261;
+	for (const character of value) {
+		hash ^= character.charCodeAt(0);
+		hash = Math.imul(hash, 16777619);
+	}
+	return (hash >>> 0).toString(36).slice(0, length).padStart(length, "0");
+}
+//#endregion
+//#region src/naming/verbose.ts
+var VerboseNaming = class extends Naming {
+	/**
+	* Produce a BEM-style class name
+	*/
+	forClass(levels) {
+		return levels.join("__");
+	}
+};
+//#endregion
+//#region src/naming.ts
+/**
+* Create a name generator for a component
+*/
+function useNaming(component, scheme = "verbose") {
+	return scheme === "compact" ? new CompactNaming(component) : new VerboseNaming(component);
+}
+//#endregion
+//#region src/compilation.ts
+/**
+* Generate CSS for a component's styles
+*/
+function styleComponent(component, config = {}) {
+	return new ComponentCompiler(component, config).compile();
+}
+var ComponentCompiler = class {
+	blocks;
+	component;
+	config;
+	indent;
+	name;
+	/**
+	* Create a compiler for a component's styles
+	*/
+	constructor(component, config) {
+		this.config = {
+			indentation: 2,
+			naming: "verbose",
+			properties: new PropertyProjector(),
+			...config
+		};
+		this.blocks = [];
+		this.component = component;
+		this.indent = " ".repeat(this.config.indentation);
+		this.name = useNaming(component, config.naming);
+	}
+	/**
+	* Produce CSS for the component's styles
+	*/
+	compile() {
+		const { component, name } = this;
+		const { elements, variants } = component;
+		const root = this.buildSelector();
+		const context = buildComponentContext(component, { name });
+		this.blocks.push(this.formatRule(root, component.styles));
+		if (variants) this.addVariantRules(root, variants(defineRelativeFragment, context));
+		for (const [name, element] of Object.entries(elements)) this.addElementStyles([name], element);
+		for (const provider of component.nested) this.addRelativeFragmentRules(root, provider(defineRelativeFragment, context));
+		for (const provider of component.global) this.addGlobalFragmentRules(provider(defineAbsoluteFragment, context));
+		return this.blocks.filter(Boolean).join("\n\n");
+	}
+	/**
+	* Add base styles for a component's elements
+	*/
+	addElementStyles(path, element) {
+		const { children, variants } = element;
+		const selector = this.buildSelector(...path);
+		const context = buildElementContext([this.component.id, ...path], element, { name: this.name });
+		this.blocks.push(this.formatRule(selector, element.styles));
+		if (variants) this.addVariantRules(selector, variants(defineRelativeFragment, context));
+		for (const provider of element.nested) this.addRelativeFragmentRules(selector, provider(defineRelativeFragment, context));
+		for (const [name, child] of Object.entries(children)) this.addElementStyles([...path, name], child);
+	}
+	/**
+	* Add variant rules for component or element variants
+	*/
+	addVariantRules(anchor, definitions) {
+		for (const [name, fragment] of Object.entries(definitions)) this.blocks.push(this.formatFragmentRules(`${anchor}.${this.name.forVariant(name)}`, fragment));
+	}
+	/**
+	* Add global fragment rules
+	*/
+	addGlobalFragmentRules(definitions) {
+		for (const [key, fragment] of Object.entries(definitions)) this.blocks.push(this.formatFragmentRules(key, fragment));
+	}
+	/**
+	* Add relative fragment rules
+	*/
+	addRelativeFragmentRules(anchor, definitions) {
+		for (const [key, fragment] of Object.entries(definitions)) this.blocks.push(this.formatFragmentRules(this.buildNestedSelector(anchor, key), fragment));
+	}
+	/**
+	* Format a fragment as CSS at a selector
+	*/
+	formatFragmentRules(parentSelector, fragment) {
+		const { nested, root: styles } = fragment.styles;
+		const nestedEntries = Object.entries(nested);
+		if (nestedEntries.length === 0) return this.formatRule(parentSelector, styles);
+		const inner = [];
+		const declarations = this.formatDeclarations(styles);
+		if (declarations) inner.push(declarations);
+		for (const [key, child] of nestedEntries) {
+			const rule = this.formatFragmentRules(key.startsWith("&") ? `${parentSelector}${key.slice(1)}` : key, child);
+			if (rule) inner.push(rule);
+		}
+		if (!inner.length) return null;
+		return this.formatNestedBlock(parentSelector, inner);
+	}
+	/**
+	* Format declaration as key/value pairs
+	*/
+	formatDeclarations(styles) {
+		const { config: { properties }, indent } = this;
+		const props = Object.entries(styles).filter(([_, v]) => v !== void 0);
+		if (props.length === 0) return null;
+		return props.map(([p]) => `${indent}${properties.project(p)}: ${styles[p]};`).join("\n");
+	}
+	/**
+	* Wrap nested rules in a selector block
+	*/
+	formatNestedBlock(selector, inner) {
+		const { indent } = this;
+		return `${selector} {\n${inner.map((rule) => rule.split("\n").map((line) => `${indent}${line}`).join("\n")).join("\n\n")}\n}`;
+	}
+	/**
+	* Build a selector for a nested rule key
+	*/
+	buildNestedSelector(anchor, key) {
+		if (key.startsWith("&")) return `${anchor}${key.slice(1)}`;
+		else if (key === anchor) return anchor;
+		else return `${anchor} ${key}`;
+	}
+	/**
+	* Build a selector for a component element
+	*/
+	buildSelector(...parts) {
+		return `.${this.name.forClass([this.component.id, ...parts])}`;
+	}
+	/**
+	* Format a CSS rule
+	*/
+	formatRule(selector, styles) {
+		const body = this.formatDeclarations(styles);
+		return body === null ? null : `${selector} {\n${body}\n}`;
+	}
+};
+//#endregion
+//#region src/builder.ts
+var Builder = class {
+	current;
+	/**
+	* Create a builder that progressively updates its state
+	*/
+	constructor(defaultState) {
+		this.current = defaultState;
+	}
+	/**
+	* Set a state field
+	*
+	* @throws if the field already has a value
+	*/
+	setStateField(key, value) {
+		const current = this.current[key];
+		if (current !== void 0) {
+			if (typeof current === "object" ? Object.keys(current).length > 0 : true) throw new Error(`${key} may only be set once`);
+		}
+		this.current[key] = value;
+	}
+};
+//#endregion
+//#region src/traits.ts
+/**
+* Merge traits into a collection of styles
+*/
+function mergeTraits(...traits) {
+	return traits.reduce((previous, { styles }) => {
+		previous.root = mergeStyles(previous.root, styles.root);
+		Object.assign(previous.nested, styles.nested);
+		return previous;
+	}, {
+		nested: {},
+		root: {}
+	});
+}
+/**
+* Define a trait
+*/
+function defineTrait(build) {
+	return build(defineRelativeFragment);
+}
+//#endregion
+//#region src/utils.ts
+/**
+* Cast a value
+*/
+function cast(value) {
+	return value;
+}
+/**
+* Resolve an eager value or a thunk
+*/
+function resolve(value) {
+	return typeof value === "function" ? value() : value;
+}
+//#endregion
+//#region src/elements.ts
+/**
+* Define an element
+*/
+function defineElement(styles = {}) {
+	return new Element().css(styles);
+}
+/**
+* Resolve element providers to concrete elements
+*/
+function resolveElements(providers) {
+	return Object.entries(providers).reduce((els, [name, provider]) => {
+		els[name] = resolve(provider).current;
+		return els;
+	}, {});
+}
+var Element = class extends Builder {
+	/**
+	* Create an element
+	*/
+	constructor() {
+		super({
+			children: {},
+			nested: [],
+			styles: {}
+		});
+	}
+	/**
+	* Define child elements
+	*/
+	children(definitions) {
+		this.setStateField("children", resolveElements(resolve(definitions)));
+		return this;
+	}
+	/**
+	* Apply styles to the element
+	*/
+	css(styles) {
+		const { current } = this;
+		current.styles = mergeStyles(current.styles, styles);
+		return this;
+	}
+	/**
+	* Apply traits to the element
+	*/
+	is(...traits) {
+		const { nested, root } = mergeTraits(...traits);
+		this.current.styles = mergeStyles(this.current.styles, root);
+		if (Object.keys(nested).length > 0) this.current.nested.push(() => nested);
+		return this;
+	}
+	/**
+	* Define nested styles for the element
+	*/
+	nested(provider) {
+		this.current.nested.push(provider);
+		return this;
+	}
+	/**
+	* Define variants for the element
+	*/
+	variants(provider) {
+		this.setStateField("variants", provider);
+		return this;
+	}
+};
+//#endregion
+//#region src/internal.ts
+const build = Symbol.for("ruscus/build");
+const identifiers = Symbol.for("ruscus/identifiers");
+/**
+* Apply internal annotations to a component
+*/
+function annotateComponent(component, annotations) {
+	const annotate = (key, value) => {
+		Object.defineProperty(component, key, {
+			configurable: false,
+			enumerable: false,
+			value,
+			writable: false
+		});
+	};
+	annotate(build, annotations.buildPlan);
+	annotate(identifiers, annotations.identifiers);
+	return component;
+}
+/**
+* Extract identifiers from a component
+*/
+function extractIdentifiers(component) {
+	return component[identifiers];
+}
+//#endregion
+//#region src/projection.ts
+/**
+* Project a component as class names
+*/
+function projectComponent({ current }, name) {
+	return projectTree([current.id], current.elements, {
+		format: "names",
+		hasVariants: current.variants !== void 0,
+		name
+	});
+}
+//#endregion
+//#region src/components.ts
+var Component = class extends Builder {
+	id;
+	/**
+	* Create a component
+	*/
+	constructor(name, { namespace = [] } = {}) {
+		const id = [...namespace, name].filter(Boolean).join("--");
+		super({
+			elements: {},
+			global: [],
+			id,
+			identifiers: {},
+			nested: [],
+			styles: {}
+		});
+		this.id = id;
+	}
+	/**
+	* Project the component into class names and identifiers
+	*/
+	apply() {
+		const name = useNaming(this.current);
+		return annotateComponent(projectComponent(this, name), {
+			buildPlan: {
+				compile: (config = {}) => styleComponent(this.current, config),
+				component: this.current
+			},
+			identifiers: cast(projectIdentifiers(this.current))
+		});
+	}
+	/**
+	* Apply styles to the component root
+	*/
+	css(styles) {
+		const { current } = this;
+		current.styles = mergeStyles(current.styles, styles);
+		return this;
+	}
+	/**
+	* Define component-specific identifiers
+	*/
+	identifiers(types) {
+		this.setStateField("identifiers", types);
+		return this;
+	}
+	/**
+	* Define the component's elements
+	*/
+	elements(provider) {
+		this.setStateField("elements", resolveElements(provider(defineElement, { ids: projectIdentifiers(this.current) })));
+		return this;
+	}
+	/**
+	* Apply reusable trait styles and nested rules
+	*/
+	is(...traits) {
+		const { nested, root } = mergeTraits(...traits);
+		this.current.styles = mergeStyles(this.current.styles, root);
+		if (Object.keys(nested).length > 0) this.current.nested.push(() => nested);
+		return this;
+	}
+	/**
+	* Define global styles for the component
+	*/
+	global(definitions) {
+		this.current.global.push(definitions);
+		return this;
+	}
+	/**
+	* Define nested styles for the component
+	*/
+	nested(definitions) {
+		this.current.nested.push(definitions);
+		return this;
+	}
+	/**
+	* Define variants for the component root
+	*/
+	variants(provider) {
+		this.setStateField("variants", provider);
+		return this;
+	}
+};
+/**
+* Define a component
+*/
+function defineComponent(name) {
+	return new Component(name);
+}
+//#endregion
+//#region src/queries.ts
+/**
+* Define a provider of named queries
+*/
+function defineQueries(queries) {
+	const build = (blocks) => {
+		return Object.entries(blocks).reduce((previous, [label, rules]) => {
+			const query = queries[label];
+			if (rules && query) previous[query] = defineAbsoluteFragment().nested(rules);
+			return previous;
+		}, {});
+	};
+	return Object.assign(build, queries);
+}
+//#endregion
+export { defineComponent as component, extractIdentifiers as identifiers, defineQueries as queries, styleComponent as style, defineTrait as trait };

package/dist/vite.d.mts

@@ -0,0 +1,20 @@
+import { Plugin } from "vite";
+//#region src/naming.d.ts
+/**
+ * An available naming scheme for classes
+ */
+type NamingScheme = 'compact' | 'verbose';
+//#endregion
+//#region src/vite/plugin.d.ts
+/**
+ * Plugin options
+ */
+type PluginOptions = {
+  naming?: NamingScheme;
+};
+/**
+ * Define the Vite plugin
+ */
+declare function plugin(options?: PluginOptions): Plugin;
+//#endregion
+export { plugin as default };