@westonkd/sprint 0.1.2 → 0.2.0

package/dist/index.d.ts

@@ -868,6 +868,105 @@ export declare interface HeadingProps extends ComponentPropsWithRef<"h2"> {
     level?: HeadingLevel;
 }
 
+declare function Image_2(props: ImageProps): JSX.Element | null;
+export { Image_2 as Image }
+
+export declare type ImageFit = "cover" | "contain";
+
+export declare const imageMeta: {
+    readonly name: "Image";
+    readonly category: "display";
+    readonly 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.";
+    readonly 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.";
+    readonly 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.";
+    readonly status: "experimental";
+    readonly props: {
+        readonly src: {
+            readonly kind: "string";
+            readonly description: "Where the pixels are. Published as data-sprint-src so an agent that can see can fetch the file itself.";
+            readonly required: true;
+        };
+        readonly alt: {
+            readonly kind: "string";
+            readonly 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.";
+            readonly required: true;
+        };
+        readonly caption: {
+            readonly kind: "string";
+            readonly 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.";
+        };
+        readonly ratio: {
+            readonly kind: "enum";
+            readonly 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.";
+            readonly values: readonly ["1:1", "4:3", "3:2", "16:9", "auto"];
+            readonly default: "auto";
+        };
+        readonly fit: {
+            readonly kind: "enum";
+            readonly description: "How the picture fills a slot of a fixed ratio. cover crops it, contain letterboxes it. Ignored when ratio is auto.";
+            readonly values: readonly ["cover", "contain"];
+            readonly default: "cover";
+        };
+    };
+    readonly state: {
+        readonly src: {
+            readonly description: "The image source, so an agent can fetch the file without the DOM.";
+            readonly attribute: "data-sprint-src";
+        };
+        readonly status: {
+            readonly 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.";
+            readonly attribute: "data-sprint-status";
+            readonly values: readonly ["loading", "ready", "error"];
+        };
+        readonly ratio: {
+            readonly description: "The shape the slot holds.";
+            readonly attribute: "data-sprint-ratio";
+            readonly values: readonly ["1:1", "4:3", "3:2", "16:9", "auto"];
+        };
+        readonly fit: {
+            readonly description: "Whether a fixed-ratio slot crops the picture or letterboxes it.";
+            readonly attribute: "data-sprint-fit";
+            readonly values: readonly ["cover", "contain"];
+        };
+        readonly decorative: {
+            readonly description: "Present when the image was declared meaningless with an empty alt and no caption. It renders nothing at all in agent view.";
+            readonly attribute: "data-sprint-decorative";
+        };
+    };
+    readonly agentView: {
+        readonly 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\"";
+    };
+    readonly examples: readonly [{
+        readonly title: "A described picture";
+        readonly 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.";
+        readonly code: "<Image\n  src=\"media/pad-39b.svg\"\n  alt=\"Launch pad 39B under floodlights, gantry retracted\"\n  ratio=\"16:9\"\n/>";
+    }, {
+        readonly title: "A captioned figure";
+        readonly description: "The caption is read as well as seen, and arrives as its own part, so it can say what alt should not repeat.";
+        readonly code: "<Image\n  src=\"media/telemetry.svg\"\n  alt=\"Line chart of chamber pressure holding flat for nine minutes, then dropping\"\n  caption=\"Static fire 04, chamber pressure\"\n  ratio=\"3:2\"\n  fit=\"contain\"\n/>";
+    }, {
+        readonly title: "A picture that means nothing";
+        readonly 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.";
+        readonly code: "<Image src=\"media/grain.svg\" alt=\"\" ratio=\"1:1\" />";
+    }];
+    readonly a11y: {
+        readonly 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.";
+    };
+    readonly relatedComponents: readonly ["Card", "Panel"];
+};
+
+export declare interface ImageProps extends Omit<ComponentPropsWithRef<"figure">, "children"> {
+    src: string;
+    alt: string;
+    caption?: string;
+    ratio?: ImageRatio;
+    fit?: ImageFit;
+}
+
+export declare type ImageRatio = "1:1" | "4:3" | "3:2" | "16:9" | "auto";
+
+export declare type ImageStatus = "loading" | "ready" | "error";
+
 export declare function isModelContextAvailable(): boolean;
 
 export declare interface JsonSchemaObject {
@@ -1766,7 +1865,7 @@ export declare interface SprintProviderProps {
     theme?: SprintTheme;
 }
 
-export declare type SprintTheme = "dark" | "light";
+export declare type SprintTheme = "dark" | "light" | "calorie" | "calorie-dark";
 
 export declare type SprintView = "human" | "agent";