@arronqzy/ui 1.0.8 → 1.0.10

package/README.md

@@ -1,15 +1,12 @@
 # @arronqzy/ui
 
-Abuilder 的**共享 UI 组件库**，基于 [shadcn/ui](https://ui.shadcn.com/) + Radix UI + Tailwind CSS，为编辑器与蓝图提供统一视觉与交互。
+React 编辑器和蓝图用的组件：Button、Dialog、Menu、Toast、可调面板等。基于 Radix 和 Tailwind，视觉和 `@arronqzy/tailwind` 的令牌一致。
 
-## 功能概览
+这是编辑器内部 UI，不是给业务大屏用的组件库。大屏上的图表、表格、三维在 `react-view` 的物料里。
 
-- **基础组件**：Button、Input、Dialog、Dropdown、Tabs、Tooltip、Toast 等
-- **表单**：与 `react-hook-form`、`zod` 集成的表单控件
-- **布局**：Resizable Panels、ScrollArea、Separator
-- **主题**：`ThemeProvider` 支持亮/暗色与 `class` 策略
-- **层级管理**：`UI_Z_INDEX` / `MODAL_Z_INDEX` 统一浮层 z-index
-- **图表**：封装 Recharts 常用图表（按需使用）
+下图顶栏、侧栏、按钮都来自本包：
+
+![编辑器界面由本包的菜单、按钮和面板拼出来](https://github.com/qianzhuoyao/APanel5/raw/v5/docs/guide-assets/live-zh/01-overview.png)
 
 ## 安装
 
@@ -21,7 +18,7 @@ pnpm add @arronqzy/ui
 import "@arronqzy/ui/styles.css";
 ```
 
-## 使用
+## 用法
 
 ```tsx
 import { ThemeProvider, Button, toast } from "@arronqzy/ui";
@@ -36,27 +33,27 @@ function App() {
 }
 ```
 
-### 工具函数
-
 ```ts
-import { cn } from "@arronqzy/ui";
-import { UI_Z_INDEX } from "@arronqzy/ui";
+import { cn, UI_Z_INDEX } from "@arronqzy/ui";
 ```
 
-## 导出说明
+浮层 z-index 用 `UI_Z_INDEX` / `MODAL_Z_INDEX`，不要在蓝图或配置面板里另写一个魔法数字，否则菜单会被画布盖住。
+
+## 导出
 
-- `@arronqzy/ui` — 全部组件、`cn`、`ThemeProvider`、`useToast`
-- `@arronqzy/ui/styles.css` — 编译后的 Tailwind 样式
+- `@arronqzy/ui` — 组件、`cn`、`ThemeProvider`、`useToast`
+- `@arronqzy/ui/styles.css` — 编好的 Tailwind
 
-组件源码位于 `src/ui/`，遵循 shadcn 可组合模式，可按需在本包内扩展。
+源码在 `src/ui/`，按 shadcn 的方式组合。加组件时放进这个包，不要在 `react-view` 里复制一份 Dialog。
 
 ## 构建样式
 
 ```bash
 pnpm -C packages/ui build:css
+pnpm -C packages/ui dev:css
 ```
 
-依赖 `@arronqzy/tailwind` 预设保持与设计令牌一致。
+`apps/web` 的 `predev` 会构建一次。改组件 class 时开 `dev:css`，否则演示页看不到样式变化。
 
 ## 许可证
 

package/dist/styles.css

@@ -566,13 +566,13 @@ video {
   --secondary: 210 40% 96.1%;
   --secondary-foreground: 222.2 47.4% 11.2%;
   --muted: 210 40% 96.1%;
-  --muted-foreground: 215.4 16.3% 46.9%;
+  --muted-foreground: 215.4 16.7% 45.7%;
   --accent: 210 40% 96.1%;
   --accent-foreground: 222.2 47.4% 11.2%;
-  --destructive: 0 84.2% 60.2%;
-  --destructive-foreground: 210 40% 98%;
+  --destructive: 358.6 72.7% 53.5%;
+  --destructive-foreground: 0 0% 100%;
   --border: 214.3 31.8% 91.4%;
-  --input: 214.3 31.8% 91.4%;
+  --input: 214.3 15.9% 83%;
   --ring: 222.2 84% 4.9%;
   --radius: 0.5rem;
 }
@@ -592,10 +592,10 @@ video {
   --muted-foreground: 215 20.2% 65.1%;
   --accent: 217.2 32.6% 17.5%;
   --accent-foreground: 210 40% 98%;
-  --destructive: 0 62.8% 30.6%;
-  --destructive-foreground: 210 40% 98%;
+  --destructive: 0 90.6% 70.8%;
+  --destructive-foreground: 222.2 47.4% 11.2%;
   --border: 217.2 32.6% 17.5%;
-  --input: 217.2 32.6% 17.5%;
+  --input: 217.2 28.5% 20.4%;
   --ring: 212.7 26.8% 83.9%;
 }
 
@@ -636,6 +636,10 @@ body {
   visibility: hidden;
 }
 
+.static {
+  position: static;
+}
+
 .fixed {
   position: fixed;
 }
@@ -1946,6 +1950,10 @@ body {
   text-underline-offset: 4px;
 }
 
+.accent-foreground {
+  accent-color: hsl(var(--foreground));
+}
+
 .opacity-0 {
   opacity: 0;
 }
@@ -1999,6 +2007,12 @@ body {
   outline-style: solid;
 }
 
+.ring {
+  --tw-ring-offset-shadow: var(--tw-ring-inset) 0 0 0 var(--tw-ring-offset-width) var(--tw-ring-offset-color);
+  --tw-ring-shadow: var(--tw-ring-inset) 0 0 0 calc(3px + var(--tw-ring-offset-width)) var(--tw-ring-color);
+  box-shadow: var(--tw-ring-offset-shadow), var(--tw-ring-shadow), var(--tw-shadow, 0 0 #0000);
+}
+
 .ring-0 {
   --tw-ring-offset-shadow: var(--tw-ring-inset) 0 0 0 var(--tw-ring-offset-width) var(--tw-ring-offset-color);
   --tw-ring-shadow: var(--tw-ring-inset) 0 0 0 calc(0px + var(--tw-ring-offset-width)) var(--tw-ring-color);
@@ -2121,6 +2135,8 @@ body {
   --cell-size: 2rem;
 }
 
+/* Static fallback; ThemeProvider overrides these with the chroma-js palette from lib/theme-palette.ts. */
+
 /* 弹窗蒙层全屏覆盖，层级高于画布 Ruler / 工具栏 */
 
 [data-radix-dialog-overlay],

package/index.ts

@@ -5,3 +5,4 @@ export * from "./src/lib/utils";
 export { MODAL_Z_INDEX, UI_Z_INDEX } from "./src/lib/overlay-z-index";
 export * from "./src/hooks/use-toast";
 export * from "./src/theme-provider";
+export * from "./src/lib/theme-palette";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arronqzy/ui",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "exports": {
     ".": "./index.ts",
     "./counter": "./components/counter.ts",
@@ -38,6 +38,7 @@
     "@radix-ui/react-toggle": "^1.1.9",
     "@radix-ui/react-toggle-group": "^1.1.10",
     "@radix-ui/react-tooltip": "^1.2.8",
+    "chroma-js": "^3.2.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
@@ -58,13 +59,14 @@
     "zod": "^4.1.9"
   },
   "devDependencies": {
+    "@types/chroma-js": "^3.1.2",
     "@types/react": "^19.0.1",
     "@types/react-dom": "^19.0.2",
     "eslint": "^8.57.0",
     "typescript": "^5.5.4",
     "@arronqzy/eslint-config": "0.0.0",
-    "@arronqzy/typescript-config": "1.0.0",
-    "@arronqzy/tailwind": "1.0.2"
+    "@arronqzy/tailwind": "1.0.2",
+    "@arronqzy/typescript-config": "1.0.0"
   },
   "scripts": {
     "lint": "eslint \"**/*.{ts,tsx}\"",

package/src/lib/theme-palette.ts

@@ -0,0 +1,228 @@
+import chroma, { type Color } from "chroma-js";
+
+export type ThemeMode = "light" | "dark";
+
+export const THEME_TOKENS = [
+  "background",
+  "foreground",
+  "card",
+  "card-foreground",
+  "popover",
+  "popover-foreground",
+  "primary",
+  "primary-foreground",
+  "secondary",
+  "secondary-foreground",
+  "muted",
+  "muted-foreground",
+  "accent",
+  "accent-foreground",
+  "destructive",
+  "destructive-foreground",
+  "border",
+  "input",
+  "ring",
+] as const;
+
+export type ThemeToken = (typeof THEME_TOKENS)[number];
+
+/** Any color string chroma-js can parse (hex, rgb(), hsl(), named…). */
+export type ThemeColors = Record<ThemeToken, string>;
+
+export type ThemePaletteOptions = {
+  /** Brand color; `primary-foreground` and `ring` are derived from it. */
+  primary?: string | Partial<Record<ThemeMode, string>>;
+  overrides?: Partial<Record<ThemeMode, Partial<ThemeColors>>>;
+};
+
+export const BASE_THEME_COLORS: Record<ThemeMode, ThemeColors> = {
+  light: {
+    background: "#ffffff",
+    foreground: "#020817",
+    card: "#ffffff",
+    "card-foreground": "#020817",
+    popover: "#ffffff",
+    "popover-foreground": "#020817",
+    primary: "#0f172a",
+    "primary-foreground": "#f8fafc",
+    secondary: "#f1f5f9",
+    "secondary-foreground": "#0f172a",
+    muted: "#f1f5f9",
+    "muted-foreground": "#64748b",
+    accent: "#f1f5f9",
+    "accent-foreground": "#0f172a",
+    destructive: "#ef4444",
+    "destructive-foreground": "#f8fafc",
+    border: "#e2e8f0",
+    input: "#e2e8f0",
+    ring: "#020817",
+  },
+  dark: {
+    background: "#020817",
+    foreground: "#f8fafc",
+    card: "#020817",
+    "card-foreground": "#f8fafc",
+    popover: "#020817",
+    "popover-foreground": "#f8fafc",
+    primary: "#f8fafc",
+    "primary-foreground": "#0f172a",
+    secondary: "#1e293b",
+    "secondary-foreground": "#f8fafc",
+    muted: "#1e293b",
+    "muted-foreground": "#94a3b8",
+    accent: "#1e293b",
+    "accent-foreground": "#f8fafc",
+    destructive: "#f87171",
+    "destructive-foreground": "#0f172a",
+    border: "#1e293b",
+    input: "#1e293b",
+    ring: "#cbd5e1",
+  },
+};
+
+type ContrastRule = { token: ThemeToken; against: ThemeToken[]; min: number };
+
+/**
+ * Applied in order: a token is only adjusted against tokens that are already final,
+ * so surfaces come first, then fills, then the text drawn on top of them.
+ */
+const CONTRAST_RULES: ContrastRule[] = [
+  { token: "foreground", against: ["background"], min: 7 },
+  { token: "card-foreground", against: ["card"], min: 7 },
+  { token: "popover-foreground", against: ["popover"], min: 7 },
+  { token: "primary", against: ["background"], min: 3 },
+  { token: "destructive", against: ["background", "card"], min: 4.5 },
+  { token: "ring", against: ["background"], min: 3 },
+  { token: "primary-foreground", against: ["primary"], min: 4.5 },
+  { token: "secondary-foreground", against: ["secondary"], min: 4.5 },
+  { token: "accent-foreground", against: ["accent"], min: 4.5 },
+  { token: "destructive-foreground", against: ["destructive"], min: 4.5 },
+  { token: "muted-foreground", against: ["background", "card", "muted", "accent"], min: 4.5 },
+  { token: "border", against: ["background"], min: 1.2 },
+  { token: "input", against: ["background"], min: 1.5 },
+];
+
+const LIGHTNESS_STEP = 0.005;
+const CHROMA_STEP = 0.002;
+
+function minContrast(color: Color, against: Color[]): number {
+  return Math.min(...against.map((bg) => chroma.contrast(color, bg)));
+}
+
+/** Drops chroma until the color fits sRGB; clipping would otherwise shift the hue. */
+function inGamutOklch(l: number, c: number, h: number): Color {
+  let chromaValue = c;
+  let candidate = chroma.oklch(l, chromaValue, h);
+  while (candidate.clipped() && chromaValue > 0) {
+    chromaValue = Math.max(0, chromaValue - CHROMA_STEP);
+    candidate = chroma.oklch(l, chromaValue, h);
+  }
+  return candidate;
+}
+
+function walkLightness(
+  color: Color,
+  against: Color[],
+  min: number,
+  direction: 1 | -1,
+): Color | null {
+  const [l, c, h] = color.oklch();
+  const hue = Number.isNaN(h) ? 0 : h;
+  for (let next = l; next >= 0 && next <= 1; next += direction * LIGHTNESS_STEP) {
+    const candidate = inGamutOklch(next, c, hue);
+    if (minContrast(candidate, against) >= min) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Nudges `color` along OKLCH lightness (hue and chroma kept) until it reaches `min`
+ * contrast against every color in `against`. Moves away from the backgrounds first and
+ * flips direction only when that side cannot satisfy the target.
+ */
+export function ensureContrast(color: string | Color, against: Array<string | Color>, min: number): Color {
+  const fg = chroma(color);
+  const bgs = against.map((bg) => chroma(bg));
+  if (minContrast(fg, bgs) >= min) return fg;
+
+  const bgLuminance = bgs.reduce((sum, bg) => sum + bg.luminance(), 0) / bgs.length;
+  const preferred: 1 | -1 = fg.luminance() >= bgLuminance ? 1 : -1;
+  const result =
+    walkLightness(fg, bgs, min, preferred) ?? walkLightness(fg, bgs, min, preferred === 1 ? -1 : 1);
+  if (result) return result;
+
+  const extremes = [chroma("#ffffff"), chroma("#000000")];
+  return extremes.reduce((best, c) => (minContrast(c, bgs) > minContrast(best, bgs) ? c : best));
+}
+
+/** Best of near-white / near-black text for a fill color. */
+function readableOn(fill: Color, light: string, dark: string): string {
+  return chroma.contrast(light, fill) >= chroma.contrast(dark, fill) ? light : dark;
+}
+
+function resolvePrimary(option: ThemePaletteOptions["primary"], mode: ThemeMode): string | undefined {
+  if (!option) return undefined;
+  return typeof option === "string" ? option : option[mode];
+}
+
+export function createThemeColors(mode: ThemeMode, options: ThemePaletteOptions = {}): Record<ThemeToken, Color> {
+  const base = BASE_THEME_COLORS[mode];
+  const source: ThemeColors = { ...base };
+
+  const primary = resolvePrimary(options.primary, mode);
+  if (primary && chroma.valid(primary)) {
+    source.primary = primary;
+    source["primary-foreground"] = readableOn(
+      chroma(primary),
+      BASE_THEME_COLORS.light["primary-foreground"],
+      BASE_THEME_COLORS.dark["primary-foreground"],
+    );
+    source.ring = primary;
+  }
+
+  for (const [token, value] of Object.entries(options.overrides?.[mode] ?? {})) {
+    if (value && chroma.valid(value)) source[token as ThemeToken] = value;
+  }
+
+  const colors = Object.fromEntries(
+    THEME_TOKENS.map((token) => [token, chroma(source[token])]),
+  ) as Record<ThemeToken, Color>;
+
+  for (const rule of CONTRAST_RULES) {
+    colors[rule.token] = ensureContrast(
+      colors[rule.token],
+      rule.against.map((token) => colors[token]),
+      rule.min,
+    );
+  }
+  return colors;
+}
+
+const round = (value: number) => Math.round(value * 10) / 10;
+
+/** Formats a color as the `H S% L%` triplet consumed by `hsl(var(--token))`. */
+export function toHslTriplet(color: Color): string {
+  const [h, s, l] = color.hsl();
+  const hue = Number.isNaN(h) ? 0 : h;
+  const sat = Number.isNaN(s) ? 0 : s;
+  return `${round(hue)} ${round(sat * 100)}% ${round(l * 100)}%`;
+}
+
+export function createThemePalette(mode: ThemeMode, options?: ThemePaletteOptions): Record<ThemeToken, string> {
+  const colors = createThemeColors(mode, options);
+  return Object.fromEntries(
+    THEME_TOKENS.map((token) => [token, toHslTriplet(colors[token])]),
+  ) as Record<ThemeToken, string>;
+}
+
+function toCssBlock(selector: string, palette: Record<ThemeToken, string>): string {
+  const lines = THEME_TOKENS.map((token) => `  --${token}: ${palette[token]};`);
+  return `${selector} {\n${lines.join("\n")}\n}`;
+}
+
+export function buildThemePaletteCss(options?: ThemePaletteOptions): string {
+  return [
+    toCssBlock(":root", createThemePalette("light", options)),
+    toCssBlock(".dark", createThemePalette("dark", options)),
+  ].join("\n");
+}

package/src/styles.css

@@ -2,6 +2,7 @@
 @tailwind components;
 @tailwind utilities;
 
+/* Static fallback; ThemeProvider overrides these with the chroma-js palette from lib/theme-palette.ts. */
 @layer base {
   :root {
     --background: 0 0% 100%;
@@ -20,16 +21,16 @@
     --secondary-foreground: 222.2 47.4% 11.2%;
 
     --muted: 210 40% 96.1%;
-    --muted-foreground: 215.4 16.3% 46.9%;
+    --muted-foreground: 215.4 16.7% 45.7%;
 
     --accent: 210 40% 96.1%;
     --accent-foreground: 222.2 47.4% 11.2%;
 
-    --destructive: 0 84.2% 60.2%;
-    --destructive-foreground: 210 40% 98%;
+    --destructive: 358.6 72.7% 53.5%;
+    --destructive-foreground: 0 0% 100%;
 
     --border: 214.3 31.8% 91.4%;
-    --input: 214.3 31.8% 91.4%;
+    --input: 214.3 15.9% 83%;
     --ring: 222.2 84% 4.9%;
 
     --radius: 0.5rem;
@@ -57,11 +58,11 @@
     --accent: 217.2 32.6% 17.5%;
     --accent-foreground: 210 40% 98%;
 
-    --destructive: 0 62.8% 30.6%;
-    --destructive-foreground: 210 40% 98%;
+    --destructive: 0 90.6% 70.8%;
+    --destructive-foreground: 222.2 47.4% 11.2%;
 
     --border: 217.2 32.6% 17.5%;
-    --input: 217.2 32.6% 17.5%;
+    --input: 217.2 28.5% 20.4%;
     --ring: 212.7 26.8% 83.9%;
   }
 

package/src/theme-provider.tsx

@@ -3,6 +3,7 @@
 import * as React from "react";
 import { ThemeProvider as NextThemesProvider } from "next-themes";
 import type { ThemeProviderProps } from "next-themes";
+import { buildThemePaletteCss, type ThemePaletteOptions } from "./lib/theme-palette";
 
 export type AppTheme = "light" | "dark";
 
@@ -12,14 +13,23 @@ export type ArronqzyThemeProviderProps = Omit<
 > & {
   defaultTheme?: AppTheme;
   enableSystem?: boolean;
+  /** Contrast-checked theme variables generated with chroma-js; `false` keeps the static CSS. */
+  palette?: ThemePaletteOptions | false;
 };
 
 export function ThemeProvider({
   children,
   defaultTheme = "dark",
   enableSystem = true,
+  palette = {},
   ...props
 }: ArronqzyThemeProviderProps) {
+  const paletteKey = palette ? JSON.stringify(palette) : "";
+  const paletteCss = React.useMemo(
+    () => (paletteKey ? buildThemePaletteCss(JSON.parse(paletteKey) as ThemePaletteOptions) : ""),
+    [paletteKey],
+  );
+
   return (
     <NextThemesProvider
       attribute="class"
@@ -27,10 +37,12 @@ export function ThemeProvider({
       enableSystem={enableSystem}
       {...props}
     >
+      {paletteCss ? (
+        <style data-arronqzy-theme-palette="" dangerouslySetInnerHTML={{ __html: paletteCss }} />
+      ) : null}
       {children}
     </NextThemesProvider>
   );
 }
 
 export { useTheme } from "next-themes";
-