Select User Dropdown Component

A Vue 3 + Quasar component for selecting users with advanced features including search, filtering, tags, multiple selection, checkboxes, and contact actions. Perfect for user assignment, watcher selection, and user management interfaces.

Features

• ✅ Search & Filter - Real-time user search and filtering
• ✅ Multiple Selection - Support for single and multiple user selection
• ✅ Tag Support - Display and filter users by project tags
• ✅ Checkbox Mode - Checkbox-based selection for menu list mode
• ✅ Contact Actions - Email, phone, Skype, and direct chat buttons
• ✅ Owner Highlighting - Highlight owner users with star icon
• ✅ TypeScript Ready - Full TypeScript support
• ✅ Customizable - Extensive props for customization

Installation

npm install itc-select-user-dropdown
# or
pnpm install itc-select-user-dropdown

Requirements

• Vue 3.x
• Quasar 2.x

These are peer dependencies and must be installed in your project.

Usage

Basic Example

<script setup>
import { ref } from 'vue'
import { UserDropdown } from 'itc-select-user-dropdown'

const users = ref([
  {
    id: 1,
    user_name: 'John Doe',
    email: '[email protected]',
    profile_photo_url: { converted: { '50x50': '/avatar.jpg' } }
  },
  {
    id: 2,
    user_name: 'Jane Smith',
    email: '[email protected]'
  }
])

const selectedUser = ref(null)
</script>

<template>
  <UserDropdown
    :users="users"
    v-model="selectedUser"
    @select-user="(userId) => console.log('Selected:', userId)"
  />
</template>

Multiple Selection

<template>
  <UserDropdown
    :users="users"
    :multiple="true"
    :use-chips="true"
    v-model="selectedUsers"
  />
</template>

Menu List Mode (with Checkboxes)

<template>
  <q-btn label="Select Users">
    <UserDropdown
      :users="users"
      :user-menu-list="true"
      :use-check-box="true"
      :show-search-box="true"
    />
  </q-btn>
</template>

With Tags and Filtering

<script setup>
const users = ref([...])
const selectedTags = ref([1, 2])
const tagInfoMap = ref({
  1: { id: 1, name: 'Developer', primary: '#1976d2', text: '#fff' },
  2: { id: 2, name: 'Designer', primary: '#26a69a', text: '#fff' }
})
</script>

<template>
  <UserDropdown
    :users="users"
    :selected-tags="selectedTags"
    :tag-info-map="tagInfoMap"
    :project-tag-ids="[1, 2]"
  />
</template>

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | users | User[] | [] | Required. Array of user objects | | label | String | 'Select User' | Label for the dropdown | | multiple | Boolean | false | Enable multiple selection | | preSelectedUser | Array<number\|string> | [] | Pre-selected user IDs | | excludeUsers | Array<number\|string> | [] | User IDs to exclude | | selectedTags | Array<number\|string> | [] | Selected tag IDs for filtering | | userMenuList | Boolean | false | Use menu list mode instead of select | | useCheckBox | Boolean | false | Show checkboxes in menu list mode | | showSearchBox | Boolean | true | Show search box in menu mode | | showContactBtn | Boolean | false | Show contact action buttons | | readonly | Boolean | false | Readonly mode | | ownerId | Number | null | Owner user ID to highlight | | tagInfoMap | Object | {} | Map of tag IDs to tag info objects | | placeholderLogo | String | Base64 SVG | Fallback avatar logo | | skypeLogo | String | '' | Optional Skype logo URL |

See component source for complete props list.

Events

| Event | Payload | Description | |-------|---------|-------------| | select-user | userId \| userId[] \| null | Emitted when user(s) are selected | | assign-users | selectedUsers, preSelectedUsers, taskId | Emitted when users are assigned | | unassign-user | user, taskId | Emitted when a user is unassigned | | direct-chat-click | user | Emitted when direct chat button is clicked | | unassign-watcher | userId | Emitted when watcher is unassigned |

Path Aliases

This plugin uses path aliases for imports. When developing or extending this plugin, you can import using the src/ prefix:

// ✅ Good - Using path alias
import { sortList } from "src/utils/sortList";
import { DEFAULT_USER_LOGO } from "src/consts";
import UserDropdown from "src/components/UserDropdown.vue";

// ❌ Avoid - Relative paths (still works, but not recommended)
import { sortList } from "../utils/sortList";
import UserDropdown from "./components/UserDropdown.vue";

Project Structure

├─ src/
│   ├─ components/          # Vue components
│   │   ├─ UserDropdown.vue
│   │   └─ UseDropdownItem.vue
│   ├─ utils/              # Utility functions
│   │   └─ sortList.ts
│   ├─ consts.ts           # Constants
│   ├─ index.ts            # Main export file
│   └─ vue-shim.d.ts       # Vue type declarations
├─ dist/                   # Build output (generated)
├─ package.json
├─ tsconfig.json
└─ vite.config.ts

Building

Build for Production

pnpm run build
# or
npm run build

This will:

• Compile TypeScript to JavaScript
• Bundle Vue components
• Generate both ES Modules (.js) and CommonJS (.cjs) formats
• Output to dist/ directory with preserved src/ structure

Build Output Structure

dist/
└─ src/
   ├─ index.js              # ES Module entry
   ├─ index.cjs             # CommonJS entry
   ├─ components/
   │   └─ ...
   └─ ...

Testing Locally

Option 1: Using pnpm link (Recommended)

1. In your plugin directory:

   pnpm link --global

2. In your test project:

   pnpm link --global itc-select-user-dropdown

3. Use in your project:

   <script setup>
   import { UserDropdown } from "itc-select-user-dropdown";
   // or
   import { UserDropdown } from "itc-select-user-dropdown/src/components/UserDropdown.vue";
   </script>

Option 2: Using File Path

1. In your test project's package.json:

   {
     "dependencies": {
       "itc-select-user-dropdown": "file:../path/to/quasar-package-starter-kit-plugins-select-user-dropdown"
     }
   }

2. Install:

   pnpm install

3. Use in your project:

   <script setup>
   import { UserDropdown } from "itc-select-user-dropdown";
   </script>

Unlinking After Local Development

When you're done with local development and want to switch back to the published version (or remove the link):

For Option 1 (pnpm/npm link):

1. In your test project, unlink the package:

   # For pnpm
   pnpm unlink --global itc-select-user-dropdown
   
   # For npm
   npm unlink itc-select-user-dropdown

2. Reinstall the package from npm (or your registry):

   pnpm install itc-select-user-dropdown
   # or
   npm install itc-select-user-dropdown

3. Optionally, unlink from global (in your plugin directory):

   # For pnpm
   pnpm unlink --global
   
   # For npm
   npm unlink -g

   Note: This step is optional. The global link can remain for future development sessions.

For Option 2 (File Path):

1. Remove the file path dependency from your test project's package.json:

   {
     "dependencies": {
       // Remove or comment out:
       // "itc-select-user-dropdown": "file:../path/to/quasar-package-starter-kit-plugins-select-user-dropdown"
     }
   }

2. Reinstall the package from npm:

   pnpm install itc-select-user-dropdown
   # or
   npm install itc-select-user-dropdown

Troubleshooting Unlinking

If you encounter issues after unlinking:

• Clear node_modules and reinstall:

  rm -rf node_modules
  pnpm install
  # or
  npm install

• Check for leftover symlinks:

  # Check if symlink still exists
  ls -la node_modules/itc-select-user-dropdown
  
  # If it's still a symlink, remove it manually
  rm node_modules/itc-select-user-dropdown
  pnpm install

• Verify package source:

  # Check where the package is coming from
  pnpm why itc-select-user-dropdown
  # or
  npm ls itc-select-user-dropdown

Development Workflow

For active development with auto-rebuild:

Run in watch mode:

pnpm run dev

Changes will rebuild automatically. Restart your test project's dev server to pick up changes.

Publishing to npm

Before Publishing

1. Update package.json:

   • Set correct name (must be unique on npm)
   • Update version (follow semver)
   • Add description, keywords, author, license
   • Verify files array includes only what should be published:

     {
       "files": ["dist", "README.md"]
     }

2. Build the package:

   pnpm run build

3. Test the build locally (see Testing Locally section above)

Publishing Steps

1. Login to npm:

   npm login

2. Verify you're logged in:

   npm whoami

3. Check what will be published:

   npm pack --dry-run

4. Publish:

   npm publish

   For scoped packages (e.g., @your-org/package-name):

   npm publish --access public

5. Verify on npm: Visit https://www.npmjs.com/package/itc-select-user-dropdown

Version Management

Use npm version commands to bump versions:

# Patch version (1.0.0 → 1.0.1)
npm version patch

# Minor version (1.0.0 → 1.1.0)
npm version minor

# Major version (1.0.0 → 2.0.0)
npm version major

Then publish:

npm publish

Configuration

External Dependencies

By default, vue and quasar are marked as external (not bundled). To add more:

Update vite.config.ts:

rollupOptions: {
  external: (id) => {
    return (
      id === "vue" ||
      id === "quasar" ||
      id.startsWith("@quasar/") ||
      id.startsWith("quasar/") ||
      id === "some-other-package"
    ); // Add here
  };
}

Build Formats

The template builds both ES Modules and CommonJS. To change formats:

Update vite.config.ts:

build: {
  lib: {
    formats: ["es", "cjs"]; // or ['es'], ['cjs'], etc.
  }
}

Troubleshooting

TypeScript Errors

• "Cannot find module 'src/...'": Restart TypeScript server
• "Cannot find module 'path'": Ensure @types/node is installed
• Path aliases not working: Check both tsconfig.json and vite.config.ts have matching aliases

Build Errors

• "Rollup failed to resolve import": Add the package to external in vite.config.ts
• "Preprocessor dependency not found": Install required preprocessors (e.g., sass-embedded for SCSS)

Import Errors in Test Project

• Ensure the package is built (pnpm run build)
• Check package.json exports are correct
• Verify the import path matches your exports

License

MIT

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Build and test locally
5. Submit a pull request

Happy coding! 🚀