@hortonstudio/main 1.2.4 → 1.2.6

package/attributes-master/packages/toc/src/actions/collect.ts

@@ -0,0 +1,136 @@
+import {
+  ALLOWED_HEADINGS_SELECTOR,
+  ANCHOR_SELECTOR,
+  CUSTOM_HEADING_REGEXP,
+  DEFAULT_INITIAL_HEADING_LEVEL,
+  OMIT_HEADING_REGEXP,
+} from '../utils/constants';
+import { extractHeadingLevel } from '../utils/helpers';
+import { getElementSelector } from '../utils/selectors';
+import type { HeadingData, LinkData } from '../utils/types';
+import { createHeadingWrapper } from './create';
+
+/**
+ * Collects the {@link HeadingData} of all heading elements.
+ * @param contentsElement The element that holds all the contents.
+ *
+ * @returns A {@link HeadingData} array
+ */
+export const collectHeadingsData = ({ children }: HTMLElement) => {
+  const headingsData: HeadingData[] = [];
+
+  for (let i = children.length - 1; i >= 0; i--) {
+    const child = children[i];
+    if (!child) continue;
+
+    const headingElement = child.closest<HTMLParagraphElement>(ALLOWED_HEADINGS_SELECTOR);
+    if (!headingElement) continue;
+
+    const { tagName, textContent } = headingElement;
+    if (!textContent) continue;
+
+    const omit = textContent.match(OMIT_HEADING_REGEXP);
+    if (omit) {
+      headingElement.textContent = textContent.replace(OMIT_HEADING_REGEXP, '').trim();
+      continue;
+    }
+
+    const [customTag] = textContent.match(CUSTOM_HEADING_REGEXP) || [];
+    if (customTag) headingElement.textContent = textContent.replace(CUSTOM_HEADING_REGEXP, '').trim();
+
+    const level = extractHeadingLevel(customTag || tagName);
+    if (!level) continue;
+
+    const headingWrapper = createHeadingWrapper(headingElement);
+    if (!headingWrapper) continue;
+
+    const { id } = headingWrapper;
+
+    // Create a placeholder level memo when a heading level has been skipped
+    // Example: the user added an <h5> after an <h3>, he skipped the <h4> level
+    const [previousHeadingData] = headingsData;
+
+    if (previousHeadingData?.level) {
+      const correspondingLevel = previousHeadingData.level - 1;
+
+      if (level < correspondingLevel) {
+        for (let i = 1; i <= correspondingLevel - level; i++) {
+          headingsData.unshift({ level: previousHeadingData.level - i });
+        }
+      }
+    }
+
+    // Render the wrapper
+    headingElement.insertAdjacentElement('beforebegin', headingWrapper);
+
+    // Group all lower elements under the wrapper
+    const nextHeading = headingsData.find((headingData) => headingData.level <= level);
+    const childrenSlice = Array.from(children).slice(i + 1);
+
+    for (const element of childrenSlice) {
+      if (element === nextHeading?.headingWrapper) break;
+
+      headingWrapper.append(element);
+    }
+
+    // Store the data
+    headingsData.unshift({
+      level,
+      headingElement,
+      headingWrapper,
+      id,
+    });
+  }
+
+  return headingsData;
+};
+
+/**
+ * Collects the template links data.
+ * @param firstLinkTemplate
+ * @returns A {@link LinkData} array.
+ */
+export const collectLinksData = (firstLinkTemplate: Element) => {
+  const linksData: LinkData[] = [];
+
+  const collectLinkData = (referenceNode: Element) => {
+    // Query elements
+    const linkElement = referenceNode.closest('a');
+    if (!linkElement) return;
+
+    const component = linkElement.parentElement;
+    if (!component) return;
+
+    // Get the link level
+    const previousLevel = linksData[linksData.length - 1]?.level;
+    const level = previousLevel ? previousLevel + 1 : DEFAULT_INITIAL_HEADING_LEVEL;
+
+    linksData.push({
+      linkElement,
+      level,
+      component,
+    });
+
+    // Get next link component
+    const followingTextNodes = [...component.querySelectorAll(`* ${getElementSelector('link')}`)];
+    const followingTextNode = followingTextNodes.find((node) => node !== referenceNode);
+
+    if (!followingTextNode) return component;
+
+    const followingComponent = collectLinkData(followingTextNode);
+
+    // Place the anchor
+    if (followingComponent) {
+      const anchor = new Comment(ANCHOR_SELECTOR);
+      component.insertBefore(anchor, followingComponent);
+      followingComponent.remove();
+    }
+
+    return component;
+  };
+
+  // Init collection
+  collectLinkData(firstLinkTemplate);
+
+  return linksData;
+};

package/attributes-master/packages/toc/src/actions/create.ts

@@ -0,0 +1,44 @@
+import slugify from 'slugify';
+
+import { ZERO_WIDTH_CHARS_REGEXP } from '../utils/constants';
+
+/**
+ * Creates a wrapper element for a heading and identifies it.
+ * @param headingElement
+ * @returns The new wrapper element.
+ */
+export const createHeadingWrapper = (headingElement: HTMLHeadingElement) => {
+  const headingWrapper = document.createElement('div');
+
+  const { id, textContent } = headingElement;
+  const trimmedTextContent = textContent?.trim().replace(ZERO_WIDTH_CHARS_REGEXP, '');
+
+  if (!id && !trimmedTextContent) return;
+
+  if (id) {
+    headingElement.removeAttribute('id');
+    headingWrapper.id = ensureUniqueId(id);
+  } else if (trimmedTextContent) {
+    const slugified = slugify(trimmedTextContent, { lower: true, strict: true });
+    headingWrapper.id = ensureUniqueId(slugified);
+  }
+
+  return headingWrapper;
+};
+
+/**
+ * Ensures that an element ID is unique on the page by adding an index suffix if necessary.
+ * @param requestedId
+ * @returns The unique ID.
+ */
+const ensureUniqueId = (requestedId: string) => {
+  let proposedId = requestedId;
+  let index = 2;
+
+  while (document.getElementById(proposedId)) {
+    proposedId = `${requestedId}-${index}`;
+    index += 1;
+  }
+
+  return proposedId;
+};

package/attributes-master/packages/toc/src/actions/events.ts

@@ -0,0 +1,29 @@
+import { addListener, isElement } from '@finsweet/attributes-utils';
+
+/**
+ * Prevents the TOC links from adding the hash in the URL.
+ * @param tocWrapper
+ * @param hideURLHash Defines if the URL hash should be hidden after clicking the links.
+ *
+ * @returns A callback to remove the event listener.
+ */
+export const listenTOCLinkClicks = (tocWrapper: HTMLElement, hideURLHash?: boolean) => {
+  const clickCleanup = addListener(tocWrapper, 'click', (e) => {
+    if (!isElement(e.target)) return;
+
+    const link = e.target.closest('a');
+    if (!link) return;
+
+    e.stopPropagation();
+
+    if (!hideURLHash) return;
+
+    window.setTimeout(() => {
+      const { origin, pathname, search } = window.location;
+
+      history.replaceState('', document.title, origin + pathname + search);
+    });
+  });
+
+  return clickCleanup;
+};

package/attributes-master/packages/toc/src/actions/observe.ts

@@ -0,0 +1,31 @@
+import { isHTMLAnchorElement } from '@finsweet/attributes-utils';
+
+import type { TOCItem } from '../components/TOCItem';
+
+/**
+ * Observes when the TOC links' state changes.
+ * @param tocWrapper
+ * @param tocItems
+ *
+ * @returns The MutationObserver.
+ */
+export const observeLinksState = (tocWrapper: HTMLElement, tocItems: TOCItem[]) => {
+  const observer = new MutationObserver((mutations) => {
+    for (const { target } of mutations) {
+      if (!isHTMLAnchorElement(target)) continue;
+
+      const tocItem = tocItems.find(({ linkElement }) => linkElement === target);
+      if (!tocItem) continue;
+
+      tocItem.updateState();
+    }
+  });
+
+  observer.observe(tocWrapper, {
+    attributes: true,
+    subtree: true,
+    attributeFilter: ['class'],
+  });
+
+  return observer;
+};

package/attributes-master/packages/toc/src/actions/populate.ts

@@ -0,0 +1,68 @@
+import { cloneNode } from '@finsweet/attributes-utils';
+
+import { TOCItem } from '../components/TOCItem';
+import { ANCHOR_SELECTOR } from '../utils/constants';
+import { getElementSelector, queryElement } from '../utils/selectors';
+import type { HeadingData, LinkData } from '../utils/types';
+
+/**
+ * Populates all links using the headings data.
+ * @param headingsData
+ * @param linksData
+ * @param tocWrapper
+ */
+export const populateLinks = (headingsData: HeadingData[], linksData: LinkData[], tocWrapper: HTMLElement) => {
+  const tocItems: TOCItem[] = [];
+  const levelsMemo: TOCItem[] = [];
+
+  for (const headingData of headingsData) {
+    // Get the corresponding link data
+    const linkData = linksData.find((data) => data.level === headingData.level);
+    if (!linkData) continue;
+
+    // Get the level memo
+    for (let i = levelsMemo.length - 1; i >= 0; i--) {
+      if (headingData.level > levelsMemo[i].level) break;
+
+      levelsMemo.pop();
+    }
+
+    const levelMemo = levelsMemo[levelsMemo.length - 1];
+
+    // Create the component
+    const linkWrapper = levelMemo?.component || tocWrapper;
+    const component = cloneNode(linkData.component);
+
+    const referenceNode = queryElement('link', { scope: component });
+    if (!referenceNode) continue;
+
+    const linkElement = referenceNode.closest('a');
+    if (!linkElement) continue;
+
+    const anchor = [...linkWrapper.childNodes].find(
+      ({ nodeType, nodeValue }) => nodeType === 8 && nodeValue === ANCHOR_SELECTOR
+    );
+    if (!anchor) continue;
+
+    const ixTrigger = component.querySelector<HTMLElement>(`:scope > ${getElementSelector('ix-trigger')}`);
+
+    const tocItem = new TOCItem({
+      linkWrapper,
+      component,
+      referenceNode,
+      linkElement,
+      ixTrigger,
+      anchor,
+      ...headingData,
+    });
+
+    // Store the new level memo
+    if (!levelMemo || headingData.level > levelMemo.level) {
+      levelsMemo.push(tocItem);
+    }
+
+    tocItems.push(tocItem);
+  }
+
+  return tocItems;
+};

package/attributes-master/packages/toc/src/actions/prepare.ts

@@ -0,0 +1,25 @@
+import { ANCHOR_SELECTOR } from '../utils/constants';
+import { queryElement } from '../utils/selectors';
+import type { LinkData } from '../utils/types';
+
+/**
+ * Queries the TOC wrapper and replaces the template links for an anchor placeholder.
+ * @param linksData
+ * @param instance
+ *
+ * @returns The TOC wrapper element.
+ */
+export const prepareTOC = ([{ component: firstLinkComponent }]: LinkData[], instance: string | null) => {
+  const tocWrapper = queryElement('table', { instance }) || firstLinkComponent.parentElement;
+  if (!tocWrapper) return;
+
+  const anchor = new Comment(ANCHOR_SELECTOR);
+  const isDirectChild = firstLinkComponent.parentElement === tocWrapper;
+
+  if (isDirectChild) tocWrapper.insertBefore(anchor, firstLinkComponent);
+  else tocWrapper.append(anchor);
+
+  firstLinkComponent.remove();
+
+  return tocWrapper;
+};

package/attributes-master/packages/toc/src/actions/scroll.ts

@@ -0,0 +1,33 @@
+import type { TOCItem } from '../components/TOCItem';
+import { getElementSelector } from '../utils/selectors';
+import type { ScrollOffsetStyles } from '../utils/types';
+
+/**
+ * Sets scroll offset to all headings using CSS scroll-margin.
+ * @param tocWrapper
+ * @param tocItems
+ * @param offsets
+ *
+ */
+export const setScrollOffsets = (tocItems: TOCItem[], offsets: ScrollOffsetStyles) => {
+  if (!Object.values(offsets).some(Boolean)) return;
+
+  document.documentElement.style.scrollBehavior = 'smooth';
+
+  for (const tocItem of tocItems) {
+    tocItem.setScrollOffset(offsets);
+  }
+};
+
+/**
+ * Scrolls into view the currently active hash anchor in the URL, only if it's part of the table of contents.
+ */
+export const scrollToAnchor = () => {
+  const { hash } = window.location;
+  if (!hash) return;
+
+  const id = hash.replace('#', '');
+  const headingWrapper = document.querySelector(`${getElementSelector('contents')} [id="${id}"]`);
+
+  if (headingWrapper) headingWrapper.scrollIntoView({ behavior: 'smooth' });
+};

package/attributes-master/packages/toc/src/components/TOCItem.ts

@@ -0,0 +1,88 @@
+import { CURRENT_CSS_CLASS, Interaction } from '@finsweet/attributes-utils';
+
+import type { ScrollOffsetStyles, TOCData } from '../utils/types';
+
+export class TOCItem implements TOCData {
+  public readonly level: number;
+  public readonly linkWrapper: HTMLElement;
+  public readonly referenceNode: Element;
+  public readonly anchor: Node;
+  public readonly component: HTMLElement;
+  public readonly linkElement: HTMLAnchorElement;
+  public readonly headingElement?: HTMLHeadingElement;
+  public readonly headingWrapper?: HTMLDivElement;
+  public readonly id?: string;
+  public readonly ixTrigger: HTMLElement | null;
+
+  private readonly interaction?: Interaction;
+
+  private currentState?: boolean;
+
+  constructor({
+    level,
+    component,
+    linkElement,
+    linkWrapper,
+    headingElement,
+    headingWrapper,
+    id,
+    ixTrigger,
+    referenceNode,
+    anchor,
+  }: TOCData) {
+    this.level = level;
+    this.linkWrapper = linkWrapper;
+    this.referenceNode = referenceNode;
+    this.anchor = anchor;
+    this.component = component;
+    this.linkElement = linkElement;
+    this.headingElement = headingElement;
+    this.headingWrapper = headingWrapper;
+    this.id = id;
+    this.ixTrigger = ixTrigger;
+    this.interaction = ixTrigger ? new Interaction({ element: ixTrigger }) : undefined;
+
+    this.#render();
+  }
+
+  /**
+   * Populates and the link in the TOC.
+   */
+  #render() {
+    const { headingElement, id, referenceNode, linkElement, linkWrapper, component, anchor } = this;
+
+    if (headingElement && id) {
+      referenceNode.textContent = headingElement.textContent;
+      linkElement.href = `#${id}`;
+    } else {
+      linkElement.remove();
+    }
+
+    linkWrapper.insertBefore(component, anchor);
+  }
+
+  /**
+   * Sets scroll offset to the heading using CSS scroll-margin.
+   * @param offsets
+   */
+  public setScrollOffset(offsets: ScrollOffsetStyles) {
+    const { headingWrapper } = this;
+
+    if (headingWrapper) Object.assign(headingWrapper.style, offsets);
+  }
+
+  /**
+   * Updates the `active` state of the link and triggers the correspondent interaction, if existing.
+   */
+  public updateState() {
+    const { linkElement, interaction, currentState } = this;
+
+    const isActive = linkElement.classList.contains(CURRENT_CSS_CLASS);
+
+    if (isActive === currentState) return;
+
+    interaction?.trigger(isActive ? 'first' : 'second');
+
+    this.currentState = isActive;
+  }
+}

package/attributes-master/packages/toc/src/factory.ts

@@ -0,0 +1,47 @@
+import { collectHeadingsData, collectLinksData } from './actions/collect';
+import { listenTOCLinkClicks } from './actions/events';
+import { observeLinksState } from './actions/observe';
+import { populateLinks } from './actions/populate';
+import { prepareTOC } from './actions/prepare';
+import { setScrollOffsets } from './actions/scroll';
+import { getAttribute, getInstance, hasAttributeValue, queryElement } from './utils/selectors';
+
+/**
+ * Inits a TOC instance.
+ * @param contentsElement
+ * @returns
+ */
+export const initTOCInstance = (contentsElement: HTMLElement) => {
+  const instance = getInstance(contentsElement);
+
+  const linkTemplate = queryElement('link', { instance });
+  if (!linkTemplate) return;
+
+  const headingsData = collectHeadingsData(contentsElement);
+  const linksData = collectLinksData(linkTemplate) || [];
+
+  if (!headingsData.length || !linksData.length) return;
+
+  const tocWrapper = prepareTOC(linksData, instance);
+  if (!tocWrapper) return;
+
+  const tocItems = populateLinks(headingsData, linksData, tocWrapper);
+
+  // Scroll offset
+  const scrollMarginTop = getAttribute(contentsElement, 'offsettop');
+  const scrollMarginBottom = getAttribute(contentsElement, 'offsetbottom');
+
+  setScrollOffsets(tocItems, { scrollMarginTop, scrollMarginBottom });
+
+  // Handle TOC link clicks
+  const hideURLHash = hasAttributeValue(contentsElement, 'hideurlhash', 'true');
+  const removeListener = listenTOCLinkClicks(tocWrapper, hideURLHash);
+
+  // Link States
+  const observer = observeLinksState(tocWrapper, tocItems);
+
+  return () => {
+    removeListener();
+    observer.disconnect();
+  };
+};

package/attributes-master/packages/toc/src/index.ts

@@ -0,0 +1,3 @@
+export { version } from '../package.json';
+export { init } from './init';
+export { ELEMENTS, SETTINGS } from './utils/constants';

package/attributes-master/packages/toc/src/init.ts

@@ -0,0 +1,37 @@
+import {
+  type FinsweetAttributeInit,
+  isNotEmpty,
+  restartWebflow,
+  waitAttributeLoaded,
+  waitWebflowReady,
+} from '@finsweet/attributes-utils';
+
+import { scrollToAnchor } from './actions/scroll';
+import { initTOCInstance } from './factory';
+import { queryAllElements } from './utils/selectors';
+
+/**
+ * Inits the attribute.
+ */
+export const init: FinsweetAttributeInit = async () => {
+  await waitWebflowReady();
+  await waitAttributeLoaded('inject');
+
+  const contentsElements = queryAllElements('contents');
+
+  const cleanups = contentsElements.map(initTOCInstance).filter(isNotEmpty);
+
+  // URL hash Anchor
+  scrollToAnchor();
+
+  if (cleanups.length) {
+    await restartWebflow();
+  }
+
+  // TODO: Finish API
+  return {
+    destroy() {
+      for (const cleanup of cleanups) cleanup();
+    },
+  };
+};

package/attributes-master/packages/toc/src/utils/constants.ts

@@ -0,0 +1,55 @@
+import { type AttributeElements, type AttributeSettings, TOC_ATTRIBUTE } from '@finsweet/attributes-utils';
+
+export const ELEMENTS = [
+  /**
+   * Defines the contents to use as the table source.
+   */
+  'contents',
+
+  /**
+   * OPTIONAL. Defines the wrapper element that will hold all the TOC links.
+   * If not defined, the library will use the immediate parent of the link template elements.
+   */
+  'table',
+
+  /**
+   * Defines a link template element.
+   * If the attribute is set to a non-link element, the library will look up for the first parent element that is a link.
+   */
+  'link',
+
+  /**
+   * Defines an interaction trigger.
+   * This attribute must be added to a hidden div and place it inside the correspondent link wrapper.
+   * When the link is active, it will trigger the "First Click" interaction. When the link is unactive, it will trigger the "Second Click" interaction.
+   */
+  'ix-trigger',
+] as const satisfies AttributeElements;
+
+export const SETTINGS = {
+  /**
+   * Defines a [scroll-margin-top](https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-margin-top) value for the headers.
+   */
+  offsettop: { key: 'offsettop' },
+
+  /**
+   * Defines a [scroll-margin-bottom](https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-margin-bottom) value for the headers.
+   */
+  offsetbottom: { key: 'offsetbottom' },
+
+  /**
+   * Defines if the links hash should be removed from the URL.
+   */
+  hideurlhash: { key: 'hideurlhash', values: ['true'] },
+} as const satisfies AttributeSettings;
+
+export const DEFAULT_INITIAL_HEADING_LEVEL = 2;
+export const ANCHOR_SELECTOR = `fs-${TOC_ATTRIBUTE}-anchor`;
+
+const ALLOWED_HEADINGS_REGEX = '[2-6]';
+export const ALLOWED_HEADINGS_SELECTOR = 'h2, h3, h4, h5, h6';
+
+export const OMIT_HEADING_REGEXP = new RegExp(`^\\[fs-${TOC_ATTRIBUTE}-omit\\]`, 'i');
+export const CUSTOM_HEADING_REGEXP = new RegExp(`^\\[fs-${TOC_ATTRIBUTE}-h${ALLOWED_HEADINGS_REGEX}\\]`, 'i');
+export const HEADING_LEVEL_REGEXP = new RegExp(ALLOWED_HEADINGS_REGEX);
+export const ZERO_WIDTH_CHARS_REGEXP = /[\u200B-\u200D\uFEFF]/g;

package/attributes-master/packages/toc/src/utils/helpers.ts

@@ -0,0 +1,23 @@
+import { HEADING_LEVEL_REGEXP } from './constants';
+
+/**
+ * Extracts the heading level from a heading tag.
+ * @param value The heading tag.
+ *
+ * @example ```
+ * extractHeadingLevel('h2') // 2
+ * extractHeadingLevel('h5') // 5
+ * extractHeadingLevel('5') // 5
+ * extractHeadingLevel('hh') // undefined
+ * ```
+ *
+ */
+export const extractHeadingLevel = (value: string) => {
+  const rawLevel = value.match(HEADING_LEVEL_REGEXP)?.[0];
+  if (!rawLevel) return;
+
+  const level = parseInt(rawLevel);
+  if (isNaN(level)) return;
+
+  return level;
+};

package/attributes-master/packages/toc/src/utils/selectors.ts

@@ -0,0 +1,6 @@
+import { generateSelectors, TOC_ATTRIBUTE } from '@finsweet/attributes-utils';
+
+import { ELEMENTS, SETTINGS } from './constants';
+
+export const { getElementSelector, queryElement, getInstance, getAttribute, hasAttributeValue, queryAllElements } =
+  generateSelectors(TOC_ATTRIBUTE, ELEMENTS, SETTINGS);

package/attributes-master/packages/toc/src/utils/types.ts

@@ -0,0 +1,21 @@
+export interface HeadingData {
+  level: number;
+  headingElement?: HTMLHeadingElement;
+  id?: string;
+  headingWrapper?: HTMLDivElement;
+}
+
+export interface LinkData {
+  level: number;
+  linkElement: HTMLAnchorElement;
+  component: HTMLElement;
+}
+
+export interface TOCData extends HeadingData, LinkData {
+  referenceNode: Element;
+  linkWrapper: HTMLElement;
+  ixTrigger: HTMLElement | null;
+  anchor: Node;
+}
+
+export type ScrollOffsetStyles = Partial<Pick<HTMLElement['style'], 'scrollMarginTop' | 'scrollMarginBottom'>>;

package/attributes-master/packages/toc/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../tsconfig.json"
+}