The zh pair's other direction, and a rule pack that mostly says no
`pair_lang` had always been answering a second question nobody asked: it says which two languages, and every surface built on it assumed English was the one being learned. That is why hanzi is never tokenized, never spell-checked, never glossed — correct for a Mandarin native practising English, backwards for an English native practising Mandarin. `users.direction` (migration 0016) separates the two questions; a `zh-learner` pair code would have been cheaper and would have made two directions of one pair look like two unrelated languages to every query. Segmentation is what replaces `wordAt` where there are no spaces: a shortest-path walk over log-probabilities, 232 ms and 14 MB for 188,522 words. The browser gets the word list because segmentation runs on hover; the server keeps the whole dictionary. Their coverage gates come out opposite on purpose — the client list is frequency-gated because the segmentation is measurably identical without the tail, and the dictionary is gated by nothing, because its only power is to explain and the word a learner stops on is the rare one. The 错别字 pack is 24 confusable pairs behind two mechanical gates. One admits a pair only if the wrong form is not a dictionary word and the right form is, which is why it refuses 自已 for 自己 — a real error whose wrong form is a headword. The other asks the segmenter whether the two characters already belong to two different words, without which 自己经常, 睡觉的时候 and 不知到底 would all be corrupted silently into text still made of real characters. Not deployed (this carries a migration), not seen in a browser, and no account has ever been in the learner direction. The IME composition guards were in scope and are not done — see BUILD_PLAN Phase 26.
This commit is contained in:
prosolis
@@ -0,0 +1,141 @@
|
||||
import { readFileSync } from 'node:fs'
|
||||
import { gunzipSync } from 'node:zlib'
|
||||
import { describe, expect, it } from 'vitest'
|
||||
|
||||
import { CONFUSION_PAIRS, hanziFindings } from './hanzi'
|
||||
import { buildSegmenter } from '../../lib/segment'
|
||||
|
||||
// The 错别字 pack, held to the bar Phase 22 set for the English rule pack: every
|
||||
// rule pinned in *two* directions — the mistake it must catch, and the correct
|
||||
// writing next to it that it must leave alone.
|
||||
//
|
||||
// Here the second direction is the one that matters, and it is unusually easy to
|
||||
// get wrong. Chinese has no spaces, so every one of these rules is a substring
|
||||
// match on running text, and for most of them there exists an ordinary correct
|
||||
// sentence that contains the substring across a word boundary. Those sentences
|
||||
// are the real test.
|
||||
|
||||
const raw = gunzipSync(readFileSync(new URL('../../../public/dictionaries/zh/words.txt.gz', import.meta.url)))
|
||||
const seg = buildSegmenter(raw.toString('utf8'))
|
||||
|
||||
const flagged = (text: string) => hanziFindings(text, seg).map((f) => `${f.original}→${f.replacement}`)
|
||||
|
||||
describe('the gate that admits a rule', () => {
|
||||
// The pack's own claim about itself, checked against the shipped dictionary
|
||||
// rather than asserted in a comment. A pair whose wrong form is a real word
|
||||
// cannot be decided mechanically and does not belong here.
|
||||
it('every wrong form is not a word, and every right form is', () => {
|
||||
for (const { wrong, right } of CONFUSION_PAIRS) {
|
||||
expect(seg.has(wrong), `${wrong} is a dictionary word and must not be flagged`).toBe(false)
|
||||
expect(seg.has(right), `${right} is not a dictionary word`).toBe(true)
|
||||
}
|
||||
})
|
||||
|
||||
// The errors this pack deliberately refuses, and why — each is a genuine
|
||||
// mistake by a modern standard whose wrong form is itself a headword. If a
|
||||
// dictionary rebuild ever drops one of these, this test fails and the pair
|
||||
// becomes admissible; that is the intended way to find out.
|
||||
it('refuses the well-known errors it cannot decide', () => {
|
||||
for (const undecidable of ['自已', '好象', '倒底', '帐号', '部份']) {
|
||||
expect(seg.has(undecidable), `${undecidable} is no longer a word — reconsider the rule`).toBe(true)
|
||||
expect(flagged(`这是${undecidable}的例子`)).toEqual([])
|
||||
}
|
||||
})
|
||||
})
|
||||
|
||||
describe('the mistakes it catches', () => {
|
||||
it('已 / 己 / 以', () => {
|
||||
expect(flagged('我己经写完了作业')).toEqual(['己经→已经'])
|
||||
expect(flagged('我以经吃过饭了')).toEqual(['以经→已经'])
|
||||
expect(flagged('下课已后我们去公园')).toEqual(['已后→以后'])
|
||||
})
|
||||
|
||||
it('在 / 再', () => {
|
||||
expect(flagged('明天在见')).toEqual(['在见→再见'])
|
||||
expect(flagged('他正再看书')).toEqual(['正再→正在'])
|
||||
expect(flagged('现再几点了')).toEqual(['现再→现在'])
|
||||
})
|
||||
|
||||
it('做 / 作', () => {
|
||||
expect(flagged('我的工做很忙')).toEqual(['工做→工作'])
|
||||
expect(flagged('老师给我们很多做业')).toEqual(['做业→作业'])
|
||||
expect(flagged('这本书的做者是谁')).toEqual(['做者→作者'])
|
||||
})
|
||||
|
||||
it('the rest', () => {
|
||||
expect(flagged('我觉的这个很好')).toEqual(['觉的→觉得'])
|
||||
expect(flagged('你因该早点睡')).toEqual(['因该→应该'])
|
||||
expect(flagged('即然你来了就坐下吧')).toEqual(['即然→既然'])
|
||||
expect(flagged('你知到吗')).toEqual(['知到→知道'])
|
||||
expect(flagged('请输入你的蜜码')).toEqual(['蜜码→密码'])
|
||||
})
|
||||
|
||||
it('reports an exact span, so the card replaces the right characters', () => {
|
||||
const text = '我己经到了'
|
||||
const [f] = hanziFindings(text, seg)
|
||||
expect(text.slice(f.from, f.to)).toBe('己经')
|
||||
expect(text.slice(0, f.from) + f.replacement + text.slice(f.to)).toBe('我已经到了')
|
||||
})
|
||||
|
||||
it('finds every occurrence, in document order', () => {
|
||||
expect(flagged('我己经吃了，他也己经吃了')).toEqual(['己经→已经', '己经→已经'])
|
||||
expect(flagged('我的工做很忙，所以我觉的很累')).toEqual(['工做→工作', '觉的→觉得'])
|
||||
})
|
||||
})
|
||||
|
||||
// ── the direction that matters ──────────────────────────────────────────────
|
||||
|
||||
describe('the correct writing it must not touch', () => {
|
||||
// Each of these is an ordinary sentence containing a flagged substring across
|
||||
// a word boundary. Without the boundary gate, every one would be corrupted —
|
||||
// and corrupted silently, into text that is still made of real characters.
|
||||
it('leaves two real words alone where they happen to abut', () => {
|
||||
// 自己 + 经常. The substring is 己经.
|
||||
expect(flagged('他自己经常做饭')).toEqual([])
|
||||
// 睡觉 + 的. The substring is 觉的.
|
||||
expect(flagged('睡觉的时候不要看手机')).toEqual([])
|
||||
// 感觉 + 的.
|
||||
expect(flagged('这是我感觉的方向')).toEqual([])
|
||||
// 不知 + 到底.
|
||||
expect(flagged('我不知到底该怎么办')).toEqual([])
|
||||
// 因 + 位置.
|
||||
expect(flagged('因位置不好我们换了座位')).toEqual([])
|
||||
// 已 + 后悔.
|
||||
expect(flagged('他已后悔了')).toEqual([])
|
||||
})
|
||||
|
||||
it('leaves ordinary correct prose entirely alone', () => {
|
||||
for (const good of [
|
||||
'我今天早上去公园跑步了',
|
||||
'他的中文说得很好',
|
||||
'我已经完成了我的作业',
|
||||
'现在几点了，我们再见面吧',
|
||||
'我觉得这个工作很有意思',
|
||||
'既然你已经知道了，就按照计划做',
|
||||
]) {
|
||||
expect(flagged(good), good).toEqual([])
|
||||
}
|
||||
})
|
||||
|
||||
// Where the gate costs the pack a real catch, and the trade it is making.
|
||||
// 不知 is itself a word, so 我不知到他在哪里 — which really is 知到 for 知道 —
|
||||
// reads to the segmenter as 不知 + 到 and is left alone. That is the gate
|
||||
// preferring a missed error to a corrupted sentence, which is the whole
|
||||
// premise: 我不知到底该怎么办 is the same three characters and is correct.
|
||||
it('declines a real error rather than risk the sentence beside it', () => {
|
||||
expect(flagged('我不知到他在哪里')).toEqual([])
|
||||
expect(flagged('你知到吗')).toEqual(['知到→知道'])
|
||||
})
|
||||
|
||||
it('says nothing about English, or about nothing', () => {
|
||||
expect(flagged('I already finished my homework')).toEqual([])
|
||||
expect(flagged('')).toEqual([])
|
||||
})
|
||||
|
||||
// The direction gate. The word list is loaded only for an account learning
|
||||
// Chinese, so without one this pack is silent — a writer practising English
|
||||
// must never be told her own quoted Chinese is wrong.
|
||||
it('is silent without a segmenter, which is how the direction gate works', () => {
|
||||
expect(hanziFindings('我己经写完了', null)).toEqual([])
|
||||
})
|
||||
})
|
||||
@@ -0,0 +1,149 @@
|
||||
import type { MechanicsFinding } from '../../api/client'
|
||||
import type { Segmenter } from '../../lib/segment'
|
||||
|
||||
// 错别字 — wrong-character detection, the Chinese counterpart of the spell
|
||||
// checker, and a different problem from the one Hunspell solves.
|
||||
//
|
||||
// Chinese has no misspellings in the English sense: every character a writer can
|
||||
// type is a real character, correctly formed, and an IME will not offer one that
|
||||
// is not. What it *will* offer is the wrong one. Typing pinyin `yijing` and
|
||||
// taking the first candidate gives 已经 or 己经 depending on the moment, and both
|
||||
// are made of real characters. So the unit of error is not a malformed word but
|
||||
// a **substituted character inside a correct-looking one** — which is why this
|
||||
// is a rule pack over confusable pairs rather than a dictionary membership test.
|
||||
//
|
||||
// The discipline is Phase 22's, and the bar is the same: **precision over
|
||||
// recall**. A wrong nudge costs more trust than a missed one earns, and it costs
|
||||
// double here, because a learner has no way to know the tool is wrong. Two
|
||||
// mechanical gates enforce it, and both are checked in the tests rather than
|
||||
// asserted in prose.
|
||||
|
||||
// A confusable pair: `wrong` is never a word, `right` is what was meant.
|
||||
//
|
||||
// **Gate one — the pair must be decidable by the dictionary.** Each entry is
|
||||
// admitted only if `wrong` is absent from the 188k-word list *and* `right` is
|
||||
// present. That is what makes the correction a fact rather than a preference,
|
||||
// and it is checked against the shipped asset in hanzi.test.ts.
|
||||
//
|
||||
// It is also the gate that keeps out errors everyone knows are errors. 自已 for
|
||||
// 自己 is among the commonest slips in written Chinese, and 自已 is itself a
|
||||
// dictionary headword — so this pack does not flag it, exactly as Phase 22's
|
||||
// English pack left out `married with`. The same fate for 好象 (an older form of
|
||||
// 好像, still in the dictionary), 倒底, 帐号 and 部份: all real errors by a modern
|
||||
// standard, none of them decidable here.
|
||||
interface Confusion {
|
||||
wrong: string
|
||||
right: string
|
||||
// The note on the card. English, because this pack only ever runs for a writer
|
||||
// whose English is the language they think in — see the direction gate below.
|
||||
why: string
|
||||
}
|
||||
|
||||
const CONFUSIONS: Confusion[] = [
|
||||
// 已 / 己 / 以 — three characters that differ by one stroke and share a
|
||||
// syllable. The most productive source of 错别字 there is.
|
||||
{ wrong: '己经', right: '已经', why: '已经 (already) — 己 is the "self" character; the one you want is 已.' },
|
||||
{ wrong: '以经', right: '已经', why: '已经 (already) — 以 is a different word; 已 is the one that means "already".' },
|
||||
{ wrong: '已后', right: '以后', why: '以后 (afterwards) takes 以, not 已.' },
|
||||
|
||||
// 在 / 再 — same pinyin (zài), completely different jobs: one is location and
|
||||
// ongoing action, the other is repetition.
|
||||
{ wrong: '在见', right: '再见', why: '再见 (goodbye) — 再 is "again", which is what "see you again" needs.' },
|
||||
{ wrong: '正再', right: '正在', why: '正在 (in the middle of doing) takes 在, the one about being somewhere.' },
|
||||
{ wrong: '现再', right: '现在', why: '现在 (now) takes 在.' },
|
||||
|
||||
// 做 / 作 — both zuò, both "to do", and which one a compound takes is simply
|
||||
// fixed by convention. A learner cannot reason it out, which is what makes a
|
||||
// reminder worth having.
|
||||
{ wrong: '工做', right: '工作', why: '工作 (work) is written with 作.' },
|
||||
{ wrong: '做业', right: '作业', why: '作业 (homework) is written with 作.' },
|
||||
{ wrong: '做者', right: '作者', why: '作者 (author) is written with 作.' },
|
||||
{ wrong: '做文', right: '作文', why: '作文 (an essay) is written with 作.' },
|
||||
{ wrong: '做用', right: '作用', why: '作用 (effect, function) is written with 作.' },
|
||||
|
||||
// 得 / 的 — the pair everyone knows about. Only the fixed compound is flagged:
|
||||
// deciding 的 against 地 against 得 in the general case needs to know whether
|
||||
// the next word is a verb or a noun, which nothing here can tell.
|
||||
{ wrong: '觉的', right: '觉得', why: '觉得 (to feel, to think) ends in 得.' },
|
||||
|
||||
// 即 / 既 — one stroke apart, opposite meanings ("namely" against "since").
|
||||
{ wrong: '即然', right: '既然', why: '既然 (since, given that) takes 既.' },
|
||||
{ wrong: '既使', right: '即使', why: '即使 (even if) takes 即.' },
|
||||
|
||||
// The rest: ordinary IME slips where the wrong character is a homophone.
|
||||
{ wrong: '因该', right: '应该', why: '应该 (should) — 因 means "because"; the word you want starts with 应.' },
|
||||
{ wrong: '因位', right: '因为', why: '因为 (because) ends in 为.' },
|
||||
{ wrong: '知到', right: '知道', why: '知道 (to know) ends in 道.' },
|
||||
{ wrong: '安照', right: '按照', why: '按照 (according to) takes 按.' },
|
||||
{ wrong: '蜜码', right: '密码', why: '密码 (password) takes 密 — 蜜 is honey.' },
|
||||
{ wrong: '犹其', right: '尤其', why: '尤其 (especially) takes 尤.' },
|
||||
{ wrong: '甘净', right: '干净', why: '干净 (clean) takes 干.' },
|
||||
{ wrong: '什末', right: '什么', why: '什么 (what) ends in 么.' },
|
||||
{ wrong: '一像', right: '一样', why: '一样 (the same) ends in 样 — 像 is "to resemble".' },
|
||||
{ wrong: '必须品', right: '必需品', why: '必需品 (a necessity) takes 需. 必须 is "must", which is a different word.' },
|
||||
]
|
||||
|
||||
// **Gate two — the characters must not already belong to two different words.**
|
||||
//
|
||||
// This is the gate that stops the pack from destroying correct writing, and
|
||||
// without it every rule above is dangerous. 自己经常 ("oneself, often") contains
|
||||
// the string 己经. 睡觉的时候 ("when sleeping") contains 觉的. 不知到底 contains 知到.
|
||||
// A substring match would corrupt all three.
|
||||
//
|
||||
// The segmenter already knows the difference, so the test is: split the text,
|
||||
// and if the two characters land in different tokens *and* either token is a
|
||||
// real multi-character word, this is a word boundary and not an error. Two
|
||||
// adjacent single-character tokens is what the walk produces when it has nothing
|
||||
// better to offer — which is exactly what a mistyped compound looks like.
|
||||
function isWordBoundary(tokens: { word: string; from: number; to: number }[], at: number): boolean {
|
||||
const left = tokens.find((t) => at >= t.from && at < t.to)
|
||||
const right = tokens.find((t) => at + 1 >= t.from && at + 1 < t.to)
|
||||
if (!left || !right || left === right) return false
|
||||
return left.word.length > 1 || right.word.length > 1
|
||||
}
|
||||
|
||||
// hanziFindings returns the 错别字 in a piece of text, as ordinary mechanics
|
||||
// findings — the same shape, the same rail, the same cards, the same accept.
|
||||
//
|
||||
// It needs the segmenter and does nothing without one, which is also the
|
||||
// direction gate: the word list is loaded only for an account learning Chinese
|
||||
// (useSegmenter), so a writer practising English can never be told her quoted
|
||||
// Chinese is wrong. That is not a nicety. Petal deliberately never corrects the
|
||||
// pair language — the fr and es dictionaries are chosen to hold every variety
|
||||
// precisely so they cannot underline correct writing — and a Mandarin native
|
||||
// does not need her own language checked by a rule pack of two dozen entries.
|
||||
export function hanziFindings(text: string, segmenter: Segmenter | null): MechanicsFinding[] {
|
||||
if (!segmenter || !text) return []
|
||||
// One segmentation for the whole text, shared by every rule. The walk is
|
||||
// linear, but running it two dozen times over a long document would not be.
|
||||
const tokens = segmenter.segment(text)
|
||||
const found: MechanicsFinding[] = []
|
||||
|
||||
for (const c of CONFUSIONS) {
|
||||
let from = text.indexOf(c.wrong)
|
||||
while (from !== -1) {
|
||||
// The boundary test is asked at the seam the substitution sits on: the
|
||||
// gap between the first two characters, which is where a mistyped
|
||||
// compound and two adjacent words look different from each other.
|
||||
if (!isWordBoundary(tokens, from)) {
|
||||
found.push({
|
||||
from,
|
||||
to: from + c.wrong.length,
|
||||
original: c.wrong,
|
||||
replacement: c.right,
|
||||
explanation: c.why,
|
||||
type: 'mechanics',
|
||||
})
|
||||
}
|
||||
from = text.indexOf(c.wrong, from + 1)
|
||||
}
|
||||
}
|
||||
|
||||
// Document order, so the rail reads down the page rather than down this file.
|
||||
return found.sort((a, b) => a.from - b.from)
|
||||
}
|
||||
|
||||
// Exported for the tests, which check every pair against the shipped word list.
|
||||
// A pack whose own gate is only described in a comment is a pack whose gate can
|
||||
// rot; this is how the description is made to stay true.
|
||||
export const CONFUSION_PAIRS = CONFUSIONS.map((c) => ({ wrong: c.wrong, right: c.right }))
|
||||
@@ -20,6 +20,11 @@ interface Props {
|
||||
// The signed-in writer, when there is real auth to sign out of. Null in a
|
||||
// local-dev build, where there is nothing to leave.
|
||||
account: { name: string } | null
|
||||
// The account's learner direction and the way to change it, passed straight
|
||||
// through to the language picker in the footer — the sidebar is the drawer,
|
||||
// and the drawer is the only chrome always one tap away on a phone.
|
||||
direction?: string
|
||||
onDirection?: (direction: string) => Promise<void>
|
||||
}
|
||||
|
||||
// Sidebar sort orders. 'recent' keeps the server's updated_at-desc ordering.
|
||||
@@ -43,6 +48,8 @@ export function DocList({
|
||||
onToggleTag,
|
||||
onCreateTag,
|
||||
account,
|
||||
direction,
|
||||
onDirection,
|
||||
}: Props) {
|
||||
const t = usePack()
|
||||
// Active tag filter (null = show all). Cleared automatically if the tag
|
||||
@@ -161,7 +168,7 @@ export function DocList({
|
||||
{/* The pair Petal speaks. Unlike the rows above it this is not about any
|
||||
document, and unlike sign-out it is offered whether or not there is an
|
||||
account behind the session — a local-dev build still has a langpack. */}
|
||||
<LanguagePicker />
|
||||
<LanguagePicker direction={direction} onDirection={onDirection} />
|
||||
|
||||
{/* Who's writing, and the way out. Shown only when there's a real account
|
||||
behind the session — a local-dev build has nobody to sign out as. */}
|
||||
|
||||
@@ -15,15 +15,46 @@ import { setPackLang, shippedPacks, usePack } from '../../i18n'
|
||||
// read a label that says "Portuguese" in Chinese, so the buttons say 中文 and
|
||||
// Português and nothing else — the one place in Petal where bilingual copy would
|
||||
// actively get in the way.
|
||||
export function LanguagePicker() {
|
||||
interface Props {
|
||||
// The account's current direction ('learning_en' | 'learning_pair'), and the
|
||||
// way to change it. Owned by App rather than here, because turning the pair
|
||||
// around changes what the *editor* does — it is what loads the word list —
|
||||
// and this control is only where the writer says so.
|
||||
direction?: string
|
||||
onDirection?: (direction: string) => Promise<void>
|
||||
}
|
||||
|
||||
export function LanguagePicker({ direction, onDirection }: Props = {}) {
|
||||
const t = usePack()
|
||||
const packs = shippedPacks()
|
||||
const [saving, setSaving] = useState<string | null>(null)
|
||||
const [failed, setFailed] = useState(false)
|
||||
const [turning, setTurning] = useState(false)
|
||||
const [turnFailed, setTurnFailed] = useState(false)
|
||||
|
||||
// Nothing to choose between — a deployment with one pack shows no picker
|
||||
// rather than a single button that does nothing.
|
||||
if (packs.length < 2) return null
|
||||
// rather than a single button that does nothing. The direction control is
|
||||
// still worth rendering in that case, so it is checked separately below.
|
||||
const showPacks = packs.length >= 2
|
||||
// `t.learner` is the pack's own statement that this pair can be learned
|
||||
// toward, and the server keeps the matching list (auth.learnerPairs). A pack
|
||||
// without it renders nothing here, which is the same failure mode as a pair
|
||||
// without copy: absent rather than broken.
|
||||
const learner = t.learner
|
||||
if (!showPacks && !learner) return null
|
||||
|
||||
const turn = async (next: string) => {
|
||||
if (!onDirection || next === (direction ?? 'learning_en') || turning) return
|
||||
setTurning(true)
|
||||
setTurnFailed(false)
|
||||
try {
|
||||
await onDirection(next)
|
||||
} catch {
|
||||
setTurnFailed(true)
|
||||
} finally {
|
||||
setTurning(false)
|
||||
}
|
||||
}
|
||||
|
||||
const choose = async (code: string) => {
|
||||
if (code === t.code || saving) return
|
||||
@@ -47,6 +78,8 @@ export function LanguagePicker() {
|
||||
|
||||
return (
|
||||
<div className="flex flex-col gap-1 px-1">
|
||||
{showPacks && (
|
||||
<>
|
||||
{/* Label and buttons wrap as a pair: the label is itself bilingual
|
||||
("Langue · Language"), and three self-naming buttons beside it need
|
||||
more than the drawer is wide in every language Petal ships. When they
|
||||
@@ -89,6 +122,52 @@ export function LanguagePicker() {
|
||||
{t.docs.languageFailed}
|
||||
</span>
|
||||
)}
|
||||
</>
|
||||
)}
|
||||
|
||||
{/* Which way round the pair is being learned. Below the language buttons
|
||||
because it only makes sense once the language is settled, and rendered
|
||||
at all only for a pair Petal has the learner-side data for. */}
|
||||
{learner && onDirection && (
|
||||
<div
|
||||
className="flex flex-wrap items-center gap-x-2 gap-y-1 text-xs"
|
||||
style={{ color: 'var(--color-muted)' }}
|
||||
>
|
||||
<span className="shrink-0 font-semibold">{learner.label}</span>
|
||||
<div className="ml-auto flex shrink-0 gap-1">
|
||||
{[
|
||||
{ code: 'learning_en', text: learner.toEn, en: `learning English` },
|
||||
{ code: 'learning_pair', text: learner.toPair, en: `learning ${t.nativeName}` },
|
||||
].map((opt) => {
|
||||
const active = (direction ?? 'learning_en') === opt.code
|
||||
return (
|
||||
<button
|
||||
key={opt.code}
|
||||
type="button"
|
||||
onClick={() => void turn(opt.code)}
|
||||
disabled={turning}
|
||||
aria-pressed={active}
|
||||
aria-label={`I am ${opt.en}`}
|
||||
className="petal-tap-sm px-2.5 py-1 text-xs font-bold transition-colors disabled:opacity-60"
|
||||
style={{
|
||||
borderRadius: 'var(--radius-pill)',
|
||||
background: active ? 'var(--color-accent)' : 'var(--color-surface)',
|
||||
color: active ? '#fff' : 'var(--color-plum)',
|
||||
boxShadow: active ? 'none' : 'var(--shadow-soft)',
|
||||
}}
|
||||
>
|
||||
{opt.text}
|
||||
</button>
|
||||
)
|
||||
})}
|
||||
</div>
|
||||
</div>
|
||||
)}
|
||||
{turnFailed && learner && (
|
||||
<span className="text-[0.7rem]" style={{ color: 'var(--color-accent)' }}>
|
||||
{learner.failed}
|
||||
</span>
|
||||
)}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
@@ -34,6 +34,8 @@ import { planBatch } from './acceptBatch'
|
||||
import { api, type Suggestion, type SuggestionType, type WordInfo } from '../../api/client'
|
||||
import { speak, speechSupported } from '../../audio/speech'
|
||||
import type { SpellChecker } from '../../hooks/useSpellChecker'
|
||||
import type { Segmenter } from '../../lib/segment'
|
||||
import { hanziWordAt, hanziToWordInfo, hanziPinyin } from './hanziWord'
|
||||
import { usePack } from '../../i18n'
|
||||
|
||||
// Breathing room left below the last suggestion card when the rail's stack is what
|
||||
@@ -73,6 +75,11 @@ interface Props {
|
||||
// to the personal dictionary is bubbled up so it persists app-wide.
|
||||
spellChecker: SpellChecker | null
|
||||
onAddWord: (word: string) => void
|
||||
// The Chinese word list, non-null only for a writer learning the pair
|
||||
// language (users.direction = 'learning_pair'). Its presence is what turns on
|
||||
// every Chinese-side behaviour here: hanzi stops being text the editor steps
|
||||
// over and becomes words it can point at.
|
||||
segmenter: Segmenter | null
|
||||
}
|
||||
|
||||
interface MisspellState {
|
||||
@@ -95,6 +102,12 @@ interface WordInfoState {
|
||||
left: number
|
||||
loading: boolean
|
||||
info: WordInfo | null
|
||||
// The word's own pinyin, for a Chinese lookup. Kept beside `info` rather than
|
||||
// inside it because WordInfo is the English dictionary's shape and `phonetic`
|
||||
// there means IPA — printing pinyin between the slashes that say "this is
|
||||
// IPA" would be a small lie in the one place a learner is looking for the
|
||||
// truth about pronunciation.
|
||||
pinyin: string
|
||||
// Garden state: the captured word's id (null until the auto-capture returns or
|
||||
// after it's removed) and whether it's currently in the garden.
|
||||
vocabId: string | null
|
||||
@@ -188,6 +201,10 @@ interface GlossState {
|
||||
gloss: string
|
||||
// The other reading, when the token is a word in her language too.
|
||||
reverse?: string
|
||||
// A line shown *above* the meaning rather than below it: pinyin, for a
|
||||
// Chinese word. Above because it is read first — the meaning of 公园 may
|
||||
// already be clear to someone who cannot yet say it.
|
||||
lead?: string
|
||||
from: number
|
||||
to: number
|
||||
top: number
|
||||
@@ -234,6 +251,7 @@ export function EditorCore({
|
||||
onFocusMode,
|
||||
spellChecker,
|
||||
onAddWord,
|
||||
segmenter,
|
||||
}: Props) {
|
||||
// Her pair's copy — the hover tip labels the second reading with the language's
|
||||
// own name, so it says "português" rather than "pt-PT".
|
||||
@@ -421,6 +439,26 @@ export function EditorCore({
|
||||
// popover would offer a definition of "cora".
|
||||
const wordAlphabet = spellChecker?.extendedAlphabet ?? false
|
||||
|
||||
// "The word under here", for a document that may hold two writing systems at
|
||||
// once — which every document in this pair does, because a learner's Chinese
|
||||
// practice is full of English and her English is full of quoted Chinese.
|
||||
//
|
||||
// Chinese is tried first and Latin second, and the order costs nothing to get
|
||||
// right: the two can never both answer, because a Han character is not a Latin
|
||||
// letter and neither tokenizer will cross into the other's run. `hanzi` rides
|
||||
// along because the two answers go to different dictionaries — the same
|
||||
// string is a word in exactly one of them.
|
||||
const resolveWord = useCallback(
|
||||
(pos: number): { from: number; to: number; word: string; hanzi: boolean } | null => {
|
||||
if (!editor) return null
|
||||
const han = hanziWordAt(editor.state.doc, pos, segmenter)
|
||||
if (han) return { ...han, hanzi: true }
|
||||
const latin = wordAt(editor.state.doc, pos, wordAlphabet)
|
||||
return latin ? { ...latin, hanzi: false } : null
|
||||
},
|
||||
[editor, segmenter, wordAlphabet],
|
||||
)
|
||||
|
||||
// Push the spell checker into its decoration plugin once the dictionary loads
|
||||
// (and again whenever the personal dictionary changes its identity).
|
||||
useEffect(() => {
|
||||
@@ -833,7 +871,7 @@ export function EditorCore({
|
||||
const openWordLookup = useCallback(
|
||||
(pos: number) => {
|
||||
if (!editor) return
|
||||
const range = wordAt(editor.state.doc, pos, wordAlphabet)
|
||||
const range = resolveWord(pos)
|
||||
if (!range) return
|
||||
const wrapper = wrapperRef.current
|
||||
if (!wrapper) return
|
||||
@@ -849,12 +887,18 @@ export function EditorCore({
|
||||
closeCard()
|
||||
setMisspell(null)
|
||||
const token = ++wordReqRef.current
|
||||
setWordInfo({ word: range.word, from: range.from, to: range.to, top, left, loading: true, info: null, vocabId: null, saved: false })
|
||||
setWordInfo({ word: range.word, from: range.from, to: range.to, top, left, loading: true, info: null, pinyin: '', vocabId: null, saved: false })
|
||||
// The sentence the word sits in, for review context in the garden.
|
||||
const example = exampleAt(range.from)
|
||||
api
|
||||
.lookupWord(range.word)
|
||||
.then((info) => {
|
||||
// Two dictionaries, one card. The Chinese lookup answers in English and
|
||||
// the English one answers in her language; which is wanted follows from
|
||||
// which script the word is written in, so nothing here has to consult the
|
||||
// account's direction a second time.
|
||||
const lookup: Promise<{ info: WordInfo; pinyin: string }> = range.hanzi
|
||||
? api.hanziWord(range.word).then((h) => ({ info: hanziToWordInfo(h), pinyin: hanziPinyin(h) }))
|
||||
: api.lookupWord(range.word).then((info) => ({ info, pinyin: '' }))
|
||||
lookup
|
||||
.then(({ info, pinyin }) => {
|
||||
if (token !== wordReqRef.current) return
|
||||
// Auto-capture into the vocabulary garden — only words the dictionary
|
||||
// actually knows (a real gloss or definition), so accidental lookups of
|
||||
@@ -864,14 +908,18 @@ export function EditorCore({
|
||||
// Reflect the saved state optimistically so the heart shows 💚 the
|
||||
// moment a known word loads, rather than flashing 🤍 until the capture
|
||||
// round-trips. vocabId is filled in when recordVocab returns.
|
||||
setWordInfo((w) => (w ? { ...w, loading: false, info, saved: known } : null))
|
||||
setWordInfo((w) => (w ? { ...w, loading: false, info, pinyin, saved: known } : null))
|
||||
if (!known) return
|
||||
api
|
||||
.recordVocab({
|
||||
word: range.word,
|
||||
gloss: info.gloss,
|
||||
definition: info.definitions[0]?.definition ?? '',
|
||||
phonetic: info.phonetic,
|
||||
// The garden's pronunciation field holds whichever this word has:
|
||||
// IPA for an English word, pinyin for a Chinese one. Both answer
|
||||
// the same question on a review card — how do I say this — and a
|
||||
// second column would only be a second thing to keep in sync.
|
||||
phonetic: pinyin || info.phonetic,
|
||||
example,
|
||||
doc_id: docId,
|
||||
})
|
||||
@@ -891,7 +939,7 @@ export function EditorCore({
|
||||
}
|
||||
})
|
||||
},
|
||||
[editor, closeCard, docId],
|
||||
[editor, closeCard, docId, resolveWord, exampleAt],
|
||||
)
|
||||
|
||||
// Toggle a looked-up word in/out of the vocabulary garden from the WordCard
|
||||
@@ -998,7 +1046,7 @@ export function EditorCore({
|
||||
clear()
|
||||
return
|
||||
}
|
||||
const range = wordAt(editor.state.doc, coords.pos, wordAlphabet)
|
||||
const range = resolveWord(coords.pos)
|
||||
if (!range) {
|
||||
clear()
|
||||
return
|
||||
@@ -1007,9 +1055,21 @@ export function EditorCore({
|
||||
if (gloss && gloss.from === range.from && gloss.to === range.to) return
|
||||
clearTimeout(glossTimer.current)
|
||||
const token = ++glossReqRef.current
|
||||
// The Chinese hover carries a second line the English one has no use for:
|
||||
// pinyin above the meaning. It is the thing a learner most often stops to
|
||||
// ask about their own writing — reading a character back is not the same
|
||||
// as being able to say it — and it is why this tooltip is worth having at
|
||||
// all for a script the writer can already read the meaning of half the
|
||||
// time.
|
||||
const ask = (): Promise<{ gloss: string; reverse?: string; lead?: string }> =>
|
||||
range.hanzi
|
||||
? api.hanziWord(range.word).then((h) => ({
|
||||
gloss: h.readings[0]?.senses ?? h.chars.map((c) => `${c.char} ${c.senses}`).join(' · '),
|
||||
lead: hanziPinyin(h),
|
||||
}))
|
||||
: api.glossWord(range.word).then((g) => ({ gloss: g.gloss, reverse: g.reverse }))
|
||||
glossTimer.current = setTimeout(() => {
|
||||
api
|
||||
.glossWord(range.word)
|
||||
ask()
|
||||
.then((g) => {
|
||||
if (token !== glossReqRef.current) return
|
||||
const wrapper = wrapperRef.current
|
||||
@@ -1024,14 +1084,14 @@ export function EditorCore({
|
||||
const wrapRect = wrapper.getBoundingClientRect()
|
||||
const left = Math.max(0, Math.min(start.left - wrapRect.left, wrapper.clientWidth - 280))
|
||||
const top = end.bottom - wrapRect.top + 6
|
||||
setGloss({ word: range.word, gloss: g.gloss, reverse: g.reverse, from: range.from, to: range.to, top, left })
|
||||
setGloss({ word: range.word, gloss: g.gloss, reverse: g.reverse, lead: g.lead, from: range.from, to: range.to, top, left })
|
||||
})
|
||||
.catch(() => {
|
||||
if (token === glossReqRef.current) setGloss(null)
|
||||
})
|
||||
}, 350)
|
||||
},
|
||||
[editor, wordAlphabet, selection, rewrite, misspell, wordInfo, pinned, gloss],
|
||||
[editor, resolveWord, selection, rewrite, misspell, wordInfo, pinned, gloss],
|
||||
)
|
||||
|
||||
// Leaving the editor surface drops any pending/shown gloss.
|
||||
@@ -1255,6 +1315,7 @@ export function EditorCore({
|
||||
{gloss && (
|
||||
<GlossTip
|
||||
gloss={gloss.gloss}
|
||||
lead={gloss.lead}
|
||||
reverse={gloss.reverse}
|
||||
reverseLang={pack.nativeName}
|
||||
style={{ top: gloss.top, left: gloss.left }}
|
||||
@@ -1287,6 +1348,7 @@ export function EditorCore({
|
||||
loading={wordInfo.loading}
|
||||
saved={wordInfo.saved}
|
||||
onToggleSave={toggleSaveWord}
|
||||
pinyin={wordInfo.pinyin}
|
||||
style={{ top: wordInfo.top, left: wordInfo.left }}
|
||||
onReplace={replaceWord}
|
||||
/>
|
||||
|
||||
@@ -7,6 +7,11 @@
|
||||
|
||||
interface Props {
|
||||
gloss: string
|
||||
// A line above the gloss, in a lighter weight: the pinyin of a Chinese word.
|
||||
// It leads because it is what is actually being asked — a learner reading
|
||||
// their own 公园 back may know it means a park and still not know how to say
|
||||
// it, which is the one thing the character does not tell them.
|
||||
lead?: string
|
||||
// The English meaning of the same token read as a word of the writer's own
|
||||
// language, when it is one. On a Latin-script pair "sale" is both, and the
|
||||
// bubble shows the two readings stacked rather than picking one — the same
|
||||
@@ -17,7 +22,7 @@ interface Props {
|
||||
style: React.CSSProperties
|
||||
}
|
||||
|
||||
export function GlossTip({ gloss, reverse, reverseLang, style }: Props) {
|
||||
export function GlossTip({ gloss, lead, reverse, reverseLang, style }: Props) {
|
||||
return (
|
||||
<div
|
||||
className="petal-gloss-tip pointer-events-none absolute z-20 px-2.5 py-1.5 text-sm"
|
||||
@@ -33,6 +38,11 @@ export function GlossTip({ gloss, reverse, reverseLang, style }: Props) {
|
||||
...style,
|
||||
}}
|
||||
>
|
||||
{lead && (
|
||||
<span className="mb-0.5 block font-semibold" style={{ opacity: 0.9 }}>
|
||||
{lead}
|
||||
</span>
|
||||
)}
|
||||
{gloss}
|
||||
{reverse && (
|
||||
<span className="mt-0.5 block" style={{ opacity: 0.72, fontSize: '0.85em' }}>
|
||||
|
||||
@@ -17,11 +17,16 @@ interface Props {
|
||||
// heart toggles it; `onToggleSave` removes/re-adds it.
|
||||
saved: boolean
|
||||
onToggleSave: () => void
|
||||
// A Chinese word's pinyin. Shown in place of the IPA line and *without* the
|
||||
// slashes, because pinyin is not a phonetic transcription — it is how the word
|
||||
// is spelled in letters, and the slashes would say something untrue about it
|
||||
// in the one place a learner is looking for the truth about pronunciation.
|
||||
pinyin?: string
|
||||
style: React.CSSProperties
|
||||
onReplace: (synonym: string) => void
|
||||
}
|
||||
|
||||
export function WordCard({ word, info, loading, saved, onToggleSave, style, onReplace }: Props) {
|
||||
export function WordCard({ word, info, loading, saved, onToggleSave, pinyin, style, onReplace }: Props) {
|
||||
const t = usePack()
|
||||
const definitions = info?.definitions ?? []
|
||||
const synonyms = info?.synonyms ?? []
|
||||
@@ -117,9 +122,10 @@ export function WordCard({ word, info, loading, saved, onToggleSave, style, onRe
|
||||
when she has found a word she likes — "can I use this?". Both are
|
||||
quiet, muted lines: information she can take or leave, never a verdict
|
||||
on her writing. */}
|
||||
{(phonetic || band) && (
|
||||
{(phonetic || pinyin || band) && (
|
||||
<div className="mt-1.5 flex items-center gap-2 text-sm">
|
||||
{phonetic && <span style={{ color: 'var(--color-muted)' }}>/{phonetic}/</span>}
|
||||
{pinyin && <span style={{ color: 'var(--color-muted)' }}>{pinyin}</span>}
|
||||
{!pinyin && phonetic && <span style={{ color: 'var(--color-muted)' }}>/{phonetic}/</span>}
|
||||
{band && (
|
||||
<span
|
||||
className="rounded-full px-2 py-0.5 text-xs font-semibold"
|
||||
|
||||
@@ -0,0 +1,126 @@
|
||||
import type { Node as PMNode } from '@tiptap/pm/model'
|
||||
|
||||
import { mapOffset } from './SuggestionHighlight'
|
||||
import type { Segmenter } from '../../lib/segment'
|
||||
import type { HanziInfo, WordInfo } from '../../api/client'
|
||||
|
||||
// The Chinese counterpart of `wordAt` (SpellCheck.ts): given a position in the
|
||||
// document, which Chinese word is there.
|
||||
//
|
||||
// It lives in its own file rather than as a branch inside `wordAt` because the
|
||||
// two answer the same question by genuinely different means — one runs a regex
|
||||
// over the text, the other runs a shortest-path walk over a 188k-word list it
|
||||
// had to fetch — and only one of them is about spelling at all. What they share
|
||||
// is the part that matters for correctness: the offset→position mapping, which
|
||||
// is `mapOffset`, the same function the suggestion, spell and search decoration
|
||||
// layers all anchor through.
|
||||
|
||||
export interface HanziRange {
|
||||
from: number
|
||||
to: number
|
||||
word: string
|
||||
}
|
||||
|
||||
// blockAt finds the textblock containing pos, along with where that block starts
|
||||
// — everything else here is arithmetic within one block.
|
||||
//
|
||||
// Segmentation is per-block for the same reason the spell tokenizer is: a word
|
||||
// cannot span a paragraph break, and a block is the largest unit whose text is
|
||||
// contiguous in the document.
|
||||
function blockAt(doc: PMNode, pos: number): { node: PMNode; start: number } | null {
|
||||
let found: { node: PMNode; start: number } | null = null
|
||||
doc.descendants((node, nodePos) => {
|
||||
if (found) return false
|
||||
if (!node.isTextblock) return true
|
||||
if (pos <= nodePos || pos >= nodePos + node.nodeSize) return false
|
||||
found = { node, start: nodePos }
|
||||
return false
|
||||
})
|
||||
return found
|
||||
}
|
||||
|
||||
// offsetOf is the inverse of mapOffset: an absolute ProseMirror position to a
|
||||
// character offset within the block's flattened text. Inline atoms (a hard
|
||||
// break) occupy a position and contribute no text, so the two are not the same
|
||||
// number and subtracting the block position would be wrong in any paragraph
|
||||
// containing one.
|
||||
function offsetOf(block: PMNode, blockStart: number, pos: number): number {
|
||||
let textOffset = 0
|
||||
let pmPos = blockStart + 1
|
||||
let result = -1
|
||||
block.forEach((child) => {
|
||||
if (result >= 0) return
|
||||
const len = child.isText ? (child.text?.length ?? 0) : 0
|
||||
if (pos <= pmPos + child.nodeSize) {
|
||||
result = textOffset + Math.max(0, Math.min(pos - pmPos, len))
|
||||
return
|
||||
}
|
||||
textOffset += len
|
||||
pmPos += child.nodeSize
|
||||
})
|
||||
return result >= 0 ? result : textOffset
|
||||
}
|
||||
|
||||
// hanziWordAt resolves the Chinese word at a document position, or null when
|
||||
// there is no Chinese there — which is the ordinary case in a mixed paragraph
|
||||
// and is why the caller falls through to the Latin tokenizer.
|
||||
export function hanziWordAt(doc: PMNode, pos: number, segmenter: Segmenter | null): HanziRange | null {
|
||||
if (!segmenter) return null
|
||||
const block = blockAt(doc, pos)
|
||||
if (!block) return null
|
||||
const text = block.node.textContent
|
||||
if (!text) return null
|
||||
|
||||
const token = segmenter.wordAt(text, offsetOf(block.node, block.start, pos))
|
||||
if (!token) return null
|
||||
return {
|
||||
from: mapOffset(block.node, block.start, token.from),
|
||||
to: mapOffset(block.node, block.start, token.to),
|
||||
word: token.word,
|
||||
}
|
||||
}
|
||||
|
||||
// hanziToWordInfo adapts a Chinese lookup into the shape the word card already
|
||||
// renders.
|
||||
//
|
||||
// An adapter rather than a second card, because everything around the card is
|
||||
// the same in both directions: it opens the same way, anchors the same way,
|
||||
// captures into the same vocabulary garden, and reads aloud through the same
|
||||
// voice — the zh pair already speaks Chinese, so 🔊 needs nothing new to say
|
||||
// 公园 out loud. What differs is only which fields carry what.
|
||||
//
|
||||
// * `definitions` holds one entry per reading, labelled with its pinyin. The
|
||||
// part-of-speech slot is where the card puts a short italic prefix, which
|
||||
// is exactly the shape a reading label wants — and a reading *is* the thing
|
||||
// that distinguishes these senses from each other (得 dé "to obtain" from 得
|
||||
// de, the complement marker).
|
||||
// * `gloss` stays empty. It means "translated into the writer's language",
|
||||
// and for a writer learning Chinese that language is English, which is what
|
||||
// the senses already are. Putting the English there too would print it
|
||||
// twice.
|
||||
// * The per-character fallback fills the same list, labelled by character, so
|
||||
// a compound with no headword still says something true about itself.
|
||||
export function hanziToWordInfo(info: HanziInfo): WordInfo {
|
||||
const definitions =
|
||||
info.readings.length > 0
|
||||
? info.readings.map((r) => ({ part_of_speech: r.pinyin, definition: r.senses }))
|
||||
: info.chars.map((c) => ({ part_of_speech: `${c.char} ${c.pinyin}`, definition: c.senses }))
|
||||
return {
|
||||
word: info.word,
|
||||
gloss: '',
|
||||
phonetic: '',
|
||||
definitions,
|
||||
synonyms: [],
|
||||
frequency: 0,
|
||||
difficulty: -1,
|
||||
etymology: '',
|
||||
}
|
||||
}
|
||||
|
||||
// hanziPinyin is the word's own pronunciation, for the line under the headword.
|
||||
// Empty when only the character fallback answered: the characters' readings are
|
||||
// not the word's reading — 不 is bù alone and bú before a fourth tone — and
|
||||
// printing them joined up would be inventing a pronunciation.
|
||||
export function hanziPinyin(info: HanziInfo): string {
|
||||
return info.readings[0]?.pinyin ?? ''
|
||||
}
|
||||
Reference in New Issue
Block a user