@lmzhen/dsh-evolution-client-kit 0.36.2 → 0.37.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
@@ -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);
@@ -533,11 +564,12 @@ function actionButton(action, role) {
533
564
  }, action.label);
534
565
  }
535
566
  /** Render a quiet empty state; loading/failure remain the caller's separate states. */
536
- function EmptyState({ title, description, tone = "neutral", primary, secondary, className }) {
567
+ function EmptyState({ title, description, tone = "neutral", primary, secondary, className, variant = "default" }) {
537
568
  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
569
  return createElement("section", {
539
570
  "data-role": "empty-state",
540
571
  "data-tone": tone,
572
+ ...variant === "default" ? {} : { "data-variant": variant },
541
573
  ...className === void 0 ? {} : { className }
542
574
  }, createElement("h2", { "data-role": "empty-title" }, title), description === void 0 || description === "" ? null : createElement("p", { "data-role": "empty-description" }, description), actions);
543
575
  }
@@ -1,5 +1,5 @@
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';
@@ -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.0",
5
5
  "private": false,
6
6
  "publishConfig": {
7
7
  "access": "public"