@lmfaole/basics 0.4.0 → 0.5.0

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

@@ -0,0 +1,53 @@
+# `basic-accordion`
+
+Coordinates direct child `<details>` items into an accordion.
+
+## Register
+
+```js
+import "@lmfaole/basics/basic-components/basic-accordion/register";
+```
+
+## Example
+
+```html
+<basic-accordion>
+  <details open>
+    <summary>Oversikt</summary>
+    <p>Viser en kort oppsummering.</p>
+  </details>
+
+  <details>
+    <summary>Implementasjon</summary>
+    <p>Viser implementasjonsdetaljer.</p>
+  </details>
+</basic-accordion>
+```
+
+## Props
+
+| Prop | Description | Type | Default | Options |
+| --- | --- | --- | --- | --- |
+| `data-multiple` | Allows more than one accordion item to stay open at the same time. | boolean attribute | off | `present`, `omitted` |
+| `data-collapsible` | Allows the last open item in single-open mode to close. | boolean attribute | off | `present`, `omitted` |
+
+## Item Hooks
+
+| Hook | Description | Type | Default | Options |
+| --- | --- | --- | --- | --- |
+| `open` on a child `<details>` | Sets an item's initial expanded state before the accordion normalizes it. | boolean attribute | closed | `present`, `omitted` |
+| `data-disabled` on a child `<details>` | Removes the item from toggle behavior and arrow-key navigation. | boolean attribute | off | `present`, `omitted` |
+
+## Behavior
+
+- Preserves native `details` and `summary` semantics
+- Keeps `data-open` in sync with the normalized open state
+- Supports `ArrowUp`, `ArrowDown`, `Home`, and `End` between enabled summaries
+- In single-open mode, keeps one enabled item open unless `data-collapsible` is set
+
+## Markup Contract
+
+- Provide direct child `<details>` items, each with a first-child `<summary>`
+- Add `open` to any item that should start expanded
+- Add `data-disabled` to a `<details>` item when it should be skipped by arrow-key navigation and blocked from toggling
+- Keep layout and styling outside the package

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

@@ -175,13 +175,9 @@ export class AccordionElement extends HTMLElementBase {
             return;
         }
 
-        if (
-            !this.#isMultiple()
-            && !this.#isCollapsible()
-            && itemStates[summaryIndex]?.open
-            && getOpenAccordionIndexes(itemStates).length === 1
-        ) {
+        if (!this.#isMultiple()) {
             event.preventDefault();
+            this.#toggleItem(summaryIndex, itemStates);
         }
     };
 
@@ -215,21 +211,7 @@ export class AccordionElement extends HTMLElementBase {
             case " ":
             case "Enter":
                 event.preventDefault();
-
-                if (itemStates[currentIndex]?.disabled) {
-                    return;
-                }
-
-                if (
-                    !this.#isMultiple()
-                    && !this.#isCollapsible()
-                    && itemStates[currentIndex]?.open
-                    && getOpenAccordionIndexes(itemStates).length === 1
-                ) {
-                    return;
-                }
-
-                this.#items[currentIndex].details.open = !this.#items[currentIndex].details.open;
+                this.#toggleItem(currentIndex, itemStates);
                 return;
             default:
                 return;
@@ -338,22 +320,7 @@ export class AccordionElement extends HTMLElementBase {
             }
         }
 
-        const openIndexSet = new Set(openIndexes);
-
-        this.#isSyncingState = true;
-
-        try {
-            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 (details.open !== open) {
-                    details.open = open;
-                }
-            }
-        } finally {
-            this.#isSyncingState = false;
-        }
+        this.#applyOpenState(openIndexes, itemStates);
     }
 
     #applyState() {
@@ -376,6 +343,61 @@ export class AccordionElement extends HTMLElementBase {
             }
         }
     }
+
+    #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) {

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-carousel/README.md

@@ -0,0 +1,108 @@
+# `basic-carousel`
+
+Named carousel regions built around a native scroll-snap track.
+
+## Register
+
+```js
+import "@lmfaole/basics/basic-components/basic-carousel/register";
+```
+
+## Example
+
+```html
+<basic-carousel
+  data-label="Featured stories"
+  data-controls="both"
+  data-snapping="center"
+>
+  <div data-carousel-track>
+    <article>
+      <h2>Launch Week</h2>
+      <p>Three product updates shipping across the design system.</p>
+    </article>
+
+    <article data-carousel-marker-label="Go to the accessibility slide">
+      <h2>Accessibility</h2>
+      <p>Keyboard and announcement details for the next release.</p>
+    </article>
+
+    <article>
+      <h2>Change Freeze Window</h2>
+      <p>Friday deployment holds and rollback owners are published for the April migration.</p>
+    </article>
+
+    <article>
+      <h2>Signup Funnel Feedback</h2>
+      <p>Eight research sessions highlighted friction around plan limits and account handoff.</p>
+    </article>
+
+    <article>
+      <h2>Tokens</h2>
+      <p>New surface and border tokens for interaction states.</p>
+    </article>
+
+    <article>
+      <h2>Migration Guides Updated</h2>
+      <p>Upgrade notes now include copy-paste examples and QA checklists for current component consumers.</p>
+    </article>
+
+    <article>
+      <h2>Bundle Audit Review</h2>
+      <p>A new audit flags duplicate helper code across package entry points and the next trim targets.</p>
+    </article>
+
+    <article>
+      <h2>Permission Model Review</h2>
+      <p>Security notes now spell out which stories need elevated browser APIs and which ones stay sandbox-safe.</p>
+    </article>
+
+    <article>
+      <h2>Pilot Teams Onboarded</h2>
+      <p>Three product squads have moved their prototypes onto the package and started filing integration feedback.</p>
+    </article>
+
+    <article>
+      <h2>Regression Sweep</h2>
+      <p>A targeted browser sweep caught contrast regressions, stale labels, and one broken close action before release cut.</p>
+    </article>
+  </div>
+</basic-carousel>
+```
+
+Import the optional starter carousel CSS when you want native `::scroll-button()` and `::scroll-marker` controls where the browser supports them.
+
+## Props
+
+| Prop | Description | Type | Default | Options |
+| --- | --- | --- | --- | --- |
+| `data-label` | Accessible name for the carousel region when no own `aria-label` or `aria-labelledby` is present. | string | `Carousel` | any string |
+| `data-controls` | Chooses which native scroll controls to expose when the browser supports them. | string | `both` | `both`, `markers`, `arrows`, `none` |
+| `data-snapping` | Chooses where each slide snaps within the scrollport and where `scrollToItem()` aligns it. | string | `center` | `start`, `center`, `end` |
+
+## Markup Hooks
+
+| Hook | Description | Type | Default | Options |
+| --- | --- | --- | --- | --- |
+| `data-carousel-track` | Marks the scroll container that owns the slides and native CSS controls. | descendant container attribute | required | present on one descendant scroll container |
+| direct children of `[data-carousel-track]` | Each direct child becomes one carousel slide and one generated scroll marker. | descendant item | required | present on one or more direct child elements |
+| `data-carousel-marker-label` | Optional per-slide label used for the generated marker's accessible name. | string attribute on a direct slide child | auto-generated | any string |
+
+## Behavior
+
+- Applies `role="region"` and a fallback accessible label on the root element
+- Normalizes `data-controls` to `both`, `markers`, `arrows`, or `none`
+- Normalizes `data-snapping` to `start`, `center`, or `end`
+- Annotates each slide with generated marker text and marker labels for CSS `content: attr(...)`
+- Exposes `refresh()` when the slide structure changes after connection
+- Exposes `scrollToItem(index, options)` for programmatic navigation
+
+## Markup Contract
+
+- Provide one descendant element with `data-carousel-track`
+- Keep each slide as a direct child of that track
+- Add your own slide semantics inside each item, for example `article`, `li`, or `section`
+- Use `data-controls="none"` for no generated controls, `data-controls="markers"` for numbered markers only, `data-controls="arrows"` for arrows only, or `data-controls="both"` for both controls
+- Use `data-snapping="start"`, `center`, or `end` to align the active slide consistently
+- Import starter CSS if you want generated scroll buttons and scroll markers
+- Browsers without native scroll controls still get the scroll-snap track and manual scrolling

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

@@ -0,0 +1,73 @@
+export const CAROUSEL_TAG_NAME: "basic-carousel";
+export type CarouselControls = "both" | "markers" | "arrows" | "none";
+export type CarouselSnapping = "start" | "center" | "end";
+
+export interface CarouselScrollOptions {
+    behavior?: ScrollBehavior | null;
+    snapping?: CarouselSnapping | string | null;
+}
+
+/**
+ * Normalizes unsupported or empty labels back to the default `"Carousel"`.
+ */
+export function normalizeCarouselLabel(
+    value?: string | null,
+): string;
+
+/**
+ * Normalizes carousel controls to `"both"`, `"markers"`, `"arrows"`, or `"none"`.
+ */
+export function normalizeCarouselControls(
+    value?: string | null,
+): CarouselControls;
+
+/**
+ * Normalizes scroll behaviors to `"auto"` or `"smooth"`.
+ */
+export function normalizeCarouselScrollBehavior(
+    value?: string | null,
+): ScrollBehavior;
+
+/**
+ * Normalizes snap positions to `"start"`, `"center"`, or `"end"`.
+ */
+export function normalizeCarouselSnapping(
+    value?: string | null,
+): CarouselSnapping;
+
+/**
+ * Clamps a requested item index into the available carousel range.
+ */
+export function clampCarouselIndex(
+    index: number,
+    itemCount: number,
+): number;
+
+/**
+ * Custom element that upgrades a scroll-snap track into a named carousel region
+ * and annotates each slide for CSS-native scroll buttons and markers.
+ *
+ * Attributes:
+ * - `data-label`: fallback accessible name for the carousel region
+ * - `data-controls`: show generated markers, arrows, both, or no generated controls where supported
+ * - `data-snapping`: align slides to the start, center, or end of the scrollport
+ *
+ * Descendant hooks:
+ * - one `[data-carousel-track]` scroll container
+ * - direct child items inside that track
+ * - optional `data-carousel-marker-label` on each item for custom marker names
+ */
+export class CarouselElement extends HTMLElement {
+    static observedAttributes: string[];
+    get track(): HTMLElement | null;
+    get items(): HTMLElement[];
+    refresh(): number;
+    scrollToItem(index: number, options?: CarouselScrollOptions): boolean;
+}
+
+/**
+ * Registers the `basic-carousel` custom element if it is not already defined.
+ */
+export function defineCarousel(
+    registry?: CustomElementRegistry,
+): typeof CarouselElement;

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

@@ -0,0 +1,255 @@
+const HTMLElementBase = globalThis.HTMLElement ?? class {};
+
+export const CAROUSEL_TAG_NAME = "basic-carousel";
+
+const DEFAULT_LABEL = "Carousel";
+const DEFAULT_CONTROLS = "both";
+const DEFAULT_SNAPPING = "center";
+const TRACK_SELECTOR = "[data-carousel-track]";
+const MANAGED_LABEL_ATTRIBUTE = "data-basic-carousel-managed-label";
+const MANAGED_READY_ATTRIBUTE = "data-basic-carousel-ready";
+
+let nextCarouselInstanceId = 1;
+
+function collectOwnedElements(root, scope, selector) {
+    return Array.from(scope.querySelectorAll(selector)).filter(
+        (element) => element instanceof HTMLElementBase && element.closest(CAROUSEL_TAG_NAME) === root,
+    );
+}
+
+function collectCarouselItems(track) {
+    return Array.from(track.children).filter(
+        (element) => element instanceof HTMLElementBase,
+    );
+}
+
+function normalizeMarkerLabel(value, index, total) {
+    const normalized = value?.trim();
+
+    if (normalized) {
+        return normalized;
+    }
+
+    return `Go to slide ${index} of ${total}`;
+}
+
+export function normalizeCarouselLabel(value) {
+    return value?.trim() || DEFAULT_LABEL;
+}
+
+export function normalizeCarouselControls(value) {
+    const normalized = value?.trim().toLowerCase();
+
+    if (normalized === "none") {
+        return "none";
+    }
+
+    if (
+        normalized === "markers"
+        || normalized === "numbers"
+        || normalized === "number-buttons"
+    ) {
+        return "markers";
+    }
+
+    if (normalized === "arrows") {
+        return "arrows";
+    }
+
+    return DEFAULT_CONTROLS;
+}
+
+export function normalizeCarouselScrollBehavior(value) {
+    const normalized = value?.trim().toLowerCase();
+
+    return normalized === "smooth" ? "smooth" : "auto";
+}
+
+export function normalizeCarouselSnapping(value) {
+    const normalized = value?.trim().toLowerCase();
+
+    if (normalized === "start" || normalized === "end") {
+        return normalized;
+    }
+
+    return DEFAULT_SNAPPING;
+}
+
+export function clampCarouselIndex(index, itemCount) {
+    if (!Number.isInteger(index) || itemCount <= 0) {
+        return -1;
+    }
+
+    return Math.min(Math.max(index, 0), itemCount - 1);
+}
+
+function clampScrollOffset(offset, maxOffset) {
+    return Math.min(Math.max(offset, 0), Math.max(maxOffset, 0));
+}
+
+function getItemInlineMetrics(track, item) {
+    const trackRect = track.getBoundingClientRect?.();
+    const itemRect = item.getBoundingClientRect?.();
+
+    if (trackRect?.width > 0 && itemRect?.width > 0) {
+        const start = itemRect.left - trackRect.left + track.scrollLeft;
+
+        return {
+            start,
+            width: itemRect.width,
+        };
+    }
+
+    return {
+        start: item.offsetLeft || 0,
+        width: item.offsetWidth || track.clientWidth || 0,
+    };
+}
+
+function getTrackViewportWidth(track) {
+    return track.clientWidth || track.getBoundingClientRect?.().width || 0;
+}
+
+function getScrollOffsetForItem(track, item, snapping) {
+    const viewportWidth = getTrackViewportWidth(track);
+    const { start, width } = getItemInlineMetrics(track, item);
+
+    if (snapping === "end") {
+        return start - (viewportWidth - width);
+    }
+
+    if (snapping === "center") {
+        return start - ((viewportWidth - width) / 2);
+    }
+
+    return start;
+}
+
+export class CarouselElement extends HTMLElementBase {
+    static observedAttributes = ["data-controls", "data-label", "data-snapping"];
+
+    #instanceId = `${CAROUSEL_TAG_NAME}-${nextCarouselInstanceId++}`;
+    #track = null;
+    #items = [];
+
+    connectedCallback() {
+        this.refresh();
+    }
+
+    attributeChangedCallback() {
+        this.#applyState();
+    }
+
+    get track() {
+        return this.#track;
+    }
+
+    get items() {
+        return [...this.#items];
+    }
+
+    refresh() {
+        this.#track = collectOwnedElements(this, this, TRACK_SELECTOR)[0] ?? null;
+        this.#items = this.#track ? collectCarouselItems(this.#track) : [];
+        this.#applyState();
+        return this.#items.length;
+    }
+
+    scrollToItem(index, options = {}) {
+        const nextIndex = clampCarouselIndex(index, this.#items.length);
+        const item = nextIndex === -1 ? null : this.#items[nextIndex];
+        const track = this.#track;
+
+        if (!(item instanceof HTMLElementBase) || !(track instanceof HTMLElementBase)) {
+            return false;
+        }
+
+        const behavior = normalizeCarouselScrollBehavior(options.behavior);
+        const snapping = normalizeCarouselSnapping(options.snapping ?? this.getAttribute("data-snapping"));
+        const viewportWidth = getTrackViewportWidth(track);
+        const maxOffset = Math.max(track.scrollWidth - viewportWidth, 0);
+        const left = clampScrollOffset(getScrollOffsetForItem(track, item, snapping), maxOffset);
+
+        if (typeof track.scrollTo === "function") {
+            track.scrollTo({
+                left,
+                behavior,
+            });
+        } else {
+            track.scrollLeft = left;
+        }
+
+        return true;
+    }
+
+    #applyState() {
+        const baseId = this.id || this.#instanceId;
+        const controls = normalizeCarouselControls(this.getAttribute("data-controls"));
+        const snapping = normalizeCarouselSnapping(this.getAttribute("data-snapping"));
+
+        if (this.#track instanceof HTMLElementBase && !this.#track.id) {
+            this.#track.id = `${baseId}-track`;
+        }
+
+        this.dataset.basicCarouselControls = controls;
+        this.dataset.basicCarouselSnapping = snapping;
+        this.toggleAttribute(MANAGED_READY_ATTRIBUTE, this.#track instanceof HTMLElementBase && this.#items.length > 0);
+        this.setAttribute("role", "region");
+        this.#syncAccessibleLabel();
+
+        const total = this.#items.length;
+
+        for (const [index, item] of this.#items.entries()) {
+            item.dataset.basicCarouselMarker = String(index + 1);
+            item.dataset.basicCarouselMarkerLabel = normalizeMarkerLabel(
+                item.getAttribute("data-carousel-marker-label"),
+                index + 1,
+                total,
+            );
+
+            if (!item.id) {
+                item.id = `${baseId}-item-${index + 1}`;
+            }
+        }
+    }
+
+    #syncAccessibleLabel() {
+        const nextLabel = normalizeCarouselLabel(this.getAttribute("data-label"));
+        const hasManagedLabel = this.hasAttribute(MANAGED_LABEL_ATTRIBUTE);
+
+        if (hasManagedLabel && this.getAttribute("aria-label") !== nextLabel) {
+            this.removeAttribute("aria-label");
+            this.removeAttribute(MANAGED_LABEL_ATTRIBUTE);
+        }
+
+        if (this.hasAttribute("aria-labelledby")) {
+            if (hasManagedLabel) {
+                this.removeAttribute("aria-label");
+                this.removeAttribute(MANAGED_LABEL_ATTRIBUTE);
+            }
+
+            return;
+        }
+
+        const hasOwnAriaLabel = this.hasAttribute("aria-label") && !hasManagedLabel;
+
+        if (hasOwnAriaLabel) {
+            return;
+        }
+
+        this.setAttribute("aria-label", nextLabel);
+        this.setAttribute(MANAGED_LABEL_ATTRIBUTE, "");
+    }
+}
+
+export function defineCarousel(registry = globalThis.customElements) {
+    if (!registry?.get || !registry?.define) {
+        return CarouselElement;
+    }
+
+    if (!registry.get(CAROUSEL_TAG_NAME)) {
+        registry.define(CAROUSEL_TAG_NAME, CarouselElement);
+    }
+
+    return CarouselElement;
+}

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

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