66 lines
8.3 KiB
Markdown
66 lines
8.3 KiB
Markdown
# Text blocks and container layout
|
||
|
||
Apply C16–C19 in [production rules](production-rules.md) to page authoring, reconstruction, reusable components and collaboration. These are required constraints. A page-library example is a design reference, not an exemption from current rules. Keep fonts, sizes, colors, grid and spacing tied to the selected external template.
|
||
|
||
## One paragraph, one logical text block
|
||
|
||
Prefer one native text frame for each paragraph, including a continuous multi-line heading or label. Use wrapping, internal line breaks and styled runs inside that frame. Separate subheadings, separate list items, table cells, axis labels and independently meaningful node labels may be separate objects; a visual line break does not create a new semantic item. Do not split a paragraph across independent boxes to fit a container or imitate a mockup.
|
||
|
||
If the selected route has a concrete technical reason to fragment the text, preserve all of these properties:
|
||
|
||
- One stable logical block ID and one complete text/runs source. Store line breaks as part of that source or compute them from it, never as independent authored line strings.
|
||
- One overall frame, text-role contract, alignment, line spacing and reading order. A shared layout implementation derives fragment positions and wrapping from the whole block; the page author cannot override individual fragment coordinates or styles.
|
||
- One update operation: changing text, width or typography regenerates the whole block. Preserve the logical ID and fragment mapping in project inputs; group exported fragments as one movable unit where the route supports it.
|
||
- Record the reason for fragmentation and actual object behavior. Source-level unified editing does not prove PowerPoint-native text flow; if edits in PowerPoint cannot reflow across fragments, disclose that limit. Grouping existing independently authored lines alone does not create a logical text block.
|
||
|
||
The project content model may represent this as `{id, content, runs?, bounds, text_role, layout_rule}`. This is an authoring pattern, not new compiler metadata or an automatically interpreted schema. The shared renderer consumes the block. Fragments, if necessary, are derived output and are never independently maintained content.
|
||
|
||
### SVG and the bundled native route
|
||
|
||
Use a single SVG `text` for the paragraph. For authored visual rows, use direct-child `tspan` elements: repeat the parent's `x`, start at `dy="0"`, then use the same positive line step. Inline styling may use nested spans without baseline jumps. Take all coordinates and text styles from the selected layout/renderer, not hand-measured mockup offsets.
|
||
|
||
The bundled compiler's default `preserve` text flow retains eligible stacked rows as one native frame, with internal breaks. Arbitrary per-line `y`, unequal `x`, nested baseline jumps or prior line-flattening may produce separate frames. Do not assume that one SVG `text` guarantees one PPTX frame. Inspect the actual native object structure. Do not select split text flow for ordinary paragraph authoring.
|
||
|
||
For an object check, find the text-bearing `p:sp` objects and their `p:txBody` in the current slide XML. A normal paragraph should occupy one text-bearing shape; multiple `a:r` runs, `a:br` breaks or `a:p` elements inside the same `p:txBody` are internal text structure. Distinct semantic labels remain independent. If the fallback is used, check the whole-block source and fragment mapping as well as native counts. Group/native XML checks do not establish actual application editing or appearance.
|
||
|
||
## Keep substantive explanations visible
|
||
|
||
Determine importance before assigning `caption`, `detail` or muted styles. Small muted text is for supplementary background, provenance and nonessential definitions. Key conditions, timing, dependencies, conclusions and interpretation-changing limitations belong in readable body, node, callout or heading roles. A qualifying statement is not supplementary merely because it sounds cautious.
|
||
|
||
| Statement | Treatment |
|
||
|---|---|
|
||
| Data source, collection date or a nonessential terminology expansion | Supplementary note is allowed; retain source metadata too |
|
||
| “Only proceed after approval”, “retry after timeout” | Main process/node text; the viewer needs it to follow the process |
|
||
| “Method B is faster” | Main comparison/conclusion hierarchy |
|
||
| “Only measured on this dataset; does not establish general performance” | Visible limitation alongside the claim, not small muted text or speaker-notes-only |
|
||
| A unit/definition that changes what a chart means | Keep it visibly associated with the chart at a suitable readable level |
|
||
|
||
Read the page without the small muted notes. Its workflow, conclusion and scope must still be accurate and complete. This check also applies to any field named `source`: the field name cannot make a substantive claim into provenance.
|
||
|
||
## Different roles inside a container
|
||
|
||
Assign named roles before rendering: for example `card_heading`, `card_body`, `value`, `unit` and `source_note`, mapped to the external template's declared typography and palette. If subheading and body have different functions, distinguish them perceptibly with size, weight and/or color. Using serif for one and sans serif for the other at otherwise identical styling is insufficient. Do not introduce arbitrary sizes or literal colors to create the difference.
|
||
|
||
The required distinction is between functions, not every string. Peers with the same function share a role. Verify the distinction in the actual theme and normal viewing scale; two almost identical colors are not a useful hierarchy. A substantive statement remains a body/callout role even when the component offers a small `detail` field.
|
||
|
||
## A shared layout implementation for each container type
|
||
|
||
Reuse a template/component renderer when it fits. For a new container, define one shared recipe/function and a content interface before placing its instances. The same type/variant must use the same padding, slot order, text roles, wrapping/height policy, icon size/alignment and spacing rules across pages and authors.
|
||
|
||
The caller may pass semantic content, an icon asset/role, a declared variant and the whole container's bounds/placement. Internal `title_x`, `body_y`, `icon_offset`, per-line coordinates and similar instance-level overrides are prohibited. The renderer may compute geometry from bounds, content and common style; deterministic calculation is how the rule is implemented. A shared content-driven height/wrapping policy can produce different heights for different text lengths.
|
||
|
||
If content does not fit, use the recipe's supported wrapping/height rules, rewrite, enlarge the whole slot or change the page/layout. Add a named shared variant only for a meaningful repeated need; do not disguise each instance's manual offsets as its own variant. Do not stretch generated text or icons with a group transform to make them fit. Regenerate from new bounds.
|
||
|
||
Diagram nodes may be arranged to express the actual topology. Each repeated node's internal label/icon layout still comes from the shared node recipe. Custom diagrams do not justify hand-positioning the contents of every repeated card or node.
|
||
|
||
Keep the recipe, parameters, content and assets in the portable project's declared inputs. For multiple authors, the coordinator freezes the shared implementation/style/variant set; page workers only instantiate it. Shared changes return to the coordinator and trigger checks on affected pages.
|
||
|
||
## Review before delivery
|
||
|
||
1. Compare the complete paragraph source with native text frames. Confirm one frame, or the justified whole-block fallback with derived fragments; inspect actual breaks, reading order and edit behavior at the requested evidence level.
|
||
2. Review every small muted note for meaning. Move essential statements into the main hierarchy and verify no qualification disappeared in the move.
|
||
3. Compare subheading/body and other distinct roles within each container at normal viewing scale. Font family alone cannot pass.
|
||
4. Compare all instances of each type/variant and inspect their creation calls/source. Confirm one shared implementation, no child-coordinate overrides and no post-generation nudges. Equal-looking screenshots alone cannot prove this.
|
||
|
||
The compiler cannot reliably infer these semantic properties from arbitrary SVG. Combine source review, native object checks and current rendered-page review; mark unavailable application checks explicitly.
|