@lmzhen/dsh-evolution-client-kit 0.36.2 → 0.37.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.js CHANGED
@@ -162,6 +162,22 @@ async function describe(namespace) {
162
162
  return EMPTY;
163
163
  }
164
164
  }
165
+ /**
166
+ * Classify one refused write from the exact route's response: the route answers 409 for a revision
167
+ * CAS loss and 400 with an "invalid config" error for a schema refusal, so the card can name the
168
+ * right cause instead of calling every refusal a concurrent edit.
169
+ * @param response - the non-ok response.
170
+ * @returns the refusal class; anything the route did not name stays transport.
171
+ */
172
+ async function refusalKind(response) {
173
+ if (response.status === 409) return "conflict";
174
+ try {
175
+ const body = await response.json();
176
+ return typeof body.error === "string" && body.error.startsWith("invalid config") ? "validation" : "transport";
177
+ } catch {
178
+ return "transport";
179
+ }
180
+ }
165
181
  async function write(namespace, ops, expectedRevision) {
166
182
  try {
167
183
  const response = await fetch(SETTINGS_MUTATE, {
@@ -176,14 +192,20 @@ async function write(namespace, ops, expectedRevision) {
176
192
  ...expectedRevision === void 0 ? {} : { expectedRevision }
177
193
  })
178
194
  });
179
- if (!response.ok) return { ok: false };
195
+ if (!response.ok) return {
196
+ ok: false,
197
+ kind: await refusalKind(response)
198
+ };
180
199
  const body = await response.json();
181
200
  return {
182
201
  ok: body.ok === true,
183
202
  snapshot: snapshotFrom(body.data, namespace)
184
203
  };
185
204
  } catch {
186
- return { ok: false };
205
+ return {
206
+ ok: false,
207
+ kind: "transport"
208
+ };
187
209
  }
188
210
  }
189
211
  function createForm(namespace, ctx) {
@@ -247,6 +269,15 @@ function createForm(namespace, ctx) {
247
269
  op: "unset",
248
270
  path: [field]
249
271
  }]),
272
+ save: async (ops, expectedRevision) => {
273
+ const outcome = await write(namespace, ops, expectedRevision ?? snapshot.revision);
274
+ if (outcome.snapshot !== void 0) absorb(outcome.snapshot);
275
+ else await refresh();
276
+ return outcome.ok ? { written: true } : {
277
+ written: false,
278
+ kind: outcome.kind ?? "transport"
279
+ };
280
+ },
250
281
  mutate: async (ops, expectedRevision) => {
251
282
  const outcome = await write(namespace, ops, expectedRevision ?? snapshot.revision);
252
283
  if (outcome.snapshot !== void 0) absorb(outcome.snapshot);
@@ -407,6 +438,20 @@ var AsyncResource = class {
407
438
  };
408
439
  //#endregion
409
440
  //#region lib/types/format.js
441
+ /** Parse an ISO string, epoch ms, or null into a valid Date; null when absent/invalid. */
442
+ function toLocalDate(value) {
443
+ if (value === null || value === void 0) return null;
444
+ const ms = typeof value === "number" ? value : Date.parse(value);
445
+ if (!Number.isFinite(ms)) return null;
446
+ const date = new Date(ms);
447
+ return Number.isNaN(date.getTime()) ? null : date;
448
+ }
449
+ const pad = (part) => String(part).padStart(2, "0");
450
+ /** The local clock part, HH:MM[:SS]. */
451
+ function clockOf(date, options) {
452
+ const head = pad(date.getHours()) + ":" + pad(date.getMinutes());
453
+ return options.seconds === false ? head : head + ":" + pad(date.getSeconds());
454
+ }
410
455
  /**
411
456
  * Format an ISO string, epoch milliseconds, or null as local wall time.
412
457
  * Invalid values return null; callers decide how to say "unknown".
@@ -415,14 +460,30 @@ var AsyncResource = class {
415
460
  * @returns the formatted local time, or null when the value is absent/invalid.
416
461
  */
417
462
  function formatLocalDateTime(value, options = {}) {
418
- if (value === null || value === void 0) return null;
419
- const ms = typeof value === "number" ? value : Date.parse(value);
420
- if (!Number.isFinite(ms)) return null;
421
- const date = new Date(ms);
422
- if (Number.isNaN(date.getTime())) return null;
423
- const pad = (part) => String(part).padStart(2, "0");
424
- const head = String(date.getFullYear()) + "-" + pad(date.getMonth() + 1) + "-" + pad(date.getDate()) + " " + pad(date.getHours()) + ":" + pad(date.getMinutes());
425
- return options.seconds === false ? head : head + ":" + pad(date.getSeconds());
463
+ const date = toLocalDate(value);
464
+ if (date === null) return null;
465
+ return String(date.getFullYear()) + "-" + pad(date.getMonth() + 1) + "-" + pad(date.getDate()) + " " + clockOf(date, options);
466
+ }
467
+ /**
468
+ * Format only the local clock part, HH:MM[:SS]; null when the value is absent/invalid.
469
+ * @param value - ISO string, epoch ms, or null.
470
+ * @param options - seconds on/off; defaults to on.
471
+ * @returns the local clock text, or null.
472
+ */
473
+ function formatLocalClock(value, options = {}) {
474
+ const date = toLocalDate(value);
475
+ return date === null ? null : clockOf(date, options);
476
+ }
477
+ /**
478
+ * True when the value falls on the same local calendar day as now.
479
+ * @param value - ISO string, epoch ms, or null.
480
+ * @param now - the reference instant; defaults to the current time.
481
+ * @returns whether both are the same local day; false for invalid input.
482
+ */
483
+ function isSameLocalDay(value, now = /* @__PURE__ */ new Date()) {
484
+ const date = toLocalDate(value);
485
+ if (date === null) return false;
486
+ return date.getFullYear() === now.getFullYear() && date.getMonth() === now.getMonth() && date.getDate() === now.getDate();
426
487
  }
427
488
  //#endregion
428
489
  //#region lib/types/notice.js
@@ -533,11 +594,12 @@ function actionButton(action, role) {
533
594
  }, action.label);
534
595
  }
535
596
  /** Render a quiet empty state; loading/failure remain the caller's separate states. */
536
- function EmptyState({ title, description, tone = "neutral", primary, secondary, className }) {
597
+ function EmptyState({ title, description, tone = "neutral", primary, secondary, className, variant = "default" }) {
537
598
  const actions = primary === void 0 && secondary === void 0 ? null : createElement("div", { "data-role": "empty-actions" }, primary === void 0 ? null : actionButton(primary, "primary"), secondary === void 0 ? null : actionButton(secondary, "secondary"));
538
599
  return createElement("section", {
539
600
  "data-role": "empty-state",
540
601
  "data-tone": tone,
602
+ ...variant === "default" ? {} : { "data-variant": variant },
541
603
  ...className === void 0 ? {} : { className }
542
604
  }, createElement("h2", { "data-role": "empty-title" }, title), description === void 0 || description === "" ? null : createElement("p", { "data-role": "empty-description" }, description), actions);
543
605
  }
@@ -769,4 +831,4 @@ function createSettingsGatewayCache(binder, api) {
769
831
  };
770
832
  }
771
833
  //#endregion
772
- export { ActionMenu, AsyncResource, Block, CommandCopyButton, DecisionFrame, DisclosureGroup, EmptyState, FALLBACKS, FailureBlock, FilterChip, PAGE_SURFACE_CLASS, PAGE_SURFACE_CSS, PLATFORM_MENU, ROUTES, StateNotice, StatusChip, TOKENS, TOKEN_CSS, TaskBanner, TimeText, copyAction, createSettingsGatewayCache, createSettingsSeat, failureText, formatLocalDateTime, loadStateOf, menuPrimitivesFrom, panelWorkspaceId, registerSidebarPanel, registerWorkbenchView, renderPlatformMenu, saveSettings, tokenVars };
834
+ export { ActionMenu, AsyncResource, Block, CommandCopyButton, DecisionFrame, DisclosureGroup, EmptyState, FALLBACKS, FailureBlock, FilterChip, PAGE_SURFACE_CLASS, PAGE_SURFACE_CSS, PLATFORM_MENU, ROUTES, StateNotice, StatusChip, TOKENS, TOKEN_CSS, TaskBanner, TimeText, copyAction, createSettingsGatewayCache, createSettingsSeat, failureText, formatLocalClock, formatLocalDateTime, isSameLocalDay, loadStateOf, menuPrimitivesFrom, panelWorkspaceId, registerSidebarPanel, registerWorkbenchView, renderPlatformMenu, saveSettings, tokenVars };
@@ -11,4 +11,18 @@ export interface LocalDateTimeOptions {
11
11
  * @returns the formatted local time, or null when the value is absent/invalid.
12
12
  */
13
13
  export declare function formatLocalDateTime(value: string | number | null | undefined, options?: LocalDateTimeOptions): string | null;
14
+ /**
15
+ * Format only the local clock part, HH:MM[:SS]; null when the value is absent/invalid.
16
+ * @param value - ISO string, epoch ms, or null.
17
+ * @param options - seconds on/off; defaults to on.
18
+ * @returns the local clock text, or null.
19
+ */
20
+ export declare function formatLocalClock(value: string | number | null | undefined, options?: LocalDateTimeOptions): string | null;
21
+ /**
22
+ * True when the value falls on the same local calendar day as now.
23
+ * @param value - ISO string, epoch ms, or null.
24
+ * @param now - the reference instant; defaults to the current time.
25
+ * @returns whether both are the same local day; false for invalid input.
26
+ */
27
+ export declare function isSameLocalDay(value: string | number | null | undefined, now?: Date): boolean;
14
28
  //# sourceMappingURL=format.d.ts.map
@@ -1,3 +1,19 @@
1
+ /** Parse an ISO string, epoch ms, or null into a valid Date; null when absent/invalid. */
2
+ function toLocalDate(value) {
3
+ if (value === null || value === undefined)
4
+ return null;
5
+ const ms = typeof value === 'number' ? value : Date.parse(value);
6
+ if (!Number.isFinite(ms))
7
+ return null;
8
+ const date = new Date(ms);
9
+ return Number.isNaN(date.getTime()) ? null : date;
10
+ }
11
+ const pad = (part) => String(part).padStart(2, '0');
12
+ /** The local clock part, HH:MM[:SS]. */
13
+ function clockOf(date, options) {
14
+ const head = pad(date.getHours()) + ':' + pad(date.getMinutes());
15
+ return options.seconds === false ? head : head + ':' + pad(date.getSeconds());
16
+ }
1
17
  /**
2
18
  * Format an ISO string, epoch milliseconds, or null as local wall time.
3
19
  * Invalid values return null; callers decide how to say "unknown".
@@ -6,17 +22,31 @@
6
22
  * @returns the formatted local time, or null when the value is absent/invalid.
7
23
  */
8
24
  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))
25
+ const date = toLocalDate(value);
26
+ if (date === null)
13
27
  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());
28
+ return String(date.getFullYear()) + '-' + pad(date.getMonth() + 1) + '-' + pad(date.getDate()) + ' ' + clockOf(date, options);
29
+ }
30
+ /**
31
+ * Format only the local clock part, HH:MM[:SS]; null when the value is absent/invalid.
32
+ * @param value - ISO string, epoch ms, or null.
33
+ * @param options - seconds on/off; defaults to on.
34
+ * @returns the local clock text, or null.
35
+ */
36
+ export function formatLocalClock(value, options = {}) {
37
+ const date = toLocalDate(value);
38
+ return date === null ? null : clockOf(date, options);
39
+ }
40
+ /**
41
+ * True when the value falls on the same local calendar day as now.
42
+ * @param value - ISO string, epoch ms, or null.
43
+ * @param now - the reference instant; defaults to the current time.
44
+ * @returns whether both are the same local day; false for invalid input.
45
+ */
46
+ export function isSameLocalDay(value, now = new Date()) {
47
+ const date = toLocalDate(value);
48
+ if (date === null)
49
+ return false;
50
+ return date.getFullYear() === now.getFullYear() && date.getMonth() === now.getMonth() && date.getDate() === now.getDate();
21
51
  }
22
52
  //# sourceMappingURL=format.js.map
@@ -1,12 +1,12 @@
1
1
  /** Shared browser seams and panel lifecycle for the evolution family. */
2
- export type { ClientSeam, ConfigFormLike, ConfigFormSnapshotLike, ConfigFormsSeat, ConfigPathOpLike, LocaleSeat, PanelBodyOptions, PanelRowOptions, SettingsFace, SlotsSeat } from './seam.ts';
2
+ export type { ClientSeam, ConfigFormLike, ConfigFormSnapshotLike, ConfigFormsSeat, ConfigPathOpLike, ConfigWriteKind, ConfigWriteOutcome, LocaleSeat, PanelBodyOptions, PanelRowOptions, SettingsFace, SlotsSeat } from './seam.ts';
3
3
  export { registerSidebarPanel, type SidebarPanelSpec, type Translate } from './panel.ts';
4
4
  export { registerWorkbenchView } from './workbench-view.ts';
5
5
  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';
9
+ export { formatLocalClock, formatLocalDateTime, isSameLocalDay, type LocalDateTimeOptions } from './format.ts';
10
10
  export { StateNotice, type StateNoticeProps, type StateNoticeTone } from './notice.ts';
11
11
  export { DecisionFrame, type DecisionFrameProps } from './presentation/decision-frame.ts';
12
12
  export { TaskBanner, type TaskBannerProps } from './presentation/task-banner.ts';
@@ -3,7 +3,7 @@ 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";
6
+ export { formatLocalClock, formatLocalDateTime, isSameLocalDay } from "./format.js";
7
7
  export { StateNotice } from "./notice.js";
8
8
  export { DecisionFrame } from "./presentation/decision-frame.js";
9
9
  export { TaskBanner } from "./presentation/task-banner.js";
@@ -1,6 +1,8 @@
1
1
  /** A compact completed/empty state with at most one primary next step. */
2
2
  import { type ReactNode } from 'react';
3
3
  import type { PresentationAction, PresentationTone } from './types.ts';
4
+ /** Density/layout hints for the one shared empty state; page CSS owns the actual spacing. */
5
+ export type EmptyStateVariant = 'default' | 'compact' | 'centered';
4
6
  /** Props for the shared empty state. */
5
7
  export interface EmptyStateProps {
6
8
  readonly title: string;
@@ -9,7 +11,9 @@ export interface EmptyStateProps {
9
11
  readonly primary?: PresentationAction | undefined;
10
12
  readonly secondary?: PresentationAction | undefined;
11
13
  readonly className?: string | undefined;
14
+ /** Omit for legacy layout; compact/centered are opt-in markers for page-level CSS. */
15
+ readonly variant?: EmptyStateVariant | undefined;
12
16
  }
13
17
  /** Render a quiet empty state; loading/failure remain the caller's separate states. */
14
- export declare function EmptyState({ title, description, tone, primary, secondary, className }: EmptyStateProps): ReactNode;
18
+ export declare function EmptyState({ title, description, tone, primary, secondary, className, variant }: EmptyStateProps): ReactNode;
15
19
  //# sourceMappingURL=empty-state.d.ts.map
@@ -14,11 +14,12 @@ function actionButton(action, role) {
14
14
  }, action.label);
15
15
  }
16
16
  /** Render a quiet empty state; loading/failure remain the caller's separate states. */
17
- export function EmptyState({ title, description, tone = 'neutral', primary, secondary, className }) {
17
+ export function EmptyState({ title, description, tone = 'neutral', primary, secondary, className, variant = 'default' }) {
18
18
  const actions = primary === undefined && secondary === undefined ? null : createElement('div', { 'data-role': 'empty-actions' }, primary === undefined ? null : actionButton(primary, 'primary'), secondary === undefined ? null : actionButton(secondary, 'secondary'));
19
19
  return createElement('section', {
20
20
  'data-role': 'empty-state',
21
21
  'data-tone': tone,
22
+ ...(variant === 'default' ? {} : { 'data-variant': variant }),
22
23
  ...(className === undefined ? {} : { className }),
23
24
  }, createElement('h2', { 'data-role': 'empty-title' }, title), description === undefined || description === '' ? null : createElement('p', { 'data-role': 'empty-description' }, description), actions);
24
25
  }
@@ -57,6 +57,14 @@ export interface ConfigFormSnapshotLike<T = Record<string, unknown>> {
57
57
  writable: boolean;
58
58
  revision: number | undefined;
59
59
  }
60
+ /** Why a form write was refused, as far as the host reported it. */
61
+ export type ConfigWriteKind = 'conflict' | 'validation' | 'transport';
62
+ /** One atomic write and, when it was refused, the class the host reported. */
63
+ export interface ConfigWriteOutcome {
64
+ readonly written: boolean;
65
+ /** Absent on success; when a write was refused, why (revision CAS, invalid value, transport). */
66
+ readonly kind?: ConfigWriteKind;
67
+ }
60
68
  export interface ConfigFormLike<T = Record<string, unknown>> {
61
69
  getSnapshot(): ConfigFormSnapshotLike<T>;
62
70
  subscribe(listener: () => void): () => void;
@@ -64,6 +72,13 @@ export interface ConfigFormLike<T = Record<string, unknown>> {
64
72
  unset(field: string): Promise<boolean>;
65
73
  /** Atomic multi-field save; `expectedRevision` is the read the caller is replacing. */
66
74
  mutate(ops: readonly ConfigPathOpLike[], expectedRevision?: number): Promise<boolean>;
75
+ /**
76
+ * The same atomic save with the host's refusal class. `mutate` answers only the boolean, which
77
+ * cannot tell "another page changed the settings" from "this value is invalid"; a card that says
78
+ * the wrong cause is worse than saying nothing. Optional so a test double (and the previous
79
+ * two-method face) still works.
80
+ */
81
+ save?(ops: readonly ConfigPathOpLike[], expectedRevision?: number): Promise<ConfigWriteOutcome>;
67
82
  /** Re-read the row (used by the card's readback verdict). */
68
83
  refresh?(): Promise<void>;
69
84
  /** Stop the form's remote subscription; owned by the seat. */
@@ -27,6 +27,24 @@ async function describe(namespace) {
27
27
  return EMPTY;
28
28
  }
29
29
  }
30
+ /**
31
+ * Classify one refused write from the exact route's response: the route answers 409 for a revision
32
+ * CAS loss and 400 with an "invalid config" error for a schema refusal, so the card can name the
33
+ * right cause instead of calling every refusal a concurrent edit.
34
+ * @param response - the non-ok response.
35
+ * @returns the refusal class; anything the route did not name stays transport.
36
+ */
37
+ async function refusalKind(response) {
38
+ if (response.status === 409)
39
+ return 'conflict';
40
+ try {
41
+ const body = await response.json();
42
+ return typeof body.error === 'string' && body.error.startsWith('invalid config') ? 'validation' : 'transport';
43
+ }
44
+ catch {
45
+ return 'transport';
46
+ }
47
+ }
30
48
  async function write(namespace, ops, expectedRevision) {
31
49
  try {
32
50
  const response = await fetch(SETTINGS_MUTATE, {
@@ -35,12 +53,12 @@ async function write(namespace, ops, expectedRevision) {
35
53
  body: JSON.stringify({ ns: namespace, ops, ...(expectedRevision === undefined ? {} : { expectedRevision }) }),
36
54
  });
37
55
  if (!response.ok)
38
- return { ok: false };
56
+ return { ok: false, kind: await refusalKind(response) };
39
57
  const body = await response.json();
40
58
  return { ok: body.ok === true, snapshot: snapshotFrom(body.data, namespace) };
41
59
  }
42
60
  catch {
43
- return { ok: false };
61
+ return { ok: false, kind: 'transport' };
44
62
  }
45
63
  }
46
64
  function createForm(namespace, ctx) {
@@ -95,6 +113,15 @@ function createForm(namespace, ctx) {
95
113
  },
96
114
  set: async (field, value) => (await form.mutate([{ op: 'set', path: [field], value }])),
97
115
  unset: async (field) => (await form.mutate([{ op: 'unset', path: [field] }])),
116
+ save: async (ops, expectedRevision) => {
117
+ const revision = expectedRevision ?? snapshot.revision;
118
+ const outcome = await write(namespace, ops, revision);
119
+ if (outcome.snapshot !== undefined)
120
+ absorb(outcome.snapshot);
121
+ else
122
+ await refresh();
123
+ return outcome.ok ? { written: true } : { written: false, kind: outcome.kind ?? 'transport' };
124
+ },
98
125
  mutate: async (ops, expectedRevision) => {
99
126
  const revision = expectedRevision ?? snapshot.revision;
100
127
  const outcome = await write(namespace, ops, revision);
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.36.2",
4
+ "version": "0.37.1",
5
5
  "private": false,
6
6
  "publishConfig": {
7
7
  "access": "public"