` +
`` +
// ── hero ──
`
` +
- `${esc(t.eyebrow)}` +
+ `${esc(t.eyebrow)}` +
`` +
- `` +
// ── stats ──
- `` +
+ `` +
t.stats
.map(
- (s, i) =>
- `
` + - words.map((w, i) => `${esc(w)}`).join('') + + words.map((w) => `${esc(w)}`).join('') + `
` + - `${esc(t.subtitle)}
` + - `npm i ranui ranuts` +
+ `${esc(t.subtitle)}
` + + `npm i ranui ranuts` +
`` +
- `${esc(t.ctaPrimary)}${ARROW}` +
+ `
` +
// The live panel holds real ranui elements. They are inert custom elements until the
// bundle upgrades them, so this is the markup either way — no skeleton swap, and
// therefore none of the hydration mismatch the Vue version had to avoid.
- `` +
+ `${esc(t.ctaPrimary)}${ARROW}` +
`${GITHUB_MARK}${esc(t.ctaSecondary)}` +
`
` +
+ `
${esc(t.liveNote)}` +
`${esc(t.liveCheck)}
` +
`${esc(t.liveLabel)}` +
`html
` +
/*
@@ -176,11 +173,11 @@ export const renderHome = (locale: LocaleDef): string => {
`${esc(s.num)}` +
+ (s) =>
+ `` +
t.pillars
.map(
- (p, i) =>
- `` +
+ (p) =>
+ `` +
`` +
` ` +
// ── capabilities ──
- `
${esc(s.num)}` +
`${esc(s.label)}
`,
)
.join('') +
@@ -189,8 +186,8 @@ export const renderHome = (locale: LocaleDef): string => {
`${esc(p.title)}
${esc(p.desc)}
` + `${esc(p.more)} ${ARROW_SM}`, @@ -198,9 +195,9 @@ export const renderHome = (locale: LocaleDef): string => { .join('') + `` +
+ `
` +
`${esc(t.capsKicker)}
${esc(t.capsTitle)}
` + - `${esc(t.capsSub)}
` +
+ `
${esc(t.capsSub)}
` +
t.caps
.map(
(col) =>
@@ -209,8 +206,8 @@ export const renderHome = (locale: LocaleDef): string => {
`
- ` +
col.items
.map(
- (item, ii) =>
- `
- ${icon(item.kind)}` + + (item) => + `` + // ── get started ── - `
- ${icon(item.kind)}
`, ) @@ -220,19 +217,19 @@ export const renderHome = (locale: LocaleDef): string => { .join('') + `` + `${esc(item.name)}${esc(item.api)}` + `${esc(item.desc)}` + + `` + `${esc(t.startKicker)}` + - `${esc(t.startTitle)}
` + `${esc(t.startDesc)}
` + + `` + `` + // ── feature strip ── - `` + `${esc(t.startStep1)}${SNIPPET_INSTALL}` + `${esc(t.startStep2)}${SNIPPET_USE}` + + ` ` + t.features .map( - (f, i) => - ` ` + + (f) => + `` + ``, ) diff --git a/packages/docs/build/content.ts b/packages/docs/build/content.ts index 480191e77e..09e2aacbef 100644 --- a/packages/docs/build/content.ts +++ b/packages/docs/build/content.ts @@ -1,7 +1,7 @@ /** * The documentation site's page model. * - * The shape that matters here and does not exist on chaxus.com is **the locale**. Every + * Each page model includes **the locale**. Every * page belongs to one, its URL carries that locale's prefix, and the same page in * another language is a sibling reached by swapping the prefix. Getting that wrong is * not a visible bug — it is a set of hreflang tags pointing at 404s, which nobody diff --git a/packages/docs/build/langs/home-copy.ts b/packages/docs/build/langs/home-copy.ts index 38028c7eca..9c6419ab75 100644 --- a/packages/docs/build/langs/home-copy.ts +++ b/packages/docs/build/langs/home-copy.ts @@ -1,7 +1,7 @@ /** * Home page copy, per language. * - * It lives outside `HomeCinematic.vue` because eight languages of hero, pillars, + * It lives outside the home renderer because eight languages of hero, pillars, * capabilities and features is more prose than component — and because the invariant half * (which capability sits in which column, what its API signature is, where a pillar links) * must not be retyped per language, where it would drift. @@ -42,7 +42,7 @@ const STAT_NUMS = ['40', '90+', '8', 'MIT'] as const; const PILLAR_STRUCTURE = [ { kind: 'ui', link: '/src/ranui/' }, { kind: 'utils', link: '/src/ranuts/' }, - { kind: 'article', link: '/src/article/doc_preview' }, + { kind: 'article', link: '/src/design/' }, ] as const; const FEATURE_KINDS = ['agnostic', 'typed', 'pwa', 'i18n'] as const; @@ -66,7 +66,7 @@ export interface HomeStrings { ctaSecondary: string; /** Labels under `STAT_NUMS`, in that order. */ statLabels: [string, string, string, string]; - /** `{ title, desc, more }` for ranui, ranuts and the articles pillar, in that order. */ + /** `{ title, desc, more }` for ranui, ranuts and the Ran Design pillar, in that order. */ pillars: [Pair3, Pair3, Pair3]; capsKicker: string; capsTitle: string; @@ -113,11 +113,11 @@ interface Pair3 extends Pair2 { export const HOME_STRINGS: Record${esc(f.title)}
` + `${esc(f.desc)}
('[data-copy]')) { wireCopy(button, button.dataset.copy ?? ''); } - - const reveals = [...root.querySelectorAll ('[data-reveal]')]; - const reduce = window.matchMedia('(prefers-reduced-motion: reduce)').matches; - if (reduce || typeof IntersectionObserver === 'undefined') { - // Reduced motion means the end state, immediately — not "no animation, and also - // never visible", which is what skipping the observer would have produced. - for (const el of reveals) el.classList.add('in'); - return; - } - - /** Count a numeric stat up from zero. Non-numeric values ("MIT") are left alone. */ - const countUp = (el: HTMLElement): void => { - const match = /^(\d+)(.*)$/.exec(el.textContent ?? ''); - if (!match) return; - const target = Number(match[1]); - const suffix = match[2]; - const duration = 1100; - let start = 0; - const tick = (now: number): void => { - start ||= now; - const p = Math.min((now - start) / duration, 1); - const eased = 1 - (1 - p) ** 3; - el.textContent = `${Math.round(target * eased)}${suffix}`; - if (p < 1) requestAnimationFrame(tick); - }; - requestAnimationFrame(tick); - }; - - const observer = new IntersectionObserver( - (entries) => { - for (const entry of entries) { - if (!entry.isIntersecting) continue; - entry.target.classList.add('in'); - if (entry.target.classList.contains('stats')) { - entry.target.querySelectorAll ('[data-count]').forEach(countUp); - } - observer.unobserve(entry.target); - } - }, - { threshold: 0.18, rootMargin: '0px 0px -8% 0px' }, - ); - for (const el of reveals) observer.observe(el); - // The head bootstrap alone cannot prove the client can reveal hidden content. - root.dataset.revealReady = 'true'; }; const mountGlass = (): void => { diff --git a/packages/docs/cn/src/agents/index.md b/packages/docs/cn/src/agents/index.md new file mode 100644 index 0000000000..73ea92f03e --- /dev/null +++ b/packages/docs/cn/src/agents/index.md @@ -0,0 +1,31 @@ +--- +title: Agents +--- + +# Agents + +一个 ran 插件提供三个 skill：design 指导产品设计，ranui 指导组件使用，ranuts 指导工具选择。 + +[design](../design/) · [ranui](../ranui/) · [ranuts](../ranuts/) + +在仓库根目录注册当前工作副本并安装插件。 + +## Codex + +```sh +codex plugin marketplace add . +codex plugin add ran@ran +``` + +## Claude Code + +```sh +claude plugin marketplace add . +claude plugin install ran@ran +``` + +新建会话后，Codex 使用 `$design`、`$ranui` 或 `$ranuts`；Claude Code 使用 `/ran:design`、`/ran:ranui` 或 `/ran:ranuts`。 + +发布后，将市场命令中的 `.` 替换为 `chaxus/ran`。下方仓库链接指向合并后 main 分支的正式位置。 + +[plugins/ran](https://github.com/chaxus/ran/tree/main/plugins/ran) diff --git a/packages/docs/cn/src/design/index.md b/packages/docs/cn/src/design/index.md new file mode 100644 index 0000000000..55114a3093 --- /dev/null +++ b/packages/docs/cn/src/design/index.md @@ -0,0 +1,17 @@ +--- +title: Ran Design +--- + +# Ran Design + +涵盖布局、交互、动效和实际验收的方法，不依赖特定组件库。 + +先明确任务和真实内容，为整个产品确定统一的视觉语言，再在浏览器中验收完整状态，包括键盘操作和动效。具体契约见下方参考。 + +- [视觉与布局](https://github.com/chaxus/ran/blob/main/design/DESIGN.md) +- [交互](https://github.com/chaxus/ran/blob/main/design/INTERACTION.md) +- [验收](https://github.com/chaxus/ran/blob/main/design/ACCEPTANCE.md) +- [产品场景](https://github.com/chaxus/ran/blob/main/design/WORKFLOW_PATTERNS.md) +- [参考资料](https://github.com/chaxus/ran/blob/main/design/REFERENCE_RESEARCH.md) + +[ranui](../ranui/) · [ranuts](../ranuts/) · [Agents](../agents/) diff --git a/packages/docs/cn/src/ranui/api.md b/packages/docs/cn/src/ranui/api.md index 05d360e570..7d9d31979d 100644 --- a/packages/docs/cn/src/ranui/api.md +++ b/packages/docs/cn/src/ranui/api.md @@ -194,9 +194,9 @@ description: 'ranui 的全部自定义元素 —— 40 个元素的属性、属 - **插槽**: — - **Part**: `ran-icon` -> **Requires registration.** ` ` has no built-in icon set — it renders only SVGs -> registered into its in-memory registry, so ` ` is **blank** until `lock` -> is registered. Register once, in the browser, before the first ` ` connects: +> **Bundled icons are loaded on demand.** ` ` works without registration: +> its SVG is fetched on first use and cached. To register the entire bundled set eagerly, +> optionally call the following in the browser before the first ` ` connects: > > ```ts > import { registerBuiltinIcons } from 'ranui'; // or 'ranui/icons' @@ -211,7 +211,7 @@ description: 'ranui 的全部自定义元素 —— 40 个元素的属性、属 源码: `components/image/index.ts` -- **属性（attribute）**: — +- **属性（attribute）**: `alt`, `fallback`, `sheet`, `src` - **属性值（property）**: - `alt` — Alternative text forwarded to the inner ` `. Defaults to `''` (empty), - `fallback` @@ -273,7 +273,7 @@ description: 'ranui 的全部自定义元素 —— 40 个元素的属性、属 源码: `components/markdown/index.ts` -- **属性（attribute）**: `caret: string`, `content: string`, `copy`, `download`, `highlight: string | null`, `inline-math`, `line-numbers`, `link-target`, `mode: string`, `sheet: string`, `theme: string` +- **属性（attribute）**: `caret: string`, `content: string`, `copy`, `download`, `highlight: string | null`, `inline-math`, `label-copy-error`, `line-numbers`, `link-target`, `mode: string`, `sheet: string`, `theme: string` - **属性值（property）**: - `caret: string` - `content: string` — Markdown source. Resolution order: the `content` property (set via JS, not @@ -292,7 +292,7 @@ description: 'ranui 的全部自定义元素 —— 40 个元素的属性、属 - `error` · bubbles, composed · detail `{ message }` - `render` · bubbles, composed · detail `{ blocks, changed }` - **插槽**: — -- **Part**: `block`, `body`, `error`, `markdown` +- **Part**: `block`, `body`, `button`, `code`, `code-actions`, `code-header`, `code-lang`, `copy-status`, `error`, `markdown`, `table` ## `
` @@ -306,7 +306,7 @@ description: 'ranui 的全部自定义元素 —— 40 个元素的属性、属 - `error` · bubbles, composed · detail `{ message }` - `render` · bubbles, composed · detail `{ ok }` - **插槽**: — -- **Part**: `button`, `error`, `math`, `menu`, `render`, `toolbar` +- **Part**: `button`, `copy-status`, `error`, `math`, `menu`, `render`, `toolbar` ## ` ` @@ -321,13 +321,13 @@ description: 'ranui 的全部自定义元素 —— 40 个元素的属性、属 - `fullscreenchange` · bubbles, composed · detail `{ open }` - `render` · bubbles, composed · detail `{ ok }` - **插槽**: — -- **Part**: `button`, `diagram`, `error`, `menu`, `mermaid`, `toolbar` +- **Part**: `button`, `copy-status`, `diagram`, `error`, `menu`, `mermaid`, `toolbar` ## ` ` 源码: `components/message/index.ts` -- **属性（attribute）**: — +- **属性（attribute）**: `content: string | null`, `sheet: string`, `type: string | null` - **属性值（property）**: `content: string | null`, `sheet: string`, `type: string | null` - **事件**: — - **插槽**: — @@ -362,7 +362,7 @@ description: 'ranui 的全部自定义元素 —— 40 个元素的属性、属 源码: `components/select/option/index.ts` -- **属性（attribute）**: — +- **属性（attribute）**: `disabled: boolean | string | undefined | null`, `sheet`, `value` - **属性值（property）**: `disabled: boolean | string | undefined | null`, `sheet`, `value` - **事件**: — - **插槽**: `默认插槽` @@ -419,7 +419,7 @@ description: 'ranui 的全部自定义元素 —— 40 个元素的属性、属 源码: `components/progress/index.ts` -- **属性（attribute）**: `drag`, `primary` +- **属性（attribute）**: `dot: string`, `percent: string`, `sheet: string`, `total: string`, `type: string` - **属性值（property）**: `dot: string`, `percent: string`, `sheet: string`, `total: string`, `type: string` - **事件**: - `change` · element-only · detail `{ percent, total, value }` @@ -430,7 +430,7 @@ description: 'ranui 的全部自定义元素 —— 40 个元素的属性、属 源码: `components/radar/index.ts` -- **属性（attribute）**: — +- **属性（attribute）**: `abilitys`, `colorline`, `colorpolygon`, `fillcolor`, `sheet`, `strokecolor` - **属性值（property）**: `abilitys`, `colorLine`, `colorPolygon`, `fillColor`, `fontColor`, `sheet`, `strokeColor` - **事件**: — - **插槽**: — @@ -483,11 +483,11 @@ description: 'ranui 的全部自定义元素 —— 40 个元素的属性、属 源码: `components/scratch/index.ts` -- **属性（attribute）**: `disabled: boolean`, `sheet: string` -- **属性值（property）**: `disabled: boolean`, `sheet: string` +- **属性（attribute）**: `disabled: boolean`, `reveal-label`, `revealed-label`, `sheet: string` +- **属性值（property）**: `disabled: boolean`, `revealedLabel: string`, `revealLabel: string`, `sheet: string` - **事件**: — - **插槽**: `默认插槽` -- **Part**: `award` +- **Part**: `award`, `reveal-button` ## ` ` @@ -503,7 +503,7 @@ description: 'ranui 的全部自定义元素 —— 40 个元素的属性、属 源码: `components/select/index.ts` -- **属性（attribute）**: `defaultvalue`, `disabled: boolean`, `dropdownclass: string`, `getpopupcontainerid`, `label: string`, `open: boolean`, `placement: Placement`, `required: boolean`, `sheet: string`, `showsearch`, `trigger: string`, `type: string`, `value: string` +- **属性（attribute）**: `defaultvalue`, `disabled: boolean`, `dropdownclass: string`, `getpopupcontainerid`, `label: string`, `open: boolean`, `placeholder: string`, `placement: Placement`, `required: boolean`, `sheet: string`, `showsearch`, `trigger: string`, `type: string`, `value: string` - **属性值（property）**: - `defaultValue: string` - `disabled: boolean` @@ -511,6 +511,7 @@ description: 'ranui 的全部自定义元素 —— 40 个元素的属性、属 - `getPopupContainerId: string` - `label: string` — 字段上方的静态说明文字（label）。 - `open: boolean` — Whether the dropdown is showing. + - `placeholder: string` — Empty-field hint; the field's accessible name remains its label. - `placement: Placement` — Which side of the trigger the panel opens on, with an optional alignment. - `required: boolean` - `sheet: string` @@ -557,7 +558,7 @@ description: 'ranui 的全部自定义元素 —— 40 个元素的属性、属 源码: `components/tabpane/index.ts` -- **属性（attribute）**: — +- **属性（attribute）**: `disabled`, `effect`, `icon`, `iconsize`, `key`, `label`, `sheet` - **属性值（property）**: `disabled`, `effect`, `icon`, `iconSize`, `key`, `label`, `sheet` - **事件**: — - **插槽**: `默认插槽` @@ -578,7 +579,7 @@ description: 'ranui 的全部自定义元素 —— 40 个元素的属性、属 源码: `components/theme-switch/index.ts` -- **属性（attribute）**: `label-dark`, `label-light`, `label-system`, `sheet: string` +- **属性（attribute）**: `label`, `label-dark`, `label-light`, `label-system`, `sheet: string` - **属性值（property）**: - `sheet: string` - `value: RanThemeName` — Current selection; falls back to 'system' when nothing is forced. @@ -625,7 +626,7 @@ description: 'ranui 的全部自定义元素 —— 40 个元素的属性、属 - **属性（attribute）**: `active-label`, `cancel-hint`, `cancelling`, `disabled: boolean`, `hold-hint`, `holding`, `label: string`, `listening: boolean`, `sheet: string` - **属性值（property）**: - - `activeLabel: string` — Accessible name while listening; the name has to change, not only the icon. + - `activeLabel: string` — Accessible cancel/stop name while capture is pending or listening. - `cancelHint: string` — Replaces {@link holdHint} once the finger has slid far enough to discard. - `continuous: boolean` — Keep listening across pauses instead of stopping at the first one. - `disabled: boolean` diff --git a/packages/docs/cn/src/ranui/button/index.md b/packages/docs/cn/src/ranui/button/index.md index cc8e59cf0f..f940cdf4bf 100644 --- a/packages/docs/cn/src/ranui/button/index.md +++ b/packages/docs/cn/src/ranui/button/index.md @@ -53,6 +53,10 @@ description: 'ranui Button（ ）用于触发即时操作，支持多 ### 禁用状态 `disabled` +禁用按钮会阻止指针、键盘和程序化 `click()` 激活；重新启用后保留原控件及其可访问名称。 + +`focus(options?: FocusOptions)` 会聚焦可用的键盘操作区域，并转发原生聚焦选项。浮层可在关闭后调用它恢复触发按钮的焦点；禁用按钮不会获得焦点。 + 添加 `disabled` 属性可以让按钮处于不可用状态，同时按钮样式也会相应改变 diff --git a/packages/docs/cn/src/ranui/card/index.md b/packages/docs/cn/src/ranui/card/index.md index d03d05ff37..19aa8e8c7b 100644 --- a/packages/docs/cn/src/ranui/card/index.md +++ b/packages/docs/cn/src/ranui/card/index.md @@ -57,7 +57,7 @@ description: '带有页眉、主体和页脚区域的结构化内容容器，Gei ### 描述 `description` -渲染在标题下方的副标题。为空时隐藏。当 `title` 和 `description` 都未设置时，整个页眉都会隐藏。 +渲染在标题下方的副标题。为空时隐藏。只有当 `heading` 和 `description` 都为空，且 `extra` 插槽没有分配的元素时，整个页眉才会隐藏。 @@ -140,9 +140,9 @@ r-card::part(header) { ## 最佳实践 -- **标题与描述**：用 `title` 承载标题、`description` 承载简短的辅助副标题；两者都不设置时整个页眉会被隐藏。 +- **标题与描述**：用 `heading` 承载标题、`description` 承载简短的辅助副标题。两者都为空且 `extra` 插槽为空时，整个页眉会被隐藏。 - **主体内容**：把主要内容放在默认插槽里。 -- **页眉操作**：用 `extra` 插槽放置徽标、链接或对齐到页眉右侧的操作按钮。 +- **页眉操作**：用 `extra` 插槽放置徽标、链接或操作按钮；没有标题时也可单独显示。卡片较窄、同一行放不下时，操作区会换行到标题下方。 - **页脚**：用 `footer` 插槽放置次要操作或链接；在插入内容之前它会保持隐藏。 - **悬停反馈**：只给真正可点击的卡片加 `hoverable`，非交互卡片不应该响应悬停。 - **主题定制**：优先使用 CSS 变量和 `::part()` 而不是 `sheet` 属性，以获得可复用的样式方案。 diff --git a/packages/docs/cn/src/ranui/changelog.md b/packages/docs/cn/src/ranui/changelog.md index 55543f0f8b..e124475cab 100644 --- a/packages/docs/cn/src/ranui/changelog.md +++ b/packages/docs/cn/src/ranui/changelog.md @@ -9,6 +9,18 @@ description: 'ranui 的变更记录——新增、变更、修复与移除及其 ::: v-pre +## [0.5.1] — 2026-10-23 + +发布准备版本；通过验证后再发布到 npm。 + +- 保留带图标输入框的标签，修复字段布局、禁用按钮行为及键盘焦点可见性，包括弹层关闭后的焦点返回。 +- 统一嵌套弹层逐层关闭、重新连接时的节点保留，以及 Select 退出期间立即重新打开的行为。 +- 流式内容保留代码复制原文、局部失败重试反馈、原生文字选择、表格增强和阅读滚动位置。 +- 优化代码与表格的排版、内边距、焦点和触屏操作目标；产品页面布局仍由宿主负责。 +- 减少展开推理头部的重复信息，并尊重明确关闭的自动跟随。 +- 提供规范、交互和验收的唯一入口，以轻量 agent 插件按任务路由，并提供有范围说明的参考案例。 +- 协同 `ranuts@0.5.1` 和 `@alixex/ranview@0.2.1`，打包后的内部依赖使用精确版本。继续支持 Node 24+、ESM 和独立 IIFE。 + ## [0.5.0] — 2026-10-19 [ranui@0.5.0](https://www.npmjs.com/package/ranui/v/0.5.0) 已正式发布到 npm 的 `latest` 标签。 diff --git a/packages/docs/cn/src/ranui/conversation/index.md b/packages/docs/cn/src/ranui/conversation/index.md index 22038e145b..469fb87774 100644 --- a/packages/docs/cn/src/ranui/conversation/index.md +++ b/packages/docs/cn/src/ranui/conversation/index.md @@ -65,7 +65,7 @@ chat.addEventListener('pinnedchange', (e) => { }); ``` -`follow="false"` 让用户从一开始就掌握控制权；`scrollToBottom()` 把控制权收回。加载更早的内容时，在前插之前调用 `captureAnchor()`、之后调用 `restoreAnchor()`，用户就会一直看着他们正在看的那一行。 +`follow="false"` 从首次挂载到重新连接都会禁用自动跟随，包括内容和底部区域尺寸变化。显式禁用时，`pinned` 返回 `false`；切换 `follow` 导致有效状态变化时触发 `pinnedchange`。`scrollToBottom()` 显式跳到最新内容，并把 `follow` 恢复为 `true`。加载更早的内容时，在前插之前调用 `captureAnchor()`、之后调用 `restoreAnchor()`，用户就会一直看着他们正在看的那一行。 ## API 参考 diff --git a/packages/docs/cn/src/ranui/design-guides/index.md b/packages/docs/cn/src/ranui/design-guides/index.md index ecfebe8124..aa3f7846ed 100644 --- a/packages/docs/cn/src/ranui/design-guides/index.md +++ b/packages/docs/cn/src/ranui/design-guides/index.md @@ -127,12 +127,20 @@ description: '使用 ranui 构建界面：根据元素的用途选择设计令 吸顶导航之上。这个 bug 在本站上真实发生过。记得同时匹配 `closing`：`open` 被移除后，遮罩还会按过渡 时长继续绘制。 +相关组件与文档外框应共享一套视觉语言：文字角色、控件密度、圆角与内边距的关系、语义强调和动效相互协调； +表达角色与优先级的差异仍须保留。先用不同真实内容比较完整布局，再添加效果；颜色一致不能补救比例失调。 +原始来源、实际观察与验证边界集中记录在[参考索引](https://github.com/chaxus/ran/blob/main/packages/ranui/docs/REFERENCE_RESEARCH.md)。 + ## 动效 {#motion} 根据目的和使用频率决定是否需要动效。高频的悬停、聚焦和键盘反馈默认即时响应。只有动效能解释变化时， 才使用已有动效令牌：小幅过渡约 150ms、菜单约 200ms、对话框约 300ms，都是可选参考，而非必须等待的时长。 动效应能被新操作打断，并尊重 `prefers-reduced-motion`。 +修改动效前，说明触发操作、状态变化和目标位置。新操作应能打断或反向衔接，避免过期回调和重复触发； +保留草稿与阅读位置，插入或移除时避免可见文字被挤压。用连续录屏检查操作和返回路径，先正常播放， +再慢放定位不连续的瞬间。减弱动效后仍须有清晰可见的最终状态；相关组件的可选动效应保持语义一致。 + **绝不要让调色属性参与过渡。** CSS 分不清颜色**为什么**变了，所以给 `background-color`、`color`、 `border-color`、`box-shadow`、`fill`、`stroke` 加的 `transition`，在**主题**翻转时同样会触发：每个 元素按各自的时长淡变，而页面其余部分早已切换完毕。要动就动运动属性（`transform`、`opacity`、几何 @@ -213,3 +221,10 @@ display 规则、引用未声明令牌的兜底、组件查询自己的 shadow - [ ] 间距取自尺度、排版按角色、颜色用语义令牌。 - [ ] `transition` 里没有调色属性；没有 `transition: all`。 - [ ] 文案与上下文共同明确操作及对象；没有任何状态只靠颜色表达。 + +## 证据与验收 {#evidence-and-acceptance} + +[验收契约](https://github.com/chaxus/ran/blob/main/packages/ranui/docs/ACCEPTANCE.md) +统一维护实际浏览器验证、运行版本与截图的新鲜度，以及自动检查、agent 视觉审查和用户决定的区别。 +共享样式变化后，应更新受影响的证据；agent 自检不等于用户验收。 +删除没有信息增量的次级标签和说明，让布局解释显而易见的关系；保留无障碍名称、有用的字段标签、单位、错误和风险说明。 diff --git a/packages/docs/cn/src/ranui/design-system/index.md b/packages/docs/cn/src/ranui/design-system/index.md index 2b940f9301..b581b6e152 100644 --- a/packages/docs/cn/src/ranui/design-system/index.md +++ b/packages/docs/cn/src/ranui/design-system/index.md @@ -200,6 +200,8 @@ ranui 把这套阶梯落成 `--ran-*` 色阶，在其上叠加语义令牌，并 `--ran-color-primary-hover` / `-active` 是语义层里仅有的两个字面量：它们是朝页面背景方向走的，而不 是沿着某条色阶走，所以暗色模式直接重定义了它们。 +`--ran-media-background` 在两种主题下均为 `#000`。视频画布需要保持深色，以承托固定白色的播放控件；Player 的 `--ran-player-background` 派生自此令牌。这个媒体角色不会随页面配色反转。 + ### 每个色彩语义只有一个含义 - **主操作是无彩色的**：浅色下黑底白字，暗色下白底黑字（Geist 的品牌调性， diff --git a/packages/docs/cn/src/ranui/disclosure-row/index.md b/packages/docs/cn/src/ranui/disclosure-row/index.md index 89bc8a9432..4e6ca7d33c 100644 --- a/packages/docs/cn/src/ranui/disclosure-row/index.md +++ b/packages/docs/cn/src/ranui/disclosure-row/index.md @@ -133,6 +133,10 @@ row.addEventListener('disclosurebeforetoggle', async (event) => { 收起时正文是被裁切而不是被移除，这样才能做动画。同时它会被标记为 `inert`，内容用 `content-visibility: hidden` 跳过渲染，因此收起期间既不在 Tab 顺序里，也不占渲染开销。 +收起时若焦点位于正文内，会先返回该行，再把正文设为 inert；程序控制和分组联动收起也遵守此规则。 +焦点位于其他位置时不会被移动。存在 leading 内容时，键盘聚焦与悬停一样，会以箭头替换原图标， +不会把两者叠画在一起。 + 行高 24px，正好卡在 WCAG 2.5.8 的最小值上，而且行与行之间没有间隔。在粗指针（触摸）设备上默认行高会 变成 32px：命中区无法在不与上一行重叠的前提下继续扩大，而重叠只会把「目标偏小」换成「点错行」。设置 `--ran-disclosure-row-height` 可以在任何输入方式下固定行高。 diff --git a/packages/docs/cn/src/ranui/input/index.md b/packages/docs/cn/src/ranui/input/index.md index c3f1974cdf..733536ff46 100644 --- a/packages/docs/cn/src/ranui/input/index.md +++ b/packages/docs/cn/src/ranui/input/index.md @@ -53,6 +53,8 @@ description: 'ranui Input（ ）是用于键盘输入的基础表单控 ``` +标签、输入控件和提示文案各占一行。显式设置宿主高度时，输入控件填满标签和提示文案之外的剩余空间，并保留自身的最小高度。 + ### 占位提示 `placeholder` 与原生 `placeholder` 属性一致。 @@ -87,6 +89,8 @@ description: 'ranui Input（ ）是用于键盘输入的基础表单控 ### 图标 `icon` +前置图标可以与静态 `label` 同时使用。添加或更改 `icon` 会保留可见标签及其与原生输入框的关联。 + ）在内容或操作进行中展示旋 ### 属性 -| 属性 | 类型 | 默认值 | 说明 | -| ------- | -------- | ---------- | ------------------------------------------------ | -| `name` | `string` | `'circle'` | 动画类型；未设置或无法识别时回退为 `circle` | -| `sheet` | `string` | `''` | 注入组件 shadow DOM、用于外部样式定制的 CSS 文本 | +| 属性 | 类型 | 默认值 | 说明 | +| ------- | -------- | ---------- | ------------------------------------------------- | +| `name` | `string` | `'circle'` | 动画类型；未设置时为 `circle`，未知名称不渲染内容 | +| `sheet` | `string` | `''` | 注入组件 shadow DOM、用于外部样式定制的 CSS 文本 | ### 加载动画类型 `name` @@ -184,3 +184,5 @@ r-loading::part(rotate) { - **按需加载**：每个动画都是独立的懒加载 chunk（自带 JS + CSS），设置某个 `name` 只会加载它用到的那一个 variant，引用一个动画绝不会把其余 28 个也打进来。默认的 `circle` 和高频的 `dot` 内置为同步渲染，首帧即时无闪烁；其余在首次使用时异步加载。用法完全不变，设置 `name` 即可。 - **一致性**：在应用中保持一致的 CSS 变量命名模式 - **主题适配**：基础颜色跟随 `--ran-color-*` 系列主题 token，动画会自动适配浅色/深色模式 + +加载指示器是视觉反馈，宿主应为实际加载区域提供适当的 `aria-busy` 或状态通知，避免把多个动画分别设为 live region。减少动态效果时，circle、circle-fold、cube-fold、dot-bar 和 triple-bounce 保留静态可见形状；text 保持可读的字号和主题文字色。cube-dim 与 dot-line 的默认几何区域在窄父容器中收缩；已有尺寸/颜色 hooks 仍可覆盖。装饰变体保留各自的颜色，不保证每款都自动转为单色主题。 diff --git a/packages/docs/cn/src/ranui/markdown/index.md b/packages/docs/cn/src/ranui/markdown/index.md index 9046f214c7..3623dc11d4 100644 --- a/packages/docs/cn/src/ranui/markdown/index.md +++ b/packages/docs/cn/src/ranui/markdown/index.md @@ -50,7 +50,8 @@ container.append(el); ``` - **光标**：`caret` 在最后一块后显示闪烁的 `▋`，`caret="circle"` 显示 `●`。当代码围栏尚未闭合或最后一块是表格时自动隐藏。 -- **未闭合的代码围栏** 在闭合前保持纯文本（不会高亮闪烁、不会渲染半个图表），期间容器带 `data-incomplete`。 +- **未闭合的代码围栏** 在文本到达时保留同一个代码视口；图表在围栏闭合前仍显示为代码，期间容器带 `data-incomplete`。 +- 代码和表格更新会保留滚动视口及未变化的前缀文本节点。选中代码期间，待处理的高亮会延后，取消选区后再完成。 ## 代码块 @@ -66,6 +67,8 @@ container.append(el); ``` +复制和下载使用围栏内的源文本，保留制表符、空行与末尾换行。每个代码块独立显示复制成功状态；剪贴板拒绝时在代码块内显示可重试的提示，可通过 `label-copy-error` 覆盖。内容发生变化或组件断开连接后，迟到的剪贴板或高亮结果不会更新它。代码和表格视口支持键盘聚焦。 + ## Mermaid 与公式 @@ -79,20 +82,20 @@ container.append(el); ### 属性 -| 属性 | 类型 | 默认值 | 说明 | -| -------------- | ------------------------------ | ------------- | ---------------------------------------------------------------------------------------------------- | -| `content` | `string` | — | Markdown 源。`content` **property** 优先且不反射；否则回退到元素文本内容。 | -| `mode` | `'streaming' \| 'static'` | `'streaming'` | `streaming` 补全未闭合 Markdown 并按块 diff；`static` 原样整体渲染一次。 | -| `caret` | boolean / `'circle'` | 关 | 最后一块后的闪烁光标（`▋`，`circle` 时为 `●`）。 | -| `copy` | boolean | 关 | 代码块复制按钮（也透传给内嵌的 ` `）。 | -| `download` | boolean | 关 | 代码块下载按钮（按语言生成 `code. `）。 | -| `line-numbers` | boolean | 关 | 代码块行号。 | -| `highlight` | boolean / `"亮色 暗色"` 主题名 | 关 | shiki 语法高亮。空值 → `github-light github-dark`；一个名字 → 两者相同；两个名字 → 亮色 / 暗色。 | -| `inline-math` | boolean | 关 | 把 `$…$` 当作行内公式（`\(…\)` 始终是）。 | -| `link-target` | `string` | `'_blank'` | 外部链接的 `target`（附带 `rel="noopener noreferrer"`）。`_self` 不处理链接。页内 `#锚点` 永远不加。 | -| `theme` | `'auto' \| 'light' \| 'dark'` | `'auto'` | 高亮 / 图表主题。`auto` 跟随页面（`.dark`、`[data-ran-theme]`，否则 `prefers-color-scheme`）。 | -| `sheet` | `string` | — | 注入 shadow root 的额外 CSS。 | -| `label-*` | `string` | 英文 | 覆盖控件文案：`label-copy`、`label-download`。 | +| 属性 | 类型 | 默认值 | 说明 | +| -------------- | ------------------------------ | ------------- | ------------------------------------------------------------------------------------------------------- | +| `content` | `string` | — | Markdown 源。`content` **property** 优先且不反射；否则回退到元素文本内容。 | +| `mode` | `'streaming' \| 'static'` | `'streaming'` | `streaming` 补全未闭合 Markdown 并按块 diff；`static` 原样整体渲染一次。 | +| `caret` | boolean / `'circle'` | 关 | 最后一块后的闪烁光标（`▋`，`circle` 时为 `●`）。 | +| `copy` | boolean | 关 | 代码块复制按钮（也透传给内嵌的 ` `）。 | +| `download` | boolean | 关 | 代码块下载按钮（按语言生成 `code. `）。 | +| `line-numbers` | boolean | 关 | 代码块行号。 | +| `highlight` | boolean / `"亮色 暗色"` 主题名 | 关 | shiki 语法高亮。空值 → `github-light github-dark`；一个名字 → 两者相同；两个名字 → 亮色 / 暗色。 | +| `inline-math` | boolean | 关 | 把 `$…$` 当作行内公式（`\(…\)` 始终是）。 | +| `link-target` | `string` | `'_blank'` | 外部链接的 `target`（附带 `rel="noopener noreferrer"`）。`_self` 不处理链接。页内 `#锚点` 永远不加。 | +| `theme` | `'auto' \| 'light' \| 'dark'` | `'auto'` | 高亮 / 图表主题。`auto` 跟随页面（`.dark`、`[data-ran-theme]`，否则 `prefers-color-scheme`）。 | +| `sheet` | `string` | — | 注入 shadow root 的额外 CSS。 | +| `label-*` | `string` | 英文 | 覆盖控件文案：`label-copy`、`label-download`、`label-copy-error`（默认 “Could not copy. Try again.”）。 | 对应的 property：`content`、`mode`、`caret`、`copyable`、`downloadable`、`lineNumbers`、`highlight`、`inlineMath`、`linkTarget`、`theme`、`sheet`。 @@ -109,18 +112,19 @@ container.append(el); ## CSS Parts -| Part | 说明 | -| -------------- | ----------------------- | -| `markdown` | 最外层容器。 | -| `body` | 块容器。 | -| `block` | 每个渲染出的块。 | -| `code` | 代码块容器。 | -| `code-header` | 代码块的语言 / 操作栏。 | -| `code-lang` | 语言标签。 | -| `code-actions` | 操作按钮组。 | -| `button` | 每个复制 / 下载按钮。 | -| `table` | 可横向滚动的表格外层。 | -| `error` | 渲染失败时的错误框。 | +| Part | 说明 | +| -------------- | -------------------------- | +| `markdown` | 最外层容器。 | +| `body` | 块容器。 | +| `block` | 每个渲染出的块。 | +| `code` | 代码块容器。 | +| `code-header` | 代码块的语言 / 操作栏。 | +| `code-lang` | 语言标签。 | +| `code-actions` | 操作按钮组。 | +| `button` | 每个复制 / 下载按钮。 | +| `copy-status` | 就地显示的剪贴板失败提示。 | +| `table` | 可横向滚动的表格外层。 | +| `error` | 渲染失败时的错误框。 | ```css r-markdown::part(code) { @@ -137,7 +141,7 @@ r-markdown::part(code) { `--ran-markdown-code-radius`、`--ran-markdown-code-font-size`、`--ran-markdown-mono-font`、 `--ran-markdown-blockquote-border`、`--ran-markdown-table-border`、 `--ran-markdown-table-header-bg`、`--ran-markdown-caret`、`--ran-markdown-caret-color`、 -`--ran-markdown-button-color`、`--ran-markdown-error-color`。 +`--ran-markdown-button-touch-size`、`--ran-markdown-button-color`、`--ran-markdown-error-color`。 ## 说明 diff --git a/packages/docs/cn/src/ranui/math/index.md b/packages/docs/cn/src/ranui/math/index.md index c61b5cf228..279ab6d9b1 100644 --- a/packages/docs/cn/src/ranui/math/index.md +++ b/packages/docs/cn/src/ranui/math/index.md @@ -35,7 +35,7 @@ description: '使用 Temml 把 LaTeX 数学公式直接编译为原生 MathML， | `download` | `boolean` | `false` | 显示下载按钮/菜单，用于下载源码（`.tex`）和/或 MathML（`.mml`）。 | | `sheet` | `string` | `''` | 注入组件 shadow DOM 的 CSS。 | -> 💡 **提示**：`latex` 属性的 getter 会用 `decodeURIComponent` 解码后再渲染，因此支持传入 URI 编码后的公式。以 slotted 文本内容传入公式不会生效，只有 `latex` 属性的内容才会渲染。 +> 💡 **提示**：`latex` 属性的 getter 会用 `decodeURIComponent` 解码后再渲染，因此支持传入 URI 编码后的公式。没有该属性时，会使用元素的文本内容作为公式。 ### 公式 `latex` @@ -87,3 +87,9 @@ Part：`button` · `error` · `math` · `menu` · `render` · `toolbar` - **在 JavaScript 中转义反斜杠**：从 JS 字符串字面量赋值 `latex` 时，记得转义 `\`（如 `'\\frac{1}{2}'`）。 - **处理解析失败**：监听 `error` 事件（或检查渲染出的 `::part(error)` 区块），不要假设每个公式都是合法的 LaTeX。 - **通过 `sheet` 自定义布局**：需要覆盖内部 `.ran-math` 布局时使用 `sheet` 属性。 + +### 复制与窄屏 + +已开启的控件在内容上方保持可见：精细指针目标为 32px，触屏为 44px，与内容间隔 8px；未开启控件时不预留工具条空间。复制期间保留焦点并阻止重复请求；拒绝或不可用时在局部 `::part(copy-status)`（`role="status"`）显示错误，可用 `label-copy-error` 本地化，原按钮可立即重试。只有当前内容成功写入剪贴板才发出 `copied`；内容或复制目标更改后，旧请求不会再报告成功。 仅更新内容时保留原按钮及焦点，新内容可立即复制。 + +宽公式在 `::part(render)` 内独立横向滚动，不会撑宽页面；工具条不随公式滚动。 diff --git a/packages/docs/cn/src/ranui/mermaid/index.md b/packages/docs/cn/src/ranui/mermaid/index.md index 4de6a86024..28717e72ab 100644 --- a/packages/docs/cn/src/ranui/mermaid/index.md +++ b/packages/docs/cn/src/ranui/mermaid/index.md @@ -31,7 +31,7 @@ el.code = 'classDiagram\n Dog --|> Animal'; // 属性 setter 会自动 URI 编 ## 控件 -所有控件都通过布尔属性**按需开启**；不加任何控件属性的 ` ` 就是一张干净的静态图，工具栏仅在鼠标悬停时显示（右上角）。 +所有控件都通过布尔属性**按需开启**；不加任何控件属性的 ` ` 就是一张干净的静态图，已开启的工具栏在图表上方保持可见。 graph TD; A[开始] --> B[处理]; B --> C[结束] @@ -77,7 +77,7 @@ el.code = 'classDiagram\n Dog --|> Animal'; // 属性 setter 会自动 URI 编 | --------- | ------------------------ | | `mermaid` | 最外层容器。 | | `diagram` | 渲染图表的容器。 | -| `toolbar` | hover 显示的控件栏。 | +| `toolbar` | 保持可见的操作栏。 | | `button` | 每个工具栏图标按钮。 | | `error` | 渲染失败时的错误信息框。 | @@ -99,3 +99,7 @@ r-mermaid::part(toolbar) { - **懒加载**：mermaid（以及全屏功能用到的 r-modal）都是动态 import，只有在图表渲染或打开全屏时，才会作为独立的 async chunk 加载。 - **渲染保真**：`` 直接使用 mermaid 自身的渲染逻辑，支持全部图表类型与主题。 - **PNG 导出**：使用 HTML label（mermaid 的 `htmlLabels`）的图表会通过 ` ` 渲染，可能污染 canvas，导致 PNG 导出失败，此时会派发 `error` 事件。SVG 与源码导出不受影响，始终可用。 + +### 复制与窄屏 + +已开启的控件在内容上方保持可见：精细指针目标为 32px，触屏为 44px，与内容间隔 8px；未开启控件时不预留工具条空间。复制期间保留焦点并阻止重复请求；拒绝或不可用时在局部 `::part(copy-status)`（`role="status"`）显示错误，可用 `label-copy-error` 本地化，原按钮可立即重试。只有当前内容成功写入剪贴板才发出 `copied`；内容或复制目标更改后，旧请求不会再报告成功。 仅更新内容时保留原按钮及焦点，新内容可立即复制。 diff --git a/packages/docs/cn/src/ranui/popover/index.md b/packages/docs/cn/src/ranui/popover/index.md index 1b97bd7806..dfaafc3315 100644 --- a/packages/docs/cn/src/ranui/popover/index.md +++ b/packages/docs/cn/src/ranui/popover/index.md @@ -218,6 +218,11 @@ description: 'ranui Popover（ ）在悬停或点击时弹出浮动气 - **打开**：`mouseenter`（当 `trigger` 包含 `hover` 时）、`click`，或聚焦时按下 `Enter` / `Space`。 - **关闭**：`mouseleave`（hover 模式）、按下 `Escape`，或点击文档中的其他位置。 +焦点位于传送后的面板控件内时，Escape 同样能关闭面板，并把焦点还给打开它的触发器。 +嵌套弹层先处理自己的 Escape；已被处理的 Escape 或输入法组合输入不会关闭父弹层。 +立即关闭会取消排队中的入场工作，包括首个绘制帧之前。Tab 顺序与模态焦点约束仍由组合界面 +负责；Popover 不是模态对话框。 + 在内部，配套的 ` ` 元素会用 `MutationObserver` 监视自身子树，并派发一个 `change` `CustomEvent`（`detail: { type, value: { content, mutation } }`），popover 消费这个事件以保持面板同步。这是一个实现细节，而非公开 API。 无障碍访问是自动接好的：host 元素会带上 `tabindex="0"`、`aria-haspopup="dialog"`，以及会随面板开关在 `"false"` 和 `"true"` 之间切换的 `aria-expanded`。 diff --git a/packages/docs/cn/src/ranui/scratch/index.md b/packages/docs/cn/src/ranui/scratch/index.md index 54120d876d..52f82fe164 100644 --- a/packages/docs/cn/src/ranui/scratch/index.md +++ b/packages/docs/cn/src/ranui/scratch/index.md @@ -4,7 +4,7 @@ description: '一个实验性的刮刮卡组件：拖动擦除画布覆盖层， # Scratch 刮刮卡 -一个实验性的刮刮卡组件。它在 Shadow DOM 内渲染一个铺满的 ` - ${icon(item.kind)}