@omnitend/dashboard-for-laravel 0.45.0 → 0.47.0

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

@@ -47,7 +47,7 @@
                         v-else-if="isProviderMode || isClientSideMode || isInertiaMode"
                         ref="tableRef"
                         :key="activeMode + ':' + tableSlotSignature($slots)"
-                        :fields="fields"
+                        :fields="renderedFields"
                         :sort-by="effectiveSortBy"
                         :multisort="false"
                         :no-sortable-icon="true"
@@ -245,8 +245,10 @@
                          PaginationData; `handleActivePageChange` routes the page
                          event to the right per-mode handler. Previously three
                          byte-identical copies, one per mode. -->
+                    <!-- Not while the loader shows: the count would read "0 items"
+                         before the rows have arrived. -->
                     <DXTablePagination
-                        v-if="activePagination"
+                        v-if="activePagination && !(effectiveBusy && !isProviderMode)"
                         :pagination="activePagination"
                         :per-page="effectivePerPage"
                         :per-page-options="perPageOptions"
@@ -264,7 +266,8 @@
         </DRow>
 
         <!-- Edit/create modal (only when editFields provided). The consumer's
-             edit-value / edit-span / tab-* slots are forwarded through to it
+             edit-value / edit-span / edit-password-actions / tab-* slots are
+             forwarded through to it
              generically; it maps them onto DXForm and provides the row context
              + a close handle (#129). -->
         <DXTableEditorModal
@@ -297,6 +300,7 @@
         >
             <!--
               @slot edit-value(<fieldKey>) / edit-span(<fieldKey>) /
+              edit-password-actions(<fieldKey>) /
               tab-content|tab-before|tab-after(<tabKey>) — forwarded to the edit
               modal (see DXTableEditorModal for their bindings).
             -->
@@ -340,7 +344,8 @@ import DXTableEditorModal from "./DXTableEditorModal.vue";
 export type FilterType = 'text' | 'select' | 'select-native' | 'number' | 'date' | false;
 
 export interface FilterOption {
-    value: string;
+    /** Numbers and booleans are accepted and compared as their string form. */
+    value: string | number | boolean | null;
     text: string;
 }
 
@@ -449,6 +454,15 @@ export interface TableField {
      * A number is pixels; a string is used verbatim.
      */
     minWidth?: string | number;
+
+    /**
+     * Render this column's figures tabular (every digit the same width), so
+     * amounts line up down the column: adds the global `.dx-tabular` class to
+     * the column's body cells and its header cell. Composes with the field's
+     * own `tdClass`/`thClass` (string, array, object or `tdClass` function)
+     * rather than replacing them. Default `false`.
+     */
+    tabular?: boolean;
     [key: string]: any;
 }
 
@@ -1379,6 +1393,35 @@ const columnStyleFor = (field: TableField): Record<string, string> | undefined =
 // content-sized default byte-for-byte.
 const fieldsHaveWidths = computed(() => props.fields.some(hasDeclaredWidth));
 
+/*
+ * Tabular columns (#215). A `tabular: true` field gets `.dx-tabular` added
+ * to its `tdClass` and `thClass`, appended to the consumer's own value
+ * (wrapped in an array, or called through when `tdClass` is a function) so
+ * their classes survive. Fields without the flag pass through as the same
+ * objects, so a table using no tabular column renders exactly as before.
+ */
+const TABULAR_CLASS = 'dx-tabular';
+
+const withTabularClass = (consumerClass: unknown): unknown[] =>
+    consumerClass === undefined || consumerClass === null
+        ? [TABULAR_CLASS]
+        : [consumerClass, TABULAR_CLASS];
+
+const renderedFields = computed<TableField[]>(() =>
+    props.fields.map((field) => {
+        if (field.tabular !== true) return field;
+        const consumerTdClass = field.tdClass;
+        return {
+            ...field,
+            tdClass:
+                typeof consumerTdClass === 'function'
+                    ? (...args: unknown[]) => withTabularClass(consumerTdClass(...args))
+                    : withTabularClass(consumerTdClass),
+            thClass: withTabularClass(field.thClass),
+        };
+    }),
+);
+
 // Computed: Get effective filter options for a field
 // The key a column's filter is SENT under, which is not always the column's own
 // key: a display column can filter on a different server param via `filterKey`.
@@ -1579,9 +1622,21 @@ const getFieldFilterOptions = (field: TableField): FilterOption[] => {
         options.push({ value: filterNullValueFor(field), text: field.filterNullText });
     }
 
-    // If field has static filterOptions, use those
+    // If field has static filterOptions, use those. Their values are
+    // stringified: options built from records carry numbers (ids) and booleans
+    // (flags), but the filter map, the URL and the row match all speak strings,
+    // and DAutocomplete matches its model to an option by strict equality — so a
+    // raw `1` never re-selected the stored `'1'`, and picking it put a number in
+    // the map that the active-filter check could not `.trim()`.
     if (field.filterOptions && field.filterOptions.length > 0) {
-        return [...options, ...field.filterOptions];
+        return [
+            ...options,
+            ...field.filterOptions.map((option) =>
+                option.value === null || option.value === undefined
+                    ? option
+                    : { ...option, value: String(option.value) },
+            ),
+        ];
     }
 
     // Otherwise, check for server-provided values (keyed by the filter key)
@@ -2461,6 +2516,7 @@ const handleDelete = editor.remove;
 const EDIT_MODAL_SLOT_PREFIXES = [
     'edit-value(',
     'edit-span(',
+    'edit-password-actions(',
     'tab-content(',
     'tab-before(',
     'tab-after(',

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

@@ -1,8 +1,8 @@
 <!--
   @component
   Internal edit/create modal for `DXTable` (#129). Renders the `DModal` +
-  `DXForm` and maps DXTable's `edit-value`/`edit-span`/`tab-*` slots onto
-  DXForm's `value`/`span`/`tab-*` slots, providing the row context and a `close`
+  `DXForm` and maps DXTable's `edit-value`/`edit-span`/`edit-password-actions`/
+  `tab-*` slots onto DXForm's `value`/`span`/`password-actions`/`tab-*` slots, providing the row context and a `close`
   handle. Extracted so `DXTable` is a thin façade over the table render, the
   pagination, the editor logic (`useResourceEditor`) and this modal — rather than
   owning all four.
@@ -115,6 +115,36 @@
                     />
                 </template>
 
+                <!-- Forward edit-password-actions(key) → password-actions(key):
+                     content beside the password input, inside its input group,
+                     with a handle on dfl's own reveal (eye) state. -->
+                <template
+                    v-for="key in editPasswordActionsSlotKeys"
+                    :key="`epa-${key}`"
+                    #[`password-actions(${key})`]="sp"
+                >
+                    <!--
+                      @slot Extra controls beside password field `<key>`'s input in the edit/create modal, inside its input group after the reveal (eye) toggle — e.g. a "Generate password" button. Name it `edit-password-actions(<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 {boolean} revealed Whether the password is currently shown as plain text.
+                      @binding {Function} setRevealed Call with true to show the password (as the eye does) or false to mask it.
+                      @binding {boolean} disabled Whether the field is disabled or read-only.
+                      @binding {object} field The field definition.
+                    -->
+                    <slot
+                        :name="`edit-password-actions(${key})`"
+                        :item="item"
+                        :value="sp.value"
+                        :update="sp.update"
+                        :revealed="sp.revealed"
+                        :set-revealed="sp.setRevealed"
+                        :disabled="sp.disabled"
+                        :field="sp.field"
+                    />
+                </template>
+
                 <!-- Forward tab-content / tab-before / tab-after slots -->
                 <template
                     v-for="key in tabContentSlotKeys"
@@ -318,6 +348,9 @@ const editValueSlotKeys = computed(() =>
 const editSpanSlotKeys = computed(() =>
     fieldKeys.value.filter((key) => !!slots[`edit-span(${key})`]),
 );
+const editPasswordActionsSlotKeys = computed(() =>
+    fieldKeys.value.filter((key) => !!slots[`edit-password-actions(${key})`]),
+);
 const tabContentSlotKeys = computed(() =>
     tabKeys.value.filter((key) => !!slots[`tab-content(${key})`]),
 );

package/resources/js/composables/useResourceEditor.ts

@@ -7,6 +7,7 @@ import {
     resolveFieldDefault,
     isFieldVisible as isFieldVisibleFor,
     isSubmittableField,
+    nonSubmittedFieldKeys as nonSubmittedFieldKeysFor,
 } from "../utils/formSchema";
 
 /**
@@ -207,24 +208,67 @@ export function useResourceEditor<T = any>(
     // Enforced at SUBMIT, not just at seeding: the modal still renders every field,
     // so a `submit: false` control — or a `span` slot calling `update` — can write
     // its key back into the form data after seeding. Strip them on the way out.
-    const nonSubmittedFieldKeys = computed(
-        () =>
-            new Set(
-                (props.editFields ?? [])
-                    .filter(
-                        (field) =>
-                            // Presentational: lays the form out, holds no data (#110).
-                            !isSubmittableField(field) ||
-                            // Hidden by `when` at submit time (#117). Submitting a field
-                            // the user cannot see is a silent write — and with `default`
-                            // set it writes a value they never chose. Omitting the key
-                            // leaves the stored value alone.
-                            !isEditFieldVisible(field),
-                    )
-                    .map((field) => field.key),
-            ),
+    //
+    // Decided per KEY (#228): a key is dropped only when no field with that key
+    // is both submitting and visible at submit time. A presentational field
+    // (#110) holds no data, and a field hidden by `when` (#117) must not write a
+    // value the user cannot see — but a display-only twin sharing its key with
+    // the visible editable field must not strip the editable field's value.
+    const nonSubmittedFieldKeys = computed(() =>
+        nonSubmittedFieldKeysFor(props.editFields ?? [], isEditFieldVisible),
     );
 
+    /*
+     * Seed the form's data, ONE value per key (#228). Presentational fields are
+     * never seeded. When several submitting fields share a key (alternative
+     * controls for one value, switched by `when`), the key is seeded from the
+     * first of them that is visible against the seeded model, else the first
+     * declared. This used to be last-declared-wins, so a hidden alternative
+     * declared after the visible field replaced its default.
+     *
+     * Two submitting fields with one key that are visible TOGETHER are almost
+     * certainly a mistake (two controls bound to one value): the first declared
+     * wins, and DXTable warns once per key.
+     */
+    const warnedSharedVisibleKeys = new Set<string>();
+    const seedFormData = (
+        valueFor: (field: FieldDefinition) => any,
+        context: Record<string, any>,
+    ): Record<string, any> => {
+        const fieldsByKey = new Map<string, FieldDefinition[]>();
+        submittableEditFields.value.forEach((field) => {
+            const sharing = fieldsByKey.get(field.key);
+            if (sharing) sharing.push(field);
+            else fieldsByKey.set(field.key, [field]);
+        });
+
+        const formData: Record<string, any> = {};
+        fieldsByKey.forEach((fields, key) => {
+            formData[key] = valueFor(fields[0]);
+        });
+
+        const seededModel = { ...context, ...formData };
+        fieldsByKey.forEach((fields, key) => {
+            if (fields.length < 2) return;
+            const visibleFields = fields.filter((field) =>
+                isFieldVisibleFor(field, seededModel),
+            );
+            if (visibleFields.length > 1 && !warnedSharedVisibleKeys.has(key)) {
+                warnedSharedVisibleKeys.add(key);
+                // eslint-disable-next-line no-console
+                console.warn(
+                    `[DXTable] ${visibleFields.length} submitting edit fields share the key "${key}" and are visible together, ` +
+                        'so they edit one value; the first declared seeds it. ' +
+                        'Give alternatives mutually exclusive `when` predicates, or mark a display-only one `submit: false`.',
+                );
+            }
+            if (visibleFields.length > 0 && visibleFields[0] !== fields[0]) {
+                formData[key] = valueFor(visibleFields[0]);
+            }
+        });
+        return formData;
+    };
+
     const stripNonSubmittedFields = (data: Record<string, any>): Record<string, any> => {
         if (nonSubmittedFieldKeys.value.size === 0) return data;
         return Object.fromEntries(
@@ -265,11 +309,9 @@ export function useResourceEditor<T = any>(
         // between successive row opens. Presentational fields (submit: false)
         // lay the form out; they hold no data and must not be POSTed just
         // because they were declared.
-        const formData: Record<string, any> = {};
-        submittableEditFields.value.forEach(field => {
-            formData[field.key] = seedValueFor(field, item);
-        });
-        startSession(formData);
+        startSession(
+            seedFormData((field) => seedValueFor(field, item), item as any),
+        );
 
         // Open modal
         editFormInstanceKey.value++;
@@ -332,11 +374,7 @@ export function useResourceEditor<T = any>(
         editLoading.value = false;
 
         // A fresh form seeded with the field defaults (see `startSession`).
-        const formData: Record<string, any> = {};
-        submittableEditFields.value.forEach(field => {
-            formData[field.key] = resolveFieldDefault(field);
-        });
-        startSession(formData);
+        startSession(seedFormData(resolveFieldDefault, {}));
         editFormInstanceKey.value++;
         showEditModal.value = true;
     };

package/resources/js/index.ts

@@ -62,9 +62,11 @@ export { default as DDropdownItem } from "./components/base/DDropdownItem.vue";
 export { default as DForm } from "./components/base/DForm.vue";
 export { default as DFormCheckbox } from "./components/base/DFormCheckbox.vue";
 export { default as DFormCheckboxGroup } from "./components/base/DFormCheckboxGroup.vue";
+export { default as DFormFile } from "./components/base/DFormFile.vue";
 export { default as DFormGroup } from "./components/base/DFormGroup.vue";
 export { default as DFormInput } from "./components/base/DFormInput.vue";
 export { default as DFormInvalidFeedback } from "./components/base/DFormInvalidFeedback.vue";
+export { default as DFormValidFeedback } from "./components/base/DFormValidFeedback.vue";
 export { default as DFormOtp } from "./components/base/DFormOtp.vue";
 export { default as DFormRadio } from "./components/base/DFormRadio.vue";
 export { default as DFormRadioGroup } from "./components/base/DFormRadioGroup.vue";
@@ -146,6 +148,8 @@ export type {
     FormTab,
     MaybeFn,
     OptionsLoader,
+    PasswordActionsSlotProps,
+    EditPasswordActionsSlotProps,
     // Strict, discriminated field types (#131) — opt-in; canonical in a future
     // major. `FieldDef` is the union; the rest are its per-type members.
     FieldDef,
@@ -216,7 +220,14 @@ export type {
     NavigationItem,
     NavigationGroup,
     Navigation,
+    NavigationItemOf,
     NavbarSearchAlign,
     NavbarActionsOnMobile,
     SidebarVariant,
+    DashboardUser,
+    DashboardNavbarSlots,
+    DashboardSidebarSlots,
+    DashboardSlotExtras,
+    DashboardSlots,
+    PrefixedDashboardSlots,
 } from "./types/navigation";

package/resources/js/types/index.ts

@@ -274,6 +274,20 @@ export interface FieldDefinition {
      */
     default?: any;
 
+    /**
+     * For a field whose value is a list of rows (a `repeater`, or a span
+     * field that renders its own rows and owns `key.N.*` error keys): the
+     * row's own name, called with the row (`model[key][index]`, or `{}` when
+     * the model has no such row) and its 0-based index. When it returns a
+     * non-empty string, the error summary lists that row's errors under it
+     * alone ("Chaucer Ale (Pint): Enter a price.") instead of
+     * "<sub-field label> (line N)". Returning `undefined`, `null` or `""`
+     * (a row with no name yet), or throwing, keeps the line-number label.
+     * Only labels: which field owns the error, and what a click on the
+     * summary row focuses, are unchanged.
+     */
+    rowLabel?: (row: Record<string, any>, index: number) => string | null | undefined;
+
     /** Label for a repeater's "add row" button (default: "Add"). */
     addLabel?: string;
 
@@ -364,6 +378,10 @@ export interface FieldDefinition {
      * every `editFields` key, so those decorative fields are POSTed alongside
      * the real ones (an empty string, an empty array) purely because they were
      * declared.
+     *
+     * Applies per KEY (#228): DXTable drops a key only when no field with that
+     * key is both submitting and visible, so a `submit: false` display twin
+     * does not strip the value of a visible editable field sharing its key.
      */
     submit?: boolean;
 
@@ -579,6 +597,7 @@ export interface ComponentFieldDef extends BaseFieldDef {
 export interface RepeaterFieldDef extends BaseFieldDef {
     type: "repeater";
     fields?: FieldDef[];
+    rowLabel?: (row: Record<string, any>, index: number) => string | null | undefined;
     addLabel?: string;
     minItems?: number;
     maxItems?: number;
@@ -652,6 +671,51 @@ export interface FormTab {
     lazy?: boolean;
 }
 
+/**
+ * Slot props of DXField's `password-actions` slot (DXForm:
+ * `password-actions(<key>)`): content placed beside a password input, inside
+ * its input group after the reveal (eye) toggle, such as a "Generate password"
+ * button. `setRevealed` drives the same state the eye toggles.
+ *
+ * ```vue
+ * <template #password-actions(password)="{ update, setRevealed, disabled }">
+ *   <DButton variant="outline-secondary" :disabled="disabled"
+ *     @click="update(generatePassword()); setRevealed(true)">Generate</DButton>
+ * </template>
+ * ```
+ */
+export interface PasswordActionsSlotProps {
+    /** The field definition being rendered. */
+    field: FieldDefinition;
+    /** The model passed to field predicates (defaults to the live form data). */
+    model: any;
+    /** The current field value. */
+    value: any;
+    /** Write a new value (also marks the field touched and clears its error). */
+    update: (value: any) => void;
+    /** Whether the password is currently shown as plain text. */
+    revealed: boolean;
+    /**
+     * Show (`true`) or mask (`false`) the password, exactly as the eye does.
+     * A no-op on a `revealable: false` field, which never unmasks.
+     */
+    setRevealed: (revealed: boolean) => void;
+    /** Whether the field is disabled or read-only. */
+    disabled: boolean;
+}
+
+/**
+ * Slot props of DXTable's `edit-password-actions(<key>)` slot, the edit/create
+ * modal's form of {@link PasswordActionsSlotProps}. `item` is the row being
+ * edited, `null` in create mode. (`model` is not passed, as with the modal's
+ * other field slots.)
+ */
+export interface EditPasswordActionsSlotProps
+    extends Omit<PasswordActionsSlotProps, "model"> {
+    /** The row being edited; `null` in create mode. */
+    item: any;
+}
+
 /**
  * The theme's extra colour variant, `pending`: waiting, and the next move is
  * not yours ("awaiting payment", "sent to printer, not yet confirmed").

package/resources/js/types/navigation.ts

@@ -8,7 +8,13 @@ export interface NavigationItem {
   visible?: boolean;
 }
 
-export interface NavigationGroup {
+/**
+ * A group of sidebar links. `TItem` is the app's own item type, for menus whose
+ * items carry extra keys (a permission, a route name): DXDashboard and
+ * DXDashboardSidebar infer it from the `navigation` prop, so the `link` slot's
+ * `item` has those keys too. Defaults to `NavigationItem`.
+ */
+export interface NavigationGroup<TItem extends NavigationItem = NavigationItem> {
   label?: string;
   /**
    * Stable identifier for the group's collapsible open/closed state. Defaults
@@ -17,7 +23,7 @@ export interface NavigationGroup {
    * state attached to the right group.
    */
   key?: string;
-  items: NavigationItem[];
+  items: TItem[];
   /**
    * Per-group override for the sidebar's `collapsibleGroups` behaviour.
    * Set to `false` to keep a group permanently expanded (no toggle header)
@@ -29,7 +35,26 @@ export interface NavigationGroup {
   visible?: boolean;
 }
 
-export type Navigation = NavigationGroup[];
+/** The sidebar's navigation: its groups, in order. See `NavigationGroup` for `TItem`. */
+export type Navigation<TItem extends NavigationItem = NavigationItem> = NavigationGroup<TItem>[];
+
+/**
+ * The item type of a navigation, as the `link` slot's `item` receives it:
+ * `NavigationItemOf<Navigation<AppItem>>` is `AppItem`. An `any` navigation
+ * (untyped page props) gives `any`, and an empty `[]` gives `NavigationItem`.
+ *
+ * DXDashboard and DXDashboardSidebar are generic over the whole navigation
+ * (`TNavigation`) and derive the item from it, rather than generic over the
+ * item: TypeScript infers `any` for a type parameter that IS the prop's type,
+ * but not for one nested inside it (`{ items: TItem[] }[]`), where an `any`
+ * navigation would have fallen back to `NavigationItem` and rejected the app's
+ * extra keys.
+ */
+export type NavigationItemOf<TNavigation extends Navigation> = [
+  TNavigation[number]["items"][number],
+] extends [never]
+  ? NavigationItem
+  : TNavigation[number]["items"][number];
 
 /**
  * Horizontal alignment of the navbar search slot content within its region:
@@ -54,3 +79,150 @@ export type SidebarVariant = "light" | "dark";
  * Shared by DXDashboard (which forwards it) and DXDashboardNavbar.
  */
 export type NavbarActionsOnMobile = "wrap" | "hide";
+
+/**
+ * The signed-in user DXDashboardNavbar (and DXDashboard, which forwards it)
+ * shows in the avatar dropdown. Extra keys are allowed and reach the
+ * user-menu slots.
+ */
+export interface DashboardUser {
+  name: string;
+  email: string;
+  [key: string]: any;
+}
+
+/** A slot that receives no props. */
+type NoSlotProps = Record<never, never>;
+
+/*
+ * The slot interfaces below are what `defineSlots` uses and what an editor
+ * shows on hover. The API docs (`docs:generate:ai`) still read each slot from
+ * the `@slot`/`@binding` comments in the component's template: vue-docgen-api
+ * only reads `defineSlots` members whose keys are bare identifiers, and it
+ * drops the binding types when it does, so every key here is QUOTED on
+ * purpose. Keep the text in step with the template comments.
+ */
+
+/** Slots of DXDashboardNavbar, with their slot props. All are optional. */
+export interface DashboardNavbarSlots {
+  /** Custom hamburger/menu icon. Defaults to a three-line SVG. */
+  "menu-icon"?(props: NoSlotProps): any;
+  /**
+   * Search input or component. Fills the middle of the bar at every width,
+   * aligned per `searchAlign`. The region is a size container named
+   * `dx-navbar-search`; a `<kbd>` hint inside it is hidden when it is
+   * narrower than 16rem.
+   */
+  "search"?(props: NoSlotProps): any;
+  /**
+   * Page-level primary actions (e.g. a Create button). Right-aligned next to
+   * the user menu from `md` up; below, wraps to its own full-width row or is
+   * hidden entirely per `actionsOnMobile`.
+   */
+  "actions"?(props: {
+    /** The current page title, for context. */
+    pageTitle: string;
+  }): any;
+  /** Replaces the entire user menu (the default avatar dropdown). */
+  "user-menu"?(props: {
+    /** The signed-in user; `null` for a guest. */
+    user: DashboardUser | null;
+  }): any;
+  /**
+   * Custom user avatar/icon in the dropdown trigger. To decorate the default
+   * avatar (e.g. add a notification dot) rather than replace it, render
+   * `DXUserAvatar`. Only rendered for a signed-in user.
+   */
+  "user-icon"?(props: {
+    /** The first letter of the user's name. */
+    initial: string;
+    /** The signed-in user. */
+    user: DashboardUser;
+  }): any;
+  /** Items for the default user dropdown menu. Only rendered for a signed-in user. */
+  "user-menu-items"?(props: {
+    /** The signed-in user. */
+    user: DashboardUser;
+  }): any;
+}
+
+/**
+ * Slots of DXDashboardSidebar, with their slot props. All are optional.
+ * `TItem` is the navigation's item type (see `NavigationGroup`).
+ */
+export interface DashboardSidebarSlots<TItem extends NavigationItem = NavigationItem> {
+  /**
+   * Brand/logo area in the sidebar header. Defaults to the title's initial
+   * plus the full title (hidden when collapsed).
+   */
+  "brand"?(props: {
+    /** Whether the sidebar rail is collapsed to icons only. */
+    collapsed: boolean;
+    /** The sidebar title text. */
+    title: string;
+  }): any;
+  /**
+   * Renders a single navigation item link. Defaults to an anchor with
+   * optional icon, label, and badge.
+   */
+  "link"?(props: {
+    /**
+     * The navigation item (label, url, icon, badge, badgeColor), typed as the
+     * app's own item type when its items carry extra keys.
+     */
+    item: TItem;
+    /** Whether this item matches the current route. */
+    isActive: boolean;
+    /** Whether the sidebar rail is collapsed to icons only. */
+    collapsed: boolean;
+    /** Whether the item's group is currently expanded. */
+    isExpanded: boolean;
+  }): any;
+  /**
+   * Utility/secondary links pinned to the bottom of the sidebar (help,
+   * changelog, sign-out, …), below the nav groups.
+   */
+  "footer"?(props: {
+    /** Whether the sidebar rail is collapsed to icons only. */
+    collapsed: boolean;
+  }): any;
+}
+
+/**
+ * The two bindings DXDashboard adds to every forwarded `sidebar-*` and
+ * `navbar-*` slot. They are bound after the child's own slot props, so they
+ * win a name clash.
+ */
+export interface DashboardSlotExtras {
+  /** Shows/hides the sidebar. */
+  toggleSidebar: () => void;
+  /** Whether the sidebar is currently hidden. */
+  sidebarHidden: boolean;
+}
+
+/** The props a (possibly optional) slot function receives. */
+type SlotPropsOf<Slot> = NonNullable<Slot> extends (props: infer Props) => any ? Props : never;
+
+/**
+ * A child component's slots renamed with `Prefix` and given the dashboard's
+ * extra bindings: `{ brand(props: P) }` becomes
+ * `{ "sidebar-brand"(props: P & DashboardSlotExtras) }`. Derived from the
+ * child's slot types, so a slot added to the child is typed here for free.
+ */
+export type PrefixedDashboardSlots<Slots, Prefix extends string> = {
+  [Name in keyof Slots as `${Prefix}${Name & string}`]?: (
+    props: Omit<SlotPropsOf<Slots[Name]>, keyof DashboardSlotExtras> & DashboardSlotExtras,
+  ) => any;
+};
+
+/**
+ * Slots of DXDashboard: the page content (`default`), every
+ * DXDashboardSidebar slot as `sidebar-<name>` and every DXDashboardNavbar
+ * slot as `navbar-<name>`. An unprefixed name (`#search`) is not forwarded.
+ * `TItem` is the navigation's item type (see `NavigationGroup`).
+ */
+export type DashboardSlots<TItem extends NavigationItem = NavigationItem> = {
+  /** The main page content. */
+  default?(props: NoSlotProps): any;
+} & PrefixedDashboardSlots<DashboardSidebarSlots<TItem>, "sidebar-"> &
+  PrefixedDashboardSlots<DashboardNavbarSlots, "navbar-">;