@ukic/canary-web-components 3.0.0-canary.25 → 3.0.0-canary.26

package/dist/collection/components/ic-table-of-contents/ic-table-of-contents.css

@@ -0,0 +1,145 @@
+:host {
+  display: block;
+  border: none;
+  max-height: 100vh;
+}
+
+.table-of-contents-section-container {
+  display: flex;
+}
+
+.table-of-contents-content {
+  top: 0;
+  left: 0;
+  padding: 0 var(--ic-space-md);
+  font: var(--ic-color-text-primary);
+  max-height: 100vh;
+  z-index: 1;
+}
+
+:host .table-of-contents-position-top {
+  min-width: 10rem;
+  max-width: 50rem;
+}
+
+:host .table-of-contents-position-side {
+  min-width: 8rem;
+  max-width: 20rem;
+  width: 20rem;
+  position: sticky;
+}
+
+.table-of-contents-list {
+  display: flex;
+  flex-direction: row;
+  max-width: inherit;
+}
+
+:host ol {
+  list-style: none;
+  margin-block-start: 0;
+  padding-inline-start: 0;
+}
+
+.table-of-contents-list-items {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+}
+
+.table-of-contents-sidebar {
+  background-color: var(--ic-table-of-contents-banner);
+  height: 1.75rem;
+  min-width: 0.25rem;
+}
+
+.table-of-contents-sidebar-monochrome {
+  background-color: var(--ic-table-of-contents-banner-monochrome);
+}
+
+.table-of-contents-item {
+  min-height: 1.5rem;
+  line-height: 1.5rem;
+}
+
+.table-of-contents-item-content:hover {
+  background-color: var(--ic-table-of-contents-hover);
+}
+
+.table-of-contents-item-monochrome-content:hover {
+  background-color: var(--ic-table-of-contents-hover-monochrome);
+}
+
+.table-of-contents-item-content {
+  border: none;
+  max-width: inherit;
+  display: flex;
+  align-items: center;
+  text-decoration: none;
+  position: relative;
+  color: var(--ic-table-of-contents-text);
+  min-height: 1.5rem;
+
+  --ic-typography-color: var(--ic-table-of-contents-text);
+}
+
+.table-of-contents-item-content-default {
+  padding-top: var(--ic-space-xxxs);
+  padding-bottom: var(--ic-space-xxxs);
+}
+
+.table-of-contents-item-content:focus {
+  box-shadow: var(--ic-border-focus);
+  border-radius: var(--ic-border-radius);
+  transition: var(--ic-transition-duration-fast);
+  outline: none;
+  background-color: var(--ic-table-of-contents-hover);
+}
+
+.table-of-contents-item-content:active {
+  box-shadow: var(--ic-border-focus);
+  border-radius: var(--ic-border-radius);
+  transition: var(--ic-transition-duration-fast);
+  outline: none;
+  background-color: var(--ic-table-of-contents-pressed);
+}
+
+.truncated-item-text {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* Large styles */
+
+.table-of-contents-item-content-large {
+  padding-top: var(--ic-space-xxs);
+  padding-bottom: var(--ic-space-xxs);
+}
+
+.table-of-contents-sidebar.large {
+  height: 2.5rem;
+}
+
+.table-of-contents-heading.large {
+  padding-bottom: var(--ic-space-xs);
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .table-of-contents-sidebar {
+    transition: all 0.3s ease;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  /* limit sidebar scroll animation */
+  .table-of-contents-sidebar {
+    transition: none;
+  }
+}
+
+@media (forced-colors: active) {
+  .table-of-contents-sidebar {
+    background-color: Highlight;
+  }
+}

package/dist/collection/components/ic-table-of-contents/ic-table-of-contents.js

@@ -0,0 +1,526 @@
+import { h, Host } from "@stencil/core";
+import { TableOfContentsItem } from "./ic-table-of-contents-item";
+import { DEVICE_SIZES } from "../../utils/helpers";
+const TOC_CONTENT_CLASS = "table-of-contents-content";
+const TOC_LIST_ITEMS_CLASS = "table-of-contents-list-items";
+const TOC_ITEM_CLASS = "table-of-contents-item-content";
+const TOC_CONTAINER_CLASS = "table-of-contents-section-container";
+export class TableOfContents {
+    constructor() {
+        /**
+         * Heading text of the table of contents.
+         */
+        this.heading = "Contents";
+        /**
+         * Maximum heading level of child content that will generate an item in the table of contents. E.g. when set to '3', headings of <h4> and <h5> will not appear.
+         */
+        this.maximumHeadingLevel = 3;
+        /**
+         * If `true`, the table of contents will display as black in the light theme, and white in dark theme.
+         */
+        this.monochrome = false;
+        /**
+         * Whether the table of contents will appear on the right of or above child content on large viewport widths.
+         */
+        this.position = "right";
+        /**
+         * Vertical offset to page scroll (in percent) when table of contents item is selected, to account for other page components like headers.
+         */
+        this.setScrollHeight = 50;
+        /**
+         * The size of the table of contents items.
+         */
+        this.size = "medium";
+        /**
+         * Sets the theme color to the dark or light theme color. "inherit" will set the color based on the system settings or ic-theme component.
+         */
+        this.theme = "inherit";
+        /**
+         * If `true`, the table of contents item label will be truncated.
+         */
+        this.truncate = true;
+        this.focusedElement = 0;
+        // heading items
+        this.referenceElements = [];
+        // heights of heading items
+        this.currentTargetHeights = [];
+        // header height if present
+        this.headerHeight = 0;
+        // holds initial position to allow for responsive changes
+        this.initialPosition = this.position;
+        // suppress scroll listener to allow for click selection without scroll listener firing
+        this.suppressListener = false;
+        /**
+         * Generate a TOC Item.
+         * These items are wrapped in empty tooltips that will be populated by addTooltip()
+         * @param tocHeading heading element to refer item information from
+         * @param children
+         * @returns TocItem ready to be rendered, with nested children if applicable
+         */
+        this.createTocItem = (tocHeading, children) => {
+            const tocId = `toc_${tocHeading.id}`;
+            const tocItem = (h(TableOfContentsItem, { id: tocId, className: TOC_ITEM_CLASS, variant: tocHeading.tagName.toLowerCase(), label: tocHeading.textLabel, target: tocHeading.id, truncate: this.truncate, selected: this.focusedElement, updateSelected: this.updateOnSelection, position: tocHeading.trueIndex, size: this.size }));
+            const wrappedToc = this.truncate ? (h("ic-tooltip", { target: tocId, label: tocHeading.innerHTML }, tocItem)) : (tocItem);
+            return (h("li", { class: `table-of-contents-item  ${this.monochrome && "table-of-contents-item-monochrome"}` }, wrappedToc, children ? h("ol", null, children) : null));
+        };
+        /**
+         * Render TocItems and recursively render children items if they exist
+         * @param listItem
+         * @returns HTML Element array to be rendered
+         */
+        this.renderTocTree = (listItem) => {
+            let results;
+            if (listItem.treeChildren.length > 0) {
+                const children = listItem.treeChildren.map((i) => this.renderTocTree(i));
+                results = this.createTocItem(listItem, children);
+            }
+            else {
+                results = this.createTocItem(listItem);
+            }
+            return results;
+        };
+        // list item clicked logic
+        this.updateOnSelection = (position) => {
+            this.suppressListener = true;
+            this.focusedElement = position;
+            this.sidebarTranslation(this.focusedElement);
+        };
+        // truncate text if it goes out of bounds of the container
+        this.truncateText = () => {
+            var _a, _b;
+            const links = (_a = this.el.shadowRoot) === null || _a === void 0 ? void 0 : _a.querySelectorAll(`.${TOC_ITEM_CLASS}`);
+            const contentList = (_b = this.el.shadowRoot) === null || _b === void 0 ? void 0 : _b.querySelector(`.${TOC_LIST_ITEMS_CLASS}`);
+            if (contentList)
+                links === null || links === void 0 ? void 0 : links.forEach((item) => {
+                    this.addTooltip(item, DEVICE_SIZES.S);
+                });
+        };
+    }
+    suppressListenerHandler() {
+        window.scrollTo(0, window.scrollY - this.headerHeight - 50);
+    }
+    /**
+     * Scrape for heading elements on the page content within TOC, down to the maximumHeadingLevel.
+     * From this, generate an array of Elements with lower rank headings inserted as treeChildren on top level headings.
+     * @returns RankedElement[] array of HTML elements with additional props for rank, trueIndex and treeChildren array
+     */
+    generateHeadingTree() {
+        var _a;
+        const resultArray = [];
+        const headingDepth = this.maximumHeadingLevel < 5
+            ? ["h2", "h3", "h4", "h5"]
+                .slice(0, (this.maximumHeadingLevel < 2 ? 2 : this.maximumHeadingLevel) - 1)
+                .join(",")
+            : "h2, h3, h4, h5";
+        const headingList = this.el.querySelectorAll(headingDepth);
+        if (headingList) {
+            const headingArray = Array.from(headingList);
+            headingArray.forEach((item, index) => {
+                this.referenceElements.push(item);
+                item.trueIndex = index;
+                item.rank = item.tagName.toLowerCase().slice(1, 2);
+                item.textLabel = item.textContent
+                    ? item.textContent.trimStart().split("\n")[0]
+                    : `${item.rank}-${index}`;
+                item.treeChildren = [];
+            });
+            let currentRank = ((_a = headingArray[0]) === null || _a === void 0 ? void 0 : _a.rank) || 2;
+            headingArray.reverse().forEach((h, i) => {
+                if (!h.id) {
+                    h.setAttribute("id", h.textLabel.replace(/\s+/g, "-").toLowerCase());
+                }
+                if (h.rank > currentRank && h.trueIndex > 0) {
+                    if (headingArray[i] && headingArray[i].rank < h.rank) {
+                        headingArray[i].treeChildren.unshift(h);
+                    }
+                    else {
+                        resultArray.push(h);
+                    }
+                }
+                else {
+                    currentRank = h.rank;
+                    resultArray.push(h);
+                }
+            });
+        }
+        return resultArray.reverse();
+    }
+    //container orientation logic
+    containerPosition() {
+        var _a;
+        if (this.position) {
+            const container = (_a = this.el.shadowRoot) === null || _a === void 0 ? void 0 : _a.querySelector(`.${TOC_CONTAINER_CLASS}`);
+            switch (this.position) {
+                case "right":
+                    container.style.flexDirection = "row-reverse";
+                    break;
+                case "top":
+                    container.style.flexDirection = "column";
+                    break;
+            }
+        }
+    }
+    /**
+     * Move the sidebar to the provided position on the page.
+     * Also, resize the sidebar to stretch the height of the selected heading.
+     * @param newPosition
+     */
+    sidebarTranslation(newPosition) {
+        var _a, _b, _c;
+        const sidebar = (_a = this.el.shadowRoot) === null || _a === void 0 ? void 0 : _a.querySelector(".table-of-contents-sidebar");
+        const itemHeights = [];
+        let previousItemsHeight = 0;
+        (_c = (_b = this.el.shadowRoot) === null || _b === void 0 ? void 0 : _b.querySelectorAll(`.${TOC_ITEM_CLASS}`)) === null || _c === void 0 ? void 0 : _c.forEach((item) => {
+            if (item !== null)
+                itemHeights.push(item.offsetHeight);
+        });
+        itemHeights
+            .slice(0, newPosition)
+            .forEach((i) => (previousItemsHeight += i));
+        sidebar.style.transform = `translateY(${previousItemsHeight}px)`;
+        sidebar.style.height = `${itemHeights[newPosition]}px`;
+    }
+    // find element heights to be used to determine focused item from scroll position
+    findElementsHeights() {
+        const contentBounds = [];
+        this.referenceElements.forEach((element) => {
+            contentBounds.push(element.getBoundingClientRect().top);
+        });
+        this.currentTargetHeights = contentBounds;
+    }
+    //resize window logic
+    handleResizeBounds() {
+        if (window.innerWidth < DEVICE_SIZES.XL && this.initialPosition !== "top") {
+            this.position = "top";
+            this.containerPosition();
+        }
+        else if (window.innerWidth > DEVICE_SIZES.XL &&
+            this.position === "top" &&
+            this.initialPosition === "right") {
+            this.position = "right";
+            this.containerPosition();
+        }
+        this.findElementsHeights();
+        this.truncateText();
+    }
+    // scroll logic
+    updateSelectedItemFromScroll() {
+        const targetHeight = window.scrollY + window.innerHeight * (this.setScrollHeight / 100);
+        if (window.scrollY === 0) {
+            this.focusedElement = 0;
+            this.sidebarTranslation(this.focusedElement);
+        }
+        else if (targetHeight < this.currentTargetHeights[this.focusedElement]) {
+            const previousItems = this.currentTargetHeights.slice(0, this.focusedElement);
+            const closestItem = previousItems.reduce((newValue, curr, index) => {
+                if (Math.abs(curr - targetHeight) <
+                    Math.abs(previousItems[newValue] - targetHeight))
+                    return index;
+                return newValue;
+            }, 0);
+            this.focusedElement = closestItem;
+            this.sidebarTranslation(this.focusedElement);
+        }
+        else if (targetHeight > this.currentTargetHeights[this.focusedElement] &&
+            this.focusedElement !== this.currentTargetHeights.length) {
+            const relevantItems = this.currentTargetHeights.slice(this.focusedElement);
+            const closestItem = relevantItems.reduce((newValue, curr, index) => {
+                if (Math.abs(curr - targetHeight) <
+                    Math.abs(relevantItems[newValue] - targetHeight) &&
+                    curr < targetHeight)
+                    return index;
+                return newValue;
+            }, 0);
+            if (closestItem + this.focusedElement !== this.focusedElement) {
+                this.focusedElement += closestItem;
+                this.sidebarTranslation(this.focusedElement);
+            }
+        }
+    }
+    // find header element height
+    findHeaderElement() {
+        const element = document.querySelector("ic-page-header");
+        if (element) {
+            return element.clientHeight;
+        }
+        const header = document.querySelector("header");
+        if (header) {
+            return header.clientHeight;
+        }
+        return 0;
+    }
+    // add margin to the list based off the header element height
+    addListMargin() {
+        var _a;
+        const content = (_a = this.el.shadowRoot) === null || _a === void 0 ? void 0 : _a.querySelector(`.${TOC_CONTENT_CLASS}`);
+        content === null || content === void 0 ? void 0 : content.style.setProperty("top", `${this.headerHeight}px`);
+    }
+    // add tooltip to the item if it is too wide
+    addTooltip(item, widthBreakpoint) {
+        var _a;
+        const itemLabel = item.querySelector(".table-of-contents-item-label");
+        if (((_a = item.parentNode) === null || _a === void 0 ? void 0 : _a.tagName) == "IC-TOOLTIP") {
+            const tooltip = item.parentNode;
+            if ((itemLabel === null || itemLabel === void 0 ? void 0 : itemLabel.offsetWidth) < (itemLabel === null || itemLabel === void 0 ? void 0 : itemLabel.scrollWidth)) {
+                const tooltipPosition = window.innerWidth < widthBreakpoint
+                    ? "bottom"
+                    : this.position === "right"
+                        ? "left"
+                        : "right";
+                //Modify the ic-tooltip wrapped around the list item
+                tooltip.setAttribute("disable-click", false);
+                tooltip.setAttribute("disable-hover", false);
+                tooltip.setAttribute("placement", tooltipPosition);
+                tooltip.setAttribute("target", item.id);
+                tooltip.setAttribute("style", "overflow:hidden");
+            }
+            else {
+                //disable the tooltip if the item does not need to truncate
+                tooltip.setAttribute("disable-click", true);
+                tooltip.setAttribute("disable-hover", true);
+            }
+        }
+    }
+    // initialise resize observer
+    componentWillLoad() {
+        this.resizeObserver = new ResizeObserver(() => this.handleResizeBounds());
+        this.resizeObserver.observe(this.el);
+    }
+    // initialise scroll listener
+    componentDidRender() {
+        document.addEventListener("scroll", () => {
+            if (!this.suppressListener)
+                this.updateSelectedItemFromScroll();
+            else
+                this.suppressListener = false;
+        });
+        this.containerPosition();
+        this.findElementsHeights();
+        this.sidebarTranslation(this.focusedElement);
+    }
+    // after component has loaded modify the list based of position, size and surrounding elements
+    async componentDidLoad() {
+        this.focusedElement = 0;
+        this.headerHeight = this.findHeaderElement();
+        this.addListMargin();
+        this.truncateText();
+        this.findElementsHeights();
+        this.sidebarTranslation(this.focusedElement);
+    }
+    // Component is a wrapper for page contents, and will build list from heading items
+    render() {
+        const { heading, monochrome, position, size, theme } = this;
+        return (h(Host, { key: '251846b7b12255064f6f08dc5ed373e8ccf0326b', class: { [`ic-theme-${theme}`]: theme !== "inherit" } }, h("ic-section-container", { key: '3a178d62dfe2ce56c052e18114bb2d7c3fbd47ee', class: TOC_CONTAINER_CLASS, aligned: "full-width" }, h("div", { key: '34378cb8e4ac052d1f05cdc7b61880ab866e5c30', role: "navigation", class: `${TOC_CONTENT_CLASS} ${position === "top" && "table-of-contents-position-top"}
+            ${position === "right" && "table-of-contents-position-side"}` }, h("ic-typography", { key: '9c2e6cd5dcf1bdcaada2fc63035c3fbe1aff0f44', class: `table-of-contents-heading ${size}`, variant: "subtitle-large" }, heading), h("div", { key: '848fbb7b4e2923e6abc7c2b7dbe267221b0158e6', class: "table-of-contents-list" }, h("div", { key: '31324398f103b292dfdf6edec92e738fa0c49c60', class: `table-of-contents-sidebar ${monochrome && `table-of-contents-sidebar-monochrome`}
+                ${size}
+                ` }), h("ol", { key: 'b4cf6c02151d3257155a4b8e055df992b06e64e0', class: TOC_LIST_ITEMS_CLASS }, this.generateHeadingTree().map((item) => this.renderTocTree(item))))), h("slot", { key: '0a5e55adfd3eeb0ba3c502c8936557f1b5f8bd76' }))));
+    }
+    static get is() { return "ic-table-of-contents"; }
+    static get encapsulation() { return "shadow"; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["ic-table-of-contents.css"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["ic-table-of-contents.css"]
+        };
+    }
+    static get properties() {
+        return {
+            "heading": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Heading text of the table of contents."
+                },
+                "getter": false,
+                "setter": false,
+                "attribute": "heading",
+                "reflect": false,
+                "defaultValue": "\"Contents\""
+            },
+            "maximumHeadingLevel": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "number",
+                    "resolved": "number",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Maximum heading level of child content that will generate an item in the table of contents. E.g. when set to '3', headings of <h4> and <h5> will not appear."
+                },
+                "getter": false,
+                "setter": false,
+                "attribute": "maximum-heading-level",
+                "reflect": false,
+                "defaultValue": "3"
+            },
+            "monochrome": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "If `true`, the table of contents will display as black in the light theme, and white in dark theme."
+                },
+                "getter": false,
+                "setter": false,
+                "attribute": "monochrome",
+                "reflect": false,
+                "defaultValue": "false"
+            },
+            "position": {
+                "type": "string",
+                "mutable": true,
+                "complexType": {
+                    "original": "IcPositionTopOrRight",
+                    "resolved": "\"right\" | \"top\"",
+                    "references": {
+                        "IcPositionTopOrRight": {
+                            "location": "import",
+                            "path": "../../utils/types",
+                            "id": "src/utils/types.ts::IcPositionTopOrRight"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Whether the table of contents will appear on the right of or above child content on large viewport widths."
+                },
+                "getter": false,
+                "setter": false,
+                "attribute": "position",
+                "reflect": false,
+                "defaultValue": "\"right\""
+            },
+            "setScrollHeight": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "number",
+                    "resolved": "number",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Vertical offset to page scroll (in percent) when table of contents item is selected, to account for other page components like headers."
+                },
+                "getter": false,
+                "setter": false,
+                "attribute": "set-scroll-height",
+                "reflect": false,
+                "defaultValue": "50"
+            },
+            "size": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "IcSizes",
+                    "resolved": "\"large\" | \"medium\" | \"small\"",
+                    "references": {
+                        "IcSizes": {
+                            "location": "import",
+                            "path": "../../utils/types",
+                            "id": "src/utils/types.ts::IcSizes"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "The size of the table of contents items."
+                },
+                "getter": false,
+                "setter": false,
+                "attribute": "size",
+                "reflect": false,
+                "defaultValue": "\"medium\""
+            },
+            "theme": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "IcThemeMode",
+                    "resolved": "\"dark\" | \"inherit\" | \"light\" | undefined",
+                    "references": {
+                        "IcThemeMode": {
+                            "location": "import",
+                            "path": "../../utils/types",
+                            "id": "src/utils/types.ts::IcThemeMode"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Sets the theme color to the dark or light theme color. \"inherit\" will set the color based on the system settings or ic-theme component."
+                },
+                "getter": false,
+                "setter": false,
+                "attribute": "theme",
+                "reflect": false,
+                "defaultValue": "\"inherit\""
+            },
+            "truncate": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "If `true`, the table of contents item label will be truncated."
+                },
+                "getter": false,
+                "setter": false,
+                "attribute": "truncate",
+                "reflect": false,
+                "defaultValue": "true"
+            }
+        };
+    }
+    static get states() {
+        return {
+            "focusedElement": {},
+            "suppressListener": {}
+        };
+    }
+    static get elementRef() { return "el"; }
+    static get watchers() {
+        return [{
+                "propName": "suppressListener",
+                "methodName": "suppressListenerHandler"
+            }];
+    }
+}
+//# sourceMappingURL=ic-table-of-contents.js.map