@kanyun-ai-infra/band-plugin-react 0.1.1 → 0.1.2

package/dist/{chunk-ULDBT77D.js → chunk-HX653UQN.js}

@@ -334,6 +334,358 @@ function LogoLockup() {
   ] });
 }
 
+// src/settings/kit.tsx
+import {
+  useEffect,
+  useId,
+  useRef
+} from "react";
+import { Fragment, jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
+function settingsLinkHandler(go, target) {
+  return (e) => {
+    if (!go) return;
+    if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+    e.preventDefault();
+    go(target);
+  };
+}
+function SettingsLayout({
+  navLabel,
+  title,
+  obj,
+  crumb,
+  groups,
+  current,
+  view = "page",
+  back,
+  backMobile,
+  onNavigate,
+  mainRef,
+  children
+}) {
+  return /* @__PURE__ */ jsxs2("div", { className: "band-sf", "data-view": view, children: [
+    /* @__PURE__ */ jsxs2("nav", { className: "band-sf-nav", "aria-label": navLabel, children: [
+      /* @__PURE__ */ jsxs2("div", { className: "band-sf-head", children: [
+        crumb ? /* @__PURE__ */ jsx2("div", { className: "band-sf-crumb", children: crumb }) : null,
+        /* @__PURE__ */ jsx2("span", { className: "band-sf-title", children: title }),
+        !crumb && obj ? /* @__PURE__ */ jsx2("span", { className: "band-sf-obj", children: obj }) : null
+      ] }),
+      groups.map((g) => /* @__PURE__ */ jsxs2("div", { className: "band-sf-grp", children: [
+        /* @__PURE__ */ jsx2("span", { children: g.group }),
+        g.sections.map((s) => /* @__PURE__ */ jsxs2(
+          "a",
+          {
+            href: s.href,
+            "aria-current": s.slug === current ? "page" : void 0,
+            onClick: settingsLinkHandler(onNavigate, s),
+            children: [
+              s.title,
+              s.glyph ?? null,
+              /* @__PURE__ */ jsx2("span", { className: "band-sf-chev", "aria-hidden": "true", children: "\u203A" })
+            ]
+          },
+          s.slug
+        ))
+      ] }, g.group))
+    ] }),
+    /* @__PURE__ */ jsx2("div", { className: "band-sf-scroll", children: /* @__PURE__ */ jsxs2("main", { className: "band-sf-main", "data-view": view, ref: mainRef, children: [
+      view === "page" && back ? /* @__PURE__ */ jsx2(SettingsBack, { target: back, onNavigate }) : null,
+      view === "page" && backMobile ? /* @__PURE__ */ jsx2(SettingsBack, { target: backMobile, onNavigate, mobileOnly: true }) : null,
+      children
+    ] }) })
+  ] });
+}
+function SettingsBack({
+  target,
+  onNavigate,
+  mobileOnly = false
+}) {
+  return /* @__PURE__ */ jsxs2(
+    "a",
+    {
+      className: mobileOnly ? "band-sf-back band-sf-back-m" : "band-sf-back",
+      href: target.href,
+      onClick: settingsLinkHandler(onNavigate, target),
+      children: [
+        /* @__PURE__ */ jsx2("span", { "aria-hidden": "true", children: "\u2039" }),
+        " ",
+        target.label
+      ]
+    }
+  );
+}
+function SettingsHead({
+  title,
+  desc,
+  action
+}) {
+  return /* @__PURE__ */ jsxs2("div", { className: "band-sf-h", children: [
+    /* @__PURE__ */ jsxs2("div", { children: [
+      /* @__PURE__ */ jsx2("h1", { children: title }),
+      desc ? /* @__PURE__ */ jsx2("p", { children: desc }) : null
+    ] }),
+    action ? /* @__PURE__ */ jsx2("div", { className: "band-sf-h-a", children: action }) : null
+  ] });
+}
+function SettingsRows({ label, children }) {
+  return /* @__PURE__ */ jsx2("ul", { className: "band-sf-rows", "aria-label": label, children });
+}
+var warnedExtra = false;
+function warnExtraWithOpen() {
+  const env = globalThis.process?.env?.NODE_ENV;
+  if (warnedExtra || env === void 0 || env === "production") return;
+  warnedExtra = true;
+  console.warn("SettingsRow\uFF1Aextra \u4E0E onOpen \u4E0D\u8981\u540C\u65F6\u7ED9\uFF0C\u6574\u884C\u94FE\u63A5\u4F1A\u76D6\u4F4F\u5C55\u5F00\u7684\u90A3\u4E00\u5757");
+}
+function SettingsRow({
+  title,
+  tags,
+  meta,
+  actions,
+  leading,
+  href,
+  onOpen,
+  mono = false,
+  isNew = false,
+  extra
+}) {
+  if (extra && onOpen) warnExtraWithOpen();
+  const name = /* @__PURE__ */ jsx2("b", { className: mono ? "band-sf-mono" : void 0, children: title });
+  const cls = ["band-sf-row", leading ? "has-lead" : "", isNew ? "is-new" : ""].filter(Boolean).join(" ");
+  return /* @__PURE__ */ jsxs2("li", { className: cls, children: [
+    leading ? /* @__PURE__ */ jsx2("div", { className: "band-sf-row-l", children: leading }) : null,
+    /* @__PURE__ */ jsxs2("div", { className: "band-sf-row-t", children: [
+      onOpen ? /* @__PURE__ */ jsx2(
+        "a",
+        {
+          className: "band-sf-row-link",
+          href: href ?? "#",
+          onClick: (e) => {
+            if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+            e.preventDefault();
+            onOpen();
+          },
+          children: name
+        }
+      ) : name,
+      tags
+    ] }),
+    /* @__PURE__ */ jsxs2("div", { className: "band-sf-row-a", children: [
+      actions,
+      onOpen ? /* @__PURE__ */ jsx2("span", { className: "band-sf-chev", "aria-hidden": "true", children: "\u203A" }) : null
+    ] }),
+    meta && meta.length > 0 ? /* @__PURE__ */ jsx2("div", { className: "band-sf-row-m", children: meta.map((m, i) => (
+      // biome-ignore lint/suspicious/noArrayIndexKey: 元信息是一串短句，没有稳定 id
+      /* @__PURE__ */ jsx2("span", { children: m }, i)
+    )) }) : null,
+    extra ? /* @__PURE__ */ jsx2("div", { className: "band-sf-row-x", children: extra }) : null
+  ] });
+}
+function SettingsFacts({ items }) {
+  return /* @__PURE__ */ jsx2("dl", { className: "band-sf-facts", children: items.map((f) => /* @__PURE__ */ jsxs2("div", { className: "band-sf-fact", children: [
+    /* @__PURE__ */ jsx2("dt", { children: f.key }),
+    /* @__PURE__ */ jsx2("dd", { children: f.value })
+  ] }, f.key)) });
+}
+function SettingsSection({
+  title,
+  desc,
+  children
+}) {
+  return /* @__PURE__ */ jsxs2("section", { className: "band-sf-sec", "aria-label": title, children: [
+    /* @__PURE__ */ jsx2("h2", { children: title }),
+    desc ? /* @__PURE__ */ jsx2("p", { children: desc }) : null,
+    children
+  ] });
+}
+function SettingsSingle({ label, children }) {
+  return /* @__PURE__ */ jsx2("section", { className: "band-sf-one", "aria-label": label, children });
+}
+function SettingsChoices({ children }) {
+  return /* @__PURE__ */ jsx2("div", { className: "band-sf-choices", children });
+}
+function SettingsDanger({ children }) {
+  return /* @__PURE__ */ jsxs2("section", { className: "band-sf-dz", "aria-label": "\u5371\u9669\u64CD\u4F5C", children: [
+    /* @__PURE__ */ jsx2("h2", { children: "\u5371\u9669\u64CD\u4F5C" }),
+    children
+  ] });
+}
+function SettingsDangerRow({
+  title,
+  note,
+  action
+}) {
+  return /* @__PURE__ */ jsxs2("div", { className: "band-sf-dz-r", children: [
+    /* @__PURE__ */ jsxs2("div", { children: [
+      /* @__PURE__ */ jsx2("b", { children: title }),
+      /* @__PURE__ */ jsx2("span", { children: note })
+    ] }),
+    action
+  ] });
+}
+function SettingsLoading({ text }) {
+  return /* @__PURE__ */ jsx2("output", { className: "band-sf-load", children: /* @__PURE__ */ jsxs2("span", { className: "tuning", children: [
+    /* @__PURE__ */ jsxs2("svg", { viewBox: "0 0 80 55", "aria-hidden": "true", children: [
+      /* @__PURE__ */ jsx2("line", { x1: "0", y1: "12", x2: "80", y2: "12" }),
+      /* @__PURE__ */ jsx2("line", { x1: "0", y1: "22", x2: "80", y2: "22" }),
+      /* @__PURE__ */ jsx2("line", { x1: "0", y1: "32", x2: "80", y2: "32" }),
+      /* @__PURE__ */ jsx2("line", { x1: "0", y1: "42", x2: "80", y2: "42" }),
+      /* @__PURE__ */ jsx2("line", { x1: "0", y1: "52", x2: "80", y2: "52" }),
+      /* @__PURE__ */ jsx2("circle", { cx: "20", cy: "37", r: "4.6", fill: "var(--ink)" }),
+      /* @__PURE__ */ jsx2("circle", { cx: "40", cy: "27", r: "4.6", fill: "var(--accent)" }),
+      /* @__PURE__ */ jsx2("circle", { cx: "60", cy: "17", r: "4.6", fill: "var(--ink)" })
+    ] }),
+    /* @__PURE__ */ jsx2("span", { children: text })
+  ] }) });
+}
+function SettingsEmpty({ children, action }) {
+  return /* @__PURE__ */ jsxs2("div", { className: "band-sf-empty rest", children: [
+    /* @__PURE__ */ jsx2("i", {}),
+    /* @__PURE__ */ jsx2("p", { children }),
+    action ?? null
+  ] });
+}
+function SettingsReadError({ children, retry }) {
+  return /* @__PURE__ */ jsx2("div", { className: "band-sf-error", children: /* @__PURE__ */ jsx2(ErrorNote, { retry, children }) });
+}
+function SettingsNoAccess({
+  title,
+  children,
+  action
+}) {
+  const id = useId();
+  return /* @__PURE__ */ jsxs2("section", { className: "band-settings-no-access", "aria-labelledby": id, children: [
+    /* @__PURE__ */ jsx2("h2", { id, children: title }),
+    /* @__PURE__ */ jsx2("p", { children }),
+    action ? /* @__PURE__ */ jsx2("button", { type: "button", className: "btn", onClick: action.onClick, children: action.label }) : null
+  ] });
+}
+function SettingsNotice({ text }) {
+  return /* @__PURE__ */ jsx2("output", { className: "sr-only", "aria-live": "polite", children: text });
+}
+function SettingsSaved({ text = "\u5DF2\u4FDD\u5B58" }) {
+  return /* @__PURE__ */ jsx2("output", { className: "band-sf-ok", children: text });
+}
+function SettingsDialog({
+  title,
+  children,
+  actions,
+  onClose
+}) {
+  const ref = useRef(null);
+  const titleId = useId();
+  useEffect(() => {
+    const el = ref.current;
+    const opener = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+    if (el && !el.open) {
+      if (typeof el.showModal === "function") el.showModal();
+      else el.setAttribute("open", "");
+    }
+    return () => {
+      if (opener?.isConnected) opener.focus();
+    };
+  }, []);
+  return /* @__PURE__ */ jsxs2(
+    "dialog",
+    {
+      ref,
+      className: "band-sf-dialog",
+      "aria-labelledby": titleId,
+      onCancel: (e) => {
+        e.preventDefault();
+        onClose();
+      },
+      children: [
+        /* @__PURE__ */ jsx2("h2", { id: titleId, children: title }),
+        children,
+        /* @__PURE__ */ jsx2("div", { className: "band-sf-acts band-sf-acts-end", children: actions })
+      ]
+    }
+  );
+}
+function SettingsForm({
+  label,
+  onSubmit,
+  children
+}) {
+  return /* @__PURE__ */ jsx2(
+    "form",
+    {
+      className: "band-sf-form",
+      "aria-label": label,
+      onSubmit: (e) => {
+        e.preventDefault();
+        onSubmit?.();
+      },
+      children
+    }
+  );
+}
+function SettingsField({
+  label,
+  required = false,
+  optional = false,
+  hint,
+  error,
+  count,
+  over = false,
+  children
+}) {
+  const id = useId();
+  const noteId = `${id}-note`;
+  const note = error ?? hint;
+  const props = { id };
+  if (note) props["aria-describedby"] = `${noteId}-t`;
+  if (error) props["aria-invalid"] = true;
+  return /* @__PURE__ */ jsxs2("div", { className: "band-sf-fld", children: [
+    /* @__PURE__ */ jsxs2("label", { htmlFor: id, children: [
+      label,
+      required ? /* @__PURE__ */ jsxs2(Fragment, { children: [
+        " ",
+        /* @__PURE__ */ jsx2("span", { className: "band-sf-req", children: "\u5FC5\u586B" })
+      ] }) : optional ? /* @__PURE__ */ jsxs2(Fragment, { children: [
+        " ",
+        /* @__PURE__ */ jsx2("span", { className: "band-sf-optional", children: "\u9009\u586B" })
+      ] }) : null
+    ] }),
+    children(props),
+    note || count ? (
+      // 出错的话当场播报：校验被拦时焦点不动，读屏不会自己走到这一行
+      /* @__PURE__ */ jsxs2(
+        "p",
+        {
+          className: error ? "field-note err" : "field-note",
+          id: noteId,
+          role: error ? "alert" : void 0,
+          children: [
+            note ? /* @__PURE__ */ jsx2("span", { id: `${noteId}-t`, children: note }) : null,
+            count ? /* @__PURE__ */ jsx2("span", { className: over ? "field-count over" : "field-count", children: count }) : null
+          ]
+        }
+      )
+    ) : null
+  ] });
+}
+function SettingsActions({
+  children,
+  end = false
+}) {
+  return /* @__PURE__ */ jsx2("div", { className: end ? "band-sf-acts band-sf-acts-end" : "band-sf-acts", children });
+}
+function SettingsSaveState({
+  saving,
+  saved,
+  failed,
+  missing
+}) {
+  if (failed)
+    return /* @__PURE__ */ jsx2("p", { className: "band-sf-err", role: "alert", children: failed });
+  if (saved) return /* @__PURE__ */ jsx2(SettingsSaved, { text: saved === true ? "\u5DF2\u4FDD\u5B58" : saved });
+  const text = saving ?? missing;
+  if (!text) return /* @__PURE__ */ jsx2("span", { className: "band-sf-state", "aria-live": "polite" });
+  return /* @__PURE__ */ jsx2("span", { className: "band-sf-state", "aria-live": "polite", children: text });
+}
+
 export {
   ErrorNote,
   InfoNote,
@@ -350,5 +702,28 @@ export {
   WorkshopIcon,
   WorkshopEmblem,
   BandMark,
-  LogoLockup
+  LogoLockup,
+  settingsLinkHandler,
+  SettingsLayout,
+  SettingsBack,
+  SettingsHead,
+  SettingsRows,
+  SettingsRow,
+  SettingsFacts,
+  SettingsSection,
+  SettingsSingle,
+  SettingsChoices,
+  SettingsDanger,
+  SettingsDangerRow,
+  SettingsLoading,
+  SettingsEmpty,
+  SettingsReadError,
+  SettingsNoAccess,
+  SettingsNotice,
+  SettingsSaved,
+  SettingsDialog,
+  SettingsForm,
+  SettingsField,
+  SettingsActions,
+  SettingsSaveState
 };

package/dist/components.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { ReactNode } from 'react';
+import { ReactNode, Ref, MouseEvent } from 'react';
 import { MemberView } from '@kanyun-ai-infra/band-plugin-sdk';
 
 /**
@@ -96,4 +96,218 @@ declare function BandMark({ size, className }: {
 /** Band 字标（五线谱 + 三个音符 + 「Band」，DESIGN.md「标志」）。样式在 Band Design 的 `.logo`。 */
 declare function LogoLockup(): react.JSX.Element;
 
-export { AgentAvatar, Avatar, BandMark, ErrorNote, Glyph, type GlyphKind, INSTRUMENTS, InfoNote, type Instrument, LogoLockup, PaneHeader, WorkshopEmblem, WorkshopIcon, agentInstrument, avatarInitial, avatarTone, instrumentOf, memberOrder };
+/** 一次页内跳转的目标：页键与地址参数，由调用方交给宿主。 */
+interface SettingsTarget {
+    page: string;
+    params?: Record<string, string>;
+}
+/** 导航里的一项（分区导航的链接）。 */
+interface SettingsNavItem extends SettingsTarget {
+    slug: string;
+    title: string;
+    href: string;
+    /** 右侧 16px 状态符号（同侧栏），可选。 */
+    glyph?: ReactNode;
+}
+interface SettingsGroup {
+    group: string;
+    sections: readonly SettingsNavItem[];
+}
+/** 页头上方那行返回（`‹ 设置`、`‹ 列表名`）。 */
+interface SettingsBackTarget extends SettingsTarget {
+    label: string;
+    href: string;
+}
+type Navigate = (target: SettingsTarget) => void;
+/** 只在主键上点（没按修饰键）时走页内跳转；其余交给浏览器（新标签页）。 */
+declare function settingsLinkHandler(go: Navigate | undefined, target: SettingsTarget): (e: MouseEvent<HTMLAnchorElement>) => void;
+/**
+ * 四个作用域共用的骨架（稿 §3.1、§3.7）：左边分区导航、右边内容。作用域只决定导航头与分区名单；
+ * 摆法与手机宽度（600px）下的两页切换不变。导航是链接列表（`aria-current="page"`），不是 tablist。
+ */
+declare function SettingsLayout({ navLabel, title, obj, crumb, groups, current, view, back, backMobile, onNavigate, mainRef, children, }: {
+    /** 分区导航的 aria-label（「设置分区」「项目设置分区」）。 */
+    navLabel: string;
+    title: string;
+    /** 导航头第二行（「只有你看得到这里」）。 */
+    obj?: ReactNode;
+    /** 导航头上方的面包屑；项目、工坊作用域的对象头沿用页面顶栏，一般不传。 */
+    crumb?: ReactNode;
+    groups: readonly SettingsGroup[];
+    /** 当前分区的 slug；目录页不传。 */
+    current?: string | undefined;
+    view?: "page" | "index";
+    /** 详情 / 新增页头上的「‹ 列表名」：宽窄都画（稿 §3.2）。 */
+    back?: SettingsBackTarget | undefined;
+    /** 分区页给手机宽度的「‹ 设置」：只在窄屏画（稿 §3.7）。 */
+    backMobile?: SettingsBackTarget | undefined;
+    /** 页内跳转；不给就按普通链接走。 */
+    onNavigate?: Navigate;
+    /** 内容区的 ref（接线层在上面装未保存离开的守卫）。 */
+    mainRef?: Ref<HTMLElement>;
+    children: ReactNode;
+}): react.JSX.Element;
+/** 「‹ 列表名」：详情、新增页头上方；`mobileOnly` 是只在手机宽度画的「‹ 设置」。 */
+declare function SettingsBack({ target, onNavigate, mobileOnly, }: {
+    target: SettingsBackTarget;
+    onNavigate?: Navigate | undefined;
+    mobileOnly?: boolean;
+}): react.JSX.Element;
+/** 页头：标题（分区名）+ 一句说明这里管什么、谁看得到 + 主操作（靠右，一页最多一个）。 */
+declare function SettingsHead({ title, desc, action, }: {
+    title: ReactNode;
+    desc?: ReactNode;
+    action?: ReactNode;
+}): react.JSX.Element;
+/** 列表：行不画框不画线，悬停垫浅底；整行进详情。 */
+declare function SettingsRows({ label, children }: {
+    label: string;
+    children: ReactNode;
+}): react.JSX.Element;
+/**
+ * 一行：（可选的头像 / 图标位）名称 + 标记 / 一行元信息 / 右端最多一个快捷操作 + 进详情的箭头。
+ * 给了 `onOpen` 时整行可点。
+ */
+declare function SettingsRow({ title, tags, meta, actions, leading, href, onOpen, mono, isNew, extra, }: {
+    title: ReactNode;
+    tags?: ReactNode;
+    meta?: readonly ReactNode[];
+    actions?: ReactNode;
+    /** 名称左边的头像或图标（成员行用 `Avatar`），占两行高。 */
+    leading?: ReactNode;
+    href?: string;
+    onOpen?: () => void;
+    mono?: boolean;
+    /** 刚保存的那一行垫 `--ok-soft`（回列表时标出来）。 */
+    isNew?: boolean;
+    /** 行内展开的一块，占满整行宽。画它时别给 `onOpen`：整行链接会盖住它。 */
+    extra?: ReactNode;
+}): react.JSX.Element;
+interface SettingsFact {
+    key: string;
+    value: ReactNode;
+}
+/** 详情概况：定义列表，不画框。 */
+declare function SettingsFacts({ items }: {
+    items: readonly SettingsFact[];
+}): react.JSX.Element;
+/** 一节：`h2` + 可选的一句说明 + 内容；节与节之间留白，不画线、不套卡（稿 §3.1）。 */
+declare function SettingsSection({ title, desc, children, }: {
+    title: string;
+    desc?: ReactNode;
+    children: ReactNode;
+}): react.JSX.Element;
+/**
+ * 只有一份设置的分区（提醒、批准）：不分节、不画 h2（稿 §3.2），控件、说明与反馈竖排。
+ * 名字给 `aria-label`；里面要成组的控件自己放 `fieldset`（组件抹掉它的默认框）。
+ */
+declare function SettingsSingle({ label, children }: {
+    label: string;
+    children: ReactNode;
+}): react.JSX.Element;
+/** 一排勾选（`.choice`）：自动折行。 */
+declare function SettingsChoices({ children }: {
+    children: ReactNode;
+}): react.JSX.Element;
+/** 危险操作区：只在详情页最下面，每项一行（动作 + 后果一句 + 按钮），按钮是 `.btn.danger`（稿 §3.6）。 */
+declare function SettingsDanger({ children }: {
+    children: ReactNode;
+}): react.JSX.Element;
+declare function SettingsDangerRow({ title, note, action, }: {
+    title: ReactNode;
+    note: ReactNode;
+    action: ReactNode;
+}): react.JSX.Element;
+/** 加载：页头照常画，内容区用 Band Design 的 `.tuning`（五线谱）配「正在读取<什么>…」；不画骨架条（稿 §3.3）。 */
+declare function SettingsLoading({ text }: {
+    text: string;
+}): react.JSX.Element;
+/** 空：休止符插画 + 一句「还没有什么、有了能做什么」+ 主操作（没有新增权限时不画按钮）。 */
+declare function SettingsEmpty({ children, action }: {
+    children: ReactNode;
+    action?: ReactNode;
+}): react.JSX.Element;
+/** 读失败：一行 `ErrorNote`（「<什么>没读出来：<原因>」+「重试」）。 */
+declare function SettingsReadError({ children, retry }: {
+    children: ReactNode;
+    retry: () => void;
+}): react.JSX.Element;
+/**
+ * 没有权限（读 403）与环境没开通：标题、谁能看 / 缺什么、去找谁，一个离开的按钮（可不给）；不画重试（稿 §3.3）。
+ */
+declare function SettingsNoAccess({ title, children, action, }: {
+    title: string;
+    children: ReactNode;
+    action?: {
+        label: string;
+        onClick: () => void;
+    } | undefined;
+}): react.JSX.Element;
+/** 保存后的读屏播报（「已保存」「已删除」，不抢眼、不占版面）。 */
+declare function SettingsNotice({ text }: {
+    text: string;
+}): react.JSX.Element;
+/** 「已保存」那一句（控件旁或按钮旁，停四拍由调用方的 `useSavedNote` 管）。 */
+declare function SettingsSaved({ text }: {
+    text?: ReactNode;
+}): react.JSX.Element;
+/**
+ * 确认弹窗（稿 §3.6）：`--scrim`、`--shadow-pop`、`--r-xl`；标题问动作，正文列后果，末尾写能不能恢复。
+ * 不用输入名字确认：弹窗已列后果，多打一遍字不增加信息。
+ */
+declare function SettingsDialog({ title, children, actions, onClose, }: {
+    title: string;
+    children: ReactNode;
+    actions: ReactNode;
+    onClose: () => void;
+}): react.JSX.Element;
+/** 设置里的表单：字段竖排，最宽 560。提交走 `onSubmit`（已 `preventDefault`）。 */
+declare function SettingsForm({ label, onSubmit, children, }: {
+    label?: string;
+    onSubmit?: () => void;
+    children: ReactNode;
+}): react.JSX.Element;
+/** 字段的输入要挂的属性：id、读屏说明、出错标记。 */
+interface SettingsFieldProps {
+    id: string;
+    "aria-describedby"?: string;
+    "aria-invalid"?: true;
+}
+/**
+ * 字段行：标签（必填写「必填」）、输入、下一行的提示或出错、计数。提示 / 出错 / 计数用 Band Design 的
+ * `.field-note`（出错加 `.err`）与 `.field-count`（DESIGN.md「控件」），出错时输入挂 `aria-invalid`。
+ * 输入本身由调用方用 Band Design 的 `.field` 画，组件只摆位置、接好 id 与读屏说明。
+ */
+declare function SettingsField({ label, required, optional, hint, error, count, over, children, }: {
+    label: ReactNode;
+    required?: boolean;
+    /** 选填：标签旁写「选填」（稿 §3.5 的样张两种都标）；与 `required` 不同时给。 */
+    optional?: boolean;
+    hint?: ReactNode;
+    /** 出错的话；有它时不画提示。 */
+    error?: ReactNode;
+    /** 计数（「12 / 200」），靠右。 */
+    count?: ReactNode;
+    /** 计数超了：计数变红。 */
+    over?: boolean;
+    children: (props: SettingsFieldProps) => ReactNode;
+}): react.JSX.Element;
+/** 表单末尾的操作行：按钮 + 保存反馈 / 还缺什么。 */
+declare function SettingsActions({ children, end, }: {
+    children: ReactNode;
+    end?: boolean;
+}): react.JSX.Element;
+/**
+ * 保存反馈（稿 §3.5）：`saving` 时写在做什么（「正在验证…」那一档的旁注），`saved` 停四拍的「已保存」，
+ * `failed` 是贴在按钮旁的整体错误（「没保存：」开头），`missing` 是按钮置灰时缺什么（「还差 key 没填」）。
+ * 不用吐司；读屏走 `aria-live`。
+ */
+declare function SettingsSaveState({ saving, saved, failed, missing, }: {
+    saving?: ReactNode;
+    /** `true` 写「已保存」；给文字或节点就照它写（「已保存，ModelGate 验证通过」）。 */
+    saved?: ReactNode;
+    failed?: ReactNode;
+    missing?: ReactNode;
+}): react.JSX.Element;
+
+export { AgentAvatar, Avatar, BandMark, ErrorNote, Glyph, type GlyphKind, INSTRUMENTS, InfoNote, type Instrument, LogoLockup, PaneHeader, SettingsActions, SettingsBack, type SettingsBackTarget, SettingsChoices, SettingsDanger, SettingsDangerRow, SettingsDialog, SettingsEmpty, type SettingsFact, SettingsFacts, SettingsField, type SettingsFieldProps, SettingsForm, type SettingsGroup, SettingsHead, SettingsLayout, SettingsLoading, type SettingsNavItem, SettingsNoAccess, SettingsNotice, SettingsReadError, SettingsRow, SettingsRows, SettingsSaveState, SettingsSaved, SettingsSection, SettingsSingle, type SettingsTarget, WorkshopEmblem, WorkshopIcon, agentInstrument, avatarInitial, avatarTone, instrumentOf, memberOrder, settingsLinkHandler };