feat: add slide and table styling helpers

examples/presentation_tree.json

@@ -5080,4 +5080,4 @@
       }
     ]
   }
-}
+}

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tppt"
-version = "0.2.2"
+version = "0.3.0"
 description = "Typed Python PowerPoint Tool"
 readme = "README.md"
 requires-python = ">=3.11.0"

src/tppt/pptx/__init__.py

@@ -11,4 +11,5 @@
 from .shape.text import Text as Text
 from .slide import Slide as Slide
 from .table import Table as Table
+from .table import TableBorderStyle as TableBorderStyle
 from .table import TableCellStyle as TableCellStyle

src/tppt/pptx/chart/chart.py

@@ -1,19 +1,25 @@
 from typing import TYPE_CHECKING, Literal, Self, TypedDict, assert_never
 
 from pptx.chart.chart import Chart as PptxChart
-from pptx.chart.chart import Legend as PptxLegend
+from pptx.chart.chart import ChartTitle as PptxChartTitle
+from pptx.chart.data import BubbleChartData as PptxBubbleChartData
+from pptx.chart.data import CategoryChartData as PptxCategoryChartData
 from pptx.chart.data import ChartData as PptxChartData
+from pptx.chart.data import XyChartData as PptxXyChartData
+from pptx.chart.legend import Legend as PptxLegend
 from pptx.enum.chart import XL_CHART_TYPE, XL_LEGEND_POSITION
 
 from tppt.pptx.converter import PptxConvertible
 from tppt.types._length import Length, LiteralLength
 
 if TYPE_CHECKING:
-    from pptx.chart.chart import ChartTitle as PptxChartTitle
-
     from tppt.pptx.text.font import Font
     from tppt.pptx.text.text_frame import TextFrame
 
+PptxChartDataLike = (
+    PptxChartData | PptxCategoryChartData | PptxXyChartData | PptxBubbleChartData
+)
+
 LiteralChartType = Literal[
     "3D Area",
     "3D Stacked Area",
@@ -253,7 +259,7 @@ class ChartProps(TypedDict):
     y: Length | LiteralLength
     cx: Length | LiteralLength
     cy: Length | LiteralLength
-    chart_data: PptxChartData
+    chart_data: PptxChartDataLike
 
 
 class ChartData(ChartProps):
@@ -262,7 +268,7 @@ class ChartData(ChartProps):
     type: Literal["chart"]
 
 
-class ChartTitle(PptxConvertible["PptxChartTitle"]):
+class ChartTitle(PptxConvertible[PptxChartTitle]):
     """Chart title wrapper class."""
 
     @property
@@ -399,8 +405,10 @@ def set_has_title(self, value: bool) -> Self:
     @property
     def legend(self) -> Legend:
         """Legend of the chart."""
-        return Legend(self._pptx.legend)
+        legend = self._pptx.legend
+        assert legend is not None
+        return Legend(legend)
 
-    def replace_data(self, chart_data: PptxChartData) -> None:
+    def replace_data(self, chart_data: PptxChartDataLike) -> None:
         """Replace chart data with new data."""
         self._pptx.replace_data(chart_data)

src/tppt/pptx/dml/color.py

@@ -104,15 +104,14 @@ def set_brightness(self, value: float) -> Self:
 
     @property
     def rgb(self) -> Color:
-        solid_fill = cast(
-            _Element, self._pptx._xFill.solidFill.get_or_change_to_srgbClr()
+        srgb_clr = cast(_Element, cast(_SRgbColor, self._pptx._color)._srgbClr)
+        alpha_elem = srgb_clr.find("a:alpha", namespace)
+        alpha = (
+            round(int(alpha_elem.attrib["val"]) * 255 / 100000)
+            if alpha_elem is not None
+            else None
         )
 
-        if alpha := solid_fill.find("a:alpha", namespace):
-            alpha = alpha.attrib["val"]
-        else:
-            alpha = None
-
         return to_tppt_rgb_color(cast(PptxRGBColor, self._pptx.rgb), alpha=alpha)
 
     @rgb.setter

src/tppt/pptx/dml/line.py

@@ -42,7 +42,7 @@ def width(self) -> EnglishMetricUnits | None:
 
     @width.setter
     def width(self, value: EnglishMetricUnits | _PptxEmu) -> None:
-        self._pptx.width = to_english_metric_units(value)
+        self._pptx.width = to_english_metric_units(value).value
 
     def set_width(self, value: EnglishMetricUnits | _PptxEmu) -> "LineFormat":
         self.width = value

src/tppt/pptx/notes_slide.py

@@ -6,7 +6,7 @@
 
 if TYPE_CHECKING:
     from tppt.pptx.shape import BaseShape
-    from tppt.pptx.shape.placeholder import SlidePlaceholder
+    from tppt.pptx.shape.placeholder import NotesSlidePlaceholder, SlidePlaceholder
     from tppt.pptx.text.text_frame import TextFrame
 
 
@@ -18,14 +18,18 @@ def notes_text_frame(self) -> "TextFrame":
         """Text frame of the notes body placeholder."""
         from tppt.pptx.text.text_frame import TextFrame
 
-        return TextFrame(self._pptx.notes_text_frame)
+        text_frame = self._pptx.notes_text_frame
+        assert text_frame is not None
+        return TextFrame(text_frame)
 
     @property
-    def notes_placeholder(self) -> "SlidePlaceholder":
+    def notes_placeholder(self) -> "NotesSlidePlaceholder":
         """Notes body placeholder shape."""
-        from tppt.pptx.shape.placeholder import SlidePlaceholder
+        from tppt.pptx.shape.placeholder import NotesSlidePlaceholder
 
-        return SlidePlaceholder(self._pptx.notes_placeholder)
+        placeholder = self._pptx.notes_placeholder
+        assert placeholder is not None
+        return NotesSlidePlaceholder(placeholder)
 
     @property
     def placeholders(self) -> "list[SlidePlaceholder]":

src/tppt/pptx/shape/picture.py

@@ -1,4 +1,13 @@
-from typing import IO, TYPE_CHECKING, Literal, NotRequired, Self, TypedDict, assert_never
+from typing import (
+    IO,
+    TYPE_CHECKING,
+    Literal,
+    NotRequired,
+    Self,
+    TypedDict,
+    assert_never,
+    cast,
+)
 
 from pptx.opc.constants import CONTENT_TYPE
 from pptx.shapes.picture import Movie as PptxMovie
@@ -10,7 +19,7 @@
 
 if TYPE_CHECKING:
     from pptx.enum.shapes import MSO_AUTO_SHAPE_TYPE
-    from pptx.image import Image
+    from pptx.parts.image import Image
 
     from tppt.pptx.dml.line import LineFormat
 
@@ -185,11 +194,11 @@ def __init__(
         self._pptx = pptx_obj
 
     @property
-    def poster_frame(self) -> "Image":
+    def poster_frame(self) -> "Image | None":
         """Poster frame image for the movie."""
         return self._pptx.poster_frame
 
     @property
     def media_type(self) -> str | None:
         """Media type (MIME type) of the movie."""
-        return self._pptx.media_type
+        return cast(str | None, self._pptx.media_type)

src/tppt/pptx/shape/placeholder.py

@@ -1,5 +1,6 @@
 from pptx.shapes.placeholder import LayoutPlaceholder as _PptxLayoutPlaceholder
 from pptx.shapes.placeholder import MasterPlaceholder as _PptxMasterPlaceholder
+from pptx.shapes.placeholder import NotesSlidePlaceholder as _PptxNotesSlidePlaceholder
 from pptx.shapes.placeholder import SlidePlaceholder as _PptxSlidePlaceholder
 
 from . import Shape
@@ -11,4 +12,7 @@ class LayoutPlaceholder(Shape[_PptxLayoutPlaceholder]): ...
 class MasterPlaceholder(Shape[_PptxMasterPlaceholder]): ...
 
 
+class NotesSlidePlaceholder(Shape[_PptxNotesSlidePlaceholder]): ...
+
+
 class SlidePlaceholder(Shape[_PptxSlidePlaceholder]): ...

src/tppt/pptx/shape/text.py

@@ -17,6 +17,7 @@ class TextProps(RangeProps):
     bold: NotRequired[bool]
     italic: NotRequired[bool]
     color: NotRequired[Color | LiteralColor]
+    font_name: NotRequired[str]
     margin_bottom: NotRequired[Length | LiteralLength]
     margin_left: NotRequired[Length | LiteralLength]
     vertical_anchor: NotRequired[MSO_ANCHOR]
@@ -52,6 +53,8 @@ def __init__(self, pptx_obj: PptxShape, data: TextData | None = None, /) -> None
                 font.italic = italic
             if (color := data.get("color")) is not None:
                 font.color.rgb = to_color(color)
+            if (font_name := data.get("font_name")) is not None:
+                font.name = font_name
             if (margin_bottom := data.get("margin_bottom")) is not None:
                 p.space_after = to_length(margin_bottom)
             if (margin_left := data.get("margin_left")) is not None:

src/tppt/pptx/slide.py

@@ -13,6 +13,7 @@
     overload,
 )
 
+from pptx.chart.data import ChartData as PptxChartData
 from pptx.slide import Slide as PptxSlide
 from pptx.slide import _BaseSlide as _PptxBaseSlide
 
@@ -24,9 +25,9 @@
     PptxMovie,
     to_pptx_movie_mime_type,
 )
-from tppt.types import FilePath
+from tppt.types import Color, FilePath, Length, LiteralColor, LiteralLength
 
-from .converter import PptxConvertible, to_pptx_length
+from .converter import PptxConvertible, to_pptx_length, to_pptx_rgb_color
 from .shape import BaseShape, RangeProps, Shape
 from .shape.picture import Picture, PictureData, PictureProps
 from .shape.placeholder import SlidePlaceholder
@@ -111,6 +112,15 @@ def slide_layout(self) -> SlideLayout:
 class SlideBuilder:
     """Slide builder."""
 
+    class AddShapeProps(RangeProps, total=False):
+        fill_color: Color | LiteralColor
+        fill_alpha: float
+        line_color: Color | LiteralColor
+        line_width: Length | LiteralLength
+        text: str
+        font_size: Length | LiteralLength
+        font_color: Color | LiteralColor
+
     def __init__(
         self,
         slide_layout: SlideLayout,
@@ -349,7 +359,7 @@ def _register(slide: Slide) -> Chart:
                     y=to_pptx_length(data["y"]),
                     cx=to_pptx_length(data["cx"]),
                     cy=to_pptx_length(data["cy"]),
-                    chart_data=data["chart_data"],
+                    chart_data=cast(PptxChartData, data["chart_data"]),
                 )
             )
             if isinstance(data, Callable):
@@ -366,7 +376,7 @@ def add_shape(
         self,
         shape_type: "MSO_AUTO_SHAPE_TYPE",
         /,
-        **kwargs: Unpack[RangeProps],
+        **kwargs: Unpack[AddShapeProps],
     ) -> Self: ...
 
     @overload
@@ -375,14 +385,21 @@ def add_shape(
         shape_type: "MSO_AUTO_SHAPE_TYPE",
         shape: Callable[[Shape], Shape],
         /,
-        **kwargs: Unpack[RangeProps],
+        **kwargs: Unpack[AddShapeProps],
     ) -> Self: ...
 
     def add_shape(
         self,
         shape_type: "MSO_AUTO_SHAPE_TYPE",
         shape: Callable[[Shape], Shape] | None = None,
         /,
+        fill_color: "Color | LiteralColor | None" = None,
+        fill_alpha: float | None = None,
+        line_color: "Color | LiteralColor | None" = None,
+        line_width: "Length | LiteralLength | None" = None,
+        text: str | None = None,
+        font_size: "Length | LiteralLength | None" = None,
+        font_color: "Color | LiteralColor | None" = None,
         **kwargs: Unpack[RangeProps],
     ) -> Self:
         """Add a shape to the slide."""
@@ -397,6 +414,56 @@ def _register(slide: Slide) -> Shape:
                     to_pptx_length(kwargs["height"]),
                 )
             )
+
+            if fill_color is not None:
+                rgb, alpha = to_pptx_rgb_color(fill_color)
+                shape_obj.fill.solid().fore_color.set_rgb(fill_color)
+
+            if fill_alpha is not None:
+                from lxml.etree import _Element
+
+                from pptx.oxml.ns import _nsmap as namespace
+                from pptx.oxml.xmlchemy import OxmlElement
+
+                pptx_shape = shape_obj.to_pptx()
+                solid_fill = cast(
+                    _Element,
+                    pptx_shape.fill._xPr.solidFill,  # type: ignore[union-attr]
+                )
+                # Remove existing alpha element if any
+                existing_alpha = solid_fill.find("a:alpha", namespace)
+                if existing_alpha is not None:
+                    solid_fill.remove(existing_alpha)
+                alpha_elem = OxmlElement("a:alpha")
+                alpha_elem.attrib["val"] = str(int(fill_alpha * 100000))
+                # Find srgbClr or other color child to append alpha to
+                for child in solid_fill:
+                    child.append(alpha_elem)
+                    break
+
+            if line_color is not None:
+                shape_obj.line.fill.solid().fore_color.set_rgb(line_color)
+
+            if line_width is not None:
+                from tppt.types._length import EnglishMetricUnits
+
+                pptx_len = to_pptx_length(line_width)
+                shape_obj.line.set_width(EnglishMetricUnits(int(pptx_len)))
+
+            if text is not None:
+                shape_obj.text = text
+
+            if font_size is not None or font_color is not None:
+                tf = shape_obj.to_pptx().text_frame
+                if tf.paragraphs:
+                    paragraph = tf.paragraphs[0]
+                    run = paragraph.runs[0] if paragraph.runs else paragraph.add_run()
+                    if font_size is not None:
+                        run.font.size = to_pptx_length(font_size)
+                    if font_color is not None:
+                        rgb_val, _ = to_pptx_rgb_color(font_color)
+                        run.font.color.rgb = rgb_val
+
             if shape is not None:
                 return shape(shape_obj)
             else:
@@ -405,6 +472,15 @@ def _register(slide: Slide) -> Shape:
         self._shape_registry.append(_register)
         return self
 
+    def customize(self, callback: Callable[[PptxSlide], None]) -> Self:
+        """Register a callback for direct access to the python-pptx Slide object."""
+
+        def _register(slide: Slide) -> None:
+            callback(slide.to_pptx())
+
+        self._shape_registry.append(_register)
+        return self
+
     def tap(self, callback: Callable[[Slide], None]) -> Self:
         """Register a callback for direct slide access."""
         self._shape_registry.append(callback)

src/tppt/pptx/table/__init__.py

@@ -3,4 +3,5 @@
 from .table import Row as Row
 from .table import RowCollection as RowCollection
 from .table import Table as Table
+from .table import TableBorderStyle as TableBorderStyle
 from .table import TableCellStyle as TableCellStyle