@lmfaole/basics 0.3.0 → 0.5.0

package/{components → basic-components}/basic-table/index.js

@@ -12,6 +12,22 @@ const GENERATED_ROW_HEADER_ATTRIBUTE = "data-basic-table-generated-row-header";
 const GENERATED_DESCRIPTION_ATTRIBUTE = "data-basic-table-generated-description";
 const MANAGED_HEADERS_ATTRIBUTE = "data-basic-table-managed-headers";
 const MANAGED_LABEL_ATTRIBUTE = "data-basic-table-managed-label";
+const TABLE_OBSERVER_OPTIONS = {
+    childList: true,
+    subtree: true,
+    characterData: true,
+    attributes: true,
+    attributeFilter: [
+        "aria-describedby",
+        "aria-label",
+        "aria-labelledby",
+        "colspan",
+        "headers",
+        "id",
+        "rowspan",
+        "scope",
+    ],
+};
 
 let nextTableInstanceId = 1;
 
@@ -198,6 +214,21 @@ function replaceCellTag(cell, tagName, generatedAttributeName) {
     return replacement;
 }
 
+function demoteManagedHeaderCell(cell, generatedAttributeName) {
+    const replacement = document.createElement("td");
+
+    for (const attribute of Array.from(cell.attributes)) {
+        if (attribute.name === generatedAttributeName || attribute.name === "scope") {
+            continue;
+        }
+
+        replacement.setAttribute(attribute.name, attribute.value);
+    }
+
+    replacement.replaceChildren(...Array.from(cell.childNodes));
+    cell.parentElement?.replaceChild(replacement, cell);
+}
+
 function promoteFirstRowCellsToHeaders(table) {
     const firstRow = table.rows[0];
 
@@ -214,38 +245,41 @@ function promoteFirstRowCellsToHeaders(table) {
     }
 }
 
-function promoteBodyCellsToRowHeaders(table, rowHeaderColumnIndex) {
-    for (const section of Array.from(table.tBodies)) {
-        for (const row of Array.from(section.rows)) {
-            const targetCell = findCellAtColumnIndex(row, rowHeaderColumnIndex);
-
-            if (!(targetCell instanceof HTMLTableCellElementBase) || targetCell.tagName === "TH") {
-                continue;
-            }
-
-            replaceCellTag(targetCell, "th", GENERATED_ROW_HEADER_ATTRIBUTE);
-        }
-    }
-}
-
 function demoteManagedHeaders(table, generatedAttributeName) {
     for (const cell of Array.from(table.querySelectorAll(`th[${generatedAttributeName}]`))) {
         if (!(cell instanceof HTMLTableCellElementBase)) {
             continue;
         }
 
-        const replacement = document.createElement("td");
+        demoteManagedHeaderCell(cell, generatedAttributeName);
+    }
+}
 
-        for (const attribute of Array.from(cell.attributes)) {
-            if (attribute.name === generatedAttributeName || attribute.name === "scope") {
+function syncBodyRowHeaders(table, rowHeaderColumnIndex, rowHeadersEnabled) {
+    for (const section of Array.from(table.tBodies)) {
+        for (const row of Array.from(section.rows)) {
+            const targetCell = rowHeadersEnabled
+                ? findCellAtColumnIndex(row, rowHeaderColumnIndex)
+                : null;
+
+            for (const cell of Array.from(row.cells)) {
+                if (
+                    !(cell instanceof HTMLTableCellElementBase)
+                    || !cell.hasAttribute(GENERATED_ROW_HEADER_ATTRIBUTE)
+                    || cell === targetCell
+                ) {
+                    continue;
+                }
+
+                demoteManagedHeaderCell(cell, GENERATED_ROW_HEADER_ATTRIBUTE);
+            }
+
+            if (!(targetCell instanceof HTMLTableCellElementBase) || targetCell.tagName === "TH") {
                 continue;
             }
 
-            replacement.setAttribute(attribute.name, attribute.value);
+            replaceCellTag(targetCell, "th", GENERATED_ROW_HEADER_ATTRIBUTE);
         }
-
-        replacement.replaceChildren(...Array.from(cell.childNodes));
-        cell.parentElement?.replaceChild(replacement, cell);
     }
 }
 
@@ -256,6 +290,12 @@ function createGeneratedCaption(table) {
     return caption;
 }
 
+function syncTextContent(node, text) {
+    if (node.textContent !== text) {
+        node.textContent = text;
+    }
+}
+
 function syncTableCaption(table, captionText) {
     const existingCaption = table.caption;
     const generatedCaption = existingCaption?.hasAttribute(GENERATED_CAPTION_ATTRIBUTE)
@@ -272,18 +312,12 @@ function syncTableCaption(table, captionText) {
     }
 
     const caption = generatedCaption ?? createGeneratedCaption(table);
-    caption.textContent = captionText;
+    syncTextContent(caption, captionText);
 }
 
 function syncFallbackAccessibleName(table, label) {
     const hasCaption = Boolean(table.caption);
-    let hasManagedLabel = table.hasAttribute(MANAGED_LABEL_ATTRIBUTE);
-
-    if (hasManagedLabel && table.getAttribute("aria-label") !== label) {
-        table.removeAttribute(MANAGED_LABEL_ATTRIBUTE);
-        hasManagedLabel = false;
-    }
-
+    const hasManagedLabel = table.hasAttribute(MANAGED_LABEL_ATTRIBUTE);
     const hasOwnAriaLabel = table.hasAttribute("aria-label") && !hasManagedLabel;
     const hasOwnLabelledBy = table.hasAttribute("aria-labelledby");
 
@@ -296,8 +330,13 @@ function syncFallbackAccessibleName(table, label) {
         return;
     }
 
-    table.setAttribute("aria-label", label);
-    table.setAttribute(MANAGED_LABEL_ATTRIBUTE, "");
+    if (table.getAttribute("aria-label") !== label) {
+        table.setAttribute("aria-label", label);
+    }
+
+    if (!hasManagedLabel) {
+        table.setAttribute(MANAGED_LABEL_ATTRIBUTE, "");
+    }
 }
 
 function getGeneratedDescription(root) {
@@ -321,7 +360,11 @@ function syncTableDescription(root, table, descriptionText, baseId) {
             );
 
             if (tokens.length > 0) {
-                table.setAttribute("aria-describedby", tokens.join(" "));
+                const nextValue = tokens.join(" ");
+
+                if (table.getAttribute("aria-describedby") !== nextValue) {
+                    table.setAttribute("aria-describedby", nextValue);
+                }
             } else {
                 table.removeAttribute("aria-describedby");
             }
@@ -343,13 +386,17 @@ function syncTableDescription(root, table, descriptionText, baseId) {
         description.id = `${baseId}-description`;
     }
 
-    description.textContent = descriptionText;
+    syncTextContent(description, descriptionText);
 
     const tokens = getAriaReferenceTokens(table.getAttribute("aria-describedby")).filter(
         (token) => token !== description.id,
     );
     tokens.push(description.id);
-    table.setAttribute("aria-describedby", tokens.join(" "));
+    const nextValue = tokens.join(" ");
+
+    if (table.getAttribute("aria-describedby") !== nextValue) {
+        table.setAttribute("aria-describedby", nextValue);
+    }
 }
 
 export class TableElement extends HTMLElementBase {
@@ -364,6 +411,7 @@ export class TableElement extends HTMLElementBase {
 
     #instanceId = `${TABLE_TAG_NAME}-${nextTableInstanceId++}`;
     #observer = null;
+    #observing = false;
     #scheduledFrame = 0;
 
     connectedCallback() {
@@ -372,7 +420,7 @@ export class TableElement extends HTMLElementBase {
     }
 
     disconnectedCallback() {
-        this.#observer?.disconnect();
+        this.#stopObserving();
         this.#observer = null;
 
         if (this.#scheduledFrame !== 0 && typeof window !== "undefined") {
@@ -386,119 +434,126 @@ export class TableElement extends HTMLElementBase {
     }
 
     refresh() {
-        const table = collectOwnedTables(this)[0] ?? null;
+        this.#stopObserving();
 
-        if (!(table instanceof HTMLTableElementBase)) {
-            return;
-        }
+        try {
+            const table = collectOwnedTables(this)[0] ?? null;
 
-        const label = normalizeTableLabel(this.getAttribute("data-label"));
-        const caption = normalizeTableCaption(this.getAttribute("data-caption"));
-        const description = normalizeTableDescription(this.getAttribute("data-description"));
-        const columnHeadersEnabled = normalizeTableColumnHeaders(
-            this.getAttribute("data-column-headers") ?? this.hasAttribute("data-column-headers"),
-        );
-        const rowHeaderColumnIndex = normalizeTableRowHeaderColumn(
-            this.getAttribute("data-row-header-column"),
-        ) - 1;
-        const rowHeadersEnabled = normalizeTableRowHeaders(
-            this.getAttribute("data-row-headers") ?? this.hasAttribute("data-row-header-column"),
-        );
-        const baseId = this.id || this.#instanceId;
-
-        syncTableCaption(table, caption);
-        syncFallbackAccessibleName(table, label);
-        syncTableDescription(this, table, description, baseId);
-
-        if (columnHeadersEnabled) {
-            promoteFirstRowCellsToHeaders(table);
-        } else {
-            demoteManagedHeaders(table, GENERATED_COLUMN_HEADER_ATTRIBUTE);
-        }
+            if (!(table instanceof HTMLTableElementBase)) {
+                return;
+            }
 
-        if (rowHeadersEnabled) {
-            demoteManagedHeaders(table, GENERATED_ROW_HEADER_ATTRIBUTE);
-            promoteBodyCellsToRowHeaders(table, rowHeaderColumnIndex);
-        } else {
-            demoteManagedHeaders(table, GENERATED_ROW_HEADER_ATTRIBUTE);
-        }
+            const label = normalizeTableLabel(this.getAttribute("data-label"));
+            const caption = normalizeTableCaption(this.getAttribute("data-caption"));
+            const description = normalizeTableDescription(this.getAttribute("data-description"));
+            const columnHeadersEnabled = normalizeTableColumnHeaders(
+                this.getAttribute("data-column-headers") ?? this.hasAttribute("data-column-headers"),
+            );
+            const rowHeaderColumnIndex = normalizeTableRowHeaderColumn(
+                this.getAttribute("data-row-header-column"),
+            ) - 1;
+            const rowHeadersEnabled = normalizeTableRowHeaders(
+                this.getAttribute("data-row-headers") ?? this.hasAttribute("data-row-header-column"),
+            );
+            const baseId = this.id || this.#instanceId;
 
-        const placements = buildTablePlacements(table);
-        const headerPlacements = [];
-        let nextHeaderIndex = 1;
+            syncTableCaption(table, caption);
+            syncFallbackAccessibleName(table, label);
+            syncTableDescription(this, table, description, baseId);
 
-        for (const placement of placements) {
-            if (placement.cell.tagName !== "TH") {
-                continue;
+            if (columnHeadersEnabled) {
+                promoteFirstRowCellsToHeaders(table);
+            } else {
+                demoteManagedHeaders(table, GENERATED_COLUMN_HEADER_ATTRIBUTE);
             }
 
-            const scope = inferHeaderScope(placement.cell, placement, {
-                columnHeadersEnabled,
-                rowHeadersEnabled,
-                rowHeaderColumnIndex,
-            });
+            syncBodyRowHeaders(table, rowHeaderColumnIndex, rowHeadersEnabled);
 
-            if (scope) {
-                placement.cell.setAttribute("scope", scope);
-            }
+            const placements = buildTablePlacements(table);
+            const headerPlacements = [];
+            let nextHeaderIndex = 1;
 
-            headerPlacements.push({
-                ...placement,
-                scope,
-                id: ensureHeaderId(placement.cell, this.id || this.#instanceId, nextHeaderIndex),
-            });
-            nextHeaderIndex += 1;
-        }
+            for (const placement of placements) {
+                if (placement.cell.tagName !== "TH") {
+                    continue;
+                }
 
-        headerPlacements.sort(sortPlacementsInDocumentOrder);
+                const scope = inferHeaderScope(placement.cell, placement, {
+                    columnHeadersEnabled,
+                    rowHeadersEnabled,
+                    rowHeaderColumnIndex,
+                });
 
-        for (const placement of placements) {
-            if (placement.cell.tagName !== "TD") {
-                continue;
+                if (scope) {
+                    if (placement.cell.getAttribute("scope") !== scope) {
+                        placement.cell.setAttribute("scope", scope);
+                    }
+                }
+
+                headerPlacements.push({
+                    ...placement,
+                    scope,
+                    id: ensureHeaderId(placement.cell, this.id || this.#instanceId, nextHeaderIndex),
+                });
+                nextHeaderIndex += 1;
             }
 
-            const associatedHeaders = headerPlacements.filter((header) => {
-                switch (header.scope) {
-                    case "col":
-                    case "colgroup":
-                        return (
-                            header.rowIndex < placement.rowIndex
-                            && header.columnIndex < placement.columnIndex + placement.colSpan
-                            && header.columnIndex + header.colSpan > placement.columnIndex
-                        );
-                    case "row":
-                    case "rowgroup":
-                        return (
-                            header.columnIndex < placement.columnIndex
-                            && header.rowIndex < placement.rowIndex + placement.rowSpan
-                            && header.rowIndex + header.rowSpan > placement.rowIndex
-                        );
-                    default:
-                        return false;
+            headerPlacements.sort(sortPlacementsInDocumentOrder);
+
+            for (const placement of placements) {
+                if (placement.cell.tagName !== "TD") {
+                    continue;
                 }
-            });
 
-            if (associatedHeaders.length === 0) {
-                if (placement.cell.hasAttribute(MANAGED_HEADERS_ATTRIBUTE)) {
-                    placement.cell.removeAttribute("headers");
-                    placement.cell.removeAttribute(MANAGED_HEADERS_ATTRIBUTE);
+                const associatedHeaders = headerPlacements.filter((header) => {
+                    switch (header.scope) {
+                        case "col":
+                        case "colgroup":
+                            return (
+                                header.rowIndex < placement.rowIndex
+                                && header.columnIndex < placement.columnIndex + placement.colSpan
+                                && header.columnIndex + header.colSpan > placement.columnIndex
+                            );
+                        case "row":
+                        case "rowgroup":
+                            return (
+                                header.columnIndex < placement.columnIndex
+                                && header.rowIndex < placement.rowIndex + placement.rowSpan
+                                && header.rowIndex + header.rowSpan > placement.rowIndex
+                            );
+                        default:
+                            return false;
+                    }
+                });
+
+                if (associatedHeaders.length === 0) {
+                    if (placement.cell.hasAttribute(MANAGED_HEADERS_ATTRIBUTE)) {
+                        placement.cell.removeAttribute("headers");
+                        placement.cell.removeAttribute(MANAGED_HEADERS_ATTRIBUTE);
+                    }
+
+                    continue;
                 }
 
-                continue;
-            }
+                if (
+                    placement.cell.hasAttribute("headers")
+                    && !placement.cell.hasAttribute(MANAGED_HEADERS_ATTRIBUTE)
+                ) {
+                    continue;
+                }
 
-            if (
-                placement.cell.hasAttribute("headers")
-                && !placement.cell.hasAttribute(MANAGED_HEADERS_ATTRIBUTE)
-            ) {
-                continue;
-            }
+                const nextHeaders = associatedHeaders.map((header) => header.id).join(" ");
 
-            placement.cell.setAttribute(
-                "headers",
-                associatedHeaders.map((header) => header.id).join(" "),
-            );
-            placement.cell.setAttribute(MANAGED_HEADERS_ATTRIBUTE, "");
+                if (placement.cell.getAttribute("headers") !== nextHeaders) {
+                    placement.cell.setAttribute("headers", nextHeaders);
+                }
+
+                if (!placement.cell.hasAttribute(MANAGED_HEADERS_ATTRIBUTE)) {
+                    placement.cell.setAttribute(MANAGED_HEADERS_ATTRIBUTE, "");
+                }
+            }
+        } finally {
+            this.#startObserving();
         }
     }
 
@@ -522,22 +577,25 @@ export class TableElement extends HTMLElementBase {
             this.#scheduleRefresh();
         });
 
-        this.#observer.observe(this, {
-            childList: true,
-            subtree: true,
-            characterData: true,
-            attributes: true,
-            attributeFilter: [
-                "aria-describedby",
-                "aria-label",
-                "aria-labelledby",
-                "colspan",
-                "headers",
-                "id",
-                "rowspan",
-                "scope",
-            ],
-        });
+        this.#startObserving();
+    }
+
+    #startObserving() {
+        if (!this.#observer || this.#observing) {
+            return;
+        }
+
+        this.#observer.observe(this, TABLE_OBSERVER_OPTIONS);
+        this.#observing = true;
+    }
+
+    #stopObserving() {
+        if (!this.#observer || !this.#observing) {
+            return;
+        }
+
+        this.#observer.disconnect();
+        this.#observing = false;
     }
 }
 

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

@@ -0,0 +1,63 @@
+# `basic-tabs`
+
+Accessible tablists and panels from existing markup.
+
+## Register
+
+```js
+import "@lmfaole/basics/basic-components/basic-tabs/register";
+```
+
+## Example
+
+```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>
+```
+
+## Props
+
+| Prop | Description | Type | Default | Options |
+| --- | --- | --- | --- | --- |
+| `data-label` | Accessible name for the generated tablist when it does not already have one. | string | `Faner` | any string |
+| `data-activation` | Chooses whether arrow-key focus changes also activate the selected panel. | enum string | `automatic` | `automatic`, `manual` |
+| `data-selected-index` | Sets the initially selected tab by index. Invalid values fall back to the first enabled tab. | zero-based integer | first enabled tab | zero-based integer |
+
+## Markup Hooks
+
+| Hook | Description | Type | Default | Options |
+| --- | --- | --- | --- | --- |
+| `data-tabs-list` | Holds the interactive tab controls. | descendant container attribute | required | present on one descendant container |
+| `data-tab` | Marks each tab control. Prefer `<button>` elements. | descendant control attribute | required | present on matching descendant controls |
+| `data-tab-panel` | Marks each panel in the same order as the tabs. | descendant panel attribute | required | present on matching descendant panels |
+| `disabled` on a `[data-tab]` control | Removes that tab from keyboard navigation and selection. | boolean attribute | off | `present`, `omitted` |
+
+## Behavior
+
+- Generates missing tab and panel ids
+- Keeps `aria-selected`, `aria-controls`, `aria-labelledby`, `hidden`, and `data-selected` in sync
+- Supports click, `ArrowLeft`, `ArrowRight`, `Home`, and `End`
+- Skips disabled tabs during keyboard navigation
+- In `manual` mode, arrow keys move focus and `Enter` or `Space` activates
+
+## Markup Contract
+
+- Provide one descendant element with `data-tabs-list`
+- Provide matching counts of `[data-tab]` and `[data-tab-panel]` in the same order
+- Prefer `<button>` elements for tabs
+- Keep layout and styling outside the package

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

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

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

@@ -0,0 +1,62 @@
+# `basic-toast`
+
+Toast notifications with managed open state and live-region announcements.
+
+## Register
+
+```js
+import "@lmfaole/basics/basic-components/basic-toast/register";
+```
+
+## Example
+
+```html
+<basic-toast data-label="Lagring fullfort" data-duration="5000">
+  <button type="button" data-toast-open>Show toast</button>
+
+  <section data-toast-panel>
+    <h2 data-toast-title>Lagret</h2>
+    <p>Meldingen ble lagret uten feil.</p>
+  </section>
+</basic-toast>
+```
+
+## Props
+
+| Prop | Description | Type | Default | Options |
+| --- | --- | --- | --- | --- |
+| `data-label` | Fallback accessible name when the toast panel has no `aria-label`, `aria-labelledby`, or `[data-toast-title]`. | string | `Toast` | any string |
+| `data-live` | Chooses whether the announcement behaves like `status` or `alert`. | enum string | `polite` | `polite`, `assertive` |
+| `data-duration` | Auto-dismiss timeout for the toast. | non-negative integer | `5000` | non-negative integer milliseconds, `0` disables auto-dismiss |
+| `data-open` | Optional initial open state for the managed toast panel. | boolean-ish attribute | closed | `present`, `omitted`, `false` |
+
+## Starter Styling Prop
+
+| Prop | Description | Type | Default | Options |
+| --- | --- | --- | --- | --- |
+| `data-toast-position` | Optional starter-CSS hook for viewport placement when you import `basic-styling`. | enum string | none | `top-left`, `top-center`, `top-right`, `center-left`, `center`, `center-right`, `bottom-left`, `bottom-center`, `bottom-right` |
+
+## Markup Hooks
+
+| Hook | Description | Type | Default | Options |
+| --- | --- | --- | --- | --- |
+| `data-toast-open` | Shows or toggles the toast. | descendant control attribute | none | present on a descendant button or control |
+| `data-toast-panel` | Marks the message container managed by the component. | descendant element attribute | required | present on one descendant element |
+| `data-toast-title` | Makes the visible heading the toast's accessible name. | descendant heading attribute | none | present on a descendant heading |
+| `data-toast-close` | Closes the toast when activated. | descendant control attribute | none | present on a descendant control outside `[data-toast-panel]` |
+
+## Behavior
+
+- Uses the Popover API in manual mode when available so the toast can render in the top layer
+- Announces the current toast text through an internal live region whenever the toast opens
+- Syncs `hidden` and `data-open` on the panel and root element
+- Uses `[data-toast-title]` as the accessible name when present, otherwise falls back to `data-label`
+- Supports `show()`, `hide()`, and `toggle()`
+
+## Markup Contract
+
+- Provide one descendant `[data-toast-panel]`
+- Keep `[data-toast-panel]` to non-interactive message content
+- Use `[data-toast-open]` on buttons that should show or toggle the toast
+- If you need an explicit dismiss control, place `[data-toast-close]` outside `[data-toast-panel]`
+- Keep layout and styling outside the package

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

@@ -0,0 +1,68 @@
+export const TOAST_TAG_NAME: "basic-toast";
+
+/**
+ * Normalizes unsupported or empty labels back to the default `"Toast"`.
+ */
+export function normalizeToastLabel(
+    value?: string | null,
+): string;
+
+/**
+ * Normalizes unsupported live-region values back to `"polite"`.
+ */
+export function normalizeToastLive(
+    value?: string | null,
+): "assertive" | "polite";
+
+/**
+ * Maps a toast live setting to the matching ARIA role.
+ */
+export function getToastRoleForLive(
+    value?: string | null,
+): "alert" | "status";
+
+/**
+ * Normalizes the optional `data-duration` attribute into milliseconds.
+ * A value of `0` disables auto-dismiss.
+ */
+export function normalizeToastDuration(
+    value?: string | null,
+): number;
+
+/**
+ * Normalizes the optional `data-open` attribute into a boolean flag.
+ */
+export function normalizeToastOpen(
+    value?: string | null,
+): boolean;
+
+/**
+ * Custom element that upgrades trigger-and-panel markup into a toast
+ * notification flow with optional auto-dismiss.
+ *
+ * Attributes:
+ * - `data-label`: fallback accessible name when the toast has no title
+ * - `data-live`: chooses between `status` and `alert` semantics
+ * - `data-duration`: auto-dismiss timeout in milliseconds, `0` disables it
+ * - `data-open`: optional initial open state
+ *
+ * Behavior:
+ * - uses the Popover API in manual mode when available so the toast panel can
+ *   render in the top layer
+ * - announces the current toast text through an internal live region whenever
+ *   the toast opens
+ * - expects `[data-toast-panel]` to contain non-interactive message content
+ */
+export class ToastElement extends HTMLElement {
+    static observedAttributes: string[];
+    show(opener?: HTMLElement | null): boolean;
+    hide(): boolean;
+    toggle(opener?: HTMLElement | null): boolean;
+}
+
+/**
+ * Registers the `basic-toast` custom element if it is not already defined.
+ */
+export function defineToast(
+    registry?: CustomElementRegistry,
+): typeof ToastElement;