@ditojs/admin 2.92.0 → 2.94.1

package/types/index.d.ts

@@ -8,7 +8,7 @@ import {
   TimeFormat
 } from '@ditojs/utils'
 import { RequireAtLeastOne, SetOptional } from 'type-fest'
-import { Component as VueComponent } from 'vue'
+import { Component as VueComponent, ComponentPublicInstance } from 'vue'
 import { Router as VueRouter } from 'vue-router'
 
 declare global {
@@ -695,7 +695,19 @@ export interface SchemaSourceMixin<$Item> {
    *
    * @defaultValue `false`
    */
-  creatable?: OrItemAccessor<$Item, {}, boolean | { label: string }>
+  creatable?: OrItemAccessor<
+    $Item,
+    {},
+    | boolean
+    | {
+        label?: string
+        /**
+         * Returns additional query parameters to include in the
+         * URL when navigating to the create form.
+         */
+        query?: (context: DitoContext) => Record<string, any>
+      }
+  >
   /**
    * Whether to add edit buttons next to the list items.
    *
@@ -788,11 +800,14 @@ export type SchemaOptions<$Item, $Option = any> =
        */
       groupBy?: keyof $Option
       /**
-       * Custom equality function for comparing options.
+       * Custom equality function for matching a value to an
+       * option. Receives a context with `value` and `option`.
        */
       equals?: (
-        a: $Option,
-        b: $Option
+        context: DitoContext & {
+          value: any
+          option: $Option
+        }
       ) => boolean
       /**
        * Relative path to resolve options from data
@@ -1640,6 +1655,12 @@ export interface CheckboxesSchema<$Item = any>
    * The type of the component.
    */
   type: 'checkboxes'
+  /**
+   * Whether multiple values can be selected.
+   *
+   * @defaultValue `true`
+   */
+  multiple?: boolean
   /**
    * @defaultValue `'vertical'`
    */
@@ -1918,7 +1939,7 @@ export type DitoContext<$Item = any> = {
   /**
    * The current search term in select components.
    */
-  searchTerm: string | undefined
+  searchTerm: string
   /**
    * Whether a button request is currently running.
    */
@@ -1976,9 +1997,22 @@ export type DitoContext<$Item = any> = {
   getResourceUrl(resource: Resource): string
   /** Displays a notification to the user. */
   notify(options: {
+    /** Notification style. @defaultValue `'info'` */
     type?: LiteralUnion<'warning' | 'error' | 'info' | 'success'>
+    /** Heading text. Defaults to a label matching `type`. */
     title?: string
+    /** Body text, rendered as HTML paragraphs. */
     text: OrArrayOf<string>
+    /**
+     * The original error object. When `type` is `'error'`,
+     * this is logged to the console alongside the message.
+     */
+    error?: unknown
+    /**
+     * Display duration in milliseconds. When omitted, calculated
+     * automatically from content length. Use `0` for sticky.
+     */
+    duration?: number
   }): void
 }
 
@@ -1997,7 +2031,9 @@ export type DitoComponentInstance<
   $Members extends Record<string, any> = {}
 > = DitoComponentInstanceBase<$Item> & $Members
 
-export interface DitoComponentInstanceBase<$Item = any> extends EmitterMixin {
+export interface DitoComponentInstanceBase<$Item = any>
+  extends ComponentPublicInstance,
+    EmitterMixin {
   // -- Data access (ValueMixin, ContextMixin, TypeMixin) --
 
   /** The current value of the component (getter/setter). */
@@ -2968,6 +3004,31 @@ export type SourceComponent<$Item = any> =
   | TreeListSchema<$Item>
   | TreeObjectSchema<$Item>
 
+/**
+ * Field components that don't have an options mixin (excludes
+ * select, multiselect, and source components like list/object/tree).
+ */
+type NonOptionFieldComponent<$Item = any> = Exclude<
+  NonSectionComponent<$Item>,
+  SelectSchema<$Item> | MultiselectSchema<$Item> | SourceComponent<$Item>
+>
+
+/**
+ * Select/multiselect with a typed `$Option` for option callbacks.
+ *
+ * Note: This is intentionally an intersection type rather than
+ * `SelectSchema<$Item, $Option> | MultiselectSchema<$Item, $Option>`,
+ * because using the full interfaces in a union breaks TypeScript's
+ * contextual typing for callbacks in the `Components` mapped type.
+ */
+type OptionComponent<$Item, $Option> = BaseSchema<$Item> &
+  SchemaOptionsMixin<$Item, $Option> &
+  SchemaAffixMixin<$Item> &
+  Pick<
+    MultiselectSchema,
+    'multiple' | 'searchable' | 'stayOpen' | 'taggable'
+  > & { type: 'select' | 'multiselect' }
+
 /**
  * Strips properties with `never` values from a type.
  */
@@ -3047,14 +3108,16 @@ export type Components<$Item = any> = 0 extends 1 & $Item
   : {
       [K in keyof $Item]?: [$Item[K]] extends [never]
         ? NonSectionComponent<$Item> | SectionSchema<$Item>
-        : $Item[K] extends (infer E)[]
+        : NonNullable<$Item[K]> extends (infer E)[]
           ? E extends Record<string, any>
             ? NonSectionComponent<E>
             : NonSectionComponent<$Item>
-          : $Item[K] extends Record<string, any>
+          : NonNullable<$Item[K]> extends Record<string, any>
             ?
-                | NonSectionComponent<$Item>
-                | SectionSchema<$Item, $Item[K]>
+                | NonOptionFieldComponent<$Item>
+                | OptionComponent<$Item, NonNullable<$Item[K]>>
+                | SourceComponent<NonNullable<$Item[K]>>
+                | SectionSchema<$Item, NonNullable<$Item[K]>>
             :
                 | NonSectionComponent<$Item>
                 | SectionSchema<$Item>

package/types/tests/admin.test-d.ts

@@ -1,27 +0,0 @@
-import { assertType, describe, it } from 'vitest'
-import type { default as DitoAdmin, View } from '../index.d.ts'
-import type { Entry } from './fixtures.ts'
-
-describe('DitoAdmin', () => {
-  it('constructor accepts element and views option', () => {
-    assertType<ConstructorParameters<typeof DitoAdmin>>([
-      document.body,
-      {
-        views: {
-          entries: {
-            type: 'view',
-            component: {
-              type: 'list',
-              form: {
-                type: 'form',
-                components: {
-                  title: { type: 'text' }
-                }
-              }
-            }
-          } satisfies View<Entry>
-        }
-      }
-    ])
-  })
-})

package/types/tests/component-buttons.test-d.ts

@@ -1,44 +0,0 @@
-import { expectTypeOf, assertType, describe, it } from 'vitest'
-import type { Buttons } from '../index.d.ts'
-import type { Entry } from './fixtures.ts'
-
-describe('Buttons', () => {
-  it('accepts button without type', () => {
-    assertType<Buttons<Entry>>({
-      save: { text: 'Save' }
-    })
-  })
-
-  it('accepts button with type', () => {
-    assertType<Buttons<Entry>>({
-      save: { type: 'button', text: 'Save' }
-    })
-  })
-
-  it('click callback receives typed item', () => {
-    assertType<Buttons<Entry>>({
-      save: {
-        text: 'Save',
-        events: {
-          click({ item }) {
-            expectTypeOf(item).not.toBeAny()
-            expectTypeOf(item).toHaveProperty('id')
-            expectTypeOf(item).toHaveProperty('title')
-            expectTypeOf(item.id).toBeNumber()
-            expectTypeOf(item.title).toBeString()
-          }
-        }
-      }
-    })
-  })
-
-  it('rejects invalid button type', () => {
-    assertType<Buttons<Entry>>({
-      save: {
-        // @ts-expect-error 'text' is not a valid button type
-        type: 'text',
-        text: 'Save'
-      }
-    })
-  })
-})

package/types/tests/component-list.test-d.ts

@@ -1,159 +0,0 @@
-import { expectTypeOf, assertType, describe, it } from 'vitest'
-import type {
-  Components,
-  Form,
-  ListSchema,
-  ColumnSchema,
-  DitoContext
-} from '../index.d.ts'
-import type { Entry, Parent } from './fixtures.ts'
-
-describe('ListSchema', () => {
-  it('accepts form components typed against $Item', () => {
-    assertType<ListSchema<Entry>>({
-      type: 'list',
-      form: {
-        type: 'form',
-        components: {
-          title: { type: 'text' }
-        }
-      }
-    })
-  })
-
-  it('accepts columns as a record of ColumnSchema', () => {
-    assertType<ListSchema<Entry>>({
-      type: 'list',
-      columns: {
-        title: {
-          label: 'Title',
-          sortable: true
-        } satisfies ColumnSchema<Entry>
-      }
-    })
-  })
-
-  it('column render callback receives typed value', () => {
-    assertType<ListSchema<Entry>>({
-      type: 'list',
-      columns: {
-        title: {
-          render({ value }) {
-            expectTypeOf(value).not.toBeAny()
-            expectTypeOf(value).toBeString()
-            return value
-          }
-        }
-      }
-    })
-  })
-
-  it('accepts columns as an array of item keys', () => {
-    assertType<ListSchema<Entry>>({
-      type: 'list',
-      columns: ['title', 'id']
-    })
-  })
-
-  it('rejects unknown keys in columns array', () => {
-    assertType<ListSchema<Entry>>({
-      type: 'list',
-      // @ts-expect-error 'missing' is not a key of Entry
-      columns: ['title', 'missing']
-    })
-  })
-
-  it('accepts creatable as boolean or callback', () => {
-    assertType<ListSchema<Entry>>({
-      type: 'list',
-      creatable: true
-    })
-
-    assertType<ListSchema<Entry>>({
-      type: 'list',
-      creatable(ctx) {
-        expectTypeOf(ctx).not.toBeAny()
-        expectTypeOf(ctx).toMatchTypeOf<DitoContext<Entry>>()
-        expectTypeOf(ctx.item.title).toBeString()
-        return true
-      }
-    })
-  })
-
-  it('types list correctly inside Components', () => {
-    assertType<Components<Parent>>({
-      entries: {
-        type: 'list',
-        form: {
-          type: 'form',
-          components: {
-            title: { type: 'text' }
-          }
-        } satisfies Form<Entry>
-      }
-    })
-  })
-
-  it('rejects wrong form type via typed variable', () => {
-    const parentForm: Form<Parent> = {
-      type: 'form',
-      components: {
-        title: { type: 'text' },
-        entries: { type: 'list' }
-      }
-    }
-
-    assertType<ListSchema<Entry>>({
-      type: 'list',
-      // @ts-expect-error Form<Parent> is not assignable to ResolvableForm<Entry>
-      form: parentForm
-    })
-  })
-
-  it('accepts draggable as OrItemAccessor', () => {
-    assertType<ListSchema<Entry>>({
-      type: 'list',
-      draggable(ctx) {
-        expectTypeOf(ctx).not.toBeAny()
-        expectTypeOf(ctx).toMatchTypeOf<DitoContext<Entry>>()
-        return true
-      }
-    })
-  })
-
-  it('accepts scopes as string array or object', () => {
-    assertType<ListSchema<Entry>>({
-      type: 'list',
-      scopes: ['active', 'archived']
-    })
-
-    assertType<ListSchema<Entry>>({
-      type: 'list',
-      scopes: {
-        active: { label: 'Active', defaultScope: true },
-        archived: 'Archived'
-      }
-    })
-  })
-
-  it('accepts itemLabel as string, callback, or false', () => {
-    assertType<ListSchema<Entry>>({
-      type: 'list',
-      itemLabel: 'title'
-    })
-
-    assertType<ListSchema<Entry>>({
-      type: 'list',
-      itemLabel: false
-    })
-
-    assertType<ListSchema<Entry>>({
-      type: 'list',
-      itemLabel({ item }) {
-        expectTypeOf(item).not.toBeAny()
-        expectTypeOf(item.title).toBeString()
-        return item.title
-      }
-    })
-  })
-})

package/types/tests/component-misc.test-d.ts

@@ -1,137 +0,0 @@
-import { expectTypeOf, assertType, describe, it } from 'vitest'
-import type { MenuSchema, View, NumberSchema, Form } from '../index.d.ts'
-import type { Entry } from './fixtures.ts'
-
-describe('MenuSchema', () => {
-  it('accepts menu with items containing views', () => {
-    assertType<MenuSchema<Entry>>({
-      type: 'menu',
-      label: 'Main Menu',
-      name: 'mainMenu',
-      items: {
-        entries: {
-          type: 'view',
-          component: {
-            type: 'list',
-            form: {
-              type: 'form',
-              components: {
-                title: { type: 'text' }
-              }
-            }
-          }
-        }
-      }
-    })
-  })
-
-  it('View union accepts both ViewSchema and MenuSchema', () => {
-    const viewSchema: View<Entry> = {
-      type: 'view',
-      components: {
-        title: { type: 'text' }
-      }
-    }
-
-    const menuSchema: View<Entry> = {
-      type: 'menu',
-      label: 'Group',
-      items: {
-        sub: {
-          type: 'view',
-          components: {
-            title: { type: 'text' }
-          }
-        }
-      }
-    }
-
-    assertType<View<Entry>>(viewSchema)
-    assertType<View<Entry>>(menuSchema)
-  })
-})
-
-describe('NumberSchema', () => {
-  it('accepts min, max, step, decimals', () => {
-    assertType<NumberSchema<Entry>>({
-      type: 'number',
-      min: 0,
-      max: 100,
-      step: 0.5,
-      decimals: 2
-    })
-  })
-
-  it('accepts range as tuple', () => {
-    assertType<NumberSchema<Entry>>({
-      type: 'integer',
-      range: [0, 100]
-    })
-  })
-
-  it('accepts rules including integer', () => {
-    assertType<NumberSchema<Entry>>({
-      type: 'number',
-      rules: {
-        min: 0,
-        max: 999,
-        integer: true
-      }
-    })
-  })
-})
-
-describe('SchemaAffixMixin (prefix/suffix)', () => {
-  it('accepts prefix as string', () => {
-    assertType<NumberSchema<Entry>>({
-      type: 'number',
-      prefix: '$'
-    })
-  })
-
-  it('accepts prefix as array of SchemaAffix objects', () => {
-    assertType<NumberSchema<Entry>>({
-      type: 'number',
-      prefix: [
-        { type: 'icon', text: 'currency' },
-        { html: '<b>$</b>' }
-      ]
-    })
-  })
-
-  it('accepts suffix with conditional if callback', () => {
-    assertType<NumberSchema<Entry>>({
-      type: 'number',
-      suffix: {
-        text: '%',
-        if({ item }) {
-          expectTypeOf(item).not.toBeAny()
-          return item.id > 0
-        }
-      }
-    })
-  })
-})
-
-describe('ClipboardConfig', () => {
-  it('accepts copy/paste callbacks on a form', () => {
-    assertType<Form<Entry>>({
-      type: 'form',
-      clipboard: {
-        copy(context) {
-          expectTypeOf(context).not.toBeAny()
-          expectTypeOf(context.item).not.toBeAny()
-          return context.item
-        },
-        paste(context) {
-          expectTypeOf(context).not.toBeAny()
-          expectTypeOf(context.item).not.toBeAny()
-          return context.item
-        }
-      },
-      components: {
-        title: { type: 'text' }
-      }
-    })
-  })
-})

package/types/tests/component-object.test-d.ts

@@ -1,69 +0,0 @@
-import { expectTypeOf, assertType, describe, it } from 'vitest'
-import type {
-  ObjectSchema,
-  TreeListSchema,
-  Form,
-  Components
-} from '../index.d.ts'
-import type { Address, Entry, ParentWithAddress } from './fixtures.ts'
-
-describe('ObjectSchema', () => {
-  it('accepts typed form', () => {
-    assertType<ObjectSchema<Address>>({
-      type: 'object',
-      form: {
-        type: 'form',
-        components: {
-          street: { type: 'text' },
-          city: { type: 'text' }
-        }
-      } satisfies Form<Address>
-    })
-  })
-
-  it('accepts typed columns', () => {
-    assertType<ObjectSchema<Address>>({
-      type: 'object',
-      columns: {
-        street: { label: 'Street' },
-        city: { label: 'City' }
-      }
-    })
-  })
-
-  it('rejects unknown key in columns array', () => {
-    assertType<ObjectSchema<Address>>({
-      type: 'object',
-      // @ts-expect-error 'zipCode' is not a key of Address
-      columns: ['street', 'zipCode']
-    })
-  })
-
-  it('works inside Components for a data key', () => {
-    assertType<Components<ParentWithAddress>>({
-      address: {
-        type: 'object',
-        form: {
-          type: 'form',
-          components: {
-            title: { type: 'text' }
-          }
-        } satisfies Form<ParentWithAddress>
-      }
-    })
-  })
-})
-
-describe('TreeListSchema', () => {
-  it('accepts typed form', () => {
-    assertType<TreeListSchema<Entry>>({
-      type: 'tree-list',
-      form: {
-        type: 'form',
-        components: {
-          title: { type: 'text' }
-        }
-      } satisfies Form<Entry>
-    })
-  })
-})