{"_id":"@avesbox/canary","name":"@avesbox/canary","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@avesbox/canary","version":"0.1.0","type":"module","description":"A vitepress transformer for rendering Dart code examples with advanced features like inline annotations, custom types, and enhanced syntax highlighting.","author":{"name":"Francesco Vallone"},"license":"MIT","sideEffects":false,"exports":{".":"./dist/index.mjs","./style.css":"./style.css"},"main":"./dist/index.mjs","module":"./dist/index.mjs","types":"./dist/index.d.mts","dependencies":{"@types/hast":"^3.0.4","hast-util-to-html":"^9.0.5","shiki":"^3.20.0","typescript":"^5.6.3","vue":"^3.5.26"},"scripts":{"test":"vitest run","build":"unbuild","dev":"unbuild --stub","prepublishOnly":"nr build"},"directories":{"example":"example","test":"test"},"devDependencies":{"unbuild":"^3.6.1"},"repository":{"type":"git","url":"git+https://github.com/francescovallone/canary.git"},"keywords":["vitepress-plugin","shiki"],"bugs":{"url":"https://github.com/francescovallone/canary/issues"},"homepage":"https://github.com/francescovallone/canary#readme","_id":"@avesbox/canary@0.1.0","gitHead":"babd932ab128fb716d80b5d1542d0114338dbf3a","_nodeVersion":"22.20.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-QRZatC1mFHIKXvRydM+SL8stqFUbBSwpXrcqmhIr8I3O6PwEnHoAKcT+A+kFly2P8CDSKCSu0Iq0I5U1GyxDlQ==","shasum":"51d97cb5e75c93ea11c4c6c1a9ac5ddbb96b0ee9","tarball":"https://registry.npmjs.org/@avesbox/canary/-/canary-0.1.0.tgz","fileCount":6,"unpackedSize":233478,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC0Tc7Iy/tPmqazXOf7iL6bkY5A1ZVXngJgF0v+bbsZSwIgafVk8EzDFRbZUwKnpSjOVbVxP1nmetjLeE8legFCilQ="}]},"_npmUser":{"name":"francescovallone","email":"vallonefrancesco587@gmail.com"},"maintainers":[{"name":"francescovallone","email":"vallonefrancesco587@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/canary_0.1.0_1768936395181_0.09826412108904758"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-20T19:13:15.033Z","0.1.0":"2026-01-20T19:13:15.324Z","modified":"2026-01-20T19:13:15.555Z"},"maintainers":[{"name":"francescovallone","email":"vallonefrancesco587@gmail.com"}],"description":"A vitepress transformer for rendering Dart code examples with advanced features like inline annotations, custom types, and enhanced syntax highlighting.","homepage":"https://github.com/francescovallone/canary#readme","keywords":["vitepress-plugin","shiki"],"repository":{"type":"git","url":"git+https://github.com/francescovallone/canary.git"},"author":{"name":"Francesco Vallone"},"bugs":{"url":"https://github.com/francescovallone/canary/issues"},"license":"MIT","readme":"# Canary\r\n\r\nLightweight Shiki transformer to add Dart code inspection hovers in VitePress.\r\n\r\n## What it does\r\n\r\n- Lexes Dart code blocks to identify declarations and expressions.\r\n- Builds a simple CST and scope tree to track variable and type information.\r\n- Adds hover popovers showing inferred types and documentation for variables, members, and expressions.\r\n\r\n## How to use\r\n\r\nGo to `.vitepress/config.mts` and add the `canaryTransformer` to the list of code transformers:\r\n\r\n```ts\r\n// .vitepress/config.mts\r\nimport { canaryTransformer } from '@avesbox/canary'\r\nexport default defineConfig({\r\n  markdown: {\r\n    codeTransformers: [canaryTransformer()],\r\n  },\r\n})\r\n```\r\n\r\nThe transformer will automatically apply to all Dart code blocks (```dart). If you wish for it to only apply to specific code blocks, you can use the canary directive and add the parameter explicitTrigger set to true:\r\n\r\n```ts\r\n// .vitepress/config.mts\r\nimport { canaryTransformer } from '@avesbox/canary'\r\n\r\nexport default defineConfig({\r\n  markdown: {\r\n    codeTransformers: [canaryTransformer({ explicitTrigger: true })],\r\n  },\r\n})\r\n```\r\n\r\nThen in your markdown files, use the `canary` directive in the code fence:\r\n\r\n```dart canary\r\nfinal message = \"Hello, Canary!\";\r\nmessage.length;\r\n```\r\n\r\nThen in your theme file, initialize the Canary theme enhancements:\r\n\r\n```ts\r\n// .vitepress/theme/index.ts\r\nimport { setupCanaryTheme } from '@avesbox/canary'\r\nimport '@avesbox/canary/style.css'\r\n\r\nexport default {\r\n  extends: DefaultTheme,\r\n  Layout,\r\n  enhanceApp(ctx) {\r\n    DefaultTheme?.enhanceApp?.(ctx)\r\n    setupCanaryTheme()\r\n  },\r\n}\r\n```\r\n\r\nUse regular ```dart fences; no custom fence syntax is needed.\r\n\r\n## Custom Types\r\n\r\nYou can define external types for the inspector to recognize. This is useful for documenting framework types that aren't defined in the code block itself.\r\n\r\n### Inline configuration\r\n\r\n```ts\r\n// .vitepress/config.mts\r\nimport { canaryTransformer, defineCustomTypes } from '@avesbox/canary'\r\n\r\nconst customTypes = defineCustomTypes({\r\n  types: [\r\n    {\r\n      name: 'Provider',\r\n      description: 'A dependency injection container.',\r\n      members: {\r\n        get: { type: 'T', description: 'Retrieves an instance of type T.' },\r\n        has: 'bool',\r\n      },\r\n      staticMembers: {\r\n        of: { type: 'Provider', description: 'Returns the nearest Provider.' },\r\n      },\r\n    },\r\n    {\r\n      name: 'Request',\r\n      description: 'Represents an HTTP request.',\r\n      members: {\r\n        method: 'String',\r\n        path: 'String',\r\n        body: { type: 'dynamic', description: 'The parsed request body.' },\r\n      },\r\n    },\r\n  ],\r\n})\r\n\r\nexport default defineConfig({\r\n  markdown: {\r\n    codeTransformers: [canaryTransformer({ customTypes })],\r\n  },\r\n})\r\n```\r\n\r\nWhen a custom type is used in code, the inspector will:\r\n\r\n1. Recognize the type name and show its description on hover\r\n2. Resolve member access (e.g., `request.body`) with the correct type and description\r\n3. Include the type in variable inference (e.g., `final req = Request()` → `req: Request`)\r\n","readmeFilename":"README.md","_rev":"1-8eae3d422a5affc6b8d238130dcbdc3b"}