feat: add stable classnames to child elements (#375)

README.md

@@ -218,3 +218,35 @@ If you get an error when importing allotment in a Next.js project consider [not
 ### How do I prevent a pane from being resized?
 
 Set `minSize` and `maxSize` props to the same value.
+
+### How do I style the component?
+
+Some common style changes can be made by setting CSS variables.
+
+These include:
+
+| Name                  | Default                     | Description                    |
+| :-------------------- | :-------------------------- | :----------------------------- |
+| `--focus-border`      | `#007fd4`                   | Color of the sash when hovered |
+| ` --separator-border` | `rgba(128, 128, 128, 0.35)` | Color of the separator         |
+
+For more involved styling you can target the component's child elements.
+
+| Class                      | Description                                                    |
+| :------------------------- | :------------------------------------------------------------- |
+| `.split-view`              | Styles applied to the top-level container                      |
+| `.split-view-horizontal`   | Styles applied to the top-level container if `vertical={false} |
+| `.split-view-vertical`     | Styles applied to the top-level container if `vertical={true}  |
+| `.sash-container`          | Styles applied to the sash container                           |
+| `.sash`                    | Styles applied to the sash                                     |
+| `.sash-active`             | Styles applied to the sash if being dragged                    |
+| `.sash-disabled`           | Styles applied to the sash if disabled                         |
+| `.sash-horizontal`         | Styles applied to the sash if vertical={false}`                |
+| `.sash-hover`              | Styles applied to the sash if being hovered over               |
+| `.sash-mac`                | Styles applied to the sash if running under macos              |
+| `.sash-maximum`            | Styles applied to the sash if the pane is maximised            |
+| `.sash-minimum`            | Styles applied to the sash if the pane is minimised            |
+| `.sash-vertical`           | Styles applied to the sash if vertical={true}`                 |
+| `.split-view-container`    | Styles applied to the split view container                     |
+| `.split-view-view`         | Styles applied to the split view view                          |
+| `.split-view-view-visible` | Styles applied to the split view view if `visible={true}`      |

src/allotment.tsx

@@ -72,7 +72,14 @@ export type PaneProps = {
 export const Pane = forwardRef<HTMLDivElement, PaneProps>(
   ({ className, children }: PaneProps, ref) => {
     return (
-      <div ref={ref} className={classNames(styles.splitViewView, className)}>
+      <div
+        ref={ref}
+        className={classNames(
+          "split-view-view",
+          styles.splitViewView,
+          className
+        )}
+      >
         {children}
       </div>
     );
@@ -451,13 +458,20 @@ const Allotment = forwardRef<AllotmentHandle, AllotmentProps>(
       <div
         ref={containerRef}
         className={classNames(
+          "split-view",
+          vertical ? "split-view-vertical" : "split-view-horizontal",
           styles.splitView,
           vertical ? styles.vertical : styles.horizontal,
           styles.separatorBorder,
           className
         )}
       >
-        <div className={styles.splitViewContainer}>
+        <div
+          className={classNames(
+            "split-view-container",
+            styles.splitViewContainer
+          )}
+        >
           {React.Children.toArray(children).map((child) => {
             if (!React.isValidElement(child)) {
               return null;

src/sash/sash.ts

@@ -87,7 +87,7 @@ export class Sash extends EventEmitter implements Disposable {
   private size: number;
   private hoverDelay = 300;
   private hoverDelayer = debounce(
-    (el) => el.classList.add(styles.hover),
+    (el) => el.classList.add("sash-hover", styles.hover),
     this.hoverDelay
   );
 
@@ -106,8 +106,11 @@ export class Sash extends EventEmitter implements Disposable {
     }
 
     this.el.classList.toggle(styles.disabled, state === SashState.Disabled);
+    this.el.classList.toggle("dash-disabled", state === SashState.Disabled);
     this.el.classList.toggle(styles.minimum, state === SashState.Minimum);
+    this.el.classList.toggle("sash-minimum", state === SashState.Minimum);
     this.el.classList.toggle(styles.maximum, state === SashState.Maximum);
+    this.el.classList.toggle("sash-maximum", state === SashState.Maximum);
 
     this._state = state;
 
@@ -147,12 +150,12 @@ export class Sash extends EventEmitter implements Disposable {
     super();
 
     this.el = document.createElement("div");
-    this.el.classList.add(styles.sash);
+    this.el.classList.add("sash", styles.sash);
     this.el.dataset.testid = "sash";
     container.append(this.el);
 
     if (isMacintosh) {
-      this.el.classList.add(styles.mac);
+      this.el.classList.add("sash-mac", styles.mac);
     }
 
     this.el.addEventListener("pointerdown", this.onPointerStart);
@@ -182,11 +185,11 @@ export class Sash extends EventEmitter implements Disposable {
     this.orientation = options.orientation ?? Orientation.Vertical;
 
     if (this.orientation === Orientation.Horizontal) {
-      this.el.classList.add(styles.horizontal);
-      this.el.classList.remove(styles.vertical);
+      this.el.classList.add("sash-horizontal", styles.horizontal);
+      this.el.classList.remove("sash-vertical", styles.vertical);
     } else {
-      this.el.classList.remove(styles.horizontal);
-      this.el.classList.add(styles.vertical);
+      this.el.classList.remove("sash-horizontal", styles.horizontal);
+      this.el.classList.add("sash-vertical", styles.vertical);
     }
 
     this.layout();
@@ -203,7 +206,7 @@ export class Sash extends EventEmitter implements Disposable {
       currentY: startY,
     };
 
-    this.el.classList.add(styles.active);
+    this.el.classList.add("sash-active", styles.active);
 
     this.emit("start", startEvent);
 
@@ -225,7 +228,7 @@ export class Sash extends EventEmitter implements Disposable {
     const onPointerUp = (event: PointerEvent): void => {
       event.preventDefault();
 
-      this.el.classList.remove(styles.active);
+      this.el.classList.remove("sash-active", styles.active);
       this.hoverDelayer.cancel();
       this.emit("end");
 
@@ -246,15 +249,15 @@ export class Sash extends EventEmitter implements Disposable {
   private onMouseEnter = (): void => {
     if (this.el.classList.contains(styles.active)) {
       this.hoverDelayer.cancel();
-      this.el.classList.add(styles.hover);
+      this.el.classList.add("sash-hover", styles.hover);
     } else {
       this.hoverDelayer(this.el);
     }
   };
 
   private onMouseLeave = (): void => {
     this.hoverDelayer.cancel();
-    this.el.classList.remove(styles.hover);
+    this.el.classList.remove("sash-hover", styles.hover);
   };
 
   /**

src/split-view/split-view.ts

@@ -170,13 +170,13 @@ abstract class ViewItem {
     this.container = container;
     this.view = view;
 
-    this.container.classList.add(styles.splitViewView);
+    this.container.classList.add("split-view-view", styles.splitViewView);
     this.container.dataset.testid = "split-view-view";
 
     if (typeof size === "number") {
       this._size = size;
       this._cachedVisibleSize = undefined;
-      container.classList.add(styles.visible);
+      container.classList.add("split-view-view-visible", styles.visible);
     } else {
       this._size = 0;
       this._cachedVisibleSize = size.cachedVisibleSize;
@@ -225,7 +225,8 @@ abstract class ViewItem {
       this.size = 0;
     }
 
-    this.container.classList.toggle("visible", visible);
+    this.container.classList.toggle(styles.visible, visible);
+    this.container.classList.toggle("split-view-view-visible", visible);
 
     if (this.view.setVisible) {
       this.view.setVisible(visible);
@@ -376,7 +377,7 @@ export class SplitView extends EventEmitter implements Disposable {
 
     this.sashContainer = document.createElement("div");
 
-    this.sashContainer.classList.add(styles.sashContainer);
+    this.sashContainer.classList.add("sash-container", styles.sashContainer);
     container.prepend(this.sashContainer); // Should always be first child
 
     // We have an existing set of view, add them now

website/docs/styling.md

@@ -0,0 +1,36 @@
+---
+id: styling
+title: Styling
+---
+
+# Styling
+
+Some common style changes can be made by setting CSS variables.
+
+These include:
+
+| Name                  | Default                     | Description                    |
+| :-------------------- | :-------------------------- | :----------------------------- |
+| `--focus-border`      | `#007fd4`                   | Color of the sash when hovered |
+| ` --separator-border` | `rgba(128, 128, 128, 0.35)` | Color of the separator         |
+
+For more involved styling you can target the component's child elements.
+
+| Class                      | Description                                                    |
+| :------------------------- | :------------------------------------------------------------- |
+| `.split-view`              | Styles applied to the top-level container                      |
+| `.split-view-horizontal`   | Styles applied to the top-level container if `vertical={false} |
+| `.split-view-vertical`     | Styles applied to the top-level container if `vertical={true}  |
+| `.sash-container`          | Styles applied to the sash container                           |
+| `.sash`                    | Styles applied to the sash                                     |
+| `.sash-active`             | Styles applied to the sash if being dragged                    |
+| `.sash-disabled`           | Styles applied to the sash if disabled                         |
+| `.sash-horizontal`         | Styles applied to the sash if vertical={false}`                |
+| `.sash-hover`              | Styles applied to the sash if being hovered over               |
+| `.sash-mac`                | Styles applied to the sash if running under macos              |
+| `.sash-maximum`            | Styles applied to the sash if the pane is maximised            |
+| `.sash-minimum`            | Styles applied to the sash if the pane is minimised            |
+| `.sash-vertical`           | Styles applied to the sash if vertical={true}`                 |
+| `.split-view-container`    | Styles applied to the split view container                     |
+| `.split-view-view`         | Styles applied to the split view view                          |
+| `.split-view-view-visible` | Styles applied to the split view view if `visible={true}`      |

website/sidebars.json

@@ -2,6 +2,7 @@
   "docs": [
     {
       "Getting Started": ["getting-started"],
+      "How To Guides": ["styling"],
       "API reference": ["overview", "allotment", "pane"],
       "Examples": ["basic", "nested", "closable", "reset", "visible"]
     },