@lmfaole/basics 0.1.0

package/README.md

@@ -0,0 +1,114 @@
+# `@lmfaole/basics`
+
+Simple unstyled custom elements and DOM helpers.
+
+## Install
+
+```sh
+pnpm add @lmfaole/basics
+```
+
+## Storybook
+
+```sh
+pnpm storybook
+```
+
+```sh
+pnpm build-storybook
+```
+
+```sh
+pnpm test:storybook
+```
+
+```sh
+pnpm test:storybook:coverage
+```
+
+Autodocs is enabled globally for the package stories, and the Docs page includes Storybook's built-in Code panel for rendered examples.
+Storybook Test coverage is enabled through the Vitest addon. In the Storybook UI, turn coverage on in the testing panel to see the summary and open the full report at `/coverage/index.html`. From the CLI, `test:storybook:coverage` writes reports to `coverage/storybook/`.
+
+The Visual Tests panel is provided by `@chromatic-com/storybook`. To run cloud visual checks, connect the addon to a Chromatic project from the Storybook UI.
+
+## Basic Tabs
+
+```html
+<basic-tabs data-label="Eksempelkode">
+  <div data-tabs-list>
+    <button type="button" data-tab>Oversikt</button>
+    <button type="button" data-tab>Implementasjon</button>
+    <button type="button" data-tab>Tilgjengelighet</button>
+  </div>
+
+  <section data-tab-panel>
+    <p>Viser en kort oppsummering.</p>
+  </section>
+  <section data-tab-panel>
+    <p>Viser implementasjonsdetaljer.</p>
+  </section>
+  <section data-tab-panel>
+    <p>Viser tilgjengelighetsnotater.</p>
+  </section>
+</basic-tabs>
+
+<script type="module">
+  import "@lmfaole/basics/components/basic-tabs/register";
+</script>
+```
+
+The element upgrades existing markup into an accessible tab interface without adding any styles of its own.
+
+### Attributes
+
+- `data-label`: sets the generated tablist's accessible name when the tablist does not already have `aria-label` or `aria-labelledby`. Defaults to `Faner`.
+- `data-orientation`: sets arrow-key behavior and mirrors `aria-orientation` on the tablist. Supported values are `horizontal` and `vertical`.
+- `data-activation`: chooses whether arrow-key focus changes also activate the panel. Supported values are `automatic` and `manual`.
+- `data-selected-index`: sets the initially selected tab by zero-based index. Defaults to the first enabled tab.
+
+### Behavior
+
+- Missing tab and panel ids are generated automatically.
+- `aria-selected`, `aria-controls`, `aria-labelledby`, `hidden`, and `data-selected` stay in sync with the active tab.
+- Click, `Home`, `End`, and orientation-aware arrow keys move between tabs.
+- Disabled tabs are skipped during keyboard navigation.
+- In `manual` mode, arrow keys move focus and `Enter` or `Space` activates the focused tab.
+
+### Markup Contract
+
+- Provide one descendant element with `data-tabs-list` to hold the interactive tab controls.
+- Provide matching counts of `[data-tab]` and `[data-tab-panel]` descendants in the same order.
+- Prefer `<button>` elements for tabs so click and keyboard activation stay native.
+- Keep layout and styling outside the package; the component only manages semantics, state, and keyboard behavior.
+
+## Basic Toc
+
+```html
+<basic-toc data-title="Innhold">
+  <nav aria-label="Innhold" data-page-toc-nav></nav>
+</basic-toc>
+
+<script type="module">
+  import "@lmfaole/basics/components/basic-toc/register";
+</script>
+```
+
+The element reads headings from the nearest `<main>` and updates automatically when that content changes.
+
+### Attributes
+
+- `data-title`: sets the generated nav's accessible label. Defaults to `Innhold`.
+- `data-heading-selector`: limits which headings are indexed. Defaults to `h1, h2, h3, h4, h5, h6`.
+
+### Behavior
+
+- Missing heading ids are generated automatically.
+- Duplicate headings receive unique fragment ids.
+- Hidden headings are ignored.
+- The outline is rebuilt when matching headings are added or changed.
+
+### Markup Contract
+
+- Render the element inside the same `<main>` that contains the content it should index.
+- Provide a descendant element with `data-page-toc-nav` for the generated links.
+- Keep layout and styling outside the package; the component only manages structure and link generation.

package/components/basic-tabs/index.d.ts

@@ -0,0 +1,64 @@
+export interface TabsTabState {
+    disabled: boolean;
+    selected?: boolean;
+}
+
+export type TabsActivation = "automatic" | "manual";
+export type TabsOrientation = "horizontal" | "vertical";
+
+/**
+ * Public tag name registered by `defineTabs`.
+ */
+export const TABS_TAG_NAME: "basic-tabs";
+
+/**
+ * Normalizes unsupported orientation values back to `"horizontal"`.
+ */
+export function normalizeTabsOrientation(
+    value?: string | null,
+): TabsOrientation;
+
+/**
+ * Normalizes unsupported activation values back to `"automatic"`.
+ */
+export function normalizeTabsActivation(
+    value?: string | null,
+): TabsActivation;
+
+/**
+ * Returns the initially active tab index, preferring an explicitly selected,
+ * enabled tab and otherwise falling back to the first enabled one.
+ */
+export function getInitialSelectedTabIndex(
+    tabStates: TabsTabState[],
+): number;
+
+/**
+ * Returns the next enabled tab index, wrapping around the list when needed.
+ */
+export function findNextEnabledTabIndex(
+    tabStates: TabsTabState[],
+    startIndex: number,
+    direction: number,
+): number;
+
+/**
+ * Custom element that upgrades existing button-and-panel markup into
+ * an accessible tabs interface.
+ *
+ * Attributes:
+ * - `data-label`: fallback accessible name when the tablist has no own label
+ * - `data-orientation`: sets the keyboard orientation and `aria-orientation`
+ * - `data-activation`: `automatic` or `manual`
+ * - `data-selected-index`: zero-based initially selected tab index
+ */
+export class TabsElement extends HTMLElement {
+    static observedAttributes: string[];
+}
+
+/**
+ * Registers the `basic-tabs` custom element if it is not already defined.
+ */
+export function defineTabs(
+    registry?: CustomElementRegistry,
+): typeof TabsElement;

package/components/basic-tabs/index.js

@@ -0,0 +1,386 @@
+const ElementBase = globalThis.Element ?? class {};
+const HTMLElementBase = globalThis.HTMLElement ?? class {};
+const HTMLButtonElementBase = globalThis.HTMLButtonElement ?? class {};
+
+export const TABS_TAG_NAME = "basic-tabs";
+
+const DEFAULT_LABEL = "Faner";
+const DEFAULT_ACTIVATION = "automatic";
+const DEFAULT_ORIENTATION = "horizontal";
+const MANUAL_ACTIVATION = "manual";
+const VERTICAL_ORIENTATION = "vertical";
+const TABLIST_SELECTOR = "[data-tabs-list]";
+const TAB_SELECTOR = "[data-tab]";
+const PANEL_SELECTOR = "[data-tab-panel]";
+
+let nextTabsInstanceId = 1;
+
+export function normalizeTabsOrientation(value) {
+    return value?.trim().toLowerCase() === VERTICAL_ORIENTATION
+        ? VERTICAL_ORIENTATION
+        : DEFAULT_ORIENTATION;
+}
+
+export function normalizeTabsActivation(value) {
+    return value?.trim().toLowerCase() === MANUAL_ACTIVATION
+        ? MANUAL_ACTIVATION
+        : DEFAULT_ACTIVATION;
+}
+
+export function getInitialSelectedTabIndex(tabStates) {
+    for (let index = 0; index < tabStates.length; index += 1) {
+        const tabState = tabStates[index];
+
+        if (tabState?.selected && !tabState.disabled) {
+            return index;
+        }
+    }
+
+    for (let index = 0; index < tabStates.length; index += 1) {
+        if (!tabStates[index]?.disabled) {
+            return index;
+        }
+    }
+
+    return -1;
+}
+
+export function findNextEnabledTabIndex(tabStates, startIndex, direction) {
+    if (tabStates.length === 0) {
+        return -1;
+    }
+
+    const step = direction < 0 ? -1 : 1;
+    let nextIndex = startIndex;
+
+    for (let checked = 0; checked < tabStates.length; checked += 1) {
+        nextIndex += step;
+
+        if (nextIndex < 0) {
+            nextIndex = tabStates.length - 1;
+        } else if (nextIndex >= tabStates.length) {
+            nextIndex = 0;
+        }
+
+        if (!tabStates[nextIndex]?.disabled) {
+            return nextIndex;
+        }
+    }
+
+    return -1;
+}
+
+function collectOwnedElements(root, scope, selector) {
+    return Array.from(scope.querySelectorAll(selector)).filter(
+        (element) => element instanceof HTMLElementBase && element.closest(TABS_TAG_NAME) === root,
+    );
+}
+
+function isTabDisabled(tab) {
+    return tab.hasAttribute("disabled") || tab.getAttribute("aria-disabled") === "true";
+}
+
+function findLastEnabledTabIndex(tabStates) {
+    for (let index = tabStates.length - 1; index >= 0; index -= 1) {
+        if (!tabStates[index]?.disabled) {
+            return index;
+        }
+    }
+
+    return -1;
+}
+
+export class TabsElement extends HTMLElementBase {
+    static observedAttributes = [
+        "data-activation",
+        "data-label",
+        "data-orientation",
+        "data-selected-index",
+    ];
+
+    #instanceId = `${TABS_TAG_NAME}-${nextTabsInstanceId++}`;
+    #tabList = null;
+    #tabs = [];
+    #panels = [];
+    #selectedIndex = -1;
+    #focusIndex = -1;
+    #eventsBound = false;
+
+    connectedCallback() {
+        if (!this.#eventsBound) {
+            this.addEventListener("click", this.#handleClick);
+            this.addEventListener("keydown", this.#handleKeyDown);
+            this.#eventsBound = true;
+        }
+
+        this.#sync({ resetSelection: true });
+    }
+
+    disconnectedCallback() {
+        if (!this.#eventsBound) {
+            return;
+        }
+
+        this.removeEventListener("click", this.#handleClick);
+        this.removeEventListener("keydown", this.#handleKeyDown);
+        this.#eventsBound = false;
+    }
+
+    attributeChangedCallback(name) {
+        this.#sync({ resetSelection: name === "data-selected-index" });
+    }
+
+    #handleClick = (event) => {
+        if (!(event.target instanceof ElementBase)) {
+            return;
+        }
+
+        const tab = event.target.closest(TAB_SELECTOR);
+
+        if (!(tab instanceof HTMLElementBase) || tab.closest(TABS_TAG_NAME) !== this) {
+            return;
+        }
+
+        const tabIndex = this.#tabs.indexOf(tab);
+
+        if (tabIndex === -1) {
+            return;
+        }
+
+        this.#selectTab(tabIndex, { focus: true });
+    };
+
+    #handleKeyDown = (event) => {
+        if (!(event.target instanceof ElementBase)) {
+            return;
+        }
+
+        const currentTab = event.target.closest(TAB_SELECTOR);
+
+        if (!(currentTab instanceof HTMLElementBase) || currentTab.closest(TABS_TAG_NAME) !== this) {
+            return;
+        }
+
+        const tabStates = this.#getTabStates();
+        const currentIndex = this.#tabs.indexOf(currentTab);
+        const activation = this.#getActivation();
+        const orientation = this.#getOrientation();
+        let nextIndex = -1;
+
+        if (currentIndex === -1 || currentIndex >= tabStates.length) {
+            return;
+        }
+
+        switch (event.key) {
+            case "ArrowRight":
+                if (orientation === DEFAULT_ORIENTATION) {
+                    nextIndex = findNextEnabledTabIndex(tabStates, currentIndex, 1);
+                }
+                break;
+            case "ArrowLeft":
+                if (orientation === DEFAULT_ORIENTATION) {
+                    nextIndex = findNextEnabledTabIndex(tabStates, currentIndex, -1);
+                }
+                break;
+            case "ArrowDown":
+                if (orientation === VERTICAL_ORIENTATION) {
+                    nextIndex = findNextEnabledTabIndex(tabStates, currentIndex, 1);
+                }
+                break;
+            case "ArrowUp":
+                if (orientation === VERTICAL_ORIENTATION) {
+                    nextIndex = findNextEnabledTabIndex(tabStates, currentIndex, -1);
+                }
+                break;
+            case "Home":
+                nextIndex = getInitialSelectedTabIndex(tabStates);
+                break;
+            case "End":
+                nextIndex = findLastEnabledTabIndex(tabStates);
+                break;
+            case " ":
+            case "Enter":
+                event.preventDefault();
+                this.#selectTab(this.#focusIndex === -1 ? currentIndex : this.#focusIndex, { focus: true });
+                return;
+            default:
+                return;
+        }
+
+        if (nextIndex === -1) {
+            return;
+        }
+
+        event.preventDefault();
+
+        if (activation === MANUAL_ACTIVATION) {
+            this.#focusIndex = nextIndex;
+            this.#applyState({ focus: true });
+            return;
+        }
+
+        this.#selectTab(nextIndex, { focus: true });
+    };
+
+    #getActivation() {
+        return normalizeTabsActivation(this.getAttribute("data-activation"));
+    }
+
+    #getConfiguredSelectedIndex(tabStates) {
+        const selectedIndex = Number.parseInt(
+            this.getAttribute("data-selected-index") ?? "",
+            10,
+        );
+
+        if (
+            Number.isInteger(selectedIndex)
+            && selectedIndex >= 0
+            && selectedIndex < tabStates.length
+            && !tabStates[selectedIndex]?.disabled
+        ) {
+            return selectedIndex;
+        }
+
+        return getInitialSelectedTabIndex(tabStates);
+    }
+
+    #getLabel() {
+        return this.getAttribute("data-label")?.trim() || DEFAULT_LABEL;
+    }
+
+    #getOrientation() {
+        return normalizeTabsOrientation(
+            this.getAttribute("data-orientation") ?? this.#tabList?.getAttribute("aria-orientation"),
+        );
+    }
+
+    #getTabStates(configuredSelectedIndex = null) {
+        const pairCount = Math.min(this.#tabs.length, this.#panels.length);
+
+        return this.#tabs.slice(0, pairCount).map((tab, index) => ({
+            disabled: isTabDisabled(tab),
+            selected: index === configuredSelectedIndex
+                || tab.hasAttribute("data-selected")
+                || tab.getAttribute("aria-selected") === "true",
+        }));
+    }
+
+    #sync({ resetSelection = false } = {}) {
+        this.#tabList = collectOwnedElements(this, this, TABLIST_SELECTOR)[0] ?? null;
+        this.#tabs = this.#tabList
+            ? collectOwnedElements(this, this.#tabList, TAB_SELECTOR)
+            : [];
+        this.#panels = collectOwnedElements(this, this, PANEL_SELECTOR).filter(
+            (panel) => !this.#tabList?.contains(panel),
+        );
+
+        const tabStates = this.#getTabStates();
+
+        if (resetSelection || this.#selectedIndex === -1 || tabStates[this.#selectedIndex]?.disabled) {
+            this.#selectedIndex = this.#getConfiguredSelectedIndex(tabStates);
+        }
+
+        if (resetSelection || this.#focusIndex === -1 || tabStates[this.#focusIndex]?.disabled) {
+            this.#focusIndex = this.#selectedIndex;
+        }
+
+        this.#applyState();
+    }
+
+    #applyState({ focus = false } = {}) {
+        if (!(this.#tabList instanceof HTMLElementBase)) {
+            return;
+        }
+
+        const orientation = this.#getOrientation();
+        const pairCount = Math.min(this.#tabs.length, this.#panels.length);
+        const baseId = this.id || this.#instanceId;
+
+        if (!this.#tabList.hasAttribute("aria-label") && !this.#tabList.hasAttribute("aria-labelledby")) {
+            this.#tabList.setAttribute("aria-label", this.#getLabel());
+        }
+
+        this.#tabList.setAttribute("role", "tablist");
+        this.#tabList.setAttribute("aria-orientation", orientation);
+
+        for (let index = 0; index < this.#tabs.length; index += 1) {
+            const tab = this.#tabs[index];
+            const panel = index < pairCount ? this.#panels[index] : null;
+            const disabled = index >= pairCount || isTabDisabled(tab);
+            const selected = index === this.#selectedIndex && !disabled;
+            const focusable = index === this.#focusIndex && !disabled;
+
+            if (!tab.id) {
+                tab.id = `${baseId}-tab-${index + 1}`;
+            }
+
+            if (tab instanceof HTMLButtonElementBase && !tab.hasAttribute("type")) {
+                tab.type = "button";
+            }
+
+            tab.setAttribute("role", "tab");
+            tab.setAttribute("aria-selected", String(selected));
+            tab.tabIndex = focusable ? 0 : -1;
+            tab.toggleAttribute("data-selected", selected);
+
+            if (panel) {
+                if (!panel.id) {
+                    panel.id = `${baseId}-panel-${index + 1}`;
+                }
+
+                tab.setAttribute("aria-controls", panel.id);
+            } else {
+                tab.removeAttribute("aria-controls");
+            }
+        }
+
+        for (let index = 0; index < this.#panels.length; index += 1) {
+            const panel = this.#panels[index];
+            const tab = this.#tabs[index];
+            const selected = index === this.#selectedIndex && index < pairCount;
+
+            if (!panel.id) {
+                panel.id = `${baseId}-panel-${index + 1}`;
+            }
+
+            panel.setAttribute("role", "tabpanel");
+
+            if (tab?.id) {
+                panel.setAttribute("aria-labelledby", tab.id);
+            } else {
+                panel.removeAttribute("aria-labelledby");
+            }
+
+            panel.hidden = !selected;
+            panel.toggleAttribute("data-selected", selected);
+        }
+
+        if (focus && this.#focusIndex !== -1) {
+            this.#tabs[this.#focusIndex]?.focus();
+        }
+    }
+
+    #selectTab(index, { focus = false } = {}) {
+        const tabStates = this.#getTabStates();
+
+        if (index < 0 || index >= tabStates.length || tabStates[index]?.disabled) {
+            return;
+        }
+
+        this.#selectedIndex = index;
+        this.#focusIndex = index;
+        this.#applyState({ focus });
+    }
+}
+
+export function defineTabs(registry = globalThis.customElements) {
+    if (!registry?.get || !registry?.define) {
+        return TabsElement;
+    }
+
+    if (!registry.get(TABS_TAG_NAME)) {
+        registry.define(TABS_TAG_NAME, TabsElement);
+    }
+
+    return TabsElement;
+}

package/components/basic-tabs/register.d.ts

@@ -0,0 +1 @@
+export {};

package/components/basic-tabs/register.js

@@ -0,0 +1,3 @@
+import { defineTabs } from "./index.js";
+
+defineTabs();

package/components/basic-toc/index.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Normalized heading data collected from the nearest `<main>`.
+ */
+export interface TableOfContentsHeading {
+    id: string;
+    text: string;
+    level: number;
+}
+
+/**
+ * Nested outline item returned by `buildTableOfContentsTree`.
+ */
+export interface TableOfContentsItem extends TableOfContentsHeading {
+    children: TableOfContentsItem[];
+}
+
+/**
+ * Public tag name registered by `defineTableOfContents`.
+ */
+export const TABLE_OF_CONTENTS_TAG_NAME: "basic-toc";
+
+/**
+ * Collapses repeated whitespace and trims the result.
+ */
+export function normalizeHeadingText(text: string): string;
+/**
+ * Converts heading text into a stable fragment id.
+ */
+export function slugifyHeading(text: string): string;
+/**
+ * Returns a unique heading id and stores it in the provided set.
+ */
+export function createUniqueHeadingId(baseText: string, usedIds: Set<string>): string;
+/**
+ * Converts a flat heading list into a nested outline tree.
+ */
+export function buildTableOfContentsTree(
+    headings: TableOfContentsHeading[],
+): TableOfContentsItem[];
+
+/**
+ * Custom element that renders a heading outline into a descendant
+ * `[data-page-toc-nav]` container.
+ *
+ * Attributes:
+ * - `data-title`: aria-label for the generated nav. Defaults to `"Innhold"`.
+ * - `data-heading-selector`: CSS selector used to collect headings from the nearest `<main>`.
+ */
+export class TableOfContentsElement extends HTMLElement {
+    static observedAttributes: string[];
+}
+
+/**
+ * Registers the `basic-toc` custom element if it is not already defined.
+ */
+export function defineTableOfContents(
+    registry?: CustomElementRegistry,
+): typeof TableOfContentsElement;

package/components/basic-toc/index.js

@@ -0,0 +1,257 @@
+const HTMLElementBase = globalThis.HTMLElement ?? class {};
+
+export const TABLE_OF_CONTENTS_TAG_NAME = "basic-toc";
+
+const DEFAULT_TITLE = "Innhold";
+const DEFAULT_HEADING_SELECTOR = "h1, h2, h3, h4, h5, h6";
+
+export function normalizeHeadingText(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+
+export function slugifyHeading(text) {
+    const normalized = normalizeHeadingText(text)
+        .toLocaleLowerCase("nb")
+        .replace(/['’"]/g, "")
+        .replace(/[^\p{Letter}\p{Number}\s-]/gu, "")
+        .replace(/\s+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+
+    return normalized || "overskrift";
+}
+
+export function createUniqueHeadingId(baseText, usedIds) {
+    const baseId = slugifyHeading(baseText);
+    let nextId = baseId;
+    let suffix = 2;
+
+    while (usedIds.has(nextId)) {
+        nextId = `${baseId}-${suffix}`;
+        suffix += 1;
+    }
+
+    usedIds.add(nextId);
+    return nextId;
+}
+
+export function buildTableOfContentsTree(headings) {
+    const root = [];
+    const stack = [];
+
+    for (const heading of headings) {
+        const item = {
+            ...heading,
+            children: [],
+        };
+
+        while (stack.length > 0 && stack[stack.length - 1].level >= item.level) {
+            stack.pop();
+        }
+
+        const parent = stack[stack.length - 1];
+
+        if (parent) {
+            parent.children.push(item);
+        } else {
+            root.push(item);
+        }
+
+        stack.push(item);
+    }
+
+    return root;
+}
+
+function renderTableOfContentsItems(items) {
+    const list = document.createElement("ol");
+
+    for (const item of items) {
+        const listItem = document.createElement("li");
+        const link = document.createElement("a");
+        link.href = `#${item.id}`;
+        link.textContent = item.text;
+        listItem.append(link);
+
+        if (item.children.length > 0) {
+            listItem.append(renderTableOfContentsItems(item.children));
+        }
+
+        list.append(listItem);
+    }
+
+    return list;
+}
+
+function collectTableOfContentsHeadings(main, tocRoot, headingSelector) {
+    const usedIds = new Set();
+    const headings = [];
+
+    for (const heading of main.querySelectorAll(headingSelector)) {
+        if (!(heading instanceof HTMLHeadingElement)) {
+            continue;
+        }
+
+        if (tocRoot.contains(heading) || heading.closest("[hidden], [aria-hidden='true']")) {
+            continue;
+        }
+
+        const text = normalizeHeadingText(heading.textContent ?? "");
+
+        if (!text) {
+            continue;
+        }
+
+        const existingId = normalizeHeadingText(heading.id);
+
+        if (existingId && !usedIds.has(existingId)) {
+            usedIds.add(existingId);
+        } else if (existingId) {
+            heading.id = createUniqueHeadingId(existingId, usedIds);
+        } else {
+            heading.id = createUniqueHeadingId(text, usedIds);
+        }
+
+        headings.push({
+            id: heading.id,
+            text,
+            level: Number(heading.tagName.slice(1)),
+        });
+    }
+
+    return headings;
+}
+
+export class TableOfContentsElement extends HTMLElementBase {
+    static observedAttributes = ["data-title", "data-heading-selector"];
+
+    #observer = null;
+    #observedMain = null;
+    #scheduledFrame = 0;
+
+    connectedCallback() {
+        this.#ensureShell();
+        this.#syncObserver();
+    }
+
+    disconnectedCallback() {
+        this.#teardownObserver();
+    }
+
+    attributeChangedCallback() {
+        this.#ensureShell();
+        this.#scheduleUpdate();
+    }
+
+    #getTitle() {
+        return this.getAttribute("data-title")?.trim() || DEFAULT_TITLE;
+    }
+
+    #getHeadingSelector() {
+        return this.getAttribute("data-heading-selector")?.trim() || DEFAULT_HEADING_SELECTOR;
+    }
+
+    #getNav() {
+        const nav = this.querySelector("[data-page-toc-nav]");
+        return nav instanceof HTMLElement ? nav : null;
+    }
+
+    #ensureShell() {
+        if (typeof document === "undefined") {
+            return;
+        }
+
+        let nav = this.#getNav();
+
+        if (!(nav instanceof HTMLElement)) {
+            nav = document.createElement("nav");
+            nav.dataset.pageTocNav = "";
+            this.replaceChildren(nav);
+        }
+
+        nav.setAttribute("aria-label", this.#getTitle());
+    }
+
+    #scheduleUpdate() {
+        if (this.#scheduledFrame !== 0 || typeof window === "undefined") {
+            return;
+        }
+
+        this.#scheduledFrame = window.requestAnimationFrame(() => {
+            this.#scheduledFrame = 0;
+            this.#update();
+        });
+    }
+
+    #syncObserver() {
+        const main = this.closest("main");
+
+        if (!(main instanceof HTMLElement)) {
+            return;
+        }
+
+        if (main !== this.#observedMain) {
+            this.#teardownObserver();
+            this.#observedMain = main;
+            this.#observer = new MutationObserver(() => {
+                this.#scheduleUpdate();
+            });
+            this.#observer.observe(main, {
+                childList: true,
+                subtree: true,
+                characterData: true,
+            });
+        }
+
+        this.#update();
+    }
+
+    #teardownObserver() {
+        this.#observer?.disconnect();
+        this.#observer = null;
+        this.#observedMain = null;
+
+        if (this.#scheduledFrame !== 0 && typeof window !== "undefined") {
+            window.cancelAnimationFrame(this.#scheduledFrame);
+            this.#scheduledFrame = 0;
+        }
+    }
+
+    #update() {
+        const nav = this.#getNav();
+        const main = this.closest("main");
+
+        if (!(nav instanceof HTMLElement) || !(main instanceof HTMLElement)) {
+            return;
+        }
+
+        const headings = collectTableOfContentsHeadings(
+            main,
+            this,
+            this.#getHeadingSelector(),
+        );
+        const nextMarkup = headings.length > 0
+            ? renderTableOfContentsItems(buildTableOfContentsTree(headings)).outerHTML
+            : "";
+
+        if (nav.innerHTML !== nextMarkup) {
+            nav.innerHTML = nextMarkup;
+        }
+
+        this.hidden = headings.length === 0;
+    }
+}
+
+export function defineTableOfContents(
+    registry = globalThis.customElements,
+) {
+    if (!registry?.get || !registry?.define) {
+        return TableOfContentsElement;
+    }
+
+    if (!registry.get(TABLE_OF_CONTENTS_TAG_NAME)) {
+        registry.define(TABLE_OF_CONTENTS_TAG_NAME, TableOfContentsElement);
+    }
+
+    return TableOfContentsElement;
+}

package/components/basic-toc/register.d.ts

@@ -0,0 +1 @@
+export {};

package/components/basic-toc/register.js

@@ -0,0 +1,3 @@
+import { defineTableOfContents } from "./index.js";
+
+defineTableOfContents();

package/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./components/basic-toc";
+export * from "./components/basic-tabs";

package/index.js

@@ -0,0 +1,2 @@
+export * from "./components/basic-toc/index.js";
+export * from "./components/basic-tabs/index.js";

package/package.json

@@ -0,0 +1,88 @@
+{
+    "name": "@lmfaole/basics",
+    "version": "0.1.0",
+    "description": "Simple unstyled custom elements and DOM helpers.",
+    "type": "module",
+    "sideEffects": [
+        "./components/basic-toc/register.js",
+        "./components/basic-tabs/register.js"
+    ],
+    "exports": {
+        ".": {
+            "types": "./index.d.ts",
+            "import": "./index.js"
+        },
+        "./components/basic-toc": {
+            "types": "./components/basic-toc/index.d.ts",
+            "import": "./components/basic-toc/index.js"
+        },
+        "./components/basic-toc/register": {
+            "types": "./components/basic-toc/register.d.ts",
+            "import": "./components/basic-toc/register.js"
+        },
+        "./components/basic-tabs": {
+            "types": "./components/basic-tabs/index.d.ts",
+            "import": "./components/basic-tabs/index.js"
+        },
+        "./components/basic-tabs/register": {
+            "types": "./components/basic-tabs/register.d.ts",
+            "import": "./components/basic-tabs/register.js"
+        }
+    },
+    "files": [
+        "README.md",
+        "index.js",
+        "index.d.ts",
+        "components/*/index.js",
+        "components/*/index.d.ts",
+        "components/*/register.js",
+        "components/*/register.d.ts"
+    ],
+    "keywords": [
+        "custom-element",
+        "basic-tabs",
+        "basic-toc",
+        "table-of-contents",
+        "tabs",
+        "tablist",
+        "toc",
+        "unstyled",
+        "vanilla-js",
+        "web-components"
+    ],
+    "license": "ISC",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/lmfaole/basics.git"
+    },
+    "bugs": {
+        "url": "https://github.com/lmfaole/basics/issues"
+    },
+    "homepage": "https://github.com/lmfaole/basics",
+    "scripts": {
+        "storybook": "storybook dev -p 6006 --no-open",
+        "build-storybook": "storybook build",
+        "test": "pnpm run test:unit && pnpm run test:storybook",
+        "test:unit": "vitest run --config vitest.config.ts",
+        "test:storybook": "vitest run --config vitest.storybook.config.ts",
+        "test:storybook:watch": "vitest --config vitest.storybook.config.ts",
+        "test:storybook:coverage": "vitest run --config vitest.storybook.config.ts --coverage"
+    },
+    "devDependencies": {
+        "@chromatic-com/storybook": "^5.0.2",
+        "@storybook/addon-a11y": "^10.3.1",
+        "@storybook/addon-docs": "10.3.1",
+        "@storybook/addon-vitest": "10.3.1",
+        "@storybook/web-components-vite": "^10.3.1",
+        "@vitest/browser-playwright": "4.1.0",
+        "@vitest/coverage-v8": "4.1.0",
+        "playwright": "^1.58.2",
+        "storybook": "^10.3.1",
+        "vitest": "^4.1.0"
+    },
+    "publishConfig": {
+        "access": "public",
+        "registry": "https://registry.npmjs.org/"
+    },
+    "packageManager": "pnpm@10.30.3"
+}

package/readme.mdx

@@ -0,0 +1,6 @@
+import { Markdown, Meta } from "@storybook/addon-docs/blocks";
+import Readme from "./README.md?raw";
+
+<Meta title="Readme" />
+
+<Markdown>{Readme}</Markdown>