{
  "name": "DotMatrix",
  "package": "@magicblocksai/ui",
  "file": "packages/ui/src/components/DotMatrix.tsx",
  "chapterTag": "11 Narrative Systems",
  "chapter": "12-narrative-systems.html",
  "sectionId": "dot-matrix",
  "elName": "Two systems, side by side",
  "demoUrl": "https://brand.magicblocks.ai/components/12-narrative-systems#dot-matrix",
  "hasLiveDemo": false,
  "description": "Proportion visualisation — a grid of dots where a subset is highlighted\nto communicate \"out of N, M did X\". The 1000-dot 40×25 grid is the\ncanonical default (one dot per lead in a 1k-lead sample); resize via\n`total` / `cols` for other ratios.",
  "useClient": false,
  "interactivity": "display",
  "namedExports": [
    {
      "name": "DotMatrix",
      "isPrincipal": true,
      "isType": false
    },
    {
      "name": "DotMatrixProps",
      "isPrincipal": false,
      "isType": true
    }
  ],
  "importStatement": "import { DotMatrix } from \"@magicblocksai/ui\";",
  "props": [
    {
      "name": "total",
      "optional": true,
      "type": "number",
      "doc": "Total number of dots. Default `1000`."
    },
    {
      "name": "highlight",
      "optional": false,
      "type": "number",
      "doc": "Number of highlighted dots."
    },
    {
      "name": "cols",
      "optional": true,
      "type": "number",
      "doc": "Number of grid columns. Default `40` (40×25 = 1000 default)."
    },
    {
      "name": "highlightColor",
      "optional": true,
      "type": "string",
      "doc": "CSS colour for highlighted dots. Defaults to `var(--accent)`."
    },
    {
      "name": "baseColor",
      "optional": true,
      "type": "string",
      "doc": "CSS colour for base dots. Defaults to `var(--bg-warm)`."
    },
    {
      "name": "distribution",
      "optional": true,
      "type": "\"scatter\" | \"head\" | \"tail\" | \"random\"",
      "doc": "How to distribute the highlighted dots through the grid. `\"scatter\"` (default) spaces them evenly so the highlight reads as a proportion rather than a clump. `\"head\"` puts them at the start, `\"tail\"` at the end, `\"random\"` uses a deterministic PRNG seeded by `total` + `highlight`."
    },
    {
      "name": "aria-label",
      "optional": true,
      "type": "string",
      "doc": "Accessible label (e.g. `\"25 of 1000 leads lost to agent errors\"`). Falls back to a generated `\"N of M highlighted\"` string."
    }
  ],
  "classesUsed": [
    "dot-matrix",
    "dot-matrix-cell"
  ],
  "examples": {
    "react": "<DotMatrix\n  total={1000}\n  highlight={25}\n  highlightColor=\"var(--accent)\"\n  aria-label=\"25 of 1,000 leads lost to agent errors\"\n/>",
    "html": "<div class=\"dot-matrix-compare\">\n                <div class=\"dmc-side\">\n                  <h4 class=\"dmc-title\">MagicBlocks</h4>\n                  <p class=\"dmc-caption\"><strong>~25 lost</strong> to agent errors.</p>\n                  <div class=\"dot-matrix\" role=\"img\" aria-label=\"25 of 1,000 leads lost on MagicBlocks\" style=\"--dm-cols:40;\">\n                    <!-- 1,000 cells emitted by JS at chapter-load time -->\n                  </div>\n                </div>\n                <div class=\"dmc-side\">\n                  <h4 class=\"dmc-title\">OnePrompt</h4>\n                  <p class=\"dmc-caption\"><strong>~410 lost</strong> to agent errors.</p>\n                  <div class=\"dot-matrix\" role=\"img\" aria-label=\"410 of 1,000 leads lost on OnePrompt\" style=\"--dm-cols:40;\">\n                    <!-- 1,000 cells emitted by JS at chapter-load time -->\n                  </div>\n                </div>\n              </div>",
    "css": ".dot-matrix {\n  display: grid;\n  grid-template-columns: repeat(var(--dm-cols, 40), 1fr);\n  gap: var(--dm-gap, 3px);\n  margin-top: var(--s-4);\n}\n\n.dot-matrix-cell {\n  width: 100%;\n  aspect-ratio: 1 / 1;\n  border-radius: 2px;\n  background: var(--dm-base, var(--bg-warm));\n  opacity: 0.45;\n}"
  }
}