feat(tree-list): configurable & themeable guide lines (guideStyle prop + astryx-tree-list-guide target)

[freddymeta]

Summary

TreeList draws its hierarchy guide (connector) lines as per-row vertical
segments, with the guide color hardcoded to a token baked into StyleX. Today
consumers who want to hide those connectors — or recolor them per theme — have
no supported path: they have to hide the built-in guides and reimplement their
own with unlayered CSS, which fights the cascade and drifts from the system.

This PR makes the guides configurable and themeable, additively and with
defaults unchanged:

• New guideStyle prop — 'segments' | 'none', default 'segments'.
  'segments' is the current behavior (byte-identical). 'none' omits the
  connector lines entirely, for layouts that already convey nesting or themes
  that supply their own connectors. Threaded through
  TreeList → TreeListItem → TreeListBranches the same way density already
  flows.
• New astryx-tree-list-guide theme target — the connector line element
  now carries a stable theme target (via themeProps), so a theme can recolor
  the guides through defineTheme (components['tree-list-guide']) instead of
  reaching them through internal StyleX classes. Mirrors the existing
  astryx-tree-list / astryx-tree-list-item targets.

Why

The guide color being hardcoded (not overridable per theme), plus there being
no way to turn guides off, forces consumers into the exact anti-pattern the
theming model is meant to prevent: hiding a built-in element and re-drawing it
with raw CSS. A prop + a stable theme target keeps guide customization inside
the system.

What's in scope

• TreeList / TreeListItem / TreeListBranches: prop type + threading +
  guide rendering + theme target
• TreeList.test.tsx: default 'segments' unchanged, 'none' hides guides,
  the new target renders, and a defineTheme override reaches it
• TreeList.doc.mjs: documents the guideStyle prop and adds
  astryx-tree-list-guide to theming.targets (EN + ZH)
• Storybook: NoGuides and ThemedGuides stories
• Changeset (patch)

Deferred: a 'rail' guide style

A third 'rail' mode — one continuous rail per group instead of per-row
segments — was considered but intentionally left out. It is a structural
rendering change (a rail spanning a whole group rather than independent
per-row segments) and carries real visual-regression risk against the current
segment layout. It fits better alongside the deeper TreeList layout work rather
than being forced into this additive, default-unchanged change. This PR keeps
the surface to 'segments' | 'none' plus the themeable color, which fully
covers the "hide or recolor" need.

Testing

• @astryxdesign/core test suite (TreeList + themingTargets guard)
• core typecheck + typecheck:docs, storybook typecheck
• eslint on changed files
• docsite generate + test
• sync-exports --check, check-sync, check-changesets, token-docs --check

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
astryx	Ready	Preview, Comment	Jul 25, 2026 3:08am

[github-actions]

PR Analysis Report

📚 Storybook Preview

View Storybook for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

🧪 Sandbox Preview

View Sandbox for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

Modified Components

TreeList · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	738	-
Complexity	N/A	Very High (75)	-

Bundle Size Summary

Package	Size (ESM)	Size (CJS)	Gzipped
@astryxdesign/core	N/A	4.7KB	0B

Accessibility Audit

Status: No accessibility violations detected.

---

_{Generated by PR Enrichment workflow | Storybook | Sandbox | View full report}

[cixzhang]

Thanks for this — the astryx-tree-list-guide theme target itself is great and follows the convention cleanly: the themeProps('tree-list-guide') call sites on the connector elements are recorded in TreeList.doc.mjs theming.targets (both docs and docsZh), with test + story + changeset. That part is welcome.

The blocker is scope: this PR also introduces new public API surface — the guideStyle?: TreeListGuideStyle prop on TreeListProps, plus a new exported TreeListGuideStyle type (from index.ts and TreeList.tsx) and the new type in TreeListTypes.ts. New public props/exports need to go through the API design review process rather than land via a lightweight theme-parity merge — a new prop is a long-term compatibility commitment and deserves that review (naming, value set, whether 'none' vs. a boolean, interaction with theming, etc.).

Could you split this into two PRs?

1. Keep the astryx-tree-list-guide theme target here (target + call sites + doc entry + test + story + changeset) — that can merge on the theme-parity path.
2. Pull the guideStyle prop + TreeListGuideStyle type into a separate PR that goes through the API/spec review.

Requesting changes to split out the prop; the theme-target half is good to go once separated.