jg-personal-react-ui
jg品牌的React组件由共享的jg-react-ui实现支持。
安装
pnpm add jg-personal-react-ui
用法
import { createElement } from 'react';
import { Button } from 'jg-personal-react-ui/components/button';
const saveAction = createElement(Button, { size: 'touch' }, 'Save changes');
那么，进口一次顺风吧 jg-personal-react-ui/styles.css。
按钮、徽章、IconTile、警报、它们的组合槽、变体和公共契约都是直接再导出的 jg-react-ui。 JgMark 是装饰的JG标志，用的 className 用于布局和与Astro相同的固定艺术品。从根目录或 jg-personal-react-ui/components/jg-mark;在识别品牌链接时，将其与可见文本配对。
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 在需要时。服务器快照使用初始道具或默认值，然后存储在聚合后同步。请参阅配方的组成和共享 自有错误契约。
控件、窗体和纯文本
表单、菜单、选项卡、工具提示、复制命令、进度、空状态、排版、表格、链接和内联代码都是的直接导出 jg-react-ui． 它们的refs、本机属性、插槽、事件别名和取消行为共享相同的实现和上下文。JG样式绑定字段、代码、菜单和反向暗主题角色；集 font-sans bg-background text-foreground 在应用程序根目录下。在相关的标签行中保持至少44px的紧凑选择符号，并为溢出表提供一个标记的、可聚焦的可见焦点区域。请参阅合成配方。
对话框、抽屉和布局
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保留了本地的语义道具和共享的几何形状。JG将通用表面阴影角色绑定到共享基础。样式表提供源页行距和抽屉行距挂钩；它不会重置文档的调色板或排版。
路由和查询恢复
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）; 选择和聚焦发挥了它的主要作用。查询客户机、网络适配器、分页限制、应用程序代码映射和路由历史记录仍然是主机所有的。
文件上传和音频输入
这些部件是直接出口的 jg-react-ui。 FileUpload， FileUploadDialog， ImageUploadField, AudioInput 保留固定的源道具和回调。文件上传重用 jg-react允许、并发、进度、取消和重试队列。调用方提供验证和传输回调；不包括端点、授权策略、存储服务或转录提供程序。上传适配器必须遵守其中止信号。image字段显示调用者的当前图像，并在预览失败时安全返回；调用者拥有对象URL的创建和撤销。
上传对话框通过完成成功的结果 onSubmit重试结束而不重新加载，并通过报告放弃的成功项目 onDiscard． 调用方拥有远程清理和回调失败。音频输入拥有麦克风轨道、记录器处理程序、波形上下文、间隔和延迟命令。废弃的权限/转录结果在卸载后无法更新替换会话或调用完成。记录复位是即时的；关闭保留了源的短视觉复位延迟。
transcribe 接收捕获的记录并返回文本。用户可以直接发送或先编辑抄本；发送失败会重试已编写的文本，而不会再次转录。提供者操作仍然是调用者所有的，并且应该有自己的截止日期/取消策略。记录/转录错误回调接收诊断异常，而可见反馈使用最近的作用域解析器。七个拥有的音频代码和稳定消息列在 errors/README.md;编码提供程序异常保留其诊断标识。取消的许可/转录工作保持沉默，可以重新启动；诊断回调仍在运行。可选的结果回调仍然是可选的。独立审查仍然是默认的。供应 onTranscriptionApply 用于主输入 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 合同。
减价的编辑
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． 这些个人使用的包裹没有在公共包裹网站上列出。
许可证
麻省理工学院。
源比较
CodeDiff， CODE_DIFF_LANGUAGES，而它们的公共类型是直接转口的 jg-react-ui/components/code-diff． JG标记提供颜色、排版和表面样式。base会发送检查过的补丁查看器和lazy worker块，因此消费者不需要配置补丁。私人画廊 /diff 在两种配色方案中，Route练习折叠、偏好、修订更新、长路径和一个单独的消费者拥有的基础主题。