etaf-ui/README.md

etaf-ui

etaf-ui is the official ETAF Component catalog. It is a normal optional package above etaf; it does not add a second Control or Widget model. Button, Checkbox, Label, Panel, and DataGrid are all ordinary Components with the same View, props, slots, events, and Data contracts.

Use the exact registered names etaf-panel, etaf-label, etaf-button, and etaf-checkbox in every View. Evaluate this complete example in a lexical-binding .el file, then switch to *etaf-preferences* to use its controls.

;;; -*- lexical-binding: t; -*-
(require 'etaf-ui)

(etaf-define-component demo-preferences ()
  :setup (list (etaf-ref nil) (etaf-ref "Unsaved"))
  :render
  (let* ((state (etaf-state))
         (done (car state))
         (saved (cadr state)))
    (etaf-view
     (etaf-panel :title "Account"
       (slot :name 'header
         (etaf-button :label "Save" :ref 'save-button
                      :on-press (lambda ()
                                  (setf (etaf-value saved) "Saved"))))
       (etaf-label :text (etaf-value saved))
       (etaf-checkbox :checked (etaf-value done) :label "Done"
                      :ref 'done-checkbox
                      :on-change (lambda (next)
                                   (setf (etaf-value done) next)))
       (text (expr (if (etaf-value done) "Complete" "Pending")))))))

(etaf-mount "*etaf-preferences*" (etaf-view (demo-preferences)))

Core does not automatically load .etaf files. The optional Playground reads inert structural source and explicitly loads its registered Elisp companion; that file format does not create shorter Component aliases. Local callbacks need no named Action. Components receive props and slots through the same API as application-defined Components.

Button and Checkbox are controlled Components. etaf-button accepts :label, :on-press, :disabled, :ref, and the small presentation set :class, :color, :bgcolor, :border, :padding, :font-weight, :tab-index, and :aria-label, plus :use for a public Behavior list. An enabled button defaults to role button and tab index 0; a disabled button keeps its label and disabled styling but has no press handler, Behavior, or tab stop. etaf-checkbox accepts :checked, :label, :on-change, :disabled, :ref, and the same presentation props. It exposes role checkbox, a stable :ref, and tab index 0 while enabled. Its :on-change receives the next boolean value; disabled checkboxes have no handler or tab stop.

etaf-number-input is a small controlled input primitive for values edited through Emacs's native minibuffer. It accepts :value, :label, :on-change, :min, :max, :ref, and :disabled; the callback receives the validated integer while the caller remains the owner of the ref.

The catalog uses one semantic Theme vocabulary for color roles. The main tokens are :ui-fg, :ui-bg, :ui-border, :ui-muted-fg, :ui-disabled-*, :ui-button-primary-*, :ui-button-secondary-*, :ui-button-ghost-*, :ui-checkbox-*, :ui-table-*, :ui-data-grid-error-fg, :ui-pagination-muted-fg, and :ui-panel-*. Applications provide these through ETAF's etaf-theme-provide; legacy :ui-button-color-style aliases remain accepted for compatibility. etaf-ui does not depend on TP or on a renderer-specific palette registry. If an application wants TP's light/dark palette data, the optional etaf-theme-tp adapter converts it into the same ETAF Theme plist before the UI catalog sees it.

Component :styles declarations own default appearance. A non-nil presentation prop supplied by the caller wins; an omitted or nil prop leaves the inherited Theme/default style available. Button has the deliberately small primary, secondary, and ghost visual vocabulary; it is a visual variant set, not a second widget taxonomy.

Enabled buttons and checkboxes expose the same interaction affordances: a hand pointer, native mouse-face hover feedback, a readable help-echo, a numeric tab stop, and a semantic role. Hover ends when the pointer leaves; activation does not create retained visual state. Disabled controls retain their text and disabled appearance but expose no callback, pointer activation, or tab stop. The Runtime owns composition of an explicit :on-* callback with a Behavior callback; the UI package only declares the control and its visual state.

The parent owns spacing: use (row :item-gap 1 ...) or (column :item-gap 1 ...); flex and grid use :gap. In particular, migrate row :gap to row :item-gap. Keep an explicit gap between adjacent controls so each has a separate hover and hit range.

Root event forwarding appends the business action, inner-to-outer wrapper callbacks, then Behaviors in declaration order. For Checkbox, adding :on-press does not replace its :on-change conversion. Errors stop the chain; each declaration runs once. Wrapper :use lists concatenate and duplicate Behavior names are rejected before installation.

Disabled inputs combine with OR; outer nil cannot enable an internally disabled control. Disabled dispatch and focus signal etaf-event-error; disabled cell controls block pointer activation from falling through to their parent row. Disabled input Behaviors are not installed. A conflicting fallthrough :role or owned aria state, such as :aria-checked, is an input error; accessible :aria-label and :aria-description remain caller-overridable. See the interaction and migration rules for the complete contract.

etaf-label accepts :text, :class, :color, :bgcolor, :font-weight, :width, :border, :padding, and :ref. etaf-panel accepts :title, the same surface presentation props, and projects the named header slot plus the default slot.

The public Component business props are derived from the definitions and kept separate from forwarded Host attributes:

Component	Business props
etaf-label	:text, :variant
etaf-button	:label, :on-press, :disabled, :ref, :class, :color, :bgcolor, :border, :padding, :font-weight, :tab-index, :aria-label, :use, :variant
etaf-checkbox	:checked, :label, :on-change, :disabled
etaf-panel	:title, :variant
etaf-number-input	:value, :label, :on-change, :disabled, :min, :max
etaf-table	:columns, :rows, :row-key, :row-ref, :on-row-press, :row-selected-p
etaf-data-grid	:controller, :columns, :row-key, :on-row-press, :row-ref, :row-selected-p, :loading-label, :error-label, :empty-label
etaf-pagination	:controller, :previous-ref, :next-ref, :previous-label, :next-label, :class, :color, :bgcolor, :border, :padding, :aria-label

Every public catalog Component mounts exactly one Host root. All valid Host attributes that are not consumed as business props—such as :ref, :class, and :aria-label—are forwarded to that root. This forwarding rule does not make those attributes business props of every Component.

DataGrid accepts column descriptors, a function-valued :row-key, and the optional :loading-label, :error-label, :empty-label, or function-valued :row-selected-p. When :on-row-press is supplied, every row is an interactive button with role button and tab index 0; the callback receives the row. Without :on-row-press, rows have no callback or tab stop.

Interactive etaf-table rows may also omit :row-ref; the framework supplies stable references scoped to the retained Table instance. Supply refs only for external focus, tests, or integration addresses; do not derive global symbols from row labels. Row keys identify data; refs identify interactive Hosts.

:row-ref is optional for DataGrid. When it is omitted on an interactive grid, DataGrid derives a stable internal Host reference from the row identity owned by the controller. Fallback refs are uninterned and scoped to each retained DataGrid instance, so separate grids may share row identities without colliding. When :row-ref is supplied, the callback owns that identity and must return a non-nil stable Host reference for every row. :row-key remains a required non-nil stable scalar identity for retained rows. DataGrid retains one action closure per row key, so selection or Data Range updates do not recreate handlers for unchanged rows. An integer column :width is readable character capacity, not a raw pixel value. DataGrid passes Ebox's native character unit through and reserves one native character between non-final tracks. Use :width '(fr 1) to let a column fill the remaining width; multiple fractional columns share that space by their positive weights. For example, (:key :title :width (fr 1)) next to (:key :actions :width 22 :cell render-actions) lets the title adapt while reserving room for the action controls. Headers and rows use the same tracks and gap. Fractional cells clip to their allocation without widening neighboring columns. Fixed tracks still reserve their declared space, so the containing layout must provide enough width for those controls and gaps.

Changing a custom cell's column width between fixed and fractional values does not replace its Component state. All-fixed text-only tables retain their compact text rendering path.

Custom cells and column migration

Table and DataGrid share the column contract. Every column needs a unique, non-nil :key (symbol, integer, or string), including presentation-only columns. The default cell reads that field as text. A :cell function receives one row and returns nil, a string, a typed Host or Component View, or a proper sequence of those values. Table owns cell width and clips overflow; text-only tables keep their existing compact representation.

The example repeats the :name field with two distinct column keys and puts an ordinary Button in a third column. Select the row or activate Open independently:

;;; -*- lexical-binding: t; -*-
(require 'etaf-ui)

(etaf-mount
 "*etaf-cell-demo*"
 (etaf-view
  (etaf-table
   :rows '((:id 1 :name "Ada"))
   :row-key (lambda (row) (plist-get row :id))
   :on-row-press (lambda (row) (message "Select %s" (plist-get row :name)))
   :columns
   (list
    '(:key :name :label "Name" :width 12)
    (list :key :name-upper :label "Uppercase" :width 12
          :cell (lambda (row) (upcase (plist-get row :name))))
    (list :key :open :label "Action" :width 10
          :cell
          (lambda (row)
            (etaf-view
             (etaf-button
              :label "Open"
              :on-press (lambda ()
                          (message "Open %s" (plist-get row :name)))))))))))

To migrate duplicate field columns, keep one :key :name, give the other a unique key such as :name-upper, and use :cell to read the original :name field. Missing or duplicate column keys are errors. Row and column keys retain cell identity across reordering; changing a key replaces that cell instance.

Cell functions use their row argument and normal lexical captures. Their Context is the consuming Table/Grid location; they do not recover the author's props, etaf-state, or private styles. Return an ordinary Component when a cell needs its own state, styles, or lifecycle, and create persistent refs and watches in that Component's :setup. Capture an author's stable ref before building a callback when sharing it is intentional. Do not create persistent state on each cell-function call.

etaf-pagination is a controlled Data Component. It accepts a Data controller plus stable :previous-ref and :next-ref values, renders padded secondary Buttons (‹ Previous / Next ›) around a centered Page N / M and item-count summary, and disables the boundary action while a page is loading or already at the first/last page. It owns no page state and uses the same Button interaction contract and Theme tokens. Narrow allocations wrap the complete controls and summary. Optional :previous-label and :next-label replace the complete captions, for example "‹ 上一页" and "下一页 ›"; the stable English accessibility labels remain unchanged.

Keyboard focus uses ETAF's public runtime ports: call (etaf-focus-next runtime) to move through visible Hosts with a numeric non-negative :tab-index, and dispatch through (etaf-dispatch-event runtime ref 'press) when an action must be invoked by code. Disabled controls and non-interactive DataGrid rows are omitted from that tab order.

Run make check EMACS=/Applications/Emacs.app/Contents/MacOS/Emacs from this directory.