@dpa-id-components/dpa-shared-components 23.0.0 → 23.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dpa-id-components/dpa-shared-components",
-  "version": "23.0.0",
+  "version": "23.1.1",
   "license": "ISC",
   "author": "dpa Deutsche Presse-Agentur GmbH",
   "description": "Shared Vue component library for dpa projects",
@@ -25,11 +25,11 @@
   "devEngines": {
     "runtime": {
       "name": "node",
-      "version": "24.20.0"
+      "version": "24.21.0"
     },
     "packageManager": {
       "name": "pnpm",
-      "version": "11.25.0",
+      "version": "11.26.0",
       "onFail": "download"
     }
   },
@@ -41,13 +41,13 @@
     "@tailwindcss/vite": "4.3.3",
     "@tsconfig/node24": "24.0.5",
     "@types/jsdom": "30.0.0",
-    "@types/node": "25.9.5",
+    "@types/node": "25.9.6",
     "@vitejs/plugin-vue": "6.0.8",
     "@vue/test-utils": "2.5.0",
     "@vue/tsconfig": "0.9.1",
     "ajv": "8.20.0",
-    "commit-and-tag-version": "13.1.2",
-    "eslint": "10.9.1",
+    "commit-and-tag-version": "13.2.0",
+    "eslint": "10.10.0",
     "eslint-plugin-storybook": "10.6.0",
     "husky": "9.1.7",
     "jsdom": "30.0.1",
@@ -57,7 +57,7 @@
     "storybook": "10.6.0",
     "tailwindcss": "4.3.3",
     "typescript": "6.0.3",
-    "vite": "8.2.2",
+    "vite": "8.3.0",
     "vitest": "5.0.0",
     "vue": "3.5.42",
     "vue-router": "5.3.1",

package/src/components/UiBadge/README.md

@@ -12,18 +12,3 @@
 import { UiBadge } from "@dpa-id-components/dpa-shared-components";
 </script>
 ```
-
-## API
-
-### Props
-
-| Name         | Type                                                                                                                                                                                       | Default        | Description                                                            |
-|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------|------------------------------------------------------------------------|
-| `appearance` | `"accent-red" \| "accent-red-dark" \| "accent-orange" \| "accent-purple" \| "accent-green" \| "primary" \| "neutral-primary" \| "neutral-emphasis" \| "neutral-medium" \| "neutral-faint"` | `"accent-red"` | Color variant of the badge                                             |
-| `iconName`   | `UiIconName`                                                                                                                                                                               | `undefined`    | Optional icon displayed to the left of the text                        |
-
-### Slots
-
-| Name      | Description                                |
-|-----------|--------------------------------------------|
-| `default` | Slot for the rendering the badge's content |

package/src/components/UiBadge/UiBadge.vue

@@ -14,6 +14,10 @@ import { computed } from "vue";
 import UiIcon, { type UiIconName } from "../UiIcon/UiIcon.vue";
 
 const { appearance = "accent-red", iconName = undefined } = defineProps<{
+  /**
+   * The color variant of the badge.
+   * @default "accent-red"
+   */
   appearance?:
     | "accent-red"
     | "accent-orange"
@@ -23,9 +27,19 @@ const { appearance = "accent-red", iconName = undefined } = defineProps<{
     | "neutral-primary"
     | "neutral-medium"
     | "neutral-faint";
+  /**
+   * The name of an icon to show to the left of the badge content.
+   */
   iconName?: UiIconName;
 }>();
 
+defineSlots<{
+  /**
+   * The content of the badge.
+   */
+  default: () => any;
+}>();
+
 const colorClass = computed(() => {
   return {
     "accent-red": "bg-accent-red text-neutral",

package/src/components/UiButton/README.md

@@ -6,7 +6,9 @@ This component transparently wraps `RouterLink` and `button` and toggles between
 
 **Important**: Always implement direct navigation interactions using the `to` prop rather than attaching a `click` event listener to `UiButton` to ensure a properly accessible and usable link is created.
 
-```vue
+This component binds all non-prop attributes on its principal element (either a `button` or an `a` element). This allows you to add arbitrary HTML attributes (and event listeners) on the principal element without them being explicitly supported by the component.
+
+```html
 <template>
   <UiButton size="lg" appearance="secondary" @click="save">
     Save
@@ -35,20 +37,3 @@ This component transparently wraps `RouterLink` and `button` and toggles between
 import { UiButton } from "@dpa-id-components/dpa-shared-components";
 </script>
 ```
-
-## API
-
-### Props
-Note: This component binds all non-prop attributes on its principal element (either a button or a element). This allows you to add arbitrary HTML attributes (and event listeners) on the principal element without them being explicitly supported by the component.
-
-| Name         | Type                                                                                       | Default     | Description                      |
-|--------------|--------------------------------------------------------------------------------------------|-------------|----------------------------------|
-| `to`         | `RouteLocationRaw`                                                                         | `undefined` | `RouterLink` `to` prop           |
-| `size`       | `"xs"`, `"sm"`, `"md"`, or `"lg"`                                                          | `"md"`      |                                  |
-| `appearance` | `"fill-emphasis"`, `"fill-subtle"`, `"outline-emphasis"`, `"outline-subtle"`, or `"ghost"` | `"primary"` |                                  |
-
-### Slots
-
-| Name      | Description                                                                                                                                                                      |
-|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `default` | Button content. Note, that text nodes are wrapped in a `span` element to ensure they can be detected using the CSS selectors responsible for applying icon-only-specific styles. |

package/src/components/UiButton/UiButton.vue

@@ -44,8 +44,21 @@ const {
   size = "md",
   appearance = "fill-emphasis",
 } = defineProps<{
+  /**
+   * `RouterLink`'s `to` prop. Providing this prop renders the button as a
+   * `RouterLink` (or a plain anchor element for absolute URLs) instead of a
+   * `button` element.
+   */
   to?: RouteLocationRaw;
+  /**
+   * Size of the button.
+   * @default "md"
+   */
   size?: keyof typeof BUTTON_SIZE_CLASSES;
+  /**
+   * Visual style of the button.
+   * @default "fill-emphasis"
+   */
   appearance?:
     | "fill-emphasis"
     | "fill-subtle"

package/src/components/UiCheckbox/README.md

@@ -2,32 +2,10 @@
 
 ## Usage
 
-```vue
+```html
 <UiCheckbox required name="terms" appearance="secondary">
   Accept terms and conditions
 </UiCheckbox>
 ```
 
-## API
-
-### Models
-
-| Name      | Type               | Default     | Description          |
-|-----------|--------------------|-------------|----------------------|
-| _default_ | `string[] \| string \| boolean` | `undefined` | Sets the input value |
-
-### Props
-
-**Note**: This component binds all non-prop attributes (apart from `class`) on its principal element (`input[type="checkbox"]`) instead of the root element. This allows you to add arbitrary HTML attributes (and event listeners) on the principal element without them being explicitly supported by the component.
-
-| Name           | Type      | Default    | Description                                 |
-|----------------|-----------|------------|---------------------------------------------|
-| `appearance` | `"primary"`, `"secondary"` | `"primary"` |  |
-| `size` | `"sm"`, `"md"` | `"md"` |  |
-
-### Slots
-
-| Name      | Description                                 |
-|-----------|---------------------------------------------|
-| `default` | Checkbox label |
-| `errors`  | For validation error content that's associated with the form control via `aria-errormessage` |
+This component binds all non-prop attributes (apart from `class`) on its principal element (`input[type="checkbox"]`) instead of the root element. This allows you to add arbitrary HTML attributes (and event listeners) on the principal element without them being explicitly supported by the component.

package/src/components/UiCheckbox/UiCheckbox.vue

@@ -75,10 +75,21 @@ const {
    * ID of the `input` element. Used for the `label`'s `for` attribute.
    */
   id?: string;
+  /**
+   * Visual style of the checkbox.
+   * @default "primary"
+   */
   appearance?: "primary" | "secondary";
+  /**
+   * Size of the checkbox and label text.
+   * @default "md"
+   */
   size?: "sm" | "md";
 }>();
 
+/**
+ * The value of the checkbox.
+ */
 const model = defineModel<ModelValue>();
 
 const defaultId = useId();

package/src/components/UiChip/README.md

@@ -12,24 +12,3 @@
     import {UiChip} from "@dpa-id-components/dpa-shared-components";
 </script>
 ```
-
-## API
-
-### Props
-
-| Name          | Type                   | Default | Description                                                  |
-|---------------|------------------------|---------|--------------------------------------------------------------|
-| `size`        | `"xs" \| "sm" \| "md"` | `sm`    | Determines the font-size and line-height of the chip content |
-| `closeButton` | `boolean`              | `false` | renders optional close button                                |
-
-### Events
-
-| Name    | Payload | Description                          |
-|---------|---------|--------------------------------------|
-| `close` | `[]`    | Emitted when close button is clicked |
-
-### Slots
-
-| Name      | Description                               |
-|-----------|-------------------------------------------|
-| `default` | slot for the rendering the chip's content |

package/src/components/UiChip/UiChip.vue

@@ -23,10 +23,16 @@ import type { Size } from "../../types";
 import UiIcon from "../UiIcon/UiIcon.vue";
 
 defineSlots<{
+  /**
+   * Slot for rendering the chip's content.
+   */
   default: () => any;
 }>();
 
 defineEmits<{
+  /**
+   * Emitted when the close button is clicked.
+   */
   close: [];
 }>();
 
@@ -37,7 +43,14 @@ const CHIP_SIZES: Record<Extract<Size, "xs" | "sm" | "md">, string> = {
 };
 
 const { size = "sm", closeButton = undefined } = defineProps<{
+  /**
+   * Renders an optional close button.
+   */
   closeButton?: boolean;
+  /**
+   * Determines the font-size and line-height of the chip content.
+   * @default "sm"
+   */
   size?: Extract<Size, "xs" | "sm" | "md">;
 }>();
 </script>

package/src/components/UiColorPicker/README.md

@@ -2,7 +2,7 @@
 
 ## Usage
 
-```vue
+```html
 <template>
   <UiLabel for="colorPicker">Farbe wählen</UiLabel>
   <UiColorPicker id="colorPicker" v-model="colorValue" />
@@ -15,17 +15,3 @@ import { UiColorPicker, UiLabel } from "@dpa-id-components/dpa-shared-components
 const colorValue = ref("");
 </script>
 ```
-
-## API
-
-### Props
-
-| Name          | Type        | Default                              | Description                                         |
-|---------------|-------------|--------------------------------------|-----------------------------------------------------|
-| `modelValue`  | `String`    | `"#e53935"` (see `./lib/colors.ts`)  | Color code in hexadecimal syntax                    |
-
-### Events
-
-| Name                | Type                                        | Description                                       |
-|---------------------|---------------------------------------------|---------------------------------------------------|
-| `update:modelValue` | `string` (color code in hexadecimal syntax) | Emitted when a color has been selected or entered |

package/src/components/UiColorPicker/UiColorPicker.vue

@@ -54,6 +54,10 @@ import UiIcon from "../UiIcon/UiIcon.vue";
 
 import { COLORS } from "./lib/colors.ts";
 
+/**
+ * The selected color code in hexadecimal syntax.
+ * @default "#e53935"
+ */
 const model = defineModel<string>({ default: COLORS[0] });
 
 const checkmarkIconColor = computed(() => {

package/src/components/UiDatePicker/README.md

@@ -1,8 +1,10 @@
 # @dpa-shared-components/UiDatePicker
 
+A date input wrapping the [`@vuepic/vue-datepicker`](https://vue3datepicker.com/) library. Supports single-date, date-range (via an array `v-model`), and month-only (`monthPicker`) selection modes, an optional time picker, multiple side-by-side calendar months (`multiCalendars`), and an optional quick filter sidebar (`leftSidebar` + `quickFilterRanges`) for jumping to preset ranges.
+
 ## Usage
 
-```vue
+```html
 <template>
   <UiDatePicker v-model="date" />
 </template>
@@ -16,64 +18,10 @@
 </script>
 ```
 
-## API
-
-### Props
-
-
-| Name                     | Type                                     | Default                  | Description                                                                                                 |
-|--------------------------|------------------------------------------|--------------------------|-------------------------------------------------------------------------------------------------------------|
-| `autoApply`              | `boolean`                                | `true`                   | Clicking a date immediately selects it without requiring confirmation                                       |
-| `closeOnAutoApply`       | `boolean`                                | `true`                   | Close the datepicker menu after auto-applying a selection                                                   |
-| `inline`                 | `boolean`                                | `false`                  | Renders the datepicker inline instead of as a popup                                                         |
-| `disabled`               | `boolean`                                | `false`                  | Disables the datepicker and applies disabled styling                                                        |
-| `locale`                 | `Locale`                                 | `de`                     | date-fns locale used for formatting and translations                                                        |
-| `utc`                    | `boolean`                                | `false`                  | Sets Timezone to utc or not                                                                                 |
-| `teleport`               | `boolean \| string \| HTMLElement`       | `false`                  | Teleports the datepicker menu to the body or a provided selector. Useful for solving hidden overflow issues |
-| `minDate`                | `Date \| string \| number`               | `new Date("1948-01-01")` | Minimum selectable date                                                                                     |
-| `maxDate`                | `Date \| string \| number`               | `undefined`              | Maximum selectable date                                                                                     |
-| `multiCalendars`         | `boolean`                                | `false`                  | Shows multiple calendar months side by side                                                                 |
-| `monthPicker`            | `boolean`                                | `false`                  | Switches to month-only picker mode. Disables range selection                                                |
-| `enableTimePicker`       | `boolean`                                | `false`                  | Enables a time picker alongside the date picker                                                             |
-| `autoPosition`           | `boolean`                                | `true`                   | Automatically repositions the menu based on viewport (flip & shift)                                         |
-| `autoRange`              | `string \| number`                       | `undefined`              | Automatically selects a range of N days from the clicked date                                               |
-| `maxRange`               | `string \| number`                       | `undefined`              | Maximum number of days allowed in a selected range                                                          |
-| `triggerWidth`           | `full \| fit`                            | `full`                   | Trigger button has either w-full applied ot w-fit                                                           |
-| `triggerPlaceholderText` | `string`                                 | `undefined`              | Placeholder text shown in the trigger button when no date is selected                                       |
-| `customFormatCallback`   | `(date: Date \| [Date, Date]) => string` | `undefined`              | Custom callback for formatting the displayed date string in the input                                       |
-| `leftTriggerIcon`        | `UiIconName`                             | `undefined`              | Icon displayed to the left of the label in the trigger button                                               |
-| `leftSidebar`            | `boolean`                                | `false`                  | Enables the quick filter sidebar                                                                            |
-| `quickFilterHeadline`    | `string`                                 | `undefined`              | Headline text for the quick filter sidebar                                                                  |
-| `quickFilterRanges`      | `PresetRange[]`                          | `[]`                     | Preset date ranges displayed as buttons in the quick filter sidebar                                         |
-| `actionExtraContent`     | `string`                                 | `undefined`              | Text content displayed at the bottom of the datepicker. Overridden when the `action-extra` slot is used     |
-
-### Model
-
-| Name         | Type       | Description                                                                                        |
-|--------------|------------|----------------------------------------------------------------------------------------------------|
-| `modelValue` | `DateType` | The selected date. Supports `Date`, `[Date, Date]`, `string`, or `{ month: number; year: number }` |
-
-### Events
-
-| Name                   | Payload       | Description                                    |
-|------------------------|---------------|------------------------------------------------|
-| `update:modelValue`    | `DateType`    | Emitted when a date or date range is selected  |
-| `quick-filter-changed` | `PresetRange` | Emitted when a quick filter preset is selected |
-| `open`                 | —             | Emitted when the datepicker menu opens         |
-| `closed`               | —             | Emitted when the datepicker menu closes        |
-| `start-range`          | `Date`        | Emitted when first date of range is selected   |
-| `end-range`            | `Date`        | Emitted when last date of range is selected    |
-
-### Slots
-
-| Name           | Slot Props                                             | Description                                                                                      |
-|----------------|--------------------------------------------------------|--------------------------------------------------------------------------------------------------|
-| `action-row`   | `ActionRowSlotProps`                                   | Custom action row at the bottom of the datepicker (e.g. confirm/cancel buttons)                  |
-| `action-extra` | `{ selectCurrentDate: () => void, reset: () => void }` | Additional content above the action row. Falls back to `actionExtraContent` prop if not provided |
-
-
 ### Types
 
+The `quickFilterRanges` prop and `quick-filter-changed` event use `PresetRange`; `v-model` accepts/emits `DateType`. Storybook's generated API tables show these as opaque type names, so their shapes are documented here instead:
+
 ```typescript
 export interface PresetRange {
   label: string;

package/src/components/UiDatePicker/UiDatePicker.vue

@@ -146,11 +146,28 @@ import { computed, ref, type ShallowRef, useTemplateRef } from "vue";
 import UiButton from "../UiButton/UiButton.vue";
 import UiIcon, { type UiIconName } from "../UiIcon/UiIcon.vue";
 
+/**
+ * A preset date range displayed as a button in the quick filter sidebar
+ * (see the `leftSidebar` and `quickFilterRanges` props).
+ */
 export interface PresetRange {
+  /** Label displayed on the quick filter button. */
   label: string;
+  /**
+   * The date range (or month/year) selected when this preset is clicked.
+   * Use a `[Date, Date]` tuple for a day range, or `{ year, month }` when
+   * `monthPicker` is enabled.
+   */
   range: [Date, Date] | { year: number; month: number };
+  /** Optional internal identifier for the preset. */
   name?: string;
 }
+
+/**
+ * The value of `UiDatePicker`'s `v-model`. A single `Date` when selecting one
+ * date, a `[Date, Date]` tuple when selecting a range, a `string` for raw
+ * input, or `{ month, year }` when `monthPicker` is enabled.
+ */
 export type DateType =
   Date | [Date, Date] | string | { month: number; year: number };
 
@@ -161,20 +178,38 @@ const menuArrow =
   useTemplateRef<Readonly<ShallowRef<HTMLDivElement>>>("menuArrow");
 
 defineSlots<{
+  /**
+   * Custom action row at the bottom of the datepicker (e.g. confirm/cancel
+   * buttons), replacing the default one. Receives the underlying date
+   * picker's current `modelValue` and `disabled` state, plus `selectDate`
+   * and `closePicker` functions to confirm or dismiss the menu.
+   */
   "action-row"?: (props: ActionRowSlotProps) => any;
+  /**
+   * Additional content rendered above the action row. Falls back to the
+   * `actionExtraContent` prop when not provided. Receives
+   * `selectCurrentDate` (selects today's date) and `reset` (clears the
+   * selection and closes the menu) functions.
+   */
   "action-extra"?: (props: {
     selectCurrentDate: () => void;
     reset: () => void;
   }) => any;
 }>();
 
+/** The selected date, range, or month. See {@link DateType}. */
 const date = defineModel<DateType>();
 
 const emit = defineEmits<{
+  /** Emitted when the datepicker menu closes. */
   closed: [];
+  /** Emitted when the datepicker menu opens. */
   open: [];
+  /** Emitted with the first selected date when a range selection starts. */
   "range-start": [Date];
+  /** Emitted with the last selected date when a range selection ends. */
   "range-end": [Date];
+  /** Emitted when a quick filter preset is selected. */
   "quick-filter-changed": [PresetRange];
 }>();
 
@@ -203,38 +238,120 @@ const {
   quickFilterRanges = [],
   actionExtraContent = undefined,
 } = defineProps<{
+  /**
+   * Clicking a date immediately selects it without requiring a separate
+   * confirmation step (i.e. hides/bypasses the action row).
+   * @default true
+   */
   autoApply?: boolean;
+  /**
+   * date-fns locale used for formatting dates and translating internal
+   * labels.
+   * @default de
+   */
   locale?: Locale;
+  /**
+   * Disables the datepicker trigger and applies disabled styling.
+   * @default false
+   */
   disabled?: boolean;
+  /**
+   * Minimum selectable date.
+   * @default new Date("1948-01-01")
+   */
   minDate?: Date | string | number;
+  /** Maximum selectable date. */
   maxDate?: Date | string | number;
+  /**
+   * Renders the datepicker inline instead of as a popup.
+   * @default false
+   */
   inline?: boolean;
+  /**
+   * Teleports the datepicker menu to the given target (or to `<body>` when
+   * `true`). Useful for avoiding clipping by an ancestor's `overflow:
+   * hidden`.
+   * @default false
+   */
   teleport?: string | boolean | HTMLElement;
+  /**
+   * Switches to a month-only picker mode (selecting `{ month, year }`
+   * instead of a day). Disables range selection.
+   * @default false
+   */
   monthPicker?: boolean;
+  /**
+   * Shows multiple calendar months side by side.
+   * @default false
+   */
   multiCalendars?: boolean;
+  /**
+   * Interprets and displays the selected date(s) in UTC instead of the
+   * local timezone.
+   */
   utc?: boolean;
 
   // Time Config
+  /**
+   * Enables a time picker alongside the date picker.
+   * @default false
+   */
   enableTimePicker?: boolean;
 
   // Floating Config
+  /**
+   * Automatically repositions the menu to stay within the viewport (flip &
+   * shift).
+   * @default true
+   */
   autoPosition?: boolean;
 
   // Range Config
+  /** Automatically selects a range of N days starting from the clicked date. */
   autoRange?: string | number;
+  /** Maximum number of days allowed in a selected range. */
   maxRange?: string | number;
 
   // General Config
+  /**
+   * Closes the datepicker menu automatically after auto-applying a
+   * selection (only relevant when `autoApply` is `true`).
+   * @default true
+   */
   closeOnAutoApply?: boolean;
 
   // Slots
+  /** Placeholder text shown in the trigger button when no date is selected. */
   triggerPlaceholderText?: string;
+  /**
+   * Whether the trigger button spans the full width of its container
+   * (`"full"`) or only as wide as its content (`"fit"`).
+   * @default "fit"
+   */
   triggerWidth?: "full" | "fit";
+  /**
+   * Custom callback for formatting the displayed date (or range) string in
+   * the trigger button. Overrides the built-in `dd.MM.yyyy` formatting.
+   */
   customFormatCallback?: (date: Date | [Date, Date]) => string;
+  /** Icon displayed to the left of the label in the trigger button. */
   leftTriggerIcon?: UiIconName;
+  /**
+   * Enables the quick filter sidebar showing buttons for `quickFilterRanges`.
+   * @default false
+   */
   leftSidebar?: boolean;
+  /** Headline text for the quick filter sidebar. */
   quickFilterHeadline?: string;
+  /**
+   * Preset date ranges displayed as buttons in the quick filter sidebar.
+   * @default []
+   */
   quickFilterRanges?: PresetRange[];
+  /**
+   * Text content displayed at the bottom of the datepicker, above the
+   * action row. Overridden by the `action-extra` slot when it is used.
+   */
   actionExtraContent?: string;
 }>();
 

package/src/components/UiDialog/README.md

@@ -1,5 +1,7 @@
 # @dpa-shared-components/UiDialog
 
+A wrapper around the native `<dialog>` element. Native `<dialog>` behaviors and events (such as the `cancel` event fired when the Escape key is pressed) apply.
+
 ## Usage
 
 ```html
@@ -16,30 +18,3 @@
     import {UiDialog} from "@dpa-id-components/dpa-shared-components";
 </script>
 ```
-
-## API
-
-### Props
-
-
-| Name             | Type      | Default | Description                                       |
-|------------------|-----------|---------|---------------------------------------------------|
-| `hasCloseButton` | `boolean` | `true`  | Whether to show the close button |
-| `closeLabel`     | `string`  | `undefined` | Close button label |
-
-
-### Exposes
-
-| Name           | Type | Description                                                          |
-|----------------|------|----------------------------------------------------------------------|
-| `close`        | none | Exposes the native `close()` function of a `<dialog>` element        |
-| `requestClose` | none | Exposes the native `requestClose()` function of a `<dialog>` element |
-| `showModal`    | none | Exposes the native `showModal()` function of a `<dialog>` element    |
-
-### Slots
-
-| Name      | Description  |
-|-----------|--------------|
-| `default` | Main content |
-| `header`  | Header       |
-| `footer`  | Footer       |