@elrayes/dual-listbox 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ahmed Elrayes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,126 @@
+# @elrayes/dual-listbox
+
+A zero-dependency (vanilla JS) dual-list box with grouping, search, select-all, and theming (Bootstrap 5.2 default, Tailwind optional) with TypeScript types.
+
+## Installation
+
+```bash
+npm install @elrayes/dual-listbox
+```
+
+
+## Usage (ES Modules)
+
+```ts
+import { DualListBox, useTheme, tailwindTheme} from '@elrayes/dual-listbox';
+import { tailwindTheme } from '@elrayes/dual-listbox';
+useTheme(tailwindTheme); // sets global default for all new instances 
+DualListBox.setTheme(tailwindTheme); // alias for useTheme()
+import '@elrayes/dual-listbox/styles/core.css';
+import '@elrayes/dual-listbox/themes/bootstrap.css'; // or tailwind.css
+
+const items = [
+  { item: 'Apple', value: 1, group: 'Fruits' },
+  { item: 'Tomato', value: 2, group: 'Vegetables' },
+];
+
+const dlb = new DualListBox('#dual-listbox-container', {
+  dataArray: items,
+  selectedItems: [],
+  onSubmit: (selected, unselected, all, selectedArray) => {
+    console.log(selectedArray);
+  },
+});
+
+// New methods (no duplicates)
+const selectedItems = dlb.getSelectedItems();
+const unselectedItems = dlb.getUnselectedItems();
+const allItems = dlb.getAllItems();
+```
+
+## Usage (CommonJS)
+
+```js
+const { DualListBox } = require('@elrayes/dual-listbox');
+require('@elrayes/dual-listbox/styles/core.css');
+require('@elrayes/dual-listbox/themes/bootstrap.css');
+
+const dlb = new DualListBox('#dual-listbox-container', { /* options */ });
+```
+
+## Options (TypeScript)
+
+```ts
+export interface DualListBoxOptions {
+  itemName?: string; // default "item"
+  groupName?: string; // default "group"
+  valueName?: string; // default "value"
+  inputName?: string; // form input name for hidden fields
+  tabNameText?: string;
+  rightTabNameText?: string;
+  searchPlaceholderText?: string;
+  includeButtonText?: string;
+  excludeButtonText?: string;
+  dataArray?: any[];
+  selectedItems?: any[];
+  hideEmptyGroups?: boolean;
+  submitForm?: boolean;
+  onSubmit?: (selected, unselected, allItems, selectedArray) => void | null;
+  theme?: Partial<DualListBoxTheme>;
+}
+```
+
+## Theming
+
+- Built-in theme maps classes to your CSS framework.
+- Presets: Bootstrap 5.2 (defaultTheme) and Tailwind (tailwindTheme).
+- You can set a global default for all new instances using `useTheme`:
+
+```ts
+import { DualListBox, useTheme } from '@elrayes/dual-listbox';
+import { tailwindTheme } from '@elrayes/dual-listbox/dist/themePresets';
+
+useTheme(tailwindTheme); // applies to all new DualListBox instances
+
+new DualListBox('#el'); // uses the global Tailwind theme
+```
+
+- Or provide a custom theme per instance (an instance option has priority over global):
+
+```ts
+new DualListBox('#el', {
+  theme: {
+    // override any class strings
+    btn: 'my-btn my-btn--primary',
+  }
+});
+```
+
+Note: For backward compatibility, `DualListBox.setTheme(tailwindTheme)` is still available and is an alias to `useTheme(tailwindTheme)`.
+
+Alternatively, rely on CSS variables and write a stylesheet that targets `.dual-listbox`.
+
+## Laravel + Vite Integration
+
+1. Place the container in your Blade:
+
+```html
+<div id="dual-listbox-container"></div>
+```
+
+2. Import and initialize in your app JS that Vite builds.
+
+3. Include core.css and choose a theme stylesheet.
+
+## API
+
+- `new DualListBox(element, options)`
+- `getSelectedValues(): Promise<(string|number)[]>` (legacy values API)
+- Getters: `selected`, `unselected`, `allItems`, `selectedArray`
+- New methods (return item objects without duplicates):
+  - `getSelectedItems()`
+  - `getUnselectedItems()`
+  - `getAllItems()`
+
+## License
+MIT

package/dist/index.d.mts

@@ -0,0 +1,83 @@
+type DualListBoxItem = Record<string, any> & {
+    [key: string]: any;
+};
+type OnSubmitHandler = (selected: Record<string, DualListBoxItem[]>, unselected: Record<string, DualListBoxItem[]>, allItems: DualListBoxItem[], selectedArray: (string | number)[]) => void;
+interface DualListBoxTheme {
+    container: string;
+    row: string;
+    colLeft: string;
+    colCenter: string;
+    colRight: string;
+    card: string;
+    cardHeader: string;
+    cardBody: string;
+    cardFooter: string;
+    searchInput: string;
+    listGroup: string;
+    listItem: string;
+    formCheck: string;
+    formCheckInput: string;
+    formCheckLabel: string;
+    btn: string;
+    btnInclude: string;
+    btnExclude: string;
+}
+interface DualListBoxOptions {
+    itemName?: string;
+    groupName?: string;
+    valueName?: string;
+    inputName?: string;
+    tabNameText?: string;
+    rightTabNameText?: string;
+    searchPlaceholderText?: string;
+    includeButtonText?: string;
+    excludeButtonText?: string;
+    dataArray?: DualListBoxItem[];
+    selectedItems?: DualListBoxItem[];
+    hideEmptyGroups?: boolean;
+    submitForm?: boolean;
+    onSubmit?: OnSubmitHandler | null;
+    theme?: Partial<DualListBoxTheme>;
+}
+
+/**
+ * Set the global default theme for all new DualListBox instances.
+ * Instance option `theme` still has highest priority.
+ */
+declare function useTheme(theme: Partial<DualListBoxTheme> | DualListBoxTheme): void;
+declare class DualListBox {
+    private rootEl;
+    private formEl;
+    private instanceId;
+    private defaults;
+    private settings;
+    private groups;
+    private selectedGroups;
+    constructor(element: Element | string, options?: DualListBoxOptions);
+    private generateInstanceId;
+    private buildGroups;
+    private removeDuplicatesFromLeft;
+    private render;
+    private generateGroupedListHTML;
+    private updateSelectAllInfo;
+    private bindEvents;
+    private moveItems;
+    private toggleSelectAll;
+    private searchItems;
+    private appendSelectedGroupsOnSubmit;
+    getSelectedValues(): Promise<(string | number)[]>;
+    get selected(): Record<string, DualListBoxItem[]>;
+    get selectedArray(): (string | number)[];
+    get unselected(): Record<string, DualListBoxItem[]>;
+    get allItems(): DualListBoxItem[];
+    getSelectedItems(): DualListBoxItem[];
+    getUnselectedItems(): DualListBoxItem[];
+    getAllItems(): DualListBoxItem[];
+}
+declare function initDualListBox(selector: string | Element, options?: DualListBoxOptions): DualListBox;
+
+declare const defaultTheme: DualListBoxTheme;
+declare const bootstrapTheme: DualListBoxTheme;
+declare const tailwindTheme: DualListBoxTheme;
+
+export { DualListBox, type DualListBoxItem, type DualListBoxOptions, type DualListBoxTheme, bootstrapTheme, defaultTheme, initDualListBox, tailwindTheme, useTheme };

package/dist/index.d.ts

@@ -0,0 +1,83 @@
+type DualListBoxItem = Record<string, any> & {
+    [key: string]: any;
+};
+type OnSubmitHandler = (selected: Record<string, DualListBoxItem[]>, unselected: Record<string, DualListBoxItem[]>, allItems: DualListBoxItem[], selectedArray: (string | number)[]) => void;
+interface DualListBoxTheme {
+    container: string;
+    row: string;
+    colLeft: string;
+    colCenter: string;
+    colRight: string;
+    card: string;
+    cardHeader: string;
+    cardBody: string;
+    cardFooter: string;
+    searchInput: string;
+    listGroup: string;
+    listItem: string;
+    formCheck: string;
+    formCheckInput: string;
+    formCheckLabel: string;
+    btn: string;
+    btnInclude: string;
+    btnExclude: string;
+}
+interface DualListBoxOptions {
+    itemName?: string;
+    groupName?: string;
+    valueName?: string;
+    inputName?: string;
+    tabNameText?: string;
+    rightTabNameText?: string;
+    searchPlaceholderText?: string;
+    includeButtonText?: string;
+    excludeButtonText?: string;
+    dataArray?: DualListBoxItem[];
+    selectedItems?: DualListBoxItem[];
+    hideEmptyGroups?: boolean;
+    submitForm?: boolean;
+    onSubmit?: OnSubmitHandler | null;
+    theme?: Partial<DualListBoxTheme>;
+}
+
+/**
+ * Set the global default theme for all new DualListBox instances.
+ * Instance option `theme` still has highest priority.
+ */
+declare function useTheme(theme: Partial<DualListBoxTheme> | DualListBoxTheme): void;
+declare class DualListBox {
+    private rootEl;
+    private formEl;
+    private instanceId;
+    private defaults;
+    private settings;
+    private groups;
+    private selectedGroups;
+    constructor(element: Element | string, options?: DualListBoxOptions);
+    private generateInstanceId;
+    private buildGroups;
+    private removeDuplicatesFromLeft;
+    private render;
+    private generateGroupedListHTML;
+    private updateSelectAllInfo;
+    private bindEvents;
+    private moveItems;
+    private toggleSelectAll;
+    private searchItems;
+    private appendSelectedGroupsOnSubmit;
+    getSelectedValues(): Promise<(string | number)[]>;
+    get selected(): Record<string, DualListBoxItem[]>;
+    get selectedArray(): (string | number)[];
+    get unselected(): Record<string, DualListBoxItem[]>;
+    get allItems(): DualListBoxItem[];
+    getSelectedItems(): DualListBoxItem[];
+    getUnselectedItems(): DualListBoxItem[];
+    getAllItems(): DualListBoxItem[];
+}
+declare function initDualListBox(selector: string | Element, options?: DualListBoxOptions): DualListBox;
+
+declare const defaultTheme: DualListBoxTheme;
+declare const bootstrapTheme: DualListBoxTheme;
+declare const tailwindTheme: DualListBoxTheme;
+
+export { DualListBox, type DualListBoxItem, type DualListBoxOptions, type DualListBoxTheme, bootstrapTheme, defaultTheme, initDualListBox, tailwindTheme, useTheme };