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

255 lines
10 KiB
TypeScript
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
// 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.
/**
* `SYMBOL_TREE_MODEL_ADAPTER` (eeschema/symbol_tree_model_adapter.{h,cpp}): the
* symbol chooser's tree model — the two extra columns its constructor offers,
* the persisted column set (`loadColumnConfig`), and `AddLibraries`, which
* puts a library in the tree only once it is LOADED and retries the rest on a
* one-second timer.
*
* Split out of `widgets/panel_symbol_chooser.tsx`, where it had been fused
* into the panel's effects. What the adapter reads of the library layer
* (`SYMBOL_LIBRARY_ADAPTER`'s load status and symbols, the library table's
* description, the pinned list) comes in as a {@link SYMBOL_TREE_LIBRARY_SOURCE}
* because the hosted library store is the app's.
*
* The node builders (`populateItemNode`, `addUnitRows`) are
* `LIB_TREE_NODE_ITEM`'s constructor and `Update` as this adapter feeds them a
* `LIB_TREE_ITEM` — `LIB_SYMBOL::cacheSearchTerms` / `cacheChooserFields` over
* the projection the preload keeps.
*/
import { searchTerm } from '@ziroeda/common';
import { LibTreeModelAdapter, type SortMode } from '@ziroeda/common/lib_tree_model_adapter.js';
import { LibTreeNode, LibTreeNodeType } from '@ziroeda/common/lib_tree_model.js';
import { letterSubReference } from './fieldbox.js';
import { libTreeItem, type LibTreeItem, libTreeItemSearchTerms } from './lib_tree_item.js';
import type { LibIndexEntry } from './libraries/symbol_library_adapter.js';
import type { LibSymbol } from './types.js';
/**
* `m_check_pending_libraries_timer->Start( 1000 )`
* (symbol_tree_model_adapter.cpp:209): how often AddLibraries retries the
* libraries that were not LOADED yet.
*/
export const PENDING_LIBRARY_POLL_MS = 1000;
/** What `AddLibraries` asks of the library layer. */
export interface SYMBOL_TREE_LIBRARY_SOURCE {
/** `GetLibraryStatus( lib )->load_status == LOAD_STATUS::LOADED`. */
libraryLoaded(aLib: string): boolean;
/** `m_adapter->GetSymbols( lib )`, as the preload keeps them. */
loadedLibraryItems(aLib: string): readonly LibTreeItem[] | undefined;
/** The library table row's `Description()`. */
libraryDescription(aLib: LibIndexEntry): string;
/** `cfg->m_Session.pinned_symbol_libs` ∪ `project.m_PinnedSymbolLibs`. */
pinnedLibraries(): readonly string[];
/** Whether an index symbol is a power symbol, built from the whole index. */
powerSymbolTest(
aIndex: readonly LibIndexEntry[],
): (aEntry: LibIndexEntry, aSymbolName: string) => boolean;
}
/**
* `LIB_TREE_NODE_ITEM::Update`'s tail: a symbol with more than one unit gets a
* child row per unit.
*
* if( aItem->GetSubUnitCount() > 1 )
* for( int u = 1; u <= aItem->GetSubUnitCount(); ++u )
* AddUnit( aItem, u );
*
* Idempotent: the on-selection hydrate calls it again with the count read from
* the real symbol, which corrects an index that disagrees and does nothing when
* it does not.
*/
export function addUnitRows(node: LibTreeNode, units: number): void {
if (units <= 1 || node.children.length === units) return;
node.children.length = 0;
for (let u = 1; u <= units; ++u) {
const unit = new LibTreeNode();
unit.type = LibTreeNodeType.UNIT;
unit.parent = node;
unit.name = `Unit ${letterSubReference(u)}`;
unit.unit = u;
unit.libNickname = node.libNickname;
unit.libItemName = node.libItemName;
unit.intrinsicRank = -u;
node.children.push(unit);
}
}
/**
* LIB_SYMBOL::cacheSearchTerms + cacheChooserFields, weighted terms and the
* optional-column values, once the item's `LIB_TREE_ITEM` face is known.
*
* Takes the projection rather than the `LIB_SYMBOL` because that is all it ever
* read, and because the preload no longer keeps the symbols.
* {@link populateFromSymbol} is the same thing for the call sites that do hold
* a real symbol.
*/
export function populateItemNode(
node: LibTreeNode,
item: LibTreeItem,
adapter?: LibTreeModelAdapter,
): void {
const keywords = item.keywords;
node.desc = item.description;
node.footprint = item.footprint;
node.isPower = item.isPower;
node.isRoot = item.isRoot;
node.pinCount = item.pinCount;
node.sourceSearchTerms = libTreeItemSearchTerms(node.libNickname, item);
// cacheChooserFields: fields flagged `(show_in_chooser yes)` become columns,
// and "Keywords" is offered unless the symbol defines a field by that name.
node.fields = new Map<string, string>(item.chooserFields);
if (!node.fields.has('Keywords')) node.fields.set('Keywords', keywords);
if (adapter) for (const name of node.fields.keys()) adapter.addColumnIfNecessary(name);
node.rebuildSearchTerms(adapter?.getShownColumns() ?? []);
addUnitRows(node, item.unitCount);
}
/** {@link populateItemNode}, from a symbol that is actually in hand. */
export function populateFromSymbol(
node: LibTreeNode,
sym: LibSymbol,
adapter?: LibTreeModelAdapter,
): void {
populateItemNode(node, libTreeItem(sym), adapter);
}
/** The eeschema.json slices the constructor and `loadColumnConfig` read. */
export interface SYMBOL_TREE_CONFIG {
/** `m_SymChooserPanel.sort_mode`. */
sortMode: SortMode;
/** `m_LibTree.columns`. */
columns: readonly string[];
}
export class SYMBOL_TREE_MODEL_ADAPTER extends LibTreeModelAdapter {
/** `m_pending_load_libraries`. */
private m_pending_load_libraries: LibIndexEntry[] = [];
/** `m_check_pending_libraries_timer`. */
private m_check_pending_libraries_timer: ReturnType<typeof setInterval> | null = null;
/** `m_lazyLoadHandler`: the panel's refresh after a pass added rows. */
private m_lazyLoadHandler: (() => void) | null = null;
/**
* `SYMBOL_TREE_MODEL_ADAPTER::SYMBOL_TREE_MODEL_ADAPTER` (:50-58) — the ONLY
* adapter upstream that widens the base pair of available columns. Not
* decoration: every shown column becomes a weight-4 search term in
* `RebuildSearchTerms`, so it is part of this chooser's ranking as well as
* its header — then `loadColumnConfig`'s persisted set.
*/
constructor(aCfg: SYMBOL_TREE_CONFIG) {
super();
this.setSymbolChooserColumns();
this.setSortMode(aCfg.sortMode);
// loadColumnConfig: the persisted column set, defaulting to Item +
// Description with "Item" forced to the front.
if (aCfg.columns.length > 0) this.setShownColumns(aCfg.columns);
}
/** `SetLazyLoadHandler( std::function<void()> )` (lib_tree_model_adapter.h). */
SetLazyLoadHandler(aHandler: (() => void) | null): void {
this.m_lazyLoadHandler = aHandler;
}
/** The libraries still waiting to load (`m_pending_load_libraries`). */
PendingLibraries(): readonly LibIndexEntry[] {
return this.m_pending_load_libraries;
}
/**
* `SYMBOL_TREE_MODEL_ADAPTER::AddLibraries` (:81-222), including the part
* that decides WHICH libraries are in the tree at all.
*
* A library is added only when its status is LOADED; anything else goes in
* `m_pending_load_libraries` and is skipped. A retry looks at the pending set
* ALONE and adds to the tree already built, it does not rebuild it. While
* anything is pending, a 1000 ms timer re-runs this until the set empties.
*
* One difference: the lazy-load handler runs after EVERY pass, not only a
* lazy one that added something (:217-221) — the panel builds its tree after
* it is shown, so the first pass is the one that has to refresh it too.
*/
AddLibraries(aIndex: readonly LibIndexEntry[], aSource: SYMBOL_TREE_LIBRARY_SOURCE): void {
// Built from the whole index, not per entry: the generator omits `power`
// both for a library with none and for an index too old to carry the
// flag, and only the index as a whole separates the two.
const isPower = aSource.powerSymbolTest(aIndex);
const pinned = aSource.pinnedLibraries();
const toLoad =
this.m_pending_load_libraries.length > 0 ? this.m_pending_load_libraries : aIndex;
const stillPending: LibIndexEntry[] = [];
for (const lib of toLoad) {
// `if( !status || status->load_status != LOAD_STATUS::LOADED )
// { m_pending_load_libraries.insert( lib ); continue; }`
if (!aSource.libraryLoaded(lib.name)) {
stillPending.push(lib);
continue;
}
const libNode = this.addLibrary(
lib.name,
aSource.libraryDescription(lib),
pinned.includes(lib.name),
);
// `std::vector<LIB_SYMBOL*> libSymbols = m_adapter->GetSymbols( lib );`
const symbols = new Map(
(aSource.loadedLibraryItems(lib.name) ?? []).map((item) => [item.name, item]),
);
for (const name of lib.symbols) {
const item = new LibTreeNode();
item.type = LibTreeNodeType.ITEM;
item.parent = libNode;
item.name = name;
item.libNickname = lib.name;
item.libItemName = name;
item.isPower = isPower(lib, name);
item.sourceSearchTerms = [
searchTerm(lib.name, 4),
searchTerm(name, 8, true),
searchTerm(`${lib.name}:${name}`, 16, true),
];
// `LIB_SYMBOL::cacheSearchTerms` is SEVEN terms, not three
// (eeschema/lib_symbol.cpp:160-183); the loaded item supplies the rest.
const loaded = symbols.get(name);
if (loaded) populateItemNode(item, loaded, this);
// The unit rows are built with the node, from the count the index
// carries, so a multi-unit part shows its expander before anything is
// fetched.
addUnitRows(item, lib.units?.[name] ?? 1);
libNode.children.push(item);
}
this.finishLibrary(libNode);
}
this.m_pending_load_libraries = stillPending;
this.tree.assignIntrinsicRanks();
this.m_lazyLoadHandler?.();
// `if( !m_pending_load_libraries.empty() && !m_check_pending_libraries_timer )`
// — one timer, started once, stopped when nothing is pending.
if (this.m_pending_load_libraries.length > 0 && !this.m_check_pending_libraries_timer) {
this.m_check_pending_libraries_timer = setInterval(() => {
this.AddLibraries(aIndex, aSource);
if (this.m_pending_load_libraries.length === 0) this.StopPendingTimer();
}, PENDING_LIBRARY_POLL_MS);
}
}
/** `m_check_pending_libraries_timer->Stop(); .reset()` — also the destructor's. */
StopPendingTimer(): void {
if (this.m_check_pending_libraries_timer) {
clearInterval(this.m_check_pending_libraries_timer);
this.m_check_pending_libraries_timer = null;
}
}
}