@lmfaole/basics 0.3.0 → 0.5.0

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();

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

@@ -0,0 +1,57 @@
+# `basic-dialog`
+
+Modal dialog flow built on native `<dialog>`.
+
+## Register
+
+```js
+import "@lmfaole/basics/basic-components/basic-dialog/register";
+```
+
+## Example
+
+```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>
+```
+
+## Props
+
+| Prop | Description | Type | Default | Options |
+| --- | --- | --- | --- | --- |
+| `data-label` | Fallback accessible name when the dialog has no `aria-label`, `aria-labelledby`, or `[data-dialog-title]`. | string | `Dialog` | any string |
+| `data-backdrop-close` | Allows clicks on the dialog backdrop to close the modal. | boolean attribute | off | `present`, `omitted` |
+
+## Markup Hooks
+
+| Hook | Description | Type | Default | Options |
+| --- | --- | --- | --- | --- |
+| `data-dialog-open` | Opens the managed dialog. | descendant control attribute | none | present on a descendant button or control |
+| `data-dialog-panel` | Marks the native dialog element managed by the component. | descendant `<dialog>` attribute | required | present on one descendant `<dialog>` |
+| `data-dialog-title` | Makes the visible heading the dialog's accessible name. | descendant heading attribute | none | present on a descendant heading |
+| `data-dialog-close` | Closes the dialog when activated. | descendant control attribute | none | present on a descendant button or control |
+| `data-dialog-close-value` | Return value passed to `dialog.close()` when used on a `[data-dialog-close]` control. | string | empty string | any string |
+
+## Behavior
+
+- Uses native modal dialog behavior via `showModal()`
+- Restores focus to the opener on close
+- Lets the platform handle modal focus and `Esc` dismissal
+- `[data-dialog-close]` can optionally set `data-dialog-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]` when the heading should become the accessible name
+- Keep layout and styling outside the package

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

@@ -0,0 +1,56 @@
+# `basic-popover`
+
+Non-modal overlay behavior using the Popover API.
+
+## Register
+
+```js
+import "@lmfaole/basics/basic-components/basic-popover/register";
+```
+
+## Example
+
+```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>
+```
+
+## Props
+
+| Prop | Description | Type | Default | Options |
+| --- | --- | --- | --- | --- |
+| `data-label` | Fallback accessible name when the popover has no `aria-label`, `aria-labelledby`, or `[data-popover-title]`. | string | `Popover` | any string |
+| `data-anchor-trigger` | Uses the opener as the popover's implicit anchor. | boolean attribute | off | `present`, `omitted` |
+| `data-position-area` | Default anchored placement used when `data-anchor-trigger` is enabled. | CSS `position-area` token | `bottom` | any CSS `position-area` token such as `bottom`, `top`, `left`, `right`, `block-start`, `block-end`, `inline-start`, or `inline-end` |
+| `data-position-try-fallbacks` | Overrides the built-in fallback sequence used when the default placement would overflow. | comma-separated string list | derived from `data-position-area` | comma-separated CSS fallback list |
+
+## Markup Hooks
+
+| Hook | Description | Type | Default | Options |
+| --- | --- | --- | --- | --- |
+| `data-popover-open` | Toggles the popover open state. | descendant control attribute | none | present on a descendant button or control |
+| `data-popover-panel` | Marks the overlay panel managed by the component. | descendant element attribute | required | present on one descendant element |
+| `data-popover-title` | Makes the visible heading the popover's accessible name. | descendant heading attribute | none | present on a descendant heading |
+| `data-popover-close` | Closes the popover when activated. | descendant control attribute | none | present on a descendant button or control |
+
+## 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 when dismissal should return to the opener
+- Supports anchored placement when `data-anchor-trigger` is set
+
+## Markup Contract
+
+- Provide one descendant `[data-popover-panel]`
+- Use `[data-popover-open]` on buttons that should toggle the panel
+- Use `[data-popover-title]` when the heading should become the accessible name
+- Use `[data-popover-close]` when the panel should expose an explicit dismiss action
+- Keep layout and styling outside the package

package/basic-components/basic-summary-table/README.md

@@ -0,0 +1,93 @@
+# `basic-summary-table`
+
+Tables with generated totals in `<tfoot>`.
+
+## Register
+
+```js
+import "@lmfaole/basics/basic-components/basic-summary-table/register";
+```
+
+## Example
+
+```html
+<basic-summary-table
+  data-caption="Månedlig kostnadsoversikt"
+  data-description="Viser antall og summerte beløp for faste kostnader."
+  data-row-headers
+  data-summary-columns="2,4"
+  data-total-label="Totalt"
+  data-locale="nb-NO"
+>
+  <table>
+    <thead>
+      <tr>
+        <th>Post</th>
+        <th>Antall</th>
+        <th>Enhetspris</th>
+        <th>Beløp</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td>Basisabonnement</td>
+        <td>12</td>
+        <td>49,00 kr</td>
+        <td>588,00 kr</td>
+      </tr>
+      <tr>
+        <td>Supportavtale</td>
+        <td>1</td>
+        <td>299,00 kr</td>
+        <td>299,00 kr</td>
+      </tr>
+      <tr>
+        <td>Lagringstillegg</td>
+        <td>4</td>
+        <td>120,00 kr</td>
+        <td>480,00 kr</td>
+      </tr>
+    </tbody>
+  </table>
+</basic-summary-table>
+```
+
+## Props
+
+| Prop | Description | Type | Default | Options |
+| --- | --- | --- | --- | --- |
+| `data-caption` | Generates a visible `<caption>` when the wrapped table does not already define one. | string | none | any string |
+| `data-description` | Generates hidden helper text and connects it with `aria-describedby`. | string | none | any string |
+| `data-label` | Fallback accessible name when the table has no caption, `aria-label`, or `aria-labelledby`. | string | `Tabell` | any string |
+| `data-row-headers` | Enables generated row headers in body rows. This is also enabled automatically when `data-row-header-column` is present. | boolean attribute | off | `present`, `omitted` |
+| `data-row-header-column` | Chooses which one-based body column becomes the row header. | positive integer | `1` | positive integer |
+| `data-summary-columns` | Selects which columns are totalled in the generated footer row. | comma-separated integer list | infer numeric body columns | comma-separated one-based column indexes |
+| `data-total-label` | Footer row label used for the generated totals row. | string | `Totalt` | any string |
+| `data-locale` | Locale passed to generated footer totals. | locale string | browser default | any `Intl.NumberFormat` locale string |
+
+## Starter Styling Prop
+
+| Prop | Description | Type | Default | Options |
+| --- | --- | --- | --- | --- |
+| `data-zebra` | Optional starter-CSS hook that adds alternating body-row backgrounds when you import `basic-styling`. | boolean attribute | off | `present`, `omitted` |
+| `data-separators` | Optional starter-CSS hook that chooses whether interior dividers appear between rows, columns, or both when you import `basic-styling`. | enum string | `rows` | `rows`, `columns`, `both` |
+
+## Cell Hooks
+
+| Hook | Description | Type | Default | Options |
+| --- | --- | --- | --- | --- |
+| `data-value` on a body cell | Raw numeric value used for calculations when the displayed text is formatted differently. | numeric string | uses the cell text | any parseable numeric string |
+
+## Behavior
+
+- Inherits caption, description, row-header, and `headers` association behavior from `basic-table`
+- Parses numbers from cell text and supports raw values through `data-value` on body cells
+- Generates and updates a totals row in `<tfoot>`
+- Recalculates when body rows or `data-value` attributes change
+
+## Markup Contract
+
+- Provide one descendant `<table>` with line items in `<tbody>`
+- Prefer a label column and enable `data-row-headers` so each row remains easy to navigate
+- Use `data-value` on cells when the displayed text differs from the numeric value you want summed
+- Keep layout and styling outside the package