@mj-biz-apps/contracts-entities 0.4.2 → 0.6.0

package/dist/ContractEntity.d.ts

@@ -21,6 +21,7 @@
  */
 import { ValidationResult } from '@memberjunction/core';
 import { mjBizAppsContractsContractEntity } from './generated/entity_subclasses.js';
+import { type ContractRenewalField } from './renewal-defaults.js';
 /**
  * Do two contracts sit at the SAME LEVEL of the tree — i.e. may one supersede the other?
  *
@@ -207,6 +208,49 @@ export declare class ContractEntity extends mjBizAppsContractsContractEntity {
      * neither does. Mirrors orders' `Confirm()`, which is likewise an intent-setter, not a persister.
      */
     Supersede(successor: ContractEntity): void;
+    /**
+     * Record that the USER set one of the four renewal fields, so seeding will never overwrite it.
+     *
+     * Called by the form panel that owns those fields, on every write it makes. It has to be an
+     * explicit signal rather than something derived from the entity's dirty state: `AutoRenew` starts
+     * at No on a new contract, so a user who deliberately answers No leaves the field holding the
+     * value it already had, and no amount of comparing against `OldValue` can tell that apart from a
+     * field nobody has looked at.
+     */
+    MarkRenewalFieldEdited(field: ContractRenewalField): void;
+    /**
+     * Copy the selected Contract Type's renewal defaults onto this contract.
+     *
+     * UNSAVED RECORDS ONLY, and this is the guard that makes the feature safe rather than merely
+     * convenient. On a saved contract every renewal value was typed by somebody reading the paper —
+     * including the blanks, which mean "the agreement says nothing" — so a type change on an existing
+     * record must not touch them. The story is about filling in a new contract, and the blast radius
+     * is kept to exactly that.
+     *
+     * Returns whether anything was written, so a caller can skip a redundant change-detection pass.
+     * Safe to call repeatedly with the same type: the computed seed is empty when the fields already
+     * hold their targets.
+     */
+    SeedRenewalDefaultsFromType(): Promise<boolean>;
+    /** The four fields as they stand right now. */
+    private currentRenewalValues;
+    /**
+     * The selected type's four default columns, or null when no type is selected — which restores the
+     * pristine values rather than leaving the departing type's numbers behind.
+     *
+     * One `RunView` rather than an entity load: four scalars are wanted and none of the type's rules
+     * are, and this runs on a keystroke-adjacent path (picking from a dropdown). The UUID is shape-
+     * checked before it reaches `ExtraFilter` for the same reason `ContractEntityServer` checks the
+     * one it walks the lineage with — this string is concatenated into SQL.
+     */
+    private loadRenewalDefaults;
+    /**
+     * Per-instance and deliberately NOT persisted: both of these describe an editing session, not the
+     * contract. A fresh instance of a saved record starts with neither, which is right — seeding does
+     * not run on saved records at all.
+     */
+    private readonly renewalFieldsUserEdited;
+    private renewalFieldsPristine;
 }
 /**
  * Anti-tree-shake anchor. Importing this module is what fires `@RegisterClass`; a production build

package/dist/ContractEntity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ContractEntity.d.ts","sourceRoot":"","sources":["../src/ContractEntity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAwD,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE9G,OAAO,EAAE,gCAAgC,EAAE,MAAM,+BAA+B,CAAC;AAEjF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAM5H;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM,EAAE,CAWpF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAAC,aAAa,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAUtF;AAED,qBACa,cAAe,SAAQ,gCAAgC;IAChE;;;;;;;;;;;;;OAaG;IACa,QAAQ,IAAI,gBAAgB;IAwB5C;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,wBAAwB;IAchC;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,kCAAkC;IAkB1C;;;;;;;;;;;;;;;;;;;OAmBG;IACH;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,OAAO,CAAC,4BAA4B;IAmBpC;;;;OAIG;IACH,SAAS,CAAC,uBAAuB,UAAS;IAE1C;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,yBAAyB;IAIjC;;;;;;;;;;;OAWG;IACI,SAAS,CAAC,SAAS,EAAE,cAAc,GAAG,IAAI;CAgBpD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}
+{"version":3,"file":"ContractEntity.d.ts","sourceRoot":"","sources":["../src/ContractEntity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAwD,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE9G,OAAO,EAAE,gCAAgC,EAAE,MAAM,+BAA+B,CAAC;AACjF,OAAO,EAGH,KAAK,oBAAoB,EAG5B,MAAM,oBAAoB,CAAC;AAS5B;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAM5H;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM,EAAE,CAWpF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAAC,aAAa,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAUtF;AAED,qBACa,cAAe,SAAQ,gCAAgC;IAChE;;;;;;;;;;;;;OAaG;IACa,QAAQ,IAAI,gBAAgB;IAwB5C;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,wBAAwB;IAchC;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,kCAAkC;IAkB1C;;;;;;;;;;;;;;;;;;;OAmBG;IACH;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,OAAO,CAAC,4BAA4B;IAmBpC;;;;OAIG;IACH,SAAS,CAAC,uBAAuB,UAAS;IAE1C;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,yBAAyB;IAIjC;;;;;;;;;;;OAWG;IACI,SAAS,CAAC,SAAS,EAAE,cAAc,GAAG,IAAI;IAqBjD;;;;;;;;OAQG;IACI,sBAAsB,CAAC,KAAK,EAAE,oBAAoB,GAAG,IAAI;IAIhE;;;;;;;;;;;;OAYG;IACU,2BAA2B,IAAI,OAAO,CAAC,OAAO,CAAC;IAsB5D,+CAA+C;IAC/C,OAAO,CAAC,oBAAoB;IAQ5B;;;;;;;;OAQG;YACW,mBAAmB;IAgBjC;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAmC;IAC3E,OAAO,CAAC,qBAAqB,CAA4B;CAE5D;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}

package/dist/ContractEntity.js

@@ -28,6 +28,13 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { BaseEntity, ValidationErrorInfo, ValidationErrorType } from '@memberjunction/core';
 import { RegisterClass } from '@memberjunction/global';
 import { mjBizAppsContractsContractEntity } from './generated/entity_subclasses.js';
+import { ComputeRenewalSeed, RENEWAL_SEED_FIELDS, } from './renewal-defaults.js';
+/**
+ * Guards an ID before it is interpolated into a filter. Mirrors `ContractEntityServer`'s own guard;
+ * both exist because MJ has no parameter binding on `ExtraFilter`, so the shape check IS the
+ * protection.
+ */
+const UUID_SHAPE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
 /**
  * Do two contracts sit at the SAME LEVEL of the tree — i.e. may one supersede the other?
  *
@@ -126,6 +133,13 @@ let ContractEntity = class ContractEntity extends mjBizAppsContractsContractEnti
          * the entity has any business claiming a number was system-assigned.
          */
         this.NumberWasSystemAssigned = false;
+        /**
+         * Per-instance and deliberately NOT persisted: both of these describe an editing session, not the
+         * contract. A fresh instance of a saved record starts with neither, which is right — seeding does
+         * not run on saved records at all.
+         */
+        this.renewalFieldsUserEdited = new Set();
+        this.renewalFieldsPristine = null;
     }
     /**
      * `HasModifications` is MONOTONIC: it must be true when modification rows exist, and it is never
@@ -299,6 +313,83 @@ let ContractEntity = class ContractEntity extends mjBizAppsContractsContractEnti
         }
         this.SupersededByContractID = successor.ID;
     }
+    /* ────────────────────────────────────────────────────────────────────────
+     * Renewal-obligation defaults (golive #217 / C-US1). The decision is in
+     * `renewal-defaults.ts`; this is the half that reads the type row and writes.
+     * ──────────────────────────────────────────────────────────────────────── */
+    /**
+     * Record that the USER set one of the four renewal fields, so seeding will never overwrite it.
+     *
+     * Called by the form panel that owns those fields, on every write it makes. It has to be an
+     * explicit signal rather than something derived from the entity's dirty state: `AutoRenew` starts
+     * at No on a new contract, so a user who deliberately answers No leaves the field holding the
+     * value it already had, and no amount of comparing against `OldValue` can tell that apart from a
+     * field nobody has looked at.
+     */
+    MarkRenewalFieldEdited(field) {
+        this.renewalFieldsUserEdited.add(field);
+    }
+    /**
+     * Copy the selected Contract Type's renewal defaults onto this contract.
+     *
+     * UNSAVED RECORDS ONLY, and this is the guard that makes the feature safe rather than merely
+     * convenient. On a saved contract every renewal value was typed by somebody reading the paper —
+     * including the blanks, which mean "the agreement says nothing" — so a type change on an existing
+     * record must not touch them. The story is about filling in a new contract, and the blast radius
+     * is kept to exactly that.
+     *
+     * Returns whether anything was written, so a caller can skip a redundant change-detection pass.
+     * Safe to call repeatedly with the same type: the computed seed is empty when the fields already
+     * hold their targets.
+     */
+    async SeedRenewalDefaultsFromType() {
+        if (this.IsSaved)
+            return false;
+        // Captured ONCE, before the first seed ever writes: the values this record had of its own
+        // accord. Restored later for any field the newly-chosen type has no opinion about, so a
+        // default never outlives the type that supplied it.
+        this.renewalFieldsPristine ??= this.currentRenewalValues();
+        const seed = ComputeRenewalSeed({
+            defaults: await this.loadRenewalDefaults(),
+            current: this.currentRenewalValues(),
+            pristine: this.renewalFieldsPristine,
+            userEdited: this.renewalFieldsUserEdited,
+        });
+        const fields = Object.keys(seed);
+        for (const field of fields) {
+            this.Set(field, seed[field]);
+        }
+        return fields.length > 0;
+    }
+    /** The four fields as they stand right now. */
+    currentRenewalValues() {
+        const values = {};
+        for (const field of RENEWAL_SEED_FIELDS) {
+            values[field.ContractField] = this.Get(field.ContractField);
+        }
+        return values;
+    }
+    /**
+     * The selected type's four default columns, or null when no type is selected — which restores the
+     * pristine values rather than leaving the departing type's numbers behind.
+     *
+     * One `RunView` rather than an entity load: four scalars are wanted and none of the type's rules
+     * are, and this runs on a keystroke-adjacent path (picking from a dropdown). The UUID is shape-
+     * checked before it reaches `ExtraFilter` for the same reason `ContractEntityServer` checks the
+     * one it walks the lineage with — this string is concatenated into SQL.
+     */
+    async loadRenewalDefaults() {
+        const id = String(this.ContractTypeID ?? '').trim();
+        if (!UUID_SHAPE.test(id))
+            return null;
+        const result = await this.RunViewProviderToUse.RunView({
+            EntityName: 'MJ_BizApps_Contracts: Contract Types',
+            ExtraFilter: `ID = '${id}'`,
+            Fields: RENEWAL_SEED_FIELDS.map((f) => f.TypeField),
+            ResultType: 'simple',
+        }, this.ContextCurrentUser);
+        return result?.Results?.[0] ?? null;
+    }
 };
 ContractEntity = __decorate([
     RegisterClass(BaseEntity, 'MJ_BizApps_Contracts: Contracts')

package/dist/ContractEntity.js.map

@@ -1 +1 @@
-{"version":3,"file":"ContractEntity.js","sourceRoot":"","sources":["../src/ContractEntity.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ContractEntity.js","sourceRoot":"","sources":["../src/ContractEntity.ts"],"names":[],"mappings":"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"}

package/dist/default-template.d.ts

@@ -0,0 +1,128 @@
+/**
+ * @fileoverview Which template a NEW contract starts with, and when we are allowed to put it there.
+ *
+ * golive #218. Story C-US1 says `ContractTemplateID` defaults to the current template and the user
+ * corrects it if the executed document cites an older version. Nothing defaulted it, so every new
+ * Order Form, Statement of Work and Payment Link opened with the field empty — and all three carry
+ * `TemplateRequired = 1`, so the save was refused until the user found the picker themselves.
+ *
+ * FOUR DECISIONS LIVE HERE, AND THE PANEL OWNS THE QUERY — the same split as
+ * `supersede-candidates.ts`, and for the same reason: anything declared inside an Angular component
+ * can only be asserted by standing up Angular's DI, so a rule stated in a panel is a rule no unit
+ * test reaches.
+ *
+ *   · {@link CurrentTemplateFilter}  — WHICH templates may be defaulted at all
+ *   · {@link CurrentTemplateOrderBy} — which of them is "current"
+ *   · {@link ShouldDefaultTemplate}  — whether we may write over what is in the field right now
+ *   · {@link ShouldWithdrawDefaultTemplate} — whether we must TAKE BACK what we wrote, once the
+ *     contract type stops wanting a template at all
+ *
+ * SCOPING, THE ISSUE'S ONE OPEN DECISION: the newest published usable template wins, REGARDLESS of
+ * its template type. Not a simplification — `ContractType` carries no `ContractTemplateTypeID`, so
+ * there is nothing in the data to scope by, and of the two seeded template types only Master
+ * Agreement has templates behind it (Statement of Work is seeded deliberately unused, because the
+ * business does not version its SOW language). Scoping by type would need a schema change and would
+ * today narrow a one-element set to itself.
+ *
+ * @module @mj-biz-apps/contracts-entities
+ */
+/**
+ * The templates a contract may be started on — an `ExtraFilter`, not a preference.
+ *
+ * Both halves restate what `ContractEntityServer.refuseUnusableTemplate()` enforces on save, and
+ * that duplication is the point: a default that offers something the server will refuse turns a
+ * convenience into a save the user cannot complete and did not cause. The server stays the floor.
+ *
+ *   · `Status = 'Published'` — a draft's provisions can still be added to, edited and removed, so a
+ *     contract pointing at one would have its standard terms change underneath it.
+ *   · `IsUsable = 1` — derived in `vwContractTemplates`: the template records a `SourceURL` or has a
+ *     file attached. A contract cannot incorporate terms nobody can open.
+ */
+export declare const CurrentTemplateFilter = "Status = 'Published' AND IsUsable = 1";
+/**
+ * Which published template is the CURRENT one: the most recently introduced.
+ *
+ * `IntroducedDate` is when a version started being offered — deliberately not named `EffectiveDate`,
+ * because a template becomes effective for a customer when THAT customer signs it. It is the column
+ * the business versions by, so it leads.
+ *
+ * IT IS NULLABLE, AND THE DIRECTION MATTERS. T-SQL sorts NULLs FIRST ascending, therefore LAST
+ * descending — so a template whose introduction date was never recorded loses to every template that
+ * has one, and only wins when it is the only candidate. That is the outcome we want and it is the
+ * one a switch to `ASC` silently inverts, which is why it is pinned by a test rather than by this
+ * sentence.
+ *
+ * `__mj_CreatedAt` breaks a same-date tie by which row was registered last. Two templates introduced
+ * on one day is a correction, not a schedule, and the later row is the correction.
+ */
+export declare const CurrentTemplateOrderBy = "IntroducedDate DESC, __mj_CreatedAt DESC";
+/** What the defaulting rule needs to know about the contract in front of it. */
+export interface TemplateDefaultState {
+    /** `BaseEntity.IsSaved` — false only for a contract that has never been written. */
+    isSaved: boolean;
+    /** The value in the field right now. */
+    currentTemplateID: string | null | undefined;
+    /** The value THIS session last defaulted, or null if it has defaulted nothing yet. */
+    lastDefaultedID: string | null | undefined;
+}
+/**
+ * May this panel write the template field at all — the half of every rule that needs no database?
+ *
+ * Exported separately so the caller can ask it BEFORE reading the contract type, the only input the
+ * rules below need that costs a query. It is false for every saved contract, which is what keeps an
+ * ordinary form open free of one.
+ *
+ * NAMED FOR PERMISSION RATHER THAN FOR DEFAULTING, because it now gates two opposite writes — the
+ * default and its withdrawal — and both are allowed in exactly the same circumstances: the contract
+ * is unsaved, and the field is either empty or still holds our own default. It was
+ * `RecordWantsDefaultTemplate` while defaulting was the only thing it guarded.
+ *
+ *   · **a SAVED contract is never touched.** Its template is a fact about an agreement that exists,
+ *     and re-deciding it when someone opens the form would rewrite history on a record the user only
+ *     came to read.
+ *   · **an empty field is fair game** — the ordinary case the issue is about.
+ *   · **a HAND-PICKED template is never touched.** A user who deliberately chose last year's version
+ *     and then corrected the type must not silently get this year's back, and must not have theirs
+ *     taken away either. We may only overwrite what we ourselves put there.
+ */
+export declare function MayWriteDefaultTemplate(state: TemplateDefaultState): boolean;
+/**
+ * Take back a template we defaulted, once the type stops wanting one (review of PR #51).
+ *
+ * THE BUG THIS EXISTS TO CLOSE. Picking Order Form fills the field in; changing the type to Change
+ * Order used to leave it filled, because the defaulting rule saw a type that needs no template and
+ * simply stopped — treating "there was never anything to do here" and "what I put here no longer
+ * belongs" as the same case. Nothing downstream caught it: `ContractEntityServer` refuses a MISSING
+ * template on a type that requires one and says nothing about a present one on a type that does not.
+ * The contract saved, claiming to incorporate a full set of standard terms nobody chose.
+ *
+ * A default leaves with the type that supplied it — the same principle the renewal-field defaults
+ * follow.
+ *
+ * ONLY OUR OWN DEFAULT IS WITHDRAWN. A template the user picked by hand stays, exactly as it stays
+ * through a default; `holdsOurDefault` is the single comparison both directions read.
+ *
+ * Clearing the type entirely withdraws it too, and that is deliberate: the caller reports a type it
+ * genuinely could not find as `templateRequired = false`, and a contract with no type has nothing
+ * asserting that those standard terms apply. A type it could not READ is a different answer, and the
+ * caller must not translate that into `false` — see the panel's `typeRequiresTemplate`.
+ */
+export declare function ShouldWithdrawDefaultTemplate(state: TemplateDefaultState & {
+    templateRequired: boolean;
+}): boolean;
+/**
+ * The whole rule in the other direction: may we default this contract's template right now?
+ *
+ * `templateRequired` is `ContractType.TemplateRequired`, read from the type the contract currently
+ * names. It gates the default because the flag is what says a type's terms live in a template at
+ * all: Change Order is the one seeded type carrying `0`, and it carries no template of its own —
+ * a modification recorded on a change order cites a provision of a template at or above it in the
+ * tree. Defaulting one onto it would assert an incorporation nobody made.
+ *
+ * A contract with NO type yet cannot be defaulted either, and falls out of this naturally: the
+ * caller has no type to read `TemplateRequired` from, so it passes `false`.
+ */
+export declare function ShouldDefaultTemplate(state: TemplateDefaultState & {
+    templateRequired: boolean;
+}): boolean;
+//# sourceMappingURL=default-template.d.ts.map

package/dist/default-template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-template.d.ts","sourceRoot":"","sources":["../src/default-template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,0CAA0C,CAAC;AAE7E;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,sBAAsB,6CAA6C,CAAC;AAEjF,gFAAgF;AAChF,MAAM,WAAW,oBAAoB;IACjC,oFAAoF;IACpF,OAAO,EAAE,OAAO,CAAC;IACjB,wCAAwC;IACxC,iBAAiB,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAC7C,sFAAsF;IACtF,eAAe,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CAC9C;AA2BD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAK5E;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,oBAAoB,GAAG;IAAE,gBAAgB,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAIlH;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,oBAAoB,GAAG;IAAE,gBAAgB,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAE1G"}

package/dist/default-template.js

@@ -0,0 +1,155 @@
+/**
+ * @fileoverview Which template a NEW contract starts with, and when we are allowed to put it there.
+ *
+ * golive #218. Story C-US1 says `ContractTemplateID` defaults to the current template and the user
+ * corrects it if the executed document cites an older version. Nothing defaulted it, so every new
+ * Order Form, Statement of Work and Payment Link opened with the field empty — and all three carry
+ * `TemplateRequired = 1`, so the save was refused until the user found the picker themselves.
+ *
+ * FOUR DECISIONS LIVE HERE, AND THE PANEL OWNS THE QUERY — the same split as
+ * `supersede-candidates.ts`, and for the same reason: anything declared inside an Angular component
+ * can only be asserted by standing up Angular's DI, so a rule stated in a panel is a rule no unit
+ * test reaches.
+ *
+ *   · {@link CurrentTemplateFilter}  — WHICH templates may be defaulted at all
+ *   · {@link CurrentTemplateOrderBy} — which of them is "current"
+ *   · {@link ShouldDefaultTemplate}  — whether we may write over what is in the field right now
+ *   · {@link ShouldWithdrawDefaultTemplate} — whether we must TAKE BACK what we wrote, once the
+ *     contract type stops wanting a template at all
+ *
+ * SCOPING, THE ISSUE'S ONE OPEN DECISION: the newest published usable template wins, REGARDLESS of
+ * its template type. Not a simplification — `ContractType` carries no `ContractTemplateTypeID`, so
+ * there is nothing in the data to scope by, and of the two seeded template types only Master
+ * Agreement has templates behind it (Statement of Work is seeded deliberately unused, because the
+ * business does not version its SOW language). Scoping by type would need a schema change and would
+ * today narrow a one-element set to itself.
+ *
+ * @module @mj-biz-apps/contracts-entities
+ */
+/**
+ * The templates a contract may be started on — an `ExtraFilter`, not a preference.
+ *
+ * Both halves restate what `ContractEntityServer.refuseUnusableTemplate()` enforces on save, and
+ * that duplication is the point: a default that offers something the server will refuse turns a
+ * convenience into a save the user cannot complete and did not cause. The server stays the floor.
+ *
+ *   · `Status = 'Published'` — a draft's provisions can still be added to, edited and removed, so a
+ *     contract pointing at one would have its standard terms change underneath it.
+ *   · `IsUsable = 1` — derived in `vwContractTemplates`: the template records a `SourceURL` or has a
+ *     file attached. A contract cannot incorporate terms nobody can open.
+ */
+export const CurrentTemplateFilter = `Status = 'Published' AND IsUsable = 1`;
+/**
+ * Which published template is the CURRENT one: the most recently introduced.
+ *
+ * `IntroducedDate` is when a version started being offered — deliberately not named `EffectiveDate`,
+ * because a template becomes effective for a customer when THAT customer signs it. It is the column
+ * the business versions by, so it leads.
+ *
+ * IT IS NULLABLE, AND THE DIRECTION MATTERS. T-SQL sorts NULLs FIRST ascending, therefore LAST
+ * descending — so a template whose introduction date was never recorded loses to every template that
+ * has one, and only wins when it is the only candidate. That is the outcome we want and it is the
+ * one a switch to `ASC` silently inverts, which is why it is pinned by a test rather than by this
+ * sentence.
+ *
+ * `__mj_CreatedAt` breaks a same-date tie by which row was registered last. Two templates introduced
+ * on one day is a correction, not a schedule, and the later row is the correction.
+ */
+export const CurrentTemplateOrderBy = `IntroducedDate DESC, __mj_CreatedAt DESC`;
+/**
+ * Does the field hold exactly the value THIS panel put there?
+ *
+ * The shared notion underneath every rule in this file, and the reason it is factored out rather
+ * than written three times: "ours" is what separates a default we may revisit from a choice a person
+ * made, and a copy of that comparison that drifts turns one of those into the other.
+ *
+ * An EMPTY field is not ours — it is nobody's. That distinction is what keeps
+ * {@link ShouldWithdrawDefaultTemplate} from dirtying a record to write null over null.
+ *
+ * The comparison is case-insensitive because MJ hands UUIDs back in either casing depending on how
+ * the record was loaded (MJ's UUID_COMPARISON_GUIDE); a `===` here would read our own default as the
+ * user's choice. Compared by hand rather than through `UUIDsEqual` for the same reason
+ * `IsSameContractLevel` does: these free functions stay importable by a test with no MJ runtime
+ * standing behind them.
+ */
+function holdsOurDefault(state) {
+    const current = (state.currentTemplateID ?? '').trim();
+    if (!current)
+        return false;
+    const defaulted = (state.lastDefaultedID ?? '').trim();
+    if (!defaulted)
+        return false;
+    return current.toLowerCase() === defaulted.toLowerCase();
+}
+/**
+ * May this panel write the template field at all — the half of every rule that needs no database?
+ *
+ * Exported separately so the caller can ask it BEFORE reading the contract type, the only input the
+ * rules below need that costs a query. It is false for every saved contract, which is what keeps an
+ * ordinary form open free of one.
+ *
+ * NAMED FOR PERMISSION RATHER THAN FOR DEFAULTING, because it now gates two opposite writes — the
+ * default and its withdrawal — and both are allowed in exactly the same circumstances: the contract
+ * is unsaved, and the field is either empty or still holds our own default. It was
+ * `RecordWantsDefaultTemplate` while defaulting was the only thing it guarded.
+ *
+ *   · **a SAVED contract is never touched.** Its template is a fact about an agreement that exists,
+ *     and re-deciding it when someone opens the form would rewrite history on a record the user only
+ *     came to read.
+ *   · **an empty field is fair game** — the ordinary case the issue is about.
+ *   · **a HAND-PICKED template is never touched.** A user who deliberately chose last year's version
+ *     and then corrected the type must not silently get this year's back, and must not have theirs
+ *     taken away either. We may only overwrite what we ourselves put there.
+ */
+export function MayWriteDefaultTemplate(state) {
+    if (state.isSaved)
+        return false;
+    const current = (state.currentTemplateID ?? '').trim();
+    if (!current)
+        return true;
+    return holdsOurDefault(state);
+}
+/**
+ * Take back a template we defaulted, once the type stops wanting one (review of PR #51).
+ *
+ * THE BUG THIS EXISTS TO CLOSE. Picking Order Form fills the field in; changing the type to Change
+ * Order used to leave it filled, because the defaulting rule saw a type that needs no template and
+ * simply stopped — treating "there was never anything to do here" and "what I put here no longer
+ * belongs" as the same case. Nothing downstream caught it: `ContractEntityServer` refuses a MISSING
+ * template on a type that requires one and says nothing about a present one on a type that does not.
+ * The contract saved, claiming to incorporate a full set of standard terms nobody chose.
+ *
+ * A default leaves with the type that supplied it — the same principle the renewal-field defaults
+ * follow.
+ *
+ * ONLY OUR OWN DEFAULT IS WITHDRAWN. A template the user picked by hand stays, exactly as it stays
+ * through a default; `holdsOurDefault` is the single comparison both directions read.
+ *
+ * Clearing the type entirely withdraws it too, and that is deliberate: the caller reports a type it
+ * genuinely could not find as `templateRequired = false`, and a contract with no type has nothing
+ * asserting that those standard terms apply. A type it could not READ is a different answer, and the
+ * caller must not translate that into `false` — see the panel's `typeRequiresTemplate`.
+ */
+export function ShouldWithdrawDefaultTemplate(state) {
+    if (state.templateRequired)
+        return false;
+    if (state.isSaved)
+        return false;
+    return holdsOurDefault(state);
+}
+/**
+ * The whole rule in the other direction: may we default this contract's template right now?
+ *
+ * `templateRequired` is `ContractType.TemplateRequired`, read from the type the contract currently
+ * names. It gates the default because the flag is what says a type's terms live in a template at
+ * all: Change Order is the one seeded type carrying `0`, and it carries no template of its own —
+ * a modification recorded on a change order cites a provision of a template at or above it in the
+ * tree. Defaulting one onto it would assert an incorporation nobody made.
+ *
+ * A contract with NO type yet cannot be defaulted either, and falls out of this naturally: the
+ * caller has no type to read `TemplateRequired` from, so it passes `false`.
+ */
+export function ShouldDefaultTemplate(state) {
+    return state.templateRequired && MayWriteDefaultTemplate(state);
+}
+//# sourceMappingURL=default-template.js.map

package/dist/default-template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-template.js","sourceRoot":"","sources":["../src/default-template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,uCAAuC,CAAC;AAE7E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,0CAA0C,CAAC;AAYjF;;;;;;;;;;;;;;;GAeG;AACH,SAAS,eAAe,CAAC,KAA2B;IAChD,MAAM,OAAO,GAAG,CAAC,KAAK,CAAC,iBAAiB,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACvD,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAE3B,MAAM,SAAS,GAAG,CAAC,KAAK,CAAC,eAAe,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACvD,IAAI,CAAC,SAAS;QAAE,OAAO,KAAK,CAAC;IAC7B,OAAO,OAAO,CAAC,WAAW,EAAE,KAAK,SAAS,CAAC,WAAW,EAAE,CAAC;AAC7D,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAA2B;IAC/D,IAAI,KAAK,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAChC,MAAM,OAAO,GAAG,CAAC,KAAK,CAAC,iBAAiB,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACvD,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1B,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC;AAClC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,6BAA6B,CAAC,KAA2D;IACrG,IAAI,KAAK,CAAC,gBAAgB;QAAE,OAAO,KAAK,CAAC;IACzC,IAAI,KAAK,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAChC,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC;AAClC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAA2D;IAC7F,OAAO,KAAK,CAAC,gBAAgB,IAAI,uBAAuB,CAAC,KAAK,CAAC,CAAC;AACpE,CAAC"}