sveltacular 1.1.0 → 1.1.1

package/dist/forms/check-box/check-box-group.svelte

@@ -1,6 +1,7 @@
 <script lang="ts">
 	import { untrack } from 'svelte';
-	import type { ReferenceItem, ComponentSize } from '../../types/form.js';
+	import type { ReferenceItem, ComponentSize, FieldNameMapping } from '../../types/form.js';
+	import { createFieldMapper } from '../../types/form.js';
 	import FormField from '../form-field/form-field.svelte';
 	import CheckBox from './check-box.svelte';
 	import { uniqueId } from '../../helpers/unique-id.js';
@@ -8,40 +9,62 @@
 	const id = uniqueId();
 
 	let {
-		group = $bindable([] as string[]),
+		group = $bindable([] as (string | number)[]),
 		items = [],
+		fieldNames = undefined as FieldNameMapping | undefined,
 		size = 'md' as ComponentSize,
 		disabled = false,
 		required = false,
 		onChange,
 		label
 	}: {
-		group?: string[];
-		items?: ReferenceItem[];
+		group?: (string | number)[];
+		items?: any[];
+		/**
+		 * Maps database field names to ReferenceItem properties.
+		 * Use this when your data uses different field names (e.g., 'name' instead of 'label').
+		 * 
+		 * @example
+		 * // Basic usage
+		 * fieldNames={{ label: 'name', value: 'id' }}
+		 * 
+		 * @example
+		 * // With description field
+		 * fieldNames={{ label: 'title', value: 'id', description: 'subtitle' }}
+		 */
+		fieldNames?: FieldNameMapping | undefined;
 		size?: ComponentSize;
 		disabled?: boolean;
 		required?: boolean;
-		onChange?: ((selected: string[]) => void) | undefined;
+		onChange?: ((selected: (string | number)[]) => void) | undefined;
 		label?: string;
 	} = $props();
 
+	// Create field mapper
+	const mapper = $derived(createFieldMapper<any>(fieldNames));
+
+	// Transform items for internal use (always work with ReferenceItem internally)
+	const referenceItems = $derived(
+		fieldNames ? items.map(item => mapper.toReferenceItem(item)) : items as ReferenceItem[]
+	);
+
 	// Create reactive items with checked state, synced with group
 	let itemsWithState = $state<Array<ReferenceItem & { isChecked: boolean }>>([]);
 
 	// Sync itemsWithState when items or group changes (one-way: items/group -> itemsWithState)
 	// Reassign the entire array to avoid reading itemsWithState in the effect
 	$effect(() => {
-		// Track items and group as dependencies
-		const currentItems = items;
+		// Track referenceItems and group as dependencies
+		const currentItems = referenceItems;
 		const currentGroup = group;
 
 		// Use untrack to prevent writing to itemsWithState from triggering this effect again
 		untrack(() => {
-			// Rebuild itemsWithState from items, using group to determine checked state
+			// Rebuild itemsWithState from referenceItems, using group to determine checked state
 			// Reassign instead of mutate to avoid circular dependency
 			const newItems = currentItems.map((item) => ({
 				...item,
-				isChecked: currentGroup.includes(item.value != null ? String(item.value) : '')
+				isChecked: currentGroup.includes(item.value as any)
 			}));
 			itemsWithState = newItems;
 		});

package/dist/forms/check-box/check-box-group.svelte.d.ts

@@ -1,11 +1,24 @@
-import type { ReferenceItem, ComponentSize } from '../../types/form.js';
+import type { ComponentSize, FieldNameMapping } from '../../types/form.js';
 type $$ComponentProps = {
-    group?: string[];
-    items?: ReferenceItem[];
+    group?: (string | number)[];
+    items?: any[];
+    /**
+     * Maps database field names to ReferenceItem properties.
+     * Use this when your data uses different field names (e.g., 'name' instead of 'label').
+     *
+     * @example
+     * // Basic usage
+     * fieldNames={{ label: 'name', value: 'id' }}
+     *
+     * @example
+     * // With description field
+     * fieldNames={{ label: 'title', value: 'id', description: 'subtitle' }}
+     */
+    fieldNames?: FieldNameMapping | undefined;
     size?: ComponentSize;
     disabled?: boolean;
     required?: boolean;
-    onChange?: ((selected: string[]) => void) | undefined;
+    onChange?: ((selected: (string | number)[]) => void) | undefined;
     label?: string;
 };
 declare const CheckBoxGroup: import("svelte").Component<$$ComponentProps, {}, "group">;

package/dist/forms/list-box/list-box.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
-	import type { ReferenceItem, ComponentSize } from '../../types/form.js';
+	import type { ReferenceItem, ComponentSize, FieldNameMapping } from '../../types/form.js';
+	import { createFieldMapper } from '../../types/form.js';
 	import FormField, { type FormFieldFeedback } from '../form-field/form-field.svelte';
 	import { uniqueId } from '../../helpers/unique-id.js';
 	import Menu from '../../generic/menu/menu.svelte';
@@ -12,8 +13,9 @@
 	import type { CreateNewFunction, SearchFunction } from '../../types/form.js';
 
 	let {
-		value = $bindable(null as string | null),
-		items = [] as ReferenceItem[],
+		value = $bindable(null as string | number | null),
+		items = [] as any[],
+		fieldNames = undefined as FieldNameMapping | undefined,
 		size = 'md',
 		disabled = false,
 		required = false,
@@ -32,8 +34,21 @@
 		createNew = undefined,
 		resourceName = undefined
 	}: {
-		value?: string | null;
-		items?: ReferenceItem[];
+		value?: string | number | null;
+		items?: any[];
+		/**
+		 * Maps database field names to ReferenceItem properties.
+		 * Use this when your data uses different field names (e.g., 'name' instead of 'label').
+		 * 
+		 * @example
+		 * // Basic usage
+		 * fieldNames={{ label: 'name', value: 'id' }}
+		 * 
+		 * @example
+		 * // With description field
+		 * fieldNames={{ label: 'title', value: 'id', description: 'subtitle' }}
+		 */
+		fieldNames?: FieldNameMapping | undefined;
 		size?: ComponentSize;
 		disabled?: boolean;
 		required?: boolean;
@@ -41,7 +56,7 @@
 		searchable?: boolean;
 		search?: SearchFunction | undefined;
 		placeholder?: string;
-		onChange?: ((value: string | null) => void) | undefined;
+		onChange?: ((value: string | number | null) => void) | undefined;
 		onFocus?: ((e: FocusEvent) => void) | undefined;
 		onBlur?: ((e: FocusEvent) => void) | undefined;
 		label?: string;
@@ -56,9 +71,17 @@
 	const id = uniqueId();
 	const listboxId = `${id}-listbox`;
 
-	// Use local items state when search function is provided, otherwise use prop
+	// Create field mapper
+	const mapper = $derived(createFieldMapper<any>(fieldNames));
+
+	// Transform items for internal use (always work with ReferenceItem internally)
+	const referenceItems = $derived(
+		fieldNames ? items.map(item => mapper.toReferenceItem(item)) : items as ReferenceItem[]
+	);
+
+	// Use local items state when search function is provided, otherwise use transformed items
 	let localItems = $state<ReferenceItem[]>([]);
-	let currentItems = $derived(search ? localItems : items);
+	let currentItems = $derived(search ? localItems : referenceItems);
 
 	const getText = () => currentItems.find((item) => item.value == value)?.label || '';
 
@@ -78,10 +101,18 @@
 	// Initialize localItems when items prop changes (only when no search function)
 	$effect(() => {
 		if (!search) {
-			localItems = [...items];
+			localItems = [...referenceItems];
 		}
 	});
 
+	// Internal value for Menu component (always string | null)
+	let internalValue = $state<string | null>(value != null ? String(value) : null);
+
+	// Sync internal value from external value
+	$effect(() => {
+		internalValue = value != null ? String(value) : null;
+	});
+
 	// Initialize text from value on mount and when value/items change (but not when user is typing)
 	$effect(() => {
 		// Track value and currentItems to update text when they change
@@ -141,7 +172,8 @@
 	// When an item is selected from the dropdown menu
 	const onSelect = (item: ReferenceItem) => {
 		isUserTyping = false;
-		value = item.value != null ? String(item.value) : null;
+		// Keep value as-is (string | number | null)
+		value = item.value;
 		onChange?.(value);
 		text = getText();
 		isMenuOpen = false;
@@ -337,11 +369,12 @@
 			const result = await createNew(name);
 
 			if (result) {
-				items = [...items, result];
+				// Note: items prop is read-only, so we can't update it
+				// Just add to localItems for display
 				localItems = [...localItems, result];
 
 				// Select the newly created item
-				value = result.value != null ? String(result.value) : null;
+				value = result.value;
 				onChange?.(value);
 				text = result.label;
 				isMenuOpen = false;
@@ -475,7 +508,7 @@
 					searchText={isSearchable ? text : ''}
 					{onSelect}
 					bind:highlightIndex
-					bind:value
+					bind:value={internalValue}
 					{listboxId}
 					{virtualScroll}
 					{itemHeight}

package/dist/forms/list-box/list-box.svelte.d.ts

@@ -1,9 +1,22 @@
-import type { ReferenceItem, ComponentSize } from '../../types/form.js';
+import type { ReferenceItem, ComponentSize, FieldNameMapping } from '../../types/form.js';
 import { type FormFieldFeedback } from '../form-field/form-field.svelte';
 import type { CreateNewFunction, SearchFunction } from '../../types/form.js';
 type $$ComponentProps = {
-    value?: string | null;
-    items?: ReferenceItem[];
+    value?: string | number | null;
+    items?: any[];
+    /**
+     * Maps database field names to ReferenceItem properties.
+     * Use this when your data uses different field names (e.g., 'name' instead of 'label').
+     *
+     * @example
+     * // Basic usage
+     * fieldNames={{ label: 'name', value: 'id' }}
+     *
+     * @example
+     * // With description field
+     * fieldNames={{ label: 'title', value: 'id', description: 'subtitle' }}
+     */
+    fieldNames?: FieldNameMapping | undefined;
     size?: ComponentSize;
     disabled?: boolean;
     required?: boolean;
@@ -11,7 +24,7 @@ type $$ComponentProps = {
     searchable?: boolean;
     search?: SearchFunction | undefined;
     placeholder?: string;
-    onChange?: ((value: string | null) => void) | undefined;
+    onChange?: ((value: string | number | null) => void) | undefined;
     onFocus?: ((e: FocusEvent) => void) | undefined;
     onBlur?: ((e: FocusEvent) => void) | undefined;
     label?: string;

package/dist/forms/radio-group/radio-group.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
-	import type { ReferenceItem, ComponentSize } from '../../types/form.js';
+	import type { ReferenceItem, ComponentSize, FieldNameMapping } from '../../types/form.js';
+	import { createFieldMapper } from '../../types/form.js';
 	import FormField, { type FormFieldFeedback } from '../form-field/form-field.svelte';
 	import { uniqueId } from '../../helpers/unique-id.js';
 	import RadioBox from './radio-box.svelte';
@@ -7,8 +8,9 @@
 	const id = uniqueId();
 
 	let {
-		group = '',
+		group = $bindable(''),
 		items = [],
+		fieldNames = undefined as FieldNameMapping | undefined,
 		size = 'md' as ComponentSize,
 		disabled = false,
 		required = false,
@@ -17,22 +19,63 @@
 		feedback = undefined,
 		onChange = undefined
 	}: {
-		group?: string;
-		items?: ReferenceItem[];
+		group?: string | number;
+		items?: any[];
+		/**
+		 * Maps database field names to ReferenceItem properties.
+		 * Use this when your data uses different field names (e.g., 'name' instead of 'label').
+		 * 
+		 * @example
+		 * // Basic usage
+		 * fieldNames={{ label: 'name', value: 'id' }}
+		 * 
+		 * @example
+		 * // With description field
+		 * fieldNames={{ label: 'title', value: 'id', description: 'subtitle' }}
+		 */
+		fieldNames?: FieldNameMapping | undefined;
 		size?: ComponentSize;
 		disabled?: boolean;
 		required?: boolean;
 		label?: string;
 		helperText?: string;
 		feedback?: FormFieldFeedback;
-		onChange?: ((value: string) => void) | undefined;
+		onChange?: ((value: string | number) => void) | undefined;
 	} = $props();
+
+	// Create field mapper
+	const mapper = $derived(createFieldMapper<any>(fieldNames));
+
+	// Transform items for internal use (always work with ReferenceItem internally)
+	const referenceItems = $derived(
+		fieldNames ? items.map(item => mapper.toReferenceItem(item)) : items as ReferenceItem[]
+	);
+
+	// Internal string group for binding to RadioBox components
+	let internalGroup = $state<string>(String(group ?? ''));
+
+	// Sync internal group from external group
+	$effect(() => {
+		internalGroup = String(group ?? '');
+	});
+
+	// Handle change to convert back to original type
+	function handleChange(value: string) {
+		// Try to convert back to number if the original was a number
+		const numValue = Number(value);
+		if (!isNaN(numValue) && String(numValue) === value) {
+			group = numValue;
+		} else {
+			group = value;
+		}
+		onChange?.(group);
+	}
 </script>
 
 <FormField {size} {label} {id} {required} {disabled} {helperText} {feedback}>
 	<div>
-		{#each items as item}
-			<RadioBox bind:group {disabled} value={item.value} {onChange}>{item.label}</RadioBox>
+		{#each referenceItems as item}
+			<RadioBox bind:group={internalGroup} {disabled} value={item.value} onChange={handleChange}>{item.label}</RadioBox>
 		{/each}
 	</div>
 </FormField>

package/dist/forms/radio-group/radio-group.svelte.d.ts

@@ -1,16 +1,29 @@
-import type { ReferenceItem, ComponentSize } from '../../types/form.js';
+import type { ComponentSize, FieldNameMapping } from '../../types/form.js';
 import { type FormFieldFeedback } from '../form-field/form-field.svelte';
 type $$ComponentProps = {
-    group?: string;
-    items?: ReferenceItem[];
+    group?: string | number;
+    items?: any[];
+    /**
+     * Maps database field names to ReferenceItem properties.
+     * Use this when your data uses different field names (e.g., 'name' instead of 'label').
+     *
+     * @example
+     * // Basic usage
+     * fieldNames={{ label: 'name', value: 'id' }}
+     *
+     * @example
+     * // With description field
+     * fieldNames={{ label: 'title', value: 'id', description: 'subtitle' }}
+     */
+    fieldNames?: FieldNameMapping | undefined;
     size?: ComponentSize;
     disabled?: boolean;
     required?: boolean;
     label?: string;
     helperText?: string;
     feedback?: FormFieldFeedback;
-    onChange?: ((value: string) => void) | undefined;
+    onChange?: ((value: string | number) => void) | undefined;
 };
-declare const RadioGroup: import("svelte").Component<$$ComponentProps, {}, "">;
+declare const RadioGroup: import("svelte").Component<$$ComponentProps, {}, "group">;
 type RadioGroup = ReturnType<typeof RadioGroup>;
 export default RadioGroup;

package/dist/forms/reference-box/reference-box.svelte

@@ -1,4 +1,4 @@
-<script lang="ts">
+<script lang="ts" generics="T = ReferenceItem">
 	import MultiSelectBase, {
 		type MultiSelectAdapter
 	} from '../multi-select-base/multi-select-base.svelte';
@@ -8,15 +8,18 @@
 		ReferenceItem,
 		SearchFunction,
 		CreateNewFunction,
-		LinkBuilderFunction
+		LinkBuilderFunction,
+		FieldNameMapping
 	} from '../../types/form.js';
+	import { createFieldMapper } from '../../types/form.js';
 	import Prompt from '../../modals/prompt.svelte';
 	import { ucfirst } from '../../helpers/ucfirst.js';
 	import Icon from '../../icons/icon.svelte';
 
 	let {
-		value = $bindable([] as ReferenceItem[]),
-		items = [] as ReferenceItem[],
+		value = $bindable([] as T[]),
+		items = [] as T[],
+		fieldNames = undefined as FieldNameMapping | undefined,
 		search = undefined,
 		createNew = undefined,
 		linkBuilder = undefined as LinkBuilderFunction | undefined,
@@ -29,10 +32,23 @@
 		helperText = undefined as string | undefined,
 		feedback = undefined as FormFieldFeedback | undefined,
 		maxItems = undefined as number | undefined,
-		onChange = undefined as ((value: ReferenceItem[]) => void) | undefined
+		onChange = undefined as ((value: T[]) => void) | undefined
 	}: {
-		value?: ReferenceItem[];
-		items?: ReferenceItem[];
+		value?: T[];
+		items?: T[];
+		/**
+		 * Maps database field names to ReferenceItem properties.
+		 * Use this when your data uses different field names (e.g., 'name' instead of 'label').
+		 * 
+		 * @example
+		 * // Basic usage
+		 * fieldNames={{ label: 'name', value: 'id' }}
+		 * 
+		 * @example
+		 * // With description field
+		 * fieldNames={{ label: 'title', value: 'id', description: 'subtitle' }}
+		 */
+		fieldNames?: FieldNameMapping | undefined;
 		search?: SearchFunction | undefined;
 		createNew?: CreateNewFunction<ReferenceItem> | undefined;
 		linkBuilder?: LinkBuilderFunction | undefined;
@@ -45,7 +61,7 @@
 		helperText?: string;
 		feedback?: FormFieldFeedback | undefined;
 		maxItems?: number | undefined;
-		onChange?: ((value: ReferenceItem[]) => void) | undefined;
+		onChange?: ((value: T[]) => void) | undefined;
 	} = $props();
 
 	let baseComponent: MultiSelectBase<ReferenceItem> | null = $state(null);
@@ -57,10 +73,40 @@
 	let promptKey = $state(0);
 	let currentSearchText = $state('');
 
-	// Use local items when search function is provided, otherwise use static items
-	let currentItems = $derived(search ? localItems : items);
+	// Create field mapper
+	const mapper = $derived(createFieldMapper<T>(fieldNames));
 
-	// Convert ReferenceItem[] to menu options format
+	// Transform items for internal use (always work with ReferenceItem internally)
+	const referenceItems = $derived(
+		fieldNames ? items.map(item => mapper.toReferenceItem(item)) : items as unknown as ReferenceItem[]
+	);
+
+	// Internal value state (always ReferenceItem[])
+	let internalValue = $state<ReferenceItem[]>([]);
+
+	// Sync internal value from external value
+	$effect(() => {
+		if (fieldNames) {
+			internalValue = value.map(item => mapper.toReferenceItem(item));
+		} else {
+			internalValue = value as unknown as ReferenceItem[];
+		}
+	});
+
+	// Update external value from internal value
+	function updateExternalValue(newInternalValue: ReferenceItem[]) {
+		if (fieldNames) {
+			value = newInternalValue.map(ref => mapper.fromReferenceItem(ref));
+		} else {
+			value = newInternalValue as unknown as T[];
+		}
+		onChange?.(value);
+	}
+
+	// Use local items when search function is provided, otherwise use transformed items
+	let currentItems = $derived(search ? localItems : referenceItems);
+
+	// Convert to menu options format
 	let menuOptions = $derived(currentItems);
 
 	// Adapter to work with ReferenceItems
@@ -69,7 +115,15 @@
 		getKey: (item: ReferenceItem) => String(item.value ?? item.label),
 		equals: (a: ReferenceItem, b: ReferenceItem) => a.value === b.value,
 		fromMenuOption: (option: ReferenceItem) => option,
-		getLink: linkBuilder ? (item: ReferenceItem) => linkBuilder(item) : undefined,
+		getLink: linkBuilder 
+			? (item: ReferenceItem) => {
+				// Find original item to pass to linkBuilder
+				const original = fieldNames 
+					? value.find(v => mapper.toReferenceItem(v).value === item.value)
+					: item;
+				return linkBuilder(original as any);
+			}
+			: undefined,
 		getTooltip: (item: ReferenceItem) => item.description
 	});
 
@@ -122,9 +176,10 @@
 					localItems = [...localItems, result];
 				}
 
-				// Add the newly created item to value
-				value = [...value, result];
-				onChange?.(value);
+				// Add the newly created item to internal value, then sync to external
+				const newInternalValue = [...internalValue, result];
+				internalValue = newInternalValue;
+				updateExternalValue(newInternalValue);
 				showPrompt = false;
 			} else {
 				createError = 'Failed to create new item';
@@ -158,7 +213,7 @@
 
 <MultiSelectBase
 	bind:this={baseComponent}
-	bind:value
+	bind:value={internalValue}
 	adapter={referenceAdapter}
 	{placeholder}
 	{required}
@@ -169,7 +224,7 @@
 	{helperText}
 	{feedback}
 	{maxItems}
-	{onChange}
+	onChange={updateExternalValue}
 	onInputChange={handleInputChange}
 	{isLoading}
 	filterSuggestions={!search}

package/dist/forms/reference-box/reference-box.svelte.d.ts

@@ -1,22 +1,55 @@
 import type { FormFieldFeedback } from '../form-field/form-field.svelte';
-import type { ComponentSize, ReferenceItem, SearchFunction, CreateNewFunction, LinkBuilderFunction } from '../../types/form.js';
-type $$ComponentProps = {
-    value?: ReferenceItem[];
-    items?: ReferenceItem[];
-    search?: SearchFunction | undefined;
-    createNew?: CreateNewFunction<ReferenceItem> | undefined;
-    linkBuilder?: LinkBuilderFunction | undefined;
-    resourceName?: string | undefined;
-    placeholder?: string;
-    required?: boolean;
-    disabled?: boolean;
-    size?: ComponentSize;
-    label?: string;
-    helperText?: string;
-    feedback?: FormFieldFeedback | undefined;
-    maxItems?: number | undefined;
-    onChange?: ((value: ReferenceItem[]) => void) | undefined;
+import type { ComponentSize, ReferenceItem, SearchFunction, CreateNewFunction, LinkBuilderFunction, FieldNameMapping } from '../../types/form.js';
+declare function $$render<T = ReferenceItem>(): {
+    props: {
+        value?: T[];
+        items?: T[];
+        /**
+         * Maps database field names to ReferenceItem properties.
+         * Use this when your data uses different field names (e.g., 'name' instead of 'label').
+         *
+         * @example
+         * // Basic usage
+         * fieldNames={{ label: 'name', value: 'id' }}
+         *
+         * @example
+         * // With description field
+         * fieldNames={{ label: 'title', value: 'id', description: 'subtitle' }}
+         */
+        fieldNames?: FieldNameMapping | undefined;
+        search?: SearchFunction | undefined;
+        createNew?: CreateNewFunction<ReferenceItem> | undefined;
+        linkBuilder?: LinkBuilderFunction | undefined;
+        resourceName?: string | undefined;
+        placeholder?: string;
+        required?: boolean;
+        disabled?: boolean;
+        size?: ComponentSize;
+        label?: string;
+        helperText?: string;
+        feedback?: FormFieldFeedback | undefined;
+        maxItems?: number | undefined;
+        onChange?: ((value: T[]) => void) | undefined;
+    };
+    exports: {};
+    bindings: "value";
+    slots: {};
+    events: {};
 };
-declare const ReferenceBox: import("svelte").Component<$$ComponentProps, {}, "value">;
-type ReferenceBox = ReturnType<typeof ReferenceBox>;
+declare class __sveltets_Render<T = ReferenceItem> {
+    props(): ReturnType<typeof $$render<T>>['props'];
+    events(): ReturnType<typeof $$render<T>>['events'];
+    slots(): ReturnType<typeof $$render<T>>['slots'];
+    bindings(): "value";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T = ReferenceItem>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T = ReferenceItem>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const ReferenceBox: $$IsomorphicComponent;
+type ReferenceBox<T = ReferenceItem> = InstanceType<typeof ReferenceBox<T>>;
 export default ReferenceBox;

package/dist/types/form.d.ts

@@ -33,3 +33,78 @@ export type CreateNewFunction<ReferenceItem> = (inputName: string) => Promise<Re
  * Link builder function type
  */
 export type LinkBuilderFunction = (item: ReferenceItem) => string | undefined;
+/**
+ * Maps database object field names to ReferenceItem properties.
+ * Allows components to work directly with your database objects.
+ *
+ * @example
+ * // Basic usage - map database fields to display format
+ * fieldNames={{ label: 'name', value: 'id' }}
+ *
+ * @example
+ * // With optional fields
+ * fieldNames={{
+ *   label: 'title',
+ *   value: 'id',
+ *   description: 'subtitle',
+ *   disabled: 'isInactive'
+ * }}
+ */
+export type FieldNameMapping = {
+    /**
+     * Database field name to use for display label
+     * @default 'label'
+     */
+    label?: string;
+    /**
+     * Database field name to use for unique value/ID
+     * @default 'value'
+     */
+    value?: string;
+    /**
+     * Database field name to use for description/subtitle text
+     * @default 'description'
+     */
+    description?: string;
+    /**
+     * Database field name to use for disabled state
+     * @default 'disabled'
+     */
+    disabled?: string;
+};
+/**
+ * Creates field mapping transformation functions.
+ * Used internally by components to convert between user types and ReferenceItem.
+ *
+ * @internal
+ */
+export declare function createFieldMapper<T>(fieldNames?: FieldNameMapping): {
+    /**
+     * Converts user's database object to ReferenceItem for internal use
+     */
+    toReferenceItem: (item: T) => ReferenceItem;
+    /**
+     * Converts ReferenceItem back to user's database object type
+     * Note: Only reconstructs mapped fields, additional fields are lost
+     */
+    fromReferenceItem: (ref: ReferenceItem) => T;
+    /**
+     * Extracts just the value field from user's object
+     */
+    extractValue: (item: T) => string | number | null;
+    /**
+     * Finds an item in array by matching value field
+     */
+    findByValue: (items: T[], value: string | number | null) => T | undefined;
+};
+/**
+ * Helper function to create field name mappings with less syntax.
+ *
+ * @example
+ * // Instead of:
+ * fieldNames={{ label: 'name', value: 'id' }}
+ *
+ * // You can write:
+ * fieldNames={mapFields('name', 'id')}
+ */
+export declare function mapFields(label: string, value: string, description?: string, disabled?: string): FieldNameMapping;

package/dist/types/form.js

@@ -1 +1,73 @@
-export {};
+/**
+ * Creates field mapping transformation functions.
+ * Used internally by components to convert between user types and ReferenceItem.
+ *
+ * @internal
+ */
+export function createFieldMapper(fieldNames) {
+    const labelField = fieldNames?.label ?? 'label';
+    const valueField = fieldNames?.value ?? 'value';
+    const descriptionField = fieldNames?.description ?? 'description';
+    const disabledField = fieldNames?.disabled ?? 'disabled';
+    return {
+        /**
+         * Converts user's database object to ReferenceItem for internal use
+         */
+        toReferenceItem: (item) => {
+            const obj = item;
+            return {
+                label: String(obj[labelField] ?? ''),
+                value: obj[valueField] ?? null,
+                description: obj[descriptionField],
+                disabled: obj[disabledField]
+            };
+        },
+        /**
+         * Converts ReferenceItem back to user's database object type
+         * Note: Only reconstructs mapped fields, additional fields are lost
+         */
+        fromReferenceItem: (ref) => {
+            const obj = {
+                [labelField]: ref.label,
+                [valueField]: ref.value
+            };
+            if (ref.description !== undefined) {
+                obj[descriptionField] = ref.description;
+            }
+            if (ref.disabled !== undefined) {
+                obj[disabledField] = ref.disabled;
+            }
+            return obj;
+        },
+        /**
+         * Extracts just the value field from user's object
+         */
+        extractValue: (item) => {
+            return item[valueField] ?? null;
+        },
+        /**
+         * Finds an item in array by matching value field
+         */
+        findByValue: (items, value) => {
+            return items.find(item => item[valueField] === value);
+        }
+    };
+}
+/**
+ * Helper function to create field name mappings with less syntax.
+ *
+ * @example
+ * // Instead of:
+ * fieldNames={{ label: 'name', value: 'id' }}
+ *
+ * // You can write:
+ * fieldNames={mapFields('name', 'id')}
+ */
+export function mapFields(label, value, description, disabled) {
+    return {
+        label,
+        value,
+        ...(description && { description }),
+        ...(disabled && { disabled })
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "sveltacular",
-	"version": "1.1.0",
+	"version": "1.1.1",
 	"description": "A Svelte component library",
 	"main": "dist/index.js",
 	"module": "dist/index.js",