@joewinke/jatui 0.36.3 → 0.38.0

package/dist/artifact-blocks/blocks/callout/CalloutBlock.svelte.d.ts

@@ -0,0 +1,40 @@
+import type { BlockProps } from "../../types.js";
+declare const CalloutBlock: import("svelte").Component<BlockProps<{
+    variant: "warn" | "success" | "note" | "decision";
+    title?: string | undefined;
+    body?: string | undefined;
+    question?: string | undefined;
+    options?: {
+        id: string;
+        label: string;
+        letter?: string | undefined;
+        detail?: string | undefined;
+    }[] | undefined;
+    recommended?: string | undefined;
+    allowOther?: boolean | undefined;
+    commentLabel?: string | undefined;
+    allowComment?: boolean | undefined;
+    meta?: {
+        label: string;
+        value: string;
+        href?: string | undefined;
+        title?: string | undefined;
+        tone?: "error" | "warning" | "info" | "success" | "neutral" | undefined;
+    }[] | undefined;
+    sections?: {
+        heading: string;
+        markdown: string;
+        open?: boolean | undefined;
+    }[] | undefined;
+    primaryAction?: {
+        label: string;
+        url: string;
+    } | undefined;
+    group?: {
+        key: string;
+        label: string;
+        quiet?: boolean | undefined;
+    } | undefined;
+}>, {}, "">;
+type CalloutBlock = ReturnType<typeof CalloutBlock>;
+export default CalloutBlock;

package/dist/artifact-blocks/blocks/callout/block.d.ts

@@ -0,0 +1,7 @@
+/**
+ * callout block — note/warn/success banners + interactive decision.
+ */
+import type { ArtifactBlockDef } from "../../types.js";
+import { type CalloutParams } from "./schema.js";
+declare const def: ArtifactBlockDef<CalloutParams>;
+export default def;

package/dist/artifact-blocks/blocks/callout/block.js

@@ -0,0 +1,39 @@
+import CalloutBlock from "./CalloutBlock.svelte";
+import { calloutSchema } from "./schema.js";
+const EXAMPLE = {
+    variant: "decision",
+    title: "Ruby rollout",
+    body: "Support needs **two weeks** after training before calls go live, and the carrier port finishes October 28.",
+    question: "Which go-live date should we commit to?",
+    options: [
+        { id: "nov-1", label: "November 1" },
+        { id: "nov-15", label: "November 15" },
+        { id: "dec-1", label: "December 1" },
+    ],
+    allowOther: true,
+    commentLabel: "Anything we should know about the date",
+    meta: [
+        { label: "asked by", value: "Support lead" },
+        { label: "priority", value: "P1", tone: "warning" },
+        { label: "task", value: "ops-12ab3", href: "/tasks?task=ops-12ab3" },
+    ],
+    primaryAction: { label: "Open the training plan", url: "https://example.com/training" },
+    sections: [
+        {
+            heading: "What was done",
+            markdown: "- Carrier port booked for **October 28**\n- Training sessions drafted for both shifts",
+        },
+        { heading: "Context", markdown: "The two-week buffer comes from last year's rollout." },
+    ],
+};
+const def = {
+    type: "callout",
+    title: "Callout / decision",
+    description: "Banners and one interactive question. variant note|warn|success renders an info/warning/success alert with an optional markdown body (through the shared sanitized renderer) — use for context, caveats, confirmations. variant decision asks the viewer a question with 2-6 options (ids lowercase a-z0-9_-, labels ≤120 chars), an optional 'other' free-text choice (allowOther) and an optional comment box (allowComment:false removes it). When the comment box exists it doubles as the Other explanation: picking Other relabels it 'Say what instead' and focuses it, and its text saves to BOTH state.other and state.comment so readers of either keep working; without a comment box the Other text comes from a dedicated 'Say which' input into state.other. Saving is automatic and every save is a per-viewer DRAFT — no button: picking an option saves at once (arrow keys move, space/enter pick), switching options re-saves, and the note and Other text autosave ~800ms after typing stops and on blur, per viewer via ctx.saveState as { pick, other?, comment?, at? } — drafts survive a reload, and the page's Finish review sends them. A card with a saved answer shows the done treatment (success border + 'Draft: <choice>' chip); a save in flight or failed shows a small Saving…/error+Retry state and never loses the viewer's pick. It renders read-only (disabled) where saving is impossible. NEEDS YOU fields (decision only, all optional, none answerable — links navigate, they never save a verdict): meta [{label ≤24, value ≤80, href? http(s)/root-relative, title? hover text, tone? neutral|info|success|warning|error}] ≤8 as one compact row under the question; primaryAction {label ≤60, url} as the card's primary link button above the options (off-origin opens a new tab); sections [{heading ≤60, markdown, open?}] ≤8 as collapsed <details> below the note, sharing the 20,000-char body budget — when sections are present the body is NOT rendered (it is their flattened fallback for older renderers); group {key [a-z0-9-]{1,32}, label ≤60, quiet?} puts the card under a group header the renderer draws between cards. Tip: one decision per callout; title names the topic, body gives the reasoning, question is the ask (it renders as the lead line), so they never repeat each other.",
+    schema: calloutSchema,
+    component: CalloutBlock,
+    // mos-8fvt9: the section's Listen + comment sit on the heading row.
+    hostsTools: () => true,
+    example: EXAMPLE,
+};
+export default def;

package/dist/artifact-blocks/blocks/callout/schema.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Params schema for the callout block (note/warn/success/decision).
+ */
+import { z } from "zod";
+export declare const calloutSchema: z.ZodObject<{
+    variant: z.ZodEnum<{
+        warn: "warn";
+        success: "success";
+        note: "note";
+        decision: "decision";
+    }>;
+    title: z.ZodOptional<z.ZodString>;
+    body: z.ZodOptional<z.ZodString>;
+    question: z.ZodOptional<z.ZodString>;
+    options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        letter: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    recommended: z.ZodOptional<z.ZodString>;
+    allowOther: z.ZodOptional<z.ZodBoolean>;
+    commentLabel: z.ZodOptional<z.ZodString>;
+    allowComment: z.ZodOptional<z.ZodBoolean>;
+    meta: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        value: z.ZodString;
+        href: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+        tone: z.ZodOptional<z.ZodEnum<{
+            error: "error";
+            warning: "warning";
+            info: "info";
+            success: "success";
+            neutral: "neutral";
+        }>>;
+    }, z.core.$strip>>>;
+    sections: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        heading: z.ZodString;
+        markdown: z.ZodString;
+        open: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+    primaryAction: z.ZodOptional<z.ZodObject<{
+        label: z.ZodString;
+        url: z.ZodString;
+    }, z.core.$strip>>;
+    group: z.ZodOptional<z.ZodObject<{
+        key: z.ZodString;
+        label: z.ZodString;
+        quiet: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Reserved pick id for the "Other" free-text choice. Option ids can never
+ * collide with it: the id regex forbids a leading underscore.
+ */
+export declare const OTHER_ID = "__other__";
+/** Per-viewer state a decision callout saves through ctx.saveState. */
+export interface CalloutState {
+    /** Chosen option id, or OTHER_ID for the free-text "Other" choice. */
+    pick?: string;
+    /** The viewer's text when pick === OTHER_ID. */
+    other?: string;
+    /** Optional comment from the comment box. */
+    comment?: string;
+    /** The note's voice/video/screen/file attachments (mos-rccb5) —
+     * descriptors in the artifact's private asset store. */
+    attachments?: import("../../review/attachments.js").NoteAttachment[];
+    /** ISO timestamp of the last save. */
+    at?: string;
+}
+export type CalloutParams = z.infer<typeof calloutSchema>;

package/dist/artifact-blocks/blocks/callout/schema.js

@@ -0,0 +1,115 @@
+/**
+ * Params schema for the callout block (note/warn/success/decision).
+ */
+import { z } from "zod";
+import { DECISION_BODY_BUDGET, blockGroupSchema, decisionMetaSchema, decisionPrimaryActionSchema, decisionSectionsSchema, } from "../../contractBlocks.js";
+const calloutVariantSchema = z.enum(["note", "warn", "success", "decision"]);
+const calloutOptionSchema = z.object({
+    /** Stable id the viewer's pick is stored under (lowercase a-z0-9_-). */
+    id: z
+        .string()
+        .regex(/^[a-z0-9][a-z0-9_-]{0,63}$/, "option id must be lowercase a-z0-9_- (max 64)"),
+    label: z.string().min(1, "option label is required").max(120),
+    /** The contract letter this option answers to (mos-4tgfj). Absent = its
+     * position (A, B, C…). Set on cards published as a contract `decision`. */
+    letter: z
+        .string()
+        .regex(/^[A-Z]$/, "letter must be one capital A-Z")
+        .optional(),
+    /** A muted second line under the label. */
+    detail: z.string().max(300).optional(),
+});
+const CALLOUT_BODY_MAX_CHARS = 20_000;
+export const calloutSchema = z
+    .object({
+    variant: calloutVariantSchema,
+    title: z.string().min(1).max(120).optional(),
+    /** Markdown, rendered through the shared sanitized renderer. */
+    body: z.string().max(CALLOUT_BODY_MAX_CHARS).optional(),
+    /** decision only — the question asked of the viewer. */
+    question: z.string().min(1).max(500).optional(),
+    /** decision only — 2-6 options the viewer picks between (up to 26 when
+     * every option carries its contract letter). */
+    options: z
+        .array(calloutOptionSchema)
+        .min(2, "at least 2 options")
+        .max(26, "at most 26 options")
+        .optional(),
+    /** decision only — the letter the publisher recommends (a badge). */
+    recommended: z
+        .string()
+        .regex(/^[A-Z]$/, "recommended must be one capital A-Z")
+        .optional(),
+    /** decision only — adds an "Other" option with a free-text field. */
+    allowOther: z.boolean().optional(),
+    /** decision only — label above the optional comment box. */
+    commentLabel: z.string().max(120).optional(),
+    /** decision only — set false to author a decision with no comment/notes
+     * box. Without one, the Other pick explains itself in a dedicated
+     * "Say which" input; with one (the default), the notes box doubles as the
+     * Other explanation. */
+    allowComment: z.boolean().optional(),
+    // NEEDS YOU fields (PARAMS-SPEC §1, jat-j49id) — all optional, none
+    // answerable: links and the primary button navigate, they never post a
+    // verdict. Same limits as the contract normalizer (contractBlocks.ts).
+    /** A compact row of facts under the question (≤8). */
+    meta: decisionMetaSchema.optional(),
+    /** Collapsed markdown sections; when present the body is not rendered
+     * (it is their flattened fallback for older renderers). */
+    sections: decisionSectionsSchema.optional(),
+    /** The card's primary link button, above the options. */
+    primaryAction: decisionPrimaryActionSchema.optional(),
+    /** The group header the renderer draws between cards (BlockRenderer). */
+    group: blockGroupSchema.optional(),
+})
+    .superRefine((v, ctx) => {
+    const sectionChars = (v.sections ?? []).reduce((n, sec) => n + sec.markdown.length, 0);
+    if (sectionChars > DECISION_BODY_BUDGET)
+        ctx.addIssue({
+            code: "custom",
+            path: ["sections"],
+            message: `sections share a ${DECISION_BODY_BUDGET}-character budget`,
+        });
+    if (v.variant !== "decision")
+        return;
+    if (!v.question)
+        ctx.addIssue({
+            code: "custom",
+            path: ["question"],
+            message: "decision callouts require a question",
+        });
+    if (!v.options)
+        ctx.addIssue({
+            code: "custom",
+            path: ["options"],
+            message: "decision callouts require 2-6 options",
+        });
+    if (v.options && v.options.length > 6 && v.options.some((o) => !o.letter))
+        ctx.addIssue({
+            code: "custom",
+            path: ["options"],
+            message: "at most 6 options",
+        });
+    const letters = optionLetters(v.options ?? []);
+    if (new Set(letters).size !== letters.length)
+        ctx.addIssue({
+            code: "custom",
+            path: ["options"],
+            message: "option letters must be unique",
+        });
+    if (v.recommended && !letters.includes(v.recommended))
+        ctx.addIssue({
+            code: "custom",
+            path: ["recommended"],
+            message: "recommended must be one of the option letters",
+        });
+});
+/** Each option's contract letter: its own, else its position (A, B, C…). */
+function optionLetters(options) {
+    return options.map((o, i) => o.letter ?? String.fromCharCode(65 + i));
+}
+/**
+ * Reserved pick id for the "Other" free-text choice. Option ids can never
+ * collide with it: the id regex forbids a leading underscore.
+ */
+export const OTHER_ID = "__other__";