@directus/composables 11.1.11 → 11.2.1

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { AppCollection, Field, Item, Query, RefRecord } from '@directus/types';
 import { ComputedRef, Ref, WritableComputedRef, Component } from 'vue';
-import { AppExtensionConfigs } from '@directus/extensions';
+import { LayoutConfig, AppExtensionConfigs } from '@directus/extensions';
 import { DirectusClient, RestClient } from '@directus/sdk';
 import { AxiosInstance } from 'axios';
 
@@ -14,22 +14,133 @@ type UsableCollection = {
     isSingleton: ComputedRef<boolean>;
     accountabilityScope: ComputedRef<'all' | 'activity' | null>;
 };
+/**
+ * A Vue composable that provides reactive access to collection metadata, fields, and computed properties.
+ *
+ * This composable serves as a centralized way to access and work with Directus collections,
+ * providing reactive computed properties for collection information, field definitions,
+ * default values, and various collection-specific metadata.
+ *
+ * @param collectionKey - The collection identifier. Can be a string or a reactive reference to a string.
+ *                        If null, most computed properties will return empty/null values.
+ *
+ * @returns An object containing reactive computed properties for the collection:
+ * - `info` - The complete collection configuration object or null if not found
+ * - `fields` - Array of sorted field definitions for the collection
+ * - `defaults` - Object mapping field names to their default values from schema
+ * - `primaryKeyField` - The field marked as primary key, or null if none exists
+ * - `userCreatedField` - The field with 'user_created' special type, or null if none exists
+ * - `sortField` - The field name used for sorting, from collection meta, or null
+ * - `isSingleton` - Boolean indicating if the collection is configured as a singleton
+ * - `accountabilityScope` - The accountability scope setting ('all', 'activity', or null)
+ *
+ * @example
+ * ```typescript
+ * // Using with a static collection name
+ * const { info, fields, primaryKeyField } = useCollection('users');
+ *
+ * // Using with a reactive collection name
+ * const collectionName = ref('articles');
+ * const { fields, defaults, isSingleton } = useCollection(collectionName);
+ *
+ * // Accessing properties
+ * console.log(info.value?.name); // Collection display name
+ * console.log(fields.value.length); // Number of fields
+ * console.log(primaryKeyField.value?.field); // Primary key field name
+ * ```
+ */
 declare function useCollection(collectionKey: string | Ref<string | null>): UsableCollection;
 
 type UsableCustomSelection = {
     otherValue: Ref<string | null>;
     usesOtherValue: ComputedRef<boolean>;
 };
+/**
+ * A Vue composable for managing custom selection values that aren't present in a predefined list of items.
+ *
+ * This composable is typically used in form components where users can select from a predefined list
+ * of options, but also have the ability to enter custom values that aren't in the list. It manages
+ * the state and logic for detecting when a custom value is being used and provides a reactive
+ * interface for getting and setting custom values.
+ *
+ * @param currentValue - A reactive reference to the currently selected value. Can be null if no value is selected.
+ * @param items - A reactive reference to the array of available predefined items. Each item should have a 'value' property.
+ * @param emit - A callback function to emit value changes to the parent component.
+ *
+ * @returns An object containing:
+ * - `otherValue` - A computed ref for getting/setting custom values. Returns current value when using custom,
+ *   empty string otherwise. Setting triggers the emit callback.
+ * - `usesOtherValue` - A computed boolean indicating whether the current value is a custom value
+ *   (not found in the predefined items list).
+ *
+ * @example
+ * ```typescript
+ * const currentValue = ref('custom-option');
+ * const items = ref([
+ *   { value: 'option1', label: 'Option 1' },
+ *   { value: 'option2', label: 'Option 2' }
+ * ]);
+ * const emit = (value: string | null) => console.log('Value changed:', value);
+ *
+ * const { otherValue, usesOtherValue } = useCustomSelection(currentValue, items, emit);
+ *
+ * console.log(usesOtherValue.value); // true (custom-option not in items)
+ * console.log(otherValue.value); // 'custom-option'
+ *
+ * otherValue.value = 'new-custom-value'; // Triggers emit with 'new-custom-value'
+ * ```
+ */
 declare function useCustomSelection(currentValue: Ref<string | null>, items: Ref<any[]>, emit: (event: string | null) => void): UsableCustomSelection;
 type OtherValue = {
     key: string;
     value: string;
+    focus?: boolean;
 };
 type UsableCustomSelectionMultiple = {
     otherValues: Ref<OtherValue[]>;
-    addOtherValue: (value?: string) => void;
+    addOtherValue: (value?: string, focus?: boolean) => void;
     setOtherValue: (key: string, newValue: string | null) => void;
 };
+/**
+ * A Vue composable for managing multiple custom selection values that aren't present in a predefined list of items.
+ *
+ * This composable extends the single custom selection pattern to support multiple values. It's typically used
+ * in multi-select form components where users can select multiple predefined options and also add custom
+ * values that aren't in the predefined list. It automatically detects custom values in the current selection,
+ * manages their state, and provides functions for adding and updating custom values.
+ *
+ * @param currentValues - A reactive reference to the currently selected values array. Can be null if no values are selected.
+ * @param items - A reactive reference to the array of available predefined items. Each item should have a 'value' property.
+ * @param emit - A callback function to emit value changes to the parent component.
+ *
+ * @returns An object containing:
+ * - `otherValues` - A reactive array of custom value objects, each with a unique key, value, and optional focus state.
+ * - `addOtherValue` - A function to add a new custom value with optional value and focus parameters.
+ * - `setOtherValue` - A function to update or remove a custom value by its key, automatically syncing with currentValues.
+ *
+ * @example
+ * ```typescript
+ * const currentValues = ref(['option1', 'custom-value1', 'custom-value2']);
+ * const items = ref([
+ *   { value: 'option1', label: 'Option 1' },
+ *   { value: 'option2', label: 'Option 2' }
+ * ]);
+ * const emit = (values: string[] | null) => console.log('Values changed:', values);
+ *
+ * const { otherValues, addOtherValue, setOtherValue } = useCustomSelectionMultiple(currentValues, items, emit);
+ *
+ * console.log(otherValues.value); // [{ key: 'abc123', value: 'custom-value1' }, { key: 'def456', value: 'custom-value2' }]
+ *
+ * // Add a new custom value
+ * addOtherValue('new-custom-value', true);
+ *
+ * // Update an existing custom value
+ * setOtherValue('abc123', 'updated-custom-value');
+ *
+ * // Remove a custom value
+ * setOtherValue('def456', null);
+ * ```
+ */
 declare function useCustomSelectionMultiple(currentValues: Ref<string[] | null>, items: Ref<any[]>, emit: (event: string[] | null) => void): UsableCustomSelectionMultiple;
 
 declare global {
@@ -37,56 +148,239 @@ declare global {
         ResizeObserver: any;
     }
 }
+/**
+ * A Vue composable that reactively tracks the size of a DOM element using ResizeObserver.
+ *
+ * @template T - The type of the element being observed, must extend Element
+ * @param target - The element to observe. Can be:
+ *   - A direct element reference
+ *   - A Vue ref containing an element
+ *   - A Vue ref that might be undefined
+ *
+ * @returns An object containing reactive width and height values:
+ *   - width: Ref<number> - The current width of the element in pixels
+ *   - height: Ref<number> - The current height of the element in pixels
+ *
+ * @example
+ * ```typescript
+ * // With a template ref
+ * const elementRef = ref<HTMLDivElement>();
+ * const { width, height } = useElementSize(elementRef);
+ *
+ * // With a direct element
+ * const element = document.getElementById('my-element');
+ * const { width, height } = useElementSize(element);
+ * ```
+ *
+ * @remarks
+ * - The composable automatically sets up a ResizeObserver when the component mounts
+ * - The observer is automatically disconnected when the component unmounts
+ * - Initial values are 0 until the first resize event
+ * - Handles cases where the target element might be undefined
+ */
 declare function useElementSize<T extends Element>(target: T | Ref<T> | Ref<undefined>): {
     width: Ref<number>;
     height: Ref<number>;
 };
 
+/**
+ * A Vue composable that filters and groups fields based on multiple filter criteria.
+ *
+ * @template T - The type of filter names as string literals
+ * @param fields - A Vue ref containing an array of Field objects to be filtered
+ * @param filters - An object where keys are filter names and values are predicate functions
+ *                  that return true if a field should be included in that group
+ *
+ * @returns An object containing:
+ *   - fieldGroups: ComputedRef<Record<Extract<T, string>, Field[]>> - A reactive object
+ *     where each key corresponds to a filter name and the value is an array of fields
+ *     that pass that filter
+ *
+ * @example
+ * ```typescript
+ * // Define filter criteria
+ * const fieldFilters = {
+ *   required: (field: Field) => field.required === true,
+ *   optional: (field: Field) => field.required !== true,
+ *   text: (field: Field) => field.type === 'string',
+ *   numeric: (field: Field) => ['integer', 'float', 'decimal'].includes(field.type)
+ * };
+ *
+ * const fieldsRef = ref<Field[]>([
+ *   { name: 'id', type: 'integer', required: true },
+ *   { name: 'title', type: 'string', required: true },
+ *   { name: 'description', type: 'text', required: false },
+ *   { name: 'price', type: 'decimal', required: false }
+ * ]);
+ *
+ * const { fieldGroups } = useFilterFields(fieldsRef, fieldFilters);
+ *
+ * // Access filtered groups
+ * console.log(fieldGroups.value.required); // [id, title]
+ * console.log(fieldGroups.value.text); // [title]
+ * console.log(fieldGroups.value.numeric); // [id, price]
+ * ```
+ *
+ * @remarks
+ * - Fields can appear in multiple groups if they pass multiple filters
+ * - If a field doesn't pass any filter, it won't appear in any group
+ * - The result is reactive and will update when the input fields change
+ * - Filter functions are called for each field against each filter criterion
+ * - Groups are initialized as empty arrays even if no fields match the criteria
+ */
 declare function useFilterFields<T extends string>(fields: Ref<Field[]>, filters: Record<T, (field: Field) => boolean>): {
     fieldGroups: ComputedRef<Record<Extract<T, string>, Field[]>>;
 };
 
+/**
+ * Represents a groupable item instance with its active state and value.
+ */
 type GroupableInstance = {
+    /** Reactive reference to the active state of the item */
     active: Ref<boolean>;
+    /** Unique identifier for the item within the group */
     value: string | number | undefined;
 };
 /**
+ * Configuration options for the useGroupable composable.
  * Used to make child item part of the group context. Needs to be used in a component that is a child
- * of a component that has the `useGroupableParent` composition enabled
+ * of a component that has the `useGroupableParent` composition enabled.
  */
 type GroupableOptions = {
+    /** Unique identifier for this groupable item */
     value?: string | number;
+    /** Name of the group to inject from (defaults to 'item-group') */
     group?: string;
+    /** External reactive reference to control the active state */
     active?: Ref<boolean>;
+    /** Whether to watch the external active reference for changes */
     watch?: boolean;
 };
+/**
+ * Return type for the useGroupable composable.
+ */
 type UsableGroupable = {
+    /** Reactive reference to the active state */
     active: Ref<boolean>;
+    /** Toggle the active state of this item */
     toggle: () => void;
+    /** Activate this item (if not already active) */
     activate: () => void;
+    /** Deactivate this item (if currently active) */
     deactivate: () => void;
 };
+/**
+ * Vue composable for creating groupable child items that can participate in group selection.
+ *
+ * This composable enables a component to be part of a group context managed by a parent component
+ * using `useGroupableParent`. It provides reactive active state management and selection control.
+ *
+ * @param options - Configuration options for the groupable item
+ * @param options.value - Unique identifier for this item within the group
+ * @param options.group - Name of the group to inject from (defaults to 'item-group')
+ * @param options.active - External reactive reference to control the active state
+ * @param options.watch - Whether to watch the external active reference for changes
+ *
+ * @returns Object containing active state and control methods
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useGroupable } from '@directus/composables';
+ *
+ * const props = defineProps(['value', 'active']);
+ *
+ * const { active, toggle, activate, deactivate } = useGroupable({
+ *   value: props.value,
+ *   active: toRef(props, 'active'),
+ *   watch: true
+ * });
+ * </script>
+ * ```
+ */
 declare function useGroupable(options?: GroupableOptions): UsableGroupable;
+/**
+ * State configuration for the groupable parent.
+ */
 type GroupableParentState = {
+    /** External selection state (can be readonly) */
     selection?: Ref<(string | number)[] | undefined> | Ref<readonly (string | number)[] | undefined>;
+    /** Callback fired when the selection changes */
     onSelectionChange?: (newSelectionValues: readonly (string | number)[]) => void;
+    /** Callback fired when an item is toggled */
     onToggle?: (item: GroupableInstance) => void;
 };
+/**
+ * Configuration options for the groupable parent.
+ */
 type GroupableParentOptions = {
+    /** Whether at least one item must always be selected */
     mandatory?: Ref<boolean>;
+    /** Maximum number of items that can be selected (-1 for unlimited) */
     max?: Ref<number>;
+    /** Whether multiple items can be selected simultaneously */
     multiple?: Ref<boolean>;
 };
+/**
+ * Return type for the useGroupableParent composable.
+ */
 type UsableGroupableParent = {
+    /** Reactive array of all registered groupable items */
     items: Ref<GroupableInstance[]>;
+    /** Computed selection array (readonly) */
     selection: Ref<readonly (string | number)[]>;
+    /** Internal selection state */
     internalSelection: Ref<(string | number)[]>;
+    /** Get the value identifier for a given item */
     getValueForItem: (item: GroupableInstance) => string | number;
+    /** Synchronize children's active state with selection */
     updateChildren: () => void;
 };
 /**
- * Used to make a component a group parent component. Provides the registration / toggle functions
- * to its group children
+ * Vue composable for creating a group parent that manages multiple groupable child items.
+ *
+ * This composable provides the foundation for components that need to manage a collection
+ * of selectable items, such as tabs, radio groups, or multi-select lists. It handles
+ * registration of child items, selection state management, and provides various selection
+ * constraints (mandatory, maximum, multiple).
+ *
+ * @param state - External state configuration for selection management
+ * @param state.selection - External selection state reference
+ * @param state.onSelectionChange - Callback fired when selection changes
+ * @param state.onToggle - Callback fired when an item is toggled
+ * @param options - Configuration options for selection behavior
+ * @param options.mandatory - Whether at least one item must always be selected
+ * @param options.max - Maximum number of items that can be selected (-1 for unlimited)
+ * @param options.multiple - Whether multiple items can be selected simultaneously
+ * @param group - Injection key for the group (defaults to 'item-group')
+ *
+ * @returns Object containing items array, selection state, and utility functions
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useGroupableParent } from '@directus/composables';
+ * import { ref } from 'vue';
+ *
+ * const selectedItems = ref([]);
+ * const isMultiple = ref(true);
+ * const isMandatory = ref(false);
+ *
+ * const { items, selection } = useGroupableParent(
+ *   {
+ *     selection: selectedItems,
+ *     onSelectionChange: (values) => {
+ *       console.log('Selection changed:', values);
+ *     }
+ *   },
+ *   {
+ *     multiple: isMultiple,
+ *     mandatory: isMandatory,
+ *     max: ref(3)
+ *   }
+ * );
+ * </script>
+ * ```
  */
 declare function useGroupableParent(state?: GroupableParentState, options?: GroupableParentOptions, group?: string): UsableGroupableParent;
 
@@ -120,10 +414,127 @@ type ComputedQuery = {
 };
 declare function useItems(collection: Ref<string | null>, query: ComputedQuery): UsableItems;
 
+declare const WRITABLE_PROPS: readonly ["selection", "layoutOptions", "layoutQuery"];
+type WritableProp = (typeof WRITABLE_PROPS)[number];
+/**
+ * Type guard to check if a property is writable (can be updated via emit).
+ *
+ * This function determines whether a given property name corresponds to one of the
+ * writable properties that can be updated through Vue's emit system.
+ *
+ * @param prop - The property name to check
+ * @returns True if the property is writable, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isWritableProp('selection')) {
+ *   // Property is writable, can emit update
+ *   emit('update:selection', newValue);
+ * }
+ * ```
+ */
+declare function isWritableProp(prop: string): prop is WritableProp;
+/**
+ * Creates a Vue component wrapper for a layout configuration.
+ *
+ * This function creates a dynamic Vue component that wraps a layout with standardized
+ * props, emits, and state management. It handles reactive state updates, prop validation,
+ * and provides a consistent interface for all layout components.
+ *
+ * @template Options - The type for layout-specific options
+ * @template Query - The type for layout-specific query parameters
+ * @param layout - The layout configuration object containing id and setup function
+ * @returns A Vue component that can be used to render the layout
+ *
+ * @example
+ * ```typescript
+ * interface MyLayoutOptions {
+ *   itemSize: number;
+ *   showHeaders: boolean;
+ * }
+ *
+ * interface MyLayoutQuery {
+ *   page: number;
+ *   limit: number;
+ * }
+ *
+ * const layoutConfig: LayoutConfig = {
+ *   id: 'my-layout',
+ *   setup: (props, { emit }) => ({
+ *     // Layout-specific setup logic
+ *   })
+ * };
+ *
+ * const LayoutWrapper = createLayoutWrapper<MyLayoutOptions, MyLayoutQuery>(layoutConfig);
+ * ```
+ */
+declare function createLayoutWrapper<Options, Query>(layout: LayoutConfig): Component;
+/**
+ * Composable for managing layout components in Directus.
+ *
+ * This composable provides access to layout components and handles the dynamic
+ * selection of layout wrappers based on the provided layout ID. It automatically
+ * falls back to the tabular layout if the requested layout is not found.
+ *
+ * @template Options - The type for layout-specific options (default: any)
+ * @template Query - The type for layout-specific query parameters (default: any)
+ * @param layoutId - A reactive reference to the layout ID
+ * @returns An object containing the layout wrapper component
+ *
+ * @example
+ * ```typescript
+ * import { ref } from 'vue';
+ * import { useLayout } from './use-layout';
+ *
+ * const selectedLayoutId = ref('table');
+ * const { layoutWrapper } = useLayout(selectedLayoutId);
+ *
+ * // Use the layout wrapper in your template
+ * // <component :is="layoutWrapper" :collection="'users'" />
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With typed options and query
+ * interface TableOptions {
+ *   spacing: 'cozy' | 'comfortable' | 'compact';
+ *   showHeaders: boolean;
+ * }
+ *
+ * interface TableQuery {
+ *   sort: string[];
+ *   limit: number;
+ * }
+ *
+ * const layoutId = ref<string | null>('table');
+ * const { layoutWrapper } = useLayout<TableOptions, TableQuery>(layoutId);
+ * ```
+ */
 declare function useLayout<Options = any, Query = any>(layoutId: Ref<string | null>): {
     layoutWrapper: ComputedRef<Component>;
 };
 
+/**
+ * Vue props definition for size-related boolean properties.
+ *
+ * This object defines the standard size props that can be used in Vue components
+ * to control size-based styling through CSS classes.
+ *
+ * @example
+ * ```typescript
+ * // In a Vue component
+ * export default defineComponent({
+ *   props: {
+ *     ...sizeProps,
+ *     // other props
+ *   },
+ *   setup(props) {
+ *     const sizeClass = useSizeClass(props);
+ *     return { sizeClass };
+ *   }
+ * });
+ * ```
+ */
 declare const sizeProps: {
     xSmall: {
         type: BooleanConstructor;
@@ -148,13 +559,500 @@ interface SizeProps {
     large?: boolean;
     xLarge?: boolean;
 }
+/**
+ * Composable for generating CSS size class names based on size props.
+ *
+ * This composable takes props containing size boolean flags and returns a computed
+ * CSS class name string. It follows a priority order: xSmall > small > large > xLarge.
+ * If no size props are true, it returns null.
+ *
+ * @template T - The type of additional props that extend SizeProps
+ * @param props - The props object containing size boolean properties
+ * @returns A computed ref that resolves to the appropriate CSS class name or null
+ *
+ * @example
+ * ```typescript
+ * // Basic usage in a Vue component
+ * const props = { small: true, large: false };
+ * const sizeClass = useSizeClass(props);
+ * console.log(sizeClass.value); // 'small'
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Usage with additional props
+ * interface MyProps {
+ *   color: string;
+ *   disabled: boolean;
+ * }
+ *
+ * const props: MyProps & SizeProps = {
+ *   color: 'blue',
+ *   disabled: false,
+ *   xLarge: true
+ * };
+ *
+ * const sizeClass = useSizeClass(props);
+ * console.log(sizeClass.value); // 'x-large'
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // In a Vue component with reactive props
+ * export default defineComponent({
+ *   props: {
+ *     ...sizeProps,
+ *     label: String,
+ *   },
+ *   setup(props) {
+ *     const sizeClass = useSizeClass(props);
+ *
+ *     return { sizeClass };
+ *   },
+ *   template: `
+ *     <button :class="['btn', sizeClass]">
+ *       {{ label }}
+ *     </button>
+ *   `
+ * });
+ * ```
+ */
 declare function useSizeClass<T>(props: T & SizeProps): ComputedRef<string | null>;
 
+/**
+ * Composable for creating two-way binding between parent and child components.
+ *
+ * @deprecated Use Vue's native `defineModel()` instead. This composable is kept for backward compatibility.
+ * Vue 3.4+ provides `defineModel()` which offers a more streamlined and performant way to create v-model bindings.
+ *
+ * @see {@link https://vuejs.org/api/sfc-script-setup.html#definemodel} Vue's defineModel documentation
+ *
+ * This composable creates a computed ref that synchronizes a prop value with
+ * its parent component through Vue's v-model pattern. It provides a getter
+ * that returns the current prop value and a setter that emits an update event
+ * to notify the parent component of changes.
+ *
+ * This is particularly useful for creating custom form components that need
+ * to work with v-model while maintaining proper data flow patterns.
+ *
+ * @template T - The type of the props object
+ * @template K - The key of the prop to sync (must be a string key of T)
+ * @template E - The emit function type with proper event typing
+ *
+ * @param props - The component props object containing the value to sync
+ * @param key - The specific prop key to create a two-way binding for
+ * @param emit - The Vue emit function for sending update events to parent
+ *
+ * @returns A computed ref that can be used with v-model pattern
+ *
+ * @example
+ * ```typescript
+ * // DEPRECATED: Old way using useSync
+ * export default defineComponent({
+ *   props: {
+ *     modelValue: String,
+ *     disabled: Boolean,
+ *   },
+ *   emits: ['update:modelValue'],
+ *   setup(props, { emit }) {
+ *     const syncedValue = useSync(props, 'modelValue', emit);
+ *     return { syncedValue };
+ *   }
+ * });
+ *
+ * // RECOMMENDED: New way using defineModel (Vue 3.4+)
+ * <script setup lang="ts">
+ * const modelValue = defineModel<string>();
+ * const disabled = defineProps<{ disabled?: boolean }>();
+ * </script>
+ *
+ * <template>
+ *   <input v-model="modelValue" :disabled="disabled" />
+ * </template>
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // DEPRECATED: Custom input component with useSync
+ * interface Props {
+ *   value: string;
+ *   placeholder?: string;
+ *   type?: string;
+ * }
+ *
+ * export default defineComponent({
+ *   props: {
+ *     value: { type: String, required: true },
+ *     placeholder: String,
+ *     type: { type: String, default: 'text' },
+ *   },
+ *   emits: ['update:value'],
+ *   setup(props: Props, { emit }) {
+ *     const syncedValue = useSync(props, 'value', emit);
+ *     return { syncedValue };
+ *   }
+ * });
+ *
+ * // RECOMMENDED: Using defineModel with custom prop name
+ * <script setup lang="ts">
+ * const value = defineModel<string>('value', { required: true });
+ * const { placeholder, type = 'text' } = defineProps<{
+ *   placeholder?: string;
+ *   type?: string;
+ * }>();
+ * </script>
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // DEPRECATED: Usage with complex objects using useSync
+ * interface UserData {
+ *   name: string;
+ *   email: string;
+ *   age: number;
+ * }
+ *
+ * export default defineComponent({
+ *   props: {
+ *     userData: { type: Object as PropType<UserData>, required: true },
+ *     isLoading: Boolean,
+ *   },
+ *   emits: ['update:userData'],
+ *   setup(props, { emit }) {
+ *     const syncedUserData = useSync(props, 'userData', emit);
+ *
+ *     const updateName = (newName: string) => {
+ *       syncedUserData.value = {
+ *         ...syncedUserData.value,
+ *         name: newName
+ *       };
+ *     };
+ *
+ *     return { syncedUserData, updateName };
+ *   }
+ * });
+ *
+ * // RECOMMENDED: Using defineModel with complex objects
+ * <script setup lang="ts">
+ * interface UserData {
+ *   name: string;
+ *   email: string;
+ *   age: number;
+ * }
+ *
+ * const userData = defineModel<UserData>('userData', { required: true });
+ * const { isLoading } = defineProps<{ isLoading?: boolean }>();
+ *
+ * const updateName = (newName: string) => {
+ *   userData.value = {
+ *     ...userData.value,
+ *     name: newName
+ *   };
+ * };
+ * </script>
+ * ```
+ */
 declare function useSync<T, K extends keyof T & string, E extends (event: `update:${K}`, ...args: any[]) => void>(props: T, key: K, emit: E): Ref<T[K]>;
 
+/**
+ * Vue composable that provides access to the global Directus stores through dependency injection.
+ *
+ * This composable injects the stores object that contains all the Pinia stores used throughout
+ * the Directus application, including user store, permissions store, collections store, etc.
+ *
+ * @returns The injected stores object containing all application stores
+ * @throws Error if the stores could not be found in the injection context
+ *
+ * @example
+ * ```typescript
+ * import { useStores } from '@directus/composables';
+ *
+ * export default defineComponent({
+ *   setup() {
+ *     const stores = useStores();
+ *
+ *     // Access specific stores
+ *     const userStore = stores.useUserStore();
+ *     const collectionsStore = stores.useCollectionsStore();
+ *     const permissionsStore = stores.usePermissionsStore();
+ *
+ *     return {
+ *       userInfo: userStore.currentUser,
+ *       collections: collectionsStore.collections,
+ *       permissions: permissionsStore.permissions
+ *     };
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using in a component with reactive store data
+ * import { useStores } from '@directus/composables';
+ * import { computed } from 'vue';
+ *
+ * export default defineComponent({
+ *   setup() {
+ *     const stores = useStores();
+ *     const userStore = stores.useUserStore();
+ *
+ *     const isAdmin = computed(() => {
+ *       return userStore.currentUser?.role?.admin_access === true;
+ *     });
+ *
+ *     const hasCreatePermission = computed(() => {
+ *       const permissionsStore = stores.usePermissionsStore();
+ *       return permissionsStore.hasPermission('directus_files', 'create');
+ *     });
+ *
+ *     return { isAdmin, hasCreatePermission };
+ *   }
+ * });
+ * ```
+ */
 declare function useStores(): Record<string, any>;
+/**
+ * Vue composable that provides access to the Axios HTTP client instance through dependency injection.
+ *
+ * This composable injects the configured Axios instance that is set up with the proper base URL,
+ * authentication headers, interceptors, and other configuration needed to communicate with the
+ * Directus API. It provides a convenient way to make HTTP requests from components and composables.
+ *
+ * @returns The injected Axios instance configured for Directus API communication
+ * @throws Error if the API instance could not be found in the injection context
+ *
+ * @example
+ * ```typescript
+ * import { useApi } from '@directus/composables';
+ *
+ * export default defineComponent({
+ *   setup() {
+ *     const api = useApi();
+ *
+ *     const fetchUserData = async (userId: string) => {
+ *       try {
+ *         const response = await api.get(`/users/${userId}`);
+ *         return response.data;
+ *       } catch (error) {
+ *         console.error('Failed to fetch user data:', error);
+ *         throw error;
+ *       }
+ *     };
+ *
+ *     return { fetchUserData };
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using with reactive data and error handling
+ * import { useApi } from '@directus/composables';
+ * import { ref, onMounted } from 'vue';
+ *
+ * export default defineComponent({
+ *   setup() {
+ *     const api = useApi();
+ *     const collections = ref([]);
+ *     const loading = ref(false);
+ *     const error = ref(null);
+ *
+ *     const loadCollections = async () => {
+ *       loading.value = true;
+ *       error.value = null;
+ *
+ *       try {
+ *         const response = await api.get('/collections');
+ *         collections.value = response.data.data;
+ *       } catch (err) {
+ *         error.value = err.response?.data?.errors?.[0]?.message || 'Failed to load collections';
+ *       } finally {
+ *         loading.value = false;
+ *       }
+ *     };
+ *
+ *     onMounted(loadCollections);
+ *
+ *     return { collections, loading, error, loadCollections };
+ *   }
+ * });
+ * ```
+ */
 declare function useApi(): AxiosInstance;
+/**
+ * Vue composable that provides access to the Directus SDK client instance through dependency injection.
+ *
+ * This composable injects the configured Directus SDK client that provides a type-safe, modern API
+ * for interacting with Directus. The SDK offers methods for CRUD operations, authentication, file
+ * management, and more, with full TypeScript support and automatic type inference based on your schema.
+ *
+ * @template Schema - The TypeScript schema type for your Directus instance, defaults to `any`
+ * @returns The injected Directus SDK client with REST client capabilities
+ * @throws Error if the SDK instance could not be found in the injection context
+ *
+ * @example
+ * ```typescript
+ * import { useSdk } from '@directus/composables';
+ *
+ * // Using with default schema
+ * export default defineComponent({
+ *   setup() {
+ *     const sdk = useSdk();
+ *
+ *     const fetchArticles = async () => {
+ *       try {
+ *         const articles = await sdk.items('articles').readByQuery({
+ *           filter: { status: { _eq: 'published' } },
+ *           sort: ['-date_created'],
+ *           limit: 10
+ *         });
+ *         return articles;
+ *       } catch (error) {
+ *         console.error('Failed to fetch articles:', error);
+ *         throw error;
+ *       }
+ *     };
+ *
+ *     return { fetchArticles };
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using with typed schema for better type safety
+ * import { useSdk } from '@directus/composables';
+ *
+ * interface MySchema {
+ *   articles: {
+ *     id: string;
+ *     title: string;
+ *     content: string;
+ *     status: 'draft' | 'published';
+ *     author: string;
+ *     date_created: string;
+ *   };
+ *   authors: {
+ *     id: string;
+ *     name: string;
+ *     email: string;
+ *   };
+ * }
+ *
+ * export default defineComponent({
+ *   setup() {
+ *     const sdk = useSdk<MySchema>();
+ *
+ *     const createArticle = async (articleData: Partial<MySchema['articles']>) => {
+ *       try {
+ *         const newArticle = await sdk.items('articles').createOne(articleData);
+ *         return newArticle; // Fully typed return value
+ *       } catch (error) {
+ *         console.error('Failed to create article:', error);
+ *         throw error;
+ *       }
+ *     };
+ *
+ *     const updateArticle = async (id: string, updates: Partial<MySchema['articles']>) => {
+ *       try {
+ *         const updatedArticle = await sdk.items('articles').updateOne(id, updates);
+ *         return updatedArticle; // Type-safe updates
+ *       } catch (error) {
+ *         console.error('Failed to update article:', error);
+ *         throw error;
+ *       }
+ *     };
+ *
+ *     return { createArticle, updateArticle };
+ *   }
+ * });
+ * ```
+ */
 declare function useSdk<Schema extends object = any>(): DirectusClient<Schema> & RestClient<Schema>;
+/**
+ * Vue composable that provides access to the registered Directus extensions through dependency injection.
+ *
+ * This composable injects the extensions configuration object that contains all registered app
+ * extensions including interfaces, displays, layouts, modules, panels, operations, and more.
+ * The extensions are provided as reactive references and can be used to dynamically access
+ * and utilize custom functionality within the Directus application.
+ *
+ * @returns A reactive record of extension configurations organized by extension type
+ * @throws Error if the extensions could not be found in the injection context
+ *
+ * @example
+ * ```typescript
+ * import { useExtensions } from '@directus/composables';
+ *
+ * export default defineComponent({
+ *   setup() {
+ *     const extensions = useExtensions();
+ *
+ *     const getAvailableInterfaces = () => {
+ *       return Object.values(extensions.interfaces || {});
+ *     };
+ *
+ *     const getAvailableDisplays = () => {
+ *       return Object.values(extensions.displays || {});
+ *     };
+ *
+ *     const findInterfaceByName = (name: string) => {
+ *       return extensions.interfaces?.[name] || null;
+ *     };
+ *
+ *     return {
+ *       getAvailableInterfaces,
+ *       getAvailableDisplays,
+ *       findInterfaceByName
+ *     };
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using with computed properties for reactive extension lists
+ * import { useExtensions } from '@directus/composables';
+ * import { computed } from 'vue';
+ *
+ * export default defineComponent({
+ *   setup() {
+ *     const extensions = useExtensions();
+ *
+ *     const availableLayouts = computed(() => {
+ *       return Object.entries(extensions.layouts || {}).map(([key, config]) => ({
+ *         id: key,
+ *         name: config.name,
+ *         icon: config.icon,
+ *         component: config.component
+ *       }));
+ *     });
+ *
+ *     const customModules = computed(() => {
+ *       return Object.values(extensions.modules || {}).filter(module =>
+ *         !module.preRegisterCheck || module.preRegisterCheck()
+ *       );
+ *     });
+ *
+ *     const operationsByGroup = computed(() => {
+ *       const operations = Object.values(extensions.operations || {});
+ *       return operations.reduce((groups, operation) => {
+ *         const group = operation.overview?.group || 'other';
+ *         if (!groups[group]) groups[group] = [];
+ *         groups[group].push(operation);
+ *         return groups;
+ *       }, {} as Record<string, any[]>);
+ *     });
+ *
+ *     return {
+ *       availableLayouts,
+ *       customModules,
+ *       operationsByGroup
+ *     };
+ *   }
+ * });
+ * ```
+ */
 declare function useExtensions(): RefRecord<AppExtensionConfigs>;
 
-export { type ComputedQuery, type GroupableInstance, type GroupableOptions, type ManualSortData, type UsableCollection, type UsableCustomSelection, type UsableGroupable, type UsableItems, sizeProps, useApi, useCollection, useCustomSelection, useCustomSelectionMultiple, useElementSize, useExtensions, useFilterFields, useGroupable, useGroupableParent, useItems, useLayout, useSdk, useSizeClass, useStores, useSync };
+export { type ComputedQuery, type GroupableInstance, type GroupableOptions, type ManualSortData, type OtherValue, type UsableCollection, type UsableCustomSelection, type UsableGroupable, type UsableItems, createLayoutWrapper, isWritableProp, sizeProps, useApi, useCollection, useCustomSelection, useCustomSelectionMultiple, useElementSize, useExtensions, useFilterFields, useGroupable, useGroupableParent, useItems, useLayout, useSdk, useSizeClass, useStores, useSync };

package/dist/index.js

@@ -61,9 +61,7 @@ function useCollection(collectionKey) {
     return info.value?.meta?.singleton === true;
   });
   const accountabilityScope = computed(() => {
-    if (!info.value) return null;
-    if (!info.value.meta) return null;
-    return info.value.meta.accountability;
+    return info.value?.meta?.accountability || null;
   });
   return { info, fields, defaults, primaryKeyField, userCreatedField, sortField, isSingleton, accountabilityScope };
 }
@@ -118,12 +116,13 @@ function useCustomSelectionMultiple(currentValues, items, emit) {
     { immediate: true }
   );
   return { otherValues, addOtherValue, setOtherValue };
-  function addOtherValue(value = "") {
+  function addOtherValue(value = "", focus = false) {
     otherValues.value = [
       ...otherValues.value,
       {
         key: nanoid(),
-        value
+        value,
+        focus
       }
     ];
   }
@@ -683,6 +682,8 @@ function useSync(props, key, emit) {
   });
 }
 export {
+  createLayoutWrapper,
+  isWritableProp,
   sizeProps,
   useApi,
   useCollection,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@directus/composables",
-  "version": "11.1.11",
+  "version": "11.2.1",
   "description": "Shared Vue composables for Directus use",
   "homepage": "https://directus.io",
   "repository": {
@@ -22,24 +22,24 @@
     "dist"
   ],
   "dependencies": {
-    "axios": "1.8.4",
+    "axios": "1.11.0",
     "lodash-es": "4.17.21",
-    "nanoid": "5.1.2",
+    "nanoid": "5.1.5",
     "@directus/constants": "13.0.1",
-    "@directus/utils": "13.0.6"
+    "@directus/utils": "13.0.8"
   },
   "devDependencies": {
     "@directus/tsconfig": "3.0.0",
     "@types/lodash-es": "4.17.12",
-    "@vitest/coverage-v8": "2.1.9",
+    "@vitest/coverage-v8": "3.2.4",
     "@vue/test-utils": "2.4.6",
-    "tsup": "8.4.0",
-    "typescript": "5.8.2",
-    "vitest": "2.1.9",
-    "vue": "3.5.13",
-    "@directus/extensions": "3.0.6",
-    "@directus/types": "13.1.2",
-    "@directus/sdk": "19.1.0"
+    "tsup": "8.5.0",
+    "typescript": "5.8.3",
+    "vitest": "3.2.4",
+    "vue": "3.5.18",
+    "@directus/extensions": "3.0.8",
+    "@directus/sdk": "20.0.1",
+    "@directus/types": "13.2.0"
   },
   "peerDependencies": {
     "vue": "^3.4"
@@ -47,6 +47,7 @@
   "scripts": {
     "build": "tsup src/index.ts --format=esm --dts",
     "dev": "tsup src/index.ts --format=esm --dts --watch",
-    "test": "vitest --watch=false"
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
   }
 }