dommief 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.
- package/dist/cli.js +2695 -0
- package/dist/index.d.ts +326 -0
- package/dist/index.js +1383 -0
- package/dist/theme-api.d.ts +108 -0
- package/dist/theme-api.js +268 -0
- package/dist/types-zwMRCGy9.d.ts +81 -0
- package/package.json +70 -4
- package/src/client/Api.tsx +73 -0
- package/src/client/AppRoutes.tsx +51 -0
- package/src/client/ClientOnly.tsx +22 -0
- package/src/client/Demo.tsx +70 -0
- package/src/client/DemoRegistry.ts +11 -0
- package/src/client/NotFound.tsx +13 -0
- package/src/client/Tabs.tsx +70 -0
- package/src/client/entry-client.tsx +84 -0
- package/src/client/entry-server.tsx +52 -0
- package/src/client/index.tsx +4 -0
- package/src/client/search-client.ts +91 -0
- package/src/client/search-core.ts +151 -0
- package/src/client/search-worker.ts +45 -0
- package/src/client/virtual.d.ts +16 -0
- package/src/routesModule.ts +61 -0
- package/src/search-config.ts +45 -0
- package/src/theme-api.tsx +242 -0
- package/src/types.ts +71 -0
- package/README.md +0 -3
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
import * as react from 'react';
|
|
2
|
+
import { ReactNode } from 'react';
|
|
3
|
+
import { d as SiteData, N as NavItem, P as PageSummary, S as SidebarGroup } from './types-zwMRCGy9.js';
|
|
4
|
+
export { T as TocEntry } from './types-zwMRCGy9.js';
|
|
5
|
+
|
|
6
|
+
type ColorValue = 'light' | 'dark';
|
|
7
|
+
type PrefersColorValue = ColorValue | 'auto';
|
|
8
|
+
declare const PREFERS_COLOR_ATTR = "data-prefers-color";
|
|
9
|
+
declare const PREFERS_COLOR_STORAGE_KEY = "dommief:prefers-color";
|
|
10
|
+
/**
|
|
11
|
+
* Inline script < 1KB, không `async`/`defer` (DM-510 tiêu chí #1), chạy TRƯỚC paint để không
|
|
12
|
+
* nháy sáng rồi sang tối (FOUC). Chỉ **ghi đè** khi `localStorage` có lựa chọn (THEME-API
|
|
13
|
+
* Amendment 2026-10-22 #1): giá trị mặc định từ config đã được SSR render thẳng vào
|
|
14
|
+
* `<html data-prefers-color>` (xem vite/plugin.ts), nên trang vẫn đúng màu khi tắt JS.
|
|
15
|
+
*/
|
|
16
|
+
declare const PREFERS_COLOR_BOOT_SCRIPT: string;
|
|
17
|
+
/** `'auto'|'dark'|'light'` khác `'auto'` → màu áp dụng thật (để SSR render attribute trên `<html>`). */
|
|
18
|
+
declare function resolveConfiguredColor(defaultValue: PrefersColorValue | undefined): ColorValue | undefined;
|
|
19
|
+
|
|
20
|
+
interface SearchHit {
|
|
21
|
+
id: string;
|
|
22
|
+
routeId: string;
|
|
23
|
+
path: string;
|
|
24
|
+
pageTitle: string;
|
|
25
|
+
sectionTitle: string;
|
|
26
|
+
pageKey: string;
|
|
27
|
+
sectionKey: string;
|
|
28
|
+
score: number;
|
|
29
|
+
/** Nguyên văn đoạn text gốc (store field `value` của SearchDocument) — UI (DM-803) tự cắt
|
|
30
|
+
* snippet quanh `highlight` và bọc `<mark>`, không phải tìm lại trong chuỗi (tiêu chí DM-802 scope). */
|
|
31
|
+
value: string;
|
|
32
|
+
/** Vị trí từ khoá khớp trong `value` gốc (KHÔNG phải snippet) — null nếu không định vị được. */
|
|
33
|
+
highlight: {
|
|
34
|
+
start: number;
|
|
35
|
+
end: number;
|
|
36
|
+
} | null;
|
|
37
|
+
}
|
|
38
|
+
interface SearchResult {
|
|
39
|
+
hits: SearchHit[];
|
|
40
|
+
error?: string | undefined;
|
|
41
|
+
superseded?: boolean;
|
|
42
|
+
}
|
|
43
|
+
interface SearchManifest {
|
|
44
|
+
locales: Record<string, string>;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
interface ClientOnlyProps {
|
|
48
|
+
children: ReactNode;
|
|
49
|
+
fallback?: ReactNode;
|
|
50
|
+
}
|
|
51
|
+
declare function ClientOnly({ children, fallback }: ClientOnlyProps): ReactNode;
|
|
52
|
+
|
|
53
|
+
declare const SiteContext: react.Context<SiteData | null>;
|
|
54
|
+
declare function SiteProvider({ value, children }: {
|
|
55
|
+
value: SiteData;
|
|
56
|
+
children?: ReactNode;
|
|
57
|
+
}): react.JSX.Element;
|
|
58
|
+
declare function useSiteData(): SiteData;
|
|
59
|
+
/** Locale của pathname (đã bỏ basename): route khớp → locale của route; không khớp (404) → base locale dài nhất; cuối cùng locale mặc định. */
|
|
60
|
+
declare function localeIdFor(site: SiteData, pathname: string): string;
|
|
61
|
+
declare function useRouteMeta(): PageSummary;
|
|
62
|
+
/** Giao diện tối thiểu `useSiteSearch` cần — CHỈ `search`/`dispose`, KHÔNG lộ `SearchClient`/
|
|
63
|
+
* `SearchPort` ra public API (review Q2: export chúng từ `theme-api` khoá luôn hai type đó
|
|
64
|
+
* thành public API v0.1 chỉ để phục vụ test seam — không đáng). Test tiêm một object thuần
|
|
65
|
+
* bọc `SearchClient`/`SearchCore` tự dựng, không cần import type nào từ `search-client.js`. */
|
|
66
|
+
interface SearchRuntime {
|
|
67
|
+
search(query: string, locale: string): Promise<SearchResult>;
|
|
68
|
+
dispose?(): void;
|
|
69
|
+
}
|
|
70
|
+
declare const SearchRuntimeContext: react.Context<SearchRuntime | null>;
|
|
71
|
+
declare function SearchRuntimeProvider({ value, children }: {
|
|
72
|
+
value: SearchRuntime;
|
|
73
|
+
children?: ReactNode;
|
|
74
|
+
}): react.JSX.Element;
|
|
75
|
+
interface UseSiteSearchResult {
|
|
76
|
+
/** `error`: thông điệp an toàn (DM-802 fail-open) — UI hiển thị "không tìm được" thay vì
|
|
77
|
+
* coi nhầm là "không có kết quả". `superseded`: query này đã bị một query mới hơn thay
|
|
78
|
+
* thế (UI nên bỏ qua, KHÔNG hiển thị "không tìm thấy" chớp nhoáng — review #8). */
|
|
79
|
+
search: (query: string) => Promise<SearchResult>;
|
|
80
|
+
loading: boolean;
|
|
81
|
+
}
|
|
82
|
+
/** DM-802/803: Web Worker CHỈ được tạo khi có truy vấn đầu tiên (không tải ở lúc boot trang —
|
|
83
|
+
* tiêu chí DM-803 #4). SSR không có `Worker`: `search()` trả `[]` thay vì throw — hàm này luôn
|
|
84
|
+
* được gọi ở event handler phía client (gõ vào ô tìm kiếm), không phải trong render path
|
|
85
|
+
* nên nhánh SSR thực tế không chạy, nhưng vẫn giữ an toàn nếu ai đó gọi trái quy ước.
|
|
86
|
+
*
|
|
87
|
+
* `clientPromiseRef` (KHÔNG phải instance) — review #2: hai lần gọi `search()` gần nhau (debounce
|
|
88
|
+
* không đảm bảo tuần tự giữa 2 keystroke liên tiếp qua React) đều thấy `clientRef.current`
|
|
89
|
+
* là null nếu chỉ lưu instance sau khi `await import()` xong — tạo 2 `Worker`, cái bị ghi đè
|
|
90
|
+
* không ai `terminate()`. Lưu promise để lần gọi thứ 2 đợi chung lần tạo đầu. */
|
|
91
|
+
declare function useSiteSearch(): UseSiteSearchResult;
|
|
92
|
+
declare function useNavData(): NavItem[];
|
|
93
|
+
declare function useSidebarData(): SidebarGroup[];
|
|
94
|
+
/**
|
|
95
|
+
* `setPrefers` dùng chung cho mọi nơi gọi (hook, inline script không dùng hàm này vì chạy
|
|
96
|
+
* trước khi React mount — xem `PREFERS_COLOR_BOOT_SCRIPT` trong prefers-color.ts). Ghi
|
|
97
|
+
* localStorage + attribute + báo mọi instance `usePrefersColor` khác re-render.
|
|
98
|
+
*/
|
|
99
|
+
declare function setPrefersColor(value: PrefersColorValue): void;
|
|
100
|
+
/**
|
|
101
|
+
* `[color, prefers, setPrefers]`. Ở SSR và lần render đầu sau hydrate, `color`/`prefers` là
|
|
102
|
+
* `undefined` để KHÔNG BAO GIỜ lệch với HTML tĩnh (hydration mismatch) — `ColorSwitch`
|
|
103
|
+
* phải render icon trung tính khi `color === undefined`.
|
|
104
|
+
*/
|
|
105
|
+
declare function usePrefersColor(): [color: ColorValue | undefined, prefers: PrefersColorValue | undefined, setPrefers: (v: PrefersColorValue) => void];
|
|
106
|
+
|
|
107
|
+
export { ClientOnly, NavItem, PREFERS_COLOR_ATTR, PREFERS_COLOR_BOOT_SCRIPT, PREFERS_COLOR_STORAGE_KEY, PageSummary, SearchRuntimeContext, SearchRuntimeProvider, SidebarGroup, SiteContext, SiteData, SiteProvider, localeIdFor, resolveConfiguredColor, setPrefersColor, useNavData, usePrefersColor, useRouteMeta, useSidebarData, useSiteData, useSiteSearch };
|
|
108
|
+
export type { ClientOnlyProps, ColorValue, PrefersColorValue, SearchHit, SearchManifest, SearchResult, SearchRuntime, UseSiteSearchResult };
|
|
@@ -0,0 +1,268 @@
|
|
|
1
|
+
// src/theme-api.tsx
|
|
2
|
+
import { createContext, useContext, useEffect as useEffect2, useMemo, useRef, useState as useState2, useSyncExternalStore } from "react";
|
|
3
|
+
import { useLocation } from "react-router";
|
|
4
|
+
|
|
5
|
+
// src/prefers-color.ts
|
|
6
|
+
var PREFERS_COLOR_ATTR = "data-prefers-color";
|
|
7
|
+
var PREFERS_COLOR_STORAGE_KEY = "dommief:prefers-color";
|
|
8
|
+
var PREFERS_COLOR_BOOT_SCRIPT = `(function(){try{var k=${JSON.stringify(PREFERS_COLOR_STORAGE_KEY)},a=${JSON.stringify(PREFERS_COLOR_ATTR)},v=localStorage.getItem(k);if(v!=='light'&&v!=='dark'&&v!=='auto')return;var c=v==='auto'?(matchMedia('(prefers-color-scheme: dark)').matches?'dark':'light'):v;document.documentElement.setAttribute(a,c)}catch(e){}})();`;
|
|
9
|
+
function resolveConfiguredColor(defaultValue) {
|
|
10
|
+
if (!defaultValue || defaultValue === "auto") return void 0;
|
|
11
|
+
return defaultValue;
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
// src/client/search-client.ts
|
|
15
|
+
function wrapRealWorker(worker) {
|
|
16
|
+
return {
|
|
17
|
+
postMessage: (msg) => worker.postMessage(msg),
|
|
18
|
+
set onmessage(handler) {
|
|
19
|
+
worker.onmessage = handler;
|
|
20
|
+
},
|
|
21
|
+
get onmessage() {
|
|
22
|
+
return worker.onmessage;
|
|
23
|
+
},
|
|
24
|
+
terminate: () => worker.terminate()
|
|
25
|
+
};
|
|
26
|
+
}
|
|
27
|
+
var SearchClient = class {
|
|
28
|
+
port;
|
|
29
|
+
seq = 0;
|
|
30
|
+
pending = /* @__PURE__ */ new Map();
|
|
31
|
+
disposed = false;
|
|
32
|
+
lastLocale = null;
|
|
33
|
+
constructor(port, manifest) {
|
|
34
|
+
this.port = port;
|
|
35
|
+
this.port.onmessage = (ev) => this.handleMessage(ev.data);
|
|
36
|
+
this.port.postMessage({ type: "init", manifest });
|
|
37
|
+
}
|
|
38
|
+
handleMessage(res) {
|
|
39
|
+
const entry = this.pending.get(res.id);
|
|
40
|
+
if (!entry) return;
|
|
41
|
+
this.pending.delete(res.id);
|
|
42
|
+
entry.resolve({ hits: res.hits, error: res.error });
|
|
43
|
+
}
|
|
44
|
+
/** (c) truy vấn rỗng -> [] ngay, KHÔNG gửi qua port (không tốn một round-trip worker).
|
|
45
|
+
* (d) chỉ Promise của `seq` MỚI NHẤT được resolve với hit thật; mọi `search()` gọi trước đó còn
|
|
46
|
+
* đang chờ được resolve NGAY với `{hits:[], superseded:true}` (không treo Promise mãi — tránh rò
|
|
47
|
+
* bộ nhớ nếu UI không bao giờ nhận lại response của chúng). `superseded` để UI PHÂN BIỆT được
|
|
48
|
+
* "bị thay thế" với "không tìm thấy thật" (review #8) — nếu UI tự so `query` hiện tại trước khi
|
|
49
|
+
* `setState` thì có thể bỏ qua cờ này, nhưng contract vẫn phải tường minh. */
|
|
50
|
+
search(query, locale) {
|
|
51
|
+
if (!query.trim()) return Promise.resolve({ hits: [] });
|
|
52
|
+
if (this.lastLocale !== null && this.lastLocale !== locale) {
|
|
53
|
+
this.port.postMessage({ type: "dropLocale", locale: this.lastLocale });
|
|
54
|
+
}
|
|
55
|
+
this.lastLocale = locale;
|
|
56
|
+
for (const [id2, entry] of this.pending) {
|
|
57
|
+
entry.resolve({ hits: [], superseded: true });
|
|
58
|
+
this.pending.delete(id2);
|
|
59
|
+
}
|
|
60
|
+
const id = ++this.seq;
|
|
61
|
+
return new Promise((resolve) => {
|
|
62
|
+
this.pending.set(id, { resolve });
|
|
63
|
+
this.port.postMessage({ id, type: "search", query, locale });
|
|
64
|
+
});
|
|
65
|
+
}
|
|
66
|
+
dispose() {
|
|
67
|
+
if (this.disposed) return;
|
|
68
|
+
this.disposed = true;
|
|
69
|
+
for (const [id, entry] of this.pending) {
|
|
70
|
+
entry.resolve({ hits: [], superseded: true });
|
|
71
|
+
this.pending.delete(id);
|
|
72
|
+
}
|
|
73
|
+
this.port.onmessage = null;
|
|
74
|
+
this.port.terminate?.();
|
|
75
|
+
}
|
|
76
|
+
};
|
|
77
|
+
|
|
78
|
+
// src/client/ClientOnly.tsx
|
|
79
|
+
import { useEffect, useLayoutEffect, useState } from "react";
|
|
80
|
+
var useIsomorphicLayoutEffect = typeof document === "undefined" ? useEffect : useLayoutEffect;
|
|
81
|
+
function ClientOnly({ children, fallback = null }) {
|
|
82
|
+
const [mounted, setMounted] = useState(false);
|
|
83
|
+
useIsomorphicLayoutEffect(() => {
|
|
84
|
+
setMounted(true);
|
|
85
|
+
}, []);
|
|
86
|
+
return mounted ? children : fallback;
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
// src/theme-api.tsx
|
|
90
|
+
import { jsx } from "react/jsx-runtime";
|
|
91
|
+
var SiteContext = createContext(null);
|
|
92
|
+
function SiteProvider({ value, children }) {
|
|
93
|
+
return /* @__PURE__ */ jsx(SiteContext.Provider, { value, children });
|
|
94
|
+
}
|
|
95
|
+
function useSiteData() {
|
|
96
|
+
const ctx = useContext(SiteContext);
|
|
97
|
+
return ctx ?? {};
|
|
98
|
+
}
|
|
99
|
+
function localeIdFor(site, pathname) {
|
|
100
|
+
const locales = site.locales ?? [];
|
|
101
|
+
const def = locales[0]?.id ?? "";
|
|
102
|
+
const route = Object.values(site.routes ?? {}).find((r) => r.path === pathname);
|
|
103
|
+
if (route) return route.locale ?? def;
|
|
104
|
+
const hit = locales.filter((l) => l.suffix === "" && l.base !== "/" && (pathname + "/").startsWith(l.base)).sort((a, b) => b.base.length - a.base.length)[0];
|
|
105
|
+
return hit?.id ?? def;
|
|
106
|
+
}
|
|
107
|
+
function useRouteMeta() {
|
|
108
|
+
const site = useSiteData();
|
|
109
|
+
const { pathname } = useLocation();
|
|
110
|
+
const route = Object.values(site.routes ?? {}).find((r) => r.path === pathname);
|
|
111
|
+
return (route ? site.meta?.[route.id] : void 0) ?? { frontmatter: {} };
|
|
112
|
+
}
|
|
113
|
+
var SearchRuntimeContext = createContext(null);
|
|
114
|
+
function SearchRuntimeProvider({ value, children }) {
|
|
115
|
+
return /* @__PURE__ */ jsx(SearchRuntimeContext.Provider, { value, children });
|
|
116
|
+
}
|
|
117
|
+
async function createWorkerRuntime() {
|
|
118
|
+
if (typeof window === "undefined" || typeof Worker === "undefined") return null;
|
|
119
|
+
const manifestMod = await import("virtual:dommief/search-index");
|
|
120
|
+
if (!Object.keys(manifestMod.default.locales).length) return null;
|
|
121
|
+
const worker = new Worker(new URL("./client/search-worker.ts", import.meta.url), { type: "module" });
|
|
122
|
+
return new SearchClient(wrapRealWorker(worker), manifestMod.default);
|
|
123
|
+
}
|
|
124
|
+
function useSiteSearch() {
|
|
125
|
+
const site = useSiteData();
|
|
126
|
+
const { pathname } = useLocation();
|
|
127
|
+
const locale = localeIdFor(site, pathname);
|
|
128
|
+
const injected = useContext(SearchRuntimeContext);
|
|
129
|
+
const runtimePromiseRef = useRef(null);
|
|
130
|
+
const unmountedRef = useRef(false);
|
|
131
|
+
const [loading, setLoading] = useState2(false);
|
|
132
|
+
useEffect2(() => {
|
|
133
|
+
unmountedRef.current = false;
|
|
134
|
+
return () => {
|
|
135
|
+
unmountedRef.current = true;
|
|
136
|
+
void runtimePromiseRef.current?.then((r) => r?.dispose?.());
|
|
137
|
+
runtimePromiseRef.current = null;
|
|
138
|
+
};
|
|
139
|
+
}, []);
|
|
140
|
+
const ensureRuntime = useMemo(() => {
|
|
141
|
+
return () => {
|
|
142
|
+
if (runtimePromiseRef.current) return runtimePromiseRef.current;
|
|
143
|
+
if (injected) {
|
|
144
|
+
runtimePromiseRef.current = Promise.resolve(injected);
|
|
145
|
+
return runtimePromiseRef.current;
|
|
146
|
+
}
|
|
147
|
+
setLoading(true);
|
|
148
|
+
const promise = (async () => {
|
|
149
|
+
try {
|
|
150
|
+
const runtime = await createWorkerRuntime();
|
|
151
|
+
if (runtime && unmountedRef.current) {
|
|
152
|
+
runtime.dispose?.();
|
|
153
|
+
return null;
|
|
154
|
+
}
|
|
155
|
+
return runtime;
|
|
156
|
+
} catch {
|
|
157
|
+
return null;
|
|
158
|
+
} finally {
|
|
159
|
+
setLoading(false);
|
|
160
|
+
}
|
|
161
|
+
})();
|
|
162
|
+
runtimePromiseRef.current = promise;
|
|
163
|
+
return promise;
|
|
164
|
+
};
|
|
165
|
+
}, [injected]);
|
|
166
|
+
const search = useMemo(() => {
|
|
167
|
+
return async (query) => {
|
|
168
|
+
if (!query.trim()) return { hits: [] };
|
|
169
|
+
const runtime = await ensureRuntime();
|
|
170
|
+
if (!runtime) return { hits: [] };
|
|
171
|
+
return runtime.search(query, locale);
|
|
172
|
+
};
|
|
173
|
+
}, [ensureRuntime, locale]);
|
|
174
|
+
return { search, loading };
|
|
175
|
+
}
|
|
176
|
+
function useNavData() {
|
|
177
|
+
const site = useSiteData();
|
|
178
|
+
const { pathname } = useLocation();
|
|
179
|
+
return site.nav?.[localeIdFor(site, pathname)] ?? [];
|
|
180
|
+
}
|
|
181
|
+
function useSidebarData() {
|
|
182
|
+
const site = useSiteData();
|
|
183
|
+
const { pathname } = useLocation();
|
|
184
|
+
return site.sidebar?.[localeIdFor(site, pathname)] ?? [];
|
|
185
|
+
}
|
|
186
|
+
function readStoredPrefers() {
|
|
187
|
+
try {
|
|
188
|
+
const v = localStorage.getItem(PREFERS_COLOR_STORAGE_KEY);
|
|
189
|
+
return v === "light" || v === "dark" || v === "auto" ? v : null;
|
|
190
|
+
} catch {
|
|
191
|
+
return null;
|
|
192
|
+
}
|
|
193
|
+
}
|
|
194
|
+
function systemPrefersDark() {
|
|
195
|
+
try {
|
|
196
|
+
return window.matchMedia("(prefers-color-scheme: dark)").matches;
|
|
197
|
+
} catch {
|
|
198
|
+
return false;
|
|
199
|
+
}
|
|
200
|
+
}
|
|
201
|
+
function resolveColor(prefers) {
|
|
202
|
+
return prefers === "auto" ? systemPrefersDark() ? "dark" : "light" : prefers;
|
|
203
|
+
}
|
|
204
|
+
function applyColor(color) {
|
|
205
|
+
try {
|
|
206
|
+
document.documentElement.setAttribute(PREFERS_COLOR_ATTR, color);
|
|
207
|
+
} catch {
|
|
208
|
+
}
|
|
209
|
+
}
|
|
210
|
+
var prefersListeners = /* @__PURE__ */ new Set();
|
|
211
|
+
function emitPrefersChange() {
|
|
212
|
+
for (const l of prefersListeners) l();
|
|
213
|
+
}
|
|
214
|
+
function setPrefersColor(value) {
|
|
215
|
+
try {
|
|
216
|
+
localStorage.setItem(PREFERS_COLOR_STORAGE_KEY, value);
|
|
217
|
+
} catch {
|
|
218
|
+
}
|
|
219
|
+
applyColor(resolveColor(value));
|
|
220
|
+
emitPrefersChange();
|
|
221
|
+
}
|
|
222
|
+
function subscribePrefers(onChange) {
|
|
223
|
+
prefersListeners.add(onChange);
|
|
224
|
+
const media = (() => {
|
|
225
|
+
try {
|
|
226
|
+
return window.matchMedia("(prefers-color-scheme: dark)");
|
|
227
|
+
} catch {
|
|
228
|
+
return null;
|
|
229
|
+
}
|
|
230
|
+
})();
|
|
231
|
+
media?.addEventListener("change", onChange);
|
|
232
|
+
const onStorage = (e) => {
|
|
233
|
+
if (e.key === PREFERS_COLOR_STORAGE_KEY || e.key === null) onChange();
|
|
234
|
+
};
|
|
235
|
+
window.addEventListener("storage", onStorage);
|
|
236
|
+
return () => {
|
|
237
|
+
prefersListeners.delete(onChange);
|
|
238
|
+
media?.removeEventListener("change", onChange);
|
|
239
|
+
window.removeEventListener("storage", onStorage);
|
|
240
|
+
};
|
|
241
|
+
}
|
|
242
|
+
function getPrefersSnapshot() {
|
|
243
|
+
return readStoredPrefers() ?? "auto";
|
|
244
|
+
}
|
|
245
|
+
function usePrefersColor() {
|
|
246
|
+
const prefers = useSyncExternalStore(subscribePrefers, getPrefersSnapshot, () => void 0);
|
|
247
|
+
const color = prefers === void 0 ? void 0 : resolveColor(prefers);
|
|
248
|
+
return [color, prefers, setPrefersColor];
|
|
249
|
+
}
|
|
250
|
+
export {
|
|
251
|
+
ClientOnly,
|
|
252
|
+
PREFERS_COLOR_ATTR,
|
|
253
|
+
PREFERS_COLOR_BOOT_SCRIPT,
|
|
254
|
+
PREFERS_COLOR_STORAGE_KEY,
|
|
255
|
+
SearchRuntimeContext,
|
|
256
|
+
SearchRuntimeProvider,
|
|
257
|
+
SiteContext,
|
|
258
|
+
SiteProvider,
|
|
259
|
+
localeIdFor,
|
|
260
|
+
resolveConfiguredColor,
|
|
261
|
+
setPrefersColor,
|
|
262
|
+
useNavData,
|
|
263
|
+
usePrefersColor,
|
|
264
|
+
useRouteMeta,
|
|
265
|
+
useSidebarData,
|
|
266
|
+
useSiteData,
|
|
267
|
+
useSiteSearch
|
|
268
|
+
};
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
interface Route {
|
|
2
|
+
id: string;
|
|
3
|
+
path: string;
|
|
4
|
+
file: string;
|
|
5
|
+
locale?: string;
|
|
6
|
+
parentId?: string;
|
|
7
|
+
tab?: string;
|
|
8
|
+
}
|
|
9
|
+
interface ResolvedLocale {
|
|
10
|
+
id: string;
|
|
11
|
+
name: string;
|
|
12
|
+
base: string;
|
|
13
|
+
suffix: string;
|
|
14
|
+
}
|
|
15
|
+
interface NavItem {
|
|
16
|
+
title: string;
|
|
17
|
+
link?: string;
|
|
18
|
+
order: number;
|
|
19
|
+
activePath: string;
|
|
20
|
+
children?: NavItem[];
|
|
21
|
+
}
|
|
22
|
+
interface SidebarItem {
|
|
23
|
+
title: string;
|
|
24
|
+
link: string;
|
|
25
|
+
order: number;
|
|
26
|
+
frontmatter?: Record<string, unknown>;
|
|
27
|
+
}
|
|
28
|
+
interface SidebarGroup {
|
|
29
|
+
title?: string;
|
|
30
|
+
order: number;
|
|
31
|
+
children: SidebarItem[];
|
|
32
|
+
}
|
|
33
|
+
interface TocEntry {
|
|
34
|
+
id: string;
|
|
35
|
+
depth: number;
|
|
36
|
+
title: string;
|
|
37
|
+
}
|
|
38
|
+
interface PageSummary {
|
|
39
|
+
frontmatter: Record<string, unknown>;
|
|
40
|
+
toc?: TocEntry[];
|
|
41
|
+
tabs?: {
|
|
42
|
+
key: string;
|
|
43
|
+
title: string;
|
|
44
|
+
link: string;
|
|
45
|
+
}[];
|
|
46
|
+
}
|
|
47
|
+
interface SiteData {
|
|
48
|
+
base: string;
|
|
49
|
+
title: string;
|
|
50
|
+
description?: string;
|
|
51
|
+
locales: ResolvedLocale[];
|
|
52
|
+
themeConfig: Record<string, unknown>;
|
|
53
|
+
routes: Record<string, Route>;
|
|
54
|
+
meta: Record<string, PageSummary>;
|
|
55
|
+
nav: Record<string, NavItem[]>;
|
|
56
|
+
sidebar: Record<string, SidebarGroup[]>;
|
|
57
|
+
/** DM-803: theme ẩn ô tìm kiếm khi `false`. Optional để site data cũ/tay vẫn hợp lệ (mặc định bật). */
|
|
58
|
+
search?: {
|
|
59
|
+
enabled: boolean;
|
|
60
|
+
};
|
|
61
|
+
}
|
|
62
|
+
/** Phần config mà tầng route cần — ResolvedConfig (DM-201) thoả cấu trúc này. */
|
|
63
|
+
interface RouteConfig {
|
|
64
|
+
srcDir: string;
|
|
65
|
+
docDirs: {
|
|
66
|
+
dir: string;
|
|
67
|
+
}[];
|
|
68
|
+
locales: ResolvedLocale[];
|
|
69
|
+
forceKebabCase: boolean;
|
|
70
|
+
preset?: 'docs' | 'library';
|
|
71
|
+
}
|
|
72
|
+
interface RouteTable {
|
|
73
|
+
warnings: string[];
|
|
74
|
+
routes: Route[];
|
|
75
|
+
byId: Record<string, Route>;
|
|
76
|
+
byPath: Record<string, Route>;
|
|
77
|
+
byFile: Record<string, Route>;
|
|
78
|
+
configHash: string;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
export type { NavItem as N, PageSummary as P, Route as R, SidebarGroup as S, TocEntry as T, RouteConfig as a, RouteTable as b, ResolvedLocale as c, SiteData as d };
|
package/package.json
CHANGED
|
@@ -1,6 +1,72 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dommief",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"type": "module",
|
|
5
|
+
"main": "dist/index.js",
|
|
6
|
+
"types": "dist/index.d.ts",
|
|
7
|
+
"bin": {
|
|
8
|
+
"dommief": "dist/cli.js"
|
|
9
|
+
},
|
|
10
|
+
"exports": {
|
|
11
|
+
".": {
|
|
12
|
+
"types": "./dist/index.d.ts",
|
|
13
|
+
"default": "./dist/index.js"
|
|
14
|
+
},
|
|
15
|
+
"./theme-api": {
|
|
16
|
+
"types": "./dist/theme-api.d.ts",
|
|
17
|
+
"default": "./dist/theme-api.js"
|
|
18
|
+
},
|
|
19
|
+
"./client": {
|
|
20
|
+
"types": "./src/client/index.tsx",
|
|
21
|
+
"default": "./src/client/index.tsx"
|
|
22
|
+
}
|
|
23
|
+
},
|
|
24
|
+
"files": [
|
|
25
|
+
"dist",
|
|
26
|
+
"src/client",
|
|
27
|
+
"src/types.ts",
|
|
28
|
+
"src/routesModule.ts",
|
|
29
|
+
"src/theme-api.tsx",
|
|
30
|
+
"src/search-config.ts"
|
|
31
|
+
],
|
|
32
|
+
"scripts": {
|
|
33
|
+
"build": "tsup",
|
|
34
|
+
"dev": "tsup --watch"
|
|
35
|
+
},
|
|
36
|
+
"dependencies": {
|
|
37
|
+
"cac": "^7.1.0",
|
|
38
|
+
"chokidar": "^6.0.0",
|
|
39
|
+
"estree-util-to-js": "^2.0.0",
|
|
40
|
+
"github-slugger": "^2.0.0",
|
|
41
|
+
"hast-util-to-estree": "^3.1.3",
|
|
42
|
+
"minisearch": "^7.2.0",
|
|
43
|
+
"picocolors": "^1.1.1",
|
|
44
|
+
"react-docgen-typescript": "^2.4.0",
|
|
45
|
+
"rehype-raw": "^7.0.0",
|
|
46
|
+
"remark-directive": "^4.0.0",
|
|
47
|
+
"remark-frontmatter": "^5.0.0",
|
|
48
|
+
"remark-gfm": "^4.0.1",
|
|
49
|
+
"remark-parse": "^11.0.0",
|
|
50
|
+
"remark-rehype": "^11.1.2",
|
|
51
|
+
"shiki": "^4.5.0",
|
|
52
|
+
"unified": "^11.0.5",
|
|
53
|
+
"unist-util-visit": "^5.0.0",
|
|
54
|
+
"yaml": "^2.9.1",
|
|
55
|
+
"zod": "^4.6.7"
|
|
56
|
+
},
|
|
57
|
+
"peerDependencies": {
|
|
58
|
+
"react": "^19.0.0",
|
|
59
|
+
"react-dom": "^19.0.0",
|
|
60
|
+
"react-router": "^8.0.0",
|
|
61
|
+
"typescript": "^5.0.0",
|
|
62
|
+
"vite": "^8.0.0"
|
|
63
|
+
},
|
|
64
|
+
"devDependencies": {
|
|
65
|
+
"react": "^19.3.1",
|
|
66
|
+
"react-dom": "^19.3.1",
|
|
67
|
+
"react-router": "^8.5.0",
|
|
68
|
+
"tsup": "^9.0.0",
|
|
69
|
+
"typescript": "^5.9.3",
|
|
70
|
+
"vite": "^8.3.5"
|
|
71
|
+
}
|
|
72
|
+
}
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
import React, { useState } from 'react';
|
|
2
|
+
|
|
3
|
+
export interface ApiProp {
|
|
4
|
+
name: string;
|
|
5
|
+
type?: string;
|
|
6
|
+
required?: boolean;
|
|
7
|
+
description?: string;
|
|
8
|
+
defaultValue?: any;
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
export interface ApiEntry {
|
|
12
|
+
displayName: string;
|
|
13
|
+
description?: string;
|
|
14
|
+
props: ApiProp[];
|
|
15
|
+
src?: string;
|
|
16
|
+
hash?: string;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
export interface ApiProps {
|
|
20
|
+
src?: string;
|
|
21
|
+
data?: string | ApiEntry[];
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
export function DomApi({ src, data }: ApiProps) {
|
|
25
|
+
let entries: ApiEntry[] = [];
|
|
26
|
+
try {
|
|
27
|
+
if (Array.isArray(data)) entries = data;
|
|
28
|
+
else if (typeof data === 'string' && data) entries = JSON.parse(data);
|
|
29
|
+
} catch {
|
|
30
|
+
entries = [];
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
if (!entries || entries.length === 0) {
|
|
34
|
+
return <div className="dommief-api" data-src={src}>No API data</div>;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
return (
|
|
38
|
+
<div className="dommief-api" data-src={src}>
|
|
39
|
+
{entries.map((entry, i) => (
|
|
40
|
+
<div key={i} className="dommief-api__component">
|
|
41
|
+
<h3 className="dommief-api__name">{entry.displayName}</h3>
|
|
42
|
+
{entry.description ? <p className="dommief-api__desc">{entry.description}</p> : null}
|
|
43
|
+
<table className="dommief-api__table">
|
|
44
|
+
<thead>
|
|
45
|
+
<tr>
|
|
46
|
+
<th>Property</th>
|
|
47
|
+
<th>Type</th>
|
|
48
|
+
<th>Required</th>
|
|
49
|
+
<th>Description</th>
|
|
50
|
+
<th>Default</th>
|
|
51
|
+
</tr>
|
|
52
|
+
</thead>
|
|
53
|
+
<tbody>
|
|
54
|
+
{(entry.props || []).map((p, j) => (
|
|
55
|
+
<tr key={j}>
|
|
56
|
+
<td>{p.name}</td>
|
|
57
|
+
<td><code>{p.type}</code></td>
|
|
58
|
+
<td>{p.required ? 'yes' : 'no'}</td>
|
|
59
|
+
<td>{p.description}</td>
|
|
60
|
+
<td>{p.defaultValue != null ? String(p.defaultValue) : ''}</td>
|
|
61
|
+
</tr>
|
|
62
|
+
))}
|
|
63
|
+
</tbody>
|
|
64
|
+
</table>
|
|
65
|
+
</div>
|
|
66
|
+
))}
|
|
67
|
+
</div>
|
|
68
|
+
);
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/** @deprecated Use DomApi */
|
|
72
|
+
export const DumiApi = DomApi;
|
|
73
|
+
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
// Đặc tả: backlog DM-207. Cây `<Routes>` từ `virtual:dommief/routes`; route `*` cuối cùng.
|
|
2
|
+
// Suspense bọc **từng route**, không bọc cả <Routes> (tránh unmount cả trang khi chuyển trang).
|
|
3
|
+
import { Suspense, type ComponentType } from 'react';
|
|
4
|
+
import { Routes, Route } from 'react-router';
|
|
5
|
+
import virtualRoutes from 'virtual:dommief/routes';
|
|
6
|
+
import type { RouteModule } from '../routesModule.js';
|
|
7
|
+
import GlobalLayout from 'dommief/theme/layouts/GlobalLayout';
|
|
8
|
+
import DocLayout from 'dommief/theme/layouts/DocLayout';
|
|
9
|
+
import NotFound404 from 'dommief/theme/slots/NotFound';
|
|
10
|
+
const NotFound = NotFound404;
|
|
11
|
+
|
|
12
|
+
/** Fallback rỗng (không spinner — tránh nháy). Phase 5 theme thay bằng slot. */
|
|
13
|
+
export function RouteLoading() {
|
|
14
|
+
return null;
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* Dựng `<AppRoutes>` từ `RouteModule[]`; export riêng để test không cần Vite.
|
|
19
|
+
* `<Route path="*">` nằm trong **cùng** `<Routes>` để SSG (DM-404) render 404 qua đúng cây.
|
|
20
|
+
*/
|
|
21
|
+
export function createAppRoutes(routes: RouteModule[]) {
|
|
22
|
+
return function AppRoutes() {
|
|
23
|
+
return (
|
|
24
|
+
<GlobalLayout>
|
|
25
|
+
<Routes>
|
|
26
|
+
{routes.map((r) => {
|
|
27
|
+
// SAFETY: RouteModule.component là React.LazyExoticComponent (CONTRACTS §5); typed `unknown` vì repo không có @types/react.
|
|
28
|
+
const Page = r.component as ComponentType;
|
|
29
|
+
return (
|
|
30
|
+
<Route
|
|
31
|
+
key={r.id}
|
|
32
|
+
path={r.path}
|
|
33
|
+
element={
|
|
34
|
+
<Suspense fallback={<RouteLoading />}>
|
|
35
|
+
<DocLayout>
|
|
36
|
+
<Page />
|
|
37
|
+
</DocLayout>
|
|
38
|
+
</Suspense>
|
|
39
|
+
}
|
|
40
|
+
/>
|
|
41
|
+
);
|
|
42
|
+
})}
|
|
43
|
+
{/* THEME-API §6: NotFound KHÔNG nằm trong DocLayout (không phải trang tài liệu). */}
|
|
44
|
+
<Route path="*" element={<NotFound />} />
|
|
45
|
+
</Routes>
|
|
46
|
+
</GlobalLayout>
|
|
47
|
+
);
|
|
48
|
+
};
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
export const AppRoutes = createAppRoutes(virtualRoutes);
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import { useEffect, useLayoutEffect, useState, type ReactNode } from 'react';
|
|
2
|
+
|
|
3
|
+
// Đặc tả: docs/spec/THEME-API.md §4, §8; backlog DM-408.
|
|
4
|
+
// `useState(false) + useEffect` là cách KHÔNG gây hydration mismatch: server render `fallback`,
|
|
5
|
+
// và client cũng render `fallback` ở LẦN RENDER ĐẦU (y hệt cây server) rồi mới swap sang
|
|
6
|
+
// `children` — không bao giờ có "cây server khác cây client lần đầu của client".
|
|
7
|
+
// KHÔNG dùng `typeof window` trong thân component này (nó phải sạch, không tự là nguồn lỗi
|
|
8
|
+
// mà ssr-guard.ts chặn) — `useEffect` tự nhiên không chạy ở server nên không cần kiểm tra đó.
|
|
9
|
+
|
|
10
|
+
/** `useLayoutEffect` ở client, `useEffect` ở server (tránh warning "useLayoutEffect does nothing on the server"). */
|
|
11
|
+
const useIsomorphicLayoutEffect = typeof document === 'undefined' ? useEffect : useLayoutEffect;
|
|
12
|
+
|
|
13
|
+
export interface ClientOnlyProps {
|
|
14
|
+
children: ReactNode;
|
|
15
|
+
fallback?: ReactNode;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
export function ClientOnly({ children, fallback = null }: ClientOnlyProps) {
|
|
19
|
+
const [mounted, setMounted] = useState(false);
|
|
20
|
+
useIsomorphicLayoutEffect(() => { setMounted(true); }, []);
|
|
21
|
+
return mounted ? children : fallback;
|
|
22
|
+
}
|