@mj-biz-apps/sales-ng 5.1.0

package/dist/lib/board/deal-board.component.d.ts

@@ -0,0 +1,194 @@
+/**
+ * @fileoverview The pipeline board — deals as cards, pipeline stages as columns.
+ *
+ * WHAT THIS IS FOR. The roster answers "where does this deal stand"; the board answers "where is
+ * everything, and what needs pushing". Same deals, same data, a different question — which is why it is a
+ * rail page beside the dashboard and the roster rather than a section of its own.
+ *
+ * ── WHY THIS IS NOT AN MJ GENERIC KANBAN ────────────────────────────────────────────────────────
+ *
+ * CLAUDE.md lists `kanban` among MJ's Angular Generic components. **At MJ v5.51.0 it does not exist** —
+ * there is no `@memberjunction/ng-kanban`, and no kanban export anywhere under `@memberjunction/*`
+ * (`ng-timeline`, `ng-filter-builder`, `ng-entity-card` and `ng-join-grid` all do exist, so the list is
+ * aspirational rather than wrong). Recorded in BOARD-DECISIONS.md D-BD1.
+ *
+ * So the columns are laid out here, but the DRAG is not invented: it uses `@angular/cdk/drag-drop`, which
+ * is already the in-house primitive in this very package — `vendored/workspace-tabs/workspace-tab-strip`
+ * imports `CdkDropList`/`CdkDrag` for tab reordering. Same library, same idiom, no new dependency. When a
+ * generic kanban lands, this component is the thing to delete.
+ *
+ * ── WHAT IT REFUSES TO DO ───────────────────────────────────────────────────────────────────────
+ *
+ * A drag NEVER closes a deal. Dropping onto a stage whose `DealStatusType.LocksDeal` is set is refused
+ * with a hint pointing at the explicit close action, because a lock freezes the deal, its lines and its
+ * team, and an accidental mouse gesture is not an adequate signature on that. It also never calls the
+ * orders or contracts seams — closing is `Sales.CloseDeal`, deliberately explicit.
+ *
+ * ── VOCABULARY IS DATA ──────────────────────────────────────────────────────────────────────────
+ *
+ * Columns come from `PipelineStage` rows ordered by `DisplayOrder`. Whether a column is a closing column
+ * is read from the `DealStatusType.LocksDeal` FLAG its stage points at. No status name, stage name or
+ * pipeline name is compared anywhere in this file.
+ *
+ * ── IT COMPUTES NO MONEY ────────────────────────────────────────────────────────────────────────
+ *
+ * A column total is `SUM(Deal.Amount)` over the cards in that column — stored values, added up for
+ * display, exactly as the dashboard does it. Nothing is priced, derived, discounted or prorated. The sum
+ * is taken over DEALS, never over team members, which is the attribution double-count trap: a deal with
+ * an AE, an SE and an SDR has three `DealTeamMember` rows and would be counted three times.
+ *
+ * @module @mj-biz-apps/sales-ng
+ */
+import { CdkDragDrop } from '@angular/cdk/drag-drop';
+import { EventEmitter } from '@angular/core';
+import { type DealRosterRow } from '../workspace/deal-workspace.service';
+import type { DealStatusLookup, PipelineLookup, StageLookup } from '../workspace/deal-workspace.types';
+import * as i0 from "@angular/core";
+/**
+ * The one currency a set of cards shares, or NULL when they do not share one.
+ *
+ * Uniformly-NULL counts as sharing: `Deal.CurrencyID` is unpopulated on every deal today, so treating
+ * that as a disagreement would suppress every total on the board and help nobody. What it must not do
+ * is treat NULL as the display default -- unknown and dollars are different claims, and conflating
+ * them is how a EUR deal ends up rendered as $48,000.
+ */
+export declare function SingleCurrencyOf(cards: readonly DealRosterRow[]): string | null;
+/**
+ * What a figure is LABELLED as when no deal states a currency.
+ *
+ * A display default, not a fact about the money. It is here as one named constant rather than three
+ * hardcoded 'USD' literals so that the assumption is stated once, in a place a reader meets it, and
+ * so populating `Deal.CurrencyID` is a data change rather than a code hunt.
+ */
+export declare const DEFAULT_DISPLAY_CURRENCY = "USD";
+/** One column: a stage, the deals sitting in it, and the two figures its header shows. */
+export interface BoardColumn {
+    StageID: string;
+    Label: string;
+    /** Set when arriving here would lock the deal — the column refuses drops. */
+    IsClosing: boolean;
+    Cards: DealRosterRow[];
+    /** `SUM(Deal.Amount)` over `Cards`. Stored amounts, added for display. */
+    Total: number;
+    /**
+     * The currency every card in this column is denominated in, or NULL when they disagree.
+     *
+     * NULL means DO NOT RENDER THE TOTAL. Three display sites used to hardcode 'USD', so a deal priced
+     * in EUR rendered as dollars and was added into a dollar column total -- a number that is wrong in
+     * a way no reader can see. Refusing beats guessing: a missing figure prompts a question, a
+     * confidently wrong one does not.
+     */
+    Currency: string | null;
+    /** True when the cards disagree about currency, so the template can say why the total is absent. */
+    MixedCurrency: boolean;
+    /**
+     * Cards in this column whose figure did NOT come from the orders engine.
+     *
+     * WIDENED, and the old definition was the more dangerous of the two. It counted only cards with a
+     * null amount, so a figure a human typed was counted as priced and folded into the total with no
+     * caveat at all -- and on the seeded data every deal carries `AmountIsComputed = 0`, which made this
+     * read `0 unpriced` on a board where nothing whatsoever was priced. A missing figure at least looks
+     * missing; a stated one looks authoritative, which is why it is the case that needed counting.
+     *
+     * A null amount is still counted -- it is certainly not priced -- so the footnote keeps one
+     * vocabulary rather than growing a second.
+     */
+    Unpriced: number;
+    /** True when NOTHING in the column was priced, so the footnote can say so rather than count to N. */
+    NonePriced: boolean;
+}
+export declare class DealBoardComponent {
+    private readonly service;
+    private readonly cdr;
+    /** The roster, owned by the section so the board and the list cannot disagree about what exists. */
+    Deals: DealRosterRow[];
+    Pipelines: PipelineLookup[];
+    Stages: StageLookup[];
+    DealStatusTypes: DealStatusLookup[];
+    /** A card was clicked — the section opens it in the workspace, exactly as a roster row does. */
+    readonly DealOpened: EventEmitter<DealRosterRow>;
+    /** A move persisted; the section re-reads the roster so every page sees the new stage. */
+    readonly StageMoved: EventEmitter<void>;
+    SelectedPipelineID: string | null;
+    /** Shown verbatim. A refused or failed move must say why rather than silently snapping back. */
+    Message: string | null;
+    Moving: boolean;
+    /** The pipeline actually in view — the chosen one, or the first that has any stages. */
+    get ActivePipelineID(): string | null;
+    /**
+     * The columns, in `DisplayOrder`.
+     *
+     * Recomputed on read rather than cached, matching how the workspace's `IssuesForPane` and the
+     * dashboard's tiles already work. The card counts here are small — a pipeline has a handful of stages
+     * and a rep has tens of deals, not thousands — so the clarity is worth more than the memoization.
+     */
+    get Columns(): BoardColumn[];
+    /** Deals on this pipeline that have no stage set — otherwise they would vanish from the board. */
+    get Unstaged(): DealRosterRow[];
+    /**
+     * The drop-list ids CDK needs to know a card may travel between columns.
+     *
+     * ── CACHED BY VALUE, BECAUSE THIS FEEDS `[cdkDropListConnectedTo]` ──────────────────
+     *
+     * `.map()` returns a NEW ARRAY IDENTITY on every call, this component runs default change
+     * detection, and CDK re-wires its drop-list connections whenever that input's identity changes.
+     * During a drag Angular runs change detection on every `pointermove`, so the board was tearing down
+     * and rebuilding the connection graph continuously — on the one gesture the demo shows.
+     *
+     * The sibling `Products` getter in the workspace already documents this exact hazard and returns a
+     * stable reference for it. The reasoning was there; it had not reached here.
+     *
+     * Rebuilt only when the JOINED ids actually change, so adding, removing or reordering a stage still
+     * re-wires — which is the behaviour that must not be lost by caching. Comparing the joined
+     * string rather than the array means a re-render that produces equal ids reuses the reference,
+     * which is the whole point.
+     */
+    get ColumnIDs(): string[];
+    private _columnIDsKey;
+    private _columnIDs;
+    SelectPipeline(pipelineID: string): void;
+    OpenCard(deal: DealRosterRow): void;
+    /** CDK asks per drop list whether a given drag may land. This is where the lock is refused. */
+    CanDropInto: (column: BoardColumn) => () => boolean;
+    /**
+     * A card was dropped on a column.
+     *
+     * The move goes through `Sales.SaveDeal` — the same operation the workspace saves with — rather than a
+     * bespoke write. That is what earns the stage event, the validation and the company resolution without
+     * this component knowing they exist; the operation appends the append-only `DealStageEvent` itself when
+     * it sees the stage change. Reusing `LoadDraft` also means the deal's lines and instalments round-trip
+     * intact, which matters because the operation treats a present array as the complete desired set.
+     */
+    OnDrop(event: CdkDragDrop<BoardColumn>, target: BoardColumn): Promise<void>;
+    /**
+     * ── THE BOARD DOES NOT WRITE STAGE DEFAULTS EITHER ──────────────────────────────────────────────
+     *
+     * `ApplyStageDefaults` was here too, assigning `Probability` and `ForecastCategoryTypeID`
+     * unconditionally onto the dragged card's header — with a comment saying it was deliberately the same
+     * rule as the workspace's, so that "a drag and a dropdown must not produce different deals". The
+     * intent was right and the implementation destroyed a rep-typed probability, in both places, before
+     * the server could apply its fill-but-don't-overwrite rule.
+     *
+     * Both copies are gone. The server applies the stage's answer inside the save (same trigger, same
+     * transaction), and the board re-reads the row afterwards, so the card shows what was actually
+     * written rather than what the client guessed. A drag and a dropdown now produce the same deal
+     * because they go through the same single writer, which is a stronger guarantee than two clients
+     * agreeing with each other.
+     */
+    NameOf(pipelineID: string | null): string;
+    /** Track by ID so a re-render does not tear down every card. */
+    TrackCard: (_: number, deal: DealRosterRow) => string;
+    /** Exposed for the template's per-card fallback. See DEFAULT_DISPLAY_CURRENCY. */
+    readonly DefaultCurrency = "USD";
+    /**
+     * What the stated-amount footnote says when a reader hovers it.
+     *
+     * In the component rather than the template because it is a sentence, and a sentence built out of
+     * a ternary inside a binding is unreadable in both places at once.
+     */
+    PricingNote(column: BoardColumn): string;
+    TrackColumn: (_: number, column: BoardColumn) => string;
+    static ɵfac: i0.ɵɵFactoryDeclaration<DealBoardComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<DealBoardComponent, "mjs-deal-board", never, { "Deals": { "alias": "Deals"; "required": false; }; "Pipelines": { "alias": "Pipelines"; "required": false; }; "Stages": { "alias": "Stages"; "required": false; }; "DealStatusTypes": { "alias": "DealStatusTypes"; "required": false; }; }, { "DealOpened": "DealOpened"; "StageMoved": "StageMoved"; }, never, never, true, never>;
+}
+//# sourceMappingURL=deal-board.component.d.ts.map

package/dist/lib/board/deal-board.component.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deal-board.component.d.ts","sourceRoot":"","sources":["../../../src/lib/board/deal-board.component.ts"],"names":[],"mappings":"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"}