svelte-select-5 6.0.2 → 6.1.1

package/Select.svelte

@@ -1,4 +1,39 @@
 <script>
+    /**
+     * @typedef {Object} SelectItem
+     * @property {string|number} [value] - The value identifier for the item
+     * @property {string} [label] - Display label (or use custom label prop)
+     * @property {boolean} [selectable] - Whether the item can be selected
+     * @property {boolean} [isCreator] - Whether this is a "create new" item
+     * @property {string} [groupValue] - Group identifier for grouped items
+     * @property {string} [groupHeader] - Group header display text
+     * @property {*} [key: string] - Additional custom properties
+     */
+
+    /**
+     * @typedef {SelectItem|SelectItem[]|null|undefined} SelectValue
+     */
+
+    /**
+     * @typedef {Object} FloatingConfig
+     * @property {'absolute'|'fixed'} [strategy] - Positioning strategy
+     * @property {'bottom-start'|'bottom-end'|'top-start'|'top-end'} [placement] - Dropdown placement
+     */
+
+    /**
+     * @callback ItemFilterFn
+     * @param {string} label - The item's label value
+     * @param {string} filterText - Current filter text
+     * @param {SelectItem} item - The item being filtered
+     * @returns {boolean} - Whether the item matches the filter
+     */
+
+    /**
+     * @callback LoadOptionsFn
+     * @param {string} filterText - Current filter text
+     * @returns {Promise<SelectItem[]>} - Promise resolving to items
+     */
+
     import { onDestroy, onMount } from 'svelte';
     import { offset, flip, shift } from 'svelte-floating-ui/dom';
     import { createFloatingActions } from 'svelte-floating-ui';
@@ -26,6 +61,10 @@
         listOpen = $bindable(false),
         hoverItemIndex = $bindable(0),
 
+        // Read-only bindable props (output only - external changes are ignored)
+        readonlyValue = $bindable(),
+        readonlyId = $bindable(),
+
         // Function props
         filter = _filter,
         getItems = _getItems,
@@ -122,6 +161,7 @@
     let isScrolling = $state(false);
     let prefloat = $state(true);
     let _inputAttributes = $state({});
+    let prevJustValue = $state(undefined);
     let isScrollingTimer;
 
     // Floating UI config - using closure for listOffset to capture current value
@@ -719,6 +759,32 @@
         justValue = computeJustValue();
     });
 
+    // Handle external changes to justValue (allows setting value via justValue)
+    $effect(() => {
+        const computed = computeJustValue();
+        const isExternalChange = justValue !== prevJustValue &&
+            JSON.stringify(justValue) !== JSON.stringify(computed);
+
+        if (isExternalChange && items) {
+            if (multiple) {
+                value = justValue
+                    ? items.filter(item => justValue.includes(item[itemId]))
+                    : null;
+            } else {
+                value = justValue != null
+                    ? items.find(item => item[itemId] === justValue) ?? null
+                    : null;
+            }
+        }
+        prevJustValue = justValue;
+    });
+
+    // Read-only props - always reflect current state, external changes are ignored
+    $effect(() => {
+        readonlyValue = value;
+        readonlyId = computeJustValue();
+    });
+
     $effect(() => {
         if (!multiple && prev_value && !value) oninput?.(value);
     });

package/Select.svelte.d.ts

@@ -1,9 +1,52 @@
 export default Select;
+export type SelectItem = {
+    /**
+     * - The value identifier for the item
+     */
+    value?: string | number;
+    /**
+     * - Display label (or use custom label prop)
+     */
+    label?: string;
+    /**
+     * - Whether the item can be selected
+     */
+    selectable?: boolean;
+    /**
+     * - Whether this is a "create new" item
+     */
+    isCreator?: boolean;
+    /**
+     * - Group identifier for grouped items
+     */
+    groupValue?: string;
+    /**
+     * - Group header display text
+     */
+    groupHeader?: string;
+    /**
+     * : string] - Additional custom properties
+     */
+    key?: any;
+};
+export type SelectValue = SelectItem | SelectItem[] | null | undefined;
+export type FloatingConfig = {
+    /**
+     * - Positioning strategy
+     */
+    strategy?: "absolute" | "fixed";
+    /**
+     * - Dropdown placement
+     */
+    placement?: "bottom-start" | "bottom-end" | "top-start" | "top-end";
+};
+export type ItemFilterFn = (label: string, filterText: string, item: SelectItem) => boolean;
+export type LoadOptionsFn = (filterText: string) => Promise<SelectItem[]>;
 type Select = {
     $on?(type: string, callback: (e: any) => void): () => void;
     $set?(props: Partial<$$ComponentProps>): void;
 } & {
-    getFilteredItems: () => any;
+    getFilteredItems: () => SelectItem[];
     handleClear: () => void;
 };
 declare const Select: import("svelte").Component<{
@@ -17,6 +60,8 @@ declare const Select: import("svelte").Component<{
     loading?: boolean;
     listOpen?: boolean;
     hoverItemIndex?: number;
+    readonlyValue?: any;
+    readonlyId?: any;
     filter?: typeof _filter;
     getItems?: typeof _getItems;
     id?: any;
@@ -79,9 +124,9 @@ declare const Select: import("svelte").Component<{
     inputHidden?: any;
     requiredSlot?: any;
 }, {
-    getFilteredItems: () => any;
+    getFilteredItems: () => import("./filter").SelectItem[];
     handleClear: () => void;
-}, "loading" | "filterText" | "items" | "value" | "justValue" | "container" | "input" | "focused" | "listOpen" | "hoverItemIndex">;
+}, "loading" | "filterText" | "items" | "value" | "focused" | "listOpen" | "justValue" | "container" | "input" | "hoverItemIndex" | "readonlyValue" | "readonlyId">;
 type $$ComponentProps = {
     justValue?: any;
     container?: any;
@@ -93,6 +138,8 @@ type $$ComponentProps = {
     loading?: boolean;
     listOpen?: boolean;
     hoverItemIndex?: number;
+    readonlyValue?: any;
+    readonlyId?: any;
     filter?: typeof _filter;
     getItems?: typeof _getItems;
     id?: any;

package/filter.d.ts

@@ -1,14 +1,85 @@
-export default function filter({ loadOptions, filterText, items, multiple, value, itemId, groupBy, filterSelectedItems, itemFilter, convertStringItemsToObjects, filterGroupedItems, label, }: {
-    loadOptions: any;
-    filterText: any;
-    items: any;
-    multiple: any;
-    value: any;
-    itemId: any;
-    groupBy: any;
-    filterSelectedItems: any;
-    itemFilter: any;
-    convertStringItemsToObjects: any;
-    filterGroupedItems: any;
-    label: any;
-}): any;
+/**
+ * @typedef {Object} SelectItem
+ * @property {string|number} [value]
+ * @property {string} [label]
+ * @property {*} [key: string]
+ */
+/**
+ * @typedef {Object} FilterOptions
+ * @property {Function|undefined} loadOptions - Async load function
+ * @property {string} filterText - Current filter text
+ * @property {(SelectItem|string)[]} items - Items to filter
+ * @property {boolean} multiple - Multi-select mode
+ * @property {SelectItem|SelectItem[]|null} value - Current value
+ * @property {string} itemId - Property name for item ID
+ * @property {string|undefined} groupBy - Property name for grouping
+ * @property {boolean} filterSelectedItems - Whether to filter out selected items
+ * @property {(label: string, filterText: string, item: SelectItem) => boolean} itemFilter - Filter function
+ * @property {(items: (string|SelectItem)[]) => SelectItem[]} convertStringItemsToObjects - Converter function
+ * @property {(items: SelectItem[]) => SelectItem[]} filterGroupedItems - Group filter function
+ * @property {string} label - Property name for label
+ */
+/**
+ * Filters items based on filter text and selection state
+ * @param {FilterOptions} options - Filter options
+ * @returns {SelectItem[]} Filtered items
+ */
+export default function filter({ loadOptions, filterText, items, multiple, value, itemId, groupBy, filterSelectedItems, itemFilter, convertStringItemsToObjects, filterGroupedItems, label, }: FilterOptions): SelectItem[];
+export type SelectItem = {
+    value?: string | number;
+    label?: string;
+    /**
+     * : string]
+     */
+    key?: any;
+};
+export type FilterOptions = {
+    /**
+     * - Async load function
+     */
+    loadOptions: Function | undefined;
+    /**
+     * - Current filter text
+     */
+    filterText: string;
+    /**
+     * - Items to filter
+     */
+    items: (SelectItem | string)[];
+    /**
+     * - Multi-select mode
+     */
+    multiple: boolean;
+    /**
+     * - Current value
+     */
+    value: SelectItem | SelectItem[] | null;
+    /**
+     * - Property name for item ID
+     */
+    itemId: string;
+    /**
+     * - Property name for grouping
+     */
+    groupBy: string | undefined;
+    /**
+     * - Whether to filter out selected items
+     */
+    filterSelectedItems: boolean;
+    /**
+     * - Filter function
+     */
+    itemFilter: (label: string, filterText: string, item: SelectItem) => boolean;
+    /**
+     * - Converter function
+     */
+    convertStringItemsToObjects: (items: (string | SelectItem)[]) => SelectItem[];
+    /**
+     * - Group filter function
+     */
+    filterGroupedItems: (items: SelectItem[]) => SelectItem[];
+    /**
+     * - Property name for label
+     */
+    label: string;
+};

package/filter.js

@@ -1,3 +1,31 @@
+/**
+ * @typedef {Object} SelectItem
+ * @property {string|number} [value]
+ * @property {string} [label]
+ * @property {*} [key: string]
+ */
+
+/**
+ * @typedef {Object} FilterOptions
+ * @property {Function|undefined} loadOptions - Async load function
+ * @property {string} filterText - Current filter text
+ * @property {(SelectItem|string)[]} items - Items to filter
+ * @property {boolean} multiple - Multi-select mode
+ * @property {SelectItem|SelectItem[]|null} value - Current value
+ * @property {string} itemId - Property name for item ID
+ * @property {string|undefined} groupBy - Property name for grouping
+ * @property {boolean} filterSelectedItems - Whether to filter out selected items
+ * @property {(label: string, filterText: string, item: SelectItem) => boolean} itemFilter - Filter function
+ * @property {(items: (string|SelectItem)[]) => SelectItem[]} convertStringItemsToObjects - Converter function
+ * @property {(items: SelectItem[]) => SelectItem[]} filterGroupedItems - Group filter function
+ * @property {string} label - Property name for label
+ */
+
+/**
+ * Filters items based on filter text and selection state
+ * @param {FilterOptions} options - Filter options
+ * @returns {SelectItem[]} Filtered items
+ */
 export default function filter({
     loadOptions,
     filterText,

package/get-items.d.ts

@@ -1,11 +1,70 @@
-export default function getItems({ dispatch, loadOptions, convertStringItemsToObjects, filterText }: {
-    dispatch: any;
-    loadOptions: any;
-    convertStringItemsToObjects: any;
-    filterText: any;
-}): Promise<{
-    filteredItems: any;
+/**
+ * @typedef {Object} SelectItem
+ * @property {string|number} [value]
+ * @property {string} [label]
+ * @property {*} [key: string]
+ */
+/**
+ * @typedef {Object} GetItemsOptions
+ * @property {(event: string, detail: Object) => void} dispatch - Event dispatcher function
+ * @property {(filterText: string) => Promise<SelectItem[]|string[]>} loadOptions - Async load function
+ * @property {(items: string[]) => SelectItem[]} convertStringItemsToObjects - String to object converter
+ * @property {string} filterText - Current filter text
+ */
+/**
+ * @typedef {Object} GetItemsResult
+ * @property {SelectItem[]} filteredItems - Loaded items
+ * @property {boolean} loading - Loading state
+ * @property {boolean} focused - Focus state
+ * @property {boolean} listOpen - List open state
+ */
+/**
+ * Asynchronously loads items using loadOptions function
+ * @param {GetItemsOptions} options - Options for loading items
+ * @returns {Promise<GetItemsResult|undefined>} Result object or undefined if cancelled
+ */
+export default function getItems({ dispatch, loadOptions, convertStringItemsToObjects, filterText }: GetItemsOptions): Promise<GetItemsResult | undefined>;
+export type SelectItem = {
+    value?: string | number;
+    label?: string;
+    /**
+     * : string]
+     */
+    key?: any;
+};
+export type GetItemsOptions = {
+    /**
+     * - Event dispatcher function
+     */
+    dispatch: (event: string, detail: any) => void;
+    /**
+     * - Async load function
+     */
+    loadOptions: (filterText: string) => Promise<SelectItem[] | string[]>;
+    /**
+     * - String to object converter
+     */
+    convertStringItemsToObjects: (items: string[]) => SelectItem[];
+    /**
+     * - Current filter text
+     */
+    filterText: string;
+};
+export type GetItemsResult = {
+    /**
+     * - Loaded items
+     */
+    filteredItems: SelectItem[];
+    /**
+     * - Loading state
+     */
     loading: boolean;
+    /**
+     * - Focus state
+     */
     focused: boolean;
+    /**
+     * - List open state
+     */
     listOpen: boolean;
-}>;
+};

package/get-items.js

@@ -1,3 +1,31 @@
+/**
+ * @typedef {Object} SelectItem
+ * @property {string|number} [value]
+ * @property {string} [label]
+ * @property {*} [key: string]
+ */
+
+/**
+ * @typedef {Object} GetItemsOptions
+ * @property {(event: string, detail: Object) => void} dispatch - Event dispatcher function
+ * @property {(filterText: string) => Promise<SelectItem[]|string[]>} loadOptions - Async load function
+ * @property {(items: string[]) => SelectItem[]} convertStringItemsToObjects - String to object converter
+ * @property {string} filterText - Current filter text
+ */
+
+/**
+ * @typedef {Object} GetItemsResult
+ * @property {SelectItem[]} filteredItems - Loaded items
+ * @property {boolean} loading - Loading state
+ * @property {boolean} focused - Focus state
+ * @property {boolean} listOpen - List open state
+ */
+
+/**
+ * Asynchronously loads items using loadOptions function
+ * @param {GetItemsOptions} options - Options for loading items
+ * @returns {Promise<GetItemsResult|undefined>} Result object or undefined if cancelled
+ */
 export default async function getItems({ dispatch, loadOptions, convertStringItemsToObjects, filterText }) {
     let res = await loadOptions(filterText).catch((err) => {
         console.warn('svelte-select loadOptions error :>> ', err);

package/no-styles/Select.svelte

@@ -1,4 +1,39 @@
 <script>
+    /**
+     * @typedef {Object} SelectItem
+     * @property {string|number} [value] - The value identifier for the item
+     * @property {string} [label] - Display label (or use custom label prop)
+     * @property {boolean} [selectable] - Whether the item can be selected
+     * @property {boolean} [isCreator] - Whether this is a "create new" item
+     * @property {string} [groupValue] - Group identifier for grouped items
+     * @property {string} [groupHeader] - Group header display text
+     * @property {*} [key: string] - Additional custom properties
+     */
+
+    /**
+     * @typedef {SelectItem|SelectItem[]|null|undefined} SelectValue
+     */
+
+    /**
+     * @typedef {Object} FloatingConfig
+     * @property {'absolute'|'fixed'} [strategy] - Positioning strategy
+     * @property {'bottom-start'|'bottom-end'|'top-start'|'top-end'} [placement] - Dropdown placement
+     */
+
+    /**
+     * @callback ItemFilterFn
+     * @param {string} label - The item's label value
+     * @param {string} filterText - Current filter text
+     * @param {SelectItem} item - The item being filtered
+     * @returns {boolean} - Whether the item matches the filter
+     */
+
+    /**
+     * @callback LoadOptionsFn
+     * @param {string} filterText - Current filter text
+     * @returns {Promise<SelectItem[]>} - Promise resolving to items
+     */
+
     import { onDestroy, onMount } from 'svelte';
     import { offset, flip, shift } from 'svelte-floating-ui/dom';
     import { createFloatingActions } from 'svelte-floating-ui';
@@ -26,6 +61,10 @@
         listOpen = $bindable(false),
         hoverItemIndex = $bindable(0),
 
+        // Read-only bindable props (output only - external changes are ignored)
+        readonlyValue = $bindable(),
+        readonlyId = $bindable(),
+
         // Function props
         filter = _filter,
         getItems = _getItems,
@@ -122,6 +161,7 @@
     let isScrolling = $state(false);
     let prefloat = $state(true);
     let _inputAttributes = $state({});
+    let prevJustValue = $state(undefined);
     let isScrollingTimer;
 
     // Floating UI config - using closure for listOffset to capture current value
@@ -719,6 +759,32 @@
         justValue = computeJustValue();
     });
 
+    // Handle external changes to justValue (allows setting value via justValue)
+    $effect(() => {
+        const computed = computeJustValue();
+        const isExternalChange = justValue !== prevJustValue &&
+            JSON.stringify(justValue) !== JSON.stringify(computed);
+
+        if (isExternalChange && items) {
+            if (multiple) {
+                value = justValue
+                    ? items.filter(item => justValue.includes(item[itemId]))
+                    : null;
+            } else {
+                value = justValue != null
+                    ? items.find(item => item[itemId] === justValue) ?? null
+                    : null;
+            }
+        }
+        prevJustValue = justValue;
+    });
+
+    // Read-only props - always reflect current state, external changes are ignored
+    $effect(() => {
+        readonlyValue = value;
+        readonlyId = computeJustValue();
+    });
+
     $effect(() => {
         if (!multiple && prev_value && !value) oninput?.(value);
     });

package/no-styles/Select.svelte.d.ts

@@ -1,9 +1,52 @@
 export default Select;
+export type SelectItem = {
+    /**
+     * - The value identifier for the item
+     */
+    value?: string | number;
+    /**
+     * - Display label (or use custom label prop)
+     */
+    label?: string;
+    /**
+     * - Whether the item can be selected
+     */
+    selectable?: boolean;
+    /**
+     * - Whether this is a "create new" item
+     */
+    isCreator?: boolean;
+    /**
+     * - Group identifier for grouped items
+     */
+    groupValue?: string;
+    /**
+     * - Group header display text
+     */
+    groupHeader?: string;
+    /**
+     * : string] - Additional custom properties
+     */
+    key?: any;
+};
+export type SelectValue = SelectItem | SelectItem[] | null | undefined;
+export type FloatingConfig = {
+    /**
+     * - Positioning strategy
+     */
+    strategy?: "absolute" | "fixed";
+    /**
+     * - Dropdown placement
+     */
+    placement?: "bottom-start" | "bottom-end" | "top-start" | "top-end";
+};
+export type ItemFilterFn = (label: string, filterText: string, item: SelectItem) => boolean;
+export type LoadOptionsFn = (filterText: string) => Promise<SelectItem[]>;
 type Select = {
     $on?(type: string, callback: (e: any) => void): () => void;
     $set?(props: Partial<$$ComponentProps>): void;
 } & {
-    getFilteredItems: () => any;
+    getFilteredItems: () => SelectItem[];
     handleClear: () => void;
 };
 declare const Select: import("svelte").Component<{
@@ -17,6 +60,8 @@ declare const Select: import("svelte").Component<{
     loading?: boolean;
     listOpen?: boolean;
     hoverItemIndex?: number;
+    readonlyValue?: any;
+    readonlyId?: any;
     filter?: typeof _filter;
     getItems?: typeof _getItems;
     id?: any;
@@ -79,9 +124,9 @@ declare const Select: import("svelte").Component<{
     inputHidden?: any;
     requiredSlot?: any;
 }, {
-    getFilteredItems: () => any;
+    getFilteredItems: () => import("../filter").SelectItem[];
     handleClear: () => void;
-}, "loading" | "filterText" | "items" | "value" | "justValue" | "container" | "input" | "focused" | "listOpen" | "hoverItemIndex">;
+}, "loading" | "filterText" | "items" | "value" | "focused" | "listOpen" | "justValue" | "container" | "input" | "hoverItemIndex" | "readonlyValue" | "readonlyId">;
 type $$ComponentProps = {
     justValue?: any;
     container?: any;
@@ -93,6 +138,8 @@ type $$ComponentProps = {
     loading?: boolean;
     listOpen?: boolean;
     hoverItemIndex?: number;
+    readonlyValue?: any;
+    readonlyId?: any;
     filter?: typeof _filter;
     getItems?: typeof _getItems;
     id?: any;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-select-5",
-  "version": "6.0.2",
+  "version": "6.1.1",
   "description": "A <Select> component for Svelte 5 apps (fork of svelte-select)",
   "repository": "https://github.com/Dbone29/svelte-select-5.git",
   "author": "Robert Balfré <rob.balfre@gmail.com> (https://github.com/rob-balfre)",