kirby-types 1.3.1 → 1.4.0

package/index.d.ts

@@ -10,26 +10,7 @@ export type {
 } from "./src/blocks";
 
 // Blueprint types
-export type {
-  KirbyAnyFieldProps,
-  KirbyBlocksFieldProps,
-  KirbyDateFieldProps,
-  KirbyFieldProps,
-  KirbyFieldsetGroup,
-  KirbyFieldsetProps,
-  KirbyFieldsetTab,
-  KirbyFilesFieldProps,
-  KirbyLayoutFieldProps,
-  KirbyNumberFieldProps,
-  KirbyObjectFieldProps,
-  KirbyOption,
-  KirbyOptionsFieldProps,
-  KirbyStructureColumn,
-  KirbyStructureFieldProps,
-  KirbyTextFieldProps,
-  KirbyToggleFieldProps,
-  KirbyWriterFieldProps,
-} from "./src/blueprint";
+export type * from "./src/blueprint";
 
 // KQL types
 export type {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kirby-types",
   "type": "module",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "packageManager": "pnpm@10.27.0",
   "description": "TypeScript types for Kirby Panel plugins and headless CMS usage",
   "author": "Johann Schopplich <hello@johannschopplich.com>",

package/src/blueprint.d.ts

@@ -110,12 +110,12 @@ export interface KirbyFieldProps {
 // =============================================================================
 
 /**
- * Props for text and textarea fields.
+ * Props for text fields.
  *
  * @see https://getkirby.com/docs/reference/panel/fields/text
  */
 export interface KirbyTextFieldProps extends KirbyFieldProps {
-  type: "text" | "textarea" | "slug" | "url" | "email" | "tel";
+  type: "text" | "slug" | "url" | "email" | "tel";
   /** Value converter: `lower`, `upper`, `ucfirst`, `slug` */
   converter?: "lower" | "upper" | "ucfirst" | "slug";
   /** Whether to show character counter */
@@ -133,6 +133,34 @@ export interface KirbyTextFieldProps extends KirbyFieldProps {
   value?: string;
 }
 
+/**
+ * Props for textarea fields.
+ *
+ * @see https://getkirby.com/docs/reference/panel/fields/textarea
+ */
+export interface KirbyTextareaFieldProps extends KirbyFieldProps {
+  type: "textarea";
+  /** Format buttons: true/false or array of allowed buttons (headlines, italic, bold, link, email, file, code, ul, ol) */
+  buttons?: boolean | string[];
+  /** Whether to show character counter */
+  counter: boolean;
+  /** File picker options (query string or config object) */
+  files?: string | Record<string, any>;
+  /** Font family: `sans-serif` or `monospace` */
+  font: "sans-serif" | "monospace";
+  /** Maximum character length */
+  maxlength?: number;
+  /** Minimum character length */
+  minlength?: number;
+  /** Textarea size */
+  size?: "small" | "medium" | "large" | "huge";
+  /** Whether spellcheck is enabled */
+  spellcheck: boolean;
+  /** Upload configuration */
+  uploads?: false | string | Record<string, any>;
+  value?: string;
+}
+
 /**
  * Props for number fields.
  *
@@ -200,6 +228,8 @@ export interface KirbyDateFieldProps extends KirbyFieldProps {
   calendar?: boolean;
   /** Date/time display format (dayjs tokens) */
   display?: string;
+  /** Storage format for the value (from datetime mixin) */
+  format?: string;
   /** Maximum date/time */
   max?: string;
   /** Minimum date/time */
@@ -243,6 +273,8 @@ export interface KirbyFilesFieldProps extends KirbyFieldProps {
   image?: Record<string, any>;
   /** Info text template for each item */
   info?: string;
+  /** Display layout for selected items */
+  layout?: "list" | "cardlets" | "cards";
   /** Whether each item should be clickable */
   link?: boolean;
   /** Maximum number of items */
@@ -255,10 +287,16 @@ export interface KirbyFilesFieldProps extends KirbyFieldProps {
   query?: string;
   /** Whether to show search field in picker */
   search?: boolean;
+  /** Layout size for cards */
+  size?: "tiny" | "small" | "medium" | "large" | "huge" | "full" | "auto";
   /** Whether to store `"uuid"` or `"id"` in content file */
   store?: "uuid" | "id";
+  /** Include subpages in picker (pages field only) */
+  subpages?: boolean;
   /** Text template for each item */
   text?: string;
+  /** Upload configuration (files field only) */
+  uploads?: false | string | Record<string, any>;
   /** Selected items (transformed picker data, not raw IDs) */
   value?: KirbyPickerItem[];
 }
@@ -446,6 +484,8 @@ export interface KirbyBlocksFieldProps extends KirbyFieldProps {
   max?: number;
   /** Minimum number of blocks */
   min?: number;
+  /** Format JSON output with indentation */
+  pretty?: boolean;
   value?: KirbyBlockValue[];
 }
 
@@ -488,7 +528,7 @@ export interface KirbyLayoutFieldProps extends KirbyFieldProps {
 export interface KirbyWriterFieldProps extends KirbyFieldProps {
   type: "writer";
   /** Whether to show character counter */
-  counter?: boolean;
+  counter: boolean;
   /** Available heading levels (1-6) */
   headings?: number[];
   /** Whether only inline formatting is allowed */
@@ -506,6 +546,61 @@ export interface KirbyWriterFieldProps extends KirbyFieldProps {
   value?: string;
 }
 
+/**
+ * Props for entries fields.
+ * A simplified structure field for single-field entries.
+ *
+ * @since Kirby 5.0.0
+ * @see https://getkirby.com/docs/reference/panel/fields/entries
+ */
+export interface KirbyEntriesFieldProps extends KirbyFieldProps {
+  type: "entries";
+  /** Placeholder text when no entries exist */
+  empty?: string;
+  /** Single field definition for entry items */
+  field: KirbyFieldProps;
+  /** Maximum number of entries */
+  max?: number;
+  /** Minimum number of entries */
+  min?: number;
+  /** Whether entries are sortable via drag & drop */
+  sortable?: boolean;
+  value?: any[];
+}
+
+/**
+ * Stats report item for the stats field.
+ */
+export interface KirbyStatsReport {
+  /** Report label */
+  label: string;
+  /** Report value */
+  value: string | number;
+  /** Additional info text */
+  info?: string;
+  /** Link URL */
+  link?: string;
+  /** Icon identifier */
+  icon?: string;
+  /** Color theme */
+  theme?: string;
+}
+
+/**
+ * Props for stats fields.
+ * Display stats/metrics as cards.
+ *
+ * @since Kirby 5.1.0
+ * @see https://getkirby.com/docs/reference/panel/fields/stats
+ */
+export interface KirbyStatsFieldProps extends KirbyFieldProps {
+  type: "stats";
+  /** Array of report objects or query string */
+  reports: KirbyStatsReport[] | string;
+  /** Card size */
+  size?: "tiny" | "small" | "medium" | "large";
+}
+
 // =============================================================================
 // Block & Layout Values
 // =============================================================================
@@ -644,6 +739,7 @@ export interface KirbyFieldsetGroup {
 export type KirbyAnyFieldProps =
   | KirbyFieldProps
   | KirbyTextFieldProps
+  | KirbyTextareaFieldProps
   | KirbyNumberFieldProps
   | KirbyOptionsFieldProps
   | KirbyToggleFieldProps
@@ -655,6 +751,8 @@ export type KirbyAnyFieldProps =
   | KirbyLinkFieldProps
   | KirbyStructureFieldProps
   | KirbyObjectFieldProps
+  | KirbyEntriesFieldProps
   | KirbyBlocksFieldProps
   | KirbyLayoutFieldProps
-  | KirbyWriterFieldProps;
+  | KirbyWriterFieldProps
+  | KirbyStatsFieldProps;

package/src/panel/index.d.ts

@@ -18,7 +18,15 @@
  * @since 4.0.0
  */
 
-import type { ComponentPublicInstance, VueConstructor } from "vue";
+import type {
+  ComponentOptions,
+  ComponentPublicInstance,
+  PluginFunction,
+  PluginObject,
+  VNode,
+  VueConstructor,
+  h as VueH,
+} from "vue";
 import type { PanelApi } from "./api";
 import type {
   PanelContext,
@@ -222,6 +230,32 @@ export type PanelApp = InstanceType<VueConstructor> & {
   $esc: (string: string) => string;
 };
 
+// =============================================================================
+// Plugin Component Types
+// =============================================================================
+
+/**
+ * Vue component options for Panel plugin extensions.
+ *
+ * Components can be defined as:
+ * - Vue component options object with template or render function
+ * - Component that extends another component by name
+ */
+export type PanelComponentExtension =
+  | ComponentPublicInstance
+  | ComponentOptions<any>
+  | {
+      /** Extend another component by name (e.g., `"k-text-field"`) */
+      extends?: string | ComponentPublicInstance;
+      /** Named mixins (e.g., `"dialog"`, `"drawer"`, `"section"`) or component objects */
+      mixins?: (string | ComponentOptions<any>)[];
+      /** Template string */
+      template?: string;
+      /** Render function */
+      render?: (h: typeof VueH) => VNode;
+      [key: string]: any;
+    };
+
 // =============================================================================
 // Panel Configuration
 // =============================================================================
@@ -421,6 +455,175 @@ export interface PanelRequestResponse {
   };
 }
 
+// =============================================================================
+// Panel Plugin Extensions (window.panel.plugin)
+// =============================================================================
+
+/**
+ * Extensions object passed to `window.panel.plugin()`.
+ *
+ * @example
+ * ```ts
+ * window.panel.plugin("my-plugin", {
+ *   // Custom block types
+ *   blocks: {
+ *     video: `<k-block-video :source="content.source" />`
+ *   },
+ *
+ *   // Custom field types
+ *   fields: {
+ *     "color-picker": {
+ *       extends: "k-text-field",
+ *       template: `<k-field v-bind="$props">...</k-field>`
+ *     }
+ *   },
+ *
+ *   // Custom sections
+ *   sections: {
+ *     stats: {
+ *       template: `<div>{{ data }}</div>`
+ *     }
+ *   },
+ *
+ *   // Textarea toolbar buttons
+ *   textareaButtons: {
+ *     timestamp: {
+ *       label: "Insert Timestamp",
+ *       icon: "clock",
+ *       click() {
+ *         this.command("insert", () => new Date().toISOString());
+ *       }
+ *     }
+ *   },
+ *
+ *   // Writer marks and nodes
+ *   writerMarks: {
+ *     highlight: {
+ *       button: { icon: "highlight", label: "Highlight" },
+ *       schema: {
+ *         parseDOM: [{ tag: "mark" }],
+ *         toDOM: () => ["mark", 0]
+ *       }
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @see https://getkirby.com/docs/reference/plugins/extensions
+ */
+export interface PanelPluginExtensions {
+  /**
+   * Custom block types for the blocks field.
+   *
+   * Can be either a template string (shorthand) or a component options object.
+   * Registered as `k-block-type-${name}` components that automatically
+   * extend `k-block-type-default`.
+   *
+   * @see https://getkirby.com/docs/reference/plugins/extensions/blocks
+   */
+  blocks?: Record<string, string | PanelComponentExtension>;
+
+  /**
+   * Vue components to register globally in the Panel.
+   *
+   * @see https://getkirby.com/docs/reference/plugins/extensions/components
+   */
+  components?: Record<string, PanelComponentExtension>;
+
+  /**
+   * Custom field types.
+   *
+   * Registered as `k-${name}-field` components.
+   *
+   * @see https://getkirby.com/docs/reference/plugins/extensions/fields
+   */
+  fields?: Record<string, PanelComponentExtension>;
+
+  /**
+   * SVG icon definitions.
+   *
+   * @see https://getkirby.com/docs/reference/plugins/extensions/icons
+   */
+  icons?: Record<string, string>;
+
+  /**
+   * Custom section types.
+   *
+   * Registered as `k-${name}-section` components.
+   * The `section` mixin is automatically prepended to the mixins array.
+   *
+   * @see https://getkirby.com/docs/reference/plugins/extensions/sections
+   */
+  sections?: Record<string, PanelComponentExtension>;
+
+  /**
+   * View button components.
+   *
+   * Registered as `k-${name}-view-button` components.
+   *
+   * @see https://getkirby.com/docs/reference/plugins/extensions/view-buttons
+   */
+  viewButtons?: Record<string, PanelComponentExtension>;
+
+  /**
+   * Vue plugins to install via `Vue.use()`.
+   *
+   * Can be used to add global methods, directives, or mixins.
+   */
+  use?: Record<string, PluginObject<any> | PluginFunction<any>>;
+
+  /**
+   * Callback executed after the Panel Vue app is created.
+   *
+   * Receives the Vue app instance as parameter.
+   *
+   * @example
+   * ```ts
+   * window.panel.plugin("my-plugin", {
+   *   created(app) {
+   *     console.log("Panel app created", app);
+   *   }
+   * });
+   * ```
+   */
+  created?: (app: PanelApp) => void;
+
+  /**
+   * Custom login form component.
+   *
+   * Replaces the default login form with a custom implementation.
+   */
+  login?: PanelComponentExtension;
+
+  /**
+   * Custom textarea toolbar buttons.
+   *
+   * @see https://getkirby.com/docs/reference/plugins/extensions/textarea-buttons
+   */
+  textareaButtons?: Record<string, TextareaButton>;
+
+  /**
+   * Arbitrary third-party plugin data.
+   *
+   * Can be used to pass configuration to other plugins.
+   */
+  thirdParty?: Record<string, any>;
+
+  /**
+   * Custom Writer inline formatting marks.
+   *
+   * @see https://getkirby.com/docs/reference/plugins/extensions/writer-marks
+   */
+  writerMarks?: Record<string, WriterMarkExtension>;
+
+  /**
+   * Custom Writer block-level nodes.
+   *
+   * @see https://getkirby.com/docs/reference/plugins/extensions/writer-nodes
+   */
+  writerNodes?: Record<string, WriterNodeExtension>;
+}
+
 // =============================================================================
 // Panel Plugins
 // =============================================================================
@@ -769,6 +972,37 @@ export interface Panel {
    */
   overlays: () => ("drawer" | "dialog")[];
 
+  /**
+   * Registers a Panel plugin with its extensions.
+   *
+   * @param name - Unique plugin identifier (typically vendor/plugin-name)
+   * @param extensions - Plugin extensions to register
+   *
+   * @example
+   * ```ts
+   * window.panel.plugin("my-plugin", {
+   *   fields: {
+   *     "color-picker": {
+   *       extends: "k-text-field",
+   *       template: `<k-field v-bind="$props">...</k-field>`
+   *     }
+   *   },
+   *   textareaButtons: {
+   *     timestamp: {
+   *       label: "Insert Timestamp",
+   *       icon: "clock",
+   *       click() {
+   *         this.command("insert", () => new Date().toISOString());
+   *       }
+   *     }
+   *   }
+   * });
+   * ```
+   *
+   * @see https://getkirby.com/docs/reference/plugins/extensions
+   */
+  plugin: (name: string, extensions: PanelPluginExtensions) => void;
+
   /**
    * Sends a POST request through the Panel router.
    *

package/src/panel/writer.d.ts

@@ -268,7 +268,7 @@ export interface WriterToolbarButton {
   command?: string;
   /** Icon name from Kirby's icon set */
   icon: string;
-  /** Display label (usually translated via `window.panel.$t()`) */
+  /** Display label (usually translated via `window.panel.t()`) */
   label: string;
   /** Extension name this button belongs to */
   name?: string;