ebox/docs/user/ebox-api-reference.en.md

Ebox public API reference

中文

This reference describes the current public boundary of the standalone Ebox package. It separates the ordinary author path from the evaluated typed API used by framework integrations. Names beginning with ebox-- are private.

Ebox requires Emacs 29.1 or newer, ECSS, and TP:

(require 'ebox)

1. Author grammar

ebox-build accepts exactly these author entries:

STRING
(text PROPERTY VALUE ... STRING)
(box PROPERTY VALUE ... CHILD ...)
(row PROPERTY VALUE ... CHILD ...)
(column PROPERTY VALUE ... CHILD ...)
(flex PROPERTY VALUE ... CHILD ...)
(grid PROPERTY VALUE ... CHILD ...)

STRING is the short form of (text STRING). A Text form requires exactly one string payload. Every Box form accepts zero or more directly nested Text or Box children. The form name selects Normal, Row, Column, Flex, or Grid child layout; authors do not pass a layout selector as a property.

(ebox-build
 '(column :padding (1 2)
          (box :id "status" :color "#166534" "Ready")
          (row :item-gap 1
               (box "Left")
               (box "Right"))))

The author source fields are :key, :class, and :id. :outer is inline or block and controls how a Box participates in its parent.

Layout-owned properties

Form or relationship	Properties
row, column	:item-gap, :cross-align
flex	:flex-direction, :flex-wrap, :flex-flow, :justify-content, :align-items, :align-content, :gap, :row-gap, :column-gap
Direct child Box of flex	:order, :flex, :flex-grow, :flex-shrink, :flex-basis, :align-self
grid	:grid-template-columns, :grid-template-rows, :grid-auto-columns, :grid-auto-rows, :grid-auto-flow, :justify-items, :justify-content, :align-items, :align-content, :gap, :row-gap, :column-gap
Direct child Box of grid	:order, :grid-column, :grid-row, :grid-column-span, :grid-row-span, :align-self

Participation properties are ordinary child Box properties. They do not create another public node or wrapper.

Common current properties

Area	Current inputs
Size	:box-sizing, :width, :min-width, :max-width, :height, :min-height, :max-height
Edges	:padding, :margin, :border, side shorthands, and their longhands
Paint	:color, :background-color, exact alias :bgcolor, border colors, :visibility
Text layout	:text-align, :wrap-mode (word, char, kp, none)
Overflow	:overflow (visible, hidden, scroll)

Ordinary horizontal numbers are character columns; a one-element horizontal list is pixels. Vertical numbers are lines. (viewport) and (viewport-height) use the current render context. Property validation belongs to Ebox and invalid context/value combinations signal an error.

2. Evaluated typed construction

Frameworks that already own author parsing can construct canonical nodes directly:

(let ((layout (ebox-column-layout-create
               :item-gap 1 :cross-align 'stretch)))
  (ebox-box-create
   :layout layout
   :children (list (ebox-text-create :value "One")
                   (ebox-text-create :value "Two"))))

• ebox-text-create requires :value STRING.
• ebox-normal-layout-create creates Normal LayoutConfig.
• ebox-row-layout-create and ebox-column-layout-create accept :item-gap and :cross-align.
• ebox-flex-layout-create creates a validated Flex LayoutConfig.
• ebox-grid-layout-create creates a validated Grid LayoutConfig.
• ebox-box-create requires one typed :layout value and accepts a :children list of typed nodes.

The last two fields belong only to this evaluated integration contract. They are not author properties or alternate DSL syntax.

Node inspection functions are ebox-node-kind, ebox-text-node-p, ebox-box-node-p, ebox-node-source-handle, ebox-text-node-value, ebox-box-node-layout, ebox-box-node-children, and ebox-box-node-range-anchors. They are public from the typed module even though the facade inventory below focuses on application entry points.

3. Rendering and retained publication

Function	Contract
ebox-render	Return a propertized string without publishing a live buffer.
ebox-render-to-buffer	Copy the built root, mount a retained TP surface, enable ebox-buffer-mode, and return the buffer.
ebox-display-buffer	Render through the retained path, delete other windows, and switch to the result.
ebox-commit	Atomically publish a newly built root or one-shot logical candidate.
ebox-buffer-update-report	Return a defensive copy of the last successful update report.
ebox-rerender-buffer-with-context	Apply explicit viewport width and optional height while retaining identity.
ebox-viewport-window-width	Return Ebox's display-safe pixel width for a window.

ebox-commit accepts optional framework publish and rollback callbacks. They join the existing atomic publication; failures restore the previous buffer, surface, runtime state, and successful report.

ebox-call-with-render-burst is the exception-safe allocation/GC boundary for a framework callback. ebox-render-burst-begin and ebox-render-burst-end provide the lower-level token form and must be paired with unwind-protect. They do not publish by themselves.

4. Identity, direct updates, and logical candidates

Function	Contract
ebox-region-ids	Return current low-level region ids in document order.
ebox-region-resolve	Resolve one logical :id in a mounted buffer to an opaque surface-scoped handle.
ebox-region-update	Apply supported mutable style or scroll properties through one retained transaction.
ebox-child-range	Build a transparent, addressable child Range descriptor from typed nodes.
ebox-candidate-begin	Capture the exact current mounted generation in a one-shot candidate.
ebox-candidate-replace	Replace one candidate node address.
ebox-candidate-replace-range-ref	Replace one transparent child Range payload.
ebox-candidate-replace-root	Replace the candidate's private root address.
ebox-candidate-replace-host-ref	Replace one framework-owned opaque host reference.
ebox-candidate-patch-host-paint	Record a proven paint-only host patch or return nil when replacement is required.
ebox-host-ref-bounds	Return current margin-free bounds for an opaque host reference.
ebox-host-ref-position	Return its first current position.

Handles and reported positions belong to one live publication generation. Resolve them again after their object is removed. A candidate is sealed by commit and cannot be reused.

5. Selectors

ECSS is the sole selector parser and matcher. Ebox supplies logical tree relations and mounted indexes.

Function	Contract
ebox-selector-parse	Compile a CSS-like selector to the ECSS AST.
ebox-selector-match-node-p	Match one built node against a selector or AST.
ebox-selector-query-all	Query an unmounted built tree in document order.
ebox-selector-query-buffer	Query one mounted runtime.
ebox-selector-update-buffer	Update all editable mounted matches and return a structured report.
ebox-select-all	Alias of ebox-selector-query-buffer.
ebox-update-selector	Alias of ebox-selector-update-buffer.

6. Scrolling

ebox-buffer-mode installs ebox-scroll-map. The map routes line, page, and wheel intent through the innermost semantic scroll owner before ordinary Emacs scrolling.

The public commands are ebox-scroll-down, ebox-scroll-up, ebox-scroll-page-down, ebox-scroll-page-up, ebox-wheel-scroll-down, and ebox-wheel-scroll-up. ebox-scroll-state returns a read-only snapshot for a numeric region id.

7. Measurement, cache, and build tools

Function	Contract
ebox-string-pixel-width	Measure the first-line display width of a string.
ebox-display-signature	Return display inputs used for measurement-cache invalidation.
ebox-clear-cache	Clear Ebox measurement/render caches.
ebox-byte-compile	Compile active Ebox Elisp sources; restart Emacs to load the new bytecode.
ebox-native-status	Report native toolchain, module, ABI, and load status.
ebox-native-build	Build and install the optional native module asynchronously.

The native module is an accelerator, never a correctness requirement. Ebox does not build it during package load.

8. Facade inventory

ebox-public-api contains the stable facade entries. The following grouping names every entry:

• Construction: ebox-build, ebox-text-create, ebox-normal-layout-create, ebox-row-layout-create, ebox-column-layout-create, ebox-flex-layout-create, ebox-grid-layout-create, ebox-box-create, ebox-child-range.
• Render/publication: ebox-render, ebox-render-to-buffer, ebox-display-buffer, ebox-commit, ebox-buffer-update-report, ebox-rerender-buffer-with-context, ebox-viewport-window-width, ebox-call-with-render-burst, ebox-render-burst-begin, ebox-render-burst-end.
• Candidate/identity: ebox-candidate-begin, ebox-candidate-replace, ebox-candidate-replace-range-ref, ebox-candidate-replace-root, ebox-candidate-replace-host-ref, ebox-candidate-patch-host-paint, ebox-region-ids, ebox-region-resolve, ebox-region-update, ebox-host-ref-bounds, ebox-host-ref-position.
• Selectors: ebox-selector-parse, ebox-selector-match-node-p, ebox-selector-query-all, ebox-selector-query-buffer, ebox-selector-update-buffer, ebox-select-all, ebox-update-selector.
• Scroll: ebox-buffer-mode, ebox-scroll-map, ebox-scroll-down, ebox-scroll-up, ebox-scroll-page-down, ebox-scroll-page-up, ebox-wheel-scroll-down, ebox-wheel-scroll-up, ebox-scroll-state.
• Measurement/build: ebox-string-pixel-width, ebox-display-signature, ebox-clear-cache, ebox-byte-compile, ebox-native-status, ebox-native-build.

9. Verification

make load EMACS=/Applications/Emacs.app/Contents/MacOS/Emacs
make compile EMACS=/Applications/Emacs.app/Contents/MacOS/Emacs
make docs-contract-tests EMACS=/Applications/Emacs.app/Contents/MacOS/Emacs
make dsl-tests EMACS=/Applications/Emacs.app/Contents/MacOS/Emacs
make check EMACS=/Applications/Emacs.app/Contents/MacOS/Emacs