docs(charts): mark BarChart as experimental in the guide

[rodorgas]

Summary

Follow-up to #2147 addressing the post-merge feedback on the BarChart docs. Three points were raised:

1. No beta/rc npm dist-tag needed — the package is at 0.x, which already signals instability.
2. Mark it experimental in the docs so consumers know.
3. Indicate it in the JSDoc if possible.

What changed

1. Beta/rc tag — no change needed

@vtex/shoreline-charts publishes with only a latest dist-tag (currently 0.2.1) and the release workflow (lerna publish with no --tag) introduces no beta/rc tag. The 0.x version already conveys instability, so nothing to add or remove.

2. Experimental notice in the docs — added

Added a Nextra <Callout> right under the component description on bar-chart.mdx, the page consumers land on to install and use the component:

<Callout type="warning" emoji="🧪">
  **Experimental.** `BarChart` is not stable yet: it ships in `@vtex/shoreline-charts` at `0.x`, so its API and visuals may change between minor versions. Use it with that in mind.
</Callout>

This mirrors the existing Callout pattern used in table/figma-usage.mdx.

3. JSDoc — already present

BarChart already carries @status experimental in its JSDoc (packages/charts/src/components/bar-chart/bar-chart.tsx), matching the @status convention from the documentation guideline. The props build picks it up — __props__/index.ts has status: 'experimental' for bar-chart — so the experimental status is captured in the generated docs data. No change needed.

Test plan

• pnpm --filter @shoreline/docs gen:props succeeds — bar-chart still resolves with status: 'experimental'
• pnpm --filter @shoreline/docs gen:examples succeeds
• next build in packages/docs succeeds (full site)
• The Callout renders in the built /components/bar-chart HTML (Experimental. / not stable yet: it ships in)

Related

• docs(charts): add bar chart guide and best practices #2147 — docs(charts): add bar chart guide and best practices (the merged PR this follows up on)

Session cost

• Total cost: $0.00 (measured from the pi session log)
• Agent pi 0.84.1, model huawei/glm-5.2-vision (reasoning: off), 43 assistant turns
• Token breakdown: 85K input · 15K output · 9.8K reasoning · 1.1M cache-read (~1.2M total)

Summary by CodeRabbit

• Documentation
  • Added an experimental warning to the BarChart documentation.
  • Clarified that the component is unstable and may change between minor versions.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
shoreline-docs	Ready	Preview	Aug 13, 2026 11:32pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: ce20caca-2c23-49a2-89c7-fe43fee9d129

📥 Commits

Reviewing files that changed from the base of the PR and between 9e0c5b8 and 651e26d.

📒 Files selected for processing (1)

• packages/docs/pages/components/bar-chart.mdx

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/docs/pages/components/bar-chart.mdx

---

📝 Walkthrough

Walkthrough

The BarChart documentation now warns that the component is experimental and may change between minor versions.

Changes

BarChart documentation

Layer / File(s)	Summary
Add experimental warning packages/docs/pages/components/bar-chart.mdx	Adds a callout that identifies BarChart as experimental in the 0.x @vtex/shoreline-charts package and notes possible API and visual changes.

Estimated code review effort: 1 (Trivial) | ~2 minutes

Mergeability Score: ⚪ Minimal · up to 651e2

This localized documentation change clarifies that BarChart is experimental without changing runtime behavior, so no actionable merge-blocking risk remains after normal checks and review.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the documentation change that marks BarChart as experimental.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/barchart-experimental-notice

---

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.}

[rodorgas]

docs: improve callout text