RFC: reusable Python components with owned styles and table columns

[krflol]

We're exploring a more useful component model for Fullbleed: import a function together with its appearance, customize it without knowing its internal selectors, and define a table column once.

This is an experimental Python API in draft PR #85, with a prebuilt GitHub preview available for trying it. The experimental namespace is not in the PyPI 2.5.26 wheel. Names and behavior may change; the released component workflow remains the stable API.

Try the preview without building Rust | Inspect the PDFs and guide | Read the design decision brief

The invoice PDF and five-page report PDF import the same Field, WorkTable and Total functions from one small design kit. The report changes the brand values and supplies 60 records; the same table repeats its headers as the rows flow across pages. No installation is needed to inspect the output. All data is fictional.

The proposal keeps ordinary functions, arguments and children. A component owns its style values, so importing it does not require separately attaching its stylesheet. Root changes return a new node:

# Field is the ordinary function defined in the linked preview.
customer = Field("Prepared for", "Maple & Finch")
highlighted = customer.with_style(background="#f2f5f8", padding=pt(12))

Reusable factories supply shared style defaults. Themes supply brand values. Components can advertise named parts for intentional internal customization. Tables accept column declarations containing their label, cell callback, alignment and width together.

class_name remains a literal CSS label. Attach its rules through Document(styles=...), using CSS text, a selector mapping or an existing StyleSheet. Mappings can use the same immutable style values and theme tokens as components. The new selector_styles() editing exercise shows a shared class changing a reusable default and an explicit instance override taking precedence. The native CSS cascade still applies, including !important; class order is not priority.

The example-kit download includes a standalone first_pdf.py, the shared invoice/report kit and five focused editing tasks. Its installer selects a prebuilt wheel for supported Windows, macOS and Linux platforms; you need CPython 3.10+ and internet access, without Rust for that path. Follow the included README in an isolated environment. The snapshot retains version metadata 2.5.26, so the included URLs and hashes identify the experiment, and the command uses --force-reinstall. An optional requirements-source.txt still supports building the same commit with Rust/Cargo and native build tools.

This iteration also makes table defaults follow the same styling rules as other components: ordinary class selectors can customize built-in table appearance, while explicit column alignment/width and part overrides retain their documented precedence. Duplicate column labels remain distinguishable through column positions in diagnostics. Themes support immutable with_values(...) updates, and constructed nodes expose required_tokens so callers can inspect their actual theme dependencies.

We want to evaluate this through real edits before settling the API. Try reusing a field, changing the brand, adding a column, changing the paper size or repairing a clipping constraint, then share a small synthetic example:

1. Where did the component API still feel more indirect than HTML/CSS?
2. Was it clear when to use a function argument, a root style, a theme or a named part?
3. Which recurring print/layout task still required internal selectors or inspecting generated HTML?

The current prototype has limits: some oversized table content is unsupported, and token/part-name completion is unfinished. Native table and block split errors now identify their responsible cell or container when the engine provides that cause; other failures retain their authored scope. Document.prepare(renderer) checks one layout and lets PDF output and previews share it. Broader diagnostics, semantic continuation and performance qualification remain open. The preview retains artifact hashes and verification scope. Automated examples establish fixture behavior, not independent usability or conformance.

The intent is to settle the authoring contracts in Python, then adapt them to other languages' idioms. Feedback on an actual document or editing task is especially useful.

[krflol]

The component API is now available as an opt-in 2.6.0a1 alpha on PyPI:

python -m pip install --pre "fullbleed==2.6.0a1"

The Bootstrap guide and runnable kit include a first document, production report and component catalog. Cards own their sections, tables own their column definitions, and to_html(include_styles=True/False) exports documents or fragments with or without CSS. The 23 Bootstrap 5.0.0 component families use authored static states in both PDF and HTML; no Bootstrap JavaScript is included.

This alpha also adds required and optional style-part declarations plus explicit child-part forwarding. A component can expose a child's heading without requiring callers to know its internal markup. The part-styling guide covers those choices and the distinction between local styles, class_name, and application CSS.

The API remains experimental under fullbleed.ui.experimental. Ordinary pip resolution still selects stable 2.5.26, and the older preview downloads remain unchanged. The release has platform wheels, checksums and retained qualification records; component coverage does not imply complete CSS/browser or accessibility parity.

Useful feedback is a concrete editing task: add a formatted table column, rebrand a card, or expose a child part through a reusable component. Please share any step that still required writing raw HTML or inspecting generated selectors, using a small synthetic example.