@marianmeres/collection-types 1.15.0 → 1.17.0

package/dist/example.d.ts

@@ -31,11 +31,13 @@ export interface ExampleDataBar extends ExampleDataDefault {
 }
 /** Union of all example data types */
 export type ExampleData = ExampleDataDefault | ExampleDataFoo | ExampleDataBar;
-/** Comment model data for testing strong relations */
+/** Comment model data for testing strong and linked relations */
 export interface CommentData {
     body: string;
     author_name?: string;
     created_at?: string;
+    /** Links to examples with matching slug (for linked relation testing) */
+    example_slug?: string;
     /** Index signature for Model<T> compatibility */
     [key: string]: unknown;
 }

package/dist/linked.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Linked Configuration Types
+ *
+ * Types for the linked models feature - a configuration-driven system
+ * for displaying models 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
+ */
+import type { MaybeLocalized } from "./utils.js";
+/**
+ * Comparison operators supported for matching conditions.
+ * Maps to @marianmeres/condition-builder OPERATOR enum.
+ */
+export type LinkedOperator = "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 LinkedValueSource = "literal" | "model_field";
+/**
+ * A single matching condition for linked models.
+ *
+ * @example
+ * // Match models where data.custom.sku equals source model's sku field
+ * {
+ *   target_field: "data.custom.sku",
+ *   operator: "eq",
+ *   value_source: "model_field",
+ *   value: "sku"
+ * }
+ */
+export interface LinkedCondition {
+    /**
+     * The field path on the target model to match against.
+     * Examples: "type", "data.custom.sku", "folder", "tags"
+     */
+    target_field: string;
+    /** Comparison operator */
+    operator: LinkedOperator;
+    /** How to interpret the value */
+    value_source: LinkedValueSource;
+    /**
+     * The value to match:
+     * - If value_source is "literal": the actual value to compare
+     * - If value_source is "model_field": dot-path to source model field
+     */
+    value: string | number | boolean;
+}
+/**
+ * Upload configuration for linked models.
+ * When present, enables file upload capability.
+ */
+export interface LinkedUploadConfig {
+    /**
+     * Auto-populate custom fields from parent model during upload.
+     * Key: target field path (e.g., "custom.sku")
+     * Value: source model field path (e.g., "sku")
+     */
+    auto_fill_custom: Record<string, string>;
+    /**
+     * Target type to use for uploads.
+     * @default target_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 models.
+ * Defines how to remove the link between target and source model.
+ */
+export interface LinkedUnlinkConfig {
+    /**
+     * 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;
+}
+/**
+ * Target query configuration within a rule.
+ */
+export interface LinkedQueryConfig {
+    /**
+     * Target domain to query.
+     * @default "asset"
+     */
+    domain?: string;
+    /**
+     * Target entity/collection to query.
+     * @default "asset"
+     */
+    entity?: string;
+    /**
+     * Target type filter (e.g., "product-image").
+     * If specified, adds `type:eq:<value>` to conditions.
+     */
+    type?: string;
+    /**
+     * Conditions to build the target query.
+     * Combined with AND logic.
+     */
+    conditions: LinkedCondition[];
+    /**
+     * Always include these base conditions.
+     * @default [{ target_field: "is_enabled", operator: "eq", value_source: "literal", value: true }]
+     */
+    base_conditions?: LinkedCondition[];
+}
+/**
+ * Match context configuration.
+ * Defines when a rule should be applied.
+ */
+export interface LinkedMatchConfig {
+    /** 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;
+}
+/**
+ * Display options for rendering linked items.
+ * Used both as global defaults and per-rule overrides.
+ */
+export interface LinkedDisplayOptions {
+    /** Maximum number of items to show (default: 20) */
+    limit?: number;
+    /** Grid column count (default: 4) */
+    columns?: number;
+    /** Whether to show filenames below items (default: true) */
+    show_filename?: boolean;
+    /** Thumbnail variant size (default: "sm") */
+    thumbnail_variant?: "xs" | "sm" | "lg";
+}
+/**
+ * Configuration for the "Referenced By" feature.
+ * Shows which other models reference the current model via reverse lookup.
+ */
+export interface ReverseLinkedConfig {
+    /** Collections that display reverse linked lookups UI */
+    enabled_collections: Array<{
+        domain: string;
+        entity: string;
+        type?: string;
+    }>;
+}
+/**
+ * A single linked rule configuration.
+ * Defines when and how to show/manage linked models for a specific model context.
+ */
+export interface LinkedRule {
+    /** 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: LinkedMatchConfig;
+    /** Target query configuration */
+    target_query: LinkedQueryConfig;
+    /** Upload configuration - enables CRUD mode when present */
+    upload?: LinkedUploadConfig;
+    /** Unlink configuration - defines how to remove links */
+    unlink?: LinkedUnlinkConfig;
+    /**
+     * Whether this rule is enabled.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Sort order when multiple rules match (lower = earlier).
+     * @default 0
+     */
+    order?: number;
+    /** Display options for rendering (optional, falls back to config defaults) */
+    display?: LinkedDisplayOptions;
+}
+/**
+ * The complete linked configuration structure.
+ * Stored as the value of the `__joy_linked__` config record.
+ */
+export interface LinkedConfig {
+    /**
+     * Schema version for future migrations.
+     */
+    version: number;
+    /**
+     * Array of linked rules.
+     */
+    rules: LinkedRule[];
+    /** Global default display options (individual rules can override) */
+    defaults?: LinkedDisplayOptions;
+    /** Configuration for reverse lookups ("referenced by" feature) */
+    reverse?: ReverseLinkedConfig;
+}

package/dist/{linked-assets.js → linked.js}

@@ -1,14 +1,14 @@
 /**
- * Linked Assets Configuration Types
+ * Linked Configuration Types
  *
- * Types for the linked assets feature - a configuration-driven system
- * for displaying assets that are implicitly linked via metadata matching
+ * Types for the linked models feature - a configuration-driven system
+ * for displaying models 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
+ * @module linked
  */
 export {};

package/dist/mod.d.ts

@@ -33,7 +33,7 @@ export * from "./relation.js";
 export * from "./schema.js";
 export * from "./api.js";
 export * from "./asset.js";
-export * from "./linked-assets.js";
+export * from "./linked.js";
 export * from "./adapter.js";
 export * from "./session.js";
 export * from "./customer.js";

package/dist/mod.js

@@ -38,8 +38,8 @@ export * from "./schema.js";
 export * from "./api.js";
 // Assets
 export * from "./asset.js";
-// Linked Assets (metadata-based linking configuration)
-export * from "./linked-assets.js";
+// Linked models (metadata-based linking configuration)
+export * from "./linked.js";
 // Adapter (database layer)
 export * from "./adapter.js";
 // E-commerce domain types

package/package.json

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

package/dist/linked-assets.d.ts

@@ -1,183 +0,0 @@
-/**
- * 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[];
-}