@openviking/react 0.1.0 → 0.1.2

package/README.md

@@ -1,54 +1,73 @@
 # @openviking/react
 
-React UI modules for OpenViking applications. The initial scaffold exports `StatusBadge`; business modules have not been migrated.
+English / [中文](README_CN.md)
+
+React foundations for OpenViking AI application interfaces: build tooling, documentation, layered directories, and scoped styles. FileTree, Tui and FilePreview provide working views, alongside five file-type icons. Two business module placeholders support early layout integration; ScopeCascade provides a working cascade Hook and composition.
 
 This package inherits the repository's AGPL-3.0-only license. The release workflow publishes it to npm when a `react@<version>` tag matches the version in this package's manifest.
 
-## 模块目录
+## Module map
+
+| Source directory                                                       | Public entry                                  | Responsibility                                                                        |
+| ---------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------- |
+| [components/file-tree](./src/components/file-tree/README.md)           | `@openviking/react/components/file-tree`      | Directory tree rendering, expansion, selection and event callbacks                    |
+| [components/file-preview](./src/components/file-preview/README.md)     | `@openviking/react/components/file-preview`   | Read-only preview state and extension tabs; view is a placeholder                     |
+| [components/tui](./src/components/tui/README.md)                       | `@openviking/react/components/tui`            | Command record, result and input views with host-provided command metadata            |
+| [components/scope-switcher](./src/components/scope-switcher/README.md) | `@openviking/react/components/scope-switcher` | Stateless scope layout and independent ScopeSelector options, panels and search       |
+| [components/agent-connect](./src/components/agent-connect/README.md)   | `@openviking/react/components/agent-connect`  | Fixed Figma connection view with original icons, built-in copy and clipboard feedback |
+| [components/viking-bot](./src/components/viking-bot/README.md)         | `@openviking/react/components/viking-bot`     | Conversation contract with a placeholder view rendering against it                    |
+| [modules](./src/modules/README.md)                                     | `@openviking/react/modules/<module>`          | ScopeCascade Hooks and composition, plus two placeholder business modules             |
+| [client](./src/client/index.ts)                                        | `@openviking/react/client`                    | Framework-neutral request client: `createOvClient`, `OvClient`, `OvClientError`       |
+| [hooks](./src/hooks/README.md), [utils](./src/utils/README.md)         | Internal only                                 | Cross-module Hooks and pure utilities                                                 |
+
+Components implement their reviewed contracts incrementally. FileTree renders every documented row type with keyboard interaction; FilePreview implements the tab shell, header actions and the plain-text preview and editing foundation, with its body not yet wired to FileViewer. ScopeSwitcher is a stateless layout container; independently rendered ScopeSelector children own visibility, with host-owned per-level data subscriptions, search and requests. Tui renders records, results and the input. AgentConnect follows the Figma layout with built-in bilingual agent and developer integration content, host-provided credentials and locale, optional controlled selection and clipboard feedback. VikingBot provides a working view pending design review. Limits are described in each component's own docs. The package also ships five file-type icons.
+
+Components receive view data and state through props and express user intent through callbacks, following the [component directory conventions](./src/components/AGENTS.md). [modules](./src/modules/README.md) plan Hooks and views per business capability: Hooks load data, hold state and expose operations, and composite views wire them into components. Full pages and product-specific flows belong to the host; the admin console is out of scope for this phase. `file-browser` and `console` currently ship placeholder components, base Props / Labels types and styles so hosts can integrate layout first; business Hooks, data loading and cross-component coordination are not implemented yet.
+
+Modules consume the native OpenViking API through a shared Client by default, with the Provider supplying `baseURL`, headers and other configuration, and modules or standalone Hooks overriding individual fields through `requestOptions`. Standard integration needs no per-module Adapter; nonstandard gateways are adapted at the host's request boundary. The request contract — `OvRequestOptions`, `OvClient` and `OvClientError` — comes from the `@openviking/react/client` subpath, which ships a `fetch`-based `createOvClient`; the Provider is exported from the same subpath; these native API module Hooks are not implemented yet. ScopeCascade instead accepts three host API adapters and needs no Provider. See [request conventions](./src/modules/README.md#request-conventions-and-default-configuration).
 
-| 源码目录                                                                 | 公开入口                                       | 职责                             |
-| ------------------------------------------------------------------------ | ---------------------------------------------- | -------------------------------- |
-| [components/file-tree](./src/components/file-tree/README.md)             | `@openviking/react/components/file-tree`       | 目录树渲染、展开、选中与事件回传 |
-| [components/file-preview](./src/components/file-preview/README.md)       | `@openviking/react/components/file-preview`    | 只读预览状态与扩展页签           |
-| [components/tui](./src/components/tui/README.md)                         | `@openviking/react/components/tui`             | 命令输入、执行状态与结果展示     |
-| [components/viking-bot](./src/components/viking-bot/README.md)           | `@openviking/react/components/viking-bot`      | 对话、会话、回复及附件交互       |
-| [components/scope-switcher](./src/components/scope-switcher/README.md)   | `@openviking/react/components/scope-switcher`  | 作用域选择与切换交互             |
-| [components/agent-connect](./src/components/agent-connect/README.md)     | `@openviking/react/components/agent-connect`   | Agent 接入步骤、配置说明及状态   |
-| [components/resource-import](./src/components/resource-import/README.md) | `@openviking/react/components/resource-import` | 导入方式、文件选择、进度及结果   |
-| [pages](./src/pages/README.md)                                           | 尚无公开入口                                   | 页面组合、数据获取与处理         |
-| [hooks](./src/hooks/README.md)、[utils](./src/utils/README.md)           | 仅包内使用                                     | 跨模块 Hook 与纯工具             |
+Tui preserves JSON numeric tokens when indenting output. Structured resource links allow only `viking://`, `https://`, and `http://`; other targets render as text. Resource tables retain entry titles, native links and metadata. Output follows updates only near the bottom or after explicit submission. Read-only and disabled consoles cannot submit or insert help commands. `labels.resource` customizes the resource identity column.
 
-七个业务模块均为占位入口，尚无组件或类型可导入；对应 CSS 入口目前为空样式。`StatusBadge` 是唯一已实现的脚手架示例，可从根入口或 `@openviking/react/components/status-badge` 导入。
-组件通过 props 接收视图数据与状态，通过回调表达用户意图，遵循 [组件目录约定](./src/components/AGENTS.md)。[pages](./src/pages/README.md) 负责取数、处理业务状态和编排；尚未定义首个页面。
+### Props conventions
 
-## 公开入口与样式
+The same props are consumed by different hosts. Hosts differ in flows and interfaces while matching in interaction and UI, so:
 
-- 根入口聚合已实现的公开 API；具体组件使用 `components/<模块>` 子路径。不提供 `@openviking/react/components` 或 `@openviking/react/pages` 分类聚合 JS 入口。包导出显式列举，内部文件不开放。
-- 当前私有开发包的旧 `/tree`、`/preview`、`/console`、`/tui` 和 `/viking-bot` 子路径统一替换为上述分层路径，不保留旧路径别名。
-- JS 入口共享实现，不隐式加载 CSS。整包、组件集合与单模块样式由同一份源码构建，选择所需范围导入即可。
+- Components receive **already adapted data**: file entries, tabs and content sources are mapped into package types by module Hooks or the host, and components reference no host data model.
+- State is expressed with controlled fields, and callbacks only report intent without returning business data.
+- Copy is passed through labels, defaulting to English; hosts map i18next or Starling in their integration layer.
+- Icons, extension tabs, extra fields and toolbar actions come in as slots or nodes; components bind to no third-party UI library.
+- List components render the rows or items the caller has already expanded; paging, loading, error and empty states come from module Hooks or the host.
 
-| 范围     | CSS 入口                                        |
-| -------- | ----------------------------------------------- |
-| 整包     | `@openviking/react/style.css`                   |
-| 组件集合 | `@openviking/react/components/style.css`        |
-| 单组件   | `@openviking/react/components/<模块>/style.css` |
+## Public entries and styles
 
-单组件 CSS 可独立使用。后续有真实页面时再开放 `@openviking/react/pages/<页面>`、`pages/style.css` 及 `pages/<页面>/style.css`；页面 CSS 包含页面自身与依赖组件所需样式，整包 CSS 同步纳入页面样式。公共 Hook 有真实实现后再开放 `@openviking/react/hooks`；Hook 不提供 CSS。模块私有 Hook 和工具不进入公共导出。
+- The root entry exports each component and each business module placeholder with its main Props type (`<Component>Props`) only — currently `FileTree`, `Tui`, `ScopeSwitcher`, `ScopeSelector`, `ScopeCascade`, `AgentConnect` and the two business module placeholders. Row types, option types, handles and label bags come from the `components/<component>` and `modules/<module>` subpaths. `FilePreview` is not on the root entry: its types reference the optional `@ark-design/ui`, and putting it there would make that peer required. ScopeCascade exports a working three-level composition and per-level subscription Hooks from `modules/scope-cascade`; other business modules remain placeholders. No aggregate `@openviking/react/components` or `@openviking/react/modules` JavaScript entry. Package exports are listed explicitly and internal files stay closed.
+- Components expose only the explicitly listed layered subpaths, with no legacy path aliases.
+- JS entries share implementations and never load CSS implicitly. Whole-package, component-set and single-module stylesheets are built from the same source, so import the scope you need.
 
-经验看板属于预览扩展；任务进度先归所属模块；API Key 展示控件按需复用，凭证创建及管理由宿主负责。本次不新增这些独立模块。
+| Scope                  | CSS entry                                         |
+| ---------------------- | ------------------------------------------------- |
+| Whole package          | `@openviking/react/style.css`                     |
+| Component set          | `@openviking/react/components/style.css`          |
+| Single component       | `@openviking/react/components/<module>/style.css` |
+| Business module set    | `@openviking/react/modules/style.css`             |
+| Single business module | `@openviking/react/modules/<module>/style.css`    |
 
-## 使用示例
+Each CSS entry works standalone, and the whole-package CSS already includes module placeholder styles. Once real capability lands, module CSS must also include the composite view and the styles of the components it uses; using a module Hook alone needs no CSS. Cross-module public Hooks open `@openviking/react/hooks` only after a real implementation; module-specific public Hooks are exported from their module entry, and private Hooks and utilities stay out of public exports.
 
 ```tsx
-import { StatusBadge } from '@openviking/react';
-import '@openviking/react/style.css';
+import { FileBrowser } from '@openviking/react/modules/file-browser';
+import '@openviking/react/modules/file-browser/style.css';
 
-export default function Example() {
-  return <StatusBadge status="ready">Connected</StatusBadge>;
-}
+<FileBrowser
+  labels={{ title: 'File browser', description: 'Placeholder component.' }}
+/>;
 ```
 
-### 图标
+The remaining module exports `Console`; it currently accepts `className`, `style` and `labels`, and needs no Provider or request configuration.
+
+Experience dashboards belong to preview extensions; task progress starts inside its owning module; API Key display controls are reused on demand while credential creation and management belong to the host. No separate modules are added for these now.
+
+## Icons
 
 ```tsx
 import { PdfIcon } from '@openviking/react/icons';
@@ -56,8 +75,12 @@ import { PdfIcon } from '@openviking/react/icons';
 <PdfIcon width={20} height={20} className="file-icon" alt="PDF" />;
 ```
 
-图标默认以 16 × 16 的图片渲染。装饰性图标可沿用默认空 `alt`，用于传达文件类型时可提供描述。SVG 随构建产物内联，宿主直接消费包导出。
+Icons render as 16 × 16 images by default. Decorative icons can keep the empty `alt`, while icons that convey file type can provide a description. SVGs are inlined into the build output, and hosts consume them directly from the package exports.
 
 React and ReactDOM are peer dependencies (`^18.2.0 || ^19.0.0`), automatically externalized by Rslib. Rslib emits shared ESM JavaScript and declarations, plus independently built CSS entries. The public `@openviking/react/style.css` entry resolves to `dist/style.css`. Styles are scoped and do not reset application styles.
 
 From `frontend/`, run `npm run build:lib` to generate `packages/react/dist/`. See the [workspace README](../../README.md) for documentation development and deployment.
+
+### ScopeCascade
+
+Pass three stable API adapter functions to `useScopeCascade({ loadLibraries, loadSpaces, loadUsers })`, then render `<ScopeCascade controller={controller} />`. Adapters return `{ id, label }` options and receive an `AbortSignal`. The module handles dependent requests, descendant resets, loading, errors, retries and stale responses. Each selector subscribes independently; the Hook caller does not subscribe to request state. Import the Hook and composition from `@openviking/react/modules/scope-cascade` and its CSS from the corresponding `/style.css` entry.