gis-view-webgl2 0.1.0 → 0.1.2

package/docs/steps/selftest-docs.html

@@ -121,12 +121,19 @@
 					await Promise.race([api.ready, sleep(8000)])
 					const meta = doc.querySelector('#content .meta')
 					check('文档中心：首屏 README 渲染完（行数 / 体积读数 + 标题 + 目录）', Boolean(meta) && meta.textContent.includes('README') && doc.querySelectorAll('#content h1, #content h2').length >= 2 && doc.querySelectorAll('#toc nav a').length >= 3, meta ? meta.textContent.trim().slice(0, 72) : '8 s 还没读完')
+					const pathCards = [...doc.querySelectorAll('#content .doc-path')]
+					const pathDocs = pathCards.map(card => card.dataset.doc).filter(Boolean)
+					const apiPathCard = pathCards.find(card => card.textContent.includes('查方法与参数'))
+					check('文档中心：README 顶部有 4 条推荐阅读路径，3 篇文档加 API 页都指向真实目标', pathCards.length === 4 && pathDocs.length === 3 && pathDocs.every(file => files.includes(file)) && (apiPathCard?.getAttribute('href') ?? '').includes('api/index.html') && pathCards.every(card => card.querySelector('.doc-path__badge') && card.textContent.trim().length > 12), pathCards.map(card => card.querySelector('b')?.textContent?.trim()).join(' / '))
 					check('文档中心：正文链接的解析（相对「当前那份文档」算，解析不到给 null）', api.resolve('docs/GisView.md', '../README.md') === 'GisView.md' && api.resolve('../从0到完整的实现.md', 'steps/README.md') === '从0到完整的实现.md' && api.resolve('../index.html', 'README.md') === null)
-					const fixture = api.render('## 标题\n\n| A | B |\n| --- | --- |\n| 1 | 2 |\n\n```js\nconst a = 1\n```\n\n- 一级\n  - 二级\n\n> 引用\n\n行内 `code` 与 [链接](GisView.md)\n')
-					check('文档中心：markdown 渲染器（标题 / 表格 / 带语言代码块 / 两级列表 / 引用 / 行内代码 / md 链接 / 目录）', fixture.html.includes('<table>') && fixture.html.includes('data-lang="js"') && (fixture.html.match(/<ul>/g) ?? []).length >= 2 && fixture.html.includes('<blockquote>') && fixture.html.includes('<code>code</code>') && fixture.html.includes('data-doc="GisView.md"') && fixture.toc.length === 1, `${fixture.html.length} 字符 / ${fixture.toc.length} 条目录`)
+					const fixture = api.render('# 文档标题\n\n> 一句话摘要\n\n## 标题\n\n| A | B |\n| --- | --- |\n| 1 | 2 |\n\n```js\nconst a = 1\n```\n\n- 一级\n  - 二级\n\n> 正文引用\n\n行内 `code` 与 [链接](GisView.md)\n')
+					const leadFixture = api.render('# 只有导语\n\n第一段就是全文导语。\n')
+					check('文档中心：markdown 渲染器（标题 / 表格 / 带语言代码块 / 两级列表 / 引用 / 行内代码 / md 链接 / 目录）', fixture.html.includes('<table>') && fixture.html.includes('data-lang="js"') && (fixture.html.match(/<ul>/g) ?? []).length >= 2 && fixture.html.includes('<blockquote class="doc-summary">') && fixture.html.includes('<blockquote><p>正文引用</p></blockquote>') && fixture.html.includes('<code>code</code>') && fixture.html.includes('data-doc="GisView.md"') && fixture.toc.length === 1, `${fixture.html.length} 字符 / ${fixture.toc.length} 条目录`)
+					check('文档中心：H1 后的摘要 / 首段分别套导语卡片与导语段落', leadFixture.html.includes('<p class="doc-lead">第一段就是全文导语。</p>'), leadFixture.html.slice(0, 120))
 					await api.load('数据格式.md')
 					const meta2 = doc.querySelector('#content .meta')
 					const indexLinks = [...doc.querySelectorAll('#content a[data-doc]')]
+					check('文档中心：阅读路径只在 README 首屏出现，切到其他文档后移除', doc.querySelectorAll('#content .doc-path').length === 0)
 					check('文档中心：索引页（数据格式.md）把 7 份子文档都链上了，每条都解析到清单里的真文件', Boolean(meta2) && meta2.textContent.includes('数据格式.md') && indexLinks.length >= 7 && indexLinks.every(link => files.includes(api.resolve('数据格式.md', link.dataset.doc))), meta2 ? `${indexLinks.length} 条子文档链接 / ${doc.querySelectorAll('#toc nav a').length} 条目录` : '')
 					await api.load('format/07-事件载荷与示例数据.md')
 					check('文档中心：子文档（format/07）表格与目录都渲染出来（这一份没有围栏代码，全是缩进续行）', doc.querySelectorAll('#content table').length >= 4 && doc.querySelectorAll('#toc nav a').length >= 5, `${doc.querySelectorAll('#content table').length} 表 / ${doc.querySelectorAll('#toc nav a').length} 条目录`)
@@ -373,23 +380,25 @@
 							doc.documentElement.classList.contains('theme-dark') === Boolean(docsFrame.contentWindow.matchMedia('(prefers-color-scheme: dark)').matches))
 					const progressEl = doc.querySelector('#progress')
 					const backtopEl = doc.querySelector('#backtop')
+					const backtopPercentEl = doc.querySelector('#backtop-percent')
 					docsFrame.contentWindow.scrollTo(0, 4000)
 					api.syncScrollReadouts()
 					const scrolledWidth = progressEl.style.width
 					const backtopOn = backtopEl.classList.contains('on')
+					const scrolledPercent = backtopPercentEl?.textContent ?? ''
 					docsFrame.contentWindow.scrollTo(0, 0)
 					api.syncScrollReadouts()
 					check('文档中心：顶部进度条跟着滚动长、「回到顶部」滚下去才出现（回顶后收回去）',
 							scrolledWidth !== '' && scrolledWidth !== '0%' && scrolledWidth !== '0.00%' && backtopOn &&
-							parseFloat(progressEl.style.width || '0') === 0 && !backtopEl.classList.contains('on'),
-							`滚下去 ${scrolledWidth} / 回顶 ${progressEl.style.width} · 按钮 ${backtopOn ? '在' : '不在'}`)
+							parseInt(scrolledPercent, 10) > 0 && parseFloat(progressEl.style.width || '0') === 0 && backtopPercentEl?.textContent === '0%' && !backtopEl.classList.contains('on'),
+							`滚下去 ${scrolledWidth} / ${scrolledPercent} · 回顶 ${progressEl.style.width} · 数字 ${backtopPercentEl?.textContent} · 按钮 ${backtopOn ? '在' : '不在'}`)
 					/* ---- 这一轮加的：文档页的观感（侧栏计数 / 元信息胶囊 / 代码块头部 / 空态 / 「/」快捷键） ---- */
 					const counts = [doc.querySelector('#doc-count')?.textContent, doc.querySelector('#page-count')?.textContent]
 					check('文档中心：侧栏两个分组标题上挂着计数（数得跟清单一样）', counts[0] === String(api.docs.length) && counts[1] === String(api.pages.length), counts.join(' / '))
 					await api.load('GisView.md')
 					const chips = [...doc.querySelectorAll('#content .meta > *')]
-					check('文档中心：正文开头那行元信息是几枚胶囊（文件 / 行数 + 体积 / 小节数 / 代码块数 / 看原文）',
-						chips.length === 5 && chips[0].textContent === 'GisView.md' && /\d+ 行 \/ [\d.]+ KB/.test(chips[1].textContent) && /\d+ 个小节/.test(chips[2].textContent) && /\d+ 段代码/.test(chips[3].textContent) && chips[4].textContent === '看原文',
+					check('文档中心：正文开头那行元信息是几枚胶囊（文件 / 行数 + 体积 / 阅读时长 / 小节数 / 代码块数 / 看原文）',
+						chips.length === 6 && chips[0].textContent === 'GisView.md' && /\d+ 行 \/ [\d.]+ KB/.test(chips[1].textContent) && /^约 \d+ 分钟$/.test(chips[2].textContent) && /\d+ 个小节/.test(chips[3].textContent) && /\d+ 段代码/.test(chips[4].textContent) && chips[5].textContent === '看原文',
 						chips.map(node => node.textContent).join(' | ').slice(0, 120))
 					check('文档中心：语言徽标与「复制」都收在代码块头部那一条里（一块只有一个按钮）',
 						[...doc.querySelectorAll('#content .code')].every(block => block.querySelector('.code-head > button') && block.querySelectorAll('button').length === 1),
@@ -409,6 +418,39 @@
 					searchInputEl.value = ''
 					searchInputEl.dispatchEvent(new Event('input', { bubbles: true }))
 					await api.load('README.md')
+					/* 390px 视口回归：窄屏时侧栏排在正文上方，首屏不能被 content.scrollIntoView 带过目录 */
+					const mobileFrame = document.createElement('iframe')
+					mobileFrame.title = '文档中心 390px'
+					mobileFrame.style.width = '390px'
+					mobileFrame.style.height = '760px'
+					mobileFrame.src = '../index.html?selftest=390'
+					document.body.append(mobileFrame)
+					const mobileReady = await waitFor(() => {
+						const win = mobileFrame.contentWindow
+						return win?.__gisDocs && mobileFrame.contentDocument?.querySelector('#content .meta') ? win : null
+					})
+					await sleep(350)
+					const mobileWin = mobileReady
+					const mobileDoc = mobileFrame.contentDocument
+					const initialScroll = mobileWin.scrollY
+					const initialOverflow = mobileDoc.documentElement.scrollWidth > mobileDoc.documentElement.clientWidth + 1
+					check('文档中心：390px 首屏停在页面顶部（不被正文 scrollIntoView 带过目录）', initialScroll === 0 && mobileWin.history.scrollRestoration === 'manual', `scrollY=${initialScroll} / ${mobileWin.history.scrollRestoration}`)
+					check('文档中心：390px 首屏无横向溢出', !initialOverflow && mobileWin.innerWidth < 941, `视口 ${mobileWin.innerWidth}px / ${mobileDoc.documentElement.scrollWidth}px`)
+					const deepUrl = new URL('../index.html?selftest=deep', location.href)
+					deepUrl.hash = `${encodeURIComponent('manual/15-导出与集成.md')}~${encodeURIComponent('插件')}`
+					const mobileReloaded = new Promise(resolve => mobileFrame.addEventListener('load', resolve, { once: true }))
+					mobileFrame.src = deepUrl.href
+					await mobileReloaded
+					const deepReady = await waitFor(() => {
+						const win = mobileFrame.contentWindow
+						return win?.__gisDocs && mobileFrame.contentDocument?.querySelector('[data-slug="插件"]') ? win : null
+					})
+					await sleep(350)
+					const deepDoc = mobileFrame.contentDocument
+					const deepTarget = deepDoc.querySelector('[data-slug="插件"]')
+					const deepTop = deepTarget?.getBoundingClientRect().top ?? -1
+					check('文档中心：390px 深链仍落到对应小节（顶栏下 72px）', deepReady.__gisDocs.current() === 'manual/15-导出与集成.md' && deepReady.scrollY > 0 && deepTop >= 60 && deepTop <= 90, `${deepReady.__gisDocs.current()} / scrollY=${Math.round(deepReady.scrollY)} / top=${Math.round(deepTop)}`)
+					mobileFrame.remove()
 				}
 				/* ---------------- 图解页：docs/guide/sample-document.html ---------------- */
 				const guideFrame = document.querySelector('#guide-frame')
@@ -476,21 +518,39 @@
 				if (check('API 速查：挂上了 __gisApi 钩子（数据来自 api-index.js，没钩子多半是 file:// 打开的）', Boolean(apiHook))) {
 					const apiDoc = apiFrame.contentDocument
 					const summary = apiHook.summary
-					check('API 速查：清单来自 api-index（243 个成员 / 87 个 options / 14 个分组）',
-						summary.members === 243 && summary.options === 87 && summary.sections === 14,
+					check('API 速查：清单来自 api-index（249 个成员 / 92 个 options / 16 个分组）',
+						summary.members === 249 && summary.options === 92 && summary.sections === 16,
 						JSON.stringify(summary))
-					check('API 速查：分组都渲染出来（14 组 + options 一组）',
-						apiDoc.querySelectorAll('.api-group').length === 15 && apiDoc.querySelectorAll('.api-group > h2 b').length === 15,
+					check('API 速查：左侧分组有当前项，滚动 / 点选时会跟着亮', apiHook.activeGroup() !== null, String(apiHook.activeGroup()))
+					check('API 速查：分组都渲染出来（16 组 + options 一组）',
+						apiDoc.querySelectorAll('.api-group').length === 17 && apiDoc.querySelectorAll('.api-group > h2 b').length === 17,
 						`${apiDoc.querySelectorAll('.api-group').length} 组`)
 					check('API 速查：成员卡片全在（方法与属性按清单来）',
 						apiDoc.querySelectorAll('.api-member').length === summary.members && apiDoc.querySelectorAll('.api-member[data-kind="property"]').length === summary.properties,
 						`${apiDoc.querySelectorAll('.api-member').length} 张卡片 / 属性 ${apiDoc.querySelectorAll('.api-member[data-kind="property"]').length} 张`)
 					const noExample = [...apiDoc.querySelectorAll('.api-member')].filter(node => Number(node.dataset.examples) < 1)
 					check('API 速查：每个成员都带至少一段示例（不出现空卡片）', noExample.length === 0,
-						noExample.length ? noExample.map(node => node.dataset.name).join(' / ') : '243 张卡片都有示例')
-					check('API 速查：87 个 options 都列全（名字 / 类型 / 默认值 / 说明四件套）',
+						noExample.length ? noExample.map(node => node.dataset.name).join(' / ') : '249 张卡片都有示例')
+					check('API 速查：92 个 options 都列全（名字 / 类型 / 默认值 / 说明四件套）',
 						apiDoc.querySelectorAll('.api-option').length === summary.options && [...apiDoc.querySelectorAll('.api-option')].every(node => node.querySelector('.name code') && node.querySelector('.type') && node.querySelector('.def') && node.querySelector('.doc')),
 						`${apiDoc.querySelectorAll('.api-option').length} 个`)
+					const statCards = [...apiDoc.querySelectorAll('#stats .api-stat')]
+					const optionStat = statCards.find(node => node.dataset.stat === 'options')
+					check('API 速查：首屏统计卡为六张，options 卡读数与清单一致',
+						statCards.length === 6 && statCards.map(node => node.dataset.stat).join(',') === 'members,methods,properties,options,sections,examples' && (optionStat?.textContent ?? '').includes(String(summary.options)),
+						`${statCards.length} 张 / ${optionStat?.textContent ?? '缺 options 卡'}`)
+					const optionHead = apiDoc.querySelector('.option-table > .option-head')
+					check('API 速查：options 用四列表头（字段 / 类型 / 默认值 / 说明）',
+						optionHead?.children.length === 4 && [...optionHead.children].map(node => node.textContent).join(',') === '字段,类型,默认值,说明',
+						`${optionHead?.children.length ?? 0} 列`)
+					check('API 速查：成员卡片都带参数 / 返回签名网格',
+						apiDoc.querySelectorAll('.api-member .signature-grid').length === summary.members && [...apiDoc.querySelectorAll('.api-member .signature-grid')].every(node => node.children.length === 2),
+						`${apiDoc.querySelectorAll('.api-member .signature-grid').length} 张`)
+					const memberExamples = [...apiDoc.querySelectorAll('.api-member .example')]
+					check('API 速查：示例改为可折叠 details，首段默认展开且仍保留运行按钮',
+						memberExamples.length > 0 && memberExamples.every(node => node.tagName === 'DETAILS') && memberExamples[0]?.open === true &&
+						apiDoc.querySelectorAll('.api-member .example .try-code').length === memberExamples.length,
+						`${memberExamples.length} 段 / 首段展开 ${memberExamples[0]?.open === true}`)
 					check('API 速查：代码块带高亮，每段示例都有复制按钮',
 						apiDoc.querySelectorAll('.example pre code .tok-fn').length > 0 && [...apiDoc.querySelectorAll('.example')].every(node => node.querySelector('button')),
 						`${apiDoc.querySelectorAll('.example').length} 段示例`)
@@ -529,6 +589,18 @@
 						apiDoc.querySelectorAll('.api-member .try-code').length === apiDoc.querySelectorAll('.api-member .example').length &&
 						apiOpens.length === 1 && apiOpens[0].includes('playground/index.html?from=api') && stashed.includes('updateLine'),
 						`${apiDoc.querySelectorAll('.api-member .try-code').length} 个按钮 / ${apiOpens.join(',')}`)
+					const themeBefore = apiHook.theme()
+					apiHook.setTheme('dark')
+					await settle(apiFrame.contentWindow, 1)
+					const darkThemeApplied = apiDoc.documentElement.classList.contains('theme-dark') && apiDoc.querySelector('#theme-btn')?.textContent === '主题：深色'
+					const storedTheme = JSON.parse(apiFrame.contentWindow.localStorage.getItem('gisDocs.reading') ?? 'null')?.theme
+					apiHook.setTheme('light')
+					await settle(apiFrame.contentWindow, 1)
+					const lightThemeApplied = !apiDoc.documentElement.classList.contains('theme-dark') && apiDoc.querySelector('#theme-btn')?.textContent === '主题：浅色'
+					apiHook.setTheme(themeBefore)
+					check('API 速查：深 / 浅主题切换生效并写进文档中心共用的阅读设置',
+						darkThemeApplied && lightThemeApplied && storedTheme === 'dark',
+						`深色 ${darkThemeApplied} / 浅色 ${lightThemeApplied} / 存储 ${storedTheme}`)
 				}
 				/* ---------------- 调试演示页：docs/playground/index.html ---------------- */
 				const playFrame = document.querySelector('#playground-frame')
@@ -540,7 +612,7 @@
 						Boolean(playView) && playView.getData().points.length === 3 && playView.getData().lines.length === 3 && playView.getChannels().length === 2,
 						`${playView?.getData().points.length} 点 / ${playView?.getChannels().length} 组`)
 					check('调试演示页：示例下拉有货，编辑器默认载入欢迎示例', playHook.sampleNames().length >= 5 && (playHook.getCode() ?? '').includes('view.'), `${playHook.sampleNames().length} 个示例`)
-					await playHook.run('view.setPointColor(\'a\', \'#123456\')\nview.getData().points.length')
+					await playHook.run('view.updatePoint(\'a\', { color: \'#123456\' })\nview.getData().points.length')
 					await settle(playFrame.contentWindow, 1)
 					const playOut = playDoc.querySelector('#out').textContent
 					check('调试演示页：run(code) 改到真实视图，最后一行返回值打在输出区',
@@ -550,12 +622,13 @@
 					await settle(playFrame.contentWindow, 1)
 					const playErr = playDoc.querySelector('#out').textContent
 					check('调试演示页：代码报错打在输出区（红字 + 不炸整页）', playErr.includes('noSuchMethod') && playDoc.querySelector('#out .err') !== null, playErr.split('\n')[0])
+					const playCanvasCount = playDoc.querySelectorAll('#map canvas').length
 					await playHook.run('createGisView(\'#map\', {})\nview.getData().points.length')
 					await settle(playFrame.contentWindow, 1)
 					check('调试演示页：示例里的 createGisView(\'#map\') 沿用右边这份视图（不会新开一块画布）',
-						playDoc.querySelectorAll('#map canvas').length === 1 && (playDoc.querySelector('#out').textContent ?? '').includes('3'),
-						`画布 ${playDoc.querySelectorAll('#map canvas').length} 块`)
-					playHook.setCode('view.setPointColor(\'b\', \'#00aa88\')')
+						playDoc.querySelectorAll('#map canvas').length === playCanvasCount && (playDoc.querySelector('#out').textContent ?? '').includes('3'),
+						`画布 ${playCanvasCount} → ${playDoc.querySelectorAll('#map canvas').length} 块`)
+					playHook.setCode('view.updatePoint(\'b\', { color: \'#00aa88\' })')
 					check('调试演示页：setCode 换编辑器内容（深链 #code= 与 API 页带过来的代码都走它）', playHook.getCode().includes('00aa88'))
 					playHook.reset()
 					await settle(playFrame.contentWindow, 1)

package/docs/steps/selftest-effects.html

@@ -284,19 +284,19 @@
 					JSON.stringify({ point: stats.pointEffectCount, line: stats.lineEffectCount }))
 				const still = view.getEffects()
 				check('关掉一层之后 getEffects 读得出来（point 为 null）', still.point === null && still.line.period === 1, JSON.stringify({ point: still.point, period: still.line?.period }))
-				view.setEffects(false)
+				view.updateOptions({ effects: false })
 				await advance(60, 2)
 				stats = view.getStats()
-				check('setEffects(false) 一处关掉：动点与涟漪都收掉、动画停下',
+				check('effects: false 一处关掉：动点与涟漪都收掉、动画停下',
 					stats.lineEffectCount === 0 && stats.pointEffectCount === 0 && stats.animating === false && view.getLineEffects().length === 0,
 					JSON.stringify({ line: stats.lineEffectCount, point: stats.pointEffectCount, animating: stats.animating }))
 				check('总开关关着时 getEffects.enabled 为 false', view.getEffects().enabled === false)
-				view.setEffects({ line: { period: 1 }, point: { radius: 18 } })
+				view.updateOptions({ effects: { line: { period: 1 }, point: { radius: 18 } } })
 				await advance(60, 2)
 				stats = view.getStats()
 				check('再次打开：动点与涟漪都回来', stats.lineEffectCount === 1 && stats.pointEffectCount === 3,
 					JSON.stringify({ line: stats.lineEffectCount, point: stats.pointEffectCount }))
-				check('getOptions 与 setEffects 一致（配置记进了 current）', view.getOptions().effects?.line?.period === 1, JSON.stringify(view.getOptions().effects?.line?.period))
+				check('getOptions 与 updateOptions({ effects }) 一致（配置记进了 current）', view.getOptions().effects?.line?.period === 1, JSON.stringify(view.getOptions().effects?.line?.period))
 
 				/* ---------------- 引擎：全局什么都不配，只在数据里逐条配 ---------------- */
 				// 需求里的第二种写法：不动全局缺省，写在哪条上哪条就动（全局没配不代表关掉）
@@ -317,7 +317,7 @@
 				const soloEffects = solo.getEffects()
 				check('这一份的 getEffects：总开关为真、两层缺省都是 null（画什么全看逐要素）',
 					soloEffects.enabled === true && soloEffects.line === null && soloEffects.point === null, JSON.stringify(soloEffects))
-				solo.setEffects(false)
+				solo.updateOptions({ effects: false })
 				await advance(60, 2)
 				check('显式 effects: false 连逐要素配的一起关掉（一处关掉的语义）',
 					solo.getStats().lineEffectCount === 0 && solo.getStats().pointEffectCount === 0 && solo.getStats().animating === false,