Files
vibemake-pcb-studio/common/commit.ts
T
likang 7e01147566
CI / typecheck + test + build (push) Has been cancelled
Initial commit: import VibeMake PCB Studio
2026-11-03 11:20:08 +08:00

351 lines
11 KiB
TypeScript

// SPDX-License-Identifier: GPL-3.0-or-later
// Copyright (C) 2026 ZiroEDA and contributors.
// Portions derived from KiCad, copyright The KiCad Developers. See NOTICE.md.
/**
* `COMMIT` (include/commit.h, common/commit.cpp): a set of staged changes to
* a model — items added, removed or modified — that `Push()` applies with an
* undo entry, or `Revert()` undoes. `BOARD_COMMIT` and `SCH_COMMIT` are the
* two models' subclasses.
*/
import { asEdaGroup } from './eda_group.js';
import { type EDA_ITEM, RECURSE_MODE } from './eda_item.js';
import { STRUCT_DELETED } from './eda_item_flags.js';
import { type BASE_SCREEN_LIKE, type PICKED_ITEMS_LIST, UNDO_REDO } from './undo_redo_container.js';
///< Types of changes
export enum CHANGE_TYPE {
CHT_ADD = 1,
CHT_REMOVE = 2,
CHT_MODIFY = 4,
CHT_TYPE = CHT_ADD | CHT_REMOVE | CHT_MODIFY,
CHT_DONE = 32, ///< Flag to indicate the change is already applied
CHT_FLAGS = CHT_DONE,
}
/** One staged change. */
export interface COMMIT_LINE {
m_item: EDA_ITEM | null; ///< Main item that is added/deleted/modified
m_copy: EDA_ITEM | null; ///< Optional copy of the item
m_type: number; ///< Modification type (a CHANGE_TYPE or-ed with its flags)
m_screen: BASE_SCREEN_LIKE | null;
}
/** `std::set<std::pair<EDA_ITEM*, BASE_SCREEN*>>`. */
class ITEM_SCREEN_SET {
private readonly m_map = new Map<EDA_ITEM, Set<BASE_SCREEN_LIKE | null>>();
has(aItem: EDA_ITEM, aScreen: BASE_SCREEN_LIKE | null): boolean {
return this.m_map.get(aItem)?.has(aScreen) ?? false;
}
add(aItem: EDA_ITEM, aScreen: BASE_SCREEN_LIKE | null): void {
let screens = this.m_map.get(aItem);
if (!screens) {
screens = new Set();
this.m_map.set(aItem, screens);
}
screens.add(aScreen);
}
clear(): void {
this.m_map.clear();
}
}
/**
* Represent a set of changes (additions, deletions or modifications) of a data model
* (e.g. the BOARD) class.
*
* The changes are not immediately applied to the model; they are staged and applied on
* Push(), which also creates the undo entry.
*/
export abstract class COMMIT {
protected m_addedItems = new ITEM_SCREEN_SET();
protected m_changedItems = new ITEM_SCREEN_SET();
protected m_deletedItems = new ITEM_SCREEN_SET();
protected m_entries: COMMIT_LINE[] = [];
/// Add a new item to the model.
Add(aItem: EDA_ITEM, aScreen: BASE_SCREEN_LIKE | null = null): COMMIT {
return this.Stage(aItem, CHANGE_TYPE.CHT_ADD, aScreen);
}
/// Notify observers that aItem has been added.
Added(aItem: EDA_ITEM, aScreen: BASE_SCREEN_LIKE | null = null): COMMIT {
return this.Stage(aItem, CHANGE_TYPE.CHT_ADD | CHANGE_TYPE.CHT_DONE, aScreen);
}
/// Remove a new item from the model.
Remove(aItem: EDA_ITEM, aScreen: BASE_SCREEN_LIKE | null = null): COMMIT {
return this.Stage(aItem, CHANGE_TYPE.CHT_REMOVE, aScreen);
}
///< Notify observers that aItem has been removed
Removed(aItem: EDA_ITEM, aScreen: BASE_SCREEN_LIKE | null = null): COMMIT {
return this.Stage(aItem, CHANGE_TYPE.CHT_REMOVE | CHANGE_TYPE.CHT_DONE, aScreen);
}
/**
* Modify a given item in the model.
*
* @note Must be called before modification is performed.
*/
Modify(
aItem: EDA_ITEM,
aScreen: BASE_SCREEN_LIKE | null = null,
aRecurse: RECURSE_MODE = RECURSE_MODE.NO_RECURSE,
): COMMIT {
return this.Stage(aItem, CHANGE_TYPE.CHT_MODIFY, aScreen, aRecurse);
}
/**
* Create an undo entry for an item that has been already modified.
*
* @note Requires a copy done before the modification.
*/
Modified(aItem: EDA_ITEM, aCopy: EDA_ITEM, aScreen: BASE_SCREEN_LIKE | null = null): COMMIT {
if (this.undoLevelItem(aItem) !== aItem)
console.assert(false, "We've no way to get a copy of the undo level item at this point");
else this.makeEntry(aItem, CHANGE_TYPE.CHT_MODIFY, aCopy, aScreen);
return this;
}
/// Add a change of the item aItem of type aChangeType to the change list.
Stage(
aItem: EDA_ITEM,
aChangeType: number,
aScreen?: BASE_SCREEN_LIKE | null,
aRecurse?: RECURSE_MODE,
): COMMIT;
Stage(container: EDA_ITEM[], aChangeType: number, aScreen?: BASE_SCREEN_LIKE | null): COMMIT;
Stage(aItems: PICKED_ITEMS_LIST, aModFlag?: UNDO_REDO, aScreen?: BASE_SCREEN_LIKE | null): COMMIT;
Stage(
a: EDA_ITEM | EDA_ITEM[] | PICKED_ITEMS_LIST,
b: number = UNDO_REDO.UNSPECIFIED,
aScreen: BASE_SCREEN_LIKE | null = null,
aRecurse: RECURSE_MODE = RECURSE_MODE.NO_RECURSE,
): COMMIT {
if (Array.isArray(a)) return this.stageContainer(a, b, aScreen);
if (isPickedItemsList(a)) return this.stagePickedItems(a, b as UNDO_REDO, aScreen);
return this.stageItem(a, b, aScreen, aRecurse);
}
/** `Stage( EDA_ITEM*, CHANGE_TYPE, BASE_SCREEN*, RECURSE_MODE )`. */
protected stageItem(
aItem: EDA_ITEM,
aChangeType: number,
aScreen: BASE_SCREEN_LIKE | null,
_aRecurse: RECURSE_MODE,
): COMMIT {
let flags = aChangeType & CHANGE_TYPE.CHT_FLAGS;
let changeType = aChangeType & CHANGE_TYPE.CHT_TYPE;
const undoItem = this.undoLevelItem(aItem);
if (undoItem !== aItem) {
changeType = CHANGE_TYPE.CHT_MODIFY;
// CHT_DONE means the original add/remove was already applied to the child, but that
// semantic doesn't carry over when we remap to a modify of the parent
flags &= ~CHANGE_TYPE.CHT_DONE;
}
console.assert(changeType !== CHANGE_TYPE.CHT_MODIFY || (flags & CHANGE_TYPE.CHT_DONE) === 0);
switch (changeType) {
case CHANGE_TYPE.CHT_ADD:
if (this.m_addedItems.has(aItem, aScreen)) break;
this.makeEntry(aItem, CHANGE_TYPE.CHT_ADD | flags, null, aScreen);
break;
case CHANGE_TYPE.CHT_REMOVE: {
if (this.m_deletedItems.has(aItem, aScreen)) break;
this.makeEntry(aItem, CHANGE_TYPE.CHT_REMOVE | flags, this.makeImage(aItem), aScreen);
const parentGroup = aItem.GetParentGroup();
if (parentGroup) {
if (parentGroup.AsEdaItem().GetFlags() & STRUCT_DELETED)
this.Modify(parentGroup.AsEdaItem(), aScreen, RECURSE_MODE.NO_RECURSE);
}
break;
}
case CHANGE_TYPE.CHT_MODIFY:
if (this.m_addedItems.has(aItem, aScreen)) break;
if (this.m_changedItems.has(undoItem, aScreen)) break;
this.makeEntry(undoItem, CHANGE_TYPE.CHT_MODIFY | flags, this.makeImage(undoItem), aScreen);
break;
default:
throw new Error(`UNIMPLEMENTED_FOR( ${undoItem.GetClass()} )`);
}
return this;
}
/** `Stage( std::vector<EDA_ITEM*>&, CHANGE_TYPE, BASE_SCREEN* )`. */
protected stageContainer(
container: EDA_ITEM[],
aChangeType: number,
aScreen: BASE_SCREEN_LIKE | null,
): COMMIT {
for (const item of container) this.Stage(item, aChangeType, aScreen);
return this;
}
/** `Stage( const PICKED_ITEMS_LIST&, UNDO_REDO, BASE_SCREEN* )`. */
protected stagePickedItems(
aItems: PICKED_ITEMS_LIST,
aModFlag: UNDO_REDO,
aScreen: BASE_SCREEN_LIKE | null,
): COMMIT {
for (let i = 0; i < aItems.GetCount(); i++) {
let change_type = aItems.GetPickedItemStatus(i);
const item = aItems.GetPickedItem(i)!;
if (change_type === UNDO_REDO.UNSPECIFIED) change_type = aModFlag;
const copy = aItems.GetPickedItemLink(i);
if (copy) {
console.assert(change_type === UNDO_REDO.CHANGED);
// There was already a copy created, so use it
this.Modified(item, copy, aScreen);
} else {
this.Stage(item, this.convertFromUndoRedo(change_type), aScreen);
}
}
return this;
}
Unstage(aItem: EDA_ITEM, aScreen: BASE_SCREEN_LIKE | null): void {
this.m_entries = this.m_entries.filter((line) => {
if (line.m_item === aItem && line.m_screen === aScreen) {
// Only new items which have never been committed can be unstaged
console.assert(line.m_item.IsNew());
return false;
}
return true;
});
}
/// Execute the changes.
abstract Push(aMessage?: string, aFlags?: number): void;
/// Revert the commit by restoring the modified items state.
abstract Revert(): void;
Empty(): boolean {
return this.m_entries.length === 0;
}
/// Returns status of an item.
GetStatus(aItem: EDA_ITEM, aScreen: BASE_SCREEN_LIKE | null = null): number {
const entry = this.findEntry(this.undoLevelItem(aItem), aScreen);
return entry ? entry.m_type : 0;
}
GetFirst(): EDA_ITEM | null {
return this.m_entries.length === 0 ? null : this.m_entries[0]!.m_item;
}
/// Should be called in Push() & Revert() methods
protected clear(): void {
this.m_addedItems.clear();
this.m_changedItems.clear();
this.m_deletedItems.clear();
this.m_entries = [];
}
protected makeEntry(
aItem: EDA_ITEM,
aType: number,
aCopy: EDA_ITEM | null = null,
aScreen: BASE_SCREEN_LIKE | null = null,
): void {
const ent: COMMIT_LINE = { m_item: aItem, m_type: aType, m_copy: aCopy, m_screen: aScreen };
// N.B. Do not throw an assertion for multiple changed items. An item can be changed
// multiple times in a single commit such as when importing graphics and grouping them.
switch (aType & CHANGE_TYPE.CHT_TYPE) {
case CHANGE_TYPE.CHT_ADD:
this.m_addedItems.add(aItem, aScreen);
break;
case CHANGE_TYPE.CHT_REMOVE:
this.m_deletedItems.add(aItem, aScreen);
break;
case CHANGE_TYPE.CHT_MODIFY:
this.m_changedItems.add(aItem, aScreen);
break;
default:
console.assert(false);
break;
}
this.m_entries.push(ent);
}
/**
* Search for an entry describing change for a particular item.
*
* @return null if there is no related entry.
*/
protected findEntry(
aItem: EDA_ITEM,
aScreen: BASE_SCREEN_LIKE | null = null,
): COMMIT_LINE | null {
for (const entry of this.m_entries) {
if (entry.m_item === aItem && entry.m_screen === aScreen) return entry;
}
return null;
}
protected abstract undoLevelItem(aItem: EDA_ITEM): EDA_ITEM;
protected abstract makeImage(aItem: EDA_ITEM): EDA_ITEM;
/** `convert( UNDO_REDO aType )`. */
protected convertFromUndoRedo(aType: UNDO_REDO): CHANGE_TYPE {
switch (aType) {
case UNDO_REDO.NEWITEM:
return CHANGE_TYPE.CHT_ADD;
case UNDO_REDO.DELETED:
return CHANGE_TYPE.CHT_REMOVE;
case UNDO_REDO.CHANGED:
return CHANGE_TYPE.CHT_MODIFY;
default:
console.assert(false);
return CHANGE_TYPE.CHT_MODIFY;
}
}
/** `convert( CHANGE_TYPE aType )`. */
protected convertToUndoRedo(aType: number): UNDO_REDO {
switch (aType) {
case CHANGE_TYPE.CHT_ADD:
return UNDO_REDO.NEWITEM;
case CHANGE_TYPE.CHT_REMOVE:
return UNDO_REDO.DELETED;
case CHANGE_TYPE.CHT_MODIFY:
return UNDO_REDO.CHANGED;
default:
console.assert(false);
return UNDO_REDO.CHANGED;
}
}
}
function isPickedItemsList(a: object): a is PICKED_ITEMS_LIST {
return typeof (a as PICKED_ITEMS_LIST).GetPickedItemStatus === 'function';
}