kirby-types 1.2.0 → 1.3.0

package/src/blueprint.d.ts

@@ -0,0 +1,660 @@
+/**
+ * Blueprint type definitions for Kirby.
+ *
+ * Types representing field, fieldset, and option structures as returned
+ * by Kirby's Form and Fieldset classes when serialized via `toArray()`.
+ *
+ * @see https://getkirby.com/docs/reference/panel/blueprints
+ */
+
+// =============================================================================
+// Field Options
+// =============================================================================
+
+/**
+ * Rendered option for select, radio, checkbox, and toggle fields.
+ *
+ * Represents the output of `Option->render()` which is used by
+ * fields with the options mixin (select, radio, checkboxes, etc.).
+ *
+ * @see https://github.com/getkirby/kirby/blob/main/src/Option/Option.php
+ *
+ * @example
+ * ```ts
+ * const option: KirbyOption = {
+ *   disabled: false,
+ *   icon: "page",
+ *   info: "Additional info",
+ *   text: "Draft",
+ *   value: "draft"
+ * };
+ * ```
+ */
+export interface KirbyOption {
+  /** Whether the option is disabled */
+  disabled: boolean;
+  /** Optional icon identifier */
+  icon: string | null;
+  /** Optional additional info text */
+  info: string | null;
+  /** Display text (falls back to value if not set) */
+  text: string | null;
+  /** Option value stored in content file */
+  value: string | number | null;
+}
+
+// =============================================================================
+// Field Props (Base)
+// =============================================================================
+
+/**
+ * Base field props shared by all field types.
+ *
+ * Represents the common properties returned by `Field->toArray()`.
+ * Field-specific types extend this with additional props.
+ *
+ * @see https://github.com/getkirby/kirby/blob/main/src/Form/Field.php
+ *
+ * @example
+ * ```ts
+ * const field: KirbyFieldProps = {
+ *   name: "title",
+ *   type: "text",
+ *   label: "Title",
+ *   required: true,
+ *   width: "1/2"
+ * };
+ * ```
+ */
+export interface KirbyFieldProps {
+  /** Optional text shown after the input */
+  after?: string;
+  /** Whether field receives focus on form load */
+  autofocus: boolean;
+  /** Optional text shown before the input */
+  before?: string;
+  /** Default value for new content */
+  default?: any;
+  /** Whether the field is disabled */
+  disabled: boolean;
+  /** Help text below the field (supports Markdown) */
+  help?: string;
+  /** Whether the field is hidden via `when` condition */
+  hidden: boolean;
+  /** Icon identifier */
+  icon?: string;
+  /** Human-readable field label */
+  label?: string;
+  /** Field identifier within the blueprint */
+  name: string;
+  /** Placeholder text for empty fields */
+  placeholder?: string;
+  /** Whether the field is required */
+  required: boolean;
+  /** Whether field values can be saved (false for info/headline fields) */
+  saveable: boolean;
+  /** Whether the field is translatable in multi-lang setups */
+  translate: boolean;
+  /** Field type identifier (e.g., `text`, `textarea`, `blocks`) */
+  type: string;
+  /** Current field value */
+  value?: any;
+  /** Conditional visibility rules */
+  when?: Record<string, any>;
+  /** Field width in grid (e.g., `1/1`, `1/2`, `1/3`) */
+  width: string;
+}
+
+// =============================================================================
+// Field Props (Type-Specific)
+// =============================================================================
+
+/**
+ * Props for text and textarea fields.
+ *
+ * @see https://getkirby.com/docs/reference/panel/fields/text
+ */
+export interface KirbyTextFieldProps extends KirbyFieldProps {
+  type: "text" | "textarea" | "slug" | "url" | "email" | "tel";
+  /** Value converter: `lower`, `upper`, `ucfirst`, `slug` */
+  converter?: "lower" | "upper" | "ucfirst" | "slug";
+  /** Whether to show character counter */
+  counter: boolean;
+  /** Font family: `sans-serif` or `monospace` */
+  font: "sans-serif" | "monospace";
+  /** Maximum character length */
+  maxlength?: number;
+  /** Minimum character length */
+  minlength?: number;
+  /** Validation regex pattern */
+  pattern?: string;
+  /** Whether spellcheck is enabled */
+  spellcheck: boolean;
+  value?: string;
+}
+
+/**
+ * Props for number fields.
+ *
+ * @see https://getkirby.com/docs/reference/panel/fields/number
+ */
+export interface KirbyNumberFieldProps extends KirbyFieldProps {
+  type: "number";
+  /** Maximum value */
+  max?: number;
+  /** Minimum value */
+  min?: number;
+  /** Step increment, or `"any"` to allow any decimal value */
+  step?: number | "any";
+  value?: number;
+}
+
+/**
+ * Props for select, radio, checkboxes, multiselect, and toggles fields.
+ *
+ * @see https://getkirby.com/docs/reference/panel/fields/select
+ */
+export interface KirbyOptionsFieldProps extends KirbyFieldProps {
+  type: "select" | "radio" | "checkboxes" | "multiselect" | "toggles";
+  /** Input acceptance mode for multiselect: `"all"` or `"options"` */
+  accept?: "all" | "options";
+  /** Whether to show batch select toggle (checkboxes only) */
+  batch?: boolean;
+  /** Number of columns for layout (radio, checkboxes) */
+  columns?: number;
+  /** Whether toggles should span full width */
+  grow?: boolean;
+  /** Whether to show labels for icon-only toggles */
+  labels?: boolean;
+  /** Maximum number of selected options (checkboxes, multiselect) */
+  max?: number;
+  /** Minimum number of selected options (checkboxes, multiselect) */
+  min?: number;
+  /** Available options */
+  options: KirbyOption[];
+  /** Whether a toggle can be deactivated on click (toggles only) */
+  reset?: boolean;
+  value?: string | string[];
+}
+
+/**
+ * Props for toggle fields.
+ *
+ * @see https://getkirby.com/docs/reference/panel/fields/toggle
+ */
+export interface KirbyToggleFieldProps extends KirbyFieldProps {
+  type: "toggle";
+  /** Text shown when toggle is off */
+  text?: string | [string, string];
+  value?: boolean;
+}
+
+/**
+ * Props for date and time fields.
+ *
+ * @see https://getkirby.com/docs/reference/panel/fields/date
+ */
+export interface KirbyDateFieldProps extends KirbyFieldProps {
+  type: "date" | "time";
+  /** Whether to show the dropdown calendar (date only) */
+  calendar?: boolean;
+  /** Date/time display format (dayjs tokens) */
+  display?: string;
+  /** Maximum date/time */
+  max?: string;
+  /** Minimum date/time */
+  min?: string;
+  /** Hour notation: `12` or `24` (time only) */
+  notation?: 12 | 24;
+  /** Step configuration for rounding (size and unit like `"minute"`, `"hour"`, `"day"`) */
+  step?: { size: number; unit: string };
+  /** Whether to include time picker (date only) */
+  time?: boolean | Record<string, any>;
+  value?: string;
+}
+
+/**
+ * Picker item data as returned by the Panel API.
+ */
+export interface KirbyPickerItem {
+  /** Item identifier (UUID or ID) */
+  id: string;
+  /** Display text */
+  text?: string;
+  /** Additional info text */
+  info?: string;
+  /** Image configuration */
+  image?: Record<string, any>;
+  /** Item link URL */
+  link?: string;
+  [key: string]: any;
+}
+
+/**
+ * Props for files, pages, and users fields.
+ *
+ * @see https://getkirby.com/docs/reference/panel/fields/files
+ */
+export interface KirbyFilesFieldProps extends KirbyFieldProps {
+  type: "files" | "pages" | "users";
+  /** Placeholder text when no items are selected */
+  empty?: string;
+  /** Image settings for each item */
+  image?: Record<string, any>;
+  /** Info text template for each item */
+  info?: string;
+  /** Whether each item should be clickable */
+  link?: boolean;
+  /** Maximum number of items */
+  max?: number;
+  /** Minimum number of items */
+  min?: number;
+  /** Whether multiple selection is allowed */
+  multiple: boolean;
+  /** Query for available items */
+  query?: string;
+  /** Whether to show search field in picker */
+  search?: boolean;
+  /** Whether to store `"uuid"` or `"id"` in content file */
+  store?: "uuid" | "id";
+  /** Text template for each item */
+  text?: string;
+  /** Selected items (transformed picker data, not raw IDs) */
+  value?: KirbyPickerItem[];
+}
+
+/**
+ * Props for color fields.
+ *
+ * @see https://getkirby.com/docs/reference/panel/fields/color
+ */
+export interface KirbyColorFieldProps extends KirbyFieldProps {
+  type: "color";
+  /** Whether to allow alpha transparency */
+  alpha?: boolean;
+  /** CSS color format to display and store */
+  format?: "hex" | "rgb" | "hsl";
+  /** Color picker mode */
+  mode?: "picker" | "input" | "options";
+  /** Predefined color options */
+  options?: KirbyColorOption[];
+  value?: string;
+}
+
+/**
+ * Color option for the color field.
+ */
+export interface KirbyColorOption {
+  /** Color value (hex, rgb, or hsl) */
+  value: string;
+  /** Optional display text/label */
+  text?: string;
+}
+
+/**
+ * Props for range fields (slider input).
+ *
+ * @see https://getkirby.com/docs/reference/panel/fields/range
+ */
+export interface KirbyRangeFieldProps extends KirbyFieldProps {
+  type: "range";
+  /** Maximum value (default: 100) */
+  max?: number;
+  /** Minimum value */
+  min?: number;
+  /** Step increment, or `"any"` for any decimal value */
+  step?: number | "any";
+  /** Tooltip configuration (before/after text) or boolean to enable/disable */
+  tooltip?: boolean | { before?: string; after?: string };
+  value?: number;
+}
+
+/**
+ * Search configuration for tags field.
+ */
+export interface KirbyTagsSearch {
+  /** Maximum items to display in dropdown */
+  display?: number;
+  /** Minimum characters before search starts */
+  min?: number;
+}
+
+/**
+ * Props for tags fields.
+ *
+ * @see https://getkirby.com/docs/reference/panel/fields/tags
+ */
+export interface KirbyTagsFieldProps extends KirbyFieldProps {
+  type: "tags";
+  /** Input acceptance: `"all"` for any input, `"options"` for predefined only */
+  accept?: "all" | "options";
+  /** Tag icon */
+  icon?: string;
+  /** Display layout: `"list"` for full-width tags */
+  layout?: "list" | null;
+  /** Maximum number of tags */
+  max?: number;
+  /** Minimum number of tags */
+  min?: number;
+  /** Predefined tag options */
+  options?: KirbyOption[];
+  /** Search configuration or boolean to enable/disable */
+  search?: boolean | KirbyTagsSearch;
+  /** Tag separator for storage (default: `,`) */
+  separator?: string;
+  /** Whether to sort tags by dropdown position */
+  sort?: boolean;
+  value?: string[];
+}
+
+/**
+ * Props for link fields.
+ *
+ * @see https://getkirby.com/docs/reference/panel/fields/link
+ */
+export interface KirbyLinkFieldProps extends KirbyFieldProps {
+  type: "link";
+  /** Allowed link types */
+  options?: ("anchor" | "url" | "page" | "file" | "email" | "tel" | "custom")[];
+  value?: string;
+}
+
+/**
+ * Props for structure fields.
+ *
+ * @see https://getkirby.com/docs/reference/panel/fields/structure
+ */
+export interface KirbyStructureFieldProps extends KirbyFieldProps {
+  type: "structure";
+  /** Whether to enable batch editing */
+  batch?: boolean;
+  /** Column definitions for table display */
+  columns?: Record<string, KirbyStructureColumn>;
+  /** Whether to allow duplicating rows */
+  duplicate?: boolean;
+  /** Placeholder text when no entries exist */
+  empty?: string;
+  /** Nested field definitions */
+  fields: Record<string, KirbyFieldProps>;
+  /** Number of entries per page before pagination */
+  limit?: number;
+  /** Maximum number of entries */
+  max?: number;
+  /** Minimum number of entries */
+  min?: number;
+  /** Whether to prepend new entries */
+  prepend?: boolean | null;
+  /** Whether entries are sortable via drag & drop */
+  sortable?: boolean | null;
+  /** Sort entries by field (disables drag & drop) */
+  sortBy?: string;
+  value?: Record<string, any>[];
+}
+
+/**
+ * Column definition for structure field table display.
+ */
+export interface KirbyStructureColumn {
+  /** Column label */
+  label?: string;
+  /** Column width */
+  width?: string;
+  /** Field type for display */
+  type?: string;
+  /** Whether to show mobile */
+  mobile?: boolean;
+  /** Text alignment */
+  align?: "left" | "center" | "right";
+  /** Value template */
+  value?: string;
+  /** Before text */
+  before?: string;
+  /** After text */
+  after?: string;
+}
+
+/**
+ * Props for object fields.
+ *
+ * @see https://getkirby.com/docs/reference/panel/fields/object
+ */
+export interface KirbyObjectFieldProps extends KirbyFieldProps {
+  type: "object";
+  /** Placeholder text when no data exists */
+  empty?: string;
+  /** Nested field definitions */
+  fields: Record<string, KirbyFieldProps>;
+  value?: Record<string, any> | "";
+}
+
+/**
+ * Props for blocks fields.
+ *
+ * @see https://getkirby.com/docs/reference/panel/fields/blocks
+ */
+export interface KirbyBlocksFieldProps extends KirbyFieldProps {
+  type: "blocks";
+  /** Empty state configuration */
+  empty?: string;
+  /** Available block fieldsets */
+  fieldsets: Record<string, KirbyFieldsetProps>;
+  /** Fieldset group configuration */
+  fieldsetGroups?: Record<string, KirbyFieldsetGroup>;
+  /** Group name for fieldsets */
+  group?: string;
+  /** Maximum number of blocks */
+  max?: number;
+  /** Minimum number of blocks */
+  min?: number;
+  value?: KirbyBlockValue[];
+}
+
+/**
+ * Props for layout fields.
+ *
+ * @see https://getkirby.com/docs/reference/panel/fields/layout
+ */
+export interface KirbyLayoutFieldProps extends KirbyFieldProps {
+  type: "layout";
+  /** Empty state configuration */
+  empty?: string;
+  /** Available block fieldsets */
+  fieldsets: Record<string, KirbyFieldsetProps>;
+  /** Fieldset group configuration */
+  fieldsetGroups?: Record<string, KirbyFieldsetGroup>;
+  /** Group name for fieldsets */
+  group?: string;
+  /** Available layout configurations (column width arrays) */
+  layouts: string[][];
+  /** Maximum number of layouts */
+  max?: number;
+  /** Minimum number of layouts */
+  min?: number;
+  /** Layout selector styling options (size: `"small"`|`"medium"`|`"large"`|`"huge"`, columns count) */
+  selector?: {
+    size?: "small" | "medium" | "large" | "huge";
+    columns?: number;
+  };
+  /** Layout settings fieldset (rendered via `Fieldset->toArray()`) */
+  settings?: KirbyFieldsetProps;
+  value?: KirbyLayoutValue[];
+}
+
+/**
+ * Props for writer fields.
+ *
+ * @see https://getkirby.com/docs/reference/panel/fields/writer
+ */
+export interface KirbyWriterFieldProps extends KirbyFieldProps {
+  type: "writer";
+  /** Whether to show character counter */
+  counter?: boolean;
+  /** Available heading levels (1-6) */
+  headings?: number[];
+  /** Whether only inline formatting is allowed */
+  inline: boolean;
+  /** Available formatting marks (`bold`, `italic`, `underline`, `strike`, `code`, `link`, `email`) or `true`/`false` */
+  marks?: string[] | boolean;
+  /** Maximum character length */
+  maxlength?: number;
+  /** Minimum character length */
+  minlength?: number;
+  /** Available block nodes (`paragraph`, `heading`, `bulletList`, `orderedList`, `quote`) or `true`/`false` */
+  nodes?: string[] | boolean;
+  /** Toolbar configuration */
+  toolbar?: Record<string, any>;
+  value?: string;
+}
+
+// =============================================================================
+// Block & Layout Values
+// =============================================================================
+
+/**
+ * Block value as stored in content.
+ */
+export interface KirbyBlockValue {
+  /** Block content fields */
+  content: Record<string, any>;
+  /** Unique block identifier */
+  id: string;
+  /** Whether the block is hidden */
+  isHidden: boolean;
+  /** Block type identifier */
+  type: string;
+}
+
+/**
+ * Layout value as stored in content.
+ */
+export interface KirbyLayoutValue {
+  /** Layout attributes */
+  attrs: Record<string, any> | any[];
+  /** Layout columns */
+  columns: KirbyLayoutColumnValue[];
+  /** Unique layout identifier */
+  id: string;
+}
+
+/**
+ * Layout column value as stored in content.
+ */
+export interface KirbyLayoutColumnValue {
+  /** Blocks in this column */
+  blocks: KirbyBlockValue[];
+  /** Unique column identifier */
+  id: string;
+  /** Column width fraction */
+  width: string;
+}
+
+// =============================================================================
+// Fieldset (Block Type Definition)
+// =============================================================================
+
+/**
+ * Fieldset props as returned by `Fieldset->toArray()`.
+ *
+ * Represents a block type definition with its fields organized in tabs.
+ * Used by blocks and layout fields.
+ *
+ * @see https://github.com/getkirby/kirby/blob/main/src/Cms/Fieldset.php
+ *
+ * @example
+ * ```ts
+ * const fieldset: KirbyFieldsetProps = {
+ *   disabled: false,
+ *   editable: true,
+ *   icon: "text",
+ *   label: null,
+ *   name: "Heading",
+ *   preview: "fields",
+ *   tabs: {
+ *     content: {
+ *       fields: { text: {...}, level: {...} },
+ *       label: "Content",
+ *       name: "content"
+ *     }
+ *   },
+ *   translate: true,
+ *   type: "heading",
+ *   unset: false,
+ *   wysiwyg: false
+ * };
+ * ```
+ */
+export interface KirbyFieldsetProps {
+  /** Whether the fieldset is disabled */
+  disabled: boolean;
+  /** Whether the block can be edited (has fields) */
+  editable: boolean;
+  /** Icon identifier */
+  icon: string | null;
+  /** Short label for block selector */
+  label: string | null;
+  /** Human-readable block name */
+  name: string;
+  /** Preview mode: `fields`, field name, or custom component */
+  preview: string | boolean | null;
+  /** Tabs containing field definitions */
+  tabs: Record<string, KirbyFieldsetTab>;
+  /** Whether the block is translatable */
+  translate: boolean;
+  /** Block type identifier (e.g., `text`, `heading`, `image`) */
+  type: string;
+  /** Whether the fieldset should be hidden */
+  unset: boolean;
+  /** Whether the block uses WYSIWYG editing */
+  wysiwyg: boolean;
+}
+
+/**
+ * Tab within a fieldset.
+ */
+export interface KirbyFieldsetTab {
+  /** Field definitions in this tab */
+  fields: Record<string, KirbyFieldProps>;
+  /** Tab label */
+  label?: string;
+  /** Tab identifier */
+  name: string;
+}
+
+/**
+ * Fieldset group for organizing block types.
+ */
+export interface KirbyFieldsetGroup {
+  /** Group label */
+  label: string;
+  /** Group identifier */
+  name: string;
+  /** Whether the group is open by default */
+  open: boolean;
+  /** Block types in this group */
+  sets: string[];
+}
+
+// =============================================================================
+// Union Types
+// =============================================================================
+
+/**
+ * Union of all field prop types.
+ */
+export type KirbyAnyFieldProps =
+  | KirbyFieldProps
+  | KirbyTextFieldProps
+  | KirbyNumberFieldProps
+  | KirbyOptionsFieldProps
+  | KirbyToggleFieldProps
+  | KirbyDateFieldProps
+  | KirbyFilesFieldProps
+  | KirbyColorFieldProps
+  | KirbyRangeFieldProps
+  | KirbyTagsFieldProps
+  | KirbyLinkFieldProps
+  | KirbyStructureFieldProps
+  | KirbyObjectFieldProps
+  | KirbyBlocksFieldProps
+  | KirbyLayoutFieldProps
+  | KirbyWriterFieldProps;

package/src/panel/features.d.ts

@@ -649,6 +649,8 @@ export interface PanelViewDefaults extends PanelFeatureDefaults {
   id: string | null;
   /** View link */
   link: string | null;
+  /** Relative path to this view */
+  path: string;
   /** Default search type */
   search: string;
   /** View title */
@@ -678,6 +680,8 @@ export interface PanelView extends Omit<
   id: string | null;
   /** View link */
   link: string | null;
+  /** Relative path to this view */
+  path: string;
   /** Default search type */
   search: string;
   /** View title */
@@ -967,7 +971,7 @@ export interface PanelContent {
   /**
    * Emits a content event with environment context.
    *
-   * @param event - Event name (prefixed with 'content.')
+   * @param event - Event name (prefixed with `"content."`)
    * @param options - Additional event data
    * @param env - Environment context
    */
@@ -1379,11 +1383,6 @@ export interface PanelUpload
 // Events
 // -----------------------------------------------------------------------------
 
-/**
- * Keychain modifier string (e.g., `'cmd.shift.s'`).
- */
-export type PanelKeychain = string;
-
 /**
  * Event emitter interface (mitt-compatible).
  */
@@ -1479,13 +1478,13 @@ export interface PanelEvents extends PanelEventEmitter {
   focus: (event: FocusEvent) => void;
 
   /**
-   * Creates keychain modifier string.
+   * Creates keychain modifier string (e.g., `"keydown.cmd.shift.s"`).
    *
    * @param type - Event type
    * @param event - KeyboardEvent
-   * @returns Keychain string (e.g., `'keydown.cmd.shift.s'`)
+   * @returns Keychain string
    */
-  keychain: (type: "keydown" | "keyup", event: KeyboardEvent) => PanelKeychain;
+  keychain: (type: "keydown" | "keyup", event: KeyboardEvent) => string;
 
   /**
    * Handles window keydown event.