@politiet/sheriff-web-components 2.13.0 → 2.14.0

package/dist/skill/SKILL.md

@@ -1,12 +1,16 @@
 ---
 name: sheriff-web-components
 description: >
-    Assists developers using @politiet/sheriff-web-components — Lit-based custom
-    elements with the sds-* prefix. Covers all 22 components (alert, button, card,
-    checkbox, chip, details, dialog, heading, icon, loader, radio, select, stepper,
-    switch, tag, text, textarea, textfield), React wrappers, form-associated
-    elements, slots, events, and data-palette theming. Use when the user references
-    sds-* components, @politiet/sheriff-web-components imports, or React wrappers.
+    Assists developers using @politiet/sheriff-web-components made of Lit-based custom
+    elements with the sds-* prefix. Covers all 33 components (alert, button, card,
+    checkbox, checkbox-group, chip, details, details-group, dialog,
+    environment-banner, file-upload, file-upload-item, file-upload-file-list,
+    heading, icon, internal-header, loader, notification,
+    popover, process, process-step, radio, radio-group, search, select, stepper,
+    stepper-step, switch, tag, text, textarea, textfield, tooltip), React
+    wrappers, framework type definitions, form-associated elements, slots,
+    events, and data-palette theming. Use when the user references sds-*
+    components, @politiet/sheriff-web-components imports, or React wrappers.
     Do not use for CSS-only questions, icon loading configuration, or SSR/RSC usage.
 ---
 
@@ -17,17 +21,20 @@ description: >
 When looking up component details not covered here, read the source directly:
 
 -   Most components: `packages/sheriff/web-components/src/sds-{name}/sds-{name}.ts`
--   Exception components (alert, button, heading, icon, text): `packages/sheriff/web-components/src/sds-{name}/sds-{name}.component.ts`
+-   Exception components (alert, button, dialog, environment-banner, heading, icon, internal-header, select, text, textfield): `packages/sheriff/web-components/src/sds-{name}/sds-{name}.component.ts`
+-   Styles and CSS custom properties: `packages/sheriff/web-components/src/sds-{name}/sds-{name}.styles.ts`
 -   Usage examples: `packages/sheriff/web-components/src/sds-{name}/sds-{name}.stories.ts`
--   Documentation: `packages/sheriff/web-components/src/sds-{name}/sds-{name}.mdx`
+-   Documentation: `packages/sheriff/web-components/src/sds-{name}/sds-{name}.mdx`, `variables.mdx` (CSS variables), `guidelines.mdx` (design guidance)
+
+Inside an installed package the same files live under `node_modules/@politiet/sheriff-web-components/dist/sds-{name}/`.
 
 ## Architecture
 
 1. Components that dispatch events extend `LitElement` via `SDSEventDispatcherMixin`.
-2. Properties use `@property({ reflect: true })` — settable as HTML attributes or JS properties.
-3. Content distribution uses named slots (`slot="before"`, `slot="after"`) and a default slot.
-4. Form-associated components implement `ElementInternals` with `formAssociated = true`.
-5. Events dispatch via `dispatchSheriffEvent()` as `CustomEvent` with `bubbles: true, composed: true`.
+2. Properties use `@property({ reflect: true })`, so they are settable as HTML attributes or JS properties.
+3. Content distribution uses named slots (`slot="before"`, `slot="after"`, `slot="label"`, …) and a default slot.
+4. Form-associated components implement `ElementInternals` with `formAssociated = true` and `delegatesFocus`.
+5. Events dispatch via `dispatchSheriffEvent()` as `CustomEvent` with `bubbles: true, composed: true`. **The event name is used verbatim — there is no automatic `sds-` prefix.** Some components dispatch native-sounding names (`change`, `toggle`, `close`), others dispatch prefixed names (`sds-remove`, `sds-update`).
 6. Color theming uses the `data-palette` attribute (see `@politiet/sheriff-css-framework` skill for palette details).
 
 ## Prerequisites
@@ -66,37 +73,80 @@ import '@politiet/sheriff-web-components/sds-button';
 import '@politiet/sheriff-web-components/sds-textfield';
 ```
 
+Every component has its own subpath export matching its tag name (`./sds-alert` … `./sds-tooltip`).
+
 ## Component Quick Reference
 
-All components use the `sds-` prefix. Sizes are `"lg"` | `"md"` | `"sm"` (default `"md"`).
-
-| Component            | Description                                  | Key Props                                                        |
-| -------------------- | -------------------------------------------- | ---------------------------------------------------------------- |
-| `sds-alert`          | Contextual alert banner                      | `variant`, `data-palette`, `removable-label`, `size`             |
-| `sds-button`         | Button or link-as-button                     | `variant`, `size`, `type`, `disabled`, `loading`, `icon`, `href` |
-| `sds-card`           | Content container; link card when `link` set | `link`                                                           |
-| `sds-checkbox`       | Single checkbox                              | `label`, `name`, `value`, `checked`, `error`                     |
-| `sds-checkbox-group` | Grouped checkboxes with legend               | `legend`, `error-message`, `help-text`                           |
-| `sds-chip`           | Selectable or removable chip/pill            | `variant`, `checked`, `name`, `value`                            |
-| `sds-details`        | Expandable accordion                         | `open`, `standalone`, `name` (exclusive group)                   |
-| `sds-dialog`         | Modal/dialog wrapping native `<dialog>`      | `open`, `modal`, `closedby`                                      |
-| `sds-heading`        | Semantic heading                             | `level`, `size`                                                  |
-| `sds-icon`           | Dynamic SVG icon                             | `name`, `size`, `label`, `data-palette`                          |
-| `sds-loader`         | Loading spinner                              | `size`, `contrast`                                               |
-| `sds-notification`   | **Deprecated** — use `sds-alert`             | `variant`, `removable-label`                                     |
-| `sds-radio`          | Single radio button                          | `label`, `name`, `value`, `checked`                              |
-| `sds-radio-group`    | Grouped radios with legend                   | `legend`, `direction`, `error-message`                           |
-| `sds-select`         | Dropdown select                              | `label`, `name`, `default-value`, `error-message`                |
-| `sds-stepper`        | Step indicator for multi-step flows          | `orientation`                                                    |
-| `sds-stepper-step`   | Individual step in stepper                   | `complete`, `interactive`, `active`                              |
-| `sds-switch`         | Toggle switch                                | `label`, `name`, `checked`, `reverse`, `hide-label`              |
-| `sds-tag`            | Non-interactive label/badge                  | `size`, `data-palette`                                           |
-| `sds-text`           | Text container with typography               | `size`, `strong`, `tall`                                         |
-| `sds-textarea`       | Multi-line text input                        | `label`, `name`, `counter`, `error-message`                      |
-| `sds-textfield`      | Single-line text input                       | `label`, `name`, `type`, `error-message`                         |
+All components use the `sds-` prefix. Sizes are `"lg"` | `"md"` | `"sm"`, default `"md"` — **except `sds-button`, which defaults to `"lg"`**. `sds-heading` and `sds-text` use the wider `"xl" | "lg" | "md" | "sm" | "xs"` scale.
+
+| Component                   | Description                                  | Key Props                                                                                        |
+| --------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `sds-alert`                 | Contextual alert banner                      | `variant`, `size`, `removable-label`, `data-palette`                                             |
+| `sds-button`                | Button or link-as-button                     | `variant`, `size`, `type`, `disabled`, `loading`, `icon`, `inverted`, `label`, `href`, `command` |
+| `sds-card`                  | Content container; link card when `link` set | `link`                                                                                           |
+| `sds-checkbox`              | Single checkbox                              | `label`, `name`, `value`, `checked`, `error`, `help-text`                                        |
+| `sds-checkbox-group`        | Grouped checkboxes with legend               | `legend`, `error-message`, `help-text`                                                           |
+| `sds-chip`                  | Selectable or removable chip/pill            | `variant`, `checked`, `name`, `value`, `size`                                                    |
+| `sds-details`               | Expandable accordion                         | `open`, `standalone`, `name` (exclusive group)                                                   |
+| `sds-details-group`         | Wraps `sds-details` into one accordion group | `outlined`, `name` (makes the group exclusive)                                                   |
+| `sds-dialog`                | Modal/dialog wrapping native `<dialog>`      | `open`, `modal`, `closedby`, `close-button-label`                                                |
+| `sds-environment-banner`    | Environment/build strip for internal apps    | `env`, `build`                                                                                   |
+| `sds-file-upload`           | File picker with drag and drop (beta)        | `name`, `accept`, `multiple`, `max-size-in-bytes`, `error-message`, `hide-file-list`             |
+| `sds-file-upload-item`      | One file row with remove button and progress | `file`, `size-in-bytes`, `uploaded-percent`, `error-message`, `for`                              |
+| `sds-file-upload-file-list` | List container for `sds-file-upload-item`    | —                                                                                                |
+| `sds-heading`               | Semantic heading                             | `level`, `size`                                                                                  |
+| `sds-icon`                  | Dynamic SVG icon                             | `name`, `size`, `label`, `color`                                                                 |
+| `sds-internal-header`       | App header for internal (non-public) apps    | `app-name`, `home-href`                                                                          |
+| `sds-loader`                | Loading spinner                              | `size`, `contrast`                                                                               |
+| `sds-notification`          | **Deprecated** — use `sds-alert`             | `variant`, `removable-label`                                                                     |
+| `sds-popover`               | Anchored popover built on the Popover API    | `placement`, `autoplacement`, `overscroll`                                                       |
+| `sds-process`               | Timeline / process list                      | `heading-level`                                                                                  |
+| `sds-process-step`          | Individual step in a process                 | `heading`, `timestamp`                                                                           |
+| `sds-radio`                 | Single radio button                          | `label`, `name`, `value`, `checked`, `hide-label`                                                |
+| `sds-radio-group`           | Grouped radios with legend                   | `legend`, `direction`, `error-message`                                                           |
+| `sds-search`                | Search field with search button              | `label`, `hide-label`, `name`, `button-variant`                                                  |
+| `sds-select`                | Dropdown select                              | `label`, `name`, `default-value`, `error-message`                                                |
+| `sds-stepper`               | Step indicator for multi-step flows          | `orientation`                                                                                    |
+| `sds-stepper-step`          | Individual step in a stepper                 | `complete`, `interactive`, `active`                                                              |
+| `sds-switch`                | Toggle switch                                | `label`, `name`, `checked`, `reverse`, `hide-label`                                              |
+| `sds-tag`                   | Non-interactive label/badge                  | `size`, `data-palette`                                                                           |
+| `sds-text`                  | Text container with typography               | `size`, `strong`, `subtle`, `tall`                                                               |
+| `sds-textarea`              | Multi-line text input                        | `label`, `name`, `counter`, `autosize`, `error-message`                                          |
+| `sds-textfield`             | Single-line text input                       | `label`, `hide-label`, `name`, `type`, `error-message`                                           |
+| `sds-tooltip`               | Hover/focus tooltip anchored to a trigger    | `id` (required), `placement`                                                                     |
 
 For full component API (all props, slots, events, code examples), see `references/components.md`.
 
+## `data-palette` Support
+
+`data-palette` works on **every** component and is inherited from any ancestor container, with three exceptions:
+
+-   `sds-alert`: `data-palette` is a typed component property, so it must be set **on the alert itself** (it does not inherit from a container). Accepted values are only `info` | `success` | `attention` | `danger`; it also selects the alert's status icon.
+-   `sds-tooltip` and `sds-environment-banner`: fixed colors, palette has no effect. The environment banner colors itself from `env`.
+-   `sds-loader`: the palette variant is designed for a loader sitting **on** a palette-colored surface. Add `contrast` to flip it back for a plain background.
+
+`sds-tag` additionally accepts `data-palette="danger-action"` (deep red), which is not a general framework palette.
+
+## Form-Associated Components
+
+`sds-button`, `sds-checkbox`, `sds-chip`, `sds-file-upload`, `sds-radio`, `sds-search`, `sds-select`, `sds-switch`, `sds-textarea`, and `sds-textfield` are form-associated: they participate in `<form>` submission, validation, and reset without extra wiring. Set both `name` and `value` for the value to be submitted. `sds-switch` submits `"on"` / `"off"`. `sds-file-upload` only needs `name` and submits the selected files, and it has no `readonly`.
+
+Shared props from the form-control mixin: `name`, `disabled`, `readonly`. In a `sds-checkbox-group` / `sds-radio-group`, setting `disabled` or `readonly` on the group propagates to children unless the child sets it explicitly.
+
+### Slotted labels
+
+`sds-checkbox`, `sds-radio`, `sds-select`, `sds-switch`, `sds-textarea`, and `sds-textfield` accept a `label` slot as an alternative to the `label` attribute, for labels that need markup:
+
+```html
+<sds-textfield name="orgnr">
+	<span slot="label">Org.nr <sds-icon name="info-material-outlined" size="sm"></sds-icon></span>
+</sds-textfield>
+```
+
+The attribute is the default slot content, so use one or the other — not both.
+
+`sds-file-upload` has **only** the `label` slot, no `label` attribute.
+
 ## React Wrappers
 
 React versions before v19 do not natively handle web component events. Use the provided wrappers from `@politiet/sheriff-web-components/react-wrappers`:
@@ -116,10 +166,20 @@ function MyForm() {
 }
 ```
 
-React 19+ supports custom elements natively — can use web components directly without wrappers.
+React 19+ supports custom elements natively — can use web components directly without wrappers. Event props on raw elements must match the event name exactly: `onclose`, `oncancel`, `ontoggle` (lowercase). React treats camelCase `onClose`/`onCancel`/`onToggle` as its own synthetic events and never fires them on custom elements. They are only typed for backwards compatibility and marked deprecated.
 
 For the full list of available wrappers and event mappings, see `references/react-wrappers.md`.
 
+## Framework Type Definitions
+
+Type-only subpath exports register the `sds-*` tags with a framework's JSX/template typings, so custom elements type-check without wrappers. Import once in a global `.d.ts`:
+
+```ts
+/// <reference types="@politiet/sheriff-web-components/framework/react" />
+```
+
+Available: `framework/react`, `framework/preact`, `framework/vue`, `framework/svelte`, `framework/solidjs`. These ship types only and they emit no runtime code, so you still need to import the components themselves to register them.
+
 ## Common Patterns
 
 ### Form layout
@@ -139,16 +199,37 @@ For the full list of available wrappers and event mappings, see `references/reac
 ### Dialog with actions
 
 ```html
-<sds-dialog modal closedby="any">
+<sds-button command="show-modal" commandfor="confirm-dialog">Delete…</sds-button>
+
+<sds-dialog id="confirm-dialog" modal closedby="any">
 	<sds-heading level="h2" size="md" slot="header">Confirm</sds-heading>
 	<sds-text>Are you sure?</sds-text>
 	<div slot="footer" class="sds-stack-x-2xs">
-		<sds-button size="md">Confirm</sds-button>
-		<sds-button size="md" variant="secondary" data-command="close">Cancel</sds-button>
+		<sds-button size="md" data-palette="danger">Confirm</sds-button>
+		<sds-button size="md" variant="secondary" command="close">Cancel</sds-button>
 	</div>
 </sds-dialog>
 ```
 
+`command="show-modal"` needs `commandfor` pointing at the dialog's `id`, and it also wires `aria-haspopup`/`aria-expanded`/`aria-controls` on the trigger. `command="close"` (or the legacy `data-command="close"`) works on any button inside the dialog without `commandfor`.
+
+### Popover and tooltip
+
+```html
+<sds-button popovertarget="filters">Filters</sds-button>
+<sds-popover id="filters" placement="bottom-start">
+	<sds-checkbox label="Open cases" name="open"></sds-checkbox>
+</sds-popover>
+
+<!-- Tooltip: the trigger references the tooltip id, the tooltip is a sibling -->
+<span style="position: relative; display: inline-block;">
+	<sds-button aria-describedby="orgnr-tip" variant="secondary" icon>
+		<sds-icon name="info-material-outlined" label="Om org.nr"></sds-icon>
+	</sds-button>
+	<sds-tooltip id="orgnr-tip">Organisasjonsnummer</sds-tooltip>
+</span>
+```
+
 ### Alert with title
 
 ```html
@@ -164,9 +245,22 @@ For the full list of available wrappers and event mappings, see `references/reac
 <sds-button variant="primary" data-palette="danger">Delete</sds-button>
 ```
 
+### Icon-only button
+
+Put the accessible name on the button via `label` (it becomes `aria-label` on the internal `<button>`), and leave the icon undescribed:
+
+```html
+<sds-button variant="tertiary" icon label="Search">
+	<sds-icon name="search-material-outlined"></sds-icon>
+</sds-button>
+```
+
 ## Error Handling
 
 -   **Component does not render or render weird**: Verify the CSS framework is imported. This is needed for CSS custom properties.
 -   **Events do not fire in React (pre-v19)**: Confirm React wrappers are used instead of web components.
+-   **`onClose`/`onToggle` never fires in React 19**: On raw `sds-*` elements use lowercase `onclose`/`ontoggle`/`oncancel`, or use the wrapper, where camelCase is correct.
+-   **Event listener never fires**: Check the exact event name in `references/components.md`. `sds-details`/`sds-popover`/`sds-tooltip` dispatch `toggle` (not `sds-toggle`) and `sds-dialog` dispatches `close` (not `sds-close`, which is deprecated).
 -   **Icons do not load**: Check the icon name format (`{name}-{source}-{variant}`) and network access to jsDelivr CDN. If in secure/isolated network, use Artifactory. If needed, see `@politiet/sheriff-icons` for icon skill.
 -   **Form values not submitted**: Ensure the component has both `name` and `value` attributes set.
+-   **`data-palette` seems ignored**: On `sds-alert` it must be set on the element itself, and only `info`/`success`/`attention`/`danger` are valid. `sds-tooltip` and `sds-environment-banner` do not support palettes.