CSS Builder

Generates a scoped CSS file for a Data Model, combining local CSS from each container and any referenced style sheets.

Remarks

Overview

The CSS Builder class assembles the final CSS used to style data extraction elements in Grooper's Data Viewer and Data Grid UI controls. It combines all relevant CSS sources—including the CSS property of each Data Model, Data Section, and Data Table, as well as any style sheets referenced by the Data Model—and scopes them to ensure styles apply only to the intended elements.

This process enables precise, maintainable, and conflict-free styling for complex document schemas, supporting both global and highly-targeted visual customization.

How CSS Is Combined and Scoped

1. Included Style Sheets:
   The Data Model may reference one or more external style sheets (resource files) though the 'Included Style Sheets' property. These are included first, providing a base set of styles for the entire model and its descendants. Each referenced file is read and its contents are added to the CSS output.

2. Local CSS Properties:
   Every Data Model, Data Section, and Data Table can define its own CSS property. These local styles are appended after any included style sheets, allowing for targeted overrides and customizations at any level of the data hierarchy.

3. Hierarchy Traversal:
   The builder recursively processes all child containers (sections, tables, and nested models), collecting their local CSS and combining it with ancestor styles. This ensures that every container's styles are included in the final output, regardless of depth or inheritance.

4. Ancestor Models:
   If the Data Model inherits from one or more parent models, the builder also includes the CSS from those ancestors. This supports consistent styling across inherited structures, while still allowing for overrides in child models.

5. CSS Qualification and Scoping:
   All CSS selectors are automatically "qualified"—that is, they are prefixed with a unique class path based on the Content Type and the code path of each container. This ensures that styles apply only to the intended elements, preventing conflicts with other models or unrelated UI components. For example, a selector like .field-label becomes .Invoice .Vendor .field-label, targeting only the Vendor section of an Invoice.

6. Preview Scoping:
   When generating CSS for a preview (such as a single field or section), the builder further restricts the output to only the relevant containers, ensuring that previewed styles do not bleed into unrelated elements.

Example: CSS Combination and Scoping

Suppose you have the following structure:

- Invoice (Data Model) - Vendor (Data Section) - Address (Data Field) - LineItems (Data Table) - Description (Data Field)

• The Invoice Data Model includes a style sheet with global table styles.
• The Vendor section defines a local CSS property for its background color.
• The LineItems table defines a local CSS property for row highlighting.

The CSS Builder will:

• Read and include the global table styles from the referenced style sheet.
• Append the Vendor section's CSS, scoped as .Invoice .Vendor { ... }.
• Append the LineItems table's CSS, scoped as .Invoice .LineItems { ... }.
• Ensure that all selectors are fully qualified, so styles do not affect other models or unrelated UI elements.

Best Practices

• Use included style sheets for global or shared styles across multiple models.
• Use the CSS property on Data Model, Data Section, or Data Table for targeted overrides or customizations.
• Avoid using overly generic selectors; rely on the builder's scoping to ensure styles are applied only where intended.
• When inheriting from parent models, review ancestor styles to ensure consistency and avoid unintended overrides.

Diagnostics

• The builder automatically strips comments and normalizes whitespace for clean output.
• If a style sheet cannot be read or a CSS property is invalid, errors may be logged for troubleshooting.