kirby-types 0.7.3 → 1.1.0

package/README.md

@@ -1,8 +1,10 @@
 # kirby-types
 
-[![NPM version](https://img.shields.io/npm/v/kirby-types?color=a1b858&label=)](https://www.npmjs.com/package/kirby-types)
+A collection of TypeScript types for [Kirby CMS](https://getkirby.com), covering:
 
-A collection of TypeScript types to work with [Kirby CMS](https://getkirby.com), mainly in the context of the Kirby Query Language and [headless Kirby usage](https://github.com/johannschopplich/kirby-headless).
+- 🪟 **Panel types** for Kirby Panel plugin development
+- 🔌 **Backend API types** for headless Kirby usage and KQL
+- 🧱 **Block and layout types** for page builder content
 
 ## Setup
 
@@ -17,50 +19,291 @@ npm i -D kirby-types
 yarn add -D kirby-types
 ```
 
+## Features
+
+### Panel Types
+
+- **Panel API**: Complete API client method types.
+- **State Management**: State, Feature, and Modal hierarchies.
+- **Features**: Views, dialogs, drawers, notifications, uploads, and more.
+- **Helpers**: Array, string, object, URL, and other utility types.
+- **Libraries**: Color manipulation, dayjs, and autosize types.
+- **Writer**: ProseMirror-based rich text editor utilities.
+
+### Backend Types
+
+- **API Response**: Type-safe API responses.
+- **Blocks**: All 11 default block types with content structures.
+- **Layouts**: Layout and column types with width unions.
+- **KQL**: Query Language request/response types.
+- **Query Parsing**: Parse query strings into structured objects at the type level.
+
 ## Basic Usage
 
+### Panel Types
+
+Type the global `window.panel` object for Panel plugin development:
+
 ```ts
-import type { KirbyQuery } from "kirby-types";
+import type { Panel } from "kirby-types";
 
-// Strictly typed query
-const query: KirbyQuery = 'page.children.filterBy("featured", true)';
+// Augment the global Window interface
+declare global {
+  interface Window {
+    panel: Panel;
+  }
+}
 
-// Invalid queries will throw a type error
-let invalidQuery: KirbyQuery;
-invalidQuery = "unknown"; // Not a valid model
-invalidQuery = 'site("'; // Empty parentheses
-invalidQuery = 'site("value"'; // Missing closing parenthesis
+// Now window.panel is fully typed
+window.panel.notification.success("Page saved!");
+window.panel.dialog.open("pages/create");
 ```
 
-## API
+Common Panel operations with full type safety:
 
-By clicking on a type name, you will be redirected to the corresponding TypeScript definition file.
+```ts
+// Notifications
+window.panel.notification.success("Changes saved");
+window.panel.notification.error("Something went wrong");
 
-### API
+// Theme
+window.panel.theme.set("dark");
+const currentTheme = window.panel.theme.current; // "light" | "dark"
 
-- [`KirbyApiResponse`](./src/api.d.ts) - Matches the response of a [Kirby API request](https://getkirby.com/docs/reference/api).
+// Navigation
+await window.panel.view.open("/pages/blog");
+await window.panel.dialog.open("/dialogs/pages/create");
 
-### Query
+// API calls
+const page = await window.panel.api.pages.read("blog");
+await window.panel.api.pages.update("blog", { title: "New Title" });
+
+// Content state
+const hasChanges = window.panel.content.hasChanges;
+await window.panel.content.save();
+
+// User info
+const user = window.panel.user;
+console.log(user.email, user.role);
+```
+
+### Writer Extensions
+
+For ProseMirror-based Writer extensions (requires optional ProseMirror peer dependencies):
+
+```ts
+import type { WriterMarkContext } from "kirby-types";
+
+// In a Writer mark extension
+class Bold {
+  commands({ type, utils }: WriterMarkContext) {
+    return () => utils.toggleMark(type);
+  }
 
-- [`KirbyQueryModel`](./src/query.d.ts) - Matches any supported KirbyQL model.
-- [`KirbyQuery`](./src/query.d.ts) - Matches a KirbyQL [`query`](https://getkirby.com/docs/guide/blueprints/query-language).
+  inputRules({ type, utils }: WriterMarkContext) {
+    return [utils.markInputRule(/\*\*([^*]+)\*\*$/, type)];
+  }
+}
+```
+
+### API Responses
+
+```ts
+import type { KirbyApiResponse } from "kirby-types";
+
+interface PageData {
+  id: string;
+  title: string;
+  url: string;
+}
+
+const response: KirbyApiResponse<PageData> = {
+  code: 200,
+  status: "ok",
+  result: {
+    id: "home",
+    title: "Home",
+    url: "/",
+  },
+};
+```
 
 ### Blocks
 
-- [`KirbyBlock`](./src/blocks.d.ts) - Matches a [Kirby block](https://getkirby.com/docs/guide/page-builder).
-- [`KirbyDefaultBlockType`](./src/blocks.d.ts) - Matches any [Kirby default block type](https://getkirby.com/docs/reference/panel/blocks).
-- [`KirbyDefaultBlocks`](./src/blocks.d.ts) - Maps each of [Kirby's default block type](https://getkirby.com/docs/reference/panel/blocks) to its corresponding block content.
+```ts
+import type { KirbyBlock, KirbyDefaultBlockType } from "kirby-types";
+
+// Using a default block type
+const textBlock: KirbyBlock<"text"> = {
+  id: "abc123",
+  type: "text",
+  isHidden: false,
+  content: { text: "Hello world" },
+};
 
-### Layout
+// Using a custom block type
+interface HeroContent {
+  title: string;
+  image: string;
+  cta: string;
+}
 
-- [`KirbyLayout`](./src/layout.d.ts) - Matches a [Kirby layout](https://getkirby.com/docs/reference/panel/fields/layout).
-- [`KirbyLayoutColumn`](./src/layout.d.ts) - Matches any [supported layout width](https://getkirby.com/docs/reference/panel/fields/layout#defining-your-own-layouts__available-widths).
+const heroBlock: KirbyBlock<"hero", HeroContent> = {
+  id: "def456",
+  type: "hero",
+  isHidden: false,
+  content: {
+    title: "Welcome",
+    image: "hero.jpg",
+    cta: "Learn more",
+  },
+};
+```
+
+### Layouts
+
+```ts
+import type { KirbyLayout, KirbyLayoutColumn } from "kirby-types";
+
+const layout: KirbyLayout = {
+  id: "layout-xyz789",
+  attrs: { class: "highlight" },
+  columns: [
+    { id: "col-1", width: "1/3", blocks: [] },
+    { id: "col-2", width: "2/3", blocks: [] },
+  ],
+};
+```
+
+### KQL Queries
+
+```ts
+import type {
+  KirbyQuery,
+  KirbyQueryRequest,
+  KirbyQueryResponse,
+} from "kirby-types";
+
+// KQL request with pagination
+const request: KirbyQueryRequest = {
+  query: 'page("blog").children.listed',
+  select: {
+    title: "page.title",
+    date: "page.date.toDate",
+  },
+  pagination: { limit: 10 },
+};
+
+// Typed response
+interface BlogPost {
+  title: string;
+  date: string;
+}
+
+const response: KirbyQueryResponse<BlogPost[], true> = {
+  code: 200,
+  status: "ok",
+  result: {
+    data: [{ title: "Post 1", date: "2024-01-01" }],
+    pagination: { page: 1, pages: 5, offset: 0, limit: 10, total: 50 },
+  },
+};
+```
+
+### Query Parsing
+
+Parse query strings into structured objects at the type level:
+
+```ts
+import type { ParseKirbyQuery } from "kirby-types";
+
+type Parsed = ParseKirbyQuery<'page.children.filterBy("status", "published")'>;
+// Result: {
+//   model: "page";
+//   chain: [
+//     { type: "property"; name: "children" },
+//     { type: "method"; name: "filterBy"; params: '"status", "published"' }
+//   ]
+// }
+```
+
+## API Reference
+
+### Panel
+
+| Type                                         | Description                         |
+| -------------------------------------------- | ----------------------------------- |
+| [`Panel`](./src/panel/index.d.ts)            | Main Panel interface                |
+| [`PanelApi`](./src/panel/api.d.ts)           | API client methods                  |
+| [`PanelState`](./src/panel/base.d.ts)        | Base state interface                |
+| [`PanelFeature`](./src/panel/base.d.ts)      | Feature with loading states         |
+| [`PanelModal`](./src/panel/base.d.ts)        | Modal (dialog/drawer) interface     |
+| [`PanelHelpers`](./src/panel/helpers.d.ts)   | Utility functions                   |
+| [`PanelLibrary`](./src/panel/libraries.d.ts) | Libraries (colors, dayjs, autosize) |
+
+### Writer
+
+| Type                                                | Description                        |
+| --------------------------------------------------- | ---------------------------------- |
+| [`WriterUtils`](./src/panel/writer.d.ts)            | ProseMirror commands and utilities |
+| [`WriterMarkContext`](./src/panel/writer.d.ts)      | Context for mark extensions        |
+| [`WriterNodeContext`](./src/panel/writer.d.ts)      | Context for node extensions        |
+| [`WriterExtensionContext`](./src/panel/writer.d.ts) | Context for generic extensions     |
+
+### API
+
+| Type                                    | Description                           |
+| --------------------------------------- | ------------------------------------- |
+| [`KirbyApiResponse<T>`](./src/api.d.ts) | Standard Kirby API response structure |
+
+### Blocks
+
+| Type                                         | Description                       |
+| -------------------------------------------- | --------------------------------- |
+| [`KirbyBlock<T, U>`](./src/blocks.d.ts)      | Block with type and content       |
+| [`KirbyCodeLanguage`](./src/blocks.d.ts)     | Valid code block languages        |
+| [`KirbyDefaultBlocks`](./src/blocks.d.ts)    | Default block content types       |
+| [`KirbyDefaultBlockType`](./src/blocks.d.ts) | Union of default block type names |
+
+### Layouts
+
+| Type                                          | Description                  |
+| --------------------------------------------- | ---------------------------- |
+| [`KirbyLayout`](./src/layout.d.ts)            | Layout row with columns      |
+| [`KirbyLayoutColumn`](./src/layout.d.ts)      | Column with width and blocks |
+| [`KirbyLayoutColumnWidth`](./src/layout.d.ts) | Valid column width fractions |
 
 ### KQL
 
-- [`KirbyQuerySchema`](./src/kql.d.ts) - Matches a [KQL query schema](https://github.com/getkirby/kql).
-- [`KirbyQueryRequest`](./src/kql.d.ts) - Matches any [KQL request](https://github.com/getkirby/kql).
-- [`KirbyQueryResponse`](./src/kql.d.ts) - Matches any [KQL response](https://github.com/getkirby/kql).
+| Type                                         | Description                           |
+| -------------------------------------------- | ------------------------------------- |
+| [`KirbyQuerySchema`](./src/kql.d.ts)         | KQL query schema structure            |
+| [`KirbyQueryRequest`](./src/kql.d.ts)        | KQL request with pagination           |
+| [`KirbyQueryResponse<T, P>`](./src/kql.d.ts) | KQL response with optional pagination |
+
+### Query
+
+| Type                                     | Description                           |
+| ---------------------------------------- | ------------------------------------- |
+| [`KirbyQuery<M>`](./src/query.d.ts)      | Valid KQL query string                |
+| [`KirbyQueryModel<M>`](./src/query.d.ts) | Supported query models                |
+| [`KirbyQueryChain<M>`](./src/query.d.ts) | Query chain patterns                  |
+| [`ParseKirbyQuery<T>`](./src/query.d.ts) | Parse query string to structured type |
+
+## Optional Dependencies
+
+The Panel types include Writer types that require ProseMirror packages. These are optional peer dependencies:
+
+```bash
+# Only needed if using Writer extension types
+pnpm add -D prosemirror-commands prosemirror-inputrules prosemirror-model prosemirror-schema-list prosemirror-state
+```
+
+Vue is also an optional peer dependency for Panel types:
+
+```bash
+pnpm add -D vue@^2.7.0
+```
 
 ## License
 

package/index.d.ts

@@ -1,13 +1,35 @@
+// API types
 export type { KirbyApiResponse } from "./src/api";
+
+// Block types
 export type {
   KirbyBlock,
+  KirbyCodeLanguage,
   KirbyDefaultBlocks,
   KirbyDefaultBlockType,
 } from "./src/blocks";
+
+// KQL types
 export type {
   KirbyQueryRequest,
   KirbyQueryResponse,
   KirbyQuerySchema,
 } from "./src/kql";
-export type { KirbyLayout, KirbyLayoutColumn } from "./src/layout";
-export type { KirbyQuery, KirbyQueryChain, KirbyQueryModel } from "./src/query";
+
+// Layout types
+export type {
+  KirbyLayout,
+  KirbyLayoutColumn,
+  KirbyLayoutColumnWidth,
+} from "./src/layout";
+
+// Panel types
+export * from "./src/panel/index";
+
+// Query types
+export type {
+  KirbyQuery,
+  KirbyQueryChain,
+  KirbyQueryModel,
+  ParseKirbyQuery,
+} from "./src/query";

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "kirby-types",
   "type": "module",
-  "version": "0.7.3",
-  "packageManager": "pnpm@9.11.0",
+  "version": "1.1.0",
+  "packageManager": "pnpm@10.27.0",
   "description": "A collection of TypeScript types for the Kirby CMS",
   "author": "Johann Schopplich <hello@johannschopplich.com>",
   "license": "MIT",
@@ -16,6 +16,7 @@
     "getkirby",
     "kirby-cms",
     "kirby",
+    "kirby-panel",
     "kql",
     "query-language",
     "query",
@@ -25,7 +26,7 @@
   "exports": {
     ".": {
       "types": "./index.d.ts",
-      "import": "./index.mjs"
+      "default": "./index.js"
     }
   },
   "types": "./index.d.ts",
@@ -41,12 +42,40 @@
     "release": "bumpp --commit --push --tag",
     "test": "tsd -f \"test/**/*.test-d.ts\""
   },
+  "peerDependencies": {
+    "prosemirror-commands": "^1.0.0",
+    "prosemirror-inputrules": "^1.0.0",
+    "prosemirror-model": "^1.0.0",
+    "prosemirror-schema-list": "^1.0.0",
+    "prosemirror-state": "^1.0.0",
+    "vue": "^2.7.0"
+  },
+  "peerDependenciesMeta": {
+    "prosemirror-commands": {
+      "optional": true
+    },
+    "prosemirror-inputrules": {
+      "optional": true
+    },
+    "prosemirror-model": {
+      "optional": true
+    },
+    "prosemirror-schema-list": {
+      "optional": true
+    },
+    "prosemirror-state": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
   "devDependencies": {
-    "@antfu/eslint-config": "^3.7.1",
-    "bumpp": "^9.5.2",
-    "eslint": "^9.10.0",
-    "prettier": "^3.3.3",
-    "tsd": "^0.31.2",
-    "typescript": "^5.5.4"
+    "@antfu/eslint-config": "^6.7.3",
+    "bumpp": "^10.3.2",
+    "eslint": "^9.39.2",
+    "prettier": "^3.7.4",
+    "tsd": "^0.33.0",
+    "typescript": "^5.9.3"
   }
 }

package/src/api.d.ts

@@ -1,5 +1,45 @@
+/**
+ * Represents the standard response structure from the Kirby API.
+ *
+ * @typeParam T - The type of the result data. Defaults to `any`.
+ *
+ * @see https://getkirby.com/docs/reference/api
+ *
+ * @example
+ * ```ts
+ * // Typed API response for a page
+ * interface PageData {
+ *   id: string;
+ *   title: string;
+ *   url: string;
+ * }
+ *
+ * const response: KirbyApiResponse<PageData> = {
+ *   code: 200,
+ *   status: "ok",
+ *   result: {
+ *     id: "home",
+ *     title: "Home",
+ *     url: "/"
+ *   }
+ * };
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Error response
+ * const errorResponse: KirbyApiResponse = {
+ *   code: 404,
+ *   status: "error"
+ *   // result is undefined for errors
+ * };
+ * ```
+ */
 export interface KirbyApiResponse<T = any> {
+  /** HTTP status code of the response. */
   code: number;
+  /** Status string, typically `"ok"` for success or `"error"` for failures. */
   status: string;
+  /** The response data. Only present for successful responses. */
   result?: T;
 }