From e3f92f0e7dcf15055f93042ef6b6aa3d42604788 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 17 Aug 2026 22:31:38 +0000 Subject: [PATCH] =?UTF-8?q?docs(plugin-view):=20README=20=E6=8C=89?= =?UTF-8?q?=E7=9C=9F=E5=AE=9E=E5=AF=BC=E5=87=BA=E9=9D=A2=E9=87=8D=E5=86=99?= =?UTF-8?q?=E8=99=9A=E6=9E=84=E7=9A=84=20viewComponents=20=E6=89=8B?= =?UTF-8?q?=E5=8A=A8=E6=B3=A8=E5=86=8C,ObjectViewSchema=20=E6=94=B9?= =?UTF-8?q?=E4=BB=8E=20@object-ui/types=20=E5=AF=BC=E5=85=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `### Manual Registration` 教的 `viewComponents` 在本包乃至全仓零命中(唯二命中就是 README 自己),照抄第一行即 `Object.entries(undefined)` 抛 TypeError。删掉该虚构节, 换成三节真话:七个 `ComponentRegistry.register` 调用认领的 schema 类型键表(含 `Registry.ts:195,240` 的命名空间键 + 裸 type 回落)、本包 39 个真实导出名、以及原片段 真正想做的事(把导出组件挂到自定义键)。 `ObjectViewSchema` 是真类型,但声明在 `@object-ui/types`(`objectql.ts`),本包只 import(`src/ObjectView.tsx:27`)不 re-export,按 README 原路径导入是 TS2305。修法是改 导入路径,⛔ 未新增任何导出或 re-export。改路径后示例的键面成为编译面上的断言,故随之 对齐真身:`objectName` 必填(`object` 不是声明成员)、`defaultViewType`、 `table.columns`。 其余未加类型标注的 schema 字面量键面(`object` / `viewMode` / `fields` / `mode` / `recordId` / `fieldConfig` / `nestedFields` / `tabs` …)渲染器一个都不读,性质不同、 需独立定级,另立卡不夹带。 Co-authored-by: Claude --- .changeset/plugin-view-readme-truth-5014.md | 15 +++ packages/plugin-view/README.md | 111 ++++++++++++++++++-- 2 files changed, 117 insertions(+), 9 deletions(-) create mode 100644 .changeset/plugin-view-readme-truth-5014.md diff --git a/.changeset/plugin-view-readme-truth-5014.md b/.changeset/plugin-view-readme-truth-5014.md new file mode 100644 index 0000000000..c77c90bb99 --- /dev/null +++ b/.changeset/plugin-view-readme-truth-5014.md @@ -0,0 +1,15 @@ +--- +'@object-ui/plugin-view': patch +--- + +docs: README 按真实导出面重写虚构的 `viewComponents` 手动注册,并把 `ObjectViewSchema` 的导入路径改到 `@object-ui/types` + +`### Manual Registration` 教的 `viewComponents` 在本包(以至全仓)零命中,照抄第一行就是 +`Object.entries(undefined)` 抛 TypeError;替换为三节真话:七个 `ComponentRegistry.register` +调用认领的 schema 类型键表、本包 39 个真实导出名、以及把导出组件挂到自定义键的写法。 + +`ObjectViewSchema` 是真类型,但声明在 `@object-ui/types`,本包只 import 不 re-export,按 +README 原路径导入是 TS2305;改导入路径(未新增任何导出或 re-export),示例键面随之对齐真身 +(`objectName` 必填、`defaultViewType`、`table.columns`)。 + +无代码/类型/运行时改动。声明 patch 是因为 `README.md` 在包的 `files` 里,随下次发布到 npm。 diff --git a/packages/plugin-view/README.md b/packages/plugin-view/README.md index 494a5417b9..954e55c63c 100644 --- a/packages/plugin-view/README.md +++ b/packages/plugin-view/README.md @@ -35,15 +35,94 @@ const schema = { }; ``` -### Manual Registration +### What the side-effect import registers + +Registration is *only* a side effect of importing the package — the single +`import '@object-ui/plugin-view'` above is the whole of it. There is no +components map to iterate over: importing the entry point runs the +`ComponentRegistry.register(...)` calls in `src/index.tsx`, which claim these +schema types: + +| Schema `type` | Namespaced key | Renderer | +| --- | --- | --- | +| `object-view` | `plugin-view:object-view` | `ObjectViewRenderer` | +| `view` | `plugin-view:view` | `ObjectViewRenderer` (alias of `object-view`) | +| `view-switcher` | `view:view-switcher` | `ViewSwitcher` | +| `filter-ui` | `view:filter-ui` | `FilterUI` | +| `sort-ui` | `view:sort-ui` | `SortUI` | +| `shared-view-link` | `view:shared-view-link` | `SharedViewLink` | +| `view:simple` | `plugin-view:view:simple` | `SimpleViewRenderer` (container) | + +Both spellings resolve — `register` stores the namespaced key *and* a bare-`type` +fallback (`packages/core/src/registry/Registry.ts:195,240`). Note the namespaces +are not uniform: `object-view` / `view` / `view:simple` register under +`plugin-view`, the four control components under `view`. + +`ObjectViewRenderer` is a thin internal wrapper — it pulls `dataSource` off the +renderer context and hands the schema to `ObjectView`. It is not exported, +because `ObjectView` itself takes `dataSource` as a **required prop**, not as a +schema key. + +### Public exports + +The package exports components, helpers and their types — not a registry map: + +```typescript +import { + ObjectView, // ObjectQL-integrated view: list + integrated create/edit + ViewSwitcher, // registered renderer for `view-switcher` + FilterUI, // registered renderer for `filter-ui` + SortUI, // registered renderer for `sort-ui` + SharedViewLink, // registered renderer for `shared-view-link` + ViewTabBar, // horizontal strip of saved-view tabs + ManageViewsDialog, // sortable dialog over every saved view + deriveRecordSurface, // record schema -> drawer / modal / page surface + deriveRecordFlowSurface, + deriveOverlaySize, + overlayWidthFor, + RECORD_SURFACE_PAGE_THRESHOLD, + deriveFieldOptions, // object fields -> picker options + toFilterGroup, // filter rules -> FilterGroup + toSortItems, // sort config -> SortItem[] + VIEW_TYPE_LABELS, + VIEW_TYPE_OPTIONS, + isImageLikeField, + isGeoLikeField, + pickPreferredField, + KANBAN_GROUP_PREFERRED, + PRIMARY_DATE_PREFERRED, + END_DATE_PREFERRED, + TITLE_PREFERRED, +} from '@object-ui/plugin-view'; + +import type { + ObjectViewProps, + ViewSwitcherProps, + FilterUIProps, + SortUIProps, + SharedViewLinkProps, + ViewTabBarProps, + ViewTabItem, + AvailableViewType, + ManageViewsDialogProps, + RecordSurface, + RecordFlow, + RecordFlowContainer, + RecordFlowSurface, + OverlaySize, + FieldOption, +} from '@object-ui/plugin-view'; +``` + +To serve one of these components under a registry key of your own, register the +exported component under that key: ```typescript -import { viewComponents } from '@object-ui/plugin-view'; import { ComponentRegistry } from '@object-ui/core'; +import { ViewSwitcher } from '@object-ui/plugin-view'; -// Register view components -Object.entries(viewComponents).forEach(([type, component]) => { - ComponentRegistry.register(type, component); +ComponentRegistry.register('my-switcher', ViewSwitcher, { + namespace: 'my-app', }); ``` @@ -333,14 +412,28 @@ const schema = { ## TypeScript Support +This package's type export surface is the seven `*Props` types plus the +record-surface and field-option types listed under "Public exports" — it ships +**no schema types**. The authored `type: 'object-view'` node is typed by +`@object-ui/types`, which this package imports (`src/ObjectView.tsx`) without +re-exporting, so import it from there: + +| Import from `@object-ui/types` | What it types | +| --- | --- | +| `ObjectViewSchema` | the whole `type: 'object-view'` node — `objectName` (required), `title`, `description`, `layout`, `defaultViewType`, `listViews`, `defaultListView`, `navigation`, `table`, `form`, `searchableFields`, `filterableFields`, `show*`, `operations`, `onNavigate`, `viewTabBar`, `viewActions` | +| `NamedListView` | one entry of `listViews` | +| `ViewNavigationConfig` | `navigation` — row/item click behaviour | +| `ViewTabBarConfig` | `viewTabBar` — tab-bar UX (inline add, overflow, indicators) | + ```typescript -import type { ObjectViewSchema } from '@object-ui/plugin-view'; +import type { ObjectViewSchema } from '@object-ui/types'; const userView: ObjectViewSchema = { type: 'object-view', - object: 'users', - viewMode: 'grid', - fields: ['name', 'email', 'role'] + objectName: 'users', + defaultViewType: 'grid', + // Displayed columns are grid configuration, inherited from ObjectGridSchema. + table: { columns: ['name', 'email', 'role'] }, }; ```