dsh-plugin-term-dictionary 1.0.0 → 1.1.1

package/lib/core/settings.js

@@ -23,12 +23,34 @@ const SETTINGS_KEY = "dsh-plugin-term-dictionary:settings:v1";
 /** The most sources the list will hold. A UI bound, not a security one. */
 const MAX_SOURCES = 12;
 
+/**
+ * The source a fresh install starts with: this plugin's own repository, as a static file.
+ *
+ * Why ship one at all: without it the packs page opens on an empty list, and a first-time reader has
+ * to be TOLD a URL before they can see what a term pack even is. The alternative — fetching from a
+ * server we run — is the thing this design refuses to have, so the default is an ordinary source like
+ * any other: visible in the list, removable in one press, and fetched only when the reader asks (the
+ * page refreshes it on first open, which is a request to the source THEY have configured).
+ *
+ * `@main` rather than a tag because a default should follow the packs the repository actually has:
+ * pinned to a tag, a new pack would need a plugin release before anyone could see it.
+ */
+const DEFAULT_PACK_SOURCE = "https://cdn.jsdelivr.net/gh/lakerian/dsh-plugin-term-dictionary@main/packs/index.json";
+
 /**
  * The URL rule, imported rather than restated: the settings store, the page and the host's transport
  * must agree on what a usable source is, and two copies of that rule is how one of them drifts.
  */
 const { refuseUrl } = require("./pack.js");
 
+const ENTRY_COLUMNS = ["auto", "1", "2", "3"];
+
+/** The two row-height readings: equal cards, or each card as tall as its own text. */
+const ENTRY_ROWS = ["uniform", "compact"];
+
+/** The narrowest a column may be when the layout is choosing. Below this a gloss wraps every other word. */
+const MIN_COLUMN_PX = 260;
+
 /**
  * The three switches and their defaults.
  *
@@ -80,6 +102,23 @@ const DEFAULT_SETTINGS = {
 	 * the pointer had gone. Anyone who wants a grace period may have one; nobody gets it by accident.
 	 */
 	hoverOutMs: 0,
+	/**
+	 * How many columns the entry list is laid out in.
+	 *
+	 * `auto` fits as many as the panel is wide enough for, and is the default: a dictionary row is
+	 * short, a single column of them is a very long strip to read, and a narrow panel simply gets one
+	 * column back. The fixed values exist for a reader who wants the layout to stop moving under them.
+	 */
+	entryColumns: "auto",
+	/**
+	 * How tall a row of the entry list is.
+	 *
+	 * `uniform` gives every card in a grid row the height of the tallest, so the cards line up and no
+	 * empty strip is left under the short ones. `compact` lets each keep its own height, which reads
+	 * tighter in a single column and leaves exactly those strips in a grid. Both are defensible, which
+	 * is why it is a preference rather than a constant.
+	 */
+	entryRows: "uniform",
 	/**
 	 * The term-pack sources the user added: https URLs of static `index.json` files.
 	 *
@@ -88,8 +127,13 @@ const DEFAULT_SETTINGS = {
 	 * is not configuration. Validated by the same rule the host applies before it fetches anything
 	 * ({@link module:core/pack.refuseUrl}), so the page and the transport cannot disagree about what a
 	 * usable source is.
+	 *
+	 * The default is not empty: see {@link DEFAULT_PACK_SOURCE}. An ABSENT key means "never touched, use
+	 * the default"; an empty array means "the reader removed them all", which is honoured (§
+	 * `normalizeSettings`) — the two are different statements and a store that conflated them would
+	 * resurrect the default every time somebody cleared the list.
 	 */
-	packSources: []
+	packSources: [DEFAULT_PACK_SOURCE]
 };
 
 /** The accepted minimum term lengths, for the panel's cycling control. */
@@ -195,7 +239,13 @@ function normalizeSettings(raw) {
 		collectCjk: readFlag(value.collectCjk, DEFAULT_SETTINGS.collectCjk),
 		hoverInMs: readDelay(value.hoverInMs, DEFAULT_SETTINGS.hoverInMs),
 		hoverOutMs: readDelay(value.hoverOutMs, DEFAULT_SETTINGS.hoverOutMs),
-		packSources: readSources(value.packSources)
+		entryColumns: readChoice(value.entryColumns, ENTRY_COLUMNS, DEFAULT_SETTINGS.entryColumns),
+		entryRows: readChoice(value.entryRows, ENTRY_ROWS, DEFAULT_SETTINGS.entryRows),
+		// Absent means "never touched" and gets the shipped default; an empty array means the reader
+		// removed every source, and is kept as it is. A fresh array either way: a snapshot is compared by
+		// identity, so handing back the shared default array would make one page's edit appear in
+		// another page's defaults.
+		packSources: value.packSources === undefined ? [...DEFAULT_SETTINGS.packSources] : readSources(value.packSources)
 	};
 }
 
@@ -303,6 +353,10 @@ module.exports = {
 	DEFAULT_SETTINGS,
 	normalizeSettings,
 	MAX_SOURCES,
+	DEFAULT_PACK_SOURCE,
+	ENTRY_COLUMNS,
+	ENTRY_ROWS,
+	MIN_COLUMN_PX,
 	EXPLAIN_LANGS,
 	EXPLAIN_DEPTHS,
 	COLLECT_LENGTHS,

package/lib/core/store.js

@@ -201,6 +201,44 @@ function createDictionaryStore(options) {
 			return result.entry;
 		},
 
+		/**
+		 * Move a group, and everything under it, to another path.
+		 * @param from - the path to move.
+		 * @param to - the path to move it to.
+		 * @returns a promise resolving to `{ moved, error }`.
+		 */
+		async renameGroup(from, to) {
+			const result = dictionary.renameGroup(state, from, to, { now: now() });
+			if (result.moved > 0) await commit(result.state);
+			return { moved: result.moved, error: result.error };
+		},
+
+		/**
+		 * Delete a group by deleting everything inside it, which is the only way a group can be deleted.
+		 * @param from - the path to empty.
+		 * @returns a promise resolving to `{ removed, error }`.
+		 */
+		async deleteGroup(from) {
+			const result = dictionary.deleteGroup(state, from, { now: now() });
+			if (result.removed > 0) await commit(result.state);
+			return { removed: result.removed, error: result.error };
+		},
+
+		/**
+		 * Bring a deleted term back, as an explicit act.
+		 *
+		 * See `restoreEntry` in the core: a restoration is a decision with its own evidence and it
+		 * withdraws the tombstone, rather than an edit that has to win a comparison on the way to the host.
+		 * @param idOrTerm - the entry id, term or alias.
+		 * @param patch - the text to restore it with, if any.
+		 * @returns a promise resolving to `{ entry, restored }`.
+		 */
+		async restoreEntry(idOrTerm, patch) {
+			const result = dictionary.restoreEntry(state, idOrTerm, patch, { now: now() });
+			if (result.restored) await commit(result.state);
+			return { entry: result.entry, restored: result.restored };
+		},
+
 		/**
 		 * Record that a term appeared in a message, without overwriting a definition
 		 * the user wrote.
@@ -327,17 +365,29 @@ function createDictionaryStore(options) {
 			return this.saveEntry(found.term, patch);
 		},
 
+		/**
+		 * The groups directly inside one path, each with how many entries it holds.
+		 * @param prefix - the path to look inside, `""` for the top level.
+		 * @returns `[{ group, name, count }]`.
+		 */
+		groups(prefix) {
+			return dictionary.groupsIn(state.entries, prefix);
+		},
+
 		/**
 		 * The visible list for the panel.
 		 * @param query - search text.
 		 * @param filter - `all`, `unexplained`, `pinned`, `deleted` or `flagged`.
+		 * @param group - the group path to look inside, `""` for the top level.
 		 * @returns the ordered entries. For `deleted`, the tombstones.
 		 */
-		list(query, filter) {
+		list(query, filter, group) {
+			const at = group === undefined || group === null ? "" : String(group);
 			// The deleted view is a different LIST rather than a different filter: tombstones live in
-			// `backing`, not in `entries`, so no predicate over the live list could ever show one.
-			if (filter === "deleted") return dictionary.listDeleted(state, query);
-			return listEntries(state, query, filter);
+			// `backing`, not in `entries`, so no predicate over the live list could ever show one. The group
+			// still applies — standing in a folder and asking what was deleted there means that folder.
+			if (filter === "deleted") return dictionary.listDeleted(state, query).filter((entry) => (typeof entry.group === "string" ? entry.group : "") === at);
+			return listEntries(state, query, filter, at);
 		},
 
 		/**

package/lib/core/styles.js

@@ -124,6 +124,25 @@ const applyStyles = {
 		boxShadow: "0 0 0 1px var(--dsw-alias-brand-primary, #4d6bfe)"
 	},
 	rowHead: { display: "flex", alignItems: "center", gap: "6px", flexWrap: "wrap" },
+	/** Where you are, and the way back up: a directory you can only enter is a trap. */
+	breadcrumb: { display: "flex", alignItems: "center", gap: "2px", flexWrap: "wrap", padding: "2px 0 6px", fontSize: "12px" },
+	breadcrumbPart: { display: "inline-flex", alignItems: "center", gap: "2px" },
+	breadcrumbSep: { color: "var(--dsw-alias-label-tertiary)", margin: "0 2px" },
+	breadcrumbButton: { appearance: "none", border: "none", background: "none", padding: "2px 4px", font: "inherit", fontSize: "12px", color: "var(--dsw-alias-brand-primary, #4d6bfe)", cursor: "pointer" },
+	breadcrumbHere: { appearance: "none", border: "none", background: "none", padding: "2px 4px", font: "inherit", fontSize: "12px", color: "var(--dsw-alias-label-secondary)", cursor: "default" },
+	/** The group row's own bits: the mark that says "not an entry", and the chevron that says "opens". */
+	groupIcon: { display: "inline-flex", alignItems: "center", color: "var(--dsw-alias-label-secondary)" },
+	groupEnter: { color: "var(--dsw-alias-label-tertiary)", fontSize: "14px", lineHeight: 1 },
+	/** One line saying what is inside a group, so the card is not a name over a blank space. */
+	groupPreview: { margin: 0, fontSize: "12px", lineHeight: 1.5, color: "var(--dsw-alias-label-tertiary)", overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" },
+	/**
+	 * The row's action toolbar: the second line, always.
+	 *
+	 * On the title line the controls moved from row to row with the length of the term and the number of
+	 * badges; a line of their own puts every row's controls in the same place and keeps them out of the
+	 * way of the text they act on.
+	 */
+	rowActions: { display: "flex", alignItems: "center", gap: "6px", marginTop: "2px" },
 	termButton: {
 		appearance: "none",
 		background: "transparent",

package/lib/core/transfer.js

@@ -70,6 +70,9 @@ function toRecord(entry) {
 		}
 	};
 	if (typeof entry?.domain === "string" && entry.domain !== "") record.domain = entry.domain;
+	// A group travels through an export, so a backup restores the structure it was filed under; it does NOT
+	// travel in a pack, where the reader organizes entries their own way (see `pack.js`'s allowlist).
+	if (typeof entry?.group === "string" && entry.group !== "") record.group = entry.group;
 	if (Array.isArray(entry?.aliases) && entry.aliases.length > 0) record.aliases = [...entry.aliases];
 	if (entry?.pinned === true) record.pinned = true;
 	if (typeof entry?.source === "string" && entry.source !== "") record.source = entry.source;
@@ -151,6 +154,9 @@ function toEntry(raw) {
 			usage: typeof definition.usage === "string" ? definition.usage : ""
 		},
 		domain: typeof raw.domain === "string" ? raw.domain.trim() : "",
+		// A group is read back from a file like any other label the user assigned — that is what makes an
+		// export a backup of the STRUCTURE and not only of the words.
+		group: typeof raw.group === "string" ? raw.group.trim() : "",
 		aliases: Array.isArray(raw.aliases) ? raw.aliases.filter((alias) => typeof alias === "string" && alias.trim() !== "") : [],
 		pinned: raw.pinned === true
 	};
@@ -191,6 +197,64 @@ function parseImport(text) {
 	return { ok: true, entries, skipped };
 }
 
+/**
+ * The folder path a file sits in, as a group path.
+ *
+ * The picked folder's own name IS the first group: choosing a folder called `packs` is how you say "file
+ * these under `packs`", and dropping the name would put everything at the top level — which is precisely
+ * the structure the user just picked a folder to express.
+ *
+ * @param path - a `relative/path/file.json`, as `webkitRelativePath` reports it.
+ * @returns the group path.
+ */
+function folderPathOf(path) {
+	const parts = String(path)
+		.split("/")
+		.filter((part) => part !== "");
+	// Everything but the file name.
+	return parts.slice(0, -1).join("/");
+}
+
+/**
+ * Read a whole directory into one import.
+ *
+ * A folder is a mixed bag: several exported dictionaries, somebody's downloaded pack files, an
+ * `index.json` that lists packs rather than holding entries, and often a README or a screenshot. So this
+ * reports what it could NOT use instead of refusing the folder — the alternative is a user with twenty
+ * files and one bad one, told "no" with no idea which file it was. Files that are not JSON are not
+ * reported at all: they are not mistakes.
+ *
+ * @param files - `[{ path, text }]`, the directory's files as the browser hands them over.
+ * @param options - `useFolderAsGroup` files each entry under the folder it came from, which is the shape
+ *   people actually keep: one folder per topic, and the reason the option exists at all.
+ * @returns `{ entries, files, used, skipped }`, where `skipped` is `[{ name, error }]`.
+ */
+function collectFolderImport(files, options) {
+	const list = Array.isArray(files) ? files : [];
+	const entries = [];
+	const skipped = [];
+	const useFolder = options?.useFolderAsGroup === true;
+	let used = 0;
+	let jsonFiles = 0;
+	for (const file of list) {
+		const path = typeof file?.path === "string" ? file.path : "";
+		if (!/\.json$/i.test(path)) continue;
+		jsonFiles++;
+		const parsed = parseImport(typeof file?.text === "string" ? file.text : "");
+		if (parsed.ok !== true) {
+			skipped.push({ name: path, error: parsed.error });
+			continue;
+		}
+		used++;
+		const folder = useFolder ? folderPathOf(path) : "";
+		for (const entry of parsed.entries) {
+			const hasGroup = typeof entry.group === "string" && entry.group !== "";
+			entries.push(folder !== "" && !hasGroup ? { ...entry, group: folder } : entry);
+		}
+	}
+	return { entries, files: jsonFiles, used, skipped };
+}
+
 /**
  * Decide what an import would do, without doing any of it.
  *
@@ -236,10 +300,15 @@ function planImport(existing, incoming, deletedKeys, options) {
 	// Opting in does not empty the `deleted` bucket by accident: it moves those entries into
 	// `accepted`, and the bucket is then genuinely empty, so the report says "0 you deleted" and
 	// means it.
+	//
+	// `revived` names the accepted entries that were previously DELETED, separately from the ones that are
+	// simply new. The caller must not treat the two the same: a new term is a write, while a deleted term is
+	// a RESTORATION — a decision that has to beat the tombstone, not an edit that hopes to. Running both
+	// through the same write is how "a term that was collected and then deleted cannot be restored" happened.
 	const retract = options?.includeDeleted === true;
 	return retract
-		? { accepted: [...accepted, ...wasDeleted], existing: alreadyHave, deleted: [], duplicates }
-		: { accepted, existing: alreadyHave, deleted: wasDeleted, duplicates };
+		? { accepted: [...accepted, ...wasDeleted], revived: wasDeleted, existing: alreadyHave, deleted: [], duplicates }
+		: { accepted, revived: [], existing: alreadyHave, deleted: wasDeleted, duplicates };
 }
 
 /**
@@ -301,6 +370,7 @@ module.exports = {
 	buildExport,
 	buildFeedbackReport,
 	parseImport,
+	collectFolderImport,
 	planImport,
 	domainsIn,
 	toRecord,