@dr-ishaan/remake-blocks 1.9.0 → 2.0.0

package/dist/dx.js

@@ -0,0 +1,230 @@
+/**
+ * v1.10.0: Developer Experience utilities.
+ *
+ * Exports:
+ *   - CLASSES: frozen object of CSS class name constants for programmatic use
+ *   - warn(message, ...args): dev-mode warning emitter (gated on devWarnings option)
+ *   - validateCustomCallouts(configs, strict): validates customCallouts at init time
+ *   - suggestSimilarType(type, knownTypes): Levenshtein-based "did you mean" suggester
+ *
+ * @module dx
+ */
+// ---------------------------------------------------------------------------
+// CLASSES — exported CSS class name constants
+// ---------------------------------------------------------------------------
+/**
+ * v1.10.0+: Frozen object of CSS class names used by the plugin. Use these
+ * in CSS-in-JS, tests, or any code that needs to reference callout classes
+ * programmatically without hardcoding strings.
+ *
+ * @example
+ * ```ts
+ * import { CLASSES } from '@dr-ishaan/remake-blocks';
+ *
+ * document.querySelector(`.${CLASSES.CALLOUT_NOTE}`) // '.callout-note'
+ * ```
+ */
+export const CLASSES = Object.freeze({
+    // Container classes
+    CALLOUT: "callout",
+    CALLOUT_NOTE: "callout-note",
+    CALLOUT_TIP: "callout-tip",
+    CALLOUT_IMPORTANT: "callout-important",
+    CALLOUT_WARNING: "callout-warning",
+    CALLOUT_CAUTION: "callout-caution",
+    CALLOUT_ABSTRACT: "callout-abstract",
+    CALLOUT_INFO: "callout-info",
+    CALLOUT_SUCCESS: "callout-success",
+    CALLOUT_QUESTION: "callout-question",
+    CALLOUT_FAILURE: "callout-failure",
+    CALLOUT_DANGER: "callout-danger",
+    CALLOUT_QUOTE: "callout-quote",
+    CALLOUT_BUG: "callout-bug",
+    CALLOUT_EXAMPLE: "callout-example",
+    CALLOUT_TODO: "callout-todo",
+    CALLOUT_SUMMARY: "callout-summary",
+    CALLOUT_TLDR: "callout-tldr",
+    CALLOUT_HINT: "callout-hint",
+    CALLOUT_CHECK: "callout-check",
+    CALLOUT_DONE: "callout-done",
+    CALLOUT_HELP: "callout-help",
+    CALLOUT_FAQ: "callout-faq",
+    CALLOUT_ATTENTION: "callout-attention",
+    CALLOUT_FAIL: "callout-fail",
+    CALLOUT_MISSING: "callout-missing",
+    CALLOUT_ERROR: "callout-error",
+    CALLOUT_CITE: "callout-cite",
+    // v1.6.0 types
+    CALLOUT_DEFINITION: "callout-definition",
+    CALLOUT_ASIDE: "callout-aside",
+    CALLOUT_CORRECTION: "callout-correction",
+    CALLOUT_UPDATE: "callout-update",
+    CALLOUT_FIGURE: "callout-figure",
+    CALLOUT_FURTHER_READING: "callout-further-reading",
+    CALLOUT_PREREQUISITE: "callout-prerequisite",
+    CALLOUT_EXERCISE: "callout-exercise",
+    CALLOUT_SIDENOTE: "callout-sidenote",
+    CALLOUT_TIMELINE: "callout-timeline",
+    CALLOUT_ANNOUNCEMENT: "callout-announcement",
+    CALLOUT_BIBLIOGRAPHY: "callout-bibliography",
+    CALLOUT_DRAFT: "callout-draft",
+    CALLOUT_TRANSLATION: "callout-translation",
+    CALLOUT_DISCUSSION: "callout-discussion",
+    CALLOUT_RETRO: "callout-retro",
+    // Sub-element classes
+    CALLOUT_TITLE: "callout-title",
+    CALLOUT_TITLE_TEXT: "callout-title-text",
+    CALLOUT_ICON: "callout-icon",
+    CALLOUT_BODY: "callout-body",
+    CALLOUT_COLLAPSIBLE: "collapsible",
+    // Disclosure / accordion
+    DISCLOSURE: "disclosure",
+    DISCLOSURE_TITLE: "disclosure-title",
+    DISCLOSURE_BODY: "disclosure-body",
+    DISCLOSURE_ACCORDION: "disclosure-accordion",
+    DISCLOSURE_TREE: "disclosure-tree",
+    // Pull quote / epigraph
+    PULL_QUOTE: "pull-quote",
+    PULL_QUOTE_TEXT: "pull-quote-text",
+    PULL_QUOTE_ATTRIBUTION: "pull-quote-attribution",
+    EPIGRAPH: "epigraph",
+    EPIGRAPH_TEXT: "epigraph-text",
+    EPIGRAPH_ATTRIBUTION: "epigraph-attribution",
+    // Blockquote enhancement
+    BLOCKQUOTE_ENHANCED: "blockquote-enhanced",
+});
+// ---------------------------------------------------------------------------
+// warn — dev-mode warning emitter
+// ---------------------------------------------------------------------------
+/**
+ * v1.10.0+: Emit a developer-mode warning via `console.warn`.
+ *
+ * The warning is prefixed with `[remake-blocks]` for easy identification
+ * and filtering. No-op when `devWarnings` is false OR when running in
+ * production (`process.env.NODE_ENV === 'production'`).
+ *
+ * @param enabled — whether devWarnings is enabled (from plugin options)
+ * @param message — warning message (without prefix)
+ * @param args — additional context args
+ */
+export function warn(enabled, message, ...args) {
+    if (!enabled)
+        return;
+    if (typeof process !== "undefined" && process.env && process.env.NODE_ENV === "production" && enabled !== true) {
+        // Auto-disable in production unless explicitly enabled
+        return;
+    }
+    console.warn(`[remake-blocks] ${message}`, ...args);
+}
+// ---------------------------------------------------------------------------
+// suggestSimilarType — Levenshtein-based "did you mean" suggester
+// ---------------------------------------------------------------------------
+/**
+ * Compute Levenshtein edit distance between two strings.
+ * Used by `suggestSimilarType` to find the closest match.
+ */
+function levenshtein(a, b) {
+    const m = a.length;
+    const n = b.length;
+    if (m === 0)
+        return n;
+    if (n === 0)
+        return m;
+    const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+    for (let i = 0; i <= m; i++)
+        dp[i][0] = i;
+    for (let j = 0; j <= n; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            const cost = a[i - 1].toLowerCase() === b[j - 1].toLowerCase() ? 0 : 1;
+            dp[i][j] = Math.min(dp[i - 1][j] + 1, // deletion
+            dp[i][j - 1] + 1, // insertion
+            dp[i - 1][j - 1] + cost);
+        }
+    }
+    return dp[m][n];
+}
+/**
+ * Find the closest matching type from a list of known types.
+ * Returns the best match if its edit distance is ≤ 3 (reasonable threshold
+ * for typo detection), or null if no close match exists.
+ *
+ * @example
+ * ```ts
+ * suggestSimilarType('TYPO', ['note', 'tip', 'warning']) // → 'tip'
+ * suggestSimilarType('XYZ', ['note', 'tip'])             // → null
+ * ```
+ */
+export function suggestSimilarType(input, knownTypes) {
+    let bestMatch = null;
+    let bestDistance = Infinity;
+    for (const candidate of knownTypes) {
+        const dist = levenshtein(input, candidate);
+        if (dist < bestDistance) {
+            bestDistance = dist;
+            bestMatch = candidate;
+        }
+    }
+    // Only suggest if the edit distance is reasonable (≤ 3 edits, or ≤ half
+    // the input length for longer type names like 'further-reading').
+    const threshold = Math.max(3, Math.floor(input.length / 2));
+    return bestDistance <= threshold ? bestMatch : null;
+}
+// ---------------------------------------------------------------------------
+// validateCustomCallouts — strict config validation
+// ---------------------------------------------------------------------------
+const REQUIRED_CALLOUT_FIELDS = ["type", "icon", "className", "defaultTitle", "color", "backgroundColor"];
+/**
+ * v1.10.0+: Validate `customCallouts` config entries.
+ *
+ * When `strict` is true, throws a descriptive Error for the first config
+ * entry that's missing a required field. When `strict` is false, returns
+ * an array of validation errors without throwing (caller decides what to do).
+ *
+ * Required fields per CalloutConfig:
+ *   - type (non-empty string)
+ *   - icon (string, may be empty for icon-less callouts)
+ *   - className (non-empty string, used for CSS targeting)
+ *   - defaultTitle (non-empty string)
+ *   - color (valid CSS color)
+ *   - backgroundColor (valid CSS color)
+ *
+ * @example
+ * ```ts
+ * validateCustomCallouts([
+ *   { type: 'x', icon: '🔥', className: 'callout-x', defaultTitle: 'X', color: '#f00', backgroundColor: '#fee' }
+ * ], true); // OK — no throw
+ *
+ * validateCustomCallouts([
+ *   { type: 'x', icon: '🔥' /* missing className, defaultTitle, color, backgroundColor *\/ }
+ * ], true); // throws: "Custom callout config[0] ('x') is missing required fields: className, defaultTitle, color, backgroundColor"
+ * ```
+ */
+export function validateCustomCallouts(configs, strict) {
+    const errors = [];
+    for (let i = 0; i < configs.length; i++) {
+        const c = configs[i];
+        if (!c || typeof c !== "object") {
+            errors.push(`Custom callout config[${i}] is not an object`);
+            continue;
+        }
+        const missing = [];
+        for (const field of REQUIRED_CALLOUT_FIELDS) {
+            const val = c[field];
+            if (val === undefined || val === null || (typeof val === "string" && val.trim() === "" && field !== "icon")) {
+                missing.push(field);
+            }
+        }
+        if (missing.length > 0) {
+            const name = typeof c.type === "string" ? `'${c.type}'` : `at index ${i}`;
+            const msg = `Custom callout config[${i}] (${name}) is missing required fields: ${missing.join(", ")}`;
+            errors.push(msg);
+            if (strict) {
+                throw new Error(`[remake-blocks] ${msg}`);
+            }
+        }
+    }
+    return errors;
+}
+//# sourceMappingURL=dx.js.map

package/dist/dx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dx.js","sourceRoot":"","sources":["../src/dx.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -9,6 +9,8 @@
 export { remarkRemakeBlocks, remarkCalloutBlocks, BUILTIN_CALLOUTS } from "./remark-remake-blocks.js";
 export { escapeHtml, escapeAttribute, sanitizeColor } from "./remark-remake-blocks.js";
 export { generateCss, generateMinimalThemeCss } from "./css-generator.js";
+export { CLASSES, validateCustomCallouts, suggestSimilarType } from "./dx.js";
+export type { CalloutClassName } from "./dx.js";
 export { default } from "./astro.js";
-export type { RemakeBlocksOptions, AstroRemakeBlocksOptions, CalloutConfig, CalloutType, BuiltinCalloutType, ParsedCallout, CustomCalloutType, CalloutConfigMap, } from "./types.js";
+export type { RemakeBlocksOptions, AstroRemakeBlocksOptions, CalloutConfig, CalloutType, BuiltinCalloutType, LucideIconName, ParsedCallout, CustomCalloutType, CalloutConfigMap, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAEtG,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAIvF,OAAO,EAAE,WAAW,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAG1E,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAGrC,YAAY,EACV,mBAAmB,EACnB,wBAAwB,EACxB,aAAa,EACb,WAAW,EACX,kBAAkB,EAClB,aAAa,EACb,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAEtG,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAIvF,OAAO,EAAE,WAAW,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAG1E,OAAO,EAAE,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAC9E,YAAY,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAGhD,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAGrC,YAAY,EACV,mBAAmB,EACnB,wBAAwB,EACxB,aAAa,EACb,WAAW,EACX,kBAAkB,EAClB,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -13,6 +13,8 @@ export { escapeHtml, escapeAttribute, sanitizeColor } from "./remark-remake-bloc
 // v1.7.0+: CSS generator (for advanced usage outside Astro)
 // v1.9.0+: also exports generateMinimalThemeCss for tree-shaken theme CSS
 export { generateCss, generateMinimalThemeCss } from "./css-generator.js";
+// v1.10.0+: DX utilities — CSS class constants, validation, "did you mean" suggester
+export { CLASSES, validateCustomCallouts, suggestSimilarType } from "./dx.js";
 // Astro integration (default export, re-exported for backward compatibility)
 export { default } from "./astro.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,qBAAqB;AACrB,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AACtG,kEAAkE;AAClE,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAEvF,4DAA4D;AAC5D,0EAA0E;AAC1E,OAAO,EAAE,WAAW,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAE1E,6EAA6E;AAC7E,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,qBAAqB;AACrB,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AACtG,kEAAkE;AAClE,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAEvF,4DAA4D;AAC5D,0EAA0E;AAC1E,OAAO,EAAE,WAAW,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAE1E,qFAAqF;AACrF,OAAO,EAAE,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAG9E,6EAA6E;AAC7E,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC"}

package/dist/remark-remake-blocks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"remark-remake-blocks.d.ts","sourceRoot":"","sources":["../src/remark-remake-blocks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAqC,MAAM,OAAO,CAAC;AACrE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAEtC,OAAO,KAAK,EACV,mBAAmB,EACnB,aAAa,EAId,MAAM,YAAY,CAAC;AAMpB,QAAA,MAAM,gBAAgB,EAAE,aAAa,EAyQpC,CAAC;AA4NF,iBAAS,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE5C;AAUD,iBAAS,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAW9D;AAgTD,iBAAS,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAOvC;AA08BD,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,CAAC,mBAAmB,CAAC,CAAC,EAAE,IAAI,CAkJnE,CAAC;AAiFF,eAAO,MAAM,mBAAmB,oDAAqB,CAAC;AAItD,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,aAAa,EAAE,CAAC;AAEtD,OAAO,EAAE,gBAAgB,EAAE,CAAC"}
+{"version":3,"file":"remark-remake-blocks.d.ts","sourceRoot":"","sources":["../src/remark-remake-blocks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAqC,MAAM,OAAO,CAAC;AACrE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAEtC,OAAO,KAAK,EACV,mBAAmB,EACnB,aAAa,EAId,MAAM,YAAY,CAAC;AAQpB,QAAA,MAAM,gBAAgB,EAAE,aAAa,EAyQpC,CAAC;AA0OF,iBAAS,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE5C;AAUD,iBAAS,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAW9D;AA6TD,iBAAS,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAOvC;AA89BD,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,CAAC,mBAAmB,CAAC,CAAC,EAAE,IAAI,CAgMnE,CAAC;AA2GF,eAAO,MAAM,mBAAmB,oDAAqB,CAAC;AAItD,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,aAAa,EAAE,CAAC;AAEtD,OAAO,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/remark-remake-blocks.js

@@ -14,6 +14,9 @@
  *   `allowDangerousHtml: true` in plugin options to disable escaping —
  *   only do this if you fully trust your markdown source.
  */
+import { visit } from "unist-util-visit";
+// v1.10.0: DX utilities — warnings, validation, "did you mean" suggester
+import { warn, validateCustomCallouts, suggestSimilarType } from "./dx.js";
 // ---------------------------------------------------------------------------
 // 27 Built-in callout configurations
 // ---------------------------------------------------------------------------
@@ -446,6 +449,13 @@ const DEFAULT_OPTIONS = {
     // v1.9.0 defaults — all opt-in
     icons: undefined,
     cssMinimalTheme: false,
+    // v1.10.0 defaults — devWarnings auto-resolves (undefined = auto), strict off
+    devWarnings: undefined,
+    strictConfigValidation: false,
+    // v2.0.0 defaults — roles off (all use "note"), srIconText off, ariaAccordion on
+    roles: undefined,
+    srIconText: false,
+    ariaAccordion: true,
 };
 // ---------------------------------------------------------------------------
 // Helper: Validate + normalize a single custom callout config.
@@ -693,7 +703,7 @@ function parseDirectiveAttrs(attrsBlock) {
 // ---------------------------------------------------------------------------
 // Helper: Parse the first paragraph of a blockquote to detect a callout
 // ---------------------------------------------------------------------------
-function parseCalloutDirective(blockquote, calloutPattern, configMap, enableDisclosures, defaultCollapse) {
+function parseCalloutDirective(blockquote, calloutPattern, configMap, enableDisclosures, defaultCollapse, options) {
     const firstChild = blockquote.children[0];
     if (!firstChild || firstChild.type !== "paragraph")
         return null;
@@ -708,8 +718,19 @@ function parseCalloutDirective(blockquote, calloutPattern, configMap, enableDisc
     const lowerType = rawType.toLowerCase();
     const isPullQuote = lowerType === "pull";
     const isEpigraph = lowerType === "epigraph";
-    if (!isDisclosure && !isPullQuote && !isEpigraph && !configMap.has(lowerType))
+    if (!isDisclosure && !isPullQuote && !isEpigraph && !configMap.has(lowerType)) {
+        // v1.10.0: dev warning for unknown callout types with "did you mean" suggestion
+        const devWarn = options?._devWarnings;
+        if (devWarn) {
+            const known = options?._knownTypes;
+            const suggestion = known && known.length > 0 ? suggestSimilarType(rawType, known) : null;
+            const msg = suggestion
+                ? `Unknown callout type '${rawType}'. Did you mean '${suggestion}'?`
+                : `Unknown callout type '${rawType}'. It will render as a plain blockquote.`;
+            warn(true, msg);
+        }
         return null;
+    }
     const type = isDisclosure ? "disclosure"
         : isPullQuote ? "pull"
             : isEpigraph ? "epigraph"
@@ -927,7 +948,11 @@ function buildCalloutHtml(parsed, blockquote, calloutPattern, configMap, options
     // Sanitize colors before interpolating into style attribute
     const safeIconColor = sanitizeColor(config.iconColor || config.color, "#57606a");
     // v1.2.0: WCAG fix — use role="note" for ALL callouts (was: role="alert" for warnings).
-    const ariaRole = "note";
+    // v2.0.0: per-type role override via `roles` option.
+    const roleOverride = options.roles?.[parsed.type];
+    const ariaRole = roleOverride === "none" ? "" : (roleOverride ?? "note");
+    // v2.0.0: when ariaRole is empty (role="none"), omit the attribute entirely.
+    const roleAttr = ariaRole ? ` role="${ariaRole}"` : "";
     // Escape className + calloutClass to prevent attribute breakout
     const safeCalloutClass = escapeAttribute(options.calloutClass);
     const safeConfigClassName = escapeAttribute(config.className);
@@ -1005,8 +1030,12 @@ function buildCalloutHtml(parsed, blockquote, calloutPattern, configMap, options
         : "";
     // v1.2.0: title-text always rendered (unless appearance="hidden")
     const renderTitle = appearance !== "hidden";
-    const titleTextHtml = renderTitle
-        ? `<span class="callout-title-text">${escapeHtml(title)}</span>`
+    // v2.0.0: sr-only text — prepended to title for screen readers when
+    // srIconText is enabled. Uses the callout's default title (or custom title)
+    // so screen readers announce "Warning:" even when the visual title is
+    // just an icon or when appearance="minimal" hides the text.
+    const srOnlyHtml = options.srIconText && renderTitle
+        ? `<span class="sr-only">${escapeHtml(title)}:</span>`
         : "";
     // v1.2.0: tags option (override element names)
     const tags = options.tags ?? {};
@@ -1021,10 +1050,12 @@ function buildCalloutHtml(parsed, blockquote, calloutPattern, configMap, options
         ? `<${iconTag} class="callout-icon" style="color:${safeIconColor}" aria-hidden="true">${effectiveIconHtml}</${iconTag}>`
         : "";
     // Build the title block (or skip for "hidden" appearance)
+    // v2.0.0: prepend srOnlyHtml (when srIconText is on) before the visible title text.
     const titleBlock = renderTitle
         ? [
             `  <${titleTag} class="${safeCalloutTitleClass}" style="color:${safeIconColor}" id="${titleId}">`,
             iconSpan && `    ${iconSpan}`,
+            srOnlyHtml && `    ${srOnlyHtml}`,
             `    <${titleTextTag} class="callout-title-text">${escapeHtml(title)}</${titleTextTag}>`,
             `  </${titleTag}>`,
         ].filter(Boolean).join("\n")
@@ -1040,6 +1071,7 @@ function buildCalloutHtml(parsed, blockquote, calloutPattern, configMap, options
         ? [
             `  <${titleTag} class="${safeCalloutTitleClass}" style="color:${safeIconColor}" id="${titleId}"${titleDirAuto}>`,
             iconSpan && `    ${iconSpan}`,
+            srOnlyHtml && `    ${srOnlyHtml}`,
             `    <${titleTextTag} class="callout-title-text">${escapeHtml(title)}</${titleTextTag}>`,
             `  </${titleTag}>`,
         ].filter(Boolean).join("\n")
@@ -1047,7 +1079,7 @@ function buildCalloutHtml(parsed, blockquote, calloutPattern, configMap, options
     if (parsed.collapsible) {
         const openAttr = parsed.collapsibleOpen ? " open" : "";
         return html([
-            `<${containerTag} class="${safeCalloutClass} ${safeConfigClassName} collapsible${appearanceClass}${inlineClass}${directiveClasses}"${dataAttr}${collapsibleDataAttr} role="${ariaRole}"${labelledby}${dirAuto}${openAttr}${directiveId}${extraAttrs}${directiveAttrs}>`,
+            `<${containerTag} class="${safeCalloutClass} ${safeConfigClassName} collapsible${appearanceClass}${inlineClass}${directiveClasses}"${dataAttr}${collapsibleDataAttr}${roleAttr}${labelledby}${dirAuto}${openAttr}${directiveId}${extraAttrs}${directiveAttrs}>`,
             titleBlockWithDir,
             `  <${bodyTag} class="${safeCalloutBodyClass}">`,
             bodyHtml,
@@ -1056,7 +1088,7 @@ function buildCalloutHtml(parsed, blockquote, calloutPattern, configMap, options
         ].filter(Boolean).join("\n"));
     }
     return html([
-        `<${containerTag} class="${safeCalloutClass} ${safeConfigClassName}${appearanceClass}${inlineClass}${directiveClasses}"${dataAttr}${collapsibleDataAttr} role="${ariaRole}"${labelledby}${dirAuto}${directiveId}${extraAttrs}${directiveAttrs}>`,
+        `<${containerTag} class="${safeCalloutClass} ${safeConfigClassName}${appearanceClass}${inlineClass}${directiveClasses}"${dataAttr}${collapsibleDataAttr}${roleAttr}${labelledby}${dirAuto}${directiveId}${extraAttrs}${directiveAttrs}>`,
         titleBlockWithDir,
         `  <${bodyTag} class="${safeCalloutBodyClass}">`,
         bodyHtml,
@@ -1548,7 +1580,10 @@ function buildCalloutFromParts(parsed, config, bodyHtml, options) {
     const dataAttr = options.dataCalloutType ? ` data-callout-type="${escapeAttribute(parsed.type)}"` : "";
     const collapsibleDataAttr = ` data-collapsible="${parsed.collapsible ? "true" : "false"}"`;
     const safeIconColor = sanitizeColor(config.iconColor || config.color, "#57606a");
-    const ariaRole = "note";
+    // v2.0.0: per-type role override via `roles` option (same logic as buildCalloutHtml).
+    const roleOverride = options.roles?.[parsed.type];
+    const ariaRole = roleOverride === "none" ? "" : (roleOverride ?? "note");
+    const roleAttr = ariaRole ? ` role="${ariaRole}"` : "";
     const safeCalloutClass = escapeAttribute(options.calloutClass);
     const safeConfigClassName = escapeAttribute(config.className);
     const safeCalloutTitleClass = escapeAttribute(options.calloutTitleClass);
@@ -1588,10 +1623,15 @@ function buildCalloutFromParts(parsed, config, bodyHtml, options) {
     const labelledby = renderTitle ? ` aria-labelledby="${titleId}"` : "";
     const appearanceClass = appearance !== "default" ? ` callout-${appearance}` : "";
     const inlineClass = parsed.overrides?.inline ? ` callout-${parsed.overrides.inline}` : "";
+    // v2.0.0: sr-only text (same as buildCalloutHtml)
+    const srOnlyHtml = options.srIconText && renderTitle
+        ? `<span class="sr-only">${escapeHtml(title)}:</span>`
+        : "";
     const titleBlock = renderTitle
         ? [
             `  <div class="${safeCalloutTitleClass}" style="color:${safeIconColor}" id="${titleId}" dir="auto">`,
             iconSpan && `    ${iconSpan}`,
+            srOnlyHtml && `    ${srOnlyHtml}`,
             `    <span class="callout-title-text">${escapeHtml(title)}</span>`,
             `  </div>`,
         ].filter(Boolean).join("\n")
@@ -1599,7 +1639,7 @@ function buildCalloutFromParts(parsed, config, bodyHtml, options) {
     if (parsed.collapsible) {
         const openAttr = parsed.collapsibleOpen ? " open" : "";
         return [
-            `<details class="${safeCalloutClass} ${safeConfigClassName} collapsible${appearanceClass}${inlineClass}${directiveClasses}"${dataAttr}${collapsibleDataAttr} role="${ariaRole}"${labelledby} dir="auto"${openAttr}${directiveId}${directiveAttrs}>`,
+            `<details class="${safeCalloutClass} ${safeConfigClassName} collapsible${appearanceClass}${inlineClass}${directiveClasses}"${dataAttr}${collapsibleDataAttr}${roleAttr}${labelledby} dir="auto"${openAttr}${directiveId}${directiveAttrs}>`,
             titleBlock.replace(/<div /, "<summary ").replace(/<\/div>$/, "</summary>"),
             `  <div class="${safeCalloutBodyClass}">`,
             bodyHtml,
@@ -1608,7 +1648,7 @@ function buildCalloutFromParts(parsed, config, bodyHtml, options) {
         ].filter(Boolean).join("\n");
     }
     return [
-        `<aside class="${safeCalloutClass} ${safeConfigClassName}${appearanceClass}${inlineClass}${directiveClasses}"${dataAttr}${collapsibleDataAttr} role="${ariaRole}"${labelledby} dir="auto"${directiveId}${directiveAttrs}>`,
+        `<aside class="${safeCalloutClass} ${safeConfigClassName}${appearanceClass}${inlineClass}${directiveClasses}"${dataAttr}${collapsibleDataAttr}${roleAttr}${labelledby} dir="auto"${directiveId}${directiveAttrs}>`,
         titleBlock,
         `  <div class="${safeCalloutBodyClass}">`,
         bodyHtml,
@@ -1624,6 +1664,19 @@ export const remarkRemakeBlocks = (userOptions) => {
         ...DEFAULT_OPTIONS,
         ...userOptions,
     };
+    // v1.10.0: resolve devWarnings. undefined → auto (true in dev, false in prod).
+    const isProd = typeof process !== "undefined" && process.env && process.env.NODE_ENV === "production";
+    const devWarningsEnabled = options.devWarnings === undefined ? !isProd : options.devWarnings;
+    // v1.10.0: strict customCallouts validation. Throws at init time when
+    // strictConfigValidation is true and any config entry is missing required
+    // fields. In non-strict mode, emits a dev warning instead.
+    if (options.customCallouts && options.customCallouts.length > 0) {
+        const errors = validateCustomCallouts(options.customCallouts, options.strictConfigValidation);
+        if (errors.length > 0 && !options.strictConfigValidation) {
+            for (const e of errors)
+                warn(devWarningsEnabled, e);
+        }
+    }
     // v1.8.0: resolve `syntax` into enableDirectiveSyntax / enableMkDocsSyntax.
     // Explicit `enableDirectiveSyntax` / `enableMkDocsSyntax` (v1.3.0 / v1.4.0
     // API) take precedence over `syntax` for backward compatibility.
@@ -1643,6 +1696,10 @@ export const remarkRemakeBlocks = (userOptions) => {
     }
     const configMap = buildCalloutConfigMap(options);
     const calloutPattern = options.calloutPattern || buildCalloutPattern(configMap, options.enableDisclosures);
+    // v1.10.0: stash devWarnings flag + known types list on options so
+    // buildCalloutHtml / parseCalloutDirective can emit warnings.
+    options._devWarnings = devWarningsEnabled;
+    options._knownTypes = Array.from(configMap.keys());
     // v1.9.0: sprite collector — accumulates { symbolId: svgInnerHtml } entries
     // across all callouts in this document. Populated by buildCalloutHtml when
     // icons.strategy === 'sprite'. Emitted as a single <svg> sprite at the top
@@ -1667,6 +1724,37 @@ export const remarkRemakeBlocks = (userOptions) => {
         if (options.enableMkDocsSyntax) {
             transformMkDocsSyntax(tree, configMap, options);
         }
+        // v1.10.0: Pass 0c — Scan for unknown callout directives and emit dev warnings.
+        // The calloutPattern only matches KNOWN types, so unknown types like
+        // [!TYPO] fall through to plain blockquotes WITHOUT entering parseCalloutDirective.
+        // This pre-scan catches them so users get a "did you mean" hint.
+        if (devWarningsEnabled) {
+            const knownTypes = options._knownTypes;
+            const anyDirectiveRe = /^\[!([A-Za-z][A-Za-z0-9-]*)\]/;
+            visit(tree, "blockquote", (bq) => {
+                const first = bq.children[0];
+                if (!first || first.type !== "paragraph")
+                    return;
+                const text = extractTextContent(first);
+                if (!text)
+                    return;
+                const m = text.match(anyDirectiveRe);
+                if (!m)
+                    return;
+                const rawType = m[1];
+                const lowerType = rawType.toLowerCase();
+                // Skip disclosures (empty type), pull quotes, epigraphs, and known types
+                if (lowerType === "" || lowerType === "pull" || lowerType === "epigraph")
+                    return;
+                if (configMap.has(lowerType))
+                    return;
+                const suggestion = suggestSimilarType(rawType, knownTypes);
+                const msg = suggestion
+                    ? `Unknown callout type '${rawType}'. Did you mean '${suggestion}'?`
+                    : `Unknown callout type '${rawType}'. It will render as a plain blockquote.`;
+                warn(true, msg);
+            });
+        }
         // ── Pass 1: Transform blockquotes → callouts / disclosures ──────
         // We must process DEEPEST blockquotes first (inside-out) so that
         // nested [!] directives are converted before their parents read them.
@@ -1703,7 +1791,7 @@ export const remarkRemakeBlocks = (userOptions) => {
                 if (foundIdx === -1)
                     continue; // Already replaced
             }
-            const parsed = parseCalloutDirective(bq, calloutPattern, configMap, options.enableDisclosures, options.defaultCollapse);
+            const parsed = parseCalloutDirective(bq, calloutPattern, configMap, options.enableDisclosures, options.defaultCollapse, options);
             if (parsed) {
                 // For disclosures: depth > 0 means it's nested inside another blockquote
                 // (which is likely another disclosure or callout) → tree view
@@ -1733,7 +1821,7 @@ export const remarkRemakeBlocks = (userOptions) => {
         }
         // ── Pass 2: Group consecutive disclosures into accordions ───────
         if (options.enableAccordion && options.enableDisclosures) {
-            groupAccordions(tree, options.accordionClass);
+            groupAccordions(tree, options.accordionClass, options.ariaAccordion);
         }
         // v1.9.0: Pass 3 — Emit icon sprite at the top of the document.
         // Only when icons.strategy === 'sprite' AND at least one callout
@@ -1753,7 +1841,7 @@ export const remarkRemakeBlocks = (userOptions) => {
 // ---------------------------------------------------------------------------
 // Pass 2: Group consecutive disclosure <details> into accordion wrapper
 // ---------------------------------------------------------------------------
-function groupAccordions(tree, accordionClass) {
+function groupAccordions(tree, accordionClass, ariaAccordion) {
     function walk(node) {
         if (!node.children)
             return;
@@ -1784,9 +1872,28 @@ function groupAccordions(tree, accordionClass) {
                 }
                 // If we found 2+ consecutive disclosures, wrap in accordion
                 if (group.length >= 2) {
+                    // v2.0.0: when ariaAccordion is enabled, add role="accordion" to the
+                    // wrapper and aria-expanded to each <summary> (reflecting open state).
+                    // Also add tabindex="0" to <summary> if not already focusable (native
+                    // summary is focusable by default, but explicit tabindex aids older
+                    // browsers and signals intent for the accordion.js keyboard handler).
+                    const accordionRole = ariaAccordion ? ` role="accordion"` : "";
+                    let groupHtml = group;
+                    if (ariaAccordion) {
+                        groupHtml = group.map(detailsHtml => {
+                            // Inject aria-expanded onto each <summary> based on whether the
+                            // parent <details> has the `open` attribute.
+                            const isOpen = /<details[^>]*\sopen[\s>]/.test(detailsHtml);
+                            const expanded = isOpen ? "true" : "false";
+                            if (/<summary[^>]*>/.test(detailsHtml)) {
+                                return detailsHtml.replace(/(<summary[^>]*?)(>)/, `$1 aria-expanded="${expanded}"$2`);
+                            }
+                            return detailsHtml;
+                        });
+                    }
                     const accordionHtml = [
-                        `<div class="${escapeAttribute(accordionClass)}" data-accordion>`,
-                        ...group,
+                        `<div class="${escapeAttribute(accordionClass)}"${accordionRole} data-accordion>`,
+                        ...groupHtml,
                         `</div>`,
                     ].join("\n");
                     newChildren.push(html(accordionHtml));
@@ -1816,8 +1923,15 @@ function groupAccordions(tree, accordionClass) {
  */
 function isDisclosureHtml(htmlStr) {
     const trimmed = htmlStr.trim();
+    // v2.0.0: fix pre-existing bug — the old `!trimmed.includes('callout')` check
+    // accidentally rejected ALL disclosures because their HTML contains
+    // `aria-labelledby="callout-disclosure-N"`. The intent was to exclude
+    // callout-details (which have `class="callout ..."`) from accordion grouping.
+    // The correct check: the details element must have class="disclosure" (the
+    // exact disclosure class) and NOT have the `callout` class (which would make
+    // it a collapsible callout instead).
     return trimmed.startsWith('<details class="disclosure"') &&
-        !trimmed.includes('callout');
+        !trimmed.startsWith('<details class="disclosure-accordion"');
 }
 // ---------------------------------------------------------------------------
 // Backward-compatible alias