fix: booktab reference (fix #37)

[lucifer1004]

Summary by CodeRabbit

• Bug Fixes

  • Captioned tables can now be referenced by label (@Label) as expected.
  • Fixed alignment between Chinese and English text in tables.
  • Adjusted table rendering so captioned tables are wrapped as figures and text sizing aligns correctly.

• Documentation

  • Added guidance on table citation rules and cross-reference requirements for charts and tables.
  • Included a concrete example demonstrating captioned booktab usage with labels.

• Chores

  • Version bumped to 0.2.2.

[coderabbitai]

Warning

Rate limit exceeded

@lucifer1004 has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 15 minutes and 25 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📝 Walkthrough

Walkthrough

Moves table font sizing into the table block, removes table top-edge: "ascender", tightens figure-wrapping to require outlined plus a caption for table referenceability, adds documentation and changelog entries, and bumps package version to 0.2.2.

Changes

Cohort / File(s)	Summary
Changelog changelog.typ	Added changelog entry (2026-02-16) for PR 38 documenting the table/booktab fixes.
Docs / Examples doc/ch03-basics.typ	Clarified cross-reference rules: tables must use booktab with a caption (and outlined = true) to be targetable by @label; added example and repeated guidance in relevant sections.
Rendering / Components lib/components.typ	Moved text(字号.表文) into an inner block around the table, removed top-edge: "ascender", adjusted logic so only outlined booktabs with a caption are wrapped/targetable; switched caption rendering to use new helper.
Utilities lib/utils.typ	Replaced bodytotextwithtrim with caption-to-text(a) supporting strings and nested content bodies/children to extract caption text robustly.
Metadata typst.toml	Bumped package.version from 0.2.1 to 0.2.2.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• A complete rewrite of the whole package #26: Prior work touching booktab rendering and caption handling in the same components — likely directly related.
• fix: outline customization & format fix #27: Earlier changes to table/booktab rendering and caption utilities that this PR continues/refines.

Poem

🐰 I hopped into code with a tiny tap,
Moved font snug inside the table's lap,
No more ascender trimming the line,
Captions call labels—clear by design,
A carrot for docs, a joyful rap 🥕

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: fixing booktab reference issues (related to issue #37). The change directly addresses problems with booktab referenceability and citation behavior.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Merge Conflict Detection	✅ Passed	✅ No merge conflicts detected when merging into main

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix-37

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

lib/components.typ (1)

163-164: ⚠️ Potential issue | 🟡 Minor

Comment on caption parameter doesn't match the new guard condition.

Line 163 says figure is not used only when both caption is none and outlined is false. But the code on line 225 requires both outlined and caption != none to wrap in a figure. These are different conditions — e.g., outlined: true, caption: none would create a figure per the comment but not per the code.

Update the comment to reflect the actual behavior:

Suggested fix

-//   caption: 表格标题（设为 none 且 outlined 为 false 时不使用 figure）
-//   outlined: 是否包装在 figure 中（默认 true），设为 false 时生成纯表格
+//   caption: 表格标题（仅在 caption 不为 none 且 outlined 为 true 时包装为 figure）
+//   outlined: 是否允许包装在 figure 中（默认 true），设为 false 时生成纯表格

Also applies to: 225-229

🧹 Nitpick comments (1)

doc/ch03-basics.typ (1)

411-417: Trailing table at end of file has a caption but no label or surrounding explanation.

This booktab with caption: [交叉引用表示例] appears at the end of the cross-reference section without any accompanying text or a <label>. If the intent is to demonstrate a referenceable table, consider adding a label and a sentence referencing it. If it's just decorative, a brief comment explaining its purpose would help future maintainers.

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

lib/components.typ (1)

163-164: ⚠️ Potential issue | 🟡 Minor

Docstring is now inconsistent with the updated condition.

Line 163 states that figure wrapping is skipped only when both caption is none and outlined is false. However, the new condition on line 225 (outlined and caption != none) skips figure wrapping whenever caption is none, regardless of outlined. The comment should be updated to match the actual behavior.

Suggested docstring update

-//   caption: 表格标题（设为 none 且 outlined 为 false 时不使用 figure）
-//   outlined: 是否包装在 figure 中（默认 true），设为 false 时生成纯表格
+//   caption: 表格标题（设为 none 时不使用 figure，不可被引用）
+//   outlined: 是否在 figure 中显示（默认 true），需同时设置 caption 才会包装在 figure 中

Also applies to: 225-225

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

lib/components.typ (1)

225-229: ⚠️ Potential issue | 🟡 Minor

Edge case: outlined: true with caption: none may produce a broken list-of-figures entry.

When outlined is true but no caption is provided, the figure is created with caption: none. If this figure appears in listoffigures, caption-to-text(el.caption) receives none (type is neither str nor content), and link(el_loc, none) could produce unexpected output or an error.

Consider either:

• Defaulting caption to [] (empty content) when outlined is true, or
• Guarding in listoffigures before calling caption-to-text.

Suggested guard in booktab

   if outlined {
-    figure(the-table, caption: caption, kind: table)
+    figure(the-table, caption: if caption == none { [] } else { caption }, kind: table)
   } else {
     the-table
   }