shareable-twoslash-comments 0.0.1

package/.prettierrc

@@ -0,0 +1,3 @@
+{
+  "printWidth": 100
+}

package/CONTRIBUTING.md

@@ -0,0 +1,66 @@
+## Contributing to a TypeScript Playground Plugin
+
+## Contributing
+
+You can use `pnpm start` to set up both a copy of Rollup to generate the JS, and Serve to host it.
+
+```sh
+pnpm start
+```
+
+Then set up the TypeScript playground to connect to a dev plugin at `http://localhost:5000/`.
+
+#### Plugin API
+
+The plugin API is documented in the [interface PlaygroundPlugin in `./src/index.ts`](src/index.ts).
+
+Roughly:
+
+- There are a set of mounting and un-mounting functions which you can use to handle your UI in the sidebar
+- There are `modelChanged` methods, which are shortcuts to knowing when the code in monaco editor has changed
+
+### Sandbox
+
+The plugins are passed copies of the TypeScript sandbox, which is a high level API wrapper to the [`monaco-editor`](https://microsoft.github.io/monaco-editor/). You can learn more about the sandbox on [the TypeScript website](http://www.typescriptlang.org/v2/dev/sandbox/).
+
+#### Rollup
+
+[Rollup](https://rollupjs.org) is a JavaScript bundler, that will take all of the TypeScript + JavaScript code you reference and then create an AMD bundle for it all. AMD bundles are used in Monaco, TypeScript Sandbox and the Playground - so, this is used for consistency with the rest of the ecosystem.
+
+## Adding a dependency
+
+Because most node_modules expect to be running in node, you might have to do some work to get the dependency working on the web.
+
+The route to handle this is via rollup:
+
+- add a new dependency via `pnpm add xyz`
+- import it into your `index.ts`
+- run `pnpm build` - did it provide some error messages?
+  - If it did, you may need to edit your `rollup.config.js`.
+  - You could probably start by taking the [rollup config from `playground-plugin-tsquery`](https://github.com/orta/playground-plugin-tsquery/blob/master/rollup.config.js) and by adding any extra externals and globals.
+
+#### Serve
+
+[Serve](https://github.com/zeit/serve) is used to make a web-server for the dist folder.
+
+## Deployment
+
+This module should be deployed to npm when you would like the world to see it, this may mean making your code handle a staging vs production environment (because the URLs will be different.)
+
+For example, this is how you can handle getting the URL for a CSS file which is included in your `dist` folder:
+
+```ts
+const isDev = document.location.host.includes("localhost")
+const unpkgURL = "https://unpkg.com/typescript-playground-presentation-mode@latest/dist/slideshow.css"
+const cssHref = isDev ? "http://localhost:5000/slideshow.css" : unpkgURL
+```
+
+### Post-Deploy
+
+Once this is deployed, you can test it on the TypeScript playground by passing in the name of your plugin on npm to the custom plugin box. This is effectively your staging environment.
+
+Once you're happy and it's polished, you can apply to have it in the default plugin list.
+
+## Support
+
+Ask questions either on the [TypeScript Website issues](https://github.com/microsoft/TypeScript-Website/issues), or in the [TypeScript Community Discord](https://discord.gg/typescript) - in the TypeScript Website channel.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License Copyright (c) 2025 Som Shekhar Mukherjee
+
+Permission is hereby
+granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice
+(including the next paragraph) shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,29 @@
+## Shareable Twoslash Comments
+
+A TypeScript Playground plugin that embeds twoslash (// ^?) type hints as literal comments in your code, making them easy to copy and share.
+
+## Running this plugin
+
+- [Click this link](https://www.typescriptlang.org/play?install-plugin=shareable-twoslash-comments) to install
+
+or
+
+- Open up the TypeScript Playground
+- Go the "Plugins" in the sidebar
+- Look for "Plugins from npm"
+- Add "shareable-twoslash-comments"
+- Reload the browser
+
+Then it will show up as a tab in the sidebar.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full details, however, TLDR:
+
+```sh
+git clone ...
+yarn install
+yarn start
+```
+
+Then tick the box for starting plugin development inside the TypeScript Playground.

package/dist/index.js

@@ -0,0 +1,175 @@
+define(function () { 'use strict';
+
+    /******************************************************************************
+    Copyright (c) Microsoft Corporation.
+
+    Permission to use, copy, modify, and/or distribute this software for any
+    purpose with or without fee is hereby granted.
+
+    THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+    REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+    AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+    INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+    LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+    OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+    PERFORMANCE OF THIS SOFTWARE.
+    ***************************************************************************** */
+
+    function __awaiter(thisArg, _arguments, P, generator) {
+        function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+        return new (P || (P = Promise))(function (resolve, reject) {
+            function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+            function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+            function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+            step((generator = generator.apply(thisArg, _arguments || [])).next());
+        });
+    }
+
+    function __generator(thisArg, body) {
+        var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+        return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+        function verb(n) { return function (v) { return step([n, v]); }; }
+        function step(op) {
+            if (f) throw new TypeError("Generator is already executing.");
+            while (g && (g = 0, op[0] && (_ = 0)), _) try {
+                if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+                if (y = 0, t) op = [op[0] & 2, t.value];
+                switch (op[0]) {
+                    case 0: case 1: t = op; break;
+                    case 4: _.label++; return { value: op[1], done: false };
+                    case 5: _.label++; y = op[1]; op = [0]; continue;
+                    case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                    default:
+                        if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                        if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                        if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                        if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                        if (t[2]) _.ops.pop();
+                        _.trys.pop(); continue;
+                }
+                op = body.call(thisArg, _);
+            } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+            if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+        }
+    }
+
+    var _SuppressedError = typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+        var e = new Error(message);
+        return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+    };
+
+    var twoSlashQueryRegex = /(^\s*)(\/\/\s*\^\?)/gm;
+    var fillTwoSlashQueries = function (sandbox) { return __awaiter(void 0, void 0, void 0, function () {
+        var multilineEnabled, model, worker, text, editOperations, _i, _a, match, commentPrefix, caretOffset, caretPos, quickInfoPos, quickInfoOffset, quickInfo, quickInfoString, quickInfoComment, prevQuickInfoComment, prevQuickInfoLines, prevQuickInfoEndLine;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0:
+                    multilineEnabled = localStorage.getItem("shareable-twoslash-comments/enable-multiline-comments") === "true";
+                    model = sandbox.getModel();
+                    return [4 /*yield*/, sandbox.getWorkerProcess()];
+                case 1:
+                    worker = _b.sent();
+                    text = model.getValue();
+                    editOperations = [];
+                    _i = 0, _a = Array.from(text.matchAll(twoSlashQueryRegex));
+                    _b.label = 2;
+                case 2:
+                    if (!(_i < _a.length)) return [3 /*break*/, 5];
+                    match = _a[_i];
+                    commentPrefix = "".concat(match[1], "//").padEnd(match[0].length + 1);
+                    caretOffset = match.index + match[0].length - 1;
+                    caretPos = model.getPositionAt(caretOffset);
+                    quickInfoPos = new sandbox.monaco.Position(caretPos.lineNumber - 1, caretPos.column);
+                    quickInfoOffset = model.getOffsetAt(quickInfoPos);
+                    return [4 /*yield*/, worker.getQuickInfoAtPosition("file://" + model.uri.path, quickInfoOffset)];
+                case 3:
+                    quickInfo = _b.sent();
+                    if (!(quickInfo === null || quickInfo === void 0 ? void 0 : quickInfo.displayParts)) {
+                        return [3 /*break*/, 4];
+                    }
+                    quickInfoString = quickInfo.displayParts.map(function (d) { return d.text; }).join("");
+                    quickInfoComment = "".concat(match[0], " ").concat(multilineEnabled
+                        ? quickInfoString.replace(new RegExp(model.getEOL(), "g"), "".concat(model.getEOL()).concat(commentPrefix))
+                        : quickInfoString.replace(/\r?\n\s*/g, " "));
+                    prevQuickInfoComment = getPreviousQuickInfoComment({
+                        model: model,
+                        lineNumber: caretPos.lineNumber,
+                        commentPrefix: commentPrefix,
+                    });
+                    prevQuickInfoLines = prevQuickInfoComment.split("\n").length;
+                    prevQuickInfoEndLine = caretPos.lineNumber + prevQuickInfoLines - 1;
+                    if (prevQuickInfoComment !== quickInfoComment) {
+                        editOperations.push({
+                            range: new sandbox.monaco.Range(caretPos.lineNumber, 0, prevQuickInfoEndLine, model.getLineContent(prevQuickInfoEndLine).length + 1),
+                            text: quickInfoComment,
+                        });
+                    }
+                    _b.label = 4;
+                case 4:
+                    _i++;
+                    return [3 /*break*/, 2];
+                case 5:
+                    if (editOperations.length > 0) {
+                        model.pushEditOperations([], editOperations, function () { return null; });
+                    }
+                    return [2 /*return*/];
+            }
+        });
+    }); };
+    var getPreviousQuickInfoComment = function (_a) {
+        var model = _a.model, lineNumber = _a.lineNumber, commentPrefix = _a.commentPrefix;
+        var prevQuickInfoLines = [];
+        for (var currLineNumber = lineNumber; currLineNumber <= model.getLineCount(); currLineNumber++) {
+            var lineContent = model.getLineContent(currLineNumber);
+            if (!(lineContent.startsWith(commentPrefix) || lineContent.search(twoSlashQueryRegex) !== -1)) {
+                break;
+            }
+            prevQuickInfoLines.push(lineContent);
+        }
+        return prevQuickInfoLines.join("\n");
+    };
+    //# sourceMappingURL=utils.js.map
+
+    var makePlugin = function (utils) {
+        var customPlugin = {
+            id: "shareable-twoslash-comments",
+            displayName: "Shareable Twoslash Comments",
+            didMount: function (sandbox, container) {
+                // Create a design system object to handle
+                // making DOM elements which fit the playground (and handle mobile/light/dark etc)
+                var ds = utils.createDesignSystem(container);
+                ds.p("This plugin embeds twoslash (// ^?) type hints as literal comments in your code, making them easy to copy and share.");
+                ds.showOptionList([
+                    {
+                        blurb: "Preserve multiline types instead of collapsing them to a single line.",
+                        flag: "shareable-twoslash-comments/enable-multiline-comments",
+                        display: "Enable multiline comments",
+                        onchange: function () { return fillTwoSlashQueries(sandbox); },
+                    },
+                ], {
+                    style: "separated",
+                });
+            },
+            // This is called occasionally as text changes in monaco,
+            // it does not directly map 1 keyup to once run of the function
+            // because it is intentionally called at most once every 0.3 seconds
+            // and then will always run at the end.
+            modelChangedDebounce: function (sandbox, model) { return __awaiter(void 0, void 0, void 0, function () {
+                return __generator(this, function (_a) {
+                    fillTwoSlashQueries(sandbox);
+                    return [2 /*return*/];
+                });
+            }); },
+            // Gives you a chance to remove anything set up,
+            // the container itself if wiped of children after this.
+            didUnmount: function () {
+                console.log("De-focusing plugin");
+            },
+        };
+        return customPlugin;
+    };
+    //# sourceMappingURL=index.js.map
+
+    return makePlugin;
+
+});

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "shareable-twoslash-comments",
+  "version": "0.0.1",
+  "main": "dist/index.js",
+  "description": "A TypeScript Playground plugin that embeds twoslash (// ^?) type hints as literal comments in your code, making them easy to copy and share.",
+  "license": "MIT",
+  "keywords": [
+    "playground-plugin"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/som-sm/shareable-twoslash-comments"
+  },
+  "scripts": {
+    "build": "rollup -c rollup.config.js",
+    "compile": "tsc",
+    "bootstrap": "node scripts/getDTS.js",
+    "start": "concurrently -p \"[{name}]\" -n \"ROLLUP,SITE\" -c \"bgBlue.bold,bgMagenta.bold\" \"yarn rollup -c rollup.config.js --watch\" \"yarn serve dist\"",
+    "prepublish": "yarn build",
+    "postinstall": "yarn bootstrap && yarn build"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^11.0.2",
+    "@rollup/plugin-json": "^4.0.2",
+    "@rollup/plugin-node-resolve": "^7.1.0",
+    "@rollup/plugin-typescript": "^3.0.0",
+    "@types/react": "^16.9.23",
+    "concurrently": "^8.2.2",
+    "monaco-editor": "^0.32.1",
+    "node-fetch": "^2.6.0",
+    "prettier": "^3.4.2",
+    "rollup": "^1.31.0",
+    "serve": "^11.3.0",
+    "typescript": "latest",
+    "lz-string": "^1.5.0"
+  },
+  "dependencies": {
+    "tslib": "^2.5.0"
+  }
+}