ropav 0.1.5 → 0.1.7

package/dist/useFormControl.js

@@ -1,5 +1,5 @@
 import { inject, provide, watchEffect } from "vue";
-//#region src/composables/useFormControl.ts
+//#region src/internal/composables/useFormControl.ts
 var nestedFormControlOwnerKey = Symbol("nestedFormControlOwner");
 function provideNestedFormControlOwner() {
 	let claimed = false;
@@ -32,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(() => {

package/dist/useOverlayZIndex.js

@@ -1,5 +1,6 @@
+import { n as isEventWithinElement } from "./events.js";
 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();
@@ -38,11 +39,6 @@ function syncLayerZIndices(state) {
 		highestZIndex = zIndex;
 	}
 }
-function isEventWithinElement(event, element) {
-	const path = event.composedPath();
-	if (path.length > 0) return path.some((entry) => entry === element || typeof Node !== "undefined" && entry instanceof Node && element.contains(entry));
-	return typeof Node !== "undefined" && event.target instanceof Node && element.contains(event.target);
-}
 function restoreInertBackground(state) {
 	for (const [element, snapshot] of state.inertSnapshots) {
 		element.inert = snapshot.inert;

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/useTeleportTarget.js

@@ -7,21 +7,14 @@ function readTeleportTarget(target) {
 function hasTarget(target) {
 	return target != null && target !== "";
 }
-function provideTeleportTarget(props, positioningKey) {
+function provideTeleportTarget(props) {
 	const parentContext = inject(teleportTargetKey, void 0);
 	const target = computed(() => {
 		const ownTarget = readTeleportTarget(props.teleportTo);
 		if (hasTarget(ownTarget)) return ownTarget;
 		return parentContext?.target.value ?? "body";
 	});
-	provide(teleportTargetKey, {
-		target,
-		positioningKey: computed(() => [
-			target.value,
-			toValue(positioningKey),
-			parentContext?.positioningKey.value
-		])
-	});
+	provide(teleportTargetKey, { target });
 	return target;
 }
 function useTeleportTarget(target) {
@@ -32,9 +25,5 @@ function useTeleportTarget(target) {
 		return providedContext?.target.value ?? "body";
 	});
 }
-function useTeleportPositioningKey() {
-	const providedContext = inject(teleportTargetKey, void 0);
-	return computed(() => providedContext?.positioningKey.value);
-}
 //#endregion
-export { useTeleportPositioningKey as n, useTeleportTarget as r, provideTeleportTarget as t };
+export { useTeleportTarget as n, provideTeleportTarget as t };

package/dist/useTypeahead.js

@@ -0,0 +1,94 @@
+import { n as normalizeTypeaheadText } from "./text.js";
+import { onBeforeUnmount } from "vue";
+//#region src/internal/composables/useTypeahead.ts
+var DEFAULT_TYPEAHEAD_TIMEOUT = 1e3;
+function isRepeatedQuery(query) {
+	const characters = [...query];
+	return characters.length > 1 && characters.every((character) => character === characters[0]);
+}
+function useTypeahead(options) {
+	let buffer = "";
+	let timer;
+	let lastMatch;
+	let currentScope = options.scopeKey?.();
+	const isDisabled = options.isDisabled ?? (() => false);
+	function clearTimer() {
+		if (timer !== void 0) clearTimeout(timer);
+		timer = void 0;
+	}
+	function reset() {
+		clearTimer();
+		buffer = "";
+		lastMatch = void 0;
+		currentScope = options.scopeKey?.();
+	}
+	function scheduleReset() {
+		clearTimer();
+		timer = setTimeout(reset, options.timeout ?? DEFAULT_TYPEAHEAD_TIMEOUT);
+	}
+	function hasBuffer() {
+		return buffer.length > 0;
+	}
+	function getMatchIndex(query, startIndex, keepCurrent) {
+		const items = options.items();
+		if (items.length === 0) return -1;
+		function matches(index) {
+			const item = items[index];
+			return Boolean(item && !isDisabled(item) && normalizeTypeaheadText(options.getTextValue(item)).startsWith(query));
+		}
+		if (keepCurrent && startIndex >= 0 && matches(startIndex)) return startIndex;
+		for (let offset = 1; offset <= items.length; offset += 1) {
+			const index = (startIndex + offset + items.length) % items.length;
+			if (matches(index)) return index;
+		}
+		return -1;
+	}
+	function getLastMatchIndex(items) {
+		const match = lastMatch;
+		if (!match) return -1;
+		if (Object.is(items[match.index], match.item)) return match.index;
+		const identityIndex = items.findIndex((item) => Object.is(item, match.item));
+		if (identityIndex >= 0) return identityIndex;
+		let keyIndex = -1;
+		for (let index = 0; index < items.length; index += 1) {
+			if (!Object.is(options.getKey(items[index]), match.key)) continue;
+			if (keyIndex >= 0) return -1;
+			keyIndex = index;
+		}
+		return keyIndex;
+	}
+	function handleKey(event) {
+		const nextScope = options.scopeKey?.();
+		if (!Object.is(currentScope, nextScope)) reset();
+		currentScope = nextScope;
+		if (event.ctrlKey || event.metaKey || event.altKey || event.isComposing || [...event.key].length !== 1 || event.key === " " && !hasBuffer()) return false;
+		event.preventDefault();
+		buffer += event.key;
+		scheduleReset();
+		const normalizedBuffer = normalizeTypeaheadText(buffer);
+		if (!normalizedBuffer) return true;
+		const repeated = isRepeatedQuery(normalizedBuffer);
+		const query = repeated ? [...normalizedBuffer][0] : normalizedBuffer;
+		const items = options.items();
+		const lastMatchIndex = getLastMatchIndex(items);
+		const matchIndex = getMatchIndex(query, lastMatchIndex >= 0 ? lastMatchIndex : options.activeIndex(), !repeated && [...query].length > 1);
+		if (matchIndex < 0) return true;
+		const item = items[matchIndex];
+		if (!item) return true;
+		lastMatch = {
+			item,
+			index: matchIndex,
+			key: options.getKey(item)
+		};
+		options.onMatch(item, matchIndex);
+		return true;
+	}
+	onBeforeUnmount(clearTimer);
+	return {
+		handleKey,
+		hasBuffer,
+		reset
+	};
+}
+//#endregion
+export { useTypeahead as t };

package/dist/utils/aria.d.ts

@@ -0,0 +1,3 @@
+export declare function parseAriaIdRefs(value: string | null | undefined): string[];
+export declare function hasAriaIdRef(value: string | null | undefined, id: string): boolean;
+export declare function mergeAriaIdRefs(...values: Array<string | null | undefined>): string | undefined;

package/dist/utils/attributes.d.ts

@@ -0,0 +1,2 @@
+export declare function toPresenceAttribute(value: unknown): '' | undefined;
+export declare function toOptionalAttribute<T extends boolean | string | undefined>(value: T): T | undefined;

package/dist/utils/bem.d.ts

@@ -0,0 +1,3 @@
+type BemModifier = string | Record<string, boolean | undefined>;
+export declare function bem(block: string, ...modifiers: BemModifier[]): string[];
+export {};

package/dist/utils/collectionNavigation.d.ts

@@ -0,0 +1,2 @@
+export declare function getEnabledIndexes<T>(items: readonly T[], isDisabled: (item: T) => boolean): number[];
+export declare function getNextEnabledIndex<T>(items: readonly T[], currentIndex: number, direction: 1 | -1, isDisabled: (item: T) => boolean, loop?: boolean): number | undefined;

package/dist/utils/color.d.ts

@@ -0,0 +1,7 @@
+export interface ParsedCssColor {
+    red: number;
+    green: number;
+    blue: number;
+    opacity: number;
+}
+export declare function parseCssColor(value: string): ParsedCssColor | undefined;

package/dist/{components/color-picker/color-picker-utils.d.ts → utils/colorPicker.d.ts}

@@ -1,22 +1,23 @@
-import { ColorPickerFormat } from './types.js';
+export declare const colorPickerFormats: readonly ["hex", "hexa", "rgb", "rgba", "hsl", "hsla"];
+export type ColorPickerFormat = (typeof colorPickerFormats)[number];
 export declare const DEFAULT_HUE = 0;
 export declare const HUE_MAX = 359;
-export declare const KEYBOARD_STEP = 1;
-export declare const KEYBOARD_LARGE_STEP = 10;
 export declare const DEFAULT_OPACITY = 100;
+export declare const COLOR_PICKER_KEYBOARD_STEP = 1;
+export declare const COLOR_PICKER_KEYBOARD_LARGE_STEP = 10;
 export interface ColorPickerHsvColor {
     hue: number;
     saturation: number;
     value: number;
     opacity: number;
 }
-export declare function clamp(value: number, min: number, max: number): number;
 export declare function clampPercent(value: number | undefined): number;
 export declare function normalizeHue(value: number | undefined): number;
 export declare function normalizeHueForColor(value: number | undefined): number;
 export declare function clampHue(value: number): number;
 export declare function clampOpacity(value: number | undefined): number;
 export declare function roundPercent(value: number): number;
+export declare function getColorPickerKeyboardValue(key: string, currentValue: number, maxValue: number, step?: number): number | undefined;
 export declare function isColorPickerAlphaFormat(format: ColorPickerFormat): format is "hexa" | "rgba" | "hsla";
 export declare function parseColorPickerValue(value: string): ColorPickerHsvColor | undefined;
 export declare function formatColorPickerValue(color: ColorPickerHsvColor, format: ColorPickerFormat): string;

package/dist/utils/componentColors.d.ts

@@ -46,6 +46,12 @@ export interface ComponentVariantColorOptions extends ComponentContrastColorOpti
     variant: ComponentColorVariant | undefined;
     defaultColor?: ComponentColorValue;
 }
+export interface ComponentCheckedColorStyleOptions extends ComponentContrastColorOptions {
+    color: ComponentColorValue | undefined;
+    colorProperty: `--${string}`;
+    checkedColorProperty: `--${string}`;
+    defaultColor?: ComponentColorValue;
+}
 export type ParsedComponentColor = {
     kind: 'empty';
 } | {
@@ -68,6 +74,7 @@ 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 getComponentCheckedColorStyle({ color, colorProperty, checkedColorProperty, defaultColor, autoContrast, contrastColor, }: ComponentCheckedColorStyleOptions): Record<string, string> | undefined;
 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, contrastColor, }: ComponentVariantColorOptions): ComponentVariantColorRoles | undefined;

package/dist/utils/css.d.ts

@@ -0,0 +1,3 @@
+export type CssLength = number | string | null | undefined;
+export declare function toCssLength(value: CssLength): string | undefined;
+export declare function toPositiveCssLength(value: CssLength): string | undefined;

package/dist/utils/dom/ancestry.d.ts

@@ -0,0 +1,7 @@
+export interface ObserveComposedAncestryOptions {
+    deferWhileDisconnected?: boolean;
+}
+export declare function getComposedParent(node: Node): Node | null;
+export declare function getComposedAncestry(node: Node | null | undefined): Node[];
+export declare function areNodeListsIdentical(left: readonly Node[], right: readonly Node[]): boolean;
+export declare function observeComposedAncestry(getNodes: () => readonly (Node | null | undefined)[], onChange: () => void, options?: ObserveComposedAncestryOptions): () => void;

package/dist/utils/dom/attributes.d.ts

@@ -0,0 +1,16 @@
+export type AttributeSnapshot<Name extends string = string> = ReadonlyMap<Name, string | null>;
+export interface CompatibilityAttributes {
+    class?: unknown;
+    style?: unknown;
+}
+export type EventHandler<EventType extends Event> = (event: EventType) => unknown;
+export declare function splitCompatibilityAttributes<Attributes extends CompatibilityAttributes>(attributes: Attributes): {
+    compatibilityClass: Attributes['class'];
+    compatibilityStyle: Attributes['style'];
+    forwardedAttributes: Omit<Attributes, 'class' | 'style'>;
+};
+export declare function composeEventHandlers<EventType extends Event>(...handlers: ReadonlyArray<EventHandler<EventType> | undefined>): (event: EventType) => void;
+export declare function parseAttributeTokens(value: string | null | undefined): string[];
+export declare function hasAttributeToken(value: string | null | undefined, token: string): boolean;
+export declare function snapshotAttributes<Name extends string>(element: Element, attributes: readonly Name[]): AttributeSnapshot<Name>;
+export declare function restoreAttributes(element: Element, snapshot: AttributeSnapshot): void;

package/dist/utils/dom/componentRef.d.ts

@@ -0,0 +1,4 @@
+import { ComponentPublicInstance, VaporComponentInstance } from 'vue';
+export type ComponentElementRef = Element | ComponentPublicInstance | VaporComponentInstance | null;
+export declare function toHTMLElement(value: ComponentElementRef, fallbackId?: string): HTMLElement | null;
+export declare function resolveHTMLElementRef(value: ComponentElementRef, fallbackId: string, resolve: (element: HTMLElement | null) => void): void;

package/dist/utils/dom/events.d.ts

@@ -0,0 +1,5 @@
+export declare function isNodeWithinElement(value: unknown, element: unknown): value is Node;
+export declare function isEventWithinElement(event: Event, element: Element): boolean;
+export type EventContainmentTarget = string | Element | null | undefined;
+export declare function isEventWithinTargets(event: Event, targets: readonly EventContainmentTarget[]): boolean;
+export declare function createCancelableCustomEvent<T>(type: string, detail: T, originalEvent: Event): CustomEvent<T>;

package/dist/utils/dom/focusNavigation.d.ts

@@ -0,0 +1,7 @@
+export type FocusNavigationOrientation = 'horizontal' | 'vertical';
+export interface FocusNavigationOptions {
+    itemSelector: string;
+    collectionSelector: string;
+    orientation: FocusNavigationOrientation;
+}
+export declare function getFocusNavigationTarget<ElementType extends HTMLElement>(event: Pick<KeyboardEvent, 'key' | 'target'>, collection: HTMLElement, options: FocusNavigationOptions): ElementType | undefined;

package/dist/utils/dom/interactive.d.ts

@@ -0,0 +1,2 @@
+export declare const INTERACTIVE_ELEMENT_SELECTOR: string;
+export declare function isInteractiveElement(target: unknown, ignoredSelector?: string): boolean;

package/dist/utils/dom/pointer.d.ts

@@ -0,0 +1,2 @@
+export declare function getPointerId(event: Pick<PointerEvent, 'pointerId'>): number | undefined;
+export declare function isMatchingPointer(event: Pick<PointerEvent, 'pointerId'>, pointerId: number | undefined): boolean;

package/dist/utils/dom/query.d.ts

@@ -0,0 +1,4 @@
+export declare function isElement(value: unknown): value is Element;
+export declare function matchesSelectorSafe(element: Element, selector: string): boolean;
+export declare function querySelectorSafe<ElementType extends Element = Element>(selector: string, root?: ParentNode | null): ElementType | null;
+export declare function querySelectorAllSafe<ElementType extends Element = Element>(selector: string, root?: ParentNode | null): ElementType[];

package/dist/utils/dom/scroll.d.ts

@@ -0,0 +1,23 @@
+export type ScrollAxis = 'x' | 'y';
+export type ScrollDirection = 'ltr' | 'rtl';
+export interface KeyboardScrollPositionOptions {
+    axis: ScrollAxis;
+    key: string;
+    current: number;
+    pageSize: number;
+    maxPosition: number;
+    direction: ScrollDirection;
+    lineStep: number;
+}
+export declare function getScrollDirection(element: Element): ScrollDirection;
+export declare function getLogicalHorizontalScrollPosition(scrollLeft: number, maxPosition: number, direction: ScrollDirection): number;
+export declare function getRawHorizontalScrollPosition(position: number, maxPosition: number, direction: ScrollDirection): number;
+export declare function getScrollThumbGeometry(trackSize: number, viewportSize: number, scrollSize: number, minimumSize: number): {
+    size: number;
+    offsetRatio: number;
+};
+export declare function getScrollThumbOffset(position: number, maxPosition: number, sizeRatio: number): number;
+export declare function getKeyboardScrollPosition({ axis, key, current, pageSize, maxPosition, direction, lineStep, }: KeyboardScrollPositionOptions): number | undefined;
+export declare function getWheelScrollDelta(axis: ScrollAxis, event: Pick<WheelEvent, 'deltaX' | 'deltaY'>, direction: ScrollDirection): number;
+export declare function applyFallbackScrollPosition(element: Pick<HTMLElement, 'scrollLeft' | 'scrollTop'>, options: Pick<ScrollToOptions, 'left' | 'top'>, mode: 'absolute' | 'relative'): void;
+export declare function getPointerAxisCoordinate(axis: ScrollAxis, event: Pick<PointerEvent, 'clientX' | 'clientY'>): number;

package/dist/utils/floatingOffset.d.ts

@@ -0,0 +1,10 @@
+export interface FloatingOffsetAxes {
+    mainAxis?: number;
+    crossAxis?: number;
+}
+export type FloatingOffsetValue = number | FloatingOffsetAxes;
+export interface FloatingOffsetProperties {
+    mainAxis: `--${string}`;
+    crossAxis: `--${string}`;
+}
+export declare function getFloatingOffsetStyle(offset: FloatingOffsetValue | null | undefined, properties: FloatingOffsetProperties): Record<string, string> | undefined;

package/dist/utils/geometry.d.ts

@@ -0,0 +1,14 @@
+export interface Point {
+    x: number;
+    y: number;
+}
+export type Triangle = [Point, Point, Point];
+type RectBounds = Pick<DOMRect, 'bottom' | 'height' | 'left' | 'right' | 'top' | 'width'>;
+export declare function getClientPoint(event: Pick<MouseEvent, 'clientX' | 'clientY'>): Point;
+export declare function hasMeasuredRect(rect: Pick<DOMRect, 'height' | 'width'>): boolean;
+export declare function isPointInRect(point: Point, rect: RectBounds, padding?: number): boolean;
+export declare function getTriangleArea(a: Point, b: Point, c: Point): number;
+export declare function isPointInTriangle(point: Point, triangle: Triangle, tolerance?: number): boolean;
+export declare function clampPointToRect(point: Point, rect: RectBounds): Point;
+export declare function createPointRect(point: Point): DOMRect;
+export {};

package/dist/utils/indexPath.d.ts

@@ -0,0 +1,6 @@
+export type IndexPath = number[];
+export declare function getPathKey(path: IndexPath): string;
+export declare function getParentPath(path: IndexPath): IndexPath;
+export declare function arePathsEqual(a: IndexPath, b: IndexPath): boolean;
+export declare function isPathPrefix(prefix: IndexPath, path: IndexPath): boolean;
+export declare function normalizePath(indexOrPath: number | IndexPath): IndexPath;

package/dist/utils/number.d.ts

@@ -0,0 +1,4 @@
+export declare function clamp(value: number, min: number, max: number): number;
+export declare function getValuePercent(value: number, min: number, max: number): number;
+export declare function normalizeDelay(value: number | null | undefined, fallback?: number): number;
+export declare function roundTo(value: number, fractionDigits?: number): number;

package/dist/utils/rafScheduler.d.ts

@@ -0,0 +1,4 @@
+export declare function createRafScheduler(callback: () => void, getView: () => Window | null | undefined): {
+    cancel: () => void;
+    schedule: () => void;
+};

package/dist/utils/text.d.ts

@@ -0,0 +1,2 @@
+export declare function getNameInitials(name: string | null | undefined): string;
+export declare function normalizeTypeaheadText(value: string, locales?: Intl.LocalesArgument): string;

package/docs/code-architecture.md

@@ -0,0 +1,118 @@
+# Code architecture
+
+This guide defines the source structure expected from contributors. The goal is a predictable
+codebase where UI files describe rendering, behavior is testable through small interfaces, and
+shared logic has one obvious home.
+
+## Module seams
+
+A module should hide a meaningful amount of behavior behind a small interface. Extract code around
+a responsibility, not merely to reduce a line count. A useful extraction makes callers simpler and
+lets tests exercise the same interface that production code uses.
+
+Use this dependency direction:
+
+```text
+Vue components and component-local modules
+    -> internal composables
+    -> public composables
+    -> utilities
+```
+
+A higher layer may also import a lower layer directly. Lower layers must not import higher layers:
+
+- `src/utils/` does not import components or composables.
+- `src/composables/` does not import components or internal modules.
+- `src/internal/` does not import components.
+- Components may compose other components when the dependency remains acyclic.
+
+## Where code belongs
+
+| Location                                  | Responsibility                                                        |
+| ----------------------------------------- | --------------------------------------------------------------------- |
+| `src/components/<name>/*.vue`             | Template, bindings, slots, and lightweight view-derived state         |
+| `src/components/<name>/useX.ts`           | Component-specific reactive state, lifecycle, and event orchestration |
+| `src/components/<name>/<concern>Model.ts` | Pure behavior that encodes only that component's contract             |
+| `src/internal/composables/`               | Shared reactive behavior that is not part of the package interface    |
+| `src/composables/`                        | Reusable public composables exported by the package                   |
+| `src/utils/`                              | Reusable runtime helpers without component state or lifecycle         |
+| `src/utils/dom/`                          | Reusable helpers that operate on browser and DOM primitives           |
+| `tests/`, `tooling/`, `scripts/`          | Test, build, and repository automation helpers                        |
+
+Do not add catch-all `utils`, `helpers`, or `core` modules beside a component. Keep a pure helper
+local when it expresses one component's contract, and give it a semantic name such as
+`sliderModel`. Move it to `src/utils/` once more than one feature needs the behavior.
+
+## Component shape
+
+Production SFCs use `<script setup lang="ts" vapor>` and remain zero-VDOM. Do not use `h`, `VNode`,
+`defineComponent`, `createVNode`, or related VDOM block helpers in production source.
+
+Keep SFC blocks in this order:
+
+1. `<template>`
+2. `<script setup lang="ts" vapor>`
+3. `<style>`
+
+Within the script block, use this order:
+
+1. Imports
+2. `defineOptions`, props defaults, emits, and slots
+3. Composable state and template refs
+4. View-derived computed attributes
+5. Small event adapters and `defineExpose`
+
+A short computed value used only to bind the template can stay in the SFC. Move state transitions,
+timers, document listeners, multi-step event handling, and reusable calculations behind a
+composable or pure model interface.
+
+## Function design
+
+Oxlint enforces a conservative baseline of cyclomatic complexity 20, nesting depth 4, at most 5
+parameters, and at most 250 non-blank, non-comment lines per function. These are upper bounds, not
+targets.
+
+- Give each function one reason to change.
+- Prefer guard clauses over deeply nested branches.
+- Use an options object when several parameters describe one concept.
+- Split orchestration into named steps, while keeping the external interface small.
+- Accept dependencies or callbacks at the module seam instead of constructing hard-to-test global
+  dependencies inside the implementation.
+- Return observable results where practical; isolate side effects in lifecycle or event adapters.
+
+Do not create shallow pass-through functions solely to satisfy a metric. A refactor should improve
+the caller, the module interface, or the test surface.
+
+## Imports and package interfaces
+
+- Import utilities directly from their module, for example `@/utils/number`; do not add a utils
+  barrel.
+- Component `index.ts` files define package-facing exports. Internal code should not import from the
+  root package barrel.
+- Keep imports acyclic. If two modules need each other, move the shared behavior to the lowest
+  layer that owns the concept.
+- Use `import type` for type-only dependencies.
+
+## Testing
+
+Test through the interface of the extracted module:
+
+- Pure models and utilities use deterministic unit tests.
+- Composables test returned state and commands, using the smallest host needed for lifecycle
+  behavior.
+- Component tests cover DOM integration, events, accessibility, and public rendering contracts.
+- Storybook tests cover visual and interaction scenarios that depend on real browser layout.
+
+Tests should assert observable behavior rather than private implementation details. Refactoring a
+module internally should not require rewriting its behavioral tests.
+
+## Contributor checklist
+
+Before opening a pull request:
+
+- The SFC primarily adapts props, slots, and composable results to the template.
+- New reusable helpers live in `src/utils/`; feature-only pure logic has a semantic local name.
+- Dependency direction remains downward and acyclic.
+- Functions stay below the enforced complexity, depth, length, and parameter limits.
+- New behavior is tested at the module interface.
+- `pnpm run verify` passes.

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-floating-api.md

@@ -42,7 +42,6 @@ const { actualPlacement, arrowStyle, floatingStyle } = useFloatingPosition({
   open,
   placement: 'bottom-start',
   offset: 8,
-  restartKey: () => [teleport.value, teleportTo.value],
 });
 </script>
 ```
@@ -63,7 +62,7 @@ The composable accepts plain values, refs, computed refs or getters for reactive
 | `shift`                            | `true`     | Keeps the floating element inside the collision boundary.              |
 | `collisionPadding`                 | `8`        | Padding between the floating element and viewport boundary.            |
 | `autoUpdateOptions.animationFrame` | `false`    | Tracks transform animations and detached nested floating contexts.     |
-| `restartKey`                       | —          | Rebinds auto-update observers when its reactive value changes.         |
+| `restartKey`                       | —          | Forces a rebind for reactive changes unrelated to DOM ancestry.        |
 
 Use `autoUpdateOptions.animationFrame` sparingly. It checks the reference position every animation
 frame and is intended for references moving with CSS transforms or nested floating elements outside
@@ -78,9 +77,11 @@ The return value contains readonly `actualPlacement`, `floatingStyle`, `arrowSty
 `isPositioned` refs, plus an async `update()` method for content-driven layout changes.
 
 `useTeleportTarget()` resolves the nearest `TeleportProvider` target and falls back to `body`. Pass
-a target value, ref or getter to override the provider for one floating element. Include the
-resolved target and the Teleport enabled state in `restartKey` whenever either can change while the
-floating element is open.
+a target value, ref or getter to override the provider for one floating element. Positioning
+automatically rebinds when the reference or floating element moves through the composed DOM,
+including Teleport moves, temporary detachments and slot reassignment within an existing shadow
+tree. Use `restartKey` when a reactive change outside observable DOM ancestry must recreate the
+auto-update subscriptions, such as a host attaching a new shadow root after positioning starts.
 
 Positioning does not add interaction or accessibility behavior. Custom overlays remain responsible
 for keyboard handling, focus management, roles, labels, outside interaction and dismissal.