@fangxinyan/lumina 0.6.2 → 0.6.3

package/docs/llms/theme.md

@@ -1,6 +1,6 @@
 # Theme 主题
 
-> ThemeProvider + useTheme,覆盖深浅色、强调色、密度、圆角、字体、阴影强度。
+> ThemeProvider + useTheme,覆盖深浅色、自定义模式、强调色、密度、圆角、字体、阴影强度。
 
 ## 导入
 
@@ -22,6 +22,7 @@ function Root() {
     <ThemeProvider
       mode="system"        // "light" | "dark" | "system"
       accent="violet"      // 预设 或 自定义颜色
+      themes={{ graphite: { base: "dark", tokens: {} } }}
       density="comfortable"
       intensity={5}        // 1..10 阴影强度
       radius={20}          // 圆角基准 px
@@ -78,6 +79,38 @@ t.reset();                   // 重置到 props 初值
 }} />
 ```
 
+### 自定义主题模式
+
+mode 可以指向 themes 中的命名 preset。base 决定 light/dark 基底,tokens 决定完整视觉。
+
+```tsx
+const themes = {
+  graphite: {
+    base: "dark",
+    accent: {
+      accent: "oklch(72% 0.13 190)",
+      ink: "oklch(85% 0.1 190)",
+      soft: "oklch(31% 0.05 190)",
+      glow: "oklch(72% 0.13 190 / 0.18)",
+    },
+    intensity: 4,
+    radius: 18,
+    tokens: {
+      bg: "#181b22",
+      "bg-raised": "#20242d",
+      "bg-sunken": "#11141a",
+      fg: "#edf1f7",
+      "shadow-dark": "rgba(0,0,0,.58)",
+      "shadow-light": "rgba(128,146,166,.07)",
+    },
+  },
+};
+
+<ThemeProvider mode="graphite" themes={themes}>
+  <App />
+</ThemeProvider>
+```
+
 ### 作用域嵌套
 
 target="scope" 只作用于子树,可以层层嵌套。
@@ -131,13 +164,15 @@ applyTheme(document.documentElement, {
 
 | Prop | 类型 | 默认 | 说明 |
 | --- | --- | --- | --- |
-| mode | `"light" | "dark" | "system"` | `"light"` | 深浅色模式 |
+| mode | `ThemeMode` | `"light"` | 深浅色模式或自定义模式名 |
+| colorScheme | `"light" | "dark"` | `"light"` | 自定义模式使用的 light/dark 基底 |
 | accent | `AccentKey | CustomAccentInput` | `"sky"` | 强调色,预设或自定义 |
 | density | `"compact" | "comfortable" | "spacious"` | `"comfortable"` | 密度 |
 | intensity | `number` | `5` | 阴影强度 1-10 |
 | radius | `number` | `20` | 圆角基准 px |
 | font | `FontConfig` | `"sf"` | 字体预设或 CSS 栈 |
 | tokens | `Record<string, string>` | — | 任意 CSS 变量覆写 |
+| themes | `Record<string, ThemePreset>` | — | 命名自定义模式 preset |
 | target | `"root" | "scope"` | `"root"` | 应用到根还是局部 |
 | as | `keyof JSX.IntrinsicElements` | `"div"` | scope 模式的元素标签 |
 | storageKey | `string` | — | localStorage 持久化 key |
@@ -149,14 +184,16 @@ applyTheme(document.documentElement, {
 | Prop | 类型 | 默认 | 说明 |
 | --- | --- | --- | --- |
 | mode | `ThemeMode` | — | 请求的模式(保留 system) |
-| resolvedMode | `"light" | "dark"` | — | 解析后的具体模式 |
+| resolvedMode | `ResolvedThemeMode` | — | 解析后的具体模式;自定义模式保留名称 |
+| colorScheme | `"light" | "dark"` | — | 当前 light/dark 基底 |
 | accent | `AccentKey | "custom"` | — | 预设 key 或 "custom" |
 | accentPalette | `AccentPalette` | — | 当前完整调色板 |
 | density / intensity / radius / font / tokens | `-` | — | 当前各维度状态 |
+| themes / activeTheme | `-` | — | 自定义模式注册表与当前命中的 preset |
 | setMode(m) | `(m: ThemeMode) => void` | — | 切换模式 |
 | toggleMode() | `() => void` | — | light ⇄ dark 切换 |
 | setAccent(a) | `(a: AccentKey | CustomAccentInput) => void` | — | 切换强调色 |
-| setDensity / setIntensity / setRadius / setFont / setTokens | `-` | — | 对应字段的 setter |
+| setDensity / setIntensity / setRadius / setFont / setTokens / setThemes | `-` | — | 对应字段的 setter |
 | update(cfg) | `(cfg: Partial<ThemeConfig>) => void` | — | 浅合并多字段 |
 | reset() | `() => void` | — | 重置到初始 props |
 

package/docs/llms.md

@@ -3,7 +3,7 @@
 > 拟态风格的 React 18 组件库,目标是 Electron 桌面应用。**写给 AI 编程助手**的按需文档 —— 每个组件单独一个 `.md`,避免一次性读取全部。示例源自 playground 的 demo,可直接复制运行。
 
 - **包名**: `@fangxinyan/lumina`
-- **版本**: `0.6.2`
+- **版本**: `0.6.3`
 - **React 最低版本**: 18
 - **环境**: 带打包器的 React 工程(Vite / Next.js / Webpack / Remix / Electron + Vite 等)
 - **零运行时依赖**: 只依赖 `react` / `react-dom` (peer deps)
@@ -32,8 +32,8 @@
    ```
    如果你还需要 reset / scrollbar / focus-visible 基线样式,请改用 `@fangxinyan/lumina/styles`。
 3. **TypeScript**: 所有 `XxxProps` 接口都是 `export`,可直接 `import { Button, type ButtonProps } from "@fangxinyan/lumina";`
-4. **主题**: 用 `<ThemeProvider>` 包根;运行时可通过 `useTheme()` 改。六种强调色 (`rose / sky / coral / mint / violet / amber`) × 两种模式 (`light / dark` + `system`) × 三档密度 (`compact / comfortable / spacious`)。详见 [`llms/theme.md`](./llms/theme.md)。
-5. **图标**: 所有接受 `icon / leadingIcon / trailingIcon` 的 prop 用字符串 `IconName`。完整列表见 [`llms/icon.md`](./llms/icon.md)。
+4. **主题**: 用 `<ThemeProvider>` 包根;运行时可通过 `useTheme()` 改。六种强调色 (`rose / sky / coral / mint / violet / amber`) × 内置模式 (`light / dark / system`) × 命名自定义模式 × 三档密度 (`compact / comfortable / spacious`)。详见 [`llms/theme.md`](./llms/theme.md)。
+5. **图标**: 常用 `icon / leadingIcon / trailingIcon` prop 支持内置字符串 `IconName`,高频组件也可传 `ReactNode`(如远程图片图标)。完整内置列表见 [`llms/icon.md`](./llms/icon.md)。
 6. **浮层组件**(Tooltip / Popover / Select / Cascader / ColorPicker / Modal / Drawer): 内部已 `createPortal` 到 `document.body` + 视口边界翻转,放在 `overflow: hidden` 的容器里也不会被裁。
 7. **Electron 专属组件**: `TitleBar` / `WindowControls` / `Sidebar` / `AppShell` 提供 macOS / Windows 原生风格的标题栏与导航。
 
@@ -42,7 +42,7 @@
 ### 起步
 
 - [Lumina](./llms/intro.md) — 为 Electron 应用定制的拟态风格 React 组件库。
-- [Theme 主题](./llms/theme.md) — ThemeProvider + useTheme,覆盖深浅色、强调色、密度、圆角、字体、阴影强度。
+- [Theme 主题](./llms/theme.md) — ThemeProvider + useTheme,覆盖深浅色、自定义模式、强调色、密度、圆角、字体、阴影强度。
 
 ### 通用
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fangxinyan/lumina",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "Lumina — Neumorphic component library for Electron & React apps",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -57,6 +57,21 @@
       "import": "./dist/Message.js",
       "require": "./dist/Message.cjs"
     },
+    "./ImageGrid": {
+      "types": "./dist/Image.d.ts",
+      "import": "./dist/Image.js",
+      "require": "./dist/Image.cjs"
+    },
+    "./SpriteImage": {
+      "types": "./dist/Image.d.ts",
+      "import": "./dist/Image.js",
+      "require": "./dist/Image.cjs"
+    },
+    "./LayeredImage": {
+      "types": "./dist/Image.d.ts",
+      "import": "./dist/Image.js",
+      "require": "./dist/Image.cjs"
+    },
     "./*": {
       "types": "./dist/*.d.ts",
       "import": "./dist/*.js",

package/dist/chunk-B2KEZQ6S.cjs

@@ -1,116 +0,0 @@
-'use strict';
-
-var chunkTJII7BQ2_cjs = require('./chunk-TJII7BQ2.cjs');
-require('./tokens-BIIUTPKN.css');
-require('./shared-NJHRNLRH.css');
-require('./Image-4MN34O6P.css');
-var React = require('react');
-var ReactDOM = require('react-dom');
-var jsxRuntime = require('react/jsx-runtime');
-
-function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
-
-function _interopNamespace(e) {
-  if (e && e.__esModule) return e;
-  var n = Object.create(null);
-  if (e) {
-    Object.keys(e).forEach(function (k) {
-      if (k !== 'default') {
-        var d = Object.getOwnPropertyDescriptor(e, k);
-        Object.defineProperty(n, k, d.get ? d : {
-          enumerable: true,
-          get: function () { return e[k]; }
-        });
-      }
-    });
-  }
-  n.default = e;
-  return Object.freeze(n);
-}
-
-var React__namespace = /*#__PURE__*/_interopNamespace(React);
-var ReactDOM__default = /*#__PURE__*/_interopDefault(ReactDOM);
-
-var Image = React__namespace.forwardRef(({
-  src,
-  alt,
-  width = 200,
-  height = 140,
-  preview = true,
-  hover = true,
-  placeholder,
-  className = "",
-  style,
-  ...rest
-}, ref) => {
-  const [loaded, setLoaded] = React__namespace.useState(false);
-  const [err, setErr] = React__namespace.useState(false);
-  const [open, setOpen] = React__namespace.useState(false);
-  const canPreview = preview && loaded && !err;
-  return /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
-    /* @__PURE__ */ jsxRuntime.jsx(
-      "div",
-      {
-        ref,
-        className: `n-image ${hover ? "hover" : ""} ${canPreview ? "clickable" : ""} ${className}`,
-        style: { width, ...style },
-        onClick: () => canPreview && setOpen(true),
-        ...rest,
-        children: /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "n-image-frame", style: { width: "100%", height }, children: [
-          !err && src && /* @__PURE__ */ jsxRuntime.jsx("img", { src, alt, onLoad: () => setLoaded(true), onError: () => setErr(true) }),
-          /* @__PURE__ */ jsxRuntime.jsx("div", { className: `n-image-placeholder ${loaded && !err ? "loaded" : ""}`, children: placeholder ?? /* @__PURE__ */ jsxRuntime.jsx(chunkTJII7BQ2_cjs.Icon, { name: "image", size: 28 }) }),
-          canPreview && /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
-            /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "image-hint", children: [
-              /* @__PURE__ */ jsxRuntime.jsx(chunkTJII7BQ2_cjs.Icon, { name: "eye", size: 14 }),
-              /* @__PURE__ */ jsxRuntime.jsx("span", { children: "\u70B9\u51FB\u67E5\u770B" })
-            ] }),
-            /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "image-actions", onClick: (e) => e.stopPropagation(), children: [
-              /* @__PURE__ */ jsxRuntime.jsx(
-                "button",
-                {
-                  type: "button",
-                  className: "ia-btn",
-                  onClick: () => setOpen(true),
-                  "aria-label": "\u9884\u89C8",
-                  children: /* @__PURE__ */ jsxRuntime.jsx(chunkTJII7BQ2_cjs.Icon, { name: "eye", size: 13 })
-                }
-              ),
-              src && /* @__PURE__ */ jsxRuntime.jsx("a", { className: "ia-btn", href: src, download: true, "aria-label": "\u4E0B\u8F7D", children: /* @__PURE__ */ jsxRuntime.jsx(chunkTJII7BQ2_cjs.Icon, { name: "download", size: 13 }) })
-            ] })
-          ] })
-        ] })
-      }
-    ),
-    open && typeof document !== "undefined" && ReactDOM__default.default.createPortal(
-      /* @__PURE__ */ jsxRuntime.jsx("div", { className: "image-preview-overlay", onClick: () => setOpen(false), children: /* @__PURE__ */ jsxRuntime.jsx("img", { src, alt, onClick: (e) => e.stopPropagation() }) }),
-      document.body
-    )
-  ] });
-});
-Image.displayName = "Image";
-var ImageGrid = React__namespace.forwardRef(({
-  images,
-  columns,
-  itemHeight = 130,
-  className = "",
-  style,
-  ...rest
-}, ref) => /* @__PURE__ */ jsxRuntime.jsx(
-  "div",
-  {
-    ref,
-    className,
-    style: {
-      display: "grid",
-      gap: 14,
-      gridTemplateColumns: columns ? `repeat(${columns}, 1fr)` : "repeat(auto-fill, minmax(160px, 1fr))",
-      ...style
-    },
-    ...rest,
-    children: images.map((img, i) => /* @__PURE__ */ jsxRuntime.jsx(Image, { src: img.src, alt: img.alt, width: "100%", height: itemHeight }, i))
-  }
-));
-ImageGrid.displayName = "ImageGrid";
-
-exports.Image = Image;
-exports.ImageGrid = ImageGrid;

package/dist/chunk-PH3YECMF.js

@@ -1,90 +0,0 @@
-import { Icon } from './chunk-OF3SGLZY.js';
-import './tokens-BIIUTPKN.css';
-import './shared-NJHRNLRH.css';
-import './Image-4MN34O6P.css';
-import * as React from 'react';
-import ReactDOM from 'react-dom';
-import { jsxs, Fragment, jsx } from 'react/jsx-runtime';
-
-var Image = React.forwardRef(({
-  src,
-  alt,
-  width = 200,
-  height = 140,
-  preview = true,
-  hover = true,
-  placeholder,
-  className = "",
-  style,
-  ...rest
-}, ref) => {
-  const [loaded, setLoaded] = React.useState(false);
-  const [err, setErr] = React.useState(false);
-  const [open, setOpen] = React.useState(false);
-  const canPreview = preview && loaded && !err;
-  return /* @__PURE__ */ jsxs(Fragment, { children: [
-    /* @__PURE__ */ jsx(
-      "div",
-      {
-        ref,
-        className: `n-image ${hover ? "hover" : ""} ${canPreview ? "clickable" : ""} ${className}`,
-        style: { width, ...style },
-        onClick: () => canPreview && setOpen(true),
-        ...rest,
-        children: /* @__PURE__ */ jsxs("div", { className: "n-image-frame", style: { width: "100%", height }, children: [
-          !err && src && /* @__PURE__ */ jsx("img", { src, alt, onLoad: () => setLoaded(true), onError: () => setErr(true) }),
-          /* @__PURE__ */ jsx("div", { className: `n-image-placeholder ${loaded && !err ? "loaded" : ""}`, children: placeholder ?? /* @__PURE__ */ jsx(Icon, { name: "image", size: 28 }) }),
-          canPreview && /* @__PURE__ */ jsxs(Fragment, { children: [
-            /* @__PURE__ */ jsxs("div", { className: "image-hint", children: [
-              /* @__PURE__ */ jsx(Icon, { name: "eye", size: 14 }),
-              /* @__PURE__ */ jsx("span", { children: "\u70B9\u51FB\u67E5\u770B" })
-            ] }),
-            /* @__PURE__ */ jsxs("div", { className: "image-actions", onClick: (e) => e.stopPropagation(), children: [
-              /* @__PURE__ */ jsx(
-                "button",
-                {
-                  type: "button",
-                  className: "ia-btn",
-                  onClick: () => setOpen(true),
-                  "aria-label": "\u9884\u89C8",
-                  children: /* @__PURE__ */ jsx(Icon, { name: "eye", size: 13 })
-                }
-              ),
-              src && /* @__PURE__ */ jsx("a", { className: "ia-btn", href: src, download: true, "aria-label": "\u4E0B\u8F7D", children: /* @__PURE__ */ jsx(Icon, { name: "download", size: 13 }) })
-            ] })
-          ] })
-        ] })
-      }
-    ),
-    open && typeof document !== "undefined" && ReactDOM.createPortal(
-      /* @__PURE__ */ jsx("div", { className: "image-preview-overlay", onClick: () => setOpen(false), children: /* @__PURE__ */ jsx("img", { src, alt, onClick: (e) => e.stopPropagation() }) }),
-      document.body
-    )
-  ] });
-});
-Image.displayName = "Image";
-var ImageGrid = React.forwardRef(({
-  images,
-  columns,
-  itemHeight = 130,
-  className = "",
-  style,
-  ...rest
-}, ref) => /* @__PURE__ */ jsx(
-  "div",
-  {
-    ref,
-    className,
-    style: {
-      display: "grid",
-      gap: 14,
-      gridTemplateColumns: columns ? `repeat(${columns}, 1fr)` : "repeat(auto-fill, minmax(160px, 1fr))",
-      ...style
-    },
-    ...rest,
-    children: images.map((img, i) => /* @__PURE__ */ jsx(Image, { src: img.src, alt: img.alt, width: "100%", height: itemHeight }, i))
-  }
-));
-ImageGrid.displayName = "ImageGrid";
-
-export { Image, ImageGrid };