like-sci-figures 0.0.0-stage → 1.0.0

package/scripts/add_chart.py

@@ -0,0 +1,201 @@
+#!/usr/bin/env python3
+"""Scaffolding tool for adding new chart types to like-sci-figures.
+
+Why this exists
+---------------
+Adding a new chart type used to require manual edits to 4 files. This tool
+generates the boilerplate in one command, so the developer only needs to
+fill in the rendering logic and example data.
+
+Usage
+-----
+    python scripts/add_chart.py --name my_chart --zh "我的图表"
+    python scripts/add_chart.py --name my_chart --kind statistics --aliases myplot,my
+
+What it generates
+-----------------
+    scripts/fig_my_chart.py     ChartPlugin subclass with render() stub
+    examples/my_chart.json      Example data file
+    registry.py entry           Auto-appended (with marker comment)
+
+After running this tool, edit the generated files and run:
+    python scripts/gen_figure.py --verify-all    # check it renders
+    python scripts/generate_showcases.py         # update preview images
+"""
+import argparse
+import json
+import os
+import sys
+import textwrap
+
+SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+SKILL_DIR = os.path.dirname(SCRIPT_DIR)
+EXAMPLES_DIR = os.path.join(SKILL_DIR, "examples")
+REGISTRY_PATH = os.path.join(SCRIPT_DIR, "registry.py")
+
+# Marker comments for idempotent registry updates.
+_REGISTRY_START = "# ── Auto-generated entries (add_chart.py) ──"
+_REGISTRY_END = "# ── End auto-generated entries ──"
+
+
+def generate_plugin_module(chart_name, zh_name, kind, aliases):
+    """Return the source code for fig_<name>.py."""
+    alias_list = list(aliases) if aliases else []
+    alias_line = "aliases = %s" % repr(tuple(alias_list)) if alias_list else "aliases = ()"
+    return textwrap.dedent(f"""\
+#!/usr/bin/env python3
+\"\"\"Chart type: {chart_name} ({zh_name}).
+
+Generated by add_chart.py. Fill in the render() method and example data.
+\"\"\"
+from chart_plugin import ChartPlugin
+
+
+class {chart_name.capitalize().replace('_', '')}Chart(ChartPlugin):
+    name = \"{chart_name}\"
+    zh = \"{zh_name}\"
+    kind = \"{kind}\"
+    {alias_line}
+    required_keys = (\"x\", \"y\")
+    optional_keys = ()
+    data_format = \"json\"
+
+    def render(self, data, ax, colors, cjk_fp, **kwargs):
+        \"\"\"Render the chart.
+
+        Args:
+            data: parsed data dict
+            ax: matplotlib axes object
+            colors: list of hex colours
+            cjk_fp: CJK font path or None
+            **kwargs: chart-specific flags
+
+        Returns:
+            Optional colorbar artist, else None.
+        \"\"\"
+        # TODO: Implement rendering logic
+        # Example:
+        # x = data.get(\"x\", [])
+        # y = data.get(\"y\", [])
+        # ax.plot(x, y, color=colors[0])
+        # return None
+
+        raise NotImplementedError(
+            f\"Render logic not implemented for {{self.name}}\")
+""")
+
+
+def generate_example_data(chart_name):
+    """Return a minimal valid JSON example for the chart type."""
+    example = {
+        "labels": ["A", "B", "C", "D", "E"],
+        "series": {
+            "Series A": [10, 20, 15, 30, 25],
+            "Series B": [5, 12, 8, 18, 15],
+        }
+    }
+    return json.dumps(example, ensure_ascii=False, indent=2)
+
+
+def update_registry(chart_name, zh_name, example_file, kind, aliases):
+    """Append a new entry to registry.py's _REGISTRY list."""
+    alias_tuple = tuple(list(aliases) + ([example_file] if False else []))
+    # Build the registry entry line.
+    entry = f'    ("{chart_name}", "{zh_name}", "{example_file}", "{kind}", ({", ".join(repr(a) for a in aliases)})), '
+    with open(REGISTRY_PATH, "r", encoding="utf-8") as f:
+        content = f.read()
+
+    # Check if entry already exists.
+    if f'"{chart_name}"' in content:
+        print(f"  (entry for {chart_name} already exists in registry.py)")
+        return
+
+    # Insert before the closing bracket of _REGISTRY.
+    marker = "    (\"subplots\""
+    idx = content.find(marker)
+    if idx == -1:
+        # Try to find the end of the list.
+        idx = content.rfind("]")
+    if idx == -1:
+        print("ERROR: Could not find insertion point in registry.py", file=sys.stderr)
+        return 1
+
+    # Insert before the marker (at the end of the list, before the closing bracket).
+    # Find the closing bracket.
+    bracket_idx = content.find("]", idx)
+    if bracket_idx == -1:
+        print("ERROR: Could not find closing bracket in registry.py", file=sys.stderr)
+        return 1
+
+    # Insert before the closing bracket.
+    insert_pos = content.rfind("\n", 0, bracket_idx) + 1
+    indent = "    "
+    entry_line = f'{indent}("{chart_name}", "{zh_name}", "{example_file}", "{kind}", {repr(tuple(aliases))}),\n'
+
+    new_content = content[:insert_pos] + entry_line + content[insert_pos:]
+    with open(REGISTRY_PATH, "w", encoding="utf-8") as f:
+        f.write(new_content)
+    print(f"  Updated registry.py: added {chart_name}")
+    return 0
+
+
+def main():
+    ap = argparse.ArgumentParser(
+        prog="add_chart.py",
+        description="Scaffold a new chart type for like-sci-figures.",
+    )
+    ap.add_argument("--name", required=True,
+                    help="Chart type slug (e.g. my_chart)")
+    ap.add_argument("--zh", required=True,
+                    help="Chinese display name (e.g. 我的图表)")
+    ap.add_argument("--kind", default="specialized",
+                    choices=["statistics", "relational", "specialized"],
+                    help="Chart category (default: specialized)")
+    ap.add_argument("--aliases", default="",
+                    help="Comma-separated alias slugs (e.g. myplot,my)")
+    ap.add_argument("--force", action="store_true",
+                    help="Overwrite existing files")
+    args = ap.parse_args()
+
+    chart_name = args.name
+    zh_name = args.zh
+    kind = args.kind
+    aliases = [a.strip() for a in args.aliases.split(",") if a.strip()]
+
+    # ── Generate plugin module ─────────────────────────────────────────
+    module_path = os.path.join(SCRIPT_DIR, f"fig_{chart_name}.py")
+    if os.path.exists(module_path) and not args.force:
+        print(f"SKIP: {module_path} already exists (use --force to overwrite)")
+    else:
+        code = generate_plugin_module(chart_name, zh_name, kind, aliases)
+        with open(module_path, "w", encoding="utf-8") as f:
+            f.write(code)
+        print(f"  Created: {module_path}")
+
+    # ── Generate example data ───────────────────────────────────────────
+    example_path = os.path.join(EXAMPLES_DIR, f"{chart_name}.json")
+    if os.path.exists(example_path) and not args.force:
+        print(f"SKIP: {example_path} already exists (use --force to overwrite)")
+    else:
+        data = generate_example_data(chart_name)
+        with open(example_path, "w", encoding="utf-8") as f:
+            f.write(data)
+        print(f"  Created: {example_path}")
+
+    # ── Update registry ─────────────────────────────────────────────────
+    rc = update_registry(chart_name, zh_name, f"{chart_name}.json", kind, aliases)
+    if rc != 0:
+        return rc
+
+    print()
+    print("Done. Next steps:")
+    print(f"  1. Edit fig_{chart_name}.py and implement render()")
+    print(f"  2. Edit examples/{chart_name}.json with real data")
+    print(f"  3. Test: python scripts/gen_figure.py --type {chart_name} \\")
+    print(f"     --data examples/{chart_name}.json --out test_{chart_name}.png")
+    print(f"  4. Update previews: python scripts/generate_showcases.py --force")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/build_gallery.py

@@ -0,0 +1,360 @@
+#!/usr/bin/env python3
+"""Build an interactive HTML palette gallery for like-sci-figures.
+
+Why this exists
+---------------
+When the agent asks the user to pick a palette, a flat text list or even a
+tall poster is awkward. This generator produces a single self-contained
+`references/palette_gallery.html`:
+
+  * One compact card per palette (slug, 中文名, 类型徽章, 适用领域, 色卡条)
+  * Hovering a card floats up its pre-generated thumbnail
+    (previews/<slug>.png) — the exact "hover → preview" UX
+  * A fixed preview pane on the right shows the hovered palette large
+  * Click a card → copies the slug to the clipboard (to paste into --palette)
+  * A search box filters by name / domain / slug
+
+The previews are referenced by RELATIVE path (`../previews/<slug>.png`) so the
+file stays small and stays in sync with the generated assets. Pass
+`--bundle` to inline the PNGs as base64 for a single portable file.
+
+Usage
+-----
+    build_gallery.py                  # write references/palette_gallery.html
+    build_gallery.py --bundle         # inline images as base64 (single file)
+    build_gallery.py --out PATH       # write to an explicit absolute PATH
+    # The script prints "PRESENT_PATH=<abs path>" — present THAT path.
+    # (Never a relative/$(pwd) path: the static server returns 403 for a
+    #  file that does not exist at the presented location.)
+"""
+import argparse
+import base64
+import json
+import os
+import sys
+import time
+
+SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, SCRIPT_DIR)
+
+from palettes import list_palettes, palette_info  # noqa: E402
+
+SKILL_DIR = os.path.dirname(SCRIPT_DIR)
+PREVIEW_DIR = os.path.join(SKILL_DIR, "previews")
+OUT_PATH = os.path.join(SKILL_DIR, "references", "palette_gallery.html")
+OUT_BUNDLE = os.path.join(SKILL_DIR, "references", "palette_gallery.bundled.html")
+
+KIND_ZH = {"qualitative": "定性", "sequential": "顺序", "diverging": "发散"}
+
+
+def _b64(path):
+    with open(path, "rb") as fh:
+        return "data:image/png;base64," + base64.b64encode(fh.read()).decode("ascii")
+
+
+def _atomic_write(path, text):
+    """Write text to `path` atomically (temp file + os.replace) to avoid
+    leaving a half-written / locked file that a preview server or browser
+    might be holding."""
+    import tempfile
+    d = os.path.dirname(path)
+    if d and not os.path.isdir(d):
+        os.makedirs(d, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=d or ".", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            fh.write(text)
+        os.replace(tmp, path)
+    except BaseException:
+        try:
+            os.remove(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def build(bundle=False, out_path=None):
+    slugs = [s for s in list_palettes() if palette_info(s)]
+    cards = []
+    for slug in slugs:
+        info = palette_info(slug)
+        colors = list(info.get("colors") or [])
+        domain = info.get("domain") or []
+        cards.append({
+            "slug": slug,
+            "zh": info.get("zh") or slug,
+            "kind": info.get("kind") or "",
+            "desc": (info.get("desc") or "").strip(),
+            "domain": domain,
+            "colors": colors,
+        })
+
+    # Image source per slug
+    img_src = {}
+    for c in cards:
+        p = os.path.join(PREVIEW_DIR, "%s.png" % c["slug"])
+        if bundle and os.path.exists(p):
+            img_src[c["slug"]] = _b64(p)
+        elif os.path.exists(p):
+            img_src[c["slug"]] = "../previews/%s.png" % c["slug"]
+        else:
+            img_src[c["slug"]] = ""
+
+    data_json = json.dumps(
+        [dict(c, img=img_src[c["slug"]]) for c in cards],
+        ensure_ascii=False,
+    )
+
+    html = _TEMPLATE.replace("/*__DATA__*/", data_json)
+    target = out_path or (OUT_BUNDLE if bundle else OUT_PATH)
+    _atomic_write(target, html)
+
+    size = os.path.getsize(target)
+    print("Gallery: %d palettes -> %s (%.1f KB, %s)"
+          % (len(cards), target, size / 1024.0,
+             "bundled base64" if bundle else "relative paths"))
+    # The absolute path to present. This file always lives next to the skill
+    # (CWD-independent), and WorkBuddy's internal static server serves it fine
+    # (verified HTTP 200). Present THIS path — never a relative/$(pwd) path,
+    # or the server returns 403 Forbidden for the non-existent file.
+    print("PRESENT_PATH=%s" % os.path.abspath(target))
+    return 0
+
+
+_TEMPLATE = r"""<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>LIKE Sci Figures — 配色方案画廊</title>
+<style>
+  :root{
+    --green:#0B6E4F; --green-soft:#F0F6F3; --ink:#1a1a1a; --muted:#777;
+    --line:#e6e6e6; --bg:#fafbfc;
+  }
+  *{box-sizing:border-box;}
+  body{
+    margin:0; font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",
+    "PingFang SC","Microsoft YaHei",sans-serif; color:var(--ink); background:var(--bg);
+  }
+  header{
+    background:var(--green); color:#fff; padding:14px 22px; position:sticky; top:0; z-index:20;
+    display:flex; align-items:center; justify-content:space-between;
+  }
+  header h1{font-size:18px; margin:0; font-weight:600;}
+  header .sub{font-size:13px; color:#CDE7DD; margin-top:2px;}
+  header .author{font-size:14px; color:#CDE7DD; letter-spacing:1px;}
+  .toolbar{padding:12px 22px; border-bottom:1px solid var(--line); background:#fff;}
+  .toolbar input{
+    width:100%; max-width:420px; padding:9px 12px; border:1px solid var(--line);
+    border-radius:8px; font-size:14px; outline:none;
+  }
+  .toolbar input:focus{border-color:var(--green);}
+  .hint{font-size:12px; color:var(--muted); margin-top:6px;}
+  .layout{display:flex; gap:0; align-items:flex-start;}
+  .list{flex:1; padding:16px 22px 60px; display:grid;
+    grid-template-columns:repeat(auto-fill,minmax(300px,1fr)); gap:14px;}
+  .card{
+    background:#fff; border:1px solid var(--line); border-radius:12px; padding:14px;
+    cursor:pointer; transition:box-shadow .15s, transform .15s, border-color .15s;
+    position:relative;
+  }
+  .card:hover{box-shadow:0 6px 22px rgba(11,110,79,.14); border-color:var(--green);
+    transform:translateY(-2px);}
+  .card.sel{border-color:var(--green); box-shadow:0 0 0 2px rgba(11,110,79,.25);}
+  .row1{display:flex; align-items:center; gap:8px; flex-wrap:wrap;}
+  .slug{font-family:ui-monospace,Menlo,Consolas,monospace; font-size:13px; font-weight:600; color:var(--green);}
+  .zh{font-size:16px; font-weight:700; margin-left:2px;}
+  .slug2{font-family:ui-monospace,Menlo,Consolas,monospace; font-size:12px; color:var(--muted); margin:2px 0 8px;}
+  .badge{font-size:11px; color:#fff; padding:2px 7px; border-radius:999px;}
+  .b-qual{background:#0066CC;} .b-seq{background:#2E7D32;} .b-div{background:#B71C1C;}
+  .domtags{display:flex; flex-wrap:wrap; align-items:center; gap:5px; margin:4px 0 10px;}
+  .domlabel{font-size:11px; color:var(--green); font-weight:600; margin-right:2px;}
+  .domtag{font-size:11px; color:#0B6E4F; background:#EAF4EF; border:1px solid #CBE3D8; border-radius:999px; padding:2px 8px;}
+  .swatch{display:flex; height:18px; border-radius:5px; overflow:hidden; border:1px solid var(--line);}
+  .swatch span{flex:1;}
+  .pvtag{position:absolute; top:12px; right:12px; font-size:11px; color:var(--muted);
+    border:1px solid var(--line); border-radius:6px; padding:2px 7px; background:var(--green-soft);}
+  .card:hover .pvtag{color:var(--green); border-color:var(--green);}
+  /* fixed preview pane */
+  .pane{position:sticky; top:64px; width:360px; flex:0 0 360px; padding:16px 18px 24px;
+    border-left:1px solid var(--line); background:#fff; height:calc(100vh - 64px);
+    display:flex; flex-direction:column; align-items:center; gap:10px;}
+  .pane img{width:100%; border:1px solid var(--line); border-radius:10px; background:#fff;}
+  .pane .ph{font-size:13px; color:var(--muted); text-align:center;}
+  .pane .pname{font-weight:600;}
+  /* floating tooltip preview */
+  #tip{position:fixed; z-index:50; pointer-events:none; display:none;
+    border:2px solid var(--green); border-radius:10px; box-shadow:0 8px 24px rgba(0,0,0,.25);
+    background:#fff; padding:4px;}
+  #tip img{display:block; width:300px; border-radius:6px;}
+  .toast{position:fixed; bottom:26px; left:50%; transform:translateX(-50%);
+    background:var(--green); color:#fff; padding:10px 18px; border-radius:10px;
+    font-size:14px; opacity:0; transition:opacity .25s; z-index:60;}
+  .toast.show{opacity:1;}
+  @media(max-width:820px){ .pane{display:none;} }
+</style>
+</head>
+<body>
+<header>
+  <div>
+    <h1>LIKE Sci Figures — 配色方案画廊</h1>
+    <div class="sub">悬停卡片查看缩略图 · 点击复制 slug 用于 --palette</div>
+  </div>
+  <div class="author">LIKE</div>
+</header>
+<div class="toolbar">
+  <input id="q" placeholder="搜索：名称 / 领域 / slug（如 医学、nature、wx13）">
+  <div class="hint">共 <span id="cnt">0</span> 套配色 · 右侧为悬停大图预览</div>
+</div>
+<div class="layout">
+  <div class="list" id="list"></div>
+  <div class="pane">
+    <div class="pname" id="pname">将鼠标移到左侧任一配色</div>
+    <img id="pimg" alt="preview" style="display:none">
+    <div class="ph" id="pdesc">悬停即可预览该配色的 5 类代表图表效果</div>
+    <input id="slugbox" readonly value="" title="点击卡片复制；若自动复制失败可在此手动 Ctrl+C"
+      style="width:100%;padding:9px 8px;border:1px solid var(--line);border-radius:8px;
+             font-family:ui-monospace,Menlo,Consolas,monospace;font-size:13px;text-align:center;
+             color:var(--green);background:var(--green-soft);margin-top:6px;">
+    <div class="ph">点击左侧卡片即复制此 slug 用于 --palette</div>
+  </div>
+</div>
+<div id="tip"><img id="tipimg" src="" alt=""></div>
+<div class="toast" id="toast"></div>
+
+<script>
+const DATA = /*__DATA__*/;
+const list = document.getElementById('list');
+const q = document.getElementById('q');
+const tip = document.getElementById('tip');
+const tipimg = document.getElementById('tipimg');
+const pimg = document.getElementById('pimg');
+const pname = document.getElementById('pname');
+const pdesc = document.getElementById('pdesc');
+const slugbox = document.getElementById('slugbox');
+const cnt = document.getElementById('cnt');
+const toast = document.getElementById('toast');
+
+const badgeClass = {qualitative:'b-qual', sequential:'b-seq', diverging:'b-div'};
+const kindZh = {qualitative:'定性', sequential:'顺序', diverging:'发散'};
+
+function swatch(colors){
+  if(!colors || !colors.length) return '';
+  return '<div class="swatch">'+colors.map(c=>'<span style="background:'+c+'"></span>').join('')+'</div>';
+}
+
+function cardHTML(d, i){
+  const bc = badgeClass[d.kind]||'b-qual';
+  const kz = kindZh[d.kind]||d.kind;
+  const dom = (d.domain&&d.domain.length)? d.domain.map(x=>'<span class="domtag">'+x+'</span>').join('') : '';
+  return '<div class="card" data-i="'+i+'">'
+    + '<div class="pvtag">预览 ▸</div>'
+    + '<div class="row1"><span class="zh">'+d.zh+'</span>'
+    + '<span class="badge '+bc+'">'+kz+'</span></div>'
+    + '<div class="slug2">'+d.slug+'</div>'
+    + (dom? '<div class="domtags"><span class="domlabel">适用</span>'+dom+'</div>' : '')
+    + swatch(d.colors)
+    + '</div>';
+}
+
+function render(filter){
+  const f = (filter||'').trim().toLowerCase();
+  const items = DATA.map((d,i)=>({d,i})).filter(o=>{
+    if(!f) return true;
+    const hay = (o.d.slug+' '+o.d.zh+' '+(o.d.domain||[]).join(' ')+' '+(o.d.desc||'')).toLowerCase();
+    return hay.indexOf(f)>=0;
+  });
+  list.innerHTML = items.map(o=>cardHTML(o.d,o.i)).join('');
+  cnt.textContent = items.length;
+  // bind
+  list.querySelectorAll('.card').forEach(el=>{
+    const idx = +el.getAttribute('data-i');
+    const d = DATA[idx];
+    el.addEventListener('mouseenter', ()=>showPreview(d));
+    el.addEventListener('mousemove', moveTip);
+    el.addEventListener('mouseleave', hideTip);
+    el.addEventListener('click', ()=>pick(d, el));
+  });
+}
+
+function showPreview(d){
+  pname.textContent = d.slug+'  ·  '+d.zh;
+  pdesc.textContent = d.desc || '';
+  slugbox.value = d.slug;
+  if(d.img){ pimg.src=d.img; pimg.style.display='block'; }
+  tipimg.src = d.img||'';
+  tip.style.display='block';
+}
+function moveTip(e){
+  let x = e.clientX + 18, y = e.clientY + 18;
+  const w = 308;
+  let rw = tipimg.naturalWidth || 0, rh = tipimg.naturalHeight || 0;
+  const h = (rw && rh) ? (rh * (300 / rw) + 10) : 220;
+  if(x + w > window.innerWidth) x = e.clientX - w - 18;
+  if(y + h > window.innerHeight) y = e.clientY - h - 18;
+  if(x < 4) x = 4;
+  if(y < 4) y = 4;
+  tip.style.left = x+'px'; tip.style.top = y+'px';
+}
+function hideTip(){ tip.style.display='none'; }
+
+// Robust copy: clipboard API first, then legacy execCommand, then manual.
+function copyText(text){
+  if(navigator.clipboard && navigator.clipboard.writeText){
+    return navigator.clipboard.writeText(text)
+      .then(()=>true)
+      .catch(()=>legacyCopy(text));
+  }
+  return Promise.resolve(legacyCopy(text));
+}
+function legacyCopy(text){
+  try{
+    const ta=document.createElement('textarea');
+    ta.value=text; ta.setAttribute('readonly','');
+    ta.style.position='fixed'; ta.style.top='-9999px'; ta.style.left='0';
+    document.body.appendChild(ta); ta.focus(); ta.select();
+    const ok=document.execCommand('copy');
+    document.body.removeChild(ta);
+    return ok;
+  }catch(e){ return false; }
+}
+
+function pick(d, el){
+  document.querySelectorAll('.card.sel').forEach(c=>c.classList.remove('sel'));
+  el.classList.add('sel');
+  slugbox.value = d.slug;
+  copyText(d.slug).then(ok=>{
+    if(ok){
+      toast.textContent = '已复制: '+d.slug+'  （用于 --palette '+d.slug+'）';
+    }else{
+      toast.textContent = '自动复制失败，请手动复制：'+d.slug;
+      slugbox.focus(); slugbox.select();
+    }
+    toast.classList.add('show');
+    clearTimeout(pick._t);
+    pick._t = setTimeout(()=>toast.classList.remove('show'), 2400);
+  });
+}
+
+q.addEventListener('input', ()=>render(q.value));
+render('');
+</script>
+</body>
+</html>
+"""
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Build interactive palette gallery HTML")
+    ap.add_argument("--bundle", action="store_true",
+                    help="Inline preview PNGs as base64 (single portable file)")
+    ap.add_argument("--out", default=None,
+                    help="Write the gallery to this absolute path instead of "
+                         "references/palette_gallery.bundled.html")
+    args = ap.parse_args()
+    return build(bundle=args.bundle, out_path=args.out)
+
+
+if __name__ == "__main__":
+    sys.exit(main())