kirby-types 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022-PRESENT Johann Schopplich <https://github.com/johannschopplich>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# 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 to work with Kirby, mainly in the context of the Kirby Query Language.
+
+## Setup
+
+```bash
+# pnpm
+pnpm add -D kirby-types
+
+# npm
+npm i -D kirby-types
+
+# yarn
+yarn add -D kirby-types
+```
+
+## Basic Usage
+
+```ts
+import type { KirbyQuery } from "kirby-types";
+
+// Strictly typed query for the Kirby Query Language
+const query: KirbyQuery = 'kirby.page("about")';
+```
+
+## API
+
+Click the type names for complete docs.
+
+### Query
+
+- [`KirbyQueryModel`](./src/query.d.ts) - Matches any [supported KirbyQL model](https://github.com/getkirby/kql/blob/66abd20093e5656b0f7e6f51ee04f630ab38f2a3/src/Kql/Kql.php#L73).
+- [`KirbyQuery`](./src/query.d.ts) - Matches a KirbyQL [`query`](https://getkirby.com/docs/guide/blueprints/query-language).
+
+### Blocks
+
+- [`KirbyBlockType`](./src/blocks.d.ts) - Matches any [Kirby block type](https://getkirby.com/docs/reference/panel/blocks).
+- [`KirbyBlock`](./src/blocks.d.ts) - Matches a [Kirby block](https://getkirby.com/docs/guide/page-builder).
+
+### Layout
+
+- [`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).
+
+### 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).
+
+## License
+
+[MIT](./LICENSE) License © 2022-PRESENT [Johann Schopplich](https://github.com/johannschopplich)

package/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./src/blocks";
+export * from "./src/kql";
+export * from "./src/layout";
+export * from "./src/query";

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "kirby-types",
+  "type": "module",
+  "version": "0.5.0",
+  "packageManager": "pnpm@8.7.0",
+  "description": "A collection of TypeScript types for the Kirby CMS",
+  "author": "Johann Schopplich <pkg@johannschopplich.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/johannschopplich/kirby-types#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/johannschopplich/kirby-types.git"
+  },
+  "bugs": "https://github.com/johannschopplich/kirby-types/issues",
+  "keywords": [
+    "getkirby",
+    "kirby-cms",
+    "kirby",
+    "kql",
+    "query-language",
+    "query",
+    "typescript"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./index.d.ts"
+    }
+  },
+  "types": "./index.d.ts",
+  "files": [
+    "src",
+    "index.d.ts"
+  ],
+  "scripts": {
+    "lint": "eslint \"**/*.ts\" --ignore-path .gitignore",
+    "lint:fix": "npm run lint -- --fix",
+    "format": "prettier \"**/*.{css,html,json,md,mjs,ts,vue,yml}\" --write",
+    "format:check": "prettier \"**/*.{css,html,json,md,mjs,ts,vue,yml}\" --check",
+    "release": "bumpp --commit --push --tag",
+    "test": "tsd -f \"test/**/*.test-d.ts\""
+  },
+  "devDependencies": {
+    "@nuxt/eslint-config": "^0.1.1",
+    "bumpp": "^9.2.0",
+    "eslint": "^8.48.0",
+    "eslint-config-prettier": "^9.0.0",
+    "prettier": "^3.0.2",
+    "tsd": "^0.28.1",
+    "typescript": "^5.1.6"
+  }
+}

package/src/blocks.d.ts

@@ -0,0 +1,51 @@
+export type KirbyBlockType =
+  | "code"
+  | "gallery"
+  | "heading"
+  | "image"
+  | "line"
+  | "list"
+  | "markdown"
+  | "quote"
+  | "table"
+  | "text"
+  | "video";
+
+export interface KirbyBlock<
+  T extends string = KirbyBlockType,
+  U extends Record<string, any> | undefined = undefined,
+> {
+  content: U extends Record<string, any>
+    ? U
+    : T extends "code"
+    ? { code: string; language: string }
+    : T extends "gallery"
+    ? { images: string[] }
+    : T extends "heading"
+    ? { level: string; text: string }
+    : T extends "image"
+    ? {
+        location: string;
+        image: string[];
+        src: string;
+        alt: string;
+        caption: string;
+        link: string;
+        ratio: string;
+        crop: boolean;
+      }
+    : T extends "list"
+    ? { text: string }
+    : T extends "markdown"
+    ? { text: string }
+    : T extends "quote"
+    ? { text: string; citation: string }
+    : T extends "text"
+    ? { text: string }
+    : T extends "video"
+    ? { url: string; caption: string }
+    : Record<string, never>;
+  id: string;
+  isHidden: boolean;
+  type: T;
+}

package/src/kql.d.ts

@@ -0,0 +1,36 @@
+import type { KirbyQuery } from "./query";
+
+export interface KirbyQuerySchema {
+  query: KirbyQuery;
+  select?:
+    | string[]
+    | Record<string, string | number | boolean | KirbyQuerySchema>;
+}
+
+export interface KirbyQueryRequest extends KirbyQuerySchema {
+  pagination?: {
+    /** @default 100 */
+    limit?: number;
+    page?: number;
+  };
+}
+
+export interface KirbyQueryResponse<
+  T = any,
+  Pagination extends boolean = false,
+> {
+  code: number;
+  status: string;
+  result?: Pagination extends true
+    ? {
+        data: T;
+        pagination: {
+          page: number;
+          pages: number;
+          offset: number;
+          limit: number;
+          total: number;
+        };
+      }
+    : T;
+}

package/src/layout.d.ts

@@ -0,0 +1,41 @@
+import type { KirbyBlock } from "./blocks";
+
+export interface KirbyLayoutColumn {
+  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";
+  blocks: KirbyBlock[];
+}
+
+export interface KirbyLayout {
+  id: string;
+  attrs: Record<string, any> | string[];
+  columns: KirbyLayoutColumn[];
+}

package/src/query.d.ts

@@ -0,0 +1,32 @@
+// https://github.com/getkirby/kql/blob/4c8cdd88c076cdef5323efcd4f0fda38c0865eed/src/Kql/Kql.php#L73
+export type KirbyQueryModel<CustomModel extends string = never> =
+  | "collection"
+  | "file"
+  | "kirby"
+  | "page"
+  | "site"
+  | "user"
+  | "arrayItem"
+  | "structureItem"
+  | "block"
+  | CustomModel;
+
+// For simple dot-based queries like `site.title`, `page.images`, etc.
+type DotNotationQuery<M extends string = never> =
+  `${KirbyQueryModel<M>}.${string}`;
+
+// For function-based queries like `page("id")`, `user("name")`, etc.
+type FunctionNotationQuery<M extends string = never> =
+  `${KirbyQueryModel<M>}(${string})${string}`;
+
+// Combines the two types above to allow for either dot or function notation
+export type KirbyQueryChain<M extends string = never> =
+  | DotNotationQuery<M>
+  | FunctionNotationQuery<M>;
+
+export type KirbyQuery<CustomModel extends string = never> =
+  | KirbyQueryModel<CustomModel>
+  // Ensures that it must match the pattern exactly, but not more broadly
+  | (string extends KirbyQueryChain<CustomModel>
+      ? never
+      : KirbyQueryChain<CustomModel>);