kirbyuse/dist/composables.d.ts

Collection of Vue Composition utilities for Kirby CMS

import * as _$kirby_types0 from "kirby-types";
import { KirbyFieldProps, KirbyFieldsetProps, Panel, PanelContent } from "kirby-types";
import * as _$vue from "vue";

//#region src/composables/api.d.ts
/**
 * Returns Kirby's Panel API for making HTTP requests to the backend.
 *
 * @remarks
 * This composable is a simple shortcut to `window.panel.api`.
 */
declare function useApi(): _$kirby_types0.PanelApi;
//#endregion
//#region src/composables/app.d.ts
/**
 * Returns the main Panel Vue instance.
 *
 * @remarks
 * This composable is a simple shortcut to `window.panel.app`.
 */
declare function useApp(): _$kirby_types0.PanelApp;
//#endregion
//#region src/composables/block.d.ts
/**
 * Props passed to block components by Kirby's block field.
 */
interface BlockComponentProps {
  /** Block content data */
  content: Record<string, unknown>;
  /** Fieldset definition with tabs and fields */
  fieldset: KirbyFieldsetProps;
  /** Allow additional block-specific props */
  [key: string]: unknown;
}
/**
 * Provides block methods exposed by the default block component (Options API), which all custom blocks are extending.
 * Since Options API methods are not avaiable in Composition API, we need to extract them into a composable.
 *
 * @see https://github.com/getkirby/kirby/blob/main/panel/src/components/Forms/Blocks/Types/Default.vue
 *
 * @example
 * ```vue
 * <script setup>
 * import { computed, ref, useApi, usePanel, watch } from "kirbyuse";
 *
 * // Will inherit props from extended default block
 * const props = defineProps({});
 * const emit = defineEmits([]);
 *
 * const { field, open, update } = useBlock(props, emit);
 * ```
 */
declare function useBlock(props: BlockComponentProps, emit?: (...args: unknown[]) => void): {
  field: (name: string, fallback?: KirbyFieldProps) => KirbyFieldProps | undefined;
  open: () => void;
  update: (content: Record<string, unknown>) => void;
};
//#endregion
//#region src/composables/compatibility.d.ts
declare const isKirby5: () => boolean;
declare const isKirby4: () => boolean;
//#endregion
//#region src/composables/content.d.ts
/**
 * Reactive getters and methods to work with content of the current view.
 *
 * @remarks
 * This composable follows the Kirby 5 content API while staying compatible with Kirby 4 (falling back to the Vuex store of Kirby 4).
 */
declare function useContent(): {
  content: PanelContent;
  currentContent: _$vue.ComputedRef<Record<string, any>>;
  contentChanges: _$vue.ComputedRef<Record<string, any>>;
  hasChanges: _$vue.ComputedRef<boolean>;
  update: (values?: Record<string, unknown>, save?: boolean) => Promise<void>;
};
//#endregion
//#region src/composables/dialog.d.ts
/**
 * Dialog size options.
 *
 * @see https://github.com/getkirby/kirby/blob/main/panel/src/mixins/dialog.js
 */
type DialogSize = "small" | "default" | "medium" | "large" | "huge";
/**
 * Button theme options.
 *
 * Includes semantic themes, color themes, and special themes.
 * Any theme can be suffixed with `-icon` to only color the icon.
 *
 * @see https://github.com/getkirby/kirby/blob/main/panel/src/styles/utilities/theme.css
 */
type ButtonTheme = "positive" | "negative" | "info" | "notice" | "warning" | "passive" | "error" | "love" | "text" | "red" | "orange" | "yellow" | "blue" | "pink" | "green" | "aqua" | "purple" | "gray" | "white" | "dark" | "code" | "empty" | "none" | `${string}-icon`;
/**
 * Button configuration for dialog buttons.
 *
 * @see https://github.com/getkirby/kirby/blob/main/panel/src/components/Navigation/Button.vue
 */
interface DialogButtonProps {
  /** Button text */
  text?: string;
  /** Icon identifier */
  icon?: string;
  /** Button color theme */
  theme?: ButtonTheme;
  /** Whether the button is disabled */
  disabled?: boolean;
  /** Button variant */
  variant?: "filled" | "dimmed";
}
/**
 * Field definition for dialog fields.
 */
type DialogFieldProps = Partial<Omit<KirbyFieldProps, "type">> & {
  type: string; /** Allow additional field-type-specific properties */
  [key: string]: unknown;
};
/**
 * Props for opening a fields dialog.
 *
 * @see https://github.com/getkirby/kirby/blob/main/panel/src/components/Dialogs/FormDialog.vue
 */
interface FieldsDialogProps<T = Record<string, any>, R = T> {
  /**
   * Dialog width.
   * @default "medium"
   */
  size?: DialogSize;
  /**
   * Submit button configuration. Can be:
   * - `false` to hide the button
   * - A string for the button text
   * - An object with button props
   */
  submitButton?: false | string | DialogButtonProps;
  /**
   * Cancel button configuration.
   */
  cancelButton?: false | string | DialogButtonProps;
  /**
   * Optional text shown above the fields.
   */
  text?: string;
  /**
   * Empty state message if no fields are defined.
   */
  empty?: string;
  /**
   * Field definitions as object (keyed by field name) or array.
   */
  fields?: Record<string, DialogFieldProps> | DialogFieldProps[];
  /**
   * Initial values for the fields.
   */
  value?: Partial<T>;
  /**
   * Custom submit handler. Controls dialog closing behavior.
   * - Return `false` to keep the dialog open (e.g., validation failed)
   * - Return any other value to close the dialog and resolve with that value
   * - Throw to keep the dialog open
   *
   * @example
   * ```ts
   * // Validate before closing (e.g., check slug uniqueness)
   * const data = await openFieldsDialog<{ slug: string }>({
   *   fields,
   *   onSubmit: async (value) => {
   *     const response = await panel.api.post("/site/search", {
   *       query: `slug:${value.slug}`,
   *       limit: 1
   *     })
   *     if (response.data?.length > 0) {
   *       panel.notification.error("This slug is already taken")
   *       return false // Keep dialog open
   *     }
   *     return value // Close dialog, resolve with form values
   *   },
   * })
   *
   * // Transform data before resolving
   * const page = await openFieldsDialog<{ title: string }, { id: string }>({
   *   fields,
   *   onSubmit: async (value) => {
   *     const response = await panel.api.post(`/pages/${parentId}/children`, {
   *       slug: value.slug,
   *       template: "default",
   *       content: { title: value.title }
   *     })
   *     if (!response?.id) {
   *       panel.notification.error("Failed to create page")
   *       return false // Keep dialog open
   *     }
   *     return { id: response.id } // Close dialog, resolve with created resource
   *   },
   * })
   * ```
   */
  onSubmit?: (value: T) => R | false | Promise<R | false>;
}
/**
 * Provides methods to open different types of dialogs.
 */
declare function useDialog(): {
  openTextDialog: (text: string) => Promise<boolean>;
  openFieldsDialog: {
    <T extends Record<string, any>, R>(props: Omit<FieldsDialogProps<T, R>, "onSubmit"> & {
      onSubmit: (value: T) => R | false | Promise<R | false>;
    }): Promise<R | undefined>;
    <T extends Record<string, any>>(props: Omit<FieldsDialogProps<T, T>, "onSubmit">): Promise<T | undefined>;
  };
};
//#endregion
//#region src/composables/helpers.d.ts
/**
 * Returns the internal Fiber helpers.
 *
 * @see https://lab.getkirby.com/public/lab/internals/helpers/
 *
 * @remarks
 * This composable is a simple shortcut to `window.panel.app.$helper`.
 */
declare function useHelpers(): _$kirby_types0.PanelHelpers;
//#endregion
//#region src/composables/i18n.d.ts
/**
 * Returns translation utility functions.
 *
 * @remarks
 * In most cases, use `window.panel.t` for Kirby's built-in translation function. This composable is useful for custom translation objects, such as those returned by a section's `label` property.
 *
 * @example
 * ```ts
 * const { t } = useI18n()
 *
 * // Simple string
 * t("Hello") // -> "Hello"
 *
 * // Translation object
 * t({ en: "Hello", de: "Hallo" }) // -> Returns value based on current Panel language
 * ```
 */
declare function useI18n(): {
  t: (value?: string | Record<string, string>) => string | undefined;
};
//#endregion
//#region src/composables/library.d.ts
/**
 * Returns the internal Kirby Panel libraries (dayjs, colors and autosize).
 *
 * @see https://lab.getkirby.com/public/lab/internals/library.colors
 * @see https://lab.getkirby.com/public/lab/internals/library.dayjs
 *
 * @remarks
 * This composable is a simple shortcut to `window.panel.app.$library`.
 */
declare function useLibrary(): _$kirby_types0.PanelLibrary;
//#endregion
//#region src/composables/panel.d.ts
/**
 * Returns the reactive Kirby Panel object.
 *
 * @remarks
 * This composable is a simple shortcut to `window.panel`.
 */
declare function usePanel(): Panel;
//#endregion
//#region src/composables/section.d.ts
/**
 * Provides section methods for loading section data.
 */
declare function useSection(): {
  load: ({
    parent,
    name
  }: {
    parent: string;
    name: string;
  }) => Promise<any>;
};
//#endregion
//#region src/composables/store.d.ts
type PanelAppStoreState = Record<string, any>;
interface PanelAppStoreGetters {
  "content/exists": (arg1?: any, arg2?: any) => any;
  "content/hasChanges": (arg1?: any) => any;
  "content/isCurrent": () => any;
  "content/id": (arg1?: any) => any;
  "content/model": (arg1?: any) => any;
  "content/originals": (arg1?: any) => any;
  "content/values": (arg1?: any) => any;
  "content/changes": (arg1?: any) => any;
}
interface PanelAppStore {
  state: PanelAppStoreState;
  getters: PanelAppStoreGetters;
  commit: (arg1: any, arg2: any, arg3: any) => any;
  dispatch: (arg1: any, arg2: any) => any;
}
/**
 * Returns the Vuex store of the Panel app.
 *
 * @deprecated The Vuex store is removed in Kirby 5. Use the `useContent` composable instead.
 */
declare function useStore(): Readonly<PanelAppStore>;
//#endregion
export { BlockComponentProps, ButtonTheme, DialogButtonProps, DialogFieldProps, DialogSize, FieldsDialogProps, isKirby4, isKirby5, useApi, useApp, useBlock, useContent, useDialog, useHelpers, useI18n, useLibrary, usePanel, useSection, useStore };