Skip to content

Commit e893cde

Browse files
committed
feat(a11y): 面板无障碍批次一——aria-live 播报网络、语义标题、焦点圈与图摘要 (#178)
- 模块级 announce():单例 polite live region 挂 body,九处瞬时反馈 (保存/裁决/刷新/复制)统一经此播报,读屏不再依赖纯视觉 span - StatusCard 标题 div→h3(CSS margin 归零),读屏可按标题导航 - 记忆库弹层焦点管理:Tab 圈在面板内、打开焦点入面板、关闭还原 opener (两个入口按钮均标记 data-mneme-overlay-opener) - 冲突队列:busy 防重、保留 A/B 按钮带条目标题 aria-label、 裁决/刷新结果播报 - ego 关系图 role=img + 中英计数摘要键 memory.graph.summary - 新增 5 条回归测试(client.test.js 31 例全绿)
1 parent f2f658c commit e893cde

2 files changed

Lines changed: 162 additions & 23 deletions

File tree

‎dsh-mneme/lib/client.js‎

Lines changed: 117 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,25 @@ window.__ModuleLoader__.load({
77
let react = require("react");
88
let primitives = require("@deepseek-ai/dsh-client-ui-primitives");
99
let { useState, useEffect, useCallback, useRef } = react;
10+
11+
// #178 无障碍批次一:aria-live 网络。模块级单例 polite live region +
12+
// announce():面板所有瞬时反馈(保存成功/失败、队列刷新、裁决完成、
13+
// 复制成功)经此播报,读屏用户不再依赖纯视觉 span。单例挂 <body>,
14+
// 与面板组件生命周期解耦;文本先清空下一帧再写入,让连续两次相同
15+
// 文案也能各播报一次。
16+
let liveRegion = null;
17+
function announce(text) {
18+
if (!text || typeof document === "undefined") return;
19+
if (!liveRegion || !liveRegion.isConnected) {
20+
liveRegion = document.createElement("div");
21+
liveRegion.setAttribute("role", "status");
22+
liveRegion.setAttribute("aria-live", "polite");
23+
liveRegion.style.cssText = "position:absolute;width:1px;height:1px;margin:-1px;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap";
24+
document.body.appendChild(liveRegion);
25+
}
26+
liveRegion.textContent = "";
27+
window.requestAnimationFrame(() => { if (liveRegion) liveRegion.textContent = text; });
28+
}
1029
const IconArchiveOutline20 = primitives.IconArchiveOutline20;
1130

1231
// Portal target for the hero fallback surface. The host whitelists
@@ -245,6 +264,7 @@ window.__ModuleLoader__.load({
245264
"memory.graph.sourceMemory": "查看来源记忆",
246265
"memory.graph.hint": "拖拽节点调整布局 · 空白处拖动平移 · 滚轮缩放",
247266
"memory.graph.resetView": "重置视图",
267+
"memory.graph.summary": "实体关系图:{entity} 及其 {nodes} 个节点、{edges} 条关系",
248268
"memory.graph.viewInGraph": "在实体视图中打开",
249269
"memory.graph.loading": "加载中…",
250270
"memory.graph.distance": "距中心 {n} 跳",
@@ -456,7 +476,10 @@ window.__ModuleLoader__.load({
456476
"memory.status.conflictQueue.markReviewed": "仅标记已处理",
457477
"memory.status.conflictQueue.applyHint": "确认后:保留方正文追加已否决注记,另一方归档。",
458478
"memory.status.conflictQueue.missing": "(该记忆已不存在)",
479+
"memory.status.conflictQueue.goto": "查看待确认冲突队列",
480+
"memory.status.conflictQueue.resolved": "已裁决:保留{name}",
459481
"memory.status.conflictQueue.refresh": "刷新队列",
482+
"memory.status.conflictQueue.refreshed": "冲突队列已刷新",
460483
"memory.status.workbench": "工作动态",
461484
"memory.status.dreamConsolidate": "记忆巩固",
462485
"memory.status.summarize": "总结提炼",
@@ -608,6 +631,7 @@ window.__ModuleLoader__.load({
608631
"memory.graph.sourceMemory": "View source memory",
609632
"memory.graph.hint": "Drag nodes to rearrange · drag the background to pan · scroll to zoom",
610633
"memory.graph.resetView": "Reset view",
634+
"memory.graph.summary": "Entity graph: {entity} with {nodes} nodes and {edges} edges",
611635
"memory.graph.viewInGraph": "Open in entity explorer",
612636
"memory.graph.loading": "Loading…",
613637
"memory.graph.distance": "{n} hop(s) from root",
@@ -819,7 +843,10 @@ window.__ModuleLoader__.load({
819843
"memory.status.conflictQueue.markReviewed": "Mark reviewed only",
820844
"memory.status.conflictQueue.applyHint": "On confirm: a veto note is appended to the kept side and the other side is archived.",
821845
"memory.status.conflictQueue.missing": "(memory no longer exists)",
846+
"memory.status.conflictQueue.goto": "View pending conflict queue",
847+
"memory.status.conflictQueue.resolved": "Resolved: kept {name}",
822848
"memory.status.conflictQueue.refresh": "Refresh queue",
849+
"memory.status.conflictQueue.refreshed": "Conflict queue refreshed",
823850
"memory.status.workbench": "Activity",
824851
"memory.status.dreamConsolidate": "Consolidation",
825852
"memory.status.summarize": "Summarization",
@@ -972,7 +999,7 @@ window.__ModuleLoader__.load({
972999
".mneme-xrow{display:flex;align-items:center;gap:8px;flex-wrap:wrap}",
9731000
".mneme-xsearch{width:100%}",
9741001
".mneme-xselect{flex:1;min-width:0}",
975-
".mneme-xcolhead{flex:none;font-size:12px;font-weight:500;color:var(--dsw-alias-label-tertiary);padding:2px 8px 8px}",
1002+
".mneme-xcolhead{flex:none;font-size:12px;font-weight:500;margin:0;color:var(--dsw-alias-label-tertiary);padding:2px 8px 8px}",
9761003
".mneme-xtype{display:flex;justify-content:flex-start;align-items:center;gap:8px;width:100%;padding:5px 8px;border:none;border-radius:8px;background:none;color:var(--dsw-alias-label-secondary);cursor:pointer;font-family:inherit;font-size:13px;line-height:18px;text-align:left}",
9771004
".mneme-xtype:hover{background:var(--dsw-alias-interactive-bg-hover)}",
9781005
".mneme-xtype.mneme-active{background:var(--dsw-alias-interactive-bg-active);color:var(--dsw-alias-label-primary);font-weight:500}",
@@ -1727,6 +1754,11 @@ window.__ModuleLoader__.load({
17271754
className: "mneme-graphsvg",
17281755
viewBox: `0 0 ${VIEW_W} ${VIEW_H}`,
17291756
style: { height: 320 },
1757+
role: "img",
1758+
"aria-label": t("memory.graph.summary")
1759+
.replace("{entity}", (data.root && (data.root.label || data.root.name)) || "")
1760+
.replace("{nodes}", String(data.nodes.length))
1761+
.replace("{edges}", String(data.edges.length)),
17301762
onMouseDown: onSurfaceMouseDown
17311763
},
17321764
h("g", {
@@ -1859,6 +1891,7 @@ window.__ModuleLoader__.load({
18591891
});
18601892
if (!res.ok) throw new Error("HTTP " + res.status);
18611893
setState(await res.json());
1894+
announce(t("memory.features.restartHint"));
18621895
setSavedTick(true);
18631896
setTimeout(() => setSavedTick(false), 1800);
18641897
} catch {
@@ -2245,6 +2278,7 @@ window.__ModuleLoader__.load({
22452278
body: JSON.stringify({ profile })
22462279
});
22472280
setSaved(true);
2281+
announce(t("memory.settings.profileSaved"));
22482282
setTimeout(() => setSaved(false), 1500);
22492283
} catch { /* ignore */ }
22502284
}
@@ -2303,6 +2337,7 @@ window.__ModuleLoader__.load({
23032337
body: JSON.stringify(vector)
23042338
});
23052339
setVectorSaved(true);
2340+
announce(t("memory.settings.vectorSaved"));
23062341
setTimeout(() => setVectorSaved(false), 1500);
23072342
} catch { /* ignore */ }
23082343
}
@@ -2324,6 +2359,7 @@ window.__ModuleLoader__.load({
23242359
if (apiToken.trim()) window.localStorage.setItem("dsh-mneme-api-token", apiToken.trim());
23252360
else window.localStorage.removeItem("dsh-mneme-api-token");
23262361
setApiTokenSaved(true);
2362+
announce(t("memory.settings.apiTokenSaved"));
23272363
setTimeout(() => setApiTokenSaved(false), 1500);
23282364
} catch { /* ignore */ }
23292365
}
@@ -2344,6 +2380,7 @@ window.__ModuleLoader__.load({
23442380
});
23452381
if (!res.ok) throw new Error("HTTP " + res.status);
23462382
setModeSaved(true);
2383+
announce(t("memory.settings.mode.savedHint"));
23472384
setTimeout(() => setModeSaved(false), 2500);
23482385
} catch (err) {
23492386
setMode(prev);
@@ -2376,6 +2413,7 @@ window.__ModuleLoader__.load({
23762413
setExtapiHost(next.host);
23772414
setExtapiPort(next.port ? String(next.port) : "");
23782415
setExtapiSaved(true);
2416+
announce(t("memory.settings.extapi.savedHint"));
23792417
setTimeout(() => setExtapiSaved(false), 2500);
23802418
} catch (err) {
23812419
setExtapiError((err && err.message) || "failed");
@@ -2402,7 +2440,7 @@ window.__ModuleLoader__.load({
24022440
function copyExtapiToken() {
24032441
const token = extapi ? extapi.token || "" : "";
24042442
navigator.clipboard?.writeText(token).then(
2405-
() => { setExtapiCopied(true); setTimeout(() => setExtapiCopied(false), 1500); },
2443+
() => { setExtapiCopied(true); announce(t("memory.settings.extapi.copied")); setTimeout(() => setExtapiCopied(false), 1500); },
24062444
() => {}
24072445
);
24082446
}
@@ -2670,11 +2708,35 @@ window.__ModuleLoader__.load({
26702708
// 上下文裁不住它;运行时拒绝 react-dom 时就地渲染(position:fixed 仍然成立)。
26712709
function MemoryOverlay({ t }) {
26722710
const [open, setOpen] = useOverlayOpen();
2711+
// #178:弹层焦点管理——打开时把焦点移入面板(关闭按钮为入口),
2712+
// Tab 循环圈在面板内(Tab 从最后一个元素出去回到关闭按钮),
2713+
// Esc/关闭时把焦点还给触发元素(侧边栏入口)。
2714+
const panelRef = useRef(null);
2715+
const closeBtnRef = useRef(null);
26732716
useEffect(() => {
26742717
if (!open) return undefined;
2675-
const onKey = (e) => { if (e.key === "Escape") setOpen(false); };
2718+
const onKey = (e) => {
2719+
if (e.key === "Escape") { setOpen(false); return; }
2720+
if (e.key !== "Tab" || !panelRef.current) return;
2721+
const focusables = panelRef.current.querySelectorAll('button, input, select, textarea, a[href], [tabindex]:not([tabindex="-1"])');
2722+
if (focusables.length === 0) return;
2723+
const first = focusables[0];
2724+
const last = focusables[focusables.length - 1];
2725+
if (e.shiftKey && (document.activeElement === first || !panelRef.current.contains(document.activeElement))) {
2726+
e.preventDefault();
2727+
last.focus();
2728+
} else if (!e.shiftKey && document.activeElement === last) {
2729+
e.preventDefault();
2730+
first.focus();
2731+
}
2732+
};
26762733
window.addEventListener("keydown", onKey);
2677-
return () => window.removeEventListener("keydown", onKey);
2734+
if (closeBtnRef.current) closeBtnRef.current.focus();
2735+
return () => {
2736+
window.removeEventListener("keydown", onKey);
2737+
const opener = document.querySelector('[data-mneme-overlay-opener]');
2738+
if (opener) opener.focus();
2739+
};
26782740
}, [open]);
26792741
if (!open) return null;
26802742
// 背板与 sheet 是兄弟节点而不是嵌套:点击背板自身才关闭,sheet 内部
@@ -2685,7 +2747,7 @@ window.__ModuleLoader__.load({
26852747
onClick: () => setOpen(false),
26862748
"aria-hidden": "true"
26872749
}),
2688-
h("div", { className: "mneme-overlay", role: "region", "aria-label": t("memory.view.label") },
2750+
h("div", { className: "mneme-overlay", role: "region", "aria-label": t("memory.view.label"), ref: panelRef },
26892751
h("div", { className: "mneme-overlaybar" },
26902752
h("span", { className: "mneme-overlaytitle" },
26912753
h(IconArchiveOutline20, { size: 15 }),
@@ -2694,6 +2756,7 @@ window.__ModuleLoader__.load({
26942756
h("button", {
26952757
type: "button",
26962758
className: "mneme-footbtn",
2759+
ref: closeBtnRef,
26972760
"aria-label": t("memory.overlay.close"),
26982761
title: t("memory.overlay.close"),
26992762
onClick: () => setOpen(false)
@@ -2714,7 +2777,7 @@ window.__ModuleLoader__.load({
27142777
// never blanks or blocks the others. ---
27152778
function StatusCard({ t, title, loading, error, num, cap }) {
27162779
return h("div", { className: "mneme-statuscard" },
2717-
h("div", { className: "mneme-xcolhead" }, title),
2780+
h("h3", { className: "mneme-xcolhead" }, title),
27182781
loading
27192782
? h("div", { className: "mneme-statusnum" }, "…")
27202783
: error
@@ -2995,7 +3058,7 @@ window.__ModuleLoader__.load({
29953058

29963059
// 巩固状态卡(×2):最近一次 autoDream 运行 + 待确认冲突计数。数据来自
29973060
// /dream-status,一次取回两张卡共用;失败只影响这两张卡自身。
2998-
function DreamStatusCards({ t }) {
3061+
function DreamStatusCards({ t, onGotoQueue }) {
29993062
const [state, setState] = useState({ loading: true, error: false, lastRun: null, pending: 0 });
30003063
useEffect(() => {
30013064
let cancelled = false;
@@ -3018,16 +3081,29 @@ window.__ModuleLoader__.load({
30183081
const cap = run
30193082
? `${run.status || "—"}${run.model ? ` · ${run.model}` : ""}`
30203083
: t("memory.settings.mode.offList");
3084+
// #178:pending>0 时冲突卡可激活(role=button + 可聚焦 + 回车/空格),
3085+
// 激活直达队列——StatusPanel 把 onGotoQueue 传进来(一步 prop,无线程)。
3086+
const pending = state.pending > 0;
3087+
const gotoQueue = () => { if (pending && onGotoQueue) onGotoQueue(); };
30213088
return h(react.Fragment, null,
30223089
h(StatusCard, { t, title: t("memory.status.dream"), loading: state.loading, error: state.error, num, cap }),
3023-
h(StatusCard, {
3024-
t,
3025-
title: t("memory.status.conflicts"),
3026-
loading: state.loading,
3027-
error: state.error,
3028-
num: state.pending.toLocaleString(),
3029-
cap: t("memory.status.conflictsHint")
3030-
})
3090+
h("div", {
3091+
role: pending ? "button" : undefined,
3092+
tabIndex: pending ? 0 : undefined,
3093+
"aria-label": pending ? t("memory.status.conflictQueue.goto") : undefined,
3094+
style: pending ? { cursor: "pointer" } : undefined,
3095+
onClick: pending ? gotoQueue : undefined,
3096+
onKeyDown: pending ? (e) => { if (e.key === "Enter" || e.key === " ") { e.preventDefault(); gotoQueue(); } } : undefined
3097+
},
3098+
h(StatusCard, {
3099+
t,
3100+
title: t("memory.status.conflicts"),
3101+
loading: state.loading,
3102+
error: state.error,
3103+
num: state.pending.toLocaleString(),
3104+
cap: t("memory.status.conflictsHint")
3105+
})
3106+
)
30313107
);
30323108
}
30333109

@@ -3062,20 +3138,27 @@ window.__ModuleLoader__.load({
30623138
const load = () => {
30633139
apiFetch("/api/dsh-mneme/conflicts")
30643140
.then((res) => { if (!res.ok) throw new Error("http"); return res.json(); })
3065-
.then((d) => setItems(d.items || []))
3141+
.then((d) => { setItems(d.items || []); announce(t("memory.status.conflictQueue.refreshed")); })
30663142
.catch(() => setItems([]));
30673143
};
30683144
useEffect(() => { load(); }, []);
30693145
if (!items || items.length === 0) return null;
30703146
const resolve = (id, winner) => {
3147+
if (busy) return;
30713148
setBusy(true);
3149+
// #178:裁决结果经 live region 播报(纯视觉刷新读屏不可感知)
3150+
const it = (items || []).find((x) => x.id === id) || {};
30723151
apiFetch("/api/dsh-mneme/conflicts/resolve", {
30733152
method: "POST",
30743153
headers: { "Content-Type": "application/json" },
30753154
body: JSON.stringify({ id, winner, apply: winner !== null })
30763155
})
30773156
.then((res) => { if (!res.ok) throw new Error("http"); return res.json(); })
3078-
.then(() => load())
3157+
.then(() => {
3158+
announce(t("memory.status.conflictQueue.resolved").replace("{name}",
3159+
(winner === "a" ? (it.memory_a && it.memory_a.title) : winner === "b" ? (it.memory_b && it.memory_b.title) : "") || ""));
3160+
load();
3161+
})
30793162
.catch(() => {})
30803163
.finally(() => setBusy(false));
30813164
};
@@ -3101,8 +3184,8 @@ window.__ModuleLoader__.load({
31013184
side(it.memory_b, t("memory.status.conflictQueue.sideB"))),
31023185
h("div", { className: "mneme-conflict-actions" },
31033186
h("span", { className: "mneme-conflict-hint" }, t("memory.status.conflictQueue.applyHint")),
3104-
h("button", { className: "mneme-footbtn", disabled: busy, onClick: () => resolve(it.id, "a") }, t("memory.status.conflictQueue.keepA")),
3105-
h("button", { className: "mneme-footbtn", disabled: busy, onClick: () => resolve(it.id, "b") }, t("memory.status.conflictQueue.keepB")),
3187+
h("button", { className: "mneme-footbtn", disabled: busy, "aria-label": `${t("memory.status.conflictQueue.keepA")}: ${(it.memory_a && it.memory_a.title) || ""}`, onClick: () => resolve(it.id, "a") }, t("memory.status.conflictQueue.keepA")),
3188+
h("button", { className: "mneme-footbtn", disabled: busy, "aria-label": `${t("memory.status.conflictQueue.keepB")}: ${(it.memory_b && it.memory_b.title) || ""}`, onClick: () => resolve(it.id, "b") }, t("memory.status.conflictQueue.keepB")),
31063189
h("button", { className: "mneme-footbtn", disabled: busy, onClick: () => resolve(it.id, null) }, t("memory.status.conflictQueue.markReviewed"))))
31073190
));
31083191
}
@@ -3344,18 +3427,26 @@ window.__ModuleLoader__.load({
33443427
}
33453428

33463429
function StatusPanel({ t, onBrowse }) {
3430+
// #178:冲突卡键盘直达——激活后把焦点与视口带到队列块。
3431+
const queueRef = useRef(null);
3432+
const gotoQueue = () => {
3433+
if (!queueRef.current) return;
3434+
queueRef.current.setAttribute("tabindex", "-1");
3435+
queueRef.current.focus({ preventScroll: true });
3436+
if (queueRef.current.scrollIntoView) queueRef.current.scrollIntoView({ block: "start", behavior: "smooth" });
3437+
};
33473438
return h("div", { className: "mneme-status" },
33483439
h("div", { className: "mneme-statusgrid" },
33493440
h(MemoriesStatusCard, { t }),
33503441
h(EntitiesStatusCard, { t }),
33513442
h(VectorStatusCard, { t }),
33523443
h(LlmStatusCard, { t }),
3353-
h(DreamStatusCards, { t }),
3444+
h(DreamStatusCards, { t, onGotoQueue: gotoQueue }),
33543445
h(HeatStatusCard, { t }),
33553446
h(RecallStatsCard, { t }),
33563447
h(InjectStatusCard, { t })
33573448
),
3358-
h(ConflictsQueue, { t }),
3449+
h("div", { ref: queueRef }, h(ConflictsQueue, { t })),
33593450
h(WorkbenchSection, { t, onBrowse })
33603451
);
33613452
}
@@ -3417,6 +3508,7 @@ window.__ModuleLoader__.load({
34173508
.then((d) => {
34183509
onSaved(d.memory, opts);
34193510
setEditing(false);
3511+
announce(t("memory.explorer.detail.saved"));
34203512
setSavedTick(true);
34213513
setTimeout(() => setSavedTick(false), 2000);
34223514
})
@@ -4317,7 +4409,8 @@ window.__ModuleLoader__.load({
43174409
className: wide ? "mneme-trigger" : "mneme-trigger mneme-rail",
43184410
"aria-label": t("memory.sidebar.aria"),
43194411
title: t("memory.panel.open"),
4320-
onClick: openLibrary
4412+
onClick: openLibrary,
4413+
"data-mneme-overlay-opener": "true"
43214414
},
43224415
h(IconArchiveOutline20, { size: wide ? 16 : 18 }),
43234416
wide && h("span", { className: "mneme-trigger-label" }, t("memory.panel.open"))
@@ -4404,7 +4497,8 @@ window.__ModuleLoader__.load({
44044497
className: `${nativeCls} mneme-topentry-native`.trim(),
44054498
"aria-label": t("memory.sidebar.aria"),
44064499
title: t("memory.panel.open"),
4407-
onClick: openLibrary
4500+
onClick: openLibrary,
4501+
"data-mneme-overlay-opener": "true"
44084502
},
44094503
h(IconArchiveOutline20, { size: wide ? 15 : 18 }),
44104504
wide && h("span", { className: "mneme-topentry-label" }, t("memory.panel.open"))

0 commit comments

Comments
 (0)