Allow for granular section restyling via convenience api

docs/_quarto.yml

@@ -46,6 +46,7 @@ website:
             - get-started/column-selection.qmd
             - get-started/row-selection.qmd
             - get-started/nanoplots.qmd
+            - get-started/targeted-styles.qmd
 
 format:
   html:

docs/get-started/targeted-styles.qmd

@@ -0,0 +1,131 @@
+---
+title: Targeted styles
+jupyter: python3
+---
+
+In [Styling the Table Body](./basic-styling), we discussed styling table data with `.tab_style()`.
+In this article we'll cover how the same method can be used to style many other parts of the table, like the header, specific spanner labels, the footer, and more.
+
+:::{.callout-warning}
+This feature is currently a work in progress, and not yet released. Great Tables must be installed from github in order to try it.
+:::
+
+
+## Kitchen sink
+
+Below is a big example that shows all possible `loc` specifiers being used.
+
+```{python}
+from great_tables import GT, exibble, loc, style
+
+# https://colorbrewer2.org/#type=qualitative&scheme=Paired&n=12
+brewer_colors = [
+    "#a6cee3",
+    "#1f78b4",
+    "#b2df8a",
+    "#33a02c",
+    "#fb9a99",
+    "#e31a1c",
+    "#fdbf6f",
+    "#ff7f00",
+    "#cab2d6",
+    "#6a3d9a",
+    "#ffff99",
+    "#b15928",
+]
+
+c = iter(brewer_colors)
+
+gt = (
+    GT(exibble.loc[[0, 1, 4], ["num", "char", "fctr", "row", "group"]])
+    .tab_header("title", "subtitle")
+    .tab_stub(rowname_col="row", groupname_col="group")
+    .tab_source_note("yo")
+    .tab_spanner("spanner", ["char", "fctr"])
+    .tab_stubhead("stubhead")
+)
+
+(
+    gt.tab_style(style.fill(next(c)), loc.body())
+    # Columns -----------
+    # TODO: appears in browser, but not vs code
+    .tab_style(style.fill(next(c)), loc.column_labels(columns="num"))
+    .tab_style(style.fill(next(c)), loc.column_header())
+    .tab_style(style.fill(next(c)), loc.spanner_labels(ids=["spanner"]))
+    # Header -----------
+    .tab_style(style.fill(next(c)), loc.header())
+    .tab_style(style.fill(next(c)), loc.subtitle())
+    .tab_style(style.fill(next(c)), loc.title())
+    # Footer -----------
+    .tab_style(style.borders(weight="3px"), loc.source_notes())
+    .tab_style(style.fill(next(c)), loc.footer())
+    # Stub --------------
+    .tab_style(style.fill(next(c)), loc.row_groups())
+    .tab_style(style.borders(weight="3px"), loc.stub(rows=1))
+    .tab_style(style.fill(next(c)), loc.stub())
+    .tab_style(style.fill(next(c)), loc.stubhead())
+)
+```
+
+## Body
+
+```{python}
+gt.tab_style(style.fill("yellow"), loc.body())
+```
+
+## Column labels
+
+```{python}
+(
+    gt
+    .tab_style(style.fill("yellow"), loc.column_header())
+    .tab_style(style.fill("blue"), loc.column_labels(columns="num"))
+    .tab_style(style.fill("red"), loc.spanner_labels(ids=["spanner"]))
+)
+
+```
+
+
+
+## Header
+
+```{python}
+(
+    gt.tab_style(style.fill("yellow"), loc.header())
+    .tab_style(style.fill("blue"), loc.title())
+    .tab_style(style.fill("red"), loc.subtitle())
+)
+```
+
+## Footer
+
+```{python}
+(
+    gt.tab_style(
+        style.fill("yellow"),
+        loc.source_notes(),
+    ).tab_style(
+        style.borders(weight="3px"),
+        loc.footer(),
+    )
+)
+```
+
+## Stub
+
+```{python}
+(
+    gt.tab_style(style.fill("yellow"), loc.stub())
+    .tab_style(style.fill("blue"), loc.row_groups())
+    .tab_style(
+        style.borders(style="dashed", weight="3px", color="red"),
+        loc.stub(rows=[1]),
+    )
+)
+```
+
+## Stubhead
+
+```{python}
+gt.tab_style(style.fill("yellow"), loc.stubhead())
+```

great_tables/_gt_data.py

@@ -5,7 +5,7 @@
 from collections.abc import Sequence
 from dataclasses import dataclass, field, replace
 from enum import Enum, auto
-from typing import Any, Callable, Tuple, TypeVar, overload, TYPE_CHECKING
+from typing import Any, Callable, Literal, Tuple, TypeVar, Union, overload, TYPE_CHECKING
 
 from typing_extensions import Self, TypeAlias
 
@@ -28,6 +28,7 @@
 
 if TYPE_CHECKING:
     from ._helpers import Md, Html, UnitStr, Text
+    from ._locations import Loc
 
 T = TypeVar("T")
 
@@ -610,7 +611,7 @@
         # TODO: validate
         return self.__class__(self.rows, self.group_rows.reorder(group_order))
 
-    def group_indices_map(self) -> list[tuple[int, str | None]]:
+    def group_indices_map(self) -> list[tuple[int, GroupRowInfo | None]]:
         return self.group_rows.indices_map(len(self.rows))
 
     def __iter__(self):
@@ -740,7 +741,7 @@
 
         return self.__class__(reordered)
 
-    def indices_map(self, n: int) -> list[tuple[int, str | None]]:
+    def indices_map(self, n: int) -> list[tuple[int, GroupRowInfo]]:
         """Return pairs of row index, group label for all rows in data.
 
         Note that when no groupings exist, n is used to return from range(n).
@@ -751,7 +752,7 @@
 
         if not len(self._d):
             return [(ii, None) for ii in range(n)]
-        return [(ind, info.defaulted_label()) for info in self for ind in info.indices]
+        return [(ind, info) for info in self for ind in info.indices]
 
 
 # Spanners ----
@@ -852,7 +853,7 @@
 
 @dataclass(frozen=True)
 class FootnoteInfo:
-    locname: str | None = None
+    locname: Loc | None = None
     grpname: str | None = None
     colname: str | None = None
     locnum: int | None = None
@@ -869,8 +870,7 @@
 
 @dataclass(frozen=True)
 class StyleInfo:
-    locname: str
-    locnum: int
+    locname: Loc
     grpname: str | None = None
     colname: str | None = None
     rownum: int | None = None