@stonecrop/stonecrop 0.10.16 → 0.11.0

package/dist/registry.js

@@ -13,12 +13,30 @@ export default class Registry {
      *
      * @defaultValue 'Registry'
      */
-    name;
+    name = 'Registry';
     /**
      * The registry property contains a collection of doctypes
+     *
+     * @defaultValue `{}`
      * @see {@link Doctype}
      */
-    registry;
+    registry = {};
+    /**
+     * Reverse index: backlink fieldname → list of \{ doctype slug, link fieldname \}.
+     * Multiple doctypes can declare a link with the same backlink name, so each key
+     * maps to an array. Built at schema load time for O(1) ancestor lookups.
+     *
+     * @defaultValue `new Map()`
+     * @internal
+     */
+    _ancestorIndex = new Map();
+    /**
+     * Whether the ancestor index needs rebuilding
+     *
+     * @defaultValue `true`
+     * @internal
+     */
+    _ancestorIndexDirty = true;
     /**
      * The Vue router instance
      * @see {@link https://router.vuejs.org/}
@@ -34,8 +52,6 @@ export default class Registry {
             return Registry._root;
         }
         Registry._root = this;
-        this.name = 'Registry';
-        this.registry = {};
         this.router = router;
         this.getMeta = getMeta;
     }
@@ -53,6 +69,7 @@ export default class Registry {
     addDoctype(doctype) {
         if (!(doctype.slug in this.registry)) {
             this.registry[doctype.slug] = doctype;
+            this._ancestorIndexDirty = true;
         }
         // Register actions (including field triggers) with the field trigger engine
         const triggerEngine = getGlobalTriggerEngine();
@@ -72,95 +89,120 @@ export default class Registry {
     /**
      * Resolve nested Doctype fields in a schema by embedding child schemas inline.
      *
-     * @remarks
-     * Walks the schema array and for each field with `fieldtype: 'Doctype'` and a string
-     * `options` value, looks up the referenced doctype in the registry and:
+     * Accepts a Doctype and extracts `fields` and `links` internally.
+     * Fields array contains both scalar fields and link fields (with fieldtype: 'Link').
+     * Render order is determined by the order of fields in the fields array.
      *
-     * - If `cardinality: 'many'`: auto-derives `columns` from the child doctype's schema,
-     *   sets `component: 'ATable'`, `config: { view: 'list' }`, and initializes `rows: []`.
-     * - Otherwise (default/`cardinality: 'one'`): embeds the child schema as the field's
-     *   `schema` property for 1:1 nested forms.
+     * For each link field:
+     * - Looks up the corresponding link declaration in `links` by fieldname
+     * - `cardinality: 'noneOrMany'` or `'atLeastOne'`: auto-derives `columns` from the target's schema,
+     *   sets `component` to `link.component ?? 'ATable'`, `config: { view: 'list' }`, `rows: []`.
+     * - `cardinality: 'one'` or `'atMostOne'`: embeds the target schema as the entry's
+     *   `schema` property, sets `component` to `link.component ?? 'AForm'`.
      *
      * Recurses for deeply nested doctypes. Circular references are protected against.
+     * Returns a new array — does not mutate the original.
      *
-     * Returns a new array — does not mutate the original schema.
-     *
-     * @param schema - The schema array to resolve
-     * @returns A new schema array with nested Doctype fields resolved
-     *
-     * @example
-     * ```ts
-     * registry.addDoctype(addressDoctype)
-     * registry.addDoctype(customerDoctype)
-     *
-     * // Before: customer schema has { fieldname: 'address', fieldtype: 'Doctype', options: 'address' }
-     * const resolved = registry.resolveSchema(customerSchema)
-     * // After: address field now has schema: [...address fields...]
-     * ```
+     * @param doctype - The doctype to resolve
+     * @param visited - Internal — set of already-visited doctype slugs for cycle detection
+     * @returns A new schema array with nested links resolved
      *
      * @public
      */
-    resolveSchema(schema, visited) {
-        const seen = visited || new Set();
-        return schema.map(field => {
-            // Check for Doctype fieldtype with a string options (slug reference)
-            if ('fieldtype' in field &&
-                field.fieldtype === 'Doctype' &&
-                'options' in field &&
-                typeof field.options === 'string') {
-                const doctypeSlug = field.options;
-                // Circular reference protection
-                if (seen.has(doctypeSlug)) {
-                    return { ...field };
+    resolveSchema(doctype, visited) {
+        const seen = visited ?? new Set();
+        const slug = doctype.slug;
+        // Prevent circular resolution
+        if (seen.has(slug)) {
+            return doctype.schema ? (Array.isArray(doctype.schema) ? doctype.schema : Array.from(doctype.schema)) : [];
+        }
+        seen.add(slug);
+        // Convert schema to array
+        const schemaArray = doctype.schema
+            ? Array.isArray(doctype.schema)
+                ? doctype.schema
+                : Array.from(doctype.schema)
+            : [];
+        // Build a map of link declarations by fieldname for quick lookup
+        // Use the link's fieldname property if set, otherwise use the key
+        const linksByFieldname = new Map();
+        if (doctype.links) {
+            for (const [key, link] of Object.entries(doctype.links)) {
+                const linkFieldname = link.fieldname ?? key;
+                linksByFieldname.set(linkFieldname, link);
+            }
+        }
+        // Process fields in order: scalar fields copied as-is, link fields resolved
+        const resolvedFields = [];
+        for (const field of schemaArray) {
+            // Check if this field is a link field (fieldtype: 'Link')
+            if ('fieldtype' in field && field.fieldtype === 'Link') {
+                const link = linksByFieldname.get(field.fieldname);
+                if (!link) {
+                    // Link field without corresponding link declaration - copy as-is
+                    resolvedFields.push({ ...field });
+                    continue;
                 }
-                const doctype = this.registry[doctypeSlug];
-                if (doctype && doctype.schema) {
-                    // Convert Immutable.List to plain array if needed
-                    const childSchema = Array.isArray(doctype.schema) ? doctype.schema : Array.from(doctype.schema);
-                    // Check cardinality to determine handling
-                    const cardinality = 'cardinality' in field ? field.cardinality : undefined;
-                    if (cardinality === 'many') {
-                        // 1:many child table - derive columns, set component, config, rows
-                        const resolved = { ...field };
-                        // Auto-derive columns from child schema fields if not already provided
-                        if (!('columns' in field) || !field.columns) {
-                            resolved.columns = childSchema.map(childField => ({
-                                name: childField.fieldname,
-                                fieldname: childField.fieldname,
-                                label: ('label' in childField && childField.label) || childField.fieldname,
-                                fieldtype: 'fieldtype' in childField ? childField.fieldtype : 'Data',
-                                align: ('align' in childField && childField.align) || 'left',
-                                edit: 'edit' in childField ? childField.edit : true,
-                                width: ('width' in childField && childField.width) || '20ch',
-                            }));
-                        }
-                        // Set default component if not already specified
-                        if (!resolved.component) {
-                            resolved.component = 'ATable';
-                        }
-                        // Set default config if not already specified
-                        if (!('config' in field) || !field.config) {
-                            resolved.config = { view: 'list' };
-                        }
-                        // Initialize rows to empty array so componentProps fallback
-                        // routes data from the form's dataModel[fieldname]
-                        if (!('rows' in field) || !field.rows) {
-                            resolved.rows = [];
-                        }
-                        return resolved;
-                    }
-                    else {
-                        // 1:1 nested form (default cardinality: 'one')
-                        // Recurse into child schema to resolve deeply nested doctypes
-                        seen.add(doctypeSlug);
-                        const resolvedChild = this.resolveSchema(childSchema, seen);
-                        seen.delete(doctypeSlug);
-                        return { ...field, schema: resolvedChild };
-                    }
+                const targetDoctype = this.registry[link.target];
+                if (!targetDoctype) {
+                    // Target not found - copy as-is
+                    resolvedFields.push({ ...field });
+                    continue;
+                }
+                const childSchema = this.resolveSchema(targetDoctype, seen);
+                if (link.cardinality === 'noneOrMany' || link.cardinality === 'atLeastOne') {
+                    // Many relationship — build table config
+                    resolvedFields.push(this.buildTableConfig({ fieldname: field.fieldname, label: field.label || field.fieldname }, childSchema, link.component));
+                }
+                else {
+                    // One relationship — embed form schema
+                    resolvedFields.push({
+                        fieldname: field.fieldname,
+                        label: field.label || field.fieldname,
+                        component: link.component || 'AForm',
+                        schema: childSchema,
+                    });
                 }
             }
-            return { ...field };
-        });
+            else {
+                // Scalar field — copy as-is
+                resolvedFields.push({ ...field });
+            }
+        }
+        seen.delete(slug);
+        return resolvedFields;
+    }
+    /**
+     * Build an ATable configuration from a field and child schema
+     * @internal
+     */
+    buildTableConfig(field, childSchema, component) {
+        const resolved = {
+            fieldname: field.fieldname,
+            component: component || field.component || 'ATable',
+            columns: field.columns,
+            config: field.config,
+            rows: field.rows,
+        };
+        if (!resolved.columns) {
+            resolved.columns = childSchema
+                .filter(childField => 'fieldtype' in childField)
+                .map(childField => ({
+                name: childField.fieldname,
+                label: ('label' in childField && childField.label) || childField.fieldname,
+                fieldtype: 'fieldtype' in childField ? childField.fieldtype : 'Data',
+                align: 'align' in childField ? childField.align : 'left',
+                edit: 'edit' in childField ? childField.edit : true,
+                width: ('width' in childField && childField.width) || '20ch',
+            }));
+        }
+        if (!resolved.config) {
+            resolved.config = { view: 'list' };
+        }
+        if (!resolved.rows) {
+            resolved.rows = [];
+        }
+        return resolved;
     }
     /**
      * Initialize a new record with default values based on a schema.
@@ -172,7 +214,7 @@ export default class Registry {
      * - Check → `false`
      * - Int, Float, Decimal, Currency, Quantity → `0`
      * - JSON → `{}`
-     * - Doctype with `cardinality: 'many'` → `[]`
+     * - Doctype with `cardinality: 'noneOrMany'` or `'atLeastOne'` → `[]`
      * - Doctype without `cardinality` or `cardinality: 'one'` → recursively initializes nested record
      * - All others → `null`
      *
@@ -194,6 +236,22 @@ export default class Registry {
         const record = {};
         schema.forEach(field => {
             const fieldtype = 'fieldtype' in field ? field.fieldtype : 'Data';
+            const cardinality = 'cardinality' in field ? field.cardinality : undefined;
+            // 1:many — cardinality signals an array
+            if (cardinality === 'noneOrMany' || cardinality === 'atLeastOne') {
+                record[field.fieldname] = [];
+                return;
+            }
+            // Resolved 1:many table entry — has rows property
+            if ('rows' in field) {
+                record[field.fieldname] = [];
+                return;
+            }
+            // Resolved 1:1 link entry — has schema property (e.g., FieldsetSchema with nested schema)
+            if ('schema' in field && Array.isArray(field.schema)) {
+                record[field.fieldname] = this.initializeRecord(field.schema);
+                return;
+            }
             switch (fieldtype) {
                 case 'Data':
                 case 'Text':
@@ -213,23 +271,6 @@ export default class Registry {
                 case 'JSON':
                     record[field.fieldname] = {};
                     break;
-                case 'Doctype': {
-                    // Check cardinality to determine initial value
-                    const cardinality = 'cardinality' in field ? field.cardinality : undefined;
-                    if (cardinality === 'many') {
-                        // 1:many child table - initialize as empty array
-                        record[field.fieldname] = [];
-                    }
-                    else if ('schema' in field && Array.isArray(field.schema)) {
-                        // 1:1 nested form with resolved schema - recursively initialize
-                        record[field.fieldname] = this.initializeRecord(field.schema);
-                    }
-                    else {
-                        // 1:1 without resolved schema - empty object
-                        record[field.fieldname] = {};
-                    }
-                    break;
-                }
                 default:
                     record[field.fieldname] = null;
             }
@@ -245,4 +286,123 @@ export default class Registry {
     getDoctype(slug) {
         return this.registry[slug];
     }
+    /**
+     * Get all links declared on a doctype.
+     *
+     * @param doctypeSlug - The doctype slug to get links for
+     * @returns Array of link declarations with fieldname, or empty array if none
+     *
+     * @example
+     * ```ts
+     * const links = registry.getDescendantLinks('recipe')
+     * // [{ fieldname: 'tasks', target: 'recipe-task', cardinality: 'noneOrMany', backlink: 'recipe' }]
+     * ```
+     *
+     * @public
+     */
+    getDescendantLinks(doctypeSlug) {
+        const doctype = this.registry[doctypeSlug];
+        if (!doctype?.links)
+            return [];
+        return Object.entries(doctype.links).map(([fieldname, link]) => ({
+            ...link,
+            fieldname,
+        }));
+    }
+    /**
+     * Get links on other doctypes that target the given doctype.
+     *
+     * @param doctypeSlug - The doctype slug to find ancestor links for
+     * @returns Array of link declarations with fieldname and declaring doctype slug, or empty array
+     *
+     * @example
+     * ```ts
+     * const ancestors = registry.getAncestorLinks('recipe-task')
+     * // [{ fieldname: 'tasks', target: 'recipe-task', cardinality: 'noneOrMany', backlink: 'recipe', doctype: 'recipe' }]
+     * ```
+     *
+     * @public
+     */
+    getAncestorLinks(doctypeSlug) {
+        this._ensureAncestorIndex();
+        const results = [];
+        for (const [_backlink, entries] of this._ancestorIndex) {
+            for (const { slug: declaringSlug, fieldname } of entries) {
+                const declaringDoctype = this.registry[declaringSlug];
+                if (!declaringDoctype?.links)
+                    continue;
+                const link = declaringDoctype.links[fieldname];
+                if (link?.target === doctypeSlug) {
+                    results.push({
+                        ...link,
+                        fieldname,
+                        doctype: declaringSlug,
+                    });
+                }
+            }
+        }
+        return results;
+    }
+    /**
+     * Ensure the ancestor index is up to date
+     * @internal
+     */
+    _ensureAncestorIndex() {
+        if (!this._ancestorIndexDirty)
+            return;
+        this._ancestorIndexDirty = false;
+        this._ancestorIndex.clear();
+        for (const [slug, doctype] of Object.entries(this.registry)) {
+            if (!doctype.links)
+                continue;
+            for (const [fieldname, link] of Object.entries(doctype.links)) {
+                if (link.backlink) {
+                    const existing = this._ancestorIndex.get(link.backlink);
+                    if (existing) {
+                        existing.push({ slug, fieldname });
+                    }
+                    else {
+                        this._ancestorIndex.set(link.backlink, [{ slug, fieldname }]);
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Convert the registry to a Map of DoctypeMeta objects for use with StonecropClient.
+     *
+     * This allows passing a Registry instance to StonecropClient by deriving the
+     * Map\<string, DoctypeMeta\> that StonecropClient needs for building nested GraphQL queries.
+     *
+     * @returns Map of doctype metadata keyed by doctype name
+     *
+     * @example
+     * ```typescript
+     * const registry = new Registry()
+     * registry.addDoctype(Doctype.fromObject(customerSchema))
+     * registry.addDoctype(Doctype.fromObject(orderSchema))
+     *
+     * const client = new StonecropClient({
+     *   endpoint: '/graphql',
+     *   registry: registry.toMetaMap(),  // Convert once, use with client
+     * })
+     * ```
+     *
+     * @public
+     */
+    toMetaMap() {
+        const map = new Map();
+        for (const [slug, doctype] of Object.entries(this.registry)) {
+            const fields = doctype.schema ? doctype.schema.toArray() : [];
+            const meta = {
+                name: doctype.name,
+                slug: slug,
+                fields: fields,
+                links: doctype.links,
+                workflow: doctype.workflow,
+            };
+            map.set(doctype.name, meta);
+        }
+        return map;
+    }
 }

package/dist/schema-validator.js

@@ -19,6 +19,7 @@ export class SchemaValidator {
         this.options = {
             registry: options.registry || null,
             validateLinkTargets: options.validateLinkTargets ?? true,
+            validateLinks: options.validateLinks ?? true,
             validateActions: options.validateActions ?? true,
             validateWorkflows: options.validateWorkflows ?? true,
             validateRequiredProperties: options.validateRequiredProperties ?? true,
@@ -30,9 +31,10 @@ export class SchemaValidator {
      * @param schema - Schema fields (List or Array)
      * @param workflow - Optional workflow configuration
      * @param actions - Optional actions map
+     * @param links - Optional links object
      * @returns Validation result
      */
-    validate(doctype, schema, workflow, actions) {
+    validate(doctype, schema, workflow, actions, links) {
         const issues = [];
         // Convert schema to array for easier iteration
         const schemaArray = schema ? (Array.isArray(schema) ? schema : schema.toArray()) : [];
@@ -44,6 +46,10 @@ export class SchemaValidator {
         if (this.options.validateLinkTargets && this.options.registry) {
             issues.push(...this.validateLinkFields(doctype, schemaArray, this.options.registry));
         }
+        // Validate links object
+        if (this.options.validateLinks && this.options.registry && links) {
+            issues.push(...this.validateLinkDeclarations(doctype, links, schemaArray, this.options.registry));
+        }
         // Validate workflow configuration
         if (this.options.validateWorkflows && workflow) {
             issues.push(...this.validateWorkflow(doctype, workflow));
@@ -157,6 +163,104 @@ export class SchemaValidator {
         }
         return issues;
     }
+    /**
+     * Validates link declarations: target resolution, backlink consistency, Link field correspondence
+     * @internal
+     */
+    validateLinkDeclarations(doctype, links, schema, registry) {
+        const issues = [];
+        // Build a map of Link fields by fieldname for quick lookup
+        const linkFieldsByFieldname = new Map();
+        for (const field of schema) {
+            if ('fieldtype' in field && field.fieldtype === 'Link') {
+                linkFieldsByFieldname.set(field.fieldname, field);
+            }
+        }
+        for (const [fieldname, link] of Object.entries(links)) {
+            // Check target resolves in registry
+            const targetDoctype = registry.registry[link.target];
+            if (!targetDoctype) {
+                issues.push({
+                    severity: ValidationSeverity.ERROR,
+                    rule: 'link-invalid-target',
+                    message: `Link "${fieldname}" references non-existent doctype: "${link.target}"`,
+                    doctype,
+                    fieldname,
+                    context: { target: link.target },
+                });
+                continue;
+            }
+            // Warn on self-referential target
+            if (link.target === doctype) {
+                issues.push({
+                    severity: ValidationSeverity.WARNING,
+                    rule: 'link-self-referential',
+                    message: `Link "${fieldname}" is self-referential (target: "${link.target}")`,
+                    doctype,
+                    fieldname,
+                    context: { target: link.target },
+                });
+            }
+            // Check backlink consistency
+            if (link.backlink && targetDoctype.links) {
+                const reciprocalLink = targetDoctype.links[link.backlink];
+                if (!reciprocalLink) {
+                    issues.push({
+                        severity: ValidationSeverity.ERROR,
+                        rule: 'link-backlink-missing',
+                        message: `Backlink "${link.backlink}" not found on target doctype "${link.target}"`,
+                        doctype,
+                        fieldname,
+                        context: { backlink: link.backlink, target: link.target },
+                    });
+                }
+                else if (reciprocalLink.target !== doctype) {
+                    issues.push({
+                        severity: ValidationSeverity.WARNING,
+                        rule: 'link-backlink-mismatch',
+                        message: `Backlink "${link.backlink}" on "${link.target}" points to "${reciprocalLink.target}" instead of "${doctype}"`,
+                        doctype,
+                        fieldname,
+                        context: { backlink: link.backlink, target: link.target, actualTarget: reciprocalLink.target },
+                    });
+                }
+            }
+            // If Link field exists with same fieldname, verify it has matching target
+            // Only check if link has fieldname set (otherwise it's a standalone link without a field)
+            if (link.fieldname) {
+                const linkField = linkFieldsByFieldname.get(link.fieldname);
+                if (linkField) {
+                    const linkFieldOptions = 'options' in linkField ? linkField.options : undefined;
+                    const linkFieldTarget = typeof linkFieldOptions === 'string' ? linkFieldOptions : undefined;
+                    if (linkFieldTarget && linkFieldTarget !== link.target) {
+                        issues.push({
+                            severity: ValidationSeverity.ERROR,
+                            rule: 'link-field-target-mismatch',
+                            message: `Link field "${link.fieldname}" targets "${linkFieldTarget}" but link declaration targets "${link.target}"`,
+                            doctype,
+                            fieldname: link.fieldname,
+                            context: { linkFieldTarget, linkTarget: link.target },
+                        });
+                    }
+                }
+            }
+        }
+        // Check that every Link field has a corresponding link declaration
+        // A Link field corresponds to a link if the link's fieldname property matches the field's fieldname
+        for (const [fieldname, _field] of linkFieldsByFieldname) {
+            const hasCorrespondingLink = Object.values(links).some(link => link.fieldname === fieldname);
+            if (!hasCorrespondingLink) {
+                issues.push({
+                    severity: ValidationSeverity.ERROR,
+                    rule: 'link-field-without-declaration',
+                    message: `Link field "${fieldname}" has no corresponding link declaration`,
+                    doctype,
+                    fieldname,
+                });
+            }
+        }
+        return issues;
+    }
     /**
      * Validates workflow state machine configuration
      * @internal

package/dist/src/composable.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Re-export shim — the implementation has moved to `composables/use-stonecrop.ts`.
+ *
+ * This file is kept so that any existing relative imports of `./composable` or
+ * `../composable` continue to resolve without changes. All public consumers
+ * should import from `@stonecrop/stonecrop` (the package root), which
+ * re-exports everything from `./composables/use-stonecrop` via `index.ts`.
+ */
+export type { OperationLogAPI, BaseStonecropReturn, HSTStonecropReturn, HSTChangeData } from './composables/stonecrop';
+export { useStonecrop } from './composables/stonecrop';
+//# sourceMappingURL=composable.d.ts.map

package/dist/src/composable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composable.d.ts","sourceRoot":"","sources":["../../src/composable.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AACtH,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA"}