@animus-ui/system 0.1.0-next.v7 → 0.1.0

package/dist/compose.js

@@ -0,0 +1,36 @@
+import { createElement, forwardRef } from "react";
+//#region src/compose.ts
+/**
+* Compose independently-authored Animus components into a sealed,
+* namespaced component family with shared variant propagation via
+* CSS cascade.
+*
+* - **Enforce**: TypeScript ensures shared keys exist on Root (the
+*   cascade source). Non-Root slots that have the key consume it from
+*   CSS inheritance; slots without the key are unaffected.
+* - **Wire**: The extraction pipeline emits composed variant CSS
+*   rules — two per shared variant option per child (inheritance +
+*   override) within @layer variants.
+* - **Seal**: Output components are plain ForwardRefExoticComponent —
+*   no `.extend()`, no builder methods. One-way door from builder-land
+*   to component-land.
+*
+* For React context propagation (portal-crossing), use
+* `composeWithContext` from `@animus-ui/system/compose-with-context`.
+*/
+function compose(slots, options) {
+	const familyName = options.name ?? "Composed";
+	const result = {};
+	for (const [name, SourceComponent] of Object.entries(slots)) {
+		const Wrapper = forwardRef((props, ref) => createElement(SourceComponent, {
+			...props,
+			ref
+		}, props.children));
+		Wrapper.displayName = `${familyName}.${name}`;
+		result[name] = Wrapper;
+	}
+	if (!("Root" in result)) throw new Error("compose(): No \"Root\" slot found. The root slot key must be exactly \"Root\" (PascalCase).");
+	return result;
+}
+//#endregion
+export { compose };

package/dist/composeWithContext.d.ts

@@ -0,0 +1,30 @@
+import { type ForwardRefExoticComponent } from 'react';
+import type { AnyBrandedComponent, ComposedFamily, SharedConfig } from './types/component';
+/**
+ * Compose components into a sealed family with shared variant propagation
+ * via React context. Use this when children may be rendered in portals
+ * or other React subtrees that escape the DOM hierarchy (where CSS
+ * descendant selectors cannot reach).
+ *
+ * This function uses `createContext` and `useContext` — it is client-only.
+ * For CSS-only propagation (RSC-safe), use `compose` from the barrel or
+ * `@animus-ui/system/compose`.
+ */
+export declare function composeWithContext<Slots extends Record<string, AnyBrandedComponent>, const Shared extends SharedConfig<Slots>>(slots: Slots, options: {
+    shared: Shared;
+    name?: string;
+}): ComposedFamily<Slots>;
+/**
+ * createComposedFamilyWithContext — extraction-time replacement for composeWithContext().
+ *
+ * The transform emitter replaces `composeWithContext({ Root, Body }, { shared, name })`
+ * with `createComposedFamilyWithContext({ Root, Body }, { name, sharedKeys })`.
+ *
+ * Client-only: uses createContext and useContext. Files containing this function
+ * receive a 'use client' directive from the transform emitter.
+ */
+export declare function createComposedFamilyWithContext(slots: Record<string, ForwardRefExoticComponent<any>>, config: {
+    name: string;
+    sharedKeys: string[];
+}): Record<string, ForwardRefExoticComponent<any>>;
+//# sourceMappingURL=composeWithContext.d.ts.map

package/dist/composeWithContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composeWithContext.d.ts","sourceRoot":"","sources":["../src/composeWithContext.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,yBAAyB,EAI/B,MAAM,OAAO,CAAC;AAEf,OAAO,KAAK,EACV,mBAAmB,EACnB,cAAc,EACd,YAAY,EACb,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EACjD,KAAK,CAAC,MAAM,SAAS,YAAY,CAAC,KAAK,CAAC,EAExC,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACzC,cAAc,CAAC,KAAK,CAAC,CA8CvB;AAED;;;;;;;;GAQG;AACH,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,GAAG,CAAC,CAAC,EACrD,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,GAC7C,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,GAAG,CAAC,CAAC,CAqChD"}

package/dist/composeWithContext.js

@@ -0,0 +1,79 @@
+"use client";
+import { createContext, createElement, forwardRef, useContext } from "react";
+//#region src/composeWithContext.ts
+/**
+* Compose components into a sealed family with shared variant propagation
+* via React context. Use this when children may be rendered in portals
+* or other React subtrees that escape the DOM hierarchy (where CSS
+* descendant selectors cannot reach).
+*
+* This function uses `createContext` and `useContext` — it is client-only.
+* For CSS-only propagation (RSC-safe), use `compose` from the barrel or
+* `@animus-ui/system/compose`.
+*/
+function composeWithContext(slots, options) {
+	const familyName = options.name ?? "Composed";
+	const sharedKeySet = new Set(Object.keys(options.shared));
+	const FamilyCtx = createContext({});
+	const result = {};
+	for (const [name, SourceComponent] of Object.entries(slots)) {
+		let Wrapper;
+		if (name === "Root") Wrapper = forwardRef((props, ref) => {
+			const shared = {};
+			for (const key of sharedKeySet) if (key in props) shared[key] = props[key];
+			return createElement(SourceComponent, {
+				...props,
+				ref
+			}, createElement(FamilyCtx.Provider, { value: shared }, props.children));
+		});
+		else Wrapper = forwardRef((props, ref) => {
+			return createElement(SourceComponent, {
+				...useContext(FamilyCtx),
+				...props,
+				ref
+			});
+		});
+		Wrapper.displayName = `${familyName}.${name}`;
+		result[name] = Wrapper;
+	}
+	if (!("Root" in result)) throw new Error("composeWithContext(): No \"Root\" slot found. The root slot key must be exactly \"Root\" (PascalCase).");
+	return result;
+}
+/**
+* createComposedFamilyWithContext — extraction-time replacement for composeWithContext().
+*
+* The transform emitter replaces `composeWithContext({ Root, Body }, { shared, name })`
+* with `createComposedFamilyWithContext({ Root, Body }, { name, sharedKeys })`.
+*
+* Client-only: uses createContext and useContext. Files containing this function
+* receive a 'use client' directive from the transform emitter.
+*/
+function createComposedFamilyWithContext(slots, config) {
+	const { name, sharedKeys } = config;
+	const Ctx = createContext({});
+	const keySet = new Set(sharedKeys);
+	const result = {};
+	for (const [slotName, SourceComponent] of Object.entries(slots)) {
+		let Wrapper;
+		if (slotName === "Root") Wrapper = forwardRef((props, ref) => {
+			const shared = {};
+			for (const key of keySet) if (key in props) shared[key] = props[key];
+			return createElement(SourceComponent, {
+				...props,
+				ref
+			}, createElement(Ctx.Provider, { value: shared }, props.children));
+		});
+		else Wrapper = forwardRef((props, ref) => {
+			return createElement(SourceComponent, {
+				...useContext(Ctx),
+				...props,
+				ref
+			});
+		});
+		Wrapper.displayName = `${name}.${slotName}`;
+		result[slotName] = Wrapper;
+	}
+	return result;
+}
+//#endregion
+export { composeWithContext, createComposedFamilyWithContext };

package/dist/createComposedFamily-BsyI6rBc.js

@@ -0,0 +1,230 @@
+import { Children, cloneElement, createElement, forwardRef, isValidElement } from "react";
+import { UNITLESS_PROPERTIES } from "@animus-ui/properties";
+//#region src/runtime/resolveClasses.ts
+/**
+* Apply unit fallback to a value for a given CSS property.
+*/
+function applyUnitFallback(value, cssProperty) {
+	if (typeof value === "number") {
+		if (UNITLESS_PROPERTIES.has(cssProperty)) return String(value);
+		return `${value}px`;
+	}
+	return String(value);
+}
+/**
+* Serialize a system prop value to a lookup key matching the Rust
+* css_generator's serialize_value_key output format.
+*/
+function serializeValueKey(value) {
+	if (typeof value === "number" || typeof value === "string") return String(value);
+	if (typeof value === "object" && value !== null && !Array.isArray(value)) return Object.keys(value).sort().map((k) => `${k}:${value[k]}`).join("|");
+	return String(value);
+}
+/**
+* Resolve a dynamic prop value through scale lookup → transform → unit fallback.
+*/
+function resolveValue(value, dc) {
+	const key = String(value);
+	const scaleResolved = dc.scaleValues?.[key];
+	if (scaleResolved != null) {
+		const transformed = dc.transform ? dc.transform(scaleResolved) : scaleResolved;
+		return String(transformed);
+	}
+	return applyUnitFallback(dc.transform ? dc.transform(value) : value, dc.varName);
+}
+/**
+* Resolve className parts from props, using extracted configuration.
+* This is the shared logic between createComponent and createClassResolver.
+*/
+function resolveClasses(baseClassName, props, config, systemPropMap, dynamicPropConfig) {
+	const classes = [baseClassName];
+	let dynStyle;
+	if (config.variants) for (const [prop, vc] of Object.entries(config.variants)) {
+		const value = props[prop] ?? vc.default;
+		if (value != null) {
+			const isDefault = !(prop in props) && vc.default != null;
+			classes.push(`${baseClassName}--${prop}-${isDefault ? "default" : value}`);
+		}
+	}
+	if (config.compounds) for (const compound of config.compounds) {
+		let match = true;
+		for (const [prop, expected] of Object.entries(compound.conditions)) {
+			const current = props[prop] ?? config.variants?.[prop]?.default;
+			if (Array.isArray(expected) ? !expected.includes(current) : current !== expected) {
+				match = false;
+				break;
+			}
+		}
+		if (match) classes.push(compound.className);
+	}
+	const activeStates = [];
+	if (config.states) {
+		for (const state of config.states) if (props[state]) {
+			classes.push(`${baseClassName}--${state}`);
+			activeStates.push(state);
+		}
+	}
+	const systemPropNames = config.systemPropNames || [];
+	if (systemPropNames.length > 0) {
+		const { customPropMap, customDynamicConfig } = config;
+		for (const propName of systemPropNames) {
+			if (!(propName in props)) continue;
+			const propValue = props[propName];
+			if (propValue == null) continue;
+			const key = serializeValueKey(propValue);
+			const cls = customPropMap?.[propName]?.[key] ?? systemPropMap?.[propName]?.[key];
+			if (cls) classes.push(cls);
+			else {
+				const dc = customDynamicConfig?.[propName] ?? dynamicPropConfig?.[propName];
+				if (dc) {
+					if (!dynStyle) dynStyle = {};
+					if (typeof propValue === "object" && propValue !== null && !Array.isArray(propValue)) for (const [bp, bpVal] of Object.entries(propValue)) {
+						if (bpVal == null) continue;
+						if (bp === "_") {
+							classes.push(dc.slotClass);
+							const finalVal = resolveValue(bpVal, dc);
+							dynStyle[dc.varName] = finalVal;
+						} else {
+							classes.push(`${dc.slotClass}-${bp}`);
+							const varName = `${dc.varName}-${bp}`;
+							const finalVal = resolveValue(bpVal, dc);
+							dynStyle[varName] = finalVal;
+						}
+					}
+					else {
+						classes.push(dc.slotClass);
+						const finalVal = resolveValue(propValue, dc);
+						dynStyle[dc.varName] = finalVal;
+					}
+				}
+			}
+		}
+	}
+	return {
+		classes,
+		dynamicStyle: dynStyle,
+		activeStates
+	};
+}
+//#endregion
+//#region src/runtime/index.ts
+/**
+* Merge multiple refs (callback or object) into a single callback ref.
+* Creates a new callback on each call — no memoization possible in a
+* hook-free runtime (RSC compatibility). Matches @radix-ui/react-compose-refs.
+*/
+function composeRefs(...refs) {
+	return (node) => {
+		for (const ref of refs) if (typeof ref === "function") ref(node);
+		else if (ref) ref.current = node;
+	};
+}
+/**
+* Create a lightweight component that applies extracted CSS class names.
+* Replaces Emotion's styled() for extracted components.
+*
+* The element parameter accepts either an HTML tag string (e.g. 'button') or
+* a React component reference (e.g. NextLink). When a component reference is
+* used, prop forwarding skips the HTML-attribute validity check — all
+* non-filtered props are forwarded to the component.
+*
+* The optional systemPropMap parameter provides the shared prop→value→className
+* lookup table, served as a virtual module by the Vite plugin.
+*
+* The optional dynamicPropConfig parameter provides CSS variable fallback
+* metadata for props with detected dynamic usage.
+*/
+function createComponent(element, className, config, systemPropMap, dynamicPropConfig) {
+	const variantProps = config.variants ? Object.keys(config.variants) : [];
+	const stateProps = config.states || [];
+	const systemPropNames = config.systemPropNames || [];
+	const filterProps = new Set([
+		"as",
+		"asChild",
+		...variantProps,
+		...stateProps,
+		...systemPropNames
+	]);
+	const Component = forwardRef((props, ref) => {
+		const { classes, dynamicStyle } = resolveClasses(className, props, config, systemPropMap, dynamicPropConfig);
+		if (props.className) classes.push(props.className);
+		if (props.asChild) {
+			const child = Children.only(props.children);
+			if (!isValidElement(child)) throw new Error(`${className}: asChild requires a single React element as children`);
+			const childRef = child.ref;
+			const mergedClassName = [classes.join(" "), child.props.className].filter(Boolean).join(" ");
+			const mergedStyle = dynamicStyle || props.style || child.props.style ? {
+				...props.style,
+				...child.props.style,
+				...dynamicStyle
+			} : void 0;
+			return cloneElement(child, {
+				ref: composeRefs(ref, childRef),
+				className: mergedClassName,
+				...mergedStyle ? { style: mergedStyle } : {}
+			});
+		}
+		const renderElement = props.as || element;
+		const isComponentElement = typeof renderElement !== "string";
+		const domProps = {
+			ref,
+			className: classes.join(" ")
+		};
+		for (const [key, value] of Object.entries(props)) {
+			if (key === "className") continue;
+			if (!(key.startsWith("data-") || key.startsWith("aria-")) && filterProps.has(key)) continue;
+			if (!isComponentElement) {}
+			domProps[key] = value;
+		}
+		if (dynamicStyle) domProps.style = props.style ? {
+			...props.style,
+			...dynamicStyle
+		} : dynamicStyle;
+		return createElement(renderElement, domProps);
+	});
+	Component.displayName = className;
+	return Object.assign(Component, { extend: () => {
+		throw new Error(`Cannot extend extracted component "${className}" at runtime. Extensions must be authored in source code using the builder API (e.g. import the original component and call .extend() there) so the extraction pipeline can resolve them at build time.`);
+	} });
+}
+//#endregion
+//#region src/runtime/createClassResolver.ts
+/**
+* createClassResolver — framework-agnostic className resolution.
+*
+* Produced by .asClass() terminal. Same resolution logic as createComponent
+* (variants, states, compounds, system props) but returns a className string
+* instead of a React element.
+*/
+function createClassResolver(className, config, systemPropMap, dynamicPropConfig) {
+	return (props) => {
+		const { classes } = resolveClasses(className, props || {}, config, systemPropMap, dynamicPropConfig);
+		return classes.join(" ");
+	};
+}
+//#endregion
+//#region src/runtime/createComposedFamily.ts
+/**
+* createComposedFamily — extraction-time replacement for compose().
+*
+* The transform emitter replaces `compose({ Root, Body }, { shared, name })`
+* with `createComposedFamily({ Root, Body }, { name })`.
+*
+* RSC-safe: uses only forwardRef and createElement — no createContext,
+* no useContext, no hooks.
+*/
+function createComposedFamily(slots, config) {
+	const { name } = config;
+	const result = {};
+	for (const [slotName, SourceComponent] of Object.entries(slots)) {
+		const Wrapper = forwardRef((props, ref) => createElement(SourceComponent, {
+			...props,
+			ref
+		}, props.children));
+		Wrapper.displayName = `${name}.${slotName}`;
+		result[slotName] = Wrapper;
+	}
+	return result;
+}
+//#endregion
+export { createClassResolver as n, createComponent as r, createComposedFamily as t };