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

package/src/components/UiMenu/UiMenu.vue

@@ -131,6 +131,7 @@ import UiIcon from "../UiIcon/UiIcon.vue";
 import UiListItem from "../UiListItem/UiListItem.vue";
 import UiPopover from "../UiPopover/UiPopover.vue";
 
+/** A single selectable option of the `options` array prop of `UiMenu`. */
 export type UiMenuOptionType<Value = unknown> = {
   label: string;
   imageSrc?: string;
@@ -141,16 +142,23 @@ export type UiMenuOptionType<Value = unknown> = {
   hasDividerAbove?: boolean;
 };
 
+/** Payload emitted by the `option-selected` event, the selected option plus its index within the (flattened) option list. */
 export type UiMenuSelectedOption<Value = unknown> = UiMenuOptionType<Value> & {
   index: number;
 };
 
+/** A group of options with an optional group label, used with the `groupedOptions` prop. */
 export type UiMenuGroupedOption<Value = unknown> = {
   groupLabel?: string;
   options: UiMenuOptionType<Value>[];
 };
 
 defineSlots<{
+  /**
+   * Slot within the positioned popover div, used to build fully custom menu
+   * contents instead of the default option list. Falls back to the default
+   * rendering (with support for grouped options) when not provided.
+   */
   default?: (props: {
     checkboxAppearance: typeof checkboxAppearance;
     iconSize: typeof iconSize;
@@ -161,6 +169,10 @@ defineSlots<{
   }) => any;
 }>();
 
+/**
+ * The search `input` value.
+ * @default ""
+ */
 const queryModel = defineModel<string>("query", { default: "" });
 
 const {
@@ -193,45 +205,145 @@ const {
   checkboxAppearance = "primary",
   listVariant = "blank",
 } = defineProps<{
+  /**
+   * Array of options for selection. Used for the flat (un-grouped) variant
+   * of the menu. Mutually exclusive with `groupedOptions`.
+   */
   options?: UiMenuOptionType<Value>[];
+  /**
+   * Array of grouped options for selection, rendered with an optional group
+   * label header per group. Mutually exclusive with `options`.
+   */
   groupedOptions?: UiMenuGroupedOption<Value>[];
+  /**
+   * Whether the menu is initially open.
+   * @default false
+   */
   isOpen?: boolean;
+  /**
+   * Placement of the popover menu, see the
+   * [Floating UI Placement type](https://floating-ui.com/docs/tutorial#placements).
+   * @default "bottom-start"
+   */
   floatingUiPlacement?: Placement;
+  /**
+   * Whether to animate the opening and closing of the menu. The transition
+   * duration can be customized by applying
+   * `placed-list-class="[--transition-duration:3000ms]"` for the opening
+   * animation and `placed-list-class="[--transition-close-duration:2000ms]"`
+   * for the closing animation.
+   * @default false
+   */
   animate?: boolean;
 
   // Button slot
+  /**
+   * Disables the button that opens the menu.
+   * @default false
+   */
   disabled?: boolean;
+  /**
+   * Applies the active/filled appearance to the button to indicate an
+   * active filter selection.
+   * @default false
+   */
   active?: boolean;
+  /**
+   * Icon displayed to the left of the button label.
+   * @default null
+   */
   iconLeft?: UiIconName;
+  /**
+   * Visual appearance of the button that opens the menu.
+   * @default "outline-subtle"
+   */
   buttonAppearance?:
     | "fill-emphasis"
     | "fill-subtle"
     | "outline-emphasis"
     | "outline-subtle"
     | "ghost";
+  /**
+   * Size of the button that opens the menu.
+   * @default "sm"
+   */
   filterButtonSize?: "sm" | "xs";
+  /**
+   * Default title displayed on the button when nothing is selected.
+   * @default ""
+   */
   defaultTitle?: string;
+  /**
+   * Label appended after the selection count when more than one option is
+   * selected, e.g. "3 selected options".
+   * @default ""
+   */
   multiLabel?: string;
+  /**
+   * Displays the button without any title/selection text, useful for
+   * icon-only menu triggers.
+   * @default false
+   */
   noTitle?: boolean;
 
   // Search
+  /**
+   * Toggles a search input above the option list.
+   * @default false
+   */
   hasSearch?: boolean;
+  /**
+   * Placeholder text of the search input.
+   * @default ""
+   */
   searchPlaceholder?: string;
+  /**
+   * Whether to autofocus the search input when the menu opens.
+   * @default false
+   */
   hasAutoFocus?: boolean;
+  /**
+   * Toggles a reset button below the option list.
+   * @default false
+   */
   hasResetOption?: boolean;
+  /**
+   * Label text of the reset button.
+   * @default ""
+   */
   resetLabel?: string;
 
   // Menu
+  /**
+   * Size of the option icons/images.
+   * @default "sm"
+   */
   iconSize?: "sm" | "md" | "lg";
+  /**
+   * Shape of the option images.
+   * @default "square"
+   */
   imageShape?: "rounded" | "square";
+  /**
+   * Appearance of the checkbox used when `listVariant` is `"checkbox"`.
+   * @default "primary"
+   */
   checkboxAppearance?: "primary" | "secondary";
+  /**
+   * Visual style of the option list items.
+   * @default "blank"
+   */
   listVariant?: "checkbox" | "selectable" | "blank";
 }>();
 
 const emit = defineEmits<{
+  /** Emitted when the menu is opened. */
   open: [];
+  /** Emitted when the menu is closed. */
   close: [];
+  /** Emitted when an option is selected. */
   "option-selected": [UiMenuSelectedOption<Value>];
+  /** Emitted when the reset button is clicked. */
   reset: [];
 }>();
 

package/src/components/UiPopover/README.md

@@ -4,7 +4,7 @@ A general purpose popover component.
 
 ## Usage
 
-```vue
+```html
 <UiPopover animate placement="bottom-start">
   <template #button="{ toggle }">
     <UiButton @click="toggle">
@@ -21,36 +21,3 @@ A general purpose popover component.
   </template>
 </UiPopover>
 ```
-
-## Props
-
-### `animate`
-
-- **Description**: Whether to animate the opening and closing of the popover content.
-- **Type**: `boolean`
-- **Required**: No
-- **Default**: `false`
-
-### `initiallyOpen`
-
-- **Description**: Whether the popover content is initially open.
-- **Type**: `boolean`
-- **Required**: No
-- **Default**: `false`
-
-### `placement`
-
-- **Description**: The placement of the popover content.
-- **Type**: `Placement`
-- **Required**: No
-- **Default**: `"bottom-start"`
-
-## Slots
-
-### `button`
-
-The trigger button. Receives as slot props the `isOpen` property and the `open`, `close`, and `toggle` functions.
-
-### `default`
-
-The popover content. Receives as slot props the `close` function.

package/src/components/UiPopover/UiPopover.vue

@@ -29,12 +29,19 @@ import { onClickOutside } from "@vueuse/core";
 import { ref, useTemplateRef, watch } from "vue";
 
 defineSlots<{
+  /**
+   * The trigger button. Receives as slot props the `isOpen` property and
+   * the `open`, `close`, and `toggle` functions.
+   */
   button: (props: {
     open: typeof open;
     close: typeof close;
     toggle: typeof toggle;
     isOpen: typeof isOpen.value;
   }) => any;
+  /**
+   * The popover content. Receives as slot props the `close` function.
+   */
   default: (props: { close: typeof close }) => any;
 }>();
 
@@ -61,6 +68,9 @@ const {
 }>();
 
 const emit = defineEmits<{
+  /**
+   * Emitted when the popover is opened or closed.
+   */
   toggle: [isOpen: boolean];
 }>();
 
@@ -106,7 +116,16 @@ onClickOutside(
   },
 );
 
-defineExpose({ open, close });
+defineExpose({
+  /**
+   * Opens the popover content.
+   */
+  open,
+  /**
+   * Closes the popover content.
+   */
+  close,
+});
 </script>
 
 <style scoped>

package/src/components/UiRadioButton/README.md

@@ -2,7 +2,7 @@
 
 ## Usage
 
-```vue
+```html
 <!-- SomeComponent.vue using UiRadioButton -->
 <template>
   <div class="space-y-2">
@@ -19,26 +19,4 @@
 </script>
 ```
 
-### Props
-
-| Name         | Type                       | Default        | Description                                                       |
-|--------------|----------------------------|----------------|-------------------------------------------------------------------|
-| `modelValue` | `string`                   | `undefined`    | The selected value (use with `v-model`)                           |
-| `id`         | `string`                   | auto-generated | ID of the `input` element. Used for the `label`'s `for` attribute |
-| `appearance` | `"primary" \| "secondary"` | `"primary"`    | Visual style of the radio button                                  |
-| `size`       | `"sm" \| "md"`             | `"md"`         | Size of the radio button and label text                           |
-
 All native `input` attributes (e.g. `value`, `disabled`, `name`, `data-testid`) are forwarded to the underlying `<input>` element.
-
-### Events
-
-| Name                | Type     | Description                                        |
-|---------------------|----------|----------------------------------------------------|
-| `update:modelValue` | `string` | Emitted when the selected value changes (v-model)  |
-
-### Slots
-
-| Name      | Description                                                     |
-|-----------|-----------------------------------------------------------------|
-| `default` | Label content displayed next to the radio button                |
-| `errors`  | Error message content, rendered below the radio in an error box |

package/src/components/UiRadioButton/UiRadioButton.vue

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

package/src/components/UiSearchBar/README.md

@@ -25,32 +25,3 @@
 </template>
 
 ```
-
-### Props
-
-| Name                       | Type                             | Default             | Description                                 |
-|----------------------------|----------------------------------|---------------------|---------------------------------------------|
-| `modelValue`               | `string`                         | `""`                | The `input`'s value (use with `v-model`)    |
-| `placeholder`              | `string`                         | `""`                | Text for the `input`'s placeholder          |
-| `appearance`               | `"neutral-whisper" \| "neutral"` | `"neutral-whisper"` | Sets the background color of the search bar |
-| `executeSearchButtonTitle` | `string`                         | `"Execute Search"`  | Aria-label for the search button            |
-| `resetSearchButtonTitle`   | `string`                         | `"Reset Search"`    | Aria-label for the reset button             |
-| `showResetButtonOnMobile`  | `boolean`                        | `false`             | Shows the reset button on mobile viewports  |
-
-### Events
-
-| Name                | Type         | Description                                             |
-|---------------------|--------------|---------------------------------------------------------|
-| `blur`              | `FocusEvent` | Emitted when the `input` loses focus                    |
-| `focus`             | `FocusEvent` | Emitted when the `input` is focused                     |
-| `reset`             | `string`     | Emitted when the reset button is clicked                |
-| `search`            | `string`     | Emitted when the search button is clicked               |
-| `submit`            | `string`     | Emitted when the user presses Enter                     |
-| `update:modelValue` | `string`     | Emitted when the input value changes (implicit v-model) |
-
-### Slots
-
-| Name     | Description                                                                            |
-|----------|----------------------------------------------------------------------------------------|
-| `chips`  | Content displayed in place of the input text when the input is blurred and has a value |
-| `action` | Additional action elements rendered before the reset and search buttons                |

package/src/components/UiSearchBar/UiSearchBar.vue

@@ -71,14 +71,36 @@ import { ref, useTemplateRef } from "vue";
 import UiButton from "../UiButton/UiButton.vue";
 import UiIcon from "../UiIcon/UiIcon.vue";
 
+defineSlots<{
+  /**
+   * Content displayed in place of the input text when the input is
+   * blurred and has a value, e.g. filter chips.
+   */
+  chips?: () => any;
+  /**
+   * Additional action elements rendered before the reset and search
+   * buttons.
+   */
+  action?: () => any;
+}>();
+
 const emit = defineEmits<{
+  /** Emitted when the `input` loses focus. */
   blur: [FocusEvent];
+  /** Emitted when the `input` is focused. */
   focus: [FocusEvent];
+  /** Emitted with the current value when the reset button is clicked. */
   reset: [string];
+  /** Emitted with the current value when the search button is clicked. */
   search: [string];
+  /** Emitted with the current value when the user presses Enter. */
   submit: [string];
 }>();
 
+/**
+ * The input's value.
+ * @default ""
+ */
 const model = defineModel<string>({ default: "" });
 
 const {
@@ -88,10 +110,30 @@ const {
   resetSearchButtonTitle = "Reset Search",
   showResetButtonOnMobile = false,
 } = defineProps<{
+  /**
+   * Text for the input's placeholder.
+   * @default ""
+   */
   placeholder?: string;
+  /**
+   * Sets the background color of the search bar.
+   * @default "neutral-whisper"
+   */
   appearance?: "neutral-whisper" | "neutral";
+  /**
+   * Aria-label for the search button.
+   * @default "Execute Search"
+   */
   executeSearchButtonTitle?: string;
+  /**
+   * Aria-label for the reset button.
+   * @default "Reset Search"
+   */
   resetSearchButtonTitle?: string;
+  /**
+   * Shows the reset button on mobile viewports.
+   * @default false
+   */
   showResetButtonOnMobile?: boolean;
 }>();
 

package/src/components/UiSearchInput/README.md

@@ -2,7 +2,7 @@
 
 ## Usage
 
-```vue
+```html
 <template>
   <UiSearchInput
     :has-add-entry-option="true"
@@ -34,25 +34,3 @@
   }
 </script>
 ```
-
-### Props
-| Name                | Type       | Default               | Description                                               |
-|---------------------|------------|-----------------------|-----------------------------------------------------------|
-| `hadAddEntryOption` | `boolean`  | `false`               | Ability to add more search input                          |
-| `modelValue`        | `string[]` | `required`            | Array of string arrays with the values of the input Field |
-| `label`             | `string`   | `""`                  | Sets Label for the input field                            |
-| `placeholder`       | `string`   | `Default placeholder` | Sets Placeholder attribute for the input                  |
-
-### Slots
-
-| Name      | Description   |
-|-----------|---------------|
-| `default` | Label content |
-
-### Events
-
-| Name                | Type                  | Description                                                                         |
-|---------------------|-----------------------|-------------------------------------------------------------------------------------|
-| `update:modelValue` | `UpdateValueEvent`    | Emits the Array of strings so the parent can handle the modification                |
-| `handleKeypress`    | `HandleKeypressEvent` | Emits the keyboard event and the array of strings                                   |
-| `blur`              | `BlurEven`            | Emits blur event of the input field and transports the values entered at this point |

package/src/components/UiSearchInput/UiSearchInput.vue

@@ -87,10 +87,29 @@ const slots = defineSlots<{
 
 const props = withDefaults(
   defineProps<{
+    /**
+     * The `id` attribute of the input element. Auto-generated when not set.
+     */
     id?: string;
+    /**
+     * Whether an additional "Add Row" button is shown next to the last
+     * input, allowing the user to add more input fields.
+     * @default false
+     */
     hasAddEntryOption?: boolean;
+    /**
+     * Sets the label for the input field.
+     * @default ""
+     */
     label?: string;
+    /**
+     * Array of string values, one per rendered input field.
+     */
     modelValue: string[];
+    /**
+     * Sets the placeholder attribute for the input.
+     * @default "Default placeholder"
+     */
     placeholder?: string;
   }>(),
   {
@@ -133,8 +152,20 @@ const deleteRow = (index: number, value: string) => {
 };
 
 const emit = defineEmits<{
+  /**
+   * Emitted with the updated array of values whenever an input field
+   * changes, so the parent can keep its state in sync.
+   */
   "update:modelValue": [string[]];
+  /**
+   * Emitted on every keydown on an input field, together with the keyboard
+   * event and the current array of values.
+   */
   handleKeypress: [{ event: KeyboardEvent; value: string[] }];
+  /**
+   * Emitted when an input field loses focus, together with the values
+   * entered at this point.
+   */
   blur: [string[]];
 }>();
 

package/src/components/UiSelect/README.md

@@ -4,7 +4,7 @@ Wraps the native `select` element.
 
 ## Usage
 
-```vue
+```html
 
 <UiSelect
   v-model="appearance"
@@ -25,30 +25,4 @@ Wraps the native `select` element.
 </UiSelect>
 ```
 
-## Props
-
-**Note**: This component binds all non-prop attributes (apart from `class`) on its principal element (the `select` element) 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.
-
-### modelValue
-
-- **Description**: Sets the `value` IDL attribute of the underlying `select` element. Allows using `v-model` on `UiSelect`.
-- **Type**: `string`
-- **Required**: No
-- **Default**: `undefined`
-
-## Slots
-
-### default
-
-The label content.
-
-### options
-
-Receives arbitrarily many `option` elements (or anything that is allowed in a native `select` element, see [select: Technical summary](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/select#technical_summary)).
-
-## Events
-
-### update:modelValue
-
-- **Description**: Fired when `select` fires `input`. Allows using `v-model` on `UiSelect`.
-- **Type**: `string`
+This component binds all non-prop attributes (apart from `class`) on its principal element (the `select` element) 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/UiSelect/UiSelect.vue

@@ -62,7 +62,9 @@ defineSlots<{
    */
   errors?: () => any;
   /**
-   * Select options.
+   * Receives arbitrarily many `option` elements (or anything that is
+   * allowed inside a native `select` element, see
+   * [select: Technical summary](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/select#technical_summary)).
    */
   options: () => any;
 }>();
@@ -74,6 +76,10 @@ const { id = undefined } = defineProps<{
   id?: string;
 }>();
 
+/**
+ * Sets the `value` IDL attribute of the underlying `select` element.
+ * Allows using `v-model` on `UiSelect`.
+ */
 const model = defineModel<string>();
 
 const defaultId = useId();

package/src/components/UiSkeletonBox/README.md

@@ -12,17 +12,3 @@
     import {UiSkeletonBox} from "@dpa-id-components/dpa-shared-components";
 </script>
 ```
-
-## API
-
-### Props
-
-| Name          | Type      | Default | Description                        |
-|---------------|-----------|---------|------------------------------------|
-| `dynamicSize` | `Boolean` | `false` | If true, generates a random width. |
-| `maxWidth`    | `Number`  | `100`   | Max width for random width.        |
-| `minWidth`    | `Number`  | `80`    | Min width for random width.        |
-
-### Slots
-
-This component has no slots

package/src/components/UiSkeletonBox/UiSkeletonBox.vue

@@ -16,8 +16,20 @@ const {
   minWidth = 80,
   dynamicSize = false,
 } = defineProps<{
+  /**
+   * Max width (in percent) used when generating a random width.
+   * @default 100
+   */
   maxWidth?: number;
+  /**
+   * Min width (in percent) used when generating a random width.
+   * @default 80
+   */
   minWidth?: number;
+  /**
+   * Whether to generate a random width between `minWidth` and `maxWidth`.
+   * @default false
+   */
   dynamicSize?: boolean;
 }>();
 

package/src/components/UiSnackbar/README.md

@@ -27,29 +27,3 @@ yarn add @dpa-id-components/UiSnackbar
   };
 </script>
 ```
-
-## API
-
-### Props
-
-| Name       | Type                             | Default  | Description                                                  |
-| ---------- | -------------------------------- | -------- | ------------------------------------------------------------ |
-| `isShown`  | `boolean`                        | `false`  | Visibility of the snackbar.                                  |
-| `position` | `left` or `right`                | `left`   | Location of the snackbar, fixed in the viewport.             |
-| `iconName` | `UiIconName`                     | required | Sets the `name`, which determines which svg is used as icon. |
-| `iconSize` | `small`, `medium`, `large`       | `medium` | Sets the `size` of the icon.                                 |
-| `type`     | `info`, `warning`                | `info`   | Sets the overall design of the snackbar.                     |
-
-### Slots
-
-| Name      | Description                             |
-| --------- | --------------------------------------- |
-| `default` | Default slot for text of the snackbar   |
-| `action`  | Optional slot for text in action button |
-
-### Events
-
-| Name           | Type      | Description                            |
-| -------------- | --------- | -------------------------------------- |
-| `action-click` | none      | Emitted when the action is clicked     |
-| `input`        | `boolean` | Emitted when the snackbar gets visible |