@flanksource/ clicky-ui (英语)

Flanksource 的 React 组件库 阴影/ ui 以浅/暗为对象,并预设密度.

安装

pnpm add @flanksource/clicky-ui @tanstack/react-query react react-dom tailwindcss
npm install @flanksource/clicky-ui @tanstack/react-query react react-dom tailwindcss
yarn add @flanksource/clicky-ui @tanstack/react-query react react-dom tailwindcss
bun add @flanksource/clicky-ui @tanstack/react-query react react-dom tailwindcss

使用量

import { Button } from "@flanksource/clicky-ui/components";
import { ThemeProvider, DensityProvider } from "@flanksource/clicky-ui/hooks";
import "@flanksource/clicky-ui/styles.css";

export function App() {
  return (
    <ThemeProvider>
      <DensityProvider>
        <Button variant="default">Click me</Button>
      </DensityProvider>
    </ThemeProvider>
  );
}

运行时间设置

编曲 SpecRuntimeBar 详细内容 SpecRuntimeEditor 从 @flanksource/clicky-ui/ai。酒吧拥有模式、模式、努力、许可姿势、成本、超时、来源/工作树木,并承诺时间安排。 详细的编辑器提供即时的,倒置的,工具政策,环境的,退站的,以及工作流程的细节. 键和转弯限制输入被省略;已存在的值在编辑和序列化后幸存.

会话 ID 只能用 variant="preset". 环境变量总是使用 SecretKeySelector 用于源、资源名称和密钥。 供应 secretSelector 目录加载器可以提供资源和关键建议;没有目录,用户直接输入引用名和密钥. 字面价值仍然是一个独立的来源。 共享组合框和下放菜单扩展到可用的取景口高度,并在选项超过时滚动.

import { useState } from "react";
import {
  SpecRuntimeBar,
  SpecRuntimeEditor,
  type AISpecRuntimeValue,
} from "@flanksource/clicky-ui/ai";

export function RuntimeSettings() {
  const [value, setValue] = useState<AISpecRuntimeValue>({ mode: "agent" });
  return (
    <SpecRuntimeEditor
      value={value}
      onChange={setValue}
      beforeSections={<SpecRuntimeBar value={value} onChange={setValue} />}
    />
  );
}

通过主机 models 财务报告和审定财务报表 families 两个组件的目录 . effectiveMode 财务报告和审定财务报表 effectiveModel 描述继承身份而不将其复制到草案中。 设定 readOnly 用于保护层的两个组件. inheritedCommits 提供下层的承诺策略; 一个明确的空的承诺列表选择 Never . variant="preset" 省略任务所属的工作树路径,以及 sections 限制对主机的列动作, 如只检查编辑器 。 使用 PromptRunEditor 给一个有单人/多型跑道和共享限制的跑道作曲家.

核查细节

VerificationResults 使输入的固定步骤通过 verificationAdapters()。 。 。 . 细节 解释执行:命令、断言、紧凑等摘要、事件和导出变量. 产出 包含选定尝试的最后结构化结果,包括 null 和空的物体。 标题的尝试选择器出现多次尝试并默认为最新的;选择一次尝试将其执行,等待,输出和复制细节一起切换,而树和运行总计则保留了步骤的整体判断. 没有储存历史证据的报告在选择这种尝试时就是如此.

等待者保留有效的政策、结果、实际时间 durationMs最终 outputs终端 error 财务报告和审定财务报表 trace中间民意测验数值没有坚持。 该摘要在一行显示状况、已过期徽章、结果和短线输出预览;在徘徊时可提供全部条件,在产出标签中可提供全部产出,在《等待》中可提供时间表/误差诊断. TestRunner 财务报告和审定财务报表 VerificationResults 接受 activeAttempt 财务报告和审定财务报表 onAttemptChange 用于在 URL 中存储选中内容的主机。 域适配器供应 { id, status, durationMs, node } 视图通过 detailAttempts。 。 。 .

主机可以替换仅仅的等待部分,而不替换其余的固定渲染器:

import {
  VerificationResults,
  verificationAdapters,
  type VerifyReport,
} from "@flanksource/clicky-ui/data";

const adapters = verificationAdapters({
  renderWait: (wait) => (
    <p>
      {wait.outcome}: {wait.durationMs}ms
    </p>
  ),
});

export function VerificationPanel({ report }: { report: VerifyReport }) {
  return <VerificationResults report={report} adapters={adapters} />;
}

可选 renderWait 回调收到已解析的终局 WaitDetail。它使用紧凑行;返回 null 故意隐藏等待部分. StepWait 曝光自定义成分的标准渲染,以及 StepOutputs 使最后产出独立于执行款次.

类型属性

Properties 将元数据显示为双列列表。 每件东西都有稳定 key,一个生 value,可选 type 财务报告和审定财务报表 unit。对象和数组使用可扩展的 JSON 查看器;字符串保持文字化,除非 type: "json" 已指定。 数字类型需要有限数字,格式化的值保留了工具提示中的原始值.

import { Properties } from "@flanksource/clicky-ui/data";

export function RuntimeProperties() {
  return (
    <Properties
      keyRef="runtime"
      items={[
        { key: "memory", value: 1048576, type: "bytes" },
        { key: "uptime", value: 90000, type: "duration", unit: "ms" },
        { key: "load", value: 0.25, type: "number", unit: "percentunit" },
        { key: "enabled", value: false, type: "boolean" },
        { key: "started", value: 1704067200000, type: "date" },
        { key: "config", value: '{"enabled":true}', type: "json" },
      ]}
    />
  );
}

type 接受 text, (中文(简体) ), json, (中文(简体) ), bytes, (中文(简体) ), duration, (中文(简体) ), number, (中文(简体) ), boolean,或 date。字节使用二进制缩放。 默认为毫秒; 设定 unit: "s" 几秒钟。 数字单位还接受共享单位登记册,包括 percent, (中文(简体) ), percentunit,以及 Bps日期 a Date,一个ISO字符串,或一个以毫秒计的时间戳. keyRef 持续显示菜单中选择的密度。 自定义 renderValue 渲染器超过打入的格式,以及 prefixActions 或者说 suffixActions 在不改变原始值的情况下添加每行动作.

微缩 AST 渲染器

import { Clicky, type ClickyDocument } from "@flanksource/clicky-ui/clicky";

const document: ClickyDocument = {
  version: 1,
  node: {
    kind: "text",
    text: "hello from clicky",
    plain: "hello from clicky",
  },
};

export function ClickyPanel() {
  return <Clicky data={document} />;
}

Clicky 还接受JSON弦载荷。 打算制作的是兄弟会 clicky repo的标签 html-react AST,它保存了树,表,代码块等结构类型,倒塌的段落,按钮,和嵌入式文本内容.

行动探索者

OperationCatalog 财务报告和审定财务报表 EntityExplorerApp (从 @flanksource/clicky-ui/rpc) 使 OpenAPI spec - 通过一个 OperationsApiClient ——作为按实体表面分类的可导航业务列表. 他们期望Spec会宣布 x-clicky 它们应当暴露的表面的表面元数据。 见 apps/kitchen-sink/src/demos/OperationExplorerDemo.tsx 一个假客户的例子.

时间序列部件和工作负荷卡

TimeseriesPanel, (中文(简体) ), TimeseriesGauge, (中文(简体) ), TimeseriesCoreBars 财务报告和审定财务报表 WorkloadCard (从) @flanksource/clicky-ui/data调查他们的系列 @tanstack/react-query所以他们 必须在主机应用程序下提供 QueryClientProvider。 React Query v5 是一个需要的对等依赖,确保了 kitty-ui 并且其主机使用相同的查询客户端上下文,而不是安装孤立的副本.

每个系列要么由 URL 支持(baseUrl + id,通过 fetcher(url))或函数支持通过 load数字 :

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { WorkloadCard } from "@flanksource/clicky-ui/data";

const queryClient = new QueryClient();

<QueryClientProvider client={queryClient}>
  <WorkloadCard
    workload={{
      type: "EC2 instance",
      name: "build-runner-1",
      status: { label: "running", health: "healthy" },
      metadata: [{ label: "region", value: "us-east-1" }],
    }}
    metrics={{
      cpu: {
        value: {
          id: "i-0a1b2c3d.cpu", // cache identity: unique per data source
          load: ({ range, signal }) =>
            api.instanceCpu("i-0a1b2c3d", { range, signal }),
        },
        max: 4000,
      },
    }}
  />
</QueryClientProvider>;

A 类 load- 备份序列被缓存到下面 ["timeseries", "load", id, range]数字 : 页:1 id 是缓存身份,所以两个共享一个id的序列共享一个缓存的响应. 装填器接收部件 range 反应 -克瑞的 AbortSignal,当查询被取消时中止(例如,在未挂载时)。 URL 支持的系列保留它们 ["timeseries", requestUrl] 键。 见 时间序列指南 详细情况.

更改听众( N)x-on-change(中文(简体) )

财产 x-on-change 条目在其兄弟字段上行事,同时 when 持有(和 else 而不为. hide编号 :show, (中文(简体) ), enable编号 :disable, (中文(简体) ), require编号 :optional 财务报告和审定财务报表 patch 的状态,从每个渲染的当前值中重算. set 财务报告和审定财务报表 reset 仅在编辑字段时开火. patch 将标准关键词合并在兄弟会之上,这样听者就能做到 readOnly 或者说 writeOnly,或更改其编号 title, (中文(简体) ), enum 或界限:

"Status": {
  "type": "string",
  "enum": ["draft", "signed"],
  "x-on-change": [{
    "when": { "const": "signed" },
    "patch": {
      "Amount": { "readOnly": true },
      "Rate": { "title": "Agreed rate", "minimum": 0, "maximum": 25 }
    }
  }]
}

补丁可能不会改变字段的形状(type, (中文(简体) ), properties, (中文(简体) ), items, (中文(简体) ), allOf,(...)),其编号为: required- 性质或其价值(default, (中文(简体) ), const);形式会抛出,指向实际的动作. Form收听者厨房-下沉演示有可重复的每个动作的例子.

A 类 hide编号 :show编号 :enable编号 :disable 目标或目标 patch 键可能是一个 /- 分道扬镳地进入兄弟会的树下: groups/Rates 隐藏一组,和 groups/Rates/Fee 隐藏其一列,因为一个阵列被划入其 items对象的 x-on-load 条目的形状相同。 他们 when 读取对象本身,它们适用于任何 x-on-change,它们只允许衍生的行动和 patch。在 docs app 中参见 JSON Schema 扩展引用,用于完整的语法和命令.

A 类 writeOnly: true 字段是永不读取的输入:一个可编辑的形式使它变得正常,而一个视图则使它没有任何意义。 视图是 readOnly 形式,任何在 a 下 readOnly 对象、数组或映射,或本身的字段 readOnly。 。 。 . x-disabled 不是一个视图,所以一个被禁用的子树会保持它的控制. 使用 format: "password" 以隐藏编辑时的值.

标记下编辑器字段

JsonSchemaForm 字段为 format: md - 和独立的 MdxEditorField 从 @flanksource/clicky-ui/mdx-editor - 使一个 MDX 编辑器- 支持丰富的文字领域。 它的船底样式是 单独 样式表这样不使用字段的应用程序不支付其重量(编辑器的JavaScript也被加载了懒散,在第一渲染上). 除了在应用根导入一次 styles.css数字 :

import "@flanksource/clicky-ui/styles.css";
import "@flanksource/clicky-ui/mdx-editor.css"; // only if you render the markdown field

如果没有此导入, 字段将生成, 但是其工具栏和内容没有样式 .

如果无法导入Markdown,则字段会显示解析错误,并在源编辑器中保存文档. 校正来源并选择 重试丰富的文本 重新打开富文本编辑器。 源编辑使用相同的 onChange 调回; 保留只读和已禁用字段。 正在装入另一个文档 value 自动重试其导入 .

边框大小指导

生产应用中偏好亚路径进口:

import { Button } from "@flanksource/clicky-ui/components";
import { cn } from "@flanksource/clicky-ui/utils";
import { DataTable } from "@flanksource/clicky-ui/data";

词根 @flanksource/clicky-ui 枪管仍为相容性和方便性所支持,但副道会给捆绑者一个更小的入道表面. 导入 @flanksource/clicky-ui/styles.css 一次在应用根。 标记下解析和代码突出显示由它们的组件同步加载.

已出版的软件包使用平版成像依赖范围,不需要pnpm工作空间或目录协议. 该套装船为上述公众子路径提供无害环境管理和共同JS切入点.

表达式语言支持

导入可兼容的摩纳哥语支持 @flanksource/clicky-ui/expressions,或可选的回放游乐场 @flanksource/clicky-ui/expressions/playground。语言条目注册CEL、Go模板、JSONPath以及嵌入在YAML、JSON或文本中的模板,而不导入游戏场UI。 见 表达式指南。 。 。 .

渲染图标的UI子路径是用于浏览器捆绑器,如Vite,Rollup,Webpack,Rspack,和Bun的捆绑器. 图标反应包曝光 .jsx 模块和 CSS 导入, 因此简单的节点 import编号 :require 图标重的子路径不是一个支持的验证目标.

IntelliJ 图标目录

导入离线组件 @flanksource/clicky-ui/icons数字 :

import {
  UiBreakpoint,
  UiMessageQueue,
  UiSqlPrimaryKey,
} from "@flanksource/clicky-ui/icons";

这个 jb-site: 输入 icons/icon-selections.json 决 议 IntelliJ 图标目录运行 pnpm --filter @flanksource/clicky-ui download:icons 更改选择后 pnpm --filter @flanksource/clicky-ui build:icons:force。下载器检查每个目录路径,需要每个下载的SVG中有一个Apache 2.0头. 它将来自JetBrains, Iconify 和其他供应商的 URL 相匹配源存储于以下 icons/svg/remote;生成的 React 组件由这些本地文件构建. 每个组件源列表在 NOTICE.md。 。 。 .

下载的 IntelliJ 图标 ZIP 可以导入 pnpm --filter @flanksource/clicky-ui exec tsx scripts/import-jetbrains-zips.ts <download-dir> <since-ISO> --licensed-only。命令将每个光/暗对抽出 icons/svg/downloaded,添加 programming 选择和写入 icons/jetbrains-download-audit.json 档案。 使用 --include-without-header 而不是明确包含没有嵌入式Apache头的对子. 这对用 jb-download-unverified: 来源ID 并出现在审计的 withoutHeader 列表;其许可证不通过进口进行核查。 SVG两个目录都是线下构建输入; remote 区分 URL 相匹配的艺术与 ZIP 相匹配的艺术。 以 build:icons:force 输入后。 每个概念都有首选 Ui<Concept> 图标和编号选项,例如 UiFunction1 财务报告和审定财务报表 UiFunction2。导入的图标有匹配 Dark 变体,而现有的首选组件保留其艺术作品. programmingIconCatalog 用于调色板页面的已键入概念、变异、彩色作用和标题状态元数据.

标记下和代码突出显示使用可选的对等依赖( )marked, (中文(简体) ), shiki,以及 @shikijs/*) (中文(简体) ). 在制造这些组件的应用程序中安装它们.

尾风预设

Tailwind CSS v4 消费者可以通过其兼容指令加载预设:

/* src/styles.css */
@config "../tailwind.config.ts";
@import "tailwindcss";

// tailwind.config.ts
import preset from "@flanksource/clicky-ui/tailwind-preset";

export default {
  presets: [preset],
};

预设接线:

• 主题符号通过 [data-theme="light" | "dark"] 属性 <html>。 。 。 .
• 密度变量通过 [data-density="compact" | "comfortable" | "spacious"]。 。 。 .
• 间距公用事业(gap-density-2, (中文(简体) ), p-density-4等)由活性密度缩放.

他们

const { theme, resolvedTheme, setTheme } = useTheme();
const { density, setDensity } = useDensity();

两个钩子都坚持选择 localStorage 下级 clicky-ui-theme 编号 : clicky-ui-density中添加到 <head> 为避免FOUC:

<script>
  (function () {
    try {
      var t = localStorage.getItem("clicky-ui-theme") || "system";
      var d = localStorage.getItem("clicky-ui-density") || "comfortable";
      var resolved =
        t === "system"
          ? window.matchMedia("(prefers-color-scheme: dark)").matches
            ? "dark"
            : "light"
          : t;
      document.documentElement.setAttribute("data-theme", resolved);
      document.documentElement.setAttribute("data-density", d);
    } catch (_) {}
  })();
</script>

多重SSE 流

HTTP/1.1 浏览器每主机6个连接,通过标签共享,因此一个打开一个本地的应用程序 EventSource 每个话题都会饿死自己. createEventHub 返回一个 EventSourceFactory 钩子打开的每条溪流的多轴useTaskRun, (中文(简体) ), usePrompts, (中文(简体) ), useLogTail,.)与服务器事件端点(如: clidy's sse.Hub) (中文(简体) ). 将树包入 EventSourceProvider 一次:

import {
  EventSourceProvider,
  createEventHub,
} from "@flanksource/clicky-ui/hooks";

// Create the hub once at module scope so every render shares one connection.
// `buildId` is the build the page was served with (e.g. from a <meta> tag);
// when the server's hello reports a different build the page reloads once.
// Omit it (or pass null) to never reload.
const eventHub = createEventHub({
  buildId: document.querySelector<HTMLMetaElement>('meta[name="app-build"]')
    ?.content,
});

root.render(
  <EventSourceProvider value={eventHub}>
    <App />
  </EventSourceProvider>,
);

选项 : url (默认) /api/events, (中文(简体) ), buildId (单位:千美元)string | null),以及 onBuildMismatch (默认) window.location.reload()) (中文(简体) ). 每个枢纽保持自己的连接,因此两个枢纽从未共享状态.

林特规则

包船选入 奥克林特 继续消耗 kitty-ui 组件、 覆盖、 主题的工程的规则 和偶像,而不是用手重建它们.

在消耗工程中安装克林特. 如果项目尚未依赖 打开 @flanksource/clicky-ui中,加上作为正常运行时间依赖:

pnpm add @flanksource/clicky-ui
pnpm add -D oxlint

然后启用消费者的JS插件 .oxlintrc.json数字 :

{
  "jsPlugins": [
    {
      "name": "clicky-ui",
      "specifier": "@flanksource/clicky-ui/oxlint-plugins"
    }
  ],
  "rules": {
    "clicky-ui/prefer-clicky-components": "warn",
    "clicky-ui/no-adhoc-overlay": "error",
    "clicky-ui/prefer-tailwind-classes": "warn",
    "clicky-ui/prefer-theme-tokens": "error",
    "clicky-ui/prefer-clicky-icons": "warn"
  }
}

添加一个运行于消费源上的牛林的包脚本 :

{
  "scripts": {
    "lint:clicky-ui": "oxlint -c .oxlintrc.json src --deny-warnings"
  }
}

这个 specifier 窗体通过软件包导出解决。 在一个当地的兄弟 退出,或者如果软件包导出无法为您的工具链提供,请指出 文件直接插件 :

{
  "jsPlugins": [
    "./node_modules/@flanksource/clicky-ui/oxlint-plugins/clicky-ui.js"
  ]
}

规则旗重建了原始人(<button>, (中文(简体) ), <table>,...),特设对话框和 任意 z- 索引、 手卷内线样式、 硬码颜色/ 原始主题 从未经批准的库中导入或伪造的图标 爱摩地. 见 oxlint-plugins/README.md 全文 向导.

外部文件中的评论

CommentProvider 接受 onScrollToAnchor(anchor, options) 财务报告和审定财务报表 getAnchorTop(anchor) 给那些有注释的文档 生活在铁路框架之外的主机. onScrollToAnchor (一) 必须返回锚是否可用并发送导航; getAnchorTop 返回当前视图偏移,或 null 当无法使用时。 提供导航代表取代当地DOM滚动。 没有这些回调,提供者保留其注册元素行为. 使用 CommentSidePanel 与 focusedAlignment="flow" 并同步选择和突出显示 useCommentContext。 。 。 .

<CommentProvider
  comments={comments}
  config={config}
  initialRailMode="all"
  getAnchorTop={(anchor) => documentAnchors.get(anchor)?.top ?? null}
  onScrollToAnchor={(anchor, options) => {
    if (!documentAnchors.has(anchor)) return false;
    annotatedWindow.postMessage(
      { type: "scroll", anchor, options },
      annotatedOrigin,
    );
    return true;
  }}
>
  <CommentSidePanel focusedAlignment="flow" />
</CommentProvider>

主机拥有消息验证,评论持久性和突变回调. 请参看游乐场书签上的原生桥和外页审查表.

许可证

阿帕奇 - 2.0