hd-garden 0.12.1 → 0.13.1

package/app/components/GardenDocsNav.tsx

@@ -8,10 +8,11 @@ import {
   groupHandbookDocs,
   HANDBOOK_SECTIONS,
   HANDBOOK_UI,
-  NAV_SHORT_TITLE,
   REFERENCE_SECTION,
+  handbookNavLabel,
   isReferencePath,
   handbookPath,
+  referenceBadgeSuffix,
   sectionTitle,
   type GardenDocNavItem,
   type HandbookLang,
@@ -103,7 +104,7 @@ export function GardenDocsNav({
         <div className="gdoc-mobile-crumb" aria-hidden="true">
           <span>{sectionTitle(currentSection, lang) ?? t.name}</span>
           <CaretRight size={12} />
-          <strong>{currentDoc ? (lang === "en" ? currentDoc.navTitle ?? currentDoc.title : NAV_SHORT_TITLE[currentDoc.path] ?? currentDoc.title) : t.overviewHint}</strong>
+          <strong>{currentDoc ? handbookNavLabel(currentDoc, lang) : t.overviewHint}</strong>
         </div>
       </div>
 
@@ -161,7 +162,10 @@ export function GardenDocsNav({
                 {group.items.map((item) => {
                   const active = item.path === currentPath;
                   const badge = COMPONENT_BADGE[item.path];
-                  const label = lang === "en" ? item.navTitle ?? item.title : NAV_SHORT_TITLE[item.path] ?? item.title;
+                  const label = handbookNavLabel(item, lang);
+                  const referenceSuffix = group.id === REFERENCE_SECTION && badge
+                    ? referenceBadgeSuffix(badge, label)
+                    : null;
                   return (
                     <li key={item.path} className={active ? "is-active" : undefined}>
                       <Link
@@ -172,7 +176,11 @@ export function GardenDocsNav({
                         {badge ? (
                           <>
                             <code className="gdoc-comp-pill">{badge}</code>
-                            {group.id === REFERENCE_SECTION ? null : <span className="gdoc-comp-label">{label}</span>}
+                            {group.id === REFERENCE_SECTION ? (
+                              referenceSuffix ? <span className="gdoc-comp-label">{referenceSuffix}</span> : null
+                            ) : (
+                              <span className="gdoc-comp-label">{label}</span>
+                            )}
                           </>
                         ) : (
                           <span>{label}</span>

package/app/lib/garden-docs-meta.ts

@@ -133,6 +133,31 @@ export const NAV_SHORT_TITLE: Record<string, string> = {
   reference: "总览",
 };
 
+
+/**
+ * Reference sidebar shows COMPONENT_BADGE inside <code>. When two pages share a
+ * badge (compose + compose-icons), keep the code pill and append the remainder
+ * of navTitle / short label after a separator (space / · / dash).
+ * Returns the suffix including its leading separator, or null.
+ */
+export function referenceBadgeSuffix(badge: string, label: string): string | null {
+  if (!badge || !label || label === badge) return null;
+  if (!label.startsWith(badge)) return null;
+  const rest = label.slice(badge.length);
+  if (!rest || !/^[\s·\-—]/.test(rest)) return null;
+  return rest;
+}
+
+/** Sidebar text label: prefer authored navTitle; ZH may fall back to NAV_SHORT_TITLE. */
+export function handbookNavLabel(item: GardenDocNavItem, lang: HandbookLang): string {
+  if (item.navTitle) return item.navTitle;
+  if (lang !== "en") {
+    const short = NAV_SHORT_TITLE[item.path];
+    if (short) return short;
+  }
+  return item.title;
+}
+
 export function groupHandbookDocs<T extends GardenDocNavItem>(docs: T[]) {
   const bySection = new Map<string, T[]>();
   for (const section of HANDBOOK_SECTIONS) {

package/docs/handbook/components/compose.md

@@ -132,3 +132,73 @@ intent: |
 <slider min={1} max={12} value={seats} onChange={setSeats} label="席位" />
 <stat label="月费" value={total} unit="USD" />
 ```
+
+Play 图表：`palette`（series|categorical）、`yStep`、`overflow`（expand|clip）；块头可选 `frame: none`。布局头栏用 `<stack direction="row" justify="between">`。
+
+图例：`legend`（auto|show|hide）、`legendPosition`（top|bottom）。
+
+## 图表示例（play）
+
+下面两例是官方 compose 图表样板：静态八柱（系列蓝 + `yStep`）与可调权重五类柱（`palette="categorical"` + 底图例）。示意数据。
+
+### 静态：活跃时段分布
+
+```garden compose #compose-chart-active-hours
+caption: 示意：最近 30 天活跃记录归一化后的分布。峰在 20:00。
+frame: none
+intent: |
+  静态分布：系列蓝柱、显式 8% 刻度、stack 头栏左标题右徽章。
+---
+{@body const rows = [
+  { h: "08:00", p: 0.05 },
+  { h: "10:00", p: 0.07 },
+  { h: "12:00", p: 0.15 },
+  { h: "14:00", p: 0.06 },
+  { h: "16:00", p: 0.09 },
+  { h: "18:00", p: 0.14 },
+  { h: "20:00", p: 0.28 },
+  { h: "22:00", p: 0.16 }
+]}
+
+<stack direction="row" justify="between" align="center" gap={2}>
+  <stack gap={1}>
+    <caption>用户活跃时间分布（示例）</caption>
+    <caption>假设用户最近 30 天的活跃记录经过归一化后的分布</caption>
+  </stack>
+  <badge tone="new">推荐 20:00</badge>
+</stack>
+
+<chart data={rows} x={h} yLabel="活跃概率" yFormat="percent" yMin={0} yMax={0.32} yStep={0.08} overflow="expand" height={280}>
+  <bar y={p} label="活跃概率" tone="accent" />
+</chart>
+```
+
+### 交互：个人与整体融合权重
+
+默认权重 **45%**。拧滑杆或快切 0 / 45 / 100，五根分类色柱与「预测最佳时间」跟着变。
+
+```garden compose #compose-chart-fusion-weights
+caption: 交互示例：拧个人权重，融合柱按公式重算。示意数据。
+frame: none
+intent: |
+  融合滑杆：categorical 逐柱色、legend 底栏单系列、overflow expand。
+---
+{@body const [w, setW] = DIL.useState(45)}
+{@body const a = w / 100}
+{@body const p08 = a * 0.05 + (1 - a) * 0.12}
+{@body const p12 = a * 0.12 + (1 - a) * 0.22}
+{@body const p18 = a * 0.20 + (1 - a) * 0.26}
+{@body const p20 = a * 0.45 + (1 - a) * 0.28}
+{@body const p22 = a * 0.18 + (1 - a) * 0.12}
+{@body const rows = [{ h: "08:00", p: p08 }, { h: "12:00", p: p12 }, { h: "18:00", p: p18 }, { h: "20:00", p: p20 }, { h: "22:00", p: p22 }]}
+{@body const peak = max(p08, p12, p18, p20, p22)}
+{@body const best = p20 == peak ? "20:00" : (p18 == peak ? "18:00" : (p12 == peak ? "12:00" : (p22 == peak ? "22:00" : "08:00")))}
+
+<choice value={w} onChange={setW} label="权重快切" options={[{value:0,label:"0%"},{value:45,label:"45%"},{value:100,label:"100%"}]} />
+<slider min={0} max={100} value={w} onChange={setW} label="个人活跃数据权重" unit="%" />
+<chart legend="show" legendPosition="bottom" data={rows} x={h} palette="categorical" yLabel="融合后活跃概率" yFormat="percent" yMin={0} yMax={0.4} overflow="expand" height={280}>
+  <bar y={p} label="融合后活跃概率" tone="accent" />
+</chart>
+<stat label="预测最佳时间" value={best} />
+```
+

package/docs/handbook/components/interactive.md

@@ -42,3 +42,7 @@ caption: 示例：按字数、阅读速度和配图数估算一篇文章的阅
 ## 字段说明
 
 全部字段、默认值、取值限制和报错代码见 [组件参考 · interactive](/garden/reference/interactive)。
+
+Play 图表：`palette`（series|categorical）、`yStep`、`overflow`（expand|clip）；块头可选 `frame: none`。布局头栏用 `<stack direction="row" justify="between">`。
+
+图例：`legend`（auto|show|hide）、`legendPosition`（top|bottom）。

package/docs/handbook/en/components/compose.md

@@ -121,3 +121,71 @@ intent: |
 <slider min={1} max={12} value={seats} onChange={setSeats} label="Seats" />
 <stat label="Monthly" value={total} unit="USD" />
 ```
+
+Play charts: `palette` (`series`|`categorical`), `yStep`, `overflow` (`expand`|`clip`); block header may set `frame: none`. Title/badge rows use `<stack direction="row" justify="between">`. Legend: `legend` (`auto`|`show`|`hide`), `legendPosition` (`top`|`bottom`).
+
+## Chart examples (play)
+
+Two official compose chart samples: eight static series bars with `yStep`, and a five-category weighted fusion chart (`palette="categorical"` + bottom legend). Illustrative data.
+
+### Static: active hours
+
+```garden compose #compose-chart-active-hours
+caption: "Illustrative: normalized activity over 30 days. Peak at 20:00."
+frame: none
+intent: |
+  Static distribution: series blue bars, explicit 8% ticks, stack header.
+---
+{@body const rows = [
+  { h: "08:00", p: 0.05 },
+  { h: "10:00", p: 0.07 },
+  { h: "12:00", p: 0.15 },
+  { h: "14:00", p: 0.06 },
+  { h: "16:00", p: 0.09 },
+  { h: "18:00", p: 0.14 },
+  { h: "20:00", p: 0.28 },
+  { h: "22:00", p: 0.16 }
+]}
+
+<stack direction="row" justify="between" align="center" gap={2}>
+  <stack gap={1}>
+    <caption>User activity by hour (sample)</caption>
+    <caption>Normalized activity over the last 30 days (illustrative)</caption>
+  </stack>
+  <badge tone="new">Peak 20:00</badge>
+</stack>
+
+<chart data={rows} x={h} yLabel="Activity" yFormat="percent" yMin={0} yMax={0.32} yStep={0.08} overflow="expand" height={280}>
+  <bar y={p} label="Activity" tone="accent" />
+</chart>
+```
+
+### Interactive: personal vs global fusion weight
+
+Default weight **45%**. Twist the slider or jump 0 / 45 / 100 — five categorical bars and “best time” update together.
+
+```garden compose #compose-chart-fusion-weights
+caption: Twist personal weight; fused bars recompute. Illustrative priors.
+frame: none
+intent: |
+  Fusion slider: categorical bars, bottom one-entry legend, overflow expand.
+---
+{@body const [w, setW] = DIL.useState(45)}
+{@body const a = w / 100}
+{@body const p08 = a * 0.05 + (1 - a) * 0.12}
+{@body const p12 = a * 0.12 + (1 - a) * 0.22}
+{@body const p18 = a * 0.20 + (1 - a) * 0.26}
+{@body const p20 = a * 0.45 + (1 - a) * 0.28}
+{@body const p22 = a * 0.18 + (1 - a) * 0.12}
+{@body const rows = [{ h: "08:00", p: p08 }, { h: "12:00", p: p12 }, { h: "18:00", p: p18 }, { h: "20:00", p: p20 }, { h: "22:00", p: p22 }]}
+{@body const peak = max(p08, p12, p18, p20, p22)}
+{@body const best = p20 == peak ? "20:00" : (p18 == peak ? "18:00" : (p12 == peak ? "12:00" : (p22 == peak ? "22:00" : "08:00")))}
+
+<choice value={w} onChange={setW} label="Weight presets" options={[{value:0,label:"0%"},{value:45,label:"45%"},{value:100,label:"100%"}]} />
+<slider min={0} max={100} value={w} onChange={setW} label="Personal activity weight" unit="%" />
+<chart legend="show" legendPosition="bottom" data={rows} x={h} palette="categorical" yLabel="Fused activity" yFormat="percent" yMin={0} yMax={0.4} overflow="expand" height={280}>
+  <bar y={p} label="Fused activity" tone="accent" />
+</chart>
+<stat label="Predicted best time" value={best} />
+```
+

package/docs/handbook/en/reference/compose.md

@@ -170,6 +170,11 @@ One mini sample per group, then a one-line table for every tag. No per-tag essay
 | `code` | Code snapshot |
 | `pre` | Preformatted text |
 
+
+## Chart examples
+
+Play-level chart samples (static eight bars, fusion weight slider) live on [Diagrams · compose](/garden/en/components/compose#ui-compose-chart-active-hours).
+
 ## Limits
 
 - Nesting ~10 levels / ~220 nodes.

package/docs/handbook/reference/compose.md

@@ -170,6 +170,11 @@ badge: compose
 | `code` | 代码快照 |
 | `pre` | 预格式文本 |
 
+
+## 图表示例
+
+玩法级图表示例（静态八柱、融合权重滑杆）见 [说明图 · compose](/garden/components/compose#ui-compose-chart-active-hours)。
+
 ## 限制
 
 - 嵌套约 10 层 / 约 220 节点。