@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" | ...
  label="title"
  box?={{ x: 100, y: 360, w: 1155 }}
  source?={{ path, kind, source }}
  metadata?={{ ... }}
  className?="..."
>
  字面上的可編輯文字
</Text>

屬性 (Props)

Name	Type	Default	Description
`label` required	`string`		穩定的局部 label，供系統介面、agent、comment 與 inline editing anchor 使用。建議使用 `title`、`caption`、`metric-a-value` 這類語意值；它不是 style token。
`as`	`keyof HTMLElementTagNameMap`	`"span"`	指定輸出之 DOM 元素標籤。應優先考量語意化標記（如 `h1`, `p`, `figcaption`）。
`box`	`FixedBox`		固定版面座標，使用目前 page geometry 的座標系。簡報 template 可用它對齊來源簡報的位置與尺寸。
`source`	`EditableSourceRef`		來源對應座標定義。當子元素為非靜態字面內容（如變數參考）時，必須手動提供以支援行內編輯。
`metadata`	`Record<string, string \| number \| boolean \| null>`		附帶於物件之結構化資訊。僅接受語意資料（如 `{ role: "kicker" }`），禁止傳入樣式值。
`...rest`	`HTMLAttributes<HTMLElement>`		透傳至基礎 DOM 節點之標準 HTML 屬性，包含 `className`。

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

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

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

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

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

<Text> 的視覺樣式應由 className 與 theme CSS 決定，例如字體、字級、行高與顏色。可編輯文字請放在 JSX children 內，不要藏在自訂 wrapper 的 title 或 description prop。

來源綁定行為

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