@westonkd/sprint 0.7.0 → 0.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/agent-manifest.json +1390 -82
- package/dist/index.cjs +283 -76
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.ts +1369 -42
- package/dist/index.js +5298 -2544
- package/dist/index.js.map +1 -1
- package/dist/sprint.css +1 -1
- package/package.json +1 -1
package/dist/index.cjs
CHANGED
|
@@ -1,26 +1,29 @@
|
|
|
1
|
-
"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const a=require("react/jsx-runtime"),
|
|
2
|
-
… truncated`;function
|
|
3
|
-
`);return`${
|
|
4
|
-
`),o=[];let
|
|
5
|
-
${
|
|
6
|
-
`))o.push(`${
|
|
7
|
-
`)}const
|
|
8
|
-
`)}function
|
|
1
|
+
"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const a=require("react/jsx-runtime"),i=require("react"),Ao=require("react-dom"),Me="data-sprint",Ve="data-sprint-part",st="data-sprint-",tt="data-sprint-tool",cn="data-sprint-owner",hn="data-sprint-agent",Qn="data-sprint-view",Xn="data-sprint-view-copy",Yn="data-sprint-theme",Ct="data-sprint-region",Nt="data-sprint-tooltip",Zn=["part","tool","owner","agent","view","view-copy","theme","region","ornament","tooltip"];function un(e,t={}){const n={[Me]:e};t.part&&(n[Ve]=t.part);for(const[o,s]of Object.entries(t.state??{}))s==null||s===!1||(n[`${st}${o}`]=s===!0?"":String(s));return n}function jo(e,t){const n=`[${Me}="${e}"]`;return t?`${n} [${Ve}="${t}"]`:n}const Lt=`
|
|
2
|
+
… truncated`;function kt(e,t){if(e.length<=t)return e;if(t<=Lt.length)return e.slice(0,t);const n=t-Lt.length,o=e.slice(0,n),s=o.lastIndexOf(`
|
|
3
|
+
`);return`${s>n/2?o.slice(0,s):o.trimEnd()}${Lt}`}function pn(e,t){if(t<=0)return[e];const n=e.split(`
|
|
4
|
+
`),o=[];let s="";for(const r of n){const l=s===""?r:`${s}
|
|
5
|
+
${r}`;if(l.length<=t){s=l;continue}if(s!==""&&o.push(s),s=r.length<=t?r:"",r.length>t)for(let d=0;d<r.length;d+=t)o.push(r.slice(d,d+t))}return s!==""&&o.push(s),o.length===0?[""]:o}const Fe=1500,It=500,$t=150;function gn(){return typeof document>"u"?null:document.modelContext??null}function Ro(){return gn()!==null}function Lo(e){if(e.description.length>It)throw new Error(`Tool "${e.name}" description is ${e.description.length} characters; the platform limit is ${It}.`);for(const[t,n]of Object.entries(e.inputSchema.properties)){const o=n.description??"";if(o.length>$t)throw new Error(`Tool "${e.name}" parameter "${t}" description is ${o.length} characters; the platform limit is ${$t}.`)}}function Jn(e,t){for(const n of e.required??[])if(t[n]===void 0){const o=Object.keys(e.properties).join(", ");return`Missing required parameter "${n}". Expected parameters: ${o||"none"}.`}for(const[n,o]of Object.entries(t)){if(o===void 0)continue;const s=e.properties[n];if(s===void 0){const c=Object.keys(e.properties).join(", ");return`Unknown parameter "${n}". Expected parameters: ${c||"none"}.`}const r=typeof o,l=s.type==="number"||s.type==="integer";if(!(s.type==="string"&&r==="string"||l&&r==="number"||s.type==="boolean"&&r==="boolean"))return`Parameter "${n}" must be a ${s.type}, received ${r}.`;if(s.enum!==void 0&&!s.enum.includes(String(o)))return`Parameter "${n}" must be one of: ${s.enum.join(", ")}.`;if(typeof o=="number"){if(s.type==="integer"&&!Number.isInteger(o))return`Parameter "${n}" must be a whole number, received ${o}.`;if(s.minimum!==void 0&&o<s.minimum)return`Parameter "${n}" must be at least ${s.minimum}, received ${o}.`;if(s.maximum!==void 0&&o>s.maximum)return`Parameter "${n}" must be at most ${s.maximum}, received ${o}.`}}return null}function Po(e){return{...e,execute:async(n,o)=>{const s=Jn(e.inputSchema,n??{});if(s!==null)return s;try{const r=await e.execute(n??{},o);return r===null?null:kt(r,Fe)}catch(r){const l=r instanceof Error?r.message:String(r);return kt(`Tool "${e.name}" failed: ${l}`,Fe)}}}}function ea(e,t){Lo(e);const n=gn();if(n===null||t.aborted)return!1;const o=n.registerTool(Po(e),{signal:t});return o instanceof Promise&&o.catch(s=>{console.warn(`Sprint could not register tool "${e.name}"`,s)}),!0}const ta="<scope>-<verb>-<label-slug>",xt=new Map;function Y(e){const t=xt.get(e.name);return t!==void 0&&t!==e&&console.warn(`Agent metadata for "${e.name}" was replaced. Two components sharing a name will collapse into one manifest entry.`),xt.set(e.name,e),e}function na(e){return xt.get(e)}function aa(){return[...xt.values()].sort((e,t)=>e.name.localeCompare(t.name))}function Oo(e){return{library:"sprint",version:e,conventions:{componentAttribute:Me,partAttribute:Ve,stateAttributePrefix:st,toolAttribute:tt,ownerAttribute:cn,regionAttribute:Ct,agentViewFormat:"markdown",toolNaming:ta,toolOutputLimit:Fe},components:aa()}}function Eo(e){return e.label===void 0&&e.parts.length===0&&e.children.length===0}function oa(e){let t=0;for(const n of e)t+=1+oa(n.children);return t}function ia(e){const t=Object.keys(e).sort();return t.length===0?"":` [${t.map(o=>{const s=e[o];return s===!0?o:`${o}=${s}`}).join(", ")}]`}function sa(e){return e===void 0?"":` "${e}"`}function ra(e){return e===void 0?"":` → tool \`${e}\``}function Do(e,t){return`${t}- part \`${e.part}\`${sa(e.label)}${ia(e.state)}${ra(e.tool)}`}function la(e){const t=Eo(e)?" (empty)":"",n=e.owner===void 0?"":` (owned by \`${e.owner}\`)`;return`- **${e.component}**${sa(e.label)}${ia(e.state)}${ra(e.tool)}${n}${t}`}function da(e,t,n){const o=[`${t}${la(e)}`],s=`${t} `;if(n.includeSummary&&e.summary!==void 0)for(const r of e.summary.split(`
|
|
6
|
+
`))o.push(`${s}${r}`);for(const r of e.parts)o.push(Do(r,s));for(const r of e.children)o.push(...da(r,s,n));return e.truncated&&o.push(`${s}- … nested components omitted, depth limit reached`),o}function ca(e,t={}){const n=Array.isArray(e)?e:[e],o={includeSummary:t.includeSummary??!0};return n.length===0?"No Sprint components found.":n.flatMap(s=>da(s,"",o)).join(`
|
|
7
|
+
`)}const mn=e=>ca(e),ct=i.createContext({view:"human",setView:()=>{},controls:"always",format:mn,owned:!1}),Mo=ct.Provider;function Z(){return i.useContext(ct).view}function ha(){return i.useContext(ct)}function ue(){return i.useContext(ct).controls}function ce(){return i.useContext(ct).format}const ua=i.createContext(0),St=ua.Provider;function At(){return i.useContext(ua)}function q(e){const t={};for(const[n,o]of Object.entries(e.state??{}))o===!1||o===null||o===void 0||(t[n]=o);return{component:e.component,state:t,parts:e.parts??[],children:[],...e.label===void 0?{}:{label:e.label},...e.summary===void 0?{}:{summary:e.summary},...e.tool===void 0?{}:{tool:e.tool},...e.owner===void 0?{}:{owner:e.owner},...e.region===!0?{region:!0}:{}}}function X(e){return un(e.component,{state:{...e.state,tool:e.tool,owner:e.owner,region:e.region}})}function pa(e){const t={[hn]:e.component};return e.tool!==void 0&&(t[tt]=e.tool),t}function ga(e,t){const n={[hn]:e,[Ve]:t.part};return t.tool!==void 0&&(n[tt]=t.tool),n}function B(e){const{[Me]:t,...n}=un("",{part:e.part,state:{...e.state,tool:e.tool}});return n}function jt(e,t){return t([e]).split(`
|
|
8
|
+
`)}function te(e){const{node:t,children:n,silent:o=!1}=e,s=At(),r=ce(),l=" ".repeat(s),d=jt(t,r).map(c=>`${l}${c}`);return a.jsxs(St,{value:o?s:s+1,children:[o?null:`${d.join(`
|
|
9
9
|
`)}
|
|
10
|
-
`,n]})}function
|
|
10
|
+
`,n]})}function ke(e){const{node:t,onActivate:n,isActionable:o,children:s}=e,r=At(),l=ce(),d=" ".repeat(r),c=jt(t,l),h=c.length-t.parts.length,g=c.slice(0,h).map(u=>`${d}${u}`);return a.jsxs(St,{value:r+1,children:[`${g.join(`
|
|
11
11
|
`)}
|
|
12
|
-
`,t.parts.map((
|
|
13
|
-
`},
|
|
14
|
-
`]},
|
|
12
|
+
`,t.parts.map((u,b)=>{const m=c[h+b]??"",S=m.trimStart(),f=`${d}${m.slice(0,m.length-S.length)}`,y=`${u.part}-${u.label??b}`;return o!==void 0&&!o(u,b)?a.jsx(i.Fragment,{children:`${f}${S}
|
|
13
|
+
`},y):a.jsxs(i.Fragment,{children:[f,a.jsx("button",{type:"button",...ga(t.component,u),onClick:()=>n(u,b),children:S}),`
|
|
14
|
+
`]},y)}),s]})}function fn(e){const{node:t,value:n,onValueChange:o,multiline:s=!1,masked:r=!1,ref:l}=e,d=At(),c=ce(),h=" ".repeat(d),g=jt(t,c).map(m=>`${h}${m}`),u=pa(t),b=s?a.jsx("textarea",{...u,"aria-label":t.label,value:n,onChange:m=>o(m.currentTarget.value),ref:l}):a.jsx("input",{...u,"aria-label":t.label,type:r?"password":"text",value:n,onChange:m=>o(m.currentTarget.value),ref:l});return a.jsxs(St,{value:d+1,children:[`${g.join(`
|
|
15
15
|
`)}
|
|
16
16
|
`,h,b,`
|
|
17
|
-
`]})}function
|
|
17
|
+
`]})}function ze(e){const{node:t,as:n="button",href:o,children:s,ref:r,...l}=e,d=At(),c=ce(),h=" ".repeat(d),[g="",...u]=jt(t,c),b=u.map(f=>`${h}${f}`),m=pa(t),S=n==="a"?a.jsx("a",{...l,...m,href:o??"#",ref:r,children:g}):a.jsx("button",{...l,...m,ref:r,children:g});return a.jsxs(St,{value:d+1,children:[h,S,b.length===0?`
|
|
18
18
|
`:`
|
|
19
19
|
${b.join(`
|
|
20
20
|
`)}
|
|
21
|
-
`,
|
|
22
|
-
`);return{...e,parts:[],summary:i}}function ze(e){return e.replace(/\s+/g," ").trim()}function ft(e,t){if(e==null||typeof e=="boolean")return;if(typeof e=="string"||typeof e=="number"){t.push(String(e));return}if(Array.isArray(e)){for(const o of e)ft(o,t);return}if(!r.isValidElement(e))return;const n=e.props;if(!(n["aria-hidden"]===!0||n["aria-hidden"]==="true")){if(typeof n["aria-label"]=="string"){t.push(n["aria-label"]);return}ft(n.children,t)}}function se(e){const t=[];ft(e,t);const n=ze(t.join(""));return n===""?void 0:n}function no(e){return e.getAttribute("aria-hidden")==="true"||e.hasAttribute("hidden")}function $n(e,t,n){if(e.nodeType===Node.TEXT_NODE){t.push(e.nodeValue??"");return}if(e.nodeType!==Node.ELEMENT_NODE)return;const o=e;if(no(o)||n>0&&o.hasAttribute(fe))return;const i=o.getAttribute("aria-label");if(n>0&&i!==null){t.push(i);return}for(const s of Array.from(o.childNodes))$n(s,t,n+1)}function _e(e){const t=e.getAttribute("aria-label");if(t!==null){const s=ze(t);return s===""?void 0:s}const n=e.getAttribute("aria-labelledby");if(n!==null){const s=e.ownerDocument,d=n.split(/\s+/).filter(l=>l!=="").map(l=>s.getElementById(l)).filter(l=>l!==null).map(l=>_e(l)??"").filter(l=>l!=="");if(d.length>0)return ze(d.join(" "))}const o=[];$n(e,o,0);const i=ze(o.join(""));return i===""?void 0:i}const ao=new Set(bn),oo=new Map([["disabled","disabled"],["open","open"],["readonly","readonly"],["required","required"]]),io=new Map([["aria-disabled","disabled"],["aria-busy","loading"],["aria-expanded","expanded"],["aria-checked","checked"],["aria-selected","selected"],["aria-pressed","pressed"],["aria-invalid","invalid"]]);function Mn(e){const t={};for(const[n,o]of io){const i=e.getAttribute(n);i===null||i==="false"||(t[o]=i==="true"||i===""?!0:i)}for(const[n,o]of oo)e.hasAttribute(n)&&(t[o]=!0);for(const n of Array.from(e.attributes)){if(!n.name.startsWith(Ie))continue;const o=n.name.slice(Ie.length);o===""||ao.has(o)||(t[o]=n.value===""?!0:n.value)}return t}function ro(e){const t=[],n=[],o=i=>{for(const s of Array.from(i.children)){if(s.hasAttribute(fe)){n.push(s);continue}s.hasAttribute(Ce)&&t.push(s),o(s)}};return o(e),{parts:t,children:n}}function so(e){const t=e.getAttribute(Ce)??"",n=_e(e),o=e.getAttribute(Ne);return{part:t,state:Mn(e),...n===void 0?{}:{label:n},...o===null||o===""?{}:{tool:o}}}function nt(e,t={}){const n=e.getAttribute(fe);if(n===null)return null;const o=t.maxDepth??8,i=t.lookupMeta??kn,{parts:s,children:d}=ro(e),l=_e(e),c=i(n)?.summary,h=e.getAttribute(Ne),m=e.getAttribute($t),p=o<=0&&d.length>0;return Dn({component:n,state:Mn(e),parts:s.map(so),children:p?[]:d.map(b=>nt(b,{...t,maxDepth:o-1})).filter(b=>b!==null),...c===void 0?{}:{summary:c},...l===void 0?{}:{label:l},...h===null||h===""?{}:{tool:h},...m===null||m===""?{}:{owner:m},...e.hasAttribute(Je)?{region:!0}:{},...p?{truncated:!0}:{}})}function In(e){const t=[],n=o=>{for(const i of Array.from(o.children)){if(i.hasAttribute(fe)){t.push(i);continue}n(i)}};return n(e),t}function lo(e){const t=e.filter(s=>s.owner!==void 0);if(t.length===0)return e;const n=new Map,o=s=>{s.tool&&n.set(s.tool,s);for(const d of s.parts)d.tool&&n.set(d.tool,s);for(const d of s.children)o(d)};for(const s of e)o(s);const i=new Set;for(const s of t){const d=s.owner===void 0?void 0:n.get(s.owner);d===void 0||d===s||(d.children.push(s),i.add(s))}return e.filter(s=>!i.has(s))}function Un(e,t={}){const n=In(e).map(o=>nt(o,t)).filter(o=>o!==null);return lo(n)}function oe(){return new Promise(e=>{if(typeof requestAnimationFrame!="function"){setTimeout(e,0);return}requestAnimationFrame(()=>{requestAnimationFrame(()=>e())})})}const ct=48;function xe(e){return e.normalize("NFKD").replace(/[̀-ͯ]/g,"").toLowerCase().replace(/[^a-z0-9]+/g,"-").replace(/^-+|-+$/g,"")}function bt(e,t,n){const o=xe(n);if(o==="")return null;const i=[xe(t),o].filter(h=>h!=="").join("-"),s=e.map(xe).filter(h=>h!=="");for(;s.length>0&&[...s,i].join("-").length>ct;)s.shift();const d=[...s,i].join("-");if(d.length<=ct)return d;const l=d.slice(0,ct),c=l.lastIndexOf("-");return c>0?l.slice(0,c):l}const Ue=new Map;function co(e){const t=Ue.get(e);if(t!==void 0)return t;const n={holders:new Set,listeners:new Map};return Ue.set(e,n),n}function ho(e,t,n){const o=co(e);o.holders.add(t),o.listeners.set(t,n);for(const[i,s]of o.listeners)i!==t&&s();return()=>{if(o.holders.delete(t),o.listeners.delete(t),o.holders.size===0){Ue.delete(e);return}for(const i of o.listeners.values())i()}}function sn(e,t){const n=Ue.get(e);return n===void 0?!1:n.holders.size===1&&n.holders.has(t)}function uo(e){return Ue.get(e)?.holders.size??0}const qn=r.createContext({path:[]}),qe=qn.Provider;function Be(){return r.useContext(qn).path}function te(e){const{spec:t,label:n,nameOverride:o,inputSchema:i,enabled:s=!0,execute:d}=e,l=Be(),c=`${t.verb}|${i===void 0?"":JSON.stringify(i)}`,h=r.useRef({key:c,value:i??t.inputSchema});h.current.key!==c&&(h.current={key:c,value:i??t.inputSchema});const m=h.current.value,p=r.useRef(null);p.current===null&&(p.current=Symbol("sprint-tool"));const b=r.useRef(d);r.useEffect(()=>{b.current=d});const g=o===void 0?n===void 0?null:bt(l,t.verb,n):bt(l,t.verb,o),[C,f]=r.useState(!1);return r.useEffect(()=>{const w=p.current;if(g===null||!s||w===null){f(!1);return}const v=ho(g,w,()=>{f(sn(g,w))});return uo(g)>1&&console.warn(`Sprint tool name "${g}" is claimed by more than one component. None of them will register a tool. Set agentName on all but one, or label them distinctly.`),f(sn(g,w)),()=>{v(),f(!1)}},[g,s]),r.useEffect(()=>{if(!C||g===null)return;const w=new AbortController;return vn({name:g,description:t.description,inputSchema:m,annotations:{readOnlyHint:t.readOnly,untrustedContentHint:t.untrustedContent},execute:(v,k)=>b.current(v,k)},w.signal),()=>{w.abort()}},[C,g,t,m]),C&&g!==null?g:void 0}function ie(e){Ga.flushSync(e)}const Bt={verb:"dismiss",description:"Dismiss this alert, exactly as a person clicking its dismiss control would. The page decides what dismissal means, usually removing the message. Returns the alert's state after the dismissal, or says the alert left the page.",inputSchema:{type:"object",properties:{}},readOnly:!1,untrustedContent:!0,registeredWhen:"The alert is mounted, has an onDismiss handler, and label or agentName provides a stable name.",unregisteredWhen:"The alert unmounts or loses its onDismiss handler."},wt=K({name:"Alert",category:"feedback",summary:"A status message for the outcome of something that already happened: a notice, a warning, or a failure.",whenToUse:'Use to report the result of an action or a condition the person did not just cause: "check your inbox", "invalid credentials", "this key expires soon". Use tone="danger" for failures, "warning" for conditions needing attention, "info" for neutral notices, and "neutral" for quiet confirmations. Pass onDismiss when the message can be acknowledged and cleared.',whenNotToUse:"Do not use for validation on a specific field; the field's own error prop places the message where the problem is. Do not use for confirmation of an action the person is about to take; that is a Dialog.",status:"experimental",props:{children:{kind:"node",description:"The message. Inline content only; it is flattened to text for the agent view.",required:!0},label:{kind:"string",description:"A short uppercase title above the message. Also derives the dismiss tool name, so prefer a stable phrase."},tone:{kind:"enum",description:"The message's severity. Danger and warning announce assertively; info and neutral announce politely.",values:["neutral","info","warning","danger"],default:"info"},onDismiss:{kind:"handler",description:"Called when the dismiss control is pressed. Providing it renders the control and registers the dismiss tool; the page owns removing the alert."},agentName:{kind:"string",description:"Override the label used to derive the dismiss tool name. Required for a dismissible alert with no label."},agentTool:{kind:"boolean",description:"Set false to render a dismissible alert without registering a tool.",default:!0}},state:{tone:{description:"The alert's severity.",attribute:"data-sprint-tone",values:["neutral","info","warning","danger"]},dismissible:{description:"Present when the alert has a dismiss control.",attribute:"data-sprint-dismissible"}},tools:{dismiss:Bt},agentView:{example:'- **Alert** "Check your inbox" [dismissible, tone=info]'},examples:[{title:"A sign-in notice",description:"The default info tone for a neutral status message.",code:'<Alert label="Check your inbox">We sent a sign-in link to nomad@escadrille.test.</Alert>'},{title:"A dismissible confirmation",description:"Providing onDismiss renders the dismiss control and registers the dismiss tool. Removing the alert is the page's job.",code:'<Alert tone="neutral" label="Key revoked" onDismiss={acknowledge}>The key can no longer authenticate.</Alert>'},{title:"A failure",description:"Danger announces assertively via role=alert.",code:'<Alert tone="danger" label="Sign-in failed">Wrong callsign or access code.</Alert>'}],a11y:{role:"status",notes:"Danger and warning render role=alert and announce assertively; info and neutral render role=status. The dismiss control is a labelled button. Render the alert when the condition occurs rather than toggling its visibility, or the announcement is lost."}});function po(e){const{tone:t="info",label:n,onDismiss:o,agentName:i,agentTool:s=!0,children:d,...l}=e,c=z(),h=ae(),m=ne(),p=r.useRef(null),b=r.useRef(o);b.current=o;const g=r.useRef(m);g.current=m;const C=r.useRef($({component:wt.name})),f=r.useRef(!0);r.useEffect(()=>(f.current=!0,()=>{f.current=!1}),[]);const w=o!==void 0,v=r.useCallback(async()=>{const N=p.current;if(N!==null)N.click();else{const T=b.current;if(T===void 0)return"This alert cannot be dismissed.";ie(()=>T())}return await oe(),f.current?`Dismissed. The alert is now:
|
|
23
|
-
${
|
|
21
|
+
`,s]})}function No(e){return e.part==="cell"&&typeof e.state.column=="string"&&typeof e.state.row=="string"}function Pt(e){return e.replace(/\|/g,"\\|").replace(/\s*\n\s*/g," ")}function In(e,t){return JSON.stringify([e,t])}function ma(e){if(e.parts.length===0||!e.parts.every(No))return e;const t=[],n=[],o=new Map;for(const r of e.parts){const l=String(r.state.column),d=String(r.state.row);t.includes(l)||t.push(l),n.includes(d)||n.push(d),o.set(In(d,l),r.label??"")}const s=[`| row | ${t.map(Pt).join(" | ")} |`,`| --- | ${t.map(()=>"---").join(" | ")} |`,...n.map(r=>`| ${Pt(r)} | ${t.map(l=>Pt(o.get(In(r,l))??"")).join(" | ")} |`)].join(`
|
|
22
|
+
`);return{...e,parts:[],summary:s}}function yt(e){return e.replace(/\s+/g," ").trim()}function Ut(e,t){if(e==null||typeof e=="boolean")return;if(typeof e=="string"||typeof e=="number"){t.push(String(e));return}if(Array.isArray(e)){for(const o of e)Ut(o,t);return}if(!i.isValidElement(e))return;const n=e.props;if(!(n["aria-hidden"]===!0||n["aria-hidden"]==="true")){if(typeof n["aria-label"]=="string"){t.push(n["aria-label"]);return}Ut(n.children,t)}}function be(e){const t=[];Ut(e,t);const n=yt(t.join(""));return n===""?void 0:n}function Io(e){return e.getAttribute("aria-hidden")==="true"||e.hasAttribute("hidden")}function fa(e,t,n){if(e.nodeType===Node.TEXT_NODE){t.push(e.nodeValue??"");return}if(e.nodeType!==Node.ELEMENT_NODE)return;const o=e;if(Io(o)||n>0&&o.hasAttribute(Me))return;const s=o.getAttribute("aria-label");if(n>0&&s!==null){t.push(s);return}for(const r of Array.from(o.childNodes))fa(r,t,n+1)}function ht(e){const t=e.getAttribute("aria-label");if(t!==null){const r=yt(t);return r===""?void 0:r}const n=e.getAttribute("aria-labelledby");if(n!==null){const r=e.ownerDocument,l=n.split(/\s+/).filter(d=>d!=="").map(d=>r.getElementById(d)).filter(d=>d!==null).map(d=>ht(d)??"").filter(d=>d!=="");if(l.length>0)return yt(l.join(" "))}const o=[];fa(e,o,0);const s=yt(o.join(""));return s===""?void 0:s}const $o=new Set(Zn),Uo=new Map([["disabled","disabled"],["open","open"],["readonly","readonly"],["required","required"]]),qo=new Map([["aria-disabled","disabled"],["aria-busy","loading"],["aria-expanded","expanded"],["aria-checked","checked"],["aria-selected","selected"],["aria-pressed","pressed"],["aria-invalid","invalid"]]);function ba(e){const t={};for(const[n,o]of qo){const s=e.getAttribute(n);s===null||s==="false"||(t[o]=s==="true"||s===""?!0:s)}for(const[n,o]of Uo)e.hasAttribute(n)&&(t[o]=!0);for(const n of Array.from(e.attributes)){if(!n.name.startsWith(st))continue;const o=n.name.slice(st.length);o===""||$o.has(o)||(t[o]=n.value===""?!0:n.value)}return t}function Wo(e){const t=[],n=[],o=s=>{for(const r of Array.from(s.children)){if(r.hasAttribute(Me)){n.push(r);continue}r.hasAttribute(Ve)&&t.push(r),o(r)}};return o(e),{parts:t,children:n}}function Bo(e){const t=e.getAttribute(Ve)??"",n=ht(e),o=e.getAttribute(tt);return{part:t,state:ba(e),...n===void 0?{}:{label:n},...o===null||o===""?{}:{tool:o}}}function Rt(e,t={}){const n=e.getAttribute(Me);if(n===null)return null;const o=t.maxDepth??8,s=t.lookupMeta??na,{parts:r,children:l}=Wo(e),d=ht(e),c=s(n)?.summary,h=e.getAttribute(tt),g=e.getAttribute(cn),u=o<=0&&l.length>0;return ma({component:n,state:ba(e),parts:r.map(Bo),children:u?[]:l.map(b=>Rt(b,{...t,maxDepth:o-1})).filter(b=>b!==null),...c===void 0?{}:{summary:c},...d===void 0?{}:{label:d},...h===null||h===""?{}:{tool:h},...g===null||g===""?{}:{owner:g},...e.hasAttribute(Ct)?{region:!0}:{},...u?{truncated:!0}:{}})}function wa(e){const t=[],n=o=>{for(const s of Array.from(o.children)){if(s.hasAttribute(Me)){t.push(s);continue}n(s)}};return n(e),t}function _o(e){const t=e.filter(r=>r.owner!==void 0);if(t.length===0)return e;const n=new Map,o=r=>{r.tool&&n.set(r.tool,r);for(const l of r.parts)l.tool&&n.set(l.tool,r);for(const l of r.children)o(l)};for(const r of e)o(r);const s=new Set;for(const r of t){const l=r.owner===void 0?void 0:n.get(r.owner);l===void 0||l===r||(l.children.push(r),s.add(r))}return e.filter(r=>!s.has(r))}function va(e,t={}){const n=wa(e).map(o=>Rt(o,t)).filter(o=>o!==null);return _o(n)}function pe(){return new Promise(e=>{if(typeof requestAnimationFrame!="function"){setTimeout(e,0);return}requestAnimationFrame(()=>{requestAnimationFrame(()=>e())})})}const Ot=48;function _e(e){return e.normalize("NFKD").replace(/[̀-ͯ]/g,"").toLowerCase().replace(/[^a-z0-9]+/g,"-").replace(/^-+|-+$/g,"")}function qt(e,t,n){const o=_e(n);if(o==="")return null;const s=[_e(t),o].filter(h=>h!=="").join("-"),r=e.map(_e).filter(h=>h!=="");for(;r.length>0&&[...r,s].join("-").length>Ot;)r.shift();const l=[...r,s].join("-");if(l.length<=Ot)return l;const d=l.slice(0,Ot),c=d.lastIndexOf("-");return c>0?d.slice(0,c):d}const rt=new Map;function Fo(e){const t=rt.get(e);if(t!==void 0)return t;const n={holders:new Set,listeners:new Map};return rt.set(e,n),n}function Ho(e,t,n){const o=Fo(e);o.holders.add(t),o.listeners.set(t,n);for(const[s,r]of o.listeners)s!==t&&r();return()=>{if(o.holders.delete(t),o.listeners.delete(t),o.holders.size===0){rt.delete(e);return}for(const s of o.listeners.values())s()}}function $n(e,t){const n=rt.get(e);return n===void 0?!1:n.holders.size===1&&n.holders.has(t)}function Vo(e){return rt.get(e)?.holders.size??0}const ya=i.createContext({path:[]}),lt=ya.Provider;function ut(){return i.useContext(ya).path}function de(e){const{spec:t,label:n,nameOverride:o,inputSchema:s,enabled:r=!0,execute:l}=e,d=ut(),c=`${t.verb}|${s===void 0?"":JSON.stringify(s)}`,h=i.useRef({key:c,value:s??t.inputSchema});h.current.key!==c&&(h.current={key:c,value:s??t.inputSchema});const g=h.current.value,u=i.useRef(null);u.current===null&&(u.current=Symbol("sprint-tool"));const b=i.useRef(l);i.useEffect(()=>{b.current=l});const m=o===void 0?n===void 0?null:qt(d,t.verb,n):qt(d,t.verb,o),[S,f]=i.useState(!1);return i.useEffect(()=>{const y=u.current;if(m===null||!r||y===null){f(!1);return}const k=Ho(m,y,()=>{f($n(m,y))});return Vo(m)>1&&console.warn(`Sprint tool name "${m}" is claimed by more than one component. None of them will register a tool. Set agentName on all but one, or label them distinctly.`),f($n(m,y)),()=>{k(),f(!1)}},[m,r]),i.useEffect(()=>{if(!S||m===null)return;const y=new AbortController;return ea({name:m,description:t.description,inputSchema:g,annotations:{readOnlyHint:t.readOnly,untrustedContentHint:t.untrustedContent},execute:(k,T)=>b.current(k,T)},y.signal),()=>{y.abort()}},[S,m,t,g]),S&&m!==null?m:void 0}function me(e){Ao.flushSync(e)}const bn={verb:"dismiss",description:"Dismiss this alert, exactly as a person clicking its dismiss control would. The page decides what dismissal means, usually removing the message. Returns the alert's state after the dismissal, or says the alert left the page.",inputSchema:{type:"object",properties:{}},readOnly:!1,untrustedContent:!0,registeredWhen:"The alert is mounted, has an onDismiss handler, and label or agentName provides a stable name.",unregisteredWhen:"The alert unmounts or loses its onDismiss handler."},Wt=Y({name:"Alert",category:"feedback",summary:"A status message for the outcome of something that already happened: a notice, a warning, or a failure.",whenToUse:'Use to report the result of an action or a condition the person did not just cause: "check your inbox", "invalid credentials", "this key expires soon". Use tone="danger" for failures, "warning" for conditions needing attention, "info" for neutral notices, and "neutral" for quiet confirmations. Pass onDismiss when the message can be acknowledged and cleared.',whenNotToUse:"Do not use for validation on a specific field; the field's own error prop places the message where the problem is. Do not use for confirmation of an action the person is about to take; that is a Dialog.",status:"experimental",props:{children:{kind:"node",description:"The message. Inline content only; it is flattened to text for the agent view.",required:!0},label:{kind:"string",description:"A short uppercase title above the message. Also derives the dismiss tool name, so prefer a stable phrase."},tone:{kind:"enum",description:"The message's severity. Danger and warning announce assertively; info and neutral announce politely.",values:["neutral","info","warning","danger"],default:"info"},announce:{kind:"enum",description:"Override how assistive technology announces the alert. assertive renders role=alert and interrupts; polite renders role=status and waits. Defaults to assertive for danger and warning and polite otherwise. Pass polite for a standing warning, such as an offline notice, that should not interrupt.",values:["assertive","polite"]},onDismiss:{kind:"handler",description:"Called when the dismiss control is pressed. Providing it renders the control and registers the dismiss tool; the page owns removing the alert."},agentName:{kind:"string",description:"Override the label used to derive the dismiss tool name. Required for a dismissible alert with no label."},agentTool:{kind:"boolean",description:"Set false to render a dismissible alert without registering a tool.",default:!0}},state:{tone:{description:"The alert's severity.",attribute:"data-sprint-tone",values:["neutral","info","warning","danger"]},dismissible:{description:"Present when the alert has a dismiss control.",attribute:"data-sprint-dismissible"}},tools:{dismiss:bn},agentView:{example:'- **Alert** "Check your inbox" [dismissible, tone=info]'},examples:[{title:"A sign-in notice",description:"The default info tone for a neutral status message.",code:'<Alert label="Check your inbox">We sent a sign-in link to nomad@escadrille.test.</Alert>'},{title:"A dismissible confirmation",description:"Providing onDismiss renders the dismiss control and registers the dismiss tool. Removing the alert is the page's job.",code:'<Alert tone="neutral" label="Key revoked" onDismiss={acknowledge}>The key can no longer authenticate.</Alert>'},{title:"A failure",description:"Danger announces assertively via role=alert.",code:'<Alert tone="danger" label="Sign-in failed">Wrong callsign or access code.</Alert>'},{title:"A standing warning",description:"A warning that stays on screen while a condition holds announces politely, so it does not interrupt whatever the person is reading.",code:'<Alert tone="warning" announce="polite" label="Offline">Changes are saved on this device until the connection returns.</Alert>'}],a11y:{role:"status",notes:"Danger and warning render role=alert and announce assertively; info and neutral render role=status, unless announce overrides it. The dismiss control is a labelled button. Render the alert when the condition occurs rather than toggling its visibility, or the announcement is lost."}});function zo(e){const{tone:t="info",announce:n,label:o,onDismiss:s,agentName:r,agentTool:l=!0,children:d,...c}=e,h=Z(),g=ue(),u=ce(),b=i.useRef(null),m=i.useRef(s);m.current=s;const S=i.useRef(u);S.current=u;const f=i.useRef(q({component:Wt.name})),y=i.useRef(!0);i.useEffect(()=>(y.current=!0,()=>{y.current=!1}),[]);const k=s!==void 0,T=i.useCallback(async()=>{const W=b.current;if(W!==null)W.click();else{const $=m.current;if($===void 0)return"This alert cannot be dismissed.";me(()=>$())}return await pe(),y.current?`Dismissed. The alert is now:
|
|
23
|
+
${S.current([f.current])}`:"Dismissed. The alert is gone from the page."},[]),O=de({spec:bn,label:r??o,enabled:l&&k,execute:T}),A=be(d),E=[];A!==void 0&&E.push({part:"message",label:A,state:{}}),k&&E.push({part:"dismiss",label:"Dismiss",state:{},...O===void 0?{}:{tool:O}});const D=q({component:Wt.name,label:o,state:{tone:t,dismissible:k},parts:E});if(f.current=D,h==="agent")return!k||g==="never"?a.jsx(te,{node:D}):a.jsx(ke,{node:D,isActionable:W=>W.part==="dismiss",onActivate:()=>s?.()});const N=(n??(t==="danger"||t==="warning"?"assertive":"polite"))==="assertive"?"alert":"status";return a.jsxs("div",{...c,...X(D),role:N,...o===void 0?{}:{"aria-label":o},children:[o===void 0?null:a.jsx("strong",{...B({part:"title",state:{}}),children:o}),a.jsx("div",{...B({part:"message",state:{}}),children:d}),k?a.jsx("button",{...B({part:"dismiss",state:{},...O===void 0?{}:{tool:O}}),type:"button","aria-label":"Dismiss",ref:b,onClick:()=>s?.(),children:"×"}):null]})}const ka=Y({name:"Avatar",category:"display",summary:"A person's photo in a circle, falling back to their initials when there is no photo or it fails to load.",whenToUse:"Use beside a person's name in a row, a card, or an account menu trigger. Pass the full name; it is the accessible name and the source of the initials. Set decorative when the name is already printed right beside it, so it is not read twice.",whenNotToUse:"Do not use for a logo or an illustration; that is an Image. Do not use as a button on its own; put it inside a Button or a Menu trigger that carries the label.",status:"experimental",props:{name:{kind:"string",description:"The person's name. Names the avatar and supplies the initials.",required:!0},src:{kind:"string",description:"The photo's URL. Without it, or if it fails to load, the initials show instead."},size:{kind:"enum",description:"small for dense rows, medium beside body text, large in a profile header.",values:["small","medium","large"],default:"medium"},decorative:{kind:"boolean",description:"Hide the avatar from assistive technology and the agent view, for when the name is printed beside it.",default:!1}},state:{photo:{description:"Present while a photo is showing rather than initials.",attribute:"data-sprint-photo"},size:{description:"The size, when it is not medium.",attribute:"data-sprint-size",values:["small","large"]}},agentView:{example:'- **Avatar** "Ada Okafor" [photo]'},examples:[{title:"A photo",code:'<Avatar name="Ada Okafor" src="media/portrait.svg" />'},{title:"Initials when there is no photo",description:"The first and last initials, on the inset surface.",code:'<Avatar name="Brother Lind" size="large" />'},{title:"Beside a printed name",description:"decorative keeps a screen reader and an agent from hearing the name twice.",code:`<Stack direction="row" gap="snug" align="center">
|
|
24
|
+
<Avatar name="Sister Amaral" size="small" decorative />
|
|
25
|
+
<Text as="span">Sister Amaral</Text>
|
|
26
|
+
</Stack>`}],a11y:{role:"img",notes:"A role=img element named by the person's name, with the photo's own alt left empty so the name is read once. decorative switches it to aria-hidden."}});function xa(e){const t=e.replace(/[^\p{L}\p{N}\s'-]/gu," ").split(/\s+/).filter(s=>s!==""),n=t[0]?.[0]??"",o=t.length>1?t.at(-1)?.[0]??"":"";return`${n}${o}`.toUpperCase()}function Go(e){const{name:t,src:n,size:o="medium",decorative:s=!1,...r}=e,l=Z(),[d,c]=i.useState(void 0),h=n!==void 0&&d!==n,g=q({component:ka.name,label:t,state:{photo:h,size:o==="medium"?void 0:o}});return l==="agent"?s?null:a.jsx(te,{node:g}):a.jsx("span",{...r,...X(g),...s?{"aria-hidden":!0}:{role:"img","aria-label":t},children:h?a.jsx("img",{src:n,alt:"",onError:()=>c(n)}):a.jsx("span",{"aria-hidden":"true",children:xa(t)})})}const Ge={verb:"act",description:"Run one of this breadcrumb's trailing actions by its visible label, exactly as a person pressing it would. Only actions that do something in the page are offered; an action that is a link is reachable by its href instead. Returns the breadcrumb's state after the action, so a follow-up read is usually unnecessary.",inputSchema:{type:"object",properties:{action:{type:"string",description:"The visible label of the action to run, as shown at the end of the bar."}},required:["action"]},readOnly:!1,untrustedContent:!0,registeredWhen:"The breadcrumb is mounted, has at least one action without an href, and no other component claims the same tool name. The registered schema enumerates those actions' labels.",unregisteredWhen:"The breadcrumb unmounts, or its last action without an href is removed."},Bt=Y({name:"Breadcrumb",category:"navigation",summary:"A navigation landmark that renders as one line: the path to the current page, where every crumb opens the level it sits in. Every destination in the tree stays in the page as an addressable part; the crumbs decide which of them a person is shown.",whenToUse:"Use it as an application's primary navigation when the destinations form a tree, or when the catalogue is larger than a rail can hold. A crumb opens its siblings, a branch drills into its children, and typing in an open crumb searches the whole tree, so what a person chooses from is one level rather than the whole set. Put a page-level command or two in actions. It takes destinations as data because it counts, filters and orders them.",whenNotToUse:"Do not use it for a handful of links that fit in a sidebar; that is Nav with NavGroup, which keeps every destination visible at once. Do not use it for links inside prose, and do not pass components in items or actions: each destination is a label, an href and its children, not a node.",status:"experimental",props:{label:{kind:"string",description:"What this navigation is for. Rendered as the landmark's accessible name and as the root of the path.",required:!0},href:{kind:"string",description:"Where the root of the path leads, such as the list a detail page belongs to. Without it the root is plain text."},items:{kind:"array",description:"The destinations, as a tree of { label, href?, active?, external?, children? }. The item marked active is the current page, and the crumbs are the path to it. A branch without an href is a level, not a destination.",required:!0},actions:{kind:"array",description:"Commands for the whole page, rendered at the end of the bar, as { label, href?, external?, onSelect? }. An action with an href is a link; one without runs onSelect."},maxCrumbs:{kind:"number",description:"How many crumbs the bar shows before it folds the middle of the path behind an ellipsis. On a narrow screen every crumb but the last folds regardless.",default:4},emptyLabel:{kind:"string",description:"What the bar says when a filter matches no destination.",default:"No match"},trailEmptyLabel:{kind:"string",description:"What the bar says when nothing has been visited through it yet.",default:"Nothing visited yet"},open:{kind:"string",description:"Which crumb is open, as its depth from 0, or 'trail', or 'closed'. Pass it to drive the bar from outside, such as from an application-level shortcut; leave it off and the bar keeps its own state."},onOpenChange:{kind:"handler",description:"Called with the crumb depth the bar wants open, 'trail', or 'closed'. Required when open is controlled, so the bar can still close itself."},defaultVisited:{kind:"array",description:"The hrefs already visited, oldest first, to seed the trail with. Use it to restore a trail recorded through onNavigate when the bar remounts."},visited:{kind:"array",description:"The trail as hrefs, oldest first, when the owner keeps it. Leave it off and the bar keeps its own trail for as long as it is mounted."},onNavigate:{kind:"handler",description:"Called with the item when a destination is chosen, before the browser follows the href. Use it to record the visit somewhere that outlives this component."},agentName:{kind:"string",description:"Overrides the label when deriving the action tool's name."},agentTool:{kind:"boolean",description:"Whether actions without an href register a WebMCP tool.",default:!0}},state:{href:{description:"On the root: where the root of the path leads. On a destination or an action: where it goes.",attribute:"data-sprint-href"},recency:{description:"On a group of results while the trail is open: 1 for the group visited most recently, counting up. Orders the groups without a style attribute.",attribute:"data-sprint-recency"},path:{description:"The path to the current page, labels joined by ' / '. Absent when no item is active.",attribute:"data-sprint-path"},destinations:{description:"How many destinations the tree holds.",attribute:"data-sprint-destinations"},visited:{description:"How many destinations have been visited through this bar.",attribute:"data-sprint-visited"},open:{description:"Which crumb is open, as its depth, or trail. Absent when the bar is closed to its one line.",attribute:"data-sprint-open"},matches:{description:"How many entries the open crumb is showing.",attribute:"data-sprint-matches"},shown:{description:"On a destination: present when the open crumb is currently showing it to a person. Every destination stays in the page either way.",attribute:"data-sprint-shown"},parent:{description:"On a destination: the labels of the levels above it, joined by ' / '.",attribute:"data-sprint-parent"},active:{description:"On a destination: present when it is the current page.",attribute:"data-sprint-active"},ancestor:{description:"On a destination: present when it is on the path to the current page.",attribute:"data-sprint-ancestor"}},tools:{act:Ge},agentView:{example:'- **Breadcrumb** "Workbench" [destinations=2, path=display / Table, visited=0] → tool `act-workbench`\n - part `action` "Copy link"\n - part `destination` "Button" [href=#/Button, parent=action]\n - part `destination` "Table" [active, href=#/Table, parent=display]'},a11y:{role:"navigation",notes:"The label is the landmark's accessible name and the crumbs are an ordered list, the current one carrying aria-current=page. Destinations the open crumb is not showing are hidden from the accessibility tree by CSS, so a screen reader travels one level at a time exactly as a sighted reader does, while the page itself keeps all of them. From the field, ArrowDown enters the results and ArrowUp at the top returns to it; typing anywhere in the results goes back to the field and keeps the character. Enter takes the first result. Escape closes the bar, as does a press outside it, and the match count is a polite live region. ArrowUp in an empty field recalls the trail, the way a console recalls history. The ellipsis that folds the middle of the path is a toggle with aria-expanded."},relatedComponents:["Nav","NavGroup","Link","Shell"],examples:[{title:"A path you can edit",description:"One line of chrome over a tree. Each crumb opens the level it sits in and filters it as you type; a branch drills into its children.",code:`<Breadcrumb
|
|
24
27
|
label="Workbench"
|
|
25
28
|
items={[
|
|
26
29
|
{ label: "action", children: [{ href: "#/Button", label: "Button" }] },
|
|
@@ -73,16 +76,24 @@ ${g.current([C.current])}`:"Dismissed. The alert is gone from the page."},[]),k=
|
|
|
73
76
|
items={[{ label: "guides", children: [{ href: "#/guide/webmcp", label: "WebMCP" }] }]}
|
|
74
77
|
defaultVisited={["#/guide/webmcp"]}
|
|
75
78
|
onNavigate={(item) => console.log(item.href)}
|
|
76
|
-
/>`}]}),
|
|
77
|
-
`),
|
|
78
|
-
`)),[
|
|
79
|
-
${
|
|
80
|
-
|
|
79
|
+
/>`}]}),Be="",Ko=12,Qo="[data-sprint-shown], button:not([hidden])";function Ta(e,t=[]){const n=t.at(-1)?.id??Be;return e.flatMap((o,s)=>{const r={item:o,id:n===Be?String(s):`${n}.${s}`,parent:n,ancestors:t};return[r,...Ta(o.children??[],[...t,r])]})}function wt(e){return[...e.ancestors,e]}function Et(e){return(e.item.children?.length??0)>0}function Xo(e){return e==="closed"?void 0:e}function Dt(e){return e.map(t=>t.item.label).join(" / ")}function Yo(e){const t=Ge.inputSchema.properties.action;return{...Ge.inputSchema,properties:{...Ge.inputSchema.properties,...t===void 0?{}:{action:{...t,enum:[...e]}}}}}function Zo(e){const{label:t,items:n,actions:o=[],maxCrumbs:s=4,emptyLabel:r="No match",trailEmptyLabel:l="Nothing visited yet",open:d,onOpenChange:c,onNavigate:h,href:g,visited:u,defaultVisited:b=[],agentName:m,agentTool:S=!0,ref:f,...y}=e,k=Z(),T=ce(),[O,A]=i.useState(void 0),[E,D]=i.useState(""),[U,N]=i.useState(void 0),[W,$]=i.useState(!1),[_,V]=i.useState(b),M=u??_,I=i.useRef(null),j=i.useRef(null),z=i.useRef(null),L=i.useRef(new Map),p=i.useRef(o);p.current=o;const x=i.useRef(T);x.current=T;const P=i.useRef(q({component:Bt.name})),v=i.useRef(!0);i.useEffect(()=>(v.current=!0,()=>{v.current=!1}),[]);const K=i.useCallback(w=>{z.current=w,typeof f=="function"?f(w):f!=null&&(f.current=w)},[f]),ne=i.useRef(c);ne.current=c;const se=i.useCallback(w=>{A(w),ne.current?.(w??"closed")},[]),re=i.useCallback(()=>{se(void 0),D(""),N(void 0)},[se]),he=i.useMemo(()=>Ta(n),[n]),we=he.find(w=>w.item.active===!0),Ce=we===void 0?[]:wt(we),Se=he.find(w=>w.id===U),fe=Se===void 0?Ce:wt(Se),Pe=fe.at(-1),ve=Pe===void 0||Et(Pe),xe=fe.length+(ve?1:0),Ae=d===void 0?O:Xo(d),C=typeof Ae=="number"?Math.max(0,Math.min(Ae,xe-1)):Ae,ee=C==="trail"?xe-1:C;i.useEffect(()=>{C!==void 0&&I.current?.focus()},[C]),i.useEffect(()=>{if(C===void 0)return;const w=G=>{const Q=G.target;Q instanceof Node&&z.current?.contains(Q)===!0||re()};return document.addEventListener("pointerdown",w),()=>document.removeEventListener("pointerdown",w)},[C,re]);const J=typeof C=="number"?C===0?Be:fe[C-1]?.id??Be:Be,R=E.trim().toLowerCase(),F=R!=="",oe=typeof C=="number"&&!F,le=w=>`${Dt(w.ancestors)} ${w.item.label}`.toLowerCase().includes(R),ye=new Set;for(const w of he){const G=w.item.href!==void 0;(C==="trail"?G&&M.includes(w.item.href??"")&&(!F||le(w)):F?C!==void 0&&G&&le(w):oe&&w.parent===J)&&ye.add(w)}const je=[void 0,...he.filter(Et)].map(w=>({id:w?.id??Be,heading:[t,...w===void 0?[]:wt(w).map(G=>G.item.label)].join(" / "),members:he.filter(G=>G.parent===(w?.id??Be))})),Oe=new Set(Ce),Le=je.flatMap(w=>w.members.filter(G=>G.item.href!==void 0).map(G=>{const Q={part:"destination",label:G.item.label,state:{...G.ancestors.length>0?{parent:Dt(G.ancestors)}:{},href:G.item.href??"",...G.item.active===!0?{active:!0}:{},...G.item.active!==!0&&Oe.has(G)?{ancestor:!0}:{},...G.item.external===!0?{external:!0}:{},...ye.has(G)?{shown:!0}:{}}};return{entry:G,part:Q}})),gt=new Map(Le.map(({entry:w,part:G})=>[w,G])),nt=o.map(w=>({part:"action",label:w.label,state:{...w.href===void 0?{}:{href:w.href},...w.external===!0?{external:!0}:{}}})),Ne=o.filter(w=>w.href===void 0).map(w=>w.label).join(`
|
|
80
|
+
`),mt=i.useMemo(()=>Yo(Ne===""?[]:Ne.split(`
|
|
81
|
+
`)),[Ne]),ft=i.useCallback(async w=>{const G=typeof w.action=="string"?w.action:"",Q=p.current.filter(We=>We.href===void 0),ge=Q.find(We=>We.label===G);if(ge===void 0)return`No action named "${G}". This breadcrumb offers: ${Q.map(We=>`"${We.label}"`).join(", ")}.`;const it=L.current.get(ge.label);return it!==void 0?it.click():me(()=>ge.onSelect?.()),await pe(),v.current?`Done. The breadcrumb is now:
|
|
82
|
+
${x.current([P.current])}`:"The action removed this breadcrumb from the page."},[]),bt=de({spec:Ge,label:m??t,inputSchema:mt,enabled:S&&Ne!=="",execute:ft}),qe=oe?je.find(w=>w.id===J)?.members.length??0:ye.size,at=q({component:Bt.name,label:t,tool:bt,region:!0,state:{...g===void 0?{}:{href:g},...Ce.length>0?{path:Dt(Ce)}:{},destinations:String(Le.length),visited:String(M.length),...C===void 0?{}:{open:String(C),matches:String(qe)}},parts:[...nt,...Le.map(({part:w})=>w)]});P.current=at;const ot=w=>{if(w.href!==void 0){const G=w.href;V(Q=>[...Q.filter(ge=>ge!==G),G])}re(),h?.(w)};if(k==="agent")return a.jsx(ke,{node:at,onActivate:(w,G)=>{const Q=o[G];if(Q!==void 0){Q.href===void 0?Q.onSelect?.():window.location.assign(Q.href);return}const ge=Le[G-o.length]?.entry;ge?.item.href!==void 0&&(ot(ge.item),window.location.assign(ge.item.href))}});const H=w=>{D(""),se(C===w?void 0:w)},ae=w=>{N(w.id),D(""),se(wt(w).length)},Te=w=>w.reduce((G,Q)=>Math.max(G,M.indexOf(Q.item.href??"")),-1),Ee=C==="trail"?je.map(w=>({id:w.id,seen:Te(w.members)})).filter(w=>w.seen>=0).sort((w,G)=>G.seen-w.seen).map(w=>w.id):[],De=w=>{const G=Ee.indexOf(w)+1;return G>0&&G<=Ko?{"data-sprint-recency":String(G)}:{}},ie=()=>{const w=j.current;return w===null?[]:Array.from(w.querySelectorAll(Qo)).filter(G=>G.closest("[hidden]")===null)},Re=w=>{const G=ie();G[w<0?G.length-1:w%G.length]?.focus()},Ie=w=>{if(w.key==="Escape"){re();return}if(w.key==="ArrowDown"){w.preventDefault(),Re(0);return}if(w.key==="ArrowUp"&&C!=="trail"){w.preventDefault(),D(""),se("trail");return}w.key==="Enter"&&(w.preventDefault(),ie()[0]?.click())},$e=w=>{if(w.key==="Escape"){re();return}const Q=ie().indexOf(w.target);if(w.key==="ArrowDown"){w.preventDefault(),Re(Q+1);return}if(w.key==="ArrowUp"){w.preventDefault(),Q<=0?I.current?.focus():Re(Q-1);return}w.key.length!==1||w.metaKey||w.ctrlKey||w.altKey||(w.preventDefault(),D(ge=>`${ge}${w.key}`),I.current?.focus())},Nn=Math.max(1,s-2),yo=!W&&xe>s&&(ee===void 0||ee===0||ee>=xe-Nn),ko=w=>yo&&w>0&&w<xe-Nn,xo=w=>{const G=fe[w],Q=G?.item,ge=w===0?t:fe[w-1]?.item.label??t,it=a.jsx("button",{type:"button","aria-expanded":C===w,"aria-label":`Browse ${ge}`,onClick:()=>H(w)});return ee===w?a.jsxs(a.Fragment,{children:[it,a.jsx("input",{ref:I,type:"text","aria-label":`Search ${t}`,value:E,placeholder:C==="trail"?`Search ${M.length} visited`:`Search ${Le.length} destinations`,onChange:We=>D(We.target.value),onKeyDown:Ie})]}):a.jsxs(a.Fragment,{children:[it,Q===void 0?null:Q.href===void 0?a.jsx("span",{children:Q.label}):a.jsx("a",{href:Q.href,"aria-current":G===we?"page":void 0,target:Q.external===!0?"_blank":void 0,rel:Q.external===!0?"noreferrer noopener":void 0,onClick:()=>ot(Q),children:Q.label})]})},To=C==="trail"&&M.length===0?l:r,Co=C==="trail"?M.length:F?Le.length:qe,So=C===void 0?`${Le.length} destinations`:F?`${qe} of ${Le.length} match`:`${qe} of ${Co}`;return a.jsxs("nav",{...y,...X(at),"aria-label":t,ref:K,children:[a.jsxs("div",{children:[a.jsx("button",{type:"button","aria-label":`Visited, ${M.length}`,"aria-expanded":C==="trail",onClick:()=>{D(""),se(C==="trail"?void 0:"trail")},children:String(M.length).padStart(2,"0")}),a.jsxs("ol",{children:[a.jsx("li",{children:g===void 0?a.jsx("span",{children:t}):a.jsx("a",{href:g,children:t})}),Array.from({length:xe},(w,G)=>[a.jsx("li",{...ko(G)?{hidden:!0}:{},children:xo(G)},fe[G]?.id??"tail"),G===0&&xe>1?a.jsx("li",{children:a.jsx("button",{type:"button","aria-label":"Show the whole path","aria-expanded":W,onClick:()=>$(Q=>!Q),children:"…"})},"fold"):null])]}),a.jsx("span",{"aria-live":"polite",children:So}),o.map((w,G)=>{const Q=nt[G];return Q===void 0?null:w.href===void 0?a.jsx("button",{type:"button",...B(Q),ref:ge=>{ge===null?L.current.delete(w.label):L.current.set(w.label,ge)},onClick:()=>w.onSelect?.(),children:w.label},w.label):a.jsx("a",{...B(Q),href:w.href,target:w.external===!0?"_blank":void 0,rel:w.external===!0?"noreferrer noopener":void 0,children:w.label},w.label)})]}),a.jsxs("div",{ref:j,onKeyDown:$e,...C===void 0?{hidden:!0}:{},children:[je.map(w=>{const G=w.members.some(Q=>ye.has(Q)&&(Q.item.href!==void 0||oe));return a.jsxs("div",{...De(w.id),...G?{}:{hidden:!0},children:[a.jsx("span",{children:w.heading}),w.members.map(Q=>{const ge=gt.get(Q);return a.jsxs("span",{children:[ge===void 0?null:a.jsx("a",{...B(ge),href:Q.item.href,"aria-current":Q.item.active===!0?"page":void 0,target:Q.item.external===!0?"_blank":void 0,rel:Q.item.external===!0?"noreferrer noopener":void 0,onClick:()=>ot(Q.item),children:Q.item.label}),Et(Q)?a.jsx("button",{type:"button","aria-label":ge===void 0?void 0:`Inside ${Q.item.label}`,onClick:()=>ae(Q),...oe&&ye.has(Q)?{}:{hidden:!0},children:ge===void 0?Q.item.label:"›"}):null]},Q.id)})]},w.id||"root")}),qe===0?a.jsx("p",{children:To}):null]})]})}const Un="--sprint-floating-top",qn="--sprint-floating-bottom",Jo="--sprint-floating-left",Wn="--sprint-floating-width",ei="--sprint-floating-room",ti="data-placement",ni=16;function ai(){const e=Number.parseFloat(getComputedStyle(document.documentElement).fontSize);return Number.isFinite(e)?e:16}function oi(e){const t=Array.from(e.children).reduce((o,s)=>Math.max(o,s.scrollHeight),e.scrollHeight),n=e.offsetHeight-e.clientHeight;return Math.min(t+n,ni*ai())}function ii(e,t,n){return n==="end"?e.right-t:n==="center"?e.left+e.width/2-t/2:e.left}function _t(e,t,n="below",o="start",s=!1){const r=t.getBoundingClientRect(),l=window.innerHeight,d=window.innerWidth,c=l-r.bottom,h=r.top,g=oi(e),u=n==="below"?c:h,b=n==="below"?h:c,m=u<g&&b>u?n==="below"?"above":"below":n,S=Math.min(s?r.width:e.offsetWidth,d),f=Math.max(0,Math.min(ii(r,S,o),d-S));return e.setAttribute(ti,m),m==="above"?(e.style.removeProperty(Un),e.style.setProperty(qn,`${l-r.top}px`)):(e.style.removeProperty(qn),e.style.setProperty(Un,`${r.bottom}px`)),e.style.setProperty(ei,`${m==="above"?h:c}px`),e.style.setProperty(Jo,`${f}px`),s?e.style.setProperty(Wn,`${S}px`):e.style.removeProperty(Wn),m}function Ca(e){return typeof e.showPopover=="function"}function wn(e){Ca(e)&&(e.matches(":popover-open")||e.showPopover())}function vn(e){Ca(e)&&e.matches(":popover-open")&&e.hidePopover()}function si(e,...t){return e instanceof Node?t.some(n=>n?.contains(e)===!0):!1}function pt(e){const{open:t,anchor:n,floating:o,side:s="below",align:r="start",matchWidth:l=!1,boundary:d,onDismiss:c}=e,h=i.useRef(c);h.current=c,i.useLayoutEffect(()=>{const g=o.current,u=n.current;if(g===null||u===null)return;if(!t){vn(g);return}wn(g),_t(g,u,s,r,l);const b=()=>_t(g,u,s,r,l),m=S=>{si(S.target,u,g,d?.current??null)||h.current?.()};return window.addEventListener("resize",b),window.addEventListener("scroll",b,!0),document.addEventListener("pointerdown",m,!0),()=>{window.removeEventListener("resize",b),window.removeEventListener("scroll",b,!0),document.removeEventListener("pointerdown",m,!0)}},[t,n,o,s,r,l,d])}const Sa=Y({name:"Tooltip",category:"overlay",summary:"A short hint that appears beside one control on hover or keyboard focus. A human affordance only: it adds nothing to the agent view.",whenToUse:"Use to name an icon-only control for sighted mouse users, or to show the whole of a line that is truncated on screen. Wrap exactly one focusable element. The hint appears after a short hover or at once on keyboard focus, and Escape dismisses it.",whenNotToUse:"Never put information only in a tooltip: touch users never see it and agents never read it, so the text must repeat something the wrapped element already says through its label or its own content. Do not use it for anything interactive; that is a Menu or a Dialog. For an icon-only Button, pass hideLabel instead, which adds the tooltip itself.",status:"experimental",props:{label:{kind:"string",description:"The hint text. Keep it to a few words.",required:!0},children:{kind:"node",description:"Exactly one focusable element, such as a Button or a link. The tooltip is anchored to it and, unless describe is false, linked to it with aria-describedby.",required:!0},side:{kind:"enum",description:"Where the hint prefers to appear. It flips to the other side when there is no room.",values:["above","below"],default:"above"},describe:{kind:"boolean",description:"Link the hint to the element with aria-describedby. Set false when the hint repeats the element's accessible name, so a screen reader does not read it twice.",default:!0},disabled:{kind:"boolean",description:"Stop the hint from appearing.",default:!1}},examples:[{title:"Naming a truncated line",description:"The line is cut short on screen, so the tooltip shows it whole. The element's own text already carries the full value for assistive technology and agents.",code:`<Tooltip label="Elder Kestrel, second counselor in the elders quorum presidency">
|
|
83
|
+
<Link href="/callings/42">Elder Kestrel, second counselor…</Link>
|
|
84
|
+
</Tooltip>`},{title:"A hint below its control",description:"side moves the hint below the control; it still flips when the control sits at the bottom of the screen.",code:`<Tooltip label="Opens in the planner" side="below">
|
|
85
|
+
<Button>Plan Sunday</Button>
|
|
86
|
+
</Tooltip>`}],a11y:{role:"tooltip",keyboard:["Focus shows the hint","Escape hides it"],notes:"The hint is a role=tooltip element linked to the wrapped element with aria-describedby. It appears after a hover delay or immediately on keyboard focus, never on touch, and is dismissed by Escape, blur, or moving the pointer away. It is a popover in the top layer, rendered inside the wrapped element's DOM, so it shows above a modal Dialog."}}),ri=400;function li(e){try{return e.matches(":focus-visible")}catch{return!0}}function di(e,t){if(!i.isValidElement(e))return e;const n=e,o=n.props["aria-describedby"];return i.cloneElement(n,{"aria-describedby":o===void 0?t:`${o} ${t}`})}function yn(e){const{label:t,children:n,side:o="above",describe:s=!0,disabled:r=!1,...l}=e,d=Z(),c=i.useId(),[h,g]=i.useState(!1),u=i.useRef(null),b=i.useRef(null),m=i.useRef(null),S=i.useRef(void 0),f=i.useCallback(()=>{S.current!==void 0&&window.clearTimeout(S.current),S.current=void 0},[]),y=i.useCallback(()=>{f(),g(!1)},[f]),k=i.useCallback(()=>{f(),r||g(!0)},[f,r]);return i.useLayoutEffect(()=>{const T=u.current?.firstElementChild;b.current=T instanceof HTMLElement?T:null}),i.useEffect(()=>f,[f]),i.useEffect(()=>{r&&y()},[r,y]),i.useEffect(()=>{if(!h)return;const T=O=>{O.key==="Escape"&&y()};return document.addEventListener("keydown",T),()=>document.removeEventListener("keydown",T)},[h,y]),pt({open:h,anchor:b,floating:m,side:o,align:"center",onDismiss:y}),d==="agent"?n:a.jsxs("span",{...l,[Nt]:Sa.name,ref:u,onPointerEnter:T=>{T.pointerType!=="touch"&&(f(),S.current=window.setTimeout(k,ri))},onPointerLeave:y,onFocus:T=>{li(T.target)&&k()},onBlur:y,children:[s?di(n,c):n,a.jsx("span",{id:c,role:"tooltip",[Nt]:"bubble",popover:"manual",hidden:!h,ref:m,children:t})]})}const kn={verb:"press",description:"Press this button, exactly as a person clicking it would. Returns the button's state after the press, so a follow-up read is usually unnecessary. Any work the press starts is not waited for; if the button enters a loading state the result says so.",inputSchema:{type:"object",properties:{}},readOnly:!1,untrustedContent:!0,registeredWhen:"The button is mounted, enabled, not loading, has a resolvable label, and no other component claims the same tool name.",unregisteredWhen:"The button unmounts, becomes disabled, or starts loading."},Ft=Y({name:"Button",category:"action",summary:"A single action a person or an agent can trigger. Registers one press tool named from its own label.",whenToUse:'Use for any discrete action: submitting, confirming, dismissing, advancing a step. tone="action" with block marks the one primary action in a view; tone="danger" marks destructive actions.',whenNotToUse:"Do not use for navigation between pages; use a link. Do not use for toggling a persistent on/off state; that needs a switch or a checkbox.",status:"experimental",props:{children:{kind:"node",description:'The button label. Its text also derives the WebMCP tool name, so prefer a verb phrase like "Prepare launch" over "OK".',required:!0},tone:{kind:"enum",description:"Visual and semantic weight. Acid is rationed to one primary action per view.",values:["neutral","action","danger"],default:"neutral"},size:{kind:"enum",description:"medium for ordinary forms and toolbars; small for dense surfaces such as table rows, cards and toasts.",values:["medium","small"],default:"medium"},icon:{kind:"node",description:"An icon drawn before the label, sized to the text. It is decorative and hidden from assistive technology; the label still names the button."},iconEnd:{kind:"node",description:"An icon drawn after the label, such as a chevron on a button that opens something. Ignored when hideLabel is set."},hideLabel:{kind:"boolean",description:"Show only the icon, as a square button. The label stays in the page for screen readers and agents, names the press tool, and appears as a tooltip on hover and focus. Requires icon.",default:!1},block:{kind:"boolean",description:'Render as a full-width bar. Combine with tone="action" for the primary action of a region.',default:!1},loading:{kind:"boolean",description:"Mark work in progress. Sets aria-busy, disables the control, and unregisters the press tool until it clears.",default:!1},disabled:{kind:"boolean",description:"Disable the control and unregister its press tool.",default:!1},agentName:{kind:"string",description:"Override the label used to derive the tool name. Set this on icon-only buttons, when two buttons would otherwise collide, and whenever the visible label contains changing values such as a count."},agentTool:{kind:"boolean",description:"Set false to render the button without registering any WebMCP tool.",default:!0},onClick:{kind:"handler",description:"Standard click handler. The press tool dispatches a real click, so this runs for agent presses too."}},state:{tone:{description:"The button's current tone.",attribute:"data-sprint-tone",values:["neutral","action","danger"]},size:{description:"Present as small on a compact button.",attribute:"data-sprint-size",values:["small"]},block:{description:"Present when the button renders as a full-width bar.",attribute:"data-sprint-block"},loading:{description:"Present while the button is busy.",attribute:"data-sprint-loading"},disabled:{description:"Present when the button cannot be pressed.",attribute:"data-sprint-disabled"}},tools:{press:kn},agentView:{example:'- **Button** "Prepare launch" [tone=action] → tool `press-prepare-launch`'},examples:[{title:"An icon-only button",description:"hideLabel draws only the icon. The label still names the button and its tool, and shows as a tooltip, so the control is never a mystery.",code:`<Button icon={<SidebarIcon />} hideLabel onClick={collapse}>
|
|
87
|
+
Hide sidebar
|
|
88
|
+
</Button>`},{title:"A compact button with an icon",description:'size="small" for a dense row; the icon sits before the label.',code:`<Button size="small" icon={<PlusIcon />} onClick={addSpeaker}>
|
|
89
|
+
Add speaker
|
|
90
|
+
</Button>`},{title:"Primary action",description:"The one rationed acid action bar for a view.",code:'<Button tone="action" block onClick={prepare}>Prepare launch</Button>'},{title:"Destructive action",code:'<Button tone="danger" onClick={purge}>Purge vault</Button>'},{title:"Busy state",description:"While loading the press tool is unregistered, so an agent cannot double-submit.",code:"<Button loading={saving} onClick={save}>Save loadout</Button>"},{title:"Disambiguating two identical labels",description:"Without agentName both buttons would claim press-save and neither would register a tool.",code:'<Button agentName="Save billing">Save</Button>'},{title:"Keeping the tool name stable under a changing label",description:"A label carrying a value would otherwise rename the tool on every change, churning registration and staling any name an agent already holds.",code:'<Button agentName="Increment">Increment ({count})</Button>'}],a11y:{role:"button",keyboard:["Enter activates","Space activates"],notes:"Loading sets aria-busy and disables the control. Focus is an offset keyline, never a rounded ring."}});function ci(){return new MouseEvent("click",{bubbles:!0,cancelable:!0})}function dt(e){const{tone:t="neutral",size:n="medium",icon:o,iconEnd:s,hideLabel:r=!1,block:l=!1,loading:d=!1,agentName:c,agentTool:h=!0,disabled:g=!1,type:u="button",children:b,ref:m,onClick:S,...f}=e,y=Z(),k=ue(),T=ce(),O=i.useRef(null),A=i.useCallback(x=>{O.current=x,typeof m=="function"?m(x):m!=null&&(m.current=x)},[m]),E=c??(typeof b=="string"?b:void 0),[D,U]=i.useState(void 0);i.useLayoutEffect(()=>{if(E!==void 0)return;const x=O.current;x!==null&&U(ht(x))});const N=g||d,W=E??D,$=i.useRef(S);$.current=S;const _=i.useRef(q({component:Ft.name})),V=i.useRef(T);V.current=T;const M=i.useRef(!0);i.useEffect(()=>(M.current=!0,()=>{M.current=!1}),[]);const I=i.useCallback(async()=>{const x=O.current;if(x!==null)x.click();else{const P=$.current;if(P===void 0)return"This button renders no control in the current view and has no click handler.";me(()=>P(ci()))}return await pe(),M.current?`Pressed. The button is now:
|
|
91
|
+
${V.current([_.current])}`:"The press removed this button from the page."},[]),j=de({spec:kn,label:W,enabled:h&&!N,execute:I}),z=q({component:Ft.name,label:W,tool:j,state:{tone:t,size:n==="medium"?void 0:n,block:l,loading:d,disabled:N}});if(_.current=z,y==="agent")return N||k==="never"?a.jsx(te,{node:z}):a.jsx(ze,{node:z,type:u,ref:A,onClick:S,"aria-busy":d||void 0});const L=r&&o!==void 0,p=a.jsxs("button",{...f,...X(z),type:u,ref:A,onClick:S,disabled:N,"aria-busy":d||void 0,children:[o===void 0?null:a.jsx("span",{"data-sprint-icon":"","aria-hidden":"true",children:o}),L?a.jsx("span",{"data-sprint-visually-hidden":"",children:b}):b,s===void 0||L?null:a.jsx("span",{"data-sprint-icon":"","aria-hidden":"true",children:s})]});return!L||W===void 0?p:a.jsx(yn,{label:W,describe:!1,disabled:N,children:p})}const xn={verb:"open",description:"Open this card, exactly as a person clicking it would. What opening does is the card's own business: it may reveal detail in place, select this item, or start a flow. Returns the card's state after the click.",inputSchema:{type:"object",properties:{}},readOnly:!1,untrustedContent:!0,registeredWhen:"The card acts rather than navigates, is mounted, enabled, has a resolvable label, and no other component claims the same tool name.",unregisteredWhen:"The card unmounts, becomes disabled, or turns into a link by taking an href."},Ht=Y({name:"Card",category:"navigation",summary:"One entry in a catalogue: a title, a line or two of body, and the whole block clickable. Give it an href and it is a link; give it onClick and it is an action that registers an open tool.",whenToUse:"Use it in a grid of comparable things a person picks between: components in a catalogue, results in a list, templates to start from. The title is the accessible name, so it is also what an agent selects on.",whenNotToUse:"Do not use it for a static region with a header; that is Panel. Do not put separate controls inside one, because the whole card is already a single control and nesting buttons inside a link is invalid.",status:"experimental",props:{label:{kind:"string",description:"The card's title, and its accessible name. Also derives the tool name when the card acts.",required:!0},children:{kind:"node",description:"A line or two describing the entry. Carried in the agent view as the body part."},href:{kind:"string",description:"Destination, which makes the card a link. A card that navigates registers no tool by default."},onClick:{kind:"handler",description:"What clicking does. Alone it makes the card a button that registers an open tool by default. Alongside href the card stays a link and the handler rides the click, so a client-side router can intercept the navigation."},disabled:{kind:"boolean",description:"Disable an acting card and unregister its tool. Has no effect on a card that navigates.",default:!1},agentTool:{kind:"boolean",description:"Override the default: on for a card that acts, off for a card that navigates, because an agent can reach an href on its own."},agentName:{kind:"string",description:"Override the label used to derive the tool name, when two cards share a title."}},state:{href:{description:"Where the card goes, when it navigates.",attribute:"data-sprint-href"},disabled:{description:"Present when the card cannot be opened.",attribute:"data-sprint-disabled"}},tools:{open:xn},agentView:{example:'- **Card** "Button" [href=#/Button]\n - part `title` "Button"\n - part `body` "A single action a person or an agent can trigger."'},examples:[{title:"A catalogue entry",description:"A card that navigates. No tool, because the href is already public.",code:`<Card label="Button" href="#/Button">
|
|
81
92
|
A single action a person or an agent can trigger.
|
|
82
93
|
</Card>`},{title:"A card that acts",description:"onClick instead of href, so the card registers open-start-from-blank and an agent can take it.",code:`<Card label="Start from blank" onClick={create}>
|
|
83
94
|
An empty page with the provider already wired up.
|
|
84
|
-
</Card>`}],a11y:{notes:"The whole block is one control: a link when it has an href, a button when it acts. The title names it, and the body is read as its content rather than as part of the name."}});function
|
|
85
|
-
${
|
|
95
|
+
</Card>`}],a11y:{notes:"The whole block is one control: a link when it has an href, a button when it acts. The title names it, and the body is read as its content rather than as part of the name."}});function hi(e){const{label:t,children:n,href:o,onClick:s,disabled:r=!1,agentTool:l,agentName:d,ref:c,...h}=e,g=Z(),u=ue(),b=ce(),m=o!==void 0,S=!m&&r,f=i.useRef(null),y=i.useCallback($=>{f.current=$,typeof c=="function"?c($):c!=null&&(c.current=$)},[c]),k=i.useRef(b);k.current=b;const T=i.useRef(q({component:Ht.name})),O=i.useRef(!0);i.useEffect(()=>(O.current=!0,()=>{O.current=!1}),[]);const A=i.useCallback(async()=>{const $=f.current;return $===null?"This card renders no control in the current view.":($.click(),await pe(),O.current?`Opened. The card is now:
|
|
96
|
+
${k.current([T.current])}`:"Opening removed this card from the page.")},[]),E=de({spec:xn,label:d??t,enabled:(l??!m)&&!S,execute:A}),D=be(n),U=[{part:"title",label:t,state:{}},...D===void 0?[]:[{part:"body",label:D,state:{}}]],N=q({component:Ht.name,label:t,tool:E,state:{href:o,disabled:S},parts:U});if(T.current=N,g==="agent")return S||u==="never"?a.jsx(te,{node:N}):a.jsx(ze,{node:N,as:m?"a":"button",href:o,ref:y,onClick:s});const W=a.jsxs(a.Fragment,{children:[a.jsx("span",{...B({part:"title",state:{}}),children:t}),n===void 0?null:a.jsx("span",{...B({part:"body",state:{}}),children:n})]});return m?a.jsx("a",{...h,...X(N),href:o,"aria-label":t,onClick:s,ref:y,children:W}):a.jsx("button",{...h,...X(N),type:"button","aria-label":t,disabled:r,onClick:s,ref:y,children:W})}const Aa=Y({name:"ChangeList",category:"display",summary:"A review of what will change or has changed: each row is marked added, removed or changed, and a changed row reads from → to. The kind of every row is a glyph, a tone and spoken text at once, and an agent reads it as state rather than from the glyph.",whenToUse:"Use it to show a diff before someone confirms it: a role change from Write to Maintain, members added to a team, settings a migration will drop. Pass the changes as data so each row is an addressable part carrying its kind, from and to. It registers no tool, because it only reports: the action is the Button that confirms the change, and the rows are already fully readable in the agent view.",whenNotToUse:"Do not use it for a list whose marks carry no meaning; that is List. Do not use it for a full record of fields; that is DescriptionList or Table. Do not put components in a change; label, from, to and detail are text.",status:"experimental",props:{label:{kind:"string",description:"What is changing. Names the list for a screen reader and for the agent view.",required:!0},changes:{kind:"array",description:'The rows in order, each { kind, label, from?, to?, detail? }. kind is "added", "removed" or "changed"; label is the thing that changed; from and to are its old and new values, usually on a changed row; detail is one short line of consequence beneath it.',required:!0},emptyLabel:{kind:"string",description:"What the list says when there is nothing to change.",default:"No changes"}},state:{changes:{description:"How many rows the list has.",attribute:"data-sprint-changes"},added:{description:"How many rows are additions. Absent when there are none.",attribute:"data-sprint-added"},removed:{description:"How many rows are removals. Absent when there are none.",attribute:"data-sprint-removed"},changed:{description:"How many rows are changes of value. Absent when there are none.",attribute:"data-sprint-changed"},empty:{description:"Present when there is nothing to change.",attribute:"data-sprint-empty"},kind:{description:"On a change: whether the row was added, removed or changed.",attribute:"data-sprint-kind",values:["added","removed","changed"]},from:{description:"On a change: the old value, when it has one.",attribute:"data-sprint-from"},to:{description:"On a change: the new value, when it has one.",attribute:"data-sprint-to"}},agentView:{example:'- **ChangeList** "Role changes" [changed=1, changes=1]\n - part `change` "Changed: Ada Lovelace, from Write to Maintain" [from=Write, kind=changed, to=Maintain]'},a11y:{role:"list",notes:"A ul named by its label, with an explicit list role. The +, − and → glyphs are aria-hidden; each row instead starts with visually hidden text naming its kind, and a changed row says from and to in words, so the kind never rests on the glyph or its color alone. Old values are a del and new values an ins."},relatedComponents:["List","DescriptionList","Dialog"],examples:[{title:"A role change",description:"The one row a permission review is about: what it was, and what it becomes.",code:`<ChangeList
|
|
86
97
|
label="Role changes"
|
|
87
98
|
changes={[{ kind: "changed", label: "Ada Lovelace", from: "Write", to: "Maintain" }]}
|
|
88
99
|
/>`},{title:"A review before confirming",description:"Additions, removals and changes together, each with a line of consequence where one matters.",code:`<ChangeList
|
|
@@ -92,7 +103,7 @@ ${v.current([k.current])}`:"Opening removed this card from the page.")},[]),A=te
|
|
|
92
103
|
{ kind: "removed", label: "Alan Turing" },
|
|
93
104
|
{ kind: "changed", label: "Ada Lovelace", from: "Write", to: "Maintain" },
|
|
94
105
|
]}
|
|
95
|
-
/>`},{title:"Nothing to change",description:"An empty review says so rather than rendering nothing.",code:'<ChangeList label="Role changes" changes={[]} emptyLabel="No role changes" />'}]}),
|
|
106
|
+
/>`},{title:"Nothing to change",description:"An empty review says so rather than rendering nothing.",code:'<ChangeList label="Role changes" changes={[]} emptyLabel="No role changes" />'}]}),ui={role:"list"},pi=["added","removed","changed"],ja={added:"+",removed:"−",changed:"→"},Ra={added:"Added",removed:"Removed",changed:"Changed"};function Ue(e){return e!==void 0&&e!==""}function gi(e){const t=Ue(e.from)?` from ${e.from}`:"",n=Ue(e.to)?` to ${e.to}`:"";return t===""&&n===""?"":`,${t}${n}`}function mi(e){const t=Ue(e.detail)?`. ${e.detail}`:"";return`${Ra[e.kind]}: ${e.label}${gi(e)}${t}`}function La(e){return{kind:e.kind,...Ue(e.from)?{from:e.from}:{},...Ue(e.to)?{to:e.to}:{}}}function fi(e){const t={};for(const n of pi){const o=e.filter(s=>s.kind===n).length;t[n]=o===0?void 0:String(o)}return t}function bi({change:e}){const t=Ue(e.from)?e.from:void 0,n=Ue(e.to)?e.to:void 0;return t===void 0&&n===void 0?null:a.jsxs(a.Fragment,{children:[a.jsx("span",{children:","}),t===void 0?null:a.jsxs(a.Fragment,{children:[a.jsx("span",{children:" from "}),a.jsx("del",{children:t})]}),a.jsx("span",{"aria-hidden":"true",children:ja.changed}),n===void 0?null:a.jsxs(a.Fragment,{children:[a.jsx("span",{children:" to "}),a.jsx("ins",{children:n})]})]})}function wi({change:e}){return a.jsxs("li",{...B({part:"change",state:La(e)}),children:[a.jsx("span",{"aria-hidden":"true",children:ja[e.kind]}),a.jsxs("p",{children:[a.jsxs("span",{children:[Ra[e.kind],": "]}),a.jsx("strong",{children:e.label}),a.jsx(bi,{change:e}),Ue(e.detail)?a.jsxs(a.Fragment,{children:[a.jsx("span",{children:". "}),a.jsx("small",{children:e.detail})]}):null]})]})}function vi(e){const{label:t,changes:n,emptyLabel:o="No changes",...s}=e,r=Z(),l=n.length===0,d=n.map(h=>({part:"change",label:mi(h),state:La(h)})),c=q({component:Aa.name,label:t,state:{changes:String(n.length),...fi(n),empty:l},parts:d});return r==="agent"?a.jsx(te,{node:c}):a.jsx("ul",{...s,...X(c),...ui,"aria-label":t,children:l?a.jsx("li",{children:o}):n.map((h,g)=>a.jsx(wi,{change:h},`${g}-${h.kind}-${h.label}`))})}const Tn={verb:"set",description:"Check or uncheck this box by stating the end state, exactly as a person clicking it would. Setting the state it already has succeeds and changes nothing, so the call is safe to retry. Returns the box's state after the call, so a follow-up read is unnecessary.",inputSchema:{type:"object",properties:{checked:{type:"boolean",description:"The end state: true leaves the box checked, false leaves it unchecked."}},required:["checked"]},readOnly:!1,untrustedContent:!0,registeredWhen:"The box is mounted, enabled, has a resolvable label, and no other component claims the same tool name.",unregisteredWhen:"The box unmounts or becomes disabled."},Vt=Y({name:"Checkbox",category:"input",summary:"A single on/off choice recorded as form data. It registers one set tool that takes the end state rather than toggling.",whenToUse:"Use it for a boolean a form will submit: accepting terms, opting in, including something in a request. The set tool takes checked as true or false, so an agent states the end state and never has to read before writing.",whenNotToUse:"Do not use it for a setting that takes effect the moment it changes; that is a Switch. Do not use it for choosing one of several options, which is a SegmentedControl or a Select.",status:"experimental",props:{label:{kind:"string",description:'What checking it means. Names the box for a screen reader and derives the tool name, so prefer a statement such as "Accept the terms".',required:!0},checked:{kind:"boolean",description:"Whether the box is checked. The box is fully controlled.",required:!0},indeterminate:{kind:"boolean",description:"Show the box as partly checked, for a parent box whose children are some checked and some not. It overrides checked visually and reads as checked=mixed to agents and assistive technology. Pressing a mixed box calls onChange(true); the page then clears indeterminate.",default:!1},onChange:{kind:"handler",description:"Called with the new checked state. The set tool drives a real click, so this runs for agent changes too.",required:!0},hint:{kind:"string",description:"Guidance shown under the box and carried into the agent view. Replaced by error while one is set."},error:{kind:"string",description:"A validation message. Marks the box invalid for people, screen readers, and agents alike."},name:{kind:"string",description:"The native form name submitted with the surrounding form."},disabled:{kind:"boolean",description:"Disable the box and unregister its set tool.",default:!1},required:{kind:"boolean",description:"Mark the box as one that must be checked.",default:!1},agentName:{kind:"string",description:"Override the label used to derive the tool name, when two boxes on a page would otherwise collide."},agentTool:{kind:"boolean",description:"Set false to render the box without registering a set tool.",default:!0}},state:{checked:{description:'Present while the box is checked, and "mixed" while it is indeterminate.',attribute:"data-sprint-checked"},disabled:{description:"Present when the box cannot be changed.",attribute:"data-sprint-disabled"},required:{description:"Present when the box must be checked.",attribute:"data-sprint-required"},invalid:{description:"Present while an error is set.",attribute:"data-sprint-invalid"}},tools:{set:Tn},agentView:{example:'- **Checkbox** "Accept the terms" [required] → tool `set-accept-the-terms`\n - part `error` "Required before launch"'},examples:[{title:"A consent box",description:"In agent view the box renders as one control; pressing it toggles, while the set tool states the end state.",code:`<Checkbox
|
|
96
107
|
label="Accept the terms"
|
|
97
108
|
checked={accepted}
|
|
98
109
|
onChange={setAccepted}
|
|
@@ -108,8 +119,13 @@ ${v.current([k.current])}`:"Opening removed this card from the page.")},[]),A=te
|
|
|
108
119
|
checked
|
|
109
120
|
disabled
|
|
110
121
|
onChange={setTelemetry}
|
|
111
|
-
/>`}
|
|
112
|
-
|
|
122
|
+
/>`},{title:"A partly picked group",description:"A parent box over a group shows mixed while only some of the group is picked. Pressing it picks everything.",code:`<Checkbox
|
|
123
|
+
label="Whole crew"
|
|
124
|
+
checked={picked.length === crew.length}
|
|
125
|
+
indeterminate={picked.length > 0 && picked.length < crew.length}
|
|
126
|
+
onChange={(next) => setPicked(next ? crew : [])}
|
|
127
|
+
/>`}],a11y:{role:"checkbox",keyboard:["Space toggles","Tab moves through the box"],notes:"A native checkbox input wrapped by its label, visually replaced by a keylined square. Focus draws an offset keyline around the square; errors set aria-invalid and link with aria-describedby."}});function yi(e,t){return e!==void 0?[{part:"error",label:e,state:{}}]:t!==void 0?[{part:"hint",label:t,state:{}}]:[]}function ki(e){const{label:t,checked:n,indeterminate:o=!1,onChange:s,hint:r,error:l,name:d,disabled:c=!1,required:h=!1,agentName:g,agentTool:u=!0,...b}=e,m=Z(),S=ue(),f=ce(),y=i.useId(),k=i.useRef(null),T=i.useRef(s);T.current=s;const O=i.useRef(n);O.current=n;const A=i.useRef(o);A.current=o;const E=i.useRef(null),D=i.useRef(f);D.current=f;const U=i.useRef(q({component:Vt.name})),N=i.useRef(!0);i.useEffect(()=>(N.current=!0,()=>{N.current=!1}),[]),i.useEffect(()=>{E.current!==null&&(E.current.indeterminate=o)});const W=i.useCallback(async M=>{const I=M.checked;if(typeof I!="boolean")return'Pass "checked" as true or false; it states the end state.';const j=A.current,z=!j&&I===O.current;if(!z){const p=k.current;p!==null&&!j?p.click():me(()=>T.current(I))}return await pe(),N.current?`${z?`Already ${I?"checked":"unchecked"}`:I?"Checked":"Unchecked"}. The checkbox is now:
|
|
128
|
+
${D.current([U.current])}`:"The change removed this checkbox from the page."},[]),$=de({spec:Tn,label:g??t,enabled:u&&!c,execute:W}),_=q({component:Vt.name,label:t,tool:$,state:{checked:o?"mixed":n,disabled:c,required:h,invalid:l!==void 0},parts:yi(l,r)});if(U.current=_,m==="agent")return c||S==="never"?a.jsx(te,{node:_}):a.jsx(ze,{node:_,ref:M=>{k.current=M},onClick:()=>s(o?!0:!n)});const V=l!==void 0?`${y}-error`:r!==void 0?`${y}-hint`:void 0;return a.jsxs("div",{...b,...X(_),children:[a.jsxs("label",{htmlFor:y,children:[a.jsx("input",{id:y,...B({part:"input",state:{}}),ref:M=>{k.current=M,E.current=M,M!==null&&(M.indeterminate=o)},type:"checkbox",checked:n,name:d,disabled:c,required:h,"aria-invalid":l!==void 0||void 0,"aria-describedby":V,onChange:M=>s(M.currentTarget.checked)}),a.jsx("span",{...B({part:"box",state:{}}),"aria-hidden":"true"}),t]}),l!==void 0?a.jsx("p",{id:V,...B({part:"error",state:{}}),children:l}):r!==void 0?a.jsx("p",{id:V,...B({part:"hint",state:{}}),children:r}):null]})}const Ke={verb:"choose",description:"Choose one of this grid's options by its visible label, exactly as a person pressing it would. In submit mode the choice submits the surrounding form with the option's value, so it can navigate away; in select mode it replaces the current selection. Returns the grid's state after the choice.",inputSchema:{type:"object",properties:{option:{type:"string",description:"The visible label of the option to choose, as shown under its glyph."}},required:["option"]},readOnly:!1,untrustedContent:!0,registeredWhen:"The grid is mounted, enabled, has a resolvable label, agentTool is not false, and no other component claims the same tool name. The registered schema enumerates the current option labels.",unregisteredWhen:"The grid unmounts, becomes disabled, or agentTool turns false."},zt=Y({name:"ChoiceGrid",category:"input",summary:"A question answered by pressing one of several large, equal-sized tiles, each a glyph such as an emoji over a text label. It works in two modes: submit mode, where every tile is a real submit button carrying its value, and select mode, where the tiles are a radio group driven by value and onChange.",whenToUse:'Use it when one tap should answer a question and the options are few enough to show at once, ideally six to twelve: an emoji verification step at sign-in ("pick the emoji you were sent"), a reaction, a mood, or a category picked by icon. Submit mode needs no client state, so it suits a server-rendered form page: give it a name and no onChange, and the pressed tile submits its form with name=value. Use select mode, by passing value and onChange, when the answer is one field among several and the form is submitted by something else. A verification challenge meant for a human, such as the emoji check, should pass agentTool={false} so the page does not offer an agent a one-call way through it.',whenNotToUse:"Do not use it for two to four short text options, which is a SegmentedControl, for long lists, which are a Select, or for choosing several at once, which is a set of Checkboxes. Do not put components in an option: label and glyph are strings, and the label is the tile's accessible name because an emoji on its own is not one.",status:"experimental",props:{label:{kind:"string",description:`The question the tiles answer. Rendered as the legend of the grid's fieldset and used to derive the tool name, so write it as a person would read it, such as "Which emoji were you sent?".`,required:!0},options:{kind:"array",description:"The tiles in display order: { value, label, glyph? }. value is what the form receives, label is what a person reads and what the choose tool accepts, and glyph is a short string such as an emoji drawn large above the label and hidden from assistive technology.",required:!0},columns:{kind:"enum",values:["2","3","4"],description:"How many columns the grid has at 40rem and wider. Narrower screens always get two, so every tile stays large enough to press.",default:3},name:{kind:"string",description:"The form field name. In submit mode each tile is a submit button with this name and its option's value; in select mode a hidden input carries the selected value under this name."},value:{kind:"string",description:"Select mode only: the value of the selected option. Ignored in submit mode, where nothing stays selected."},onChange:{kind:"handler",description:"Passing it switches the grid to select mode. Called with the chosen value; the choose tool drives a real click, so it runs for agent choices too."},disabled:{kind:"boolean",description:"Disable every tile and unregister the choose tool.",default:!1},agentName:{kind:"string",description:"Override the label used to derive the tool name, when the question is long or two grids on a page would collide."},agentTool:{kind:"boolean",description:"Set false to render the grid without registering a choose tool. Pass false for any challenge that exists to prove a human is present.",default:!0}},state:{mode:{description:"submit when pressing a tile submits the form, select when it changes a selection.",attribute:"data-sprint-mode",values:["submit","select"]},value:{description:"Select mode: the value of the option currently selected.",attribute:"data-sprint-value"},columns:{description:"The column count at 40rem and wider.",attribute:"data-sprint-columns",values:["2","3","4"]},disabled:{description:"Present when no tile can be pressed.",attribute:"data-sprint-disabled"}},tools:{choose:Ke},agentView:{example:'- **ChoiceGrid** "Pick a reaction" [columns=4, mode=select, value=fire] → tool `choose-pick-a-reaction`\n - part `choice` "Thumbs up" [value=up]\n - part `choice` "Fire" [checked, value=fire]\n - part `choice` "Laughing" [value=laugh]\n - part `choice` "Sad" [value=sad]'},examples:[{title:"An emoji verification check",description:"Submit mode in a plain form: each tile is a submit button named emoji, so the form posts emoji=fox with no client state. agentTool is false because the check exists to prove a person is present.",code:`<form method="post" action="verify">
|
|
113
129
|
<ChoiceGrid
|
|
114
130
|
label="Which emoji were you sent?"
|
|
115
131
|
name="emoji"
|
|
@@ -145,13 +161,50 @@ ${R.current([x.current])}`:"The change removed this checkbox from the page."},[]
|
|
|
145
161
|
{ value: "morning", label: "Morning", glyph: "☀" },
|
|
146
162
|
{ value: "evening", label: "Evening", glyph: "☾" },
|
|
147
163
|
]}
|
|
148
|
-
/>`}],a11y:{role:"group, or radiogroup in select mode",keyboard:["Tab reaches every tile in submit mode, and the group once in select mode","Arrow keys move to the next or previous tile; in select mode they also select it","Home and End move to the first and last tile","Enter or Space presses the focused tile"],notes:"The root is a fieldset labelled by its legend. A glyph is aria-hidden and the label is always visible text, so each tile's accessible name is its label. In select mode, selection follows focus with a roving tabindex. In agent view a hidden input stays in the form so a choice made there submits the same field a person's would."},relatedComponents:["SegmentedControl","Select","Button"]}),
|
|
149
|
-
${
|
|
164
|
+
/>`}],a11y:{role:"group, or radiogroup in select mode",keyboard:["Tab reaches every tile in submit mode, and the group once in select mode","Arrow keys move to the next or previous tile; in select mode they also select it","Home and End move to the first and last tile","Enter or Space presses the focused tile"],notes:"The root is a fieldset labelled by its legend. A glyph is aria-hidden and the label is always visible text, so each tile's accessible name is its label. In select mode, selection follows focus with a roving tabindex. In agent view a hidden input stays in the form so a choice made there submits the same field a person's would."},relatedComponents:["SegmentedControl","Select","Button"]}),xi=["ArrowRight","ArrowDown","ArrowLeft","ArrowUp","Home","End"];function Ti(e){const t=Ke.inputSchema.properties.option;return{...Ke.inputSchema,properties:{...Ke.inputSchema.properties,...t===void 0?{}:{option:{...t,enum:e.map(n=>n.label)}}}}}function Ci(e,t,n){return e==="Home"?0:e==="End"?n-1:(t+(e==="ArrowRight"||e==="ArrowDown"?1:-1)+n)%n}function Si(e,t){const n=e?.form??null;if(e===null||n===null)return!1;e.disabled=!1,e.value=t;try{n.requestSubmit()}finally{e.disabled=!0,e.value=""}return!0}function Ai(e){const{label:t,options:n,columns:o=3,name:s,value:r,onChange:l,disabled:d=!1,agentName:c,agentTool:h=!0,...g}=e,u=l===void 0?"submit":"select",b=Z(),m=ue(),S=ce(),f=i.useId(),y=i.useRef(new Map),k=i.useRef(null),T=i.useRef(l);T.current=l;const O=i.useRef(n);O.current=n;const A=i.useRef(u);A.current=u;const E=i.useRef(S);E.current=S;const D=i.useRef(q({component:zt.name})),U=i.useRef(!0);i.useEffect(()=>(U.current=!0,()=>{U.current=!1}),[]);const N=i.useCallback(p=>{const x=y.current.get(p);if(x!==void 0)return x.click(),A.current==="select"||x.form!==null;const P=T.current;return A.current==="select"&&P!==void 0?(me(()=>P(p)),!0):Si(k.current,p)},[]),W=i.useCallback(async p=>{const x=typeof p.option=="string"?p.option:"",P=O.current.find(ne=>ne.label===x);if(P===void 0)return`No option named "${x}". This grid offers: ${O.current.map(ne=>`"${ne.label}"`).join(", ")}.`;if(!N(P.value))return`No form surrounds this grid, so choosing "${P.label}" had nothing to submit.`;await pe();const K=A.current==="submit"?`Chose "${P.label}" and submitted the form.`:`Chose "${P.label}".`;return U.current?`${K} The grid is now:
|
|
165
|
+
${E.current([D.current])}`:`${K} The grid is no longer on the page.`},[N]),$=i.useMemo(()=>Ti(n),[n]),_=de({spec:Ke,label:c??t,inputSchema:$,enabled:h&&!d,execute:W}),V=u==="select"?r:void 0,M=n.map(p=>({part:"choice",label:p.label,state:{value:p.value,...p.value===V?{checked:!0}:{},...d?{disabled:!0}:{}}})),I=q({component:zt.name,label:t,tool:_,state:{mode:u,value:V,columns:String(o),disabled:d},parts:M});D.current=I;const j=u==="select"&&s!==void 0?a.jsx("input",{type:"hidden",name:s,value:V??""}):null;if(b==="agent")return d||m==="never"?a.jsx(te,{node:I}):a.jsx(ke,{node:I,onActivate:(p,x)=>{const P=n[x];P!==void 0&&N(P.value)},children:u==="select"?j:a.jsx("input",{type:"hidden",name:s,disabled:!0,ref:k})});const z=p=>{if(!xi.includes(p.key)||d||n.length===0)return;const x=n.findIndex(v=>y.current.get(v.value)===p.target);if(x===-1)return;const P=n[Ci(p.key,x,n.length)];P!==void 0&&(p.preventDefault(),y.current.get(P.value)?.focus(),u==="select"&&N(P.value))},L=n.some(p=>p.value===V);return a.jsxs("fieldset",{...g,...X(I),role:u==="select"?"radiogroup":void 0,"aria-labelledby":f,disabled:d,onKeyDown:z,children:[a.jsx("legend",{id:f,children:t}),a.jsx("div",{children:n.map((p,x)=>{const P=p.value===V,K=u==="select"?{type:"button",role:"radio","aria-checked":P,tabIndex:(L?P:x===0)?0:-1,onClick:()=>l?.(p.value)}:{type:"submit",name:s,value:p.value};return a.jsxs("button",{...K,disabled:d,ref:ne=>{ne===null?y.current.delete(p.value):y.current.set(p.value,ne)},...B(M[x]??{part:"choice",state:{}}),children:[p.glyph===void 0?null:a.jsx("span",{"aria-hidden":"true",children:p.glyph}),a.jsx("span",{children:p.label})]},p.value)})}),j]})}const ji=/(\/\/[^\n]*)|("[^"]*"|'[^']*'|`[^`]*`)|(<\/?[A-Za-z][\w.-]*)|([\w-]+(?==))|(\b(?:const|let|var|function|return|import|export|from|await|async|new|true|false|null|undefined)\b)|(\b\d+(?:\.\d+)?\b)|([<>/{}()[\];=,.]+)/g,Ri=["comment","string","tag","attr","keyword","number","punct"];function Pa(e){const t=[];let n=0;for(const o of e.matchAll(ji)){const s=o.index;if(s===void 0)continue;s>n&&t.push({kind:"plain",text:e.slice(n,s)});const r=Ri.find((l,d)=>o[d+1]!==void 0)??"plain";t.push({kind:r,text:o[0]}),n=s+o[0].length}return n<e.length&&t.push({kind:"plain",text:e.slice(n)}),t}const Oa=Y({name:"CodeBlock",category:"display",summary:"A snippet of code with a caption band and a copy control. In agent view the snippet is carried verbatim as the code part, so an agent reads the source instead of the highlighting.",whenToUse:"Use it for any code a reader is meant to run or copy: an install snippet, an example, a generated tool descriptor. It scrolls horizontally rather than wrapping, so a long line stays a long line.",whenNotToUse:"Do not use it for a short inline identifier inside a sentence; use a code element inside Text. Do not use it for prose you want to look technical.",status:"experimental",props:{code:{kind:"string",description:"The snippet, verbatim. Newlines are preserved and this exact string is what an agent reads and what the copy control copies.",required:!0},caption:{kind:"string",description:"What the snippet is, shown in the band above it and used as the block's accessible name. Defaults to the language."},language:{kind:"enum",description:"What the snippet is written in. Drives the caption default.",values:["tsx","json","bash","text"],default:"tsx"},copyLabel:{kind:"string",description:"Label for the copy control.",default:"Copy"}},state:{language:{description:"The language the snippet is in.",attribute:"data-sprint-language",values:["tsx","json","bash","text"]},lines:{description:"How many lines the snippet has.",attribute:"data-sprint-lines"},copied:{description:"Present for a moment after the copy control has put the snippet on the clipboard.",attribute:"data-sprint-copied"},token:{description:"On a highlight span: which token class it is. Colour comes from this, so a theme can recolour code without touching the component.",attribute:"data-sprint-token",values:["tag","attr","string","keyword","number","punct","comment"]}},agentView:{example:'- **CodeBlock** "install" [language=bash, lines=1]\n - part `copy` "Copy"\n - part `code` "npm install sprint"'},examples:[{title:"An example snippet",description:"No caption, so the language names the block. It registers no WebMCP tool: an agent has nothing to gain from putting text on a person's clipboard, and it can already read the code.",code:`<CodeBlock code={'<Button tone="action">Prepare launch</Button>'} />`},{title:"A captioned descriptor",code:`<CodeBlock
|
|
150
166
|
caption="descriptor"
|
|
151
167
|
language="json"
|
|
152
168
|
code={JSON.stringify(descriptor, null, 2)}
|
|
153
|
-
/>`}],a11y:{notes:"The frame is a figure named by its caption. The copy control is a real button and reports back in its own label once the snippet is on the clipboard; the label swap is a polite live region, so a screen reader hears the confirmation too."}}),
|
|
154
|
-
`).length),copied:
|
|
169
|
+
/>`}],a11y:{notes:"The frame is a figure named by its caption. The copy control is a real button and reports back in its own label once the snippet is on the clipboard; the label swap is a polite live region, so a screen reader hears the confirmation too."}}),Li=1200;function Pi(e){const{code:t,caption:n,language:o="tsx",copyLabel:s="Copy",...r}=e,l=Z(),[d,c]=i.useState(!1);i.useEffect(()=>{if(!d)return;const m=setTimeout(()=>c(!1),Li);return()=>clearTimeout(m)},[d]);const h=n??o,g=d?"Copied":s,u=q({component:Oa.name,label:h,state:{language:o,lines:String(t.split(`
|
|
170
|
+
`).length),copied:d},parts:[{part:"copy",label:g,state:{}},{part:"code",label:t,state:{}}]});if(l==="agent")return a.jsx(te,{node:u});const b=()=>{const m=navigator.clipboard;m!==void 0&&m.writeText(t).then(()=>c(!0),()=>c(!1))};return a.jsxs("figure",{...r,...X(u),"aria-label":h,children:[a.jsxs("header",{children:[a.jsx("span",{children:h}),a.jsx("button",{type:"button","aria-live":"polite",...B({part:"copy",state:{}}),onClick:b,children:g})]}),a.jsx("pre",{...B({part:"code",state:{}}),children:a.jsx("code",{children:Pa(t).map((m,S)=>a.jsx("span",{"data-sprint-token":m.kind==="plain"?void 0:m.kind,children:m.text},`${S}-${m.text}`))})})]})}function He(e,t){typeof e=="function"?e(t):e!=null&&(e.current=t)}const Ea=Y({name:"Spinner",category:"feedback",summary:"A small inline busy mark for work with no measurable progress, sized to sit inside a field or beside a line of text.",whenToUse:"Use where a whole bar or region would be too much: beside a field that is checking a value, at the end of a line that is saving, inside a combobox while results load. The label says what is happening and is announced politely; showLabel prints it beside the mark.",whenNotToUse:"Do not use for a region whose data is loading; that is Pending or a component's loading prop. Do not use when the work can be counted; that is Progress. Do not use for a busy button; Button's loading prop marks the button itself.",status:"experimental",props:{label:{kind:"string",description:'What is happening, such as "Checking availability".',required:!0},size:{kind:"enum",description:"medium matches body text; small fits inside a dense row or a field.",values:["small","medium"],default:"medium"},showLabel:{kind:"boolean",description:"Print the label beside the mark instead of keeping it for assistive technology only.",default:!1}},state:{loading:{description:"Always present: a spinner is only rendered while work is running.",attribute:"data-sprint-loading"},size:{description:"Present as small on the compact mark.",attribute:"data-sprint-size",values:["small"]}},agentView:{example:'- **Spinner** "Saving note" [loading]'},examples:[{title:"Saving beside a line",description:"The mark sits in the line, and the label is printed beside it.",code:'<Spinner label="Saving note" showLabel />'},{title:"A silent mark in a field",description:"A small mark with the label kept for assistive technology and agents.",code:'<Spinner label="Searching members" size="small" />'}],a11y:{role:"status",notes:"A role=status element, so the label is announced politely when the spinner appears. Render it only while work runs, rather than toggling its visibility. The mark is a stepped four-cell pulse, still under reduced motion."}});function Da(e){const{label:t,size:n="medium",showLabel:o=!1,...s}=e,r=Z(),l=q({component:Ea.name,label:t,state:{loading:!0,size:n==="medium"?void 0:n}});return r==="agent"?a.jsx(te,{node:l}):a.jsxs("span",{...s,...X(l),role:"status",children:[a.jsxs("span",{"aria-hidden":"true",children:[a.jsx("span",{}),a.jsx("span",{}),a.jsx("span",{}),a.jsx("span",{})]}),a.jsx("span",{...o?{}:{"data-sprint-visually-hidden":""},children:t})]})}const Cn={verb:"choose",description:"Choose an option in this searchable field. Pass an option's exact label to select it. Pass part of a label to search: one match is selected, several are listed back so you can call again with the exact label. Pass an empty string to clear a field that allows clearing. Returns the field's state after the change.",inputSchema:{type:"object",properties:{option:{type:"string",description:"An exact option label, a search for one, or an empty string to clear the field."}},required:["option"]},readOnly:!1,untrustedContent:!0,registeredWhen:"The field is mounted and enabled, has a resolvable label, and no other component claims the same tool name.",unregisteredWhen:"The field unmounts or becomes disabled."},Gt=Y({name:"Combobox",category:"input",summary:"A searchable single-choice field for long lists: type to filter, arrow to an option, Enter to pick. Options can be grouped, described, limited per group and rendered your own way. Registers one choose tool that takes a label or a search.",whenToUse:"Use when there are too many options to scan: a member picker over hundreds of people, a calling picker grouped by organization, a board filter. Options hold data: { value, label, group?, description?, keywords?, disabled? }. The default filter matches every word of the query against the label, description and keywords, ignoring case and accents. For a server-side search, pass filter={false}, update options from onQueryChange, and set loading while results arrive.",whenNotToUse:"Do not use for a short list a person can scan at once; that is a Select, or a SegmentedControl for two to four options. Do not use for free text that only suggests; this field only accepts its options. Do not use for choosing several values.",status:"experimental",props:{label:{kind:"string",description:'What is being chosen, such as "Member". Names the field and derives the tool name.',required:!0},options:{kind:"array",description:"The options: { value, label, group?, description?, keywords?, disabled? }. Consecutive and non-consecutive options sharing a group are gathered under one heading, in the order groups first appear. keywords are extra search terms that are never shown.",required:!0},value:{kind:"string",description:"The chosen option's value, or an empty string for none. Fully controlled.",required:!0},onChange:{kind:"handler",description:"Called with the chosen value, or an empty string when cleared.",required:!0},placeholder:{kind:"string",description:"Ghost text while nothing is chosen or while searching."},hint:{kind:"string",description:"Guidance under the field. Replaced by error while one is set."},error:{kind:"string",description:"A validation message that marks the field invalid."},name:{kind:"string",description:"The native form name the chosen value submits under."},disabled:{kind:"boolean",description:"Disable the field and unregister the choose tool.",default:!1},required:{kind:"boolean",description:"Mark the field required. A required field is not clearable by default.",default:!1},hideLabel:{kind:"boolean",description:"Hide the label visually while keeping it for screen readers and agents. Pair it with a placeholder.",default:!1},clearable:{kind:"boolean",description:"Show a clear control while something is chosen. Defaults to not required."},clearLabel:{kind:"string",description:"Accessible name of the clear control.",default:"Clear"},loading:{kind:"boolean",description:"Show a small spinner in the field while options are being fetched.",default:!1},filter:{kind:"handler",description:"(option, query) => boolean, replacing the built-in word match. Pass false when the options are already the results of a search the page ran."},onQueryChange:{kind:"handler",description:"Called with the search text as it changes, and with an empty string on close."},groupLimit:{kind:"number",description:'Show at most this many options per group, with a "more; keep typing" note for the rest, so one large group cannot bury the others.'},limit:{kind:"number",description:"Show at most this many options in total.",default:200},emptyLabel:{kind:"string",description:"What the list says when nothing matches.",default:"No matches"},renderOption:{kind:"handler",description:"(option) => ReactNode, drawing an option your own way, such as with an Avatar. It is the human rendering only: the label is still what is searched, announced and offered to agents."},inputRef:{kind:"object",description:"A ref to the underlying input, for focusing it."},agentName:{kind:"string",description:"Override the label used to derive the tool name."},agentTool:{kind:"boolean",description:"Set false to render the field without registering the choose tool.",default:!0}},state:{value:{description:"The chosen option's label.",attribute:"data-sprint-value"},empty:{description:"Present while nothing is chosen.",attribute:"data-sprint-empty"},options:{description:"How many options the field holds.",attribute:"data-sprint-options"},loading:{description:"Present while options are being fetched.",attribute:"data-sprint-loading"},disabled:{description:"Present when the field cannot be changed.",attribute:"data-sprint-disabled"},required:{description:"Present when a choice is needed.",attribute:"data-sprint-required"},invalid:{description:"Present while an error is set.",attribute:"data-sprint-invalid"}},tools:{choose:Cn},agentView:{example:'- **Combobox** "Member" [empty, options=312, listed=50] → tool `choose-member`\n - part `option` "Ada Okafor" [group=Elders quorum]'},examples:[{title:"A grouped member picker",description:"Hundreds of members grouped by organization, at most five per group until the person types. An agent passes a name, or part of one, to the choose tool.",code:`<Combobox
|
|
171
|
+
label="Member"
|
|
172
|
+
placeholder="Search members"
|
|
173
|
+
value={memberId}
|
|
174
|
+
onChange={setMemberId}
|
|
175
|
+
groupLimit={5}
|
|
176
|
+
options={members.map((member) => ({
|
|
177
|
+
value: member.id,
|
|
178
|
+
label: member.name,
|
|
179
|
+
group: member.organization,
|
|
180
|
+
keywords: [member.preferredName],
|
|
181
|
+
}))}
|
|
182
|
+
/>`},{title:"Options drawn your own way",description:"renderOption draws each option with an avatar; the label still drives search, announcement and the agent view.",code:`<Combobox
|
|
183
|
+
label="Speaker"
|
|
184
|
+
value={speaker}
|
|
185
|
+
onChange={setSpeaker}
|
|
186
|
+
options={members}
|
|
187
|
+
renderOption={(option) => (
|
|
188
|
+
<Stack direction="row" gap="snug" align="center">
|
|
189
|
+
<Avatar name={option.label} size="small" decorative />
|
|
190
|
+
<Text as="span">{option.label}</Text>
|
|
191
|
+
</Stack>
|
|
192
|
+
)}
|
|
193
|
+
/>`},{title:"A server-side search",description:"filter={false} trusts the options as given; the page searches on each onQueryChange and shows the spinner meanwhile.",code:`<Combobox
|
|
194
|
+
label="Calling"
|
|
195
|
+
value={calling}
|
|
196
|
+
onChange={setCalling}
|
|
197
|
+
filter={false}
|
|
198
|
+
onQueryChange={search}
|
|
199
|
+
loading={searching}
|
|
200
|
+
options={results}
|
|
201
|
+
error={calling === "" ? "Choose a calling." : undefined}
|
|
202
|
+
required
|
|
203
|
+
/>`}],a11y:{role:"combobox",keyboard:["Typing filters and opens the list","Down and Up Arrow open the list and move between enabled options","Ctrl+Home and Ctrl+End jump to the first and last option","Enter chooses the highlighted option","Escape closes the list and restores the chosen label"],notes:"An editable combobox with list autocomplete. Focus stays in the input and aria-activedescendant follows the highlighted option. Groups are labelled role=group sections. The list is a popover in the top layer, rendered in place, so it opens above a modal Dialog and flips above the field when there is no room below."}}),Bn=50,Oi=10;function Tt(e){return e.normalize("NFD").replace(/\p{Diacritic}/gu,"").toLowerCase().trim()}const Kt=(e,t)=>{const n=Tt(t);if(n==="")return!0;const o=[e.label,e.description??"",...e.keywords??[]].map(Tt).join(" ");return n.split(/\s+/).every(s=>o.includes(s))};function Ei(e,t,n){const o=[],s=new Map;let r=0;for(const l of e){let d=s.get(l.group);if(d===void 0&&(d={group:l.group,options:[],hidden:0},s.set(l.group,d),o.push(d)),t!==void 0&&d.options.length>=t||r>=n){d.hidden+=1;continue}d.options.push(l),r+=1}return o}function Di(e,t){return e!==void 0?[{part:"error",label:e,state:{}}]:t!==void 0?[{part:"hint",label:t,state:{}}]:[]}function _n(e,t){return{part:"option",label:e.label,state:{...e.value===t?{checked:!0}:{},...e.group===void 0?{}:{group:e.group},...e.description===void 0?{}:{description:e.description},...e.disabled===!0?{disabled:!0}:{}}}}function Mi(e){const{label:t,options:n,value:o,onChange:s,placeholder:r,hint:l,error:d,name:c,disabled:h=!1,required:g=!1,hideLabel:u=!1,clearable:b=!g,clearLabel:m="Clear",loading:S=!1,filter:f=Kt,onQueryChange:y,groupLimit:k,limit:T=200,emptyLabel:O="No matches",renderOption:A,inputRef:E,agentName:D,agentTool:U=!0,ref:N,...W}=e,$=Z(),_=ue(),V=ce(),M=i.useId(),[I,j]=i.useState(!1),[z,L]=i.useState(""),[p,x]=i.useState(void 0),P=i.useRef(null),v=i.useRef(null),K=i.useRef(null),ne=i.useRef(new Map),se=i.useRef(n);se.current=n;const re=i.useRef(s);re.current=s;const he=i.useRef(f);he.current=f;const we=i.useRef(b);we.current=b;const Ce=i.useRef(V);Ce.current=V;const Se=i.useRef(q({component:Gt.name})),fe=i.useRef(!0),Pe=i.useRef(y);Pe.current=y,i.useEffect(()=>(fe.current=!0,()=>{fe.current=!1}),[]);const ve=n.find(H=>H.value===o),xe=i.useMemo(()=>f===!1||!I?n:n.filter(H=>f(H,z)),[n,f,z,I]),Ae=i.useMemo(()=>Ei(xe,k,T),[xe,k,T]),C=i.useMemo(()=>Ae.flatMap(H=>H.options.filter(ae=>ae.disabled!==!0)),[Ae]),ee=i.useCallback(H=>{L(H),Pe.current?.(H)},[]),J=i.useCallback(()=>{j(!1),x(void 0),ee("")},[ee]);i.useEffect(()=>{h&&J()},[h,J]),i.useEffect(()=>{I&&(p!==void 0&&C.some(H=>H.value===p)||x(C[0]?.value))},[I,C,p]),i.useEffect(()=>{if(!I||p===void 0)return;const H=ne.current.get(p);H!==void 0&&typeof H.scrollIntoView=="function"&&H.scrollIntoView({block:"nearest"})},[I,p]),pt({open:I,anchor:v,floating:K,matchWidth:!0,boundary:P,onDismiss:J});const R=i.useCallback(H=>{J(),s(H)},[J,s]),F=i.useCallback(async H=>{const ae=typeof H.option=="string"?H.option:"",Te=se.current.filter(De=>De.disabled!==!0);let Ee;if(ae.trim()===""){if(!we.current)return"This field cannot be cleared; choose an option."}else{const De=Te.filter(Re=>Tt(Re.label)===Tt(ae)),ie=De.length>0?De:Te.filter(Re=>(he.current===!1?Kt:he.current)(Re,ae));if(ie.length===0)return`No option matches "${ae}". Try a shorter search.`;if(ie.length>1){const Re=ie.slice(0,Oi),Ie=ie.length-Re.length;return`"${ae}" matches ${ie.length} options. Call again with one exact label:
|
|
204
|
+
${Re.map($e=>`- "${$e.label}"${$e.group===void 0?"":` (${$e.group})`}`).join(`
|
|
205
|
+
`)}${Ie>0?`
|
|
206
|
+
- and ${Ie} more; search more narrowly.`:""}`}Ee=ie[0]}return me(()=>re.current(Ee?.value??"")),await pe(),fe.current?`${Ee===void 0?"Cleared":"Chosen"}. The field is now:
|
|
207
|
+
${Ce.current([Se.current])}`:"The change removed this field from the page."},[]),oe=de({spec:Cn,label:D??t,enabled:U&&!h,execute:F}),le=i.useMemo(()=>{const ae=n.filter(Te=>Te.disabled!==!0).slice(0,Bn);return ve===void 0||ae.includes(ve)?ae:[ve,...ae.slice(0,Bn-1)]},[n,ve]),je=[...($==="agent"?le:Ae.flatMap(H=>H.options)).map(H=>_n(H,o)),...Di(d,l)],Oe=q({component:Gt.name,label:t,tool:oe,state:{value:ve?.label,empty:ve===void 0,options:String(n.length),...$==="agent"&&n.length>le.length?{listed:String(le.length)}:{},loading:S,disabled:h,required:g,invalid:d!==void 0},parts:je});if(Se.current=Oe,$==="agent")return h||_==="never"?a.jsx(te,{node:Oe}):a.jsx(ke,{node:Oe,isActionable:H=>H.part==="option",onActivate:(H,ae)=>{const Te=le[ae];Te!==void 0&&me(()=>s(Te.value))}});const Le=`${M}-label`,gt=`${M}-listbox`,nt=H=>`${M}-option-${H}`,Ne=d!==void 0?`${M}-error`:l!==void 0?`${M}-hint`:void 0,mt=new Map(n.map((H,ae)=>[H.value,ae])),ft=p===void 0?void 0:mt.get(p),bt=H=>{if(C.length===0)return;const ae=C.findIndex(Ee=>Ee.value===p),Te=H==="first"?0:H==="last"?C.length-1:ae<0?H===1?0:C.length-1:(ae+H+C.length)%C.length;x(C[Te]?.value)},qe=H=>{const ae=H.key;if(ae==="ArrowDown"||ae==="ArrowUp"){if(H.preventDefault(),!I){j(!0);return}bt(ae==="ArrowDown"?1:-1);return}if(I){if(ae==="Home"||ae==="End"){(H.ctrlKey||H.metaKey)&&(H.preventDefault(),bt(ae==="Home"?"first":"last"));return}if(ae==="Enter"){H.preventDefault(),p!==void 0&&R(p);return}if(ae==="Escape"){H.preventDefault(),H.stopPropagation(),J();return}ae==="Tab"&&J()}},at=H=>{const ae=H.relatedTarget;ae instanceof Node&&P.current?.contains(ae)||J()},ot=I?z:ve?.label??"";return a.jsxs("div",{...W,...X(Oe),ref:H=>{P.current=H,He(N,H)},children:[a.jsx("label",{id:Le,htmlFor:M,...u?{"data-sprint-visually-hidden":""}:{},children:t}),a.jsxs("div",{children:[a.jsx("input",{id:M,type:"text",role:"combobox",...B({part:"input",state:{}}),ref:H=>{v.current=H,He(E,H)},value:ot,placeholder:ve===void 0||I?r:void 0,disabled:h,required:g,autoComplete:"off",spellCheck:!1,"aria-autocomplete":"list","aria-expanded":I,"aria-controls":gt,"aria-activedescendant":I&&ft!==void 0?nt(ft):void 0,"aria-invalid":d!==void 0||void 0,"aria-describedby":Ne,"aria-busy":S||void 0,onChange:H=>{ee(H.currentTarget.value),j(!0)},onClick:()=>{!I&&!h&&j(!0)},onKeyDown:qe,onBlur:at}),S?a.jsx(Da,{label:"Loading options",size:"small"}):null,b&&ve!==void 0&&!h?a.jsx("button",{type:"button","aria-label":m,onMouseDown:H=>H.preventDefault(),onClick:()=>{J(),s(""),v.current?.focus()},children:"×"}):null]}),a.jsx("div",{popover:"manual",hidden:!I,ref:K,children:a.jsxs("div",{id:gt,role:"listbox","aria-labelledby":Le,onMouseDown:H=>H.preventDefault(),children:[C.length===0?a.jsx("p",{children:S?"Loading":O}):null,Ae.map((H,ae)=>{const Te=H.options.map(ie=>{const Re=mt.get(ie.value)??0,Ie=_n(ie,o);return a.jsx("div",{id:nt(Re),role:"option",tabIndex:-1,"aria-selected":ie.value===o,"aria-disabled":ie.disabled===!0||void 0,...B(ie.value===p&&I?{...Ie,state:{...Ie.state,active:!0}}:Ie),ref:$e=>{$e===null?ne.current.delete(ie.value):ne.current.set(ie.value,$e)},onPointerMove:()=>{ie.disabled!==!0&&ie.value!==p&&x(ie.value)},onClick:()=>{ie.disabled!==!0&&R(ie.value)},children:A===void 0?a.jsxs(a.Fragment,{children:[a.jsx("span",{children:ie.label}),ie.description===void 0?null:a.jsx("span",{children:ie.description})]}):A(ie)},ie.value)}),Ee=H.hidden===0?null:a.jsxs("p",{"aria-hidden":"true",children:[H.hidden," more; keep typing to narrow"]});if(H.group===void 0)return a.jsxs("div",{role:"presentation",children:[Te,Ee]},`ungrouped-${ae}`);const De=`${M}-group-${ae}`;return a.jsxs("div",{role:"group","aria-labelledby":De,children:[a.jsx("span",{id:De,children:H.group}),Te,Ee]},H.group)})]})}),c===void 0?null:a.jsx("input",{type:"hidden",name:c,value:o}),d!==void 0?a.jsx("p",{id:Ne,...B({part:"error",state:{}}),children:d}):l!==void 0?a.jsx("p",{id:Ne,...B({part:"hint",state:{}}),children:l}):null]})}const Ma=Y({name:"CopyField",category:"input",summary:"A labelled, read-only value with a Copy control: a setup link, an invite URL, a webhook address. The value truncates with an ellipsis on one line, stays selectable, and the control confirms with Copied for two seconds.",whenToUse:'Use it to hand a person a value they are meant to paste somewhere else, such as "Copy the link" under a device setup step. The whole value stays in the DOM and in the agent view however narrow the field is drawn, so truncation never hides it from a screen reader or an agent.',whenNotToUse:"Do not use it for a secret; that is a SecretField, which masks the value and keeps it off every agent surface. Do not use it for a plain read-only value nobody needs to copy; that is a TextInput with readOnly, or a DescriptionList row. Do not use it for multi-line code; that is a CodeBlock.",status:"experimental",props:{label:{kind:"string",description:`What the value is, shown above it as the field label and used as the node's label in the agent view, e.g. "Setup link".`,required:!0},value:{kind:"string",description:"The text shown and copied, verbatim. It is never masked: an agent reads it from the value part.",required:!0},copyLabel:{kind:"string",description:"The copy control's label while idle.",default:"Copy"},copiedLabel:{kind:"string",description:"The copy control's label for two seconds after the value reaches the clipboard.",default:"Copied"},onCopy:{kind:"handler",description:"Called with the value once it is on the clipboard. Not called when the clipboard refuses the write."}},state:{copied:{description:"Present for two seconds after the copy control has put the value on the clipboard.",attribute:"data-sprint-copied"},"copy-failed":{description:"Present after the clipboard refused the write or is unavailable. The value's text is selected instead, so the person can copy it by hand.",attribute:"data-sprint-copy-failed"}},agentView:{example:'- **CopyField** "Setup link"\n - part `value` "https://sprint.example/setup/7HW4"\n - part `copy` "Copy"'},examples:[{title:"Copy the link",description:"The first real need: a setup link a person pastes into another device. A long URL truncates in the field and is still copied whole.",code:`<CopyField
|
|
155
208
|
label="Setup link"
|
|
156
209
|
value="https://sprint.example/setup/7HW4-XK92-QQ1D?station=KX-2209&expires=2026-10-01"
|
|
157
210
|
/>`},{title:"Custom control labels",description:"Relabel the control in the language of the task, and react once the value is on the clipboard.",code:`<CopyField
|
|
@@ -160,14 +213,14 @@ ${A.current([P.current])}`:`${J} The grid is no longer on the page.`},[T]),M=r.u
|
|
|
160
213
|
copyLabel="Copy code"
|
|
161
214
|
copiedLabel="Code copied"
|
|
162
215
|
onCopy={() => setShared(true)}
|
|
163
|
-
/>`}],a11y:{role:"group",keyboard:["Tab reaches the copy control","Enter or Space copies"],notes:"The group is named by its visible label. The full value is in the DOM however it is truncated, and its title shows it on hover. The copy control is a real button whose label swap is a polite live region. If the clipboard refuses, the value's text is selected so a keyboard copy still works. No WebMCP tool is registered: the value is already readable in the agent view, and an agent gains nothing from writing it to the person's clipboard that reading it does not give."},relatedComponents:["SecretField","TextInput","CodeBlock","DescriptionList"]}),
|
|
216
|
+
/>`}],a11y:{role:"group",keyboard:["Tab reaches the copy control","Enter or Space copies"],notes:"The group is named by its visible label. The full value is in the DOM however it is truncated, and its title shows it on hover. The copy control is a real button whose label swap is a polite live region. If the clipboard refuses, the value's text is selected so a keyboard copy still works. No WebMCP tool is registered: the value is already readable in the agent view, and an agent gains nothing from writing it to the person's clipboard that reading it does not give."},relatedComponents:["SecretField","TextInput","CodeBlock","DescriptionList"]}),Ni=2e3;function Ii(e){if(e===null)return;const t=e.ownerDocument.getSelection();t!==null&&t.selectAllChildren(e)}function $i(e){const{label:t,value:n,copyLabel:o="Copy",copiedLabel:s="Copied",onCopy:r,...l}=e,d=Z(),c=ue(),h=i.useId(),[g,u]=i.useState("idle"),b=i.useRef(null),m=i.useRef(r);m.current=r,i.useEffect(()=>{if(g!=="copied")return;const E=setTimeout(()=>u("idle"),Ni);return()=>clearTimeout(E)},[g]);const S=()=>{u("failed"),Ii(b.current)},f=()=>{const E=navigator.clipboard;if(E===void 0){S();return}E.writeText(n).then(()=>{u("copied"),m.current?.(n)},S)},y=g==="copied",k=y?s:o,T=[{part:"value",...n===""?{}:{label:n},state:{}},{part:"copy",label:k,state:{}}],O=q({component:Ma.name,label:t,state:{copied:y,"copy-failed":g==="failed"},parts:T});if(d==="agent")return c==="never"?a.jsx(te,{node:O}):a.jsx(ke,{node:O,isActionable:E=>E.part==="copy",onActivate:f});const A=`${h}-label`;return a.jsxs("fieldset",{...l,...X(O),"aria-labelledby":A,children:[a.jsx("legend",{id:A,children:t}),a.jsxs("div",{children:[a.jsx("span",{...B({part:"value",state:{}}),ref:b,title:n,children:n}),a.jsx("button",{...B({part:"copy",state:{}}),type:"button","aria-live":"polite",onClick:f,children:k})]})]})}const Na=Y({name:"DescriptionList",category:"display",summary:"Labelled term–description pairs for the details of one thing: metadata, settings, profile fields.",whenToUse:"Use for the properties of a single entity: a token's created date and scopes, a session's device and last activity, a profile's fields. Each item pairs one term with one description. It lays itself out from its own width, not the viewport's: the term sits above its value until the list is at least 32rem wide, then moves into a column of its own, so it reads the same in a sidebar as in a full-width panel.",whenNotToUse:"Do not use for many entities with the same fields; that is a Table. Do not put components inside term or description; both are flattened to text for the agent view, so only inline content survives. Do not use for prose sequences; that is a List.",status:"experimental",props:{label:{kind:"string",description:"The accessible name for the list, describing what entity it details.",required:!0},items:{kind:"array",description:"The pairs, in order. Each item is { term, description }; both are inline content flattened to text for the agent view.",required:!0},emptyLabel:{kind:"string",description:"Text shown when items is empty. The region keeps its frame.",default:"Empty"},loading:{kind:"boolean",description:"Set while the pairs are being fetched. Sets aria-busy and sweeps a bar along the top edge. Existing pairs stay visible; with none yet, the empty slot says loadingLabel instead of emptyLabel.",default:!1},loadingLabel:{kind:"string",description:"What the empty slot says while loading.",default:"Loading"}},state:{items:{description:"The number of pairs.",attribute:"data-sprint-items"},empty:{description:"Present when there are no pairs.",attribute:"data-sprint-empty"},loading:{description:"Present while the pairs are being fetched. Alongside empty it means nothing has arrived yet, not that there is nothing.",attribute:"data-sprint-loading"}},agentView:{example:'- **DescriptionList** "Key sk-prod" [items=2]'},examples:[{title:"Token metadata",code:`<DescriptionList
|
|
164
217
|
label="Key sk-prod"
|
|
165
218
|
items={[
|
|
166
219
|
{ term: "Created", description: "2026-08-01" },
|
|
167
220
|
{ term: "Last used", description: "2 hours ago" },
|
|
168
221
|
{ term: "Scopes", description: "read, write" },
|
|
169
222
|
]}
|
|
170
|
-
/>`},{title:"An empty list",description:"The region keeps its frame and states its emptiness.",code:'<DescriptionList label="Recovery codes" items={[]} emptyLabel="None generated" />'}],a11y:{role:"definition list",notes:"Renders a native dl with an aria-label. Terms are dt elements and descriptions dd, so structure survives without styling."}});function
|
|
223
|
+
/>`},{title:"An empty list",description:"The region keeps its frame and states its emptiness.",code:'<DescriptionList label="Recovery codes" items={[]} emptyLabel="None generated" />'}],a11y:{role:"definition list",notes:"Renders a native dl with an aria-label. Terms are dt elements and descriptions dd, so structure survives without styling."}});function Ui(e){const t=be(e.term),n=be(e.description);if(!(t===void 0&&n===void 0))return`${t??""}: ${n??""}`}function qi(e){const{label:t,items:n,emptyLabel:o="Empty",loading:s=!1,loadingLabel:r="Loading",...l}=e,d=Z(),c=n.length===0,h=n.map((u,b)=>{const m=Ui(u);return{part:"item",state:{index:String(b+1)},...m===void 0?{}:{label:m}}}),g=q({component:Na.name,label:t,state:{items:String(n.length),empty:c,loading:s},parts:h});return d==="agent"?a.jsx(te,{node:g}):a.jsx("dl",{...l,...X(g),"aria-label":t,"aria-busy":s||void 0,children:c?a.jsx("div",{children:a.jsx("span",{children:s?r:o})}):n.map((u,b)=>a.jsxs("div",{...B({part:"item",state:{index:String(b+1)}}),children:[a.jsx("dt",{children:u.term}),a.jsx("dd",{children:u.description})]},`${b}-${String(be(u.term))}`))})}const Sn={verb:"close",description:"Close this dialog without taking its action, exactly as pressing its close control or Escape would. Anything entered inside the dialog may be discarded by the page. To take the dialog's action instead, use the tools its contents register while it is open.",inputSchema:{type:"object",properties:{}},readOnly:!1,untrustedContent:!0,registeredWhen:"The dialog is open. A closed dialog renders nothing and has no tools.",unregisteredWhen:"The dialog closes or unmounts."},Ia=Y({name:"Dialog",category:"overlay",summary:"A modal that interrupts the page for one decision: confirm a destructive action, complete a short step, acknowledge something before continuing.",whenToUse:"Use when the page must not continue until the person decides: confirming a revocation or deletion, a short focused form, a required acknowledgement. Keep one decision per dialog and put its actions inside as ordinary Buttons; tools registered inside the dialog compose their names under its label.",whenNotToUse:"Do not use for status messages; that is an Alert. Do not use for anything the person should be able to ignore; a modal takes the whole page hostage. Do not nest dialogs.",status:"experimental",props:{label:{kind:"string",description:"The dialog's title. Names the dialog for assistive tech, derives the close tool name, and scopes the names of tools registered inside.",required:!0},open:{kind:"boolean",description:"Whether the dialog is shown. A closed dialog renders nothing at all; the page owns this state.",required:!0},onClose:{kind:"handler",description:"Called when the person or an agent asks to close: the close control, Escape, or the close tool. Set open to false in response.",required:!0},children:{kind:"node",description:"The dialog's contents. Ordinary components; anything actionable registers its own tools, scoped under the dialog's label.",required:!0},headingLevel:{kind:"enum",description:"Render the title as a real heading at this level, joining the page outline.",values:["2","3","4"]},size:{kind:"enum",description:"The dialog's width: small (26rem) for a confirmation, medium (36rem) for a short form, large (52rem) for a table or a two-column form. Every size shrinks to fit a phone.",values:["small","medium","large"],default:"small"},initialFocus:{kind:"object",description:"A ref to the element that takes focus when the dialog opens, such as the first field of a form or the safe choice in a destructive confirmation. Without it the browser focuses the first focusable element, which is the close control."},owner:{kind:"string",description:"The tool name of the control that opened this dialog. Published as data-sprint-owner so a reading agent can attach the dialog to its opener."},agentName:{kind:"string",description:"Override the label used to derive the close tool name."},agentTool:{kind:"boolean",description:"Set false to render without registering the close tool.",default:!0}},state:{open:{description:"Present while the dialog is shown. A closed dialog is absent from the DOM entirely.",attribute:"data-sprint-open"},size:{description:"The width the dialog was given, when it is not the default small.",attribute:"data-sprint-size",values:["medium","large"]}},tools:{close:Sn},agentView:{example:'- **Dialog** "Revoke key" [open] with part `close` → tool `close-revoke-key`'},examples:[{title:"A destructive confirmation",description:"The confirm Button registers its tool only while the dialog is open, and its name is scoped under the dialog's label.",code:`<Dialog label="Revoke key" open={confirming} onClose={() => setConfirming(false)}>
|
|
171
224
|
<Stack gap="tight">
|
|
172
225
|
<Text>The key stops authenticating immediately. This cannot be undone.</Text>
|
|
173
226
|
<Button tone="danger" onClick={revoke}>Revoke sk-prod</Button>
|
|
@@ -179,7 +232,18 @@ ${A.current([P.current])}`:`${J} The grid is no longer on the page.`},[T]),M=r.u
|
|
|
179
232
|
onClose={() => setRotating(false)}
|
|
180
233
|
>
|
|
181
234
|
<Text>The current secret keeps working for one hour.</Text>
|
|
182
|
-
</Dialog>`}
|
|
235
|
+
</Dialog>`},{title:"A form that focuses its first field",description:"A medium dialog for a short form. initialFocus puts the cursor in the field instead of on the close control, so the person can type straight away.",code:`<Dialog
|
|
236
|
+
label="Rename station"
|
|
237
|
+
size="medium"
|
|
238
|
+
open={renaming}
|
|
239
|
+
initialFocus={nameField}
|
|
240
|
+
onClose={() => setRenaming(false)}
|
|
241
|
+
>
|
|
242
|
+
<Stack gap="tight">
|
|
243
|
+
<TextInput label="Station name" value={name} onChange={setName} inputRef={nameField} />
|
|
244
|
+
<Button tone="action" onClick={save}>Save name</Button>
|
|
245
|
+
</Stack>
|
|
246
|
+
</Dialog>`}],a11y:{role:"dialog",keyboard:["Escape closes","Tab cycles within the dialog"],notes:"A native dialog element shown with showModal, so focus containment, inerting the page behind, and Escape come from the browser. The title names the dialog via aria-label."}});function Wi(e){const{label:t,open:n,onClose:o,headingLevel:s,size:r="small",initialFocus:l,owner:d,agentName:c,agentTool:h=!0,children:g,ref:u,...b}=e,m=Z(),S=ue(),f=ut(),y=i.useRef(null),k=i.useRef(null),T=i.useRef(o);T.current=o;const O=i.useRef(n);O.current=n;const A=i.useRef(l);A.current=l;const E=i.useCallback(_=>{y.current=_,typeof u=="function"?u(_):u!=null&&(u.current=_)},[u]);i.useEffect(()=>{if(!n)return;const _=y.current;if(_!==null)return _.open||(typeof _.showModal=="function"?_.showModal():_.open=!0,A.current?.current?.focus()),()=>{_.open&&(typeof _.close=="function"?_.close():_.open=!1)}},[n]);const D=i.useCallback(async()=>{const _=k.current;return _!==null?_.click():me(()=>T.current()),await pe(),O.current?"The page kept the dialog open.":"Closed. The dialog is gone from the page."},[]),U=de({spec:Sn,label:c??t,enabled:h&&n,execute:D}),N=i.useMemo(()=>({path:[...f,t]}),[f,t]);if(!n)return null;const W=q({component:Ia.name,label:t,owner:d,region:!0,state:{open:!0,size:r==="small"?void 0:r},parts:[{part:"close",label:"Close",state:{},...U===void 0?{}:{tool:U}}]});if(m==="agent")return a.jsx(ke,{node:W,isActionable:()=>S!=="never",onActivate:()=>o(),children:a.jsx(lt,{value:N,children:g})});const $=s===void 0?"span":`h${s}`;return a.jsxs("dialog",{...b,...X(W),"aria-label":t,ref:E,onCancel:_=>{_.preventDefault(),o()},children:[a.jsxs("header",{children:[a.jsx($,{children:t}),a.jsx("button",{...B({part:"close",state:{},...U===void 0?{}:{tool:U}}),type:"button","aria-label":"Close",ref:k,onClick:()=>o(),children:"×"})]}),a.jsx("div",{children:a.jsx(lt,{value:N,children:g})})]})}const An={verb:"expand",description:"Expand or collapse this region for the person viewing the page, by stating the end state, exactly as a person pressing its toggle would. The content is already readable in the agent view either way, so call this only to change what a person sees. Setting the state it already has succeeds and changes nothing. Returns the region's state after the call.",inputSchema:{type:"object",properties:{expanded:{type:"boolean",description:"The end state: true reveals the region, false conceals it."}},required:["expanded"]},readOnly:!1,untrustedContent:!0,registeredWhen:"The disclosure is mounted, has a resolvable label, and no other component claims the same tool name.",unregisteredWhen:"The disclosure unmounts or agentTool is set false."},Qt=Y({name:"Disclosure",category:"layout",summary:"A labelled region a person can show or hide with a toggle that carries its expanded state. Collapsing conceals the content from a person only: it stays in the page, and the agent view always renders it.",whenToUse:'Use it for secondary detail a person reads on demand beside the primary content, such as an access breakdown on a user page behind "Show access breakdown". It replaces a Button that swaps its own label, because the toggle publishes aria-expanded and the region it controls, and the content stays readable to an agent without a click.',whenNotToUse:"Do not use it to hide content an agent should not read; collapsing is a human affordance and the agent view carries the content regardless. Do not use it for a region that is always visible, which is a Panel, or for content that must interrupt the page, which is a Dialog. Do not use it to switch between alternative views of the same data, which is a SegmentedControl.",status:"experimental",props:{label:{kind:"string",description:'What the region is, as a noun phrase such as "Access breakdown". It names the region for a screen reader, derives the toggle text and the tool name.',required:!0},children:{kind:"node",description:"The region's content. It is always mounted: collapsing hides it from a person with CSS, so components inside keep their tools and stay in the page projection."},expanded:{kind:"boolean",description:"Whether the region is revealed. Pass it with onExpandedChange to control the disclosure; leave it unset to let the disclosure keep its own state."},defaultExpanded:{kind:"boolean",description:"The initial state when the disclosure is uncontrolled.",default:!1},onExpandedChange:{kind:"handler",description:"Called with the new state whenever the toggle is pressed, by a person, a DOM-driving agent, or the expand tool."},showLabel:{kind:"string",description:"The toggle text while collapsed.",default:'"Show " followed by the label'},hideLabel:{kind:"string",description:"The toggle text while expanded.",default:'"Hide " followed by the label'},agentName:{kind:"string",description:"Override the label used to derive the tool name, when two disclosures on a page would otherwise collide."},agentTool:{kind:"boolean",description:"Set false to render the disclosure without registering an expand tool.",default:!0}},state:{expanded:{description:"Present while the region is revealed to a person. Absent means collapsed: the content is still in the page, concealed by CSS rather than unmounted or marked hidden.",attribute:"data-sprint-expanded"}},tools:{expand:An},agentView:{example:'- **Disclosure** "Access breakdown" → tool `expand-access-breakdown`\n - part `toggle` "Show access breakdown"\n - **Text** "Admin through the Operators group."'},examples:[{title:"Secondary detail on demand",description:"Uncontrolled: the disclosure keeps its own state. In agent view the content renders beneath the line whether or not a person has opened it, and the toggle is one control.",code:`<Disclosure label="Access breakdown">
|
|
183
247
|
<Text>Admin through the Operators group.</Text>
|
|
184
248
|
</Disclosure>`},{title:"A controlled disclosure",description:"Pass expanded and onExpandedChange when something else on the page needs to know or set whether the region is open. The expand tool drives the same toggle.",code:`<Disclosure
|
|
185
249
|
label="Access breakdown"
|
|
@@ -189,17 +253,17 @@ ${A.current([P.current])}`:`${J} The grid is no longer on the page.`},[T]),M=r.u
|
|
|
189
253
|
<Text>Admin through the Operators group.</Text>
|
|
190
254
|
</Disclosure>`},{title:"Custom toggle text",description:"showLabel and hideLabel replace the derived toggle text when the noun phrase does not read naturally after Show and Hide.",code:`<Disclosure label="Audit trail" showLabel="Show 12 events" hideLabel="Hide events">
|
|
191
255
|
<Text>Last change was a role grant by the on-call operator.</Text>
|
|
192
|
-
</Disclosure>`}],a11y:{role:"region",keyboard:["Enter toggles","Space toggles"],notes:"The root is a section named by the label. The toggle is a real button with aria-expanded and aria-controls pointing at the content. Collapsed content is display: none, which removes it from the accessibility tree for a person and a screen reader while leaving it in the DOM for the agent projection."},relatedComponents:["Panel","Switch"]});function
|
|
193
|
-
${
|
|
256
|
+
</Disclosure>`}],a11y:{role:"region",keyboard:["Enter toggles","Space toggles"],notes:"The root is a section named by the label. The toggle is a real button with aria-expanded and aria-controls pointing at the content. Collapsed content is display: none, which removes it from the accessibility tree for a person and a screen reader while leaving it in the DOM for the agent projection."},relatedComponents:["Panel","Switch"]});function Fn(e){return/^[A-Z][a-z]/.test(e)?`${e[0]?.toLowerCase()}${e.slice(1)}`:e}function Bi(e){const{label:t,expanded:n,defaultExpanded:o=!1,onExpandedChange:s,showLabel:r=`Show ${Fn(t)}`,hideLabel:l=`Hide ${Fn(t)}`,agentName:d,agentTool:c=!0,children:h,...g}=e,u=Z(),b=ue(),m=ce(),S=i.useId(),[f,y]=i.useState(o),k=n??f,T=i.useRef(null),O=i.useRef(k);O.current=k;const A=i.useRef(n!==void 0);A.current=n!==void 0;const E=i.useRef(s);E.current=s;const D=i.useRef(m);D.current=m;const U=i.useRef(q({component:Qt.name})),N=i.useRef(!0);i.useEffect(()=>(N.current=!0,()=>{N.current=!1}),[]);const W=i.useCallback(j=>{A.current||y(j),E.current?.(j)},[]),$=()=>W(!k),_=i.useCallback(async j=>{const z=j.expanded;if(typeof z!="boolean")return'Pass "expanded" as true or false; it states the end state.';const L=z===O.current;if(!L){const x=T.current;x!==null?x.click():me(()=>W(z))}return await pe(),N.current?`${L?`Already ${z?"expanded":"collapsed"}`:z?"Expanded":"Collapsed"}. The disclosure is now:
|
|
257
|
+
${D.current([U.current])}`:"The change removed this disclosure from the page."},[W]),V=de({spec:An,label:d??t,enabled:c,execute:_}),M={part:"toggle",label:k?l:r,state:k?{expanded:!0}:{}},I=q({component:Qt.name,label:t,tool:V,region:!0,state:{expanded:k},parts:[M]});return U.current=I,u==="agent"?b==="never"?a.jsx(te,{node:I,children:h}):a.jsx(ke,{node:I,onActivate:$,children:h}):a.jsxs("section",{...g,...X(I),"aria-label":t,children:[a.jsx("button",{...B(M),ref:T,type:"button","aria-expanded":k,"aria-controls":S,onClick:$,children:M.label}),a.jsx("div",{id:S,children:h})]})}const $a=Y({name:"Divider",category:"layout",summary:"A horizontal rule that segments a page: the line between a header or a breadcrumb and the body under it, or between two runs of content. It draws in the active theme's own keyline or band, and can name the segment it opens.",whenToUse:"Use it where a page changes subject and nothing else marks the change: under a PageHeader or a Breadcrumb before the body starts, or between groups of panels. Give it a label when the segment that follows has a name worth reading; an unlabelled Divider is invisible in agent view, because an agent does not care where a line is drawn, only what the line announces.",whenNotToUse:"Do not use it to space things out; that is the gap on Stack. Do not use it to frame a region with a header; that is Panel, which draws its own keylines. Do not stack two in a row, and do not use it inside a Panel to separate a list's items; the list draws its own.",status:"experimental",props:{label:{kind:"string",description:"The name of the segment the divider opens, rendered small on the rule."},weight:{kind:"enum",description:`How hard the break is. "hairline" is a keyline, "heavy" a thick strong keyline, "band" a strip of the theme's own ornament for the one break that matters most on a page.`,values:["hairline","heavy","band"],default:"hairline"}},state:{weight:{description:"How hard the break is.",attribute:"data-sprint-weight",values:["hairline","heavy","band"]}},agentView:{example:'- **Divider** "Results" [weight=band]'},a11y:{role:"separator",notes:"The rule is a native hr, so assistive technology announces a separator. A label is ordinary text read just before it, the way a person reads it on the rule."},relatedComponents:["Stack","PageHeader","Breadcrumb","Panel"],examples:[{title:"Separating the header from the body",description:"The plainest break: a keyline under the page's chrome, before the content starts.",code:`<Stack>
|
|
194
258
|
<Breadcrumb
|
|
195
259
|
label="Docs"
|
|
196
260
|
items={[{ label: "guides", children: [{ href: "#/guide/webmcp", label: "WebMCP", active: true }] }]}
|
|
197
261
|
/>
|
|
198
262
|
<Divider />
|
|
199
263
|
<Text>The body of the page starts here.</Text>
|
|
200
|
-
</Stack>`},{title:"A named segment",description:"A label names what follows, on the rule itself and to an agent reading the page.",code:'<Divider label="Results" weight="heavy" />'},{title:"The page's main break",description:"A band draws the theme's own ornament: hatching in the default register, pins in calorie, a barcode strip in trax, a row of dots in ambient. Use it once per page.",code:'<Divider label="Body" weight="band" />'}]});function
|
|
264
|
+
</Stack>`},{title:"A named segment",description:"A label names what follows, on the rule itself and to an agent reading the page.",code:'<Divider label="Results" weight="heavy" />'},{title:"The page's main break",description:"A band draws the theme's own ornament: hatching in the default register, pins in calorie, a barcode strip in trax, a row of dots in ambient. Use it once per page.",code:'<Divider label="Body" weight="band" />'}]});function _i(e){const{label:t,weight:n="hairline",...o}=e,s=Z(),r=q({component:$a.name,label:t,state:{weight:n}});return s==="agent"?t===void 0?null:a.jsx(te,{node:r}):a.jsxs("div",{...o,...X(r),children:[t===void 0?null:a.jsx("span",{children:t}),a.jsx("hr",{})]})}const jn={verb:"open",description:"Follow this link and load its destination, exactly as a person clicking it would. The current page is replaced, so anything unsaved on it is lost and any tool registered by this page stops existing.",inputSchema:{type:"object",properties:{}},readOnly:!1,untrustedContent:!0,registeredWhen:"The link opts in with agentTool, is mounted, has a resolvable label, and no other component claims the same tool name. Links register nothing by default.",unregisteredWhen:"The link unmounts or opts back out."},Ua=Y({name:"Link",category:"navigation",summary:"A navigation link. It publishes its destination as state, so an agent reading the page in text learns the URL rather than having to click to find out, and it renders a real anchor in both views.",whenToUse:"Use it for anything that changes the address: a nav item, a cross-reference, a link out to a specification. Set active on the item matching the current route so the agent view and the human view agree about where you are. Under a client-side router, pass an onClick that prevents default and navigates; the handler rides the anchor in both views, so agent clicks and open tools go through the router too.",whenNotToUse:"Do not use it for an action that stays on the page; that is a Button. Do not register a tool on ordinary navigation: an agent can already reach a URL, and a page of links would flood its tool list for no gain.",status:"experimental",props:{href:{kind:"string",description:"The destination. Published as data-sprint-href and carried in the agent view, so the URL is readable without a click.",required:!0},children:{kind:"node",description:"The link text. It names the destination, so prefer the page's name over here or read more.",required:!0},active:{kind:"boolean",description:"Mark the link as the current location. Sets aria-current so a screen reader and an agent learn it the same way.",default:!1},external:{kind:"boolean",description:"Mark a destination outside this app. Opens in a new context and adds the usual rel protections.",default:!1},agentTool:{kind:"boolean",description:"Set true to register an open tool for this link. Off by default: navigation is reachable by URL, so a tool per link is cost without benefit.",default:!1},agentName:{kind:"string",description:"Override the label used to derive the tool name, for icon-only links or two links with the same text."}},state:{href:{description:"Where this link goes.",attribute:"data-sprint-href"},active:{description:"Present when this link is the current location.",attribute:"data-sprint-active"},external:{description:"Present when the destination is outside this app.",attribute:"data-sprint-external"}},tools:{open:jn},agentView:{example:'- **Link** "Button" [active, href=#/Button]'},examples:[{title:"A nav item",code:'<Link href="#/Button" active={route === "Button"}>Button</Link>'},{title:"A link out",code:`<Link href="https://developer.chrome.com/docs/ai/webmcp" external>
|
|
201
265
|
Chrome docs
|
|
202
|
-
</Link>`},{title:"A link an agent may follow itself",description:"Opting in is for the one link that completes a task, not for a nav list.",code:'<Link href="#/checkout" agentTool>Go to checkout</Link>'}],a11y:{role:"link",keyboard:["Enter follows the link"],notes:"active sets aria-current=page. External links open in a new context with rel=noreferrer noopener, and carry their outward mark as a pseudo-element with empty alternative text so it never reaches the accessible name or the tool name. Inside Text a link is underlined all the time, so colour is never the only thing distinguishing it from the prose around it."}});function
|
|
266
|
+
</Link>`},{title:"A link an agent may follow itself",description:"Opting in is for the one link that completes a task, not for a nav list.",code:'<Link href="#/checkout" agentTool>Go to checkout</Link>'}],a11y:{role:"link",keyboard:["Enter follows the link"],notes:"active sets aria-current=page. External links open in a new context with rel=noreferrer noopener, and carry their outward mark as a pseudo-element with empty alternative text so it never reaches the accessible name or the tool name. Inside Text a link is underlined all the time, so colour is never the only thing distinguishing it from the prose around it."}});function qa(e){const{href:t,active:n=!1,external:o=!1,agentTool:s=!1,agentName:r,children:l,ref:d,onClick:c,...h}=e,g=Z(),u=ue(),b=i.useRef(null),m=i.useCallback(O=>{b.current=O,typeof d=="function"?d(O):d!=null&&(d.current=O)},[d]),S=r??be(l),f=i.useCallback(()=>{const O=b.current;return O===null?"This link renders no element in the current view. Navigate to its href instead.":(O.click(),`Following ${O.getAttribute("href")??t}.`)},[t]),y=de({spec:jn,label:S,enabled:s,execute:f}),k=q({component:Ua.name,label:be(l),tool:y,state:{href:t,active:n,external:o}}),T=o?{target:"_blank",rel:"noreferrer noopener"}:{target:void 0,rel:void 0};return g==="agent"?u==="never"?a.jsx(te,{node:k}):a.jsx(ze,{node:k,as:"a",href:t,ref:m,onClick:c,target:T.target,rel:T.rel}):a.jsx("a",{...h,...X(k),href:t,ref:m,onClick:c,"aria-current":n?"page":void 0,target:T.target,rel:T.rel,children:l})}const Wa=Y({name:"EmptyState",category:"feedback",summary:"A region that says there is nothing here, and why: a headline, an optional sentence, and an optional way out such as clearing filters or creating the first record. It marks the empty field with the register's own empty ornament.",whenToUse:'Use it in place of a list, grid, or set of results that has nothing to show, so the space says it is empty rather than rendering nothing. Set reason="filtered" when records exist but none match, so an agent knows to relax the filters rather than conclude there is no data.',whenNotToUse:"Do not use it for an empty Table, List, or Panel; those already carry their own emptyLabel. Do not use it for a failure; that is an Alert. Do not use it while data is still loading; that is Pending.",status:"experimental",props:{label:{kind:"string",description:`The headline, saying what is empty in a few words: "No one matches these filters". The region's accessible name.`,required:!0},description:{kind:"string",description:"One sentence of explanation or next step. Carried as the description part."},action:{kind:"object",description:"The one way out, as data: { label, onSelect?, href? }. An href renders a Link, otherwise a Button that registers its own press tool, so the action is a single control in the agent view."},reason:{kind:"enum",description:"Why it is empty: nothing exists yet, or nothing matches the current filters.",values:["empty","filtered"],default:"empty"}},state:{empty:{description:"Always present, so one selector finds every empty region.",attribute:"data-sprint-empty"},reason:{description:"Why the region is empty.",attribute:"data-sprint-reason",values:["empty","filtered"]}},agentView:{example:'- **EmptyState** "No one matches these filters" [empty, reason=filtered]\n - part `description` "Try a different role or clear the search."'},examples:[{title:"Nothing matches",description:"Records exist but the filters exclude them all. The action is a Button, so it registers press-clear-filters.",code:`<EmptyState
|
|
203
267
|
reason="filtered"
|
|
204
268
|
label="No one matches these filters"
|
|
205
269
|
description="Try a different role or clear the search."
|
|
@@ -208,9 +272,9 @@ ${P.current([N.current])}`:"The change removed this disclosure from the page."},
|
|
|
208
272
|
label="No projects yet"
|
|
209
273
|
description="Projects you create or are invited to appear here."
|
|
210
274
|
action={{ label: "Create a project", href: "#/projects/new" }}
|
|
211
|
-
/>`},{title:"Just the headline",code:'<EmptyState label="No notifications" />'}],a11y:{role:"group",notes:"The headline names the group and the description describes it. The action is an ordinary Button or Link inside it, reached in normal tab order."},relatedComponents:["Pending","Alert","Button","Link"]});function
|
|
275
|
+
/>`},{title:"Just the headline",code:'<EmptyState label="No notifications" />'}],a11y:{role:"group",notes:"The headline names the group and the description describes it. The action is an ordinary Button or Link inside it, reached in normal tab order."},relatedComponents:["Pending","Alert","Button","Link"]});function Fi(e){const{action:t}=e;return t.href!==void 0?a.jsx(qa,{href:t.href,onClick:t.onSelect,children:t.label}):a.jsx(dt,{onClick:t.onSelect,children:t.label})}function Hi(e){const{label:t,description:n,action:o,reason:s="empty",...r}=e,l=Z(),d=i.useId(),c=n===void 0?[]:[{part:"description",label:n,state:{}}],h=q({component:Wa.name,label:t,state:{empty:!0,reason:s},parts:c}),g=o===void 0?null:a.jsx(Fi,{action:o});if(l==="agent")return a.jsx(te,{node:h,children:g});const u=`${d}-label`,b=`${d}-description`;return a.jsx("div",{...r,...X(h),role:"group","aria-labelledby":u,"aria-describedby":n===void 0?void 0:b,children:a.jsxs("div",{children:[a.jsx("p",{id:u,children:t}),n===void 0?null:a.jsx("p",{id:b,...B({part:"description",state:{}}),children:n}),g]})})}const Ba=Y({name:"Tag",category:"display",summary:"A small chip that classifies the thing next to it: a status, a category, a count, a build string.",whenToUse:"Use it for a short classification a person scans and an agent reads off the tone attribute, such as a release status, a read-only or write marker on a tool, or a version chip.",whenNotToUse:"Do not use it for anything clickable; a Tag is inert, and a chip that acts is a Button. Do not put a sentence in one.",status:"experimental",props:{children:{kind:"node",description:"The chip text. One or two words.",required:!0},tone:{kind:"enum",description:"What class of thing this is. Acid is rationed, so reach for info or inert before action.",values:["neutral","action","danger","info","warning","inert"],default:"neutral"},filled:{kind:"boolean",description:"Render as a solid field of the tone with inverted ink, instead of a keyline. Use for the one chip that must be read first.",default:!1},provisional:{kind:"boolean",description:"Draw a dashed keyline for something that is not real yet: a draft, a scenario, a proposed change. It reads as provisional to agents too.",default:!1}},state:{tone:{description:"The class of thing the chip marks.",attribute:"data-sprint-tone",values:["neutral","action","danger","info","warning","inert"]},filled:{description:"Present when the chip is a solid field rather than a keyline.",attribute:"data-sprint-filled"},provisional:{description:"Present on a chip for something that is not real yet.",attribute:"data-sprint-provisional"}},agentView:{example:'- **Tag** "experimental" [filled, tone=warning]'},examples:[{title:"A provisional chip",description:"A dashed keyline separates a scenario from the live roster without spending a colour.",code:'<Tag tone="info" provisional>Scenario: fall reshuffle</Tag>'},{title:"A release status",code:'<Tag tone="warning" filled>experimental</Tag>'},{title:"A category chip",code:"<Tag>action</Tag>"},{title:"Read-only against changes-state",description:"Two tones doing the work a legend would otherwise have to do in prose.",code:`<Tag tone={tool.readOnly ? "info" : "danger"}>
|
|
212
276
|
{tool.readOnly ? "read only" : "changes state"}
|
|
213
|
-
</Tag>`}]});function
|
|
277
|
+
</Tag>`}]});function _a(e){const{tone:t="neutral",filled:n=!1,provisional:o=!1,children:s,...r}=e,l=Z(),d=q({component:Ba.name,label:be(s),state:{tone:t,filled:n,provisional:o}});return l==="agent"?a.jsx(te,{node:d}):a.jsx("span",{...r,...X(d),children:s})}const Rn={verb:"open",description:"Open this row, exactly as a person clicking it would. What opening does is the row's own business: it may select the record, reveal its detail, or start a flow. Returns the row's state after the click.",inputSchema:{type:"object",properties:{}},readOnly:!1,untrustedContent:!0,registeredWhen:"The row acts rather than navigates, is mounted, enabled, has a resolvable title, and no other component claims the same tool name.",unregisteredWhen:"The row unmounts, becomes disabled, or turns into a link by taking an href."},Xt=Y({name:"EntityRow",category:"display",summary:"One record in a list of records, as a single clickable row: a title, a few Tags, and one line of meta. Give it an href and the whole row is a link; give it onSelect and it is an action that registers an open tool.",whenToUse:'Use it for a list of people, projects, or anything else a person scans and picks one of, where each entry needs a name, a classification, and a line of context such as last activity. Stack several in a Stack with gap="none" and adjacent rows share their keylines. The title is the accessible name, so it is also what an agent selects on.',whenNotToUse:"Do not use it when the entries are compared column by column; that is a Table. Do not use it for a catalogue entry with a paragraph of body; that is a Card. Do not put controls in it: the whole row is already one link or button, so tags and meta are data, not components.",status:"experimental",props:{title:{kind:"string",description:"The record's name, and the row's accessible name. Also derives the tool name when the row acts.",required:!0},href:{kind:"string",description:"Destination, which makes the whole row a link. A row that navigates registers no tool by default, because an agent can follow the href itself."},onSelect:{kind:"handler",description:"What clicking does, called with the click event. Alone it makes the row a button that registers an open tool by default. Alongside href the row stays a link and the handler rides the click, so a router can call preventDefault."},tags:{kind:"array",description:"Classifications rendered as Tags after the title: { label, tone? }, where tone is one of the Tag tones. Carried as Tag lines under the row in the agent view."},meta:{kind:"array",description:"One line of context, each entry a string or { term?, detail }, joined with a middle dot. Truncates rather than wraps when the row is short of room. Carried as the meta part."},description:{kind:"string",description:"An optional sentence under the row, for a record that needs more than a line of meta. Carried as the description part."},disabled:{kind:"boolean",description:"Disable an acting row and unregister its tool. Has no effect on a row that navigates or does nothing.",default:!1},agentTool:{kind:"boolean",description:"Override the default: on for a row that acts, off for a row that navigates. A row with neither href nor onSelect never registers one."},agentName:{kind:"string",description:"Override the title used to derive the tool name, when two rows share a title."}},state:{href:{description:"Where the row goes, when it navigates.",attribute:"data-sprint-href"},disabled:{description:"Present when an acting row cannot be opened.",attribute:"data-sprint-disabled"}},tools:{open:Rn},agentView:{example:'- **EntityRow** "Ada Lovelace" [href=#/people/ada]\n - part `title` "Ada Lovelace"\n - part `meta` "Last sign-in: 3 days ago · 2 apps"\n - **Tag** "admin" [tone=info]\n - **Tag** "billing" [tone=neutral]'},examples:[{title:"A person in a directory",description:"A row that navigates. No tool, because the href is already public; tags and meta are data.",code:`<EntityRow
|
|
214
278
|
title="Ada Lovelace"
|
|
215
279
|
href="#/people/ada"
|
|
216
280
|
tags={[{ label: "admin", tone: "info" }, { label: "billing" }]}
|
|
@@ -236,8 +300,8 @@ ${P.current([N.current])}`:"The change removed this disclosure from the page."},
|
|
|
236
300
|
tags={[{ label: "degraded", tone: "danger" }]}
|
|
237
301
|
meta={["Updated 4 min ago"]}
|
|
238
302
|
description="Card authorisations are timing out in eu-west."
|
|
239
|
-
/>`}],a11y:{notes:"The whole row is one control: a link with an href, a button with onSelect, or a labelled group with neither. The title is the accessible name, and the tags, meta, and description are its accessible description, so a screen reader announces the name first and the context after."},relatedComponents:["Card","Tag","Stack","Table"]}),
|
|
240
|
-
${
|
|
303
|
+
/>`}],a11y:{notes:"The whole row is one control: a link with an href, a button with onSelect, or a labelled group with neither. The title is the accessible name, and the tags, meta, and description are its accessible description, so a screen reader announces the name first and the context after."},relatedComponents:["Card","Tag","Stack","Table"]}),Hn=" · ";function Yt(e){return typeof e=="string"?e:e.term===void 0?e.detail:`${e.term}: ${e.detail}`}function Vi(e,t){return`${t}-${Yt(e)}`}function zi(e){const{title:t,href:n,onSelect:o,tags:s=[],meta:r=[],description:l,disabled:d=!1,agentTool:c,agentName:h,ref:g,...u}=e,b=Z(),m=ue(),S=ce(),f=i.useId(),y=n!==void 0,k=!y&&o!==void 0,T=k&&d,O=i.useRef(null),A=i.useCallback(v=>{O.current=v,typeof g=="function"?g(v):g!=null&&(g.current=v)},[g]),E=i.useRef(S);E.current=S;const D=i.useRef(q({component:Xt.name})),U=i.useRef(!0);i.useEffect(()=>(U.current=!0,()=>{U.current=!1}),[]);const N=i.useCallback(async()=>{const v=O.current;return v===null?"This row renders no control in the current view.":(v.click(),await pe(),U.current?`Opened. The row is now:
|
|
304
|
+
${E.current([D.current])}`:"Opening removed this row from the page.")},[]),W=de({spec:Rn,label:h??t,enabled:(c??k)&&(y||k)&&!T,execute:N}),$=r.length===0?void 0:r.map(Yt).join(Hn),_=[{part:"title",label:t,state:{}},...$===void 0?[]:[{part:"meta",label:$,state:{}}],...l===void 0?[]:[{part:"description",label:l,state:{}}]],V=q({component:Xt.name,label:t,tool:W,state:{href:n,disabled:T},parts:_});D.current=V;const M=s.map((v,K)=>a.jsx(_a,{tone:v.tone??"neutral",children:v.label},`${K}-${v.label}`));if(b==="agent")return!(y||k)||T||m==="never"?a.jsx(te,{node:V,children:M}):a.jsx(ze,{node:V,as:y?"a":"button",href:n,ref:A,onClick:o,children:M});const I=`${f}-title`,j=`${f}-tags`,z=`${f}-meta`,L=`${f}-description`,p=[s.length===0?void 0:j,$===void 0?void 0:z,l===void 0?void 0:L].filter(v=>v!==void 0).join(" "),x={"aria-labelledby":I,"aria-describedby":p===""?void 0:p},P=a.jsxs(a.Fragment,{children:[a.jsx("span",{id:I,...B({part:"title",state:{}}),children:t}),s.length===0?null:a.jsx("span",{id:j,children:M}),$===void 0?null:a.jsx("span",{id:z,...B({part:"meta",state:{}}),children:r.map((v,K)=>a.jsxs(i.Fragment,{children:[K>0?Hn:null,typeof v=="string"||v.term===void 0?a.jsx("span",{children:Yt(v)}):a.jsxs("span",{children:[a.jsxs("span",{children:[v.term,": "]}),a.jsx("span",{children:v.detail})]})]},Vi(v,K)))}),l===void 0?null:a.jsx("span",{id:L,...B({part:"description",state:{}}),children:l})]});return y?a.jsx("a",{...u,...X(V),...x,href:n,onClick:o,ref:A,children:P}):k?a.jsx("button",{...u,...X(V),...x,type:"button",disabled:d,onClick:o,ref:A,children:P}):a.jsx("div",{...u,...X(V),...x,role:"group",ref:A,children:P})}const Fa=Y({name:"Heading",category:"typography",summary:"A section title, rendered as a real h element at the level you pick so it joins the document outline.",whenToUse:"Use it for the title of a page or of a region inside one, and keep levels in document order so the outline an agent or a screen reader builds is the outline you meant.",whenNotToUse:"Do not use it for the label on a bordered region; Panel takes a label prop, draws its own header, and joins the outline through its headingLevel prop. Do not pick a level for its size, only for its place in the outline.",status:"experimental",props:{children:{kind:"node",description:"The title. Keep it short; long titles truncate in chrome.",required:!0},level:{kind:"enum",description:"Outline depth, rendered as the matching h element. 1 is the page title and there should be one per page. 5 and 6 take the level-4 voice unless size says otherwise.",values:["1","2","3","4","5","6"],default:"2"},size:{kind:"enum",description:"The type voice, from 1 (display) to 4 (smallest), when it should differ from the level. Use it when a heading's place in the outline and its visual weight disagree, such as a level-2 title inside a dense card that should read small.",values:["1","2","3","4"]}},state:{level:{description:"The outline depth, and so the type voice in use.",attribute:"data-sprint-level",values:["1","2","3","4","5","6"]},size:{description:"The type voice, present only when it differs from the level.",attribute:"data-sprint-size",values:["1","2","3","4"]}},agentView:{example:'- **Heading** "WebMCP tools" [level=2]'},examples:[{title:"A page title",code:"<Heading level={1}>Button</Heading>"},{title:"A section title",description:"The default level, for a region inside a page.",code:"<Heading>Every variant</Heading>"},{title:"A deep heading in a small voice",description:"The outline needs a level-3 heading, but inside a compact card it should read at the smallest size.",code:"<Heading level={3} size={4}>Sunday speakers</Heading>"}]});function Gi(e){const{level:t=2,size:n,children:o,...s}=e,r=Z(),l=q({component:Fa.name,label:be(o),state:{level:String(t),size:n===void 0||n===t?void 0:String(n)}});if(r==="agent")return a.jsx(te,{node:l});const d=`h${t}`;return a.jsx(d,{...s,...X(l),children:o})}const Ha=Y({name:"Image",category:"display",summary:"A framed picture in a slot that holds its shape. It is the one component whose content an agent cannot read, so alt is not decoration: it is the whole of what the agent gets, and the source URL is published beside it for an agent that can fetch pixels of its own.",whenToUse:'Use it for any picture that carries meaning: a screenshot, a diagram, a photograph, a logo in running content. Describe it in alt as if to someone on the phone. Pass alt="" only for a picture that adds nothing, which then disappears from the agent view entirely.',whenNotToUse:"Do not use it for a decorative texture; that is the ornament vocabulary, which costs no request and no description. Do not use it for an icon whose meaning is already in adjacent text.",status:"experimental",props:{src:{kind:"string",description:"Where the pixels are. Published as data-sprint-src so an agent that can see can fetch the file itself.",required:!0},alt:{kind:"string",description:'What the picture shows, in a sentence. This is the entire agent rendering of the image, so write it for a reader who will never see it. Empty means "this picture carries no meaning", and the component then renders nothing in agent view.',required:!0},caption:{kind:"string",description:"A visible line under the frame, for a credit, a date, or a figure number. It is read as well as seen, so it does not repeat alt."},ratio:{kind:"enum",description:"The shape the slot holds while the picture loads and if it fails. auto lets the file decide its own height once it arrives.",values:["1:1","4:3","3:2","16:9","auto"],default:"auto"},fit:{kind:"enum",description:"How the picture fills a slot of a fixed ratio. cover crops it, contain letterboxes it. Ignored when ratio is auto.",values:["cover","contain"],default:"cover"}},state:{src:{description:"The image source, so an agent can fetch the file without the DOM.",attribute:"data-sprint-src"},status:{description:"Whether the pixels have arrived. Present only in the human rendering, because in agent view nothing is fetched and any value would be a guess.",attribute:"data-sprint-status",values:["loading","ready","error"]},ratio:{description:"The shape the slot holds.",attribute:"data-sprint-ratio",values:["1:1","4:3","3:2","16:9","auto"]},fit:{description:"Whether a fixed-ratio slot crops the picture or letterboxes it.",attribute:"data-sprint-fit",values:["cover","contain"]},decorative:{description:"Present when the image was declared meaningless with an empty alt and no caption. It renders nothing at all in agent view.",attribute:"data-sprint-decorative"}},agentView:{example:'- **Image** "Launch pad 39B under floodlights, gantry retracted" [fit=cover, ratio=16:9, src=media/pad-39b.svg]\n - part `caption` "Pad 39B, T-minus 4h"'},examples:[{title:"A described picture",description:"The alt text is the agent rendering. It registers no WebMCP tool: there is nothing to do to a picture, and the source URL is already on the element.",code:`<Image
|
|
241
305
|
src="media/pad-39b.svg"
|
|
242
306
|
alt="Launch pad 39B under floodlights, gantry retracted"
|
|
243
307
|
ratio="16:9"
|
|
@@ -247,7 +311,7 @@ ${A.current([P.current])}`:"Opening removed this row from the page.")},[]),_=te(
|
|
|
247
311
|
caption="Static fire 04, chamber pressure"
|
|
248
312
|
ratio="3:2"
|
|
249
313
|
fit="contain"
|
|
250
|
-
/>`},{title:"A picture that means nothing",description:"An empty alt is a claim, not an omission: it says this picture carries no meaning. The component then renders nothing in agent view, the way Stack does.",code:'<Image src="media/grain.svg" alt="" ratio="1:1" />'}],a11y:{notes:"The frame is a figure named by its alt text, and the picture inside carries the same alt natively, so a fallback still reads when the file fails. A caption is a figcaption. While the picture is loading or after it has failed, the slot keeps its border and states its condition rather than collapsing; that band is aria-hidden, because on failure it shows the alt text a screen reader has already been given."},relatedComponents:["Card","Panel"]});function
|
|
314
|
+
/>`},{title:"A picture that means nothing",description:"An empty alt is a claim, not an omission: it says this picture carries no meaning. The component then renders nothing in agent view, the way Stack does.",code:'<Image src="media/grain.svg" alt="" ratio="1:1" />'}],a11y:{notes:"The frame is a figure named by its alt text, and the picture inside carries the same alt natively, so a fallback still reads when the file fails. A caption is a figcaption. While the picture is loading or after it has failed, the slot keeps its border and states its condition rather than collapsing; that band is aria-hidden, because on failure it shows the alt text a screen reader has already been given."},relatedComponents:["Card","Panel"]});function Ki(e){const{src:t,alt:n,caption:o,ratio:s="auto",fit:r="cover",...l}=e,d=Z(),[c,h]=i.useState("loading"),g=n===""&&o===void 0,u=o===void 0?[]:[{part:"caption",label:o,state:{}}],b=q({component:Ha.name,label:n===""?void 0:n,state:{src:t,ratio:s,fit:r,decorative:g,status:d==="agent"?void 0:c},parts:u});if(d==="agent")return g?null:a.jsx(te,{node:b});const m=c==="error"?n===""?"Image unavailable":n:"Loading";return a.jsxs("figure",{...l,...X(b),"aria-label":n===""?void 0:n,children:[a.jsxs("div",{children:[a.jsx("img",{src:t,alt:n,onLoad:()=>h("ready"),onError:()=>h("error")}),c==="ready"?null:a.jsx("span",{"aria-hidden":"true",children:a.jsx("span",{children:m})})]}),o===void 0?null:a.jsx("figcaption",{...B({part:"caption",state:{}}),children:o})]})}const Va=Y({name:"Kbd",category:"typography",summary:"A keyboard key or shortcut, drawn as key caps. Pass the combination as text joined with plus signs.",whenToUse:`Use to tell a person which keys do something: an undo hint in a toast, a shortcut beside a menu item's description, a search field's focus key. Write the combination as one string, such as "Ctrl+Z" or "Shift+Enter"; each part becomes its own cap.`,whenNotToUse:"Do not use for code or for a value someone types into a field; that is code or a CodeBlock. Do not use it as a control; it does not press anything.",status:"experimental",props:{children:{kind:"string",description:'The keys, joined with "+", such as "Ctrl+Z". A lone "+" is a key in its own right.',required:!0}},agentView:{example:'- **Kbd** "Ctrl+Z"'},examples:[{title:"An undo shortcut",code:"<Kbd>Ctrl+Z</Kbd>"},{title:"A single key",description:"One key is one cap.",code:"<Kbd>/</Kbd>"}],a11y:{notes:"A kbd element nesting one kbd per key, which is the HTML pattern for a key combination. The plus signs between caps are hidden from assistive technology, which reads the keys in order."}});function Qi(e){const t=[];let n="";for(const o of e)o==="+"&&n!==""?(t.push(n.trim()),n=""):n+=o;return n!==""&&t.push(n.trim()),t.filter(o=>o!=="")}function za(e){const{children:t,...n}=e,o=Z(),s=Qi(t),r=q({component:Va.name,label:s.join("+")});return o==="agent"?a.jsx(te,{node:r}):a.jsx("kbd",{...n,...X(r),children:s.map((l,d)=>a.jsxs(i.Fragment,{children:[d===0?null:a.jsx("span",{"aria-hidden":"true",children:"+"}),a.jsx("kbd",{children:l})]},`${l}-${d}`))})}const Ga=Y({name:"List",category:"display",summary:"A bulleted or numbered list built from an array of items. Each item is an addressable part carrying its position, so an agent can cite item three without counting lines.",whenToUse:"Use it for a short sequence of related points: rules, steps, links, caveats. Passing items as data rather than as children is what lets the agent view carry each one as its own part.",whenNotToUse:"Do not use it for a diff or a review of what will change, where each mark means added or removed; that is ChangeList. Do not use it for records with fields; that is Table. Do not use it as a layout for cards or controls; that is Stack.",status:"experimental",props:{label:{kind:"string",description:"What the list is a list of. Names it for a screen reader and for the agent view.",required:!0},items:{kind:"array",description:"The items in order. Inline content, not components: each is flattened to text for the agent view.",required:!0},ordered:{kind:"boolean",description:"Number the items instead of bulleting them. Use it when the order is the point.",default:!1},marker:{kind:"enum",description:'The mark before each item. "plus" is the house bullet, "bullet" a plain dot for quieter prose, "number" counts the items and makes the list ordered, "none" drops the marker column for a list whose items already lead with their own mark. Defaults to "number" when ordered is set and "plus" otherwise. The marker is drawn, not read: an item whose mark means something, such as added or removed, belongs in a ChangeList.',values:["plus","bullet","number","none"],default:"plus"},emptyLabel:{kind:"string",description:"What the list says when it has no items.",default:"Empty"},loading:{kind:"boolean",description:"Set while the items are being fetched. Sets aria-busy and sweeps a bar along the top edge. Existing items stay visible; with none yet, the empty slot says loadingLabel instead of emptyLabel.",default:!1},loadingLabel:{kind:"string",description:"What the empty slot says while loading.",default:"Loading"}},state:{items:{description:"How many items the list has.",attribute:"data-sprint-items"},ordered:{description:"Present when the list is a real ol: ordered is set, or the marker is number.",attribute:"data-sprint-ordered"},marker:{description:"The mark drawn before each item.",attribute:"data-sprint-marker",values:["plus","bullet","number","none"]},empty:{description:"Present when the list has no items.",attribute:"data-sprint-empty"},loading:{description:"Present while the items are being fetched. Alongside empty it means nothing has arrived yet, not that there is nothing.",attribute:"data-sprint-loading"},index:{description:"On an item: its 1-based position in the list.",attribute:"data-sprint-index"}},agentView:{example:'- **List** "Tool rules" [items=1, marker=plus]\n - part `item` "One tool, one action." [index=1]'},examples:[{title:"A list of rules",code:`<List
|
|
251
315
|
label="Tool rules"
|
|
252
316
|
items={[
|
|
253
317
|
<>
|
|
@@ -267,7 +331,34 @@ ${A.current([P.current])}`:"Opening removed this row from the page.")},[]),_=te(
|
|
|
267
331
|
marker="none"
|
|
268
332
|
label="Related"
|
|
269
333
|
items={["Table for records.", "Stack for layout."]}
|
|
270
|
-
/>`}],a11y:{role:"list",notes:"A real ul or ol named by its label, with an explicit list role because the custom markers require list-style none and Safari would otherwise drop the list semantics. The item count is announced, and the markers are drawn as pseudo-elements, so a marker never carries meaning a screen reader would miss."}});function
|
|
334
|
+
/>`}],a11y:{role:"list",notes:"A real ul or ol named by its label, with an explicit list role because the custom markers require list-style none and Safari would otherwise drop the list semantics. The item count is announced, and the markers are drawn as pseudo-elements, so a marker never carries meaning a screen reader would miss."}});function Xi(e){const{label:t,items:n,ordered:o=!1,marker:s,emptyLabel:r="Empty",loading:l=!1,loadingLabel:d="Loading",...c}=e,h=Z(),g=s??(o?"number":"plus"),u=o||g==="number",b=n.length===0,m=n.map((y,k)=>{const T=be(y);return{part:"item",state:{index:String(k+1)},...T===void 0?{}:{label:T}}}),S=q({component:Ga.name,label:t,state:{items:String(n.length),ordered:u,marker:g,empty:b,loading:l},parts:m});if(h==="agent")return a.jsx(te,{node:S});const f=u?"ol":"ul";return a.jsx(f,{...c,...X(S),role:"list","aria-label":t,"aria-busy":l||void 0,children:b?a.jsx("li",{children:l?d:r}):n.map((y,k)=>a.jsx("li",{...B({part:"item",state:{index:String(k+1)}}),children:a.jsx("span",{children:y})},`${k}-${String(be(y))}`))})}const Qe={verb:"choose",description:"Choose one item from this menu by its visible label, exactly as a person opening the menu and pressing the item would. The menu does not need to be open. Items that are links are not offered; reach them by their href. Returns the menu's state after the choice, so a follow-up read is usually unnecessary.",inputSchema:{type:"object",properties:{item:{type:"string",description:"The visible label of the item to choose."}},required:["item"]},readOnly:!1,untrustedContent:!0,registeredWhen:"The menu is mounted and enabled, has at least one enabled item without an href, and no other component claims the same tool name. The registered schema enumerates those items' labels.",unregisteredWhen:"The menu unmounts, becomes disabled, or its last enabled item without an href is removed or disabled."},Zt=Y({name:"Menu",category:"action",summary:"A button that opens a short list of actions, links, or one-of-several choices. Registers one choose tool enumerating the items an agent can run.",whenToUse:"Use to gather secondary actions behind one control: a card's edit, duplicate and delete; an account menu; a share menu; a switcher between a few named views. Items hold data, not elements: each is { label, onSelect?, href?, checked?, tone?, disabled?, group?, icon? }. An item with checked becomes a radio choice with a visible mark, so a menu can also pick one value from a short list.",whenNotToUse:"Do not use for the primary action of a view; that is a Button. Do not use to pick a form value that is submitted with other fields; that is a Select or a SegmentedControl. Do not use for navigation that should stay visible; that is a Nav or a Breadcrumb. Items take plain text labels and an optional icon, never components.",status:"experimental",props:{label:{kind:"string",description:`What the menu holds, such as "Card actions" or "Share". It is the trigger's text, names the menu for assistive technology, and derives the choose tool name.`,required:!0},items:{kind:"array",description:'The items in order: { label, onSelect?, href?, external?, checked?, tone?, disabled?, group?, icon? }. onSelect runs the item; href makes it a link, which agents reach by URL rather than the tool. checked, true or false, makes the item a radio choice. tone="danger" marks a destructive item. Consecutive items sharing a group string are gathered under that heading.',required:!0},icon:{kind:"node",description:"An icon drawn on the trigger before its label."},hideLabel:{kind:"boolean",description:"Show only the icon on a square trigger, such as a three-dot card menu. The label stays the accessible name and the tool name, and shows as a tooltip. Requires icon.",default:!1},size:{kind:"enum",description:"The trigger's size, matching Button.",values:["medium","small"],default:"medium"},align:{kind:"enum",description:"Which edge of the trigger the list lines up with. Use end for a menu at the right of a card or a toolbar.",values:["start","center","end"],default:"start"},side:{kind:"enum",description:"Where the list prefers to open. It flips to the other side when there is no room, so a menu low on the screen still opens fully in view.",values:["below","above"],default:"below"},disabled:{kind:"boolean",description:"Disable the trigger and unregister the choose tool.",default:!1},onOpenChange:{kind:"handler",description:"Called with true when the list opens and false when it closes."},agentName:{kind:"string",description:"Override the label used to derive the tool name, such as when every card on a page has a menu called Actions."},agentTool:{kind:"boolean",description:"Set false to render the menu without registering the choose tool.",default:!0}},state:{open:{description:"Present while the list is open on screen.",attribute:"data-sprint-open"},disabled:{description:"Present when the menu cannot be opened.",attribute:"data-sprint-disabled"}},tools:{choose:Qe},agentView:{example:'- **Menu** "Card actions" → tool `choose-card-actions`\n - part `item` "Edit"\n - part `item` "Delete" [tone=danger]'},examples:[{title:"Card actions",description:"A three-dot trigger at the end of a card. The destructive item is marked, and an agent runs either item through the choose tool without opening anything.",code:`<Menu
|
|
335
|
+
label="Card actions"
|
|
336
|
+
icon={<MoreIcon />}
|
|
337
|
+
hideLabel
|
|
338
|
+
size="small"
|
|
339
|
+
align="end"
|
|
340
|
+
items={[
|
|
341
|
+
{ label: "Edit", onSelect: edit },
|
|
342
|
+
{ label: "Duplicate", onSelect: duplicate },
|
|
343
|
+
{ label: "Delete", tone: "danger", onSelect: remove },
|
|
344
|
+
]}
|
|
345
|
+
/>`},{title:"Links and actions together",description:"An item with href is a real link and is left out of the tool, because a URL already reaches it. Groups gather related items under a heading.",code:`<Menu
|
|
346
|
+
label="Account"
|
|
347
|
+
items={[
|
|
348
|
+
{ label: "Profile", href: "#/profile", group: "Signed in as Nomad" },
|
|
349
|
+
{ label: "Settings", href: "#/settings", group: "Signed in as Nomad" },
|
|
350
|
+
{ label: "Sign out", onSelect: signOut },
|
|
351
|
+
]}
|
|
352
|
+
/>`},{title:"Choosing one of several",description:"checked turns items into radio choices with a visible mark, so the menu doubles as a compact picker. It opens with focus on the checked item.",code:`<Menu
|
|
353
|
+
label={plannerLabel}
|
|
354
|
+
agentName="Planner"
|
|
355
|
+
items={planners.map((name) => ({
|
|
356
|
+
label: name,
|
|
357
|
+
checked: name === planner,
|
|
358
|
+
onSelect: () => setPlanner(name),
|
|
359
|
+
}))}
|
|
360
|
+
/>`}],a11y:{role:"menu",keyboard:["Enter, Space or Down Arrow on the trigger opens the list on the first or checked item","Up Arrow on the trigger opens it on the last item","Arrow keys move between items and wrap","Home and End move to the first and last item","A letter moves to the next item starting with it","Escape closes the list and returns focus to the trigger","Tab closes the list and moves on"],notes:"The trigger has aria-haspopup=menu and aria-expanded. Items are menuitem buttons or links, or menuitemradio with aria-checked. The list is a popover in the top layer rendered inside the menu's own DOM, so it opens above a modal Dialog and is never clipped by an ancestor's overflow. Disabled items are skipped by the keyboard."}});function Yi(e){const t=[];return e.forEach((n,o)=>{const s=t.at(-1);s!==void 0&&s.group===n.group?s.entries.push({item:n,index:o}):t.push({group:n.group,entries:[{item:n,index:o}]})}),t}function vt(e){return e.href===void 0&&e.disabled!==!0}function Zi(e){const t=Qe.inputSchema.properties.item;return{...Qe.inputSchema,properties:{...Qe.inputSchema.properties,...t===void 0?{}:{item:{...t,enum:[...e]}}}}}function Ji(e){return{part:"item",label:e.label,state:{...e.group===void 0?{}:{group:e.group},...e.checked===!0?{checked:!0}:{},...e.tone==="danger"?{tone:"danger"}:{},...e.href===void 0?{}:{href:e.href},...e.external===!0?{external:!0}:{},...e.disabled===!0?{disabled:!0}:{}}}}function es(e){const{label:t,items:n,icon:o,hideLabel:s=!1,size:r="medium",align:l="start",side:d="below",disabled:c=!1,onOpenChange:h,agentName:g,agentTool:u=!0,ref:b,...m}=e,S=Z(),f=ue(),y=ce(),k=i.useId(),[T,O]=i.useState(!1),[A,E]=i.useState(-1),D=i.useRef(null),U=i.useRef(null),N=i.useRef(null),W=i.useRef(new Map),$=i.useRef(n);$.current=n;const _=i.useRef(y);_.current=y;const V=i.useRef(h);V.current=h;const M=i.useRef(q({component:Zt.name})),I=i.useRef(!0);i.useEffect(()=>(I.current=!0,()=>{I.current=!1}),[]);const j=i.useMemo(()=>n.flatMap((R,F)=>R.disabled===!0?[]:[F]),[n]),z=i.useCallback(R=>{O(F=>(F!==R&&V.current?.(R),R))},[]),L=i.useCallback(R=>{z(!1),E(-1),R&&U.current?.focus()},[z]),p=i.useCallback(()=>L(!1),[L]),x=i.useCallback(R=>{if(c||j.length===0)return;const F=j.find(le=>n[le]?.checked===!0),oe=R==="last"?j.at(-1):R==="checked"&&F!==void 0?F:j[0];E(oe??-1),z(!0)},[c,j,n,z]);i.useEffect(()=>{c&&L(!1)},[c,L]),pt({open:T,anchor:U,floating:N,side:d,align:l,boundary:D,onDismiss:p}),i.useLayoutEffect(()=>{!T||A<0||W.current.get(A)?.focus()},[T,A]);const P=i.useCallback(R=>{const F=$.current[R];F===void 0||F.disabled===!0||(L(!0),F.onSelect?.())},[L]),v=i.useCallback(R=>{const F=W.current.get(R);if(F!==void 0){F.click();return}const oe=$.current[R];oe?.onSelect!==void 0&&me(()=>oe.onSelect?.())},[]),K=i.useCallback(async R=>{const F=typeof R.item=="string"?R.item:"",oe=$.current,le=oe.findIndex(Oe=>Oe.label===F),ye=oe.filter(vt).map(Oe=>`"${Oe.label}"`),je=oe[le];return je===void 0||!vt(je)?`No item named "${F}" can be chosen. This menu offers: ${ye.join(", ")}.`:(v(le),await pe(),I.current?`Chosen. The menu is now:
|
|
361
|
+
${_.current([M.current])}`:"The choice removed this menu from the page.")},[v]),ne=i.useMemo(()=>n.filter(vt).map(R=>R.label),[n]),se=i.useMemo(()=>Zi(ne),[ne]),re=de({spec:Qe,label:g??t,inputSchema:se,enabled:u&&!c&&ne.length>0,execute:K}),he=n.map(Ji),we=q({component:Zt.name,label:t,tool:re,state:{open:T,disabled:c},parts:he});if(M.current=we,S==="agent")return c||f==="never"?a.jsx(te,{node:we}):a.jsx(ke,{node:we,isActionable:(R,F)=>{const oe=n[F];return oe!==void 0&&vt(oe)},onActivate:(R,F)=>v(F)});const Ce=`${k}-trigger`,Se=`${k}-menu`,fe=(R,F)=>{if(j.length===0)return;const oe=j.indexOf(R),le=oe<0?0:(oe+F+j.length)%j.length;return j[le]},Pe=(R,F)=>{const oe=F.toLowerCase(),le=Math.max(j.indexOf(R),0);for(let ye=1;ye<=j.length;ye+=1){const je=j[(le+ye)%j.length];if(je!==void 0&&n[je]?.label.toLowerCase().startsWith(oe))return je}},ve=R=>{R.key==="ArrowDown"||R.key==="Enter"||R.key===" "?(R.preventDefault(),x("checked")):R.key==="ArrowUp"&&(R.preventDefault(),x("last"))},xe=R=>{const F=R.key;if(F==="Escape"){R.preventDefault(),R.stopPropagation(),L(!0);return}if(F==="Tab"){L(!1);return}const oe=F==="ArrowDown"?fe(A,1):F==="ArrowUp"?fe(A,-1):F==="Home"?j[0]:F==="End"?j.at(-1):F.length===1&&!R.altKey&&!R.ctrlKey&&!R.metaKey?Pe(A,F):void 0;if(F===" "){const le=W.current.get(A);le instanceof HTMLAnchorElement&&(R.preventDefault(),le.click());return}oe!==void 0&&(R.preventDefault(),E(oe),W.current.get(oe)?.focus())},Ae=R=>F=>{F===null?W.current.delete(R):W.current.set(R,F)},C=(R,F)=>{const oe=R.checked!==void 0,le={...B(he[F]??{part:"item",state:{}}),role:oe?"menuitemradio":"menuitem",tabIndex:F===A?0:-1,...oe?{"aria-checked":R.checked===!0}:{},onFocus:()=>E(F)},ye=a.jsxs(a.Fragment,{children:[R.icon===void 0?null:a.jsx("span",{"data-sprint-icon":"","aria-hidden":"true",children:R.icon}),a.jsx("span",{children:R.label})]});return R.href!==void 0?a.jsx("a",{...le,ref:Ae(F),...R.disabled===!0?{"aria-disabled":!0}:{href:R.href,...R.external===!0?{target:"_blank",rel:"noopener noreferrer"}:{},onClick:()=>L(!1)},children:ye},F):a.jsx("button",{type:"button",...le,ref:Ae(F),disabled:R.disabled===!0,onClick:()=>P(F),children:ye},F)},ee=s&&o!==void 0,J=a.jsxs("button",{id:Ce,type:"button","data-sprint-control":"button",...r==="small"?{"data-sprint-size":"small"}:{},ref:U,disabled:c,"aria-haspopup":"menu","aria-expanded":T,"aria-controls":Se,onClick:()=>T?L(!1):x("checked"),onKeyDown:ve,children:[o===void 0?null:a.jsx("span",{"data-sprint-icon":"","aria-hidden":"true",children:o}),ee?a.jsx("span",{"data-sprint-visually-hidden":"",children:t}):t]});return a.jsxs("div",{...m,...X(we),ref:R=>{D.current=R,He(b,R)},children:[ee?a.jsx(yn,{label:t,describe:!1,disabled:T||c,children:J}):J,a.jsx("div",{popover:"manual",hidden:!T,ref:N,children:a.jsx("div",{id:Se,role:"menu","aria-labelledby":Ce,onKeyDown:xe,children:Yi(n).map((R,F)=>R.group===void 0?R.entries.map(({item:oe,index:le})=>C(oe,le)):a.jsxs("div",{role:"group","aria-labelledby":`${k}-group-${F}`,children:[a.jsx("span",{id:`${k}-group-${F}`,"aria-hidden":"true",children:R.group}),R.entries.map(({item:oe,index:le})=>C(oe,le))]},`${R.group}-${F}`))})})]})}const Ka=Y({name:"MetaLine",category:"display",summary:"A slash-separated manifest line of term–detail pairs: serials, build strings, issue dates. It is chrome, not content, and in the agent view it reads as the same single line of text a person sees.",whenToUse:"Use it for the compact strip of identifying metadata that belongs to a page, panel, or footer: version and build identifiers, timestamps, serial numbers, owners. Values are short. By default the line truncates with an ellipsis rather than wrapping; set wrap where it sits in a narrow container and every entry has to stay visible.",whenNotToUse:"Do not use it for the details of a record a person is meant to study; that is a DescriptionList. Do not put anything interactive in it, and do not use it for prose.",status:"experimental",props:{entries:{kind:"array",description:"Term–detail pairs in display order: { term, detail }, both strings. Rendered as TERM: DETAIL, slash-separated, and carried as one line in the agent view. An empty array renders nothing.",required:!0},wrap:{kind:"boolean",description:"Let entries flow onto further lines instead of truncating the line. Each entry stays whole on one line, and a separator stays at the end of the line it closes, so no line starts with a slash. An entry wider than the container is the only thing that still truncates.",default:!1}},state:{entries:{description:"How many term–detail pairs the line carries.",attribute:"data-sprint-entries"},wrap:{description:"Present when entries may flow onto further lines.",attribute:"data-sprint-wrap"}},agentView:{example:'- **MetaLine** "SERIAL: NU-TYPE-CORE-A1 / ISSUED: 2744.07.22" [entries=2]'},examples:[{title:"A build strip",description:"The manifest voice: uppercase mono, slash-separated, terms muted and details in ink.",code:`<MetaLine
|
|
271
362
|
entries={[
|
|
272
363
|
{ term: "Serial", detail: "NU-TYPE-CORE-A1" },
|
|
273
364
|
{ term: "Issued", detail: "2744.07.22" },
|
|
@@ -286,7 +377,7 @@ ${A.current([P.current])}`:"Opening removed this row from the page.")},[]),_=te(
|
|
|
286
377
|
{ term: "WebMCP", detail: "chrome 149" },
|
|
287
378
|
{ term: "Build", detail: "2744.07.22-a1" },
|
|
288
379
|
]}
|
|
289
|
-
/>`}],a11y:{role:"paragraph",notes:"The separators are real text, so the accessible name is the same line the agent view carries. Nothing in the line is interactive."}});function
|
|
380
|
+
/>`}],a11y:{role:"paragraph",notes:"The separators are real text, so the accessible name is the same line the agent view carries. Nothing in the line is interactive."}});function ts(e){const{entries:t,wrap:n=!1,...o}=e,s=Z();if(t.length===0)return null;const r=t.map(d=>`${d.term}: ${d.detail}`).join(" / "),l=q({component:Ka.name,label:r,state:{entries:String(t.length),wrap:n}});return s==="agent"?a.jsx(te,{node:l}):a.jsx("p",{...o,...X(l),children:t.map((d,c)=>a.jsxs(i.Fragment,{children:[c>0?" ":null,a.jsxs("span",{children:[a.jsxs("span",{children:[d.term,": "]}),a.jsx("span",{children:d.detail}),c<t.length-1?a.jsx("span",{children:" /"}):null]})]},`${d.term}-${c}`))})}const Qa=Y({name:"Nav",category:"navigation",summary:"A labelled navigation landmark: the region that holds a page's links to elsewhere.",whenToUse:"Use it around any set of links whose job is getting around the app: a sidebar, a table of contents, a footer link block. The label names the landmark, so a person navigating by landmark, a screen reader, and an agent reading the page all know these links are wayfinding rather than content. Group related links inside it with NavGroup.",whenNotToUse:"Do not use it for a link that sits inside prose; a bare Link is already readable there. Do not use it for a set of actions that stay on the page; those are Buttons in a Stack.",status:"experimental",props:{label:{kind:"string",description:"What this navigation is for. Rendered as the landmark's accessible name, so two navs on one page stay distinguishable.",required:!0},children:{kind:"node",description:"Link components, or NavGroup components wrapping them.",required:!0}},agentView:{example:'- **Nav** "Workbench"'},a11y:{role:"navigation",notes:"The label is the landmark's accessible name via aria-label. Active links inside it carry aria-current=page, so the current location is announced without any styling cue."},relatedComponents:["NavGroup","Link","Shell"],examples:[{title:"A grouped sidebar nav",description:"Each NavGroup names a cluster of destinations. The active link carries the current-page mark in every view.",code:`<Nav label="Docs">
|
|
290
381
|
<NavGroup label="Guides">
|
|
291
382
|
<Link href="#/guide/webmcp">WebMCP</Link>
|
|
292
383
|
</NavGroup>
|
|
@@ -297,14 +388,14 @@ ${A.current([P.current])}`:"Opening removed this row from the page.")},[]),_=te(
|
|
|
297
388
|
</Nav>`},{title:"A flat nav",description:"A short list of destinations needs no grouping.",code:`<Nav label="Site">
|
|
298
389
|
<Link href="#/">Home</Link>
|
|
299
390
|
<Link href="#/pricing">Pricing</Link>
|
|
300
|
-
</Nav>`}]});function
|
|
391
|
+
</Nav>`}]});function ns(e){const{label:t,children:n,...o}=e,s=Z(),r=q({component:Qa.name,label:t,region:!0});return s==="agent"?a.jsx(te,{node:r,children:n}):a.jsx("nav",{...o,...X(r),"aria-label":t,children:n})}const Xa=Y({name:"NavGroup",category:"navigation",summary:"A labelled cluster of links inside a Nav. The label names the group for screen readers and agents alike.",whenToUse:"Use it when a Nav holds more than one kind of destination: guides versus components, product versus account. The label tells every reader, including an agent scanning for the right link, what the links below it have in common.",whenNotToUse:"Do not use it outside a Nav; on its own it is just a heading over links, which Panel does better. Do not nest groups; one level of grouping is all a sidebar can carry.",status:"experimental",props:{label:{kind:"string",description:"What the links in this group have in common. Rendered as the rubric and as the group's accessible name.",required:!0},children:{kind:"node",description:"The Link components this group collects.",required:!0}},agentView:{example:'- **NavGroup** "Components"'},a11y:{role:"group",notes:"The group carries its label as an accessible name, so screen readers announce the rubric when entering the cluster rather than reading an unlabelled run of links."},relatedComponents:["Nav","Link"],examples:[{title:"A labelled group of links",code:`<NavGroup label="Reference">
|
|
301
392
|
<Link href="https://developer.chrome.com/docs/ai/webmcp" external>
|
|
302
393
|
Chrome docs
|
|
303
394
|
</Link>
|
|
304
395
|
<Link href="https://github.com/webmachinelearning/webmcp" external>
|
|
305
396
|
Specification
|
|
306
397
|
</Link>
|
|
307
|
-
</NavGroup>`}]});function
|
|
398
|
+
</NavGroup>`}]});function as(e){const{label:t,children:n,...o}=e,s=Z(),r=q({component:Xa.name,label:t});return s==="agent"?a.jsx(te,{node:r,children:n}):a.jsxs("div",{...o,...X(r),role:"group","aria-label":t,children:[a.jsx("span",{children:t}),n]})}const Ya=Y({name:"PageHeader",category:"layout",summary:"The top of a page: its h1 title, the Tag chips that classify it, an optional page-level control, and a lede underneath.",whenToUse:"Use it once per page, as the first thing inside the content region. The label becomes the page's only h1, so the document outline starts here. Put status or category Tags in tags, a control that affects the whole page in actions, and the introductory sentence or two in children as Text.",whenNotToUse:"Do not use it for a section within a page; that is a Panel with a headingLevel. Do not put navigation in actions; the page's links belong in a Nav.",status:"experimental",props:{label:{kind:"string",description:"The page title. Rendered as the page's h1.",required:!0},tags:{kind:"node",description:"Tag components that classify the page, rendered on the title line. Keep it to two or three."},actions:{kind:"node",description:"A control that acts on the whole page, rendered at the end of the title line."},children:{kind:"node",description:"The lede: a Text or two introducing the page."}},agentView:{example:'- **PageHeader** "Button"'},a11y:{notes:"The label renders as the page's h1, so keep to one PageHeader per page. Tags and the lede are ordinary content after it; the header element itself takes no landmark role because it sits inside main."},relatedComponents:["Panel","Heading","Tag"],examples:[{title:"A titled page with a lede",code:`<PageHeader label="Reports">
|
|
308
399
|
<Text>Everything the quarter produced, in one place.</Text>
|
|
309
400
|
</PageHeader>`},{title:"Status tags and a page-level control",description:"Tags classify the page on the title line; the action slot holds the one control that affects the whole page.",code:`<PageHeader
|
|
310
401
|
label="Button"
|
|
@@ -312,7 +403,7 @@ ${A.current([P.current])}`:"Opening removed this row from the page.")},[]),_=te(
|
|
|
312
403
|
actions={<Button agentTool={false}>Refresh</Button>}
|
|
313
404
|
>
|
|
314
405
|
<Text>A single action a person or an agent can trigger.</Text>
|
|
315
|
-
</PageHeader>`}]});function
|
|
406
|
+
</PageHeader>`}]});function os(e){const{label:t,tags:n,actions:o,children:s,...r}=e,l=Z(),d=q({component:Ya.name,label:t,region:!0});if(l==="agent")return a.jsxs(te,{node:d,children:[n,o,s]});const c=i.Children.toArray(s).length>0;return a.jsxs("header",{...r,...X(d),children:[a.jsxs("div",{children:[a.jsxs("div",{children:[a.jsx("h1",{children:t}),n===void 0?null:a.jsx("span",{children:n})]}),o===void 0?null:a.jsx("span",{children:o})]}),c?a.jsx("div",{children:s}):null]})}const Xe={verb:"turn",description:"Go to a page of this paginated set by its 1-based number, exactly as a person pressing Previous or Next until they reach it would. Any page from 1 to the page count is accepted, not just the neighbours. Returns the pagination's state after the change, including which items are now showing, so a follow-up read is unnecessary.",inputSchema:{type:"object",properties:{page:{type:"integer",description:"The 1-based number of the page to show.",minimum:1}},required:["page"]},readOnly:!1,untrustedContent:!1,registeredWhen:"The pagination is mounted, changes page through onPageChange rather than href, has more than one page, has a resolvable label, and no other component claims the same tool name. The registered schema states the current page count.",unregisteredWhen:"The pagination unmounts, is given href, loses onPageChange, or shrinks to a single page."},Jt=Y({name:"Pagination",category:"navigation",summary:'A navigation landmark for a long set shown one page at a time: Previous and Next controls, a "Page 2 of 3" readout, and a "Showing 26–50 of 61" summary of which items are on screen. It takes counts rather than items, so it works the same over a local array or a server query.',whenToUse:"Use it under or above a Table or List whose items arrive a page at a time, when the count is known. Give it onPageChange to page in place, which registers one turn tool that can jump straight to any page; give it href to make every page a URL, which needs no tool because a link is already reachable. Its state carries the page, the page count and the item range, so an agent reading the page knows how much it has not seen.",whenNotToUse:"Do not use it when the total is unknown or the set grows as it is read; that is a load-more Button. Do not use it for steps in a flow a person must complete in order, and do not use it to move between unrelated pages, which is Nav or Breadcrumb. Do not use it for a set that fits on one screen: it renders, but has nothing to do.",status:"experimental",props:{label:{kind:"string",description:'What is being paged. Names the navigation landmark and derives the tool name, so prefer a noun phrase such as "Users pages".',required:!0},page:{kind:"number",description:"The 1-based page currently shown. The component is controlled; a value outside 1 to the page count is clamped into it.",required:!0},pageSize:{kind:"number",description:"How many items a full page holds. Values below 1 are treated as 1.",required:!0},total:{kind:"number",description:"How many items the whole set holds. The page count is total divided by pageSize, rounded up, and never less than 1, so an empty set is one empty page.",required:!0},onPageChange:{kind:"handler",description:"Called with the page to show. Without href the controls are buttons and the turn tool registers; with href it runs alongside the link, for routers that intercept clicks."},href:{kind:"handler",description:"Given a page number, returns its URL. When present, Previous and Next render as links, each publishes its URL as data-sprint-href, and no tool registers."},previousLabel:{kind:"string",description:"The text of the control that goes back a page.",default:"Previous"},nextLabel:{kind:"string",description:"The text of the control that goes forward a page.",default:"Next"},agentName:{kind:"string",description:"Override the label used to derive the tool name, when two paginations on a page would otherwise collide."},agentTool:{kind:"boolean",description:"Set false to render the controls without registering a turn tool.",default:!0}},state:{page:{description:"The 1-based page shown, after clamping.",attribute:"data-sprint-page"},pages:{description:"How many pages the set spans. Never less than 1.",attribute:"data-sprint-pages"},total:{description:"How many items the whole set holds.",attribute:"data-sprint-total"},first:{description:"The 1-based position of the first item on this page, or 0 when the set is empty.",attribute:"data-sprint-first"},last:{description:"The 1-based position of the last item on this page, or 0 when the set is empty.",attribute:"data-sprint-last"}},tools:{turn:Xe},agentView:{example:'- **Pagination** "Users pages" [first=26, last=50, page=2, pages=3, total=61] → tool `turn-users-pages`\n - part `previous` "Previous"\n - part `next` "Next"'},a11y:{role:"navigation",keyboard:["Tab reaches Previous and Next in order","Enter or Space on a button, Enter on a link, turns the page"],notes:"The root is a nav landmark named by label. A control with nowhere to go is a disabled button, or a link with no href and aria-disabled, so it leaves the tab order. The item summary is a polite live region, so a screen reader hears the new range after a turn."},relatedComponents:["Table","List","Nav","Breadcrumb"],examples:[{title:"Paging a table in place",description:"With onPageChange the controls are buttons and one turn tool registers, so an agent can jump to page 3 without pressing Next twice.",code:`<Pagination
|
|
316
407
|
label="Users pages"
|
|
317
408
|
page={page}
|
|
318
409
|
pageSize={25}
|
|
@@ -338,9 +429,9 @@ ${A.current([P.current])}`:"Opening removed this row from the page.")},[]),_=te(
|
|
|
338
429
|
pageSize={20}
|
|
339
430
|
total={0}
|
|
340
431
|
onPageChange={setPage}
|
|
341
|
-
/>`}]});function
|
|
342
|
-
${
|
|
343
|
-
${
|
|
432
|
+
/>`}]});function Mt(e,t){return Number.isFinite(e)?Math.floor(e):t}function is(e,t,n){const o=Math.max(1,Mt(t,1)),s=Math.max(0,Mt(n,0)),r=Math.max(1,Math.ceil(s/o)),l=Math.min(r,Math.max(1,Mt(e,1))),d=s===0?0:(l-1)*o+1,c=Math.min(s,l*o);return{page:l,pages:r,total:s,first:d,last:c}}function ss(e){return e.total===0?"Showing 0 of 0":`Showing ${e.first}–${e.last} of ${e.total}`}function rs(e){const t=Xe.inputSchema.properties.page;return{...Xe.inputSchema,properties:{...Xe.inputSchema.properties,...t===void 0?{}:{page:{...t,maximum:e,description:`${t.description??""} This set has ${e} pages, so 1 to ${e}.`}}}}}function ls(e){const{label:t,page:n,pageSize:o,total:s,onPageChange:r,href:l,previousLabel:d="Previous",nextLabel:c="Next",agentName:h,agentTool:g=!0,...u}=e,b=Z(),m=ue(),S=ce(),f=is(n,o,s),y=l!==void 0||r!==void 0,k={previous:y&&f.page>1?f.page-1:null,next:y&&f.page<f.pages?f.page+1:null},T=i.useRef(new Map),O=i.useRef(r);O.current=r;const A=i.useRef(f);A.current=f;const E=i.useRef(S);E.current=S;const D=i.useRef(q({component:Jt.name})),U=i.useRef(!0);i.useEffect(()=>(U.current=!0,()=>{U.current=!1}),[]);const N=i.useCallback(p=>{const x=A.current.page,P=p===x-1?"previous":p===x+1?"next":null,v=P===null?void 0:T.current.get(P);if(v!==void 0){v.click();return}const K=O.current;K!==void 0&&me(()=>K(p))},[]),W=i.useCallback(async p=>{const x=p.page,{page:P,pages:v}=A.current;return typeof x!="number"||!Number.isInteger(x)?`Parameter "page" must be a whole page number from 1 to ${v}.`:x<1||x>v?`There is no page ${x}. This set has pages 1 to ${v}.`:x===P?`Already on page ${P}. The pagination is:
|
|
433
|
+
${E.current([D.current])}`:(N(x),await pe(),U.current?`Turned. The pagination is now:
|
|
434
|
+
${E.current([D.current])}`:"Turning the page removed this pagination from the page.")},[N]),$=i.useMemo(()=>rs(f.pages),[f.pages]),_=de({spec:Xe,label:h??t,inputSchema:$,enabled:g&&l===void 0&&r!==void 0&&f.pages>1,execute:W}),V=p=>{const x=k[p];return{part:p,label:p==="previous"?d:c,state:x===null?{disabled:!0}:l===void 0?{}:{href:l(x)}}},M=[V("previous"),V("next")],I=q({component:Jt.name,label:t,tool:_,state:{page:String(f.page),pages:String(f.pages),total:String(f.total),first:String(f.first),last:String(f.last)},parts:M});D.current=I;const j=k.previous!==null||k.next!==null;if(b==="agent")return!j||m==="never"?a.jsx(te,{node:I}):a.jsx(ke,{node:I,isActionable:p=>p.state.disabled!==!0,onActivate:p=>{const x=k[p.part];x!=null&&(l===void 0?N(x):window.location.assign(l(x)))}});const z=p=>x=>{x===null?T.current.delete(p):T.current.set(p,x)},L=(p,x)=>{const P=k[p],v=B(x),K=x.label;return l!==void 0?P===null?a.jsx("a",{...v,"aria-disabled":"true",children:K}):a.jsx("a",{...v,href:l(P),rel:p==="previous"?"prev":"next",ref:z(p),onClick:()=>r?.(P),children:K}):a.jsx("button",{...v,type:"button",disabled:P===null,ref:z(p),onClick:()=>{P!==null&&r?.(P)},children:K})};return a.jsxs("nav",{...u,...X(I),"aria-label":t,children:[a.jsx("p",{"aria-live":"polite",children:ss(f)}),a.jsxs("div",{children:[L("previous",M[0]??V("previous")),a.jsxs("span",{children:["Page ",f.page," of ",f.pages]}),L("next",M[1]??V("next"))]})]})}const Za=Y({name:"Panel",category:"layout",summary:"A labelled region with a header band and an optional slot for the controls that act on it. Everything on a Sprint page lives inside one.",whenToUse:"Use it for every distinct region of a page: a section of documentation, a form, a readout, a preview. The label is the region's accessible name, so a person, a screen reader, and an agent all address the region by the same words.",whenNotToUse:"Do not use it as a spacer or a plain box; that is Stack. Nesting reads clearly to about three deep, because each level alternates its ground and demotes its frame; past that, the depth cues repeat and the region wants a page of its own.",status:"experimental",props:{label:{kind:"string",description:"What this region is. Rendered in the header band and used as the region's accessible name.",required:!0},children:{kind:"node",description:"The region's content. An empty panel says it is empty rather than collapsing."},headingLevel:{kind:"enum",description:"Render the label as a real heading at this outline depth, so the section is reachable when a screen reader navigates by headings. Set it on every panelled section of a page; leave it unset only for chrome such as a preview frame.",values:["2","3","4"]},actions:{kind:"node",description:"Controls that act on this region, rendered at the end of the header band. Keep it to one or two."},flush:{kind:"boolean",description:"Drop the body padding, for content that draws its own edges such as a Table or a CodeBlock.",default:!1},emptyLabel:{kind:"string",description:"What the panel says when it has no content.",default:"Empty"},loading:{kind:"boolean",description:"Set while the content are being fetched. Sets aria-busy and sweeps a bar along the top edge. Existing content stay visible; with none yet, the empty slot says loadingLabel instead of emptyLabel.",default:!1},loadingLabel:{kind:"string",description:"What the empty slot says while loading.",default:"Loading"}},state:{flush:{description:"Present when the body carries no padding of its own.",attribute:"data-sprint-flush"},empty:{description:"Present when the panel has no content. The panel still renders its keyline and says it is empty.",attribute:"data-sprint-empty"},loading:{description:"Present while the content are being fetched. Alongside empty it means nothing has arrived yet, not that there is nothing.",attribute:"data-sprint-loading"}},agentView:{example:'- **Panel** "WebMCP tools"'},a11y:{role:"region",notes:"The section is a named landmark either way: the label is its accessible name. With headingLevel the label is also a heading element, so the page outline includes the region; without it the region is reachable only by landmark navigation."},examples:[{title:"A section of a page",description:"headingLevel puts the label in the page outline, so a screen reader finds the section by heading as well as by landmark.",code:`<Panel label="When to use" headingLevel={2}>
|
|
344
435
|
<Text>Use it for any discrete action.</Text>
|
|
345
436
|
</Panel>`},{title:"A panel with a control in its header",description:"The header slot is for controls that act on the region, not for navigation.",code:`<Panel
|
|
346
437
|
label="Preview"
|
|
@@ -355,14 +446,42 @@ ${A.current([P.current])}`:"Turning the page removed this pagination from the pa
|
|
|
355
446
|
<Text>Registration fields live here.</Text>
|
|
356
447
|
</Panel>
|
|
357
448
|
</Panel>
|
|
358
|
-
</Panel>`},{title:"An empty region",description:"An empty panel keeps its border and states that it is empty, rather than vanishing and leaving a person or an agent unsure whether it failed to load.",code:'<Panel label="Registered tools" emptyLabel="No tools registered" />'}]});function
|
|
449
|
+
</Panel>`},{title:"An empty region",description:"An empty panel keeps its border and states that it is empty, rather than vanishing and leaving a person or an agent unsure whether it failed to load.",code:'<Panel label="Registered tools" emptyLabel="No tools registered" />'}]});function ds(e){const{label:t,headingLevel:n,actions:o,flush:s=!1,emptyLabel:r="Empty",loading:l=!1,loadingLabel:d="Loading",children:c,...h}=e,g=Z(),u=i.Children.toArray(c).length===0,b=q({component:Za.name,label:t,region:!0,state:{flush:s,empty:u,loading:l}});if(g==="agent")return a.jsxs(te,{node:b,children:[o,c]});const m=n===void 0?"span":`h${n}`;return a.jsxs("section",{...h,...X(b),"aria-label":t,"aria-busy":l||void 0,children:[a.jsxs("header",{children:[a.jsx(m,{children:t}),o===void 0?null:a.jsx("span",{children:o})]}),a.jsx("div",{children:u?a.jsx("span",{children:l?d:r}):c})]})}const Ja=Y({name:"Pending",category:"feedback",summary:"Marks a region whose data is being fetched. Keeps stale content visible and readable while it refreshes, and holds a labelled pending field when there is nothing to show yet.",whenToUse:"Wrap a region you build yourself while its data loads: a profile card, a chart, a custom summary. Pass the children only once data exists, so the first load shows the pending field and a refetch keeps the old content under a busy bar. Table, List, DescriptionList and Panel take a loading prop of their own, so reach for that first.",whenNotToUse:"Do not wrap a Table, List, DescriptionList or Panel; use its loading prop, which keeps the region's own label and frame. Do not use for a long job with a countable amount of work; that is a Progress. Do not use for a busy action; that is Button's loading prop.",status:"experimental",props:{loading:{kind:"boolean",description:"Whether the region's data is being fetched. While false the wrapper adds nothing to the agent view.",required:!0},label:{kind:"string",description:'What is loading, as a phrase a person can read in the empty field, such as "Loading profile".',required:!0},children:{kind:"node",description:"The region's content. Omit it until data exists; while loading with children they stay visible as stale content."}},state:{loading:{description:"Present while the region's data is being fetched.",attribute:"data-sprint-loading"},empty:{description:"Present while loading with no content yet, so nothing on screen is data.",attribute:"data-sprint-empty"}},agentView:{example:'- **Pending** "Loading profile" [empty, loading]'},examples:[{title:"First load",description:"No data yet, so the region holds a labelled pending field.",code:`<Pending loading={isLoading} label="Loading profile">
|
|
359
450
|
{profile && <ProfileSummary profile={profile} />}
|
|
360
451
|
</Pending>`},{title:"Refetching stale content",description:"Content already on screen stays readable under a busy bar, and an agent reads it nested under a loading line.",code:`<Pending loading={isFetching} label="Refreshing pilot">
|
|
361
452
|
<Stack gap="tight">
|
|
362
453
|
<Heading level={3}>{pilot.callsign}</Heading>
|
|
363
454
|
<Text tone="muted">{pilot.status}</Text>
|
|
364
455
|
</Stack>
|
|
365
|
-
</Pending>`}],a11y:{role:"group",notes:"While loading the wrapper is a group named by its label with aria-busy set, so assistive technology knows the content may change. Idle, it is a plain element with no role."}});function
|
|
456
|
+
</Pending>`}],a11y:{role:"group",notes:"While loading the wrapper is a group named by its label with aria-busy set, so assistive technology knows the content may change. Idle, it is a plain element with no role."}});function cs(e){const{loading:t,label:n,children:o,...s}=e,r=Z(),l=i.Children.toArray(o).length===0,d=q({component:Ja.name,label:n,state:{loading:!0,empty:l}});if(r==="agent")return a.jsx(te,{node:d,silent:!t,children:o});const c=t?{...X(d),role:"group","aria-label":n,"aria-busy":!0}:{};return a.jsxs("div",{...s,...c,children:[t&&l?a.jsx("span",{children:n}):null,o]})}const eo=Y({name:"Progress",category:"feedback",summary:"A labelled loading indicator for work in progress. Indeterminate by default; pass value for a known fraction complete.",whenToUse:"Use while something the person is waiting on is still running: a page section fetching, an upload, an import, a long job. Omit value when the remaining work is unknown, and pass value with max when it can be counted. Keep the label a stable noun phrase for what is loading, not a percentage.",whenNotToUse:"Do not use for a busy action; Button's loading prop already marks the button itself. Do not use for the outcome of work that finished or failed; that is an Alert. Do not use for a quantity that is not progress, such as disk usage.",status:"experimental",props:{label:{kind:"string",description:`What is loading, such as "Importing manifest". It is the indicator's accessible name and its agent label.`,required:!0},value:{kind:"number",description:"Work completed so far, in the same units as max. Omit for an indeterminate indicator. Clamped to the range 0 to max."},max:{kind:"number",description:"The value at which the work is complete.",default:100},tone:{kind:"enum",values:["info","action","warning","danger"],description:"The fill colour. info is the default for ordinary loading; action suits a goal being worked towards; warning and danger mark a bar running out or over a limit.",default:"info"},hideLabel:{kind:"boolean",description:"Hide the label and percentage visually while keeping the label as the bar's accessible name and agent label. Use when a nearby heading already says what the bar measures.",default:!1}},state:{loading:{description:"Present until the work completes. An indeterminate indicator is always loading.",attribute:"data-sprint-loading"},value:{description:"The fraction complete as a whole percentage, such as 40%. Absent while indeterminate.",attribute:"data-sprint-value"},tone:{description:"The fill tone, when it is not the default info.",attribute:"data-sprint-tone"}},agentView:{example:'- **Progress** "Importing manifest" [loading, value=40%]'},examples:[{title:"Indeterminate load",description:"Nothing to count yet, so the indicator only says that work is running.",code:'<Progress label="Loading flight plan" />'},{title:"Counted progress",description:"With value and max the agent reads a percentage instead of guessing.",code:'<Progress label="Importing manifest" value={imported} max={total} />'},{title:"Complete",description:"At max the loading state clears, so the line reads as finished rather than stalled.",code:'<Progress label="Importing manifest" value={240} max={240} />'},{title:"A bare goal bar",description:"A heading beside the bar already names it, so the label is hidden and only the bar shows, in the action tone.",code:'<Progress label="Notes this week" value={3} max={5} tone="action" hideLabel />'}],a11y:{role:"progressbar",notes:"Renders a native progress element named by the visible label. Omitting value leaves it indeterminate, which assistive technology announces as busy. The percentage readout is hidden from assistive technology because the progressbar already carries its value."}});function hs(e,t){return t<=0?100:Math.round(Math.min(Math.max(e,0),t)/t*100)}function us(e){const{label:t,value:n,max:o=100,tone:s="info",hideLabel:r=!1,...l}=e,d=Z(),c=i.useId(),g=n!==void 0&&Number.isFinite(n)?hs(n,o):void 0,u=q({component:eo.name,label:t,state:{loading:g===void 0||g<100,value:g===void 0?void 0:`${g}%`,tone:s==="info"?void 0:s}});return d==="agent"?a.jsx(te,{node:u}):a.jsxs("div",{...l,...X(u),children:[a.jsx("span",{id:c,...r?{"data-sprint-visually-hidden":""}:{},children:t}),g===void 0||r?null:a.jsxs("span",{"aria-hidden":"true",children:[g,"%"]}),a.jsx("progress",{"aria-labelledby":c,...g===void 0?{}:{value:g,max:100}})]})}const to=Y({name:"Prose",category:"typography",summary:"Typography for long-form rendered content such as Markdown: headings, paragraphs, lists, links, code, tables and quotes, in the theme's voice.",whenToUse:"Wrap HTML you did not lay out yourself: member notes rendered from Markdown, an agenda's program details, a help article. Pass the original Markdown as source and the agent view carries it verbatim, which is better for an agent than flattened text. Sprint does not parse Markdown; render it with the library of your choice and pass the result as children.",whenNotToUse:"Do not use for interface copy you write yourself; that is Text and Heading. Do not put interactive Sprint components inside it; Prose styles plain elements.",status:"experimental",props:{children:{kind:"node",description:"The rendered content: plain HTML elements such as p, ul, a, code and table.",required:!0},source:{kind:"string",description:"The Markdown the children were rendered from. The agent view shows this instead of the flattened text, keeping lists, links and emphasis intact."},label:{kind:"string",description:'What the content is, such as "Member notes". Makes the block a labelled region and names it in the agent view.'},size:{kind:"enum",description:"small for notes inside a card or a side panel.",values:["small","normal"],default:"normal"}},state:{size:{description:"Present as small for the compact size.",attribute:"data-sprint-size",values:["small"]}},agentView:{example:'- **Prose** "Member notes"\n - part `content` "Moved in **March**. Plays the organ."'},examples:[{title:"Rendered Markdown",description:"The page renders Markdown however it likes and passes the original as source, which the agent view carries unchanged.",code:`<Prose label="Member notes" source={notes}>
|
|
457
|
+
<Markdown>{notes}</Markdown>
|
|
458
|
+
</Prose>`},{title:"Compact notes",code:`<Prose size="small">
|
|
459
|
+
<p>Prefers <strong>text</strong> after six.</p>
|
|
460
|
+
<ul>
|
|
461
|
+
<li>Organ</li>
|
|
462
|
+
<li>Youth program</li>
|
|
463
|
+
</ul>
|
|
464
|
+
</Prose>`}],a11y:{role:"region",notes:"With a label the block is a named region; without one it adds no semantics of its own. The content keeps its own elements, so headings join the page outline."}});function ps(e){const{label:t,source:n,size:o="normal",children:s,...r}=e,l=Z(),d=n??be(s),c=q({component:to.name,label:t,state:{size:o==="normal"?void 0:o},parts:d===void 0?[]:[{part:"content",label:d,state:{}}]});return l==="agent"?a.jsx(te,{node:c}):a.jsx("div",{...r,...X(c),...t===void 0?{}:{role:"region","aria-label":t},children:a.jsx("div",{...B({part:"content",state:{}}),children:s})})}const Ye={verb:"select",description:"Select one of this group's options by its visible label, exactly as a person clicking its radio button would. Only one option is selected at a time, so this replaces the current one. Returns the group's state after the change.",inputSchema:{type:"object",properties:{option:{type:"string",description:"The visible label of the option to select."}},required:["option"]},readOnly:!1,untrustedContent:!0,registeredWhen:"The group is mounted and enabled, has at least one enabled option, and no other component claims the same tool name. The registered schema enumerates the enabled options' labels.",unregisteredWhen:"The group unmounts, becomes disabled, or loses its last enabled option."},en=Y({name:"RadioGroup",category:"input",summary:"One choice from a short list of options, each a native radio button with a label and an optional line of description. Registers one select tool enumerating the options.",whenToUse:"Use when the options need explaining: a role with what it can do, a plan with what it includes, a delivery speed with its cost. Options hold data: { value, label, description?, disabled? }. The group is a fieldset whose legend is the label, so it submits under one name inside a form.",whenNotToUse:"Do not use for two to four short labels that need no description; that is a SegmentedControl. Do not use for a long list; that is a Select. Do not use for choosing several; that is a set of Checkboxes. Descriptions are plain strings, not components.",status:"experimental",props:{label:{kind:"string",description:'The question the options answer, such as "Role". Rendered as the legend and used to derive the tool name.',required:!0},options:{kind:"array",description:"The options in order: { value, label, description?, disabled? }. label is what a person reads and what the select tool accepts. description is a sentence under the label, linked to its radio with aria-describedby and carried into the agent view as part state.",required:!0},value:{kind:"string",description:"The selected option's value, or an empty string for none. Fully controlled.",required:!0},onChange:{kind:"handler",description:"Called with the value a person or an agent selects.",required:!0},hint:{kind:"string",description:"Guidance under the group. Replaced by error while one is set."},error:{kind:"string",description:"A validation message that marks the group invalid."},name:{kind:"string",description:"The native form name the selected value submits under."},disabled:{kind:"boolean",description:"Disable every option and unregister the select tool.",default:!1},required:{kind:"boolean",description:"Mark the group as needing an answer.",default:!1},agentName:{kind:"string",description:"Override the label used to derive the tool name."},agentTool:{kind:"boolean",description:"Set false to render the group without registering the select tool.",default:!0}},state:{value:{description:"The selected option's label.",attribute:"data-sprint-value"},empty:{description:"Present while nothing is selected.",attribute:"data-sprint-empty"},disabled:{description:"Present when the group cannot be changed.",attribute:"data-sprint-disabled"},required:{description:"Present when an answer is needed.",attribute:"data-sprint-required"},invalid:{description:"Present while an error is set.",attribute:"data-sprint-invalid"}},tools:{select:Ye},agentView:{example:'- **RadioGroup** "Role" [value=Viewer] → tool `select-role`\n - part `option` "Viewer" [checked, description=Sees the board]\n - part `option` "Editor" [description=Changes callings]'},examples:[{title:"Options that need explaining",description:"Each role says what it allows. The descriptions reach screen readers through aria-describedby and agents through part state.",code:`<RadioGroup
|
|
465
|
+
label="Role"
|
|
466
|
+
value={role}
|
|
467
|
+
onChange={setRole}
|
|
468
|
+
options={[
|
|
469
|
+
{ value: "viewer", label: "Viewer", description: "Sees the board and the agenda." },
|
|
470
|
+
{ value: "editor", label: "Editor", description: "Moves people between callings." },
|
|
471
|
+
{ value: "admin", label: "Admin", description: "Also invites and removes people." },
|
|
472
|
+
]}
|
|
473
|
+
/>`},{title:"A required choice with an unavailable option",code:`<RadioGroup
|
|
474
|
+
label="Delivery"
|
|
475
|
+
required
|
|
476
|
+
value={delivery}
|
|
477
|
+
onChange={setDelivery}
|
|
478
|
+
error={delivery === "" ? "Choose how to send the invite." : undefined}
|
|
479
|
+
options={[
|
|
480
|
+
{ value: "email", label: "Email" },
|
|
481
|
+
{ value: "text", label: "Text message", disabled: true, description: "No phone number on file." },
|
|
482
|
+
]}
|
|
483
|
+
/>`}],a11y:{role:"radiogroup",keyboard:["Arrow keys move between options and select","Tab enters and leaves the group"],notes:"A fieldset of native radio inputs sharing one name, so the browser supplies arrow-key movement and form submission. The legend names the group; a description is linked to its own radio."}});function gs(e){const t=Ye.inputSchema.properties.option;return{...Ye.inputSchema,properties:{...Ye.inputSchema.properties,...t===void 0?{}:{option:{...t,enum:[...e]}}}}}function ms(e,t){return e!==void 0?[{part:"error",label:e,state:{}}]:t!==void 0?[{part:"hint",label:t,state:{}}]:[]}function fs(e){const{label:t,options:n,value:o,onChange:s,hint:r,error:l,name:d,disabled:c=!1,required:h=!1,agentName:g,agentTool:u=!0,...b}=e,m=Z(),S=ue(),f=ce(),y=i.useId(),k=d??y,T=i.useRef(new Map),O=i.useRef(n);O.current=n;const A=i.useRef(s);A.current=s;const E=i.useRef(f);E.current=f;const D=i.useRef(q({component:en.name})),U=i.useRef(!0);i.useEffect(()=>(U.current=!0,()=>{U.current=!1}),[]);const N=i.useCallback(L=>{const p=T.current.get(L);if(p!==void 0){p.click();return}me(()=>A.current(L))},[]),W=i.useCallback(async L=>{const p=typeof L.option=="string"?L.option:"",x=O.current,P=x.find(v=>v.label===p);return P===void 0||P.disabled===!0?`No option named "${p}" can be selected. This group offers: ${x.filter(v=>v.disabled!==!0).map(v=>`"${v.label}"`).join(", ")}.`:(N(P.value),await pe(),U.current?`Selected. The group is now:
|
|
484
|
+
${E.current([D.current])}`:"The selection removed this group from the page.")},[N]),$=i.useMemo(()=>n.filter(L=>L.disabled!==!0).map(L=>L.label),[n]),_=i.useMemo(()=>gs($),[$]),V=de({spec:Ye,label:g??t,inputSchema:_,enabled:u&&!c&&$.length>0,execute:W}),M=n.map(L=>({part:"option",label:L.label,state:{...L.value===o?{checked:!0}:{},...L.description===void 0?{}:{description:L.description},...c||L.disabled===!0?{disabled:!0}:{}}})),I=n.find(L=>L.value===o),j=q({component:en.name,label:t,tool:V,state:{value:I?.label,empty:I===void 0,disabled:c,required:h,invalid:l!==void 0},parts:[...M,...ms(l,r)]});if(D.current=j,m==="agent")return c||S==="never"?a.jsx(te,{node:j}):a.jsx(ke,{node:j,isActionable:L=>L.part==="option"&&L.state.disabled!==!0,onActivate:(L,p)=>{const x=n[p];x!==void 0&&N(x.value)}});const z=l!==void 0?`${y}-error`:r!==void 0?`${y}-hint`:void 0;return a.jsxs("fieldset",{...b,...X(j),disabled:c,"aria-describedby":z,children:[a.jsx("legend",{children:t}),n.map((L,p)=>{const x=`${y}-${p}`,P=`${x}-description`,v=`${x}-label`;return a.jsxs("label",{htmlFor:x,children:[a.jsx("input",{id:x,type:"radio",name:k,value:L.value,checked:L.value===o,disabled:L.disabled===!0,required:h,"aria-invalid":l!==void 0||void 0,"aria-labelledby":v,"aria-describedby":L.description===void 0?void 0:P,ref:K=>{K===null?T.current.delete(L.value):T.current.set(L.value,K)},onChange:()=>s(L.value)}),a.jsx("span",{"aria-hidden":"true"}),a.jsxs("span",{children:[a.jsx("span",{id:v,...B(M[p]??{part:"option",state:{}}),children:L.label}),L.description===void 0?null:a.jsx("span",{id:P,children:L.description})]})]},L.value)}),l!==void 0?a.jsx("p",{id:z,...B({part:"error",state:{}}),children:l}):r!==void 0?a.jsx("p",{id:z,...B({part:"hint",state:{}}),children:r}):null]})}const Ln={verb:"search",description:"Search with this field: replace its text with the query, exactly as a person typing it would, then submit it as pressing Enter would. Pass an empty string to clear the search. Results usually render elsewhere on the page; this returns the field's state after the search, so read the results region next.",inputSchema:{type:"object",properties:{query:{type:"string",description:"The full search text. Replaces the current query rather than appending to it; an empty string clears the search."}},required:["query"]},readOnly:!1,untrustedContent:!0,registeredWhen:"The field is mounted, enabled, has a resolvable label, and no other component claims the same tool name.",unregisteredWhen:"The field unmounts or becomes disabled."},tn=Y({name:"SearchField",category:"input",summary:"A search box inside its own search landmark: a labelled query field with a clear control, Escape to clear, Enter to submit, and an optional page-wide key that focuses it. It registers one search tool that sets the query and submits it.",whenToUse:"Use it to filter or search a collection on the page, such as narrowing a users list by name. The landmark lets screen reader users jump straight to it, and the optional shortcut gives keyboard users the familiar slash-to-search.",whenNotToUse:"Do not use it for any other single-line value; a name, an email address, or an identifier is a TextInput. Do not use it to choose from a short known set, which is a Select or a SegmentedControl. Do not give two fields on one page the same shortcut.",status:"experimental",props:{label:{kind:"string",description:'What is being searched, as a noun phrase such as "Users". Names the landmark and the field, and derives the tool name, so "Users" becomes search-users.',required:!0},value:{kind:"string",description:"The current query. The field is fully controlled.",required:!0},onChange:{kind:"handler",description:"Called with the new query on every change, including the clear control, Escape, and the search tool.",required:!0},onSubmit:{kind:"handler",description:"Called with the query when Enter is pressed or the search tool runs. Leave it off for a live filter that reacts to onChange alone."},placeholder:{kind:"string",description:'Ghost text shown while the field is empty, e.g. "Name or email".'},hideLabel:{kind:"boolean",description:"Hide the label visually while keeping it for screen readers and agents. Pair it with a placeholder so sighted people still know what the field searches.",default:!1},shortcut:{kind:"string",description:'A single key that focuses the field from anywhere on the page, shown as a key chip while the field is empty and unfocused. Ignored while focus is in another editable element or a modifier is held. Pass "/" for the common convention; omit or pass false for none.'},name:{kind:"string",description:"The native form name of the query input."},disabled:{kind:"boolean",description:"Disable the field, its shortcut, and its search tool.",default:!1},agentName:{kind:"string",description:"Override the label used to derive the tool name, when two search fields on a page would otherwise collide."},agentTool:{kind:"boolean",description:"Set false to render the field without registering a search tool.",default:!0}},state:{value:{description:"The current query, absent while the field is empty.",attribute:"data-sprint-value"},empty:{description:"Present while the field holds no query.",attribute:"data-sprint-empty"},shortcut:{description:"The key that focuses the field from anywhere on the page.",attribute:"data-sprint-shortcut"},disabled:{description:"Present when the field cannot be edited.",attribute:"data-sprint-disabled"}},tools:{search:Ln},agentView:{example:'- **SearchField** "Users" [empty, shortcut=/] → tool `search-users`'},examples:[{title:"Filtering a list",description:"A live filter: onChange narrows the list as the person types, so there is no onSubmit. The label is hidden and the placeholder says what can be matched.",code:`<SearchField
|
|
366
485
|
label="Users"
|
|
367
486
|
hideLabel
|
|
368
487
|
value={query}
|
|
@@ -380,12 +499,12 @@ ${A.current([P.current])}`:"Turning the page removed this pagination from the pa
|
|
|
380
499
|
onChange={setQuery}
|
|
381
500
|
onSubmit={runSearch}
|
|
382
501
|
placeholder="Callsign or tail number"
|
|
383
|
-
/>`}],a11y:{role:"search",keyboard:["Enter submits the query","Escape clears a non-empty query and keeps focus; on an empty field it passes through, so an enclosing dialog can close","The shortcut key, when set, focuses the field from anywhere on the page"],notes:"The root is a form with role search, labelled by the field's label, so it is listed as a search landmark. The input is type search and announces its shortcut with aria-keyshortcuts; the key chip itself is hidden from assistive technology. The clear control appears only while there is a query, and returns focus to the field."},relatedComponents:["TextInput"]});function
|
|
384
|
-
${
|
|
502
|
+
/>`}],a11y:{role:"search",keyboard:["Enter submits the query","Escape clears a non-empty query and keeps focus; on an empty field it passes through, so an enclosing dialog can close","The shortcut key, when set, focuses the field from anywhere on the page"],notes:"The root is a form with role search, labelled by the field's label, so it is listed as a search landmark. The input is type search and announces its shortcut with aria-keyshortcuts; the key chip itself is hidden from assistive technology. The clear control appears only while there is a query, and returns focus to the field."},relatedComponents:["TextInput"]});function Pn(e,t){const n=e instanceof HTMLTextAreaElement?HTMLTextAreaElement.prototype:HTMLInputElement.prototype,o=Object.getOwnPropertyDescriptor(n,"value")?.set;o!==void 0&&(o.call(e,t),e.dispatchEvent(new Event("input",{bubbles:!0})))}const bs='input, textarea, select, [contenteditable]:not([contenteditable="false"])';function Vn(e){return e instanceof Element&&e.closest(bs)!==null}function ws(e,t){i.useEffect(()=>{if(e===void 0)return;const n=o=>{if(o.key!==e||o.defaultPrevented||o.ctrlKey||o.metaKey||o.altKey||Vn(o.target)||Vn(document.activeElement))return;const s=t.current;s!==null&&(o.preventDefault(),s.focus())};return document.addEventListener("keydown",n),()=>document.removeEventListener("keydown",n)},[e,t])}function vs(e){const{label:t,value:n,onChange:o,onSubmit:s,placeholder:r,hideLabel:l=!1,shortcut:d,name:c,disabled:h=!1,agentName:g,agentTool:u=!0,...b}=e,m=Z(),S=ue(),f=ce(),y=i.useId(),k=i.useRef(null),T=i.useRef(o);T.current=o;const O=i.useRef(s);O.current=s;const A=i.useRef(f);A.current=f;const E=i.useRef(q({component:tn.name})),D=i.useRef(!0);i.useEffect(()=>(D.current=!0,()=>{D.current=!1}),[]);const U=d===void 0||d===!1||d===""||h?void 0:d;ws(U,k);const N=i.useCallback(async j=>{const z=j.query;if(typeof z!="string")return'Pass "query" as a string holding the full search text.';const L=k.current;L!==null?Pn(L,z):me(()=>T.current(z));const p=O.current;return p!==void 0&&me(()=>p(z)),await pe(),D.current?`${p===void 0?"Filtered":"Searched"}. The field is now:
|
|
503
|
+
${A.current([E.current])}`:"The search removed this field from the page."},[]),W=de({spec:Ln,label:g??t,enabled:u&&!h,execute:N}),$=n==="",_=q({component:tn.name,label:t,tool:W,state:{...$?{}:{value:n},empty:$,shortcut:U,disabled:h}});if(E.current=_,m==="agent")return h||S==="never"?a.jsx(te,{node:_}):a.jsx(fn,{node:_,value:n,onValueChange:o,ref:j=>{k.current=j}});const V=`${y}-label`,M=()=>{o(""),k.current?.focus()},I=j=>{j.key!=="Escape"||$||(j.preventDefault(),j.stopPropagation(),o(""))};return a.jsxs("form",{...b,...X(_),role:"search","aria-labelledby":V,noValidate:!0,onSubmit:j=>{j.preventDefault(),h||s?.(n)},children:[a.jsx("label",{id:V,htmlFor:y,...B({part:"label",state:l?{"visually-hidden":!0}:{}}),children:t}),a.jsxs("div",{...B({part:"control",state:{}}),children:[a.jsx("input",{id:y,...B({part:"input",state:{}}),ref:j=>{k.current=j},type:"search",value:n,placeholder:r,name:c,disabled:h,autoComplete:"off","aria-keyshortcuts":U,enterKeyHint:"search",onChange:j=>o(j.currentTarget.value),onKeyDown:I}),$||h?null:a.jsx("button",{...B({part:"clear",state:{}}),type:"button","aria-label":`Clear ${t} search`,onClick:M,children:"Clear"}),U===void 0||!$?null:a.jsx("span",{...B({part:"shortcut",state:{}}),"aria-hidden":"true",children:a.jsx("kbd",{children:U})})]})]})}const no=Y({name:"SecretField",category:"display",summary:"A sensitive value shown once or on demand: an API key, a recovery code, a signing secret. Masked by default with reveal and copy controls, and the value never reaches any agent surface.",whenToUse:"Use to hand a person a secret the page holds. The mask is fixed-length so nothing leaks, and copy places the value on the clipboard without revealing it.",whenNotToUse:"Do not use for entering a secret; that is a TextInput with type password. Do not use for values that are safe to read; a DescriptionList or CodeBlock keeps those on the agent surface where they belong.",status:"experimental",props:{label:{kind:"string",description:"What the secret is, shown as the field's uppercase title.",required:!0},value:{kind:"string",description:"The secret. Never appears in agent attributes, the agent view, or the copyable text stream; only reveal and copy touch it.",required:!0},hint:{kind:"string",description:'Guidance below the value, e.g. "Store it now. It is not shown again."'},defaultRevealed:{kind:"boolean",description:"Start revealed instead of masked.",default:!1}},state:{filled:{description:"Present when the field holds a secret.",attribute:"data-sprint-filled"},revealed:{description:"Present while the value is shown in clear text.",attribute:"data-sprint-revealed"}},agentView:{example:'- **SecretField** "API key" [filled]'},examples:[{title:"A key shown once",code:`<SecretField
|
|
385
504
|
label="API key"
|
|
386
505
|
value={key}
|
|
387
506
|
hint="Store it now. It is not shown again."
|
|
388
|
-
/>`},{title:"Starting revealed",description:"For a value the person is expected to transcribe immediately.",code:'<SecretField label="Recovery code" value={code} defaultRevealed />'}],a11y:{notes:"The reveal control is a toggle button with aria-pressed; the masked value is announced as a hidden secret rather than as bullet characters. Copy announces its success by swapping its label to Copied."}}),
|
|
507
|
+
/>`},{title:"Starting revealed",description:"For a value the person is expected to transcribe immediately.",code:'<SecretField label="Recovery code" value={code} defaultRevealed />'}],a11y:{notes:"The reveal control is a toggle button with aria-pressed; the masked value is announced as a hidden secret rather than as bullet characters. Copy announces its success by swapping its label to Copied."}}),ys="••••••••••••",ks=1200;function xs(e){const{label:t,value:n,hint:o,defaultRevealed:s=!1,...r}=e,l=Z(),[d,c]=i.useState(s),[h,g]=i.useState(!1);i.useEffect(()=>{if(!h)return;const f=setTimeout(()=>g(!1),ks);return()=>clearTimeout(f)},[h]);const u=()=>{const f=navigator.clipboard;f!==void 0&&f.writeText(n).then(()=>g(!0),()=>g(!1))},b=n!=="",m=o===void 0?[]:[{part:"hint",label:o,state:{}}],S=q({component:no.name,label:t,state:{filled:b,revealed:d},parts:m});return l==="agent"?a.jsx(te,{node:S}):a.jsxs("div",{...r,...X(S),children:[a.jsx("span",{...B({part:"label",state:{}}),children:t}),a.jsxs("div",{...B({part:"control",state:{}}),children:[a.jsx("output",{...B({part:"value",state:{}}),"aria-label":d?void 0:"Hidden secret",children:d?n:ys}),a.jsx("button",{...B({part:"reveal",state:{}}),type:"button","aria-pressed":d,onClick:()=>c(f=>!f),children:d?"Hide":"Reveal"}),a.jsx("button",{...B({part:"copy",state:h?{copied:!0}:{}}),type:"button",onClick:u,children:h?"Copied":"Copy"})]}),o===void 0?null:a.jsx("p",{...B({part:"hint",state:{}}),children:o})]})}const Ze={verb:"select",description:"Select one of this control's options by its visible label, exactly as a person clicking it would. Only one option is selected at a time, so this replaces the current one. Returns the control's state after the change, so a follow-up read is unnecessary.",inputSchema:{type:"object",properties:{option:{type:"string",description:"The visible label of the option to select, as shown on the control."}},required:["option"]},readOnly:!1,untrustedContent:!0,registeredWhen:"The control is mounted, enabled, has a resolvable label, and no other component claims the same tool name. The registered schema enumerates the current option labels.",unregisteredWhen:"The control unmounts or becomes disabled."},nn=Y({name:"SegmentedControl",category:"input",summary:"A short row of mutually exclusive options, all visible at once: a radio group that registers a single select tool whose schema enumerates the options currently on screen.",whenToUse:"Use it for two to four exclusive choices a person should be able to compare without opening anything: a view switch, a density setting, a filter. One tool with an enum beats one tool per option, and it keeps a page's tool count flat as options are added.",whenNotToUse:"Do not use it for more than about four options or for long labels; that is a select. Do not use it for an on/off setting, which is a switch, and never for navigation.",status:"experimental",props:{label:{kind:"string",description:'What is being chosen. Names the group for a screen reader and derives the tool name, so prefer a noun phrase such as "Page view".',required:!0},options:{kind:"array",description:"The choices in display order: { value, label, count?, disabled? }. The label is what a person sees and what the select tool accepts, so an agent never has to know the value. count renders as a muted chip beside the label and reaches the agent view as part state, so never fold a count into the label. disabled keeps one option visible but unselectable: it is skipped by the arrow keys, left out of the tool's enum, and marked disabled in the agent view.",required:!0},value:{kind:"string",description:"The value of the selected option. The control is fully controlled.",required:!0},onChange:{kind:"handler",description:"Called with the newly selected value. The select tool drives a real click, so this runs for agent selections too.",required:!0},savedValue:{kind:"string",description:"The value currently in effect, for a control that stages a change until something confirms it. While it differs from value the saved option keeps a marker and the control reports itself dirty, so both the saved and the proposed choice stay readable."},hint:{kind:"string",description:"Guidance shown under the options, linked with aria-describedby and carried into the agent view. Say what a staged change does, such as when it takes effect."},block:{kind:"boolean",description:"Fill the container's width, with every option taking an equal share. Without it the control stays as wide as its options, even inside a stretching column.",default:!1},disabled:{kind:"boolean",description:"Disable every option and unregister the select tool.",default:!1},agentName:{kind:"string",description:"Override the label used to derive the tool name, when two controls on a page would otherwise collide."},agentTool:{kind:"boolean",description:"Set false to render the control without registering a select tool.",default:!0}},state:{value:{description:"The value of the option currently selected.",attribute:"data-sprint-value"},dirty:{description:"Present while savedValue is set and differs from value. The saved option carries data-sprint-saved.",attribute:"data-sprint-dirty"},block:{description:"Present when the control fills its container.",attribute:"data-sprint-block"},disabled:{description:"Present when no option can be chosen.",attribute:"data-sprint-disabled"}},tools:{select:Ze},agentView:{example:'- **SegmentedControl** "Access" [dirty, value=write] → tool `select-access`\n - part `option` "Read" [count=17, saved]\n - part `option` "Write" [checked, count=4]\n - part `hint` "Currently Read. Nothing changes until you confirm."'},examples:[{title:"A view switch",description:"In agent view each option renders as its own control, so an agent driving the DOM can click one without WebMCP.",code:`<SegmentedControl
|
|
389
508
|
label="Page view"
|
|
390
509
|
value={view}
|
|
391
510
|
onChange={setView}
|
|
@@ -432,8 +551,17 @@ ${x.current([A.current])}`:"The search removed this field from the page."},[]),_
|
|
|
432
551
|
{ value: "dense", label: "dense" },
|
|
433
552
|
{ value: "roomy", label: "roomy" },
|
|
434
553
|
]}
|
|
435
|
-
/>`}
|
|
436
|
-
|
|
554
|
+
/>`},{title:"One option unavailable",description:"A disabled option stays in place so the set of choices reads the same, but nobody can pick it: arrow keys skip it and the select tool does not offer it.",code:`<SegmentedControl
|
|
555
|
+
label="Interview"
|
|
556
|
+
value={status}
|
|
557
|
+
onChange={setStatus}
|
|
558
|
+
options={[
|
|
559
|
+
{ value: "pending", label: "Pending" },
|
|
560
|
+
{ value: "accepted", label: "Accepted", disabled: !interviewed },
|
|
561
|
+
{ value: "declined", label: "Declined", disabled: !interviewed },
|
|
562
|
+
]}
|
|
563
|
+
/>`}],a11y:{role:"radiogroup",keyboard:["Arrow keys move to the next or previous enabled option and select it","Home selects the first enabled option","End selects the last enabled option","Tab enters and leaves the group once"],notes:"Roving tabindex: only the selected option is in the tab order. Selection follows focus, which is the expected behaviour for a radio group. An option with a count is named by its label and its count together; the hint is linked to the group with aria-describedby."}});function Ts(e){const t=Ze.inputSchema.properties.option;return{...Ze.inputSchema,properties:{...Ze.inputSchema.properties,...t===void 0?{}:{option:{...t,enum:e.filter(n=>!n.disabled).map(n=>n.label)}}}}}function Cs(e){const{label:t,options:n,value:o,onChange:s,savedValue:r,hint:l,block:d=!1,disabled:c=!1,agentName:h,agentTool:g=!0,...u}=e,b=Z(),m=ue(),S=ce(),f=i.useId(),y=i.useRef(new Map),k=i.useRef(s);k.current=s;const T=i.useRef(n);T.current=n;const O=i.useRef(S);O.current=S;const A=i.useRef(q({component:nn.name})),E=i.useRef(!0);i.useEffect(()=>(E.current=!0,()=>{E.current=!1}),[]);const D=i.useCallback(p=>{const x=y.current.get(p);if(x!==void 0){x.click();return}me(()=>k.current(p))},[]),U=i.useCallback(async p=>{const x=typeof p.option=="string"?p.option:"",P=T.current,v=P.find(K=>K.label===x);return v===void 0?`No option named "${x}". This control offers: ${P.map(K=>`"${K.label}"`).join(", ")}.`:v.disabled?`"${v.label}" is unavailable right now. Choose one of: ${P.filter(K=>!K.disabled).map(K=>`"${K.label}"`).join(", ")}.`:(D(v.value),await pe(),E.current?`Selected. The control is now:
|
|
564
|
+
${O.current([A.current])}`:"The selection removed this control from the page.")},[D]),N=i.useMemo(()=>Ts(n),[n]),W=de({spec:Ze,label:h??t,inputSchema:N,enabled:g&&!c,execute:U}),$=r!==void 0&&r!==o&&n.some(p=>p.value===r),_=n.map(p=>({part:"option",label:p.label,state:{...p.value===o?{checked:!0}:{},...p.value===r?{saved:!0}:{},...p.count===void 0?{}:{count:String(p.count)},...c||p.disabled?{disabled:!0}:{}}})),V=l===void 0?[]:[{part:"hint",label:l,state:{}}],M=q({component:nn.name,label:t,tool:W,state:{value:o,dirty:$,block:d,disabled:c},parts:[..._,...V]});A.current=M;const I=p=>{if(!["ArrowRight","ArrowDown","ArrowLeft","ArrowUp","Home","End"].includes(p.key)||c)return;const P=n.filter(he=>!he.disabled);if(P.length===0)return;const v=P.findIndex(he=>he.value===o),K=p.key==="ArrowRight"||p.key==="ArrowDown"?1:-1,ne=v<0&&K<0?0:v,se=p.key==="Home"?0:p.key==="End"?P.length-1:(ne+K+P.length)%P.length,re=P[se];re!==void 0&&(p.preventDefault(),y.current.get(re.value)?.focus(),D(re.value))};if(b==="agent")return c||m==="never"?a.jsx(te,{node:M}):a.jsx(ke,{node:M,isActionable:p=>p.part==="option"&&p.state.disabled!==!0,onActivate:(p,x)=>{const P=n[x];P!==void 0&&D(P.value)}});const j=l===void 0?void 0:`${f}-hint`,z=n.filter(p=>!p.disabled),L=(z.find(p=>p.value===o)??z[0])?.value;return a.jsxs("div",{...u,...X(M),role:"radiogroup","aria-label":t,"aria-describedby":j,onKeyDown:I,children:[a.jsx("div",{children:n.map((p,x)=>{const P=p.value===o,v=p.value===L,K=`${f}-${x}-label`,ne=`${f}-${x}-count`;return a.jsx("button",{type:"button",role:"radio","aria-checked":P,"aria-labelledby":p.count===void 0?void 0:`${K} ${ne}`,tabIndex:v?0:-1,disabled:c||p.disabled,ref:se=>{se===null?y.current.delete(p.value):y.current.set(p.value,se)},...B(_[x]??{part:"option",state:{}}),onClick:()=>s(p.value),children:p.count===void 0?p.label:a.jsxs(a.Fragment,{children:[a.jsx("span",{id:K,children:p.label}),a.jsx("span",{id:ne,"aria-hidden":"true",children:p.count})]})},p.value)})}),l===void 0?null:a.jsx("p",{id:j,...B({part:"hint",state:{}}),children:l})]})}const Je={verb:"select",description:"Choose one of this dropdown's options by its visible label, exactly as a person opening it and clicking one would. Only one option is chosen at a time, so this replaces the current choice. Returns the dropdown's state after the change, so a follow-up read is unnecessary.",inputSchema:{type:"object",properties:{option:{type:"string",description:"The visible label of the option to choose, as a person reads it in the list."}},required:["option"]},readOnly:!1,untrustedContent:!0,registeredWhen:"The dropdown is mounted, enabled, has a resolvable label, and no other component claims the same tool name. The registered schema enumerates the current option labels.",unregisteredWhen:"The dropdown unmounts or becomes disabled."},an=Y({name:"Select",category:"input",summary:"A dropdown of mutually exclusive options: a select-only combobox that opens a listbox on click or keyboard, carrying its own label, hint, and error. It registers a single select tool whose schema enumerates the option labels currently on offer.",whenToUse:"Use it when one value is chosen from a list too long to lay out flat: a region, a squad, a category. Options are data ({ value, label }), the tool accepts the visible label, and in agent view every option renders as its own control, so an agent picks one without opening anything.",whenNotToUse:"Do not use it for two to four short options a person should compare at a glance; that is a SegmentedControl. Do not use it for a list long enough to need searching, grouping or custom option rendering; that is a Combobox. Do not use it for an on/off state, which is a Checkbox or a Switch, and never for navigation.",status:"experimental",props:{label:{kind:"string",description:'What is being chosen. Names the control for a screen reader and derives the tool name, so prefer a noun phrase such as "Region".',required:!0},options:{kind:"array",description:"The choices in display order: { value, label, count? }. The label is what a person sees and what the select tool accepts, so an agent never has to know the value. count renders as a muted chip beside the label and reaches the agent view as part state, so never fold a count into the label.",required:!0},value:{kind:"string",description:'The value of the chosen option, or "" while nothing is chosen yet. The control is fully controlled.',required:!0},onChange:{kind:"handler",description:"Called with the newly chosen value. The select tool clicks the real option, so this runs for agent selections too.",required:!0},placeholder:{kind:"string",description:'Shown in the closed control while value is "". It is not an option, so a person cannot choose it back.'},hint:{kind:"string",description:"Guidance shown under the control and carried into the agent view. Replaced by error while one is set."},error:{kind:"string",description:"A validation message. Marks the control invalid for people, screen readers, and agents alike."},name:{kind:"string",description:"The form name submitted with the surrounding form, through a hidden input carrying the value."},disabled:{kind:"boolean",description:"Disable the control and unregister its select tool.",default:!1},required:{kind:"boolean",description:"Mark the control required, visually and in the agent view.",default:!1},agentName:{kind:"string",description:"Override the label used to derive the tool name, when two controls on a page would otherwise collide."},agentTool:{kind:"boolean",description:"Set false to render the control without registering a select tool.",default:!0}},state:{value:{description:"The value of the option currently chosen.",attribute:"data-sprint-value"},empty:{description:"Present while no option is chosen.",attribute:"data-sprint-empty"},disabled:{description:"Present when nothing can be chosen.",attribute:"data-sprint-disabled"},required:{description:"Present when a choice must be made.",attribute:"data-sprint-required"},invalid:{description:"Present while an error is set.",attribute:"data-sprint-invalid"},active:{description:"On an option part, present while the list is open and that option is highlighted by the keyboard or pointer.",attribute:"data-sprint-active"}},tools:{select:Je},agentView:{example:'- **Select** "Region" [value=eu-1] → tool `select-region`\n - part `option` "North Atlantic" [count=12]\n - part `option` "Northern Europe" [checked, count=30]\n - part `option` "East Asia" [count=7]'},examples:[{title:"A dropdown",description:"In agent view each option renders as its own control, so a DOM-driving agent chooses one directly.",code:`<Select
|
|
437
565
|
label="Region"
|
|
438
566
|
value={region}
|
|
439
567
|
onChange={setRegion}
|
|
@@ -472,8 +600,8 @@ ${R.current([x.current])}`:"The selection removed this control from the page.")}
|
|
|
472
600
|
{ value: "r-1", label: "Relay one" },
|
|
473
601
|
{ value: "r-2", label: "Relay two" },
|
|
474
602
|
]}
|
|
475
|
-
/>`}],a11y:{role:"combobox",keyboard:["Enter, Space, or an arrow key opens the list","Arrow keys, Home, and End move through the options; typing a letter jumps to the next match","Enter or Space chooses the highlighted option","Escape or Tab closes the list without choosing"],notes:"A select-only combobox: a button with role combobox that opens a listbox on a plain click, so a synthetic element.click() opens it as reliably as a pointer does, and the list renders in the page rather than in browser chrome an automated session cannot see. Focus stays on the button and aria-activedescendant tracks the highlighted option. The label is linked with aria-labelledby; errors set aria-invalid and link with aria-describedby. An option with a count is named by its label and count together."}})
|
|
476
|
-
${
|
|
603
|
+
/>`}],a11y:{role:"combobox",keyboard:["Enter, Space, or an arrow key opens the list","Arrow keys, Home, and End move through the options; typing a letter jumps to the next match","Enter or Space chooses the highlighted option","Escape or Tab closes the list without choosing"],notes:"A select-only combobox: a button with role combobox that opens a listbox on a plain click, so a synthetic element.click() opens it as reliably as a pointer does, and the list renders in the page rather than in browser chrome an automated session cannot see. Focus stays on the button and aria-activedescendant tracks the highlighted option. The label is linked with aria-labelledby; errors set aria-invalid and link with aria-describedby. An option with a count is named by its label and count together."}});function Ss(e){const t=Je.inputSchema.properties.option;return{...Je.inputSchema,properties:{...Je.inputSchema.properties,...t===void 0?{}:{option:{...t,enum:e.map(n=>n.label)}}}}}function As(e,t){return e!==void 0?[{part:"error",label:e,state:{}}]:t!==void 0?[{part:"hint",label:t,state:{}}]:[]}function js(e){const{label:t,options:n,value:o,onChange:s,placeholder:r,hint:l,error:d,name:c,disabled:h=!1,required:g=!1,agentName:u,agentTool:b=!0,...m}=e,S=Z(),f=ue(),y=ce(),k=i.useId(),[T,O]=i.useState(!1),[A,E]=i.useState(-1),D=i.useRef(null),U=i.useRef(null),N=i.useRef(null),W=i.useRef(null),$=i.useRef(new Map),_=i.useRef(s);_.current=s;const V=i.useRef(n);V.current=n;const M=i.useRef(y);M.current=y;const I=i.useRef(q({component:an.name})),j=i.useRef(!0);i.useEffect(()=>(j.current=!0,()=>{j.current=!1}),[]);const z=n.findIndex(C=>C.value===o),L=n[z],p=i.useCallback(C=>{h||(E(C??Math.max(z,0)),O(!0))},[h,z]),x=i.useCallback(()=>{O(!1),E(-1)},[]);i.useEffect(()=>{h&&x()},[h,x]),pt({open:T,anchor:U,floating:N,matchWidth:!0,boundary:D,onDismiss:x}),i.useEffect(()=>{if(!T||A<0)return;const C=n[A],ee=C===void 0?void 0:$.current.get(C.value);ee!==void 0&&typeof ee.scrollIntoView=="function"&&ee.scrollIntoView({block:"nearest"})},[T,A,n]);const P=i.useCallback(C=>{x(),s(C)},[x,s]),v=i.useCallback(C=>{const ee=$.current.get(C);if(ee!==void 0){ee.click();return}me(()=>_.current(C))},[]),K=i.useCallback(async C=>{const ee=typeof C.option=="string"?C.option:"",J=V.current,R=J.find(F=>F.label===ee);return R===void 0?`No option named "${ee}". This dropdown offers: ${J.map(F=>`"${F.label}"`).join(", ")}.`:(v(R.value),await pe(),j.current?`Selected. The dropdown is now:
|
|
604
|
+
${M.current([I.current])}`:"The selection removed this dropdown from the page.")},[v]),ne=i.useMemo(()=>Ss(n),[n]),se=de({spec:Je,label:u??t,inputSchema:ne,enabled:b&&!h,execute:K}),re=n.map((C,ee)=>({part:"option",label:C.label,state:{...C.value===o?{checked:!0}:{},...T&&ee===A?{active:!0}:{},...C.count===void 0?{}:{count:String(C.count)},...h?{disabled:!0}:{}}})),he=q({component:an.name,label:t,tool:se,state:{...L===void 0?{}:{value:o},empty:L===void 0,disabled:h,required:g,invalid:d!==void 0},parts:[...re,...As(d,l)]});if(I.current=he,S==="agent")return h||f==="never"?a.jsx(te,{node:he}):a.jsx(ke,{node:he,isActionable:C=>C.part==="option",onActivate:(C,ee)=>{const J=n[ee];J!==void 0&&v(J.value)}});const we=`${k}-label`,Ce=`${k}-listbox`,Se=C=>`${k}-option-${C}`,fe=d!==void 0?`${k}-error`:l!==void 0?`${k}-hint`:void 0,Pe=C=>{const ee=A<0?z:A,J=C.toLowerCase();for(let R=1;R<=n.length;R+=1){const F=(ee+R+n.length)%n.length;if(n[F]?.label.toLowerCase().startsWith(J))return F}return-1},ve=C=>{const ee=n.length-1,J=C.key;if(!T){if(J==="ArrowDown"||J==="ArrowUp"||J==="Enter"||J===" "){C.preventDefault(),p();return}if(J==="Home"||J==="End"){C.preventDefault(),p(J==="Home"?0:ee);return}if(J.length===1&&!C.altKey&&!C.ctrlKey&&!C.metaKey){const R=Pe(J);R>=0&&p(R)}return}if(J==="Escape"||J==="Tab"){J==="Escape"&&C.preventDefault(),x();return}if(J==="Enter"||J===" "){C.preventDefault();const R=n[A];R!==void 0?P(R.value):x();return}if(J==="ArrowDown"||J==="ArrowUp"||J==="Home"||J==="End"){C.preventDefault();const R=J==="Home"?0:J==="End"?ee:J==="ArrowDown"?Math.min(A+1,ee):Math.max(A-1,0);E(R);return}if(J.length===1&&!C.altKey&&!C.ctrlKey&&!C.metaKey){const R=Pe(J);R>=0&&E(R)}},xe=C=>{C.key===" "&&C.preventDefault()},Ae=C=>{const ee=C.relatedTarget;ee instanceof Node&&D.current?.contains(ee)||x()};return a.jsxs("div",{...m,...X(he),ref:C=>{D.current=C;const ee=m.ref;typeof ee=="function"?ee(C):ee!=null&&(ee.current=C)},children:[a.jsx("label",{id:we,htmlFor:k,children:t}),a.jsxs("span",{...B({part:"control",state:{}}),children:[a.jsxs("button",{id:k,type:"button",role:"combobox",...B({part:"input",state:{}}),ref:C=>{U.current=C},disabled:h,"aria-labelledby":we,"aria-haspopup":"listbox","aria-expanded":T,"aria-controls":Ce,"aria-activedescendant":T&&A>=0?Se(A):void 0,"aria-required":g||void 0,"aria-invalid":d!==void 0||void 0,"aria-describedby":fe,onClick:()=>T?x():p(),onKeyDown:ve,onKeyUp:xe,onBlur:Ae,children:[a.jsx("span",{children:L===void 0?r??"Choose":L.label}),L?.count===void 0?null:a.jsx("span",{"aria-hidden":"true",children:L.count})]}),a.jsx("div",{popover:"manual",hidden:!T,ref:N,children:a.jsx("div",{id:Ce,role:"listbox","aria-labelledby":we,tabIndex:-1,ref:W,onMouseDown:C=>C.preventDefault(),children:n.map((C,ee)=>{const J=`${Se(ee)}-label`,R=`${Se(ee)}-count`;return a.jsxs("div",{id:Se(ee),role:"option",tabIndex:-1,"aria-selected":C.value===o,"aria-labelledby":C.count===void 0?void 0:`${J} ${R}`,ref:F=>{F===null?$.current.delete(C.value):$.current.set(C.value,F)},...B(re[ee]??{part:"option",state:{}}),onPointerMove:()=>{ee!==A&&E(ee)},onClick:()=>{P(C.value),T&&U.current?.focus()},children:[a.jsx("span",{id:J,children:C.label}),C.count===void 0?null:a.jsx("span",{id:R,"aria-hidden":"true",children:C.count})]},C.value)})})})]}),c===void 0?null:a.jsx("input",{type:"hidden",name:c,value:L===void 0?"":o}),d!==void 0?a.jsx("p",{id:fe,...B({part:"error",state:{}}),children:d}):l!==void 0?a.jsx("p",{id:fe,...B({part:"hint",state:{}}),children:l}):null]})}const ao=Y({name:"Shell",category:"layout",summary:"The page-level frame: a sidebar and a main content region, with the landmark wiring done once. On a phone the sidebar becomes a drawer behind a menu button.",whenToUse:"Use it once, at the root of an app view. Put the brand in bar, a Nav in side, and the page in children. It renders the main and complementary landmarks, a skip-to-content control for keyboard users, and the mobile drawer behaviour, so none of that is rebuilt per app. Like Stack it is silent in agent view: its regions speak for themselves.",whenNotToUse:"Do not use it inside another Shell, or anywhere below the top of the page; a region within a page is a Panel. Do not use it just to put two columns next to each other; that is Stack.",status:"experimental",props:{children:{kind:"node",description:"The page content. Rendered inside the main landmark.",required:!0},side:{kind:"node",description:"The sidebar content, usually a Nav. On narrow viewports it becomes the drawer behind the menu button, and the drawer closes itself when a link inside it is followed."},bar:{kind:"node",description:"What stays visible when the sidebar collapses to a top bar: typically the brand link. The menu button renders next to it automatically."},sideLabel:{kind:"string",description:"Accessible name for the sidebar landmark.",default:"Sidebar"},skipLabel:{kind:"string",description:"Text of the skip control that moves focus to the main region. Visually hidden until focused.",default:"Skip to content"},menuLabel:{kind:"string",description:"Label of the drawer button while the drawer is closed.",default:"Menu"},closeLabel:{kind:"string",description:"Label of the drawer button while the drawer is open.",default:"Close"},collapsible:{kind:"boolean",description:"Lets a person hide the sidebar on wide viewports too. A second toggle appears beside the bar there, and while collapsed the page takes the narrow layout: the bar runs across the top and the sidebar is gone until it is shown again.",default:!1},collapsed:{kind:"boolean",description:"Whether the sidebar is collapsed on wide viewports, when the owner keeps that state. Pair it with onCollapsedChange."},defaultCollapsed:{kind:"boolean",description:"Whether a collapsible sidebar starts collapsed when the Shell keeps its own state.",default:!1},onCollapsedChange:{kind:"handler",description:"Called with the collapsed state the Shell wants. Use it to remember the choice across visits."},drawerOpen:{kind:"boolean",description:"Whether the narrow-viewport drawer is open, when the owner keeps that state: a guided tour that steps into the sidebar, or a page that closes the drawer after an action. Pair it with onDrawerOpenChange."},onDrawerOpenChange:{kind:"handler",description:"Called with the drawer state the Shell wants: true from the menu toggle, false from the close toggle or a link followed inside the drawer."},hideLabel:{kind:"string",description:"Label of the wide-viewport toggle while the sidebar is shown.",default:"Hide menu"},showLabel:{kind:"string",description:"Label of the wide-viewport toggle while the sidebar is collapsed.",default:"Show menu"}},state:{collapsed:{description:"Present while a collapsible sidebar is hidden on wide viewports. Narrow viewports ignore it and keep the drawer.",attribute:"data-sprint-collapsed"},open:{description:"Present while the mobile drawer is open. On wide viewports the sidebar is always visible and this state is inert.",attribute:"data-sprint-open"}},a11y:{notes:"Renders the only main element and an aside named by sideLabel, so the page has its landmarks without any consumer wiring. The first focusable element is a skip control that moves focus to main without touching the URL, which keeps it safe in hash-routed apps. The drawer button carries aria-expanded and aria-controls."},relatedComponents:["Nav","Panel","Stack"],examples:[{title:"A sidebar app shell",description:"One Shell per view. The sidebar collapses to a top bar with a drawer on narrow screens, and an agent reading the page sees the nav and the content with no frame in between.",code:`<Shell
|
|
477
605
|
bar={<Link href="#/">ACME</Link>}
|
|
478
606
|
side={
|
|
479
607
|
<Nav label="Main">
|
|
@@ -496,7 +624,18 @@ ${I.current([q.current])}`:"The selection removed this dropdown from the page.")
|
|
|
496
624
|
}
|
|
497
625
|
>
|
|
498
626
|
<Text>Quarterly numbers land here.</Text>
|
|
499
|
-
</Shell>`}
|
|
627
|
+
</Shell>`},{title:"A drawer the page controls",description:"drawerOpen and onDrawerOpenChange hand the phone drawer to the page, so a guided tour can open it to point at a link and close it again.",code:`<Shell
|
|
628
|
+
drawerOpen={drawerOpen}
|
|
629
|
+
onDrawerOpenChange={setDrawerOpen}
|
|
630
|
+
bar={<Link href="#/">ACME</Link>}
|
|
631
|
+
side={
|
|
632
|
+
<Nav label="Main">
|
|
633
|
+
<Link href="#/reports" active>Reports</Link>
|
|
634
|
+
</Nav>
|
|
635
|
+
}
|
|
636
|
+
>
|
|
637
|
+
<Button onClick={() => setDrawerOpen(true)}>Show me the menu</Button>
|
|
638
|
+
</Shell>`}]});function Rs(e){const{side:t,bar:n,sideLabel:o="Sidebar",skipLabel:s="Skip to content",menuLabel:r="Menu",closeLabel:l="Close",collapsible:d=!1,collapsed:c,defaultCollapsed:h=!1,onCollapsedChange:g,drawerOpen:u,onDrawerOpenChange:b,hideLabel:m="Hide menu",showLabel:S="Show menu",children:f,...y}=e,k=Z(),[T,O]=i.useState(!1),A=u??T,E=i.useRef(b);E.current=b;const D=i.useCallback(I=>{O(I),E.current?.(I)},[]),[U,N]=i.useState(h),W=d&&(c??U),$=i.useId(),_=i.useRef(null),V=i.useCallback(I=>{const j=I.target;j instanceof Element&&j.closest("a")!==null&&D(!1)},[D]),M=q({component:ao.name,region:!0,state:{open:A,collapsed:W}});return k==="agent"?a.jsxs(a.Fragment,{children:[n,t,f]}):a.jsxs("div",{...y,...X(M),children:[a.jsx("button",{type:"button",onClick:()=>_.current?.focus(),children:s}),a.jsxs("aside",{"aria-label":o,children:[a.jsxs("div",{children:[n,a.jsxs("span",{children:[a.jsx(dt,{agentTool:!1,"aria-expanded":A,"aria-controls":$,onClick:()=>D(!A),children:A?l:r}),d?a.jsx(dt,{agentTool:!1,"aria-expanded":!W,"aria-controls":$,onClick:()=>{N(!W),g?.(!W)},children:W?S:m}):null]})]}),a.jsx("div",{id:$,onClick:V,children:t})]}),a.jsx("main",{ref:_,tabIndex:-1,children:f})]})}const oo=Y({name:"Stack",category:"layout",summary:"The one-dimensional layout primitive: a row, a column, or an auto-filling grid, with spacing drawn from the space scale. It renders a plain box and nothing else.",whenToUse:"Use it wherever two or more things sit next to each other. Prefer it over a bare div with inline styles so spacing stays on the scale. Stack is invisible in agent view: it emits no line, because an agent does not care how a region is arranged, only what is in it.",whenNotToUse:'Do not use it to draw a bordered region with a header; that is Panel. Do not nest three deep to fake a grid; use direction="grid".',status:"experimental",props:{children:{kind:"node",description:"The items to lay out.",required:!0},direction:{kind:"enum",description:'Axis. "grid" fills as many equal columns as fit, each at least min wide.',values:["row","column","grid"],default:"column"},gap:{kind:"enum",description:"Space between items, from the space scale: none, hairline, snug, tight, medium, normal, loose, wide, vast, smallest to largest.",values:["none","hairline","snug","tight","medium","normal","loose","wide","vast"],default:"normal"},padding:{kind:"enum",description:"Space inside the stack's edges, on the same scale as gap. Use it for a stack that is itself a bordered or filled region; between siblings, prefer the parent's gap.",values:["none","hairline","snug","tight","medium","normal","loose","wide","vast"],default:"none"},align:{kind:"enum",description:"Cross-axis alignment.",values:["start","center","end","stretch","baseline"]},justify:{kind:"enum",description:"Main-axis distribution.",values:["start","center","end","between"]},wrap:{kind:"boolean",description:"Let a row wrap onto more lines instead of overflowing.",default:!1},collapse:{kind:"boolean",description:"Stack a row into a column on narrow viewports. This is how a toolbar survives a phone.",default:!1},min:{kind:"enum",description:'Minimum track width for direction="grid", from a fixed scale of rem lengths. Tracks never exceed the container. Scale values are mapped in the stylesheet through data-sprint-min, so they work under a strict Content Security Policy. Any other CSS length is still accepted as an escape hatch, but it is written to an inline style attribute, which a style-src policy without unsafe-inline blocks: under such a policy an off-scale grid falls back to one column.',values:["10rem","12rem","14rem","16rem","18rem","20rem","22rem","24rem","28rem","32rem"],default:"18rem"}},state:{direction:{description:"The axis in use.",attribute:"data-sprint-direction",values:["row","column","grid"]},gap:{description:"The spacing step in use.",attribute:"data-sprint-gap",values:["none","hairline","snug","tight","medium","normal","loose","wide","vast"]},padding:{description:"The inner spacing step, when there is one.",attribute:"data-sprint-padding",values:["hairline","snug","tight","medium","normal","loose","wide","vast"]},align:{description:"Cross-axis alignment, when one was asked for.",attribute:"data-sprint-align",values:["start","center","end","stretch","baseline"]},justify:{description:"Main-axis distribution, when one was asked for.",attribute:"data-sprint-justify",values:["start","center","end","between"]},wrap:{description:"Present when a row is allowed to wrap.",attribute:"data-sprint-wrap"},collapse:{description:"Present when the row stacks into a column on narrow viewports.",attribute:"data-sprint-collapse"},min:{description:'The minimum track width in use, present only when direction="grid". A value off the scale is carried here too, with the length itself in an inline style.',attribute:"data-sprint-min"}},examples:[{title:"A row of actions",description:"Wrapping keeps a toolbar from overflowing on a narrow screen.",code:`<Stack direction="row" gap="tight" wrap>
|
|
500
639
|
<Button>Cancel</Button>
|
|
501
640
|
<Button tone="action">Confirm</Button>
|
|
502
641
|
</Stack>`},{title:"A responsive card grid",description:"Tracks fill the container and never go below min, so this is one column on a phone and three on a desktop with no media query of your own.",code:`<Stack direction="grid" min="16rem">
|
|
@@ -505,7 +644,11 @@ ${I.current([q.current])}`:"The selection removed this dropdown from the page.")
|
|
|
505
644
|
</Stack>`},{title:"A header bar that stacks on a phone",code:`<Stack direction="row" justify="between" align="center" collapse>
|
|
506
645
|
<Heading level={1}>Button</Heading>
|
|
507
646
|
<Tag tone="warning">experimental</Tag>
|
|
508
|
-
</Stack>`}
|
|
647
|
+
</Stack>`},{title:"A padded, dense list",description:"padding insets the stack's own content, and a small gap packs rows closely, without a wrapper element or a class.",code:`<Stack gap="snug" padding="medium">
|
|
648
|
+
<Text>Opening hymn</Text>
|
|
649
|
+
<Text>Invocation</Text>
|
|
650
|
+
<Text>Sacrament hymn</Text>
|
|
651
|
+
</Stack>`}]}),io=["10rem","12rem","14rem","16rem","18rem","20rem","22rem","24rem","28rem","32rem"];function Ls(e){return io.includes(e)}function Ps(e,t){return Ls(e)?t:{...t,"--sprint-stack-min":e}}function Os(e){const{direction:t="column",gap:n="normal",padding:o="none",align:s,justify:r,wrap:l=!1,collapse:d=!1,min:c="18rem",children:h,style:g,...u}=e,b=Z(),m=t==="grid",S=q({component:oo.name,state:{direction:t,gap:n,padding:o==="none"?void 0:o,align:s,justify:r,wrap:l,collapse:d,min:m?c:void 0}});return b==="agent"?a.jsx(a.Fragment,{children:h}):a.jsx("div",{...u,...X(S),style:m?Ps(c,g):g,children:h})}const so=Y({name:"Steps",category:"display",summary:"An ordered set of numbered steps a person works through: each one a number badge, a short title and an optional body, with a rule between them. A step can be marked done or current, so the list doubles as a record of how far someone has got.",whenToUse:"Use it when the order is the instruction: a handful of things to do one after another, each worth a title of its own, like the two things to send someone or the stages of a setup. Mark the step in progress as current and the finished ones as done when the page knows; leave every state off when the steps are simply instructions. Each step is an addressable part carrying its position and state, so an agent can say which step is next without counting lines.",whenNotToUse:"Do not use it for a plain numbered list of short points with no titles or progress; that is List with ordered. Do not use it as a wizard that moves between screens: Steps only displays where someone is, it has no actions and registers no WebMCP tool, because there is nothing to press and an agent reads every step and its state from the agent view. Pair it with a Button when the page itself advances. Do not put components or links in a step; title and body are plain strings.",status:"experimental",props:{label:{kind:"string",description:'What the steps achieve, as a short phrase like "Send Tess two things". Names the list for a screen reader and for the agent view.',required:!0},steps:{kind:"array",description:'The steps in order, each { title: string; body?: string; state?: "done" | "current" }. Title is the instruction in a few words; body is an optional sentence of detail. A step with no state is upcoming. Mark at most one step current.',required:!0},doneLabel:{kind:"string",description:"What a screen reader hears as the description of a finished step, since the done mark is drawn rather than written.",default:"Done"},emptyLabel:{kind:"string",description:"What the list says when it has no steps.",default:"No steps"}},state:{steps:{description:"How many steps there are.",attribute:"data-sprint-steps"},complete:{description:"Present when every step is done.",attribute:"data-sprint-complete"},empty:{description:"Present when there are no steps.",attribute:"data-sprint-empty"},index:{description:"On a step: its 1-based position, which is also the number in its badge.",attribute:"data-sprint-index"},done:{description:"On a step: present once the step is finished.",attribute:"data-sprint-done"},current:{description:"On a step: present on the step in progress.",attribute:"data-sprint-current"}},agentView:{example:'- **Steps** "Send Tess two things" [steps=2]\n - part `step` "Copy the link" [index=1]\n - part `step` "Pass on the emoji" [index=2]'},a11y:{role:"list",notes:'A real ol named by its label, with an explicit list role because the drawn badges require list-style none and Safari would otherwise drop the list semantics, so the position of each step is announced. The badge number is aria-hidden for the same reason. The current step carries aria-current="step", and a done step is described by doneLabel. Title and body are read as one item, separated by a colon that is hidden visually.'},relatedComponents:["List","Progress","Panel"],examples:[{title:"Send Tess two things",description:"The plainest case: two instructions in order, with no progress to report.",code:`<Steps
|
|
509
652
|
label="Send Tess two things"
|
|
510
653
|
steps={[{ title: "Copy the link" }, { title: "Pass on the emoji" }]}
|
|
511
654
|
/>`},{title:"Partway through",description:"A finished step, the one in progress, and one still to come, each with a line of detail.",code:`<Steps
|
|
@@ -529,8 +672,8 @@ ${I.current([q.current])}`:"The selection removed this dropdown from the page.")
|
|
|
529
672
|
{ title: "Copy the link", state: "done" },
|
|
530
673
|
{ title: "Pass on the emoji", state: "done" },
|
|
531
674
|
]}
|
|
532
|
-
/>`}]}),
|
|
533
|
-
${
|
|
675
|
+
/>`}]}),Es={role:"list"};function Ds(e){return e.body===void 0||e.body===""?e.title:`${e.title}: ${e.body}`}function zn(e,t){return{part:"step",label:Ds(e),state:{index:String(t+1),...e.state==="done"?{done:!0}:{},...e.state==="current"?{current:!0}:{}}}}function Ms(e){const{label:t,steps:n,doneLabel:o="Done",emptyLabel:s="No steps",...r}=e,l=Z(),d=i.useId(),c=n.length===0,h=n.map(zn),g=!c&&n.every(b=>b.state==="done"),u=q({component:so.name,label:t,state:{steps:String(n.length),complete:g,empty:c},parts:h});return l==="agent"?a.jsx(te,{node:u}):a.jsxs("ol",{...r,...X(u),...Es,"aria-label":t,children:[c?a.jsx("li",{children:s}):null,n.map((b,m)=>{const S=h[m]??zn(b,m),f=b.state==="done",y=`${d}-${m}-done`;return a.jsxs("li",{...B(S),"aria-current":b.state==="current"?"step":void 0,"aria-describedby":f?y:void 0,children:[a.jsx("span",{"aria-hidden":"true",children:m+1}),a.jsxs("div",{children:[a.jsx("strong",{children:b.title}),b.body===void 0||b.body===""?null:a.jsxs(a.Fragment,{children:[a.jsx("span",{children:": "}),a.jsx("p",{children:b.body})]})]}),f?a.jsx("span",{id:y,hidden:!0,children:o}):null]},`${m}-${b.title}`)})]})}const On={verb:"set",description:"Switch this setting on or off by stating the end state, exactly as a person clicking it would. The change takes effect immediately. Setting the state it already has succeeds and changes nothing, so the call is safe to retry. Returns the switch's state after the call.",inputSchema:{type:"object",properties:{on:{type:"boolean",description:"The end state: true leaves the switch on, false leaves it off."}},required:["on"]},readOnly:!1,untrustedContent:!0,registeredWhen:"The switch is mounted, enabled, has a resolvable label, and no other component claims the same tool name.",unregisteredWhen:"The switch unmounts or becomes disabled."},on=Y({name:"Switch",category:"input",summary:"An on/off setting that takes effect the moment it changes. It registers one set tool that takes the end state rather than toggling.",whenToUse:"Use it for a live setting: enabling telemetry, muting alerts, switching a feed. The set tool takes on as true or false, so an agent states the end state and never has to read before writing.",whenNotToUse:"Do not use it for a boolean a form will submit later; that is a Checkbox, and the distinction is when the change takes effect. Do not use it to choose between two named modes a person should see side by side, which is a SegmentedControl.",status:"experimental",props:{label:{kind:"string",description:'What the setting controls. Names the switch for a screen reader and derives the tool name, so prefer a noun phrase such as "Live telemetry".',required:!0},on:{kind:"boolean",description:"Whether the setting is on. The switch is fully controlled.",required:!0},onChange:{kind:"handler",description:"Called with the new state. The set tool drives a real click, so this runs for agent changes too.",required:!0},disabled:{kind:"boolean",description:"Disable the switch and unregister its set tool.",default:!1},agentName:{kind:"string",description:"Override the label used to derive the tool name, when two switches on a page would otherwise collide."},agentTool:{kind:"boolean",description:"Set false to render the switch without registering a set tool.",default:!0}},state:{on:{description:"Present while the setting is on.",attribute:"data-sprint-on"},disabled:{description:"Present when the switch cannot be changed.",attribute:"data-sprint-disabled"}},tools:{set:On},agentView:{example:'- **Switch** "Live telemetry" [on] → tool `set-live-telemetry`'},examples:[{title:"A live setting",description:"In agent view the switch renders as one control; pressing it toggles, while the set tool states the end state.",code:'<Switch label="Live telemetry" on={telemetry} onChange={setTelemetry} />'},{title:"A disabled switch",description:"Disabled unregisters the tool, so an agent cannot change what a person could not.",code:'<Switch label="Ground link" on disabled onChange={setLink} />'}],a11y:{role:"switch",keyboard:["Space toggles","Enter toggles"],notes:"A button with role switch and aria-checked, so the label and state read together. The thumb moves by a single-axis stepped translation and respects prefers-reduced-motion."}});function Ns(e){const{label:t,on:n,onChange:o,disabled:s=!1,agentName:r,agentTool:l=!0,ref:d,...c}=e,h=Z(),g=ue(),u=ce(),b=i.useRef(null),m=i.useCallback(D=>{b.current=D,typeof d=="function"?d(D):d!=null&&(d.current=D)},[d]),S=i.useRef(o);S.current=o;const f=i.useRef(n);f.current=n;const y=i.useRef(u);y.current=u;const k=i.useRef(q({component:on.name})),T=i.useRef(!0);i.useEffect(()=>(T.current=!0,()=>{T.current=!1}),[]);const O=i.useCallback(async D=>{const U=D.on;if(typeof U!="boolean")return'Pass "on" as true or false; it states the end state.';const N=U===f.current;if(!N){const $=b.current;$!==null?$.click():me(()=>S.current(U))}return await pe(),T.current?`${N?`Already ${U?"on":"off"}`:`Switched ${U?"on":"off"}`}. The switch is now:
|
|
676
|
+
${y.current([k.current])}`:"The change removed this switch from the page."},[]),A=de({spec:On,label:r??t,enabled:l&&!s,execute:O}),E=q({component:on.name,label:t,tool:A,state:{on:n,disabled:s}});return k.current=E,h==="agent"?s||g==="never"?a.jsx(te,{node:E}):a.jsx(ze,{node:E,ref:m,onClick:()=>o(!n)}):a.jsxs("button",{...c,...X(E),type:"button",role:"switch","aria-checked":n,disabled:s,ref:m,onClick:()=>o(!n),children:[a.jsx("span",{...B({part:"track",state:{}}),"aria-hidden":"true",children:a.jsx("span",{...B({part:"thumb",state:{}})})}),t]})}const ro=Y({name:"Table",category:"display",summary:"A data grid built from columns and rows rather than from markup. In the agent stream it reads as a compact Markdown table; in the DOM each cell is addressable as a part carrying its column and row. On a narrow screen every row restacks into a labelled block instead of scrolling sideways.",whenToUse:"Use it for any set of records with the same shape: props, attributes, conventions, results. Passing data instead of children is what lets the agent view carry the cells and the human view restack them on a phone.",whenNotToUse:"Do not use it for page layout; that is Stack. Do not put components in cells: cells are flattened to text for the agent view, so a Button inside one would lose its tool.",status:"experimental",props:{label:{kind:"string",description:"What this table is a table of. Used as its accessible name and read back by the agent view.",required:!0},columns:{kind:"array",description:"Column definitions, in display order: { key, header, align?, width? }. The key addresses the cell in each row and appears on the cell as data-sprint-column. width is one of 4rem, 5rem, 6rem, 7rem, 8rem, 9rem, 10rem, 12rem, 14rem, 16rem, 20rem, or 24rem, mapped in the stylesheet through data-sprint-width on the header cell so it works under a strict Content Security Policy; any other CSS length is still accepted but is written to an inline style attribute, which a style-src policy without unsafe-inline blocks.",required:!0},rows:{kind:"array",description:"Rows in display order: { id?, cells }, where cells maps a column key to inline content. id names the row for an agent and defaults to its 1-based position.",required:!0},emptyLabel:{kind:"string",description:"What the table says when it has no rows.",default:"No rows"},loading:{kind:"boolean",description:"Set while the rows are being fetched. Sets aria-busy and sweeps a bar along the top edge. Existing rows stay visible; with none yet, the empty slot says loadingLabel instead of emptyLabel.",default:!1},loadingLabel:{kind:"string",description:"What the empty slot says while loading.",default:"Loading"}},state:{columns:{description:"How many columns the table has.",attribute:"data-sprint-columns"},rows:{description:"How many rows the table currently has.",attribute:"data-sprint-rows"},empty:{description:"Present when the table has no rows.",attribute:"data-sprint-empty"},loading:{description:"Present while the rows are being fetched. Alongside empty it means nothing has arrived yet, not that there is nothing.",attribute:"data-sprint-loading"},column:{description:"On a cell: which column it belongs to.",attribute:"data-sprint-column"},row:{description:"On a cell: which row it belongs to.",attribute:"data-sprint-row"},width:{description:"On a column header: the width its column asked for, if any. A value off the scale is carried here too, with the length itself in an inline style.",attribute:"data-sprint-width"},align:{description:"On a cell: the alignment its column asked for, if any.",attribute:"data-sprint-align",values:["start","end"]}},agentView:{example:`- **Table** "Props" [columns=2, rows=1]
|
|
534
677
|
| row | prop | kind |
|
|
535
678
|
| --- | --- | --- |
|
|
536
679
|
| tone | tone | enum |`},examples:[{title:"A reference table",description:'Cells are addressable: [data-sprint-part="cell"][data-sprint-column="kind"] selects a column without knowing anything about the markup.',code:`<Table
|
|
@@ -550,9 +693,27 @@ ${w.current([v.current])}`:"The change removed this switch from the page."},[]),
|
|
|
550
693
|
loading={isFetching}
|
|
551
694
|
columns={[{ key: "name", header: "Name" }]}
|
|
552
695
|
rows={loadouts ?? []}
|
|
553
|
-
/>`}],a11y:{role:"table",notes:"Column headers keep scope=col in every layout. On narrow screens each cell repeats its column header visually, marked aria-hidden so the real header association is not announced twice."}}),
|
|
696
|
+
/>`}],a11y:{role:"table",notes:"Column headers keep scope=col in every layout. On narrow screens each cell repeats its column header visually, marked aria-hidden so the real header association is not announced twice."}}),lo=["4rem","5rem","6rem","7rem","8rem","9rem","10rem","12rem","14rem","16rem","20rem","24rem"];function Is(e){return lo.includes(e)}function $s(e){if(!(e===void 0||Is(e)))return{width:e}}function sn(e,t){return e.id??String(t+1)}function co(e,t){return{column:e.key,row:t,...e.align===void 0?{}:{align:e.align}}}function Us(e,t){return t.flatMap((n,o)=>e.map(s=>{const r=be(n.cells[s.key]);return{part:"cell",state:co(s,sn(n,o)),...r===void 0?{}:{label:r}}}))}function qs(e){const{label:t,columns:n,rows:o,emptyLabel:s="No rows",loading:r=!1,loadingLabel:l="Loading",...d}=e,c=Z(),h=o.length===0,g=q({component:ro.name,label:t,state:{columns:String(n.length),rows:String(o.length),empty:h,loading:r},parts:Us(n,o)});return c==="agent"?a.jsx(te,{node:ma(g)}):a.jsxs("table",{...d,...X(g),role:"table","aria-label":t,"aria-busy":r||void 0,children:[a.jsx("thead",{role:"rowgroup",children:a.jsx("tr",{role:"row",children:n.map(u=>a.jsx("th",{role:"columnheader",scope:"col","data-sprint-column":u.key,"data-sprint-width":u.width,style:$s(u.width),children:u.header},u.key))})}),a.jsx("tbody",{role:"rowgroup",children:h?a.jsx("tr",{role:"row",children:a.jsx("td",{role:"cell",colSpan:n.length,children:a.jsx("span",{children:r?l:s})})}):o.map((u,b)=>a.jsx("tr",{role:"row",children:n.map(m=>a.jsxs("td",{role:"cell",...B({part:"cell",state:co(m,sn(u,b))}),children:[a.jsx("span",{"aria-hidden":"true",children:m.header}),a.jsx("div",{children:u.cells[m.key]})]},m.key))},sn(u,b)))})]})}const et={verb:"select",description:"Show one of these tabs by its visible label, exactly as a person clicking the tab would. Only the selected tab's panel is on the page, so read the page again after switching to see its contents. Returns the tabs' state after the change.",inputSchema:{type:"object",properties:{tab:{type:"string",description:"The visible label of the tab to show."}},required:["tab"]},readOnly:!1,untrustedContent:!0,registeredWhen:"The tabs are mounted, at least one tab is enabled, and no other component claims the same tool name. The registered schema enumerates the enabled tabs' labels.",unregisteredWhen:"The tabs unmount or every tab is disabled."},rn=Y({name:"Tabs",category:"navigation",summary:"Sibling views of one subject, one shown at a time, with real tablist, tab and tabpanel semantics. Registers one select tool enumerating the tabs.",whenToUse:"Use to switch between a few views of the same thing without leaving the page: coming up, past and by member for one set of speakers; details and history for one record. Tabs hold data: each is { value, label, panel, count?, disabled? }, and only the selected tab's panel is mounted. An optional actions slot sits at the end of the tab row.",whenNotToUse:"Do not use to pick a value that filters or changes something else on the page; that is a SegmentedControl, a radio group. Do not use for navigation between pages with their own URLs; that is a Nav. Do not use when a person needs to compare the views side by side.",status:"experimental",props:{label:{kind:"string",description:'What the tabs switch between, such as "Speakers". Names the tablist and derives the select tool name.',required:!0},tabs:{kind:"array",description:"The tabs in order: { value, label, panel, count?, disabled? }. panel is the content shown while the tab is selected and may hold any components. count renders as a chip beside the label and reaches the agent view as part state.",required:!0},value:{kind:"string",description:"The selected tab's value, when the page owns that state. Pair it with onChange. A disabled or unknown value falls back to the first enabled tab."},defaultValue:{kind:"string",description:"The tab selected first when the Tabs keep their own state."},onChange:{kind:"handler",description:"Called with the value of the tab a person or an agent selects."},actions:{kind:"node",description:"Controls at the end of the tab row, such as an add Button that applies to every tab."},agentName:{kind:"string",description:"Override the label used to derive the tool name."},agentTool:{kind:"boolean",description:"Set false to render the tabs without registering the select tool.",default:!0}},state:{value:{description:"The selected tab's label.",attribute:"data-sprint-value"}},tools:{select:et},agentView:{example:'- **Tabs** "Speakers" [value=Coming up] → tool `select-speakers`\n - part `tab` "Coming up" [count=4, selected]\n - part `tab` "Past"'},examples:[{title:"Views of one subject",description:"Only the selected panel is on the page. An agent switches with the select tool or the tab controls in the agent view, then reads the new panel.",code:`<Tabs
|
|
697
|
+
label="Speakers"
|
|
698
|
+
tabs={[
|
|
699
|
+
{ value: "upcoming", label: "Coming up", count: 4, panel: <UpcomingSpeakers /> },
|
|
700
|
+
{ value: "past", label: "Past", panel: <PastSpeakers /> },
|
|
701
|
+
{ value: "member", label: "By member", panel: <SpeakersByMember /> },
|
|
702
|
+
]}
|
|
703
|
+
/>`},{title:"Tabs with an action",description:"actions sits at the end of the tab row and stays put while the panels change. A disabled tab is visible but cannot be selected.",code:`<Tabs
|
|
704
|
+
label="Record"
|
|
705
|
+
value={view}
|
|
706
|
+
onChange={setView}
|
|
707
|
+
actions={<Button size="small">Export</Button>}
|
|
708
|
+
tabs={[
|
|
709
|
+
{ value: "details", label: "Details", panel: <Details /> },
|
|
710
|
+
{ value: "history", label: "History", panel: <History /> },
|
|
711
|
+
{ value: "audit", label: "Audit", disabled: true, panel: null },
|
|
712
|
+
]}
|
|
713
|
+
/>`}],a11y:{role:"tablist",keyboard:["Left and Right Arrow move to the previous or next enabled tab and show it","Home and End show the first and last enabled tab","Tab moves from the selected tab into its panel"],notes:"Roving tabindex across the tabs, with selection following focus. The panel is a focusable tabpanel labelled by its tab. A count chip is hidden from assistive technology, so the tab is named by its label alone."}});function Ws(e){const t=et.inputSchema.properties.tab;return{...et.inputSchema,properties:{...et.inputSchema.properties,...t===void 0?{}:{tab:{...t,enum:[...e]}}}}}function Gn(e){return e.find(t=>t.disabled!==!0)?.value}function Bs(e){const{label:t,tabs:n,value:o,defaultValue:s,onChange:r,actions:l,agentName:d,agentTool:c=!0,...h}=e,g=Z(),u=ue(),b=ce(),m=i.useId(),[S,f]=i.useState(s??Gn(n)),y=o??S,k=n.find(v=>v.value===y&&v.disabled!==!0)?.value??Gn(n),T=i.useRef(new Map),O=i.useRef(n);O.current=n;const A=i.useRef(r);A.current=r;const E=i.useRef(b);E.current=b;const D=i.useRef(q({component:rn.name})),U=i.useRef(!0);i.useEffect(()=>(U.current=!0,()=>{U.current=!1}),[]);const N=i.useCallback(v=>{f(v),A.current?.(v)},[]),W=i.useCallback(v=>{const K=T.current.get(v);if(K!==void 0){K.click();return}me(()=>N(v))},[N]),$=i.useCallback(async v=>{const K=typeof v.tab=="string"?v.tab:"",ne=O.current,se=ne.find(re=>re.label===K);return se===void 0||se.disabled===!0?`No tab named "${K}" can be shown. These tabs offer: ${ne.filter(re=>re.disabled!==!0).map(re=>`"${re.label}"`).join(", ")}.`:(W(se.value),await pe(),U.current?`Selected. The tabs are now:
|
|
714
|
+
${E.current([D.current])}`:"Switching tabs removed them from the page.")},[W]),_=i.useMemo(()=>n.filter(v=>v.disabled!==!0).map(v=>v.label),[n]),V=i.useMemo(()=>Ws(_),[_]),M=de({spec:et,label:d??t,inputSchema:V,enabled:c&&_.length>0,execute:$}),I=n.map(v=>({part:"tab",label:v.label,state:{...v.value===k?{selected:!0}:{},...v.count===void 0?{}:{count:String(v.count)},...v.disabled===!0?{disabled:!0}:{}}})),j=q({component:rn.name,label:t,tool:M,region:!0,state:{value:n.find(v=>v.value===k)?.label},parts:I});D.current=j;const z=n.find(v=>v.value===k);if(g==="agent")return u==="never"?a.jsxs(a.Fragment,{children:[a.jsx(te,{node:j}),z?.panel]}):a.jsx(ke,{node:j,isActionable:v=>v.state.disabled!==!0&&v.state.selected!==!0,onActivate:(v,K)=>{const ne=n[K];ne!==void 0&&W(ne.value)},children:z?.panel});const L=v=>`${m}-tab-${v}`,p=`${m}-panel`,x=n.filter(v=>v.disabled!==!0),P=v=>{if(!["ArrowRight","ArrowLeft","Home","End"].includes(v.key)||x.length===0)return;const ne=x.findIndex(he=>he.value===k),se=v.key==="Home"?0:v.key==="End"?x.length-1:(ne+(v.key==="ArrowRight"?1:-1)+x.length)%x.length,re=x[se];re!==void 0&&(v.preventDefault(),T.current.get(re.value)?.focus(),N(re.value))};return a.jsxs("div",{...h,...X(j),children:[a.jsxs("div",{children:[a.jsx("div",{role:"tablist","aria-label":t,onKeyDown:P,children:n.map((v,K)=>{const ne=v.value===k;return a.jsxs("button",{id:L(v.value),type:"button",role:"tab","aria-selected":ne,"aria-controls":ne?p:void 0,tabIndex:ne?0:-1,disabled:v.disabled===!0,ref:se=>{se===null?T.current.delete(v.value):T.current.set(v.value,se)},...B(I[K]??{part:"tab",state:{}}),onClick:()=>N(v.value),children:[a.jsx("span",{children:v.label}),v.count===void 0?null:a.jsx("span",{"aria-hidden":"true",children:v.count})]},v.value)})}),l===void 0?null:a.jsx("div",{children:l})]}),z===void 0?null:a.jsx("div",{id:p,role:"tabpanel","aria-labelledby":L(z.value),tabIndex:0,children:z.panel})]})}const ho=Y({name:"Text",category:"typography",summary:"A run of prose, sized and toned from the semantic scale. In agent view it renders as its own text content, so an agent reads the words rather than inferring them from styling.",whenToUse:'Use it for every paragraph, caption, note, and inline status line, so tone carries meaning instead of an ad-hoc colour. tone="muted" is the small print under a heading, tone="warning" and tone="danger" state that something is wrong, and tone="action" confirms something is live.',whenNotToUse:"Do not use it for a section title; that is Heading. Do not put components inside it: it flattens its children to a single string for the agent view, so a nested Button would lose its tool.",status:"experimental",props:{children:{kind:"node",description:"The prose. Inline markup such as code or strong is fine; components are not.",required:!0},tone:{kind:"enum",description:"What the text means, not just how it looks. Agents read this off the attribute.",values:["default","muted","action","info","warning","danger"],default:"default"},size:{kind:"enum",description:'Type size. "small" is the annotation size used for notes and captions.',values:["small","normal"],default:"normal"},weight:{kind:"enum",description:"bold for a line that needs to stand out among its neighbours, such as a name in a list row. Prefer a Heading for a title.",values:["normal","bold"],default:"normal"},align:{kind:"enum",description:"Horizontal alignment, in the writing direction.",values:["start","center","end"],default:"start"},lines:{kind:"number",description:"Clamp the text to this many lines, 1 to 6, ending in an ellipsis. Only the screen is clamped: assistive technology and the agent view still get the whole text. Pair it with a Tooltip when a sighted person needs the rest."},italic:{kind:"boolean",description:"Set in italic, for a quotation, a title of a work, or a scripture reference.",default:!1},as:{kind:"enum",description:"The element to render. Use span when the text sits inside another line of text.",values:["p","span","div"],default:"p"}},state:{tone:{description:"What the text is saying about the thing it describes.",attribute:"data-sprint-tone",values:["default","muted","action","info","warning","danger"]},size:{description:"The type size in use.",attribute:"data-sprint-size",values:["small","normal"]},weight:{description:"Present as bold on emphasised text.",attribute:"data-sprint-weight",values:["bold"]},align:{description:"The alignment, when it is not start.",attribute:"data-sprint-align",values:["center","end"]},lines:{description:"The line clamp, when one is set. The text itself is never shortened.",attribute:"data-sprint-lines"},italic:{description:"Present on italic text.",attribute:"data-sprint-italic"}},agentView:{example:'- **Text** "Tools stay registered across a view switch." [tone=muted]'},examples:[{title:"A lede",code:"<Text>Every component renders normally for people and as text for agents.</Text>"},{title:"A note under a heading",description:"The small print that would otherwise be an untyped grey span.",code:'<Text tone="muted" size="small">Registered while the button is enabled.</Text>'},{title:"A live status line",description:"Tone is the whole message here, so an agent reading the attribute learns the same thing a person learns from the colour.",code:`<Text tone={ready ? "action" : "warning"} size="small">
|
|
554
715
|
{ready ? "WebMCP is available in this browser." : "WebMCP is unavailable here."}
|
|
555
|
-
</Text>`}]});function
|
|
716
|
+
</Text>`},{title:"A clamped line",description:"lines clamps the screen to two lines with an ellipsis. The agent view and screen readers still get every word.",code:"<Text lines={2}>{member.notes}</Text>"},{title:"Emphasis and alignment",code:'<Text weight="bold" align="center" italic>Come, follow me.</Text>'}]});function _s(e){const{tone:t="default",size:n="normal",weight:o="normal",align:s="start",lines:r,italic:l=!1,as:d="p",children:c,...h}=e,g=Z(),u=q({component:ho.name,label:be(c),state:{tone:t,size:n,weight:o==="normal"?void 0:o,align:s==="start"?void 0:s,lines:r===void 0?void 0:String(r),italic:l}});if(g==="agent")return a.jsx(te,{node:u});const b=d;return a.jsx(b,{...h,...X(u),children:c})}const En={verb:"fill",description:"Replace this text area's content with the value provided, exactly as a person typing it would. The value is the full text it ends up containing, line breaks included; pass an empty string to clear it. Returns the area's state after the change, so a follow-up read is unnecessary.",inputSchema:{type:"object",properties:{value:{type:"string",description:"The full text the area should contain afterwards, with real line breaks where line breaks belong. Replaces the current text."}},required:["value"]},readOnly:!1,untrustedContent:!0,registeredWhen:"The area is mounted, enabled, has a resolvable label, and no other component claims the same tool name.",unregisteredWhen:"The area unmounts or becomes disabled."},ln=Y({name:"Textarea",category:"input",summary:"A multi-line text area carrying its own label, hint, and error. Fully controlled, and it registers one fill tool that replaces the whole content with an explicit value, line breaks included.",whenToUse:"Use it for free-form text that runs longer than a line: a description, a message body, a set of notes. In the agent view the current content is part of the component's state line, so an agent reads what is written without a separate query.",whenNotToUse:"Do not use it for a single-line value, which is a TextInput. Do not use it for code a person should read rather than write; that is a CodeBlock. Long values make long state lines, so keep it off surfaces where the agent view must stay terse.",status:"experimental",props:{label:{kind:"string",description:'What the area holds. Names it for a screen reader and derives the tool name, so prefer a noun phrase such as "Mission notes".',required:!0},value:{kind:"string",description:"The area's current text. The area is fully controlled.",required:!0},onChange:{kind:"handler",description:"Called with the new text on every change. The fill tool drives a real input event, so this runs for agent fills too.",required:!0},rows:{kind:"number",description:"The visible line count before scrolling. With autoGrow it is the minimum height.",default:4},autoGrow:{kind:"boolean",description:"Grow the area with its content instead of scrolling, never shorter than rows.",default:!1},placeholder:{kind:"string",description:"Ghost text shown while the area is empty."},hint:{kind:"string",description:"Guidance shown under the area and carried into the agent view. Replaced by error while one is set."},error:{kind:"string",description:"A validation message. Marks the area invalid for people, screen readers, and agents alike."},name:{kind:"string",description:"The native form name submitted with the surrounding form."},disabled:{kind:"boolean",description:"Disable the area and unregister its fill tool.",default:!1},required:{kind:"boolean",description:"Mark the area required, visually and in the agent view.",default:!1},hideLabel:{kind:"boolean",description:"Hide the label visually while keeping it as the field's accessible name and agent label. Pair it with a placeholder or a nearby heading so sighted people still know what the field is for.",default:!1},inputRef:{kind:"object",description:"A ref to the underlying <textarea>, for focusing or measuring it. The component's own ref points at the wrapper."},inputProps:{kind:"object",description:"Extra native attributes and handlers for the <textarea> itself, such as autoFocus, maxLength, inputMode, onKeyDown, or onBlur. Props spread on the component land on the wrapper; these land on the area. Anything the component manages (value, onChange, disabled, the error wiring) cannot be overridden here."},agentName:{kind:"string",description:"Override the label used to derive the tool name, when two areas on a page would otherwise collide."},agentTool:{kind:"boolean",description:"Set false to render the area without registering a fill tool.",default:!0}},state:{value:{description:"The area's current text.",attribute:"data-sprint-value"},empty:{description:"Present while the area holds no text.",attribute:"data-sprint-empty"},disabled:{description:"Present when the area cannot be edited.",attribute:"data-sprint-disabled"},required:{description:"Present when the area must be filled.",attribute:"data-sprint-required"},invalid:{description:"Present while an error is set.",attribute:"data-sprint-invalid"}},tools:{fill:En},agentView:{example:'- **Textarea** "Mission notes" [empty] → tool `fill-mission-notes`\n - part `hint` "What the relief crew needs to know"'},examples:[{title:"A notes area",description:"Label, hint, and control are one component. In agent view it renders a live textarea an agent can type into.",code:`<Textarea
|
|
556
717
|
label="Mission notes"
|
|
557
718
|
value={notes}
|
|
558
719
|
onChange={setNotes}
|
|
@@ -564,8 +725,17 @@ ${w.current([v.current])}`:"The change removed this switch from the page."},[]),
|
|
|
564
725
|
required
|
|
565
726
|
rows={3}
|
|
566
727
|
error="State the reason before aborting."
|
|
567
|
-
/>`}
|
|
568
|
-
|
|
728
|
+
/>`},{title:"An area that grows",description:"autoGrow drops the scrollbar: the area starts at rows lines and grows with what is typed. The label is hidden because a heading above already names it, and inputProps puts a length cap and a key handler on the textarea itself.",code:`<Textarea
|
|
729
|
+
label="Log entry"
|
|
730
|
+
hideLabel
|
|
731
|
+
autoGrow
|
|
732
|
+
rows={2}
|
|
733
|
+
value={entry}
|
|
734
|
+
onChange={setEntry}
|
|
735
|
+
placeholder="What happened on this pass"
|
|
736
|
+
inputProps={{ maxLength: 500, onKeyDown: submitOnModEnter }}
|
|
737
|
+
/>`}],a11y:{role:"textbox",keyboard:["Standard text editing","Enter inserts a line break"],notes:"The label element is associated via htmlFor. An error sets aria-invalid and is linked with aria-describedby, as is the hint."}});function Fs(e){e.style.setProperty("height","auto");const t=e.offsetHeight-e.clientHeight;e.style.setProperty("height",`${e.scrollHeight+t}px`)}function Hs(e,t){return e!==void 0?[{part:"error",label:e,state:{}}]:t!==void 0?[{part:"hint",label:t,state:{}}]:[]}function Vs(e){const{label:t,value:n,onChange:o,rows:s=4,placeholder:r,hint:l,error:d,name:c,disabled:h=!1,required:g=!1,autoGrow:u=!1,hideLabel:b=!1,inputRef:m,inputProps:S,agentName:f,agentTool:y=!0,...k}=e,T=Z(),O=ue(),A=ce(),E=i.useId(),D=i.useRef(null),U=i.useRef(o);U.current=o;const N=i.useRef(A);N.current=A;const W=i.useRef(q({component:ln.name})),$=i.useRef(!0);i.useEffect(()=>($.current=!0,()=>{$.current=!1}),[]),i.useLayoutEffect(()=>{const j=D.current;!u||T==="agent"||j===null||Fs(j)},[u,n,T]),i.useLayoutEffect(()=>{const j=D.current;u||j===null||j.style.removeProperty("height")},[u]);const _=i.useCallback(async j=>{const z=j.value;if(typeof z!="string")return'Pass "value" as a string holding the full text the area should contain.';const L=D.current;return L!==null?Pn(L,z):me(()=>U.current(z)),await pe(),$.current?`Filled. The area is now:
|
|
738
|
+
${N.current([W.current])}`:"The change removed this area from the page."},[]),V=de({spec:En,label:f??t,enabled:y&&!h,execute:_}),M=q({component:ln.name,label:t,tool:V,state:{...n===""?{}:{value:n},empty:n==="",disabled:h,required:g,invalid:d!==void 0},parts:Hs(d,l)});if(W.current=M,T==="agent")return h||O==="never"?a.jsx(te,{node:M}):a.jsx(fn,{node:M,value:n,multiline:!0,onValueChange:o,ref:j=>{D.current=j,He(m,j)}});const I=d!==void 0?`${E}-error`:l!==void 0?`${E}-hint`:void 0;return a.jsxs("div",{...k,...X(M),children:[a.jsx("label",{htmlFor:E,...b?{"data-sprint-visually-hidden":""}:{},children:t}),a.jsx("textarea",{...S,id:E,...B({part:"input",state:{}}),ref:j=>{D.current=j,He(m,j)},rows:s,value:n,placeholder:r,name:c,disabled:h,required:g,"aria-invalid":d!==void 0||void 0,"aria-describedby":I,onChange:j=>o(j.currentTarget.value)}),d!==void 0?a.jsx("p",{id:I,...B({part:"error",state:{}}),children:d}):l!==void 0?a.jsx("p",{id:I,...B({part:"hint",state:{}}),children:l}):null]})}const Dn={verb:"fill",description:"Replace this field's text with the value provided, exactly as a person typing it would. The value is the full text the field ends up containing; pass an empty string to clear it. Returns the field's state after the change, so a follow-up read is unnecessary.",inputSchema:{type:"object",properties:{value:{type:"string",description:"The full text the field should contain afterwards. Replaces the current text rather than appending to it."}},required:["value"]},readOnly:!1,untrustedContent:!0,registeredWhen:"The field is mounted, enabled, editable rather than read-only, has a resolvable label, and no other component claims the same tool name.",unregisteredWhen:"The field unmounts, becomes disabled, or becomes read-only."},dn=Y({name:"TextInput",category:"input",summary:"A single-line text field carrying its own label, hint, and error. Fully controlled, and it registers one fill tool that replaces the field's text with an explicit value.",whenToUse:"Use it for any free-form single-line value: a name, an email address, a search term. The label is part of the component, so a form never needs a separate label element, and the error prop is how validation reaches both a person and an agent.",whenNotToUse:"Do not use it for multi-line text, which is a Textarea. Do not use it to pick from a known set of values; that is a Select or a SegmentedControl. Do not use it for an on/off state, which is a Checkbox or a Switch. Do not use a read-only TextInput to hand someone a value to paste elsewhere; that is a CopyField.",status:"experimental",props:{label:{kind:"string",description:'What the field holds. Names the field for a screen reader and derives the tool name, so prefer a noun phrase such as "Callsign".',required:!0},value:{kind:"string",description:"The field's current text. The field is fully controlled.",required:!0},onChange:{kind:"handler",description:"Called with the new text on every change. The fill tool drives a real input event, so this runs for agent fills too.",required:!0},type:{kind:"enum",description:'The input type. "password" masks the field everywhere: the value never appears in agent attributes, the agent view, or tool results. "number" keeps value a string, so the page parses it; pass min, max and step through inputProps.',values:["text","email","url","search","password","number","tel"],default:"text"},placeholder:{kind:"string",description:"Ghost text shown while the field is empty."},hint:{kind:"string",description:"Guidance shown under the field and carried into the agent view. Replaced by error while one is set."},error:{kind:"string",description:"A validation message. Marks the field invalid for people, screen readers, and agents alike."},name:{kind:"string",description:"The native form name submitted with the surrounding form."},autoComplete:{kind:"string",description:"The native autocomplete hint, forwarded to the input."},disabled:{kind:"boolean",description:"Disable the field and unregister its fill tool.",default:!1},readOnly:{kind:"boolean",description:"Show the value without letting anyone change it. The field stays focusable and selectable, renders as plain text in the agent view, and registers no fill tool, because nothing can change it.",default:!1},required:{kind:"boolean",description:"Mark the field required, visually and in the agent view.",default:!1},hideLabel:{kind:"boolean",description:"Hide the label visually while keeping it as the field's accessible name and agent label. Pair it with a placeholder or a nearby heading so sighted people still know what the field is for.",default:!1},icon:{kind:"node",description:"A decorative icon drawn inside the start of the field, such as a magnifier on a search box. Hidden from assistive technology."},trailing:{kind:"node",description:'Controls drawn inside the end of the field, such as a clear Button with hideLabel and size="small". It renders only in the human view; give an agent the same action some other way, or rely on the fill tool, which can set the field to empty.'},inputRef:{kind:"object",description:"A ref to the underlying <input>, for focusing or measuring it. The component's own ref points at the wrapper."},inputProps:{kind:"object",description:"Extra native attributes and handlers for the <input> itself, such as autoFocus, maxLength, inputMode, onKeyDown, or onBlur. Props spread on the component land on the wrapper; these land on the field. Anything the component manages (value, onChange, disabled, the error wiring) cannot be overridden here."},agentName:{kind:"string",description:"Override the label used to derive the tool name, when two fields on a page would otherwise collide."},agentTool:{kind:"boolean",description:"Set false to render the field without registering a fill tool.",default:!0}},state:{value:{description:"The field's current text. Never present on a password field, which reflects filled instead.",attribute:"data-sprint-value"},filled:{description:"Present when a password field holds text.",attribute:"data-sprint-filled"},empty:{description:"Present while the field holds no text.",attribute:"data-sprint-empty"},disabled:{description:"Present when the field cannot be edited.",attribute:"data-sprint-disabled"},readonly:{description:"Present when the field shows a value that cannot be changed. No fill tool is registered while it is set.",attribute:"data-sprint-readonly"},required:{description:"Present when the field must be filled.",attribute:"data-sprint-required"},invalid:{description:"Present while an error is set.",attribute:"data-sprint-invalid"}},tools:{fill:Dn},agentView:{example:'- **TextInput** "Callsign" [empty, required] → tool `fill-callsign`\n - part `hint` "Uppercase, three to eight letters"'},examples:[{title:"A labelled field",description:"Label, hint, and control are one component. In agent view the hint becomes a part line and the field renders a live input an agent can type into.",code:`<TextInput
|
|
569
739
|
label="Callsign"
|
|
570
740
|
value={callsign}
|
|
571
741
|
onChange={setCallsign}
|
|
@@ -589,18 +759,55 @@ ${x.current([A.current])}`:"The change removed this area from the page."},[]),T=
|
|
|
589
759
|
onChange={() => {}}
|
|
590
760
|
readOnly
|
|
591
761
|
hint="Assigned at registration"
|
|
592
|
-
/>`}
|
|
593
|
-
|
|
594
|
-
|
|
595
|
-
|
|
762
|
+
/>`},{title:"A number with field attributes",description:'type="number" keeps value a string. Native attributes for the input itself, such as min, max and autoFocus, go through inputProps, and inputRef reaches the input for focusing it later.',code:`<TextInput
|
|
763
|
+
label="Link expiry in days"
|
|
764
|
+
type="number"
|
|
765
|
+
value={days}
|
|
766
|
+
onChange={setDays}
|
|
767
|
+
inputRef={daysField}
|
|
768
|
+
inputProps={{ min: 1, max: 90, step: 1 }}
|
|
769
|
+
/>`},{title:"A search field with a clear control",description:"The icon sits inside the start of the field and a small icon-only Button clears it from the end. An agent clears it by filling an empty string.",code:`<TextInput
|
|
770
|
+
label="Filter the board"
|
|
771
|
+
hideLabel
|
|
772
|
+
placeholder="Filter by name or calling"
|
|
773
|
+
icon={<SearchIcon />}
|
|
774
|
+
value={query}
|
|
775
|
+
onChange={setQuery}
|
|
776
|
+
trailing={
|
|
777
|
+
query === "" ? null : (
|
|
778
|
+
<Button size="small" icon={<CloseIcon />} hideLabel onClick={() => setQuery("")}>
|
|
779
|
+
Clear filter
|
|
780
|
+
</Button>
|
|
781
|
+
)
|
|
782
|
+
}
|
|
783
|
+
/>`}],a11y:{role:"textbox",keyboard:["Standard text editing","Tab moves through the field"],notes:"The label element is associated via htmlFor. An error sets aria-invalid and is linked with aria-describedby, as is the hint. Focus is an offset keyline, never a rounded ring."}});function zs(e,t){return e!==void 0?[{part:"error",label:e,state:{}}]:t!==void 0?[{part:"hint",label:t,state:{}}]:[]}function Gs(e){const{label:t,value:n,onChange:o,type:s="text",placeholder:r,hint:l,error:d,name:c,autoComplete:h,disabled:g=!1,readOnly:u=!1,required:b=!1,hideLabel:m=!1,icon:S,trailing:f,inputRef:y,inputProps:k,agentName:T,agentTool:O=!0,...A}=e,E=Z(),D=ue(),U=ce(),N=i.useId(),W=i.useRef(null),$=i.useRef(o);$.current=o;const _=i.useRef(U);_.current=U;const V=i.useRef(q({component:dn.name})),M=i.useRef(!0);i.useEffect(()=>(M.current=!0,()=>{M.current=!1}),[]);const I=s==="password",j=i.useCallback(async P=>{const v=P.value;if(typeof v!="string")return'Pass "value" as a string holding the full text the field should contain.';const K=W.current;return K!==null?Pn(K,v):me(()=>$.current(v)),await pe(),M.current?`Filled. The field is now:
|
|
784
|
+
${_.current([V.current])}`:"The change removed this field from the page."},[]),z=de({spec:Dn,label:T??t,enabled:O&&!g&&!u,execute:j}),L=q({component:dn.name,label:t,tool:z,state:{...I?{filled:n!==""}:n===""?{}:{value:n},empty:n==="",disabled:g,readonly:u,required:b,invalid:d!==void 0},parts:zs(d,l)});if(V.current=L,E==="agent")return g||u||D==="never"?a.jsx(te,{node:L}):a.jsx(fn,{node:L,value:n,masked:I,onValueChange:o,ref:P=>{W.current=P,He(y,P)}});const p=d!==void 0?`${N}-error`:l!==void 0?`${N}-hint`:void 0,x=a.jsx("input",{...k,id:N,...B({part:"input",state:{}}),ref:P=>{W.current=P,He(y,P)},type:s,value:n,placeholder:r,name:c,autoComplete:h,disabled:g,readOnly:u,required:b,"aria-invalid":d!==void 0||void 0,"aria-describedby":p,onChange:P=>o(P.currentTarget.value)});return a.jsxs("div",{...A,...X(L),children:[a.jsx("label",{htmlFor:N,...m?{"data-sprint-visually-hidden":""}:{},children:t}),S===void 0&&f===void 0?x:a.jsxs("div",{children:[S===void 0?null:a.jsx("span",{"data-sprint-icon":"","aria-hidden":"true",children:S}),x,f===void 0?null:a.jsx("span",{children:f})]}),d!==void 0?a.jsx("p",{id:p,...B({part:"error",state:{}}),children:d}):l!==void 0?a.jsx("p",{id:p,...B({part:"hint",state:{}}),children:l}):null]})}const uo=Y({name:"Toast",category:"feedback",summary:"A brief message that floats at the bottom of the screen after something happened, with an optional single action such as Undo, and dismisses itself.",whenToUse:"Use to confirm an action that already took effect and can still be reversed or followed up: a person moved, a note saved, a share link copied. Render one Toast with open, message and onDismiss; the page owns which toast is showing. The action is data, { label, onSelect, shortcut? }, rendered as a Button that registers its own press tool, and the shortcut is shown as key caps.",whenNotToUse:"Do not use for an error the person must act on, or anything that must stay visible; that is an Alert in the page. Do not use for a decision; that is a Dialog. Do not show several at once: replace the message instead. Inside an open modal Dialog, render the Toast inside the Dialog, because the page behind it is inert.",status:"experimental",props:{open:{kind:"boolean",description:"Whether the toast is showing. A closed toast renders nothing.",required:!0},message:{kind:"string",description:'What happened, in a sentence, such as "Moved Sister Amaral to Primary."',required:!0},onDismiss:{kind:"handler",description:"Called when the toast should go: after duration, or when the dismiss control is pressed. Set open to false in response.",required:!0},label:{kind:"string",description:"A short title above the message, and the toast's accessible name."},tone:{kind:"enum",description:"neutral and info announce politely; warning too. danger announces assertively, but prefer an Alert for errors.",values:["neutral","info","warning","danger"],default:"neutral"},action:{kind:"object",description:"One follow-up action: { label, onSelect, shortcut? }. It is a Button with its own press tool, named from the label. shortcut is shown as key caps and published as aria-keyshortcuts; the page binds the key itself."},duration:{kind:"number",description:"Milliseconds before onDismiss is called. The timer pauses while the pointer or focus is on the toast. Pass null to keep it until dismissed.",default:6e3},dismissLabel:{kind:"string",description:"Accessible name of the dismiss control.",default:"Dismiss"}},state:{tone:{description:"The toast's tone.",attribute:"data-sprint-tone",values:["neutral","info","warning","danger"]}},agentView:{example:'- **Toast** [tone=neutral]\n - part `message` "Moved Sister Amaral to Primary."\n - part `dismiss` "Dismiss"\n - **Button** "Undo" [size=small, tone=action]'},examples:[{title:"An undo toast",description:"The action is a real Button, so an agent can press Undo through its tool while the toast is up.",code:`<Toast
|
|
785
|
+
open={moved !== null}
|
|
786
|
+
message={movedMessage}
|
|
787
|
+
action={{ label: "Undo", onSelect: undo, shortcut: "Ctrl+Z" }}
|
|
788
|
+
onDismiss={() => setMoved(null)}
|
|
789
|
+
/>`},{title:"A toast that stays",description:"duration={null} keeps it until dismissed.",code:`<Toast
|
|
790
|
+
open={offline}
|
|
791
|
+
label="Offline"
|
|
792
|
+
tone="warning"
|
|
793
|
+
duration={null}
|
|
794
|
+
message="Changes are saved on this device until the connection returns."
|
|
795
|
+
onDismiss={() => setOffline(false)}
|
|
796
|
+
/>`}],a11y:{role:"status",notes:"A role=status region, or role=alert for danger, so the message is announced when the toast appears. Render it when the event happens rather than toggling visibility. It opens as a popover in the top layer, at the bottom edge on a phone and the bottom corner on a wide screen. The timer pauses while the pointer or keyboard focus is on it, so nobody loses the action mid-reach."}}),Ks=6e3;function Qs(e){const{open:t,message:n,onDismiss:o,label:s,tone:r="neutral",action:l,duration:d=Ks,dismissLabel:c="Dismiss",...h}=e,g=Z(),u=ue(),b=i.useRef(null),m=i.useRef(void 0),S=i.useRef(o);S.current=o;const f=i.useCallback(()=>{m.current!==void 0&&window.clearTimeout(m.current),m.current=void 0},[]),y=i.useCallback(()=>{f(),!(!t||d===null)&&(m.current=window.setTimeout(()=>S.current(),d))},[t,d,f]);if(i.useEffect(()=>(y(),f),[y,f]),i.useEffect(()=>{const A=b.current;A===null||g==="agent"||(t?wn(A):vn(A))},[t,g]),!t)return null;const k=[{part:"message",label:n,state:{}},{part:"dismiss",label:c,state:{}}],T=q({component:uo.name,label:s,state:{tone:r},parts:k}),O=l===void 0?null:a.jsx(dt,{size:"small",tone:r==="danger"?"danger":"action",onClick:()=>{f(),l.onSelect()},"aria-keyshortcuts":l.shortcut,children:l.label});return g==="agent"?u==="never"?a.jsxs(a.Fragment,{children:[a.jsx(te,{node:T}),O]}):a.jsx(ke,{node:T,isActionable:A=>A.part==="dismiss",onActivate:()=>o(),children:O}):a.jsxs("div",{...h,...X(T),role:r==="danger"?"alert":"status",popover:"manual",ref:b,onPointerEnter:f,onPointerLeave:y,onFocus:f,onBlur:y,children:[a.jsxs("div",{children:[s===void 0?null:a.jsx("strong",{children:s}),a.jsx("p",{...B({part:"message",state:{}}),children:n})]}),l===void 0?null:a.jsxs("div",{children:[O,l.shortcut===void 0?null:a.jsx(za,{children:l.shortcut})]}),a.jsx("button",{type:"button","aria-label":c,...B({part:"dismiss",state:{}}),onClick:()=>o(),children:"×"})]})}const po=Y({name:"VisuallyHidden",category:"typography",summary:"Text that is off screen but still read by screen readers and agents. For context a sighted person gets from the layout.",whenToUse:`Use to say in words what the layout says visually: "(opens in a new tab)" after a link, a count's unit, a heading for a region whose purpose is obvious on screen. With focusable, it wraps a skip link that appears only while it has focus.`,whenNotToUse:"Do not use to hide a field's label; TextInput, Textarea, SearchField and Progress take hideLabel, and an icon-only Button takes hideLabel too. Do not hide content that a sighted person also needs.",status:"experimental",props:{children:{kind:"node",description:"The hidden text, or a skip link when focusable is set.",required:!0},focusable:{kind:"boolean",description:"Show the content while something inside it has keyboard focus, for a skip link.",default:!1}},state:{focusable:{description:"Present when the content appears while focused.",attribute:"data-sprint-focusable"}},agentView:{example:'- **VisuallyHidden** "opens in a new tab"'},examples:[{title:"Extra words for a screen reader",description:"The arrow says it to a sighted person; the hidden text says it to everyone else.",code:`<Link href="https://churchofjesuschrist.org" external>
|
|
797
|
+
Gospel Library ↗<VisuallyHidden> (opens in a new tab)</VisuallyHidden>
|
|
798
|
+
</Link>`},{title:"A skip link",description:"Off screen until a keyboard user tabs to it.",code:`<VisuallyHidden focusable>
|
|
799
|
+
<Link href="#main">Skip to the board</Link>
|
|
800
|
+
</VisuallyHidden>`}],a11y:{notes:"Hidden with a one-pixel clip rather than display or visibility, so screen readers still read it. The agent view renders its text as an ordinary line."}});function Xs(e){const{focusable:t=!1,children:n,...o}=e,s=Z(),r=q({component:po.name,label:be(n),state:{focusable:t}});return s==="agent"?a.jsx(te,{node:r}):a.jsx("span",{...o,...X(r),children:n})}const Mn=40;function Ys(e){const t=e.label===void 0?"":_e(e.label),n=t===""?_e(e.component):`${_e(e.component)}-${t}`;return n===""?"region":n}function Zs(e){const t=new Map;return e.map(n=>{const o=Ys(n),s=t.get(o)??0;return t.set(o,s+1),{key:s===0?o:`${o}-${s+1}`,node:n}})}function go(){if(typeof document>"u")return[];const e=document.body,t=new Set(wa(e)),n=Array.from(e.querySelectorAll(`[${Ct}]`)).filter(o=>!t.has(o));return Zs([...va(e),...n.map(o=>Rt(o)).filter(o=>o!==null)])}const Js={verb:"list",description:"List the Sprint component regions on this page, with a one-line state summary for each. Call this first to discover region keys, then call read-region to read one in full. Regions nest: a page-level region contains the labelled panels listed after it, so read the smallest region that covers what you need.",inputSchema:{type:"object",properties:{}},readOnly:!0,untrustedContent:!0,registeredWhen:"A root SprintProvider is mounted and WebMCP is available."},er={verb:"read",description:"Read one region of the page as Markdown, including every component in it, its current state, and the tools that drive it. Long regions are paginated; the response ends with the page number and total.",inputSchema:{type:"object",properties:{region:{type:"string",description:"A region key from list-page-regions."},page:{type:"integer",description:"1-based page number. Defaults to 1.",minimum:1}},required:["region"]},readOnly:!0,untrustedContent:!0,registeredWhen:"A root SprintProvider is mounted and WebMCP is available."};function tr(e){const t=go();if(t.length===0)return"This page has no Sprint components.";const n=t.map(({key:o,node:s})=>{const r=oa(s.children),l=e([{...s,children:[],parts:[]}]).split(`
|
|
801
|
+
`)[0]?.replace(/^-\s*/,""),d=r===0?"":` (${r} nested)`;return`- \`${o}\` — ${l??s.component}${d}`});return[`${t.length} region(s):`,...n].join(`
|
|
802
|
+
`)}function nr(e,t,n){const o=go(),s=o.map(c=>c.key),r=o.find(c=>c.key===t);if(r===void 0)return`No region named "${String(t)}". Available regions: ${s.join(", ")||"none"}.`;const l=pn(e([r.node]),Fe-Mn),d=typeof n=="number"?n:1;return d<1||d>l.length?`Region "${r.key}" has ${l.length} page(s); page ${d} does not exist.`:`${l[d-1]??""}
|
|
596
803
|
|
|
597
|
-
(page ${
|
|
804
|
+
(page ${d} of ${l.length})`}const ar={verb:"set",description:'Switch how this page renders. In "agent" view every Sprint component renders as plain Markdown text with no HTML elements, so the page can be read directly. In "human" view it renders normally. Tools keep working in both.',inputSchema:{type:"object",properties:{view:{type:"string",description:'Either "agent" or "human".',enum:["agent","human"]}},required:["view"]},readOnly:!1,untrustedContent:!0,registeredWhen:"A root SprintProvider is mounted and WebMCP is available."};function mo(){return typeof document>"u"?"":(document.body.textContent??"").replace(/\n{3,}/g,`
|
|
598
805
|
|
|
599
|
-
`).trim()}function
|
|
806
|
+
`).trim()}function or(e){const{enabled:t,format:n,view:o,setView:s}=e;de({spec:Js,label:"page regions",enabled:t,execute:()=>o==="agent"?'This page is in agent view and renders as one text document. Call read-region with region "page", or read the page text directly.':tr(n)}),de({spec:er,label:"region",enabled:t,execute:r=>o==="agent"?ir(r.region,r.page):nr(n,r.region,r.page)}),de({spec:ar,label:"page view",enabled:t,execute:async r=>{const l=r.view==="agent"?"agent":"human";return me(()=>s(l)),await pe(),l==="agent"?`Page is now in agent view:
|
|
600
807
|
|
|
601
|
-
${
|
|
808
|
+
${kt(mo(),Fe-Mn)}`:"Page is now in human view."}})}function ir(e,t){if(e!=="page")return`No region named "${String(e)}". In agent view the whole page is one region, named "page".`;const n=pn(mo(),Fe-Mn),o=typeof t=="number"?t:1;return o<1||o>n.length?`Region "page" has ${n.length} page(s); page ${o} does not exist.`:`${n[o-1]??""}
|
|
602
809
|
|
|
603
|
-
(page ${o} of ${n.length})`}const
|
|
810
|
+
(page ${o} of ${n.length})`}const fo="--sprint-gloss-x",bo="--sprint-gloss-fade",wo="--sprint-cast-shift",sr=22,rr=78,lr=28,dr=.25,Kn=(e,t,n)=>Math.min(n,Math.max(t,e));function cr(){return typeof matchMedia=="function"&&matchMedia("(prefers-reduced-motion: reduce)").matches}const hr=new Set(["Button","Card","Tag","SegmentedControl","Switch","Shell"]),ur=new Set(["option","thumb"]);function pr(e,t){const n=e.closest("[data-sprint-part]");if(n===null||!t.contains(n))return null;const o=n.dataset.sprintPart;return o!==void 0&&ur.has(o)?n:null}function vo(e){if(!(e instanceof Element))return null;const t=e.closest("[data-sprint]");if(t===null)return null;const n=t.dataset.sprint;return n===void 0||!hr.has(n)?null:pr(e,t)??t}function gr(e){if(e.pointerType==="touch"||cr())return;const t=vo(e.target);if(t===null)return;const n=t.getBoundingClientRect();if(n.width===0||n.height===0)return;const o=Kn((e.clientX-n.left)/n.width*100,sr,rr),s=(o-50)/lr;t.style.setProperty(fo,`${o.toFixed(1)}%`),t.style.setProperty(bo,Kn(1-Math.abs(s),dr,1).toFixed(3)),t.style.setProperty(wo,`${(s*-10).toFixed(1)}px`)}function mr(e){const t=vo(e.target);t!==null&&(t.style.removeProperty(fo),t.style.removeProperty(bo),t.style.removeProperty(wo),t.style.length===0&&t.removeAttribute("style"))}const fr=1200;function br(e){const{children:t,label:n,format:o,pageTools:s=!0,view:r,defaultView:l,onViewChange:d,agentControls:c,theme:h}=e,g=ut(),u=ha(),b=!u.owned,[m,S]=i.useState(l??"human"),f=r!==void 0,y=f||b||l!==void 0,k=f?r:y?m:u.view,T=i.useCallback(V=>{if(!y){u.setView(V);return}f||S(V),d?.(V)},[y,f,u,d]),O=c??u.controls,A=o??u.format??mn,E=i.useMemo(()=>({view:k,setView:T,controls:O,format:A,owned:y}),[k,T,O,A,y]),D=i.useMemo(()=>({path:n===void 0?g:[...g,n]}),[g,n]);or({enabled:b&&s,format:A,view:k,setView:T});const U=i.useRef(null),[N,W]=i.useState(!1);i.useEffect(()=>{if(!N)return;const V=setTimeout(()=>W(!1),fr);return()=>clearTimeout(V)},[N]);const $=()=>{const V=navigator.clipboard;if(V===void 0)return;const M=(U.current?.textContent??"").replace(/\n{3,}/g,`
|
|
604
811
|
|
|
605
|
-
`).trim();
|
|
812
|
+
`).trim();V.writeText(M).then(()=>W(!0),()=>W(!1))},_=y&&k==="agent"&&O!=="never";return a.jsx(Mo,{value:E,children:a.jsxs(lt,{value:D,children:[_?a.jsx("button",{type:"button","aria-label":N?"Copied":"Copy agent view",[Xn]:"",...N?{"data-sprint-copied":""}:{},onClick:$}):null,a.jsx("div",{ref:U,onPointerMove:k==="agent"?void 0:gr,onPointerOut:k==="agent"?void 0:mr,[Qn]:k,...h===void 0?{}:{[Yn]:h},children:t})]})})}function wr(e){const{children:t,label:n}=e,o=ut(),s=i.useMemo(()=>({path:[...o,n]}),[o,n]);return a.jsx(lt,{value:s,children:t})}const vr="0.8.0",yr={version:vr},kr=yr.version;exports.ACT_BREADCRUMB_TOOL=Ge;exports.AGENT_ATTRIBUTE=hn;exports.AgentControl=ze;exports.AgentControlGroup=ke;exports.AgentLine=te;exports.AgentRegion=wr;exports.AgentScopeProvider=lt;exports.Alert=zo;exports.Avatar=Go;exports.Breadcrumb=Zo;exports.Button=dt;exports.CHOOSE_COMBOBOX_TOOL=Cn;exports.CHOOSE_MENU_TOOL=Qe;exports.CHOOSE_TOOL=Ke;exports.CLOSE_DIALOG_TOOL=Sn;exports.COMPONENT_ATTRIBUTE=Me;exports.Card=hi;exports.ChangeList=vi;exports.Checkbox=ki;exports.ChoiceGrid=Ai;exports.CodeBlock=Pi;exports.Combobox=Mi;exports.CopyField=$i;exports.DISMISS_ALERT_TOOL=bn;exports.DescriptionList=qi;exports.Dialog=Wi;exports.Disclosure=Bi;exports.Divider=_i;exports.EXPAND_DISCLOSURE_TOOL=An;exports.EmptyState=Hi;exports.EntityRow=zi;exports.FILL_TEXTAREA_TOOL=En;exports.FILL_TOOL=Dn;exports.Heading=Gi;exports.Image=Ki;exports.Kbd=za;exports.Link=qa;exports.List=Xi;exports.Menu=es;exports.MetaLine=ts;exports.Nav=ns;exports.NavGroup=as;exports.OPEN_CARD_TOOL=xn;exports.OPEN_ENTITY_ROW_TOOL=Rn;exports.OPEN_LINK_TOOL=jn;exports.OWNER_ATTRIBUTE=cn;exports.PARAM_DESCRIPTION_LIMIT=$t;exports.PART_ATTRIBUTE=Ve;exports.PRESS_TOOL=kn;exports.PageHeader=os;exports.Pagination=ls;exports.Panel=ds;exports.Pending=cs;exports.Progress=us;exports.Prose=ps;exports.REGION_ATTRIBUTE=Ct;exports.RESERVED_STATE_KEYS=Zn;exports.RadioGroup=fs;exports.SEARCH_TOOL=Ln;exports.SELECT_OPTION_TOOL=Je;exports.SELECT_RADIO_TOOL=Ye;exports.SELECT_TAB_TOOL=et;exports.SELECT_TOOL=Ze;exports.SET_CHECKBOX_TOOL=Tn;exports.SET_SWITCH_TOOL=On;exports.STACK_MINS=io;exports.STATE_ATTRIBUTE_PREFIX=st;exports.SearchField=vs;exports.SecretField=xs;exports.SegmentedControl=Cs;exports.Select=js;exports.Shell=Rs;exports.Spinner=Da;exports.SprintProvider=br;exports.Stack=Os;exports.Steps=Ms;exports.Switch=Ns;exports.TABLE_WIDTHS=lo;exports.THEME_ATTRIBUTE=Yn;exports.TOOLTIP_ATTRIBUTE=Nt;exports.TOOL_ATTRIBUTE=tt;exports.TOOL_DESCRIPTION_LIMIT=It;exports.TOOL_NAMING_CONVENTION=ta;exports.TOOL_OUTPUT_LIMIT=Fe;exports.TURN_PAGE_TOOL=Xe;exports.Table=qs;exports.Tabs=Bs;exports.Tag=_a;exports.Text=_s;exports.TextInput=Gs;exports.Textarea=Vs;exports.Toast=Qs;exports.Tooltip=yn;exports.VIEW_ATTRIBUTE=Qn;exports.VIEW_COPY_ATTRIBUTE=Xn;exports.VisuallyHidden=Xs;exports.accessibleText=ht;exports.afterCommit=pe;exports.agentAttributes=un;exports.agentAttributesFor=X;exports.agentPartAttributesFor=B;exports.agentPartControlAttributes=ga;exports.agentSelector=jo;exports.alertMeta=Wt;exports.avatarMeta=ka;exports.breadcrumbMeta=Bt;exports.buildAgentManifest=Oo;exports.buildAgentNode=q;exports.buttonMeta=Ft;exports.cardMeta=Ht;exports.changeListMeta=Aa;exports.checkboxMeta=Vt;exports.choiceGridMeta=zt;exports.clamp=kt;exports.codeBlockMeta=Oa;exports.comboboxMeta=Gt;exports.copyFieldMeta=Ma;exports.defaultAgentFormat=mn;exports.defineAgentMeta=Y;exports.descriptionListMeta=Na;exports.dialogMeta=Ia;exports.disclosureMeta=Qt;exports.dividerMeta=$a;exports.emptyStateMeta=Wa;exports.entityRowMeta=Xt;exports.getAgentMeta=na;exports.getModelContext=gn;exports.headingMeta=Fa;exports.hideFloating=vn;exports.imageMeta=Ha;exports.initialsOf=xa;exports.isModelContextAvailable=Ro;exports.kbdMeta=Va;exports.linkMeta=Ua;exports.listAgentMeta=aa;exports.listMeta=Ga;exports.matchesQuery=Kt;exports.menuMeta=Zt;exports.metaLineMeta=Ka;exports.navGroupMeta=Xa;exports.navMeta=Qa;exports.nodeLine=la;exports.pageHeaderMeta=Ya;exports.paginate=pn;exports.paginationMeta=Jt;exports.panelMeta=Za;exports.pendingMeta=Ja;exports.placeFloating=_t;exports.progressMeta=eo;exports.proseMeta=to;exports.radioGroupMeta=en;exports.reactText=be;exports.registerTool=ea;exports.searchFieldMeta=tn;exports.secretFieldMeta=no;exports.segmentedControlMeta=nn;exports.selectMeta=an;exports.serializeElement=Rt;exports.serializeWithin=va;exports.shellMeta=ao;exports.showFloating=wn;exports.slug=_e;exports.spinnerMeta=Ea;exports.stackMeta=oo;exports.stepsMeta=so;exports.switchMeta=on;exports.tableMeta=ro;exports.tabsMeta=rn;exports.tagMeta=Ba;exports.textInputMeta=dn;exports.textMeta=ho;exports.textareaMeta=ln;exports.toMarkdown=ca;exports.toastMeta=uo;exports.tokenize=Pa;exports.toolName=qt;exports.tooltipMeta=Sa;exports.useAgentControls=ue;exports.useAgentFormat=ce;exports.useAgentScope=ut;exports.useAgentTool=de;exports.useFloating=pt;exports.useSprintView=Z;exports.useSprintViewControl=ha;exports.validateInputs=Jn;exports.version=kr;exports.visuallyHiddenMeta=po;
|
|
606
813
|
//# sourceMappingURL=index.cjs.map
|