@marianmeres/collection-types 1.6.0 → 1.7.0

package/dist/linked-assets.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Linked Assets Configuration Types
+ *
+ * Types for the linked assets feature - a configuration-driven system
+ * for displaying assets that are implicitly linked via metadata matching
+ * rather than explicit relation records.
+ *
+ * Used by:
+ * - Joy admin (frontend configuration consumption)
+ * - Backend (configuration storage and bootstrap)
+ *
+ * @module linked-assets
+ */
+import type { MaybeLocalized } from "./utils.js";
+/**
+ * Comparison operators supported for matching conditions.
+ * Maps to @marianmeres/condition-builder OPERATOR enum.
+ */
+export type LinkedAssetOperator = "eq" | "neq" | "lt" | "lte" | "gt" | "gte" | "like" | "ilike" | "in" | "nin" | "?" | "descendant";
+/**
+ * Value source: where to get the value for matching.
+ * - "literal": use the value as-is
+ * - "model_field": extract from current model's data using dot-path
+ */
+export type LinkedAssetValueSource = "literal" | "model_field";
+/**
+ * A single matching condition for linked assets.
+ *
+ * @example
+ * // Match assets where data.custom.sku equals model's sku field
+ * {
+ *   asset_field: "data.custom.sku",
+ *   operator: "eq",
+ *   value_source: "model_field",
+ *   value: "sku"
+ * }
+ */
+export interface LinkedAssetCondition {
+    /**
+     * The field path on the asset model to match against.
+     * Examples: "type", "data.custom.sku", "folder", "tags"
+     */
+    asset_field: string;
+    /** Comparison operator */
+    operator: LinkedAssetOperator;
+    /** How to interpret the value */
+    value_source: LinkedAssetValueSource;
+    /**
+     * The value to match:
+     * - If value_source is "literal": the actual value to compare
+     * - If value_source is "model_field": dot-path to model field
+     */
+    value: string | number | boolean;
+}
+/**
+ * Upload configuration for linked assets.
+ * When present, enables file upload capability.
+ */
+export interface LinkedAssetUploadConfig {
+    /**
+     * Auto-populate custom fields from parent model during upload.
+     * Key: asset field path (e.g., "custom.sku")
+     * Value: model field path (e.g., "sku")
+     */
+    auto_fill_custom: Record<string, string>;
+    /**
+     * Asset type to use for uploads.
+     * @default asset_query.type
+     */
+    type?: string;
+    /**
+     * Accepted file types (MIME patterns).
+     * @default "image/*"
+     */
+    accept?: string;
+    /**
+     * Maximum number of files (-1 for unlimited).
+     * @default -1
+     */
+    cardinality?: number;
+}
+/**
+ * Unlink configuration for linked assets.
+ * Defines how to remove the link between asset and parent model.
+ */
+export interface LinkedAssetUnlinkConfig {
+    /**
+     * Which custom field to clear when unlinking.
+     * Should match a key from upload.auto_fill_custom.
+     */
+    field: string;
+    /**
+     * Require confirmation before unlinking.
+     * @default true
+     */
+    confirm?: boolean;
+}
+/**
+ * Asset query configuration within a rule.
+ */
+export interface LinkedAssetQueryConfig {
+    /**
+     * Asset domain to query.
+     * @default "asset"
+     */
+    domain?: string;
+    /**
+     * Asset entity/collection to query.
+     * @default "asset"
+     */
+    entity?: string;
+    /**
+     * Asset type filter (e.g., "product-image").
+     * If specified, adds `type:eq:<value>` to conditions.
+     */
+    type?: string;
+    /**
+     * Conditions to build the asset query.
+     * Combined with AND logic.
+     */
+    conditions: LinkedAssetCondition[];
+    /**
+     * Always include these base conditions.
+     * @default [{ asset_field: "is_enabled", operator: "eq", value_source: "literal", value: true }]
+     */
+    base_conditions?: LinkedAssetCondition[];
+}
+/**
+ * Match context configuration.
+ * Defines when a rule should be applied.
+ */
+export interface LinkedAssetMatchConfig {
+    /** Domain to match (e.g., "product") */
+    domain?: string;
+    /** Entity/collection to match (e.g., "product", "category") */
+    entity?: string;
+    /** Type to match (e.g., "default", "variant") */
+    type?: string;
+}
+/**
+ * A single linked assets rule configuration.
+ * Defines when and how to show/manage linked assets for a specific model context.
+ */
+export interface LinkedAssetRule {
+    /** Unique identifier for this rule */
+    id: string;
+    /** Human-readable label (supports localization) */
+    label: MaybeLocalized<string>;
+    /** Optional description */
+    description?: MaybeLocalized<string>;
+    /** When to apply this rule (AND logic, omitted = any) */
+    match: LinkedAssetMatchConfig;
+    /** Asset query configuration */
+    asset_query: LinkedAssetQueryConfig;
+    /** Upload configuration - enables CRUD mode when present */
+    upload?: LinkedAssetUploadConfig;
+    /** Unlink configuration - defines how to remove links */
+    unlink?: LinkedAssetUnlinkConfig;
+    /**
+     * Whether this rule is enabled.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Sort order when multiple rules match (lower = earlier).
+     * @default 0
+     */
+    order?: number;
+}
+/**
+ * The complete linked assets configuration structure.
+ * Stored as the value of the `__joy_linked_assets__` config record.
+ */
+export interface LinkedAssetsConfig {
+    /**
+     * Schema version for future migrations.
+     */
+    version: number;
+    /**
+     * Array of linked asset rules.
+     */
+    rules: LinkedAssetRule[];
+}

package/dist/linked-assets.js

@@ -0,0 +1,14 @@
+/**
+ * Linked Assets Configuration Types
+ *
+ * Types for the linked assets feature - a configuration-driven system
+ * for displaying assets that are implicitly linked via metadata matching
+ * rather than explicit relation records.
+ *
+ * Used by:
+ * - Joy admin (frontend configuration consumption)
+ * - Backend (configuration storage and bootstrap)
+ *
+ * @module linked-assets
+ */
+export {};

package/dist/mod.d.ts

@@ -24,4 +24,5 @@ export * from "./relation.js";
 export * from "./schema.js";
 export * from "./api.js";
 export * from "./asset.js";
+export * from "./linked-assets.js";
 export * from "./adapter.js";

package/dist/mod.js

@@ -29,5 +29,7 @@ export * from "./schema.js";
 export * from "./api.js";
 // Assets
 export * from "./asset.js";
+// Linked Assets (metadata-based linking configuration)
+export * from "./linked-assets.js";
 // Adapter (database layer)
 export * from "./adapter.js";

package/dist/schema.d.ts

@@ -4,17 +4,21 @@
  */
 import type { MaybeLocalized } from "./utils.js";
 /** HTML field type for UI rendering */
-export type SchemaHtmlType = "text" | "textarea" | "wysiwyg" | "number" | "boolean" | "select" | "multiselect" | "date" | "datetime" | "time" | "color" | "relation" | "asset" | "json" | "code" | "keyvalues";
+export type SchemaHtmlType = "text" | "textarea" | "wysiwyg" | "number" | "boolean" | "checkbox" | "parent" | "object" | "select" | "multiselect" | "date" | "datetime" | "time" | "color" | "relation" | "asset" | "json" | "code" | "keyvalues";
 /** Configuration for relation-type fields in schema */
 export interface RelationTypeConfig {
     relation_type: string;
     domain?: string;
     entity?: string;
     cardinality?: number;
+    /** Entity type filter (e.g., "default", "top") */
+    type?: string;
+    /** Allow unknown relations */
+    allow_unknown?: boolean;
 }
 /** Configuration for asset-type fields in schema */
 export interface AssetTypeConfig {
-    accept?: string[];
+    accept?: string | string[];
     maxSize?: number;
     variants?: string[];
 }
@@ -35,13 +39,32 @@ export interface KeyValuesConfig {
 }
 /** Configuration for _html schema keyword */
 export interface SchemaHtmlConfig {
-    type: SchemaHtmlType;
+    /** Field type for UI rendering */
+    type?: SchemaHtmlType;
+    /** Type-specific configuration */
     _type_config?: RelationTypeConfig | AssetTypeConfig | SelectConfig | KeyValuesConfig;
+    /** Display label (can be localized) */
+    label?: MaybeLocalized<string>;
+    /** Display description (can be localized) */
+    description?: MaybeLocalized<string>;
+    /** Fieldset grouping label (can be localized) */
+    _fieldset?: MaybeLocalized<string>;
+    /** Order in model form */
+    _model_form_order?: number;
+    /** Order in data table */
+    _data_table_order?: number;
+    /** Number of textarea rows */
     rows?: number;
+    /** Input placeholder text */
     placeholder?: string;
+    /** Help text */
     help?: string;
+    /** Read-only field */
     readonly?: boolean;
+    /** Hidden field */
     hidden?: boolean;
+    /** UI-specific default (distinct from _default) (typically JSON serialized) */
+    _default?: string;
 }
 /**
  * Custom JSON Schema keywords for collection system.
@@ -51,7 +74,7 @@ export interface CustomSchemaKeywords {
     /** Default value for property */
     _default?: unknown;
     /** UI hint configuration object */
-    _html?: SchemaHtmlConfig | Record<string, unknown>;
+    _html?: SchemaHtmlConfig;
     /** Property title for display (can be localized) */
     _title?: MaybeLocalized<string>;
     /** Property description for display (can be localized) */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/collection-types",
-	"version": "1.6.0",
+	"version": "1.7.0",
 	"type": "module",
 	"main": "dist/mod.js",
 	"types": "dist/mod.d.ts",