Alpine.js Inline Editor

huxInlineEditor manages the behavior switch between static display and inline editing. It keeps committed input state, supports commit/revert keyboard shortcuts, and traps focus within the active editor controls.

Runtime Constraints

• No special runtime requirements beyond Alpine.js.
• For robust keyboard behavior, keep all editable controls inside the focus-trap container ref.
• Prefer x-show + x-cloak + x-transition for read/edit toggles because it keeps DOM elements connected (improving focus restoration reliability) and provides smoother visual transitions.
• x-if is supported, but when toggling with DOM removal you should configure returnFocusTemplateRef for consistent focus return.

API

huxInlineEditor(config)

Returns an Alpine data object with:

• isEditing: boolean
• inputValue: string
• draftValue: string
• editorId: string | null
• hasChanges: boolean
• enterEditMode(): void
• commitChanges(): void
• revertChanges(): void
• registerInput(targetElement: HTMLInputElement | HTMLTextAreaElement): void
• handleInputFocus(event: FocusEvent): void
• handleInputKeydown(event: KeyboardEvent): void
• trapFocus(event: KeyboardEvent): void

Internal helper methods are private implementation details and are not part of the supported API contract.

Options

• inputValue: string (default: '') Initial committed input value and initial draft value.
• editorId: string (optional) Adds scoped events: hux-inline-editor:{editorId}:commit and hux-inline-editor:{editorId}:revert.
• inputTemplateRef: string (default: 'inlineEditorInput') x-ref used for auto-focus and select-all behavior in edit mode.
• focusTrapTemplateRef: string (default: 'inlineEditor') x-ref used as the keyboard focus-trap root while editing.
• returnFocusTemplateRef: string (optional) Optional x-ref used as the primary focus return target after commit/revert. If the previously focused element is disconnected, focus attempts this ref first. If unavailable, focus falls back to the first visible focusable element in DOM order within the component.

Quick Start

<div x-data="huxInlineEditor({ inputValue: 'Ada Lovelace' })">
  <div x-show="!isEditing" x-cloak x-transition.opacity>
    <span x-text="inputValue"></span>
    <button type="button" x-on:click="enterEditMode()">Edit</button>
  </div>

  <div
    x-show="isEditing"
    x-cloak
    x-transition.opacity
    x-ref="inlineEditor"
    x-on:keydown="trapFocus($event)"
  >
    <label>
      <span class="sr-only">Profile name</span>
      <input
        x-ref="inlineEditorInput"
        x-model="draftValue"
        type="text"
        x-init="registerInput($el)"
        aria-describedby="profile-name-inline-editor-help"
        x-on:focus="handleInputFocus($event)"
        x-on:keydown="handleInputKeydown($event)"
      />
    </label>
    <button type="button" x-on:click="commitChanges()">Save</button>
    <button type="button" x-on:click="revertChanges()">Cancel</button>
  </div>

  <p id="profile-name-inline-editor-help">
    Press Enter to save, Escape to cancel, and Tab to cycle within editor controls.
  </p>
</div>

Common Usage Patterns

Listen for commit events

<div
  x-data="huxInlineEditor({ editorId: 'profile-name', inputValue: 'Ada Lovelace' })"
  x-on:hux-inline-editor:profile-name:commit.window="console.log($event.detail.inputValue)"
>
  ...
</div>

Configure an explicit return-focus target

<div x-data="huxInlineEditor({ inputValue: 'Ada Lovelace', returnFocusTemplateRef: 'editButton' })">
  <button type="button" x-ref="editButton" x-on:click="enterEditMode()">Edit</button>
  ...
</div>

Commit and revert with keyboard

<input
  x-ref="inlineEditorInput"
  x-model="draftValue"
  type="text"
  x-init="registerInput($el)"
  aria-describedby="profile-name-inline-editor-help"
  x-on:focus="handleInputFocus($event)"
  x-on:keydown="handleInputKeydown($event)"
/>

Behavior Contract

• enterEditMode() copies inputValue into draftValue, sets isEditing = true, focuses the configured input ref, and selects all text.
• registerInput() stores the active input/textarea element, focuses it, and selects all text.
• handleInputFocus() selects all text in the focused input/textarea.
• handleInputKeydown() commits on Enter and reverts on Escape.
• trapFocus() cycles Tab and Shift+Tab inside the active focus-trap root while editing.
• commitChanges() sets inputValue = draftValue, exits edit mode, restores focus (previous active element, configured return-focus ref, or first visible focusable element in DOM order), and dispatches commit event(s).
• revertChanges() resets draftValue = inputValue, exits edit mode, restores focus (previous active element, configured return-focus ref, or first visible focusable element in DOM order), and dispatches revert event(s).

Error Handling

• If no input or textarea target can be resolved after focus retries, the component logs: [huxInlineEditor] Unable to resolve input or textarea target for inlineEditorInput. by default. If you override inputTemplateRef, the logged value uses that configured ref name.
• Missing optional listeners do not affect commit/revert behavior.

Accessibility Notes

• Use a real button (type="button") to enter edit mode.
• Keep editable controls within the focus-trap container to preserve keyboard containment while active.
• Keep visible labels for the editable field, or use an explicit <label> for screen readers.
• If you surface status updates, use an aria-live="polite" region.

Notes

• Default event names:
  • hux-inline-editor:commit
  • hux-inline-editor:revert