ropav 0.1.4 → 0.1.6

package/dist/useFormControl.js

@@ -1,30 +1,5 @@
-import { computed, inject, provide, shallowRef, watch, watchEffect } from "vue";
-//#region src/composables/useControllableValue.ts
-function useControllableValue(options) {
-	const initialValue = options.defaultValue();
-	const uncontrolledValue = shallowRef(initialValue);
-	const isControlled = computed(() => options.modelValue() !== void 0);
-	watch(options.modelValue, (value) => {
-		if (value !== void 0) uncontrolledValue.value = value;
-	}, { immediate: true });
-	const value = computed(() => options.modelValue() ?? uncontrolledValue.value);
-	function setValue(nextValue) {
-		if (!isControlled.value) uncontrolledValue.value = nextValue;
-		options.onChange(nextValue);
-	}
-	function resetValue(nextValue = initialValue) {
-		if (!isControlled.value) uncontrolledValue.value = nextValue;
-	}
-	return {
-		initialValue,
-		isControlled,
-		value,
-		setValue,
-		resetValue
-	};
-}
-//#endregion
-//#region src/composables/useFormControl.ts
+import { inject, provide, watchEffect } from "vue";
+//#region src/internal/composables/useFormControl.ts
 var nestedFormControlOwnerKey = Symbol("nestedFormControlOwner");
 function provideNestedFormControlOwner() {
 	let claimed = false;
@@ -57,7 +32,8 @@ function useFormControl(options) {
 		if (documents.size === 0) return;
 		function onReset(event) {
 			const form = event.target;
-			if (!(form instanceof HTMLFormElement)) return;
+			const FormConstructor = event.currentTarget?.defaultView?.HTMLFormElement;
+			if (!FormConstructor || !(form instanceof FormConstructor)) return;
 			const elements = getElements(options).filter((element) => element.form === form);
 			if (elements.length === 0) return;
 			queueMicrotask(() => {
@@ -104,4 +80,4 @@ function useCheckedFormControl(element, controllable, validationMessage) {
 	});
 }
 //#endregion
-export { useTextFormControl as a, useFormControl as i, provideNestedFormControlOwner as n, useControllableValue as o, useCheckedFormControl as r, claimNestedFormControlOwner as t };
+export { useTextFormControl as a, useFormControl as i, provideNestedFormControlOwner as n, useCheckedFormControl as r, claimNestedFormControlOwner as t };

package/dist/useOverlayZIndex.js

@@ -1,5 +1,5 @@
 import { computed, inject, onBeforeUnmount, provide, readonly, ref, shallowRef, toValue, watch } from "vue";
-//#region src/composables/useOverlayLayer.ts
+//#region src/internal/composables/useOverlayLayer.ts
 var overlayLayerKey = Symbol("overlay-layer");
 var documentStates = /* @__PURE__ */ new WeakMap();
 var layerMetadata = /* @__PURE__ */ new WeakMap();

package/dist/useRequiredInject.js

@@ -1,5 +1,5 @@
 import { inject } from "vue";
-//#region src/composables/useRequiredInject.ts
+//#region src/internal/composables/useRequiredInject.ts
 function useRequiredInject(key, componentName) {
 	const value = inject(key);
 	if (value == null) throw new Error(`[Ropav] <${componentName}> must be used inside its parent provider component.`);

package/dist/utils/componentColors.d.ts

@@ -10,6 +10,8 @@ export interface ComponentColorRoles {
     hover: string;
     active: string;
     contrast: string;
+    contrastHover: string;
+    contrastActive: string;
     light: string;
     lightHover: string;
     lightActive: string;
@@ -22,12 +24,22 @@ export interface ComponentVariantColorRoles {
     hover: string;
     active: string;
     color: string;
+    colorHover: string;
+    colorActive: string;
     border: string;
     borderHover: string;
     borderActive: string;
 }
 export interface ComponentContrastColorOptions {
+    /** Automatically selects a readable foreground for preset and opaque custom colors. */
     autoContrast?: boolean;
+    /** Required when an automatically contrasted custom color is translucent. */
+    contrastColor?: string;
+}
+export interface ComponentContrastColorRoles {
+    color: string;
+    hover: string;
+    active: string;
 }
 export interface ComponentVariantColorOptions extends ComponentContrastColorOptions {
     color: ComponentColorValue | undefined;
@@ -56,5 +68,6 @@ export declare function isComponentPresetColor(color: ComponentColorValue | unde
 export declare function parseComponentColor(color: ComponentColorValue | undefined): ParsedComponentColor;
 export declare function getComponentColorValue(color: ComponentColorValue | undefined): string | undefined;
 export declare function getComponentContrastColor(color: ComponentColorValue | undefined, options?: ComponentContrastColorOptions): string;
+export declare function getComponentContrastColorRoles(color: ComponentColorValue | undefined, options?: ComponentContrastColorOptions): ComponentContrastColorRoles;
 export declare function getComponentColorRoles(color: ComponentColorValue | undefined): ComponentColorRoles | undefined;
-export declare function getComponentVariantColorRoles({ color, variant, defaultColor, autoContrast, }: ComponentVariantColorOptions): ComponentVariantColorRoles | undefined;
+export declare function getComponentVariantColorRoles({ color, variant, defaultColor, autoContrast, contrastColor, }: ComponentVariantColorOptions): ComponentVariantColorRoles | undefined;

package/docs/public-composables-api.md

@@ -0,0 +1,52 @@
+# Public composables API
+
+Ropav exposes framework-level composables from both the root package and the dedicated
+`ropav/composables` entrypoint. Prefer the dedicated entrypoint when an application only needs
+headless state behavior.
+
+## `useControllableValue`
+
+`useControllableValue` implements the controlled/uncontrolled value pattern used across Ropav
+components and composables. A defined `modelValue` makes the value controlled; only `undefined`
+selects internal state, so values such as `null` and `false` remain controlled values.
+
+```vue
+<script setup lang="ts">
+import { useControllableValue } from 'ropav/composables';
+
+const props = withDefaults(
+  defineProps<{
+    modelValue?: string;
+    defaultValue?: string;
+  }>(),
+  {
+    modelValue: undefined,
+    defaultValue: '',
+  },
+);
+
+const emit = defineEmits<{
+  'update:modelValue': [value: string];
+}>();
+
+const { value, isControlled, setValue, resetValue } = useControllableValue({
+  modelValue: () => props.modelValue,
+  defaultValue: () => props.defaultValue,
+  onChange: (value) => emit('update:modelValue', value),
+});
+</script>
+```
+
+`defaultValue()` is read once when the composable is created. `setValue()` updates internal state
+only in uncontrolled mode and always calls `onChange`, including repeated requests for the same
+value. In controlled mode, the parent remains responsible for updating `modelValue`, and a rejected
+change request does not replace the internal fallback.
+
+`resetValue(value)` updates uncontrolled state without calling `onChange`. Calling `resetValue()`
+without an argument restores the initial default. A reset is a no-op while controlled. If a value
+changes from controlled to uncontrolled, the latest defined controlled value becomes the internal
+fallback synchronously. Releasing control does not call `onChange`.
+
+The return value contains readonly `value` and `isControlled` computed refs, the captured
+`initialValue`, and the `setValue()` and `resetValue()` commands. `undefined` is reserved as the
+uncontrolled sentinel and should not be used as a controlled value.

package/docs/public-styles-api.md

@@ -111,7 +111,7 @@ The exact entries in [`styles-manifest.json`](../src/styles/styles-manifest.json
 
 The manifest contains design tokens plus a deliberately small component-geometry allowlist. Slider and RangeSlider share the `--rp-slider-*` namespace. Size presets provide fallbacks, while a consumer value wins for the individual dimension. See the generated [token table](./public-tokens.md).
 
-Palette shades and their `*-contrast` companions are required override groups because `autoContrast` consumes the companion selected at build time. The [color override contract](./public-tokens.md#color-override-contract) documents the paired override and preset-role requirements.
+Palette shades and their normal and active `*-contrast` companions are required override groups because `autoContrast` consumes state-specific companions selected at build time. The [color override contract](./public-tokens.md#color-override-contract) documents the state pairings and preset-role requirements.
 
 ## Cascade layers and migration