From 62ddf13a6afcfe8e12b60c2c25e2ba98521a01bf Mon Sep 17 00:00:00 2001
From: Cory LaViska <cory@abeautifulsite.net>
Date: Wed, 21 May 2025 13:34:24 -0400
Subject: [PATCH] Rename `vertical` to `orientation="vertical"`; fixes #674
 (#963)

* vertical => orientation="vertical"; fixes #674

* add issue

* Update divider styles and docs to use `orientation='vertical'`

* Update split panel styles and docs to use `orientation='vertical'`

* Update remaining docs and patterns examples to `orientation='vertical'`

---------

Co-authored-by: lindsaym-fa <dev@lindsaym.design>
---
 docs/docs/components/divider.md               |  8 ++---
 docs/docs/components/split-panel.md           |  8 ++---
 docs/docs/patterns/app/activity-log.md        |  8 ++---
 docs/docs/patterns/app/comments.md            |  2 +-
 docs/docs/patterns/app/description-list.md    |  4 +--
 docs/docs/patterns/ecommerce/order-summary.md |  2 +-
 .../patterns/ecommerce/product-preview.md     |  2 +-
 docs/docs/resources/changelog.md              |  1 +
 src/components/divider/divider.css            |  4 +--
 src/components/divider/divider.test.ts        |  4 +--
 src/components/divider/divider.ts             |  8 ++---
 src/components/split-panel/split-panel.css    | 10 +++----
 .../split-panel/split-panel.test.ts           | 14 ++++-----
 src/components/split-panel/split-panel.ts     | 30 +++++++++++--------
 14 files changed, 56 insertions(+), 49 deletions(-)

diff --git a/docs/docs/components/divider.md b/docs/docs/components/divider.md
index eb7abffcd..30bbed5e0 100644
--- a/docs/docs/components/divider.md
+++ b/docs/docs/components/divider.md
@@ -39,16 +39,16 @@ Use the `--spacing` custom property to change the amount of space between the di
 </div>
 ```
 
-### Vertical
+### Orientation
 
-Add the `vertical` attribute to draw the divider in a vertical orientation. The divider will span the full height of its container. Vertical dividers work especially well inside of a flex container.
+The default orientation for dividers is `horizontal`. Set `orientation` attribute to `vertical` to draw a vertical divider. The divider will span the full height of its container.
 
 ```html {.example}
 <div style="display: flex; align-items: center; height: 2rem;">
   First
-  <wa-divider vertical></wa-divider>
+  <wa-divider orientation="vertical"></wa-divider>
   Middle
-  <wa-divider vertical></wa-divider>
+  <wa-divider orientation="vertical"></wa-divider>
   Last
 </div>
 ```
diff --git a/docs/docs/components/split-panel.md b/docs/docs/components/split-panel.md
index e604a9ac5..adfaf1f04 100644
--- a/docs/docs/components/split-panel.md
+++ b/docs/docs/components/split-panel.md
@@ -80,12 +80,12 @@ To set the initial position in pixels instead of a percentage, use the `position
 </wa-split-panel>
 ```
 
-### Vertical
+### Orientation
 
-Add the `vertical` attribute to render the split panel in a vertical orientation where the start and end panels are stacked. You also need to set a height when using the vertical orientation.
+Set the `orientation` attribute to `vertical` and provide a height to render the split panel in a vertical orientation where the start and end panels are stacked.
 
 ```html {.example}
-<wa-split-panel vertical style="height: 400px;">
+<wa-split-panel orientation="vertical" style="height: 400px;">
   <div
     slot="start"
     style="height: 100%; background: var(--wa-color-surface-lowered); display: flex; align-items: center; justify-content: center; overflow: hidden;"
@@ -248,7 +248,7 @@ Create complex layouts that can be repositioned independently by nesting split p
     Start
   </div>
   <div slot="end">
-    <wa-split-panel vertical style="height: 400px;">
+    <wa-split-panel orientation="vertical" style="height: 400px;">
       <div
         slot="start"
         style="height: 100%; background: var(--wa-color-surface-lowered); display: flex; align-items: center; justify-content: center; overflow: hidden"
diff --git a/docs/docs/patterns/app/activity-log.md b/docs/docs/patterns/app/activity-log.md
index 15dd48432..3a72b9cf4 100644
--- a/docs/docs/patterns/app/activity-log.md
+++ b/docs/docs/patterns/app/activity-log.md
@@ -66,7 +66,7 @@ description: 'Track and organize recent user actions or events.'
       <wa-format-date date="2025-04-01" month="short" day="numeric"></wa-format-date>
     </div>
   </article>
-  <wa-divider vertical style="height: 1em; margin-left: 1rem"></wa-divider>
+  <wa-divider orientation="vertical" style="height: 1em; margin-left: 1rem"></wa-divider>
   <article class="wa-flank" style="flex-wrap: nowrap">
     <wa-avatar style="--size: 2rem">
       <wa-icon slot="icon" name="seedling"></wa-icon>
@@ -76,7 +76,7 @@ description: 'Track and organize recent user actions or events.'
       <wa-format-date date="2025-05-29" month="short" day="numeric"></wa-format-date>
     </div>
   </article>
-  <wa-divider vertical style="height: 1em; margin-left: 1rem"></wa-divider>
+  <wa-divider orientation="vertical" style="height: 1em; margin-left: 1rem"></wa-divider>
   <article class="wa-flank" style="flex-wrap: nowrap">
     <wa-avatar style="--size: 2rem">
       <wa-icon slot="icon" name="tree-deciduous"></wa-icon>
@@ -86,7 +86,7 @@ description: 'Track and organize recent user actions or events.'
       <wa-format-date date="2025-09-15" month="short" day="numeric"></wa-format-date>
     </div>
   </article>
-  <wa-divider vertical style="height: 1em; margin-left: 1rem"></wa-divider>
+  <wa-divider orientation="vertical" style="height: 1em; margin-left: 1rem"></wa-divider>
   <article class="wa-flank" style="flex-wrap: nowrap">
     <wa-avatar style="--size: 2rem">
       <wa-icon slot="icon" name="crate-apple"></wa-icon>
@@ -218,7 +218,7 @@ description: 'Track and organize recent user actions or events.'
       </div>
     </wa-card>
     <div class="wa-flank wa-gap-xl">
-      <wa-divider vertical style="height: auto; align-self: stretch"></wa-divider>
+      <wa-divider orientation="vertical" style="height: auto; align-self: stretch"></wa-divider>
       <ul class="wa-stack">
         <li class="wa-stack wa-gap-2xs">
           <wa-card>
diff --git a/docs/docs/patterns/app/comments.md b/docs/docs/patterns/app/comments.md
index b9e77716b..370a400a2 100644
--- a/docs/docs/patterns/app/comments.md
+++ b/docs/docs/patterns/app/comments.md
@@ -51,7 +51,7 @@ isPro: true
         </p>
       </li>
       <div class="wa-flank wa-gap-xl">
-        <wa-divider vertical style="height: auto; align-self: stretch"></wa-divider>
+        <wa-divider orientation="vertical" style="height: auto; align-self: stretch"></wa-divider>
         <ul class="wa-stack">
           <li class="wa-stack wa-gap-2xs">
             <div class="wa-flank">
diff --git a/docs/docs/patterns/app/description-list.md b/docs/docs/patterns/app/description-list.md
index 63d9b6fa8..d9085bdf7 100644
--- a/docs/docs/patterns/app/description-list.md
+++ b/docs/docs/patterns/app/description-list.md
@@ -195,7 +195,7 @@ isPro: true
                 </span>
                 <div class="wa-cluster wa-gap-2xs">
                   <wa-button appearance="plain" variant="brand" size="small">Download</wa-button>
-                  <wa-divider vertical style="height: 1em"></wa-divider>
+                  <wa-divider orientation="vertical" style="height: 1em"></wa-divider>
                   <wa-button appearance="plain" variant="danger" size="small">Delete</wa-button>
                 </div>
               </div>
@@ -210,7 +210,7 @@ isPro: true
                 </span>
                 <div class="wa-cluster wa-gap-2xs">
                   <wa-button appearance="plain" variant="brand" size="small">Download</wa-button>
-                  <wa-divider vertical style="height: 1em"></wa-divider>
+                  <wa-divider orientation="vertical" style="height: 1em"></wa-divider>
                   <wa-button appearance="plain" variant="danger" size="small">Delete</wa-button>
                 </div>
               </div>
diff --git a/docs/docs/patterns/ecommerce/order-summary.md b/docs/docs/patterns/ecommerce/order-summary.md
index d8688073f..211eaf386 100644
--- a/docs/docs/patterns/ecommerce/order-summary.md
+++ b/docs/docs/patterns/ecommerce/order-summary.md
@@ -102,7 +102,7 @@ isPro: true
         >Order placed
         <wa-format-date date="2025-02-26T09:00:00-04:00" month="long" day="numeric" year="numeric"></wa-format-date
       ></span>
-      <wa-divider vertical style="height: 2em"></wa-divider>
+      <wa-divider orientation="vertical" style="height: 2em"></wa-divider>
       <span>Order # 45646456-4656-4542</span>
     </div>
     <wa-button size="small" appearance="outlined" pill>View Invoice</wa-button>
diff --git a/docs/docs/patterns/ecommerce/product-preview.md b/docs/docs/patterns/ecommerce/product-preview.md
index c143a79c4..489141e50 100644
--- a/docs/docs/patterns/ecommerce/product-preview.md
+++ b/docs/docs/patterns/ecommerce/product-preview.md
@@ -24,7 +24,7 @@ isPro: true
       <div class="wa-stack wa-gap-xl">
         <div class="wa-cluster">
           <span class="wa-heading-2xl">$32</span>
-          <wa-divider vertical style="height: 2em"></wa-divider>
+          <wa-divider orientation="vertical" style="height: 2em"></wa-divider>
           <wa-rating label="Rating" value="3.75" readonly></wa-rating>
           <a href="" class="wa-caption-m">36 Reviews</a>
         </div>
diff --git a/docs/docs/resources/changelog.md b/docs/docs/resources/changelog.md
index d92da39c1..e8644be55 100644
--- a/docs/docs/resources/changelog.md
+++ b/docs/docs/resources/changelog.md
@@ -16,6 +16,7 @@ During the alpha period, things might break! We take breaking changes very serio
 
 - 🚨 BREAKING: Renamed the `classic` theme to `shoelace`
 - 🚨 BREAKING: Renamed `pulse` attribute in `<wa-badge>` to `attention="pulse"` and added `attention="bounce"` [issue:#940]
+- 🚨 BREAKING: Renamed the `vertical` attribute to `orientation="vertical"` in `<wa-split-panel>` and `<wa-divider>` to align with other components and the platform [issue:674]
 - Fixed a bug in `<wa-radio-group>` that caused radios to uncheck when assigning a numeric value [issue:924]
 
 ## 3.0.0-alpha.13
diff --git a/src/components/divider/divider.css b/src/components/divider/divider.css
index 20499b64d..0edd71032 100644
--- a/src/components/divider/divider.css
+++ b/src/components/divider/divider.css
@@ -4,13 +4,13 @@
   --spacing: var(--wa-space-m);
 }
 
-:host(:not([vertical])) {
+:host(:not([orientation='vertical'])) {
   display: block;
   border-top: solid var(--width) var(--color);
   margin: var(--spacing) 0;
 }
 
-:host([vertical]) {
+:host([orientation='vertical']) {
   display: inline-block;
   height: 100%;
   border-left: solid var(--width) var(--color);
diff --git a/src/components/divider/divider.test.ts b/src/components/divider/divider.test.ts
index c15168f8c..611ce2543 100644
--- a/src/components/divider/divider.test.ts
+++ b/src/components/divider/divider.test.ts
@@ -10,7 +10,7 @@ describe('<wa-divider>', () => {
         it('default properties', async () => {
           const el = await fixture<WaDivider>(html` <wa-divider></wa-divider> `);
 
-          expect(el.vertical).to.be.false;
+          expect(el.orientation).to.equal('horizontal');
           expect(el.getAttribute('role')).to.equal('separator');
           expect(el.getAttribute('aria-orientation')).to.equal('horizontal');
         });
@@ -25,7 +25,7 @@ describe('<wa-divider>', () => {
         it('aria-orientation is updated', async () => {
           const el = await fixture<WaDivider>(html` <wa-divider></wa-divider> `);
 
-          el.vertical = true;
+          el.orientation = 'vertical';
           await elementUpdated(el);
 
           expect(el.getAttribute('aria-orientation')).to.equal('vertical');
diff --git a/src/components/divider/divider.ts b/src/components/divider/divider.ts
index 43303c073..aa866ae5b 100644
--- a/src/components/divider/divider.ts
+++ b/src/components/divider/divider.ts
@@ -17,17 +17,17 @@ import styles from './divider.css';
 export default class WaDivider extends WebAwesomeElement {
   static shadowStyle = styles;
 
-  /** Draws the divider in a vertical orientation. */
-  @property({ type: Boolean, reflect: true }) vertical = false;
+  /** Sets the divider's orientation. */
+  @property({ reflect: true }) orientation: 'horizontal' | 'vertical' = 'horizontal';
 
   connectedCallback() {
     super.connectedCallback();
     this.setAttribute('role', 'separator');
   }
 
-  @watch('vertical')
+  @watch('orientation')
   handleVerticalChange() {
-    this.setAttribute('aria-orientation', this.vertical ? 'vertical' : 'horizontal');
+    this.setAttribute('aria-orientation', this.orientation);
   }
 }
 
diff --git a/src/components/split-panel/split-panel.css b/src/components/split-panel/split-panel.css
index 7b49ac166..f520feef3 100644
--- a/src/components/split-panel/split-panel.css
+++ b/src/components/split-panel/split-panel.css
@@ -37,11 +37,11 @@
 }
 
 /* Horizontal */
-:host(:not([vertical], [disabled])) .divider {
+:host(:not([orientation='vertical'], [disabled])) .divider {
   cursor: col-resize;
 }
 
-:host(:not([vertical])) .divider::after {
+:host(:not([orientation='vertical'])) .divider::after {
   display: flex;
   content: '';
   position: absolute;
@@ -51,15 +51,15 @@
 }
 
 /* Vertical */
-:host([vertical]) {
+:host([orientation='vertical']) {
   flex-direction: column;
 }
 
-:host([vertical]:not([disabled])) .divider {
+:host([orientation='vertical']:not([disabled])) .divider {
   cursor: row-resize;
 }
 
-:host([vertical]) .divider::after {
+:host([orientation='vertical']) .divider::after {
   content: '';
   position: absolute;
   width: 100%;
diff --git a/src/components/split-panel/split-panel.test.ts b/src/components/split-panel/split-panel.test.ts
index 18fd69859..c68d4803f 100644
--- a/src/components/split-panel/split-panel.test.ts
+++ b/src/components/split-panel/split-panel.test.ts
@@ -185,7 +185,7 @@ describe('<wa-split-panel>', () => {
       describe('panel sizing vertical', () => {
         it('has two evenly sized panels by default', async () => {
           const splitPanel = await fixture<WaSplitPanel>(
-            html`<wa-split-panel vertical style="height: 400px;">
+            html`<wa-split-panel orientation="vertical" style="height: 400px;">
               <div slot="start" data-testid="start-panel">Start</div>
               <div slot="end" data-testid="end-panel">End</div>
             </wa-split-panel>`,
@@ -199,7 +199,7 @@ describe('<wa-split-panel>', () => {
 
         it('changes the sizing of the panels based on the position attribute', async () => {
           const splitPanel = await fixture<WaSplitPanel>(
-            html`<wa-split-panel position="25" vertical style="height: 400px;">
+            html`<wa-split-panel position="25" orientation="vertical" style="height: 400px;">
               <div slot="start" data-testid="start-panel">Start</div>
               <div slot="end" data-testid="end-panel">End</div>
             </wa-split-panel>`,
@@ -213,7 +213,7 @@ describe('<wa-split-panel>', () => {
 
         it('updates the position in pixels to the correct result', async () => {
           const splitPanel = await fixture<WaSplitPanel>(
-            html`<wa-split-panel position="25" vertical style="height: 400px;">
+            html`<wa-split-panel position="25" orientation="vertical" style="height: 400px;">
               <div slot="start" data-testid="start-panel">Start</div>
               <div slot="end" data-testid="end-panel">End</div>
             </wa-split-panel>`,
@@ -228,7 +228,7 @@ describe('<wa-split-panel>', () => {
 
         it('emits the wa-reposition	event on position change ', async () => {
           const splitPanel = await fixture<WaSplitPanel>(
-            html`<wa-split-panel vertical style="height: 400px;">
+            html`<wa-split-panel orientation="vertical" style="height: 400px;">
               <div slot="start">Start</div>
               <div slot="end">End</div>
             </wa-split-panel>`,
@@ -241,7 +241,7 @@ describe('<wa-split-panel>', () => {
 
         it('can be resized using the mouse ', async () => {
           const splitPanel = await fixture<WaSplitPanel>(
-            html`<wa-split-panel vertical style="height: 400px;">
+            html`<wa-split-panel orientation="vertical" style="height: 400px;">
               <div slot="start">Start</div>
               <div slot="end">End</div>
             </wa-split-panel>`,
@@ -259,7 +259,7 @@ describe('<wa-split-panel>', () => {
 
         it('cannot be resized if disabled', async () => {
           const splitPanel = await fixture<WaSplitPanel>(
-            html`<wa-split-panel disabled vertical style="height: 400px;">
+            html`<wa-split-panel disabled orientation="vertical" style="height: 400px;">
               <div slot="start">Start</div>
               <div slot="end">End</div>
             </wa-split-panel>`,
@@ -277,7 +277,7 @@ describe('<wa-split-panel>', () => {
 
         it('snaps to predefined positions', async () => {
           const splitPanel = await fixture<WaSplitPanel>(
-            html`<wa-split-panel vertical style="height: 400px;">
+            html`<wa-split-panel orientation="vertical" style="height: 400px;">
               <div slot="start">Start</div>
               <div slot="end">End</div>
             </wa-split-panel>`,
diff --git a/src/components/split-panel/split-panel.ts b/src/components/split-panel/split-panel.ts
index e2eab2314..951e1345e 100644
--- a/src/components/split-panel/split-panel.ts
+++ b/src/components/split-panel/split-panel.ts
@@ -55,8 +55,8 @@ export default class WaSplitPanel extends WebAwesomeElement {
   /** The current position of the divider from the primary panel's edge in pixels. */
   @property({ attribute: 'position-in-pixels', type: Number }) positionInPixels: number;
 
-  /** Draws the split panel in a vertical orientation with the start and end panels stacked. */
-  @property({ type: Boolean, reflect: true }) vertical = false;
+  /** Sets the split panel's orientation. */
+  @property({ reflect: true }) orientation: 'horizontal' | 'vertical' = 'horizontal';
 
   /** Disables resizing. Note that the position may still change as a result of resizing the host element. */
   @property({ type: Boolean, reflect: true }) disabled = false;
@@ -93,7 +93,7 @@ export default class WaSplitPanel extends WebAwesomeElement {
 
   private detectSize() {
     const { width, height } = this.getBoundingClientRect();
-    this.size = this.vertical ? height : width;
+    this.size = this.orientation === 'vertical' ? height : width;
   }
 
   private percentageToPixels(value: number) {
@@ -118,7 +118,7 @@ export default class WaSplitPanel extends WebAwesomeElement {
 
     drag(this, {
       onMove: (x, y) => {
-        let newPositionInPixels = this.vertical ? y : x;
+        let newPositionInPixels = this.orientation === 'vertical' ? y : x;
 
         // Flip for end panels
         if (this.primary === 'end') {
@@ -138,7 +138,7 @@ export default class WaSplitPanel extends WebAwesomeElement {
               snapPoint = parseFloat(value);
             }
 
-            if (isRtl && !this.vertical) {
+            if (isRtl && this.orientation === 'horizontal') {
               snapPoint = this.size - snapPoint;
             }
 
@@ -168,11 +168,17 @@ export default class WaSplitPanel extends WebAwesomeElement {
 
       event.preventDefault();
 
-      if ((event.key === 'ArrowLeft' && !this.vertical) || (event.key === 'ArrowUp' && this.vertical)) {
+      if (
+        (event.key === 'ArrowLeft' && this.orientation === 'horizontal') ||
+        (event.key === 'ArrowUp' && this.orientation === 'vertical')
+      ) {
         newPosition -= incr;
       }
 
-      if ((event.key === 'ArrowRight' && !this.vertical) || (event.key === 'ArrowDown' && this.vertical)) {
+      if (
+        (event.key === 'ArrowRight' && this.orientation === 'horizontal') ||
+        (event.key === 'ArrowDown' && this.orientation === 'vertical')
+      ) {
         newPosition += incr;
       }
 
@@ -208,7 +214,7 @@ export default class WaSplitPanel extends WebAwesomeElement {
 
   private handleResize(entries: ResizeObserverEntry[]) {
     const { width, height } = entries[0].contentRect;
-    this.size = this.vertical ? height : width;
+    this.size = this.orientation === 'vertical' ? height : width;
 
     // There's some weird logic that gets `this.cachedPositionInPixels = NaN` or `this.position === Infinity` when
     // a split-panel goes from `display: none;` to showing.
@@ -244,8 +250,8 @@ export default class WaSplitPanel extends WebAwesomeElement {
   }
 
   render() {
-    const gridTemplate = this.vertical ? 'gridTemplateRows' : 'gridTemplateColumns';
-    const gridTemplateAlt = this.vertical ? 'gridTemplateColumns' : 'gridTemplateRows';
+    const gridTemplate = this.orientation === 'vertical' ? 'gridTemplateRows' : 'gridTemplateColumns';
+    const gridTemplateAlt = this.orientation === 'vertical' ? 'gridTemplateColumns' : 'gridTemplateRows';
     const isRtl = this.hasUpdated ? this.localize.dir() === 'rtl' : this.dir === 'rtl';
     const primary = `
       clamp(
@@ -267,13 +273,13 @@ export default class WaSplitPanel extends WebAwesomeElement {
     }
 
     if (this.primary === 'end') {
-      if (isRtl && !this.vertical) {
+      if (isRtl && this.orientation === 'horizontal') {
         this.style[gridTemplate] = `${primary} var(--divider-width) ${secondary}`;
       } else {
         this.style[gridTemplate] = `${secondary} var(--divider-width) ${primary}`;
       }
     } else {
-      if (isRtl && !this.vertical) {
+      if (isRtl && this.orientation === 'horizontal') {
         this.style[gridTemplate] = `${secondary} var(--divider-width) ${primary}`;
       } else {
         this.style[gridTemplate] = `${primary} var(--divider-width) ${secondary}`;