{"_id":"@bsol-oss/mathdiagram","name":"@bsol-oss/mathdiagram","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@bsol-oss/mathdiagram","version":"0.1.0","description":"React SVG renderer for declarative exam-style math and geometry diagrams.","type":"module","license":"MIT","repository":{"type":"git","url":"git+https://github.com/chassis-app/mathdiagram.git"},"homepage":"https://github.com/chassis-app/mathdiagram#readme","bugs":{"url":"https://github.com/chassis-app/mathdiagram/issues"},"main":"./dist-lib/mathdiagram.umd.cjs","module":"./dist-lib/mathdiagram.js","exports":{".":{"import":"./dist-lib/mathdiagram.js","require":"./dist-lib/mathdiagram.umd.cjs"},"./style.css":"./dist-lib/mathdiagram.css"},"sideEffects":["*.css","**/*.css"],"scripts":{"dev":"vite --host 0.0.0.0","build":"npm run build:app && npm run build:lib","build:app":"vite build","build:lib":"vite build --config vite.lib.config.js","preview":"vite preview --host 0.0.0.0","prepublishOnly":"npm run build:lib"},"peerDependencies":{"react":">=18","react-dom":">=18"},"devDependencies":{"@vitejs/plugin-react":"latest","d3":"latest","jsxgraph":"latest","p5":"latest","plotly.js-dist-min":"latest","react":"latest","react-dom":"latest","vite":"latest"},"gitHead":"ee2cbd143c12fe3ffec3a5cee05b2e0cf07e811a","_id":"@bsol-oss/mathdiagram@0.1.0","_nodeVersion":"24.14.0","_npmVersion":"11.9.0","dist":{"integrity":"sha512-eaSZ/rpr/jMBmWAI28Q/05tyvJVvNIqbAWbyU03oJj8AFkEOj3iikGBNA7QGIFXq2jdxmXjwEu80RCGi2lwx7g==","shasum":"927cf6e2afad09367dd57851e99f64fc0927de0a","tarball":"https://registry.npmjs.org/@bsol-oss/mathdiagram/-/mathdiagram-0.1.0.tgz","fileCount":22,"unpackedSize":223760,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGMFyeDMkAQvQ7LVNyzMwB+soWRnUrHVJiUBUNshz8DWAiEAh63rls+7sU1DW2LVq9wh4g+n761qJRqJmL7RUHPLIb4="}]},"_npmUser":{"name":"rossbsol","email":"ross@bsoltec.com"},"directories":{},"maintainers":[{"name":"wilgod","email":"wilson.kwan@w3bvolution.com"},{"name":"rossbsol","email":"ross@bsoltec.com"},{"name":"omiq17","email":"omiq17@gmail.com"},{"name":"jyotipadhi","email":"jyotipadhi1@gmail.com"},{"name":"jacky-ng-w3b","email":"jacky.ng@w3bvolution.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mathdiagram_0.1.0_1777897925107_0.33223917340064935"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-04T12:32:04.991Z","0.1.0":"2026-05-04T12:32:05.246Z","modified":"2026-05-04T12:32:05.561Z"},"maintainers":[{"name":"wilgod","email":"wilson.kwan@w3bvolution.com"},{"name":"rossbsol","email":"ross@bsoltec.com"},{"name":"omiq17","email":"omiq17@gmail.com"},{"name":"jyotipadhi","email":"jyotipadhi1@gmail.com"},{"name":"jacky-ng-w3b","email":"jacky.ng@w3bvolution.com"}],"description":"React SVG renderer for declarative exam-style math and geometry diagrams.","homepage":"https://github.com/chassis-app/mathdiagram#readme","repository":{"type":"git","url":"git+https://github.com/chassis-app/mathdiagram.git"},"bugs":{"url":"https://github.com/chassis-app/mathdiagram/issues"},"license":"MIT","readme":"# MathDiagram\n\nMathDiagram is a React SVG diagram renderer for student-friendly math and geometry diagrams. It is built for plain Vite/React projects and uses local SVG rendering only: no hosted embeds, no Three.js, no Babylon.js, and no commercial diagram platform.\n\nThe core idea is simple: pass a JSON-friendly `spec` object to `<MathDiagram />`, and the renderer draws the matching 2D or 3D exam-style diagram.\n\n## Quick Start\n\nInstall and run this repo:\n\n```bash\nnpm install\nnpm run dev\n```\n\nOpen the demo app and go to `#/mathdiagram/3d-solids` to see the live editable MathDiagram examples.\n\n## Use In React\n\nInstall the package:\n\n```bash\nnpm install @bsol-oss/mathdiagram\n```\n\nImport the component and stylesheet in any React/Vite app:\n\n```jsx\nimport { MathDiagram } from '@bsol-oss/mathdiagram';\nimport '@bsol-oss/mathdiagram/style.css';\n\nexport function Example() {\n  return <MathDiagram spec={{\n    kind: 'volume',\n    shape: 'rectangular_prism',\n    color: 'green',\n    arrowColor: 'auto',\n    canvas: {\n      width: 420,\n      height: 270,\n      fit: 'contain',\n      padding: 32\n    },\n    dimensions: {\n      length: 4,\n      width: 3,\n      height: 2,\n      unit: 'cm'\n    },\n    view: {\n      azimuth: 45,\n      elevation: 30\n    },\n    header: {\n      text: 'V = l x w x h',\n      position: 'left-upper'\n    }\n  }} />;\n}\n```\n\nThe current repo also keeps the library source in `src/diagrams` for local development. If you do not want to use npm yet, copy that folder into another React project and import `./diagrams/MathDiagram.jsx` directly.\n\nYou can also render from JSON:\n\n```jsx\nconst spec = JSON.parse(jsonText);\n\n<MathDiagram spec={spec} />\n```\n\n## Component API\n\n`MathDiagram` currently accepts one prop:\n\n| Prop | Type | Description |\n| --- | --- | --- |\n| `spec` | object | Declarative diagram configuration. Must include `shape`. |\n\nIf the spec is invalid, the component renders a visible validation error instead of throwing.\n\n## Spec Model\n\nCommon top-level keys:\n\n| Key | Type | Description |\n| --- | --- | --- |\n| `shape` | string | Diagram renderer to use, such as `rectangle`, `cube`, or `triangular_prism`. |\n| `kind` | string | Optional teaching context, usually `volume`. Net diagrams are not supported. |\n| `dimensions` | object | Numeric dimensions and `unit`. These drive labels and proportional geometry. |\n| `layoutDimensions` | object | Numeric fallback dimensions for unknown values like `height: '?'`. |\n| `unknowns` | string[] | Dimension keys to display as unknowns. |\n| `measurements` | array | Optional list of dimension arrows/labels to show. |\n| `canvas` | object | SVG output size and scaling behavior. |\n| `view` | object/string | 3D viewing angle for supported 3D shapes. |\n| `color` | string | Per-shape color name. |\n| `arrowColor` | string | `auto` or a supported color name for dimension arrows. |\n| `header` | object | Annotation badge with `text` and named `position`. |\n| `remarks` | object | Secondary annotation badge with `text` and named `position`. |\n| `labels` | array | Extra annotation badges. |\n| `alt` | string | Accessible label for the SVG. |\n\n## Canvas Sizing\n\nUse `canvas.width` and `canvas.height` to specify the rendered SVG size. The default `fit: 'contain'` scales the internal diagram coordinate system into that canvas.\n\n```js\ncanvas: {\n  width: 420,\n  height: 270,\n  fit: 'contain',\n  padding: 32\n}\n```\n\nUse `viewBoxWidth` and `viewBoxHeight` only when you need a custom SVG coordinate space:\n\n```js\ncanvas: {\n  width: 520,\n  height: 300,\n  viewBoxWidth: 520,\n  viewBoxHeight: 300,\n  padding: 36\n}\n```\n\n## Supported Shapes\n\n2D shapes:\n\n- `rectangle`\n- `square`\n- `triangle`\n- `right_triangle`\n- `circle`\n- `trapezoid`\n- `parallelogram`\n- `regular_polygon`\n- `composite_2d`\n\n3D solids:\n\n- `rectangular_prism`\n- `cube`\n- `cylinder`\n- `cone`\n- `square_pyramid`\n- `rectangular_pyramid`\n- `triangular_prism`\n- `sphere`\n- `hemisphere`\n- `capsule`\n- `triangular_pyramid`\n- `frustum_cone`\n- `frustum_pyramid`\n- `composite_3d`\n\nLegacy `shape: 'composite'` is still routed to the 3D composite renderer, but new specs should use `composite_3d`.\n\n## Dimension Names\n\nPreferred public dimension keys:\n\n| Shape | Dimensions |\n| --- | --- |\n| `rectangle` | `length`, `width`, `unit` |\n| `square` | `side`, `unit` |\n| `triangle` | `base`, `height`, `topOffset`, `unit` |\n| `right_triangle` | `base`, `height`, `hypotenuse`, `unit` |\n| `circle` | `radius`, `unit` |\n| `trapezoid` | `bottomBase`, `topBase`, `height`, `unit` |\n| `parallelogram` | `base`, `height`, `side`, `unit` |\n| `regular_polygon` | `sides`, `side`, `unit` |\n| `rectangular_prism` | `length`, `width`, `height`, `unit` |\n| `cube` | `side`, `unit` |\n| `cylinder` | `radius`, `height`, `unit` |\n| `cone` | `radius`, `height`, `slantHeight`, `unit` |\n| `square_pyramid` | `baseSide`, `height`, `unit` |\n| `rectangular_pyramid` | `length`, `width`, `height`, `unit` |\n| `triangular_prism` | `base`, `triangleHeight`, `length`, `unit` |\n| `triangular_pyramid` | `base`, `baseHeight`, `height`, `unit` |\n| `frustum_cone` | `topRadius`, `bottomRadius`, `height`, `unit` |\n| `frustum_pyramid` | `topLength`, `topWidth`, `bottomLength`, `bottomWidth`, `height`, `unit` |\n\n`topOffset` means the horizontal distance from the left base endpoint to the vertical foot of the triangle's top vertex. If omitted, the triangle defaults to an isosceles layout with `topOffset = base / 2`.\n\nOlder aliases such as `apexX`, `legA`, `legB`, `baseA`, `baseB`, and `sideLength` are kept internally for compatibility, but new JSON should use the clearer names above.\n\n## Measurements And Unknowns\n\nBy default, renderers show their standard measurements. You can restrict or relabel them with `measurements`:\n\n```js\nmeasurements: [\n  { target: 'base' },\n  { target: 'height', label: 'h = ?' }\n]\n```\n\nFor exam questions with unknown values, put the visible value in `dimensions`, provide a numeric fallback in `layoutDimensions`, and list the unknown key in `unknowns`:\n\n```js\n{\n  shape: 'triangle',\n  dimensions: { base: 8, height: '?', topOffset: 3, unit: 'cm' },\n  layoutDimensions: { height: 5 },\n  unknowns: ['height'],\n  measurements: [\n    { target: 'base' },\n    { target: 'height', label: 'h = ?' }\n  ]\n}\n```\n\n## Annotations\n\nUse `header`, `remarks`, and `labels` for diagram text. They use named positions instead of exact coordinates.\n\n```js\nheader: { text: 'A = 1/2 bh', position: 'left-upper' },\nremarks: { text: 'Find h', position: 'right-lower' },\nlabels: [{ text: 'radius shown', position: 'right-lower' }]\n```\n\nSupported positions:\n\n- `left-upper`\n- `center-upper`\n- `right-upper`\n- `left-middle`\n- `center-middle`\n- `right-middle`\n- `left-lower`\n- `center-lower`\n- `right-lower`\n\n## Colors\n\nUse one `color` per shape. Composite diagrams can set `color` per part.\n\nSupported color names:\n\n- `blue`\n- `sky`\n- `cyan`\n- `green`\n- `lime`\n- `yellow`\n- `orange`\n- `red`\n- `pink`\n- `purple`\n- `slate`\n- `neutral`\n\nUse `arrowColor: 'auto'` for contrast-friendly dimension arrows, or override it with one of the supported color names.\n\n## 3D Viewing Angle\n\nSupported 3D renderers accept either a preset string or an angle object:\n\n```js\nview: { azimuth: 45, elevation: 30 }\n```\n\nPresets:\n\n- `isometric`\n- `textbook`\n- `front`\n- `right`\n- `top`\n- `left`\n- `right_down`\n- `left_down`\n\n## Composite Examples\n\n2D additive composite:\n\n```js\n{\n  shape: 'composite_2d',\n  operation: 'add',\n  parts: [\n    { shape: 'rectangle', color: 'blue', dimensions: { length: 8, width: 4, unit: 'cm' }, position: { x: 0, y: 0 } },\n    { shape: 'rectangle', color: 'orange', dimensions: { length: 3, width: 5, unit: 'cm' }, position: { x: 0, y: 4 } }\n  ]\n}\n```\n\n3D additive composite:\n\n```js\n{\n  shape: 'composite_3d',\n  operation: 'add',\n  view: { azimuth: 45, elevation: 30 },\n  canvas: { width: 520, height: 300 },\n  parts: [\n    { id: 'A', shape: 'rectangular_prism', color: 'blue', dimensions: { length: 8, width: 4, height: 2, unit: 'cm' }, position: { x: 0, y: 0, z: 0 } },\n    { id: 'B', shape: 'rectangular_prism', color: 'orange', dimensions: { length: 3, width: 4, height: 5, unit: 'cm' }, position: { x: 5, y: 0, z: 2 } }\n  ]\n}\n```\n\n## Validation\n\nRun a production build:\n\n```bash\nnpm run build\n```\n\nThe current app also includes live JSON editors on the MathDiagram page so you can test each supported shape interactively.\n","readmeFilename":"README.md","_rev":"1-ca6b43c38be984ba2a07a0c7b0864938"}