@westonkd/sprint 0.5.0 → 0.7.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/README.md +16 -5
- package/agent-manifest.json +1742 -314
- package/dist/index.cjs +381 -69
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.ts +1647 -249
- package/dist/index.js +5455 -2342
- package/dist/index.js.map +1 -1
- package/dist/sprint.css +1 -1
- package/package.json +1 -1
package/dist/index.cjs
CHANGED
|
@@ -1,32 +1,98 @@
|
|
|
1
|
-
"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const
|
|
2
|
-
… truncated`;function
|
|
3
|
-
`);return`${i>n/2?
|
|
4
|
-
`),
|
|
5
|
-
${
|
|
6
|
-
`))
|
|
7
|
-
`)}const
|
|
8
|
-
`)}function
|
|
1
|
+
"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const a=require("react/jsx-runtime"),r=require("react"),Ga=require("react-dom"),fe="data-sprint",Ce="data-sprint-part",Ie="data-sprint-",Ne="data-sprint-tool",$t="data-sprint-owner",Mt="data-sprint-agent",gn="data-sprint-view",mn="data-sprint-view-copy",fn="data-sprint-theme",Je="data-sprint-region",bn=["part","tool","owner","agent","view","view-copy","theme","region","ornament"];function It(e,t={}){const n={[fe]:e};t.part&&(n[Ce]=t.part);for(const[o,i]of Object.entries(t.state??{}))i==null||i===!1||(n[`${Ie}${o}`]=i===!0?"":String(i));return n}function Ka(e,t){const n=`[${fe}="${e}"]`;return t?`${n} [${Ce}="${t}"]`:n}const lt=`
|
|
2
|
+
… truncated`;function Xe(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),i=o.lastIndexOf(`
|
|
3
|
+
`);return`${i>n/2?o.slice(0,i):o.trimEnd()}${lt}`}function Ut(e,t){if(t<=0)return[e];const n=e.split(`
|
|
4
|
+
`),o=[];let i="";for(const s of n){const d=i===""?s:`${i}
|
|
5
|
+
${s}`;if(d.length<=t){i=d;continue}if(i!==""&&o.push(i),i=s.length<=t?s:"",s.length>t)for(let l=0;l<s.length;l+=t)o.push(s.slice(l,l+t))}return i!==""&&o.push(i),o.length===0?[""]:o}const Te=1500,gt=500,mt=150;function qt(){return typeof document>"u"?null:document.modelContext??null}function za(){return qt()!==null}function Xa(e){if(e.description.length>gt)throw new Error(`Tool "${e.name}" description is ${e.description.length} characters; the platform limit is ${gt}.`);for(const[t,n]of Object.entries(e.inputSchema.properties)){const o=n.description??"";if(o.length>mt)throw new Error(`Tool "${e.name}" parameter "${t}" description is ${o.length} characters; the platform limit is ${mt}.`)}}function wn(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 i=e.properties[n];if(i===void 0){const c=Object.keys(e.properties).join(", ");return`Unknown parameter "${n}". Expected parameters: ${c||"none"}.`}const s=typeof o,d=i.type==="number"||i.type==="integer";if(!(i.type==="string"&&s==="string"||d&&s==="number"||i.type==="boolean"&&s==="boolean"))return`Parameter "${n}" must be a ${i.type}, received ${s}.`;if(i.enum!==void 0&&!i.enum.includes(String(o)))return`Parameter "${n}" must be one of: ${i.enum.join(", ")}.`;if(typeof o=="number"){if(i.type==="integer"&&!Number.isInteger(o))return`Parameter "${n}" must be a whole number, received ${o}.`;if(i.minimum!==void 0&&o<i.minimum)return`Parameter "${n}" must be at least ${i.minimum}, received ${o}.`;if(i.maximum!==void 0&&o>i.maximum)return`Parameter "${n}" must be at most ${i.maximum}, received ${o}.`}}return null}function Ya(e){return{...e,execute:async(n,o)=>{const i=wn(e.inputSchema,n??{});if(i!==null)return i;try{const s=await e.execute(n??{},o);return s===null?null:Xe(s,Te)}catch(s){const d=s instanceof Error?s.message:String(s);return Xe(`Tool "${e.name}" failed: ${d}`,Te)}}}}function vn(e,t){Xa(e);const n=qt();if(n===null||t.aborted)return!1;const o=n.registerTool(Ya(e),{signal:t});return o instanceof Promise&&o.catch(i=>{console.warn(`Sprint could not register tool "${e.name}"`,i)}),!0}const yn="<scope>-<verb>-<label-slug>",Ye=new Map;function K(e){const t=Ye.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.`),Ye.set(e.name,e),e}function kn(e){return Ye.get(e)}function xn(){return[...Ye.values()].sort((e,t)=>e.name.localeCompare(t.name))}function Qa(e){return{library:"sprint",version:e,conventions:{componentAttribute:fe,partAttribute:Ce,stateAttributePrefix:Ie,toolAttribute:Ne,ownerAttribute:$t,regionAttribute:Je,agentViewFormat:"markdown",toolNaming:yn,toolOutputLimit:Te},components:xn()}}function Ja(e){return e.label===void 0&&e.parts.length===0&&e.children.length===0}function Tn(e){let t=0;for(const n of e)t+=1+Tn(n.children);return t}function Cn(e){const t=Object.keys(e).sort();return t.length===0?"":` [${t.map(o=>{const i=e[o];return i===!0?o:`${o}=${i}`}).join(", ")}]`}function Sn(e){return e===void 0?"":` "${e}"`}function An(e){return e===void 0?"":` → tool \`${e}\``}function Za(e,t){return`${t}- part \`${e.part}\`${Sn(e.label)}${Cn(e.state)}${An(e.tool)}`}function jn(e){const t=Ja(e)?" (empty)":"",n=e.owner===void 0?"":` (owned by \`${e.owner}\`)`;return`- **${e.component}**${Sn(e.label)}${Cn(e.state)}${An(e.tool)}${n}${t}`}function Rn(e,t,n){const o=[`${t}${jn(e)}`],i=`${t} `;if(n.includeSummary&&e.summary!==void 0)for(const s of e.summary.split(`
|
|
6
|
+
`))o.push(`${i}${s}`);for(const s of e.parts)o.push(Za(s,i));for(const s of e.children)o.push(...Rn(s,i,n));return e.truncated&&o.push(`${i}- … nested components omitted, depth limit reached`),o}function Ln(e,t={}){const n=Array.isArray(e)?e:[e],o={includeSummary:t.includeSummary??!0};return n.length===0?"No Sprint components found.":n.flatMap(i=>Rn(i,"",o)).join(`
|
|
7
|
+
`)}const Wt=e=>Ln(e),We=r.createContext({view:"human",setView:()=>{},controls:"always",format:Wt,owned:!1}),eo=We.Provider;function z(){return r.useContext(We).view}function Pn(){return r.useContext(We)}function ae(){return r.useContext(We).controls}function ne(){return r.useContext(We).format}const En=r.createContext(0),Ze=En.Provider;function et(){return r.useContext(En)}function $(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 V(e){return It(e.component,{state:{...e.state,tool:e.tool,owner:e.owner,region:e.region}})}function On(e){const t={[Mt]:e.component};return e.tool!==void 0&&(t[Ne]=e.tool),t}function Nn(e,t){const n={[Mt]:e,[Ce]:t.part};return t.tool!==void 0&&(n[Ne]=t.tool),n}function D(e){const{[fe]:t,...n}=It("",{part:e.part,state:{...e.state,tool:e.tool}});return n}function tt(e,t){return t([e]).split(`
|
|
8
|
+
`)}function Y(e){const{node:t,children:n,silent:o=!1}=e,i=et(),s=ne(),d=" ".repeat(i),l=tt(t,s).map(c=>`${d}${c}`);return a.jsxs(Ze,{value:o?i:i+1,children:[o?null:`${l.join(`
|
|
9
9
|
`)}
|
|
10
|
-
`,n]})}function
|
|
10
|
+
`,n]})}function ce(e){const{node:t,onActivate:n,isActionable:o,children:i}=e,s=et(),d=ne(),l=" ".repeat(s),c=tt(t,d),h=c.length-t.parts.length,m=c.slice(0,h).map(p=>`${l}${p}`);return a.jsxs(Ze,{value:s+1,children:[`${m.join(`
|
|
11
11
|
`)}
|
|
12
|
-
`,t.parts.map((
|
|
13
|
-
`},
|
|
14
|
-
`]},
|
|
12
|
+
`,t.parts.map((p,b)=>{const g=c[h+b]??"",C=g.trimStart(),f=`${l}${g.slice(0,g.length-C.length)}`,w=`${p.part}-${p.label??b}`;return o!==void 0&&!o(p,b)?a.jsx(r.Fragment,{children:`${f}${C}
|
|
13
|
+
`},w):a.jsxs(r.Fragment,{children:[f,a.jsx("button",{type:"button",...Nn(t.component,p),onClick:()=>n(p,b),children:C}),`
|
|
14
|
+
`]},w)}),i]})}function _t(e){const{node:t,value:n,onValueChange:o,multiline:i=!1,masked:s=!1,ref:d}=e,l=et(),c=ne(),h=" ".repeat(l),m=tt(t,c).map(g=>`${h}${g}`),p=On(t),b=i?a.jsx("textarea",{...p,"aria-label":t.label,value:n,onChange:g=>o(g.currentTarget.value),ref:d}):a.jsx("input",{...p,"aria-label":t.label,type:s?"password":"text",value:n,onChange:g=>o(g.currentTarget.value),ref:d});return a.jsxs(Ze,{value:l+1,children:[`${m.join(`
|
|
15
15
|
`)}
|
|
16
|
-
`,
|
|
17
|
-
`]})}function
|
|
16
|
+
`,h,b,`
|
|
17
|
+
`]})}function Se(e){const{node:t,as:n="button",href:o,children:i,ref:s,...d}=e,l=et(),c=ne(),h=" ".repeat(l),[m="",...p]=tt(t,c),b=p.map(f=>`${h}${f}`),g=On(t),C=n==="a"?a.jsx("a",{...d,...g,href:o??"#",ref:s,children:m}):a.jsx("button",{...d,...g,ref:s,children:m});return a.jsxs(Ze,{value:l+1,children:[h,C,b.length===0?`
|
|
18
18
|
`:`
|
|
19
|
-
${
|
|
19
|
+
${b.join(`
|
|
20
20
|
`)}
|
|
21
|
-
`,i]})}function
|
|
22
|
-
`);return{...e,parts:[],summary:i}}function
|
|
23
|
-
${
|
|
24
|
-
|
|
21
|
+
`,i]})}function to(e){return e.part==="cell"&&typeof e.state.column=="string"&&typeof e.state.row=="string"}function dt(e){return e.replace(/\|/g,"\\|").replace(/\s*\n\s*/g," ")}function rn(e,t){return JSON.stringify([e,t])}function Dn(e){if(e.parts.length===0||!e.parts.every(to))return e;const t=[],n=[],o=new Map;for(const s of e.parts){const d=String(s.state.column),l=String(s.state.row);t.includes(d)||t.push(d),n.includes(l)||n.push(l),o.set(rn(l,d),s.label??"")}const i=[`| row | ${t.map(dt).join(" | ")} |`,`| --- | ${t.map(()=>"---").join(" | ")} |`,...n.map(s=>`| ${dt(s)} | ${t.map(d=>dt(o.get(rn(s,d))??"")).join(" | ")} |`)].join(`
|
|
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
|
+
${g.current([C.current])}`:"Dismissed. The alert is gone from the page."},[]),k=te({spec:Bt,label:i??n,enabled:s&&w,execute:v}),R=se(d),x=[];R!==void 0&&x.push({part:"message",label:R,state:{}}),w&&x.push({part:"dismiss",label:"Dismiss",state:{},...k===void 0?{}:{tool:k}});const A=$({component:wt.name,label:n,state:{tone:t,dismissible:w},parts:x});if(C.current=A,c==="agent")return!w||h==="never"?a.jsx(Y,{node:A}):a.jsx(ce,{node:A,isActionable:N=>N.part==="dismiss",onActivate:()=>o?.()});const P=t==="danger"||t==="warning"?"alert":"status";return a.jsxs("div",{...l,...V(A),role:P,...n===void 0?{}:{"aria-label":n},children:[n===void 0?null:a.jsx("strong",{...D({part:"title",state:{}}),children:n}),a.jsx("div",{...D({part:"message",state:{}}),children:d}),w?a.jsx("button",{...D({part:"dismiss",state:{},...k===void 0?{}:{tool:k}}),type:"button","aria-label":"Dismiss",ref:p,onClick:()=>o?.(),children:"×"}):null]})}const Re={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."},vt=K({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:Re},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
|
+
label="Workbench"
|
|
25
|
+
items={[
|
|
26
|
+
{ label: "action", children: [{ href: "#/Button", label: "Button" }] },
|
|
27
|
+
{
|
|
28
|
+
label: "display",
|
|
29
|
+
children: [{ href: "#/Table", label: "Table", active: true }],
|
|
30
|
+
},
|
|
31
|
+
]}
|
|
32
|
+
/>`},{title:"A deep path that folds",description:"Past maxCrumbs the middle of the path folds behind an ellipsis, which unfolds it again. A crumb that is open is never folded.",code:`<Breadcrumb
|
|
33
|
+
label="Store"
|
|
34
|
+
maxCrumbs={3}
|
|
35
|
+
items={[
|
|
36
|
+
{
|
|
37
|
+
label: "Clothing",
|
|
38
|
+
href: "#/clothing",
|
|
39
|
+
children: [
|
|
40
|
+
{
|
|
41
|
+
label: "Outerwear",
|
|
42
|
+
href: "#/clothing/outerwear",
|
|
43
|
+
children: [
|
|
44
|
+
{
|
|
45
|
+
label: "Jackets",
|
|
46
|
+
href: "#/clothing/outerwear/jackets",
|
|
47
|
+
children: [{ label: "Rain shell", href: "#/rain-shell", active: true }],
|
|
48
|
+
},
|
|
49
|
+
],
|
|
50
|
+
},
|
|
51
|
+
],
|
|
52
|
+
},
|
|
53
|
+
]}
|
|
54
|
+
/>`},{title:"Trailing actions",description:"Commands for the whole page sit at the end of the bar. A link action publishes its href; one with onSelect registers a WebMCP tool, since an agent has no URL to reach it by.",code:`<Breadcrumb
|
|
55
|
+
label="Docs"
|
|
56
|
+
items={[{ label: "guides", children: [{ href: "#/guide/webmcp", label: "WebMCP", active: true }] }]}
|
|
57
|
+
actions={[
|
|
58
|
+
{ label: "Copy link", onSelect: () => navigator.clipboard.writeText(location.href) },
|
|
59
|
+
{ label: "Source", href: "https://github.com/westonkd/sprint", external: true },
|
|
60
|
+
]}
|
|
61
|
+
/>`},{title:"A root that leads back",description:'Give the root an href and it becomes a link back to the list the page belongs to, the way "People" leads from a person back to everyone.',code:`<Breadcrumb
|
|
62
|
+
label="People"
|
|
63
|
+
href="#/people"
|
|
64
|
+
items={[
|
|
65
|
+
{
|
|
66
|
+
label: "Admin",
|
|
67
|
+
href: "#/people?role=admin",
|
|
68
|
+
children: [{ label: "Tess Ocampo", href: "#/people/tess", active: true }],
|
|
69
|
+
},
|
|
70
|
+
]}
|
|
71
|
+
/>`},{title:"Recording where a person has been",description:"The bar keeps a trail of the destinations chosen through it, reachable from the visited count at its head. Record visits through onNavigate and hand them back in defaultVisited, and the trail survives the bar remounting.",code:`<Breadcrumb
|
|
72
|
+
label="Docs"
|
|
73
|
+
items={[{ label: "guides", children: [{ href: "#/guide/webmcp", label: "WebMCP" }] }]}
|
|
74
|
+
defaultVisited={["#/guide/webmcp"]}
|
|
75
|
+
onNavigate={(item) => console.log(item.href)}
|
|
76
|
+
/>`}]}),ke="",go=12,mo="[data-sprint-shown], button:not([hidden])";function Wn(e,t=[]){const n=t.at(-1)?.id??ke;return e.flatMap((o,i)=>{const s={item:o,id:n===ke?String(i):`${n}.${i}`,parent:n,ancestors:t};return[s,...Wn(o.children??[],[...t,s])]})}function Ke(e){return[...e.ancestors,e]}function ht(e){return(e.item.children?.length??0)>0}function fo(e){return e==="closed"?void 0:e}function ut(e){return e.map(t=>t.item.label).join(" / ")}function bo(e){const t=Re.inputSchema.properties.action;return{...Re.inputSchema,properties:{...Re.inputSchema.properties,...t===void 0?{}:{action:{...t,enum:[...e]}}}}}function wo(e){const{label:t,items:n,actions:o=[],maxCrumbs:i=4,emptyLabel:s="No match",trailEmptyLabel:d="Nothing visited yet",open:l,onOpenChange:c,onNavigate:h,href:m,visited:p,defaultVisited:b=[],agentName:g,agentTool:C=!0,ref:f,...w}=e,v=z(),k=ne(),[R,x]=r.useState(void 0),[A,P]=r.useState(""),[N,T]=r.useState(void 0),[_,M]=r.useState(!1),[X,I]=r.useState(b),q=p??X,F=r.useRef(null),G=r.useRef(null),j=r.useRef(null),Q=r.useRef(new Map),y=r.useRef(o);y.current=o;const E=r.useRef(k);E.current=k;const W=r.useRef($({component:vt.name})),B=r.useRef(!0);r.useEffect(()=>(B.current=!0,()=>{B.current=!1}),[]);const J=r.useCallback(u=>{j.current=u,typeof f=="function"?f(u):f!=null&&(f.current=u)},[f]),le=r.useRef(c);le.current=c;const he=r.useCallback(u=>{x(u),le.current?.(u??"closed")},[]),de=r.useCallback(()=>{he(void 0),P(""),T(void 0)},[he]),ue=r.useMemo(()=>Wn(n),[n]),Ae=ue.find(u=>u.item.active===!0),pe=Ae===void 0?[]:Ke(Ae),je=ue.find(u=>u.id===N),ge=je===void 0?pe:Ke(je),Fe=ge.at(-1),at=Fe===void 0||ht(Fe),me=ge.length+(at?1:0),S=l===void 0?R:fo(l),L=typeof S=="number"?Math.max(0,Math.min(S,me-1)):S,H=L==="trail"?me-1:L;r.useEffect(()=>{L!==void 0&&F.current?.focus()},[L]),r.useEffect(()=>{if(L===void 0)return;const u=O=>{const U=O.target;U instanceof Node&&j.current?.contains(U)===!0||de()};return document.addEventListener("pointerdown",u),()=>document.removeEventListener("pointerdown",u)},[L,de]);const Z=typeof L=="number"?L===0?ke:ge[L-1]?.id??ke:ke,re=A.trim().toLowerCase(),be=re!=="",He=typeof L=="number"&&!be,nn=u=>`${ut(u.ancestors)} ${u.item.label}`.toLowerCase().includes(re),De=new Set;for(const u of ue){const O=u.item.href!==void 0;(L==="trail"?O&&q.includes(u.item.href??"")&&(!be||nn(u)):be?L!==void 0&&O&&nn(u):He&&u.parent===Z)&&De.add(u)}const Ve=[void 0,...ue.filter(ht)].map(u=>({id:u?.id??ke,heading:[t,...u===void 0?[]:Ke(u).map(O=>O.item.label)].join(" / "),members:ue.filter(O=>O.parent===(u?.id??ke))})),Ra=new Set(pe),we=Ve.flatMap(u=>u.members.filter(O=>O.item.href!==void 0).map(O=>{const U={part:"destination",label:O.item.label,state:{...O.ancestors.length>0?{parent:ut(O.ancestors)}:{},href:O.item.href??"",...O.item.active===!0?{active:!0}:{},...O.item.active!==!0&&Ra.has(O)?{ancestor:!0}:{},...O.item.external===!0?{external:!0}:{},...De.has(O)?{shown:!0}:{}}};return{entry:O,part:U}})),La=new Map(we.map(({entry:u,part:O})=>[u,O])),an=o.map(u=>({part:"action",label:u.label,state:{...u.href===void 0?{}:{href:u.href},...u.external===!0?{external:!0}:{}}})),Ge=o.filter(u=>u.href===void 0).map(u=>u.label).join(`
|
|
77
|
+
`),Pa=r.useMemo(()=>bo(Ge===""?[]:Ge.split(`
|
|
78
|
+
`)),[Ge]),Ea=r.useCallback(async u=>{const O=typeof u.action=="string"?u.action:"",U=y.current.filter(ye=>ye.href===void 0),ee=U.find(ye=>ye.label===O);if(ee===void 0)return`No action named "${O}". This breadcrumb offers: ${U.map(ye=>`"${ye.label}"`).join(", ")}.`;const Me=Q.current.get(ee.label);return Me!==void 0?Me.click():ie(()=>ee.onSelect?.()),await oe(),B.current?`Done. The breadcrumb is now:
|
|
79
|
+
${E.current([W.current])}`:"The action removed this breadcrumb from the page."},[]),Oa=te({spec:Re,label:g??t,inputSchema:Pa,enabled:C&&Ge!=="",execute:Ea}),$e=He?Ve.find(u=>u.id===Z)?.members.length??0:De.size,ot=$({component:vt.name,label:t,tool:Oa,region:!0,state:{...m===void 0?{}:{href:m},...pe.length>0?{path:ut(pe)}:{},destinations:String(we.length),visited:String(q.length),...L===void 0?{}:{open:String(L),matches:String($e)}},parts:[...an,...we.map(({part:u})=>u)]});W.current=ot;const it=u=>{if(u.href!==void 0){const O=u.href;I(U=>[...U.filter(ee=>ee!==O),O])}de(),h?.(u)};if(v==="agent")return a.jsx(ce,{node:ot,onActivate:(u,O)=>{const U=o[O];if(U!==void 0){U.href===void 0?U.onSelect?.():window.location.assign(U.href);return}const ee=we[O-o.length]?.entry;ee?.item.href!==void 0&&(it(ee.item),window.location.assign(ee.item.href))}});const Na=u=>{P(""),he(L===u?void 0:u)},Da=u=>{T(u.id),P(""),he(Ke(u).length)},$a=u=>u.reduce((O,U)=>Math.max(O,q.indexOf(U.item.href??"")),-1),Ma=L==="trail"?Ve.map(u=>({id:u.id,seen:$a(u.members)})).filter(u=>u.seen>=0).sort((u,O)=>O.seen-u.seen).map(u=>u.id):[],Ia=u=>{const O=Ma.indexOf(u)+1;return O>0&&O<=go?{"data-sprint-recency":String(O)}:{}},rt=()=>{const u=G.current;return u===null?[]:Array.from(u.querySelectorAll(mo)).filter(O=>O.closest("[hidden]")===null)},st=u=>{const O=rt();O[u<0?O.length-1:u%O.length]?.focus()},Ua=u=>{if(u.key==="Escape"){de();return}if(u.key==="ArrowDown"){u.preventDefault(),st(0);return}if(u.key==="ArrowUp"&&L!=="trail"){u.preventDefault(),P(""),he("trail");return}u.key==="Enter"&&(u.preventDefault(),rt()[0]?.click())},qa=u=>{if(u.key==="Escape"){de();return}const U=rt().indexOf(u.target);if(u.key==="ArrowDown"){u.preventDefault(),st(U+1);return}if(u.key==="ArrowUp"){u.preventDefault(),U<=0?F.current?.focus():st(U-1);return}u.key.length!==1||u.metaKey||u.ctrlKey||u.altKey||(u.preventDefault(),P(ee=>`${ee}${u.key}`),F.current?.focus())},on=Math.max(1,i-2),Wa=!_&&me>i&&(H===void 0||H===0||H>=me-on),_a=u=>Wa&&u>0&&u<me-on,Ba=u=>{const O=ge[u],U=O?.item,ee=u===0?t:ge[u-1]?.item.label??t,Me=a.jsx("button",{type:"button","aria-expanded":L===u,"aria-label":`Browse ${ee}`,onClick:()=>Na(u)});return H===u?a.jsxs(a.Fragment,{children:[Me,a.jsx("input",{ref:F,type:"text","aria-label":`Search ${t}`,value:A,placeholder:L==="trail"?`Search ${q.length} visited`:`Search ${we.length} destinations`,onChange:ye=>P(ye.target.value),onKeyDown:Ua})]}):a.jsxs(a.Fragment,{children:[Me,U===void 0?null:U.href===void 0?a.jsx("span",{children:U.label}):a.jsx("a",{href:U.href,"aria-current":O===Ae?"page":void 0,target:U.external===!0?"_blank":void 0,rel:U.external===!0?"noreferrer noopener":void 0,onClick:()=>it(U),children:U.label})]})},Fa=L==="trail"&&q.length===0?d:s,Ha=L==="trail"?q.length:be?we.length:$e,Va=L===void 0?`${we.length} destinations`:be?`${$e} of ${we.length} match`:`${$e} of ${Ha}`;return a.jsxs("nav",{...w,...V(ot),"aria-label":t,ref:J,children:[a.jsxs("div",{children:[a.jsx("button",{type:"button","aria-label":`Visited, ${q.length}`,"aria-expanded":L==="trail",onClick:()=>{P(""),he(L==="trail"?void 0:"trail")},children:String(q.length).padStart(2,"0")}),a.jsxs("ol",{children:[a.jsx("li",{children:m===void 0?a.jsx("span",{children:t}):a.jsx("a",{href:m,children:t})}),Array.from({length:me},(u,O)=>[a.jsx("li",{..._a(O)?{hidden:!0}:{},children:Ba(O)},ge[O]?.id??"tail"),O===0&&me>1?a.jsx("li",{children:a.jsx("button",{type:"button","aria-label":"Show the whole path","aria-expanded":_,onClick:()=>M(U=>!U),children:"…"})},"fold"):null])]}),a.jsx("span",{"aria-live":"polite",children:Va}),o.map((u,O)=>{const U=an[O];return U===void 0?null:u.href===void 0?a.jsx("button",{type:"button",...D(U),ref:ee=>{ee===null?Q.current.delete(u.label):Q.current.set(u.label,ee)},onClick:()=>u.onSelect?.(),children:u.label},u.label):a.jsx("a",{...D(U),href:u.href,target:u.external===!0?"_blank":void 0,rel:u.external===!0?"noreferrer noopener":void 0,children:u.label},u.label)})]}),a.jsxs("div",{ref:G,onKeyDown:qa,...L===void 0?{hidden:!0}:{},children:[Ve.map(u=>{const O=u.members.some(U=>De.has(U)&&(U.item.href!==void 0||He));return a.jsxs("div",{...Ia(u.id),...O?{}:{hidden:!0},children:[a.jsx("span",{children:u.heading}),u.members.map(U=>{const ee=La.get(U);return a.jsxs("span",{children:[ee===void 0?null:a.jsx("a",{...D(ee),href:U.item.href,"aria-current":U.item.active===!0?"page":void 0,target:U.item.external===!0?"_blank":void 0,rel:U.item.external===!0?"noreferrer noopener":void 0,onClick:()=>it(U.item),children:U.item.label}),ht(U)?a.jsx("button",{type:"button","aria-label":ee===void 0?void 0:`Inside ${U.item.label}`,onClick:()=>Da(U),...He&&De.has(U)?{}:{hidden:!0},children:ee===void 0?U.item.label:"›"}):null]},U.id)})]},u.id||"root")}),$e===0?a.jsx("p",{children:Fa}):null]})]})}const Ft={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."},yt=K({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"},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"]},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:Ft},agentView:{example:'- **Button** "Prepare launch" [tone=action] → tool `press-prepare-launch`'},examples:[{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 vo(){return new MouseEvent("click",{bubbles:!0,cancelable:!0})}function Qe(e){const{tone:t="neutral",block:n=!1,loading:o=!1,agentName:i,agentTool:s=!0,disabled:d=!1,type:l="button",children:c,ref:h,onClick:m,...p}=e,b=z(),g=ae(),C=ne(),f=r.useRef(null),w=r.useCallback(q=>{f.current=q,typeof h=="function"?h(q):h!=null&&(h.current=q)},[h]),v=i??(typeof c=="string"?c:void 0),[k,R]=r.useState(void 0);r.useLayoutEffect(()=>{if(v!==void 0)return;const q=f.current;q!==null&&R(_e(q))});const x=d||o,A=v??k,P=r.useRef(m);P.current=m;const N=r.useRef($({component:yt.name})),T=r.useRef(C);T.current=C;const _=r.useRef(!0);r.useEffect(()=>(_.current=!0,()=>{_.current=!1}),[]);const M=r.useCallback(async()=>{const q=f.current;if(q!==null)q.click();else{const F=P.current;if(F===void 0)return"This button renders no control in the current view and has no click handler.";ie(()=>F(vo()))}return await oe(),_.current?`Pressed. The button is now:
|
|
80
|
+
${T.current([N.current])}`:"The press removed this button from the page."},[]),X=te({spec:Ft,label:A,enabled:s&&!x,execute:M}),I=$({component:yt.name,label:A,tool:X,state:{tone:t,block:n,loading:o,disabled:x}});return N.current=I,b==="agent"?x||g==="never"?a.jsx(Y,{node:I}):a.jsx(Se,{node:I,type:l,ref:w,onClick:m,"aria-busy":o||void 0}):a.jsx("button",{...p,...V(I),type:l,ref:w,onClick:m,disabled:x,"aria-busy":o||void 0,children:c})}const Ht={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."},kt=K({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:Ht},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">
|
|
25
81
|
A single action a person or an agent can trigger.
|
|
26
82
|
</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}>
|
|
27
83
|
An empty page with the provider already wired up.
|
|
28
|
-
</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
|
|
29
|
-
${
|
|
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 yo(e){const{label:t,children:n,href:o,onClick:i,disabled:s=!1,agentTool:d,agentName:l,ref:c,...h}=e,m=z(),p=ae(),b=ne(),g=o!==void 0,C=!g&&s,f=r.useRef(null),w=r.useCallback(M=>{f.current=M,typeof c=="function"?c(M):c!=null&&(c.current=M)},[c]),v=r.useRef(b);v.current=b;const k=r.useRef($({component:kt.name})),R=r.useRef(!0);r.useEffect(()=>(R.current=!0,()=>{R.current=!1}),[]);const x=r.useCallback(async()=>{const M=f.current;return M===null?"This card renders no control in the current view.":(M.click(),await oe(),R.current?`Opened. The card is now:
|
|
85
|
+
${v.current([k.current])}`:"Opening removed this card from the page.")},[]),A=te({spec:Ht,label:l??t,enabled:(d??!g)&&!C,execute:x}),P=se(n),N=[{part:"title",label:t,state:{}},...P===void 0?[]:[{part:"body",label:P,state:{}}]],T=$({component:kt.name,label:t,tool:A,state:{href:o,disabled:C},parts:N});if(k.current=T,m==="agent")return C||p==="never"?a.jsx(Y,{node:T}):a.jsx(Se,{node:T,as:g?"a":"button",href:o,ref:w,onClick:i});const _=a.jsxs(a.Fragment,{children:[a.jsx("span",{...D({part:"title",state:{}}),children:t}),n===void 0?null:a.jsx("span",{...D({part:"body",state:{}}),children:n})]});return g?a.jsx("a",{...h,...V(T),href:o,"aria-label":t,onClick:i,ref:w,children:_}):a.jsx("button",{...h,...V(T),type:"button","aria-label":t,disabled:s,onClick:i,ref:w,children:_})}const _n=K({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
|
+
label="Role changes"
|
|
87
|
+
changes={[{ kind: "changed", label: "Ada Lovelace", from: "Write", to: "Maintain" }]}
|
|
88
|
+
/>`},{title:"A review before confirming",description:"Additions, removals and changes together, each with a line of consequence where one matters.",code:`<ChangeList
|
|
89
|
+
label="Team changes"
|
|
90
|
+
changes={[
|
|
91
|
+
{ kind: "added", label: "Grace Hopper", detail: "Gets read access to every repository." },
|
|
92
|
+
{ kind: "removed", label: "Alan Turing" },
|
|
93
|
+
{ kind: "changed", label: "Ada Lovelace", from: "Write", to: "Maintain" },
|
|
94
|
+
]}
|
|
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" />'}]}),ko={role:"list"},xo=["added","removed","changed"],Bn={added:"+",removed:"−",changed:"→"},Fn={added:"Added",removed:"Removed",changed:"Changed"};function ve(e){return e!==void 0&&e!==""}function To(e){const t=ve(e.from)?` from ${e.from}`:"",n=ve(e.to)?` to ${e.to}`:"";return t===""&&n===""?"":`,${t}${n}`}function Co(e){const t=ve(e.detail)?`. ${e.detail}`:"";return`${Fn[e.kind]}: ${e.label}${To(e)}${t}`}function Hn(e){return{kind:e.kind,...ve(e.from)?{from:e.from}:{},...ve(e.to)?{to:e.to}:{}}}function So(e){const t={};for(const n of xo){const o=e.filter(i=>i.kind===n).length;t[n]=o===0?void 0:String(o)}return t}function Ao({change:e}){const t=ve(e.from)?e.from:void 0,n=ve(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:Bn.changed}),n===void 0?null:a.jsxs(a.Fragment,{children:[a.jsx("span",{children:" to "}),a.jsx("ins",{children:n})]})]})}function jo({change:e}){return a.jsxs("li",{...D({part:"change",state:Hn(e)}),children:[a.jsx("span",{"aria-hidden":"true",children:Bn[e.kind]}),a.jsxs("p",{children:[a.jsxs("span",{children:[Fn[e.kind],": "]}),a.jsx("strong",{children:e.label}),a.jsx(Ao,{change:e}),ve(e.detail)?a.jsxs(a.Fragment,{children:[a.jsx("span",{children:". "}),a.jsx("small",{children:e.detail})]}):null]})]})}function Ro(e){const{label:t,changes:n,emptyLabel:o="No changes",...i}=e,s=z(),d=n.length===0,l=n.map(h=>({part:"change",label:Co(h),state:Hn(h)})),c=$({component:_n.name,label:t,state:{changes:String(n.length),...So(n),empty:d},parts:l});return s==="agent"?a.jsx(Y,{node:c}):a.jsx("ul",{...i,...V(c),...ko,"aria-label":t,children:d?a.jsx("li",{children:o}):n.map((h,m)=>a.jsx(jo,{change:h},`${m}-${h.kind}-${h.label}`))})}const Vt={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."},xt=K({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},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.",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:Vt},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
|
|
30
96
|
label="Accept the terms"
|
|
31
97
|
checked={accepted}
|
|
32
98
|
onChange={setAccepted}
|
|
@@ -42,20 +108,66 @@ ${k.current([x.current])}`:"Opening removed this card from the page.")},[]),P=G(
|
|
|
42
108
|
checked
|
|
43
109
|
disabled
|
|
44
110
|
onChange={setTelemetry}
|
|
45
|
-
/>`}],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
|
|
46
|
-
${
|
|
111
|
+
/>`}],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 Lo(e,t){return e!==void 0?[{part:"error",label:e,state:{}}]:t!==void 0?[{part:"hint",label:t,state:{}}]:[]}function Po(e){const{label:t,checked:n,onChange:o,hint:i,error:s,name:d,disabled:l=!1,required:c=!1,agentName:h,agentTool:m=!0,...p}=e,b=z(),g=ae(),C=ne(),f=r.useId(),w=r.useRef(null),v=r.useRef(o);v.current=o;const k=r.useRef(n);k.current=n;const R=r.useRef(C);R.current=C;const x=r.useRef($({component:xt.name})),A=r.useRef(!0);r.useEffect(()=>(A.current=!0,()=>{A.current=!1}),[]);const P=r.useCallback(async M=>{const X=M.checked;if(typeof X!="boolean")return'Pass "checked" as true or false; it states the end state.';const I=X===k.current;if(!I){const F=w.current;F!==null?F.click():ie(()=>v.current(X))}return await oe(),A.current?`${I?`Already ${X?"checked":"unchecked"}`:X?"Checked":"Unchecked"}. The checkbox is now:
|
|
112
|
+
${R.current([x.current])}`:"The change removed this checkbox from the page."},[]),N=te({spec:Vt,label:h??t,enabled:m&&!l,execute:P}),T=$({component:xt.name,label:t,tool:N,state:{checked:n,disabled:l,required:c,invalid:s!==void 0},parts:Lo(s,i)});if(x.current=T,b==="agent")return l||g==="never"?a.jsx(Y,{node:T}):a.jsx(Se,{node:T,ref:M=>{w.current=M},onClick:()=>o(!n)});const _=s!==void 0?`${f}-error`:i!==void 0?`${f}-hint`:void 0;return a.jsxs("div",{...p,...V(T),children:[a.jsxs("label",{htmlFor:f,children:[a.jsx("input",{id:f,...D({part:"input",state:{}}),ref:M=>{w.current=M},type:"checkbox",checked:n,name:d,disabled:l,required:c,"aria-invalid":s!==void 0||void 0,"aria-describedby":_,onChange:M=>o(M.currentTarget.checked)}),a.jsx("span",{...D({part:"box",state:{}}),"aria-hidden":"true"}),t]}),s!==void 0?a.jsx("p",{id:_,...D({part:"error",state:{}}),children:s}):i!==void 0?a.jsx("p",{id:_,...D({part:"hint",state:{}}),children:i}):null]})}const Le={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."},Tt=K({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:Le},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
|
+
<ChoiceGrid
|
|
114
|
+
label="Which emoji were you sent?"
|
|
115
|
+
name="emoji"
|
|
116
|
+
agentTool={false}
|
|
117
|
+
options={[
|
|
118
|
+
{ value: "fox", label: "Fox", glyph: "🦊" },
|
|
119
|
+
{ value: "rocket", label: "Rocket", glyph: "🚀" },
|
|
120
|
+
{ value: "cactus", label: "Cactus", glyph: "🌵" },
|
|
121
|
+
{ value: "anchor", label: "Anchor", glyph: "⚓" },
|
|
122
|
+
{ value: "pizza", label: "Pizza", glyph: "🍕" },
|
|
123
|
+
{ value: "comet", label: "Comet", glyph: "☄️" },
|
|
124
|
+
]}
|
|
125
|
+
/>
|
|
126
|
+
</form>`},{title:"Picking one with state",description:"Select mode with four columns: the tiles are a radio group, and in agent view each one renders as its own control so an agent can choose without WebMCP.",code:`<ChoiceGrid
|
|
127
|
+
label="Pick a reaction"
|
|
128
|
+
columns={4}
|
|
129
|
+
name="reaction"
|
|
130
|
+
value={reaction}
|
|
131
|
+
onChange={setReaction}
|
|
132
|
+
options={[
|
|
133
|
+
{ value: "up", label: "Thumbs up", glyph: "👍" },
|
|
134
|
+
{ value: "fire", label: "Fire", glyph: "🔥" },
|
|
135
|
+
{ value: "laugh", label: "Laughing", glyph: "😂" },
|
|
136
|
+
{ value: "sad", label: "Sad", glyph: "😢" },
|
|
137
|
+
]}
|
|
138
|
+
/>`},{title:"A disabled grid",description:"Disabled unregisters the tool and renders the agent view as text only, so an agent cannot press a tile a person could not.",code:`<ChoiceGrid
|
|
139
|
+
label="Delivery window"
|
|
140
|
+
columns={2}
|
|
141
|
+
disabled
|
|
142
|
+
value="morning"
|
|
143
|
+
onChange={setWindow}
|
|
144
|
+
options={[
|
|
145
|
+
{ value: "morning", label: "Morning", glyph: "☀" },
|
|
146
|
+
{ value: "evening", label: "Evening", glyph: "☾" },
|
|
147
|
+
]}
|
|
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"]}),Eo=["ArrowRight","ArrowDown","ArrowLeft","ArrowUp","Home","End"];function Oo(e){const t=Le.inputSchema.properties.option;return{...Le.inputSchema,properties:{...Le.inputSchema.properties,...t===void 0?{}:{option:{...t,enum:e.map(n=>n.label)}}}}}function No(e,t,n){return e==="Home"?0:e==="End"?n-1:(t+(e==="ArrowRight"||e==="ArrowDown"?1:-1)+n)%n}function Do(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 $o(e){const{label:t,options:n,columns:o=3,name:i,value:s,onChange:d,disabled:l=!1,agentName:c,agentTool:h=!0,...m}=e,p=d===void 0?"submit":"select",b=z(),g=ae(),C=ne(),f=r.useId(),w=r.useRef(new Map),v=r.useRef(null),k=r.useRef(d);k.current=d;const R=r.useRef(n);R.current=n;const x=r.useRef(p);x.current=p;const A=r.useRef(C);A.current=C;const P=r.useRef($({component:Tt.name})),N=r.useRef(!0);r.useEffect(()=>(N.current=!0,()=>{N.current=!1}),[]);const T=r.useCallback(y=>{const E=w.current.get(y);if(E!==void 0)return E.click(),x.current==="select"||E.form!==null;const W=k.current;return x.current==="select"&&W!==void 0?(ie(()=>W(y)),!0):Do(v.current,y)},[]),_=r.useCallback(async y=>{const E=typeof y.option=="string"?y.option:"",W=R.current.find(le=>le.label===E);if(W===void 0)return`No option named "${E}". This grid offers: ${R.current.map(le=>`"${le.label}"`).join(", ")}.`;if(!T(W.value))return`No form surrounds this grid, so choosing "${W.label}" had nothing to submit.`;await oe();const J=x.current==="submit"?`Chose "${W.label}" and submitted the form.`:`Chose "${W.label}".`;return N.current?`${J} The grid is now:
|
|
149
|
+
${A.current([P.current])}`:`${J} The grid is no longer on the page.`},[T]),M=r.useMemo(()=>Oo(n),[n]),X=te({spec:Le,label:c??t,inputSchema:M,enabled:h&&!l,execute:_}),I=p==="select"?s:void 0,q=n.map(y=>({part:"choice",label:y.label,state:{value:y.value,...y.value===I?{checked:!0}:{},...l?{disabled:!0}:{}}})),F=$({component:Tt.name,label:t,tool:X,state:{mode:p,value:I,columns:String(o),disabled:l},parts:q});P.current=F;const G=p==="select"&&i!==void 0?a.jsx("input",{type:"hidden",name:i,value:I??""}):null;if(b==="agent")return l||g==="never"?a.jsx(Y,{node:F}):a.jsx(ce,{node:F,onActivate:(y,E)=>{const W=n[E];W!==void 0&&T(W.value)},children:p==="select"?G:a.jsx("input",{type:"hidden",name:i,disabled:!0,ref:v})});const j=y=>{if(!Eo.includes(y.key)||l||n.length===0)return;const E=n.findIndex(B=>w.current.get(B.value)===y.target);if(E===-1)return;const W=n[No(y.key,E,n.length)];W!==void 0&&(y.preventDefault(),w.current.get(W.value)?.focus(),p==="select"&&T(W.value))},Q=n.some(y=>y.value===I);return a.jsxs("fieldset",{...m,...V(F),role:p==="select"?"radiogroup":void 0,"aria-labelledby":f,disabled:l,onKeyDown:j,children:[a.jsx("legend",{id:f,children:t}),a.jsx("div",{children:n.map((y,E)=>{const W=y.value===I,J=p==="select"?{type:"button",role:"radio","aria-checked":W,tabIndex:(Q?W:E===0)?0:-1,onClick:()=>d?.(y.value)}:{type:"submit",name:i,value:y.value};return a.jsxs("button",{...J,disabled:l,ref:le=>{le===null?w.current.delete(y.value):w.current.set(y.value,le)},...D(q[E]??{part:"choice",state:{}}),children:[y.glyph===void 0?null:a.jsx("span",{"aria-hidden":"true",children:y.glyph}),a.jsx("span",{children:y.label})]},y.value)})}),G]})}const Mo=/(\/\/[^\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,Io=["comment","string","tag","attr","keyword","number","punct"];function Vn(e){const t=[];let n=0;for(const o of e.matchAll(Mo)){const i=o.index;if(i===void 0)continue;i>n&&t.push({kind:"plain",text:e.slice(n,i)});const s=Io.find((d,l)=>o[l+1]!==void 0)??"plain";t.push({kind:s,text:o[0]}),n=i+o[0].length}return n<e.length&&t.push({kind:"plain",text:e.slice(n)}),t}const Gn=K({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
|
|
47
150
|
caption="descriptor"
|
|
48
151
|
language="json"
|
|
49
152
|
code={JSON.stringify(descriptor, null, 2)}
|
|
50
|
-
/>`}],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."}}),
|
|
51
|
-
`).length),copied:
|
|
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."}}),Uo=1200;function qo(e){const{code:t,caption:n,language:o="tsx",copyLabel:i="Copy",...s}=e,d=z(),[l,c]=r.useState(!1);r.useEffect(()=>{if(!l)return;const g=setTimeout(()=>c(!1),Uo);return()=>clearTimeout(g)},[l]);const h=n??o,m=l?"Copied":i,p=$({component:Gn.name,label:h,state:{language:o,lines:String(t.split(`
|
|
154
|
+
`).length),copied:l},parts:[{part:"copy",label:m,state:{}},{part:"code",label:t,state:{}}]});if(d==="agent")return a.jsx(Y,{node:p});const b=()=>{const g=navigator.clipboard;g!==void 0&&g.writeText(t).then(()=>c(!0),()=>c(!1))};return a.jsxs("figure",{...s,...V(p),"aria-label":h,children:[a.jsxs("header",{children:[a.jsx("span",{children:h}),a.jsx("button",{type:"button","aria-live":"polite",...D({part:"copy",state:{}}),onClick:b,children:m})]}),a.jsx("pre",{...D({part:"code",state:{}}),children:a.jsx("code",{children:Vn(t).map((g,C)=>a.jsx("span",{"data-sprint-token":g.kind==="plain"?void 0:g.kind,children:g.text},`${C}-${g.text}`))})})]})}const Kn=K({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
|
+
label="Setup link"
|
|
156
|
+
value="https://sprint.example/setup/7HW4-XK92-QQ1D?station=KX-2209&expires=2026-10-01"
|
|
157
|
+
/>`},{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
|
|
158
|
+
label="Invite code"
|
|
159
|
+
value="NOMAD-0042"
|
|
160
|
+
copyLabel="Copy code"
|
|
161
|
+
copiedLabel="Code copied"
|
|
162
|
+
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"]}),Wo=2e3;function _o(e){if(e===null)return;const t=e.ownerDocument.getSelection();t!==null&&t.selectAllChildren(e)}function Bo(e){const{label:t,value:n,copyLabel:o="Copy",copiedLabel:i="Copied",onCopy:s,...d}=e,l=z(),c=ae(),h=r.useId(),[m,p]=r.useState("idle"),b=r.useRef(null),g=r.useRef(s);g.current=s,r.useEffect(()=>{if(m!=="copied")return;const A=setTimeout(()=>p("idle"),Wo);return()=>clearTimeout(A)},[m]);const C=()=>{p("failed"),_o(b.current)},f=()=>{const A=navigator.clipboard;if(A===void 0){C();return}A.writeText(n).then(()=>{p("copied"),g.current?.(n)},C)},w=m==="copied",v=w?i:o,k=[{part:"value",...n===""?{}:{label:n},state:{}},{part:"copy",label:v,state:{}}],R=$({component:Kn.name,label:t,state:{copied:w,"copy-failed":m==="failed"},parts:k});if(l==="agent")return c==="never"?a.jsx(Y,{node:R}):a.jsx(ce,{node:R,isActionable:A=>A.part==="copy",onActivate:f});const x=`${h}-label`;return a.jsxs("fieldset",{...d,...V(R),"aria-labelledby":x,children:[a.jsx("legend",{id:x,children:t}),a.jsxs("div",{children:[a.jsx("span",{...D({part:"value",state:{}}),ref:b,title:n,children:n}),a.jsx("button",{...D({part:"copy",state:{}}),type:"button","aria-live":"polite",onClick:f,children:v})]})]})}const zn=K({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
|
|
52
164
|
label="Key sk-prod"
|
|
53
165
|
items={[
|
|
54
166
|
{ term: "Created", description: "2026-08-01" },
|
|
55
167
|
{ term: "Last used", description: "2 hours ago" },
|
|
56
168
|
{ term: "Scopes", description: "read, write" },
|
|
57
169
|
]}
|
|
58
|
-
/>`},{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
|
|
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 Fo(e){const t=se(e.term),n=se(e.description);if(!(t===void 0&&n===void 0))return`${t??""}: ${n??""}`}function Ho(e){const{label:t,items:n,emptyLabel:o="Empty",loading:i=!1,loadingLabel:s="Loading",...d}=e,l=z(),c=n.length===0,h=n.map((p,b)=>{const g=Fo(p);return{part:"item",state:{index:String(b+1)},...g===void 0?{}:{label:g}}}),m=$({component:zn.name,label:t,state:{items:String(n.length),empty:c,loading:i},parts:h});return l==="agent"?a.jsx(Y,{node:m}):a.jsx("dl",{...d,...V(m),"aria-label":t,"aria-busy":i||void 0,children:c?a.jsx("div",{children:a.jsx("span",{children:i?s:o})}):n.map((p,b)=>a.jsxs("div",{...D({part:"item",state:{index:String(b+1)}}),children:[a.jsx("dt",{children:p.term}),a.jsx("dd",{children:p.description})]},`${b}-${String(se(p.term))}`))})}const Gt={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."},Xn=K({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"]},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"}},tools:{close:Gt},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)}>
|
|
59
171
|
<Stack gap="tight">
|
|
60
172
|
<Text>The key stops authenticating immediately. This cannot be undone.</Text>
|
|
61
173
|
<Button tone="danger" onClick={revoke}>Revoke sk-prod</Button>
|
|
@@ -67,7 +179,65 @@ ${A.current([R.current])}`:"The change removed this checkbox from the page."},[]
|
|
|
67
179
|
onClose={() => setRotating(false)}
|
|
68
180
|
>
|
|
69
181
|
<Text>The current secret keeps working for one hour.</Text>
|
|
70
|
-
</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
|
|
182
|
+
</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 Vo(e){const{label:t,open:n,onClose:o,headingLevel:i,owner:s,agentName:d,agentTool:l=!0,children:c,ref:h,...m}=e,p=z(),b=ae(),g=Be(),C=r.useRef(null),f=r.useRef(null),w=r.useRef(o);w.current=o;const v=r.useRef(n);v.current=n;const k=r.useCallback(T=>{C.current=T,typeof h=="function"?h(T):h!=null&&(h.current=T)},[h]);r.useEffect(()=>{if(!n)return;const T=C.current;if(T!==null)return T.open||(typeof T.showModal=="function"?T.showModal():T.open=!0),()=>{T.open&&(typeof T.close=="function"?T.close():T.open=!1)}},[n]);const R=r.useCallback(async()=>{const T=f.current;return T!==null?T.click():ie(()=>w.current()),await oe(),v.current?"The page kept the dialog open.":"Closed. The dialog is gone from the page."},[]),x=te({spec:Gt,label:d??t,enabled:l&&n,execute:R}),A=r.useMemo(()=>({path:[...g,t]}),[g,t]);if(!n)return null;const P=$({component:Xn.name,label:t,owner:s,region:!0,state:{open:!0},parts:[{part:"close",label:"Close",state:{},...x===void 0?{}:{tool:x}}]});if(p==="agent")return a.jsx(ce,{node:P,isActionable:()=>b!=="never",onActivate:()=>o(),children:a.jsx(qe,{value:A,children:c})});const N=i===void 0?"span":`h${i}`;return a.jsxs("dialog",{...m,...V(P),"aria-label":t,ref:k,onCancel:T=>{T.preventDefault(),o()},children:[a.jsxs("header",{children:[a.jsx(N,{children:t}),a.jsx("button",{...D({part:"close",state:{},...x===void 0?{}:{tool:x}}),type:"button","aria-label":"Close",ref:f,onClick:()=>o(),children:"×"})]}),a.jsx("div",{children:a.jsx(qe,{value:A,children:c})})]})}const Kt={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."},Ct=K({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:Kt},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
|
+
<Text>Admin through the Operators group.</Text>
|
|
184
|
+
</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
|
+
label="Access breakdown"
|
|
186
|
+
expanded={open}
|
|
187
|
+
onExpandedChange={setOpen}
|
|
188
|
+
>
|
|
189
|
+
<Text>Admin through the Operators group.</Text>
|
|
190
|
+
</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
|
+
<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 ln(e){return/^[A-Z][a-z]/.test(e)?`${e[0]?.toLowerCase()}${e.slice(1)}`:e}function Go(e){const{label:t,expanded:n,defaultExpanded:o=!1,onExpandedChange:i,showLabel:s=`Show ${ln(t)}`,hideLabel:d=`Hide ${ln(t)}`,agentName:l,agentTool:c=!0,children:h,...m}=e,p=z(),b=ae(),g=ne(),C=r.useId(),[f,w]=r.useState(o),v=n??f,k=r.useRef(null),R=r.useRef(v);R.current=v;const x=r.useRef(n!==void 0);x.current=n!==void 0;const A=r.useRef(i);A.current=i;const P=r.useRef(g);P.current=g;const N=r.useRef($({component:Ct.name})),T=r.useRef(!0);r.useEffect(()=>(T.current=!0,()=>{T.current=!1}),[]);const _=r.useCallback(G=>{x.current||w(G),A.current?.(G)},[]),M=()=>_(!v),X=r.useCallback(async G=>{const j=G.expanded;if(typeof j!="boolean")return'Pass "expanded" as true or false; it states the end state.';const Q=j===R.current;if(!Q){const E=k.current;E!==null?E.click():ie(()=>_(j))}return await oe(),T.current?`${Q?`Already ${j?"expanded":"collapsed"}`:j?"Expanded":"Collapsed"}. The disclosure is now:
|
|
193
|
+
${P.current([N.current])}`:"The change removed this disclosure from the page."},[_]),I=te({spec:Kt,label:l??t,enabled:c,execute:X}),q={part:"toggle",label:v?d:s,state:v?{expanded:!0}:{}},F=$({component:Ct.name,label:t,tool:I,region:!0,state:{expanded:v},parts:[q]});return N.current=F,p==="agent"?b==="never"?a.jsx(Y,{node:F,children:h}):a.jsx(ce,{node:F,onActivate:M,children:h}):a.jsxs("section",{...m,...V(F),"aria-label":t,children:[a.jsx("button",{...D(q),ref:k,type:"button","aria-expanded":v,"aria-controls":C,onClick:M,children:q.label}),a.jsx("div",{id:C,children:h})]})}const Yn=K({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
|
+
<Breadcrumb
|
|
195
|
+
label="Docs"
|
|
196
|
+
items={[{ label: "guides", children: [{ href: "#/guide/webmcp", label: "WebMCP", active: true }] }]}
|
|
197
|
+
/>
|
|
198
|
+
<Divider />
|
|
199
|
+
<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 Ko(e){const{label:t,weight:n="hairline",...o}=e,i=z(),s=$({component:Yn.name,label:t,state:{weight:n}});return i==="agent"?t===void 0?null:a.jsx(Y,{node:s}):a.jsxs("div",{...o,...V(s),children:[t===void 0?null:a.jsx("span",{children:t}),a.jsx("hr",{})]})}const zt={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."},Qn=K({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:zt},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
|
+
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 Jn(e){const{href:t,active:n=!1,external:o=!1,agentTool:i=!1,agentName:s,children:d,ref:l,onClick:c,...h}=e,m=z(),p=ae(),b=r.useRef(null),g=r.useCallback(R=>{b.current=R,typeof l=="function"?l(R):l!=null&&(l.current=R)},[l]),C=s??se(d),f=r.useCallback(()=>{const R=b.current;return R===null?"This link renders no element in the current view. Navigate to its href instead.":(R.click(),`Following ${R.getAttribute("href")??t}.`)},[t]),w=te({spec:zt,label:C,enabled:i,execute:f}),v=$({component:Qn.name,label:se(d),tool:w,state:{href:t,active:n,external:o}}),k=o?{target:"_blank",rel:"noreferrer noopener"}:{target:void 0,rel:void 0};return m==="agent"?p==="never"?a.jsx(Y,{node:v}):a.jsx(Se,{node:v,as:"a",href:t,ref:g,onClick:c,target:k.target,rel:k.rel}):a.jsx("a",{...h,...V(v),href:t,ref:g,onClick:c,"aria-current":n?"page":void 0,target:k.target,rel:k.rel,children:d})}const Zn=K({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
|
+
reason="filtered"
|
|
204
|
+
label="No one matches these filters"
|
|
205
|
+
description="Try a different role or clear the search."
|
|
206
|
+
action={{ label: "Clear filters", onSelect: clearFilters }}
|
|
207
|
+
/>`},{title:"Nothing yet",description:"The first-run case, with a link to where records are made.",code:`<EmptyState
|
|
208
|
+
label="No projects yet"
|
|
209
|
+
description="Projects you create or are invited to appear here."
|
|
210
|
+
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 zo(e){const{action:t}=e;return t.href!==void 0?a.jsx(Jn,{href:t.href,onClick:t.onSelect,children:t.label}):a.jsx(Qe,{onClick:t.onSelect,children:t.label})}function Xo(e){const{label:t,description:n,action:o,reason:i="empty",...s}=e,d=z(),l=r.useId(),c=n===void 0?[]:[{part:"description",label:n,state:{}}],h=$({component:Zn.name,label:t,state:{empty:!0,reason:i},parts:c}),m=o===void 0?null:a.jsx(zo,{action:o});if(d==="agent")return a.jsx(Y,{node:h,children:m});const p=`${l}-label`,b=`${l}-description`;return a.jsx("div",{...s,...V(h),role:"group","aria-labelledby":p,"aria-describedby":n===void 0?void 0:b,children:a.jsxs("div",{children:[a.jsx("p",{id:p,children:t}),n===void 0?null:a.jsx("p",{id:b,...D({part:"description",state:{}}),children:n}),m]})})}const ea=K({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}},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"}},agentView:{example:'- **Tag** "experimental" [filled, tone=warning]'},examples:[{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
|
+
{tool.readOnly ? "read only" : "changes state"}
|
|
213
|
+
</Tag>`}]});function ta(e){const{tone:t="neutral",filled:n=!1,children:o,...i}=e,s=z(),d=$({component:ea.name,label:se(o),state:{tone:t,filled:n}});return s==="agent"?a.jsx(Y,{node:d}):a.jsx("span",{...i,...V(d),children:o})}const Xt={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."},St=K({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:Xt},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
|
+
title="Ada Lovelace"
|
|
215
|
+
href="#/people/ada"
|
|
216
|
+
tags={[{ label: "admin", tone: "info" }, { label: "billing" }]}
|
|
217
|
+
meta={[{ term: "Last sign-in", detail: "3 days ago" }, "2 apps"]}
|
|
218
|
+
/>`},{title:"A row that acts",description:"onSelect instead of href, so the row registers open-grace-hopper and an agent can pick it.",code:`<EntityRow
|
|
219
|
+
title="Grace Hopper"
|
|
220
|
+
onSelect={() => select("grace")}
|
|
221
|
+
tags={[{ label: "owner", tone: "warning" }]}
|
|
222
|
+
meta={["Invited yesterday"]}
|
|
223
|
+
/>`},{title:"A directory of rows",description:"Rows stacked with no gap share their keylines, so the list reads as one ruled block.",code:`<Stack gap="none">
|
|
224
|
+
{people.map((person) => (
|
|
225
|
+
<EntityRow
|
|
226
|
+
key={person.id}
|
|
227
|
+
title={person.name}
|
|
228
|
+
href={person.href}
|
|
229
|
+
tags={person.roles.map((role) => ({ label: role }))}
|
|
230
|
+
meta={[{ term: "Last sign-in", detail: person.lastSignIn }]}
|
|
231
|
+
/>
|
|
232
|
+
))}
|
|
233
|
+
</Stack>`},{title:"With a description",description:"A sentence under the row, for a record that needs one.",code:`<EntityRow
|
|
234
|
+
title="Payments service"
|
|
235
|
+
href="#/projects/payments"
|
|
236
|
+
tags={[{ label: "degraded", tone: "danger" }]}
|
|
237
|
+
meta={["Updated 4 min ago"]}
|
|
238
|
+
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"]}),dn=" · ";function At(e){return typeof e=="string"?e:e.term===void 0?e.detail:`${e.term}: ${e.detail}`}function Yo(e,t){return`${t}-${At(e)}`}function Qo(e){const{title:t,href:n,onSelect:o,tags:i=[],meta:s=[],description:d,disabled:l=!1,agentTool:c,agentName:h,ref:m,...p}=e,b=z(),g=ae(),C=ne(),f=r.useId(),w=n!==void 0,v=!w&&o!==void 0,k=v&&l,R=r.useRef(null),x=r.useCallback(B=>{R.current=B,typeof m=="function"?m(B):m!=null&&(m.current=B)},[m]),A=r.useRef(C);A.current=C;const P=r.useRef($({component:St.name})),N=r.useRef(!0);r.useEffect(()=>(N.current=!0,()=>{N.current=!1}),[]);const T=r.useCallback(async()=>{const B=R.current;return B===null?"This row renders no control in the current view.":(B.click(),await oe(),N.current?`Opened. The row is now:
|
|
240
|
+
${A.current([P.current])}`:"Opening removed this row from the page.")},[]),_=te({spec:Xt,label:h??t,enabled:(c??v)&&(w||v)&&!k,execute:T}),M=s.length===0?void 0:s.map(At).join(dn),X=[{part:"title",label:t,state:{}},...M===void 0?[]:[{part:"meta",label:M,state:{}}],...d===void 0?[]:[{part:"description",label:d,state:{}}]],I=$({component:St.name,label:t,tool:_,state:{href:n,disabled:k},parts:X});P.current=I;const q=i.map((B,J)=>a.jsx(ta,{tone:B.tone??"neutral",children:B.label},`${J}-${B.label}`));if(b==="agent")return!(w||v)||k||g==="never"?a.jsx(Y,{node:I,children:q}):a.jsx(Se,{node:I,as:w?"a":"button",href:n,ref:x,onClick:o,children:q});const F=`${f}-title`,G=`${f}-tags`,j=`${f}-meta`,Q=`${f}-description`,y=[i.length===0?void 0:G,M===void 0?void 0:j,d===void 0?void 0:Q].filter(B=>B!==void 0).join(" "),E={"aria-labelledby":F,"aria-describedby":y===""?void 0:y},W=a.jsxs(a.Fragment,{children:[a.jsx("span",{id:F,...D({part:"title",state:{}}),children:t}),i.length===0?null:a.jsx("span",{id:G,children:q}),M===void 0?null:a.jsx("span",{id:j,...D({part:"meta",state:{}}),children:s.map((B,J)=>a.jsxs(r.Fragment,{children:[J>0?dn:null,typeof B=="string"||B.term===void 0?a.jsx("span",{children:At(B)}):a.jsxs("span",{children:[a.jsxs("span",{children:[B.term,": "]}),a.jsx("span",{children:B.detail})]})]},Yo(B,J)))}),d===void 0?null:a.jsx("span",{id:Q,...D({part:"description",state:{}}),children:d})]});return w?a.jsx("a",{...p,...V(I),...E,href:n,onClick:o,ref:x,children:W}):v?a.jsx("button",{...p,...V(I),...E,type:"button",disabled:l,onClick:o,ref:x,children:W}):a.jsx("div",{...p,...V(I),...E,role:"group",ref:x,children:W})}const na=K({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.",values:["1","2","3","4"],default:"2"}},state:{level:{description:"The outline depth, and so the type voice in use.",attribute:"data-sprint-level",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>"}]});function Jo(e){const{level:t=2,children:n,...o}=e,i=z(),s=$({component:na.name,label:se(n),state:{level:String(t)}});if(i==="agent")return a.jsx(Y,{node:s});const d=`h${t}`;return a.jsx(d,{...o,...V(s),children:n})}const aa=K({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
|
|
71
241
|
src="media/pad-39b.svg"
|
|
72
242
|
alt="Launch pad 39B under floodlights, gantry retracted"
|
|
73
243
|
ratio="16:9"
|
|
@@ -77,9 +247,7 @@ ${A.current([R.current])}`:"The change removed this checkbox from the page."},[]
|
|
|
77
247
|
caption="Static fire 04, chamber pressure"
|
|
78
248
|
ratio="3:2"
|
|
79
249
|
fit="contain"
|
|
80
|
-
/>`},{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
|
|
81
|
-
Chrome docs
|
|
82
|
-
</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 aa(e){const{href:t,active:n=!1,external:a=!1,agentTool:i=!1,agentName:r,children:c,ref:s,onClick:h,...d}=e,f=I(),g=X(),m=l.useRef(null),u=l.useCallback(A=>{m.current=A,typeof s=="function"?s(A):s!=null&&(s.current=A)},[s]),C=r??K(c),b=l.useCallback(()=>{const A=m.current;return A===null?"This link renders no element in the current view. Navigate to its href instead.":(A.click(),`Following ${A.getAttribute("href")??t}.`)},[t]),v=G({spec:tt,label:C,enabled:i,execute:b}),k=E({component:Xt.name,label:K(c),tool:v,state:{href:t,active:n,external:a}}),x=a?{target:"_blank",rel:"noreferrer noopener"}:{target:void 0,rel:void 0};return f==="agent"?g==="never"?o.jsx(_,{node:k}):o.jsx(le,{node:k,as:"a",href:t,ref:u,onClick:h,target:x.target,rel:x.rel}):o.jsx("a",{...d,...D(k),href:t,ref:u,onClick:h,"aria-current":n?"page":void 0,target:x.target,rel:x.rel,children:c})}const Yt=$({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 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},emptyLabel:{kind:"string",description:"What the list says when it has no items.",default:"Empty"}},state:{items:{description:"How many items the list has.",attribute:"data-sprint-items"},ordered:{description:"Present when the items are numbered rather than bulleted.",attribute:"data-sprint-ordered"},empty:{description:"Present when the list has no items.",attribute:"data-sprint-empty"},index:{description:"On an item: its 1-based position in the list.",attribute:"data-sprint-index"}},agentView:{example:'- **List** "Tool rules" [items=1]\n - part `item` "One tool, one action." [index=1]'},examples:[{title:"A list of rules",code:`<List
|
|
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 Zo(e){const{src:t,alt:n,caption:o,ratio:i="auto",fit:s="cover",...d}=e,l=z(),[c,h]=r.useState("loading"),m=n===""&&o===void 0,p=o===void 0?[]:[{part:"caption",label:o,state:{}}],b=$({component:aa.name,label:n===""?void 0:n,state:{src:t,ratio:i,fit:s,decorative:m,status:l==="agent"?void 0:c},parts:p});if(l==="agent")return m?null:a.jsx(Y,{node:b});const g=c==="error"?n===""?"Image unavailable":n:"Loading";return a.jsxs("figure",{...d,...V(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:g})})]}),o===void 0?null:a.jsx("figcaption",{...D({part:"caption",state:{}}),children:o})]})}const oa=K({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
|
|
83
251
|
label="Tool rules"
|
|
84
252
|
items={[
|
|
85
253
|
<>
|
|
@@ -91,7 +259,15 @@ ${A.current([R.current])}`:"The change removed this checkbox from the page."},[]
|
|
|
91
259
|
ordered
|
|
92
260
|
label="Steps"
|
|
93
261
|
items={["Register the tool.", "Drive the DOM.", "Return the new state."]}
|
|
94
|
-
/>`}
|
|
262
|
+
/>`},{title:"Plain bullets",description:"A quieter dot for running prose, where the house plus would shout.",code:`<List
|
|
263
|
+
marker="bullet"
|
|
264
|
+
label="Caveats"
|
|
265
|
+
items={["Chrome 149 only.", "Tools are a no-op without WebMCP."]}
|
|
266
|
+
/>`},{title:"No marker",description:"For items that already lead with their own mark, such as a link or a chip.",code:`<List
|
|
267
|
+
marker="none"
|
|
268
|
+
label="Related"
|
|
269
|
+
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 ei(e){const{label:t,items:n,ordered:o=!1,marker:i,emptyLabel:s="Empty",loading:d=!1,loadingLabel:l="Loading",...c}=e,h=z(),m=i??(o?"number":"plus"),p=o||m==="number",b=n.length===0,g=n.map((w,v)=>{const k=se(w);return{part:"item",state:{index:String(v+1)},...k===void 0?{}:{label:k}}}),C=$({component:oa.name,label:t,state:{items:String(n.length),ordered:p,marker:m,empty:b,loading:d},parts:g});if(h==="agent")return a.jsx(Y,{node:C});const f=p?"ol":"ul";return a.jsx(f,{...c,...V(C),role:"list","aria-label":t,"aria-busy":d||void 0,children:b?a.jsx("li",{children:d?l:s}):n.map((w,v)=>a.jsx("li",{...D({part:"item",state:{index:String(v+1)}}),children:a.jsx("span",{children:w})},`${v}-${String(se(w))}`))})}const ia=K({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
|
|
95
271
|
entries={[
|
|
96
272
|
{ term: "Serial", detail: "NU-TYPE-CORE-A1" },
|
|
97
273
|
{ term: "Issued", detail: "2744.07.22" },
|
|
@@ -102,7 +278,15 @@ ${A.current([R.current])}`:"The change removed this checkbox from the page."},[]
|
|
|
102
278
|
{ term: "Channel", detail: "dev" },
|
|
103
279
|
{ term: "WebMCP", detail: "chrome 149" },
|
|
104
280
|
]}
|
|
105
|
-
/>`}
|
|
281
|
+
/>`},{title:"Wrapping in a narrow rail",description:"With wrap, a sidebar shows every entry on as many lines as it needs instead of cutting the later ones off.",code:`<MetaLine
|
|
282
|
+
wrap
|
|
283
|
+
entries={[
|
|
284
|
+
{ term: "Sprint", detail: "v0.0.0" },
|
|
285
|
+
{ term: "Channel", detail: "dev" },
|
|
286
|
+
{ term: "WebMCP", detail: "chrome 149" },
|
|
287
|
+
{ term: "Build", detail: "2744.07.22-a1" },
|
|
288
|
+
]}
|
|
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 ti(e){const{entries:t,wrap:n=!1,...o}=e,i=z();if(t.length===0)return null;const s=t.map(l=>`${l.term}: ${l.detail}`).join(" / "),d=$({component:ia.name,label:s,state:{entries:String(t.length),wrap:n}});return i==="agent"?a.jsx(Y,{node:d}):a.jsx("p",{...o,...V(d),children:t.map((l,c)=>a.jsxs(r.Fragment,{children:[c>0?" ":null,a.jsxs("span",{children:[a.jsxs("span",{children:[l.term,": "]}),a.jsx("span",{children:l.detail}),c<t.length-1?a.jsx("span",{children:" /"}):null]})]},`${l.term}-${c}`))})}const ra=K({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">
|
|
106
290
|
<NavGroup label="Guides">
|
|
107
291
|
<Link href="#/guide/webmcp">WebMCP</Link>
|
|
108
292
|
</NavGroup>
|
|
@@ -113,24 +297,14 @@ ${A.current([R.current])}`:"The change removed this checkbox from the page."},[]
|
|
|
113
297
|
</Nav>`},{title:"A flat nav",description:"A short list of destinations needs no grouping.",code:`<Nav label="Site">
|
|
114
298
|
<Link href="#/">Home</Link>
|
|
115
299
|
<Link href="#/pricing">Pricing</Link>
|
|
116
|
-
</Nav>`}]});function
|
|
117
|
-
label="Workbench"
|
|
118
|
-
groups={[
|
|
119
|
-
{ label: "action", items: [{ href: "#/Button", label: "Button" }] },
|
|
120
|
-
{ label: "display", items: [{ href: "#/Table", label: "Table", active: true }] },
|
|
121
|
-
]}
|
|
122
|
-
/>`},{title:"Recording where a person has been",description:"The bar keeps a trail of the destinations chosen through it, reachable from the depth count at its head. onNavigate is how that outlives the component.",code:`<NavBar
|
|
123
|
-
label="Docs"
|
|
124
|
-
groups={[{ label: "guides", items: [{ href: "#/guide/webmcp", label: "WebMCP" }] }]}
|
|
125
|
-
onNavigate={(destination) => console.log(destination.href)}
|
|
126
|
-
/>`}]}),sa="[data-sprint-shown], button";function la(e){return e==="closed"?void 0:e}function pt(e,t){return e.toLowerCase().includes(t)}function ca(e){const{label:t,groups:n,emptyLabel:a="No match",trailEmptyLabel:i="Nothing visited yet",open:r,onOpenChange:c,onNavigate:s,ref:h,...d}=e,f=I(),[g,m]=l.useState(void 0),u=r===void 0?g:la(r),[C,b]=l.useState(""),[v,k]=l.useState(void 0),[x,A]=l.useState([]),R=l.useRef(null),P=l.useRef(null),M=l.useRef(null),j=l.useCallback(p=>{M.current=p,typeof h=="function"?h(p):h!=null&&(h.current=p)},[h]),w=l.useRef(c);w.current=c;const y=l.useCallback(p=>{m(p),w.current?.(p??"closed")},[]);l.useEffect(()=>{u!==void 0&&R.current?.focus()},[u]),l.useEffect(()=>{if(u===void 0)return;const p=q=>{const B=q.target;B instanceof Node&&M.current?.contains(B)===!0||(y(void 0),b(""))};return document.addEventListener("pointerdown",p),()=>document.removeEventListener("pointerdown",p)},[u,y]);const T=n.flatMap(p=>p.items.map(q=>({item:q,group:p.label}))),L=T.find(p=>p.item.active===!0),N=L===void 0?n[0]?.label??"":L.group,S=v??N,W=C.trim().toLowerCase(),F=W!=="",U=[];if(u==="trail")for(const p of T)x.includes(p.item.href)&&(F&&!pt(`${p.group} ${p.item.label}`,W)||U.push(p.item));else if(u==="leaf"||u==="group"&&F)for(const p of T)(F?pt(`${p.group} ${p.item.label}`,W):p.group===S)&&U.push(p.item);const H=u==="group"&&!F?n:[],ee=T.filter(p=>p.group===S).length,fe=F?T.length:u==="trail"?x.length:u==="group"?n.length:ee,Z=H.length>0?H.length:U.length,rt=T.map(p=>{const q={part:"destination",label:p.item.label,state:{group:p.group,href:p.item.href,...p.item.active===!0?{active:!0}:{},...p.item.external===!0?{external:!0}:{},...U.includes(p.item)?{shown:!0}:{}}};return{...p,part:q}}),st=E({component:Zt.name,label:t,region:!0,state:{destinations:String(T.length),depth:String(x.length),...u===void 0?{}:{open:u,matches:String(Z)}},parts:rt.map(p=>p.part)}),Ce=p=>{A(q=>[...q.filter(B=>B!==p.href),p.href]),y(void 0),b(""),s?.(p)};if(f==="agent")return o.jsx(se,{node:st,onActivate:(p,q)=>{const B=T[q];B!==void 0&&(Ce(B.item),window.location.assign(B.item.href))}});const lt=()=>{y(void 0),b("")},Ae=p=>{y(u===p?void 0:p),b("")},vn=p=>u!=="trail"?0:-p.reduce((B,V)=>Math.max(B,x.indexOf(V.item.href)),-1),ct=()=>{const p=P.current;return p===null?[]:Array.from(p.querySelectorAll(sa)).filter(q=>q.closest("[hidden]")===null)},Se=p=>{const q=ct();q[p<0?q.length-1:p%q.length]?.focus()},wn=p=>{if(p.key==="Escape"){lt();return}if(p.key==="ArrowDown"){p.preventDefault(),Se(0);return}if(p.key==="ArrowUp"&&u!=="trail"){p.preventDefault(),Ae("trail");return}if(p.key!=="Enter")return;p.preventDefault();const q=H[0];if(q!==void 0){k(q.label),b(""),y("leaf");return}const B=U[0];B!==void 0&&(Ce(B),window.location.assign(B.href))},yn=p=>{if(p.key==="Escape"){lt();return}const B=ct().indexOf(p.target);if(p.key==="ArrowDown"){p.preventDefault(),Se(B+1);return}if(p.key==="ArrowUp"){p.preventDefault(),B<=0?R.current?.focus():Se(B-1);return}p.key.length!==1||p.metaKey||p.ctrlKey||p.altKey||(p.preventDefault(),b(V=>`${V}${p.key}`),R.current?.focus())},dt=(p,q)=>u===p||p==="leaf"&&u==="trail"?o.jsx("input",{ref:R,type:"text","aria-label":`Search ${t}`,value:C,placeholder:u==="trail"?`Search ${x.length} visited`:`Search ${T.length} destinations`,onChange:B=>b(B.target.value),onKeyDown:wn}):o.jsx("button",{type:"button","aria-expanded":!1,onClick:()=>Ae(p),children:q}),kn=u==="trail"&&x.length===0?i:a,xn=u===void 0?`${T.length} destinations`:F?`${Z} of ${T.length} match`:`${Z} of ${fe}`;return o.jsxs("nav",{...d,...D(st),"aria-label":t,ref:j,children:[o.jsxs("p",{children:[o.jsx("button",{type:"button","aria-label":`Visited, ${x.length}`,"aria-expanded":u==="trail",onClick:()=>Ae("trail"),children:String(x.length).padStart(2,"0")}),o.jsx("span",{children:t}),dt("group",S),dt("leaf",L?.item.label??"—"),o.jsx("span",{"aria-live":"polite",children:xn})]}),o.jsxs("div",{ref:P,onKeyDown:yn,...u===void 0?{hidden:!0}:{},children:[o.jsxs("div",{...H.length===0?{hidden:!0}:{},children:[o.jsx("span",{children:t}),H.map(p=>o.jsx("button",{type:"button",onClick:()=>{k(p.label),b(""),y("leaf")},children:p.label},p.label))]}),n.map(p=>{const q=rt.filter(V=>V.group===p.label),B=q.some(V=>U.includes(V.item));return o.jsxs("div",{style:{"--sprint-navbar-order":vn(q)},...B?{}:{hidden:!0},children:[o.jsx("span",{children:`${t} / ${p.label}`}),q.map(V=>o.jsx("a",{...O(V.part),href:V.item.href,"aria-current":V.item.active===!0?"page":void 0,target:V.item.external===!0?"_blank":void 0,rel:V.item.external===!0?"noreferrer noopener":void 0,onClick:()=>Ce(V.item),children:V.item.label},V.item.href))]},p.label)}),Z===0?o.jsx("p",{children:kn}):null]})]})}const en=$({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">
|
|
300
|
+
</Nav>`}]});function ni(e){const{label:t,children:n,...o}=e,i=z(),s=$({component:ra.name,label:t,region:!0});return i==="agent"?a.jsx(Y,{node:s,children:n}):a.jsx("nav",{...o,...V(s),"aria-label":t,children:n})}const sa=K({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">
|
|
127
301
|
<Link href="https://developer.chrome.com/docs/ai/webmcp" external>
|
|
128
302
|
Chrome docs
|
|
129
303
|
</Link>
|
|
130
304
|
<Link href="https://github.com/webmachinelearning/webmcp" external>
|
|
131
305
|
Specification
|
|
132
306
|
</Link>
|
|
133
|
-
</NavGroup>`}]});function
|
|
307
|
+
</NavGroup>`}]});function ai(e){const{label:t,children:n,...o}=e,i=z(),s=$({component:sa.name,label:t});return i==="agent"?a.jsx(Y,{node:s,children:n}):a.jsxs("div",{...o,...V(s),role:"group","aria-label":t,children:[a.jsx("span",{children:t}),n]})}const la=K({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">
|
|
134
308
|
<Text>Everything the quarter produced, in one place.</Text>
|
|
135
309
|
</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
|
|
136
310
|
label="Button"
|
|
@@ -138,7 +312,35 @@ ${A.current([R.current])}`:"The change removed this checkbox from the page."},[]
|
|
|
138
312
|
actions={<Button agentTool={false}>Refresh</Button>}
|
|
139
313
|
>
|
|
140
314
|
<Text>A single action a person or an agent can trigger.</Text>
|
|
141
|
-
</PageHeader>`}]});function
|
|
315
|
+
</PageHeader>`}]});function oi(e){const{label:t,tags:n,actions:o,children:i,...s}=e,d=z(),l=$({component:la.name,label:t,region:!0});if(d==="agent")return a.jsxs(Y,{node:l,children:[n,o,i]});const c=r.Children.toArray(i).length>0;return a.jsxs("header",{...s,...V(l),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:i}):null]})}const Pe={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=K({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:Pe},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
|
+
label="Users pages"
|
|
317
|
+
page={page}
|
|
318
|
+
pageSize={25}
|
|
319
|
+
total={61}
|
|
320
|
+
onPageChange={setPage}
|
|
321
|
+
/>`},{title:"Pages as links",description:"With href every page is a URL. The controls are links, nothing registers, and each link publishes where it goes.",code:`<Pagination
|
|
322
|
+
label="Changelog pages"
|
|
323
|
+
page={2}
|
|
324
|
+
pageSize={10}
|
|
325
|
+
total={42}
|
|
326
|
+
href={(page) => \`#/changelog?page=\${page}\`}
|
|
327
|
+
/>`},{title:"The last page, relabelled",description:"On the last page Next is disabled and the summary shows the short final range. The labels are overridable for sets that read better as time.",code:`<Pagination
|
|
328
|
+
label="Activity pages"
|
|
329
|
+
page={4}
|
|
330
|
+
pageSize={8}
|
|
331
|
+
total={31}
|
|
332
|
+
previousLabel="Newer"
|
|
333
|
+
nextLabel="Older"
|
|
334
|
+
onPageChange={setPage}
|
|
335
|
+
/>`},{title:"An empty set",description:"No items is one empty page. Both controls are disabled, no tool registers, and the summary still says what it is showing.",code:`<Pagination
|
|
336
|
+
label="Search results pages"
|
|
337
|
+
page={1}
|
|
338
|
+
pageSize={20}
|
|
339
|
+
total={0}
|
|
340
|
+
onPageChange={setPage}
|
|
341
|
+
/>`}]});function pt(e,t){return Number.isFinite(e)?Math.floor(e):t}function ii(e,t,n){const o=Math.max(1,pt(t,1)),i=Math.max(0,pt(n,0)),s=Math.max(1,Math.ceil(i/o)),d=Math.min(s,Math.max(1,pt(e,1))),l=i===0?0:(d-1)*o+1,c=Math.min(i,d*o);return{page:d,pages:s,total:i,first:l,last:c}}function ri(e){return e.total===0?"Showing 0 of 0":`Showing ${e.first}–${e.last} of ${e.total}`}function si(e){const t=Pe.inputSchema.properties.page;return{...Pe.inputSchema,properties:{...Pe.inputSchema.properties,...t===void 0?{}:{page:{...t,maximum:e,description:`${t.description??""} This set has ${e} pages, so 1 to ${e}.`}}}}}function li(e){const{label:t,page:n,pageSize:o,total:i,onPageChange:s,href:d,previousLabel:l="Previous",nextLabel:c="Next",agentName:h,agentTool:m=!0,...p}=e,b=z(),g=ae(),C=ne(),f=ii(n,o,i),w=d!==void 0||s!==void 0,v={previous:w&&f.page>1?f.page-1:null,next:w&&f.page<f.pages?f.page+1:null},k=r.useRef(new Map),R=r.useRef(s);R.current=s;const x=r.useRef(f);x.current=f;const A=r.useRef(C);A.current=C;const P=r.useRef($({component:jt.name})),N=r.useRef(!0);r.useEffect(()=>(N.current=!0,()=>{N.current=!1}),[]);const T=r.useCallback(y=>{const E=x.current.page,W=y===E-1?"previous":y===E+1?"next":null,B=W===null?void 0:k.current.get(W);if(B!==void 0){B.click();return}const J=R.current;J!==void 0&&ie(()=>J(y))},[]),_=r.useCallback(async y=>{const E=y.page,{page:W,pages:B}=x.current;return typeof E!="number"||!Number.isInteger(E)?`Parameter "page" must be a whole page number from 1 to ${B}.`:E<1||E>B?`There is no page ${E}. This set has pages 1 to ${B}.`:E===W?`Already on page ${W}. The pagination is:
|
|
342
|
+
${A.current([P.current])}`:(T(E),await oe(),N.current?`Turned. The pagination is now:
|
|
343
|
+
${A.current([P.current])}`:"Turning the page removed this pagination from the page.")},[T]),M=r.useMemo(()=>si(f.pages),[f.pages]),X=te({spec:Pe,label:h??t,inputSchema:M,enabled:m&&d===void 0&&s!==void 0&&f.pages>1,execute:_}),I=y=>{const E=v[y];return{part:y,label:y==="previous"?l:c,state:E===null?{disabled:!0}:d===void 0?{}:{href:d(E)}}},q=[I("previous"),I("next")],F=$({component:jt.name,label:t,tool:X,state:{page:String(f.page),pages:String(f.pages),total:String(f.total),first:String(f.first),last:String(f.last)},parts:q});P.current=F;const G=v.previous!==null||v.next!==null;if(b==="agent")return!G||g==="never"?a.jsx(Y,{node:F}):a.jsx(ce,{node:F,isActionable:y=>y.state.disabled!==!0,onActivate:y=>{const E=v[y.part];E!=null&&(d===void 0?T(E):window.location.assign(d(E)))}});const j=y=>E=>{E===null?k.current.delete(y):k.current.set(y,E)},Q=(y,E)=>{const W=v[y],B=D(E),J=E.label;return d!==void 0?W===null?a.jsx("a",{...B,"aria-disabled":"true",children:J}):a.jsx("a",{...B,href:d(W),rel:y==="previous"?"prev":"next",ref:j(y),onClick:()=>s?.(W),children:J}):a.jsx("button",{...B,type:"button",disabled:W===null,ref:j(y),onClick:()=>{W!==null&&s?.(W)},children:J})};return a.jsxs("nav",{...p,...V(F),"aria-label":t,children:[a.jsx("p",{"aria-live":"polite",children:ri(f)}),a.jsxs("div",{children:[Q("previous",q[0]??I("previous")),a.jsxs("span",{children:["Page ",f.page," of ",f.pages]}),Q("next",q[1]??I("next"))]})]})}const da=K({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}>
|
|
142
344
|
<Text>Use it for any discrete action.</Text>
|
|
143
345
|
</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
|
|
144
346
|
label="Preview"
|
|
@@ -153,11 +355,37 @@ ${A.current([R.current])}`:"The change removed this checkbox from the page."},[]
|
|
|
153
355
|
<Text>Registration fields live here.</Text>
|
|
154
356
|
</Panel>
|
|
155
357
|
</Panel>
|
|
156
|
-
</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
|
|
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 di(e){const{label:t,headingLevel:n,actions:o,flush:i=!1,emptyLabel:s="Empty",loading:d=!1,loadingLabel:l="Loading",children:c,...h}=e,m=z(),p=r.Children.toArray(c).length===0,b=$({component:da.name,label:t,region:!0,state:{flush:i,empty:p,loading:d}});if(m==="agent")return a.jsxs(Y,{node:b,children:[o,c]});const g=n===void 0?"span":`h${n}`;return a.jsxs("section",{...h,...V(b),"aria-label":t,"aria-busy":d||void 0,children:[a.jsxs("header",{children:[a.jsx(g,{children:t}),o===void 0?null:a.jsx("span",{children:o})]}),a.jsx("div",{children:p?a.jsx("span",{children:d?l:s}):c})]})}const ca=K({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
|
+
{profile && <ProfileSummary profile={profile} />}
|
|
360
|
+
</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
|
+
<Stack gap="tight">
|
|
362
|
+
<Heading level={3}>{pilot.callsign}</Heading>
|
|
363
|
+
<Text tone="muted">{pilot.status}</Text>
|
|
364
|
+
</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 ci(e){const{loading:t,label:n,children:o,...i}=e,s=z(),d=r.Children.toArray(o).length===0,l=$({component:ca.name,label:n,state:{loading:!0,empty:d}});if(s==="agent")return a.jsx(Y,{node:l,silent:!t,children:o});const c=t?{...V(l),role:"group","aria-label":n,"aria-busy":!0}:{};return a.jsxs("div",{...i,...c,children:[t&&d?a.jsx("span",{children:n}):null,o]})}const ha=K({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}},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"}},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} />'}],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 hi(e,t){return t<=0?100:Math.round(Math.min(Math.max(e,0),t)/t*100)}function ui(e){const{label:t,value:n,max:o=100,...i}=e,s=z(),d=r.useId(),c=n!==void 0&&Number.isFinite(n)?hi(n,o):void 0,h=$({component:ha.name,label:t,state:{loading:c===void 0||c<100,value:c===void 0?void 0:`${c}%`}});return s==="agent"?a.jsx(Y,{node:h}):a.jsxs("div",{...i,...V(h),children:[a.jsx("span",{id:d,children:t}),c===void 0?null:a.jsxs("span",{"aria-hidden":"true",children:[c,"%"]}),a.jsx("progress",{"aria-labelledby":d,...c===void 0?{}:{value:c,max:100}})]})}const Yt={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."},Rt=K({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:Yt},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
|
+
label="Users"
|
|
367
|
+
hideLabel
|
|
368
|
+
value={query}
|
|
369
|
+
onChange={setQuery}
|
|
370
|
+
placeholder="Name or email"
|
|
371
|
+
/>`},{title:"A slash shortcut",description:"Pressing / anywhere on the page focuses the field unless focus is already in something editable. The key chip disappears once the field has focus or a query.",code:`<SearchField
|
|
372
|
+
label="Users"
|
|
373
|
+
value={query}
|
|
374
|
+
onChange={setQuery}
|
|
375
|
+
shortcut="/"
|
|
376
|
+
placeholder="Name or email"
|
|
377
|
+
/>`},{title:"Submitting a query",description:"For a search that is too costly to run on every keystroke, onSubmit receives the query on Enter and when the search tool runs.",code:`<SearchField
|
|
378
|
+
label="Flight logs"
|
|
379
|
+
value={query}
|
|
380
|
+
onChange={setQuery}
|
|
381
|
+
onSubmit={runSearch}
|
|
382
|
+
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 Qt(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 pi='input, textarea, select, [contenteditable]:not([contenteditable="false"])';function cn(e){return e instanceof Element&&e.closest(pi)!==null}function gi(e,t){r.useEffect(()=>{if(e===void 0)return;const n=o=>{if(o.key!==e||o.defaultPrevented||o.ctrlKey||o.metaKey||o.altKey||cn(o.target)||cn(document.activeElement))return;const i=t.current;i!==null&&(o.preventDefault(),i.focus())};return document.addEventListener("keydown",n),()=>document.removeEventListener("keydown",n)},[e,t])}function mi(e){const{label:t,value:n,onChange:o,onSubmit:i,placeholder:s,hideLabel:d=!1,shortcut:l,name:c,disabled:h=!1,agentName:m,agentTool:p=!0,...b}=e,g=z(),C=ae(),f=ne(),w=r.useId(),v=r.useRef(null),k=r.useRef(o);k.current=o;const R=r.useRef(i);R.current=i;const x=r.useRef(f);x.current=f;const A=r.useRef($({component:Rt.name})),P=r.useRef(!0);r.useEffect(()=>(P.current=!0,()=>{P.current=!1}),[]);const N=l===void 0||l===!1||l===""||h?void 0:l;gi(N,v);const T=r.useCallback(async G=>{const j=G.query;if(typeof j!="string")return'Pass "query" as a string holding the full search text.';const Q=v.current;Q!==null?Qt(Q,j):ie(()=>k.current(j));const y=R.current;return y!==void 0&&ie(()=>y(j)),await oe(),P.current?`${y===void 0?"Filtered":"Searched"}. The field is now:
|
|
384
|
+
${x.current([A.current])}`:"The search removed this field from the page."},[]),_=te({spec:Yt,label:m??t,enabled:p&&!h,execute:T}),M=n==="",X=$({component:Rt.name,label:t,tool:_,state:{...M?{}:{value:n},empty:M,shortcut:N,disabled:h}});if(A.current=X,g==="agent")return h||C==="never"?a.jsx(Y,{node:X}):a.jsx(_t,{node:X,value:n,onValueChange:o,ref:G=>{v.current=G}});const I=`${w}-label`,q=()=>{o(""),v.current?.focus()},F=G=>{G.key!=="Escape"||M||(G.preventDefault(),G.stopPropagation(),o(""))};return a.jsxs("form",{...b,...V(X),role:"search","aria-labelledby":I,noValidate:!0,onSubmit:G=>{G.preventDefault(),h||i?.(n)},children:[a.jsx("label",{id:I,htmlFor:w,...D({part:"label",state:d?{"visually-hidden":!0}:{}}),children:t}),a.jsxs("div",{...D({part:"control",state:{}}),children:[a.jsx("input",{id:w,...D({part:"input",state:{}}),ref:G=>{v.current=G},type:"search",value:n,placeholder:s,name:c,disabled:h,autoComplete:"off","aria-keyshortcuts":N,enterKeyHint:"search",onChange:G=>o(G.currentTarget.value),onKeyDown:F}),M||h?null:a.jsx("button",{...D({part:"clear",state:{}}),type:"button","aria-label":`Clear ${t} search`,onClick:q,children:"Clear"}),N===void 0||!M?null:a.jsx("span",{...D({part:"shortcut",state:{}}),"aria-hidden":"true",children:a.jsx("kbd",{children:N})})]})]})}const ua=K({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
|
|
157
385
|
label="API key"
|
|
158
386
|
value={key}
|
|
159
387
|
hint="Store it now. It is not shown again."
|
|
160
|
-
/>`},{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."}}),
|
|
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."}}),fi="••••••••••••",bi=1200;function wi(e){const{label:t,value:n,hint:o,defaultRevealed:i=!1,...s}=e,d=z(),[l,c]=r.useState(i),[h,m]=r.useState(!1);r.useEffect(()=>{if(!h)return;const f=setTimeout(()=>m(!1),bi);return()=>clearTimeout(f)},[h]);const p=()=>{const f=navigator.clipboard;f!==void 0&&f.writeText(n).then(()=>m(!0),()=>m(!1))},b=n!=="",g=o===void 0?[]:[{part:"hint",label:o,state:{}}],C=$({component:ua.name,label:t,state:{filled:b,revealed:l},parts:g});return d==="agent"?a.jsx(Y,{node:C}):a.jsxs("div",{...s,...V(C),children:[a.jsx("span",{...D({part:"label",state:{}}),children:t}),a.jsxs("div",{...D({part:"control",state:{}}),children:[a.jsx("output",{...D({part:"value",state:{}}),"aria-label":l?void 0:"Hidden secret",children:l?n:fi}),a.jsx("button",{...D({part:"reveal",state:{}}),type:"button","aria-pressed":l,onClick:()=>c(f=>!f),children:l?"Hide":"Reveal"}),a.jsx("button",{...D({part:"copy",state:h?{copied:!0}:{}}),type:"button",onClick:p,children:h?"Copied":"Copy"})]}),o===void 0?null:a.jsx("p",{...D({part:"hint",state:{}}),children:o})]})}const Ee={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."},Lt=K({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? }. 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 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:Ee},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
|
|
161
389
|
label="Page view"
|
|
162
390
|
value={view}
|
|
163
391
|
onChange={setView}
|
|
@@ -165,6 +393,36 @@ ${A.current([R.current])}`:"The change removed this checkbox from the page."},[]
|
|
|
165
393
|
{ value: "human", label: "human" },
|
|
166
394
|
{ value: "agent", label: "agent" },
|
|
167
395
|
]}
|
|
396
|
+
/>`},{title:"Options with counts",description:"A count is data, not label text: it renders as a chip, joins the accessible name, and reaches agents as part state while the select tool still takes the plain label.",code:`<SegmentedControl
|
|
397
|
+
label="Members"
|
|
398
|
+
value={filter}
|
|
399
|
+
onChange={setFilter}
|
|
400
|
+
options={[
|
|
401
|
+
{ value: "all", label: "All", count: 48 },
|
|
402
|
+
{ value: "active", label: "Active", count: 18 },
|
|
403
|
+
{ value: "never", label: "Never signed in", count: 30 },
|
|
404
|
+
]}
|
|
405
|
+
/>`},{title:"A staged change",description:"savedValue keeps the value in effect visible while another is selected, and hint says what confirming will do. The control reports itself dirty until the two agree.",code:`<SegmentedControl
|
|
406
|
+
label="Access"
|
|
407
|
+
value={access}
|
|
408
|
+
savedValue="read"
|
|
409
|
+
onChange={setAccess}
|
|
410
|
+
hint="Currently Read. Nothing changes until you confirm."
|
|
411
|
+
options={[
|
|
412
|
+
{ value: "read", label: "Read" },
|
|
413
|
+
{ value: "write", label: "Write" },
|
|
414
|
+
{ value: "admin", label: "Admin" },
|
|
415
|
+
]}
|
|
416
|
+
/>`},{title:"A full-width control",description:"block fills the container and shares the width equally between options. Without it the control keeps its own width inside a stretching Stack.",code:`<SegmentedControl
|
|
417
|
+
label="Range"
|
|
418
|
+
block
|
|
419
|
+
value={range}
|
|
420
|
+
onChange={setRange}
|
|
421
|
+
options={[
|
|
422
|
+
{ value: "day", label: "Day" },
|
|
423
|
+
{ value: "week", label: "Week" },
|
|
424
|
+
{ value: "month", label: "Month" },
|
|
425
|
+
]}
|
|
168
426
|
/>`},{title:"A disabled control",description:"Disabled unregisters the tool, so an agent cannot select an option a person could not.",code:`<SegmentedControl
|
|
169
427
|
label="Density"
|
|
170
428
|
disabled
|
|
@@ -174,8 +432,8 @@ ${A.current([R.current])}`:"The change removed this checkbox from the page."},[]
|
|
|
174
432
|
{ value: "dense", label: "dense" },
|
|
175
433
|
{ value: "roomy", label: "roomy" },
|
|
176
434
|
]}
|
|
177
|
-
/>`}],a11y:{role:"radiogroup",keyboard:["Arrow keys move to the next or previous option and select it","Home selects the first option","End selects the last 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."}});function
|
|
178
|
-
${
|
|
435
|
+
/>`}],a11y:{role:"radiogroup",keyboard:["Arrow keys move to the next or previous option and select it","Home selects the first option","End selects the last 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 vi(e){const t=Ee.inputSchema.properties.option;return{...Ee.inputSchema,properties:{...Ee.inputSchema.properties,...t===void 0?{}:{option:{...t,enum:e.map(n=>n.label)}}}}}function yi(e){const{label:t,options:n,value:o,onChange:i,savedValue:s,hint:d,block:l=!1,disabled:c=!1,agentName:h,agentTool:m=!0,...p}=e,b=z(),g=ae(),C=ne(),f=r.useId(),w=r.useRef(new Map),v=r.useRef(i);v.current=i;const k=r.useRef(n);k.current=n;const R=r.useRef(C);R.current=C;const x=r.useRef($({component:Lt.name})),A=r.useRef(!0);r.useEffect(()=>(A.current=!0,()=>{A.current=!1}),[]);const P=r.useCallback(j=>{const Q=w.current.get(j);if(Q!==void 0){Q.click();return}ie(()=>v.current(j))},[]),N=r.useCallback(async j=>{const Q=typeof j.option=="string"?j.option:"",y=k.current,E=y.find(W=>W.label===Q);return E===void 0?`No option named "${Q}". This control offers: ${y.map(W=>`"${W.label}"`).join(", ")}.`:(P(E.value),await oe(),A.current?`Selected. The control is now:
|
|
436
|
+
${R.current([x.current])}`:"The selection removed this control from the page.")},[P]),T=r.useMemo(()=>vi(n),[n]),_=te({spec:Ee,label:h??t,inputSchema:T,enabled:m&&!c,execute:N}),M=s!==void 0&&s!==o&&n.some(j=>j.value===s),X=n.map(j=>({part:"option",label:j.label,state:{...j.value===o?{checked:!0}:{},...j.value===s?{saved:!0}:{},...j.count===void 0?{}:{count:String(j.count)},...c?{disabled:!0}:{}}})),I=d===void 0?[]:[{part:"hint",label:d,state:{}}],q=$({component:Lt.name,label:t,tool:_,state:{value:o,dirty:M,block:l,disabled:c},parts:[...X,...I]});x.current=q;const F=j=>{if(!["ArrowRight","ArrowDown","ArrowLeft","ArrowUp","Home","End"].includes(j.key)||c)return;const y=n.findIndex(J=>J.value===o),E=j.key==="ArrowRight"||j.key==="ArrowDown"?1:-1,W=j.key==="Home"?0:j.key==="End"?n.length-1:(y+E+n.length)%n.length,B=n[W];B!==void 0&&(j.preventDefault(),w.current.get(B.value)?.focus(),P(B.value))};if(b==="agent")return c||g==="never"?a.jsx(Y,{node:q}):a.jsx(ce,{node:q,isActionable:j=>j.part==="option",onActivate:(j,Q)=>{const y=n[Q];y!==void 0&&P(y.value)}});const G=d===void 0?void 0:`${f}-hint`;return a.jsxs("div",{...p,...V(q),role:"radiogroup","aria-label":t,"aria-describedby":G,onKeyDown:F,children:[a.jsx("div",{children:n.map((j,Q)=>{const y=j.value===o,E=n.some(J=>J.value===o)?y:Q===0,W=`${f}-${Q}-label`,B=`${f}-${Q}-count`;return a.jsx("button",{type:"button",role:"radio","aria-checked":y,"aria-labelledby":j.count===void 0?void 0:`${W} ${B}`,tabIndex:E?0:-1,disabled:c,ref:J=>{J===null?w.current.delete(j.value):w.current.set(j.value,J)},...D(X[Q]??{part:"option",state:{}}),onClick:()=>i(j.value),children:j.count===void 0?j.label:a.jsxs(a.Fragment,{children:[a.jsx("span",{id:W,children:j.label}),a.jsx("span",{id:B,"aria-hidden":"true",children:j.count})]})},j.value)})}),d===void 0?null:a.jsx("p",{id:G,...D({part:"hint",state:{}}),children:d})]})}const Oe={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."},Pt=K({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 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:Oe},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
|
|
179
437
|
label="Region"
|
|
180
438
|
value={region}
|
|
181
439
|
onChange={setRegion}
|
|
@@ -185,6 +443,16 @@ ${b.current([v.current])}`:"The selection removed this control from the page.")}
|
|
|
185
443
|
{ value: "eu-1", label: "Northern Europe" },
|
|
186
444
|
{ value: "ap-1", label: "East Asia" },
|
|
187
445
|
]}
|
|
446
|
+
/>`},{title:"Options with counts",description:"A count is data, not label text: it renders as a chip in the list and the closed control, joins the accessible name, and reaches agents as part state while the select tool still takes the plain label.",code:`<Select
|
|
447
|
+
label="Region"
|
|
448
|
+
value={region}
|
|
449
|
+
onChange={setRegion}
|
|
450
|
+
placeholder="Choose a region"
|
|
451
|
+
options={[
|
|
452
|
+
{ value: "na-1", label: "North Atlantic", count: 12 },
|
|
453
|
+
{ value: "eu-1", label: "Northern Europe", count: 30 },
|
|
454
|
+
{ value: "ap-1", label: "East Asia", count: 7 },
|
|
455
|
+
]}
|
|
188
456
|
/>`},{title:"A required choice with an error",description:"Empty plus required plus an error is how an unmade mandatory choice reads on every surface.",code:`<Select
|
|
189
457
|
label="Launch site"
|
|
190
458
|
value={site}
|
|
@@ -204,8 +472,8 @@ ${b.current([v.current])}`:"The selection removed this control from the page.")}
|
|
|
204
472
|
{ value: "r-1", label: "Relay one" },
|
|
205
473
|
{ value: "r-2", label: "Relay two" },
|
|
206
474
|
]}
|
|
207
|
-
/>`}],a11y:{role:"combobox",keyboard:["Arrow keys move through the options","Enter or Space
|
|
208
|
-
${
|
|
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."}}),ki="--sprint-select-top",xi="--sprint-select-left",Ti="--sprint-select-width";function Ci(e){const t=Oe.inputSchema.properties.option;return{...Oe.inputSchema,properties:{...Oe.inputSchema.properties,...t===void 0?{}:{option:{...t,enum:e.map(n=>n.label)}}}}}function Si(e,t){return e!==void 0?[{part:"error",label:e,state:{}}]:t!==void 0?[{part:"hint",label:t,state:{}}]:[]}function hn(e,t){const n=t.getBoundingClientRect();e.style.setProperty(ki,`${n.bottom}px`),e.style.setProperty(xi,`${n.left}px`),e.style.setProperty(Ti,`${n.width}px`)}function pa(e){return typeof e.showPopover=="function"}function Ai(e){pa(e)&&(e.matches(":popover-open")||e.showPopover())}function ji(e){pa(e)&&e.matches(":popover-open")&&e.hidePopover()}function Ri(e){const{label:t,options:n,value:o,onChange:i,placeholder:s,hint:d,error:l,name:c,disabled:h=!1,required:m=!1,agentName:p,agentTool:b=!0,...g}=e,C=z(),f=ae(),w=ne(),v=r.useId(),[k,R]=r.useState(!1),[x,A]=r.useState(-1),P=r.useRef(null),N=r.useRef(null),T=r.useRef(null),_=r.useRef(new Map),M=r.useRef(i);M.current=i;const X=r.useRef(n);X.current=n;const I=r.useRef(w);I.current=w;const q=r.useRef($({component:Pt.name})),F=r.useRef(!0);r.useEffect(()=>(F.current=!0,()=>{F.current=!1}),[]);const G=n.findIndex(S=>S.value===o),j=n[G],Q=r.useCallback(S=>{h||(A(S??Math.max(G,0)),R(!0))},[h,G]),y=r.useCallback(()=>{R(!1),A(-1)},[]);r.useEffect(()=>{h&&y()},[h,y]),r.useLayoutEffect(()=>{const S=T.current,L=N.current;if(S===null||L===null)return;if(!k){ji(S);return}hn(S,L),Ai(S);const H=()=>hn(S,L),Z=re=>{const be=re.target;be instanceof Node&&P.current?.contains(be)||y()};return window.addEventListener("resize",H),window.addEventListener("scroll",H,!0),document.addEventListener("pointerdown",Z,!0),()=>{window.removeEventListener("resize",H),window.removeEventListener("scroll",H,!0),document.removeEventListener("pointerdown",Z,!0)}},[k,y]),r.useEffect(()=>{if(!k||x<0)return;const S=n[x],L=S===void 0?void 0:_.current.get(S.value);L!==void 0&&typeof L.scrollIntoView=="function"&&L.scrollIntoView({block:"nearest"})},[k,x,n]);const E=r.useCallback(S=>{y(),i(S)},[y,i]),W=r.useCallback(S=>{const L=_.current.get(S);if(L!==void 0){L.click();return}ie(()=>M.current(S))},[]),B=r.useCallback(async S=>{const L=typeof S.option=="string"?S.option:"",H=X.current,Z=H.find(re=>re.label===L);return Z===void 0?`No option named "${L}". This dropdown offers: ${H.map(re=>`"${re.label}"`).join(", ")}.`:(W(Z.value),await oe(),F.current?`Selected. The dropdown is now:
|
|
476
|
+
${I.current([q.current])}`:"The selection removed this dropdown from the page.")},[W]),J=r.useMemo(()=>Ci(n),[n]),le=te({spec:Oe,label:p??t,inputSchema:J,enabled:b&&!h,execute:B}),he=n.map((S,L)=>({part:"option",label:S.label,state:{...S.value===o?{checked:!0}:{},...k&&L===x?{active:!0}:{},...S.count===void 0?{}:{count:String(S.count)},...h?{disabled:!0}:{}}})),de=$({component:Pt.name,label:t,tool:le,state:{...j===void 0?{}:{value:o},empty:j===void 0,disabled:h,required:m,invalid:l!==void 0},parts:[...he,...Si(l,d)]});if(q.current=de,C==="agent")return h||f==="never"?a.jsx(Y,{node:de}):a.jsx(ce,{node:de,isActionable:S=>S.part==="option",onActivate:(S,L)=>{const H=n[L];H!==void 0&&W(H.value)}});const ue=`${v}-label`,Ae=`${v}-listbox`,pe=S=>`${v}-option-${S}`,je=l!==void 0?`${v}-error`:d!==void 0?`${v}-hint`:void 0,ge=S=>{const L=x<0?G:x,H=S.toLowerCase();for(let Z=1;Z<=n.length;Z+=1){const re=(L+Z+n.length)%n.length;if(n[re]?.label.toLowerCase().startsWith(H))return re}return-1},Fe=S=>{const L=n.length-1,H=S.key;if(!k){if(H==="ArrowDown"||H==="ArrowUp"||H==="Enter"||H===" "){S.preventDefault(),Q();return}if(H==="Home"||H==="End"){S.preventDefault(),Q(H==="Home"?0:L);return}if(H.length===1&&!S.altKey&&!S.ctrlKey&&!S.metaKey){const Z=ge(H);Z>=0&&Q(Z)}return}if(H==="Escape"||H==="Tab"){H==="Escape"&&S.preventDefault(),y();return}if(H==="Enter"||H===" "){S.preventDefault();const Z=n[x];Z!==void 0?E(Z.value):y();return}if(H==="ArrowDown"||H==="ArrowUp"||H==="Home"||H==="End"){S.preventDefault();const Z=H==="Home"?0:H==="End"?L:H==="ArrowDown"?Math.min(x+1,L):Math.max(x-1,0);A(Z);return}if(H.length===1&&!S.altKey&&!S.ctrlKey&&!S.metaKey){const Z=ge(H);Z>=0&&A(Z)}},at=S=>{S.key===" "&&S.preventDefault()},me=S=>{const L=S.relatedTarget;L instanceof Node&&P.current?.contains(L)||y()};return a.jsxs("div",{...g,...V(de),ref:S=>{P.current=S;const L=g.ref;typeof L=="function"?L(S):L!=null&&(L.current=S)},children:[a.jsx("label",{id:ue,htmlFor:v,children:t}),a.jsxs("span",{...D({part:"control",state:{}}),children:[a.jsxs("button",{id:v,type:"button",role:"combobox",...D({part:"input",state:{}}),ref:S=>{N.current=S},disabled:h,"aria-labelledby":ue,"aria-haspopup":"listbox","aria-expanded":k,"aria-controls":Ae,"aria-activedescendant":k&&x>=0?pe(x):void 0,"aria-required":m||void 0,"aria-invalid":l!==void 0||void 0,"aria-describedby":je,onClick:()=>k?y():Q(),onKeyDown:Fe,onKeyUp:at,onBlur:me,children:[a.jsx("span",{children:j===void 0?s??"Choose":j.label}),j?.count===void 0?null:a.jsx("span",{"aria-hidden":"true",children:j.count})]}),a.jsx("div",{id:Ae,role:"listbox","aria-labelledby":ue,tabIndex:-1,popover:"manual",hidden:!k,ref:T,onMouseDown:S=>S.preventDefault(),children:n.map((S,L)=>{const H=`${pe(L)}-label`,Z=`${pe(L)}-count`;return a.jsxs("div",{id:pe(L),role:"option",tabIndex:-1,"aria-selected":S.value===o,"aria-labelledby":S.count===void 0?void 0:`${H} ${Z}`,ref:re=>{re===null?_.current.delete(S.value):_.current.set(S.value,re)},...D(he[L]??{part:"option",state:{}}),onPointerMove:()=>{L!==x&&A(L)},onClick:()=>{E(S.value),k&&N.current?.focus()},children:[a.jsx("span",{id:H,children:S.label}),S.count===void 0?null:a.jsx("span",{id:Z,"aria-hidden":"true",children:S.count})]},S.value)})})]}),c===void 0?null:a.jsx("input",{type:"hidden",name:c,value:j===void 0?"":o}),l!==void 0?a.jsx("p",{id:je,...D({part:"error",state:{}}),children:l}):d!==void 0?a.jsx("p",{id:je,...D({part:"hint",state:{}}),children:d}):null]})}const ga=K({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."},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
|
|
209
477
|
bar={<Link href="#/">ACME</Link>}
|
|
210
478
|
side={
|
|
211
479
|
<Nav label="Main">
|
|
@@ -217,7 +485,18 @@ ${P.current([M.current])}`:"The selection removed this dropdown from the page.")
|
|
|
217
485
|
<Panel label="Reports" headingLevel={2}>
|
|
218
486
|
<Text>Quarterly numbers land here.</Text>
|
|
219
487
|
</Panel>
|
|
220
|
-
</Shell>`}
|
|
488
|
+
</Shell>`},{title:"A sidebar that can be hidden",description:"With collapsible, a person can put the sidebar away on a wide screen as well as a narrow one, and get the full width for the page.",code:`<Shell
|
|
489
|
+
collapsible
|
|
490
|
+
bar={<Link href="#/">ACME</Link>}
|
|
491
|
+
side={
|
|
492
|
+
<Nav label="Main">
|
|
493
|
+
<Link href="#/reports" active>Reports</Link>
|
|
494
|
+
<Link href="#/settings">Settings</Link>
|
|
495
|
+
</Nav>
|
|
496
|
+
}
|
|
497
|
+
>
|
|
498
|
+
<Text>Quarterly numbers land here.</Text>
|
|
499
|
+
</Shell>`}]});function Li(e){const{side:t,bar:n,sideLabel:o="Sidebar",skipLabel:i="Skip to content",menuLabel:s="Menu",closeLabel:d="Close",collapsible:l=!1,collapsed:c,defaultCollapsed:h=!1,onCollapsedChange:m,hideLabel:p="Hide menu",showLabel:b="Show menu",children:g,...C}=e,f=z(),[w,v]=r.useState(!1),[k,R]=r.useState(h),x=l&&(c??k),A=r.useId(),P=r.useRef(null),N=r.useCallback(_=>{const M=_.target;M instanceof Element&&M.closest("a")!==null&&v(!1)},[]),T=$({component:ga.name,region:!0,state:{open:w,collapsed:x}});return f==="agent"?a.jsxs(a.Fragment,{children:[n,t,g]}):a.jsxs("div",{...C,...V(T),children:[a.jsx("button",{type:"button",onClick:()=>P.current?.focus(),children:i}),a.jsxs("aside",{"aria-label":o,children:[a.jsxs("div",{children:[n,a.jsxs("span",{children:[a.jsx(Qe,{agentTool:!1,"aria-expanded":w,"aria-controls":A,onClick:()=>v(!w),children:w?d:s}),l?a.jsx(Qe,{agentTool:!1,"aria-expanded":!x,"aria-controls":A,onClick:()=>{R(!x),m?.(!x)},children:x?b:p}):null]})]}),a.jsx("div",{id:A,onClick:N,children:t})]}),a.jsx("main",{ref:P,tabIndex:-1,children:g})]})}const ma=K({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.",values:["none","tight","normal","loose"],default:"normal"},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","tight","normal","loose"]},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>
|
|
221
500
|
<Button>Cancel</Button>
|
|
222
501
|
<Button tone="action">Confirm</Button>
|
|
223
502
|
</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">
|
|
@@ -226,8 +505,32 @@ ${P.current([M.current])}`:"The selection removed this dropdown from the page.")
|
|
|
226
505
|
</Stack>`},{title:"A header bar that stacks on a phone",code:`<Stack direction="row" justify="between" align="center" collapse>
|
|
227
506
|
<Heading level={1}>Button</Heading>
|
|
228
507
|
<Tag tone="warning">experimental</Tag>
|
|
229
|
-
</Stack>`}]});function
|
|
230
|
-
|
|
508
|
+
</Stack>`}]}),fa=["10rem","12rem","14rem","16rem","18rem","20rem","22rem","24rem","28rem","32rem"];function Pi(e){return fa.includes(e)}function Ei(e,t){return Pi(e)?t:{...t,"--sprint-stack-min":e}}function Oi(e){const{direction:t="column",gap:n="normal",align:o,justify:i,wrap:s=!1,collapse:d=!1,min:l="18rem",children:c,style:h,...m}=e,p=z(),b=t==="grid",g=$({component:ma.name,state:{direction:t,gap:n,align:o,justify:i,wrap:s,collapse:d,min:b?l:void 0}});return p==="agent"?a.jsx(a.Fragment,{children:c}):a.jsx("div",{...m,...V(g),style:b?Ei(l,h):h,children:c})}const ba=K({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
|
+
label="Send Tess two things"
|
|
510
|
+
steps={[{ title: "Copy the link" }, { title: "Pass on the emoji" }]}
|
|
511
|
+
/>`},{title:"Partway through",description:"A finished step, the one in progress, and one still to come, each with a line of detail.",code:`<Steps
|
|
512
|
+
label="Connect a tool"
|
|
513
|
+
steps={[
|
|
514
|
+
{
|
|
515
|
+
title: "Register the tool",
|
|
516
|
+
body: "Give it a name and an input schema.",
|
|
517
|
+
state: "done",
|
|
518
|
+
},
|
|
519
|
+
{
|
|
520
|
+
title: "Drive the DOM",
|
|
521
|
+
body: "Click the real element rather than calling a prop.",
|
|
522
|
+
state: "current",
|
|
523
|
+
},
|
|
524
|
+
{ title: "Return the new state", body: "Read it back from the page." },
|
|
525
|
+
]}
|
|
526
|
+
/>`},{title:"Every step done",description:"When all steps are done the list publishes that it is complete.",code:`<Steps
|
|
527
|
+
label="Send Tess two things"
|
|
528
|
+
steps={[
|
|
529
|
+
{ title: "Copy the link", state: "done" },
|
|
530
|
+
{ title: "Pass on the emoji", state: "done" },
|
|
531
|
+
]}
|
|
532
|
+
/>`}]}),Ni={role:"list"};function Di(e){return e.body===void 0||e.body===""?e.title:`${e.title}: ${e.body}`}function un(e,t){return{part:"step",label:Di(e),state:{index:String(t+1),...e.state==="done"?{done:!0}:{},...e.state==="current"?{current:!0}:{}}}}function $i(e){const{label:t,steps:n,doneLabel:o="Done",emptyLabel:i="No steps",...s}=e,d=z(),l=r.useId(),c=n.length===0,h=n.map(un),m=!c&&n.every(b=>b.state==="done"),p=$({component:ba.name,label:t,state:{steps:String(n.length),complete:m,empty:c},parts:h});return d==="agent"?a.jsx(Y,{node:p}):a.jsxs("ol",{...s,...V(p),...Ni,"aria-label":t,children:[c?a.jsx("li",{children:i}):null,n.map((b,g)=>{const C=h[g]??un(b,g),f=b.state==="done",w=`${l}-${g}-done`;return a.jsxs("li",{...D(C),"aria-current":b.state==="current"?"step":void 0,"aria-describedby":f?w:void 0,children:[a.jsx("span",{"aria-hidden":"true",children:g+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:w,hidden:!0,children:o}):null]},`${g}-${b.title}`)})]})}const Jt={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."},Et=K({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:Jt},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 Mi(e){const{label:t,on:n,onChange:o,disabled:i=!1,agentName:s,agentTool:d=!0,ref:l,...c}=e,h=z(),m=ae(),p=ne(),b=r.useRef(null),g=r.useCallback(P=>{b.current=P,typeof l=="function"?l(P):l!=null&&(l.current=P)},[l]),C=r.useRef(o);C.current=o;const f=r.useRef(n);f.current=n;const w=r.useRef(p);w.current=p;const v=r.useRef($({component:Et.name})),k=r.useRef(!0);r.useEffect(()=>(k.current=!0,()=>{k.current=!1}),[]);const R=r.useCallback(async P=>{const N=P.on;if(typeof N!="boolean")return'Pass "on" as true or false; it states the end state.';const T=N===f.current;if(!T){const M=b.current;M!==null?M.click():ie(()=>C.current(N))}return await oe(),k.current?`${T?`Already ${N?"on":"off"}`:`Switched ${N?"on":"off"}`}. The switch is now:
|
|
533
|
+
${w.current([v.current])}`:"The change removed this switch from the page."},[]),x=te({spec:Jt,label:s??t,enabled:d&&!i,execute:R}),A=$({component:Et.name,label:t,tool:x,state:{on:n,disabled:i}});return v.current=A,h==="agent"?i||m==="never"?a.jsx(Y,{node:A}):a.jsx(Se,{node:A,ref:g,onClick:()=>o(!n)}):a.jsxs("button",{...c,...V(A),type:"button",role:"switch","aria-checked":n,disabled:i,ref:g,onClick:()=>o(!n),children:[a.jsx("span",{...D({part:"track",state:{}}),"aria-hidden":"true",children:a.jsx("span",{...D({part:"thumb",state:{}})})}),t]})}const wa=K({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]
|
|
231
534
|
| row | prop | kind |
|
|
232
535
|
| --- | --- | --- |
|
|
233
536
|
| 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
|
|
@@ -242,11 +545,14 @@ ${v.current([k.current])}`:"The change removed this switch from the page."},[]),
|
|
|
242
545
|
emptyLabel="No tools registered"
|
|
243
546
|
columns={[{ key: "name", header: "Name" }]}
|
|
244
547
|
rows={[]}
|
|
245
|
-
/>`}
|
|
246
|
-
|
|
247
|
-
|
|
548
|
+
/>`},{title:"A table while fetching",description:"Before the first rows arrive the table reads [empty, loading], so an agent waits rather than concluding there is nothing.",code:`<Table
|
|
549
|
+
label="Loadouts"
|
|
550
|
+
loading={isFetching}
|
|
551
|
+
columns={[{ key: "name", header: "Name" }]}
|
|
552
|
+
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."}}),va=["4rem","5rem","6rem","7rem","8rem","9rem","10rem","12rem","14rem","16rem","20rem","24rem"];function Ii(e){return va.includes(e)}function Ui(e){if(!(e===void 0||Ii(e)))return{width:e}}function Ot(e,t){return e.id??String(t+1)}function ya(e,t){return{column:e.key,row:t,...e.align===void 0?{}:{align:e.align}}}function qi(e,t){return t.flatMap((n,o)=>e.map(i=>{const s=se(n.cells[i.key]);return{part:"cell",state:ya(i,Ot(n,o)),...s===void 0?{}:{label:s}}}))}function Wi(e){const{label:t,columns:n,rows:o,emptyLabel:i="No rows",loading:s=!1,loadingLabel:d="Loading",...l}=e,c=z(),h=o.length===0,m=$({component:wa.name,label:t,state:{columns:String(n.length),rows:String(o.length),empty:h,loading:s},parts:qi(n,o)});return c==="agent"?a.jsx(Y,{node:Dn(m)}):a.jsxs("table",{...l,...V(m),role:"table","aria-label":t,"aria-busy":s||void 0,children:[a.jsx("thead",{role:"rowgroup",children:a.jsx("tr",{role:"row",children:n.map(p=>a.jsx("th",{role:"columnheader",scope:"col","data-sprint-column":p.key,"data-sprint-width":p.width,style:Ui(p.width),children:p.header},p.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:s?d:i})})}):o.map((p,b)=>a.jsx("tr",{role:"row",children:n.map(g=>a.jsxs("td",{role:"cell",...D({part:"cell",state:ya(g,Ot(p,b))}),children:[a.jsx("span",{"aria-hidden":"true",children:g.header}),a.jsx("div",{children:p.cells[g.key]})]},g.key))},Ot(p,b)))})]})}const ka=K({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"},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"]}},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">
|
|
248
554
|
{ready ? "WebMCP is available in this browser." : "WebMCP is unavailable here."}
|
|
249
|
-
</Text>`}]});function
|
|
555
|
+
</Text>`}]});function _i(e){const{tone:t="default",size:n="normal",as:o="p",children:i,...s}=e,d=z(),l=$({component:ka.name,label:se(i),state:{tone:t,size:n}});if(d==="agent")return a.jsx(Y,{node:l});const c=o;return a.jsx(c,{...s,...V(l),children:i})}const Zt={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."},Nt=K({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.",default:4},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},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:Zt},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
|
|
250
556
|
label="Mission notes"
|
|
251
557
|
value={notes}
|
|
252
558
|
onChange={setNotes}
|
|
@@ -258,8 +564,8 @@ ${v.current([k.current])}`:"The change removed this switch from the page."},[]),
|
|
|
258
564
|
required
|
|
259
565
|
rows={3}
|
|
260
566
|
error="State the reason before aborting."
|
|
261
|
-
/>`}],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
|
|
262
|
-
${
|
|
567
|
+
/>`}],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 Bi(e,t){return e!==void 0?[{part:"error",label:e,state:{}}]:t!==void 0?[{part:"hint",label:t,state:{}}]:[]}function Fi(e){const{label:t,value:n,onChange:o,rows:i=4,placeholder:s,hint:d,error:l,name:c,disabled:h=!1,required:m=!1,agentName:p,agentTool:b=!0,...g}=e,C=z(),f=ae(),w=ne(),v=r.useId(),k=r.useRef(null),R=r.useRef(o);R.current=o;const x=r.useRef(w);x.current=w;const A=r.useRef($({component:Nt.name})),P=r.useRef(!0);r.useEffect(()=>(P.current=!0,()=>{P.current=!1}),[]);const N=r.useCallback(async X=>{const I=X.value;if(typeof I!="string")return'Pass "value" as a string holding the full text the area should contain.';const q=k.current;return q!==null?Qt(q,I):ie(()=>R.current(I)),await oe(),P.current?`Filled. The area is now:
|
|
568
|
+
${x.current([A.current])}`:"The change removed this area from the page."},[]),T=te({spec:Zt,label:p??t,enabled:b&&!h,execute:N}),_=$({component:Nt.name,label:t,tool:T,state:{...n===""?{}:{value:n},empty:n==="",disabled:h,required:m,invalid:l!==void 0},parts:Bi(l,d)});if(A.current=_,C==="agent")return h||f==="never"?a.jsx(Y,{node:_}):a.jsx(_t,{node:_,value:n,multiline:!0,onValueChange:o,ref:X=>{k.current=X}});const M=l!==void 0?`${v}-error`:d!==void 0?`${v}-hint`:void 0;return a.jsxs("div",{...g,...V(_),children:[a.jsx("label",{htmlFor:v,children:t}),a.jsx("textarea",{id:v,...D({part:"input",state:{}}),ref:X=>{k.current=X},rows:i,value:n,placeholder:s,name:c,disabled:h,required:m,"aria-invalid":l!==void 0||void 0,"aria-describedby":M,onChange:X=>o(X.currentTarget.value)}),l!==void 0?a.jsx("p",{id:M,...D({part:"error",state:{}}),children:l}):d!==void 0?a.jsx("p",{id:M,...D({part:"hint",state:{}}),children:d}):null]})}const en={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."},Dt=K({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.',values:["text","email","url","search","password"],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},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:en},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
|
|
263
569
|
label="Callsign"
|
|
264
570
|
value={callsign}
|
|
265
571
|
onChange={setCallsign}
|
|
@@ -277,18 +583,24 @@ ${R.current([P.current])}`:"The change removed this area from the page."},[]),w=
|
|
|
277
583
|
value={code}
|
|
278
584
|
onChange={setCode}
|
|
279
585
|
autoComplete="current-password"
|
|
280
|
-
/>`}
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
586
|
+
/>`},{title:"A read-only value",description:"A value shown in the shape of a form field that nobody may edit. It stays focusable and selectable, reads as text in the agent view, and registers no fill tool. To hand someone a value to paste elsewhere, a CopyField adds the copy control.",code:`<TextInput
|
|
587
|
+
label="Station ID"
|
|
588
|
+
value="KX-2209-ALPHA"
|
|
589
|
+
onChange={() => {}}
|
|
590
|
+
readOnly
|
|
591
|
+
hint="Assigned at registration"
|
|
592
|
+
/>`}],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 Hi(e,t){return e!==void 0?[{part:"error",label:e,state:{}}]:t!==void 0?[{part:"hint",label:t,state:{}}]:[]}function Vi(e){const{label:t,value:n,onChange:o,type:i="text",placeholder:s,hint:d,error:l,name:c,autoComplete:h,disabled:m=!1,readOnly:p=!1,required:b=!1,agentName:g,agentTool:C=!0,...f}=e,w=z(),v=ae(),k=ne(),R=r.useId(),x=r.useRef(null),A=r.useRef(o);A.current=o;const P=r.useRef(k);P.current=k;const N=r.useRef($({component:Dt.name})),T=r.useRef(!0);r.useEffect(()=>(T.current=!0,()=>{T.current=!1}),[]);const _=i==="password",M=r.useCallback(async F=>{const G=F.value;if(typeof G!="string")return'Pass "value" as a string holding the full text the field should contain.';const j=x.current;return j!==null?Qt(j,G):ie(()=>A.current(G)),await oe(),T.current?`Filled. The field is now:
|
|
593
|
+
${P.current([N.current])}`:"The change removed this field from the page."},[]),X=te({spec:en,label:g??t,enabled:C&&!m&&!p,execute:M}),I=$({component:Dt.name,label:t,tool:X,state:{..._?{filled:n!==""}:n===""?{}:{value:n},empty:n==="",disabled:m,readonly:p,required:b,invalid:l!==void 0},parts:Hi(l,d)});if(N.current=I,w==="agent")return m||p||v==="never"?a.jsx(Y,{node:I}):a.jsx(_t,{node:I,value:n,masked:_,onValueChange:o,ref:F=>{x.current=F}});const q=l!==void 0?`${R}-error`:d!==void 0?`${R}-hint`:void 0;return a.jsxs("div",{...f,...V(I),children:[a.jsx("label",{htmlFor:R,children:t}),a.jsx("input",{id:R,...D({part:"input",state:{}}),ref:F=>{x.current=F},type:i,value:n,placeholder:s,name:c,autoComplete:h,disabled:m,readOnly:p,required:b,"aria-invalid":l!==void 0||void 0,"aria-describedby":q,onChange:F=>o(F.currentTarget.value)}),l!==void 0?a.jsx("p",{id:q,...D({part:"error",state:{}}),children:l}):d!==void 0?a.jsx("p",{id:q,...D({part:"hint",state:{}}),children:d}):null]})}const tn=40;function Gi(e){const t=e.label===void 0?"":xe(e.label),n=t===""?xe(e.component):`${xe(e.component)}-${t}`;return n===""?"region":n}function Ki(e){const t=new Map;return e.map(n=>{const o=Gi(n),i=t.get(o)??0;return t.set(o,i+1),{key:i===0?o:`${o}-${i+1}`,node:n}})}function xa(){if(typeof document>"u")return[];const e=document.body,t=new Set(In(e)),n=Array.from(e.querySelectorAll(`[${Je}]`)).filter(o=>!t.has(o));return Ki([...Un(e),...n.map(o=>nt(o)).filter(o=>o!==null)])}const zi={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."},Xi={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 Yi(e){const t=xa();if(t.length===0)return"This page has no Sprint components.";const n=t.map(({key:o,node:i})=>{const s=Tn(i.children),d=e([{...i,children:[],parts:[]}]).split(`
|
|
594
|
+
`)[0]?.replace(/^-\s*/,""),l=s===0?"":` (${s} nested)`;return`- \`${o}\` — ${d??i.component}${l}`});return[`${t.length} region(s):`,...n].join(`
|
|
595
|
+
`)}function Qi(e,t,n){const o=xa(),i=o.map(c=>c.key),s=o.find(c=>c.key===t);if(s===void 0)return`No region named "${String(t)}". Available regions: ${i.join(", ")||"none"}.`;const d=Ut(e([s.node]),Te-tn),l=typeof n=="number"?n:1;return l<1||l>d.length?`Region "${s.key}" has ${d.length} page(s); page ${l} does not exist.`:`${d[l-1]??""}
|
|
284
596
|
|
|
285
|
-
(page ${
|
|
597
|
+
(page ${l} of ${d.length})`}const Ji={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 Ta(){return typeof document>"u"?"":(document.body.textContent??"").replace(/\n{3,}/g,`
|
|
286
598
|
|
|
287
|
-
`).trim()}function
|
|
599
|
+
`).trim()}function Zi(e){const{enabled:t,format:n,view:o,setView:i}=e;te({spec:zi,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.':Yi(n)}),te({spec:Xi,label:"region",enabled:t,execute:s=>o==="agent"?er(s.region,s.page):Qi(n,s.region,s.page)}),te({spec:Ji,label:"page view",enabled:t,execute:async s=>{const d=s.view==="agent"?"agent":"human";return ie(()=>i(d)),await oe(),d==="agent"?`Page is now in agent view:
|
|
288
600
|
|
|
289
|
-
${
|
|
601
|
+
${Xe(Ta(),Te-tn)}`:"Page is now in human view."}})}function er(e,t){if(e!=="page")return`No region named "${String(e)}". In agent view the whole page is one region, named "page".`;const n=Ut(Ta(),Te-tn),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]??""}
|
|
290
602
|
|
|
291
|
-
(page ${
|
|
603
|
+
(page ${o} of ${n.length})`}const Ca="--sprint-gloss-x",Sa="--sprint-gloss-fade",Aa="--sprint-cast-shift",tr=22,nr=78,ar=28,or=.25,pn=(e,t,n)=>Math.min(n,Math.max(t,e));function ir(){return typeof matchMedia=="function"&&matchMedia("(prefers-reduced-motion: reduce)").matches}const rr=new Set(["Button","Card","Tag","SegmentedControl","Switch","Shell"]),sr=new Set(["option","thumb"]);function lr(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&&sr.has(o)?n:null}function ja(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||!rr.has(n)?null:lr(e,t)??t}function dr(e){if(e.pointerType==="touch"||ir())return;const t=ja(e.target);if(t===null)return;const n=t.getBoundingClientRect();if(n.width===0||n.height===0)return;const o=pn((e.clientX-n.left)/n.width*100,tr,nr),i=(o-50)/ar;t.style.setProperty(Ca,`${o.toFixed(1)}%`),t.style.setProperty(Sa,pn(1-Math.abs(i),or,1).toFixed(3)),t.style.setProperty(Aa,`${(i*-10).toFixed(1)}px`)}function cr(e){const t=ja(e.target);t!==null&&(t.style.removeProperty(Ca),t.style.removeProperty(Sa),t.style.removeProperty(Aa),t.style.length===0&&t.removeAttribute("style"))}const hr=1200;function ur(e){const{children:t,label:n,format:o,pageTools:i=!0,view:s,defaultView:d,onViewChange:l,agentControls:c,theme:h}=e,m=Be(),p=Pn(),b=!p.owned,[g,C]=r.useState(d??"human"),f=s!==void 0,w=f||b||d!==void 0,v=f?s:w?g:p.view,k=r.useCallback(I=>{if(!w){p.setView(I);return}f||C(I),l?.(I)},[w,f,p,l]),R=c??p.controls,x=o??p.format??Wt,A=r.useMemo(()=>({view:v,setView:k,controls:R,format:x,owned:w}),[v,k,R,x,w]),P=r.useMemo(()=>({path:n===void 0?m:[...m,n]}),[m,n]);Zi({enabled:b&&i,format:x,view:v,setView:k});const N=r.useRef(null),[T,_]=r.useState(!1);r.useEffect(()=>{if(!T)return;const I=setTimeout(()=>_(!1),hr);return()=>clearTimeout(I)},[T]);const M=()=>{const I=navigator.clipboard;if(I===void 0)return;const q=(N.current?.textContent??"").replace(/\n{3,}/g,`
|
|
292
604
|
|
|
293
|
-
`).trim();
|
|
605
|
+
`).trim();I.writeText(q).then(()=>_(!0),()=>_(!1))},X=w&&v==="agent"&&R!=="never";return a.jsx(eo,{value:A,children:a.jsxs(qe,{value:P,children:[X?a.jsx("button",{type:"button","aria-label":T?"Copied":"Copy agent view",[mn]:"",...T?{"data-sprint-copied":""}:{},onClick:M}):null,a.jsx("div",{ref:N,onPointerMove:v==="agent"?void 0:dr,onPointerOut:v==="agent"?void 0:cr,[gn]:v,...h===void 0?{}:{[fn]:h},children:t})]})})}function pr(e){const{children:t,label:n}=e,o=Be(),i=r.useMemo(()=>({path:[...o,n]}),[o,n]);return a.jsx(qe,{value:i,children:t})}const gr="0.7.0",mr={version:gr},fr=mr.version;exports.ACT_BREADCRUMB_TOOL=Re;exports.AGENT_ATTRIBUTE=Mt;exports.AgentControl=Se;exports.AgentControlGroup=ce;exports.AgentLine=Y;exports.AgentRegion=pr;exports.AgentScopeProvider=qe;exports.Alert=po;exports.Breadcrumb=wo;exports.Button=Qe;exports.CHOOSE_TOOL=Le;exports.CLOSE_DIALOG_TOOL=Gt;exports.COMPONENT_ATTRIBUTE=fe;exports.Card=yo;exports.ChangeList=Ro;exports.Checkbox=Po;exports.ChoiceGrid=$o;exports.CodeBlock=qo;exports.CopyField=Bo;exports.DISMISS_ALERT_TOOL=Bt;exports.DescriptionList=Ho;exports.Dialog=Vo;exports.Disclosure=Go;exports.Divider=Ko;exports.EXPAND_DISCLOSURE_TOOL=Kt;exports.EmptyState=Xo;exports.EntityRow=Qo;exports.FILL_TEXTAREA_TOOL=Zt;exports.FILL_TOOL=en;exports.Heading=Jo;exports.Image=Zo;exports.Link=Jn;exports.List=ei;exports.MetaLine=ti;exports.Nav=ni;exports.NavGroup=ai;exports.OPEN_CARD_TOOL=Ht;exports.OPEN_ENTITY_ROW_TOOL=Xt;exports.OPEN_LINK_TOOL=zt;exports.OWNER_ATTRIBUTE=$t;exports.PARAM_DESCRIPTION_LIMIT=mt;exports.PART_ATTRIBUTE=Ce;exports.PRESS_TOOL=Ft;exports.PageHeader=oi;exports.Pagination=li;exports.Panel=di;exports.Pending=ci;exports.Progress=ui;exports.REGION_ATTRIBUTE=Je;exports.RESERVED_STATE_KEYS=bn;exports.SEARCH_TOOL=Yt;exports.SELECT_OPTION_TOOL=Oe;exports.SELECT_TOOL=Ee;exports.SET_CHECKBOX_TOOL=Vt;exports.SET_SWITCH_TOOL=Jt;exports.STACK_MINS=fa;exports.STATE_ATTRIBUTE_PREFIX=Ie;exports.SearchField=mi;exports.SecretField=wi;exports.SegmentedControl=yi;exports.Select=Ri;exports.Shell=Li;exports.SprintProvider=ur;exports.Stack=Oi;exports.Steps=$i;exports.Switch=Mi;exports.TABLE_WIDTHS=va;exports.THEME_ATTRIBUTE=fn;exports.TOOL_ATTRIBUTE=Ne;exports.TOOL_DESCRIPTION_LIMIT=gt;exports.TOOL_NAMING_CONVENTION=yn;exports.TOOL_OUTPUT_LIMIT=Te;exports.TURN_PAGE_TOOL=Pe;exports.Table=Wi;exports.Tag=ta;exports.Text=_i;exports.TextInput=Vi;exports.Textarea=Fi;exports.VIEW_ATTRIBUTE=gn;exports.VIEW_COPY_ATTRIBUTE=mn;exports.accessibleText=_e;exports.afterCommit=oe;exports.agentAttributes=It;exports.agentAttributesFor=V;exports.agentPartAttributesFor=D;exports.agentPartControlAttributes=Nn;exports.agentSelector=Ka;exports.alertMeta=wt;exports.breadcrumbMeta=vt;exports.buildAgentManifest=Qa;exports.buildAgentNode=$;exports.buttonMeta=yt;exports.cardMeta=kt;exports.changeListMeta=_n;exports.checkboxMeta=xt;exports.choiceGridMeta=Tt;exports.clamp=Xe;exports.codeBlockMeta=Gn;exports.copyFieldMeta=Kn;exports.defaultAgentFormat=Wt;exports.defineAgentMeta=K;exports.descriptionListMeta=zn;exports.dialogMeta=Xn;exports.disclosureMeta=Ct;exports.dividerMeta=Yn;exports.emptyStateMeta=Zn;exports.entityRowMeta=St;exports.getAgentMeta=kn;exports.getModelContext=qt;exports.headingMeta=na;exports.imageMeta=aa;exports.isModelContextAvailable=za;exports.linkMeta=Qn;exports.listAgentMeta=xn;exports.listMeta=oa;exports.metaLineMeta=ia;exports.navGroupMeta=sa;exports.navMeta=ra;exports.nodeLine=jn;exports.pageHeaderMeta=la;exports.paginate=Ut;exports.paginationMeta=jt;exports.panelMeta=da;exports.pendingMeta=ca;exports.progressMeta=ha;exports.reactText=se;exports.registerTool=vn;exports.searchFieldMeta=Rt;exports.secretFieldMeta=ua;exports.segmentedControlMeta=Lt;exports.selectMeta=Pt;exports.serializeElement=nt;exports.serializeWithin=Un;exports.shellMeta=ga;exports.slug=xe;exports.stackMeta=ma;exports.stepsMeta=ba;exports.switchMeta=Et;exports.tableMeta=wa;exports.tagMeta=ea;exports.textInputMeta=Dt;exports.textMeta=ka;exports.textareaMeta=Nt;exports.toMarkdown=Ln;exports.tokenize=Vn;exports.toolName=bt;exports.useAgentControls=ae;exports.useAgentFormat=ne;exports.useAgentScope=Be;exports.useAgentTool=te;exports.useSprintView=z;exports.useSprintViewControl=Pn;exports.validateInputs=wn;exports.version=fr;
|
|
294
606
|
//# sourceMappingURL=index.cjs.map
|