"""

@relation(SDOC-SRS-54, scope=file)

"""

from dataclasses import dataclass

from datetime import datetime

from enum import Enum

from typing import (

    Any,

    Dict,

    Generator,

    Iterator,

    List,

    Optional,

    Sequence,

    Set,

    Tuple,

    Union,

)

from jinja2 import Template

from markupsafe import Markup, escape

from strictdoc import __version__

from strictdoc.backend.sdoc.free_text_reader import SDFreeTextReader

from strictdoc.backend.sdoc.models.anchor import Anchor

from strictdoc.backend.sdoc.models.document import SDocDocument

from strictdoc.backend.sdoc.models.document_view import ViewElement

from strictdoc.backend.sdoc.models.grammar_element import (

    GrammarElement,

    GrammarElementFieldMultipleChoice,

    GrammarElementFieldSingleChoice,

    GrammarElementFieldTag,

)

from strictdoc.backend.sdoc.models.inline_link import InlineLink

from strictdoc.backend.sdoc.models.model import (

    RequirementFieldName,

    SDocDocumentIF,

    SDocElementIF,

    SDocNodeIF,

)

from strictdoc.backend.sdoc.models.node import SDocNode, SDocNodeField

from strictdoc.core.document_iterator import DocumentIterationContext

from strictdoc.core.document_tree import DocumentTree

from strictdoc.core.document_tree_iterator import DocumentTreeIterator

from strictdoc.core.file_system.file_tree import File, FileOrFolderEntry, Folder

from strictdoc.core.project_config import ProjectConfig

from strictdoc.core.traceability_index import TraceabilityIndex

from strictdoc.export.html.document_type import DocumentType

from strictdoc.export.html.generators.view_objects.document_chunks import (

    CHUNK_SIZE,

    DocumentChunk,

    slice_chunks,

)

from strictdoc.export.html.generators.view_objects.helpers import (

    screen_should_display_file,

    screen_should_display_folder,

)

from strictdoc.export.html.html_templates import HTMLTemplates, JinjaEnvironment

from strictdoc.export.html.renderers.html_fragment_writer import (

    HTMLFragmentWriter,

)

from strictdoc.export.html.renderers.link_renderer import LinkRenderer

from strictdoc.export.html.renderers.markup_renderer import MarkupRenderer

from strictdoc.helpers.cast import assert_cast

from strictdoc.helpers.file_system import file_open_read_utf8

from strictdoc.helpers.git_client import GitClient

from strictdoc.helpers.string import interpolate_at_pattern_lazy

from strictdoc.server.helpers.turbo import render_turbo_stream

class TableCellEditMode(str, Enum):

    AUTOCOMPLETE = "autocomplete"

    SINGLELINE = "singleline"

    MULTILINE = "multiline"

    READONLY = "readonly"

@dataclass

class DocumentScreenViewObject:

    def __init__(

        self,

        *,

        document_type: DocumentType,

        document: SDocDocument,

        traceability_index: TraceabilityIndex,

        project_config: ProjectConfig,

        link_renderer: LinkRenderer,

        markup_renderer: MarkupRenderer,

        jinja_environment: JinjaEnvironment,

        git_client: GitClient,

    ):

        self.document_type: DocumentType = document_type

        self.link_document_type: DocumentType = DocumentType.DOCUMENT

        self.document: SDocDocument = document

        self.traceability_index: TraceabilityIndex = traceability_index

        self.project_config: ProjectConfig = project_config

        self.link_renderer: LinkRenderer = link_renderer

        self.markup_renderer: MarkupRenderer = markup_renderer

        self.jinja_environment: JinjaEnvironment = jinja_environment

        self.git_client: GitClient = git_client

        self.document_iterator = self.traceability_index.get_document_iterator(

            self.document

        )

        self.document_tree_iterator: DocumentTreeIterator = (

            DocumentTreeIterator(

                assert_cast(traceability_index.document_tree, DocumentTree)

            )

        )

        self.current_view: ViewElement = document.view.get_current_view(

            project_config.view

        )

        self.is_running_on_server: bool = project_config.is_running_on_server

        self.strictdoc_version = __version__

        self._chunked_rendering: Optional[bool] = None

        self._chunk_index_by_mid: Optional[Dict[str, int]] = None

        self.custom_html2pdf_template: Optional[Template] = None

        if project_config.html2pdf_template is not None:

            with file_open_read_utf8(project_config.html2pdf_template) as f_:

                self.custom_html2pdf_template = Template(f_.read())

    def has_included_document(self) -> bool:

        return len(self.document.included_documents) > 0

    def render_screen(self) -> Markup:

        if self.document_type.is_document():

            if self.document.config.layout == "Website":

                return self.jinja_environment.render_template_as_markup(

                    "website/document/index.jinja", view_object=self

                )

            return self.jinja_environment.render_template_as_markup(

                "screens/document/document/index.jinja", view_object=self

            )

        elif self.document_type.is_table():

            return self.jinja_environment.render_template_as_markup(

                "screens/document/table/index.jinja", view_object=self

            )

        elif self.document_type.is_trace():

            return self.jinja_environment.render_template_as_markup(

                "features/trace/index.jinja", view_object=self

            )

        elif self.document_type.is_deeptrace():

            return self.jinja_environment.render_template_as_markup(

                "features/deep_trace/index.jinja",

                view_object=self,

            )

        elif self.document_type.is_pdf():

            return self.jinja_environment.render_template_as_markup(

                "features/html2pdf/index.jinja", view_object=self

            )

        else:

            raise NotImplementedError(self.document_type)  # pragma: no cover

    def render_updated_screen(self) -> Markup:

        output = self.jinja_environment.render_template_as_markup(

            "actions/"

            "document/"

            "create_requirement/"

            "stream_created_requirement.jinja.html",

            view_object=self,

        )

        output += self.jinja_environment.render_template_as_markup(

            "actions/document/_shared/stream_updated_toc.jinja.html",

            view_object=self,

        )

        output += self.jinja_environment.render_template_as_markup(

            "actions/document/_shared/stream_updated_viewtype_menu.jinja.html",

            view_object=self,

        )

        return output

    def render_updated_nodes_and_toc(

        self,

        nodes: Sequence[Union[SDocDocument, SDocNode]],

        node_updated: bool = False,

    ) -> str:

        output: str = ""

        if node_updated:

            # The TOC is rendered before the individual nodes intentionally:

            # toc.jinja calls table_of_contents() -> all_content(), which

            # iterates every node and writes the correct title_number_string

            # into each node's context as a side effect. The node templates

            # rendered below then read those values and display the right

            # section numbers. Reversing this order would cause nodes whose

            # level changed (e.g. a title was added or removed) to render

            # with stale numbers.

            #

            # FIXME: This is a bit hacky. A cleaner solution would be to

            # separate the calculation of title_number_string from the rendering

            # of the TOC, so that the side effect is explicit and not tied to

            # the TOC template.

            toc_content = self.jinja_environment.render_template_as_markup(

                "screens/document/_shared/toc.jinja", view_object=self

            )

            output += render_turbo_stream(

                content=toc_content,

                action="update",

                target="frame-toc",

            )

            viewtype_menu_content = (

                self.jinja_environment.render_template_as_markup(

                    "screens/document/_shared/viewtype_menu.jinja",

                    view_object=self,

                )

            )

            output += render_turbo_stream(

                content=viewtype_menu_content,

                action="update",

                target="frame-viewtype-menu",

            )

        for node_ in nodes:

            template_folder: str

            if isinstance(node_, SDocDocument):

                template_folder = "section"

            elif isinstance(node_, SDocNode):

                if node_.is_text_node():

                    template_folder = "text_node"

                else:

                    template_folder = "node_content"

            else:

                raise NotImplementedError

            content = self.jinja_environment.render_template_as_markup(

                f"components/{template_folder}/index_extends_node.jinja",

                view_object=self,

                node=node_,

            )

            output += render_turbo_stream(

                content=content,

                action="replace",

                target=f"article-{node_.reserved_mid}",

            )

        return output

    def render_update_document_content_with_moved_node(

        self, moved_node: Any

    ) -> Markup:

        content = self.jinja_environment.render_template_as_markup(

            "screens/document/document/frame_document_content.jinja.html",

            view_object=self,

        )

        output = render_turbo_stream(

            content=content,

            action="replace",

            target="frame_document_content",

        )

        toc_content = self.jinja_environment.render_template_as_markup(

            "actions/document/_shared/stream_updated_toc.jinja.html",

            view_object=self,

            last_moved_node_id=moved_node.reserved_mid,

        )

        output += render_turbo_stream(

            toc_content,

            action="update",

            target="frame-toc",

        )

        output += self.jinja_environment.render_template_as_markup(

            "actions/document/_shared/stream_updated_viewtype_menu.jinja.html",

            view_object=self,

        )

        return output

    def render_document_version(

        self, included_document: Optional[SDocDocument] = None

    ) -> Optional[str]:

        # 'document' is the main view document or an included document

        # (e.g., a bundle PDF member); defaults to the main view document.

        document_ = (

            included_document

            if included_document is not None

            else self.document

        )

        if document_.config.version is None:

            return None

        def resolver(variable_name: str) -> str:

            if variable_name == "GIT_VERSION":

                return self.git_client.get_commit_hash()

            elif variable_name == "GIT_BRANCH":

                return self.git_client.get_branch()

            return variable_name

        return interpolate_at_pattern_lazy(document_.config.version, resolver)

    def render_document_date(

        self, included_document: Optional[SDocDocument] = None

    ) -> Optional[str]:

        # 'document' is the main view document or an included document

        # (e.g., a bundle PDF member); defaults to the main view document.

        document_ = (

            included_document

            if included_document is not None

            else self.document

        )

        if document_.config.date is None:

            return None

        def resolver(variable_name: str) -> str:

            if variable_name == "GIT_COMMIT_DATE":

                return self.git_client.get_commit_date()

            elif variable_name == "GIT_COMMIT_DATETIME":

                return self.git_client.get_commit_datetime()

            return variable_name

        return interpolate_at_pattern_lazy(document_.config.date, resolver)

    def render_metadata_value(self, metadata_value: str) -> Markup:

        """

        FIXME: Remove duplication of Git-resolvers in this class.

        """

        def resolver(variable_name: str) -> str:

            if variable_name == "GIT_VERSION":

                return self.git_client.get_commit_hash()

            elif variable_name == "GIT_BRANCH":

                return self.git_client.get_branch()

            elif variable_name == "GIT_COMMIT_DATE":

                return self.git_client.get_commit_date()

            elif variable_name == "GIT_COMMIT_DATETIME":

                return self.git_client.get_commit_datetime()

            return variable_name

        free_text_container = SDFreeTextReader.read(metadata_value)

        output_parts: List[str] = []

        for part in free_text_container.parts:

            if isinstance(part, str):

                interpolated = interpolate_at_pattern_lazy(part, resolver)

                output_parts.append(str(escape(interpolated)))

            elif isinstance(part, InlineLink):

                linkable_node = (

                    self.traceability_index.get_linkable_node_by_uid_weak(

                        part.link

                    )

                )

                if linkable_node is None:

                    # Dangling or not-yet-complete while the user is still

                    # typing: degrade gracefully instead of crashing this

                    # ad hoc, possibly unsaved render.

                    output_parts.append(str(escape(f"[LINK: {part.link}]")))

                else:

                    href = self.link_renderer.render_node_link(

                        linkable_node, self.document, self.document_type

                    )

                    output_parts.append(

                        HTMLFragmentWriter.write_anchor_link(

                            linkable_node.get_display_title(), href

                        )

                    )

            else:

                # An Anchor can only be produced here by SDFreeTextReader

                # parsing a raw, not-yet-saved value in isolation (where

                # "[ANCHOR: ...]" happens to sit at the start of the

                # string). Persisted METADATA can never contain a real

                # Anchor: the main grammar embeds the value right after

                # "KEY: ", never at a line start, so it always parses as

                # plain text there. Render defensively as literal text.

                assert isinstance(part, Anchor)

                output_parts.append(str(escape(f"[ANCHOR: {part.value}]")))

        return Markup("".join(output_parts))

    def is_empty_tree(self) -> bool:

        return self.document_tree_iterator.is_empty_tree()

    def is_deeptrace(self) -> bool:

        return self.document_type.is_deeptrace()

    def has_any_nodes(self) -> bool:

        return self.document.has_any_nodes()

    def iterator_files_first(self) -> Iterator[FileOrFolderEntry]:

        yield from self.document_tree_iterator.iterator_files_first()

    def render_url(self, url: str) -> Markup:

        return Markup(self.link_renderer.render_url(url))

    def render_node_link(

        self, node: Union[SDocDocument, SDocNode, Anchor]

    ) -> str:

        assert isinstance(node, (SDocDocument, SDocNode, Anchor)), node

        return self.link_renderer.render_node_link(

            node, self.document, self.document_type

        )

    def render_document_link(

        self,

        document: SDocDocument,

        context_document: SDocDocument,

        document_type_string: str,

    ) -> str:

        assert document is not None, document

        return self.link_renderer.render_node_link(

            document, context_document, DocumentType(document_type_string)

        )

    def render_current_view_document_link(self, document: SDocDocument) -> str:

        assert isinstance(document, SDocDocument), document

        assert document.meta is not None

        assert self.document.meta is not None

        return document.meta.get_html_link(

            self.document_type,

            self.document.meta.level,

        )

    def render_static_url(self, url: str) -> Markup:

        return Markup(self.link_renderer.render_static_url(url))

    def render_local_anchor(

        self, node: Union[Anchor, SDocNode, SDocDocument]

    ) -> str:

        return self.link_renderer.render_local_anchor(node)

    def render_node_statement(self, node: SDocNode) -> Markup:

        return self.markup_renderer.render_node_statement(

            self.document_type, node

        )

    def render_truncated_node_statement(self, node: SDocNode) -> Markup:

        return self.markup_renderer.render_truncated_node_statement(

            self.document_type, node

        )

    def render_node_rationale(self, node: SDocNode) -> Markup:

        return self.markup_renderer.render_node_rationale(

            self.document_type, node

        )

    def render_node_field(self, node_field: SDocNodeField) -> Markup:

        assert isinstance(node_field, SDocNodeField), node_field

        return self.markup_renderer.render_node_field(

            self.document_type, node_field

        )

    def render_issues(

        self,

        node: Union[SDocNodeIF, SDocDocumentIF],

        field: Optional[str] = None,

    ) -> str:

        issues = self.traceability_index.validation_index.get_issues(

            node, field=field

        )

        if issues is None:

            return ""

        issues_html = ""

        for issue_ in issues:

            issue_html = self.jinja_environment.render_template_as_markup(

                "components/issue/index.jinja",

                issue=issue_,

                view_object=self,

            )

            issues_html += issue_html

        return issues_html

    def get_page_title(self) -> str:

        return self.document_type.get_page_title()

    def get_document_level(self) -> int:

        assert self.document.meta is not None

        return self.document.meta.level

    def date_today(self) -> str:

        return datetime.today().strftime("%Y-%m-%d")

    def get_document_by_path(self, full_path: str) -> SDocDocument:

        return self.traceability_index.document_tree.get_document_by_path(

            full_path

        )

    def get_grammar_elements(self) -> List[GrammarElement]:

        assert self.document.grammar is not None

        return self.document.grammar.elements

    def table_of_contents(

        self,

    ) -> Iterator[Tuple[SDocElementIF, DocumentIterationContext]]:

        yield from self.document_iterator.table_of_contents()

    def document_has_any_toc_nodes(self) -> bool:

        return any(self.table_of_contents())

    def document_content_iterator(

        self,

    ) -> Iterator[Tuple[SDocElementIF, DocumentIterationContext]]:

        yield from self.document_iterator.all_content(

            print_fragments=True,

        )

    def is_chunked_rendering(self) -> bool:

        """

        Chunked mode: DOCUMENT screens for large documents only (both the

        FastAPI server and static HTML export - the two differ only in how a

        chunk's HTML reaches the browser, see chunk_frame_id_for() /

        static_chunk_relative_path()).

        Activates only when the document contains strictly more content nodes

        than the lazy_document_loading_threshold option value.

        The result is computed once and memoized because the node counting

        requires a full document walk.

        """

        if self._chunked_rendering is not None:

            return self._chunked_rendering

        threshold = self.project_config.lazy_document_loading_threshold

        if threshold == 0 or not self.document_type.is_document():

            self._chunked_rendering = False

        else:

            self._chunked_rendering = self._count_content_nodes() > threshold

        return self._chunked_rendering

    def document_chunk_size(self) -> int:

        """

        Effective chunk size used by the chunked rendering templates.

        The chunking threshold caps the chunk size: with a threshold lower

        than CHUNK_SIZE, a document that activates chunked rendering must

        still be split into more than one chunk.

        """

        threshold = self.project_config.lazy_document_loading_threshold

        if 0 < threshold < CHUNK_SIZE:

            return threshold

        return CHUNK_SIZE

    def document_content_chunks(

        self, chunk_size: Optional[int] = None

    ) -> List[DocumentChunk]:

        """

        Recomputed per request; chunk cursors are node MIDs — see

        DocumentChunk.

        When chunk_size is not provided, the effective document chunk size

        is used, see document_chunk_size().

        """

        if chunk_size is None:

            chunk_size = self.document_chunk_size()

        node_mids = [

            assert_cast(node_, (SDocNodeIF, SDocDocumentIF)).reserved_mid

            for node_, _ in self.document_content_iterator()

        ]

        return slice_chunks(node_mids, chunk_size)

    def chunk_frame_id_for(

        self, node: Union[SDocNodeIF, SDocDocumentIF]

    ) -> str:

        """

        Frame id of the lazy chunk that contains node, e.g.

        "document-chunk-3", or "" when chunked rendering is inactive or the

        node is not part of the chunked content (the screen's own document

        root renders outside the chunk loop).

        Used by toc.jinja to stamp each TOC link so the deep-link script

        (toc_chunk_navigation.js) can force-load the chunk holding a target

        before scrolling to it.

        """

        if not self.is_chunked_rendering():

            return ""

        index = self._chunk_index_by_node_mid().get(node.reserved_mid)

        if index is None:

            return ""

        return f"document-chunk-{index}"

    def _chunk_index_by_node_mid(self) -> Dict[str, int]:

        # Maps each content node's reserved MID to its chunk index using the

        # same ordering and effective chunk size as document_content_chunks().

        # Built once per request and memoized.

        if self._chunk_index_by_mid is None:

            chunk_size = self.document_chunk_size()

            mapping: Dict[str, int] = {}

            for position, (node_, _) in enumerate(

                self.document_content_iterator()

            ):

                node_mid = assert_cast(

                    node_, (SDocNodeIF, SDocDocumentIF)

                ).reserved_mid

                mapping[node_mid] = position // chunk_size

            self._chunk_index_by_mid = mapping

        return self._chunk_index_by_mid

    def document_chunk_content_iterator(

        self, from_node_mid: str, count: int

    ) -> Iterator[Tuple[SDocElementIF, DocumentIterationContext]]:

        """

        Yield up to count (node, context) pairs, starting from the node whose

        reserved MID equals from_node_mid.

        The iteration always walks the document from its start because the

        per-node title numbering context must build up during the traversal.

        The nodes before the cursor node are skipped. If the cursor MID is not

        found, e.g., the node was deleted by a concurrent edit, nothing is

        yielded, and the caller is expected to render an empty fragment.

        Resolving a successor node for a stale cursor is a documented

        follow-up.

        ``count`` must be positive; HTTP callers must validate/clamp

        untrusted input before calling (the fragment route owns that

        validation).

        """

        assert count > 0, count

        cursor_found = False

        yielded = 0

        for node_, context_ in self.document_content_iterator():

            if not cursor_found:

                node_mid = assert_cast(

                    node_, (SDocNodeIF, SDocDocumentIF)

                ).reserved_mid

                if node_mid != from_node_mid:

                    continue

                cursor_found = True

            yield node_, context_

            yielded += 1

            if yielded == count:

                return

    def static_chunk_relative_path(self, chunk: DocumentChunk) -> str:

        """

        Filename of the generated .js file that delivers this chunk's HTML

        for static export, e.g. "document-chunk-3.js". Written by

        DocumentHTMLGenerator.export next to the document's own HTML output,

        and referenced client-side by toc_chunk_navigation.js's static

        delivery path (no FastAPI server to fetch a fragment route from).

        """

        assert self.document.meta is not None

        return (

            f"{self.document.meta.document_filename_base}"

            f"-chunk-{chunk.index}.js"

        )

    def static_chunk_key(self, chunk: DocumentChunk) -> str:

        """

        Key under window.StrictDoc.chunks that the generated .js file for

        this chunk assigns its rendered HTML to.

        """

        assert self.document.meta is not None

        return (

            f"{self.document.meta.document_filename_base}-chunk-{chunk.index}"

        )

    def _count_content_nodes(self) -> int:

        # This is a full document walk: no precomputed node count exists on

        # the traceability index. It is called once per request thanks to the

        # is_chunked_rendering() memoization. Note that the underlying

        # iterator re-patches node.context title numbering during the walk:

        # an idempotent mutation, the same one the render loop performs.

        return sum(1 for _ in self.document_content_iterator())

    def should_display_folder(self, folder: Folder) -> bool:

        return screen_should_display_folder(

            folder,

            self.traceability_index,

            self.project_config,

            must_only_include_non_included_sdoc=True,

        )

    def should_display_file(self, file: File) -> bool:

        return screen_should_display_file(

            file,

            self.traceability_index,

            self.project_config,

            must_only_include_non_included_sdoc=True,

        )

    def should_display_included_documents_for_document(

        self, document: SDocDocument

    ) -> bool:

        return (

            self.project_config.export_included_documents

            and len(document.included_documents) > 0

        )

    def should_display_stable_link(

        self, node: Union[SDocDocument, SDocNode]

    ) -> bool:

        assert isinstance(node, (SDocDocument, SDocNode)), node

        return node.reserved_uid is not None

    def get_stable_link(self, node: Union[SDocDocument, SDocNode]) -> str:

        """

        Get a stable link for a given node.

        An example of a link produced: ../../#SDOC_UG_CONTACT

        The copy_to_clipboard.js script consumes this link and

        transforms it into a link like: http://127.0.0.1:5111/?a=SDOC_UG_CONTACT.

        """

        assert isinstance(node, (SDocDocument, SDocNode)), node

        base_url = self.link_renderer.render_url("")

        if node.reserved_uid is not None:

            return base_url + "#" + node.reserved_uid

        if node.reserved_mid is not None and node.mid_permanent:

            return base_url + "#" + node.reserved_mid

        return base_url

    def get_html2pdf_classes(self, node: SDocNode) -> str:

        """

        Get CSS classes for html2pdf4doc for a given node.

        html2pdf4doc rules for `Narrative` requirement style:

        * If no multi-line content:

            the node is not split at all (with or without a title)

            -> add .html2pdf4doc-no-break to node.

         * ASSUMPTION:

            We assume that the number of single-line strings is no greater

            than the height of the page

        """

        assert isinstance(node, SDocNode), node

        html2pdf4doc_classes = []

        if (

            node.node_type

            in self.project_config.html2pdf_forced_page_break_nodes

        ):

            html2pdf4doc_classes.append("sdoc-html2pdf4doc-break-before")

        if not node.has_multiline_fields():

            if node.get_requirement_style_mode() == "narrative":

                html2pdf4doc_classes.append("html2pdf4doc-no-break")

            # The section that does not break away from its children.

            if node.has_child_nodes():

                html2pdf4doc_classes.append("html2pdf4doc-no-hanging")

        return " ".join(html2pdf4doc_classes)

    #

    # Document Level Actions

    #

    def can_edit_document(self, document: SDocDocument) -> bool:

        """

        Determines if the document's root configuration (title, metadata) can be edited.

        """

        return self.traceability_index.can_edit_document(document)

    #

    # Node Level Actions

    #

    def can_edit_node(self, node: Union[SDocDocument, SDocNode]) -> bool:

        return self.traceability_index.can_edit_node(node)

    def can_delete_node(self, node: Union[SDocDocument, SDocNode]) -> bool:

        return self.traceability_index.can_delete_node(node)

    def can_clone_node(self, node: Union[SDocDocument, SDocNode]) -> bool:

        return self.traceability_index.can_clone_node(node)

    def can_add_node(self, node: Union[SDocDocument, SDocNode]) -> bool:

        return self.traceability_index.can_add_node(node)

    def can_insert_next_to_node(

        self, node: Union[SDocDocument, SDocNode]

    ) -> bool:

        return self.traceability_index.can_insert_next_to_node(node)

    def get_table_first_editable_field_name(

        self, element_type: str

    ) -> Optional[str]:

        grammar = self.document.grammar

        if grammar is None:

            return None

        element = grammar.elements_by_type.get(element_type)

        if element is None:

            return None

        preferred_fields = (

            "TITLE",

            "STATEMENT",

            "RATIONALE",

            "DESCRIPTION",

            "CONTENT",

            "COMMENT",

        )

        for field_name in preferred_fields:

            if (

                field_name in element.field_titles

                and self.is_table_cell_editable(element_type, field_name)

            ):

                return field_name

        for field_name in element.field_titles:

            if field_name in ("UID", "MID", "LEVEL", "STATUS", "TAGS"):

                continue

            if self.is_table_cell_editable(element_type, field_name):

                return field_name

        for field_name in element.field_titles:

            if self.is_table_cell_editable(element_type, field_name):

                return field_name

        return None

    def can_move_node(self, node: Union[SDocDocument, SDocNode]) -> bool:

        return self.traceability_index.can_move_node(node)

    # Table editing

    #

    def get_table_cell_edit_mode(

        self, element_type: str, field_name: str

    ) -> TableCellEditMode:

        """

        Returns the editing mode for a table cell:

          AUTOCOMPLETE — SingleChoice / MultipleChoice / Tag field

          SINGLELINE   — single-line STRING field (meta fields)

          MULTILINE    — multi-line STRING field (STATEMENT, RATIONALE, COMMENT, custom content)

          READONLY     — field not declared in grammar for this element type

        """

        grammar = self.document.grammar

        if grammar is None:

            return TableCellEditMode.READONLY

        element = grammar.elements_by_type.get(element_type)

        if element is None:

            return TableCellEditMode.READONLY

        field = element.fields_map.get(field_name)

        if field is None:

            return TableCellEditMode.READONLY

        if isinstance(

            field,

            (

                GrammarElementFieldSingleChoice,

                GrammarElementFieldMultipleChoice,

                GrammarElementFieldTag,

            ),

        ):

            return TableCellEditMode.AUTOCOMPLETE

        if element.is_field_multiline(field_name):

            return TableCellEditMode.MULTILINE

        return TableCellEditMode.SINGLELINE

    def is_table_cell_editable(

        self, element_type: str, field_name: str

    ) -> bool:

        """Returns True if the field is declared in grammar and can be edited on TABLE screen."""

        if field_name == "RELATIONS":

            grammar = self.document.grammar

            if grammar is None:

                return False

            element = grammar.elements_by_type.get(element_type)

            return element is not None and len(element.relations) > 0

        return (

            self.get_table_cell_edit_mode(element_type, field_name)

            != TableCellEditMode.READONLY

        )

    def is_table_cell_multiple_choice(

        self, element_type: str, field_name: str

    ) -> bool:

        grammar = self.document.grammar

        if grammar is None:

            return False

        element = grammar.elements_by_type.get(element_type)

        if element is None:

            return False