@open-press/core

Text

一個無樣式的可編輯文字物件。當簡報、卡片、封面、圖說或是客製化元件需要一個穩定的註解/行內編輯錨點，而您又不想發明新的樣式 API 時，請使用它。

<Text> 提供一個無自帶樣式之包裹層，用於將字面文字封裝為可支援系統標記、行內編輯與註解之 ObjectEntity。

設計契約： 此元件不提供任何排版屬性（如字體、大小、顏色）。視覺呈現必須透過 className 及外部 CSS 表達式實作。其唯一目的為建構穩定的物件標識符。

Component Impl

# `<Text>`

建立一個標記有編輯來源資訊之 DOM 節點。支援自動與手動 AST 位置對應。

import { Text } from "@open-press/core";

<Text
  as?="span" | "p" | "h1" | ...
  objectId="title"
  label="Slide title"
  source?={{ path, kind, objectId, source }}
  metadata?={{ ... }}
  className?="..."
>
  字面上的可編輯文字
</Text>

屬性 (Props)

Name	Type	Default	Description
`objectId` required	`string`		相對於當前 Frame 或父實體之局部唯一識別碼。渲染引擎自動轉換為 `text:...` 前綴格式供內部尋址使用。
`label` required	`string`		供系統介面與 Agent 閱讀之文字摘要標籤，如 `Slide title`、`Caption`。
`as`	`keyof HTMLElementTagNameMap`	`"span"`	指定輸出之 DOM 元素標籤。應優先考量語意化標記（如 `h1`, `p`, `figcaption`）。
`source`	`EditableSourceRef`		來源對應座標定義。當子元素為非靜態字面內容（如變數參考）時，必須手動提供以支援行內編輯。
`metadata`	`Record<string, string \| number \| boolean \| null>`		附帶於物件之結構化資訊。僅接受語意資料（如 `{ role: "kicker" }`），禁止傳入樣式值。
`...rest`	`HTMLAttributes<HTMLElement>`		透傳至基礎 DOM 節點之標準 HTML 屬性，包含 `className`。

範例：隱式來源綁定 (字面文字)

<Text as="h1" objectId="title" label="Slide title" className="slide-title">
  Fixed canvas workflow
</Text>

系統將在 SSR 編譯期間自動注入檔案座標，使其支援編輯工具與註解。

範例：顯式來源綁定 (動態變數)

<Text
  as="h1"
  objectId="title"
  label="Slide title"
  source={{
    path: "press/slide/press.tsx",
    kind: "tsx-text",
    objectId: "title",
    source: { line: 1, column: 16, endLine: 1, endColumn: 31 },
  }}
>
  {dynamicTitle}
</Text>

來源綁定行為

字面節點 (Literal Node)：由 @open-press/core 引入且內部全為純文字之 <Text> 實例，引擎自動於 AST 遍歷期間注入 EditableSourceRef。
表達式節點 (Expression Node)：依賴變數、函數調用或陣列 map 生成之內容，不具備自動映射能力，需仰賴開發者顯式傳遞 source 屬性方可解鎖編輯功能。
顯式聲明優先：若開發者手動提供 source 屬性，引擎將直接採用該值而略過自動計算機制。