@huaqiu/dsh-sidebar-entry 0.5.21 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/index.d.mts CHANGED
@@ -49,6 +49,15 @@ interface SidebarEntryOptions {
49
49
  refresh?: {
50
50
  subscribe(listener: () => void): () => void;
51
51
  };
52
+ /**
53
+ * Optional numeric badge (e.g. actionable plugin-update count). When set,
54
+ * the row renders a small count badge after the label; the badge is hidden
55
+ * at count 0. `subscribe` re-renders the badge whenever the count changes.
56
+ */
57
+ badge?: {
58
+ subscribe(listener: () => void): () => void;
59
+ count(): number;
60
+ };
52
61
  /** Click action (open/toggle the owning panel). */
53
62
  onToggle(): void;
54
63
  /** Family-block position: 'before' inserts ahead of sibling plugin rows, 'after' behind them. */
package/lib/index.mjs CHANGED
@@ -27,27 +27,71 @@ function createEntry(options) {
27
27
  iconSpan.className = options.css["entryIcon"] ?? "";
28
28
  iconSpan.innerHTML = options.icon;
29
29
  entry.append(iconSpan, labelSpan);
30
+ let badgeSpan = null;
31
+ const applyBadge = () => {
32
+ if (options.badge === void 0) return;
33
+ const count = options.badge.count();
34
+ if (count <= 0) {
35
+ badgeSpan?.remove();
36
+ badgeSpan = null;
37
+ return;
38
+ }
39
+ if (badgeSpan === null) {
40
+ badgeSpan = document.createElement("span");
41
+ badgeSpan.className = options.css["entryBadge"] ?? "";
42
+ entry.append(badgeSpan);
43
+ }
44
+ badgeSpan.textContent = String(count);
45
+ entry.setAttribute("data-has-badge", "");
46
+ };
30
47
  const applyLabel = () => {
31
48
  entry.setAttribute("aria-label", options.label());
32
49
  if (options.tooltip !== void 0) entry.setAttribute("title", options.tooltip());
33
50
  labelSpan.textContent = options.label();
34
51
  };
35
52
  applyLabel();
53
+ applyBadge();
36
54
  entry.addEventListener("click", options.onToggle);
37
55
  return {
38
56
  entry,
39
- applyLabel
57
+ applyLabel,
58
+ applyBadge
40
59
  };
41
60
  }
42
- /** Re-insert the entry after the New Session row (before the browser region). */
61
+ /**
62
+ * Re-insert the entry after the New Session row, in the family's intended
63
+ * order.
64
+ *
65
+ * The `familySelectors` array order is the single source of truth for visual
66
+ * order, so the rendered order is stable regardless of which plugin mounts
67
+ * first or of observer callback order — a re-render can never swap two rows.
68
+ * (Earlier builds used the `position: 'before' | 'after'` convention, which
69
+ * clustered rows by mount order and let a late-mounting `before` row steal the
70
+ * lead. The array order supersedes it; `position` remains only as a fallback
71
+ * for a row whose selector is absent from the family list.)
72
+ */
43
73
  function placeEntry(root, entry, options) {
44
74
  const button = newSessionButton(root);
45
75
  if (button === void 0) return false;
46
76
  if (entry.parentElement !== root) {
47
77
  const row = button.closest("[class*=\"logoRow\"]");
48
78
  const base = row !== null && row.parentElement === root ? row : button;
49
- const family = Array.from(root.children).filter((el) => el instanceof HTMLElement && el.matches(options.familySelectors.join(", ")));
50
- const anchor = options.position === "before" ? family.length > 0 ? family[0] : base.nextElementSibling : family.length > 0 ? family[family.length - 1].nextElementSibling : base.nextElementSibling;
79
+ const order = options.familySelectors;
80
+ const present = Array.from(root.children).filter((el) => el instanceof HTMLElement && el.matches(order.join(", "))).map((el) => ({
81
+ el,
82
+ idx: order.findIndex((sel) => el.matches(sel))
83
+ }));
84
+ const selfIndex = order.indexOf(options.rowSelector);
85
+ let anchor;
86
+ if (selfIndex === -1) anchor = options.position === "before" ? present.length > 0 ? present[0].el : base.nextElementSibling : present.length > 0 ? present[present.length - 1].el.nextElementSibling : base.nextElementSibling;
87
+ else {
88
+ const later = present.find((member) => member.idx > selfIndex);
89
+ if (later !== void 0) anchor = later.el;
90
+ else {
91
+ const earlier = [...present].reverse().find((member) => member.idx < selfIndex);
92
+ anchor = earlier !== void 0 ? earlier.el.nextElementSibling : base.nextElementSibling;
93
+ }
94
+ }
51
95
  root.insertBefore(entry, anchor ?? null);
52
96
  }
53
97
  return true;
@@ -60,13 +104,17 @@ function placeEntry(root, entry, options) {
60
104
  */
61
105
  function mountSidebarEntry(options) {
62
106
  if (typeof document !== "undefined" && document.querySelector(options.rowSelector) !== null) return () => {};
63
- const { entry, applyLabel } = createEntry(options);
107
+ const { entry, applyLabel, applyBadge } = createEntry(options);
64
108
  let root;
65
109
  let placed = false;
66
110
  let unsubscribeRefresh;
67
111
  if (options.refresh !== void 0) try {
68
112
  unsubscribeRefresh = options.refresh.subscribe(applyLabel);
69
113
  } catch {}
114
+ let unsubscribeBadge;
115
+ if (options.badge !== void 0) try {
116
+ unsubscribeBadge = options.badge.subscribe(applyBadge);
117
+ } catch {}
70
118
  const tryPlace = () => {
71
119
  if (root !== void 0 && !root.isConnected) {
72
120
  rootObserver.disconnect();
@@ -102,7 +150,7 @@ function mountSidebarEntry(options) {
102
150
  }
103
151
  if (!root.contains(entry)) placed = placeEntry(root, entry, options);
104
152
  });
105
- const unsubscribeActive = options.active === void 0 ? void 0 : (() => {
153
+ options.active === void 0 || (() => {
106
154
  const syncActive = () => {
107
155
  if (options.active.isOpen()) entry.dataset.active = "true";
108
156
  else delete entry.dataset.active;
@@ -116,7 +164,7 @@ function mountSidebarEntry(options) {
116
164
  waitObserver.disconnect();
117
165
  rootObserver.disconnect();
118
166
  unsubscribeRefresh?.();
119
- unsubscribeActive?.();
167
+ unsubscribeBadge?.();
120
168
  entry.remove();
121
169
  };
122
170
  }
@@ -129,9 +177,11 @@ function mountSidebarEntry(options) {
129
177
  * family row means adding its selector here (and to no plugin-local list).
130
178
  */
131
179
  const HUAQIU_SIDEBAR_ENTRY_FAMILY = [
180
+ "[data-hq-plugin-update-entry]",
132
181
  "[data-hqcg-footprint-entry]",
133
182
  "[data-hqcg-symbol-entry]",
134
- "[data-hqcg-schematic-entry]"
183
+ "[data-hqcg-schematic-entry]",
184
+ "[data-hq-dummy-entry]"
135
185
  ];
136
186
  /**
137
187
  * Read the host UI language from `<html lang>`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@huaqiu/dsh-sidebar-entry",
3
- "version": "0.5.21",
3
+ "version": "0.6.1",
4
4
  "type": "module",
5
5
  "main": "./lib/index.mjs",
6
6
  "types": "./lib/index.d.mts",
package/src/index.ts CHANGED
@@ -47,6 +47,15 @@ export interface SidebarEntryOptions {
47
47
  * tooltip whenever the active locale changes.
48
48
  */
49
49
  refresh?: { subscribe(listener: () => void): () => void }
50
+ /**
51
+ * Optional numeric badge (e.g. actionable plugin-update count). When set,
52
+ * the row renders a small count badge after the label; the badge is hidden
53
+ * at count 0. `subscribe` re-renders the badge whenever the count changes.
54
+ */
55
+ badge?: {
56
+ subscribe(listener: () => void): () => void
57
+ count(): number
58
+ }
50
59
  /** Click action (open/toggle the owning panel). */
51
60
  onToggle(): void
52
61
  /** Family-block position: 'before' inserts ahead of sibling plugin rows, 'after' behind them. */
@@ -86,7 +95,11 @@ function newSessionButton(root: HTMLElement): HTMLButtonElement | undefined {
86
95
  }
87
96
 
88
97
  /** Build the entry row (a detached button; insert once the shell is up). */
89
- function createEntry(options: SidebarEntryOptions): { entry: HTMLButtonElement; applyLabel: () => void } {
98
+ function createEntry(options: SidebarEntryOptions): {
99
+ entry: HTMLButtonElement
100
+ applyLabel: () => void
101
+ applyBadge: () => void
102
+ } {
90
103
  const entry = document.createElement('button')
91
104
  entry.type = 'button'
92
105
  entry.setAttribute(options.rowAttribute, '')
@@ -101,36 +114,80 @@ function createEntry(options: SidebarEntryOptions): { entry: HTMLButtonElement;
101
114
  iconSpan.className = options.css['entryIcon'] ?? ''
102
115
  iconSpan.innerHTML = options.icon
103
116
  entry.append(iconSpan, labelSpan)
117
+ // Optional numeric badge (visible only when count > 0).
118
+ let badgeSpan: HTMLSpanElement | null = null
119
+ const applyBadge = (): void => {
120
+ if (options.badge === undefined) return
121
+ const count = options.badge.count()
122
+ if (count <= 0) {
123
+ badgeSpan?.remove()
124
+ badgeSpan = null
125
+ return
126
+ }
127
+ if (badgeSpan === null) {
128
+ badgeSpan = document.createElement('span')
129
+ badgeSpan.className = options.css['entryBadge'] ?? ''
130
+ entry.append(badgeSpan)
131
+ }
132
+ badgeSpan.textContent = String(count)
133
+ entry.setAttribute('data-has-badge', '')
134
+ }
104
135
  const applyLabel = (): void => {
105
136
  entry.setAttribute('aria-label', options.label())
106
137
  if (options.tooltip !== undefined) entry.setAttribute('title', options.tooltip())
107
138
  labelSpan.textContent = options.label()
108
139
  }
109
140
  applyLabel()
141
+ applyBadge()
110
142
  entry.addEventListener('click', options.onToggle)
111
- return { entry, applyLabel }
143
+ return { entry, applyLabel, applyBadge }
112
144
  }
113
145
 
114
- /** Re-insert the entry after the New Session row (before the browser region). */
146
+ /**
147
+ * Re-insert the entry after the New Session row, in the family's intended
148
+ * order.
149
+ *
150
+ * The `familySelectors` array order is the single source of truth for visual
151
+ * order, so the rendered order is stable regardless of which plugin mounts
152
+ * first or of observer callback order — a re-render can never swap two rows.
153
+ * (Earlier builds used the `position: 'before' | 'after'` convention, which
154
+ * clustered rows by mount order and let a late-mounting `before` row steal the
155
+ * lead. The array order supersedes it; `position` remains only as a fallback
156
+ * for a row whose selector is absent from the family list.)
157
+ */
115
158
  function placeEntry(root: HTMLElement, entry: HTMLButtonElement, options: SidebarEntryOptions): boolean {
116
159
  const button = newSessionButton(root)
117
160
  if (button === undefined) return false
118
161
  if (entry.parentElement !== root) {
119
- // Position relative to the family block (entries injected by sibling
120
- // plugins), never relative to transient logoRow geometry: every family
121
- // plugin that self-heals during a re-render then lands in the same
122
- // relative order, so the entries cannot swap positions regardless of
123
- // observer callback order or of shell wrapper changes. There is no
124
- // append-to-end fallback: appending at the end would randomly reorder
125
- // the block after a shell re-render.
126
162
  const row = button.closest('[class*="logoRow"]')
127
163
  const base = (row !== null && row.parentElement === root) ? row : button
128
- const family = Array.from(root.children).filter(
129
- (el): el is HTMLElement => el instanceof HTMLElement && el.matches(options.familySelectors.join(', ')),
130
- )
131
- const anchor = options.position === 'before'
132
- ? (family.length > 0 ? family[0] : base.nextElementSibling)
133
- : (family.length > 0 ? family[family.length - 1]!.nextElementSibling : base.nextElementSibling)
164
+
165
+ // Present family members, each tagged with its index in the intended
166
+ // order. The entry being placed is detached here, so it is never counted.
167
+ const order = options.familySelectors
168
+ const present = Array.from(root.children)
169
+ .filter((el): el is HTMLElement => el instanceof HTMLElement && el.matches(order.join(', ')))
170
+ .map((el) => ({ el, idx: order.findIndex((sel) => el.matches(sel)) }))
171
+
172
+ const selfIndex = order.indexOf(options.rowSelector)
173
+ let anchor: Node | null
174
+ if (selfIndex === -1) {
175
+ // Not part of the ordered family: keep the legacy position rule.
176
+ anchor = options.position === 'before'
177
+ ? (present.length > 0 ? present[0]!.el : base.nextElementSibling)
178
+ : (present.length > 0 ? present[present.length - 1]!.el.nextElementSibling : base.nextElementSibling)
179
+ } else {
180
+ // Insert before the first present member that should come AFTER this
181
+ // entry; otherwise insert after the last present member that should come
182
+ // BEFORE it; otherwise sit right after the New Session button.
183
+ const later = present.find((member) => member.idx > selfIndex)
184
+ if (later !== undefined) {
185
+ anchor = later.el
186
+ } else {
187
+ const earlier = [...present].reverse().find((member) => member.idx < selfIndex)
188
+ anchor = earlier !== undefined ? earlier.el.nextElementSibling : base.nextElementSibling
189
+ }
190
+ }
134
191
  root.insertBefore(entry, anchor ?? null)
135
192
  }
136
193
  return true
@@ -150,7 +207,7 @@ export function mountSidebarEntry(options: SidebarEntryOptions): () => void {
150
207
  if (typeof document !== 'undefined' && document.querySelector(options.rowSelector) !== null) {
151
208
  return () => {}
152
209
  }
153
- const { entry, applyLabel } = createEntry(options)
210
+ const { entry, applyLabel, applyBadge } = createEntry(options)
154
211
  let root: HTMLElement | undefined
155
212
  let placed = false
156
213
  let unsubscribeRefresh: (() => void) | undefined
@@ -162,6 +219,15 @@ export function mountSidebarEntry(options: SidebarEntryOptions): () => void {
162
219
  // its initial value and the next reload resolves it again.
163
220
  }
164
221
  }
222
+ let unsubscribeBadge: (() => void) | undefined
223
+ if (options.badge !== undefined) {
224
+ try {
225
+ unsubscribeBadge = options.badge.subscribe(applyBadge)
226
+ } catch {
227
+ // Same defensive rule as refresh: a throwing subscription must not
228
+ // break the mount; the badge keeps its initial value.
229
+ }
230
+ }
165
231
 
166
232
  const tryPlace = (): void => {
167
233
  if (root !== undefined && !root.isConnected) {
@@ -230,7 +296,7 @@ export function mountSidebarEntry(options: SidebarEntryOptions): () => void {
230
296
  waitObserver.disconnect()
231
297
  rootObserver.disconnect()
232
298
  unsubscribeRefresh?.()
233
- unsubscribeActive?.()
299
+ unsubscribeBadge?.()
234
300
  entry.remove()
235
301
  }
236
302
  }
@@ -244,9 +310,13 @@ export function mountSidebarEntry(options: SidebarEntryOptions): () => void {
244
310
  * family row means adding its selector here (and to no plugin-local list).
245
311
  */
246
312
  export const HUAQIU_SIDEBAR_ENTRY_FAMILY: readonly string[] = [
313
+ // Plugin Updates leads the family block: it is the most frequently used
314
+ // toolbutton and carries the actionable-update badge, so it sits first.
315
+ '[data-hq-plugin-update-entry]',
247
316
  '[data-hqcg-footprint-entry]',
248
317
  '[data-hqcg-symbol-entry]',
249
318
  '[data-hqcg-schematic-entry]',
319
+ '[data-hq-dummy-entry]',
250
320
  ]
251
321
 
252
322
  // ---- host locale detection (shared by every family sidebar row) ----