@lmfaole/basics 0.3.0 → 0.5.0

package/basic-components/basic-accordion/index.js

@@ -0,0 +1,413 @@
+const ElementBase = globalThis.Element ?? class {};
+const HTMLElementBase = globalThis.HTMLElement ?? class {};
+const HTMLDetailsElementBase = globalThis.HTMLDetailsElement ?? class {};
+
+export const ACCORDION_TAG_NAME = "basic-accordion";
+
+const SUMMARY_TAG_NAME = "SUMMARY";
+
+function findDirectAccordionSummary(details) {
+    return Array.from(details.children).find(
+        (child) => child instanceof HTMLElementBase && child.tagName === SUMMARY_TAG_NAME,
+    ) ?? null;
+}
+
+function collectOwnedAccordionItems(root) {
+    return Array.from(root.children).flatMap((child) => {
+        if (!(child instanceof HTMLDetailsElementBase)) {
+            return [];
+        }
+
+        const summary = findDirectAccordionSummary(child);
+
+        if (!(summary instanceof HTMLElementBase)) {
+            return [];
+        }
+
+        return [{ details: child, summary }];
+    });
+}
+
+function isAccordionItemDisabled(details) {
+    return details.hasAttribute("data-disabled")
+        || details.hasAttribute("disabled")
+        || details.getAttribute("aria-disabled") === "true";
+}
+
+function getOpenAccordionIndexes(itemStates) {
+    const openIndexes = [];
+
+    for (let index = 0; index < itemStates.length; index += 1) {
+        if (itemStates[index]?.open && !itemStates[index]?.disabled) {
+            openIndexes.push(index);
+        }
+    }
+
+    return openIndexes;
+}
+
+function findFirstEnabledAccordionIndex(itemStates) {
+    for (let index = 0; index < itemStates.length; index += 1) {
+        if (!itemStates[index]?.disabled) {
+            return index;
+        }
+    }
+
+    return -1;
+}
+
+function findLastEnabledAccordionIndex(itemStates) {
+    for (let index = itemStates.length - 1; index >= 0; index -= 1) {
+        if (!itemStates[index]?.disabled) {
+            return index;
+        }
+    }
+
+    return -1;
+}
+
+export function getInitialOpenAccordionIndexes(
+    itemStates,
+    { multiple = false, collapsible = false } = {},
+) {
+    const explicitOpenIndexes = [];
+
+    for (let index = 0; index < itemStates.length; index += 1) {
+        const itemState = itemStates[index];
+
+        if (itemState?.open && !itemState.disabled) {
+            explicitOpenIndexes.push(index);
+        }
+    }
+
+    if (multiple) {
+        return explicitOpenIndexes;
+    }
+
+    if (explicitOpenIndexes.length > 0) {
+        return [explicitOpenIndexes[0]];
+    }
+
+    if (collapsible) {
+        return [];
+    }
+
+    const firstEnabledIndex = findFirstEnabledAccordionIndex(itemStates);
+    return firstEnabledIndex === -1 ? [] : [firstEnabledIndex];
+}
+
+export function findNextEnabledAccordionIndex(itemStates, startIndex, direction) {
+    if (itemStates.length === 0) {
+        return -1;
+    }
+
+    const step = direction < 0 ? -1 : 1;
+    let nextIndex = startIndex;
+
+    for (let checked = 0; checked < itemStates.length; checked += 1) {
+        nextIndex += step;
+
+        if (nextIndex < 0) {
+            nextIndex = itemStates.length - 1;
+        } else if (nextIndex >= itemStates.length) {
+            nextIndex = 0;
+        }
+
+        if (!itemStates[nextIndex]?.disabled) {
+            return nextIndex;
+        }
+    }
+
+    return -1;
+}
+
+export class AccordionElement extends HTMLElementBase {
+    static observedAttributes = ["data-collapsible", "data-multiple"];
+
+    #items = [];
+    #eventsBound = false;
+    #isSyncingState = false;
+
+    connectedCallback() {
+        if (!this.#eventsBound) {
+            this.addEventListener("click", this.#handleClick);
+            this.addEventListener("keydown", this.#handleKeyDown);
+            this.#eventsBound = true;
+        }
+
+        this.#sync({ resetOpen: true });
+    }
+
+    disconnectedCallback() {
+        if (this.#eventsBound) {
+            this.removeEventListener("click", this.#handleClick);
+            this.removeEventListener("keydown", this.#handleKeyDown);
+            this.#eventsBound = false;
+        }
+
+        for (const { details } of this.#items) {
+            details.removeEventListener("toggle", this.#handleToggle);
+        }
+
+        this.#items = [];
+    }
+
+    attributeChangedCallback() {
+        this.#sync({ resetOpen: true });
+    }
+
+    #handleClick = (event) => {
+        if (!(event.target instanceof ElementBase)) {
+            return;
+        }
+
+        const summary = event.target.closest("summary");
+        const summaryIndex = this.#findSummaryIndex(summary);
+
+        if (summaryIndex === -1) {
+            return;
+        }
+
+        const itemStates = this.#getItemStates();
+
+        if (itemStates[summaryIndex]?.disabled) {
+            event.preventDefault();
+            return;
+        }
+
+        if (!this.#isMultiple()) {
+            event.preventDefault();
+            this.#toggleItem(summaryIndex, itemStates);
+        }
+    };
+
+    #handleKeyDown = (event) => {
+        if (!(event.target instanceof ElementBase)) {
+            return;
+        }
+
+        const currentSummary = event.target.closest("summary");
+        const currentIndex = this.#findSummaryIndex(currentSummary);
+        const itemStates = this.#getItemStates();
+        let nextIndex = -1;
+
+        if (currentIndex === -1 || currentIndex >= itemStates.length) {
+            return;
+        }
+
+        switch (event.key) {
+            case "ArrowDown":
+                nextIndex = findNextEnabledAccordionIndex(itemStates, currentIndex, 1);
+                break;
+            case "ArrowUp":
+                nextIndex = findNextEnabledAccordionIndex(itemStates, currentIndex, -1);
+                break;
+            case "Home":
+                nextIndex = findFirstEnabledAccordionIndex(itemStates);
+                break;
+            case "End":
+                nextIndex = findLastEnabledAccordionIndex(itemStates);
+                break;
+            case " ":
+            case "Enter":
+                event.preventDefault();
+                this.#toggleItem(currentIndex, itemStates);
+                return;
+            default:
+                return;
+        }
+
+        if (nextIndex === -1) {
+            return;
+        }
+
+        event.preventDefault();
+        this.#items[nextIndex]?.summary.focus();
+    };
+
+    #handleToggle = (event) => {
+        if (this.#isSyncingState) {
+            return;
+        }
+
+        const details = event.currentTarget;
+        const preferredIndex = this.#items.findIndex((item) => item.details === details);
+
+        if (preferredIndex === -1) {
+            return;
+        }
+
+        this.#sync({ preferredIndex });
+    };
+
+    #findSummaryIndex(summary) {
+        if (!(summary instanceof HTMLElementBase)) {
+            return -1;
+        }
+
+        return this.#items.findIndex((item) => item.summary === summary);
+    }
+
+    #isCollapsible() {
+        return this.hasAttribute("data-collapsible");
+    }
+
+    #isMultiple() {
+        return this.hasAttribute("data-multiple");
+    }
+
+    #getItemStates({ includeDataOpen = false } = {}) {
+        return this.#items.map(({ details }) => ({
+            disabled: isAccordionItemDisabled(details),
+            open: details.hasAttribute("open")
+                || (includeDataOpen && details.hasAttribute("data-open")),
+        }));
+    }
+
+    #sync({ resetOpen = false, preferredIndex = -1 } = {}) {
+        const previousDetails = this.#items.map((item) => item.details);
+        const nextItems = collectOwnedAccordionItems(this);
+        const nextDetails = nextItems.map((item) => item.details);
+
+        for (const details of previousDetails) {
+            if (!nextDetails.includes(details)) {
+                details.removeEventListener("toggle", this.#handleToggle);
+            }
+        }
+
+        for (const details of nextDetails) {
+            if (!previousDetails.includes(details)) {
+                details.addEventListener("toggle", this.#handleToggle);
+            }
+        }
+
+        this.#items = nextItems;
+        this.#normalizeOpenState({
+            itemStates: this.#getItemStates({ includeDataOpen: resetOpen }),
+            resetOpen,
+            preferredIndex,
+        });
+        this.#applyState();
+    }
+
+    #normalizeOpenState({ itemStates, resetOpen = false, preferredIndex = -1 }) {
+        let openIndexes = [];
+
+        if (resetOpen) {
+            openIndexes = getInitialOpenAccordionIndexes(itemStates, {
+                multiple: this.#isMultiple(),
+                collapsible: this.#isCollapsible(),
+            });
+        } else if (this.#isMultiple()) {
+            openIndexes = getOpenAccordionIndexes(itemStates);
+        } else {
+            openIndexes = getOpenAccordionIndexes(itemStates);
+
+            if (
+                preferredIndex !== -1
+                && openIndexes.includes(preferredIndex)
+                && !itemStates[preferredIndex]?.disabled
+            ) {
+                openIndexes = [preferredIndex];
+            } else if (openIndexes.length > 0) {
+                openIndexes = [openIndexes[0]];
+            } else if (!this.#isCollapsible()) {
+                const fallbackIndex = findFirstEnabledAccordionIndex(itemStates);
+
+                if (fallbackIndex !== -1) {
+                    openIndexes = [fallbackIndex];
+                }
+            }
+        }
+
+        this.#applyOpenState(openIndexes, itemStates);
+    }
+
+    #applyState() {
+        for (const { details, summary } of this.#items) {
+            const disabled = isAccordionItemDisabled(details);
+            const open = !disabled && details.open;
+
+            if (disabled && details.open) {
+                details.open = false;
+            }
+
+            details.toggleAttribute("data-open", open);
+
+            if (disabled) {
+                summary.setAttribute("aria-disabled", "true");
+                summary.tabIndex = -1;
+            } else {
+                summary.removeAttribute("aria-disabled");
+                summary.tabIndex = 0;
+            }
+        }
+    }
+
+    #toggleItem(index, itemStates = this.#getItemStates()) {
+        if (index < 0 || index >= this.#items.length || itemStates[index]?.disabled) {
+            return;
+        }
+
+        if (this.#isMultiple()) {
+            this.#items[index].details.open = !this.#items[index].details.open;
+            return;
+        }
+
+        const openIndexes = getOpenAccordionIndexes(itemStates);
+
+        if (itemStates[index]?.open) {
+            if (!this.#isCollapsible() && openIndexes.length === 1) {
+                return;
+            }
+
+            this.#applyOpenState([], itemStates);
+            this.#applyState();
+            return;
+        }
+
+        this.#applyOpenState([index], itemStates);
+        this.#applyState();
+    }
+
+    #applyOpenState(openIndexes, itemStates = this.#getItemStates()) {
+        const openIndexSet = new Set(openIndexes);
+
+        this.#isSyncingState = true;
+
+        try {
+            // Close panels first so single-open accordions do not briefly expose two bodies.
+            for (let index = 0; index < this.#items.length; index += 1) {
+                const details = this.#items[index].details;
+                const open = !itemStates[index]?.disabled && openIndexSet.has(index);
+
+                if (!open && details.open) {
+                    details.open = false;
+                }
+            }
+
+            for (let index = 0; index < this.#items.length; index += 1) {
+                const details = this.#items[index].details;
+                const open = !itemStates[index]?.disabled && openIndexSet.has(index);
+
+                if (open && !details.open) {
+                    details.open = true;
+                }
+            }
+        } finally {
+            this.#isSyncingState = false;
+        }
+    }
+}
+
+export function defineAccordion(registry = globalThis.customElements) {
+    if (!registry?.get || !registry?.define) {
+        return AccordionElement;
+    }
+
+    if (!registry.get(ACCORDION_TAG_NAME)) {
+        registry.define(ACCORDION_TAG_NAME, AccordionElement);
+    }
+
+    return AccordionElement;
+}

package/basic-components/basic-alert/README.md

@@ -0,0 +1,48 @@
+# `basic-alert`
+
+Inline live-region alert content without opinionated styling.
+
+## Register
+
+```js
+import "@lmfaole/basics/basic-components/basic-alert/register";
+```
+
+## Example
+
+```html
+<basic-alert data-label="Lagring fullfort" data-live="polite">
+  <h2 data-alert-title>Endringer lagret</h2>
+  <p>Meldingen ble lagret uten feil.</p>
+  <button type="button" data-alert-close>Dismiss</button>
+</basic-alert>
+```
+
+## Props
+
+| Prop | Description | Type | Default | Options |
+| --- | --- | --- | --- | --- |
+| `data-label` | Fallback accessible name when the alert has no `aria-label`, `aria-labelledby`, or `[data-alert-title]`. | string | `Alert` | any string |
+| `data-live` | Chooses whether the alert announces as `role="alert"` or `role="status"`. | enum string | `assertive` | `assertive`, `polite` |
+| `data-open` | Managed visibility flag. If omitted, the alert stays visible unless `hidden` is set. | boolean-ish attribute | visible | `present`, `omitted`, `false` |
+
+## Markup Hooks
+
+| Hook | Description | Type | Default | Options |
+| --- | --- | --- | --- | --- |
+| `data-alert-title` | Makes the visible heading the alert's accessible name. | descendant heading attribute | none | present on a descendant heading |
+| `data-alert-close` | Dismisses the alert when activated. | descendant control attribute | none | present on a descendant control |
+
+## Behavior
+
+- Applies the matching live-region role, `aria-live`, and `aria-atomic="true"` on the root element
+- Uses `[data-alert-title]` as the accessible name when present, otherwise falls back to `data-label`
+- `[data-alert-close]` hides the alert and removes its managed `data-open` state
+- `show()` and `hide()` support programmatic visibility changes
+
+## Markup Contract
+
+- Put the content directly inside `<basic-alert>`
+- Use `[data-alert-title]` when the alert should have a visible accessible name
+- Use `[data-alert-close]` when the alert should be dismissible
+- Keep layout and styling outside the package

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

@@ -0,0 +1,53 @@
+export const ALERT_TAG_NAME: "basic-alert";
+
+/**
+ * Normalizes unsupported or empty labels back to the default `"Alert"`.
+ */
+export function normalizeAlertLabel(
+    value?: string | null,
+): string;
+
+/**
+ * Normalizes unsupported live-region values back to `"assertive"`.
+ */
+export function normalizeAlertLive(
+    value?: string | null,
+): "assertive" | "polite";
+
+/**
+ * Maps an alert live setting to the matching ARIA role.
+ */
+export function getAlertRoleForLive(
+    value?: string | null,
+): "alert" | "status";
+
+/**
+ * Normalizes the optional `data-open` attribute into a boolean flag, using the
+ * current `hidden` state as a fallback.
+ */
+export function normalizeAlertOpen(
+    value?: string | null,
+    hidden?: boolean,
+): boolean;
+
+/**
+ * Custom element that upgrades inline content into a dismissible live-region
+ * alert.
+ *
+ * Attributes:
+ * - `data-label`: fallback accessible name when the alert has no title
+ * - `data-live`: chooses between `alert` and `status` semantics
+ * - `data-open`: optional managed visibility flag
+ */
+export class AlertElement extends HTMLElement {
+    static observedAttributes: string[];
+    show(): boolean;
+    hide(): boolean;
+}
+
+/**
+ * Registers the `basic-alert` custom element if it is not already defined.
+ */
+export function defineAlert(
+    registry?: CustomElementRegistry,
+): typeof AlertElement;

package/basic-components/basic-alert/index.js

@@ -0,0 +1,189 @@
+const ElementBase = globalThis.Element ?? class {};
+const HTMLElementBase = globalThis.HTMLElement ?? class {};
+const HTMLButtonElementBase = globalThis.HTMLButtonElement ?? class {};
+
+export const ALERT_TAG_NAME = "basic-alert";
+
+const DEFAULT_LABEL = "Alert";
+const DEFAULT_LIVE = "assertive";
+const TITLE_SELECTOR = "[data-alert-title]";
+const CLOSE_SELECTOR = "[data-alert-close]";
+const MANAGED_LABEL_ATTRIBUTE = "data-basic-alert-managed-label";
+const MANAGED_LABELLEDBY_ATTRIBUTE = "data-basic-alert-managed-labelledby";
+
+let nextAlertInstanceId = 1;
+
+function collectOwnedElements(root, scope, selector) {
+    return Array.from(scope.querySelectorAll(selector)).filter(
+        (element) => element instanceof HTMLElementBase && element.closest(ALERT_TAG_NAME) === root,
+    );
+}
+
+export function normalizeAlertLabel(value) {
+    return value?.trim() || DEFAULT_LABEL;
+}
+
+export function normalizeAlertLive(value) {
+    const normalized = value?.trim().toLowerCase();
+    return normalized === "polite" ? "polite" : DEFAULT_LIVE;
+}
+
+export function getAlertRoleForLive(value) {
+    return normalizeAlertLive(value) === "polite" ? "status" : "alert";
+}
+
+export function normalizeAlertOpen(value, hidden = false) {
+    if (hidden) {
+        return false;
+    }
+
+    if (value == null) {
+        return true;
+    }
+
+    const normalized = value.trim().toLowerCase();
+    return normalized === "" || normalized === "true" || normalized === "1";
+}
+
+export class AlertElement extends HTMLElementBase {
+    static observedAttributes = ["data-label", "data-live", "data-open", "hidden"];
+
+    #instanceId = `${ALERT_TAG_NAME}-${nextAlertInstanceId++}`;
+    #title = null;
+    #closeButtons = [];
+    #eventsBound = false;
+
+    connectedCallback() {
+        if (!this.#eventsBound) {
+            this.addEventListener("click", this.#handleClick);
+            this.#eventsBound = true;
+        }
+
+        this.#sync();
+    }
+
+    disconnectedCallback() {
+        if (!this.#eventsBound) {
+            return;
+        }
+
+        this.removeEventListener("click", this.#handleClick);
+        this.#eventsBound = false;
+    }
+
+    attributeChangedCallback() {
+        this.#sync();
+    }
+
+    show() {
+        this.hidden = false;
+        this.toggleAttribute("data-open", true);
+        this.#sync();
+        return true;
+    }
+
+    hide() {
+        this.hidden = true;
+        this.toggleAttribute("data-open", false);
+        this.#sync();
+        return true;
+    }
+
+    #handleClick = (event) => {
+        if (!(event.target instanceof ElementBase)) {
+            return;
+        }
+
+        const closeButton = event.target.closest(CLOSE_SELECTOR);
+
+        if (
+            closeButton instanceof HTMLElementBase
+            && closeButton.closest(ALERT_TAG_NAME) === this
+        ) {
+            event.preventDefault();
+            this.hide();
+        }
+    };
+
+    #sync() {
+        const nextTitle = collectOwnedElements(this, this, TITLE_SELECTOR)[0] ?? null;
+
+        this.#title = nextTitle instanceof HTMLElementBase ? nextTitle : null;
+        this.#closeButtons = collectOwnedElements(this, this, CLOSE_SELECTOR);
+        this.#applyState();
+    }
+
+    #applyState() {
+        for (const button of this.#closeButtons) {
+            if (button instanceof HTMLButtonElementBase && !button.hasAttribute("type")) {
+                button.type = "button";
+            }
+        }
+
+        const open = normalizeAlertOpen(this.getAttribute("data-open"), this.hidden);
+        const baseId = this.id || this.#instanceId;
+
+        if (this.#title instanceof HTMLElementBase && !this.#title.id) {
+            this.#title.id = `${baseId}-title`;
+        }
+
+        this.hidden = !open;
+        this.toggleAttribute("data-open", open);
+        this.setAttribute("role", getAlertRoleForLive(this.getAttribute("data-live")));
+        this.setAttribute("aria-live", normalizeAlertLive(this.getAttribute("data-live")));
+        this.setAttribute("aria-atomic", "true");
+        this.#syncAccessibleLabel();
+    }
+
+    #syncAccessibleLabel() {
+        const nextLabel = normalizeAlertLabel(this.getAttribute("data-label"));
+        const hasManagedLabel = this.hasAttribute(MANAGED_LABEL_ATTRIBUTE);
+        const hasManagedLabelledBy = this.hasAttribute(MANAGED_LABELLEDBY_ATTRIBUTE);
+
+        if (hasManagedLabel && this.getAttribute("aria-label") !== nextLabel) {
+            this.removeAttribute("aria-label");
+            this.removeAttribute(MANAGED_LABEL_ATTRIBUTE);
+        }
+
+        if (this.#title?.id) {
+            if (this.hasAttribute(MANAGED_LABEL_ATTRIBUTE)) {
+                this.removeAttribute("aria-label");
+                this.removeAttribute(MANAGED_LABEL_ATTRIBUTE);
+            }
+
+            if (!this.hasAttribute("aria-labelledby") || hasManagedLabelledBy) {
+                this.setAttribute("aria-labelledby", this.#title.id);
+                this.setAttribute(MANAGED_LABELLEDBY_ATTRIBUTE, "");
+            }
+
+            return;
+        }
+
+        if (hasManagedLabelledBy) {
+            this.removeAttribute("aria-labelledby");
+            this.removeAttribute(MANAGED_LABELLEDBY_ATTRIBUTE);
+        }
+
+        const hasOwnAriaLabel = this.hasAttribute("aria-label") && !this.hasAttribute(MANAGED_LABEL_ATTRIBUTE);
+        const hasOwnLabelledBy = this.hasAttribute("aria-labelledby");
+
+        if (hasOwnAriaLabel || hasOwnLabelledBy) {
+            return;
+        }
+
+        this.setAttribute("aria-label", nextLabel);
+        this.setAttribute(MANAGED_LABEL_ATTRIBUTE, "");
+    }
+}
+
+export function defineAlert(registry = globalThis.customElements) {
+    if (!registry?.get || !registry?.define) {
+        return AlertElement;
+    }
+
+    if (!registry.get(ALERT_TAG_NAME)) {
+        registry.define(ALERT_TAG_NAME, AlertElement);
+    }
+
+    return AlertElement;
+}

package/basic-components/basic-alert/register.js

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