OVAPortableText 0.1.4__tar.gz → 0.3.0__tar.gz

{ovaportabletext-0.1.4 → ovaportabletext-0.3.0}/CHANGELOG.md

@@ -4,6 +4,58 @@
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-04-08
+
+### Added
+
+* aligned the package with `report.v1.2`
+* added `DoughnutChartDataset` and `doughnut_chart_dataset(...)`
+* added section-level models and helpers for `sectionRole`, `navigation`, `pagination`, and `presentation`
+* added support for `_type="chart"` inside `GridTableCell.blocks`
+* added validation coverage for doughnut constraints, grid-cell chart refs, and `presentation.titleBlockStyle`
+* added tests covering v1.2 doughnut datasets, section fields, and grid-cell charts
+
+### Changed
+
+* default `schemaVersion` is now `report.v1.2`
+* `ChartBlock.id`, `TableBlock.id`, `MathBlock.id`, and `CalloutBlock.id` are now optional to match the protocol's instance-layer rules
+* `Section`, `Document.new_section(...)`, and `section(...)` now accept v1.2 section fields
+* chart / table / math helper functions now accept optional instance ids
+* public exports and packaging metadata now reflect `v0.3.0` / `report.v1.2`
+
+### Fixed
+
+* fixed the protocol mismatch where grid-cell chart blocks were still rejected by the Python models and validator
+* fixed the resolver mismatch where optional chart / table / math / callout instance ids could break target indexing
+* fixed the validation gap where grid-cell `chartRef` values were not resolved
+
+## [0.2.0] - 2026-04-01
+
+### Added
+
+* aligned the package with `report.v1.1`
+* added `theme.blockStyleDefaults` models and helpers
+* added block-level `layout` support for `TextBlock` and paragraph helpers
+* added table-level `layout.columnSpecs[]` with `auto | weight` width modes
+* added helper functions: `block_layout`, `length_em`, `length_pt`, `table_column_spec_auto`, `table_column_spec_weight`, `table_layout`
+* added support for `_type="image"` inside `GridTableCell.blocks`
+* added validation coverage for grid-cell image refs and v1.1 table/theme features
+* added `examples/v11_layout_and_cell_image_demo.py`
+
+### Changed
+
+* default `schemaVersion` is now `report.v1.1`
+* `ImageBlock.id` and `ImageBlock.anchor` are now optional
+* `image_block(...)` and `Section.append_image(...)` now accept optional instance ids
+* `record` and `grid` table datasets both accept table-level `layout`
+* API docs and quickstart examples now reflect the v1.1 contract
+
+### Fixed
+
+* fixed the protocol mismatch where image instances incorrectly required `id`
+* fixed the protocol mismatch where grid-cell `blocks` only accepted text blocks
+* fixed the validation gap where grid-cell `imageRef` values were not resolved
+
 ## [0.1.4] - 2026-03-25
 
 ### Added

{ovaportabletext-0.1.4 → ovaportabletext-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: OVAPortableText
-Version: 0.1.4
+Version: 0.3.0
 Summary: Python builder for generating OVAPortableText / Report Profile v1 JSON documents
 Author: FENG QU
 License-Expression: MIT

{ovaportabletext-0.1.4 → ovaportabletext-0.3.0}/docs/API_REFERENCE.md

@@ -1,10 +1,7 @@
 # API Reference / API 参考
 
-This page is a practical API map for the public surface of OVAPortableText.  
-本文档是 OVAPortableText 公开接口的实用型 API 地图。
-
-It is intentionally not a generated full symbol dump.  
-它刻意不是自动生成的“全量符号索引”。
+This page is a practical map of the public API in OVAPortableText `v0.3.0`, aligned to `report.v1.2`.
+本文档是 OVAPortableText `v0.3.0` 的实用 API 地图，对齐 `report.v1.2`。
 
 ---
 
@@ -13,19 +10,21 @@ It is intentionally not a generated full symbol dump.
 ### Document creation / 文档创建
 
 - `create_document(...)`
-- `document(...)`  
-  Alias of `create_document`. / `create_document` 的别名。
+- `document(...)` — alias of `create_document`
 - `Document.from_dict(...)`
 - `Document.from_json(...)`
 - `Document.load_json(...)`
 
-Typical arguments / 常用参数：
+Default schema version:
+
+- `Document.schemaVersion == "report.v1.2"`
+
+Common arguments / 常用参数：
 
 - `title`
-- `language` → current package validation: `"zh"` or `"en"`  
-  当前包校验：`"zh"` 或 `"en"`
-- `documentType` → current package validation: `"valuationReport"`  
-  当前包校验：`"valuationReport"`
+- `language`
+- `documentType`
+- `theme`
 - `strict_ids=False`
 
 ---
@@ -47,9 +46,57 @@ Body block objects / 正文块对象：
 - `MathBlock`
 - `CalloutBlock`
 
+Important v1.2 note / v1.2 重点：
+
+- `ImageBlock(imageRef="...")` remains valid
+- `ChartBlock(chartRef="...")`, `TableBlock(tableRef="...")`, and `MathBlock(latex="...")` may now omit instance `id`
+- `Section` now supports `sectionRole`, `navigation`, `pagination`, and `presentation`
+- `GridTableCell.blocks[]` now supports `_type="chart"` in addition to `_type="block"` and `_type="image"`
+
 ---
 
-## 3. Text helpers / 文本层 helper
+## 3. Theme and block layout / theme 与块级 layout
+
+### Theme models / theme 模型
+
+- `ThemeConfig`
+- `BlockStyleDefault`
+- `BlockLayout`
+- `LengthValue`
+
+### Theme helpers / theme helper
+
+- `block_layout(...)`
+- `length_em(value)`
+- `length_pt(value)`
+
+### v1.1 formal fields / v1.1 正式字段
+
+- `theme.blockStyleDefaults`
+- `TextBlock.layout`
+
+Supported `BlockLayout` fields:
+
+- `textAlign`
+- `firstLineIndent`
+- `spaceBefore`
+- `spaceAfter`
+
+Supported `textAlign` values:
+
+- `left`
+- `center`
+- `right`
+- `justify`
+
+Supported length units:
+
+- `em`
+- `pt`
+
+---
+
+## 4. Text helpers / 文本层 helper
 
 ### Inline text constructors / 行内文本构造
 
@@ -63,16 +110,11 @@ Body block objects / 正文块对象：
 ### Mark-definition helpers / markDef helper
 
 - `link_def(key=..., href=...)`
-- `xref_def(key=..., target_id=..., target_type=...)`
-- `citation_ref_def(key=..., target_id=...)`
-- `footnote_ref_def(key=..., target_id=...)`
-- `glossary_term_def(key=..., target_id=...)`
-- `inline_math_def(key=..., latex=...)`
 - `annotation_def(key=..., type=..., data=...)`
 
 ### Block constructors / 文本块构造
 
-- `paragraph(*parts, style="normal", mark_defs=None, list_item=None, level=None)`
+- `paragraph(*parts, style="normal", mark_defs=None, list_item=None, level=None, layout=None)`
 - `bullet_item(*parts, level=1, mark_defs=None)`
 - `number_item(*parts, level=1, mark_defs=None)`
 - `blocks_from_items(...)`
@@ -80,7 +122,7 @@ Body block objects / 正文块对象：
 ### Inline object helpers / 行内对象 helper
 
 - `hard_break()`
-- `xref(target_id=..., target_type=None)`
+- `xref(target_type=..., target_id=...)`
 - `citation_ref(target_id)`
 - `footnote_ref(target_id)`
 - `glossary_term(target_id)`
@@ -88,7 +130,7 @@ Body block objects / 正文块对象：
 
 ---
 
-## 4. Section helpers / Section 级 helper
+## 5. Section helpers / Section 级 helper
 
 ### Create sections / 创建章节
 
@@ -100,13 +142,16 @@ Body block objects / 正文块对象：
 
 ### Append text / 追加文本
 
-- `Section.append_paragraph(...)`
+- `Section.append_paragraph(..., layout=None)`
 - `Section.append_paragraphs(...)`
 - `Section.append_lead(...)`
 - `Section.append_blockquote(...)`
 - `Section.append_subheading(...)`
 - `Section.append_smallprint(...)`
-- `Section.append_quote_source(...)`
+- `Section.append_caption(...)`
+- `Section.append_figure_caption(...)`
+- `Section.append_table_caption(...)`
+- `Section.append_equation_caption(...)`
 
 ### Append lists / 追加列表
 
@@ -120,24 +165,25 @@ Body block objects / 正文块对象：
 - `Section.append_to_last_content(block)`
 - `Section.append_blocks_to_last_content(*blocks)`
 - `Section.append_text_block_to_last_content(block)`
-- `Section.append_paragraph_to_last_content(...)`
-
-Use these when multiple blocks should remain in the same protocol `content` item.  
-当多段内容应继续停留在同一个协议 `content` item 中时，使用这组 helper。
+- `Section.append_paragraph_to_last_content(..., layout=None)`
 
 ### Append block objects / 追加块对象
 
 - `Section.append_block(...)`
 - `Section.append_blocks(...)`
 - `Section.append_callout(...)`
-- `Section.append_image_with_caption(...)`
+- `Section.append_image(image_ref=..., id=None, anchor=None)`
+- `Section.append_chart(...)`
+- `Section.append_table(...)`
+- `Section.append_math(...)`
+- `Section.append_image_with_caption(image_ref=..., id=None, caption=...)`
 - `Section.append_chart_with_caption(...)`
 - `Section.append_table_with_caption(...)`
 - `Section.append_math_with_caption(...)`
 
 ---
 
-## 5. Registry helpers / registry helper
+## 6. Registry helpers / registry helper
 
 ### Assets / 资源
 
@@ -153,25 +199,27 @@ Use these when multiple blocks should remain in the same protocol `content` item
 ### Datasets / 数据集
 
 - `table_column(...)`
-- `table_dataset(...)` → returns `RecordTableDataset`  
-  返回 `RecordTableDataset`
+- `table_dataset(...)` → returns `RecordTableDataset`
+- `record_table_dataset(...)`
 - `grid_table_cell(...)`
 - `grid_table_row(...)`
-- `grid_table_dataset(...)` → returns `GridTableDataset`  
-  返回 `GridTableDataset`
+- `grid_table_dataset(...)` → returns `GridTableDataset`
+- `table_column_spec_auto()`
+- `table_column_spec_weight(value)`
+- `table_layout(*column_specs)`
 - `pie_slice(...)`
 - `pie_chart_dataset(...)`
 - `pie_chart_from_parallel_arrays(...)`
 - `metric_value(...)`
 - `metric_dataset(...)`
 
-### Registry content / 引用型内容
+### Registry-backed block instances / 正文引用实例
 
-- `image_block(...)`
-- `chart_block(...)`
-- `table_block(...)`
-- `math_block(...)`
-- `callout(...)`
+- `image_block(image_ref=..., id=None, anchor=None)`
+- `chart_block(id=..., chart_ref=..., anchor=None)`
+- `table_block(id=..., table_ref=..., anchor=None)`
+- `math_block(id=..., latex=..., anchor=None)`
+- `callout(id=..., blocks=None, anchor=None)`
 
 ### Bibliography / footnotes / glossary
 
@@ -181,7 +229,7 @@ Use these when multiple blocks should remain in the same protocol `content` item
 
 ---
 
-## 6. Main registry models / 主要 registry 模型
+## 7. Main registry models / 主要 registry 模型
 
 ### Assets / 资源模型
 
@@ -201,9 +249,11 @@ Use these when multiple blocks should remain in the same protocol `content` item
 - `GridTableDataset`
 - `GridTableRow`
 - `GridTableCell`
-- `TableDataset`  
-  Discriminated union of `record | grid`. / `record | grid` 判别联合类型。
+- `TableDataset`
 - `TableColumn`
+- `TableLayout`
+- `TableColumnSpec`
+- `TableColumnWidth`
 - `PieChartDataset`
 - `PieSlice`
 - `MetricDataset`
@@ -218,7 +268,44 @@ Use these when multiple blocks should remain in the same protocol `content` item
 
 ---
 
-## 7. Validation / 校验
+## 8. v1.1 table notes / v1.1 表格说明
+
+### Table-level layout / 表级 layout
+
+Both record and grid tables now support:
+
+- `layout.columnSpecs[]`
+
+Width modes:
+
+- `auto`
+- `weight`
+
+Rules:
+
+- `mode="auto"` → no `value`
+- `mode="weight"` → `value > 0`
+- `weight` is relative weight, not percent
+
+### Grid cell blocks / grid 单元格 blocks
+
+`GridTableCell.blocks` is now a restricted block array.
+
+Currently supported block types:
+
+- `_type="block"`
+- `_type="image"`
+
+Not supported in cell blocks:
+
+- `chart`
+- `table`
+- `math_block`
+- `callout`
+
+---
+
+## 9. Validation / 校验
 
 - `Document.validate()`
 - `Document.assert_valid()`
@@ -236,81 +323,32 @@ print(validation.to_text())
 report.assert_valid()
 ```
 
+Validator additions relevant to v1.1:
+
+- checks `theme.blockStyleDefaults` keys
+- checks `TextBlock.layout`
+- checks table `layout.columnSpecs`
+- checks grid cell image refs
+- warns when image-like assets omit `alt`
+
 ---
 
-## 8. Resolver / 解析器
+## 10. Resolver / 解析器
 
 - `Document.build_resolver()`
 - `DocumentResolver.get(...)`
-- `DocumentResolver.get_by_id(...)`
 - `DocumentResolver.get_by_anchor(...)`
 - `DocumentResolver.resolve_xref(...)`
 - `DocumentResolver.debug_summary()`
 
-Use the resolver when you need to inspect what is globally addressable in the document.  
+Use the resolver when you need to inspect what is globally addressable in the document.
 当你需要检查文档中哪些对象在全局可解析时，使用 resolver。
 
 ---
 
-## 9. Numbering / 编号
+## 11. Numbering / 编号
 
 - `Document.build_numbering()`
 - `NumberingConfig`
 - `DocumentNumbering`
 - `NumberedTarget`
-- `Section.numbering`
-- `NumberingMode = Literal["auto", "none", "manual"]`
-
----
-
-## 10. Export and round-trip / 导出与回转
-
-- `Document.to_dict(exclude_none=True)`
-- `Document.to_json(indent=2, exclude_none=True)`
-- `Document.save_json(path, indent=2, exclude_none=True)`
-- `Document.from_dict(data)`
-- `Document.from_json(text)`
-- `Document.load_json(path)`
-
----
-
-## 11. Package-level enums and constrained values / 包内枚举与约束值
-
-### Text styles / 文本样式
-
-- `normal`
-- `blockquote`
-- `caption`
-- `figure_caption`
-- `table_caption`
-- `equation_caption`
-- `smallprint`
-- `lead`
-- `quote_source`
-- `subheading`
-
-### Decorator marks / 装饰 mark
-
-- `strong`
-- `em`
-- `underline`
-- `code`
-
-### List styles / 列表类型
-
-- `bullet`
-- `number`
-
-### Image source kinds / 图片来源类型
-
-- `url`
-- `embedded`
-
-### Current package metadata validation / 当前包对 meta 的校验
-
-- `language` / `locale`: `"zh"` or `"en"`
-- `documentType`: `"valuationReport"`
-- `confidentiality`: `"public" | "user" | "internal" | "confidential"`
-- `reportType`: `"startupCompany" | "innovationTeam" | "patent" | "loan"`
-- `date`: `YYYY-MM-DD`
-- `generatedAt`: RFC 3339 / ISO 8601 datetime string

{ovaportabletext-0.1.4 → ovaportabletext-0.3.0}/docs/EXAMPLES.md

@@ -47,6 +47,8 @@ If you are new to the package, read in this order:
   URL and embedded image-source models. / URL 与内嵌 imageSource 模型。
 - `grid_table_demo.py`  
   `record` and `grid` table datasets, including duplicate headers and irregular layouts. / `record` 与 `grid` 表格模式。
+- `v11_layout_and_cell_image_demo.py`  
+  Demonstrates `theme.blockStyleDefaults`, block `layout`, weighted table columns, and grid-cell images. / 演示 `theme.blockStyleDefaults`、块级 `layout`、表格列权重和单元格图片。
 - `extended_registries_demo.py`  
   Logos, backgrounds, icons, attachments, and metric datasets. / logo、背景、图标、附件和指标数据集。
 

{ovaportabletext-0.1.4 → ovaportabletext-0.3.0}/docs/PROTOCOL_ALIGNMENT.md

@@ -1,7 +1,7 @@
 # Protocol Alignment / 协议对齐说明
 
-This page explains how OVAPortableText 0.1.3 aligns with the current Report Profile v1.0 protocol draft used in this repository.  
-本文档说明 OVAPortableText 0.1.3 与当前仓库内维护的 Report Profile v1.0 协议草案之间的对齐关系。
+This page explains how OVAPortableText 0.3.0 aligns with the current Report Profile v1.2 protocol maintained in this repository.  
+本文档说明 OVAPortableText 0.3.0 与当前仓库内维护的 Report Profile v1.2 正式协议之间的对齐关系。
 
 ---
 
@@ -20,8 +20,8 @@ The package aligns to this top-level shape:
 - `glossary`
 - `sections`
 
-`schemaVersion` defaults to `report.v1.0`.  
-`schemaVersion` 默认值为 `report.v1.0`。
+`schemaVersion` defaults to `report.v1.2`.  
+`schemaVersion` 默认值为 `report.v1.2`。
 
 ---
 

{ovaportabletext-0.1.4 → ovaportabletext-0.3.0}/docs/QUICKSTART.md

@@ -50,8 +50,8 @@ What happens here / 这里发生了什么：
 
 ## 3. Add registry-backed content / 添加引用型内容
 
-The protocol separates top-level registries from body instances.  
-协议把“顶层 registry”与“正文实例”分开处理。
+The protocol separates top-level registries from body instances. In `report.v1.2`, image / chart / table / math instances may omit instance `id` where the protocol allows it, text blocks can carry `layout`, sections can carry `sectionRole / navigation / pagination / presentation`, and grid cells can now contain charts.  
+协议把“顶层 registry”与“正文实例”分开处理。在 `report.v1.2` 中，协议允许的图片 / 图表 / 表格 / 公式实例都可以省略实例 `id`，文本块可携带 `layout`，section 可携带 `sectionRole / navigation / pagination / presentation`，grid 单元格现在还可以放图表。
 
 ### Example / 示例
 
@@ -91,7 +91,7 @@ report.add_table_dataset(
 )
 
 sec = report.new_section(id="sec-1", level=1, title="Body")
-sec.append_block(image_block(id="fig-cover", image_ref="img-cover"))
+sec.append_block(image_block(image_ref="img-cover", id="fig-cover"))
 sec.append_block(table_block(id="tbl-summary", table_ref="table-summary"))
 
 report.assert_valid()