veltra-compositions

veltra-compositions

Generated artifacts

File	Content
generated/modules/	One per use-* , containing all .ts source code under that module
generated/manifest.json	Sync time and module file list
references/usage-patterns.md	Real call snippets in desktop

Run bun run sync-veltra-compositions or bun run sync-skills to regenerate generated/。

Import conventions

import {
  useModel,
  usePop,
  useVirtualizer,
  useTransition,
  useFallbackProps,
  useFormFallbackProps,
  useFormComponent,
  useConfig,
  useComponentProps,
  useDrag,
  useFocus,
  useReactiveSize,
  useResizeObserver,
  useObserverCallback,
  useUserAction
} from '@veltra/compositions'

Just import the functions you use on demand; there is no default export.

Function quick reference (14)

Function	Purpose	Key parameters / behavior	Return value highlights
useModel	Custom v-model (non- defineModel scenarios)	propName、local(bool or function),shallow	ref-like { value }
useUserAction	Block modelValue backflow side effects during user actions	None	{ userAction, isUserActive }
useDrag	Dragging (such as a dialog title bar)	Target ref, boundaries, etc.	Drag state and controls
useFocus	Focus and hover semantics	Callbacks	focus、handleFocus、handleBlur etc.
useTransition	Transitions:css or style	target、name / style keyframes	enter、leave
usePop	Popper positioning	triggerRef、contentRef、direction	update、popperContainerId
useReactiveSize	Reactive size measurement	Element / size source	Size ref
useResizeObserver / useObserverCallback	ResizeObserver and callback helpers	Listen target, options	See use-resize-observer source code
useVirtualizer	Virtual list low-level adapter layer	count、scrollEl、contentEl / beforeEl / afterEl、estimateSize	{ virtualizer, snapshot, items, isScrolling }; sizes are written imperatively via the DOM, business semantics are assembled by the consumer
useFallbackProps	props → global config fallback	Source object array, default value table	Ref for each field
useFormFallbackProps	Three-level fallback for form scenarios	[formProps, props] + default value	Same as above
useFormComponent	Form provide / inject	Parent passes props; child takes no arguments	formProps、inForm etc.
useConfig	Global document/size and other configuration	Read config	config etc.
useComponentProps	Normalize component props	Depends on the specific API	See source code

Choosing by scenario

State and concurrency

• useModel: when you need a prop name other than modelValue , or when the local function switches between controlled/uncontrolled (such as a table's current row).
• useUserAction: block synchronous side effects caused by modelValue backflow during user actions; wrap event handlers with userAction(fn) (do not call it yourself), and on the side-effect side use isUserActive() for an early return.

UI interaction

• useDrag、useFocus: dialog dragging, input focus management.
• useTransition: when a transition inside a popover or dialog needs to be triggered programmatically enter/leave (often used with usePop ).

Layout and lists

• usePop: positioning floating layers such as dropdowns and Tooltips.
• useReactiveSize、useResizeObserver: recalculate layout as the container changes.
• useVirtualizer: Vue glue layer for virtualizing large lists, dropdown options, and table bodies; returns { virtualizer, snapshot, items, isScrolling }, dimensions are written imperatively via DOM (contentEl / beforeEl / afterEl），virtualEnabled / v-for :key / scrollTo alignment modes and other business semantics are explicitly assembled by the consumer.

Form

• useFormComponent: synchronizes context between UForm and child controls.
• useFormFallbackProps: uniformly applied on form child components such as size / disabled / readonly , etc.
• useFallbackProps: the same fallback logic when detached from the form.
• useConfig: reads global dimensions, etc., and works in coordination with @veltra/styles 's loadTheme .

Component Enhancements

• useComponentProps: normalization or compatibility layer for incoming props (see comments in source code).

Further Reading (Legacy Reference Documentation)

and generated/ are mirror complements: source code location, module map, and authoring patterns.

• references/source-discovery.md
• references/api-map.md
• references/patterns.md

Maintenance

• Authoritative source location:packages/compositions/src/。
• After modifying the API, please run bun run sync-veltra-compositions to update generated/, so that the skill documentation stays consistent with the types.