Chamilo Vue Base Components

Review the Vue file(s) referenced in $ARGUMENTS (or the currently open file if no argument is given) and replace every native HTML form element with the appropriate Base* component from assets/vue/components/basecomponents/. Follow the mapping and rules below exactly.

⚠ Critical rule (read first): every component used in the template must be imported

In this project, Vue 3 with <script setup> does NOT auto-register most local components. A small set of components is registered globally in assets/vue/main.js (the app.component(...) calls) and must NOT be imported:

• PrimeVue (global): Dialog, ConfirmDialog, DataView, Dropdown (alias of Select), InputText, Button, Column, ColumnGroup, Toolbar.
• Base (global): BaseAppLink.

Everything else — BaseButton, BaseDialog, BaseSelect, BaseTable, BaseInputText, BaseInputNumber, BaseCheckbox, BaseCalendar, BaseAutocomplete, BaseMultiSelect, BaseRadioButtons, BaseColorPicker, BaseTextArea, BaseIcon, SectionHeader, Fieldset, etc. — MUST be imported explicitly in <script setup>.

Note: prefer the Base* wrapper over the raw PrimeVue global where one exists. Use BaseDialog (not the global Dialog), BaseSelect (not the global Dropdown), BaseInputText (not the global InputText), BaseButton (not the global Button). The PrimeVue globals exist mostly for legacy/transitional code and inside Base* wrappers. Column, ColumnGroup and Toolbar are the normal exceptions you use directly (inside BaseTable).

Why this rule exists: when a non-global component is missing its import, Vue 3 does NOT raise a build error. yarn build reports webpack compiled successfully even with missing imports. The failure surfaces only at runtime as [Vue warn]: Failed to resolve component: BaseDialog, and that warning does not show in CI. So you cannot rely on yarn build to catch this — you must cross-check by hand (or via the verification command at the end of this skill).

When you create a new Vue file or add a component tag to an existing one, the imports are part of the same change.

Standard import paths (note: from assets/vue/views/<feature>/Foo.vue the prefix is ../../; from assets/vue/views/<feature>/<sub>/Foo.vue it is ../../../):

// Most common Base* components
import BaseAutocomplete from "../../components/basecomponents/BaseAutocomplete.vue"
import BaseButton       from "../../components/basecomponents/BaseButton.vue"
import BaseCalendar     from "../../components/basecomponents/BaseCalendar.vue"
import BaseCheckbox     from "../../components/basecomponents/BaseCheckbox.vue"
import BaseColorPicker  from "../../components/basecomponents/BaseColorPicker.vue"
import BaseDialog       from "../../components/basecomponents/BaseDialog.vue"
import BaseIcon         from "../../components/basecomponents/BaseIcon.vue"
import BaseInputNumber  from "../../components/basecomponents/BaseInputNumber.vue"
import BaseInputText    from "../../components/basecomponents/BaseInputText.vue"
import BaseMultiSelect  from "../../components/basecomponents/BaseMultiSelect.vue"
import BaseRadioButtons from "../../components/basecomponents/BaseRadioButtons.vue"
import BaseSelect       from "../../components/basecomponents/BaseSelect.vue"
import BaseTable        from "../../components/basecomponents/BaseTable.vue"
import BaseTextArea     from "../../components/basecomponents/BaseTextArea.vue"

// Layout
import SectionHeader from "../../components/layout/SectionHeader.vue"

// PrimeVue Fieldset is NOT global — import it when used
import Fieldset from "primevue/fieldset"

Exceptions (do NOT import): the global components listed above — Dialog, ConfirmDialog, DataView, Dropdown, InputText, Button, Column, ColumnGroup, Toolbar, BaseAppLink. In practice the ones you'll legitimately use directly are Column / ColumnGroup / Toolbar (inside <BaseTable>).

Mapping: native element → Base* component

Remove the surrounding <div><label>…</label><input>…</div> wrapper — every Base* component renders its own label internally.

Critical rule: label translation

Components differ in whether they call t() internally:

Passing t('Key') to BaseTextArea will attempt to translate an already-translated string and break non-English locales.

Component APIs

BaseInputText

<BaseInputText
  id="field-id"
  v-model="form.title"
  :label="t('Title')"
  name="title"
/>

Props: id (required), label (required), modelValue (String|null, required), name, errorText, isInvalid, required, helpText, formSubmitted, disabled. Has inheritAttrs: false with v-bind="$attrs" on the inner input → extra attrs and events (@input, @blur, autocomplete, placeholder, etc.) are forwarded.

BaseTextArea

<BaseTextArea
  id="field-id"
  v-model="form.description"
  label="Description"
  name="description"
  rows="3"
/>

Props: id (required), label (required, raw key), modelValue (String, default ""), errorText, isInvalid. Extra attrs (rows, name, etc.) forwarded via v-bind="$attrs".

BaseInputNumber

<BaseInputNumber
  id="field-id"
  v-model="form.score"
  :label="t('Score')"
  :min="0"
  :step="0.1"
  name="score"
/>

Props: id (required), label (required), modelValue (Number, required), step (default 1), min, max, isInvalid, errorText, disabled, helpText. Renders PrimeVue InputNumber with +/− spinner buttons. name is NOT forwarded — no v-bind="$attrs" on this component.

BaseSelect

<BaseSelect
  id="field-id"
  v-model="form.status"
  :label="t('Status')"
  :options="statusOptions"
  name="status"
/>

Props: id, label (required), options (Array, required), optionLabel (default "label"), optionValue (default "value"), name, placeholder, allowClear, hastEmptyValue, isLoading, disabled, messageText, isInvalid. Uses defineModel — compatible with v-model.

Options format (default keys):

const statusOptions = [
  { label: t('Active'), value: 'active' },
  { label: t('Inactive'), value: 'inactive' },
]

Or pass :option-label="'title'" :option-value="'id'" to use existing object keys directly.

Properties with @ in the name (e.g. @id) are not safe as optionValue strings — map them to plain keys in a computed property first:

const compensationOptions = computed(() =>
  compensations.value.map((c) => ({ label: c.title, value: c['@id'] }))
)

Use allow-clear for optional filters (adds a clear/× button). Use :hast-empty-value="true" to prepend a -- row when the field is required with a blank default.

For large lists (dozens/hundreds of options) or nested lists, use BaseAutocomplete instead of BaseSelect — see the BaseAutocomplete section and the caching pattern with useEntityCache.

BaseCalendar

<BaseCalendar
  id="field-id"
  v-model="form.startDate"
  :label="t('Start date')"
/>

Props: id (required), label (required), type ("single" | "range", default "single"), showTime, isInvalid, errorText, showInline. Uses defineModel — type Date | Array | String | null.

⚠ Important:

• Initialise the model value as null or new Date(), never as "".
• The model holds a Date object after user interaction. Serialise with new Date(value).toISOString() before sending to the API.
• For string comparisons in computed filters, convert first:

  const dateStr = value instanceof Date ? value.toISOString().slice(0, 10) : String(value).slice(0, 10)

• After switching from <input type="date">, update resetFilters / initial form values to use null instead of "".

Date range — type="range": When a form has a start field and an end field, use a single BaseCalendar with type="range" instead of two separate calendars. The model is [startDate, endDate | null]:

<BaseCalendar
  id="date-range"
  v-model="dateRange"
  :label="t('Assignment period')"
  type="range"
/>

const dateRange = ref([new Date(), null])   // initialize with start = today, end = null

// When saving, extract by index:
const payload = {
  startDate: dateRange.value?.[0] ? new Date(dateRange.value[0]).toISOString() : null,
  endDate:   dateRange.value?.[1] ? new Date(dateRange.value[1]).toISOString() : null,
}

// When resetting:
dateRange.value = null   // or [new Date(), null] if you want to pre-fill the start

The second element is null until the user selects the end date — check dateRange.value?.[1] before serializing.

BaseCheckbox

<BaseCheckbox
  id="field-id"
  v-model="form.isActive"
  :label="t('Active')"
  name="is_active"
/>

Props: id (required), name (required), label (required). Uses defineModel (Boolean) — binary checkbox only. For multi-value checkbox arrays (e.g. selecting multiple IRIs), keep native <input type="checkbox"> with v-model array binding.

BaseRadioButtons

<BaseRadioButtons
  v-model="form.type"
  :options="typeOptions"
  :title="t('Type')"
  name="type"
/>

Props: modelValue (String|Number, required), name (required), options (Array { label, value }, required), title (optional heading). Uses traditional emit pattern (not defineModel) — v-model works as expected. Translate option labels in the computed/data, not inside the component:

const typeOptions = computed(() => [
  { label: t('Internal'), value: 'internal' },
  { label: t('External'), value: 'external' },
])

BaseMultiSelect

<BaseMultiSelect
  v-model="form.tags"
  :options="tagOptions"
  :label="t('Tags')"
  input-id="field-id"
  option-label="title"
  option-value="id"
/>

Props: modelValue (Array, required), options (Array), inputId (required — note: inputId not id), label (required), optionLabel (default "name"), optionValue (default "id"), isInvalid, errorText, isLoading. Renders chips for selected values.

BaseAutocomplete

<BaseAutocomplete
  id="field-id"
  v-model="form.user"
  :label="t('User')"
  :search="searchUsers"
  option-label="fullName"
/>

Props: id (required), label (required), search (Function, required), optionLabel (default "name"), isMultiple, disabled, helpText, isInvalid.

When to use BaseAutocomplete instead of BaseSelect:

• The list has dozens or hundreds of items — a <select> becomes unwieldy.
• The source is a paginated endpoint or has no known upper bound (e.g. /api/users).
• The list is nested (e.g. skill tree) and the user needs to search by text.

For short and fixed lists (≤ ~20 items, e.g. statuses, periodicities, types), keep using BaseSelect.

The search prop receives the query and returns a Promise with the array of suggestions. There are two patterns depending on the dataset size:

1) Server-side search — large or paginated datasets:

async function searchUsers(query) {
  const result = await baseService.getCollection('/api/users', { search: query, itemsPerPage: 10 })
  return result.items
}

2) In-memory cached search — useEntityCache (assets/vue/composables/useEntityCache.js):

Factory with a module-level Map. Caches the list by endpoint for the whole session — multiple views / multiple autocomplete instances share a single request.

import { useEntityCache } from "../../composables/useEntityCache"

const skillsCache = useEntityCache("/api/skills", { pagination: false })

onMounted(async () => {
  await skillsCache.load()   // loads once per session
})

<BaseAutocomplete
  id="skill-ref"
  v-model="selectedSkill"
  :label="t('Skill')"
  :search="skillsCache.search"
  option-label="title"
/>

Cache API:

• load() — lazy-loads once; deduplicates concurrent calls; subsequent calls return the already cached items.
• search(query) — filters in-memory by the labelField (3rd argument of the factory, default "title"). Pass as the search prop.
• findById(id) — resolves a numeric id to the object. Useful in edit mode when the backend sends only the id.
• invalidate() — clears the cache. Call it after creating/editing/deleting the entity to force a reload.

When the v-model must be sent as an id (not an IRI nor an object) — BaseAutocomplete keeps the full object in the model; on save extract .id, and on load (edit) resolve id → object with findById:

// addItem
form.items.push({ ref: null })

// load (edit mode)
items: backendItems.map((i) => ({ ref: skillsCache.findById(i.refId) }))

// save payload
items: form.items.filter((i) => i.ref?.id).map((i) => ({ refId: Number(i.ref.id) }))

Backend — enable pagination=false when using the cache: entities whose ApiResource does not declare paginationClientEnabled: true will silently ignore the client's pagination: false and return only 30 items. Verify the entity attribute before caching full lists.

Always use BaseAutocomplete instead of the manual <BaseInputText> + <ul> pattern. When you see this pattern in a Vue file, replace it:

<!-- ❌ manual pattern to replace -->
<div class="relative">
  <BaseInputText v-model="userSearch" @input="onUserInput" ... />
  <ul v-if="results.length" class="absolute ...">
    <li v-for="u in results" @click="selectUser(u)">{{ u.fullName }}</li>
  </ul>
</div>
<p v-if="selectedUser">{{ selectedUser.fullName }}</p>

<!-- ✅ use BaseAutocomplete -->
<BaseAutocomplete
  id="field-id"
  v-model="selectedUser"
  :label="t('User')"
  :search="searchUsers"
  option-label="fullName"
/>

Note: this project also ships BaseUserFinder and BaseSearchSelect for some user/entity pickers. If the file already uses one of them, keep it; for new generic autocompletes prefer BaseAutocomplete.

When the v-model must be an IRI (not the full object), keep a separate ref for the autocomplete and extract the IRI when building the payload:

const selectedUser = ref(null)

// in save():
const payload = { user: selectedUser.value?.["@id"] ?? null }

When clearing or resetting, simply assign null:

function resetForm() {
  selectedUser.value = null
}

Also remove: the text refs (userSearch), the suggestion refs (userSearchResults), the debounce timers, and the onUserInput, selectUser, clearUser functions.

BaseColorPicker

<BaseColorPicker
  v-model="form.color"
  :label="t('Color')"
/>

Props: modelValue (Color instance from colorjs.io, required), label (no internal t() — use :label="t('...')"), error.

⚠ Important: The model value must be a Color object from colorjs.io, never a plain string. Three places in the script always need updating together:

import Color from 'colorjs.io'

// 1. Initial state (ref declaration)
const form = ref({ color: new Color('#3B82F6') })

// 2. Loading existing data (e.g. openForm(item))
form.value.color = item ? new Color(item.color) : new Color('#3B82F6')

// 3. Serialising for the API (save payload)
const payload = {
  color: form.value.color.toString({ format: 'hex' }),
}

colorjs.io is already a project dependency — no installation needed.

BaseDialog

<BaseDialog
  v-model:is-visible="myDialog"
  :title="editingItem ? t('Edit item') : t('Add item')"
  :style="{ width: '480px' }"
>
  <!-- form fields -->
  <template #footer>
    <BaseButton :label="t('Cancel')" icon="close" type="plain" @click="myDialog = false" />
    <BaseButton :label="t('Save')" icon="save" type="success" @click="save" />
  </template>
</BaseDialog>

Props: title (String, required), headerIcon (String, optional — MDI icon name). Model: isVisible (Boolean) — bind with v-model:is-visible. Always use <BaseDialog> instead of PrimeVue <Dialog> directly (even though Dialog is globally registered). It wraps Dialog with modal: true and a consistent header layout.

• Extra attrs (e.g. :style, :class) fall through to the inner <Dialog> — use :style="{ width: '...' }" to control dialog width.
• Footer goes in the #footer named slot.
• Never import Dialog from primevue/dialog in a view — use BaseDialog instead.
• For simple confirm/cancel or delete dialogs, BaseDialogConfirmCancel and BaseDialogDelete already exist — prefer them over hand-rolling a BaseDialog with two buttons.