@xgspz/cli-ui 0.0.0-stage → 0.6.14

package/src/layout/CliSplit.tsx

@@ -0,0 +1,53 @@
+/**
+ * 可拖动分栏（React 版）。每个子元素是一栏，栏之间可以左右拖动改宽度（规则见 split.ts）。
+ *
+ *   <CliCenterProvider baseUrl="/api/center" namespace="strategy">
+ *     <CliSplit storageKey="strategy" panes={[{ size: 300, min: 220, max: 480 }, { min: 360 }, { size: "42%", min: 320 }]}>
+ *       <CliMsgList />
+ *       <CliChat />
+ *       <CliBoard />
+ *     </CliSplit>
+ *   </CliCenterProvider>
+ *
+ * 三个组件在同一个 Provider 里照常联动（列表选中 → 对话和看板跟着切；对话里点文件 → 看板打开），分栏只管宽度。
+ */
+import { Children, useEffect, useRef, type CSSProperties, type ReactNode } from "react";
+import { attachSplit, type SplitHandle, type SplitPane } from "./split";
+
+export type CliSplitProps = {
+  children: ReactNode;
+  /** 每栏的初始宽度 / 最小 / 最大。写了 size 的是定宽栏，没写的占剩余宽度。缺省：第一栏 300px、最后一栏 42%、中间占剩余。 */
+  panes?: SplitPane[];
+  /** 记住拖好的宽度（localStorage）。 */
+  storageKey?: string;
+  onResize?: (sizes: (number | null)[]) => void;
+  className?: string;
+  style?: CSSProperties;
+};
+
+const defaultPanes = (n: number): SplitPane[] =>
+  n <= 1 ? [{}] : n === 2 ? [{ size: 300, min: 220, max: 520 }, { min: 360 }]
+    : Array.from({ length: n }, (_, i) => (i === 0 ? { size: 300, min: 220, max: 520 } : i === n - 1 ? { size: "42%", min: 320 } : { min: 360 }));
+
+export function CliSplit({ children, panes, storageKey, onResize, className, style }: CliSplitProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const handle = useRef<SplitHandle | null>(null);
+  const items = Children.toArray(children).filter(Boolean);
+  const onResizeRef = useRef(onResize);
+  onResizeRef.current = onResize;
+  const options = { panes: panes ?? defaultPanes(items.length), storageKey, onResize: (s: (number | null)[]) => onResizeRef.current?.(s) };
+  const sig = JSON.stringify([options.panes, storageKey, items.length]);
+
+  useEffect(() => {
+    if (!ref.current) return;
+    handle.current = attachSplit(ref.current, options);
+    return () => { handle.current?.destroy(); handle.current = null; };
+  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+  useEffect(() => { handle.current?.update(options); }, [sig]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  return (
+    <div ref={ref} className={`cli-split ${className ?? ""}`} style={style}>
+      {items.map((child, i) => <div key={(child as { key?: string | null }).key ?? i} className="cli-split-pane">{child}</div>)}
+    </div>
+  );
+}

package/src/layout/split.ts

@@ -0,0 +1,251 @@
+/**
+ * 可拖动分栏：把一个容器里横向排的几栏（列表 / 对话 / 看板，或宿主自己的栏）之间加上拖动条，左右拖改宽度。
+ * 不依赖 React：React 版 CliSplit 和 Web Component 版 <cli-split> 都用它。
+ *
+ *   attachSplit(container, { panes: [{ size: 300, min: 220, max: 480 }, { min: 360 }, { size: "42%", min: 320 }], storageKey: "strategy" })
+ *
+ * 规则：
+ *   · 写了 size 的栏是定宽（px 或百分比，未手动调整的百分比随容器宽度变化）；没写 size 的栏占剩下的宽度（只能有一个，没有就是最后一栏）。
+ *   · 拖动条改它旁边定宽的那一栏；任何一栏都不会小于自己的 min，占剩余宽度的那栏也一样。
+ *   · 双击拖动条：那一栏回到初始宽度。键盘：拖动条能聚焦，←/→ 每次 16px（按住 Shift 64px）。
+ *   · 子元素根节点带 collapsed 类（cli-board 收起时）：那一栏变成 40px 窄条（--cli-split-collapsed），旁边的拖动条隐藏；展开后回到原来的宽度。
+ *   · 写了 storageKey：拖好的宽度记在 localStorage（cli-ui:split:<storageKey>），下次打开还是这个宽度。
+ *   · 窗口变窄时定宽栏按超过 min 的空间比例让出宽度；各栏 min 之和能放下时，保证占剩余宽度的那栏不小于它的 min。
+ */
+export type SplitPane = { size?: number | `${number}%`; min?: number; max?: number };
+export type SplitOptions = {
+  panes?: SplitPane[];
+  storageKey?: string;
+  /** 拖完（松手 / 键盘 / 双击）后的各栏宽度，占剩余宽度的那栏是 null。 */
+  onResize?: (sizes: (number | null)[]) => void;
+};
+export type SplitHandle = { update: (options: SplitOptions) => void; reset: () => void; destroy: () => void };
+
+const DEFAULT_MIN = 160;
+const STEP = 16;
+
+export function attachSplit(container: HTMLElement, initial: SplitOptions = {}): SplitHandle {
+  let options = initial;
+  // Only user overrides are pixels. null keeps the configured responsive default.
+  // Old persisted numeric arrays remain valid user preferences.
+  let sizes: (number | null)[] = [];
+  let gutters: HTMLElement[] = [];
+  let panes: HTMLElement[] = [];
+  let dragging = false;
+
+  container.classList.add("cli-split");
+
+  const key = () => (options.storageKey ? `cli-ui:split:${options.storageKey}` : null);
+  const load = (): (number | null)[] | null => {
+    const k = key();
+    if (!k) return null;
+    try { const v = JSON.parse(localStorage.getItem(k) ?? "null"); return Array.isArray(v) ? v : null; } catch { return null; }
+  };
+  const save = () => {
+    const k = key();
+    if (k) try { localStorage.setItem(k, JSON.stringify(sizes)); } catch { /* 存不下就不记 */ }
+  };
+
+  const spec = (i: number): SplitPane => options.panes?.[i] ?? {};
+  const preferredFlexIndex = () => {
+    const i = panes.findIndex((_, n) => spec(n).size === undefined);
+    return i >= 0 ? i : panes.length - 1;
+  };
+  const minOf = (i: number) => Math.max(0, spec(i).min ?? DEFAULT_MIN);
+  const clamp = (i: number, w: number) => Math.round(Math.min(Math.max(minOf(i), spec(i).max ?? Infinity), Math.max(minOf(i), w)));
+  const contentWidth = () => {
+    const style = getComputedStyle(container);
+    return Math.max(0, container.clientWidth - (parseFloat(style.paddingLeft) || 0) - (parseFloat(style.paddingRight) || 0));
+  };
+  const initialSize = (i: number): number | null => {
+    if (i === preferredFlexIndex()) return null;
+    const s = spec(i).size;
+    if (typeof s === "string") return clamp(i, (parseFloat(s) / 100) * (contentWidth() || 1200));
+    return clamp(i, s ?? 320);
+  };
+  const isCollapsed = (pane: HTMLElement) => !!pane.firstElementChild?.classList.contains("collapsed");
+  const isVisible = (pane: HTMLElement) => !pane.hidden && getComputedStyle(pane).display !== "none";
+  const flexIndex = () => {
+    const preferred = preferredFlexIndex();
+    if (panes[preferred] && isVisible(panes[preferred]) && !isCollapsed(panes[preferred])) return preferred;
+    // A host may hide whole panes on mobile. A remaining visible pane fills the
+    // space without turning its default width into a permanent pixel override.
+    for (let i = panes.length - 1; i >= 0; i--) if (isVisible(panes[i]) && !isCollapsed(panes[i])) return i;
+    return -1;
+  };
+  const desiredSizes = () => panes.map((_, i) => i === preferredFlexIndex() ? null : clamp(i, sizes[i] ?? initialSize(i)!));
+
+  /** 定宽栏放进容器：总宽超了就按比例收，给占剩余宽度的那栏留出它的 min。 */
+  function fitted(flex: number): (number | null)[] {
+    const shown = desiredSizes();
+    const fixed = panes.flatMap((p, i) => i !== flex && isVisible(p) && !isCollapsed(p) ? [i] : []);
+    const collapsedW = panes.reduce((sum, p) => sum + (isVisible(p) && isCollapsed(p) ? p.getBoundingClientRect().width : 0), 0);
+    const gutterW = gutters.reduce((sum, g) => {
+      if (g.hidden) return sum;
+      const style = getComputedStyle(g);
+      const width = g.getBoundingClientRect().width || parseFloat(style.flexBasis) || 0;
+      return sum + Math.max(0, width + (parseFloat(style.marginLeft) || 0) + (parseFloat(style.marginRight) || 0));
+    }, 0);
+    const room = contentWidth() - (flex < 0 ? 0 : minOf(flex)) - collapsedW - gutterW;
+    const sum = fixed.reduce((total, i) => total + shown[i]!, 0);
+    if (!container.clientWidth || sum <= room) return shown;
+    const minimum = fixed.reduce((total, i) => total + minOf(i), 0);
+    // Scaling whole widths can hit one pane's minimum and still overflow the
+    // flexible pane. Allocate only the space above each minimum instead.
+    const ratio = sum > minimum ? Math.max(0, room - minimum) / (sum - minimum) : 0;
+    for (const i of fixed) shown[i] = minOf(i) + Math.floor((shown[i]! - minOf(i)) * ratio);
+    return shown;
+  }
+
+  function apply() {
+    const flex = flexIndex();
+    // Set narrow strips before measuring: their previous expanded width must
+    // not be subtracted from the available space on the first collapse frame.
+    for (const pane of panes) {
+      if (!isCollapsed(pane)) continue;
+      pane.style.flex = "0 0 var(--cli-split-collapsed, 40px)";
+      pane.style.width = "";
+      pane.style.minWidth = "";
+    }
+    gutters.forEach((g, i) => { g.hidden = !isVisible(panes[i]) || !isVisible(panes[i + 1]) || isCollapsed(panes[i]) || isCollapsed(panes[i + 1]); });
+    const shown = fitted(flex);
+    panes.forEach((pane, i) => {
+      pane.classList.add("cli-split-pane");
+      if (isCollapsed(pane)) return;
+      if (i === flex) { pane.style.flex = "1 1 0"; pane.style.width = ""; pane.style.minWidth = `${minOf(i)}px`; return; }
+      // Hidden preferred flex panes keep their flex role for when they return.
+      if (shown[i] === null) { pane.style.flex = "1 1 0"; pane.style.width = ""; pane.style.minWidth = `${minOf(i)}px`; return; }
+      pane.style.flex = `0 0 ${shown[i]}px`;
+      pane.style.width = `${shown[i]}px`;
+      pane.style.minWidth = "0";
+    });
+    gutters.forEach((g, i) => {
+      g.setAttribute("aria-valuenow", String(Math.round(panes[sideOf(i)]?.getBoundingClientRect().width ?? 0)));
+    });
+  }
+
+  /** 拖动条 i（在第 i 栏和第 i+1 栏之间）改的是哪一栏：左边定宽改左边，否则改右边。 */
+  const sideOf = (gutter: number) => (gutter === flexIndex() ? gutter + 1 : gutter);
+
+  function resize(gutter: number, dx: number) {
+    if (gutters[gutter]?.hidden) return;
+    const target = sideOf(gutter);
+    const sign = target === gutter ? 1 : -1;
+    const flex = flexIndex();
+    if (flex < 0) return;
+    const current = panes[target].getBoundingClientRect().width;
+    // 占剩余宽度的那栏不能被挤到 min 以下。
+    const flexW = panes[flex].getBoundingClientRect().width;
+    const grow = Math.min(sign * dx, Math.max(0, flexW - minOf(flex)));
+    sizes[target] = clamp(target, current + grow);
+    apply();
+  }
+
+  function finish() { save(); options.onResize?.(desiredSizes()); }
+
+  function makeGutter(index: number) {
+    const g = document.createElement("div");
+    g.className = "cli-split-gutter";
+    g.tabIndex = 0;
+    g.setAttribute("role", "separator");
+    g.setAttribute("aria-orientation", "vertical");
+    g.setAttribute("aria-label", "拖动调整宽度");
+    g.title = "拖动调整宽度，双击恢复";
+    g.addEventListener("pointerdown", (e) => {
+      if (e.button !== 0) return;
+      e.preventDefault();
+      g.setPointerCapture(e.pointerId);
+      dragging = true;
+      container.classList.add("cli-split-dragging");
+      let last = e.clientX;
+      const move = (ev: PointerEvent) => { const dx = ev.clientX - last; if (!dx) return; last = ev.clientX; resize(index, dx); };
+      const up = () => {
+        dragging = false;
+        container.classList.remove("cli-split-dragging");
+        g.removeEventListener("pointermove", move);
+        g.removeEventListener("pointerup", up);
+        g.removeEventListener("pointercancel", up);
+        finish();
+      };
+      g.addEventListener("pointermove", move);
+      g.addEventListener("pointerup", up);
+      g.addEventListener("pointercancel", up);
+    });
+    g.addEventListener("dblclick", () => {
+      const target = sideOf(index);
+      sizes[target] = null;
+      apply();
+      finish();
+    });
+    g.addEventListener("keydown", (e) => {
+      if (e.key !== "ArrowLeft" && e.key !== "ArrowRight") return;
+      e.preventDefault();
+      resize(index, (e.key === "ArrowLeft" ? -1 : 1) * (e.shiftKey ? STEP * 4 : STEP));
+      finish();
+    });
+    return g;
+  }
+
+  /** 子元素变了（宿主增删栏）：重新找栏、重新插拖动条。 */
+  function rebuild() {
+    for (const p of panes) ro?.unobserve?.(p);
+    for (const g of gutters) g.remove();
+    panes = [...container.children].filter((c): c is HTMLElement => c instanceof HTMLElement && !c.classList.contains("cli-split-gutter"));
+    const saved = load();
+    const flex = preferredFlexIndex();
+    sizes = panes.map((_, i) => {
+      if (i === flex) return null;
+      const keep = sizes[i];
+      if (typeof keep === "number" && Number.isFinite(keep)) return clamp(i, keep);
+      const s = saved && saved.length === panes.length ? saved[i] : null;
+      return typeof s === "number" && Number.isFinite(s) ? clamp(i, s) : null;
+    });
+    gutters = panes.slice(0, -1).map((_, i) => makeGutter(i));
+    gutters.forEach((g, i) => panes[i].after(g));
+    apply();
+    for (const p of panes) ro?.observe(p);
+  }
+
+  // 只看栏的增删、栏的根节点换了、根节点的 class 变了（收起 / 展开）；栏里面的内容（流式输出）不看，不然每个字都要重排。
+  const observer = new MutationObserver((records) => {
+    if (dragging) return;
+    const structural = records.some((r) => r.type === "childList" && r.target === container
+      && [...r.addedNodes, ...r.removedNodes].some((n) => !(n instanceof HTMLElement && n.classList.contains("cli-split-gutter"))));
+    observer.disconnect();
+    if (structural) rebuild(); else apply();
+    observe();
+  });
+  const observe = () => {
+    observer.observe(container, { childList: true });
+    for (const p of panes) {
+      observer.observe(p, { childList: true });
+      if (p.firstElementChild) observer.observe(p.firstElementChild, { attributes: true, attributeFilter: ["class"] });
+    }
+  };
+  const ro = typeof ResizeObserver !== "undefined" ? new ResizeObserver(() => { if (!dragging) apply(); }) : null;
+
+  rebuild();
+  observe();
+  ro?.observe(container);
+
+  return {
+    update(next) {
+      const keyChanged = next.storageKey !== options.storageKey;
+      options = next;
+      if (keyChanged) sizes = [];
+      observer.disconnect(); rebuild(); observe();
+    },
+    reset() {
+      sizes = panes.map(() => null);
+      apply();
+      finish();
+    },
+    destroy() {
+      observer.disconnect();
+      ro?.disconnect();
+      for (const g of gutters) g.remove();
+      for (const p of panes) { p.style.flex = ""; p.style.width = ""; p.style.minWidth = ""; p.classList.remove("cli-split-pane"); }
+      container.classList.remove("cli-split", "cli-split-dragging");
+    },
+  };
+}