Current TOC link item

[838]

I will try to highlight the current toc link item so the users could see where they are when they open the TOC page.

What will be correct way of knowing fx. the "href": "0002-part.xhtml#d23" link should be highlighted?

{
    "readingOrder": [
        {
            "href": "0001.xhtml",
            "properties": { "characters": 99 },
            "title": "One",
            "type": "text/html"
        },
        {
            "href": "0002.xhtml",
            "properties": { "characters": 1932 },
            "title": "Two",
            "type": "text/html"
        }
    ],
    "resources": [
        { "href": "0001.xhtml", "type": "text/html" },
        { "href": "0002.xhtml", "type": "text/html" }
    ],
    "toc": [
        { "href": "0001.xhtml#id1", "title": "One" },
        {
            "href": "0002.xhtml#d2",
            "title": "Two",
            "children": [
                {
                    "href": "0002-part.xhtml#d22",
                    "title": "Two II"
                },
                {
                    "href": "0002-part.xhtml#d23",
                    "title": "Two III"
                }
            ]
        }
    ],
    "@context": "https://readium.org/webpub-manifest/context.jsonld",
    "metadata": {
        "conformsTo": "https://readium.org/webpub-manifest/profiles/epub",
        "modified": "2022-05-19T12:03:14Z",
        "characters": 2031,
        "title": "Title",
        "language": "da",
        "type": "http://schema.org/Book"
    },
    "links": [
        {
            "href": "manifest.json",
            "rel": "self",
            "type": "application/webpub.json"
        }
    ]
}

[mickael-menu]

It's currently not supported on mobile, but something we want to implement at some point. This is a surprisingly complicated problem, especially since we moved away from EPUB CFIs which were inherently sortable.

A quick and dirty way to implement this could be to inject a JavaScript in the HTML resources observing whether any of the table of contents items become visible thanks to an Intersection Observer.

@danielweck I see that you support this feature in Thorium, would you mind chiming in on the technique you used? Thanks!

[mickael-menu]

Thank you for the detailed reply @danielweck, this is helpful!

3. this precise-ish "reading location" is of course determined from within the webview that renders the document, where some specialised JavaScript code (which was injected by the reading system into the rendered HTML document) collects useful contextual DOM information. This additional data payload is attached to the locator event which is sent across the webview boundary into the application logic. In other words, there is an event listener situated in the Electron main process (i.e. a JavaScript function callback on the other side of the IPC divide) which receives serialised DOM information that complements the basic locator object.

Is this code part of the Thorium repo, or the r2-navigator-js one?

[danielweck]

The logic is located in the "navigator" component, inside a huge Electron "preload" TypeScript file (i.e. Javascript injected into Electron WebView).

Here it the function that "collects" headings (lazy caching). Note that the Element object property does not pass through the IPC messaging system: it is resident in webview memory, but only level, id and text are used to build the event payload that reaches the consuming app.

interface IHeading {
    element: Element;
    level: number;
    id: string | undefined;
    text: string | undefined;
}
let _allHeadings: IHeading[] | undefined;
const findPrecedingAncestorSiblingHeadings = (element: Element):
    Array<{ id: string | undefined, txt: string | undefined, level: number }> | undefined => {

    if (!_allHeadings) {
        const headingElements = Array.from(window.document.querySelectorAll("h1,h2,h3,h4,h5,h6"));
        for (const n of headingElements) {
            if (n) {
                const el = n as Element;
                const t = el.textContent || el.getAttribute("title") || el.getAttribute("aria-label");
                let i = el.getAttribute("id");
                if (!i) { // common authoring pattern: parent section (or other container element) has the navigation target anchor
                    let cur = el;
                    let p: Element | null;
                    while ((p = (cur.parentNode as Element | null)) &&
                        p?.nodeType === Node.ELEMENT_NODE) {

                        if (p.firstElementChild !== cur) {
                            break;
                        }

                        const di = p.getAttribute("id");
                        if (di) {
                            i = di;
                            break;
                        }

                        cur = p;
                    }
                }
                const heading: IHeading = {
                    element: el,
                    id: i ? i : undefined,
                    // level: el.localName.toLowerCase(),
                    level: parseInt(el.localName.substring(1), 10),
                    text: t ? t : undefined,
                };
                if (!_allHeadings) {
                    _allHeadings = [];
                }
                _allHeadings.push(heading);
            }
        }

        if (!_allHeadings) {
            _allHeadings = [];
        }
    }

    let arr: Array<{ id: string | undefined, txt: string | undefined, level: number }> | undefined;
    for (let i = _allHeadings.length - 1; i >= 0; i--) {
        const heading = _allHeadings[i];

        const c = element.compareDocumentPosition(heading.element);
        // tslint:disable-next-line: no-bitwise
        if (c === 0 || (c & Node.DOCUMENT_POSITION_PRECEDING) || (c & Node.DOCUMENT_POSITION_CONTAINS)) {
            if (!arr) {
                arr = [];
            }
            arr.push({
                id: heading.id,
                level: heading.level,
                txt: heading.text,
            });
        }
    }

    return arr;
};

[danielweck]

Here is the code for EPUB "page breaks":

const _htmlNamespaces: { [prefix: string]: string } = {
    epub: "http://www.idpf.org/2007/ops",
    xhtml: "http://www.w3.org/1999/xhtml",
};
const _namespaceResolver = (prefix: string | null): string | null => {
    if (!prefix) {
        return null;
    }
    return _htmlNamespaces[prefix] || null;
};

interface IPageBreak {
    element: Element;
    text: string;
}
let _allEpubPageBreaks: IPageBreak[] | undefined;
const findPrecedingAncestorSiblingEpubPageBreak = (element: Element): string | undefined => {
    if (!_allEpubPageBreaks) {
        const xpathResult = window.document.evaluate(
            // `//*[contains(@epub:type,'pagebreak')]`,
            // `//*[tokenize(@epub:type,'\s+')='pagebreak']`
            "//*[contains(concat(' ', normalize-space(@role), ' '), ' doc-pagebreak ')] | //*[contains(concat(' ', normalize-space(@epub:type), ' '), ' pagebreak ')]",
            window.document.body,
            _namespaceResolver,
            XPathResult.ORDERED_NODE_SNAPSHOT_TYPE,
            null);

        for (let i = 0; i < xpathResult.snapshotLength; i++) {
            const n = xpathResult.snapshotItem(i);
            if (n) {
                const el = n as Element;
                const elTitle = el.getAttribute("title");
                const elLabel = el.getAttribute("aria-label");
                const elText = el.textContent;
                const pageLabel = elTitle || elLabel || elText;
                if (pageLabel) {
                    const pageBreak: IPageBreak = {
                        element: el,
                        text: pageLabel,
                    };
                    if (!_allEpubPageBreaks) {
                        _allEpubPageBreaks = [];
                    }
                    _allEpubPageBreaks.push(pageBreak);
                }
            }
        }

        if (!_allEpubPageBreaks) {
            _allEpubPageBreaks = [];
        }
    }

    for (let i = _allEpubPageBreaks.length - 1; i >= 0; i--) {
        const pageBreak = _allEpubPageBreaks[i];

        const c = element.compareDocumentPosition(pageBreak.element);
        // tslint:disable-next-line: no-bitwise
        if (c === 0 || (c & Node.DOCUMENT_POSITION_PRECEDING) || (c & Node.DOCUMENT_POSITION_CONTAINS)) {
            return pageBreak.text;
        }
    }

    return undefined;
};

[mickael-menu]

Thanks, I'll take the time to dissect all this!

[838]

@danielweck @mickael-menu
Thank you so much for your time and the very detailed explanation. I'm so glad that I have asked this here before jumping into the implementation and hitting a brick wall.