filmopen_text_ui

A snapshot

This specification is a copy of docs/software/packages/filmopen_text_ui.md in the application’s repository, taken at commit 0b4fe88 of 11 November 2026. It is imported byte for byte and is not edited here; a change is made there, and arrives with the next snapshot.

Generated by scripts/package_digest.py; regenerate, never edit.

The reusable prose editor and controller for fields in forms and scripts keeps shown text separate from canonical source, projects mentions as atomic placeholders and offers a literal mode. The controller owns an editable-text target adapter exposed as controller.target, so insertion uses shown-text offsets while saved text comes from the canonical source.

Flutter. 6 files, 1,975 lines under lib/; 255 tests in 34 files. Barrel: lib/filmopen_text_ui.dart.

Depends on

• filmopen_format — uses AssetMedia, BytesMedia, FileMedia, MediaLocation, ReferenceCodec, ReferenceKind, ReferenceTarget, ReferenceToken
• filmopen_ui — uses Breakpoints, EditableTextSelection, EditableTextTarget, ProvisionalTextEdit, TextEditGeneration, TextEditOutcome, imageProviderFor
• filmopen_l10n — uses nothing by name the digest could see

Used by

filmopen_forms, filmopen_prompt_ui, filmopen_render_ui

Public API

What the barrel exports, file by file. A name is class, enum, mixin, extension, typedef, a top-level function, getter, setter or variable; under a class, its public constructors, fields, getters, setters and methods.

lib/src/mention_candidates.dart

• class MentionCandidate — A reference offered by the chooser and recognised by the same candidate source.
  • const MentionCandidate({required this.target, required this.name, this.picture}) — Describes a canonical target, its current display name and optional picture.
  • final ReferenceTarget target — The stable kind and id saved in canonical source.
  • final String name — The current human-readable name, independent of the saved id.
  • final MediaLocation? picture — The resolved picture drawn through the shared media image provider.
• function List<(ReferenceTarget, String, Object?)> shownMentions(Iterable<MentionCandidate> candidates) — [candidates] as a box shows them: each target, name and picture, for comparing two lists.
• class MentionCandidates — One injected source of chooser candidates and reference membership.
  • const MentionCandidates() — Creates a candidate source without project-state dependencies.
  • Iterable<MentionCandidate> get candidates — The current candidates across characters, locations, epochs and props.
  • MentionCandidate? find(ReferenceTarget target) — Finds a target this source recognises, or null when it is unresolved.
  • bool isKnown(ReferenceTarget target) — A token is known exactly when this source recognises it ([find]).
  • String get fieldKind — What kind of field the chooser’s reports name: prose, or prompt for a prompt’s box.
  • String? emptyHint(String query) — The one disabled line the chooser shows where [query] matches no candidate, or null — the default — to stay shut.
  • void report(String event, Map<String, Object> data) — Where the editor reports the chooser’s actions (prose.mention.*) and its clipboard’s (prose.clipboard), silent by default.

lib/src/mention_query.dart

• class MentionQuery — The chooser’s current query and canonical source bounds.
  • final int start — The source offset of the opening at sign.
  • final int end — The source caret offset at the end of the query.
  • final String text — The query without its at sign, retaining the typed case.
  • static MentionQuery? find(ProseController controller) — Finds letters, digits, hyphens and dots between segments before the mapped caret.
  • List<MentionCandidate> matching(MentionCandidates? source) — Orders matching names by kind, folded name and stable id, without a kind filter.
  • static List<MentionCandidate> ordered(MentionCandidates? source, [String query = '']) — Orders first-per-target candidates or a folded name substring in the kind groups.
• function String mentionCandidateId(ReferenceTarget target) — The canonical kind-qualified id used by chooser semantics on one field.

lib/src/prose_brackets.dart

• class ProseBracketEdit — A pure bracket proposal with retained positions for recognised shown-text actions.
  • ProseBracketEdit(this.value, List<int?> originalOffsets) — Retains an old UTF-16 position when known, or null for inserted syntax or unknown provenance.
  • final TextEditingValue value — The complete proposed shown value, without controller publication.
  • final List<int?> originalOffsets — The surviving original positions for recognised actions, preserving selected-chip deletion identity.
• class ProseBracketFormatter — Applies paired-bracket typing and deletion to shown text as one field edit.
  • const ProseBracketFormatter() — Creates the rich field’s bracket formatter without changing loaded source.
  • static ProseBracketEdit prepare(TextEditingValue oldValue, TextEditingValue newValue) — Describes a typed bracket or paired deletion without losing surviving chip identity.
  • static List<TextRange> boldRanges(String shown) — Returns merged editable interiors of balanced unescaped pairs in shown UTF-16 offsets.

lib/src/prose_controller.dart

• class ProseMention — One atomic mention with source and shown UTF-16 bounds.
  • final ReferenceToken token — The codec’s token, retaining its original source bounds and spelling.
  • final int shownStart — The offset of the mention’s single shown placeholder.
  • final String sourceText — The exact saved bytes, including a known shorthand until its own action.
• typedef typedef ProseMentionBuilder — Builds an atomic chip for a mention in the owning editor.
• class ProseController — Edits shown text while keeping canonical source and its UTF-16 offset map.
  • ProseController({String source = '', this.candidates, bool literal = false, bool readOnly = false, this.acceptsEdit}) — Loads source, strips foreign rich placeholders and collapses eligible mentions atomically.
  • final MentionCandidates? candidates — The same injected candidates determine both membership and chooser entries.
  • bool Function(String source, TextEditingValue shown)? acceptsEdit — A pure acceptance check for proposed source and shown edits, leaving loads untouched.
  • late final EditableTextTarget target — The stable adapter used by dictation and other captured text insertions.
  • ProseMentionBuilder? mentionBuilder — The owning editor’s chip builder; a plain placeholder is used without one.
  • String get source — The canonical source, including a provisional span until commit or cancellation.
  • String get committedSource — The committed canonical source, excluding any captured provisional span.
  • bool get hasProvisional — Whether the shown source includes an uncommitted captured span.
  • bool get literal — Whether this field treats every character literally.
  • int get sourceEpoch — The reset identity used by an editor to discard the previous source’s undo stack.
  • int get historyRecordCount — The number of retained shown-text records, exposed for bounded-history verification.
  • List<ProseMention> get mentions — The currently collapsed mentions in shown order.
  • bool get canUndo — Whether a previous committed source state is available and editing is allowed.
  • bool get canRedo — Whether a later committed source state is available and editing is allowed.
  • bool undo() — Restores one complete source transaction if the current field accepts it.
  • bool redo() — Reapplies one complete source transaction if the current field accepts it.
  • void endTyping() — Ends a typing burst and the chooser’s one-keystroke punctuation opportunity.
  • void endChooserPunctuation() — Consumes chooser punctuation before a deletion without ending its typing burst.
  • ProseMention? currentMention(ProseMention mention) — Rebinds a rendered mention only within the same owner, source epoch and exact token.
  • bool get readOnly — Whether captured edits and chip actions are refused.
  • set readOnly(bool next) — A read-only transition invalidates captures and removes provisional text.
  • int sourceOffset(int shownOffset) — Maps a shown UTF-16 boundary to canonical source, including both chip edges.
  • int shownOffset(int sourceOffset) — Maps a canonical source boundary to shown text, with chip interiors at their end.
  • String get selectedSource — The selected canonical source used by the editor’s own clipboard.
  • String get clipboardText — Copies fully selected references canonically without changing their saved source spelling.
  • void refreshCandidates() — Refreshes membership and displayed names without changing saved source or capture ranges.
  • void setSource(String next) — Switches source, invalidating captures and history while stripping only foreign rich placeholders.
  • bool replaceShown(TextSelection range, String text, {bool collapseMentions = false}) — Replaces shown bounds with source text as one ordinary external edit, returning acceptance.
  • bool chooseMention(TextSelection range, ReferenceTarget target) — Inserts one chosen target only when its encoding round-trips to that entire target.
  • bool replaceMention(ProseMention mention, ReferenceTarget replacement) — Replaces the whole current chip with a representable target as one source transaction.
  • bool removeMention(ProseMention mention) — Removes one chip’s entire source token as a shown-text edit, returning acceptance.
  • bool isRepresentable(ReferenceTarget target) — Whether [target]’s canonical encoding reads back as that whole target; a chooser refuses one that does not.
  • void applyFieldValue(TextEditingValue next, { required TextEditingValue Function(TextEditingValue previous, TextEditingValue proposed) formatter, b… — Formats a field proposal after projection and before its source, map or history is published.
  • TextSpan shownSpan(BuildContext context, TextStyle? style, ProseMentionBuilder builder) — The shown text as [buildTextSpan] draws it, with [builder] drawing the chips: for a box that holds no editor (§9.3).

lib/src/prose_editor.dart

• class ProseEditor — A reusable field with atomic mentions, a field-anchored chooser and source clipboard.
  • const ProseEditor({super.key, required this.controller, required this.identifier, this.focusNode, this.decoration = const InputDecoration(), this.s… — Uses the consumer’s unique field identifier and existing field constraints.
  • final ProseController controller — The shown-text controller whose source is passed to changes and clipboard operations.
  • final String identifier — The unique consumer-owned identifier from which every mention control is derived.
  • final FocusNode? focusNode — The consumer’s focus node, or a field-owned node when omitted.
  • final Object groupId — The consumer’s tap-region group, shared by its field and mention chooser.
  • final bool canRequestFocus — Whether the field can receive focus in the consumer’s current mode.
  • final bool wrapSemantics — Whether this editor supplies the field identifier instead of its consumer’s outer wrapper.
  • final Widget? Function(BuildContext context, EditableTextTarget target, bool readOnly)? suffix — Builds the box’s suffix after the decoration’s own, on a read-only box too: the builder decides what the box gets — a microphone only where it can be typed into, an assistant’s icon either way — and null draws none.
  • final InputDecoration decoration — The consumer’s existing label, hint and suffix decoration.
  • final TextStyle? style — The consumer’s existing text style.
  • final int? minLines — The preserved minimum line count.
  • final int? maxLines — The preserved maximum line count, with null allowing multiline growth.
  • final int? maxLength — The field’s existing shown-text length limit, counting one character per chip.
  • final List<TextInputFormatter>? inputFormatters — The consumer’s existing shown-text input formatters.
  • final TextInputType? keyboardType — The consumer’s existing keyboard type.
  • final ValueChanged<String>? onChanged — Reports changed source rather than placeholders, including a source-only replacement.
  • final bool autofocus — Whether the field takes the focus when it is first drawn, as a dialog’s first box does.
  • final ValueChanged<String>? onSubmitted — Reports the canonical source when the field is submitted, Enter or the keyboard’s action.
  • final ValueChanged<bool>? onChooserOpen — Reports whether one of the field’s choosers — a typed mention’s or a chip’s replacement — is open, as it opens and closes, for a consumer whose own keys must give way to it.
  • final UndoHistoryController? undoController — An optional observer/controller for the field’s Undo and Redo.
• function Widget proseChip(BuildContext context, ProseController controller, ProseMention mention, int ordinal, bool bold, {required String identifier, VoidC… — A mention’s chip, the editor’s and a box’s alike (§9.8): its name after @ and its picture.