feat: non-react playgrounds for docs

apps/docs/content/packages/demo-ad-hoc-page.md → apps/docs/content/packages/demo-ad-hoc-page.mdx

@@ -1,3 +1,5 @@
+import { Playground } from '@site/src/components/playground';
+
 # Demo
 
 See the [docusaurus docs](https://docusaurus.io/docs/markdown-features) for full feature set.
@@ -25,7 +27,7 @@ type Day = 'Monday' | 'Tuesday' | 'Wednesday' | 'Thursday' | 'Friday' | 'Saturda
 // some other thing and stuff
 ```
 
-## live playground
+## Playground (React)
 
 ```jsx live
 function Clock(props) {
@@ -55,3 +57,18 @@ function Clock(props) {
 $$
 I = \int_0^{2\pi} \sin(x)\,dx
 $$
+
+
+## Playground (Non-React)
+
+<Playground
+  code={`import { booleanToNumber } from '@accelint/converters';
+
+console.log(booleanToNumber(true));
+// 1
+
+console.log(booleanToNumber(false));
+// 0`}
+  dependencies={['@accelint/converters']}
+/>
+

apps/docs/lib/playground-plugin-hypergiant.mjs

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+/**
+ * TypeDoc plugin for replacing @playground blocks with our custom playground component,
+ *
+ * @param {import('typedoc').Application} app
+ */
+export function load(app) {
+  app.converter.on('createSignature', convertPlaygroundBlockToComponent);
+}
+
+function convertPlaygroundBlockToComponent(context, reflection) {
+  const playgroundTag = reflection?.comment?.blockTags?.find(
+    ({ tag }) => tag === '@playground',
+  );
+
+  if (playgroundTag) {
+    const code = playgroundTag.content[0].text.trim();
+    playgroundTag.content = [
+      {
+        kind: 'text',
+        text: `import { Playground } from '@site/src/components/playground';
+
+<Playground
+  code={\`${code}\`}
+  dependencies={['${context.project.name}']}
+/>
+        `,
+      },
+    ];
+  }
+}

apps/docs/package.json

@@ -17,6 +17,7 @@
     "@accelint/design-system": "workspace:*",
     "@accelint/typescript-config": "workspace:*",
     "@biomejs/biome": "1.9.3",
+    "@codesandbox/sandpack-react": "2.19.10",
     "@docusaurus/core": "3.7.0",
     "@docusaurus/module-type-aliases": "3.7.0",
     "@docusaurus/preset-classic": "3.7.0",

apps/docs/src/components/playground.tsx

@@ -0,0 +1,35 @@
+/*
+ * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { Sandpack } from '@codesandbox/sandpack-react';
+
+type PlaygroundProps = {
+  code: string;
+  dependencies?: string[];
+};
+
+export function Playground({ code, dependencies = [] }: PlaygroundProps) {
+  return (
+    <Sandpack
+      template='vanilla-ts'
+      customSetup={{
+        dependencies: Object.fromEntries(
+          dependencies.map((dep) => [dep, 'latest']),
+        ),
+      }}
+      files={{ 'index.ts': code }}
+      options={{
+        layout: 'console',
+      }}
+    />
+  );
+}

apps/docs/typedoc.mjs

@@ -10,6 +10,8 @@
  * governing permissions and limitations under the License.
  */
 
+import { OptionDefaults } from 'typedoc';
+
 /** @type {Partial<import("typedoc").TypeDocOptions>} */
 export default {
   disableSources: true,
@@ -27,7 +29,12 @@ export default {
   pageTitleTemplates: {
     member: (args) => args.name, // simpler page titles for member pages
   },
-  plugin: ['typedoc-plugin-markdown', './lib/typedoc-plugin-hypergiant.mjs'],
+  plugin: [
+    'typedoc-plugin-markdown',
+    './lib/typedoc-plugin-hypergiant.mjs',
+    './lib/playground-plugin-hypergiant.mjs',
+  ],
   requiredToBeDocumented: ['Class', 'Function', 'Interface'],
   theme: 'markdown',
+  blockTags: [...OptionDefaults.blockTags, '@playground'], // https://typedoc.org/documents/Options.Comments.html#blocktags
 };

packages/constants/typedoc.mjs

@@ -0,0 +1,16 @@
+/*
+ * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+/** @type {Partial<import("typedoc").TypeDocOptions>} */
+export default {
+  name: '@accelint/constants',
+};

packages/converters/src/boolean-to-number/index.ts

@@ -16,11 +16,13 @@
  * @remarks
  * pure function
  *
- * @example
- * booleanToNumber(true);
+ * @playground
+ * import { booleanToNumber } from '@accelint/converters';
+ *
+ * console.log(booleanToNumber(true));
  * // 1
  *
- * booleanToNumber(false);
+ * console.log(booleanToNumber(false));
  * // 0
  */
 export function booleanToNumber(val: boolean) {

packages/converters/typedoc.mjs

@@ -0,0 +1,16 @@
+/*
+ * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+/** @type {Partial<import("typedoc").TypeDocOptions>} */
+export default {
+  name: '@accelint/converters',
+};

packages/core/typedoc.mjs

@@ -0,0 +1,16 @@
+/*
+ * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+/** @type {Partial<import("typedoc").TypeDocOptions>} */
+export default {
+  name: '@accelint/core',
+};

packages/design-system/typedoc.mjs

@@ -0,0 +1,16 @@
+/*
+ * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+/** @type {Partial<import("typedoc").TypeDocOptions>} */
+export default {
+  name: '@accelint/design-system',
+};

packages/formatters/typedoc.mjs

@@ -0,0 +1,16 @@
+/*
+ * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+/** @type {Partial<import("typedoc").TypeDocOptions>} */
+export default {
+  name: '@accelint/formatters',
+};

packages/geo/typedoc.mjs

@@ -0,0 +1,16 @@
+/*
+ * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+/** @type {Partial<import("typedoc").TypeDocOptions>} */
+export default {
+  name: '@accelint/geo',
+};

packages/math/typedoc.mjs

@@ -0,0 +1,16 @@
+/*
+ * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+/** @type {Partial<import("typedoc").TypeDocOptions>} */
+export default {
+  name: '@accelint/constants',
+};

packages/predicates/typedoc.mjs

@@ -0,0 +1,16 @@
+/*
+ * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+/** @type {Partial<import("typedoc").TypeDocOptions>} */
+export default {
+  name: '@accelint/predicates',
+};

packages/temporal/typedoc.mjs

@@ -0,0 +1,16 @@
+/*
+ * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+/** @type {Partial<import("typedoc").TypeDocOptions>} */
+export default {
+  name: '@accelint/temporal',
+};

packages/web-worker/typedoc.mjs

@@ -0,0 +1,16 @@
+/*
+ * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+/** @type {Partial<import("typedoc").TypeDocOptions>} */
+export default {
+  name: '@accelint/web-worker',
+};

packages/websocket/typedoc.mjs

@@ -0,0 +1,16 @@
+/*
+ * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+/** @type {Partial<import("typedoc").TypeDocOptions>} */
+export default {
+  name: '@accelint/websocket',
+};