@lmzhen/dsh-evolution-client-kit 0.33.0 → 0.35.0

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.js CHANGED
@@ -187,34 +187,51 @@ function createForm(namespace, ctx) {
187
187
  ...EMPTY,
188
188
  reason: "seat-missing"
189
189
  };
190
+ let lastReady;
191
+ let generation = 0;
190
192
  const listeners = /* @__PURE__ */ new Set();
191
- let started = false;
192
- let listening = false;
193
+ let remoteOff;
193
194
  const notify = () => {
194
195
  for (const listener of listeners) listener();
195
196
  };
196
- const refresh = async () => {
197
- snapshot = await describe(namespace);
197
+ const absorb = (next) => {
198
+ if (next.status === "ready") {
199
+ lastReady = next;
200
+ snapshot = next;
201
+ } else if (lastReady !== void 0) snapshot = {
202
+ ...lastReady,
203
+ stale: true,
204
+ reason: next.reason ?? "readback-failed"
205
+ };
206
+ else snapshot = next;
198
207
  notify();
199
208
  };
200
- const start = () => {
201
- if (started) return;
202
- started = true;
203
- if (!listening) {
204
- listening = true;
205
- (ctx.get?.("remote"))?.$on?.("settings/document-updated", (changed) => {
206
- if (changed === namespace) refresh();
207
- });
208
- }
209
- refresh();
209
+ const refresh = async () => {
210
+ const ticket = ++generation;
211
+ const next = await describe(namespace);
212
+ if (ticket !== generation) return;
213
+ absorb(next);
214
+ };
215
+ const remote = () => ctx.get?.("remote");
216
+ const stopRemote = () => {
217
+ remoteOff?.();
218
+ remoteOff = void 0;
219
+ };
220
+ const startRemote = () => {
221
+ if (remoteOff !== void 0) return;
222
+ remoteOff = remote()?.$on?.("settings/document-updated", (changed) => {
223
+ if (changed === namespace) refresh();
224
+ });
210
225
  };
211
226
  const form = {
212
227
  getSnapshot: () => snapshot,
213
228
  subscribe: (listener) => {
214
229
  listeners.add(listener);
215
- start();
230
+ startRemote();
231
+ refresh();
216
232
  return () => {
217
233
  listeners.delete(listener);
234
+ if (listeners.size === 0) stopRemote();
218
235
  };
219
236
  },
220
237
  set: async (field, value) => await form.mutate([{
@@ -228,35 +245,39 @@ function createForm(namespace, ctx) {
228
245
  }]),
229
246
  mutate: async (ops, expectedRevision) => {
230
247
  const outcome = await write(namespace, ops, expectedRevision ?? snapshot.revision);
231
- if (outcome.snapshot !== void 0) {
232
- snapshot = outcome.snapshot;
233
- notify();
234
- } else await refresh();
248
+ if (outcome.snapshot !== void 0) absorb(outcome.snapshot);
249
+ else await refresh();
235
250
  return outcome.ok;
251
+ },
252
+ refresh,
253
+ dispose: () => {
254
+ stopRemote();
255
+ listeners.clear();
236
256
  }
237
257
  };
238
258
  return form;
239
259
  }
240
260
  /**
241
- * Build one cached form per family namespace over the family settings routes.
242
- * @param ctx - the client plugin context (remote subscription is optional).
243
- * @returns the seat; each namespace is served by /api/dsh-evolution/settings/*.
261
+ * Build one seat per client registration; every form's remote listener is released by
262
+ * the caller's effect. No module-level WeakMap: a replaced registration must not share
263
+ * a dead seat with the previous one.
244
264
  */
245
- const seats = /* @__PURE__ */ new WeakMap();
246
265
  function createSettingsSeat(ctx) {
247
- const cached = seats.get(ctx);
248
- if (cached !== void 0) return cached;
249
266
  const forms = /* @__PURE__ */ new Map();
250
- const seat = { get(namespace) {
251
- let form = forms.get(namespace);
252
- if (form === void 0) {
253
- form = createForm(namespace, ctx);
254
- forms.set(namespace, form);
267
+ return {
268
+ get(namespace) {
269
+ let form = forms.get(namespace);
270
+ if (form === void 0) {
271
+ form = createForm(namespace, ctx);
272
+ forms.set(namespace, form);
273
+ }
274
+ return form;
275
+ },
276
+ dispose: () => {
277
+ for (const form of forms.values()) form.dispose?.();
278
+ forms.clear();
255
279
  }
256
- return form;
257
- } };
258
- seats.set(ctx, seat);
259
- return seat;
280
+ };
260
281
  }
261
282
  //#endregion
262
283
  //#region lib/types/workspace.js
@@ -381,6 +402,42 @@ var AsyncResource = class {
381
402
  }
382
403
  };
383
404
  //#endregion
405
+ //#region lib/types/format.js
406
+ /**
407
+ * Format an ISO string, epoch milliseconds, or null as local wall time.
408
+ * Invalid values return null; callers decide how to say "unknown".
409
+ * @param value - ISO string, epoch ms, or null.
410
+ * @param options - seconds on/off; defaults to on.
411
+ * @returns the formatted local time, or null when the value is absent/invalid.
412
+ */
413
+ function formatLocalDateTime(value, options = {}) {
414
+ if (value === null || value === void 0) return null;
415
+ const ms = typeof value === "number" ? value : Date.parse(value);
416
+ if (!Number.isFinite(ms)) return null;
417
+ const date = new Date(ms);
418
+ if (Number.isNaN(date.getTime())) return null;
419
+ const pad = (part) => String(part).padStart(2, "0");
420
+ const head = String(date.getFullYear()) + "-" + pad(date.getMonth() + 1) + "-" + pad(date.getDate()) + " " + pad(date.getHours()) + ":" + pad(date.getMinutes());
421
+ return options.seconds === false ? head : head + ":" + pad(date.getSeconds());
422
+ }
423
+ //#endregion
424
+ //#region lib/types/notice.js
425
+ /** One inline state notice: semantic tone plus text, no surface-specific styling. */
426
+ /**
427
+ * Render one informative/warning/error line. The caller owns the surface class and CSS;
428
+ * this leaf owns only the accessible role and the fact/count split.
429
+ * @param props - tone, text, optional count/class.
430
+ * @returns a semantic state notice.
431
+ */
432
+ function StateNotice({ tone, text, count, className }) {
433
+ return createElement("div", {
434
+ "data-role": "state-notice",
435
+ "data-tone": tone,
436
+ role: tone === "error" ? "alert" : "status",
437
+ ...className === void 0 ? {} : { className }
438
+ }, createElement("span", { "data-role": "state-notice-text" }, text), count === void 0 ? null : createElement("span", { "data-role": "state-notice-count" }, String(count)));
439
+ }
440
+ //#endregion
384
441
  //#region lib/types/action.js
385
442
  /**
386
443
  * Command-only actions. Approval decisions are a separate host API and must never
@@ -498,4 +555,4 @@ function createSettingsGatewayCache(binder, api) {
498
555
  };
499
556
  }
500
557
  //#endregion
501
- export { AsyncResource, Block, CommandCopyButton, FALLBACKS, FailureBlock, PAGE_SURFACE_CLASS, PAGE_SURFACE_CSS, ROUTES, TOKENS, TOKEN_CSS, copyAction, createSettingsGatewayCache, createSettingsSeat, failureText, loadStateOf, panelWorkspaceId, registerSidebarPanel, registerWorkbenchView, saveSettings, tokenVars };
558
+ export { AsyncResource, Block, CommandCopyButton, FALLBACKS, FailureBlock, PAGE_SURFACE_CLASS, PAGE_SURFACE_CSS, ROUTES, StateNotice, TOKENS, TOKEN_CSS, copyAction, createSettingsGatewayCache, createSettingsSeat, failureText, formatLocalDateTime, loadStateOf, panelWorkspaceId, registerSidebarPanel, registerWorkbenchView, saveSettings, tokenVars };
@@ -0,0 +1,14 @@
1
+ /** Locale-independent date/time formatting shared by the reading surfaces. */
2
+ export interface LocalDateTimeOptions {
3
+ /** Include seconds (merge/audit rows) or only minutes (version lists). */
4
+ readonly seconds?: boolean;
5
+ }
6
+ /**
7
+ * Format an ISO string, epoch milliseconds, or null as local wall time.
8
+ * Invalid values return null; callers decide how to say "unknown".
9
+ * @param value - ISO string, epoch ms, or null.
10
+ * @param options - seconds on/off; defaults to on.
11
+ * @returns the formatted local time, or null when the value is absent/invalid.
12
+ */
13
+ export declare function formatLocalDateTime(value: string | number | null | undefined, options?: LocalDateTimeOptions): string | null;
14
+ //# sourceMappingURL=format.d.ts.map
@@ -0,0 +1,22 @@
1
+ /**
2
+ * Format an ISO string, epoch milliseconds, or null as local wall time.
3
+ * Invalid values return null; callers decide how to say "unknown".
4
+ * @param value - ISO string, epoch ms, or null.
5
+ * @param options - seconds on/off; defaults to on.
6
+ * @returns the formatted local time, or null when the value is absent/invalid.
7
+ */
8
+ export function formatLocalDateTime(value, options = {}) {
9
+ if (value === null || value === undefined)
10
+ return null;
11
+ const ms = typeof value === 'number' ? value : Date.parse(value);
12
+ if (!Number.isFinite(ms))
13
+ return null;
14
+ const date = new Date(ms);
15
+ if (Number.isNaN(date.getTime()))
16
+ return null;
17
+ const pad = (part) => String(part).padStart(2, '0');
18
+ const head = String(date.getFullYear()) + '-' + pad(date.getMonth() + 1) + '-' + pad(date.getDate())
19
+ + ' ' + pad(date.getHours()) + ':' + pad(date.getMinutes());
20
+ return options.seconds === false ? head : head + ':' + pad(date.getSeconds());
21
+ }
22
+ //# sourceMappingURL=format.js.map
@@ -6,6 +6,8 @@ export { createSettingsSeat } from './settings-seat.ts';
6
6
  export type { WorkbenchViewSpec } from './workbench-view.ts';
7
7
  export { panelWorkspaceId } from './workspace.ts';
8
8
  export { AsyncResource } from './async-resource.ts';
9
+ export { formatLocalDateTime, type LocalDateTimeOptions } from './format.ts';
10
+ export { StateNotice, type StateNoticeProps, type StateNoticeTone } from './notice.ts';
9
11
  export { CommandCopyButton, copyAction } from './action.ts';
10
12
  export type { ActionRef, CommandCopyButtonProps, CommandCopyLabels, CopyStatus } from './action.ts';
11
13
  export type { AsyncLoader, AsyncState, AsyncStatus } from './async-resource.ts';
@@ -3,6 +3,8 @@ export { registerWorkbenchView } from "./workbench-view.js";
3
3
  export { createSettingsSeat } from "./settings-seat.js";
4
4
  export { panelWorkspaceId } from "./workspace.js";
5
5
  export { AsyncResource } from "./async-resource.js";
6
+ export { formatLocalDateTime } from "./format.js";
7
+ export { StateNotice } from "./notice.js";
6
8
  export { CommandCopyButton, copyAction } from "./action.js";
7
9
  export { ROUTES } from "./generated/routes.generated.js";
8
10
  export { FALLBACKS } from "./generated/fallbacks.generated.js";
@@ -0,0 +1,18 @@
1
+ /** One inline state notice: semantic tone plus text, no surface-specific styling. */
2
+ import { type ReactNode } from 'react';
3
+ export type StateNoticeTone = 'info' | 'warning' | 'error';
4
+ export interface StateNoticeProps {
5
+ readonly tone: StateNoticeTone;
6
+ readonly text: string;
7
+ /** Optional count shown after the sentence (e.g. "2 expired"). */
8
+ readonly count?: number | undefined;
9
+ readonly className?: string | undefined;
10
+ }
11
+ /**
12
+ * Render one informative/warning/error line. The caller owns the surface class and CSS;
13
+ * this leaf owns only the accessible role and the fact/count split.
14
+ * @param props - tone, text, optional count/class.
15
+ * @returns a semantic state notice.
16
+ */
17
+ export declare function StateNotice({ tone, text, count, className }: StateNoticeProps): ReactNode;
18
+ //# sourceMappingURL=notice.d.ts.map
@@ -0,0 +1,17 @@
1
+ /** One inline state notice: semantic tone plus text, no surface-specific styling. */
2
+ import { createElement } from 'react';
3
+ /**
4
+ * Render one informative/warning/error line. The caller owns the surface class and CSS;
5
+ * this leaf owns only the accessible role and the fact/count split.
6
+ * @param props - tone, text, optional count/class.
7
+ * @returns a semantic state notice.
8
+ */
9
+ export function StateNotice({ tone, text, count, className }) {
10
+ return createElement('div', {
11
+ 'data-role': 'state-notice',
12
+ 'data-tone': tone,
13
+ role: tone === 'error' ? 'alert' : 'status',
14
+ ...(className === undefined ? {} : { className }),
15
+ }, createElement('span', { 'data-role': 'state-notice-text' }, text), count === undefined ? null : createElement('span', { 'data-role': 'state-notice-count' }, String(count)));
16
+ }
17
+ //# sourceMappingURL=notice.js.map
@@ -64,9 +64,15 @@ export interface ConfigFormLike<T = Record<string, unknown>> {
64
64
  unset(field: string): Promise<boolean>;
65
65
  /** Atomic multi-field save; `expectedRevision` is the read the caller is replacing. */
66
66
  mutate(ops: readonly ConfigPathOpLike[], expectedRevision?: number): Promise<boolean>;
67
+ /** Re-read the row (used by the card's readback verdict). */
68
+ refresh?(): Promise<void>;
69
+ /** Stop the form's remote subscription; owned by the seat. */
70
+ dispose?(): void;
67
71
  }
68
72
  export interface ConfigFormsSeat {
69
73
  get<T = Record<string, unknown>>(entryId: string): ConfigFormLike<T> | undefined;
74
+ /** Release every form's remote listener; called from the client effect. */
75
+ dispose?(): void;
70
76
  }
71
77
  export interface SettingsFace {
72
78
  merge?: ConfigFormLike;
@@ -15,6 +15,11 @@ interface ContextLike {
15
15
  $on?: (event: string, listener: (namespace: string) => void) => () => void;
16
16
  };
17
17
  }
18
+ /**
19
+ * Build one seat per client registration; every form's remote listener is released by
20
+ * the caller's effect. No module-level WeakMap: a replaced registration must not share
21
+ * a dead seat with the previous one.
22
+ */
18
23
  export declare function createSettingsSeat(ctx: ContextLike): ConfigFormsSeat;
19
24
  export {};
20
25
  //# sourceMappingURL=settings-seat.d.ts.map
@@ -45,62 +45,78 @@ async function write(namespace, ops, expectedRevision) {
45
45
  }
46
46
  function createForm(namespace, ctx) {
47
47
  let snapshot = { ...EMPTY, reason: 'seat-missing' };
48
+ let lastReady;
49
+ let generation = 0;
48
50
  const listeners = new Set();
49
- let started = false;
50
- let listening = false;
51
+ let remoteOff;
51
52
  const notify = () => { for (const listener of listeners)
52
53
  listener(); };
53
- const refresh = async () => {
54
- snapshot = await describe(namespace);
54
+ const absorb = (next) => {
55
+ if (next.status === 'ready') {
56
+ lastReady = next;
57
+ snapshot = next;
58
+ }
59
+ else if (lastReady !== undefined) {
60
+ // A failed re-read must not erase the last usable values. Keep ready + mark stale;
61
+ // the card shows the values with a warning instead of claiming the plugin is absent.
62
+ snapshot = { ...lastReady, stale: true, reason: next.reason ?? 'readback-failed' };
63
+ }
64
+ else {
65
+ snapshot = next;
66
+ }
55
67
  notify();
56
68
  };
57
- const start = () => {
58
- if (started)
69
+ const refresh = async () => {
70
+ const ticket = ++generation;
71
+ const next = await describe(namespace);
72
+ if (ticket !== generation)
73
+ return;
74
+ absorb(next);
75
+ };
76
+ const remote = () => ctx.get?.('remote');
77
+ const stopRemote = () => { remoteOff?.(); remoteOff = undefined; };
78
+ const startRemote = () => {
79
+ if (remoteOff !== undefined)
59
80
  return;
60
- started = true;
61
- if (!listening) {
62
- listening = true;
63
- const remote = ctx.get?.('remote');
64
- remote?.$on?.('settings/document-updated', (changed) => { if (changed === namespace)
65
- void refresh(); });
66
- }
67
- void refresh();
81
+ remoteOff = remote()?.$on?.('settings/document-updated', (changed) => { if (changed === namespace)
82
+ void refresh(); });
68
83
  };
69
84
  const form = {
70
85
  getSnapshot: () => snapshot,
71
86
  subscribe: (listener) => {
72
87
  listeners.add(listener);
73
- start();
74
- return () => { listeners.delete(listener); };
88
+ startRemote();
89
+ void refresh();
90
+ return () => {
91
+ listeners.delete(listener);
92
+ if (listeners.size === 0)
93
+ stopRemote();
94
+ };
75
95
  },
76
96
  set: async (field, value) => (await form.mutate([{ op: 'set', path: [field], value }])),
77
97
  unset: async (field) => (await form.mutate([{ op: 'unset', path: [field] }])),
78
98
  mutate: async (ops, expectedRevision) => {
79
99
  const revision = expectedRevision ?? snapshot.revision;
80
100
  const outcome = await write(namespace, ops, revision);
81
- if (outcome.snapshot !== undefined) {
82
- snapshot = outcome.snapshot;
83
- notify();
84
- }
101
+ if (outcome.snapshot !== undefined)
102
+ absorb(outcome.snapshot);
85
103
  else
86
104
  await refresh();
87
105
  return outcome.ok;
88
106
  },
107
+ refresh,
108
+ dispose: () => { stopRemote(); listeners.clear(); },
89
109
  };
90
110
  return form;
91
111
  }
92
112
  /**
93
- * Build one cached form per family namespace over the family settings routes.
94
- * @param ctx - the client plugin context (remote subscription is optional).
95
- * @returns the seat; each namespace is served by /api/dsh-evolution/settings/*.
113
+ * Build one seat per client registration; every form's remote listener is released by
114
+ * the caller's effect. No module-level WeakMap: a replaced registration must not share
115
+ * a dead seat with the previous one.
96
116
  */
97
- const seats = new WeakMap();
98
117
  export function createSettingsSeat(ctx) {
99
- const cached = seats.get(ctx);
100
- if (cached !== undefined)
101
- return cached;
102
118
  const forms = new Map();
103
- const seat = {
119
+ return {
104
120
  get(namespace) {
105
121
  let form = forms.get(namespace);
106
122
  if (form === undefined) {
@@ -109,8 +125,11 @@ export function createSettingsSeat(ctx) {
109
125
  }
110
126
  return form;
111
127
  },
128
+ dispose: () => {
129
+ for (const form of forms.values())
130
+ form.dispose?.();
131
+ forms.clear();
132
+ },
112
133
  };
113
- seats.set(ctx, seat);
114
- return seat;
115
134
  }
116
135
  //# sourceMappingURL=settings-seat.js.map
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@lmzhen/dsh-evolution-client-kit",
3
3
  "description": "Shared browser seams and lifecycle for the evolution family sidebar panels (community build)",
4
- "version": "0.33.0",
4
+ "version": "0.35.0",
5
5
  "private": false,
6
6
  "publishConfig": {
7
7
  "access": "public"