feat(docs): add bilingual package documentation site

2026-09-20 15:53:28 +08:00
parent 60f6f1fb1a
commit dc80bd8ae0
111 changed files with 6531 additions and 0 deletions
@@ -0,0 +1,44 @@
+---
+title: Define an action
+description: Add product-specific behavior while preserving automatic dependency collection.
+order: 20
+toc:
+  - id: declare-the-action
+    title: Declare the action
+  - id: custom-control
+    title: Custom control
+  - id: typed-values
+    title: Typed values
+---
+
+## Declare the action {#declare-the-action}
+
+Keep the command and its editor dependencies in one definition:
+
+```tsx
+const Mention = defineLexicalAction({
+  name: "mention",
+  label: "Insert mention",
+  nodes: [MentionNode],
+  plugins: [MentionPopoverPlugin],
+  execute: ({ editor }) => openMentionPicker(editor),
+})
+```
+
+The node and plugin are enabled whenever `<Mention />` appears inside `LexicalActions`.
+
+## Custom control {#custom-control}
+
+```tsx
+<Mention>
+  {({ disabled, execute }) => (
+    <MentionButton disabled={disabled} onSelect={execute} />
+  )}
+</Mention>
+```
+
+Replacing the visible control does not change dependency collection.
+
+## Typed values {#typed-values}
+
+The render context exposes `execute(value?)` with the action's value type. `onClick` is the no-argument shortcut for ordinary buttons.
@@ -0,0 +1,30 @@
+---
+title: Localize the editor
+description: Connect built-in labels and custom actions to the workspace internationalization runtime.
+order: 21
+toc:
+  - id: add-the-catalog
+    title: Add the catalog
+  - id: fallback
+    title: Fallback
+  - id: custom-labels
+    title: Custom labels
+---
+
+## Add the catalog {#add-the-catalog}
+
+```json
+{
+  "catalogSources": ["@workspace/lexical/locales/{locale}"]
+}
+```
+
+The package ships American English (`en-US`) and Simplified Chinese (`zh-Hans`) editor catalogs.
+
+## Fallback {#fallback}
+
+Built-in controls follow the active `@workspace/i18n` provider. Outside a provider, they fall back to English so the editor remains usable in isolated previews and tests.
+
+## Custom labels {#custom-labels}
+
+An external action label can be a plain string or a message descriptor containing `id` and `message`. Descriptors participate in the same extraction workflow as application copy.
@@ -0,0 +1,46 @@
+---
+title: Add media
+description: Insert uploaded media and resolve images pasted or dragged into the editor.
+order: 30
+toc:
+  - id: image-and-video
+    title: Image and video
+  - id: clipboard-images
+    title: Clipboard images
+  - id: editing-media
+    title: Editing media
+---
+
+## Image and video {#image-and-video}
+
+The default `Image` and `Video` actions open built-in input dialogs. A custom uploader can hand the completed payload directly to the action:
+
+```tsx
+<Image>
+  {({ execute }) => (
+    <ImageUploader
+      onUploaded={({ src, alt, caption }) => execute({ src, alt, caption })}
+    />
+  )}
+</Image>
+```
+
+## Clipboard images {#clipboard-images}
+
+The full preset includes `ClipboardImages`. For production, resolve pasted and dropped files through object storage:
+
+```tsx
+<ClipboardImages
+  resolveImage={async (file, { reportProgress, signal }) => {
+    const uploaded = await uploadImage(file, {
+      signal,
+      onProgress: reportProgress,
+    })
+    return { alt: file.name, src: uploaded.url }
+  }}
+/>
+```
+
+## Editing media {#editing-media}
+
+Selected images support resizing, captions, alignment, and visible or keyboard deletion. Non-image clipboard files remain under normal browser handling.
@@ -0,0 +1,42 @@
+---
+title: Arrange actions
+description: Replace the preset with explicit actions and place controls in the correct editing surfaces.
+order: 11
+toc:
+  - id: explicit-actions
+    title: Explicit actions
+  - id: placement
+    title: Placement
+  - id: action-groups
+    title: Action groups
+---
+
+## Explicit actions {#explicit-actions}
+
+Switch from a preset to children when the product needs exact feature and ordering control:
+
+```tsx
+<LexicalActions>
+  <Undo />
+  <Redo />
+  <Bold />
+  <Italic />
+  <Link />
+</LexicalActions>
+```
+
+## Placement {#placement}
+
+Actions default to the fixed toolbar. The `in` prop accepts one area or several:
+
+```tsx
+<Bold in={["toolbar", "bubble"]} />
+<Date in="bubble" />
+<ClearFormatting in="footer" />
+```
+
+Hidden actions provide editor behavior without rendering a control. `DraggableBlocks` uses this pattern.
+
+## Action groups {#action-groups}
+
+`ActionGroup` can be a logical group or a visible menu. Use a menu for mutually related choices such as normal text, headings, quotes, and list styles.
@@ -0,0 +1,47 @@
+---
+title: Create the editor
+description: Render the root, content surface, toolbars, and a complete default action set.
+order: 10
+toc:
+  - id: styles
+    title: Styles
+  - id: editor-structure
+    title: Editor structure
+  - id: presets
+    title: Presets
+---
+
+## Styles {#styles}
+
+Import the editor stylesheet once in the application:
+
+```ts
+import "@workspace/lexical/globals.css"
+```
+
+## Editor structure {#editor-structure}
+
+```tsx
+import {
+  LexicalActions,
+  LexicalBubbleToolbar,
+  LexicalContent,
+  LexicalFixedToolbar,
+  LexicalFooter,
+  LexicalRoot,
+} from "@workspace/lexical"
+
+;<LexicalRoot value="" onChange={setHtml}>
+  <LexicalActions useDefaults="full" />
+  <LexicalFixedToolbar />
+  <LexicalContent placeholder="Start writing…" />
+  <LexicalBubbleToolbar />
+  <LexicalFooter />
+</LexicalRoot>
+```
+
+Toolbars and the footer render no DOM when their region has no actions and no custom children.
+
+## Presets {#presets}
+
+Choose `minimal` for basic text editing or `full` for the complete built-in feature set. Preset mode intentionally does not accept manual action children.
@@ -0,0 +1,26 @@
+---
+title: Overview
+description: Learn the editor's declarative action model before assembling a complete editing surface.
+order: 1
+toc:
+  - id: mental-model
+    title: Mental model
+  - id: tutorial-map
+    title: Tutorial map
+  - id: stable-capabilities
+    title: Stable capabilities
+---
+
+## Mental model {#mental-model}
+
+`@workspace/lexical` treats editor actions as declarations. Each action describes its behavior and the nodes, plugins, or embeds it requires. `LexicalRoot` collects those requirements before creating the editor.
+
+Toolbars decide where an action appears; they do not separately register editor capabilities.
+
+## Tutorial map {#tutorial-map}
+
+You will create the root and content surface, choose a preset, customize action placement, define an application action, add media uploads, and finish with localized labels.
+
+## Stable capabilities {#stable-capabilities}
+
+Actions, nodes, and plugins are fixed when an editor instance is created. Give `LexicalRoot` a new React `key` when the application needs to replace the entire capability set.