@verbb/plugin-kit-core 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+## Unreleased
+
+## 2.0.0 - 2026-07-19
+
+### Changed
+- Aligned package version with the Plugin Kit v2 lockstep release (`@verbb/plugin-kit-web`, React/Vue adapters, forms, and related packages).
+- Continues to ship Craft host bridge helpers, shared utils, and ESLint presets for CP frontends.
+
+## 1.0.9 - 2026-07-02
+
+### Changed
+- Released alongside `@verbb/plugin-kit-react` to keep package versions aligned.
+
+## 1.0.8 - 2026-06-23
+
+### Changed
+- Released alongside `@verbb/plugin-kit-react` to keep package versions aligned.
+
+## 1.0.7 - 2026-06-18
+
+### Changed
+- Released alongside `@verbb/plugin-kit-react` to keep package versions aligned.
+
+## 1.0.6 - 2026-06-14
+
+### Changed
+- Released alongside `@verbb/plugin-kit-react` to keep package versions aligned.
+
+## 1.0.5 - 2026-06-12
+
+### Changed
+- Released alongside `@verbb/plugin-kit-react` to keep package versions aligned.
+
+## 1.0.4 - 2026-06-10
+
+### Changed
+- Released alongside `@verbb/plugin-kit-react` to keep package versions aligned.
+
+## 1.0.1 - 2026-06-07
+
+### Changed
+- Released alongside `@verbb/plugin-kit-react` to keep package versions aligned.
+
+## 1.0.0
+
+- Initial public release.

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Verbb
+
+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,46 @@
+# `@verbb/plugin-kit-core`
+
+Shared utilities and Craft CP host integration for Plugin Kit. Framework adapters and `@verbb/plugin-kit-web` depend on this package; most apps get it transitively.
+
+## Install
+
+```bash
+npm install @verbb/plugin-kit-core
+```
+
+## What you get
+
+| Area | Examples |
+|------|----------|
+| Host bridge | `setHostBridge`, `getHostBridge`, Craft request / selector helpers |
+| Portal helpers | `setPortalContainer`, `getPortalMountNode`, … |
+| Utils | string/handle helpers, markdown, query, collections, promises |
+| Tooling | `@verbb/plugin-kit-core/eslint/*`, `@verbb/plugin-kit-core/prettier/*` |
+
+## Host bridge
+
+Prefer the adapter helpers when you use React/Vue:
+
+```ts
+import { createCraftHostBridge, PluginKitProvider } from '@verbb/plugin-kit-react/utils';
+// or from '@verbb/plugin-kit-vue/utils' / '/app'
+
+<PluginKitProvider hostBridge={createCraftHostBridge()} … />
+```
+
+Low-level (vanilla / custom bootstrap):
+
+```ts
+import { setHostBridge } from '@verbb/plugin-kit-core';
+
+setHostBridge({
+  request: (method, action, config) => Craft.sendActionRequest(method, action, config),
+  // …
+});
+```
+
+Skip the bridge when the screen only uses UI primitives.
+
+## Docs
+
+Shared concepts live under the Web / React / Vue guides on [docs.verbb.io/plugin-kit](https://docs.verbb.io/plugin-kit/).

package/dist/eslint/config.base.js

@@ -0,0 +1,222 @@
+import js from '@eslint/js';
+import globals from 'globals';
+
+export default [
+    // Global ignores
+    {
+        ignores: [
+            '**/dist/**',
+            '**/node_modules/**',
+            '**/*.min.js',
+            '**/*.bundle.js',
+            '**/*.config.js',
+            '**/*.config.ts',
+        ],
+    },
+
+    // Base JavaScript configuration
+    {
+        files: ['**/*.{js,jsx,mjs,cjs}'],
+        languageOptions: {
+            ecmaVersion: 2022,
+            sourceType: 'module',
+            globals: {
+                ...globals.browser,
+                ...globals.es2021,
+                ...globals.node,
+            },
+        },
+    },
+
+    // Global rules used by every config, not specific to any language
+    {
+        rules: {
+            // Inherit recommended rules
+            ...js.configs.recommended.rules,
+
+            //
+            // Best Practices
+            //
+
+            // enforces return statements in callbacks of array's methods
+            'array-callback-return': ['warn', { allowImplicit: true }],
+
+            // specify curly brace conventions for all control statements
+            curly: ['warn', 'all'],
+
+            // encourages use of dot notation whenever possible
+            'dot-notation': ['warn', { allowKeywords: true }],
+
+            // enforces consistent newlines before or after dots
+            'dot-location': ['warn', 'property'],
+
+            // disallow the use of alert, confirm, and prompt
+            'no-alert': 'off',
+
+            // disallow else after a return in an if
+            'no-else-return': ['warn', { allowElseIf: false }],
+
+            // disallow empty functions, except for standalone funcs/arrows
+            'no-empty-function': ['warn', {
+                allow: [
+                    'arrowFunctions',
+                    'functions',
+                    'methods',
+                ],
+            }],
+
+            // disallow use of eval()
+            'no-eval': 'warn',
+
+            // disallow the use of leading or trailing decimal points in numeric literals
+            'no-floating-decimal': 'warn',
+
+            // disallow use of multiple spaces
+            'no-multi-spaces': ['warn', {
+                ignoreEOLComments: false,
+            }],
+
+            // disallow use of multiline strings
+            'no-multi-str': 'warn',
+
+            // disallow useless string concatenation
+            'no-useless-concat': 'warn',
+
+            // disallow redundant return; keywords
+            'no-useless-return': 'warn',
+
+            // disallow unnecessary escape characters
+            'no-useless-escape': 'off',
+
+            // require or disallow Yoda conditions
+            yoda: 'warn',
+
+            //
+            // ES6
+            //
+
+            // require braces in arrow function body
+            'arrow-body-style': ['warn', 'always'],
+
+            // disallow arrow functions where they could be confused with comparisons
+            'no-confusing-arrow': ['warn', {
+                allowParens: true,
+            }],
+
+            // require let or const instead of var
+            'no-var': 'warn',
+
+            // require method and property shorthand syntax for object literals
+            'object-shorthand': ['warn', 'always', {
+                ignoreConstructors: false,
+                avoidQuotes: true,
+            }],
+
+            // suggest using arrow functions as callbacks
+            'prefer-arrow-callback': ['warn', {
+                allowNamedFunctions: false,
+                allowUnboundThis: true,
+            }],
+
+            // suggest using of const declaration for variables that are never modified after declared
+            'prefer-const': ['warn', {
+                destructuring: 'any',
+                ignoreReadBeforeAssign: true,
+            }],
+
+            // Prefer destructuring from arrays and objects
+            'prefer-destructuring': ['warn', {
+                VariableDeclarator: {
+                    array: false,
+                    object: true,
+                },
+                AssignmentExpression: {
+                    array: true,
+                    object: false,
+                },
+            }, {
+                    enforceForRenamedProperties: false,
+                }],
+
+            // suggest using template literals instead of string concatenation
+            'prefer-template': 'warn',
+
+            // import sorting
+            'sort-imports': ['off', {
+                ignoreCase: false,
+                ignoreDeclarationSort: false,
+                ignoreMemberSort: false,
+                memberSyntaxSortOrder: ['none', 'all', 'multiple', 'single'],
+                allowSeparatedGroups: true,
+            }],
+
+            //
+            // Style
+            //
+
+            // require camel case names
+            camelcase: ['warn', { properties: 'always', ignoreDestructuring: true }],
+
+            // enforce or disallow capitalization of the first letter of a comment
+            'capitalized-comments': ['warn', 'always', {
+                line: {
+                    ignorePattern: '.*',
+                    ignoreInlineComments: true,
+                    ignoreConsecutiveComments: true,
+                },
+                block: {
+                    ignorePattern: '.*',
+                    ignoreInlineComments: true,
+                    ignoreConsecutiveComments: true,
+                },
+            }],
+
+            // require or disallow an empty line between class members
+            'lines-between-class-members': ['warn', 'always', { exceptAfterSingleLine: false }],
+
+            // require or disallow newlines around directives
+            'lines-around-directive': ['warn', {
+                before: 'always',
+                after: 'always',
+            }],
+
+            // disallow if as the only statement in an else block
+            'no-lonely-if': 'warn',
+
+            // disallow multiple empty lines, only one newline at the end, and no new lines at the beginning
+            'no-multiple-empty-lines': ['warn', { max: 2, maxBOF: 0, maxEOF: 0 }],
+
+            // disallow nested ternary expressions
+            'no-nested-ternary': 'warn',
+
+            // Prefer use of an object spread over Object.assign
+            'prefer-object-spread': 'warn',
+
+            // require or disallow a space immediately following the // or /* in a comment
+            'spaced-comment': ['warn', 'always', {
+                line: {
+                    exceptions: ['-', '+'],
+                    markers: ['=', '!', '/'], // space here to support sprockets directives, slash for TS /// comments
+                },
+                block: {
+                    exceptions: ['-', '+'],
+                    markers: ['=', '!', ':', '::'], // space here to support sprockets directives and flow comment types
+                    balanced: true,
+                }
+            }],
+
+            //
+            // Variables
+            //
+
+            // disallow use of undeclared variables unless mentioned in a /*global */ block
+            'no-undef': 'off',
+
+            // disallow declaration of variables that are not used in the code
+            'no-unused-vars': 'off',
+
+            // disallow use of variables before they are defined
+            'no-use-before-define': ['warn', { functions: true, classes: true, variables: true }],
+        },
+    }
+]

package/dist/eslint/config.react-hooks.js

@@ -0,0 +1,45 @@
+import reactHooks from 'eslint-plugin-react-hooks';
+
+export function createReactHooksConfig({
+    jsxFiles = ['**/*.{jsx,tsx}'],
+    hookFiles = ['**/use*.{js,ts}', '**/*Hook*.{js,ts}'],
+} = {}) {
+    const configs = [];
+
+    if (jsxFiles.length > 0) {
+        configs.push({
+            files: jsxFiles,
+            languageOptions: {
+                parserOptions: {
+                    ecmaFeatures: {
+                        jsx: true,
+                    },
+                },
+            },
+            plugins: {
+                'react-hooks': reactHooks,
+            },
+            rules: {
+                'react-hooks/rules-of-hooks': 'error',
+                'react-hooks/exhaustive-deps': 'warn',
+            },
+        });
+    }
+
+    if (hookFiles.length > 0) {
+        configs.push({
+            files: hookFiles,
+            plugins: {
+                'react-hooks': reactHooks,
+            },
+            rules: {
+                'react-hooks/rules-of-hooks': 'error',
+                'react-hooks/exhaustive-deps': 'warn',
+            },
+        });
+    }
+
+    return configs;
+}
+
+export default createReactHooksConfig();

package/dist/eslint/config.react-typescript.js

@@ -0,0 +1,9 @@
+import baseConfig from '@verbb/plugin-kit/eslint/config.base.js';
+import reactHooksConfig from '@verbb/plugin-kit/eslint/config.react-hooks.js';
+import typescriptConfig from '@verbb/plugin-kit/eslint/config.typescript-only.js';
+
+export default [
+    ...baseConfig,
+    ...typescriptConfig,
+    ...reactHooksConfig,
+]; 

package/dist/eslint/config.react.js

@@ -0,0 +1,10 @@
+import baseConfig from '@verbb/plugin-kit/eslint/config.base.js';
+import { createReactHooksConfig } from '@verbb/plugin-kit/eslint/config.react-hooks.js';
+
+export default [
+    ...baseConfig,
+    ...createReactHooksConfig({
+        jsxFiles: ['**/*.{js,jsx}'],
+        hookFiles: ['**/use*.js', '**/*Hook*.js'],
+    }),
+]; 

package/dist/eslint/config.typescript-only.js

@@ -0,0 +1,30 @@
+import tsParser from '@typescript-eslint/parser';
+import tsPlugin from '@typescript-eslint/eslint-plugin';
+
+export function createTypeScriptConfig({ files = ['**/*.{ts,tsx}'] } = {}) {
+    return [
+        {
+            files,
+            languageOptions: {
+                parser: tsParser,
+                parserOptions: {
+                    ecmaVersion: 'latest',
+                    sourceType: 'module',
+                },
+            },
+            plugins: {
+                '@typescript-eslint': tsPlugin,
+            },
+            rules: {
+                ...tsPlugin.configs.recommended.rules,
+
+                '@typescript-eslint/no-unused-vars': 'warn',
+                '@typescript-eslint/explicit-function-return-type': 'off',
+                '@typescript-eslint/explicit-module-boundary-types': 'off',
+                '@typescript-eslint/no-explicit-any': 'warn',
+            },
+        },
+    ];
+}
+
+export default createTypeScriptConfig();

package/dist/eslint/config.typescript.js

@@ -0,0 +1,7 @@
+import baseConfig from '@verbb/plugin-kit/eslint/config.base.js';
+import typescriptConfig from '@verbb/plugin-kit/eslint/config.typescript-only.js';
+
+export default [
+    ...baseConfig,
+    ...typescriptConfig,
+]; 

package/dist/eslint/config.vite-react.js

@@ -0,0 +1,5 @@
+import reactRefresh from 'eslint-plugin-react-refresh';
+
+export default [
+    reactRefresh.configs.vite,
+];

package/dist/host/hostBridge.d.ts

@@ -0,0 +1,40 @@
+export type HostRequestMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export type HostRequestConfig = {
+    data?: Record<string, unknown>;
+    [key: string]: unknown;
+};
+export type HostSelectedElement = {
+    id?: number;
+    siteId?: number;
+    label?: string;
+    url?: string;
+    [key: string]: unknown;
+};
+export type HostElementSelectorOptions = {
+    storageKey: string;
+    sources?: string[];
+    criteria?: Record<string, unknown>;
+    multiSelect?: boolean;
+    limit?: number | null;
+    defaultSiteId?: number;
+    autoFocusSearchBox?: boolean;
+    showSiteMenu?: boolean;
+    onShow?: () => void;
+    onSelect: (elements: HostSelectedElement[]) => void;
+    closeOtherModals?: boolean;
+};
+export type PluginKitHostBridge = {
+    request: <T = unknown>(method: HostRequestMethod, action: string, config?: HostRequestConfig) => Promise<T>;
+    openElementSelector: (elementType: string, options: HostElementSelectorOptions) => void;
+    formatDate: (date: Date) => string;
+    getTimepickerOptions: () => Record<string, unknown>;
+    getLocale: () => string;
+};
+export declare const setHostBridge: (bridge?: Partial<PluginKitHostBridge>) => void;
+export declare const getHostBridge: () => Partial<PluginKitHostBridge>;
+export declare const hostRequest: <T = unknown>(method: HostRequestMethod, action: string, config?: HostRequestConfig) => Promise<T>;
+export declare const hostOpenElementSelector: (elementType: string, options: HostElementSelectorOptions) => void;
+export declare const hostFormatDate: (date: Date) => string;
+export declare const hostGetTimepickerOptions: () => Record<string, unknown>;
+export declare const hostGetLocale: () => string;
+//# sourceMappingURL=hostBridge.d.ts.map

package/dist/host/hostBridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hostBridge.d.ts","sourceRoot":"","sources":["../../src/host/hostBridge.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,iBAAiB,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE5E,MAAM,MAAM,iBAAiB,GAAG;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAC9B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,QAAQ,EAAE,CAAC,QAAQ,EAAE,mBAAmB,EAAE,KAAK,IAAI,CAAC;IACpD,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAC9B,OAAO,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,iBAAiB,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAC5G,mBAAmB,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,0BAA0B,KAAK,IAAI,CAAC;IACxF,UAAU,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,MAAM,CAAC;IACnC,oBAAoB,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpD,SAAS,EAAE,MAAM,MAAM,CAAC;CAC3B,CAAC;AAIF,eAAO,MAAM,aAAa,GAAI,SAAQ,OAAO,CAAC,mBAAmB,CAAM,KAAG,IAKzE,CAAC;AAEF,eAAO,MAAM,aAAa,QAAO,OAAO,CAAC,mBAAmB,CAE3D,CAAC;AAcF,eAAO,MAAM,WAAW,GAAU,CAAC,GAAG,OAAO,EACzC,QAAQ,iBAAiB,EACzB,QAAQ,MAAM,EACd,SAAS,iBAAiB,KAC3B,OAAO,CAAC,CAAC,CAGX,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAAI,aAAa,MAAM,EAAE,SAAS,0BAA0B,KAAG,IAGlG,CAAC;AAEF,eAAO,MAAM,cAAc,GAAI,MAAM,IAAI,KAAG,MAG3C,CAAC;AAEF,eAAO,MAAM,wBAAwB,QAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAGjE,CAAC;AAEF,eAAO,MAAM,aAAa,QAAO,MAGhC,CAAC"}

package/dist/host/index.d.ts

@@ -0,0 +1,3 @@
+export * from './portal';
+export * from './hostBridge';
+//# sourceMappingURL=index.d.ts.map

package/dist/host/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/host/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC"}

package/dist/host/portal.d.ts

@@ -0,0 +1,18 @@
+export type PortalContainer = HTMLElement | ShadowRoot | null;
+export type PortalContainerRef = {
+    current: PortalContainer;
+};
+export type PortalContainerInput = PortalContainer | PortalContainerRef;
+export declare const setPortalClassName: (className: string) => void;
+export declare const getPortalClassName: (className?: string) => string | undefined;
+export declare const setPortalContainer: (container: PortalContainerInput) => void;
+export declare const getPortalContainer: (container?: PortalContainerInput) => PortalContainer | undefined;
+export declare const setShadowRootSelectors: (selectors: string[]) => void;
+export declare const getShadowRootSelectors: () => string[];
+/**
+ * Resolve where floating content should be portaled.
+ * Falls back to document.body when no container is configured.
+ */
+export declare const getPortalMountNode: (container?: PortalContainerInput) => HTMLElement;
+export declare const getPortalTargetForAppend: () => HTMLElement | undefined;
+//# sourceMappingURL=portal.d.ts.map

package/dist/host/portal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"portal.d.ts","sourceRoot":"","sources":["../../src/host/portal.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,UAAU,GAAG,IAAI,CAAC;AAE9D,MAAM,MAAM,kBAAkB,GAAG;IAC7B,OAAO,EAAE,eAAe,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,eAAe,GAAG,kBAAkB,CAAC;AAMxE,eAAO,MAAM,kBAAkB,GAAI,WAAW,MAAM,KAAG,IAEtD,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,YAAY,MAAM,KAAG,MAAM,GAAG,SAEhE,CAAC;AAcF,eAAO,MAAM,kBAAkB,GAAI,WAAW,oBAAoB,KAAG,IAEpE,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,YAAY,oBAAoB,KAAG,eAAe,GAAG,SAEvF,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,WAAW,MAAM,EAAE,KAAG,IAQ5D,CAAC;AAEF,eAAO,MAAM,sBAAsB,QAAO,MAAM,EAE/C,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAAI,YAAY,oBAAoB,KAAG,WAmBrE,CAAC;AAEF,eAAO,MAAM,wBAAwB,QAAO,WAAW,GAAG,SAezD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './host';
+export * from './utils';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,SAAS,CAAC"}