@politiet/sheriff-web-components 2.13.0 → 2.14.0

package/dist/skill/references/components.md

@@ -1,6 +1,14 @@
 # Component Reference
 
-Full API for each SDS web component. All components support `size` (`"lg"` | `"md"` | `"sm"`, default `"md"`) unless noted otherwise.
+Full API for each SDS web component.
+
+Sizes used by components are `"lg"` | `"md"` | `"sm"` with default `"md"`, except:
+
+-   `sds-button` — defaults to `"lg"`
+-   `sds-heading` / `sds-text` — use `"xl" | "lg" | "md" | "sm" | "xs"`
+-   `sds-icon` — `"sm" | "md" | "lg"`
+
+`data-palette` works on every component and inherits from ancestor containers. Exceptions: `sds-alert` (own typed property, must be set on the element), `sds-tooltip` and `sds-environment-banner` (no palette support). See the `@politiet/sheriff-css-framework` skill for palette values.
 
 ---
 
@@ -33,9 +41,10 @@ Contextual alert/message banner. Source: `sds-alert.component.ts`.
 </sds-alert>
 ```
 
-**Props:** `variant` (`"primary"` | `"secondary"`, default `"primary"`), `size` (`"lg"` | `"md"` | `"sm"`), `removable-label` (string — shows close button on primary variant), `data-palette` (`"info"` | `"success"` | `"attention"` | `"danger"`, default `"info"`)
+**Props:** `variant` (`"primary"` | `"secondary"`, default `"primary"`), `size` (`"lg"` | `"md"` | `"sm"`, default `"md"`), `removable-label` (string — shows close button, **primary variant only**), `data-palette` (`"info"` | `"success"` | `"attention"` | `"danger"`, default `"info"`)
 **Slots:** `title` (heading element), `message` (`<p>`)
 **Events:** `sds-remove` (close button clicked)
+**Note:** `data-palette` also selects the status icon (info → `InformationSquareFill-aksel-filled`, success → `check_circle-material-filled`, attention → `warning-material-filled`, danger → `dangerous-material-filled`). Because it is a typed property rather than plain CSS, it must be set on the `sds-alert` itself — an ancestor `data-palette` will not reach it, and `warning` is not a valid value here.
 
 ---
 
@@ -49,9 +58,9 @@ Button or link-styled-as-button. Source: `sds-button.component.ts`.
 <sds-button variant="tertiary">Learn more</sds-button>
 <sds-button href="https://example.com" target="_blank">Visit site</sds-button>
 
-<!-- Icon-only -->
-<sds-button variant="primary" icon>
-	<sds-icon name="search-material-outlined" label="Search"></sds-icon>
+<!-- Icon-only: accessible name via `label` on the button -->
+<sds-button variant="primary" icon label="Search">
+	<sds-icon name="search-material-outlined"></sds-icon>
 </sds-button>
 
 <!-- With leading/trailing icons -->
@@ -67,12 +76,20 @@ Button or link-styled-as-button. Source: `sds-button.component.ts`.
 
 <sds-button variant="primary" loading>Saving...</sds-button>
 <sds-button variant="primary" type="submit">Submit</sds-button>
+
+<!-- On a dark or palette-coloured surface -->
+<div class="sds-color-accent-action-default sds-spacing-p-md">
+	<sds-button inverted>Inverted</sds-button>
+</div>
 ```
 
-**Props:** `variant` (`"primary"` | `"secondary"` | `"tertiary"`, default `"primary"`), `size` (`"lg"` | `"md"` | `"sm"`, default `"lg"`), `type` (`"button"` | `"submit"` | `"reset"`, default `"button"`), `disabled`, `loading`, `icon` (compact icon-only mode), `href`, `target`, `name`, `value`, `form`
+**Props:** `variant` (`"primary"` | `"secondary"` | `"tertiary"`, default `"primary"`), `size` (`"lg"` | `"md"` | `"sm"`, default `"lg"`), `type` (`"button"` | `"submit"` | `"reset"`, default `"button"`), `disabled`, `loading`, `icon` (compact icon-only mode), `inverted` (for dark/coloured backgrounds), `label` (sets `aria-label` on the internal button — use for icon-only buttons), `href`, `target`, `name`, `value`, `form`
+**Dialog targeting:** `command` (`"show-modal"` | `"close"` | `"request-close"`) + `commandfor` (dialog `id`). Legacy aliases `data-command` / `data-commandfor` also work.
+**Popover targeting:** `popovertarget` (popover `id`), `popovertargetaction` (`"show"` | `"hide"` | `"toggle"`)
 **Slots:** default (label), `before`, `after`
 **Events:** `click`, `submit`, `reset`
 **Danger pattern:** `<sds-button variant="primary" data-palette="danger">Delete</sds-button>`
+**Notes:** Form-associated. When `href` is set the component renders an `<a>` instead of a `<button>`, so `type`, `disabled`, `loading`, and `label` do not apply. `loading` replaces the `before` and `after` slots with a spinner.
 
 ---
 
@@ -93,8 +110,8 @@ Content container card. Renders as `<a>` with arrow icon when `link` is set.
 ```
 
 **Props:** `link` (URL — renders as anchor)
-**Slots:** `heading` (`<h2>`–`<h6>` only), `text` (`<p>` only, no nested elements)
-**Note:** Slots enforce strict content validation — use native heading/paragraph elements.
+**Slots:** `heading` (one of `<h2>`–`<h6>`), `text` (`<p>` only, no nested elements)
+**Note:** Slot content is validated on render — invalid content still renders but logs a `console.warn`. Use native heading/paragraph elements.
 
 ---
 
@@ -108,10 +125,17 @@ Single checkbox input.
 <sds-checkbox label="Remember me" name="remember" help-text="Stay logged in for 30 days"></sds-checkbox>
 <sds-checkbox label="Required option" name="required" error></sds-checkbox>
 <sds-checkbox label="Locked choice" name="locked" checked readonly></sds-checkbox>
+
+<!-- Label with markup -->
+<sds-checkbox name="terms">
+	<span slot="label">I accept the <a href="/terms">terms</a></span>
+</sds-checkbox>
 ```
 
 **Props:** `label`, `name`, `value`, `checked`, `disabled`, `required`, `readonly`, `error` (boolean — use checkbox-group for text error messages), `help-text`, `size`
+**Slots:** `label` (alternative to the `label` attribute)
 **Events:** `change`, `focus`, `blur`
+**Note:** Form-associated. Setting `disabled` explicitly makes the checkbox self-controlled — a parent `sds-checkbox-group` will no longer override it.
 
 ---
 
@@ -154,11 +178,18 @@ Form-associated chip/pill. Two variants: `selectable` (toggle) and `removable` (
 	Locked
 	<sds-icon size="sm" name="lock-material-outlined"></sds-icon>
 </sds-chip>
+
+<!-- Palette theming (works on the chip or any ancestor) -->
+<sds-chip data-palette="danger" name="risk" value="high">High risk</sds-chip>
+<div data-palette="success">
+	<sds-chip name="status" value="ok" checked>Approved</sds-chip>
+</div>
 ```
 
-**Props:** `variant` (`"selectable"` | `"removable"`, default `"selectable"`), `checked`, `name`, `value`, `disabled`, `readonly`, `size`
+**Props:** `variant` (`"selectable"` | `"removable"`, default `"selectable"`), `checked`, `name`, `value`, `disabled`, `readonly`, `size`, `data-palette`
 **Slots:** default (label, can include `sds-icon`)
 **Events:** `change` (selectable), `sds-remove` (removable)
+**Note:** Form-associated — the chip submits `value` only while `checked`.
 
 ---
 
@@ -190,7 +221,41 @@ Expandable/collapsible accordion. Summary text is a slot.
 
 **Props:** `open`, `standalone` (rounded corners + border), `name` (exclusive accordion group)
 **Slots:** `summary` (always visible), default (expandable content)
-**Events:** `sds-toggle` (detail: `{ open: boolean }`)
+**Events:** `toggle` (detail: `{ open: boolean }`) — **not** `sds-toggle`
+
+---
+
+## sds-details-group
+
+Wraps sibling `sds-details` into one visually joined accordion. Set `name` to make the group exclusive — the group copies its `name` onto every child and closes the others when one opens.
+
+```html
+<sds-details-group>
+	<sds-details>
+		<span slot="summary">Hva er Sheriff?</span>
+		<p>Sheriff er politiet sitt designsystem</p>
+	</sds-details>
+	<sds-details>
+		<span slot="summary">Hvordan kommer jeg i gang?</span>
+		<p>Start med å lese dokumentasjonen.</p>
+	</sds-details>
+</sds-details-group>
+
+<sds-details-group outlined name="faq">
+	<sds-details>
+		<span slot="summary">Question 1</span>
+		<p>Answer 1</p>
+	</sds-details>
+	<sds-details>
+		<span slot="summary">Question 2</span>
+		<p>Answer 2</p>
+	</sds-details>
+</sds-details-group>
+```
+
+**Props:** `outlined` (adds a border around the group), `name` (exclusive group — propagates to children)
+**Slots:** default (`sds-details` children)
+**Note:** Do not set `name` on the children when using a group `name`; the group overwrites it.
 
 ---
 
@@ -199,21 +264,105 @@ Expandable/collapsible accordion. Summary text is a slot.
 Modal/dialog wrapping native `<dialog>`.
 
 ```html
-<sds-dialog modal closedby="any">
+<sds-button command="show-modal" commandfor="confirm">Delete…</sds-button>
+
+<sds-dialog id="confirm" modal closedby="any">
 	<sds-heading level="h2" size="md" slot="header">Confirm Action</sds-heading>
 	<sds-text>Are you sure you want to proceed?</sds-text>
-	<div slot="footer" style="display: flex; gap: var(--sds-spacing-2xs);">
-		<sds-button size="md">Confirm</sds-button>
-		<sds-button size="md" variant="secondary" data-command="close">Cancel</sds-button>
+	<div slot="footer" class="sds-stack-x-2xs">
+		<sds-button size="md" data-palette="danger">Confirm</sds-button>
+		<sds-button size="md" variant="secondary" command="close">Cancel</sds-button>
 	</div>
 </sds-dialog>
 ```
 
-**Props:** `open`, `modal`, `closedby` (`"none"` | `"closerequest"` | `"any"`, default `"closerequest"`), `close-button-label` (default `"Lukk dialogvindu"`, empty string hides button)
+**Props:** `open`, `modal`, `closedby` (`"none"` | `"closerequest"` | `"any"`, default `"closerequest"`), `close-button-label` (default `"Lukk dialogvindu"`, empty string hides the built-in close button)
 **Slots:** `header`, default (body), `footer`
-**Events:** `close`
-**Methods:** `show()`, `showModal()`, `close()`
-**Note:** `data-command="close"` on any inner button closes the dialog.
+**Events:** `close`, `cancel` (fires before the dialog closes via ESC, outside click or `requestClose()`; call `preventDefault()` to keep it open). `sds-close` still fires but is **deprecated** — listening for it logs a console warning and it is removed in the next major.
+**Methods:** `show()`, `showModal()` (also sets `modal`), `close()`, `requestClose()`
+**Notes:**
+
+-   `command="close"` or `data-command="close"` on any button inside the dialog closes it, no `commandfor` needed.
+-   `command="show-modal"` requires `commandfor="{dialog id}"` and wires `aria-haspopup`/`aria-expanded`/`aria-controls` on the trigger.
+-   `closedby="any"` includes a Safari polyfill for outside clicks.
+-   An element in the default slot carrying `autofocus` receives focus once the open animation ends.
+-   `close` bubbles, so a listener on an outer dialog also receives it from a nested dialog. Check `event.target === event.currentTarget` when nesting. `cancel` does not bubble, matching the native event.
+
+---
+
+## sds-environment-banner
+
+Thin strip identifying the running environment and build, for internal apps. Source: `sds-environment-banner.component.ts`.
+
+```html
+<sds-environment-banner env="test" build="2026.9.1-rc3"></sds-environment-banner> <sds-environment-banner env="dev"></sds-environment-banner>
+```
+
+**Props:** `env` (`"opplaering"` | `"local"` | `"dev"` | `"test"` | `"stage"` | `"prod"`), `build` (free-text build identifier)
+**Slots:** none
+**Note:** Renders the Norwegian label for `env` (`opplaering` → "Opplæring"). Colors are fixed per environment — `data-palette` has no effect. Both props are optional; omitting `env` hides the label and omitting `build` hides the build text.
+
+---
+
+## sds-file-upload
+
+File picker with drag and drop and a built-in list of selected files. Form-associated. **Beta** — larger API changes may still happen.
+
+```html
+<sds-file-upload name="attachments" multiple accept=".pdf,image/*" max-size-in-bytes="10485760" file-limitation-text="PDF eller bilde, maks 10 MB">
+	<span slot="label">Vedlegg</span>
+</sds-file-upload>
+
+<sds-file-upload name="cv" variant="compact" size="sm" required>
+	<span slot="label">CV</span>
+</sds-file-upload>
+```
+
+**Props:** `name`, `label`, `accept` (same syntax as native: extensions, `image/*`, exact MIME types), `multiple`, `required`, `disabled`, `max-size-in-bytes`, `help-text`, `error-message`, `file-limitation-text`, `hide-file-list`, `variant` (`"default"` | `"compact"`), `size`
+**Slots:** `label` (alternative to the `label` attribute, wins if both are set). Without a label, the input is named "Velg fil" / "Velg filer".
+**Events:**
+
+-   `input`, `change` — the accepted selection changed (picked, dropped, removed or cleared). `input` fires right before `change`.
+-   `cancel` — the user closed the file picker without choosing anything. Not cancelable.
+-   `focus`, `blur`
+-   `sds-reject` — detail `{ rejected: { file, reason, errorCode }[] }`, `errorCode` is `"type-mismatch"` | `"too-large"`. `reason` is a Norwegian message.
+-   `sds-preview-ready` — detail `{ file, url }`, fired when an image or video thumbnail is ready.
+
+**Properties and methods:** `files` (`File[]`, read-only), `rejectedFiles` (`{ file, reason, errorCode }[]`, read-only), `value` (`C:\fakepath\…` of the first file; only `""` may be assigned, which clears, other values throw), `removeFile(file)`, `clear()`, `dismissRejected(file)`, `getPreviewUrl(file)`, `focus()`, `blur()`, `checkValidity()`, `reportValidity()`, `setCustomValidity(message)`
+**Notes:**
+
+-   Behaves like `<input type="file">`: a single-file selection always replaces the previous one, even if the new file is rejected. The same goes for `multiple`: every new selection replaces the previous files. Duplicates within a selection (same name, size and last modified) are dropped.
+-   Submits every accepted file under `name` as `FormData`, or an empty `File` when nothing is selected, like native. There is no `value` attribute to set, and no `readonly`.
+-   Constraint errors (`required`) use the native validation bubble. `setCustomValidity(message)` sets `error-message`.
+-   Don't call `URL.revokeObjectURL` on URLs from `getPreviewUrl()` or `sds-preview-ready` — the component cleans them up.
+-   Rejected files show in the built-in list with "Feil ved opplasting" and the `reason` as the error message.
+
+### sds-file-upload-item
+
+One file row: icon or thumbnail, name, size, a remove button and optional upload progress. Used by the built-in list, and for building your own list.
+
+**Props:** `file` (file name), `size-in-bytes`, `error-message`, `preview` (image URL), `uploaded-percent` (shows a progress bar while set), `uploaded-size-in-bytes`, `disabled`, `for` (`id` of the owning `sds-file-upload`)
+**Slots:** `actions-end` (extra buttons, placed before the remove button)
+**Events:** `sds-remove` (cancelable) — fired when the remove button is pressed.
+**Note:** Without `for`, listen for `sds-remove` and call `removeFile(file)` (or `dismissRejected(file)` for an item with `error-message`) on the upload yourself. With `for`, the item does that and removes itself from the DOM; `preventDefault()` on `sds-remove` cancels both. `disabled` doesn't reach buttons in `actions-end`, so disable those yourself, and include the file name in their labels (`label="Last ned rapport.pdf"`).
+
+### sds-file-upload-file-list
+
+List container (`role="list"`) for `sds-file-upload-item` children. No props or events.
+
+**Slots:** default (`sds-file-upload-item` children)
+
+Custom file list — set `hide-file-list` on the upload and render the items yourself, for example to show upload progress:
+
+```html
+<sds-file-upload id="docs" name="docs" multiple hide-file-list>
+	<span slot="label">Dokumenter</span>
+</sds-file-upload>
+
+<sds-file-upload-file-list>
+	<sds-file-upload-item for="docs" file="rapport.pdf" size-in-bytes="482133" uploaded-percent="40"></sds-file-upload-item>
+</sds-file-upload-file-list>
+```
 
 ---
 
@@ -227,7 +376,7 @@ Semantic heading. Source: `sds-heading.component.ts`.
 <sds-heading level="h2" data-palette="accent">Accent heading</sds-heading>
 ```
 
-**Props:** `level` (`"h1"`–`"h6"`, default `"h1"`), `size` (`"xl"` | `"lg"` | `"md"` | `"sm"` | `"xs"` — visual override)
+**Props:** `level` (`"h1"`–`"h6"`, default `"h1"`), `size` (`"xl"` | `"lg"` | `"md"` | `"sm"` | `"xs"` — visual override; `"l"`/`"m"`/`"s"` are deprecated v1 aliases)
 **Slots:** default
 
 ---
@@ -249,14 +398,38 @@ Dynamic SVG icon. Source: `sds-icon.component.ts`.
 </sds-icon>
 ```
 
-**Props:** `name` (`{icon}-{source}-{variant}`), `size` (`"sm"` | `"md"` | `"lg"`), `label` (sets `role="img"` + `aria-label`), `color`
+**Props:** `name` (`{icon}-{source}-{variant}`; typed as `string`, not the `IconName` union), `size` (`"sm"` | `"md"` | `"lg"`; `"s"`/`"m"` are deprecated aliases), `label` (sets `role="img"` + `aria-label`; omit for decorative icons), `color` (any CSS color, applied inline)
 **Slots:** default (custom `<svg>` — use instead of `name`)
+**Static methods:** `SDSIcon.setLoadLocal(boolean)`, `SDSIcon.registerResolver(fn)`
 **CSS vars:** `--sds-icon-size`, `--sds-icon-color`, `--sds-icon-display`
 
 For icon naming, loading, and resolvers, see `@politiet/sheriff-icons` package skill.
 
 ---
 
+## sds-internal-header
+
+App header for internal (non-public) applications. Renders the internal Sheriff mark plus optional app name and two content slots. Source: `sds-internal-header.component.ts`.
+
+```html
+<sds-internal-header app-name="Saksbehandling" home-href="/">
+	<nav slot="start">
+		<a href="/oversikt">Oversikt</a>
+		<a href="/oppgaver">Oppgaver</a>
+	</nav>
+	<div slot="end" class="sds-stack-x-3xs">
+		<sds-button inverted>Søk</sds-button>
+		<sds-button inverted variant="tertiary">Logg ut</sds-button>
+	</div>
+</sds-internal-header>
+```
+
+**Props:** `app-name` (title text), `home-href` (wraps the app name in a link to this URL)
+**Slots:** `start` (primary navigation), `end` (actions / user menu)
+**Note:** Renders a `<header>` internally, so do not wrap it in another `<header>`. Use `inverted` on nested `sds-button`s.
+
+---
+
 ## sds-loader
 
 Loading spinner with built-in `aria-label="Laster"`.
@@ -264,11 +437,18 @@ Loading spinner with built-in `aria-label="Laster"`.
 ```html
 <sds-loader></sds-loader>
 <sds-loader size="lg"></sds-loader>
-<sds-loader contrast></sds-loader>
-<sds-loader data-palette="accent"></sds-loader>
+
+<!-- On a palette-coloured surface -->
+<div data-palette="accent" class="sds-color-action-default sds-spacing-p-md">
+	<sds-loader></sds-loader>
+</div>
+
+<!-- Palette colours, plain background -->
+<sds-loader data-palette="accent" contrast></sds-loader>
 ```
 
-**Props:** `size`, `contrast` (for colored backgrounds)
+**Props:** `size`, `contrast`
+**Note:** With `data-palette` the spinner switches to the palette's _contrast_ colour, i.e. it is meant to sit **on** a palette-coloured surface. Add `contrast` to flip it back to the palette's action colour for a plain background.
 
 ---
 
@@ -283,9 +463,71 @@ Loading spinner with built-in `aria-label="Laster"`.
 </sds-notification>
 ```
 
-**Props:** `variant` (`"info"` | `"success"` | `"attention"` | `"danger"`), `removable-label`
+**Props:** `variant` (`"info"` | `"success"` | `"attention"` | `"danger"`, default `"info"`; `"warning"` and `"critical"` are deprecated aliases for `attention` and `danger`), `removable-label`
 **Slots:** `title`, `message`
 **Events:** `sds-remove`
+**Note:** Constructing one logs a deprecation warning. The nearest `sds-alert` equivalent maps `variant` onto `data-palette`.
+
+---
+
+## sds-popover
+
+Anchored popover built on the native Popover API. The element sets `popover="auto"` on itself unless you provide your own `popover` value, and is opened by a trigger with `popovertarget`.
+
+```html
+<sds-button popovertarget="filters">Filters</sds-button>
+
+<sds-popover id="filters" placement="bottom-start">
+	<div class="sds-stack-y-3xs">
+		<sds-checkbox label="Open cases" name="open"></sds-checkbox>
+		<sds-checkbox label="Closed cases" name="closed"></sds-checkbox>
+	</div>
+</sds-popover>
+
+<!-- Long content: make the popover scrollable instead of overflowing -->
+<sds-popover id="long" placement="bottom" overscroll="contain">…</sds-popover>
+```
+
+**Props:** `placement` (`"top"` | `"bottom"` | `"left"` | `"right"`, each also with `-start` / `-end`, or `"none"`; default `"top"`), `autoplacement` (`"true"` | `"false"`, default behaviour is to flip when there is no room), `overscroll` (`"contain"` — makes the popover scrollable)
+**Native attribute:** `popover` (`"auto"` | `"manual"`, defaults to `"auto"`)
+**Slots:** default (popover content)
+**Events:** `toggle` (native `ToggleEvent` — check `newState`)
+**Methods:** `showPopover()`, `hidePopover()` (native Popover API)
+**Note:** A trigger using `popovertarget` automatically gets `aria-haspopup`, `aria-expanded`, and `aria-controls`. The popover needs an `id`.
+
+---
+
+## sds-process
+
+Timeline / process list. Renders with `role="list"`; each `sds-process-step` is a `listitem`.
+
+```html
+<sds-process heading-level="h3">
+	<sds-process-step heading="14:41"> Fører som ikke klarte å stanse var ruset og er anmeldt. </sds-process-step>
+	<sds-process-step heading="13:48">Veien er ryddet og vi har avsluttet på stedet.</sds-process-step>
+</sds-process>
+
+<!-- Numbered / custom markers -->
+<sds-process heading-level="h3">
+	<sds-process-step heading="Send inn søknad" timestamp="1. mars">
+		<span slot="marker">1</span>
+		Fyll ut skjemaet.
+	</sds-process-step>
+	<sds-process-step heading="Behandling" timestamp="2.–14. mars">
+		<span slot="marker">2</span>
+		Vi behandler søknaden.
+	</sds-process-step>
+</sds-process>
+```
+
+**Props:** `heading-level` (`"h2"`–`"h6"`, default `"h2"`) — applied to every child step's heading
+**Slots:** default (`sds-process-step` children)
+
+### sds-process-step
+
+**Props:** `heading` (rendered at the parent's `heading-level`), `timestamp`
+**Slots:** default (step body), `marker` (leading marker content — a number, icon, or label)
+**Note:** A step with an empty `marker` slot renders in a compact "sub-step" style.
 
 ---
 
@@ -301,6 +543,7 @@ Single radio button.
 ```
 
 **Props:** `label`, `name`, `value` (default `"on"`), `checked`, `disabled`, `required`, `readonly`, `error`, `hide-label`, `help-text`, `size`
+**Slots:** `label` (alternative to the `label` attribute)
 **Events:** `change`, `focus`, `blur`
 
 ---
@@ -326,12 +569,34 @@ Groups radio buttons with shared legend and validation.
 </sds-radio-group>
 ```
 
-**Props:** `legend`, `disabled` (propagates), `required` (propagates), `readonly` (propagates), `direction` (`"column"` | `"row"`), `error-message`, `help-text`, `size` (propagates)
+**Props:** `legend`, `disabled` (propagates), `required` (propagates), `readonly` (propagates), `direction` (`"column"` | `"row"`, default `"column"`), `error-message`, `help-text`, `size` (propagates)
 **Slots:** default (`sds-radio` children)
 **Events:** `sds-update`
 
 ---
 
+## sds-search
+
+Search field: an `sds-textfield` (`type="search"`) and an icon button, shoulder to shoulder.
+
+```html
+<search aria-label="Registersøk">
+	<form action="/sok">
+		<sds-search label="Søk i registeret" hide-label name="q"></sds-search>
+	</form>
+</search>
+
+<sds-search label="Søk" button-variant="secondary"></sds-search>
+```
+
+**Props:** `label`, `hide-label`, `name`, `value`, `placeholder`, `disabled`, `readonly`, `error-message`, `help-text`, `size`, `button-label` (default `"Søk"`), `button-variant`, `required`, `minlength`, `maxlength`, `pattern`, `autocomplete` (forwarded to the inner input)
+**Slots:** `label` (rich label content, takes precedence over the `label` prop), `button` (replaces the default icon button; the slotted control owns its own click, `disabled` and form submission)
+**Events:** `search` (detail `{ value }`, cancelable), `input`, `change`, `select`, `keydown` (cancelling Enter prevents `search`), `focus`, `blur`, `invalid`. `focus`/`blur` fire when focus enters or leaves the component as a whole, not when it moves between the field and the button.
+**Methods:** `focus()`, `blur()`, `select()`, `setSelectionRange()`, `selectionStart`/`selectionEnd`, `checkValidity()`, `reportValidity()`, `setCustomValidity()`, plus `validity`, `validationMessage`, `willValidate`.
+**Note:** Clicking the button or pressing Enter validates the field (unless the form has `novalidate`), emits `search` if it is valid, then submits the surrounding form unless `search` was cancelled with `preventDefault()`. Always set `label`; use `hide-label` to hide it visually. The placeholder is not an accessible name. In React/Preact JSX without the wrapper, the listener must be lowercase: `onsearch`.
+
+---
+
 ## sds-select
 
 Dropdown select using native `<option>`/`<optgroup>` elements.
@@ -360,15 +625,16 @@ Dropdown select using native `<option>`/`<optgroup>` elements.
 </sds-select>
 ```
 
-**Props:** `label`, `name`, `value` (property only), `default-value` (attribute), `disabled`, `required`, `readonly`, `error-message`, `help-text`, `size`
-**Slots:** default (`<option>` / `<optgroup>` / `<hr>`)
+**Props:** `label`, `name`, `value` (property only — no attribute), `default-value` (attribute), `disabled`, `required`, `readonly`, `error-message`, `help-text`, `size`
+**Slots:** default (`<option>` / `<optgroup>` / `<hr>`), `label` (alternative to the `label` attribute)
 **Events:** `input`, `change`, `focus`, `blur`
+**Note:** Options are projected from light DOM and mirrored into the shadow `<select>`, so adding, removing, or relabelling options at runtime is picked up automatically. `readonly` renders a lock icon next to the label.
 
 ---
 
 ## sds-stepper
 
-Step indicator for multi-step flows. Contains `sds-stepper-step` children.
+Step indicator for multi-step flows. Contains `sds-stepper-step` children. Gets `aria-label="Steg"` unless you set your own.
 
 ```html
 <sds-stepper>
@@ -387,12 +653,13 @@ Step indicator for multi-step flows. Contains `sds-stepper-step` children.
 **Props:** `orientation` (`"horizontal"` | `"vertical"`, default `"horizontal"`)
 **Slots:** default (`sds-stepper-step` children)
 **Events:** `change` (detail: `{ index: number }`)
-**Methods:** `getActiveStep()` (returns index or -1), `goToStep(index)`
+**Methods:** `getActiveStep()` (returns index or -1), `goToStep(index)` (out-of-range indices are ignored)
 
 ### sds-stepper-step
 
 **Props:** `complete`, `interactive` (clickable), `active` (current step)
 **Slots:** default (label text)
+**Note:** Step numbers are generated automatically from the child order.
 
 ---
 
@@ -409,8 +676,9 @@ Toggle switch input.
 ```
 
 **Props:** `label`, `name`, `checked`, `disabled`, `readonly`, `reverse` (flip order), `hide-label`, `size`
+**Slots:** `label` (alternative to the `label` attribute)
 **Events:** `change`, `focus`, `blur`
-**Note:** No `error-message`, `help-text`, or `required`. Value getter returns `"on"` | `"off"`.
+**Note:** No `error-message`, `help-text`, or `required`. The `value` getter returns `"on"` | `"off"`, and `type` reports `"checkbox"`.
 
 ---
 
@@ -422,11 +690,13 @@ Non-interactive label/badge.
 <sds-tag>Default</sds-tag>
 <sds-tag data-palette="success">Approved</sds-tag>
 <sds-tag data-palette="danger">Rejected</sds-tag>
+<sds-tag data-palette="danger-action">Kritisk</sds-tag>
 <sds-tag size="sm">Small</sds-tag>
 ```
 
-**Props:** `size`
+**Props:** `size`, `data-palette`
 **Slots:** default
+**Note:** In addition to the framework palettes, `sds-tag` accepts `data-palette="danger-action"` — a deep red that is not a general palette value.
 
 ---
 
@@ -437,10 +707,11 @@ Text container with typography styling. Source: `sds-text.component.ts`.
 ```html
 <sds-text>Regular body text.</sds-text>
 <sds-text size="lg" strong tall>Large bold text with tall line height.</sds-text>
+<sds-text subtle>De-emphasised text.</sds-text>
 <sds-text data-palette="danger">Red danger text.</sds-text>
 ```
 
-**Props:** `size` (`"xl"` | `"lg"` | `"md"` | `"sm"` | `"xs"`), `strong` (bold), `tall` (increased line height)
+**Props:** `size` (`"xl"` | `"lg"` | `"md"` | `"sm"` | `"xs"`), `strong` (bold), `subtle` (de-emphasised colour), `tall` (increased line height)
 **Slots:** default
 
 ---
@@ -454,9 +725,11 @@ Multi-line text input.
 <sds-textarea label="Comments" name="comments" required error-message="Required"></sds-textarea>
 <sds-textarea label="Bio" name="bio" counter="500"></sds-textarea>
 <sds-textarea label="Address" name="address" rows="4" wrap="soft"></sds-textarea>
+<sds-textarea label="Notes" name="notes" autosize></sds-textarea>
 ```
 
-**Props:** `label`, `name`, `value`, `placeholder`, `disabled`, `readonly`, `required`, `rows`, `cols`, `wrap` (`"hard"` | `"soft"`), `minlength`, `maxlength`, `counter` (shows character count), `autocomplete`, `help-text`, `error-message`, `size`
+**Props:** `label`, `name`, `value`, `placeholder`, `disabled`, `readonly`, `required`, `rows`, `cols`, `wrap` (`"hard"` | `"soft"`), `minlength`, `maxlength`, `counter` (shows character count), `autosize` (grows with content), `autocomplete`, `help-text`, `error-message`, `size`
+**Slots:** `label` (alternative to the `label` attribute)
 **Events:** `input`, `change`, `select`, `focus`, `blur`
 
 ---
@@ -469,6 +742,7 @@ Single-line text input.
 <sds-textfield label="Email" name="email" type="email" placeholder="you@example.com"></sds-textfield>
 <sds-textfield label="Username" name="username" required help-text="3-20 characters" minlength="3" maxlength="20"></sds-textfield>
 <sds-textfield label="Phone" name="phone" type="tel" error-message="Invalid phone"></sds-textfield>
+<sds-textfield label="Amount" name="amount" type="number" min="0" max="100"></sds-textfield>
 <sds-textfield label="Search" name="search" type="search">
 	<sds-icon name="search-material-filled" slot="after"></sds-icon>
 </sds-textfield>
@@ -476,6 +750,29 @@ Single-line text input.
 <sds-textfield label="ID" name="id" value="12345" readonly></sds-textfield>
 ```
 
-**Props:** `label`, `name`, `value`, `type` (HTML input types), `placeholder`, `disabled`, `readonly`, `required`, `autocomplete`, `pattern`, `minlength`, `maxlength`, `help-text`, `error-message`, `size`
-**Slots:** `after` (e.g., icon)
+**Props:** `label`, `hide-label`, `name`, `value`, `type` (HTML input types), `placeholder`, `disabled`, `readonly`, `required`, `autocomplete`, `pattern`, `minlength`, `maxlength`, `min`, `max`, `help-text`, `error-message`, `size`
+**Slots:** `after` (e.g., icon), `label` (alternative to the `label` attribute)
 **Events:** `input`, `change`, `select`, `focus`, `blur`, `keydown`
+**Note:** When both `error-message` and `help-text` are set, `aria-describedby` lists the error first, then the help text. `readonly` renders a lock icon next to the label.
+
+---
+
+## sds-tooltip
+
+Hover/focus tooltip. The tooltip is a sibling of its trigger, and the trigger points at it with `aria-describedby` — the tooltip itself is `aria-hidden`, and its text is mirrored onto the trigger for screen readers.
+
+```html
+<span style="position: relative; display: inline-block;">
+	<sds-button aria-describedby="orgnr-tip" variant="secondary" icon label="Om org.nr">
+		<sds-icon name="info-material-outlined"></sds-icon>
+	</sds-button>
+	<sds-tooltip id="orgnr-tip">Organisasjonsnummer</sds-tooltip>
+</span>
+
+<sds-tooltip id="tip-right" placement="right">Vises til høyre</sds-tooltip>
+```
+
+**Props:** `id` (**required** — the value the trigger's `aria-describedby` references), `placement` (`"top"` | `"bottom"` | `"left"` | `"right"`, each also with `-start` / `-end`, or `"none"`; default `"top"`)
+**Slots:** default (tooltip text — keep it to plain text)
+**Events:** `toggle` (detail: the trigger element that opened it). The native popover `ToggleEvent` also fires on the host.
+**Notes:** Sets `role="tooltip"` and `popover="manual"` on itself. Multiple triggers may reference the same tooltip. Give the trigger and tooltip a `position: relative` wrapper. `data-palette` has no effect — tooltip colours are fixed.