@loadspark/core 0.0.1

package/LICENSE.md

@@ -0,0 +1,71 @@
+Copyright (c) 2025 Welle Digital Solutions
+
+Permission is hereby granted, free of charge, to any individual or legal entity
+(the "Licensee") obtaining a copy of this software and associated documentation
+files (the "Software"), to use, copy, modify, merge, publish, and distribute the
+Software, subject to the terms outlined below.
+
+---
+
+1. LICENSE GRANT
+
+---
+
+1.1 Free License for Eligible Licensees  
+ The Software may be used, modified, and distributed at no charge by any
+Licensee whose total annual gross revenue does not exceed USD 250,000.
+
+1.2 Commercial License Requirement  
+ If the Licensee’s annual gross revenue exceeds USD 250,000, the Licensee
+must obtain a paid commercial license. To acquire a commercial license,
+contact: welledigital882@gmail.com
+
+---
+
+2. DEFINITION OF LICENSEE
+
+---
+
+2.1 Individual Licensee  
+ A natural person using the Software personally or as a sole proprietor.
+
+2.2 Entity Licensee  
+ A company, corporation, partnership, organization, or other legal entity,
+including any subsidiaries, divisions, or other organizational components
+under its ownership or control.
+
+2.3 Revenue Attribution  
+ For entity Licensees, total annual gross revenue shall be calculated at the
+level of the entire legal entity, including all controlled subsidiaries.
+
+---
+
+3. ATTRIBUTION REQUIREMENTS
+
+---
+
+3.1 Credit  
+ The original author(s) must be credited in any public distribution of the
+Software, documentation, or derivative works.
+
+3.2 Modifications  
+ Licensees modifying the Software must clearly indicate that changes have
+been made.
+
+---
+
+4. WARRANTY DISCLAIMER
+
+---
+
+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.
+
+---
+
+This License constitutes the entire agreement between the parties regarding the
+Software and supersedes all prior or contemporaneous communications.

package/README.md

@@ -0,0 +1,628 @@
+# @loadspark/core
+
+<div align="center">
+
+**A comprehensive core plugin for PayloadCMS v3 providing reusable custom fields, access control, validations, translations, and utilities for the loadspark ecosystem.**
+
+<br />
+
+[![License](https://img.shields.io/badge/license-Custom-blue.svg)](LICENSE.md)
+[![Documentation](https://img.shields.io/badge/docs-Available-green.svg)](https://loadspark.dev)
+[![Website](https://img.shields.io/badge/website-loadspark.dev-orange.svg)](https://loadspark.dev)
+
+**Quick Links:** [License](#license) • [Documentation](https://loadspark.dev/docs) • [Website](https://loadspark.dev)
+
+</div>
+
+---
+
+## Table of Contents
+
+- [Introduction](#introduction)
+- [Features](#features)
+- [Getting Started](#getting-started)
+  - [Installation](#installation)
+  - [Basic Usage](#basic-usage)
+- [Components](#components)
+  - [Custom Fields](#custom-fields)
+  - [Access Control](#access-control)
+  - [Validations](#validations)
+  - [Translations](#translations)
+  - [Collections](#collections)
+  - [Constants](#constants)
+  - [Utils](#utils)
+- [Overrides & Customization](#overrides--customization)
+- [Documentation](#documentation)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Introduction
+
+`@loadspark/core` is a powerful, production-ready core plugin for **PayloadCMS v3** that provides a comprehensive set of reusable components designed to accelerate development and ensure consistency across loadspark projects. Built with extensibility and type-safety in mind, this plugin serves as the foundation for building robust PayloadCMS applications.
+
+The plugin is architected to be **fully overridable** at every level, allowing you to customize and extend functionality while maintaining a solid base. All components are built on top of PayloadCMS's native APIs and follow best practices for type safety, internationalization, and accessibility.
+
+### Key Principles
+
+- **🔧 Fully Overridable**: Every component can be customized or extended
+- **🌍 i18n Ready**: Built-in support for multiple languages
+- **🛡️ Type Safe**: Full TypeScript support with comprehensive type definitions
+- **♿ Accessible**: Components follow accessibility best practices
+- **📦 Modular**: Import only what you need via subpath exports
+- **🔄 Reusable**: Designed to be the foundation for other loadspark plugins
+
+---
+
+## Features
+
+### 🎨 Custom Fields
+
+A collection of production-ready custom fields built on top of the [Nouncelabs Custom Fields Plugin](https://github.com/NouanceLabs/payload-better-fields-plugin), each with:
+
+- Type-safe configurations
+- Default sensible settings
+- Full override capabilities
+- Comprehensive documentation
+- Built-in validation
+- Accessible UI components
+
+### 👥 User Management
+
+Pre-configured Users collection with:
+
+- Role-based access control (admin, editor, user, system)
+- Overridable field configurations
+- Built-in access rules
+- Automatic first-user admin assignment
+- System user support
+
+### 🔐 Access Control
+
+Reusable access control functions and builders:
+
+- Role-based access checks
+- Field-level access control
+- Collection-level access rules
+- System permission handling
+- Flexible access builders
+
+### ✅ Validations
+
+Ready-to-use validation functions:
+
+- Date validations (past, future, before, after, etc.)
+- Number validations (greater than, less than, etc.)
+- Relation validations
+- i18n-ready error messages
+- Programmatic override support to conditionally skip validations
+
+### 🌐 Translations
+
+Comprehensive translation system:
+
+- Pre-translated labels and messages
+- Support for German, English
+- Validation error translations
+- Field label translations
+- Easy to extend with additional languages
+
+### 📊 Constants
+
+Reusable constants:
+
+- Country codes and labels
+- Common enumerations
+- Type definitions
+
+### 🛠️ Utilities
+
+Helper functions for common tasks:
+
+- Nested object accessors
+- Override rule checking
+- Logging utilities
+
+---
+
+## Getting Started
+
+### Installation
+
+Install the package using your preferred package manager:
+
+```bash
+# Using pnpm (recommended)
+pnpm add @loadspark/core
+
+# Using npm
+npm install @loadspark/core
+
+# Using yarn
+yarn add @loadspark/core
+```
+
+### Peer Dependencies
+
+This plugin requires the following peer dependencies:
+
+- `payload@3.69.0`
+- `@payloadcms/translations@3.69.0`
+
+### Basic Usage
+
+#### 1. Add the Plugin to Your Payload Config
+
+```typescript
+import { loadsparkCorePlugin } from '@loadspark/core'
+import { buildConfig } from 'payload'
+
+export default buildConfig({
+  plugins: [
+    loadsparkCorePlugin,
+  ],
+})
+```
+
+#### 2. Use Custom Fields in Your Collections
+
+```typescript
+import { AlertBoxField, TelephoneField } from '@loadspark/core/fields'
+
+export const MyCollection: CollectionConfig = {
+  slug: 'my-collection',
+  fields: [
+    AlertBoxField({
+      config: {
+        type: 'info',
+        message: 'This is an informational alert',
+      },
+      overrides: {
+        name: 'infoAlert',
+      },
+    }),
+    TelephoneField({
+      config: {
+        defaultCountry: 'us',
+      },
+      overrides: {
+        name: 'phone',
+        label: { en: 'Phone Number', de: 'Telefonnummer' },
+      },
+    }),
+  ],
+}
+```
+
+#### 3. Use Access Control Functions
+
+```typescript
+import { hasAdminPermissions, hasEditorPermissions } from '@loadspark/core/access'
+
+export const MyCollection: CollectionConfig = {
+  slug: 'my-collection',
+  access: {
+    read: ({ req: { user } }) => {
+      return hasEditorPermissions(user)
+    },
+    update: ({ req: { user } }) => {
+      return hasAdminPermissions(user)
+    },
+  },
+}
+```
+
+#### 4. Use Validations
+
+```typescript
+import { future, greaterThan } from '@loadspark/core/validations'
+
+export const MyCollection: CollectionConfig = {
+  slug: 'my-collection',
+  fields: [
+    {
+      name: 'startDate',
+      type: 'date',
+      validate: [future()],
+    },
+    {
+      name: 'maxValue',
+      type: 'number',
+      validate: [
+        greaterThan(
+          {
+            field: 'minValue',
+            labels: { en: 'Minimum Value', de: 'Mindestwert' },
+          },
+          { override: false },
+        ),
+      ],
+    },
+  ],
+}
+```
+
+---
+
+## Components
+
+### Custom Fields
+
+The plugin provides a comprehensive set of custom fields, each designed to solve common use cases while remaining fully customizable.
+
+| Field Name       | Type      | Description                                       | Documentation                |
+| ---------------- | --------- | ------------------------------------------------- | ---------------------------- |
+| **AlertBox**     | custom    | Display styled alerts with custom types           | [Docs](docs/AlertBox.md)     |
+| **ColourText**   | text      | Text field with color-specific options            | [Docs](docs/ColourText.md)   |
+| **Combo**        | composite | Combine multiple subfields into one field         | [Docs](docs/Combo.md)        |
+| **Number**       | number    | Enhanced numeric field with validation            | [Docs](docs/Number.md)       |
+| **OpeningHours** | custom    | Structured opening hours for schedules            | [Docs](docs/OpeningHours.md) |
+| **Pattern**      | text      | Regex-based input validation                      | [Docs](docs/Pattern.md)      |
+| **Range**        | number    | Slider-based numeric range input                  | [Docs](docs/Range.md)        |
+| **Slug**         | text      | Auto-generated URL slug with formatting           | [Docs](docs/Slug.md)         |
+| **Telephone**    | text      | Phone number field with formatting and validation | [Docs](docs/Telephone.md)    |
+
+#### Field Override Pattern
+
+All custom fields follow a consistent pattern that allows full customization:
+
+```typescript
+FieldName({
+  config: {
+    // Field-specific configuration
+  },
+  overrides: {
+    // Any Payload field property can be overridden
+    name: 'customFieldName',
+    label: { en: 'Custom Label', de: 'Benutzerdefiniertes Label' },
+    admin: {
+      condition: (data) => data.someField === 'value',
+    },
+    // ... any other field properties
+  },
+})
+```
+
+**Key Points:**
+
+- All fields are **fully overridable** - you can override any Payload field property
+- Field-specific configuration is separated from general field properties
+- Type-safe with full TypeScript support
+- Each field has detailed documentation in the `docs/` folder
+
+#### Importing Fields
+
+Fields can be imported individually or as a group:
+
+```typescript
+// Individual field import
+import { AlertBoxField } from '@loadspark/core/fields/Alox'
+
+// All fields
+import { AlertBoxField, TelephoneField, SlugField } from '@loadspark/core/fields'
+
+// Client-side components (if needed)
+import { AlertBoxClient } from '@loadspark/core/fields/AlertBox/client'
+```
+
+### Validations
+
+The plugin provides reusable validation functions for dates, numbers, and relations.
+
+#### Date Validations
+
+```typescript
+import {
+  after,
+  afterOrEqual,
+  before,
+  beforeOrEqual,
+  future,
+  futureOrEqual,
+  past,
+  pastOrEqual,
+} from '@loadspark/core/validations'
+```
+
+**Field vs Field:**
+
+```typescript
+{
+  name: 'endDate',
+  type: 'date',
+  validate: [
+    after({
+      field: 'startDate',
+      labels: { en: 'Start Date', de: 'Startdatum' },
+    }),
+  ],
+}
+```
+
+**Field vs Now:**
+
+```typescript
+{
+  name: 'publishDate',
+  type: 'date',
+  validate: [future()], // Must be in the future
+}
+```
+
+**With Programmatic Override:**
+
+```typescript
+{
+  name: 'eventDate',
+  type: 'date',
+  validate: (val, ctx) => {
+    return past(undefined, { 
+      override: ctx.req?.user?.role === 'admin' // Skip validation for admins
+    })(val, ctx)
+  },
+}
+```
+
+#### Number Validations
+
+```typescript
+import {
+  greaterThan,
+  greaterThanOrEqual,
+  lessThan,
+  lessThanOrEqual,
+} from '@loadspark/core/validations'
+```
+
+**Example:**
+
+```typescript
+{
+  name: 'maxValue',
+  type: 'number',
+  validate: (val, ctx) => {
+    return greaterThan(
+      {
+        field: 'minValue',
+        labels: { en: 'Minimum Value', de: 'Mindestwert' },
+      },
+      { override: ctx.req?.user?.role === 'admin' }, // Skip validation conditionally
+    )(val, ctx)
+  },
+}
+```
+
+#### Relation Validations
+
+```typescript
+import { relationLinkedUser } from '@loadspark/core/validations'
+
+{
+  name: 'assignedUser',
+  type: 'relationship',
+  relationTo: 'users',
+  validate: [relationLinkedUser()],
+}
+```
+
+**Key Features:**
+
+- All validations support i18n error messages
+- Programmatic override support to conditionally skip validations
+- Type-safe with full TypeScript support
+- Can compare fields to other fields or constants
+
+### Translations
+
+The plugin includes comprehensive translations all payload supported languages
+
+#### Using Translations
+
+Translations are automatically merged when you use the plugin:
+
+#### Translation Keys
+
+Translation object shapes can be found in language files e.g `src/translations/languages/en.ts`
+These keys are easily overridable by providing the custom translations to payloadcms as
+
+```typescript
+const customEnTranslations = {
+  'loadspark-core': {
+    users: {
+      roles: {
+        options: {
+          admin: 'Custom Admin Label',
+        },
+      },
+    },
+  },
+}
+
+
+i18n: {
+    fallbackLanguage: 'en',
+    supportedLanguages: {
+      en,
+    },
+    translations: {
+      en: customEnTranslations,
+    },
+  },
+```
+
+### Collections
+
+#### Users Collection
+
+The plugin provides a pre-configured Users collection with sensible defaults.
+
+**Features:**
+
+- Role-based access control
+- System user support
+- Automatic first-user admin assignment
+- Overridable fields and configuration
+- Built-in hooks for user management
+
+**Default Fields:**
+
+- `email` - User email (required)
+- `role` - User role (user, admin, super-admin)
+
+**Accessing User Collection Utilities:**
+
+```typescript
+import {
+  getUserFields,
+  createUserAccess,
+  readUserAccess,
+  updateUserAccess,
+  deleteUserAccess,
+} from '@loadspark/core/users'
+```
+#### Types
+
+```typescript
+import type { CorePluginConfig, UserFieldOverrides } from '@loadspark/core/types'
+```
+
+### Utils
+
+Utility functions for common operations
+
+```typescript
+import { getItemInNestedObject } from '@loadspark/core/utils'
+```
+
+
+## Overrides & Customization
+
+One of the core principles of this plugin is that **everything is overridable**. This allows you to customize the plugin to your needs while maintaining a solid foundation
+
+### Field-Level Overrides
+
+All custom fields support overriding any Payload field property:
+
+```typescript
+AlertBoxField({
+  config: {
+    // Field-specific config
+  },
+  overrides: {
+    name: 'customName',
+    label: { en: 'Custom', de: 'Benutzerdefiniert' },
+    admin: {
+      condition: (data) => data.showAlert,
+      position: 'sidebar',
+    },
+    // Any other field property
+  },
+})
+```
+
+### Access Overrides
+
+Access rules can be overridden at the field or collection level
+
+### Validation Overrides
+
+Validations support programmatic override conditions that allow you to skip validation based on any condition:
+
+```typescript
+{
+  name: 'publishDate',
+  type: 'date',
+  validate: (val, ctx) => {
+    return future(undefined, { 
+      override: ctx.req?.user?.role === 'admin' // Conditionally skip validation
+    })(val, ctx)
+  },
+}
+```
+
+The `override` option accepts a boolean value that you can set programmatically based on any condition (user role, field values, etc.). When `override: true`, the validation is skipped entirely.
+
+---
+
+## Documentation
+
+### Field Documentation
+
+Each custom field has detailed documentation in the `docs/` folder:
+
+- [AlertBox](docs/AlertBox.md) - Display styled alerts
+- [ColourText](docs/ColourText.md) - Text field with color options
+- [Combo](docs/Combo.md) - Composite field combining multiple subfields
+- [Number](docs/Number.md) - Enhanced number field
+- [OpeningHours](docs/OpeningHours.md) - Opening hours management
+- [Pattern](docs/Pattern.md) - Regex-based validation
+- [Range](docs/Range.md) - Slider-based range input
+- [Slug](docs/Slug.md) - Auto-generated URL slugs
+- [Telephone](docs/Telephone.md) - Phone number input with validation
+
+### Example Collections
+
+Working examples of all fields can be found in `dev/collections/`:
+
+- `alert-examples.ts`
+- `colour-text-examples.ts`
+- `combo-examples.ts`
+- `number-examples.ts`
+- `opening-hours-examples.ts`
+- `pattern-examples.ts`
+- `range-examples.ts`
+- `slug-examples.ts`
+- `telephone-examples.ts`
+
+---
+
+## Contributing
+
+Contributions are currently **not yet** being accepted due to the rapid development pace and "move quick, break things" philosophy. However, we welcome:
+
+- Bug reports
+- Feature suggestions
+- Documentation improvements
+
+Once the plugin stabilizes, we'll open up for contributions. In the meantime, feel free to fork and customize for your needs!
+
+### Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/Welle-IT/loadspark-plugin-core.git
+
+# Install dependencies
+pnpm install
+
+# Build the project
+pnpm build
+
+# Run development server
+pnpm dev
+
+# Run tests
+pnpm test
+```
+
+---
+
+## License
+
+This software is provided free of charge for use, modification, and distribution by any individual or legal entity ("Licensee") whose total annual gross revenue does not exceed USD 250,000.
+
+If the Licensee’s annual gross revenue exceeds USD 250,000, a paid commercial license is required.
+For commercial licensing, contact the [maintainer](mailto:welledigital882@gmail.com) at welledigital882@gmail.com.
+
+See [LICENSE.md](LICENSE.md) for full license details.
+
+---
+
+<div align="center">
+
+**Built with ❤️ for the PayloadCMS community**
+
+[Website](https://loadspark.dev) • [GitHub](https://github.com/Welle-IT/loadspark-plugin-core) • [Documentation](#documentation)
+
+</div>

package/dist/access/accessors.d.ts

@@ -0,0 +1,22 @@
+import type { Access, FieldAccess } from 'payload';
+/**
+ * Allows access to all resources if the user is a super-admin or admin but if the user is a regular user, it will only allow access to their own resources.
+ */
+export declare const userLinkedAccess: (opts?: import("payload").Where) => Access;
+/**
+ * Allows access to all resources, regardless of authentication status.
+ */
+export declare const hasPublicAccess: Access;
+/**
+ * Grants access to the field if the user is a super-admin.
+ * @param ctx
+ * @returns
+ */
+export declare const hasSuperAdminFieldLevelAccess: FieldAccess;
+/**
+ * Grants access to the field if the user is an admin or super-admin.
+ * @param ctx
+ * @returns
+ */
+export declare const hasAdminFieldLevelAccess: FieldAccess;
+//# sourceMappingURL=accessors.d.ts.map

package/dist/access/accessors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accessors.d.ts","sourceRoot":"","sources":["../../src/access/accessors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAKlD;;GAEG;AACH,eAAO,MAAM,gBAAgB,4CAAwB,CAAA;AAErD;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,MAAe,CAAA;AAE7C;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,EAAE,WAAsD,CAAA;AAElG;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,WACwB,CAAA"}