From 0567c47aaac120c1c09d9dbec13323fec8596bf5 Mon Sep 17 00:00:00 2001
From: Stefan Dietz <mail@stefan-dietz.eu>
Date: Thu, 23 Jan 2025 12:19:09 +0100
Subject: [PATCH] Unify JSDoc property descriptions

Refs: #7115
---
 packages/components/src/components/accordion/shadow.tsx    | 2 +-
 packages/components/src/components/button-link/shadow.tsx  | 2 +-
 packages/components/src/components/button/component.tsx    | 2 +-
 packages/components/src/components/button/shadow.tsx       | 4 ++--
 packages/components/src/components/combobox/shadow.tsx     | 2 +-
 packages/components/src/components/details/shadow.tsx      | 2 +-
 packages/components/src/components/drawer/shadow.tsx       | 4 ++--
 packages/components/src/components/input/component.tsx     | 2 +-
 packages/components/src/components/link-button/shadow.tsx  | 2 +-
 packages/components/src/components/link/component.tsx      | 2 +-
 packages/components/src/components/link/shadow.tsx         | 4 ++--
 packages/components/src/components/tabs/shadow.tsx         | 2 +-
 packages/components/src/components/toolbar/shadow.tsx      | 2 +-
 packages/components/src/components/tree-item/component.tsx | 6 +++---
 packages/components/src/components/tree-item/shadow.tsx    | 6 +++---
 packages/components/src/components/tree/component.tsx      | 2 +-
 packages/components/src/components/tree/shadow.tsx         | 2 +-
 packages/components/src/schema/props/access-key.ts         | 2 +-
 packages/components/src/schema/props/align.ts              | 2 +-
 packages/components/src/schema/props/href.ts               | 2 +-
 packages/components/src/schema/props/label.ts              | 2 +-
 packages/components/src/schema/props/open.ts               | 2 +-
 packages/components/src/schema/props/short-key.ts          | 2 +-
 23 files changed, 30 insertions(+), 30 deletions(-)

diff --git a/packages/components/src/components/accordion/shadow.tsx b/packages/components/src/components/accordion/shadow.tsx
index fd22b42a47..7d30d49009 100644
--- a/packages/components/src/components/accordion/shadow.tsx
+++ b/packages/components/src/components/accordion/shadow.tsx
@@ -119,7 +119,7 @@ export class KolAccordion implements AccordionAPI, FocusableElement {
 	@Prop() public _on?: AccordionCallbacksPropType<boolean>;
 
 	/**
-	 * If set (to true) opens/expands the element, closes if not set (or set to false).
+	 * Opens/expands the element when truthy, closes/collapses when falsy.
 	 * @TODO: Change type back to `OpenPropType` after Stencil#4663 has been resolved.
 	 */
 	@Prop({ mutable: true, reflect: true }) public _open?: boolean = false;
diff --git a/packages/components/src/components/button-link/shadow.tsx b/packages/components/src/components/button-link/shadow.tsx
index 8a3307693e..99110012e2 100644
--- a/packages/components/src/components/button-link/shadow.tsx
+++ b/packages/components/src/components/button-link/shadow.tsx
@@ -77,7 +77,7 @@ export class KolButtonLink implements ButtonLinkProps, FocusableElement {
 	}
 
 	/**
-	 * Defines the elements access key.
+	 * Defines which key combination can be used to trigger or focus the interactive element of the component.
 	 */
 	@Prop() public _accessKey?: AccessKeyPropType;
 
diff --git a/packages/components/src/components/button/component.tsx b/packages/components/src/components/button/component.tsx
index be34a72421..67aedc72e5 100644
--- a/packages/components/src/components/button/component.tsx
+++ b/packages/components/src/components/button/component.tsx
@@ -177,7 +177,7 @@ export class KolButtonWc implements ButtonAPI, FocusableElement {
 	private readonly controller: AssociatedInputController;
 
 	/**
-	 * Defines the elements access key.
+	 * Defines which key combination can be used to trigger or focus the interactive element of the component.
 	 */
 	@Prop() public _accessKey?: AccessKeyPropType;
 
diff --git a/packages/components/src/components/button/shadow.tsx b/packages/components/src/components/button/shadow.tsx
index 5dbda23a4e..1be0f3879e 100644
--- a/packages/components/src/components/button/shadow.tsx
+++ b/packages/components/src/components/button/shadow.tsx
@@ -79,7 +79,7 @@ export class KolButton implements ButtonProps, FocusableElement {
 	}
 
 	/**
-	 * Defines the elements access key.
+	 * Defines which key combination can be used to trigger or focus the interactive element of the component.
 	 */
 	@Prop() public _accessKey?: AccessKeyPropType;
 
@@ -151,7 +151,7 @@ export class KolButton implements ButtonProps, FocusableElement {
 	@Prop() public _role?: AlternativeButtonLinkRolePropType;
 
 	/**
-	 * Defines the elements short key.
+	 * Adds a visual short key hint to the component.
 	 */
 	@Prop() public _shortKey?: ShortKeyPropType;
 
diff --git a/packages/components/src/components/combobox/shadow.tsx b/packages/components/src/components/combobox/shadow.tsx
index 6d691e485e..15869ebf12 100644
--- a/packages/components/src/components/combobox/shadow.tsx
+++ b/packages/components/src/components/combobox/shadow.tsx
@@ -430,7 +430,7 @@ export class KolCombobox implements ComboboxAPI {
 	@Prop() public _on?: InputTypeOnDefault;
 
 	/**
-	 * Suggestions the user can choose from.
+	 * Suggestions to provide for the input.
 	 */
 	@Prop() public _suggestions!: SuggestionsPropType;
 
diff --git a/packages/components/src/components/details/shadow.tsx b/packages/components/src/components/details/shadow.tsx
index 7fab03b159..e24fc6fc1f 100644
--- a/packages/components/src/components/details/shadow.tsx
+++ b/packages/components/src/components/details/shadow.tsx
@@ -109,7 +109,7 @@ export class KolDetails implements DetailsAPI, FocusableElement {
 	@Prop() public _on?: DetailsCallbacksPropType<boolean>;
 
 	/**
-	 * If set (to true) opens/expands the element, closes if not set (or set to false).
+	 * Opens/expands the element when truthy, closes/collapses when falsy.
 	 * @TODO: Change type back to `OpenPropType` after Stencil#4663 has been resolved.
 	 */
 	@Prop({ mutable: true, reflect: true }) public _open?: boolean = false;
diff --git a/packages/components/src/components/drawer/shadow.tsx b/packages/components/src/components/drawer/shadow.tsx
index 7a3f5adbb6..eca4d86f5c 100644
--- a/packages/components/src/components/drawer/shadow.tsx
+++ b/packages/components/src/components/drawer/shadow.tsx
@@ -77,12 +77,12 @@ export class KolDrawer implements DrawerAPI {
 	}
 
 	/**
-	 * Specifies the default open state of the drawer.
+	 * Opens/expands the element when truthy, closes/collapses when falsy.
 	 */
 	@Prop() public _open?: OpenPropType;
 
 	/**
-	 * Specifies the orientation of the drawer.
+	 * Defines the visual orientation of the component.
 	 */
 	@Prop() public _align?: AlignPropType;
 
diff --git a/packages/components/src/components/input/component.tsx b/packages/components/src/components/input/component.tsx
index 93671a73f1..2d72f3bccc 100644
--- a/packages/components/src/components/input/component.tsx
+++ b/packages/components/src/components/input/component.tsx
@@ -161,7 +161,7 @@ export class KolInputWc implements Props {
 	}
 
 	/**
-	 * Defines the elements access key.
+	 * Defines which key combination can be used to trigger or focus the interactive element of the component.
 	 */
 	@Prop() public _accessKey?: AccessKeyPropType;
 
diff --git a/packages/components/src/components/link-button/shadow.tsx b/packages/components/src/components/link-button/shadow.tsx
index d62a6d1d28..9616dbc2d9 100644
--- a/packages/components/src/components/link-button/shadow.tsx
+++ b/packages/components/src/components/link-button/shadow.tsx
@@ -69,7 +69,7 @@ export class KolLinkButton implements LinkButtonProps, FocusableElement {
 	}
 
 	/**
-	 * Defines the elements access key.
+	 * Defines which key combination can be used to trigger or focus the interactive element of the component.
 	 */
 	@Prop() public _accessKey?: AccessKeyPropType;
 
diff --git a/packages/components/src/components/link/component.tsx b/packages/components/src/components/link/component.tsx
index 9927c0dc08..c739be2934 100644
--- a/packages/components/src/components/link/component.tsx
+++ b/packages/components/src/components/link/component.tsx
@@ -209,7 +209,7 @@ export class KolLinkWc implements LinkAPI, FocusableElement {
 	}
 
 	/**
-	 * Defines the elements access key.
+	 * Defines which key combination can be used to trigger or focus the interactive element of the component.
 	 */
 	@Prop() public _accessKey?: AccessKeyPropType;
 
diff --git a/packages/components/src/components/link/shadow.tsx b/packages/components/src/components/link/shadow.tsx
index 2d6b51d2f2..c939560dc6 100644
--- a/packages/components/src/components/link/shadow.tsx
+++ b/packages/components/src/components/link/shadow.tsx
@@ -70,7 +70,7 @@ export class KolLink implements LinkProps, FocusableElement {
 	}
 
 	/**
-	 * Defines the elements access key.
+	 * Defines which key combination can be used to trigger or focus the interactive element of the component.
 	 */
 	@Prop() public _accessKey?: AccessKeyPropType;
 
@@ -127,7 +127,7 @@ export class KolLink implements LinkProps, FocusableElement {
 	@Prop() public _role?: AlternativeButtonLinkRolePropType;
 
 	/**
-	 * Defines the elements access key.
+	 * Adds a visual short key hint to the component.
 	 */
 	@Prop() public _shortKey?: ShortKeyPropType;
 
diff --git a/packages/components/src/components/tabs/shadow.tsx b/packages/components/src/components/tabs/shadow.tsx
index 5ea738ad65..bfbf0fd7de 100644
--- a/packages/components/src/components/tabs/shadow.tsx
+++ b/packages/components/src/components/tabs/shadow.tsx
@@ -213,7 +213,7 @@ export class KolTabs implements TabsAPI {
 	}
 
 	/**
-	 * Defines the position of the tab captions.
+	 * Defines the visual orientation of the component.
 	 */
 	@Prop() public _align?: AlignPropType = 'top';
 
diff --git a/packages/components/src/components/toolbar/shadow.tsx b/packages/components/src/components/toolbar/shadow.tsx
index 0e14f39803..668a96f87a 100644
--- a/packages/components/src/components/toolbar/shadow.tsx
+++ b/packages/components/src/components/toolbar/shadow.tsx
@@ -51,7 +51,7 @@ export class KolToolbar implements ToolbarAPI {
 	}
 
 	/**
-	 * Defines the semantic aria-label of the component.
+	 * Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.).
 	 */
 	@Prop() public _label!: string;
 
diff --git a/packages/components/src/components/tree-item/component.tsx b/packages/components/src/components/tree-item/component.tsx
index 37e5b017b3..ab5e7a230d 100644
--- a/packages/components/src/components/tree-item/component.tsx
+++ b/packages/components/src/components/tree-item/component.tsx
@@ -79,17 +79,17 @@ export class KolTreeItemWc implements TreeItemAPI {
 	@Prop() _active?: OpenPropType;
 
 	/**
-	 * Defines the label of the link.
+	 * Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.).
 	 */
 	@Prop() _label!: LabelPropType;
 
 	/**
-	 * If set (to true) opens/expands the element, closes if not set (or set to false).
+	 * Opens/expands the element when truthy, closes/collapses when falsy.
 	 */
 	@Prop() _open?: OpenPropType;
 
 	/**
-	 * This property is used for a link from a reference to the target URL.
+	 * Defines the target URI of the link.
 	 */
 	@Prop() _href!: HrefPropType;
 
diff --git a/packages/components/src/components/tree-item/shadow.tsx b/packages/components/src/components/tree-item/shadow.tsx
index dfd144d717..3990cc3ea3 100644
--- a/packages/components/src/components/tree-item/shadow.tsx
+++ b/packages/components/src/components/tree-item/shadow.tsx
@@ -19,17 +19,17 @@ export class KolTreeItem implements TreeItemProps {
 	@Prop() _active?: OpenPropType;
 
 	/**
-	 * Defines the label of the link.
+	 * Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.).
 	 */
 	@Prop() _label!: LabelPropType;
 
 	/**
-	 * If set (to true) opens/expands the element, closes if not set (or set to false).
+	 * Opens/expands the element when truthy, closes/collapses when falsy.
 	 */
 	@Prop() _open?: OpenPropType;
 
 	/**
-	 * This property is used for a link from a reference to the target URL.
+	 * Defines the target URI of the link.
 	 */
 	@Prop() _href!: HrefPropType;
 
diff --git a/packages/components/src/components/tree/component.tsx b/packages/components/src/components/tree/component.tsx
index ad5e86d90a..f3b55212b2 100644
--- a/packages/components/src/components/tree/component.tsx
+++ b/packages/components/src/components/tree/component.tsx
@@ -22,7 +22,7 @@ export class KolTreeWc implements TreeAPI {
 	private treeItemElements?: HTMLKolTreeItemElement[];
 
 	/**
-	 * Defines the label of the tree.
+	 * Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.).
 	 */
 	@Prop() _label!: LabelPropType;
 
diff --git a/packages/components/src/components/tree/shadow.tsx b/packages/components/src/components/tree/shadow.tsx
index 59201ce2bf..97d1a2bff2 100644
--- a/packages/components/src/components/tree/shadow.tsx
+++ b/packages/components/src/components/tree/shadow.tsx
@@ -13,7 +13,7 @@ import { KolTreeWcTag } from '../../core/component-names';
 })
 export class KolTree implements TreeProps {
 	/**
-	 * Defines the label of the tree.
+	 * Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.).
 	 */
 	@Prop() _label!: LabelPropType;
 
diff --git a/packages/components/src/schema/props/access-key.ts b/packages/components/src/schema/props/access-key.ts
index 8c108d8551..0763adaf8e 100644
--- a/packages/components/src/schema/props/access-key.ts
+++ b/packages/components/src/schema/props/access-key.ts
@@ -5,7 +5,7 @@ import { watchString } from '../utils';
 export type AccessKeyPropType = string;
 
 /**
- * Defines the elements access key.
+ * Defines which key combination can be used to trigger or focus the interactive element of the component.
  * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/accesskey
  */
 export type PropAccessKey = {
diff --git a/packages/components/src/schema/props/align.ts b/packages/components/src/schema/props/align.ts
index 02aa2a0447..cbb3efa251 100644
--- a/packages/components/src/schema/props/align.ts
+++ b/packages/components/src/schema/props/align.ts
@@ -11,7 +11,7 @@ export const alignPropTypeOptions = [...horizontalAlignOptions, ...verticalAlign
 export type AlignPropType = HorizontalAlign | VerticalAlign;
 
 /**
- * Defines where to show the element preferably: top, right, bottom or left.
+ * Defines the visual orientation of the component: top, right, bottom or left.
  */
 export type PropAlign = {
 	align: AlignPropType;
diff --git a/packages/components/src/schema/props/href.ts b/packages/components/src/schema/props/href.ts
index fbce77b36b..f7f3cff19c 100644
--- a/packages/components/src/schema/props/href.ts
+++ b/packages/components/src/schema/props/href.ts
@@ -7,7 +7,7 @@ import { watchString } from '../utils';
 export type HrefPropType = string;
 
 /**
- * This property is used for a link from a reference to the target URL.
+ * Defines the target URI of the link.
  */
 export type PropHref = {
 	href: HrefPropType;
diff --git a/packages/components/src/schema/props/label.ts b/packages/components/src/schema/props/label.ts
index 6e426a3a83..96a19fd76d 100644
--- a/packages/components/src/schema/props/label.ts
+++ b/packages/components/src/schema/props/label.ts
@@ -51,7 +51,7 @@ export function containsOnlyNumbers(str: string): boolean {
 }
 
 /**
- * Defines the type of the label property.
+ * Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.).
  */
 export type LabelPropType = string;
 
diff --git a/packages/components/src/schema/props/open.ts b/packages/components/src/schema/props/open.ts
index a85e2a09ee..c24285e90d 100644
--- a/packages/components/src/schema/props/open.ts
+++ b/packages/components/src/schema/props/open.ts
@@ -7,7 +7,7 @@ import { watchBoolean } from '../utils';
 export type OpenPropType = boolean;
 
 /**
- * If set (to true) opens/expands the element, closes if not set (or set to false).
+ * Opens/expands the element when truthy, closes/collapses when falsy.
  */
 export type PropOpen = {
 	open: OpenPropType;
diff --git a/packages/components/src/schema/props/short-key.ts b/packages/components/src/schema/props/short-key.ts
index 28f6344899..c9af4f1a72 100644
--- a/packages/components/src/schema/props/short-key.ts
+++ b/packages/components/src/schema/props/short-key.ts
@@ -5,7 +5,7 @@ import { watchString } from '../utils';
 export type ShortKeyPropType = string;
 
 /**
- * Defines the elements short key.
+ * Adds a visual short key hint to the component.
  */
 export type PropShortKey = {
 	shortKey: ShortKeyPropType;