@fecommunity/reactpress-toolkit 3.0.4 → 3.1.0

package/dist/ui/hooks/useReportArticleView.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Report article view on mount and return the latest view count for display.
+ */
+export declare function useReportArticleView(articleId: string | undefined, initialViews?: number): number | undefined;

package/dist/ui/hooks/useReportArticleView.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useReportArticleView = useReportArticleView;
+const react_1 = require("react");
+const api_envelope_1 = require("../../utils/api-envelope");
+const api_1 = require("../../theme/api/api");
+/**
+ * Report article view on mount and return the latest view count for display.
+ */
+function useReportArticleView(articleId, initialViews) {
+    const [views, setViews] = (0, react_1.useState)(initialViews);
+    (0, react_1.useEffect)(() => {
+        setViews(initialViews);
+    }, [articleId, initialViews]);
+    (0, react_1.useEffect)(() => {
+        if (!articleId)
+            return undefined;
+        let cancelled = false;
+        api_1.themeApi.article
+            .updateViewsById(articleId)
+            .then((res) => {
+            if (cancelled)
+                return;
+            const updated = (0, api_envelope_1.unpackOne)(res);
+            if (typeof updated?.views === 'number') {
+                setViews(updated.views);
+            }
+            else {
+                setViews((prev) => (typeof prev === 'number' ? prev + 1 : 1));
+            }
+        })
+            .catch((error) => {
+            console.error('[reactpress] report article view failed', error);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [articleId]);
+    return views;
+}

package/dist/ui/hooks/useReportPageView.d.ts

@@ -0,0 +1,11 @@
+export interface UseReportPageViewOptions {
+    /** Report on every render when URL changes; default uses current `window.location.href`. */
+    url?: string;
+    /** Skip localhost / 127.0.0.1 (default true). */
+    skipLocalhost?: boolean;
+    enabled?: boolean;
+}
+/**
+ * POST a page view once per distinct URL (browser only). Pair with layout shell or `_app`.
+ */
+export declare function useReportPageView(options?: UseReportPageViewOptions): void;

package/dist/ui/hooks/useReportPageView.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useReportPageView = useReportPageView;
+const react_1 = require("react");
+const api_1 = require("../../theme/api/api");
+/**
+ * POST a page view once per distinct URL (browser only). Pair with layout shell or `_app`.
+ */
+function useReportPageView(options = {}) {
+    const { url, skipLocalhost = true, enabled = true } = options;
+    const lastUrl = (0, react_1.useRef)(undefined);
+    (0, react_1.useEffect)(() => {
+        if (!enabled || typeof window === 'undefined')
+            return undefined;
+        const target = url ?? window.location.href;
+        if (skipLocalhost && /localhost|127\.0\.0\.1/.test(target))
+            return undefined;
+        if (lastUrl.current === target)
+            return undefined;
+        lastUrl.current = target;
+        api_1.themeApi.view
+            .create({ body: { url: target } })
+            .catch((error) => {
+            console.error('[reactpress] report page view failed', error);
+        });
+        return undefined;
+    });
+}

package/dist/ui/hooks/useRouteParam.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Resolve a dynamic route param during ISR fallback.
+ * Prefers the value from `getStaticProps`, then falls back to `router.query`.
+ */
+export declare function useRouteParam(propValue: string | undefined, paramName: string): string;

package/dist/ui/hooks/useRouteParam.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useRouteParam = useRouteParam;
+const router_1 = require("next/router");
+/**
+ * Resolve a dynamic route param during ISR fallback.
+ * Prefers the value from `getStaticProps`, then falls back to `router.query`.
+ */
+function useRouteParam(propValue, paramName) {
+    const router = (0, router_1.useRouter)();
+    if (propValue)
+        return propValue;
+    const queryValue = router.query[paramName];
+    return typeof queryValue === 'string' ? queryValue : '';
+}

package/dist/ui/hooks/useToggle.d.ts

@@ -0,0 +1,2 @@
+/** Boolean state with `toggle(next?)` — pass a boolean to set explicitly, or omit to flip. */
+export declare function useToggle(initialValue: boolean): [boolean, (arg?: boolean | null) => void];

package/dist/ui/hooks/useToggle.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useToggle = useToggle;
+const react_1 = require("react");
+/** Boolean state with `toggle(next?)` — pass a boolean to set explicitly, or omit to flip. */
+function useToggle(initialValue) {
+    const [value, setValue] = (0, react_1.useState)(initialValue);
+    const toggle = (0, react_1.useCallback)((arg = null) => {
+        if (arg !== null && typeof arg === 'boolean') {
+            setValue(arg);
+        }
+        else {
+            setValue((v) => !v);
+        }
+    }, []);
+    return [value, toggle];
+}

package/dist/ui/hooks/useWarningOnExit.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Confirm before leaving the page (browser refresh/close or Next.js route change).
+ * `warn` should return `true` to allow navigation, `false` to cancel.
+ */
+export declare function useWarningOnExit(shouldWarn: boolean, warn?: () => boolean): void;

package/dist/ui/hooks/useWarningOnExit.js

@@ -0,0 +1,59 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useWarningOnExit = useWarningOnExit;
+const router_1 = __importDefault(require("next/router"));
+const react_1 = require("react");
+/**
+ * Confirm before leaving the page (browser refresh/close or Next.js route change).
+ * `warn` should return `true` to allow navigation, `false` to cancel.
+ */
+function useWarningOnExit(shouldWarn, warn = () => true) {
+    (0, react_1.useEffect)(() => {
+        let isWarned = false;
+        const routeChangeStart = (url) => {
+            if (router_1.default.asPath !== url && shouldWarn && !isWarned) {
+                isWarned = true;
+                if (warn()) {
+                    router_1.default.push(url);
+                }
+                else {
+                    isWarned = false;
+                    router_1.default.events.emit('routeChangeError');
+                    router_1.default.replace(router_1.default, router_1.default.asPath, { shallow: true });
+                    throw 'Abort route change. Please ignore this error.';
+                }
+            }
+        };
+        const beforeUnload = (e) => {
+            if (shouldWarn && !isWarned) {
+                const event = e || window.event;
+                event.returnValue = 'Abort route change. Please ignore this error.';
+                return 'Abort route change. Please ignore this error.';
+            }
+            return null;
+        };
+        router_1.default.events.on('routeChangeStart', routeChangeStart);
+        window.addEventListener('beforeunload', beforeUnload);
+        router_1.default.beforePopState(({ url }) => {
+            if (router_1.default.asPath !== url && shouldWarn && !isWarned) {
+                isWarned = true;
+                if (warn()) {
+                    return true;
+                }
+                isWarned = false;
+                window.history.pushState(null, '', url);
+                router_1.default.replace(router_1.default, router_1.default.asPath, { shallow: true });
+                return false;
+            }
+            return true;
+        });
+        return () => {
+            router_1.default.events.off('routeChangeStart', routeChangeStart);
+            window.removeEventListener('beforeunload', beforeUnload);
+            router_1.default.beforePopState(() => true);
+        };
+    }, [warn, shouldWarn]);
+}

package/dist/ui/index.d.ts

@@ -0,0 +1,43 @@
+export type { ArchiveEmptyStateProps } from './components/ArchiveEmptyState';
+export { ArchiveEmptyState } from './components/ArchiveEmptyState';
+export type { ArchivePageLayoutProps } from './components/ArchivePageLayout';
+export { ArchivePageLayout } from './components/ArchivePageLayout';
+export type { ArticleCardArticle, ArticleCardLinkProps, ArticleCardProps } from './components/ArticleCard';
+export { ArticleCard } from './components/ArticleCard';
+export type { ArticleListProps } from './components/ArticleList';
+export { ArticleList } from './components/ArticleList';
+export type { BaseGlobalStylesProps } from './components/BaseGlobalStyles';
+export { BaseGlobalStyles } from './components/BaseGlobalStyles';
+export type { LocaleContextValue, LocaleProviderProps, ReactPressProviderProps, ThemeRuntimeContextValue, ThemeRuntimeProviderProps, SiteCatalogContextValue, SiteCatalogSiteConfig, SiteConfigNav, } from './context';
+export { LocaleProvider, ReactPressProvider, readPersistedLocale, SiteCatalogContext, SiteCatalogProvider, ThemeRuntimeProvider, useColorMode, useSiteCatalog, useSiteConfig, useSiteSetting, useSiteUser, useActiveThemeId, useIsThemePreview, useLocale, useSiteMeta, useThemeId, useThemeMod, useThemeModBool, useThemeRuntime, } from './context';
+export { useAsyncLoading, useForceUpdate, useNavActive, usePagination, useReportArticleView, useReportPageView, useRouteParam, useToggle, useWarningOnExit, } from './hooks';
+export type { PaginatedFetch, UsePaginationOptions, UsePaginationResult, UseReportPageViewOptions, } from './hooks';
+export type { LocaleSwitcherProps } from './components/LocaleSwitcher';
+export { LocaleSwitcher } from './components/LocaleSwitcher';
+export type { LocaleToggleButtonProps, ThemeToggleButtonProps, ToolbarIconButtonProps, } from './components/toolbar';
+export { LanguagesIcon, LocaleActiveIcon, LocaleEnToggleIcon, LocaleToggleButton, LocaleZhToggleIcon, localeToggleLabel, MoonIcon, nextLocale, SearchIcon, RP_TOOLBAR_BTN_CLASS, SunIcon, ThemeToggleButton, TOOLBAR_ICON_SIZE, ToolbarIconButton, } from './components/toolbar';
+export type { NavMenuProps, NavMenuRenderLinkProps } from './components/NavMenu';
+export { NavMenu } from './components/NavMenu';
+export type { NotFoundPanelProps } from './components/NotFoundPanel';
+export { NotFoundPanel } from './components/NotFoundPanel';
+export type { PageHeaderProps } from './components/PageHeader';
+export { PageHeader } from './components/PageHeader';
+export type { SiteBrandingProps } from './components/SiteBranding';
+export { SiteBranding } from './components/SiteBranding';
+export type { SiteDocumentProps } from './components/SiteDocument';
+export { SiteDocument } from './components/SiteDocument';
+export type { SiteDocumentFallbackProps } from './components/SiteDocumentFallback';
+export { SiteDocumentFallback } from './components/SiteDocumentFallback';
+export type { SiteLogoProps } from './components/SiteLogo';
+export { SiteLogo } from './components/SiteLogo';
+export type { SiteTaglineProps } from './components/SiteTagline';
+export { SiteTagline } from './components/SiteTagline';
+export type { TaxonomyItem, TaxonomyListProps, TaxonomyListRenderLinkProps, TaxonomyListVariant, } from './components/TaxonomyList';
+export { TaxonomyList } from './components/TaxonomyList';
+export { ThemeCssVars } from './components/ThemeCssVars';
+export type { ThemeLayoutProps } from './components/ThemeLayout';
+export { ThemeLayout } from './components/ThemeLayout';
+export type { SiteAnalyticsProps } from './components/SiteAnalytics';
+export { SiteAnalytics } from './components/SiteAnalytics';
+export type { SiteSeoProps } from './components/SiteSeo';
+export { SiteSeo } from './components/SiteSeo';

package/dist/ui/index.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NotFoundPanel = exports.NavMenu = exports.ToolbarIconButton = exports.TOOLBAR_ICON_SIZE = exports.ThemeToggleButton = exports.SunIcon = exports.RP_TOOLBAR_BTN_CLASS = exports.SearchIcon = exports.nextLocale = exports.MoonIcon = exports.localeToggleLabel = exports.LocaleZhToggleIcon = exports.LocaleToggleButton = exports.LocaleEnToggleIcon = exports.LocaleActiveIcon = exports.LanguagesIcon = exports.LocaleSwitcher = exports.useWarningOnExit = exports.useToggle = exports.useRouteParam = exports.useReportPageView = exports.useReportArticleView = exports.usePagination = exports.useNavActive = exports.useForceUpdate = exports.useAsyncLoading = exports.useThemeRuntime = exports.useThemeModBool = exports.useThemeMod = exports.useThemeId = exports.useSiteMeta = exports.useLocale = exports.useIsThemePreview = exports.useActiveThemeId = exports.useSiteUser = exports.useSiteSetting = exports.useSiteConfig = exports.useSiteCatalog = exports.useColorMode = exports.ThemeRuntimeProvider = exports.SiteCatalogProvider = exports.SiteCatalogContext = exports.readPersistedLocale = exports.ReactPressProvider = exports.LocaleProvider = exports.BaseGlobalStyles = exports.ArticleList = exports.ArticleCard = exports.ArchivePageLayout = exports.ArchiveEmptyState = void 0;
+exports.SiteSeo = exports.SiteAnalytics = exports.ThemeLayout = exports.ThemeCssVars = exports.TaxonomyList = exports.SiteTagline = exports.SiteLogo = exports.SiteDocumentFallback = exports.SiteDocument = exports.SiteBranding = exports.PageHeader = void 0;
+var ArchiveEmptyState_1 = require("./components/ArchiveEmptyState");
+Object.defineProperty(exports, "ArchiveEmptyState", { enumerable: true, get: function () { return ArchiveEmptyState_1.ArchiveEmptyState; } });
+var ArchivePageLayout_1 = require("./components/ArchivePageLayout");
+Object.defineProperty(exports, "ArchivePageLayout", { enumerable: true, get: function () { return ArchivePageLayout_1.ArchivePageLayout; } });
+var ArticleCard_1 = require("./components/ArticleCard");
+Object.defineProperty(exports, "ArticleCard", { enumerable: true, get: function () { return ArticleCard_1.ArticleCard; } });
+var ArticleList_1 = require("./components/ArticleList");
+Object.defineProperty(exports, "ArticleList", { enumerable: true, get: function () { return ArticleList_1.ArticleList; } });
+var BaseGlobalStyles_1 = require("./components/BaseGlobalStyles");
+Object.defineProperty(exports, "BaseGlobalStyles", { enumerable: true, get: function () { return BaseGlobalStyles_1.BaseGlobalStyles; } });
+var context_1 = require("./context");
+Object.defineProperty(exports, "LocaleProvider", { enumerable: true, get: function () { return context_1.LocaleProvider; } });
+Object.defineProperty(exports, "ReactPressProvider", { enumerable: true, get: function () { return context_1.ReactPressProvider; } });
+Object.defineProperty(exports, "readPersistedLocale", { enumerable: true, get: function () { return context_1.readPersistedLocale; } });
+Object.defineProperty(exports, "SiteCatalogContext", { enumerable: true, get: function () { return context_1.SiteCatalogContext; } });
+Object.defineProperty(exports, "SiteCatalogProvider", { enumerable: true, get: function () { return context_1.SiteCatalogProvider; } });
+Object.defineProperty(exports, "ThemeRuntimeProvider", { enumerable: true, get: function () { return context_1.ThemeRuntimeProvider; } });
+Object.defineProperty(exports, "useColorMode", { enumerable: true, get: function () { return context_1.useColorMode; } });
+Object.defineProperty(exports, "useSiteCatalog", { enumerable: true, get: function () { return context_1.useSiteCatalog; } });
+Object.defineProperty(exports, "useSiteConfig", { enumerable: true, get: function () { return context_1.useSiteConfig; } });
+Object.defineProperty(exports, "useSiteSetting", { enumerable: true, get: function () { return context_1.useSiteSetting; } });
+Object.defineProperty(exports, "useSiteUser", { enumerable: true, get: function () { return context_1.useSiteUser; } });
+Object.defineProperty(exports, "useActiveThemeId", { enumerable: true, get: function () { return context_1.useActiveThemeId; } });
+Object.defineProperty(exports, "useIsThemePreview", { enumerable: true, get: function () { return context_1.useIsThemePreview; } });
+Object.defineProperty(exports, "useLocale", { enumerable: true, get: function () { return context_1.useLocale; } });
+Object.defineProperty(exports, "useSiteMeta", { enumerable: true, get: function () { return context_1.useSiteMeta; } });
+Object.defineProperty(exports, "useThemeId", { enumerable: true, get: function () { return context_1.useThemeId; } });
+Object.defineProperty(exports, "useThemeMod", { enumerable: true, get: function () { return context_1.useThemeMod; } });
+Object.defineProperty(exports, "useThemeModBool", { enumerable: true, get: function () { return context_1.useThemeModBool; } });
+Object.defineProperty(exports, "useThemeRuntime", { enumerable: true, get: function () { return context_1.useThemeRuntime; } });
+var hooks_1 = require("./hooks");
+Object.defineProperty(exports, "useAsyncLoading", { enumerable: true, get: function () { return hooks_1.useAsyncLoading; } });
+Object.defineProperty(exports, "useForceUpdate", { enumerable: true, get: function () { return hooks_1.useForceUpdate; } });
+Object.defineProperty(exports, "useNavActive", { enumerable: true, get: function () { return hooks_1.useNavActive; } });
+Object.defineProperty(exports, "usePagination", { enumerable: true, get: function () { return hooks_1.usePagination; } });
+Object.defineProperty(exports, "useReportArticleView", { enumerable: true, get: function () { return hooks_1.useReportArticleView; } });
+Object.defineProperty(exports, "useReportPageView", { enumerable: true, get: function () { return hooks_1.useReportPageView; } });
+Object.defineProperty(exports, "useRouteParam", { enumerable: true, get: function () { return hooks_1.useRouteParam; } });
+Object.defineProperty(exports, "useToggle", { enumerable: true, get: function () { return hooks_1.useToggle; } });
+Object.defineProperty(exports, "useWarningOnExit", { enumerable: true, get: function () { return hooks_1.useWarningOnExit; } });
+var LocaleSwitcher_1 = require("./components/LocaleSwitcher");
+Object.defineProperty(exports, "LocaleSwitcher", { enumerable: true, get: function () { return LocaleSwitcher_1.LocaleSwitcher; } });
+var toolbar_1 = require("./components/toolbar");
+Object.defineProperty(exports, "LanguagesIcon", { enumerable: true, get: function () { return toolbar_1.LanguagesIcon; } });
+Object.defineProperty(exports, "LocaleActiveIcon", { enumerable: true, get: function () { return toolbar_1.LocaleActiveIcon; } });
+Object.defineProperty(exports, "LocaleEnToggleIcon", { enumerable: true, get: function () { return toolbar_1.LocaleEnToggleIcon; } });
+Object.defineProperty(exports, "LocaleToggleButton", { enumerable: true, get: function () { return toolbar_1.LocaleToggleButton; } });
+Object.defineProperty(exports, "LocaleZhToggleIcon", { enumerable: true, get: function () { return toolbar_1.LocaleZhToggleIcon; } });
+Object.defineProperty(exports, "localeToggleLabel", { enumerable: true, get: function () { return toolbar_1.localeToggleLabel; } });
+Object.defineProperty(exports, "MoonIcon", { enumerable: true, get: function () { return toolbar_1.MoonIcon; } });
+Object.defineProperty(exports, "nextLocale", { enumerable: true, get: function () { return toolbar_1.nextLocale; } });
+Object.defineProperty(exports, "SearchIcon", { enumerable: true, get: function () { return toolbar_1.SearchIcon; } });
+Object.defineProperty(exports, "RP_TOOLBAR_BTN_CLASS", { enumerable: true, get: function () { return toolbar_1.RP_TOOLBAR_BTN_CLASS; } });
+Object.defineProperty(exports, "SunIcon", { enumerable: true, get: function () { return toolbar_1.SunIcon; } });
+Object.defineProperty(exports, "ThemeToggleButton", { enumerable: true, get: function () { return toolbar_1.ThemeToggleButton; } });
+Object.defineProperty(exports, "TOOLBAR_ICON_SIZE", { enumerable: true, get: function () { return toolbar_1.TOOLBAR_ICON_SIZE; } });
+Object.defineProperty(exports, "ToolbarIconButton", { enumerable: true, get: function () { return toolbar_1.ToolbarIconButton; } });
+var NavMenu_1 = require("./components/NavMenu");
+Object.defineProperty(exports, "NavMenu", { enumerable: true, get: function () { return NavMenu_1.NavMenu; } });
+var NotFoundPanel_1 = require("./components/NotFoundPanel");
+Object.defineProperty(exports, "NotFoundPanel", { enumerable: true, get: function () { return NotFoundPanel_1.NotFoundPanel; } });
+var PageHeader_1 = require("./components/PageHeader");
+Object.defineProperty(exports, "PageHeader", { enumerable: true, get: function () { return PageHeader_1.PageHeader; } });
+var SiteBranding_1 = require("./components/SiteBranding");
+Object.defineProperty(exports, "SiteBranding", { enumerable: true, get: function () { return SiteBranding_1.SiteBranding; } });
+var SiteDocument_1 = require("./components/SiteDocument");
+Object.defineProperty(exports, "SiteDocument", { enumerable: true, get: function () { return SiteDocument_1.SiteDocument; } });
+var SiteDocumentFallback_1 = require("./components/SiteDocumentFallback");
+Object.defineProperty(exports, "SiteDocumentFallback", { enumerable: true, get: function () { return SiteDocumentFallback_1.SiteDocumentFallback; } });
+var SiteLogo_1 = require("./components/SiteLogo");
+Object.defineProperty(exports, "SiteLogo", { enumerable: true, get: function () { return SiteLogo_1.SiteLogo; } });
+var SiteTagline_1 = require("./components/SiteTagline");
+Object.defineProperty(exports, "SiteTagline", { enumerable: true, get: function () { return SiteTagline_1.SiteTagline; } });
+var TaxonomyList_1 = require("./components/TaxonomyList");
+Object.defineProperty(exports, "TaxonomyList", { enumerable: true, get: function () { return TaxonomyList_1.TaxonomyList; } });
+var ThemeCssVars_1 = require("./components/ThemeCssVars");
+Object.defineProperty(exports, "ThemeCssVars", { enumerable: true, get: function () { return ThemeCssVars_1.ThemeCssVars; } });
+var ThemeLayout_1 = require("./components/ThemeLayout");
+Object.defineProperty(exports, "ThemeLayout", { enumerable: true, get: function () { return ThemeLayout_1.ThemeLayout; } });
+var SiteAnalytics_1 = require("./components/SiteAnalytics");
+Object.defineProperty(exports, "SiteAnalytics", { enumerable: true, get: function () { return SiteAnalytics_1.SiteAnalytics; } });
+var SiteSeo_1 = require("./components/SiteSeo");
+Object.defineProperty(exports, "SiteSeo", { enumerable: true, get: function () { return SiteSeo_1.SiteSeo; } });

package/dist/utils/api-envelope.d.ts

@@ -0,0 +1,14 @@
+/** Nest TransformInterceptor body (axios already returns this as `response.data`). */
+export interface ApiEnvelope<T = unknown> {
+    statusCode?: number;
+    msg?: string | null;
+    success?: boolean;
+    data?: T;
+}
+/** Paginated endpoints: `data` is `[items, total]`. */
+export declare function unpackPaginated<T>(res: ApiEnvelope<[T[], number]> | null | undefined): T[];
+/** Paginated endpoints — returns `[items, total]`. */
+export declare function unpackPaginatedPair<T>(res: ApiEnvelope<[T[], number]> | null | undefined): [T[], number];
+/** List or single entity wrapped in `data`. */
+export declare function unpackList<T>(res: ApiEnvelope<T[]> | null | undefined): T[];
+export declare function unpackOne<T>(res: ApiEnvelope<T> | null | undefined): T | null;

package/dist/utils/api-envelope.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unpackPaginated = unpackPaginated;
+exports.unpackPaginatedPair = unpackPaginatedPair;
+exports.unpackList = unpackList;
+exports.unpackOne = unpackOne;
+/** Paginated endpoints: `data` is `[items, total]`. */
+function unpackPaginated(res) {
+    const payload = res?.data;
+    if (Array.isArray(payload) && Array.isArray(payload[0])) {
+        return payload[0];
+    }
+    return [];
+}
+/** Paginated endpoints — returns `[items, total]`. */
+function unpackPaginatedPair(res) {
+    const payload = res?.data;
+    if (Array.isArray(payload) && Array.isArray(payload[0])) {
+        return [payload[0], typeof payload[1] === 'number' ? payload[1] : payload[0].length];
+    }
+    return [[], 0];
+}
+/** List or single entity wrapped in `data`. */
+function unpackList(res) {
+    const data = res?.data;
+    return Array.isArray(data) ? data : [];
+}
+function unpackOne(res) {
+    const data = res?.data;
+    return data != null ? data : null;
+}

package/dist/utils/clipboard.d.ts

@@ -0,0 +1,2 @@
+/** Copy text to clipboard; returns whether the operation succeeded. */
+export declare function copyToClipboard(text: string): boolean;

package/dist/utils/clipboard.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.copyToClipboard = copyToClipboard;
+/** Copy text to clipboard; returns whether the operation succeeded. */
+function copyToClipboard(text) {
+    if (typeof navigator !== 'undefined' && navigator.clipboard?.writeText) {
+        void navigator.clipboard.writeText(text);
+        return true;
+    }
+    try {
+        const textarea = document.createElement('textarea');
+        textarea.value = text;
+        textarea.style.position = 'fixed';
+        textarea.style.opacity = '0';
+        document.body.appendChild(textarea);
+        textarea.select();
+        const ok = document.execCommand('copy');
+        document.body.removeChild(textarea);
+        return ok;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/utils/cookie.d.ts

@@ -0,0 +1,2 @@
+import type { IncomingMessage } from 'http';
+export declare function readRequestCookie(req: IncomingMessage | undefined, name: string): string | undefined;

package/dist/utils/cookie.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readRequestCookie = readRequestCookie;
+function readRequestCookie(req, name) {
+    const header = req?.headers?.cookie ?? '';
+    const match = new RegExp(`(?:^|;\\s*)${name}=([^;]*)`).exec(header);
+    if (!match?.[1])
+        return undefined;
+    try {
+        return decodeURIComponent(match[1]);
+    }
+    catch {
+        return match[1];
+    }
+}

package/dist/utils/date.d.ts

@@ -0,0 +1,4 @@
+export declare function formatDate(date: Date, format?: string): string;
+/** Format article `publishAt` for templates (SSR-safe). */
+export declare function formatPublishDate(value: string | Date | null | undefined, options?: Intl.DateTimeFormatOptions, locale?: string): string;
+export declare function formatPublishDateShort(value: string | Date | null | undefined): string;

package/dist/utils/date.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatDate = formatDate;
+exports.formatPublishDate = formatPublishDate;
+exports.formatPublishDateShort = formatPublishDateShort;
+function formatDate(date, format = 'YYYY-MM-DD') {
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, '0');
+    const day = String(date.getDate()).padStart(2, '0');
+    return format
+        .replace('YYYY', String(year))
+        .replace('MM', month)
+        .replace('DD', day);
+}
+/** Format article `publishAt` for templates (SSR-safe). */
+function formatPublishDate(value, options = {
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+}, locale = 'en-US') {
+    if (value == null || value === '')
+        return '';
+    try {
+        const date = value instanceof Date ? value : new Date(value);
+        if (Number.isNaN(date.getTime()))
+            return '';
+        return date.toLocaleDateString(locale, options);
+    }
+    catch {
+        return '';
+    }
+}
+function formatPublishDateShort(value) {
+    if (value == null || value === '')
+        return '';
+    try {
+        const date = value instanceof Date ? value : new Date(value);
+        if (Number.isNaN(date.getTime()))
+            return '';
+        return formatDate(date, 'YYYY-MM-DD');
+    }
+    catch {
+        return '';
+    }
+}

package/dist/utils/email.d.ts

@@ -0,0 +1,3 @@
+/** Permissive enough for common guest comment emails (qq/163/gmail, subdomains). */
+export declare const COMMENT_EMAIL_REGEXP: RegExp;
+export declare function isValidCommentEmail(email: string | undefined | null): boolean;

package/dist/utils/email.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMMENT_EMAIL_REGEXP = void 0;
+exports.isValidCommentEmail = isValidCommentEmail;
+/** Permissive enough for common guest comment emails (qq/163/gmail, subdomains). */
+exports.COMMENT_EMAIL_REGEXP = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+function isValidCommentEmail(email) {
+    return Boolean(email?.trim() && exports.COMMENT_EMAIL_REGEXP.test(email.trim()));
+}

package/dist/utils/error.d.ts

@@ -0,0 +1,7 @@
+export declare function isApiError(error: unknown): boolean;
+export declare class ApiError extends Error {
+    code: number;
+    details: unknown;
+    constructor(message: string, code?: number, details?: unknown);
+    static isInstance(error: unknown): error is ApiError;
+}

package/dist/utils/error.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiError = void 0;
+exports.isApiError = isApiError;
+function isApiError(error) {
+    return Boolean(error &&
+        typeof error === 'object' &&
+        'response' in error &&
+        error.response?.data);
+}
+class ApiError extends Error {
+    constructor(message, code = 500, details = null) {
+        super(message);
+        this.name = 'ApiError';
+        this.code = code;
+        this.details = details;
+    }
+    static isInstance(error) {
+        return (error instanceof ApiError ||
+            Boolean(error &&
+                typeof error === 'object' &&
+                error.name === 'ApiError' &&
+                error.code !== undefined));
+    }
+}
+exports.ApiError = ApiError;

package/dist/utils/image.d.ts

@@ -0,0 +1,7 @@
+export type ImageVariant = 'large' | 'medium' | 'thumb' | 'avatar';
+/**
+ * 根据展示场景解析图片 URL。
+ * 上传后的 WebP 资源会按 `_medium` / `_thumb` / `_avatar` 后缀生成多尺寸版本；
+ * 非 WebP 或无法识别的 URL 将原样返回，兼容历史数据。
+ */
+export declare function resolveImageUrl(url: string | null | undefined, variant?: ImageVariant): string;

package/dist/utils/image.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveImageUrl = resolveImageUrl;
+const VARIANT_SUFFIX = {
+    medium: '_medium',
+    thumb: '_thumb',
+    avatar: '_avatar',
+};
+const WEBP_VARIANT_PATTERN = /^(.+?)(?:_(medium|thumb|avatar))?\.webp(\?.*)?$/i;
+function extractWebpBase(url) {
+    const match = url.match(WEBP_VARIANT_PATTERN);
+    if (!match) {
+        return null;
+    }
+    return match[1];
+}
+/**
+ * 根据展示场景解析图片 URL。
+ * 上传后的 WebP 资源会按 `_medium` / `_thumb` / `_avatar` 后缀生成多尺寸版本；
+ * 非 WebP 或无法识别的 URL 将原样返回，兼容历史数据。
+ */
+function resolveImageUrl(url, variant = 'medium') {
+    if (!url) {
+        return '';
+    }
+    const base = extractWebpBase(url);
+    if (!base) {
+        return url;
+    }
+    if (variant === 'large') {
+        return `${base}.webp`;
+    }
+    return `${base}${VARIANT_SUFFIX[variant]}.webp`;
+}

package/dist/utils/index.d.ts

@@ -1,33 +1,15 @@
-/**
- * Format a date to the specified format
- * @param date - Date to format
- * @param format - Format string (default: YYYY-MM-DD)
- * @returns Formatted date string
- */
-export declare function formatDate(date: Date, format?: string): string;
-/**
- * Deep clone an object
- * @param obj - Object to clone
- * @returns Cloned object
- */
-export declare function deepClone<T>(obj: T): T;
-/**
- * Check if an error is an API error
- * @param error - Error to check
- * @returns True if it's an API error
- */
-export declare function isApiError(error: any): boolean;
-/**
- * API Error class
- */
-export declare class ApiError extends Error {
-    code: number;
-    details: any;
-    constructor(message: string, code?: number, details?: any);
-    /**
-     * Check if an object is an instance of ApiError
-     * @param error - Error to check
-     * @returns True if it's an ApiError instance
-     */
-    static isInstance(error: any): error is ApiError;
-}
+export type { ApiEnvelope } from './api-envelope';
+export { unpackList, unpackOne, unpackPaginated } from './api-envelope';
+export { readRequestCookie } from './cookie';
+export { formatDate, formatPublishDate, formatPublishDateShort, } from './date';
+export { COMMENT_EMAIL_REGEXP, isValidCommentEmail } from './email';
+export { ApiError, isApiError } from './error';
+export { jsonp } from './jsonp';
+export { safeJsonParse } from './json';
+export { deepClone, deepMerge, getByPath, getNestedLocaleString, getNestedLocaleValue, setByPath, } from './object';
+export type { SettingRow } from './setting';
+export { pickSiteSettings } from './setting';
+export { stripHtml, truncateWords } from './string';
+export { copyToClipboard } from './clipboard';
+export type { ImageVariant } from './image';
+export { resolveImageUrl } from './image';