@lmfaole/basics 0.1.1 → 0.2.1

package/README.md

@@ -31,12 +31,167 @@ Storybook Test coverage is enabled through the Vitest addon. In the Storybook UI
 
 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.
 
+GitHub Actions now splits Storybook automation by purpose:
+
+- `CI` runs the browser-backed Storybook test suite on pull requests and pushes to `main`.
+- `Storybook Preview` builds Storybook for pull requests and uploads `storybook-static` as an artifact.
+- `Storybook Pages` deploys the built Storybook from `main` to GitHub Pages.
+- `Chromatic` publishes Storybook builds on branch pushes when the `CHROMATIC_PROJECT_TOKEN` repository secret is configured.
+
+## Changesets
+
+For changes that affect the published package, run:
+
+```sh
+pnpm changeset
+```
+
+Commit the generated Markdown file under `.changeset/` with the rest of your work. If a change is repo-only and does not affect the published package, no changeset file is needed.
+
 ## Releasing
 
-1. Update `package.json` to the version you want to ship.
-2. Publish the package to npm with `npm publish --access public --registry=https://registry.npmjs.org`.
-3. Push a matching git tag such as `v0.1.0`.
-4. GitHub Actions will run the test suite, pack the published files, and create a GitHub Release with the tarball attached.
+Merging changesets into `main` causes the `Release` workflow to open or update a `chore: release` pull request. Merging that release pull request will:
+
+1. run `pnpm release`
+2. publish the package to npm with trusted publishing from GitHub Actions
+3. create the matching `vX.Y.Z` git tag and GitHub Release
+4. attach the packed tarball to the GitHub Release
+
+Trusted publishing must be configured on npm for `@lmfaole/basics` against the GitHub Actions workflow file `.github/workflows/release.yml` in the `lmfaole/basics` repository. No `NPM_TOKEN` repository secret is needed once trusted publishing is active.
+
+If a release needs to be retried after the workflow changes land, use the `Release` workflow's `publish_current_version` manual input to publish the current `package.json` version from `main` when it is still unpublished.
+
+## Commits
+
+Use Conventional Commits for commit messages and pull request titles. The GitHub workflow accepts `build`, `chore`, `ci`, `docs`, `feat`, `fix`, `perf`, `refactor`, `revert`, `style`, and `test`, with an optional scope such as `feat(tabs): add keyboard support`.
+
+## Basic Popover
+
+```html
+<basic-popover data-label="Filtre" data-anchor-trigger data-position-area="bottom">
+  <button type="button" data-popover-open>Toggle popover</button>
+
+  <section data-popover-panel>
+    <h2 data-popover-title>Filtre</h2>
+    <p>Popover body.</p>
+    <button type="button" data-popover-close>Close</button>
+  </section>
+</basic-popover>
+
+<script type="module">
+  import "@lmfaole/basics/components/basic-popover/register";
+</script>
+```
+
+The element upgrades popover trigger-and-panel markup into an accessible non-modal overlay without adding any styles of its own.
+
+### Attributes
+
+- `data-label`: fallback accessible name when the popover has no `aria-label`, `aria-labelledby`, or `[data-popover-title]`.
+- `data-anchor-trigger`: uses the opener as the popover's implicit anchor so consumer CSS can position the panel relative to the trigger.
+- `data-position-area`: sets the CSS anchor-positioning area used when `data-anchor-trigger` is enabled. Defaults to `bottom`.
+- `data-position-try-fallbacks`: optional comma-separated fallback list used when the default anchored placement would overflow. By default the component derives a sensible sequence from `data-position-area`.
+
+### Behavior
+
+- Uses the native Popover API in auto mode for outside-click and `Esc` dismissal.
+- Syncs `aria-expanded`, `aria-controls`, and `data-open` between the trigger and panel.
+- Restores focus to the opener when dismissal should return to it, while preserving focus on an outside control the user explicitly clicked.
+- When `data-anchor-trigger` is set, opening the popover passes the trigger as the Popover API `source`, establishes the panel's implicit anchor, and applies the configured `position-area`.
+- When `data-anchor-trigger` is set and `data-position-try-fallbacks` is not provided, the component derives a fallback sequence from the default placement:
+  `bottom` or `top` start with `flip-block`, while `left` or `right` start with `flip-inline`.
+- `[data-popover-close]` controls can dismiss the panel from inside the overlay.
+
+### Markup Contract
+
+- Provide one descendant `[data-popover-panel]`.
+- Use `[data-popover-open]` on buttons that should toggle the panel.
+- Use `[data-popover-title]` for the popover heading when you want it to become the accessible name.
+- If you set `data-anchor-trigger`, you can tune the default anchored placement with `data-position-area` and optionally override its overflow fallbacks with `data-position-try-fallbacks`.
+- Keep layout and styling outside the package; the component only manages semantics and open or close behavior.
+
+## Basic Dialog
+
+```html
+<basic-dialog data-label="Bekreft handling" data-backdrop-close>
+  <button type="button" data-dialog-open>Open dialog</button>
+
+  <dialog data-dialog-panel>
+    <h2 data-dialog-title>Bekreft handling</h2>
+    <p>Dialog body.</p>
+    <button type="button" data-dialog-close>Cancel</button>
+    <button type="button" data-dialog-close data-dialog-close-value="confirmed">
+      Confirm
+    </button>
+  </dialog>
+</basic-dialog>
+
+<script type="module">
+  import "@lmfaole/basics/components/basic-dialog/register";
+</script>
+```
+
+The element upgrades native `<dialog>` markup into an accessible modal flow without adding any styles of its own.
+
+### Attributes
+
+- `data-label`: fallback accessible name when the dialog has no `aria-label`, `aria-labelledby`, or `[data-dialog-title]`.
+- `data-backdrop-close`: allows clicks on the dialog backdrop to close the modal.
+
+### Behavior
+
+- Uses the native dialog element's modal behavior via `showModal()`.
+- Restores focus to the element that opened the dialog when the modal closes.
+- `Esc` closes the modal through the platform's dialog behavior.
+- `[data-dialog-close]` controls can optionally set `data-dialog-close-value` to pass a close value.
+
+### Markup Contract
+
+- Provide one descendant `<dialog data-dialog-panel>`.
+- Use `[data-dialog-open]` on buttons that should open the modal.
+- Use `[data-dialog-title]` for the dialog heading when you want it to become the accessible name.
+- Keep layout and styling outside the package; the component only manages semantics and open or close behavior.
+
+## Basic Accordion
+
+```html
+<basic-accordion>
+  <h3><button type="button" data-accordion-trigger>Oversikt</button></h3>
+  <section data-accordion-panel>
+    <p>Viser en kort oppsummering.</p>
+  </section>
+
+  <h3><button type="button" data-accordion-trigger>Implementasjon</button></h3>
+  <section data-accordion-panel>
+    <p>Viser implementasjonsdetaljer.</p>
+  </section>
+</basic-accordion>
+
+<script type="module">
+  import "@lmfaole/basics/components/basic-accordion/register";
+</script>
+```
+
+The element upgrades existing trigger-and-panel markup into an accessible accordion without adding any styles of its own.
+
+### Attributes
+
+- `data-multiple`: allows multiple panels to stay open at the same time.
+- `data-collapsible`: allows the last open panel in single mode to close.
+
+### Behavior
+
+- Missing trigger and panel ids are generated automatically.
+- `aria-expanded`, `aria-controls`, `aria-labelledby`, `hidden`, and `data-open` stay in sync with the current state.
+- `ArrowUp`, `ArrowDown`, `Home`, and `End` move focus between enabled triggers.
+- `Enter` and `Space` toggle the focused item.
+- Disabled triggers are skipped during keyboard navigation.
+
+### Markup Contract
+
+- Provide matching counts of `[data-accordion-trigger]` and `[data-accordion-panel]` descendants in the same order.
+- Prefer `<button>` elements for triggers, usually inside your own heading elements.
+- Keep layout and styling outside the package; the component only manages semantics, state, and keyboard behavior.
 
 ## Basic Tabs
 

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

@@ -0,0 +1,50 @@
+export interface AccordionItemState {
+    disabled: boolean;
+    open?: boolean;
+}
+
+/**
+ * Public tag name registered by `defineAccordion`.
+ */
+export const ACCORDION_TAG_NAME: "basic-accordion";
+
+/**
+ * Returns the initially open accordion item indexes based on explicit state and
+ * the root element's single-open or collapsible behavior.
+ */
+export function getInitialOpenAccordionIndexes(
+    itemStates: AccordionItemState[],
+    options?: {
+        multiple?: boolean;
+        collapsible?: boolean;
+    },
+): number[];
+
+/**
+ * Returns the next enabled accordion trigger index, wrapping around the list
+ * when needed.
+ */
+export function findNextEnabledAccordionIndex(
+    itemStates: AccordionItemState[],
+    startIndex: number,
+    direction: number,
+): number;
+
+/**
+ * Custom element that upgrades existing trigger-and-panel markup into an
+ * accessible accordion interface.
+ *
+ * Attributes:
+ * - `data-multiple`: allows multiple panels to stay open
+ * - `data-collapsible`: allows the last open panel in single mode to close
+ */
+export class AccordionElement extends HTMLElement {
+    static observedAttributes: string[];
+}
+
+/**
+ * Registers the `basic-accordion` custom element if it is not already defined.
+ */
+export function defineAccordion(
+    registry?: CustomElementRegistry,
+): typeof AccordionElement;

package/components/basic-accordion/index.js

@@ -0,0 +1,387 @@
+const ElementBase = globalThis.Element ?? class {};
+const HTMLElementBase = globalThis.HTMLElement ?? class {};
+const HTMLButtonElementBase = globalThis.HTMLButtonElement ?? class {};
+
+export const ACCORDION_TAG_NAME = "basic-accordion";
+
+const TRIGGER_SELECTOR = "[data-accordion-trigger]";
+const PANEL_SELECTOR = "[data-accordion-panel]";
+
+let nextAccordionInstanceId = 1;
+
+function collectOwnedElements(root, scope, selector) {
+    return Array.from(scope.querySelectorAll(selector)).filter(
+        (element) => element instanceof HTMLElementBase && element.closest(ACCORDION_TAG_NAME) === root,
+    );
+}
+
+function isAccordionItemDisabled(trigger) {
+    return trigger.hasAttribute("disabled") || trigger.getAttribute("aria-disabled") === "true";
+}
+
+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"];
+
+    #instanceId = `${ACCORDION_TAG_NAME}-${nextAccordionInstanceId++}`;
+    #triggers = [];
+    #panels = [];
+    #openIndexes = new Set();
+    #focusIndex = -1;
+    #eventsBound = 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) {
+            return;
+        }
+
+        this.removeEventListener("click", this.#handleClick);
+        this.removeEventListener("keydown", this.#handleKeyDown);
+        this.#eventsBound = false;
+    }
+
+    attributeChangedCallback() {
+        this.#sync({ resetOpen: true });
+    }
+
+    #handleClick = (event) => {
+        if (!(event.target instanceof ElementBase)) {
+            return;
+        }
+
+        const trigger = event.target.closest(TRIGGER_SELECTOR);
+
+        if (
+            !(trigger instanceof HTMLElementBase)
+            || trigger.closest(ACCORDION_TAG_NAME) !== this
+        ) {
+            return;
+        }
+
+        const triggerIndex = this.#triggers.indexOf(trigger);
+
+        if (triggerIndex === -1) {
+            return;
+        }
+
+        this.#toggleIndex(triggerIndex, { focus: true });
+    };
+
+    #handleKeyDown = (event) => {
+        if (!(event.target instanceof ElementBase)) {
+            return;
+        }
+
+        const currentTrigger = event.target.closest(TRIGGER_SELECTOR);
+
+        if (
+            !(currentTrigger instanceof HTMLElementBase)
+            || currentTrigger.closest(ACCORDION_TAG_NAME) !== this
+        ) {
+            return;
+        }
+
+        const itemStates = this.#getItemStates();
+        const currentIndex = this.#triggers.indexOf(currentTrigger);
+        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.#toggleIndex(currentIndex, { focus: true });
+                return;
+            default:
+                return;
+        }
+
+        if (nextIndex === -1) {
+            return;
+        }
+
+        event.preventDefault();
+        this.#focusIndex = nextIndex;
+        this.#applyState({ focus: true });
+    };
+
+    #getItemStates() {
+        const pairCount = Math.min(this.#triggers.length, this.#panels.length);
+
+        return this.#triggers.slice(0, pairCount).map((trigger, index) => ({
+            disabled: isAccordionItemDisabled(trigger),
+            open: trigger.hasAttribute("data-open")
+                || trigger.getAttribute("aria-expanded") === "true"
+                || this.#panels[index]?.hasAttribute("data-open"),
+        }));
+    }
+
+    #isCollapsible() {
+        return this.hasAttribute("data-collapsible");
+    }
+
+    #isMultiple() {
+        return this.hasAttribute("data-multiple");
+    }
+
+    #getNextFocusableIndex(itemStates) {
+        for (const openIndex of this.#openIndexes) {
+            if (!itemStates[openIndex]?.disabled) {
+                return openIndex;
+            }
+        }
+
+        return findFirstEnabledAccordionIndex(itemStates);
+    }
+
+    #sync({ resetOpen = false } = {}) {
+        this.#triggers = collectOwnedElements(this, this, TRIGGER_SELECTOR);
+        this.#panels = collectOwnedElements(this, this, PANEL_SELECTOR);
+
+        const itemStates = this.#getItemStates();
+
+        if (resetOpen) {
+            this.#openIndexes = new Set(
+                getInitialOpenAccordionIndexes(itemStates, {
+                    multiple: this.#isMultiple(),
+                    collapsible: this.#isCollapsible(),
+                }),
+            );
+        } else {
+            const nextOpenIndexes = Array.from(this.#openIndexes).filter(
+                (index) => index >= 0 && index < itemStates.length && !itemStates[index]?.disabled,
+            );
+
+            if (!this.#isMultiple() && nextOpenIndexes.length > 1) {
+                nextOpenIndexes.splice(1);
+            }
+
+            if (
+                !this.#isMultiple()
+                && nextOpenIndexes.length === 0
+                && !this.#isCollapsible()
+            ) {
+                const fallbackIndex = findFirstEnabledAccordionIndex(itemStates);
+
+                if (fallbackIndex !== -1) {
+                    nextOpenIndexes.push(fallbackIndex);
+                }
+            }
+
+            this.#openIndexes = new Set(nextOpenIndexes);
+        }
+
+        if (resetOpen || itemStates[this.#focusIndex]?.disabled || this.#focusIndex >= itemStates.length) {
+            this.#focusIndex = this.#getNextFocusableIndex(itemStates);
+        }
+
+        this.#applyState();
+    }
+
+    #applyState({ focus = false } = {}) {
+        const pairCount = Math.min(this.#triggers.length, this.#panels.length);
+        const baseId = this.id || this.#instanceId;
+
+        for (let index = 0; index < this.#triggers.length; index += 1) {
+            const trigger = this.#triggers[index];
+            const panel = index < pairCount ? this.#panels[index] : null;
+            const disabled = index >= pairCount || isAccordionItemDisabled(trigger);
+            const open = !disabled && this.#openIndexes.has(index);
+            const focusable = !disabled && index === this.#focusIndex;
+
+            if (!trigger.id) {
+                trigger.id = `${baseId}-trigger-${index + 1}`;
+            }
+
+            if (trigger instanceof HTMLButtonElementBase && !trigger.hasAttribute("type")) {
+                trigger.type = "button";
+            }
+
+            trigger.setAttribute("aria-expanded", String(open));
+            trigger.tabIndex = focusable ? 0 : -1;
+            trigger.toggleAttribute("data-open", open);
+
+            if (panel) {
+                if (!panel.id) {
+                    panel.id = `${baseId}-panel-${index + 1}`;
+                }
+
+                trigger.setAttribute("aria-controls", panel.id);
+            } else {
+                trigger.removeAttribute("aria-controls");
+            }
+        }
+
+        for (let index = 0; index < this.#panels.length; index += 1) {
+            const panel = this.#panels[index];
+            const trigger = this.#triggers[index];
+            const open = index < pairCount
+                && !isAccordionItemDisabled(trigger)
+                && this.#openIndexes.has(index);
+
+            if (!panel.id) {
+                panel.id = `${baseId}-panel-${index + 1}`;
+            }
+
+            panel.setAttribute("role", "region");
+
+            if (trigger?.id) {
+                panel.setAttribute("aria-labelledby", trigger.id);
+            } else {
+                panel.removeAttribute("aria-labelledby");
+            }
+
+            panel.hidden = !open;
+            panel.toggleAttribute("data-open", open);
+        }
+
+        if (focus && this.#focusIndex !== -1) {
+            this.#triggers[this.#focusIndex]?.focus();
+        }
+    }
+
+    #toggleIndex(index, { focus = false } = {}) {
+        const itemStates = this.#getItemStates();
+
+        if (index < 0 || index >= itemStates.length || itemStates[index]?.disabled) {
+            return;
+        }
+
+        const nextOpenIndexes = new Set(this.#openIndexes);
+        const isOpen = nextOpenIndexes.has(index);
+
+        if (this.#isMultiple()) {
+            if (isOpen) {
+                nextOpenIndexes.delete(index);
+            } else {
+                nextOpenIndexes.add(index);
+            }
+        } else if (isOpen) {
+            if (!this.#isCollapsible()) {
+                this.#focusIndex = index;
+                this.#applyState({ focus });
+                return;
+            }
+
+            nextOpenIndexes.clear();
+        } else {
+            nextOpenIndexes.clear();
+            nextOpenIndexes.add(index);
+        }
+
+        this.#openIndexes = nextOpenIndexes;
+        this.#focusIndex = index;
+        this.#applyState({ focus });
+    }
+}
+
+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/components/basic-accordion/register.d.ts

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

package/components/basic-accordion/register.js

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

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

@@ -0,0 +1,36 @@
+export const DIALOG_TAG_NAME: "basic-dialog";
+
+/**
+ * Normalizes the root `data-backdrop-close` attribute into a boolean flag.
+ */
+export function normalizeDialogBackdropClose(
+    value?: string | null,
+): boolean;
+
+/**
+ * Normalizes unsupported or empty labels back to the default `"Dialog"`.
+ */
+export function normalizeDialogLabel(
+    value?: string | null,
+): string;
+
+/**
+ * Custom element that upgrades native `<dialog>` markup into a modal dialog
+ * flow with open and close triggers.
+ *
+ * Attributes:
+ * - `data-label`: fallback accessible name when the dialog has no title
+ * - `data-backdrop-close`: allows clicks on the dialog backdrop to close it
+ */
+export class DialogElement extends HTMLElement {
+    static observedAttributes: string[];
+    showModal(opener?: HTMLElement | null): boolean;
+    close(returnValue?: string): boolean;
+}
+
+/**
+ * Registers the `basic-dialog` custom element if it is not already defined.
+ */
+export function defineDialog(
+    registry?: CustomElementRegistry,
+): typeof DialogElement;