@web-mods/articles 1.1.4 → 1.1.5

package/README.md

@@ -10,10 +10,18 @@ pnpm add @web-mods/articles
 
 ## 导航设置
 
+本次新增功能的后端统一交接文档：[文章展示、分类与导航对接](docs/backend-integration-handoff.md)，包含已确认规则、建议接口、示例及联调验收。
+
+已核对 API 仓库 `main@8f0eb08`，具体文件、数据模型、迁移及复用方案见 [API 源码修改分析](docs/backend-source-analysis.md)。
+
 文章保存时提交 `navEnabled`、`navname`、`navPlacements`，编辑时回显接口配置。启用导航需填写名称并选择至少一个展示位置，网站地址必填。
 
 父导航从 `GET /navigation/groups?host=...&position=...` 读取，通过 `POST /navigation/groups` 创建并选中真实 ID，不提供前端示例选项。切换网站地址会清空父导航选择并重新加载；关闭导航会保留名称和位置。页眉暂时仅支持顶级导航，已有父导航只读保留；页尾可选父导航。
 
+页尾父导航下拉框旁提供「调整顺序」，通过拖动左侧手柄或点击上移、下移调整同站点父导航分组的展示顺序；Guides 分类排序使用相同操作。手柄支持鼠标、触摸及键盘上下方向键，拖动时按 Escape 可撤销本次拖动。「保存顺序」独立于文章保存，取消文章编辑不会撤销已保存的排序；排序不改变文章所属父导航。自定义 service 实现可选的 `reorderNavigationGroups` 后显示排序入口。
+
+默认 service 已接入 `PUT /navigation/groups/order`，将组件中的 `groupIds` 映射为 HTTP 请求的 `ids`，提交同站点、同位置的完整父导航顺序。收到 409 时提示取消并重新打开排序，以重新加载最新列表。
+
 自定义 `ArticleService` 可实现 `getNavigationGroups`、`createNavigationGroup`；未实现查询方法时禁用导航编辑，文章保存省略导航字段，兼容旧宿主。
 
 写操作需要 Bearer Token。默认 service 每次请求会读取当前页面的 `localStorage.accessToken`，并加入 `Authorization: Bearer ...`。自定义 service 可复用宿主凭证：
@@ -24,7 +32,11 @@ const articleService = createArticleService('https://api-blog.aisee.live', {
 })
 ```
 
-本地调试运行 `pnpm dev`（或 `pnpm playground`），访问 `http://localhost:5173/articles`。页面使用默认 service，直接请求 `src/service.ts` 中配置的 `https://api-blog.aisee.live`。仅监听组件库构建请运行 `pnpm build:watch`。
+本地调试运行 `pnpm dev`（或 `pnpm playground`），访问 `http://localhost:5173/articles`。页面使用默认 service，请求正式 API 地址 `https://api-blog.aisee.live`；也可通过 `createArticleService(baseURL)` 显式指定地址。仅监听组件库构建请运行 `pnpm build:watch`。
+
+默认 service 已接入 Guides 分类查询、新增、编辑及排序。排序将 `categoryIds` 映射为 `ids`；编辑分类只提交 `name`、`description`，不发送 `host`、`id`。文章保存支持 `guidesDisplay`：省略时保留配置，`null` 清除配置，对象设置配置。
+
+预览新功能运行 `pnpm dev --mode mock --port 5187`，访问 `http://localhost:5187/articles/guide-preview/edit`。使用现有 `ArticleEdit`、列表和详情组件，只替换注入的 service 为内存模拟数据；可体验 Guides 展示字段、分类编辑、分类排序与父导航排序，刷新后重置。不另做预览表单。`docs` 中相关设计草案保留历史方案，实际 HTTP 契约以默认 service 和本次后端接口文档（提交 `8230164`）为准。
 
 接口约定见 [技术交接文档](docs/article-navigation-implementation.md)。
 

package/dist/components/ArticleGuidesSettings.d.ts

@@ -0,0 +1,12 @@
+import type { ArticleGuidesDisplay, GuidesCategory } from '../types';
+export declare function ArticleGuidesSettings({ value, categories, categoriesDisabled, onChange, onSaveCategory, onLoadCategories, onReorderCategories }: {
+    value: ArticleGuidesDisplay;
+    categories: GuidesCategory[];
+    categoriesDisabled?: boolean;
+    onChange: (value: ArticleGuidesDisplay) => void;
+    onSaveCategory?: (category: Pick<GuidesCategory, 'name' | 'description'> & {
+        id?: string;
+    }) => Promise<GuidesCategory>;
+    onLoadCategories?: () => Promise<GuidesCategory[]>;
+    onReorderCategories?: (categoryIds: string[]) => Promise<GuidesCategory[]>;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/components/ItemOrderEditor.d.ts

@@ -0,0 +1,12 @@
+export declare function ItemOrderEditor<T extends {
+    id: string;
+    name: string;
+}>({ items, label, description, presentation, saveOrder, onSaved, onCancel }: {
+    items: T[];
+    label: string;
+    description: string;
+    presentation?: 'inline' | 'dialog';
+    saveOrder: (ids: string[]) => Promise<T[]>;
+    onSaved: (items: T[]) => void;
+    onCancel: () => void;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/components/ParentNavigationOrder.d.ts

@@ -0,0 +1,9 @@
+import type { ArticleService, NavigationGroup, NavPosition } from '../types';
+export declare function ParentNavigationOrder({ host, position, groups, reorder, onSaved, onCancel }: {
+    host: string;
+    position: NavPosition;
+    groups: NavigationGroup[];
+    reorder: NonNullable<ArticleService['reorderNavigationGroups']>;
+    onSaved: (groups: NavigationGroup[]) => void;
+    onCancel: () => void;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/components/ui/SettingsDialog.d.ts

@@ -0,0 +1,9 @@
+import { type ReactNode } from 'react';
+export declare function SettingsDialog({ id, open, busy, label, onDismiss, children }: {
+    id: string;
+    open: boolean;
+    busy: boolean;
+    label?: string;
+    onDismiss: () => void;
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;