@wisemen/wise-invoicing-web 0.3.0 → 0.4.0

package/dist/ui/billing-document/table/utils/billingDocumentLineItemsEditor.util.d.ts

@@ -9,6 +9,7 @@ export declare const BILLING_DOCUMENT_VAT_RATE_OPTIONS: VatRate[];
 export declare const BILLING_DOCUMENT_UNIT_OPTIONS: UnitOfMeasurement[];
 export interface BillingDocumentLineItemEditorGroupRow {
     id: string;
+    parentGroupId: string | null;
     sourceGroupUuid: string | null;
     name: string;
     customFields: CustomFieldValue[];
@@ -31,76 +32,207 @@ export interface BillingDocumentLineItemEditorLineRow {
     vatRate: VatRate;
 }
 export type BillingDocumentLineItemEditorRow = BillingDocumentLineItemEditorGroupRow | BillingDocumentLineItemEditorLineRow;
-/**
- * Where a dropped row is meant to land when the slot itself cannot say.
- *
- * `group` joins the group the slot borders, `root` keeps the row ungrouped.
- * Callers without a pointer gesture behind them (keyboard, insert indicator)
- * pass `null` and fall back to neighbour inference.
- */
-export type BillingDocumentLineItemDropIntent = 'group' | 'root';
+/** Mirrors the API's MAX_INVOICE_LINE_GROUP_DEPTH: a top-level group is level 1. */
+export declare const BILLING_DOCUMENT_LINE_ITEM_MAX_GROUP_LEVEL = 4;
+export interface BillingDocumentLineItemRowStructure {
+    /** The groups the row sits in, outermost first. */
+    ancestorGroupIds: string[];
+    /** How many groups the row sits in: 0 at the top level. */
+    depth: number;
+}
+export interface BillingDocumentLineItemGroupStructure {
+    /** Every line inside the group, at any depth. */
+    descendantLineIds: string[];
+    /** Group levels the group spans: 1 without subgroups, 2 with one level of them, … */
+    height: number;
+    /** 1 for a top-level group. */
+    level: number;
+    /** Every group inside the group, at any depth. */
+    subgroupCount: number;
+}
+/** What the flat rows encode about nesting, derived once per change of the rows. */
+export interface BillingDocumentLineItemsStructure {
+    groups: ReadonlyMap<string, BillingDocumentLineItemGroupStructure>;
+    /** The deepest row depth in the document. */
+    maxDepth: number;
+    rows: ReadonlyMap<string, BillingDocumentLineItemRowStructure>;
+}
 export interface BillingDocumentLineItemEditorMeta {
     currency: Monetary['currency'];
     documentType: AnyBillingDocumentDetail['type'];
     precision: number;
 }
 export declare class BillingDocumentLineItemsEditorUtil {
+    /**
+     * Appends one level of the server tree in position order — lines and
+     * subgroups share the positions of their level, so they interleave — with
+     * every group directly followed by its own contents.
+     */
+    private static appendBillingDocumentEditorRows;
     static buildBillingDocumentLineItemsPayload(meta: BillingDocumentLineItemEditorMeta, rows: BillingDocumentLineItemEditorRow[]): BillingDocumentUpdateLines;
+    /**
+     * Reads the nesting the flat rows encode. Each row lands in the group its
+     * `groupId` / `parentGroupId` points at, in the order it appears; a row whose
+     * group is missing — or whose parent chain loops back on itself — is lifted
+     * to the top level.
+     */
+    private static buildRowTree;
+    /**
+     * Whether a new group can be created inside `parentGroupId` (the top level
+     * when `null`) without nesting deeper than the API allows.
+     */
+    static canAddGroupInside(structure: BillingDocumentLineItemsStructure, parentGroupId: string | null): boolean;
+    /** Whether {@link groupSelectedRows} can wrap the selection without nesting too deep. */
+    static canGroupSelectedRows(rows: BillingDocumentLineItemEditorRow[], selectedIds: ReadonlySet<string>): boolean;
+    private static collectRowTreeLineIds;
     static createBillingDocumentEditorRows(invoice: AnyBillingDocumentDetail): BillingDocumentLineItemEditorRow[];
     static createBillingDocumentLineItemDiscount(discountPercentage: Percentage | null): BillingDocumentDiscount | null;
     static createBillingDocumentLineItemDisplayRows(invoice: AnyBillingDocumentDetail, isEditable: boolean): BillingDocumentLineItemEditorRow[];
-    static createBillingDocumentLineItemGroupRow(group: BillingDocumentLineGroup): BillingDocumentLineItemEditorGroupRow;
+    static createBillingDocumentLineItemGroupRow(group: BillingDocumentLineGroup, parentGroupId?: string | null): BillingDocumentLineItemEditorGroupRow;
     static createBillingDocumentLineItemRowFromInvoiceLine(documentType: AnyBillingDocumentDetail['type'], line: BillingDocumentLine): BillingDocumentLineItemEditorLineRow;
     static createBillingDocumentLineItemRowsKey(rows: BillingDocumentLineItemEditorRow[]): string;
     static createBillingDocumentLineItemsMeta(invoice: AnyBillingDocumentDetail): BillingDocumentLineItemEditorMeta;
     static createBillingDocumentLineItemsServerSnapshot(invoice: AnyBillingDocumentDetail): string;
+    static createBillingDocumentLineItemsStructure(rows: BillingDocumentLineItemEditorRow[]): BillingDocumentLineItemsStructure;
     static createBillingDocumentLineItemTotals(row: BillingDocumentLineItemEditorLineRow): {
         discount: number;
         gross: number;
         net: number;
         vat: number;
     };
+    private static createBillingDocumentUpdateLevel;
     private static createBillingDocumentUpdateLine;
-    static createNewBillingDocumentLineItemGroupRow(): BillingDocumentLineItemEditorGroupRow;
+    static createNewBillingDocumentLineItemGroupRow(parentGroupId?: string | null): BillingDocumentLineItemEditorGroupRow;
     static createNewBillingDocumentLineItemRow(meta: BillingDocumentLineItemEditorMeta, groupId?: string | null): BillingDocumentLineItemEditorLineRow;
+    /**
+     * Removes a group header. With `deleteContents` everything inside it goes
+     * too; without, its lines and subgroups move up into its parent, in place.
+     */
+    static deleteGroupRow(rows: BillingDocumentLineItemEditorRow[], groupId: string, deleteContents: boolean): BillingDocumentLineItemEditorRow[];
+    /**
+     * Removes the selected lines. A group goes with them once every line inside
+     * it — at any depth — is selected; a group without lines is left alone.
+     */
     static deleteSelectedRows(rows: BillingDocumentLineItemEditorRow[], selectedIds: ReadonlySet<string>): BillingDocumentLineItemEditorRow[];
     static duplicateBillingDocumentLineItemRow(row: BillingDocumentLineItemEditorLineRow): BillingDocumentLineItemEditorLineRow;
     static duplicateSelectedRows(rows: BillingDocumentLineItemEditorRow[], selectedIds: ReadonlySet<string>): BillingDocumentLineItemEditorRow[];
+    /**
+     * Index of the last row inside the group's block — its lines and subgroups
+     * at any depth — or of the header itself when the group is empty. Assumes
+     * the rows are normalized, so the block is contiguous.
+     */
     static findGroupBlockEndIndex(rows: BillingDocumentLineItemEditorRow[], groupId: string): number;
-    private static findLineGroupHeaderIndex;
+    /**
+     * Where a row sits in the tree: its siblings array and index, and the same
+     * for the group it sits in (`null` at the top level).
+     */
+    private static findRowTreeLocation;
+    /**
+     * Index of the row heading the block that holds `targetIndex` on the level
+     * of `containerId`: the target itself, or its ancestor group directly inside
+     * that container. `-1` when the target sits outside the container.
+     */
+    private static findSiblingBlockStartIndex;
+    /**
+     * Flattens the tree back into rows, depth first, pointing every row at the
+     * group it now sits in. Rows whose placement did not change are kept as is.
+     */
+    private static flattenRowTree;
+    /** The level of a group, or 0 for the top level. */
+    private static getContainerLevel;
+    /**
+     * The groups a row dropped at `index` could join, deepest first: from the
+     * group the row above sits in (or heads) out to the group of the row below,
+     * which bounds the slot. `null` stands for the top level. Groups that are
+     * collapsed — or sit inside a collapsed group — are skipped, so a drop never
+     * vanishes into a group the user cannot see.
+     */
+    static getDropContainerIds(rows: BillingDocumentLineItemEditorRow[], index: number, collapsedGroupIds?: ReadonlySet<string>): Array<string | null>;
     private static getGroupBlockInsertionIndexAfterTarget;
     private static getGroupBlockInsertionIndexBeforeTarget;
+    /** The group a row sits in: a line's group, a group's parent group. */
+    private static getRowContainerId;
     private static getSignedQuantity;
     /**
-     * Consolidates the selected lines into the supplied (new) group, inserting the
-     * group block at the position of the first selected line. Non-selected rows
-     * keep their order.
+     * Wraps the selection in the supplied (new) group. A group whose lines are
+     * all selected moves along as a whole; other selected lines move on their
+     * own. The new group is created in the innermost group that holds the whole
+     * selection, where the first selected row was. Rows stay unchanged when the
+     * wrap would nest deeper than the API allows.
      */
     static groupSelectedRows(rows: BillingDocumentLineItemEditorRow[], selectedIds: ReadonlySet<string>, groupRow: BillingDocumentLineItemEditorGroupRow): BillingDocumentLineItemEditorRow[];
+    /**
+     * Moves a row one level in: into the group directly above it on its own
+     * level, as that group's last row. Unchanged when there is no such group or
+     * the move would nest deeper than the API allows.
+     */
+    static indentRow(rows: BillingDocumentLineItemEditorRow[], rowId: string): BillingDocumentLineItemEditorRow[];
     static isBillingDocumentLineItemRowValid(row: BillingDocumentLineItemEditorRow): boolean;
     static isGroupRow(row: BillingDocumentLineItemEditorRow): row is BillingDocumentLineItemEditorGroupRow;
     static isLineRow(row: BillingDocumentLineItemEditorRow): row is BillingDocumentLineItemEditorLineRow;
     static isTransientEmptyLineRow(row: BillingDocumentLineItemEditorRow): boolean;
     static moveGroupBlockByIndex(rows: BillingDocumentLineItemEditorRow[], currentIndex: number, targetIndex: number): BillingDocumentLineItemEditorRow[];
-    static moveSelectedRowsToGroup(rows: BillingDocumentLineItemEditorRow[], selectedIds: ReadonlySet<string>, groupId: string): BillingDocumentLineItemEditorRow[];
     /**
-     * Re-orders rows so every line sits directly after its group's header, keeping
-     * each group block contiguous. Lines whose group no longer exists become
-     * ungrouped. Top-level order follows the first appearance of each group header
-     * and ungrouped line.
+     * Moves a row by drag and drop. `currentIndex` and `targetIndex` follow the
+     * drag layer: the target is the index the row takes once it has left its own
+     * slot. `levelOffset` is how many levels the pointer travelled sideways
+     * (positive is deeper).
+     *
+     * A line lands in the group at the level closest to where it started plus
+     * that offset, among the groups the slot allows. A group keeps its parent
+     * and lands beside the sibling block it was dropped on, then moves in or out
+     * a level per step of offset.
+     */
+    static moveRowByIndex(rows: BillingDocumentLineItemEditorRow[], currentIndex: number, targetIndex: number, levelOffset?: number, collapsedGroupIds?: ReadonlySet<string>): BillingDocumentLineItemEditorRow[];
+    /**
+     * Moves the selected lines to the end of a group, or of the document when
+     * `groupId` is `null`.
+     */
+    static moveSelectedRowsToGroup(rows: BillingDocumentLineItemEditorRow[], selectedIds: ReadonlySet<string>, groupId: string | null): BillingDocumentLineItemEditorRow[];
+    /**
+     * Re-orders rows so every group header is directly followed by its own
+     * lines and subgroups, keeping each group block contiguous. Rows whose group
+     * no longer exists move to the top level. Order within each level follows
+     * the first appearance of each row.
      */
     static normalizeRows(rows: BillingDocumentLineItemEditorRow[]): BillingDocumentLineItemEditorRow[];
     /**
-     * Resolves the group a line belongs to once it is inserted at `index`.
+     * Moves a row one level out: out of its group, to directly after that
+     * group's block. Unchanged for a row at the top level.
+     */
+    static outdentRow(rows: BillingDocumentLineItemEditorRow[], rowId: string): BillingDocumentLineItemEditorRow[];
+    /**
+     * Works out what {@link groupSelectedRows} would wrap: the selected rows as
+     * whole nodes (a fully selected group counts once), the path of groups that
+     * holds all of them, the child of that innermost group holding the first of
+     * them, and whether wrapping them stays within the maximum level.
+     */
+    private static planGroupSelection;
+    private static pruneSelectedFromRowTree;
+    private static removeGroupFromRowTree;
+    /**
+     * The group a dropped line joins at `index`: of the groups the slot allows
+     * (see {@link getDropContainerIds}), the one whose level is closest to
+     * `preferredLevel`.
+     */
+    static resolveDropContainerId(rows: BillingDocumentLineItemEditorRow[], index: number, preferredLevel: number, collapsedGroupIds?: ReadonlySet<string>): string | null;
+    /**
+     * The group a new group inserted between two visible rows belongs to: the
+     * innermost group both rows sit in, where the row above counts as inside its
+     * own group when it is an expanded group header. So a group added between
+     * two lines of a group nests in it, and one added between two groups — or at
+     * the very end — stays beside them.
+     */
+    static resolveGroupInsertParentId(visibleRows: BillingDocumentLineItemEditorRow[], index: number, structure: BillingDocumentLineItemsStructure, collapsedGroupIds: ReadonlySet<string>): string | null;
+    /**
+     * Resolves the group a new line belongs to once it is inserted at `index`.
      *
-     * The slot right after a group's last line is ambiguous by construction: "the
-     * new last line inside the group" and "the first line after the group" are the
-     * same position in the row list and the same pixel band on screen. Neighbours
-     * cannot disambiguate it, so a drop coming from the drag layer carries an
-     * explicit `dropIntent`. Without one, the row is appended to the group it
+     * The slot right after a group's last row is ambiguous by construction: "the
+     * new last line inside the group" and "the first line after the group" are
+     * the same position in the row list. The line is appended to the group it
      * borders, which is what the insert indicators and keyboard inserts expect.
      */
-    static resolveInsertGroupId(rows: BillingDocumentLineItemEditorRow[], index: number, dropIntent?: BillingDocumentLineItemDropIntent | null): string | null;
+    static resolveInsertGroupId(rows: BillingDocumentLineItemEditorRow[], index: number): string | null;
     /**
      * Puts the rows that were never sent back between the synced rows, at the
      * offset they held among the rows that were.
@@ -121,4 +253,9 @@ export declare class BillingDocumentLineItemsEditorUtil {
      */
     static syncBillingDocumentLineItemRowsWithServer(serverRows: BillingDocumentLineItemEditorRow[], currentRows: BillingDocumentLineItemEditorRow[]): BillingDocumentLineItemEditorRow[];
     private static trimOrNull;
+    /**
+     * Rebuilds the tree without the selected nodes, inserting the wrapping
+     * group among `containerChildren` after the remaining `precedingNodes`.
+     */
+    private static wrapSelectionInRowTree;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wisemen/wise-invoicing-web",
   "type": "module",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "private": false,
   "description": "Invoicing frontend package with Vue 3 components, composables and types",
   "author": "Wisemen",
@@ -92,7 +92,7 @@
     "vite": "^8.2.0",
     "vite-plugin-dts": "5.0.3",
     "vitest": "^4.1.11",
-    "vue": "3.5.40",
+    "vue": "3.5.42",
     "vue-i18n": "11.4.8",
     "vue-router": "5.2.0",
     "vue-sonner": "2.0.9",