@omnitend/dashboard-for-laravel 0.9.2 → 0.11.0

package/resources/js/components/extended/DXField.vue

@@ -1,6 +1,17 @@
+<!--
+  @component
+  Renders a single `FieldDefinition` of any type (text, select, checkbox, switch, repeater, currency, percentage, file/image, component, etc.) with its label, validation error, hint and help. Used by `DXForm` and `DXTable`'s edit modal; exposes `value`, `span`, `info`, `hint` and `repeater-row` slots for per-field customisation.
+-->
 <template>
     <!-- Full-width span field: delegate entirely to the #span slot -->
     <div v-if="field.span" :class="field.class || 'mb-3'">
+        <!--
+          @slot Replaces the entire field with custom full-width content when `field.span` is set, bypassing the label and built-in control.
+          @binding {FieldDefinition} field The field definition being rendered.
+          @binding {any} model The model passed to field predicates (defaults to the live form data).
+          @binding {any} value The current field value.
+          @binding {(value: any) => void} update Setter that writes the value back and clears the field's validation error.
+        -->
         <slot
             name="span"
             :field="field"
@@ -12,6 +23,13 @@
 
     <!-- Checkbox: no label wrapper, label sits beside the control -->
     <div v-else-if="field.type === 'checkbox'" :class="field.class || 'mb-3'">
+        <!--
+          @slot Replaces the built-in control with a custom value editor.
+          @binding {FieldDefinition} field The field definition being rendered.
+          @binding {any} model The model passed to field predicates (defaults to the live form data).
+          @binding {any} value The current field value.
+          @binding {(value: any) => void} update Setter that writes the value back and clears the field's validation error.
+        -->
         <slot
             v-if="$slots.value"
             name="value"
@@ -32,8 +50,18 @@
         <DFormInvalidFeedback v-if="form.hasError(errorKey)" force-show>
             {{ form.getError(errorKey) }}
         </DFormInvalidFeedback>
+        <!--
+          @slot Rich info block rendered below the control.
+          @binding {FieldDefinition} field The field definition being rendered.
+          @binding {any} model The model passed to field predicates (defaults to the live form data).
+        -->
         <slot name="info" :field="field" :model="model" />
         <DFormText v-if="resolvedHint || $slots.hint" class="text-muted">
+            <!--
+              @slot Overrides the field's hint text shown below the control.
+              @binding {FieldDefinition} field The field definition being rendered.
+              @binding {any} model The model passed to field predicates (defaults to the live form data).
+            -->
             <slot name="hint" :field="field" :model="model">{{ resolvedHint }}</slot>
         </DFormText>
         <DFormText v-if="field.help">{{ field.help }}</DFormText>
@@ -44,6 +72,13 @@
         v-else-if="field.type === 'switch'"
         :class="[field.class || 'mb-3', 'dx-switch', { 'dx-switch--on': switchIsOn }]"
     >
+        <!--
+          @slot Replaces the built-in control with a custom value editor.
+          @binding {FieldDefinition} field The field definition being rendered.
+          @binding {any} model The model passed to field predicates (defaults to the live form data).
+          @binding {any} value The current field value.
+          @binding {(value: any) => void} update Setter that writes the value back and clears the field's validation error.
+        -->
         <slot
             v-if="$slots.value"
             name="value"
@@ -65,8 +100,18 @@
         <DFormInvalidFeedback v-if="form.hasError(errorKey)" force-show>
             {{ form.getError(errorKey) }}
         </DFormInvalidFeedback>
+        <!--
+          @slot Rich info block rendered below the control.
+          @binding {FieldDefinition} field The field definition being rendered.
+          @binding {any} model The model passed to field predicates (defaults to the live form data).
+        -->
         <slot name="info" :field="field" :model="model" />
         <DFormText v-if="resolvedHint || $slots.hint" class="text-muted">
+            <!--
+              @slot Overrides the field's hint text shown below the control.
+              @binding {FieldDefinition} field The field definition being rendered.
+              @binding {any} model The model passed to field predicates (defaults to the live form data).
+            -->
             <slot name="hint" :field="field" :model="model">{{ resolvedHint }}</slot>
         </DFormText>
         <DFormText v-if="field.help">{{ field.help }}</DFormText>
@@ -86,12 +131,23 @@
             >
                 <!-- Forward repeater row slot for custom row layouts -->
                 <template v-if="$slots['repeater-row']" #row="rowProps">
+                    <!-- @slot Custom layout for a single repeater row, forwarded to `DXRepeater`'s `row` slot with its row props (row index, item, remove handler, etc.). -->
                     <slot name="repeater-row" v-bind="rowProps" />
                 </template>
             </DXRepeater>
         </DFormGroup>
+        <!--
+          @slot Rich info block rendered below the control.
+          @binding {FieldDefinition} field The field definition being rendered.
+          @binding {any} model The model passed to field predicates (defaults to the live form data).
+        -->
         <slot name="info" :field="field" :model="model" />
         <DFormText v-if="resolvedHint || $slots.hint" class="text-muted">
+            <!--
+              @slot Overrides the field's hint text shown below the control.
+              @binding {FieldDefinition} field The field definition being rendered.
+              @binding {any} model The model passed to field predicates (defaults to the live form data).
+            -->
             <slot name="hint" :field="field" :model="model">{{ resolvedHint }}</slot>
         </DFormText>
         <DFormText v-if="field.help">{{ field.help }}</DFormText>
@@ -105,6 +161,13 @@
         </template>
 
         <!-- Custom value slot overrides the built-in control -->
+        <!--
+          @slot Replaces the built-in control with a custom value editor.
+          @binding {FieldDefinition} field The field definition being rendered.
+          @binding {any} model The model passed to field predicates (defaults to the live form data).
+          @binding {any} value The current field value.
+          @binding {(value: any) => void} update Setter that writes the value back and clears the field's validation error.
+        -->
         <slot
             v-if="$slots.value"
             name="value"
@@ -224,10 +287,20 @@
         </DFormInvalidFeedback>
 
         <!-- Optional rich info block -->
+        <!--
+          @slot Rich info block rendered below the control.
+          @binding {FieldDefinition} field The field definition being rendered.
+          @binding {any} model The model passed to field predicates (defaults to the live form data).
+        -->
         <slot name="info" :field="field" :model="model" />
 
         <!-- Hint (dynamic, slot-overridable) -->
         <DFormText v-if="resolvedHint || $slots.hint" class="text-muted">
+            <!--
+              @slot Overrides the field's hint text shown below the control.
+              @binding {FieldDefinition} field The field definition being rendered.
+              @binding {any} model The model passed to field predicates (defaults to the live form data).
+            -->
             <slot name="hint" :field="field" :model="model">{{ resolvedHint }}</slot>
         </DFormText>
 

package/resources/js/components/extended/DXFieldLabel.vue

@@ -1,3 +1,8 @@
+<!--
+  @component
+  A form field label with an optional info affordance that reveals help text
+  in a hover/focus popover next to the label.
+-->
 <template>
     <span class="dx-field-label">
         <span class="dx-field-label__text">{{ label }}</span>

package/resources/js/components/extended/DXForm.vue

@@ -33,7 +33,11 @@
                 :lazy="tab.lazy"
                 :active="index === 0"
             >
-                <!-- Replace the entire tab body -->
+                <!--
+                  @slot Replaces the entire body of a tab, keyed by tab (slot name `tab-content(<tabKey>)`).
+                  @binding {FormTab} tab The tab definition being rendered.
+                  @binding {object} model Live form data merged with `context`, for predicates.
+                -->
                 <slot
                     v-if="$slots[`tab-content(${tab.key})`]"
                     :name="`tab-content(${tab.key})`"
@@ -42,6 +46,11 @@
                 />
 
                 <div v-else class="pt-3">
+                    <!--
+                      @slot Content inserted above a tab's fields, keyed by tab (slot name `tab-before(<tabKey>)`).
+                      @binding {FormTab} tab The tab definition being rendered.
+                      @binding {object} model Live form data merged with `context`, for predicates.
+                    -->
                     <slot :name="`tab-before(${tab.key})`" :tab="tab" :model="model" />
 
                     <DXField
@@ -56,10 +65,16 @@
                             :key="target"
                             #[target]="slotProps"
                         >
+                            <!-- @slot Per-field overrides forwarded to DXField, keyed by field key: `value(<key>)`, `span(<key>)`, `info(<key>)`, `hint(<key>)`, `repeater-row(<key>)`. -->
                             <slot :name="slotName" v-bind="slotProps" />
                         </template>
                     </DXField>
 
+                    <!--
+                      @slot Content inserted below a tab's fields, keyed by tab (slot name `tab-after(<tabKey>)`).
+                      @binding {FormTab} tab The tab definition being rendered.
+                      @binding {object} model Live form data merged with `context`, for predicates.
+                    -->
                     <slot :name="`tab-after(${tab.key})`" :tab="tab" :model="model" />
                 </div>
             </DTab>
@@ -79,6 +94,7 @@
                     :key="target"
                     #[target]="slotProps"
                 >
+                    <!-- @slot Per-field overrides forwarded to DXField, keyed by field key: `value(<key>)`, `span(<key>)`, `info(<key>)`, `hint(<key>)`, `repeater-row(<key>)`. -->
                     <slot :name="slotName" v-bind="slotProps" />
                 </template>
             </DXField>
@@ -96,6 +112,10 @@
             <span v-else>{{ submitText }}</span>
         </DButton>
 
+        <!--
+          @slot Content rendered below the submit button (e.g. a cancel link or secondary actions).
+          @binding {UseFormReturn} form The resolved form instance (state, errors, submit helpers).
+        -->
         <slot name="footer" :form="resolvedForm" />
     </BForm>
 </template>
@@ -154,6 +174,7 @@ const props = withDefaults(defineProps<Props>(), {
 });
 
 const emit = defineEmits<{
+    /** Emitted when the form is submitted, after the native submit is prevented. */
     submit: [];
 }>();
 

package/resources/js/components/extended/DXRepeater.vue

@@ -1,3 +1,9 @@
+<!--
+  @component
+  DXRepeater renders a nested, repeatable sub-form for a repeater field: a list
+  of rows (each a group of sub-fields) with add/remove controls, honouring the
+  field's `minItems`/`maxItems` limits.
+-->
 <template>
     <div class="dx-repeater">
         <div
@@ -5,7 +11,14 @@
             :key="rowKey(index)"
             class="dx-repeater-row"
         >
-            <!-- Custom row layout escape hatch -->
+            <!--
+              @slot Custom layout for a single repeater row, replacing the default sub-field stack.
+              @binding {object} row The current row's data object.
+              @binding {number} index The row's zero-based index.
+              @binding {FieldDefinition[]} fields The sub-field definitions for the row.
+              @binding {function} remove Removes this row (respects `minItems`).
+              @binding {string} path The dot path into `form.data` for this row (e.g. `lines.0`).
+            -->
             <slot
                 v-if="$slots.row"
                 name="row"

package/resources/js/components/extended/DXTable.vue

@@ -1,9 +1,17 @@
+<!--
+  @component
+  Full-featured dashboard data table. Wraps `DTable` and adds three data modes
+  (Inertia items, client-side, and API/provider), inline per-column filters,
+  single-column sorting, pagination with a per-page selector, and an optional
+  edit/create/delete modal driven by `DXForm`.
+-->
 <template>
     <DContainer :fluid="fluid" :class="containerClass">
         <DRow class="justify-content-center">
             <DCol :md="columnSize">
                 <DCard>
                     <template v-if="title || createUrl || $slots.header" #header>
+                        <!-- @slot Card header content; overrides the default title heading and the "New {item}" button. -->
                         <slot name="header">
                             <div class="d-flex justify-content-between align-items-center">
                                 <h4 class="mb-0">{{ title }}</h4>
@@ -114,6 +122,13 @@
                             v-for="(_, name) in $slots"
                             #[name]="slotProps"
                         >
+                            <!--
+                              @slot Custom rendering for a column's cell. Name it `cell(<fieldKey>)` to target a field; receives the underlying table cell scope.
+                              @binding {object} item The row data object for this cell.
+                              @binding {any} value The cell value for the field.
+                              @binding {number} index The zero-based row index.
+                              @binding {object} field The field definition for the column.
+                            -->
                             <slot
                                 v-if="typeof name === 'string' && name.startsWith('cell')"
                                 :name="name"
@@ -203,6 +218,13 @@
                             v-for="(_, name) in $slots"
                             #[name]="slotProps"
                         >
+                            <!--
+                              @slot Custom rendering for a column's cell. Name it `cell(<fieldKey>)` to target a field; receives the underlying table cell scope.
+                              @binding {object} item The row data object for this cell.
+                              @binding {any} value The cell value for the field.
+                              @binding {number} index The zero-based row index.
+                              @binding {object} field The field definition for the column.
+                            -->
                             <slot
                                 v-if="typeof name === 'string' && name.startsWith('cell')"
                                 :name="name"
@@ -293,6 +315,13 @@
                             v-for="(_, name) in $slots"
                             #[name]="slotProps"
                         >
+                            <!--
+                              @slot Custom rendering for a column's cell. Name it `cell(<fieldKey>)` to target a field; receives the underlying table cell scope.
+                              @binding {object} item The row data object for this cell.
+                              @binding {any} value The cell value for the field.
+                              @binding {number} index The zero-based row index.
+                              @binding {object} field The field definition for the column.
+                            -->
                             <slot
                                 v-if="typeof name === 'string' && name.startsWith('cell')"
                                 :name="name"
@@ -472,6 +501,13 @@
                     :key="`ev-${key}`"
                     #[`value(${key})`]="sp"
                 >
+                    <!--
+                      @slot Custom input for field `<key>` in the edit/create modal, forwarded to DXForm. Name it `edit-value(<fieldKey>)`.
+                      @binding {object} item The row being edited (null in create mode).
+                      @binding {any} value The current field value.
+                      @binding {Function} update Call with a new value to update the field.
+                      @binding {object} field The field definition.
+                    -->
                     <slot
                         :name="`edit-value(${key})`"
                         :item="selectedItem"
@@ -487,6 +523,13 @@
                     :key="`es-${key}`"
                     #[`span(${key})`]="sp"
                 >
+                    <!--
+                      @slot Full-width custom content for field `<key>` in the edit/create modal, forwarded to DXForm's span slot. Name it `edit-span(<fieldKey>)`.
+                      @binding {object} item The row being edited (null in create mode).
+                      @binding {any} value The current field value.
+                      @binding {Function} update Call with a new value to update the field.
+                      @binding {Function} close Call to close the edit modal.
+                    -->
                     <slot
                         :name="`edit-span(${key})`"
                         :item="selectedItem"
@@ -502,6 +545,11 @@
                     :key="`tc-${key}`"
                     #[`tab-content(${key})`]="sp"
                 >
+                    <!--
+                      @slot Replaces the auto-rendered fields of edit-modal tab `<key>` with custom content. Name it `tab-content(<tabKey>)`.
+                      @binding {object} item The row being edited (null in create mode).
+                      @binding {object} tab The tab definition.
+                    -->
                     <slot :name="`tab-content(${key})`" :item="selectedItem" :tab="sp.tab" />
                 </template>
                 <template
@@ -509,6 +557,11 @@
                     :key="`tb-${key}`"
                     #[`tab-before(${key})`]="sp"
                 >
+                    <!--
+                      @slot Custom content rendered before the fields of edit-modal tab `<key>`. Name it `tab-before(<tabKey>)`.
+                      @binding {object} item The row being edited (null in create mode).
+                      @binding {object} tab The tab definition.
+                    -->
                     <slot :name="`tab-before(${key})`" :item="selectedItem" :tab="sp.tab" />
                 </template>
                 <template
@@ -516,6 +569,11 @@
                     :key="`taf-${key}`"
                     #[`tab-after(${key})`]="sp"
                 >
+                    <!--
+                      @slot Custom content rendered after the fields of edit-modal tab `<key>`. Name it `tab-after(<tabKey>)`.
+                      @binding {object} item The row being edited (null in create mode).
+                      @binding {object} tab The tab definition.
+                    -->
                     <slot :name="`tab-after(${key})`" :item="selectedItem" :tab="sp.tab" />
                 </template>
             </DXForm>
@@ -736,6 +794,16 @@ export interface Props<TItem = any> {
     /** API endpoint pattern for deletions (e.g., "/api/products/:id") */
     deleteUrl?: string;
 
+    /**
+     * Guard run when Delete is clicked, before the confirm dialog and request.
+     * Return a message for a non-deletable item to show it immediately (as a
+     * toast) and skip both the confirm and the delete request; return
+     * `null`/`undefined` to proceed with the normal confirm + delete. Lets you
+     * short-circuit a doomed delete (e.g. a record with dependents that the
+     * server would reject) with an immediate, specific reason.
+     */
+    deleteGuard?: (item: TItem) => string | null | undefined;
+
     /** API endpoint for creating new items (e.g., "/api/products") — enables "New" button */
     createUrl?: string;
 
@@ -771,20 +839,35 @@ const props = withDefaults(defineProps<Props<T>>(), {
 });
 
 const emit = defineEmits<{
+    /** Emitted when the user navigates to a different page (all modes). Payload is the new 1-based page number. */
     pageChange: [page: number];
+    /** Emitted (Inertia mode) when the sort column or direction changes, with the active field key and order. */
     sortChange: [sort: { key: string; order: 'asc' | 'desc' }];
+    /** Emitted when the inline column filter values change (debounced for server modes, immediate for client-side). Payload is the full filter map. */
     filterChange: [filters: Record<string, string>];
+    /** Emitted when the per-page selector value changes. Payload is the new page size. */
     perPageChange: [perPage: number];
+    /** Emitted when a table row is clicked, with the row item, its index, and the click event. */
     rowClicked: [item: T, index: number, event: MouseEvent];
+    /** Emitted after a new item is successfully created via `createUrl`, with the created item and the raw response. */
     rowCreated: [item: any, response: any];
+    /** Emitted when a create request fails, with the validation errors or error object. */
     createError: [error: any];
+    /** Emitted after a row is successfully updated (or, with no `editUrl`, when the modal is saved), with the item and the response/form data. */
     rowUpdated: [item: T, response: any];
+    /** Emitted when an update request fails, with the edited item and the error. */
     editError: [item: T, error: any];
+    /** Emitted after a row is successfully deleted via `deleteUrl`, with the deleted item and the response. */
     rowDeleted: [item: T, response: any];
+    /** Emitted when a delete request fails, with the item and the error. */
     deleteError: [item: T, error: any];
+    /** `v-model:sortBy` update, emitted with the normalized single-column sort array when sorting changes. */
     'update:sortBy': [sortBy: BTableSortBy[]];
+    /** `v-model:filters` update, emitted with the new filter map when a column filter changes. */
     'update:filters': [filters: Record<string, string>];
+    /** `v-model:perPage` update, emitted with the new page size when the per-page selector changes. */
     'update:perPage': [perPage: number];
+    /** `v-model:busy` update, forwarded from the underlying table's provider loading state (provider mode). */
     'update:busy': [busy: boolean];
 }>();
 
@@ -1660,6 +1743,19 @@ const handleEditCancel = () => {
 const handleDelete = async () => {
     if (!editForm.value || !selectedItem.value || !props.deleteUrl) return;
 
+    // Delete guard: a non-null message means this item can't be deleted — show
+    // it immediately and skip the confirm and the request entirely.
+    const guardMessage = props.deleteGuard?.(selectedItem.value as T);
+    if (guardMessage) {
+        createToast?.({
+            title: 'Cannot delete',
+            body: guardMessage,
+            variant: 'danger',
+            modelValue: 5000,
+        });
+        return;
+    }
+
     // Confirm deletion
     const itemName = (selectedItem.value as any).name || (selectedItem.value as any).title || singularItemName.value;
     const confirmed = window.confirm(`Are you sure you want to delete "${itemName}"? This action cannot be undone.`);
@@ -1713,6 +1809,12 @@ const handleDelete = async () => {
 
 defineExpose({
     refresh,
+    /**
+     * Open the built-in create modal (same as clicking the default "New {item}"
+     * button). Lets the create action live outside the table card — e.g. in a
+     * page header or the dashboard navbar. No-op unless `editFields` are set.
+     */
+    openCreate: handleCreateNew,
 });
 </script>
 

package/resources/js/types/navigation.ts

@@ -10,6 +10,13 @@ export interface NavigationItem {
 
 export interface NavigationGroup {
   label?: string;
+  /**
+   * Stable identifier for the group's collapsible open/closed state. Defaults
+   * to `label` (then the array index). Set this when a menu can be reordered at
+   * runtime, or two groups share a label, so a manually-opened group keeps its
+   * state attached to the right group.
+   */
+  key?: string;
   items: NavigationItem[];
   /**
    * Per-group override for the sidebar's `collapsibleGroups` behaviour.