234 lines
7.9 KiB
TypeScript
234 lines
7.9 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.
|
|
/**
|
|
* The library-tree data model used by the chooser dialogs: a root holding
|
|
* library nodes, holding item nodes, holding unit nodes. Mirrors
|
|
* kicad/common/lib_tree_model.cpp (LIB_TREE_NODE and subclasses).
|
|
*/
|
|
import { type EdaCombinedMatcher, type SearchTerm, strNumCmp } from './index.js';
|
|
|
|
/** Upstream LIB_TREE_NODE::TYPE, the numeric order matters for sorting. */
|
|
export enum LibTreeNodeType {
|
|
ROOT = 0,
|
|
LIBRARY = 1,
|
|
ITEM = 2,
|
|
UNIT = 3,
|
|
}
|
|
|
|
export type LibTreeNodeFilter = (node: LibTreeNode) => boolean;
|
|
|
|
export class LibTreeNode {
|
|
parent: LibTreeNode | null = null;
|
|
type: LibTreeNodeType = LibTreeNodeType.ROOT;
|
|
children: LibTreeNode[] = [];
|
|
|
|
/** Displayed name (Item column). */
|
|
name = '';
|
|
/** Displayed description (Description column). */
|
|
desc = '';
|
|
/** Library nickname portion of the LIB_ID ('' for groups). */
|
|
libNickname = '';
|
|
/** Item name portion of the LIB_ID ('' for library rows). */
|
|
libItemName = '';
|
|
footprint = '';
|
|
pinCount = 0;
|
|
unit = 0;
|
|
|
|
intrinsicRank = 0;
|
|
score = 0;
|
|
exactMatch = false;
|
|
pinned = false;
|
|
|
|
/** LIB_SYMBOL::IsRoot, a derived symbol's name is italicised in the tree. */
|
|
isRoot = true;
|
|
isPower = false;
|
|
isRecentlyUsedGroup = false;
|
|
isAlreadyPlacedGroup = false;
|
|
|
|
/** GetChooserFields: the values shown in the optional extra columns, keyed by
|
|
* column (field) name. */
|
|
fields = new Map<string, string>();
|
|
|
|
/** Weighted search terms as the item supplies them (LIB_SYMBOL::GetSearchTerms).
|
|
* `searchTerms` adds the shown columns' field values on top. */
|
|
sourceSearchTerms: SearchTerm[] = [];
|
|
/** Weighted search terms actually scored (LIB_TREE_NODE::m_SearchTerms). */
|
|
searchTerms: SearchTerm[] = [];
|
|
|
|
/**
|
|
* LIB_TREE_NODE::RebuildSearchTerms, the item's own terms plus the value of
|
|
* every field currently shown as a column (weight 4), so a visible column is
|
|
* also searchable.
|
|
*/
|
|
rebuildSearchTerms(shownColumns: readonly string[]): void {
|
|
this.searchTerms = [...this.sourceSearchTerms];
|
|
for (const [name, value] of this.fields)
|
|
if (shownColumns.includes(name)) this.searchTerms.push({ text: value, score: 4 });
|
|
}
|
|
|
|
/** LIB_ID as written, e.g. "Device:R", or '' when the node has none. */
|
|
get libId(): string {
|
|
return this.libItemName ? `${this.libNickname}:${this.libItemName}` : '';
|
|
}
|
|
|
|
get isGroup(): boolean {
|
|
return this.isRecentlyUsedGroup || this.isAlreadyPlacedGroup;
|
|
}
|
|
|
|
/**
|
|
* LIB_TREE_NODE::AssignIntrinsicRanks, pre-sort children alphabetically so
|
|
* they tie-break consistently once scores equalise. `presorted` preserves
|
|
* the insertion order (used by the Recently Used group).
|
|
*/
|
|
assignIntrinsicRanks(presorted = false, shownColumns: readonly string[] = []): void {
|
|
for (const child of this.children) child.rebuildSearchTerms(shownColumns);
|
|
if (presorted) {
|
|
const max = this.children.length - 1;
|
|
this.children.forEach((child, i) => {
|
|
child.intrinsicRank = max - i;
|
|
});
|
|
} else {
|
|
// Upstream sorts with `StrNumCmp( a, b, true ) > 0`, i.e. DESCENDING, and
|
|
// then hands out ranks 0..n-1 in that order; Compare() below orders by
|
|
// rank descending, so the row the user sees is ascending by name.
|
|
const sorted = [...this.children].sort((a, b) => -strNumCmp(a.name, b.name, true));
|
|
sorted.forEach((child, i) => {
|
|
child.intrinsicRank = i;
|
|
});
|
|
}
|
|
}
|
|
|
|
/** LIB_TREE_NODE_*::UpdateScore, matches propagate scores down the tree. */
|
|
updateScore(matchers: EdaCombinedMatcher[], filter: LibTreeNodeFilter | null): void {
|
|
switch (this.type) {
|
|
case LibTreeNodeType.ROOT:
|
|
for (const child of this.children) child.updateScore(matchers, filter);
|
|
return;
|
|
|
|
case LibTreeNodeType.LIBRARY:
|
|
if (this.children.length === 0) {
|
|
// As-yet-unloaded libraries score on their own terms so a library
|
|
// whose name matches still shows up.
|
|
this.scoreSelf(matchers);
|
|
} else {
|
|
this.score = 0;
|
|
this.exactMatch = false;
|
|
for (const child of this.children) {
|
|
child.updateScore(matchers, filter);
|
|
this.score = Math.max(this.score, child.score);
|
|
this.exactMatch ||= child.exactMatch;
|
|
}
|
|
}
|
|
return;
|
|
|
|
case LibTreeNodeType.ITEM:
|
|
this.scoreSelf(matchers);
|
|
if (filter && !filter(this)) this.score = 0;
|
|
for (const child of this.children) child.updateScore(matchers, filter);
|
|
return;
|
|
|
|
case LibTreeNodeType.UNIT:
|
|
// Match results are inherited from the parent symbol.
|
|
this.score = 1;
|
|
this.exactMatch = false;
|
|
if (matchers.length > 0 && this.parent) {
|
|
this.score = this.parent.score;
|
|
this.exactMatch = this.parent.exactMatch;
|
|
}
|
|
if (filter && !filter(this)) this.score = 0;
|
|
return;
|
|
}
|
|
}
|
|
|
|
private scoreSelf(matchers: EdaCombinedMatcher[]): void {
|
|
this.score = 1;
|
|
this.exactMatch = false;
|
|
for (const matcher of matchers) {
|
|
const { score, exact } = matcher.scoreTerms(this.searchTerms);
|
|
if (score === 0) {
|
|
// Each search token must match somewhere; a miss vetoes the item.
|
|
this.score = 0;
|
|
this.exactMatch = false;
|
|
return;
|
|
}
|
|
this.score += score;
|
|
this.exactMatch ||= exact;
|
|
}
|
|
}
|
|
|
|
sortNodes(useScores: boolean): void {
|
|
this.children.sort((a, b) =>
|
|
compareNodes(a, b, useScores) ? -1 : compareNodes(b, a, useScores) ? 1 : 0,
|
|
);
|
|
for (const child of this.children) child.sortNodes(useScores);
|
|
}
|
|
}
|
|
|
|
/**
|
|
* LIB_TREE_NODE::Compare, Recently Used first, then pinned libraries, then
|
|
* exact matches, then score, then the intrinsic (alphabetical) rank.
|
|
*/
|
|
export function compareNodes(a: LibTreeNode, b: LibTreeNode, useScores: boolean): boolean {
|
|
if (a.type !== b.type) return a.type < b.type;
|
|
|
|
// Recently used sorts at top; the Already Placed group ("-- " prefix) next.
|
|
if (a.isRecentlyUsedGroup) return !b.isRecentlyUsedGroup;
|
|
if (b.isRecentlyUsedGroup) return false;
|
|
if (a.name.startsWith('-- ') && !b.name.startsWith('-- ')) return true;
|
|
if (b.name.startsWith('-- ')) return false;
|
|
|
|
// Pinned nodes go next.
|
|
if (a.pinned && !b.pinned) return true;
|
|
if (b.pinned && !a.pinned) return false;
|
|
|
|
if (useScores) {
|
|
// Exact matches form a strictly higher tier than any accumulation of
|
|
// partial matches.
|
|
if (a.exactMatch !== b.exactMatch) return a.exactMatch;
|
|
if (a.score !== b.score) return a.score > b.score;
|
|
}
|
|
|
|
return a.intrinsicRank > b.intrinsicRank;
|
|
}
|
|
|
|
/** LIB_TREE_NODE_LIBRARY, one library (or pseudo-library group) row. */
|
|
export function makeLibraryNode(parent: LibTreeNode, name: string, desc: string): LibTreeNode {
|
|
const node = new LibTreeNode();
|
|
node.type = LibTreeNodeType.LIBRARY;
|
|
node.parent = parent;
|
|
node.name = name;
|
|
node.desc = desc;
|
|
node.libNickname = name;
|
|
node.sourceSearchTerms = [{ text: name, score: 8, isName: true }];
|
|
node.searchTerms = [...node.sourceSearchTerms];
|
|
parent.children.push(node);
|
|
return node;
|
|
}
|
|
|
|
/** LIB_TREE_NODE_ITEM, one symbol row under a library. */
|
|
export function makeItemNode(parent: LibTreeNode, libNickname: string, name: string): LibTreeNode {
|
|
const node = new LibTreeNode();
|
|
node.type = LibTreeNodeType.ITEM;
|
|
node.parent = parent;
|
|
node.name = name;
|
|
node.libNickname = libNickname;
|
|
node.libItemName = name;
|
|
parent.children.push(node);
|
|
return node;
|
|
}
|
|
|
|
/** LIB_TREE_NODE_UNIT, "Unit A"… sub-rows of a multi-unit symbol. */
|
|
export function makeUnitNode(parent: LibTreeNode, name: string, unit: number): LibTreeNode {
|
|
const node = new LibTreeNode();
|
|
node.type = LibTreeNodeType.UNIT;
|
|
node.parent = parent;
|
|
node.name = name;
|
|
node.unit = unit;
|
|
node.libNickname = parent.libNickname;
|
|
node.libItemName = parent.libItemName;
|
|
node.intrinsicRank = -unit;
|
|
parent.children.push(node);
|
|
return node;
|
|
}
|