@composy/layout-react

React 18/19 运行时与编辑器适配层。Grid/GridItem 渲染与 Vue/Vanilla 一致的 CSS Grid runtime（断点响应式），LayoutEditor 封装框架无关的 @composy/layout-editor，MaterialDragSource 提供物料拖拽源，且整个包不 import GridStack，不对外暴露引擎类型。它把 @composy/layout-core 的 LayoutDocument 模型以 React 组件形式暴露给上层应用。

安装

# pnpm
pnpm add @composy/layout-react

# npm
npm install @composy/layout-react

目录结构

packages/react/src/
├── index.ts                # 入口：导出 Grid / GridItem / LayoutEditor / MaterialDragSource、类型与重导出的 core/editor 类型
├── Grid.tsx                # 响应式 CSS Grid 渲染组件
├── GridItem.tsx            # 单个网格项组件
├── LayoutEditor.tsx        # 编辑器 React 包装组件（透传 LayoutEditor 实例）
├── MaterialDragSource.tsx  # 物料拖拽源组件
├── material-renderer.ts    # renderReactMaterial：按 React 组件 / Web Component / HTML descriptor 渲染
└── types.ts                # LayoutGridProps、LayoutGridHandle、LayoutEditorProps、LayoutEditorHandle 等组件类型

核心 API 详表

组件

| 名称 | 类型 | 用途 | | -------------------- | ------------------ | --------------------------------------------------------------------------- | | Grid | 组件（forwardRef） | 渲染响应式 CSS Grid 布局，随宿主宽度自动解析断点；children 支持 render-prop | | GridItem | 组件 | 单个网格项，按断点 placement 渲染 | | LayoutEditor | 组件（forwardRef） | 包装 createLayoutEditor，提供挂载/卸载/模式/文档同步的 React 生命周期管理 | | MaterialDragSource | 组件 | 把子元素包装成可拖拽的物料源，注册到编辑器引擎 |

组件 Props / Ref

| 名称 | 类型 | 说明 | | -------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | LayoutGridHandle | 接口（ref） | getBreakpoint(): BreakpointId、getElement(): HTMLDivElement \| null，由 Grid 暴露 | | LayoutGridProps | 接口 | document、可选 breakpoint、readonly、materials、className/style、children（render-prop，见示例） | | LayoutEditorHandle | 接口（ref） | editor: LayoutEditor、getElement(): HTMLDivElement \| null，由 LayoutEditor 暴露 | | LayoutEditorProps | 接口 | document、engine、materials、mode、preview、className/style、children、以及 onDocumentChange/onChange/onReady 回调 |

重导出类型（自 @composy/layout-core / @composy/layout-editor）

@composy/layout-react 仅以类型形式重导出，避免运行时引入无关实现：

• 自 core：BreakpointId、LayoutDocument、LayoutNode、LayoutPlacement、MaterialDefinition
• 自 editor：LayoutEditor（作为 LayoutEditorInstance）、LayoutEditorEngine、LayoutEditorOptions，另经 types 导出核心事件类型

使用示例

import { useState } from 'react'
import { Grid, LayoutEditor } from '@composy/layout-react'
import type { LayoutDocument } from '@composy/layout-core'

// 1) 纯展示式响应式网格
function Preview({ document }: { document: LayoutDocument }) {
  return (
    <Grid document={document} breakpoint='desktop'>
      {({ item, placement }) => (
        <Widget type={item.type} props={item.props} placement={placement} />
      )}
    </Grid>
  )
}

// 2) 接入编辑器（搭配任意 LayoutEditorEngine，例如 gridstack 引擎）
function Workspace() {
  const [document, setDocument] = useState<LayoutDocument>(initialDoc)
  return (
    <LayoutEditor document={document} engine={gridStackEngine} onDocumentChange={setDocument}>
      {({ editor }) => (
        <Toolbar onAdd={() => editor.addItem({ type: 'card' })} onUndo={editor.undo} />
      )}
    </LayoutEditor>
  )
}

构建脚本 & 验证命令

pnpm build        # 使用 @composy/builder 的 ldesign-builder 打包
pnpm type-check   # tsc --noEmit 类型检查
pnpm test:run     # ltesting run:unit 运行单元测试
pnpm release      # ldesign-release 发布当前目录

产物说明

通过 ldesign-builder 输出三套目标：

• es/：ESM 产物（es/index.js + es/index.d.ts），module/types/import 指向这里；
• lib/：CJS 产物（lib/index.cjs），main 与 require 指向这里；
• dist/：浏览器产物（dist/index.min.js），unpkg/jsdelivr/browser 指向这里。

与其它包的差异：本包 sideEffects 声明了 *.vue、*.tsx、*.jsx、dist/*、es/**/style/** 等，用于保留组件/样式副作用，并按需保留样式目录。

备注

• peerDependencies 为 react: ^18.0.0 || ^19.0.0（无 React DOM 运行时依赖，仅依赖 @composy/layout-core、@composy/layout-editor、@composy/layout-runtime）。
• 组件事件与生命周期对 React StrictMode 安全：LayoutEditor 挂载/卸载会正确 off 事件并 destroy() 编辑器；MaterialDragSource 注册的拖拽源也会在卸载时清理。
• Grid 仅在省略 breakpoint 时才通过 ResizeObserver 监听宿主宽度解析断点；传入 breakpoint 则渲染完全确定，便于测试与 SSR。
• 编辑器实例应保持稳定（用 useRef/模块级持有），onDocumentChange 只在编辑器事务真正提交后触发，避免把内部分子状态回写死循环。
• License: MIT。