From e9ce8659f6e75d4e16753a152f3af026d18b12cb Mon Sep 17 00:00:00 2001
From: Cory LaViska <cory@abeautifulsite.net>
Date: Wed, 20 Aug 2025 12:31:55 -0400
Subject: [PATCH] rename icon-position to icon-placement (#1343)

---
 packages/webawesome/docs/docs/components/details.md    | 10 +++++-----
 packages/webawesome/docs/docs/resources/changelog.md   |  1 +
 packages/webawesome/src/components/details/details.css |  4 ++--
 packages/webawesome/src/components/details/details.ts  |  4 ++--
 4 files changed, 10 insertions(+), 9 deletions(-)

diff --git a/packages/webawesome/docs/docs/components/details.md b/packages/webawesome/docs/docs/components/details.md
index f35193982..bd4f7b8a1 100644
--- a/packages/webawesome/docs/docs/components/details.md
+++ b/packages/webawesome/docs/docs/components/details.md
@@ -50,15 +50,15 @@ Use the `expand-icon` and `collapse-icon` slots to change the expand and collaps
 
 ### Icon Position
 
-The default position for the expand and collapse icons is at the end of the summary. Set the `icon-position` attribute to `start` to place the icon at the start of the summary.
+The default position for the expand and collapse icons is at the end of the summary. Set the `icon-placement` attribute to `start` to place the icon at the start of the summary.
 
 ```html {.example}
 <div class="wa-stack">
-  <wa-details summary="Start" icon-position="start">
+  <wa-details summary="Start" icon-placement="start">
     Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna
     aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
   </wa-details>
-  <wa-details summary="End" icon-position="end">
+  <wa-details summary="End" icon-placement="end">
     Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna
     aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
   </wa-details>
@@ -85,14 +85,14 @@ Links and other interactive elements will still retain their behavior:
 
 ### Right-to-Left Languages
 
-The details component, including its `icon-position`, automatically adapts to right-to-left languages:
+The details component, including its `icon-placement`, automatically adapts to right-to-left languages:
 
 ```html {.example}
 <div class="wa-stack">
   <wa-details summary="تبديلني" lang="ar" dir="rtl">
     استخدام طريقة لوريم إيبسوم لأنها تعطي توزيعاَ طبيعياَ -إلى حد ما- للأحرف عوضاً عن
   </wa-details>
-  <wa-details summary="تبديلني" lang="ar" dir="rtl" icon-position="start">
+  <wa-details summary="تبديلني" lang="ar" dir="rtl" icon-placement="start">
     استخدام طريقة لوريم إيبسوم لأنها تعطي توزيعاَ طبيعياَ -إلى حد ما- للأحرف عوضاً عن
   </wa-details>
 </div>
diff --git a/packages/webawesome/docs/docs/resources/changelog.md b/packages/webawesome/docs/docs/resources/changelog.md
index bcb298757..1a48287c5 100644
--- a/packages/webawesome/docs/docs/resources/changelog.md
+++ b/packages/webawesome/docs/docs/resources/changelog.md
@@ -16,6 +16,7 @@ Components with the <wa-badge variant="warning">Experimental</wa-badge> badge sh
   - Added the `auto-width` attribute to automatically size icons, since FA7 is fixed-width by default now
   - Improved support for duotone icons in `<wa-icon>`, including custom colors, custom opacity, and opacity swapping
   - Removed the `fixed-width` attribute as it's now the default behavior
+- 🚨 BREAKING: Renamed the `icon-position` attribute to `icon-placement` in `<wa-details>` [discuss:1340]
 - 🚨 BREAKING: Removed the `size` attribute from `<wa-button-group>` as it only set the initial size and gets out of sync when buttons are updated (apply a `size` to each button instead)
 - Added the Hindi translation [pr:1307]
 - Fixed incorrectly named exported tooltip parts in `<wa-slider>` [pr:1277]
diff --git a/packages/webawesome/src/components/details/details.css b/packages/webawesome/src/components/details/details.css
index 39ba25ed4..fac63ebc4 100644
--- a/packages/webawesome/src/components/details/details.css
+++ b/packages/webawesome/src/components/details/details.css
@@ -102,8 +102,8 @@ details {
   }
 }
 
-/* 'Start' icon position */
-:host([icon-position='start']) summary {
+/* 'Start' icon placement */
+:host([icon-placement='start']) summary {
   flex-direction: row-reverse;
   justify-content: start;
 }
diff --git a/packages/webawesome/src/components/details/details.ts b/packages/webawesome/src/components/details/details.ts
index 4086d51f6..9b58f09ca 100644
--- a/packages/webawesome/src/components/details/details.ts
+++ b/packages/webawesome/src/components/details/details.ts
@@ -77,8 +77,8 @@ export default class WaDetails extends WebAwesomeElement {
   /** The element's visual appearance. */
   @property({ reflect: true }) appearance: 'filled' | 'outlined' | 'plain' = 'outlined';
 
-  /** The position of the expand/collapse icon. */
-  @property({ attribute: 'icon-position', reflect: true }) iconPosition: 'start' | 'end' = 'end';
+  /** The location of the expand/collapse icon. */
+  @property({ attribute: 'icon-placement', reflect: true }) iconPlacement: 'start' | 'end' = 'end';
 
   disconnectedCallback() {
     super.disconnectedCallback();