@lingtools/ui 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (66) hide show
  1. package/LICENSE +373 -0
  2. package/README.md +78 -2
  3. package/dist/index.js +320 -0
  4. package/dist/src/components/LingActionItem/LingActionItem.d.ts +31 -0
  5. package/dist/src/components/LingActionItem/LingActionItem.vue.d.ts +25 -0
  6. package/dist/src/components/LingActionItem/index.d.ts +8 -0
  7. package/dist/src/components/LingActionPanel/LingActionPanel.d.ts +85 -0
  8. package/dist/src/components/LingActionPanel/LingActionPanel.vue.d.ts +35 -0
  9. package/dist/src/components/LingActionPanel/filter.d.ts +11 -0
  10. package/dist/src/components/LingActionPanel/index.d.ts +12 -0
  11. package/dist/src/components/LingDevBadge/LingDevBadge.d.ts +5 -0
  12. package/dist/src/components/LingDevBadge/LingDevBadge.vue.d.ts +3 -0
  13. package/dist/src/components/LingDevBadge/index.d.ts +4 -0
  14. package/dist/src/components/LingFooter/LingFooter.d.ts +5 -0
  15. package/dist/src/components/LingFooter/LingFooter.vue.d.ts +22 -0
  16. package/dist/src/components/LingFooter/index.d.ts +4 -0
  17. package/dist/src/components/LingFooterDivider/LingFooterDivider.d.ts +4 -0
  18. package/dist/src/components/LingFooterDivider/LingFooterDivider.vue.d.ts +3 -0
  19. package/dist/src/components/LingFooterDivider/index.d.ts +4 -0
  20. package/dist/src/components/LingKeycaps/LingKeycaps.d.ts +12 -0
  21. package/dist/src/components/LingKeycaps/LingKeycaps.vue.d.ts +9 -0
  22. package/dist/src/components/LingKeycaps/index.d.ts +8 -0
  23. package/dist/src/components/LingShortcutButton/LingShortcutButton.d.ts +14 -0
  24. package/dist/src/components/LingShortcutButton/LingShortcutButton.vue.d.ts +20 -0
  25. package/dist/src/components/LingShortcutButton/index.d.ts +8 -0
  26. package/dist/src/composables/use-list-selection.d.ts +85 -0
  27. package/dist/src/index.d.ts +69 -0
  28. package/dist/src/theme/index.d.ts +13 -0
  29. package/dist/src/theme/use-theme.d.ts +130 -0
  30. package/dist/style.css +2 -0
  31. package/dist/theme.js +4 -0
  32. package/dist/tokens.generated.less +127 -0
  33. package/dist/tokens.less +50 -0
  34. package/dist/vite.d.ts +22 -0
  35. package/dist/vite.js +49 -0
  36. package/package.json +77 -3
  37. package/src/components/LingActionItem/LingActionItem.ts +32 -0
  38. package/src/components/LingActionItem/LingActionItem.vue +105 -0
  39. package/src/components/LingActionItem/index.ts +8 -0
  40. package/src/components/LingActionPanel/LingActionPanel.ts +89 -0
  41. package/src/components/LingActionPanel/LingActionPanel.vue +340 -0
  42. package/src/components/LingActionPanel/filter.ts +25 -0
  43. package/src/components/LingActionPanel/index.ts +17 -0
  44. package/src/components/LingDevBadge/LingDevBadge.ts +5 -0
  45. package/src/components/LingDevBadge/LingDevBadge.vue +33 -0
  46. package/src/components/LingDevBadge/index.ts +4 -0
  47. package/src/components/LingFooter/LingFooter.ts +5 -0
  48. package/src/components/LingFooter/LingFooter.vue +55 -0
  49. package/src/components/LingFooter/index.ts +4 -0
  50. package/src/components/LingFooterDivider/LingFooterDivider.ts +4 -0
  51. package/src/components/LingFooterDivider/LingFooterDivider.vue +23 -0
  52. package/src/components/LingFooterDivider/index.ts +4 -0
  53. package/src/components/LingKeycaps/LingKeycaps.ts +13 -0
  54. package/src/components/LingKeycaps/LingKeycaps.vue +51 -0
  55. package/src/components/LingKeycaps/index.ts +8 -0
  56. package/src/components/LingShortcutButton/LingShortcutButton.ts +15 -0
  57. package/src/components/LingShortcutButton/LingShortcutButton.vue +71 -0
  58. package/src/components/LingShortcutButton/index.ts +8 -0
  59. package/src/composables/use-list-selection.ts +202 -0
  60. package/src/index.ts +97 -0
  61. package/src/theme/base.css +45 -0
  62. package/src/theme/index.ts +13 -0
  63. package/src/theme/tokens.generated.less +127 -0
  64. package/src/theme/tokens.json +308 -0
  65. package/src/theme/tokens.less +50 -0
  66. package/src/theme/use-theme.ts +227 -0
@@ -0,0 +1,227 @@
1
+ /**
2
+ * 页面的亮暗与毛玻璃切换:按 Desktop 给出的这个页面底下的主题切换 html.dark、html.glass、html.glass-unblurred,
3
+ * 搜索栏(Client)与各插件共用。
4
+ *
5
+ * 用法参照项目约定的 useTheme hook:入口调用一次 `useTheme`,传入页面种类与来源;
6
+ * 组件用 `useCurrentTheme()` / `useCurrentGlass()` 取响应式的当前值,非组件代码用 `getCurrentTheme()` 同步取值。
7
+ *
8
+ * 与页面自己读 `matchMedia('(prefers-color-scheme: dark)')` 不同,亮暗信号来自 Desktop:
9
+ * 用户的「跟随系统 / 亮色 / 暗色」由 Desktop 合并成最终亮暗,Linux 上系统切换也不会通知页面,
10
+ * 搜索栏与各插件页面必须显示同一结果。切换只能经设置文档与 `reloadTheme`,页面不自行改主题。
11
+ * 毛玻璃同理:Desktop 只给出页面底下是窗口毛玻璃还是背景图片,是否开、浮层是否加厚由 {@link glassModeOf} 统一判定。
12
+ */
13
+ import { readonly, ref, type Ref } from 'vue'
14
+
15
+ /**
16
+ * 实际生效的模式。
17
+ */
18
+ export type ThemeMode = 'light' | 'dark'
19
+
20
+ /**
21
+ * 组件毛玻璃(组件库 glass 风格)的模式:
22
+ * - `off`:不开;
23
+ * - `blurred`:开,页面下面的底已被模糊(窗口毛玻璃,或背景图片与页面在同一个 webview 里);
24
+ * - `unblurred`:开,但页面里的浮层模糊不到下面的底(叠在宿主之上的独立 webview 下,底是背景图片,或菜单浮层),
25
+ * 浮层要加厚底色。
26
+ */
27
+ export type GlassMode = 'off' | 'blurred' | 'unblurred'
28
+
29
+ /**
30
+ * 页面种类:宿主页(主窗口、分离窗口宿主页、快捷面板,背景与页面在同一个 webview)、
31
+ * 插件菜单浮层(叠在插件页面之上的独立 webview)、插件页面(叠在宿主卡片之上的独立 webview)。
32
+ */
33
+ export type PageKind = 'host' | 'menu' | 'plugin'
34
+
35
+ /**
36
+ * Desktop 给出的这个页面底下的主题,与插件 API 的 `ThemeInfo` 相同。
37
+ */
38
+ export interface ThemeSnapshot {
39
+ /**
40
+ * 是否暗色。
41
+ */
42
+ isDark: boolean
43
+ /**
44
+ * 页面底下是否是窗口毛玻璃。
45
+ */
46
+ vibrancy: boolean
47
+ /**
48
+ * 页面底下是否是背景图片。
49
+ */
50
+ backgroundImage: boolean
51
+ }
52
+
53
+ /**
54
+ * 主题的来源:读取当前主题、订阅变化。Client 经主题服务(`theme-changed` 事件),
55
+ * 插件经 `ling.getTheme` 与 `ling.onThemeChange`。
56
+ */
57
+ export interface ThemeSource {
58
+ /**
59
+ * 读取当前主题。
60
+ * @returns 主题信息;失败时 reject,由 `useTheme` 的调用方处理。
61
+ */
62
+ read: () => Promise<ThemeSnapshot>
63
+ /**
64
+ * 订阅主题变化;页面存活期间一直有效,不取消。
65
+ * @param callback 变化后的主题信息。
66
+ */
67
+ subscribe: (callback: (snapshot: ThemeSnapshot) => void) => void
68
+ }
69
+
70
+ /**
71
+ * `useTheme` 的选项。
72
+ */
73
+ export interface UseThemeOptions {
74
+ /**
75
+ * 主题来源。
76
+ */
77
+ source: ThemeSource
78
+ /**
79
+ * 页面种类;默认 `host`。
80
+ */
81
+ kind?: PageKind
82
+ /**
83
+ * 切换到亮色时执行;默认移除 html.dark。
84
+ */
85
+ setLightTheme?: () => void
86
+ /**
87
+ * 切换到暗色时执行;默认给 html 加上 dark。
88
+ */
89
+ setDarkTheme?: () => void
90
+ /**
91
+ * 毛玻璃模式变化时执行;默认按模式切换 html.glass 与 html.glass-unblurred。
92
+ */
93
+ setGlass?: (mode: GlassMode) => void
94
+ }
95
+
96
+ /**
97
+ * `useTheme` 的返回值。
98
+ */
99
+ export interface UseThemeResult {
100
+ /**
101
+ * 初次读取完成;入口在它完成后再挂载应用,避免先按亮色、实心画出一帧。失败时 reject。
102
+ */
103
+ themeReady: Promise<void>
104
+ /**
105
+ * 重新读取当前主题并应用。
106
+ * @returns 读取并应用完成;失败时 reject。
107
+ */
108
+ themeRefresh: () => Promise<void>
109
+ }
110
+
111
+ /**
112
+ * 判定页面的毛玻璃模式:窗口毛玻璃或背景图片生效时开;开时按页面种类决定页面里的浮层能不能模糊到下面的底。
113
+ * @param snapshot 页面底下的主题。
114
+ * @param kind 页面种类。
115
+ * @returns 毛玻璃模式。
116
+ */
117
+ export function glassModeOf(
118
+ snapshot: Pick<ThemeSnapshot, 'vibrancy' | 'backgroundImage'>,
119
+ kind: PageKind,
120
+ ): GlassMode {
121
+ if (!snapshot.vibrancy && !snapshot.backgroundImage) {
122
+ return 'off'
123
+ }
124
+ switch (kind) {
125
+ case 'host':
126
+ return 'blurred'
127
+ case 'menu':
128
+ return 'unblurred'
129
+ case 'plugin':
130
+ // 窗口毛玻璃由系统模糊;背景图片画在宿主 webview 里,插件页面里的 backdrop-filter 模糊不到
131
+ return snapshot.vibrancy ? 'blurred' : 'unblurred'
132
+ }
133
+ }
134
+
135
+ /**
136
+ * 默认的毛玻璃切换:给 html 加减 glass 与 glass-unblurred。
137
+ * @param mode 毛玻璃模式。
138
+ */
139
+ function toggleGlassClasses(mode: GlassMode) {
140
+ const classList = document.documentElement.classList
141
+ classList.toggle('glass', mode !== 'off')
142
+ classList.toggle('glass-unblurred', mode === 'unblurred')
143
+ }
144
+
145
+ /**
146
+ * 当前主题;`useTheme` 首次应用前为亮色(html 上还没有 dark)。
147
+ */
148
+ const currentTheme = ref<ThemeMode>('light')
149
+
150
+ /**
151
+ * 当前毛玻璃模式;`useTheme` 首次应用前为 off。
152
+ */
153
+ const currentGlass = ref<GlassMode>('off')
154
+
155
+ /**
156
+ * 每应用一次加一:读取发出后若已收到更新的变化事件,读取结果作废,避免旧结果覆盖新状态。
157
+ */
158
+ let appliedVersion = 0
159
+
160
+ /**
161
+ * 初始化页面主题:订阅来源的变化,并立即读取一次。每个页面在入口调用一次。
162
+ * @param options 页面种类、主题来源与切换回调。
163
+ * @returns 初次读取的完成信号与手动刷新函数。
164
+ */
165
+ export function useTheme(options: UseThemeOptions): UseThemeResult {
166
+ const kind = options.kind ?? 'host'
167
+ const setLightTheme =
168
+ options.setLightTheme ?? (() => document.documentElement.classList.remove('dark'))
169
+ const setDarkTheme =
170
+ options.setDarkTheme ?? (() => document.documentElement.classList.add('dark'))
171
+ const setGlass = options.setGlass ?? toggleGlassClasses
172
+
173
+ /**
174
+ * 应用主题并更新当前值。
175
+ * @param snapshot 页面底下的主题。
176
+ */
177
+ function applyTheme(snapshot: ThemeSnapshot) {
178
+ appliedVersion += 1
179
+ if (snapshot.isDark) {
180
+ setDarkTheme()
181
+ } else {
182
+ setLightTheme()
183
+ }
184
+ currentTheme.value = snapshot.isDark ? 'dark' : 'light'
185
+ const mode = glassModeOf(snapshot, kind)
186
+ setGlass(mode)
187
+ currentGlass.value = mode
188
+ }
189
+
190
+ /**
191
+ * 读取当前主题;读取期间收到过变化事件时丢弃本次结果。
192
+ */
193
+ async function themeRefresh() {
194
+ const version = appliedVersion
195
+ const snapshot = await options.source.read()
196
+ if (version === appliedVersion) {
197
+ applyTheme(snapshot)
198
+ }
199
+ }
200
+
201
+ options.source.subscribe(applyTheme)
202
+ return { themeReady: themeRefresh(), themeRefresh }
203
+ }
204
+
205
+ /**
206
+ * 获取响应式的当前主题(推荐):主题变化时依赖它的计算属性与模板自动更新。
207
+ * @returns 只读的当前主题。
208
+ */
209
+ export function useCurrentTheme(): Readonly<Ref<ThemeMode>> {
210
+ return readonly(currentTheme)
211
+ }
212
+
213
+ /**
214
+ * 获取响应式的当前毛玻璃模式。
215
+ * @returns 只读的毛玻璃模式。
216
+ */
217
+ export function useCurrentGlass(): Readonly<Ref<GlassMode>> {
218
+ return readonly(currentGlass)
219
+ }
220
+
221
+ /**
222
+ * 同步获取当前主题(非响应式),用于非组件代码。
223
+ * @returns 当前主题。
224
+ */
225
+ export function getCurrentTheme(): ThemeMode {
226
+ return currentTheme.value
227
+ }