@lmfaole/basics 0.1.1 → 0.3.0

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
 
@@ -69,7 +224,6 @@ The element upgrades existing markup into an accessible tab interface without ad
 ### Attributes
 
 - `data-label`: sets the generated tablist's accessible name when the tablist does not already have `aria-label` or `aria-labelledby`. Defaults to `Faner`.
-- `data-orientation`: sets arrow-key behavior and mirrors `aria-orientation` on the tablist. Supported values are `horizontal` and `vertical`.
 - `data-activation`: chooses whether arrow-key focus changes also activate the panel. Supported values are `automatic` and `manual`.
 - `data-selected-index`: sets the initially selected tab by zero-based index. Defaults to the first enabled tab.
 
@@ -77,7 +231,7 @@ The element upgrades existing markup into an accessible tab interface without ad
 
 - Missing tab and panel ids are generated automatically.
 - `aria-selected`, `aria-controls`, `aria-labelledby`, `hidden`, and `data-selected` stay in sync with the active tab.
-- Click, `Home`, `End`, and orientation-aware arrow keys move between tabs.
+- Click, `ArrowLeft`, `ArrowRight`, `Home`, and `End` move between tabs.
 - Disabled tabs are skipped during keyboard navigation.
 - In `manual` mode, arrow keys move focus and `Enter` or `Space` activates the focused tab.
 
@@ -88,6 +242,142 @@ The element upgrades existing markup into an accessible tab interface without ad
 - Prefer `<button>` elements for tabs so click and keyboard activation stay native.
 - Keep layout and styling outside the package; the component only manages semantics, state, and keyboard behavior.
 
+## Basic Table
+
+```html
+<basic-table
+  data-caption="Bemanning per sprint"
+  data-description="Viser team, lokasjon og ledig kapasitet per sprint."
+  data-row-headers
+  data-row-header-column="2"
+>
+  <table>
+    <thead>
+      <tr>
+        <th>Statuskode</th>
+        <th>Team</th>
+        <th>Lokasjon</th>
+        <th>Ledige timer</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td>A1</td>
+        <td>Plattform</td>
+        <td>Oslo</td>
+        <td>18</td>
+      </tr>
+      <tr>
+        <td>B4</td>
+        <td>Designsystem</td>
+        <td>Trondheim</td>
+        <td>10</td>
+      </tr>
+    </tbody>
+  </table>
+</basic-table>
+
+<script type="module">
+  import "@lmfaole/basics/components/basic-table/register";
+</script>
+```
+
+The element upgrades a regular table with stronger accessible naming and header associations without imposing any styles.
+
+### Attributes
+
+- `data-caption`: generates a visible `<caption>` when the wrapped table does not already define one.
+- `data-column-headers`: promotes the first row to column headers when the author provides a plain table without a header row.
+- `data-description`: generates a hidden description and connects it with `aria-describedby`.
+- `data-label`: sets a fallback accessible name when the table has no caption, `aria-label`, or `aria-labelledby`. Defaults to `Tabell`.
+- `data-row-header-column`: sets which one-based body column should become the generated row header. Defaults to `1`.
+- `data-row-headers`: enables generated row headers in body rows. If `data-row-header-column` is present, row-header mode is enabled automatically.
+
+### Behavior
+
+- Preserves author-provided captions and only generates one when needed.
+- Can generate hidden helper text for extra context without requiring a separate authored description element.
+- Can promote a plain first row to column headers when consumers start from simple body-only markup.
+- Infers common `scope` values for header cells and assigns missing header ids.
+- Populates each data cell's `headers` attribute from the matching row and column headers.
+- Re-runs automatically when the wrapped table changes.
+
+### Markup Contract
+
+- Provide one descendant `<table>` inside the custom element.
+- Use real table sections and header cells where possible; the component strengthens semantics but does not replace the HTML table model.
+- Add `data-row-headers` when one body column identifies each row, and use `data-row-header-column` when that column is not the first one.
+- Add `data-column-headers` when you want the component to promote a plain first row instead of authoring a header row yourself.
+- Keep layout and styling outside the package; the component only manages semantics and accessibility metadata.
+
+## Basic Summary Table
+
+```html
+<basic-summary-table
+  data-caption="Prosjektsammendrag"
+  data-description="Viser timer og total kostnad for prosjektets leveranser."
+  data-row-headers
+  data-summary-columns="2,4"
+  data-total-label="Totalt"
+>
+  <table>
+    <thead>
+      <tr>
+        <th>Post</th>
+        <th>Timer</th>
+        <th>Sats</th>
+        <th>Kostnad</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td>Analyse</td>
+        <td>8</td>
+        <td>100</td>
+        <td>800</td>
+      </tr>
+      <tr>
+        <td>Implementasjon</td>
+        <td>12</td>
+        <td>120</td>
+        <td>1440</td>
+      </tr>
+    </tbody>
+  </table>
+</basic-summary-table>
+
+<script type="module">
+  import "@lmfaole/basics/components/basic-summary-table/register";
+</script>
+```
+
+The element upgrades a calculation-heavy table with an automatically maintained totals row in `<tfoot>`.
+
+### Attributes
+
+- `data-caption`: generates a visible `<caption>` when the wrapped table does not already define one.
+- `data-description`: generates hidden helper text and connects it with `aria-describedby`.
+- `data-label`: sets a fallback accessible name when the table has no caption, `aria-label`, or `aria-labelledby`. Defaults to `Tabell`.
+- `data-row-headers`: enables generated row headers in body rows.
+- `data-row-header-column`: sets which one-based body column should become the generated row header. Defaults to `1`.
+- `data-summary-columns`: chooses which one-based columns should be totalled in the generated footer row. If omitted, numeric body columns are inferred automatically.
+- `data-total-label`: sets the footer row label. Defaults to `Totalt`.
+- `data-locale`: passes a locale through to `Intl.NumberFormat` for generated footer totals.
+
+### Behavior
+
+- Inherits caption, description, row-header, and `headers` association behavior from `basic-table`.
+- Parses numbers from cell text and supports raw calculation values through `data-value` on individual body cells.
+- Generates or updates a totals row in `<tfoot>` without requiring consumers to author the footer manually.
+- Recalculates totals automatically when body rows or `data-value` attributes change.
+
+### Markup Contract
+
+- Provide one descendant `<table>` with line items in `<tbody>`.
+- Prefer a label column such as `Post` or `Kategori` and enable `data-row-headers` so each line item remains easy to navigate.
+- Use `data-value` on cells when the displayed text is formatted differently from the numeric value you want summed.
+- Keep layout and styling outside the package; the component only manages semantics, totals, and footer structure.
+
 ## Basic Toc
 
 ```html

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;