独家
Phrasebook <mv-phrasebook>
受限的消息编辑器，适用于自由文本有风险或代价高的场景：用户只能通过选择模板（“{thing} was {quality}”、“Check {thing} before ordering”、“{action} helps”）并从固定的分类词汇表中填写每个空位来写作，还可以用连接词（“but”、“so”）接上第二个短语。
文化出处
《恶魔之魂》，FromSoftware（导演：宫崎英高）（2009 年，游戏）。玩家可以给陌生人留言，但只能把固定的模板与固定词汇表中的词语组合起来，这让每条消息都安全、简短，并且能用任何语言阅读，其他玩家还会为留言评分。在界面中，只保留了这一机制，模板和词语由应用编写：消息由应用声明的模板和词表组成，以 id 形式存储，因此每位读者都能用自己的语言看到它，并可以评价它是否有用。
工作原理
受限的消息编辑器，适用于自由文本有风险或代价高的场景：用户只能通过选择模板（“{thing} was {quality}”、“Check {thing} before ordering”、“{action} helps”）并从固定的分类词汇表中填写每个空位来写作，还可以用连接词（“but”、“so”）接上第二个短语。每个空位、连接词和模板切换都是真正的按钮，会打开一个可搜索、分组的选词器（combobox + listbox，在显示语言和源语言中进行不区分重音的搜索，分类筛选，源语言释义）；选词后会自动前进到下一个空位，切换模板时词语会保留，实时预览会渲染句子及其进度（“1 blank left”）和可阅读的语言（虚线标签表示部分翻译）。值是结构化的，而不是文本（{ template, slots: { thing: "delivery" }, conjunction, next }），因此应用存储的是 id，并通过一个 messages 字典在任何语言环境下渲染消息，各语言有自己的词序和标点（“{first}。{conjunction}、{second}”）；没有任何键入的内容需要审核或机器翻译。支持表单关联（JSON 表单值、required、不完整的消息无效），词汇可来自 <option>/<optgroup> 子元素、JSON <script> 或属性，可取消的 mv-pick 可否决某个选择，还有配套的 <mv-phrasebook-message> 阅读视图（任意语言环境，helpful / not helpful 投票，带可取消、可等待的 mv-rate）。
| 分类 | 表单 |
|---|---|
| 类型 | Web Component（<mv-phrasebook>） |
| 状态 | 稳定版 |
| Keywords | exclusive, culture, composer, message, feedback, review, templates, vocabulary, constrained-input, moderation, safety, i18n, translation, structured-value, sentence-builder, combobox, vote, helpful, marketplace, community |
When to use
- Buyers leave seller feedback on a marketplace and reviews must stay short, safe and readable by buyers in every language
- A kids' or gaming community lets strangers message each other, and free text would need costly moderation
- Anonymous peer or retro feedback should stay constructive, with no room for insults or identifying details
- Support agents or teammates who share no language exchange quick structured replies rendered in each reader's locale
Avoid when
- People need to say something specific in their own words, such as a detailed product review → use Textarea instead
- The sentence is a filter or automation rule evaluated by the app rather than a message read by people → use Word Rules instead
- A single overall score is enough, with no message attached → use Rating instead
安装
node scripts/add.mjs phrasebook --out ./src/marvelous通过 Marvelous UI MCP 服务器使用 AI 智能体：install_components({ slugs: ["phrasebook"], target_dir: "<absolute path>/src/marvelous", framework: "react" })。
复制的文件（含依赖）：tokens/tokens.css、core/base.css、core/dismiss.js、core/dom.js、core/element.js、core/form.js、core/motion.js、core/position.js、components/phrasebook/phrasebook.js、components/phrasebook/phrasebook.css。
用法
标准标记，可在此基础上通过属性、data-* 和 CSS 变量进行定制：
<div id="pb-demo" style="width:min(100%,70rem);margin-inline:auto">
<style>
#pb-demo { display:grid; gap:1.25rem }
#pb-demo .pb-card { min-width:0; border:1px solid var(--mv-border); border-radius:var(--mv-radius-xl); background:var(--mv-surface); box-shadow:var(--mv-shadow-xs) }
#pb-demo .pb-main { display:grid; grid-template-columns:minmax(0,1.3fr) minmax(0,1fr) }
#pb-demo .pb-compose { display:grid; gap:.875rem; align-content:start; margin:0; padding:1.25rem; border-inline-end:1px solid var(--mv-border) }
#pb-demo .pb-order { display:flex; align-items:center; gap:.75rem; padding:.625rem .75rem; border:1px solid var(--mv-border); border-radius:var(--mv-radius-lg); background:var(--mv-bg-subtle) }
#pb-demo .pb-thumb { display:grid; place-items:center; flex:none; width:2.75rem; height:2.75rem; border-radius:var(--mv-radius-md); background:color-mix(in oklab, var(--mv-success) 18%, var(--mv-surface)); color:color-mix(in oklab, var(--mv-success), var(--mv-fg) 35%) }
#pb-demo .pb-thumb svg { width:1.35rem; height:1.35rem }
#pb-demo .pb-order-text { display:grid; gap:.125rem; flex:1; min-width:0 }
#pb-demo .pb-order-text strong { font-size:.875rem; letter-spacing:-.01em }
#pb-demo .pb-order-text span { color:var(--mv-fg-muted); font-size:.75rem }
#pb-demo .pb-price { font-size:.875rem; font-weight:600; font-variant-numeric:tabular-nums }
#pb-demo .pb-field { display:grid; gap:.375rem }
#pb-demo .pb-label { font-size:.875rem; font-weight:600; letter-spacing:-.01em }
#pb-demo .pb-help { margin:0; color:var(--mv-fg-muted); font-size:.8125rem; line-height:1.45 }
#pb-demo .pb-actions { display:flex; align-items:center; justify-content:space-between; gap:.75rem 1rem; flex-wrap:wrap }
#pb-demo .pb-toggle { display:inline-flex; align-items:center; gap:.5rem; color:var(--mv-fg-muted); font-size:.8125rem; cursor:pointer }
#pb-demo .pb-side { display:grid; gap:1rem; align-content:start; padding:1.25rem; background:var(--mv-bg-subtle); border-radius:0 var(--mv-radius-xl) var(--mv-radius-xl) 0 }
#pb-demo .pb-side h4, #pb-demo .pb-feed-head h4 { margin:0; font-size:.875rem; letter-spacing:-.01em }
#pb-demo .pb-side > p { margin:-.625rem 0 0; color:var(--mv-fg-muted); font-size:.8125rem; line-height:1.45 }
#pb-demo .pb-langs { display:grid; gap:.5rem }
#pb-demo .pb-lang { display:grid; grid-template-columns:4.75rem minmax(0,1fr); gap:.75rem; align-items:baseline; padding:.625rem .75rem; border:1px solid var(--mv-border); border-radius:var(--mv-radius-lg); background:var(--mv-surface) }
#pb-demo .pb-k { color:var(--mv-fg-muted); font-size:.6875rem; font-weight:600; letter-spacing:.06em; text-transform:uppercase }
#pb-demo .pb-lang mv-phrasebook-message { --mv-phrasebook-message-size:.9375rem }
#pb-demo .pb-lang:has(mv-phrasebook-message[data-empty])::after { content:"-"; color:var(--mv-fg-subtle) }
#pb-demo pre { margin:.375rem 0 0; padding:.625rem .75rem; max-height:11rem; overflow:auto; border:1px solid var(--mv-border); border-radius:var(--mv-radius-md); background:var(--mv-surface); color:var(--mv-fg-muted); font:400 .6875rem/1.55 var(--mv-font-mono); white-space:pre-wrap; word-break:break-word }
#pb-demo pre:focus-visible { outline:none; box-shadow:var(--mv-focus-ring) }
#pb-demo .pb-log { margin:0; min-height:1.1rem; color:var(--mv-fg-subtle); font:400 .75rem/1.5 var(--mv-font-mono) }
#pb-demo .pb-feed-card { padding:1.125rem 1.25rem 1.25rem }
#pb-demo .pb-feed-head { display:flex; align-items:center; justify-content:space-between; gap:.75rem 1rem; flex-wrap:wrap; margin-bottom:.875rem }
#pb-demo .pb-feed-head > div { display:flex; align-items:center; gap:.5rem }
#pb-demo .pb-feed { display:grid; gap:.5rem; margin:0; padding:0; list-style:none }
#pb-demo .pb-item { display:grid; grid-template-columns:auto minmax(0,1fr); gap:.25rem .75rem; align-items:start }
#pb-demo .pb-av { display:grid; place-items:center; width:2rem; height:2rem; margin-top:.25rem; border-radius:50%; background:var(--mv-bg-emphasis); color:var(--mv-fg); font-size:.6875rem; font-weight:600 }
#pb-demo .pb-who { display:flex; align-items:baseline; gap:.5rem; flex-wrap:wrap; font-size:.75rem }
#pb-demo .pb-who strong { font-size:.8125rem }
#pb-demo .pb-who span { color:var(--mv-fg-subtle) }
#pb-demo .pb-body { display:grid; gap:.25rem; min-width:0 }
#pb-demo .pb-item[data-new] mv-phrasebook-message { border-color:color-mix(in oklab, var(--mv-accent) 45%, var(--mv-border)) }
@media (max-width:52rem) {
#pb-demo .pb-main { grid-template-columns:minmax(0,1fr) }
#pb-demo .pb-compose { border-inline-end:0; border-bottom:1px solid var(--mv-border) }
#pb-demo .pb-side { border-radius:0 0 var(--mv-radius-xl) var(--mv-radius-xl) }
}
</style>
<!-- 1 · Marketplace seller feedback: structured, safe, readable in every language -->
<section class="pb-card pb-main" aria-label="Order feedback">
<form class="pb-compose" id="pb-form">
<div class="pb-order">
<span class="pb-thumb" aria-hidden="true"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M8 3 4 6l2 4 2-1v12h8V9l2 1 2-4-4-3c-.5 1.5-2 2.5-4 2.5S8.5 4.5 8 3Z"/></svg></span>
<span class="pb-order-text">
<strong>Linen overshirt · Sage, M</strong>
<span>Sold by Atelier Nord · Delivered Sep 18, 2026</span>
</span>
<span class="pb-price">$68.00</span>
</div>
<div class="pb-field">
<label class="pb-label" for="pb-book">Leave feedback for the seller</label>
<p class="pb-help" id="pb-help">Pick a phrase and fill the blanks. Buyers read it in their own language, and nothing needs moderation.</p>
</div>
<mv-phrasebook id="pb-book" name="feedback" required aria-describedby="pb-help"
value='{"template":"was","slots":{"thing":"delivery","quality":"on-time"},"conjunction":"but","next":{"template":"better","slots":{"thing":"packaging"}}}'>
<option data-template="was" data-group="Describe">{thing} was {quality}</option>
<option data-template="better" data-group="Describe">{thing} could be better</option>
<option data-template="check" data-group="Advise">Check {thing} before ordering</option>
<option data-template="helps" data-group="Advise">{action} helps</option>
<option data-template="great-for" data-group="Recommend">Great for {use}</option>
<option data-type="thing">aspect</option>
<option data-type="quality">quality</option>
<option data-type="action">tip</option>
<option data-type="use">occasion</option>
<optgroup label="Shipping" data-word="thing">
<option value="delivery">delivery</option>
<option value="packaging">packaging</option>
<option value="tracking">tracking</option>
</optgroup>
<optgroup label="Product" data-word="thing">
<option value="fabric" data-keywords="material linen">the fabric</option>
<option value="fit" data-keywords="size sizing">the fit</option>
<option value="color" data-keywords="colour shade">the color</option>
<option value="stitching" data-keywords="seams finish">the stitching</option>
</optgroup>
<optgroup label="Seller" data-word="thing">
<option value="communication" data-keywords="reply answer contact">communication</option>
<option value="returns" data-keywords="refund exchange">the return process</option>
<option value="value" data-keywords="price cost">value for money</option>
</optgroup>
<optgroup label="Positive" data-word="quality">
<option value="excellent">excellent</option>
<option value="flawless">flawless</option>
<option value="on-time" data-keywords="fast quick punctual">on time</option>
<option value="better-than-expected">better than expected</option>
</optgroup>
<optgroup label="Neutral" data-word="quality">
<option value="as-described">as described</option>
</optgroup>
<optgroup label="Negative" data-word="quality">
<option value="disappointing" data-keywords="bad poor">disappointing</option>
<option value="below-average" data-keywords="bad poor worse">below average</option>
</optgroup>
<optgroup label="Before you buy" data-word="action">
<option value="size-up">sizing up</option>
<option value="size-guide">reading the size guide</option>
<option value="ask-first" data-keywords="message contact question">messaging the seller first</option>
<option value="express" data-keywords="shipping fast">choosing express shipping</option>
</optgroup>
<optgroup label="After it arrives" data-word="action">
<option value="wash-cold" data-keywords="laundry care">washing it cold</option>
</optgroup>
<optgroup label="Occasions" data-word="use">
<option value="gifts">gifts</option>
<option value="everyday">everyday wear</option>
<option value="travel">travel</option>
<option value="warm-weather" data-keywords="summer heat">warm weather</option>
</optgroup>
<option data-conjunction="and">and</option>
<option data-conjunction="but">but</option>
<option data-conjunction="so">so</option>
<option data-conjunction="plus">plus</option>
<script type="application/json" data-phrasebook>
{ "messages": {
"es": {
"templates": { "was": "{thing} fue {quality}", "better": "{thing} podría mejorar", "check": "Revisa {thing} antes de pedir", "helps": "{action} ayuda", "great-for": "Ideal para {use}" },
"words": {
"delivery": "la entrega", "packaging": "el embalaje", "tracking": "el seguimiento",
"fabric": "la tela", "fit": "el ajuste", "color": "el color", "stitching": "la costura",
"communication": "la comunicación", "returns": "el proceso de devolución", "value": "la relación calidad-precio",
"excellent": "excelente", "flawless": "impecable", "on-time": "puntual", "better-than-expected": "mejor de lo esperado",
"as-described": "como se describía", "disappointing": "decepcionante", "below-average": "inferior a la media",
"size-up": "pedir una talla más", "size-guide": "leer la guía de tallas", "ask-first": "escribir antes al vendedor", "express": "elegir envío exprés", "wash-cold": "lavarla en frío",
"gifts": "regalar", "everyday": "el día a día", "travel": "viajar", "warm-weather": "el calor"
},
"conjunctions": { "and": "y", "but": "pero", "so": "así que", "plus": "además" }
},
"ja": {
"templates": { "was": "{thing}は{quality}でした", "better": "{thing}は改善の余地あり", "check": "注文前に{thing}を確認", "helps": "{action}がおすすめ", "great-for": "{use}におすすめ" },
"words": {
"delivery": "配送", "packaging": "梱包", "tracking": "追跡情報",
"fabric": "生地", "fit": "サイズ感", "color": "色", "stitching": "縫製",
"communication": "連絡", "returns": "返品対応", "value": "コスパ",
"excellent": "最高", "flawless": "完璧", "on-time": "時間どおり", "better-than-expected": "期待以上",
"as-described": "説明どおり", "disappointing": "期待外れ", "below-average": "平均以下",
"size-up": "ワンサイズ上", "size-guide": "サイズ表の確認", "ask-first": "購入前の問い合わせ", "express": "速達配送", "wash-cold": "冷水での洗濯",
"gifts": "ギフト", "everyday": "普段使い", "travel": "旅行", "warm-weather": "暑い日"
},
"conjunctions": { "and": "そして", "but": "でも", "so": "なので", "plus": "さらに" },
"format": { "join": "{first}。{conjunction}、{second}", "end": "。" }
}
} }
</script>
</mv-phrasebook>
<div class="pb-actions">
<label class="pb-toggle"><input type="checkbox" role="switch" class="mv-switch" id="pb-two" checked> Allow a second phrase</label>
<span style="display:flex;gap:.5rem">
<button type="reset" class="mv-button" data-variant="ghost">Reset</button>
<button type="submit" class="mv-button">Post feedback</button>
</span>
</div>
</form>
<aside class="pb-side" aria-labelledby="pb-side-title">
<h4 id="pb-side-title">How other buyers read it</h4>
<p>The same stored message, rendered from each reader's dictionary.</p>
<div class="pb-langs">
<div class="pb-lang"><span class="pb-k">English</span><mv-phrasebook-message id="pb-en" for="pb-book" locale="en" rating="none" data-variant="plain"></mv-phrasebook-message></div>
<div class="pb-lang"><span class="pb-k">Spanish</span><mv-phrasebook-message id="pb-es" for="pb-book" locale="es" rating="none" data-variant="plain"></mv-phrasebook-message></div>
<div class="pb-lang"><span class="pb-k">Japanese</span><mv-phrasebook-message id="pb-ja" for="pb-book" locale="ja" rating="none" data-variant="plain"></mv-phrasebook-message></div>
</div>
<div>
<span class="pb-k" id="pb-json-label">Stored value</span>
<pre id="pb-json" tabindex="0" aria-labelledby="pb-json-label"></pre>
</div>
<p class="pb-log" id="pb-log" aria-live="polite"></p>
</aside>
</section>
<!-- 2 · The seller's feed: every message rendered in the reader's language, rated helpful or not -->
<section class="pb-card pb-feed-card" aria-labelledby="pb-feed-title">
<header class="pb-feed-head">
<div>
<h4 id="pb-feed-title">Recent feedback · Atelier Nord</h4>
<span class="mv-badge" data-variant="secondary" id="pb-count">3 messages</span>
</div>
<mv-segmented id="pb-readas" label="Read feedback in" value="en">
<button value="en">English</button>
<button value="es">Spanish</button>
<button value="ja">Japanese</button>
</mv-segmented>
</header>
<ul class="pb-feed" id="pb-feed">
<li class="pb-item">
<span class="pb-av" aria-hidden="true">PS</span>
<div class="pb-body">
<span class="pb-who"><strong>Priya Shah</strong><span>Toronto · Sep 12, 2026</span></span>
<mv-phrasebook-message for="pb-book" locale="en" up="41" down="2" vote="up"
value='{"template":"helps","slots":{"action":"size-up"}}'></mv-phrasebook-message>
</div>
</li>
<li class="pb-item">
<span class="pb-av" aria-hidden="true">KM</span>
<div class="pb-body">
<span class="pb-who"><strong>Kenji Morita</strong><span>Osaka · Sep 9, 2026</span></span>
<mv-phrasebook-message for="pb-book" locale="en" up="18" down="0"
value='{"template":"was","slots":{"thing":"stitching","quality":"flawless"},"conjunction":"but","next":{"template":"check","slots":{"thing":"fit"}}}'></mv-phrasebook-message>
</div>
</li>
<li class="pb-item">
<span class="pb-av" aria-hidden="true">LR</span>
<div class="pb-body">
<span class="pb-who"><strong>Lucía Romero</strong><span>Valencia · Sep 4, 2026</span></span>
<mv-phrasebook-message for="pb-book" locale="en" up="7" down="3" vote="down"
value='{"template":"was","slots":{"thing":"tracking","quality":"disappointing"},"conjunction":"so","next":{"template":"helps","slots":{"action":"ask-first"}}}'></mv-phrasebook-message>
</div>
</li>
</ul>
</section>
<script type="module">
const book = document.getElementById("pb-book");
const form = document.getElementById("pb-form");
const json = document.getElementById("pb-json");
const log = document.getElementById("pb-log");
const feed = document.getElementById("pb-feed");
const readAs = document.getElementById("pb-readas");
const count = document.getElementById("pb-count");
const previews = ["pb-en", "pb-es", "pb-ja"].map((id) => document.getElementById(id));
const show = () => {
const value = book.value;
for (const el of previews) el.value = value;
json.textContent = value ? JSON.stringify(value, null, 2) : "null";
};
customElements.whenDefined("mv-phrasebook").then(() => requestAnimationFrame(show));
book.addEventListener("mv-change", (e) => {
show();
log.textContent = e.detail.complete ? `Ready: “${e.detail.text}”` : `Draft (${e.detail.reason})`;
});
// "reset" fires before the fields are restored: allow two phrases again so the default message comes back whole.
form.addEventListener("reset", () => { book.maxClauses = 2; requestAnimationFrame(show); log.textContent = "Reset to the saved draft."; });
// The app can veto a pick: here, "plus" cannot follow a negative remark.
book.addEventListener("mv-pick", (e) => {
const v = book.value;
if (e.detail.kind === "conjunction" && e.detail.id === "plus" && ["disappointing", "below-average"].includes(v?.slots?.quality)) {
e.preventDefault();
log.textContent = "Blocked: “plus” can't follow a negative remark.";
}
});
document.getElementById("pb-two").addEventListener("change", (e) => {
book.maxClauses = e.target.checked ? 2 : 1;
show();
});
form.addEventListener("submit", (e) => {
e.preventDefault();
if (!book.checkValidity()) { book.reportValidity(); return; }
const li = document.createElement("li");
li.className = "pb-item";
li.dataset.new = "";
const av = Object.assign(document.createElement("span"), { className: "pb-av", textContent: "You" });
av.setAttribute("aria-hidden", "true");
const body = Object.assign(document.createElement("div"), { className: "pb-body" });
const who = Object.assign(document.createElement("span"), { className: "pb-who" });
who.append(Object.assign(document.createElement("strong"), { textContent: "You" }),
Object.assign(document.createElement("span"), { textContent: `Just now · ${new Date().toLocaleDateString("en-US", { month: "short", day: "numeric", year: "numeric" })}` }));
const msg = book.render(book.value, { locale: readAs.value, rating: "votes", up: 0, down: 0 });
body.append(who, msg);
li.append(av, body);
feed.prepend(li);
count.textContent = `${feed.children.length} messages`;
log.textContent = "Posted. Readers see it in their language.";
book.clear();
show();
});
readAs.addEventListener("mv-change", (e) => {
for (const m of feed.querySelectorAll("mv-phrasebook-message")) m.setAttribute("locale", e.detail.value);
});
// Votes: optimistic, confirmed by a fake API round trip.
feed.addEventListener("mv-rate", (e) => {
e.detail.waitUntil(new Promise((resolve) => setTimeout(resolve, 350)));
});
</script>
</div>API
Attributes
| Name | 类型 | Default | Description |
|---|---|---|---|
name | string | Form field name. The submitted value is the structured message as JSON (nothing when empty). | |
value | JSON string | Initial message, e.g. '{"template":"helps","slots":{"action":"size-up"}}'. Restored by a form reset. | |
required | boolean | An empty composer is invalid (valueMissing). A started but incomplete message is always invalid (badInput), required or not. | |
disabled | boolean | Disables every piece (also via <fieldset disabled>). | |
label | string | Accessible name of the sentence group when no <label for> points at the element. | |
locale | BCP 47 tag | Language the composer displays words and templates in (falls back from "es-MX" to "es", then to the source labels). The stored value never changes with it. | |
source-locale | BCP 47 tag | en | Language of the declared labels (used for the preview's language chips, glosses and capitalization rules). |
max-clauses | number | 2 | How many phrases can be chained with connectors. 1 hides “Add a second phrase”; lowering it trims extra phrases. |
placement | bottom-start | bottom | top-start … | bottom-start | Preferred side of the word picker relative to the piece that opened it (flips and shifts to stay in the viewport). |
data-variant | "plain" | Drops the card frame (border, background, padding) to embed the composer in your own container. | |
data-empty / data-complete / data-open | state | Set by the component: nothing chosen yet, every blank filled, a picker is open. |
Properties
| Name | 类型 | Description |
|---|---|---|
value | { template, slots: Record<string, string>, conjunction?, next? } | null | The structured message: template id, word id per blank name, and an optional chained phrase. Accepts an object or a JSON string; null or "" clears. Unknown ids are kept and shown as blanks until the vocabulary knows them. |
text | string | The message rendered as plain text in the current locale (read-only). |
complete | boolean | True when every template, blank and connector is filled (read-only). |
templates | Array<{ id, text, group?, keepCase?, keywords? }> | Templates. Blanks are written {name}, or {name:type} / {name:type|other} when the name differs from the accepted word types (two blanks of the same type need two names). Replaces the <option data-template> children. |
words | Array<{ id, label, type, group?, keywords? }> | Vocabulary. type decides which blanks accept the word, group is the picker category. Labels are written as they appear mid-sentence (“the fabric”); the first letter of a message is capitalized automatically. |
conjunctions | Array<{ id, label }> | Connectors that join phrases. None means a single phrase. |
types | Record<string, string> | Human label of each word type, shown in empty blanks and in the picker (“aspect”, “tip”). Defaults to the type id. |
messages | Record<locale, { templates?, words?, conjunctions?, types?, groups?, format?: { join, end } }> | Dictionaries keyed by locale. Templates reorder blanks by name (“{thing}は{quality}でした”); format.join places the connector (default "{first}, {conjunction} {second}") and format.end the final punctuation (default "."). Missing entries fall back to the source labels and are reported as untranslated. |
locales | string[] | Source locale followed by every dictionary key (read-only). |
book | object | The normalized phrasebook (read-only), accepted by <mv-phrasebook-message>.source and formatPhrase(). |
strings | Partial<Record<string, string>> | Overrides for the component's own UI text (choosePhrase, addClause, preview, readsIn, clear, searchWords ({type}), noMatch ({query}), blanksLeft ({n}), ready, valueMissing, incomplete…). English defaults. |
Methods
| Name | Description |
|---|---|
format(value?, locale?) | Plain-text rendering of a message (defaults: current value and locale). |
render(value?, { locale?, rating?, up?, down?, vote? }) | Returns a new <mv-phrasebook-message> bound to this phrasebook, ready to insert in a feed. |
open({ clause?, slot?, part? }) | Opens the picker of a piece (part: "template" | "conjunction"); with no argument, the first unfilled piece. |
close() / clear() / focus() | Closes the picker; resets to an empty composer (emits mv-change with reason "clear"); focuses the first unfilled piece. |
checkValidity() / reportValidity() | Native constraint validation; the validation bubble points at the first unfilled piece. |
formatPhrase(value, book, { locale, sourceLocale }) (module export) | Pure, SSR-safe text rendering from a plain phrasebook object; phraseParts() returns the parts, completeness and untranslated ids. |
Events
| Name | Description |
|---|---|
mv-pick | Cancelable, before a choice is applied. detail: { kind: "template" | "word" | "conjunction", id, clause, slot }. preventDefault() refuses it (the picker stays open and says why), e.g. to block a combination. |
mv-change | The message changed through the UI. detail: { value, text, complete, reason: "template" | "word" | "conjunction" | "add" | "remove" | "clear" | "clear-piece", clause?, slot?, id? }. |
mv-open / mv-close | The word picker opened (detail: { kind, clause, slot }) or closed. |
mv-vocabulary | The phrasebook (re)loaded its vocabulary. detail: { book }. Bound <mv-phrasebook-message> elements repaint on it. |
mv-rate (on mv-phrasebook-message) | Cancelable, before a vote is applied. detail: { vote: "up" | "down" | null (vote removed), previous, up, down, value, waitUntil(promise) }. The counts update at once; a rejected waitUntil promise rolls them back and emits mv-rate-error { vote, previous, error }. |
mv-rate-error (on mv-phrasebook-message) | A waitUntil promise passed in mv-rate was rejected: the vote and counts are rolled back. detail: { vote, previous, error }. |
Content structure
| Name | Description |
|---|---|
(children <option data-template>) | <option data-template="was" data-group="Describe">{thing} was {quality}</option>; data-keep-case keeps its first letter when it follows a connector. |
(children <option data-word> / <optgroup data-word>) | Words: <optgroup label="Shipping" data-word="thing"><option value="delivery">delivery</option></optgroup> (the optgroup label is the category; value is the id, defaulting to the slugified text). data-keywords adds search synonyms. |
(children <option data-conjunction> / <option data-type>) | Connectors (<option data-conjunction="but">but</option>) and type labels (<option data-type="thing">aspect</option>). |
(child <script type="application/json" data-phrasebook>) | The same data as JSON: { templates, words, conjunctions, types, messages, format }. Children stay in the DOM (hidden) and are re-read when they change. |
CSS classes
| Name | Description |
|---|---|
mv-phrasebook-clause / -line / -text | One phrase row (role=group), its sentence line and the template's literal words. |
mv-phrasebook-piece | Every interactive part of the sentence (data-kind="template | slot | conjunction", data-empty, data-open, data-fresh right after a pick): -template (switcher, or -start when the phrase is empty), -slot, -conjunction; -join is the connector rail, -remove and -add manage phrases. |
mv-phrasebook-preview | Live preview: -preview-text (-preview-word, -preview-conjunction, -preview-blank), -progress, -locales / -locale (data-partial), -clear. |
mv-phrasebook-popup | Word picker (Popover API, data-kind): -search, -search-input (role=combobox), -filters / -filter (aria-pressed), -list (role=listbox), -group, -option (data-active, aria-selected), -option-gloss, -option-blank, -match, -empty, -hint. |
mv-phrasebook-message | Read view element <mv-phrasebook-message for locale value up down vote rating>: -message-text (-message-word, -message-conjunction), -rating (role=group), -vote (data-vote, aria-pressed), -count. rating="votes" (default), "readonly" or "none"; data-variant="plain" drops the frame. |
CSS variables
| Name | Default | Description |
|---|---|---|
--mv-phrasebook-word | var(--mv-accent) | Tint of filled blanks, focus of empty ones and the start icon. |
--mv-phrasebook-connector | var(--mv-fg-muted) | Text color of connector pills. |
--mv-phrasebook-font-size | 1.0625rem | Size of the sentence line in the composer. |
--mv-phrasebook-list-height | 15rem | Maximum height of the picker list. |
--mv-phrasebook-helpful | var(--mv-accent) | Tint of a pressed “helpful” vote. |
--mv-phrasebook-message-size | var(--mv-text-sm) | Text size of the read view. |
Accessibility
The sentence is a labelled group (from <label for>, label or aria-label) of one group per phrase; every blank, connector and template switch is a native <button> with aria-haspopup="listbox", aria-expanded and a name that states what it holds (“Aspect: delivery”, “Aspect: empty”, “Connector: but”, “Change phrase (____ was ____)”), so the visible word is always part of the accessible name. Tab walks the sentence in reading order; Left/Right (mirrored in RTL), Home and End move between pieces; Enter, Space or Down opens a piece, typing a letter opens it with that letter searched, Backspace/Delete empties it (on a later phrase's switcher, removes the phrase). The picker is a labelled dialog around a real combobox input (aria-controls, aria-activedescendant) and a grouped listbox with aria-selected: Up/Down move, Page Up/Down jump between categories, Left/Right switch the category filter while the search is empty, Enter picks, Escape or Alt+Up close and return focus to the piece, Tab closes and moves on. Picking moves focus to the next empty blank of the same phrase (and opens it) or back to the piece, and a polite live region announces the word and the whole sentence; result counts and refused picks are announced inside the picker. Rendered sentences carry the lang of their locale so screen readers switch pronunciation; blanks read as “blank aspect”. Validity uses ElementInternals: required gives valueMissing, a started message with blanks gives badInput with “Fill in every blank before sending (1 blank left)”, anchored to the first empty piece. In <mv-phrasebook-message>, the votes are toggle buttons (aria-pressed) with visible counts and hidden “Helpful” / “Not helpful” names inside a labelled group, aria-busy while a waitUntil promise runs. Colors always come with shape: empty blanks are dashed and italic, partial translations have a dashed chip and a dot, votes fill their icon. Reduced motion (OS or data-motion="reduce"): no pop, no row entrance, counts and the picker change instantly. Forced colors: pieces get ButtonText borders, the active option a Highlight outline, pressed votes Highlight.