@lmfaole/basics 0.4.0 → 0.5.0

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

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

@@ -0,0 +1,89 @@
+# `basic-table`
+
+Accessible naming and header relationships for regular tables.
+
+## Register
+
+```js
+import "@lmfaole/basics/basic-components/basic-table/register";
+```
+
+## Example
+
+```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>Sprint</th>
+        <th>Ledige timer</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td>A1</td>
+        <td>Plattform</td>
+        <td>Oslo</td>
+        <td>14</td>
+        <td>18</td>
+      </tr>
+      <tr>
+        <td>B4</td>
+        <td>Designsystem</td>
+        <td>Trondheim</td>
+        <td>14</td>
+        <td>10</td>
+      </tr>
+      <tr>
+        <td>C2</td>
+        <td>Innsikt</td>
+        <td>Bergen</td>
+        <td>15</td>
+        <td>26</td>
+      </tr>
+    </tbody>
+  </table>
+</basic-table>
+```
+
+## Props
+
+| Prop | Description | Type | Default | Options |
+| --- | --- | --- | --- | --- |
+| `data-caption` | Generates a visible `<caption>` when the table does not already define one. | string | none | any string |
+| `data-column-headers` | Promotes the first row to column headers when the author provides a plain table without a header row. | boolean attribute | off | `present`, `omitted` |
+| `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-header-column` | One-based body column that should become the generated row header. | positive integer | `1` | positive integer |
+| `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` |
+
+## 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` |
+
+## Behavior
+
+- Preserves author-provided captions and only generates one when needed
+- Can generate hidden helper text for extra context
+- Can promote a plain first row to column headers
+- Assigns missing header ids and populates `headers` on data cells
+- Re-runs automatically when the wrapped table changes
+
+## Markup Contract
+
+- Provide one descendant `<table>`
+- Use real table sections and header cells where possible
+- Add `data-row-headers` when one body column identifies each row
+- Add `data-column-headers` only when you want the component to promote a plain first row
+- Keep layout and styling outside the package

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-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/{components → basic-components}/basic-toast/index.d.ts

@@ -49,6 +49,9 @@ export function normalizeToastOpen(
  * 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[];