kirby-types 1.4.7 → 1.4.9

package/src/panel/libraries.d.ts

@@ -14,14 +14,10 @@ import type { ConfigType, Dayjs, OpUnitType, PluginFunc } from "dayjs";
 // Color Types
 // -----------------------------------------------------------------------------
 
-/**
- * Color format identifiers.
- */
+/** Color format identifiers. */
 export type PanelColorFormat = "hex" | "rgb" | "hsl" | "hsv";
 
-/**
- * RGB color object.
- */
+/** RGB color object. */
 export interface PanelColorRGB {
   /** Red channel (0-255) */
   r: number;
@@ -33,9 +29,7 @@ export interface PanelColorRGB {
   a?: number;
 }
 
-/**
- * HSL color object.
- */
+/** HSL color object. */
 export interface PanelColorHSL {
   /** Hue (0-360) */
   h: number;
@@ -47,9 +41,7 @@ export interface PanelColorHSL {
   a?: number;
 }
 
-/**
- * HSV color object.
- */
+/** HSV color object. */
 export interface PanelColorHSV {
   /** Hue (0-360) */
   h: number;
@@ -61,22 +53,14 @@ export interface PanelColorHSV {
   a?: number;
 }
 
-/**
- * Any color object type.
- */
+/** Any color object type. */
 export type PanelColorObject = PanelColorRGB | PanelColorHSL | PanelColorHSV;
 
-/**
- * Color input (string or object).
- */
+/** Color input (string or object). */
 export type PanelColorInput = string | PanelColorObject;
 
 /**
- * Color library for color space conversions.
- *
- * Provides comprehensive color manipulation including
- * parsing CSS color strings and converting between
- * HEX, RGB, HSL, and HSV color spaces.
+ * Parses CSS color strings and converts between HEX, RGB, HSL, and HSV color spaces.
  *
  * @example
  * ```ts
@@ -87,6 +71,8 @@ export type PanelColorInput = string | PanelColorObject;
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/libraries/colors.js
  * @since 4.0.0
+ * @source panel/src/libraries/colors.js
+ * @source panel/src/libraries/colors-checks.js
  */
 export interface PanelLibraryColors {
   /**
@@ -124,7 +110,7 @@ export interface PanelLibraryColors {
    * Parses a CSS color string to HEX string or color object.
    *
    * Supports:
-   * - HEX: `#fff`, `#ffffff`, `#ffffffff`
+   * - HEX: `#fff`, `#ffff`, `#ffffff`, `#ffffffff`
    * - RGB: `rgb(255 255 255)`, `rgb(255, 255, 255)`, `rgba(255 255 255 / 0.5)`
    * - HSL: `hsl(180 50% 50%)`, `hsl(180deg 50% 50% / 0.5)`
    *
@@ -143,14 +129,14 @@ export interface PanelLibraryColors {
    * @returns Converted color or `false` if invalid
    */
   parseAs: {
-    (string: string, format: "hex"): string | false;
-    (string: string, format: "rgb"): PanelColorRGB | false;
-    (string: string, format: "hsl"): PanelColorHSL | false;
-    (string: string, format: "hsv"): PanelColorHSV | false;
+    (string: string, format: "hex"): string | null | false;
+    (string: string, format: "rgb"): PanelColorRGB | null | false;
+    (string: string, format: "hsl"): PanelColorHSL | null | false;
+    (string: string, format: "hsv"): PanelColorHSV | null | false;
     (
       string: string,
       format?: PanelColorFormat,
-    ): string | PanelColorObject | false;
+    ): string | PanelColorObject | null | false;
   };
 
   /**
@@ -173,9 +159,7 @@ export interface PanelLibraryColors {
 // Dayjs Types
 // -----------------------------------------------------------------------------
 
-/**
- * Pattern part information.
- */
+/** Pattern part information. */
 export interface PanelDayjsPatternPart {
   /** Part index in pattern */
   index: number;
@@ -189,6 +173,7 @@ export interface PanelDayjsPatternPart {
 
 /**
  * Pattern analyzer object returned by `dayjs.pattern()`.
+ * @source panel/src/libraries/dayjs-pattern.js
  */
 export interface PanelDayjsPattern {
   /** Original pattern string */
@@ -214,8 +199,10 @@ export interface PanelDayjsPattern {
 
 /**
  * Kirby plugin extensions for dayjs instances.
- *
- * These methods are added by Kirby's custom dayjs plugins.
+ * @source panel/src/libraries/dayjs-iso.js
+ * @source panel/src/libraries/dayjs-validate.js
+ * @source panel/src/libraries/dayjs-merge.js
+ * @source panel/src/libraries/dayjs-round.js
  */
 export interface PanelDayjsExtensions {
   /**
@@ -229,13 +216,13 @@ export interface PanelDayjsExtensions {
   /**
    * Validates datetime against an upper or lower (min/max) boundary.
    *
-   * @param boundary - Boundary as ISO string
+   * @param boundary - Boundary as ISO string. If falsy, returns `true` when the dayjs instance is valid.
    * @param type - `"min"` or `"max"`
    * @param unit - Comparison unit (default: `"day"`)
    * @returns Whether the date is valid against the boundary
    */
   validate: (
-    boundary: string,
+    boundary: string | null | undefined,
     type: "min" | "max",
     unit?: OpUnitType,
   ) => boolean;
@@ -272,15 +259,14 @@ export interface PanelDayjsExtensions {
   ) => Dayjs & PanelDayjsExtensions;
 }
 
-/**
- * Kirby-extended dayjs instance type.
- *
- * Combines the standard dayjs `Dayjs` class with Kirby's plugin extensions.
- */
+/** Kirby-extended dayjs instance type. */
 export type PanelDayjsInstance = Dayjs & PanelDayjsExtensions;
 
 /**
  * Kirby plugin extensions for the dayjs function (static methods).
+ * @source panel/src/libraries/dayjs-interpret.js
+ * @source panel/src/libraries/dayjs-iso.js
+ * @source panel/src/libraries/dayjs-pattern.js
  */
 export interface PanelDayjsStaticExtensions {
   /**
@@ -334,11 +320,12 @@ export interface PanelDayjsStaticExtensions {
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/libraries/dayjs.js
  * @since 4.0.0
+ * @source panel/src/libraries/dayjs.js
+ * @source panel/src/libraries/dayjs-interpret.js
+ * @source panel/src/libraries/dayjs-iso.js
+ * @source panel/src/libraries/dayjs-pattern.js
  */
 export interface PanelLibraryDayjs extends PanelDayjsStaticExtensions {
-  /**
-   * Creates a dayjs instance.
-   */
   (date?: ConfigType): PanelDayjsInstance;
   (date?: ConfigType, format?: string, strict?: boolean): PanelDayjsInstance;
   (
@@ -348,16 +335,13 @@ export interface PanelLibraryDayjs extends PanelDayjsStaticExtensions {
     strict?: boolean,
   ): PanelDayjsInstance;
 
-  /** Extends dayjs with a plugin */
   extend: <T = unknown>(
     plugin: PluginFunc<T>,
     option?: T,
   ) => typeof import("dayjs");
 
-  /** Gets or sets the global locale */
   locale: (preset?: string, object?: object, isLocal?: boolean) => string;
 
-  /** Type guard for dayjs instances */
   isDayjs: (value: unknown) => value is PanelDayjsInstance;
 
   /** Creates a dayjs instance from Unix timestamp (seconds) */
@@ -374,6 +358,8 @@ export interface PanelLibraryDayjs extends PanelDayjsStaticExtensions {
  * Automatically adjusts textarea height based on content.
  *
  * @see https://www.npmjs.com/package/autosize
+ * @source panel/src/libraries/index.js
+ * @source @types/autosize/index.d.ts
  */
 export interface PanelLibraryAutosize {
   /**
@@ -390,19 +376,21 @@ export interface PanelLibraryAutosize {
    * Triggers a resize update.
    *
    * @param element - Element(s) to update
+   * @returns The input element(s)
    */
-  update: (
-    element: HTMLTextAreaElement | HTMLTextAreaElement[] | NodeList,
-  ) => void;
+  update: <T extends HTMLTextAreaElement | HTMLTextAreaElement[] | NodeList>(
+    element: T,
+  ) => T;
 
   /**
-   * Destroys autosize on element(s).
+   * Removes autosize behavior and restores the original textarea styling.
    *
    * @param element - Element(s) to destroy
+   * @returns The input element(s)
    */
-  destroy: (
-    element: HTMLTextAreaElement | HTMLTextAreaElement[] | NodeList,
-  ) => void;
+  destroy: <T extends HTMLTextAreaElement | HTMLTextAreaElement[] | NodeList>(
+    element: T,
+  ) => T;
 }
 
 // -----------------------------------------------------------------------------
@@ -412,9 +400,6 @@ export interface PanelLibraryAutosize {
 /**
  * Panel libraries available on the Vue prototype as `$library`.
  *
- * Provides utilities for color manipulation, date handling,
- * and textarea auto-resizing.
- *
  * @example
  * ```ts
  * // In a Vue component
@@ -424,20 +409,14 @@ export interface PanelLibraryAutosize {
  * ```
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/libraries/index.js
+ * @source panel/src/libraries/index.js
+ * @source panel/src/libraries/colors.js
+ * @source panel/src/libraries/dayjs.js
  */
 export interface PanelLibrary {
-  /**
-   * Textarea auto-resize library.
-   */
   autosize: PanelLibraryAutosize;
 
-  /**
-   * Color manipulation library.
-   */
   colors: PanelLibraryColors;
 
-  /**
-   * Date manipulation library (extended dayjs).
-   */
   dayjs: PanelLibraryDayjs;
 }

package/src/panel/textarea.d.ts

@@ -16,6 +16,8 @@
  * The toolbar component context available as `this` in button click handlers.
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/components/Forms/Toolbar.vue
+ * @source panel/src/components/Forms/Toolbar/TextareaToolbar.vue
+ * @source panel/src/components/Forms/Input/TextareaInput.vue
  */
 export interface TextareaToolbarContext {
   /**
@@ -24,7 +26,7 @@ export interface TextareaToolbarContext {
    * Available commands:
    * - `"dialog"` - Opens a dialog component
    * - `"insert"` - Inserts the given text at the current selection
-   * - `"prepend"` - Prepends the given text to the current selection/line
+   * - `"prepend"` - Prepends the given text to the current selection
    * - `"toggle"` - Toggles wrapping of current selection (accepts before, after texts)
    * - `"upload"` - Opens the file upload dialog
    * - `"wrap"` - Wraps the current selection with the given text
@@ -53,14 +55,10 @@ export interface TextareaToolbarContext {
     ...args: any[]
   ) => void;
 
-  /**
-   * Closes all dropdowns.
-   */
+  /** Closes all dropdowns. */
   close: () => void;
 
-  /**
-   * Vue translation function.
-   */
+  /** Translates a Kirby translation key, with optional placeholder values. */
   $t: (key: string, ...args: any[]) => string;
 }
 
@@ -92,32 +90,18 @@ export interface TextareaToolbarContext {
  * ```
  *
  * @see https://getkirby.com/docs/reference/plugins/extensions/textarea-buttons
+ * @source panel/src/components/Forms/Toolbar/TextareaToolbar.vue
+ * @source panel/src/components/Forms/Toolbar/Toolbar.vue
  */
 export interface TextareaButton {
-  /**
-   * Display label for the button (appears in tooltip).
-   */
+  /** Display label for the button (appears in tooltip). */
   label: string;
 
-  /**
-   * Icon name from Kirby's icon set.
-   */
+  /** Icon name from Kirby's icon set. */
   icon: string;
 
   /**
-   * Click handler.
-   *
-   * Called with `this` bound to the toolbar component, which provides:
-   * - `this.command(name, ...args)` - Execute a textarea command
-   *
-   * Available commands:
-   * - `dialog` - Opens a dialog component
-   * - `insert` - Inserts text at the cursor (can be a function receiving input and selection)
-   * - `prepend` - Prepends text to the current line
-   * - `toggle` - Toggles wrapping of selection with before/after text
-   * - `upload` - Opens the file upload dialog
-   * - `wrap` - Wraps the selection with given text
-   * - `file` - Opens the file picker
+   * Click handler. `this` is bound to the toolbar component (see {@link TextareaToolbarContext}), so `this.command(...)` is available.
    *
    * @example
    * ```js
@@ -167,29 +151,19 @@ export interface TextareaButton {
    */
   dropdown?: TextareaDropdownItem[];
 
-  /**
-   * Conditional rendering. If false, the button won't be shown.
-   */
+  /** Conditional rendering. If false, the button won't be shown. */
   when?: boolean;
 
-  /**
-   * Disables the button.
-   */
+  /** Disables the button. */
   disabled?: boolean;
 
-  /**
-   * Sets the aria-current attribute for active state styling.
-   */
+  /** Sets the aria-current attribute for active state styling. */
   current?: boolean | string;
 
-  /**
-   * Alternative tooltip text (defaults to label).
-   */
+  /** Tooltip text used as a fallback when `label` is not set. */
   title?: string;
 
-  /**
-   * Custom CSS class for the button.
-   */
+  /** Custom CSS class for the button. */
   class?: string;
 }
 
@@ -237,18 +211,12 @@ export interface TextareaDropdownItem {
    */
   click: () => void;
 
-  /**
-   * Conditional rendering. If false, the item won't be shown.
-   */
+  /** Conditional rendering. If false, the item won't be shown. */
   when?: boolean;
 
-  /**
-   * Disables the dropdown item.
-   */
+  /** Disables the dropdown item. */
   disabled?: boolean;
 
-  /**
-   * Sets the aria-current attribute for active state styling.
-   */
+  /** Sets the aria-current attribute for active state styling. */
   current?: boolean | string;
 }

package/src/panel/writer.d.ts

@@ -47,6 +47,8 @@ import type {
  * when using class-based extensions, or that is passed to event handlers.
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/components/Forms/Writer/Editor.js
+ * @source panel/src/components/Forms/Writer/Editor.js
+ * @source panel/src/components/Forms/Writer/Emitter.js
  */
 export interface WriterEditor {
   // ---------------------------------------------------------------------------
@@ -65,7 +67,7 @@ export interface WriterEditor {
   commands: Record<string, (attrs?: any) => any>;
   /** The DOM element the editor is mounted to */
   element: HTMLElement | null;
-  /** Registered event handlers */
+  /** Event handlers passed via `options.events` */
   events: Record<string, (...args: any[]) => any>;
   /** The extensions manager instance */
   extensions: WriterExtensions;
@@ -233,7 +235,7 @@ export interface WriterEditorOptions {
 export interface WriterExtensions {
   /** All registered extension instances */
   extensions: (WriterExtension | WriterMarkExtension | WriterNodeExtension)[];
-  /** ProseMirror EditorView (set after editor initialization) */
+  /** ProseMirror EditorView assigned by the editor after initialization */
   view: EditorView;
 
   /** Returns toolbar buttons for the given type */
@@ -260,6 +262,10 @@ export interface WriterExtensions {
  * Buttons appear in the Writer toolbar and trigger commands when clicked.
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/components/Forms/Writer/Toolbar.vue
+ * @source panel/src/components/Forms/Writer/Extensions.js
+ * @source panel/src/components/Forms/Writer/Toolbar.vue
+ * @source panel/src/components/Forms/Writer/Nodes/Heading.js
+ * @source panel/src/components/Forms/Writer/Marks/Link.js
  */
 export interface WriterToolbarButton {
   /** Unique identifier (defaults to extension name) */
@@ -278,7 +284,7 @@ export interface WriterToolbarButton {
   separator?: boolean;
   /** Whether this is an inline node button (shown inline, not in dropdown) */
   inline?: boolean;
-  /** Node types when this button should be visible */
+  /** Names of active node types under which this dropdown button stays enabled */
   when?: string[];
 }
 
@@ -294,6 +300,7 @@ export interface WriterToolbarButton {
  * extension methods via the context object.
  *
  * @see https://github.com/getkirby/kirby/tree/main/panel/src/components/Forms/Writer/Utils
+ * @source panel/src/components/Forms/Writer/Utils/index.js
  */
 export interface WriterUtils {
   // ---------------------------------------------------------------------------
@@ -364,9 +371,16 @@ export interface WriterUtils {
    *
    * @param type - The node type to insert
    * @param attrs - Optional attributes for the node
+   * @param content - Optional initial content for the node
+   * @param marks - Optional marks to apply to the node
    * @returns A ProseMirror command
    */
-  insertNode: (type: NodeType, attrs?: Record<string, any>) => Command;
+  insertNode: (
+    type: NodeType,
+    attrs?: Record<string, any>,
+    content?: Fragment | ProseMirrorNode | ProseMirrorNode[] | null,
+    marks?: Mark[] | null,
+  ) => Command;
 
   /**
    * Creates an input rule that applies a mark when the pattern matches.
@@ -402,7 +416,7 @@ export interface WriterUtils {
   markPasteRule: (
     regexp: RegExp,
     type: MarkType,
-    getAttrs?: (match: string) => Record<string, any>,
+    getAttrs?: (match: RegExpMatchArray) => Record<string, any>,
   ) => Plugin;
 
   /**
@@ -444,11 +458,11 @@ export interface WriterUtils {
   ) => boolean;
 
   /**
-   * Creates a paste rule that applies a mark to pasted URLs matching the pattern.
+   * Creates a paste rule that applies a mark to pasted text matching the pattern.
    *
-   * @param regexp - The pattern to match URLs
+   * @param regexp - The pattern to match
    * @param type - The mark type to apply
-   * @param getAttrs - Optional function to compute mark attributes from the URL
+   * @param getAttrs - Optional function to compute mark attributes from the matched string
    * @returns A ProseMirror plugin
    */
   pasteRule: (
@@ -533,6 +547,7 @@ export interface WriterUtils {
  * ```
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/components/Forms/Writer/Extensions.js
+ * @source panel/src/components/Forms/Writer/Extensions.js
  */
 export interface WriterMarkContext {
   /** The ProseMirror schema with all registered nodes and marks */
@@ -544,9 +559,7 @@ export interface WriterMarkContext {
 }
 
 /**
- * Context passed to node extension methods.
- *
- * Similar to WriterMarkContext but provides a NodeType instead of MarkType.
+ * Context passed to node extension methods (`commands`, `keys`, `inputRules`, `pasteRules`, `plugins`).
  *
  * @example
  * ```js
@@ -558,6 +571,7 @@ export interface WriterMarkContext {
  * ```
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/components/Forms/Writer/Extensions.js
+ * @source panel/src/components/Forms/Writer/Extensions.js
  */
 export interface WriterNodeContext {
   /** The ProseMirror schema with all registered nodes and marks */
@@ -575,6 +589,7 @@ export interface WriterNodeContext {
  * are provided.
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/components/Forms/Writer/Extensions.js
+ * @source panel/src/components/Forms/Writer/Extensions.js
  */
 export interface WriterExtensionContext {
   /** The ProseMirror schema with all registered nodes and marks */
@@ -613,34 +628,29 @@ export interface WriterExtensionContext {
  * ```
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/components/Forms/Writer/Extension.js
+ * @source panel/src/components/Forms/Writer/Extension.js
+ * @source panel/src/components/Forms/Writer/Extensions/History.js
+ * @source panel/src/components/Forms/Writer/Extensions/Insert.js
+ * @source panel/src/components/Forms/Writer/Extensions/Keys.js
+ * @source panel/src/components/Forms/Writer/Extensions/Toolbar.js
  */
 export interface WriterExtension {
-  /**
-   * Unique name of the extension.
-   */
+  /** Unique name of the extension. */
   name?: string;
 
-  /** Extension type identifier */
+  /** Discriminator value, always "extension" for generic extensions */
   type?: string;
 
-  /**
-   * The editor instance, available after `bindEditor()` is called.
-   */
+  /** The editor instance, available after `bindEditor()` is called. */
   editor?: WriterEditor;
 
-  /**
-   * Merged extension options from `defaults` and constructor options.
-   */
+  /** Merged extension options from `defaults` and constructor options. */
   options?: Record<string, any>;
 
-  /**
-   * Default options for the extension.
-   */
+  /** Default options for the extension. */
   defaults?: Record<string, any>;
 
-  /**
-   * Called after the editor is bound to the extension.
-   */
+  /** Called after the editor is bound to the extension. */
   init?: () => null | void;
 
   /**
@@ -722,6 +732,19 @@ export interface WriterExtension {
  * ```
  *
  * @see https://getkirby.com/docs/reference/plugins/extensions/writer-marks-nodes
+ * @source panel/src/components/Forms/Writer/Mark.js
+ * @source panel/src/components/Forms/Writer/Extension.js
+ * @source panel/src/components/Forms/Writer/Extensions.js
+ * @source panel/src/components/Forms/Writer/Marks/Bold.js
+ * @source panel/src/components/Forms/Writer/Marks/Clear.js
+ * @source panel/src/components/Forms/Writer/Marks/Code.js
+ * @source panel/src/components/Forms/Writer/Marks/Email.js
+ * @source panel/src/components/Forms/Writer/Marks/Italic.js
+ * @source panel/src/components/Forms/Writer/Marks/Link.js
+ * @source panel/src/components/Forms/Writer/Marks/Strike.js
+ * @source panel/src/components/Forms/Writer/Marks/Sub.js
+ * @source panel/src/components/Forms/Writer/Marks/Sup.js
+ * @source panel/src/components/Forms/Writer/Marks/Underline.js
  */
 export interface WriterMarkExtension {
   // ---------------------------------------------------------------------------
@@ -736,7 +759,6 @@ export interface WriterMarkExtension {
    */
   name?: string;
 
-  /** Extension type identifier */
   type?: "mark";
 
   /**
@@ -965,6 +987,20 @@ export interface WriterMarkExtension {
  * ```
  *
  * @see https://getkirby.com/docs/reference/plugins/extensions/writer-marks-nodes
+ * @source panel/src/components/Forms/Writer/Node.js
+ * @source panel/src/components/Forms/Writer/Extension.js
+ * @source panel/src/components/Forms/Writer/Extensions.js
+ * @source panel/src/components/Forms/Writer/Nodes/BulletList.js
+ * @source panel/src/components/Forms/Writer/Nodes/Doc.js
+ * @source panel/src/components/Forms/Writer/Nodes/HardBreak.js
+ * @source panel/src/components/Forms/Writer/Nodes/Heading.js
+ * @source panel/src/components/Forms/Writer/Nodes/HorizontalRule.js
+ * @source panel/src/components/Forms/Writer/Nodes/ListDoc.js
+ * @source panel/src/components/Forms/Writer/Nodes/ListItem.js
+ * @source panel/src/components/Forms/Writer/Nodes/OrderedList.js
+ * @source panel/src/components/Forms/Writer/Nodes/Paragraph.js
+ * @source panel/src/components/Forms/Writer/Nodes/Quote.js
+ * @source panel/src/components/Forms/Writer/Nodes/Text.js
  */
 export interface WriterNodeExtension {
   // ---------------------------------------------------------------------------
@@ -979,7 +1015,6 @@ export interface WriterNodeExtension {
    */
   name?: string;
 
-  /** Extension type identifier */
   type?: "node";
 
   /**
@@ -1007,14 +1042,10 @@ export interface WriterNodeExtension {
    */
   button?: WriterToolbarButton | WriterToolbarButton[];
 
-  /**
-   * Default options for the extension.
-   */
+  /** Default options for the extension. */
   defaults?: Record<string, any>;
 
-  /**
-   * ProseMirror node schema definition.
-   */
+  /** ProseMirror node schema definition. */
   schema?: NodeSpec;
 
   /**