From da51bbfacc4e2b5bbc8edc81e233722c4c068a4d Mon Sep 17 00:00:00 2001
From: Steffen Rehberg <steffen.rehberg@googlemail.com>
Date: Tue, 9 May 2023 17:46:40 +0200
Subject: [PATCH] Add width and baseline properties documentation

- add Width property class
- fix links for baseline and width properties (Area, Bar, Bars, Dash)
---
 doc/_tutorial/properties.ipynb | 80 ++++++++++++++++++++++++++++++++++
 seaborn/_core/properties.py    |  8 ++++
 2 files changed, 88 insertions(+)

diff --git a/doc/_tutorial/properties.ipynb b/doc/_tutorial/properties.ipynb
index 70de0e9ea2..25f068e945 100644
--- a/doc/_tutorial/properties.ipynb
+++ b/doc/_tutorial/properties.ipynb
@@ -916,6 +916,86 @@
     ")"
    ]
   },
+  {
+   "attachments": {},
+   "cell_type": "raw",
+   "id": "b783edda",
+   "metadata": {},
+   "source": [
+    ".. _width_property:\n",
+    "\n",
+    "width\n",
+    "~~~~~\n",
+    "\n",
+    "The `width` property determines the relative width of bar or dash marks. A `width` of `1.0` means that there is no gap between adjacent marks, values greater than `1.0` lead to overlapping."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "fe4a0215",
+   "metadata": {
+    "tags": [
+     "hide-input"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "nan = float(\"nan\")\n",
+    "x_bar = [0, 1, 2] + [nan] * 9\n",
+    "y_bar = [1, 2, 3] + [nan] * 9\n",
+    "\n",
+    "(\n",
+    "    so.Plot()\n",
+    "    .add(\n",
+    "        so.Bar(color=\".8\", edgecolor=\".2\", edgewidth=2.5),\n",
+    "        x=x_bar,\n",
+    "        y=y_bar,\n",
+    "        fill=True,\n",
+    "        width=0.5,\n",
+    "    )\n",
+    "    .add(\n",
+    "        so.Bar(color=\".8\", edgecolor=\".2\", edgewidth=2.5),\n",
+    "        x=np.roll(x_bar, 3) + 5,\n",
+    "        y=np.roll(y_bar, 3),\n",
+    "        fill=True,\n",
+    "        width=0.8,\n",
+    "    )\n",
+    "    .add(\n",
+    "        so.Bar(color=\".8\", edgecolor=\".2\", edgewidth=2.5),\n",
+    "        x=np.roll(x_bar, 6) + 10,\n",
+    "        y=np.roll(y_bar, 6),\n",
+    "        fill=True,\n",
+    "        width=1.0,\n",
+    "    )\n",
+    "    .add(\n",
+    "        so.Bar(color=\".8\", edgecolor=\".2\", edgewidth=2.5),\n",
+    "        x=np.roll(x_bar, 9) + 15,\n",
+    "        y=np.roll(y_bar, 9),\n",
+    "        fill=True,\n",
+    "        width=1.5,\n",
+    "    ) \n",
+    "    .theme({\n",
+    "        **axes_style(\"ticks\"),\n",
+    "        \"axes.spines.left\": False,\n",
+    "        \"axes.spines.top\": False,\n",
+    "        \"axes.spines.right\": False,\n",
+    "        \"xtick.labelsize\": 14,\n",
+    "    })\n",
+    "    .layout(size=(9, 1.25), engine=None)\n",
+    "    .scale(\n",
+    "        fill=None,\n",
+    "        x=so.Continuous().tick(at=[1, 6, 11, 16])\n",
+    "        .label(\n",
+    "            like={\n",
+    "                1: 0.5, 6: 0.8, 11: 1.0, 16: 1.5\n",
+    "            }.get,\n",
+    "        ),\n",
+    "        y=so.Continuous().tick(count=0),\n",
+    "    )\n",
+    ")"
+   ]
+  },
   {
    "cell_type": "raw",
    "id": "c2ca33db-df52-4958-889a-320b4833a0d7",
diff --git a/seaborn/_core/properties.py b/seaborn/_core/properties.py
index f2d7c21eb1..c678bab097 100644
--- a/seaborn/_core/properties.py
+++ b/seaborn/_core/properties.py
@@ -331,6 +331,12 @@ def default_range(self) -> tuple[float, float]:
         return base * .5, base * 2
 
 
+class Width(IntervalProperty):
+    """Width for bar and dash marks as relative value."""
+    legend = False
+    normed = False
+
+
 # =================================================================================== #
 # Properties defined by arbitrary objects with inherently nominal scaling
 # =================================================================================== #
@@ -832,6 +838,8 @@ def _get_values(self, scale: Scale, levels: list) -> list:
     "ymin": Coordinate,
     "ymax": Coordinate,
     "group": Property,
+    "baseline": Coordinate,
+    "width": Width,
     # TODO pattern?
     # TODO gradient?
 }