kirby-types 1.0.0 → 1.1.0

package/src/blocks.d.ts

@@ -1,36 +1,274 @@
+/**
+ * Supported code languages for the code block.
+ * @see https://github.com/getkirby/kirby/blob/main/config/blocks/code/code.yml
+ */
+export type KirbyCodeLanguage =
+  | "bash"
+  | "basic"
+  | "c"
+  | "clojure"
+  | "cpp"
+  | "csharp"
+  | "css"
+  | "diff"
+  | "elixir"
+  | "elm"
+  | "erlang"
+  | "go"
+  | "graphql"
+  | "haskell"
+  | "html"
+  | "java"
+  | "js"
+  | "json"
+  | "latext"
+  | "less"
+  | "lisp"
+  | "lua"
+  | "makefile"
+  | "markdown"
+  | "markup"
+  | "objectivec"
+  | "pascal"
+  | "perl"
+  | "php"
+  | "text"
+  | "python"
+  | "r"
+  | "ruby"
+  | "rust"
+  | "sass"
+  | "scss"
+  | "shell"
+  | "sql"
+  | "swift"
+  | "typescript"
+  | "vbnet"
+  | "xml"
+  | "yaml";
+
+/**
+ * Maps each of Kirby's default block types to their corresponding content structure.
+ *
+ * @see https://getkirby.com/docs/reference/panel/blocks
+ *
+ * @example
+ * ```ts
+ * // Access content type for a specific block
+ * type CodeContent = KirbyDefaultBlocks["code"];
+ * // Result: { code: string; language: KirbyCodeLanguage }
+ * ```
+ */
 export interface KirbyDefaultBlocks {
-  code: { code: string; language: string };
-  gallery: { images: string[] };
-  heading: { level: string; text: string };
-  image: {
-    location: string;
-    image: string[];
-    src: string;
-    alt: string;
-    caption: string;
-    link: string;
-    ratio: string;
+  /**
+   * Code block for displaying syntax-highlighted code snippets.
+   * @see https://getkirby.com/docs/reference/panel/blocks/code
+   */
+  code: {
+    code: string;
+    language: KirbyCodeLanguage;
+  };
+
+  /**
+   * Gallery block for displaying multiple images.
+   * @see https://getkirby.com/docs/reference/panel/blocks/gallery
+   */
+  gallery: {
+    images: string[];
+    caption: string | null;
+    ratio: string | null;
     crop: boolean;
   };
-  list: { text: string };
-  markdown: { text: string };
-  quote: { text: string; citation: string };
-  text: { text: string };
-  video: { url: string; caption: string };
+
+  /**
+   * Heading block for section titles.
+   * @see https://getkirby.com/docs/reference/panel/blocks/heading
+   */
+  heading: {
+    level: string;
+    text: string;
+  };
+
+  /**
+   * Image block for displaying a single image.
+   * Supports both internal Kirby files and external URLs.
+   * Uses a discriminated union based on `location` field.
+   * @see https://getkirby.com/docs/reference/panel/blocks/image
+   */
+  image:
+    | {
+        /** Internal Kirby image file. */
+        location: "kirby";
+        /** Internal Kirby file references. */
+        image: string[];
+        /** Alternative text for accessibility. */
+        alt: string | null;
+        /** Image caption (supports inline HTML). */
+        caption: string | null;
+        /** Link URL when image is clicked. */
+        link: string | null;
+        /** Aspect ratio constraint (e.g., `"16/9"`, `"1/1"`). */
+        ratio: string | null;
+        /** Whether to crop the image to fit the ratio. */
+        crop: boolean;
+      }
+    | {
+        /** External image URL. */
+        location: "web";
+        /** External image URL. */
+        src: string;
+        /** Alternative text for accessibility. */
+        alt: string | null;
+        /** Image caption (supports inline HTML). */
+        caption: string | null;
+        /** Link URL when image is clicked. */
+        link: string | null;
+        /** Aspect ratio constraint (e.g., `"16/9"`, `"1/1"`). */
+        ratio: string | null;
+        /** Whether to crop the image to fit the ratio. */
+        crop: boolean;
+      };
+
+  /**
+   * Horizontal line/divider block.
+   * Has no content fields.
+   * @see https://getkirby.com/docs/reference/panel/blocks/line
+   */
+  line: Record<string, never>;
+
+  /**
+   * List block for bullet or numbered lists.
+   * @see https://getkirby.com/docs/reference/panel/blocks/list
+   */
+  list: {
+    text: string;
+  };
+
+  /**
+   * Markdown block for raw markdown content.
+   * @see https://getkirby.com/docs/reference/panel/blocks/markdown
+   */
+  markdown: {
+    text: string;
+  };
+
+  /**
+   * Quote block for blockquotes with optional citation.
+   * @see https://getkirby.com/docs/reference/panel/blocks/quote
+   */
+  quote: {
+    text: string;
+    /** Optional citation/attribution for the quote. */
+    citation?: string;
+  };
+
+  /**
+   * Table block for tabular data.
+   * Content structure is dynamic based on rows/columns.
+   */
+  table: Record<string, unknown>;
+
+  /**
+   * Rich text block (WYSIWYG editor).
+   * @see https://getkirby.com/docs/reference/panel/blocks/text
+   */
+  text: {
+    text: string;
+  };
+
+  /**
+   * Video block for embedding videos.
+   * Supports both internal Kirby files and external URLs (YouTube, Vimeo, etc.).
+   * Uses a discriminated union based on `location` field.
+   * @see https://getkirby.com/docs/reference/panel/blocks/video
+   */
+  video:
+    | {
+        /** External video source. */
+        location: "web";
+        /** External video URL (YouTube, Vimeo, etc.). */
+        url: string;
+        /** Video caption (supports inline HTML). */
+        caption: string | null;
+      }
+    | {
+        /** Internal Kirby video file. */
+        location: "kirby";
+        /** Internal Kirby video file references. */
+        video: string[];
+        /** Poster image file references. */
+        poster: string[];
+        /** Video caption (supports inline HTML). */
+        caption: string | null;
+        /** Whether to autoplay the video. */
+        autoplay: boolean;
+        /** Whether to mute the video. */
+        muted: boolean;
+        /** Whether to loop the video. */
+        loop: boolean;
+        /** Whether to show video controls. */
+        controls: boolean;
+        /** Preload behavior. */
+        preload: "auto" | "metadata" | "none";
+      };
 }
 
+/**
+ * Represents a Kirby block with its content, metadata, and type information.
+ *
+ * @typeParam T - The block type identifier. Defaults to any default block type.
+ * @typeParam U - Optional custom content structure. When provided, overrides the default content type.
+ *
+ * @see https://getkirby.com/docs/guide/page-builder
+ *
+ * @example
+ * ```ts
+ * // Using a default block type
+ * const textBlock: KirbyBlock<"text"> = {
+ *   id: "abc123",
+ *   type: "text",
+ *   isHidden: false,
+ *   content: { text: "Hello world" }
+ * };
+ *
+ * // Using a custom block type
+ * const customBlock: KirbyBlock<"hero", { title: string; image: string }> = {
+ *   id: "def456",
+ *   type: "hero",
+ *   isHidden: false,
+ *   content: { title: "Welcome", image: "hero.jpg" }
+ * };
+ * ```
+ */
 export interface KirbyBlock<
   T extends string = keyof KirbyDefaultBlocks,
   U extends Record<string, unknown> | undefined = undefined,
 > {
+  /**
+   * The block's content fields.
+   * Structure depends on the block type or custom content definition.
+   */
   content: U extends Record<string, unknown>
     ? U
     : T extends keyof KirbyDefaultBlocks
       ? KirbyDefaultBlocks[T]
       : Record<string, never>;
+  /** Unique identifier for the block (UUID v4). */
   id: string;
+  /** Whether the block is hidden in the frontend output. */
   isHidden: boolean;
+  /** The block type identifier. */
   type: T;
 }
 
+/**
+ * Union type of all default Kirby block type names.
+ *
+ * @example
+ * ```ts
+ * function isDefaultBlock(type: string): type is KirbyDefaultBlockType {
+ *   return ["code", "gallery", "heading", "image", "line", "list", "markdown", "quote", "table", "text", "video"].includes(type);
+ * }
+ * ```
+ */
 export type KirbyDefaultBlockType = keyof KirbyDefaultBlocks;

package/src/kql.d.ts

@@ -1,33 +1,159 @@
 import type { KirbyApiResponse } from "./api";
 import type { KirbyQuery } from "./query";
 
+/**
+ * Defines the structure of a KQL (Kirby Query Language) query schema.
+ * Used for building nested, structured queries against Kirby content.
+ *
+ * @see https://github.com/getkirby/kql
+ *
+ * @example
+ * ```ts
+ * // Simple query
+ * const schema: KirbyQuerySchema = {
+ *   query: "site"
+ * };
+ *
+ * // Query with field selection
+ * const schemaWithSelect: KirbyQuerySchema = {
+ *   query: "page",
+ *   select: ["title", "url", "content"]
+ * };
+ *
+ * // Nested query with sub-selections
+ * const nestedSchema: KirbyQuerySchema = {
+ *   query: "site.children",
+ *   select: {
+ *     title: true,
+ *     url: true,
+ *     children: {
+ *       query: "page.children",
+ *       select: ["title", "url"]
+ *     }
+ *   }
+ * };
+ * ```
+ */
 export interface KirbyQuerySchema {
+  /** The KQL query string to execute. */
   query: KirbyQuery;
+  /**
+   * Fields to select from the query result.
+   * Can be an array of field names or an object for nested queries.
+   */
   select?:
     | string[]
     | Record<string, string | number | boolean | KirbyQuerySchema>;
 }
 
+/**
+ * Represents a complete KQL request with optional pagination.
+ * Extends {@link KirbyQuerySchema} with pagination options.
+ *
+ * @see https://github.com/getkirby/kql
+ *
+ * @example
+ * ```ts
+ * // Paginated request for blog posts
+ * const request: KirbyQueryRequest = {
+ *   query: 'page("blog").children.listed',
+ *   select: {
+ *     title: "page.title",
+ *     date: "page.date.toDate",
+ *     excerpt: "page.excerpt.kirbytext"
+ *   },
+ *   pagination: {
+ *     limit: 10,
+ *     page: 1
+ *   }
+ * };
+ * ```
+ */
 export interface KirbyQueryRequest extends KirbyQuerySchema {
+  /**
+   * Pagination options for limiting and offsetting results.
+   */
   pagination?: {
-    /** @default 100 */
+    /**
+     * Maximum number of items to return.
+     * @default 100
+     */
     limit?: number;
+    /** Page number to retrieve (1-indexed). */
     page?: number;
   };
 }
 
+/**
+ * Represents the response from a KQL query.
+ * Wraps the result in a {@link KirbyApiResponse} with optional pagination metadata.
+ *
+ * @typeParam T - The type of the result data.
+ * @typeParam Pagination - Whether pagination metadata is included. When `true`, the result is wrapped in `{ data, pagination }`.
+ *
+ * @see https://github.com/getkirby/kql
+ *
+ * @example
+ * ```ts
+ * // Response without pagination
+ * interface Page {
+ *   title: string;
+ *   url: string;
+ * }
+ *
+ * const response: KirbyQueryResponse<Page> = {
+ *   code: 200,
+ *   status: "ok",
+ *   result: { title: "Home", url: "/" }
+ * };
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Response with pagination
+ * interface Post {
+ *   title: string;
+ *   date: string;
+ * }
+ *
+ * const paginatedResponse: KirbyQueryResponse<Post[], true> = {
+ *   code: 200,
+ *   status: "ok",
+ *   result: {
+ *     data: [
+ *       { title: "Post 1", date: "2024-01-01" },
+ *       { title: "Post 2", date: "2024-01-02" }
+ *     ],
+ *     pagination: {
+ *       page: 1,
+ *       pages: 5,
+ *       offset: 0,
+ *       limit: 10,
+ *       total: 50
+ *     }
+ *   }
+ * };
+ * ```
+ */
 export type KirbyQueryResponse<
   T = any,
   Pagination extends boolean = false,
 > = KirbyApiResponse<
   Pagination extends true
     ? {
+        /** The query result data. */
         data: T;
+        /** Pagination metadata. */
         pagination: {
+          /** Current page number (1-indexed). */
           page: number;
+          /** Total number of pages. */
           pages: number;
+          /** Number of items skipped (offset). */
           offset: number;
+          /** Maximum items per page. */
           limit: number;
+          /** Total number of items across all pages. */
           total: number;
         };
       }

package/src/layout.d.ts

@@ -1,41 +1,108 @@
 import type { KirbyBlock } from "./blocks";
 
+/**
+ * Valid column width values for Kirby layouts.
+ * Expressed as fractions (e.g., `"1/2"` for half width).
+ *
+ * @see https://getkirby.com/docs/reference/panel/fields/layout#defining-your-own-layouts__available-widths
+ */
+export type KirbyLayoutColumnWidth =
+  | "1/1"
+  | "1/2"
+  | "1/3"
+  | "1/4"
+  | "1/6"
+  | "1/12"
+  | "2/2"
+  | "2/3"
+  | "2/4"
+  | "2/6"
+  | "2/12"
+  | "3/3"
+  | "3/4"
+  | "3/6"
+  | "3/12"
+  | "4/4"
+  | "4/6"
+  | "4/12"
+  | "5/6"
+  | "5/12"
+  | "6/6"
+  | "6/12"
+  | "7/12"
+  | "8/12"
+  | "9/12"
+  | "10/12"
+  | "11/12"
+  | "12/12";
+
+/**
+ * Represents a single column within a Kirby layout row.
+ * Each column has a width and contains blocks.
+ *
+ * @see https://getkirby.com/docs/reference/panel/fields/layout
+ *
+ * @example
+ * ```ts
+ * const column: KirbyLayoutColumn = {
+ *   id: "col-abc123",
+ *   width: "1/2",
+ *   blocks: [
+ *     { id: "block-1", type: "text", isHidden: false, content: { text: "Hello" } }
+ *   ]
+ * };
+ * ```
+ */
 export interface KirbyLayoutColumn {
+  /** Unique identifier for the column (UUID v4). */
   id: string;
-  width:
-    | "1/1"
-    | "1/2"
-    | "1/3"
-    | "1/4"
-    | "1/6"
-    | "1/12"
-    | "2/2"
-    | "2/3"
-    | "2/4"
-    | "2/6"
-    | "2/12"
-    | "3/3"
-    | "3/4"
-    | "3/6"
-    | "3/12"
-    | "4/4"
-    | "4/6"
-    | "4/12"
-    | "5/6"
-    | "5/12"
-    | "6/6"
-    | "6/12"
-    | "7/12"
-    | "8/12"
-    | "9/12"
-    | "10/12"
-    | "11/12"
-    | "12/12";
+  /**
+   * Column width as a fraction.
+   * Common values: `"1/1"` (full), `"1/2"` (half), `"1/3"` (third), `"1/4"` (quarter).
+   */
+  width: KirbyLayoutColumnWidth;
+  /** Array of blocks contained within this column. */
   blocks: KirbyBlock[];
 }
 
+/**
+ * Represents a Kirby layout row containing multiple columns.
+ * Layouts are used for flexible page building with a grid-based system.
+ *
+ * @see https://getkirby.com/docs/reference/panel/fields/layout
+ *
+ * @example
+ * ```ts
+ * const layout: KirbyLayout = {
+ *   id: "layout-xyz789",
+ *   attrs: { class: "highlight" },
+ *   columns: [
+ *     { id: "col-1", width: "1/2", blocks: [] },
+ *     { id: "col-2", width: "1/2", blocks: [] }
+ *   ]
+ * };
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Layout with empty attrs (as array)
+ * const simpleLayout: KirbyLayout = {
+ *   id: "layout-abc",
+ *   attrs: [],
+ *   columns: [
+ *     { id: "col-1", width: "1/1", blocks: [] }
+ *   ]
+ * };
+ * ```
+ */
 export interface KirbyLayout {
+  /** Unique identifier for the layout row (UUID v4). */
   id: string;
+  /**
+   * Custom attributes for the layout row.
+   * Can be a key-value object or an empty array when no attrs are set.
+   */
   attrs: Record<string, any> | string[];
+  /** Array of columns in this layout row. */
   columns: KirbyLayoutColumn[];
 }