jg-react-ui
以消费者为主题的React组件，保留了源自moldea的api。
安装
pnpm add jg-react-ui
用法
import { createElement } from 'react';
import { Button } from 'jg-react-ui/components/button';
const saveAction = createElement(Button, { size: 'touch' }, 'Save changes');
那么，进口一次顺风吧 jg-react-ui/styles.css． 供应 --background， --foreground， --primary， --primary-foreground， --secondary， --secondary-foreground， --destructive， --chart-1 (成功), --chart-2 (警告) --border， --radius， --jg-ui-font-sans， --jg-ui-font-mono， --jg-ui-shadow-inset， --jg-ui-shadow-surface， --code， --code-foreground， --jg-ui-shadow-raised, --jg-ui-inverse-color-scheme 在你自己的主题里。颜色必须是完整的CSS颜色值。 .dark 选择暗效用变量；这个包不提供品牌调色板。对于JG调色板和字体，使用 jg-personal-react-ui 代替。
Button, Badge， IconTile和Alert在提交时保留Moldea的api 2920a7b0a6e814e95872fcdd6dd8746ae422c038，包括变体，大小，refs，徽章，和 asChild 支持的地方。导出的 badgeVariants， iconTileVariants, alertVariants 保留它们的源签名。Badge默认为span；IconTile是装饰性的，除非 aria-hidden={false} 提供;静态警报使用 role="alert"，带有短语内容标题和描述槽。在粗糙的指针下，按钮的触摸大小至少保持44px，包括在平板电脑上。按钮的 asChild 只需要一个元素，并保留Base UI的按钮语义，包括当该元素是锚点时。使用孩子的显式 role="link" 当它表示导航时。
在服务器呈现期间导入所有JavaScript条目都是安全的。样式仍然是显式的CSS导入。UI首选项模式保留完整的主题、diff布局、包装和安装-卸载记录；解散时间戳是一个ISO日期时间字符串或 null． 提供程序为每个挂载的树创建存储，并且在渲染期间不执行浏览器存储I/O。
首选项、主题和通知都来自同一个固定的Moldea提交。包适应将全局存储和私有应用程序注册中心替换为提供者本地ssr安全存储和限定范围的错误反馈，根据jg-storage的规则验证捕获的名称空间，保留取消，并允许显式 null 解雇重置。主题效果使用React的浏览器生命周期，通知主机保留配置的字体，并融入正文门户。
警徽和警报 asChild 也只需要一个元素，否则会抛出 Error("asChild requires exactly one valid React element child.")． 为 interaction="redirect"，开锚；为 interaction="action"，插入本地按钮。交互选项提供样式，而本机子选项提供键盘语义。继续补充 AlertAction 控件，远离交互式父按钮或锚。默认情况下，链接的Badge保持紧凑；当它是一个独立的触摸目标时，添加粗指针最小尺寸。
ErrorFeedbackProvider将应用程序拥有的错误拷贝和访问丢失分类作用到一个React树中。传递解析器 createErrorFeedback 在 jg-exception； useErrorFeedbackResolver 读取最近的政策。如果没有提供程序，未知的诊断和代码将保持在通用副本之后的私有状态。取消保持可识别性，抛出应用程序策略安全返回。
首选项、主题和通知
组成 UiPreferencesProvider， ThemeProvider，还有一个 Toastr 宿主按这个顺序。 ThemeToggleButton 保留源按钮道具和请求回调。文档主题和Sonner通知通道是文档范围的；即使挂载了独立的首选项根，也要为每个文档保留一个主题所有者和一个通知主机。
Sonner在其浏览器模块加载时注入其基本通知CSS。包主题样式仍然是显式导入。所有JavaScript条目都是可导入的，服务器上没有浏览器全局变量。
首选项提供程序支持显式 local， read-only, remote 模式。本地模式读取和写入最努力的浏览器存储，并遵循匹配的跨选项卡事件。只读模式只公开快照，不允许更新。远程模式需要完成 initialPreferences 还有async persistPreferences 适配器：更新是乐观的，保存顺序运行并合并更新的快照，被拒绝的保存回滚到最新的权威道具。应用程序拥有网络请求和缓存无效。挂起的请求在卸载后无法更新存储或显示通知。
可选 storageId 默认为 jg-ui-preferences． 只能包含ASCII字母、数字、“_”和“-”，不能为空。 getUiPreferencesStorageKey 返回原始数据 jg-storage: 关键。在提供程序生命周期内捕获id；使用键重挂载来更改名称空间。无效id在存储访问或初始化脚本创建之前失败。
渲染 ThemeInitializationScript 在应用程序JavaScript之前的文档头部，使用相同的 storageId 作为提供商和您的CSP nonce 在需要时。服务器快照使用初始道具或默认值，然后存储在聚合后同步。请参阅配方的组成和共享 自有错误契约。
控件、窗体和纯文本
表单、选择/选择控件、选项卡、下拉菜单、工具提示、复制反馈、进度、分隔符、空状态、链接、内联代码和普通的排版/表原语保留相同的固定的Moldea api。应用程序拥有表单验证和关联。设置应用的根目录 font-sans bg-background text-foreground 类，同时提供阴影角色和代码颜色角色，并围绕紧凑的复选框/单选/开关符号组成标记的触摸行。字段在粗指针下使用至少16px的文本；触摸选项卡和菜单行保留44px目标。 tw-animate-css 通过显式的包样式表提供保留的进入/退出动画实用程序。
TabsList 需要 overflowBehavior: 'scroll' | 'truncate';截断列表中的复合标签需要 title 或 aria-label． 选择并菜单取消别名，以尊重有意取消。Select保持源的接受 forceMount/sticky 别名，没有额外的基本UI行为。插槽控件需要一个有效的元素，并保留其特定于组件的本机错误保护。菜单和工具提示保留了它们的门户和定位api。
CopyButton 在初始化手势期间写入准确的文本，阻止重叠的写入，并在完成后开始反馈。它的反馈持续时间保持毫秒级。 copyLabel 提供一个作用域的就绪名称，可见 label/copiedLabel 并且保留本地命名覆盖，失败使用最近的错误策略，取消保持沉默。它清除计时器并忽略卸载后的延迟反馈。TextLink增加了安全的rel令牌和一个新标签公告；TableContainer接受键盘可滚动表的本地区域/名称/焦点道具。
对话框、抽屉和布局
Dialog、AlertDialog、Drawer、ConfirmationDialog和page/layout原语保留了固定的复合api。DialogContent需要一个大小和直接的DialogHeader， DialogBody和可选的DialogFooter子元素；asChild接受一个包含这些区域的面板元素。使用允许对话框角色的元素，例如div；在主体中放置一个表单，并将固定的提交操作与其表单ID关联起来。 抽屉需要一个边，它的内容需要一个大小，它的直接区域顺序是页眉，正文，可选页脚。AlertDialogContent需要直接的页眉和页脚。无效的组合和无效的槽子保留本地错误保护。
中型和大型对话框成为手机上的全屏页面，具有生成的后退和桌面关闭控件。正文区域拥有滚动，而标题和操作保持固定。紧凑模态关闭控件保留其精细指针外观，并在粗指针下具有实际的44px目标。默认的初始焦点会跳过不可用的控件；initialFocus和生成的控件图标/标签仍然可配置。默认情况下，对话框的覆盖解除是禁用的。 isDismissalDisabled阻止页面上的解雇；已提交导航仍然会取消过时的对话框。
DialogNavigationProvider、DialogNavigationObserver和usedialognavigation解雇直接重用了js -react-router的实现和上下文。将观察者放置在路由器中，并在同一个提供商下使用持久的对话框主机。取消导航不会创建历史记录项。宿主应用程序拥有路由历史记录及其导航UI；drawer通过显式的drawclose组合或应用程序状态关闭路由操作。
每个文档挂载一个ConfirmationDialog并使用useConfirmationDialogStore.getState(). openconfirmationdialog （options）。这个命令式存储保留了源文件范围的会话API；在服务器呈现时不要改变它。Completion在调用应用程序回调之前重置会话，在确认时接收true，在取消时接收undefined。应用程序拥有异步工作和回调错误。 受控对话子框通过关闭过渡保持不变，然后在完成时释放。移动返回快照忽略陈旧的回调，并在运动减少或不支持的浏览器中跳过。
PageShell, PageHeader, PageHeaderRow, PageHeaderTitleGroup, PageHeaderMetadata, PageTitle, PageDescription, Stack， Inline和Surface保留了本地的语义道具和共享的几何形状。Supply -jg-ui-shadow-surface以及其他通用主题角色。样式表提供源页行距和抽屉行距挂钩；它不会重置文档的调色板或排版。
路由和查询恢复
RouterRoot 保留源数据-路由器出口、挂起的进程和共享对话观察器。它需要React Router的数据路由器和共享路由器peer。路线进度尊重顶部安全区域的插入。它不添加历史条目或更改页面焦点/滚动策略；组成 jg-react-router的 PageOutlet 当主人想要那样做的时候。 GlobalErrorBoundary 读取抛出的路由错误，将其标记为recovery main，保留本地refs，并取消过时的对话会话； GlobalErrorBoundaryView 接受不带路由器上下文的显式错误。恢复默认为 jg-sw的 updateApp，带有可选的 onRefreshClick． 未知错误和恢复失败使用范围安全反馈。挂起的刷新和重试操作忽略重叠的单击。
QueryBoundary， QueryLoader， LoadMoreButton， QueryErrorAlert, QueryErrorToastr 保留结构化查询api。边界将初始解析委托给 jg-tanstack-query的共享钩子：陈旧的未经批准的数据等待，当前的数据在后台故障中幸存下来，一个新的 resolutionKey 重新开始，访问丢失会立即隐藏数据。访问丢失后，调用方审批无法恢复数据，直到每个查询都成功解决当前数据。最近的 ErrorFeedbackProvider 拥有访问丢失分类和可见副本；这些包中没有应用程序注册表。
默认的错误槽是内联阻塞/保留警报。自定义渲染器可以使用持久化 QueryErrorToastr 对于保留的内容。提供独一无二的马厩 toastId 每个活动故障所有者和一个 Toastr 每个文件的主机。Toast发布遵循提交效果，因此后安装的主机接收初始失败，并且取消过时的排队反馈。重试读取最新提交的查询和策略，忽略活动读取/重叠重试，并保持故障可操作，直到恢复；卸载清理保留相同id的替换。重试解决每个失败的查询，包括被拒绝或同步抛出的适配器。取消的错误不会产生中断警报或吐司。 Load-more click回调先运行，并可能取消请求 preventDefault。
默认的紧凑分页和恢复操作保留了它们的精细指针几何形状，并且在粗指针下至少有44px的目标。JG的全球恢复表面在两个主题中都使用了基础的反向调色板。通用消费者集 --jg-ui-inverse-color-scheme 来匹配它们的恢复面(dark 或 light）; 选择和聚焦发挥了它的主要作用。查询客户机、网络适配器、分页限制、应用程序代码映射和路由历史记录仍然是主机所有的。
文件上传和音频输入
FileUpload， FileUploadDialog， ImageUploadField, AudioInput 保留固定的源道具和回调。文件上传重用 jg-react允许、并发、进度、取消和重试队列。调用方提供验证和传输回调；不包括端点、授权策略、存储服务或转录提供程序。上传适配器必须遵守其中止信号。image字段显示调用者的当前图像，并在预览失败时安全返回；调用者拥有对象URL的创建和撤销。
上传对话框通过完成成功的结果 onSubmit重试结束而不重新加载，并通过报告放弃的成功项目 onDiscard． 调用方拥有远程清理和回调失败。音频输入拥有麦克风轨道、记录器处理程序、波形上下文、间隔和延迟命令。废弃的权限/转录结果在卸载后无法更新替换会话或调用完成。记录复位是即时的；关闭保留了源的短视觉复位延迟。
transcribe 接收捕获的记录并返回文本。用户可以直接发送或先编辑抄本；发送失败会重试已编写的文本，而不会再次转录。提供者操作仍然是调用者所有的，并且应该有自己的截止日期/取消策略。记录/转录错误回调接收诊断异常，而可见反馈使用最近的作用域解析器。七个拥有的音频代码和稳定消息列在 errors/README.md;编码提供程序异常保留其诊断标识。取消的许可/转录工作保持沉默，可以重新启动；诊断回调仍在运行。可选的结果回调仍然是可选的。独立审查仍然是默认的。供应 onTranscriptionApply 将转录结果直接放在主输入while中 onTranscriptionResult 句柄分别发送； isResultActionVisible={false} 使用转录作为唯一的结果操作。进度保持在活动按钮上，屏幕阅读器提示。待处理的工作阻止解雇和重新启动。
降价和编码
Markdown 保留GFM表/任务列表，标题和散文渲染，大写模板变量高亮，图像宽度提示(title="width=560")，渲染器/插件覆盖，以及独立的YouTube链接。默认情况下跳过原始HTML。默认情况下，HTTP(S)和相关文档链接在安全的新选项卡中打开，并附有可访问的公告；片段和非web链接保留在当前选项卡中。集 shouldOpenLinksInNewTab={false} 或者为应用程序路由提供一个锚呈现器。应用程序拥有自定义插件、URL转换和呈现器的信任策略。
消息列需要 min-width: 0;网格轨道使用 minmax(0, 1fr)． Markdown和InlineCode包装了长路径和不间断的令牌。InlineCode保留首选分隔符而不更改复制的文本。代码块和表包含它们自己的水平滚动；标记表有标记，键盘可聚焦的滚动组。未标记的栏仍然是带有精确空格的预格式化代码块。
CodeBlock 和 CodeFileHeader 保留元数据/状态/操作槽、别名、语法高亮、文字纯模式、自定义复制文本和包装控件。声明的散文语言或散文文件扩展名自动包装。 prefersWrappedCode 优先于 shouldWrapContent，然后是自动散文包装和作用域保存首选项。显式覆盖和只读提供程序隐藏了突变控制。 diff 和 diff-<language> 栅栏保留源代码结尾、补丁标记和多行语法。 CodePreferencesControls 还公开源表面的拆分/统一首选项菜单。紧凑动作保持源精细指针几何形状，并使用44px粗指针目标。
个人适配器将语法和文件状态角色映射到 jg-personal-ui现有的主题令牌。泛型语法使用无标记的One-theme回调；供应 --syntax-foreground 和 --syntax-token-{keyword,string,string-expression,comment,function,constant,parameter,punctuation,link} 来推翻他们。在呈现过程中重用令牌映射，并且记住未更改的Markdown解析器输入。每个语法/样式导入都为它的JavaScript文件命名，因此Node导入不需要更改消费者解析器。
parseYouTubeVideoUrl 验证支持的HTTPS单视频链接并返回一个标记标识符。 YouTubeVideo 使用固定的隐私增强源，剥离授权的播放参数，并仅通过其显式prop启用自动播放。URL验证/构建重用 jg-utilities，保留UI的更窄的路由策略。伪造的无效标识符将导致依赖项的文档化 INVALID_YOUTUBE_VIDEO_ID 合同。
代码差别
CodeDiff 运行下 UiPreferencesProvider 和 ThemeProvider． 它保留了源元数据、上游查看器控件、样式覆盖、折叠渲染器和响应式统一/拆分首选项。它的运行时是包的捆绑、补丁 [email protected];消费者不配置补丁或安装脚本。上游依赖项提供声明，而运行时导入使用绑定的适配器。React和React DOM仍然是外部的。
有界摘录（最多8192个组合字符和128个组合行）同步呈现，包括在服务器呈现和修订更改期间。较大的比较保留了懒惰的Web Worker路径；显式的 disableWorker 保持原意。Worker支持和Blob-worker权限取决于主机环境。 styles， loadingElement， infiniteLoading， alwaysShowLines、线偏移、沟渲染器和其他保留的查看器道具仍然可用。分屏视图从 lg 默认情况下;较窄的布局使用统一的行。代码包装在固定宽度的单元格内。可选 tabIndex 属于固定文件头下面的内容。
被检查的构建在绑定之前验证原始和修补的ESM文件标识，拒绝过时的块，并保留worker的单独动态块。Moldea的补丁没有改变。本地可访问性调整使摘要成为标记组，并为all-lines按钮提供显式名称和展开状态。折叠控件具有本地键盘行为和至少44px的粗指针目标。完整的捆绑许可证发货 THIRD-PARTY-NOTICES.md； pnpm build:viewer --write-notices 重新生成该文件，普通构建检查它是否过期。构建工具和补丁源位于tarball之外。Turbo的包本地单元和浏览器任务依赖于包构建，因此测试集合总是接收编译后的补丁查看器。在从新签出运行这些任务时使用Turbo。
大差异结果仅为当前查看器输入缓存，与同步路径的单一修订所有权相匹配。一份想念在真正的工作者中重新计算；返回到较旧的版本不会在内存中保留其旧的源/结果。对过时输入的回复不能清除当前版本的加载状态。控制 alwaysShowLines 和 extraLinesSurroundingDiff 更改重新计算大型比较；运行时行引用使用 L-1 和 R-1 形式。已检查的构建在验证未更改的源补丁后应用这些本地更正；实际工人回归在修正之前重现了这两种失败。工作保持在查看器的本地，没有跨根缓存或额外的持久性。
减价的编辑
MarkdownEditor 保留控制 value/onChange， supportedTools，可访问性道具，以及 auto/compact/wide 布局。自动测量所属容器并选择宽度为640px。 CompactMarkdownEditor 和 WideMarkdownEditor 暴露相同的道具 layout． 一个改变 value 使用文本末尾的插入符号将文档替换为保持编辑器焦点的一个编辑，并且不返回报告 onChange． 导出的所有工具、创作和散文策略保留源命令集；当创作工具受到约束时，现有文档仍然是可读的。
ChatMarkdownEditor 保留段落、H1-H3、项目符号/编号列表、粗体/斜体和安全链接格式。HTML被删除，不支持的块变成可读的散文，而图像替代仍然是文本。Paste在解析之前检查绑定的原始输入，在替换草稿之前检查序列化的结果。拒收的浆料原封不动；格式反馈保留到下次编辑。
提供一个正安全整数 maxLength，它对不包含Markdown结束的换行符的消息进行计数。 maxEditorHeight 默认为256px，必须是正的和有限的，并且被样式表限制为50dvh。 controlsRef 公开 getMarkdown()， focus(), appendLiteralText(text)． 文字插入逃避Markdown，通常在准备就绪之前或草稿太长时返回false。通过 { allowOverLimit: true } 保留完整的听写，包括在初始化期间，以便在主输入中进行编辑。只读编辑器拒绝插入。当超过限制时，用户必须阻止按钮和键盘提交。按草稿身份键输入编辑器，以清除内容并在成功提交后撤消历史记录。初始快照保留受控草稿，焦点等待初始化编辑器。使用这些控件组合呼叫者拥有的上传和听写流。
formattingContainer 省略时使用内联位置，保留外部位置为null，并将格式化菜单传送到提供的HTMLElement中。现有的 styles.css 条目包括在编辑器覆盖之前的Milkdown的通用/帧样式。个人包直接重新导出通用实现并提供共享的JG令牌。
无效配置保留了这些本地错误消息：
ChatMarkdownEditor maxLength must be a positive safe integer.ChatMarkdownEditor maxEditorHeight must be a positive finite number.
文档
API引用作为 API.md，应用程序端示例为 RECIPES.md． 这些个人使用的包裹没有在公共包裹网站上列出。
许可证
麻省理工学院。