praxis-kit 0.1.0

package/dist/react/index.d.ts

@@ -0,0 +1,28 @@
+import { C as MergeRecords, E as AnyRecord, S as EmptyRecord, T as NoVariants, _ as ExtractPluginProps, a as PolymorphicProps, b as VariantMap, c as RenderCallbackProps, d as SlottableProps, f as mergeRefs, g as AnyClassPluginFactory, h as FactoryOptions, i as PolymorphicComponent, l as UnknownProps, m as AnyFactoryOptions, n as ContractProps, o as PolymorphicWithAsChild, p as defineContractComponent, r as ElementRef, s as PolymorphicWithRender, t as ReactFactoryOptions, u as Slottable, v as PolymorphicGenerics, w as NoPreset, x as ElementType, y as RecipeMap } from "../index-BIBd_iPD.js";
+//#region ../../adapters/react/src/current/create-contract-component.d.ts
+/**
+ * Creates a polymorphic React 19 component with praxis-kit contracts applied.
+ *
+ * ```tsx
+ * const Button = createContractComponent({
+ *   tag: 'button',
+ *   name: 'Button',
+ *   styling: {
+ *     base: 'btn',
+ *     variants: { intent: { primary: 'btn--primary', ghost: 'btn--ghost' } },
+ *     defaults: { intent: 'primary' },
+ *   },
+ * })
+ *
+ * <Button intent="ghost" as="a" href="/home">Home</Button>
+ * ```
+ *
+ * `ref` is accepted as a plain prop (React 19) and forwarded to the rendered host element or,
+ * with `asChild`, to the consumer's own element. Pass `subComponents` to attach named
+ * sub-components (`Card.Header`) and `onElement` to run setup once the real DOM element exists.
+ */
+export declare function createContractComponent<TDefault extends ElementType, Props extends UnknownProps = EmptyRecord, Variants extends Readonly<VariantMap> = NoVariants, TPreset extends RecipeMap<Variants> = NoPreset, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory, TAllowed extends ElementType = ElementType, TSubComponents extends Readonly<AnyRecord> = EmptyRecord>(options: ReactFactoryOptions<TDefault, Props, Variants, TPreset, TPlugin, TAllowed> & {
+  readonly subComponents?: TSubComponents;
+}): MergeRecords<PolymorphicComponent<PolymorphicGenerics<TDefault, MergeRecords<Props, ExtractPluginProps<TPlugin>>, Variants, TPreset, TAllowed>>, TSubComponents>;
+//#endregion
+export { type AnyFactoryOptions, type ContractProps, type ElementRef, type ElementType, type EmptyRecord, type FactoryOptions, type PolymorphicComponent, type PolymorphicGenerics, type PolymorphicProps, type PolymorphicWithAsChild, type PolymorphicWithRender, type ReactFactoryOptions, type RenderCallbackProps, Slottable, type SlottableProps, defineContractComponent, mergeRefs };

package/dist/react/index.js

@@ -0,0 +1,205 @@
+import { _ as invariant, a as getElementRef, c as Slottable, d as finalizeComponent, f as SLOT_NAME, g as defineContractComponent, h as isString, i as makeCloneSlotChild, l as applyDisplayName, m as isObject, n as render, o as getPropsRef, p as isFunction, r as applySlot, s as hasWarningGetter, t as buildRuntime$1, u as mergeRefs } from "../build-runtime-CJ_nQEaZ.js";
+import { isValidElement, useCallback, useRef } from "react";
+//#region ../../lib/adapter-utils/src/runtime/is-factory-options-like.ts
+/**
+* Loosely validates one recognized `FactoryOptions` field's runtime shape.
+* "Loosely" because the field's declared type is itself parameterized by a
+* generic (Props, Variants, TPlugin, ...) that's erased at runtime — these
+* checks confirm the field is the right *kind* of value (object, function,
+* string), not that it satisfies its exact generic instantiation, which no
+* runtime check can ever do.
+*
+* Covers every field `FactoryOptions` itself declares — identical across
+* every adapter, since they all extend the same core type. Adapter-specific
+* additions (React's `slotComponent`/`artifact`, every adapter's own
+* `filterProps`, etc.) are passed in by the caller as extra entries.
+*/
+const FACTORY_OPTIONS_FIELD_VALIDATORS = {
+	tag: (v) => v === void 0 || isString(v),
+	name: (v) => v === void 0 || isString(v),
+	defaults: (v) => v === void 0 || isObject(v),
+	normalize: (v) => v === void 0 || isFunction(v),
+	styling: (v) => v === void 0 || isObject(v),
+	enforcement: (v) => v === void 0 || isObject(v),
+	diagnostics: (v) => v === void 0 || isObject(v),
+	subComponents: (v) => v === void 0 || isObject(v),
+	onElement: (v) => v === void 0 || isFunction(v)
+};
+/**
+* Type guard narrowing the generic `FactoryOptions` shape down to an
+* adapter-specific factory options type `T` — the type each adapter's
+* `buildRuntime` is declared against.
+*
+* Walks every own enumerable property on `options` and checks it against
+* `FACTORY_OPTIONS_FIELD_VALIDATORS` plus `extraFieldValidators` (the
+* adapter's own additions on top of `FactoryOptions`): an unrecognized key,
+* or a recognized key holding a value of the wrong kind, fails the guard.
+* This is a genuine structural check, not a relabeled assertion — though it
+* necessarily stops at each field's runtime *kind*, since the field's actual
+* generic instantiation is erased at runtime and no guard can validate it.
+* That part remains the caller's responsibility, same as with any other
+* generic function in TypeScript.
+*/
+function isFactoryOptionsLike(options, extraFieldValidators) {
+	if (!isObject(options)) return false;
+	const validators = {
+		...FACTORY_OPTIONS_FIELD_VALIDATORS,
+		...extraFieldValidators
+	};
+	for (const [key, value] of Object.entries(options)) {
+		const validate = validators[key];
+		if (!validate || !validate(value)) return false;
+	}
+	return true;
+}
+//#endregion
+//#region ../../adapters/react/src/shared/to-react-factory-options.ts
+/** React-specific additions on top of `FactoryOptions`. */
+const REACT_FIELD_VALIDATORS = {
+	slotComponent: (v) => v === void 0 || isFunction(v) || isObject(v),
+	filterProps: (v) => v === void 0 || isFunction(v),
+	artifact: (v) => v === void 0 || isObject(v)
+};
+/**
+* Type guard narrowing the generic `FactoryOptions` shape down to
+* `ReactFactoryOptions` — the type `buildRuntime` is declared against. See
+* `isFactoryOptionsLike` for what this does and doesn't validate.
+*/
+function isReactFactoryOptions(options) {
+	return isFactoryOptionsLike(options, REACT_FIELD_VALIDATORS);
+}
+//#endregion
+//#region ../../adapters/react/src/shared/is-polymorphic-component.ts
+/**
+* Type guard narrowing a generated component's real (framework-specific)
+* function type down to the public `PolymorphicComponent<G>` interface
+* every adapter factory exposes.
+*
+* `PolymorphicComponent<G>`'s call signatures reference `G`, which is
+* erased at runtime, so no guard can check them — the only thing this
+* interface asserts that's actually observable at runtime is "callable" and
+* an optional `displayName` of the right kind. That's a complete check for
+* everything the type declares outside its (compile-time-only) call
+* signatures.
+*/
+function isPolymorphicComponent(value) {
+	if (!isFunction(value)) return false;
+	if (!("displayName" in value)) return true;
+	return value.displayName === void 0 || isString(value.displayName);
+}
+//#endregion
+//#region ../../adapters/react/src/current/slot/composeRefs.ts
+function getChildRef(element) {
+	return hasWarningGetter(element.props, "ref") ? getElementRef(element) : getPropsRef(element);
+}
+//#endregion
+//#region ../../adapters/react/src/current/slot/cloneSlotChild.ts
+const cloneSlotChild = makeCloneSlotChild(getChildRef);
+//#endregion
+//#region ../../adapters/react/src/current/slot/Slot.tsx
+function Slot({ ref = null, children, ...slotProps }) {
+	return applySlot(children, slotProps, ref, cloneSlotChild);
+}
+Slot.displayName = SLOT_NAME;
+//#endregion
+//#region ../../adapters/react/src/current/normalize-children.ts
+const isNonEmptyTextChild = (child) => typeof child === "number" || typeof child === "string" && child.trim().length > 0;
+function normalizeChildren(children) {
+	if (isValidElement(children)) return [children];
+	if (isNonEmptyTextChild(children)) return [children];
+	if (Array.isArray(children)) return children.filter((child) => isValidElement(child) || isNonEmptyTextChild(child));
+	return [];
+}
+//#endregion
+//#region ../../adapters/react/src/current/build-runtime.ts
+function buildRuntime(options) {
+	return buildRuntime$1(options, Slot, normalizeChildren);
+}
+//#endregion
+//#region ../../adapters/react/src/current/create-contract-component.ts
+/**
+* Creates a polymorphic React 19 component with praxis-kit contracts applied.
+*
+* ```tsx
+* const Button = createContractComponent({
+*   tag: 'button',
+*   name: 'Button',
+*   styling: {
+*     base: 'btn',
+*     variants: { intent: { primary: 'btn--primary', ghost: 'btn--ghost' } },
+*     defaults: { intent: 'primary' },
+*   },
+* })
+*
+* <Button intent="ghost" as="a" href="/home">Home</Button>
+* ```
+*
+* `ref` is accepted as a plain prop (React 19) and forwarded to the rendered host element or,
+* with `asChild`, to the consumer's own element. Pass `subComponents` to attach named
+* sub-components (`Card.Header`) and `onElement` to run setup once the real DOM element exists.
+*/
+function createContractComponent(options) {
+	invariant(isReactFactoryOptions(options), "options is not a valid ReactFactoryOptions object");
+	const bundle = buildRuntime(options);
+	/** Captured once from the factory options so the callback ref below can remain stable. */
+	const { onElement } = options;
+	function Component({ ref, ...props }) {
+		/**
+		* Keep current on every render so the stable callback ref can always read the latest
+		* props via getProps() without re-registering.
+		*/
+		const propsRef = useRef(props);
+		propsRef.current = props;
+		const cleanupRef = useRef(void 0);
+		/**
+		* `onElement` originates from the options object closed over by createContractComponent,
+		* not from props, so it's static for the component's lifetime — this callback intentionally
+		* stays stable across renders. React only re-invokes a stable callback ref when the
+		* underlying element instance changes (mount, replacement, or unmount), so onElement is
+		* registered once for each mounted element, regardless of how many times Component re-renders.
+		*/
+		const onElementRef = useCallback((el) => {
+			if (!onElement) return;
+			if (el) {
+				/**
+				* Defensive: React currently always calls this ref with `null` before a replacement
+				* element, but that ordering isn't part of the formal callback-ref contract — clean up
+				* any existing registration first so a hypothetical el→el invocation can't leak one.
+				* Cleared right after invoking, not left to be overwritten below, so a subsequent
+				* `onElement(...)` throw doesn't leave a stale, already-invoked cleanup in place to be
+				* run a second time on unmount.
+				*/
+				cleanupRef.current?.();
+				cleanupRef.current = void 0;
+				/**
+				* The real element's actual tag is only known at runtime (`tag` default or a consumer's
+				* `as` override); `onElement`'s parameter type narrows that per-component via `TDefault`/
+				* `TAllowed`, which the DOM ref API itself can't express — see `FactoryOptions.onElement`.
+				*/
+				cleanupRef.current = onElement(el, () => propsRef.current) ?? void 0;
+			} else {
+				cleanupRef.current?.();
+				cleanupRef.current = void 0;
+			}
+		}, []);
+		const mergedRef = onElement ? mergeRefs(ref, onElementRef) : ref;
+		return render({
+			...bundle,
+			props,
+			ref: mergedRef ?? null
+		});
+	}
+	applyDisplayName(Component, options.name);
+	const assembled = finalizeComponent(Component, bundle.runtime.options.defaultTag, options.subComponents);
+	invariant(isPolymorphicComponent(assembled), "Generated component failed to satisfy the PolymorphicComponent shape");
+	/**
+	* MergeRecords is a conditional type. While these generics are still open, TypeScript cannot
+	* prove that the assembled value satisfies the same conditional expression used by the
+	* declared return type. Once the generics are instantiated at a call site, the conditional
+	* simplifies correctly. The invariant above validates the runtime shape; this assertion
+	* bridges the gap in the compiler's type reasoning.
+	*/
+	return assembled;
+}
+//#endregion
+export { Slottable, createContractComponent, defineContractComponent, mergeRefs };

package/dist/react/legacy.d.ts

@@ -0,0 +1,29 @@
+import { C as MergeRecords, E as AnyRecord, S as EmptyRecord, T as NoVariants, _ as ExtractPluginProps, a as PolymorphicProps, b as VariantMap, c as RenderCallbackProps, d as SlottableProps, f as mergeRefs, g as AnyClassPluginFactory, h as FactoryOptions, i as PolymorphicComponent, l as UnknownProps, m as AnyFactoryOptions, n as ContractProps, o as PolymorphicWithAsChild, p as defineContractComponent, r as ElementRef, s as PolymorphicWithRender, t as ReactFactoryOptions, u as Slottable, v as PolymorphicGenerics, w as NoPreset, x as ElementType, y as RecipeMap } from "../index-BIBd_iPD.js";
+//#region ../../adapters/react/src/legacy/create-contract-component.d.ts
+/**
+ * Creates a polymorphic React component with praxis-kit contracts applied, for React 18 and
+ * earlier (use `praxis-kit/react` instead on React 19, which accepts `ref` as a plain prop).
+ *
+ * ```tsx
+ * const Button = createContractComponent({
+ *   tag: 'button',
+ *   name: 'Button',
+ *   styling: {
+ *     base: 'btn',
+ *     variants: { intent: { primary: 'btn--primary', ghost: 'btn--ghost' } },
+ *     defaults: { intent: 'primary' },
+ *   },
+ * })
+ *
+ * <Button intent="ghost" as="a" href="/home">Home</Button>
+ * ```
+ *
+ * Returns a `forwardRef` component — `ref` is forwarded to the rendered host element the same
+ * way it works in `praxis-kit/react`. Pass `subComponents` to attach named sub-components
+ * (`Card.Header`) and `onElement` to run setup once the real DOM element exists.
+ */
+export declare function createContractComponent<TDefault extends ElementType, Props extends UnknownProps = EmptyRecord, Variants extends Readonly<VariantMap> = NoVariants, TPreset extends RecipeMap<Variants> = NoPreset, TPlugin extends AnyClassPluginFactory = AnyClassPluginFactory, TAllowed extends ElementType = ElementType, TSubComponents extends Readonly<AnyRecord> = EmptyRecord>(options: ReactFactoryOptions<TDefault, Props, Variants, TPreset, TPlugin, TAllowed> & {
+  readonly subComponents?: TSubComponents;
+}): MergeRecords<PolymorphicComponent<PolymorphicGenerics<TDefault, MergeRecords<Props, ExtractPluginProps<TPlugin>>, Variants, TPreset, TAllowed>>, TSubComponents>;
+//#endregion
+export { type AnyFactoryOptions, type ContractProps, type ElementRef, type ElementType, type EmptyRecord, type FactoryOptions, type PolymorphicComponent, type PolymorphicGenerics, type PolymorphicProps, type PolymorphicWithAsChild, type PolymorphicWithRender, type ReactFactoryOptions, type RenderCallbackProps, Slottable, type SlottableProps, defineContractComponent, mergeRefs };

package/dist/react/legacy.js

@@ -0,0 +1,80 @@
+import { a as getElementRef, c as Slottable, d as finalizeComponent, f as SLOT_NAME, g as defineContractComponent, i as makeCloneSlotChild, l as applyDisplayName, n as render, o as getPropsRef, r as applySlot, s as hasWarningGetter, t as buildRuntime$1, u as mergeRefs } from "../build-runtime-CJ_nQEaZ.js";
+import { Children, forwardRef, isValidElement, useCallback, useRef } from "react";
+//#region ../../adapters/react/src/legacy/slot/composeRefs.ts
+function getChildRef(element) {
+	return hasWarningGetter(element, "ref") ? getPropsRef(element) : getElementRef(element);
+}
+//#endregion
+//#region ../../adapters/react/src/legacy/slot/cloneSlotChild.ts
+const cloneSlotChild = makeCloneSlotChild(getChildRef);
+//#endregion
+//#region ../../adapters/react/src/legacy/slot/Slot.tsx
+const Slot = forwardRef(function Slot({ children, ...slotProps }, ref) {
+	return applySlot(children, slotProps, ref, cloneSlotChild);
+});
+Slot.displayName = SLOT_NAME;
+//#endregion
+//#region ../../adapters/react/src/legacy/normalize-children.ts
+const isNonEmptyTextChild = (child) => typeof child === "number" || typeof child === "string" && child.trim().length > 0;
+function normalizeChildren(children) {
+	return Children.toArray(children).filter((child) => isValidElement(child) || isNonEmptyTextChild(child));
+}
+//#endregion
+//#region ../../adapters/react/src/legacy/build-runtime.ts
+function buildRuntime(options) {
+	return buildRuntime$1(options, Slot, normalizeChildren);
+}
+//#endregion
+//#region ../../adapters/react/src/legacy/create-contract-component.ts
+/**
+* Creates a polymorphic React component with praxis-kit contracts applied, for React 18 and
+* earlier (use `praxis-kit/react` instead on React 19, which accepts `ref` as a plain prop).
+*
+* ```tsx
+* const Button = createContractComponent({
+*   tag: 'button',
+*   name: 'Button',
+*   styling: {
+*     base: 'btn',
+*     variants: { intent: { primary: 'btn--primary', ghost: 'btn--ghost' } },
+*     defaults: { intent: 'primary' },
+*   },
+* })
+*
+* <Button intent="ghost" as="a" href="/home">Home</Button>
+* ```
+*
+* Returns a `forwardRef` component — `ref` is forwarded to the rendered host element the same
+* way it works in `praxis-kit/react`. Pass `subComponents` to attach named sub-components
+* (`Card.Header`) and `onElement` to run setup once the real DOM element exists.
+*/
+function createContractComponent(options) {
+	const bundle = buildRuntime(options);
+	const { onElement } = options;
+	const Component = forwardRef(function Component(props, ref) {
+		const propsRef = useRef(props);
+		propsRef.current = props;
+		const cleanupRef = useRef(void 0);
+		const onElementRef = useCallback((el) => {
+			if (!onElement) return;
+			if (el) {
+				cleanupRef.current?.();
+				cleanupRef.current = void 0;
+				cleanupRef.current = onElement(el, () => propsRef.current) ?? void 0;
+			} else {
+				cleanupRef.current?.();
+				cleanupRef.current = void 0;
+			}
+		}, []);
+		const mergedRef = onElement ? mergeRefs(ref, onElementRef) : ref;
+		return render({
+			...bundle,
+			props,
+			ref: mergedRef
+		});
+	});
+	applyDisplayName(Component, options.name);
+	return finalizeComponent(Component, bundle.runtime.options.defaultTag, options.subComponents);
+}
+//#endregion
+export { Slottable, createContractComponent, defineContractComponent, mergeRefs };