@azerion/bunosaurus-theme-live-codeblock 0.0.0-stage → 4.0.0

package/lib/theme/ReactLiveScope/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+declare const ReactLiveScope: unknown;
+export default ReactLiveScope;

package/lib/theme/ReactLiveScope/index.js

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import React from 'react';
+// Add react-live imports you need here
+const ReactLiveScope = {
+  React,
+  ...React,
+};
+export default ReactLiveScope;

package/lib/validateThemeConfig.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { Joi } from '@docusaurus/utils-validation';
+import type { ThemeConfig, ThemeConfigValidationContext } from '@docusaurus/types';
+export declare const DEFAULT_CONFIG: {
+    playgroundPosition: string;
+};
+export declare const Schema: Joi.ObjectSchema<ThemeConfig>;
+export declare function validateThemeConfig({ validate, themeConfig, }: ThemeConfigValidationContext<ThemeConfig>): ThemeConfig;

package/lib/validateThemeConfig.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Schema = exports.DEFAULT_CONFIG = void 0;
+exports.validateThemeConfig = validateThemeConfig;
+const utils_validation_1 = require("@docusaurus/utils-validation");
+exports.DEFAULT_CONFIG = {
+    playgroundPosition: 'bottom',
+};
+exports.Schema = utils_validation_1.Joi.object({
+    liveCodeBlock: utils_validation_1.Joi.object({
+        playgroundPosition: utils_validation_1.Joi.string()
+            .equal('top', 'bottom')
+            .default(exports.DEFAULT_CONFIG.playgroundPosition),
+    })
+        .label('themeConfig.liveCodeBlock')
+        .default(exports.DEFAULT_CONFIG),
+});
+function validateThemeConfig({ validate, themeConfig, }) {
+    return validate(exports.Schema, themeConfig);
+}

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@azerion/bunosaurus-theme-live-codeblock",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "4.0.0",
+  "description": "Docusaurus live code block component.",
+  "main": "lib/index.js",
+  "types": "src/theme-live-codeblock.d.ts",
+  "sideEffects": [
+    "lib/theme/Playground/*"
+  ],
+  "exports": {
+    "./lib/*": "./lib/*",
+    "./src/*": "./src/*",
+    "./client": {
+      "type": "./lib/client/index.d.ts",
+      "default": "./lib/client/index.js"
+    },
+    ".": {
+      "types": "./src/theme-live-codeblock.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc --build && copy-untyped-files && oxfmt \"lib/theme/**/*.js\"",
+    "watch": "run-p -c copy:watch build:watch",
+    "build:watch": "tsc --build --watch",
+    "copy:watch": "copy-untyped-files --watch"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/azerion/bunosaurus.git",
+    "directory": "packages/docusaurus-theme-live-codeblock"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@docusaurus/core": "npm:@azerion/bunosaurus-core@4.0.0",
+    "@docusaurus/theme-classic": "npm:@azerion/bunosaurus-theme-classic@4.0.0",
+    "@docusaurus/theme-common": "npm:@azerion/bunosaurus-theme-common@4.0.0",
+    "@docusaurus/theme-translations": "npm:@azerion/bunosaurus-theme-translations@4.0.0",
+    "@docusaurus/utils-validation": "npm:@azerion/bunosaurus-utils-validation@4.0.0",
+    "clsx": "^2.1.1",
+    "react-live": "^5.0.0",
+    "tslib": "^2.8.1"
+  },
+  "devDependencies": {
+    "@docusaurus/module-type-aliases": "npm:@azerion/bunosaurus-module-type-aliases@4.0.0",
+    "@docusaurus/types": "npm:@azerion/bunosaurus-types@4.0.0"
+  },
+  "peerDependencies": {
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0"
+  },
+  "engines": {
+    "bun": ">=1.4.1"
+  }
+}

package/src/client/context.tsx

@@ -0,0 +1,32 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {createContext, useContext, type ReactNode} from 'react';
+
+type PlaygroundContextValue = {
+  reset: () => void;
+};
+
+const PlaygroundContext = createContext<PlaygroundContextValue | null>(null);
+
+export function PlaygroundProvider({
+  value,
+  children,
+}: {
+  value: PlaygroundContextValue;
+  children: ReactNode;
+}): ReactNode {
+  return <PlaygroundContext value={value}>{children}</PlaygroundContext>;
+}
+
+export function usePlayground(): PlaygroundContextValue {
+  const context = useContext(PlaygroundContext);
+  if (!context) {
+    throw new Error('usePlayground must be used within PlaygroundProvider');
+  }
+  return context;
+}

package/src/client/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+export {usePlayground, PlaygroundProvider} from './context';

package/src/index.ts

@@ -0,0 +1,35 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {readDefaultCodeTranslationMessages} from '@docusaurus/theme-translations';
+import type {LoadContext, Plugin} from '@docusaurus/types';
+
+export default function themeLiveCodeblock(context: LoadContext): Plugin {
+  const {
+    i18n: {currentLocale},
+  } = context;
+
+  return {
+    name: 'docusaurus-theme-live-codeblock',
+
+    getThemePath() {
+      return '../lib/theme';
+    },
+    getTypeScriptThemePath() {
+      return '../src/theme';
+    },
+
+    getDefaultCodeTranslationMessages() {
+      return readDefaultCodeTranslationMessages({
+        locale: currentLocale,
+        name: 'theme-live-codeblock',
+      });
+    },
+  };
+}
+
+export {validateThemeConfig} from './validateThemeConfig';

package/src/theme/CodeBlock/index.tsx

@@ -0,0 +1,38 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type {ReactNode} from 'react';
+import type {Props as CodeBlockProps} from '@theme/CodeBlock';
+import OriginalCodeBlock from '@theme-init/CodeBlock';
+import LiveCodeBlock from '@theme/LiveCodeBlock';
+
+// TODO Docusaurus v4: remove special case
+//  see packages/docusaurus-mdx-loader/src/remark/mdx1Compat/codeCompatPlugin.ts
+//  we can just use the metastring instead
+declare module '@theme/CodeBlock' {
+  interface Props {
+    live?: boolean;
+  }
+}
+
+function isLiveCodeBlock(
+  props: CodeBlockProps,
+): props is {live: true; children: string | undefined} {
+  return (
+    !!props.live &&
+    (typeof props.children === 'undefined' ||
+      typeof props.children === 'string')
+  );
+}
+
+export default function CodeBlockEnhancer(props: CodeBlockProps): ReactNode {
+  return isLiveCodeBlock(props) ? (
+    <LiveCodeBlock {...props} />
+  ) : (
+    <OriginalCodeBlock {...props} />
+  );
+}

package/src/theme/LiveCodeBlock/index.tsx

@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type {ReactNode} from 'react';
+import Playground from '@theme/Playground';
+import ReactLiveScope from '@theme/ReactLiveScope';
+import type {Props} from '@theme/LiveCodeBlock';
+
+export default function LiveCodeBlock(props: Props): ReactNode {
+  return <Playground scope={ReactLiveScope} {...props} />;
+}

package/src/theme/Playground/Buttons/ResetButton/index.tsx

@@ -0,0 +1,51 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type {ReactNode} from 'react';
+import clsx from 'clsx';
+import Translate from '@docusaurus/Translate';
+import {usePlayground} from '@docusaurus/theme-live-codeblock/client';
+import type {Props} from '@theme/Playground/Buttons/ResetButton';
+import styles from './styles.module.css';
+
+function Icon() {
+  return (
+    <svg
+      className={styles.resetButtonIcon}
+      viewBox="0 0 16 16"
+      fill="currentColor"
+      aria-hidden="true">
+      <path d="M8 3a5 5 0 1 0 4.546 2.914.5.5 0 0 1 .908-.417A6 6 0 1 1 8 2v1z" />
+      <path d="M8 4.466V.534a.25.25 0 0 1 .41-.192l2.36 1.966c.12.1.12.284 0 .384L8.41 4.658A.25.25 0 0 1 8 4.466z" />
+    </svg>
+  );
+}
+
+function Label() {
+  return (
+    <Translate
+      id="theme.Playground.buttons.reset"
+      description="The reset button label for live code blocks">
+      Reset
+    </Translate>
+  );
+}
+
+export default function ResetButton({className}: Props): ReactNode {
+  const {reset} = usePlayground();
+  return (
+    <button
+      type="button"
+      aria-label="Reset code to original"
+      title="Reset"
+      className={clsx('clean-btn', className, styles.resetButton)}
+      onClick={() => reset()}>
+      <Icon />
+      <Label />
+    </button>
+  );
+}

package/src/theme/Playground/Buttons/ResetButton/styles.module.css

@@ -0,0 +1,36 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+.resetButton {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25rem;
+  padding: 0.25rem 0.5rem;
+  font-size: 0.875rem;
+  line-height: 1.5;
+  border: 1px solid var(--ifm-color-emphasis-300);
+  border-radius: var(--ifm-global-radius);
+  background: var(--ifm-button-background-color);
+  color: var(--ifm-font-color-base);
+  cursor: pointer;
+  transition: all var(--ifm-transition-fast);
+}
+
+.resetButton:hover {
+  background: var(--ifm-color-emphasis-200);
+  border-color: var(--ifm-color-emphasis-400);
+}
+
+.resetButton:active {
+  background: var(--ifm-color-emphasis-300);
+}
+
+.resetButtonIcon {
+  width: 1rem;
+  height: 1rem;
+  flex-shrink: 0;
+}

package/src/theme/Playground/Container/index.tsx

@@ -0,0 +1,16 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type {ReactNode} from 'react';
+
+import type {Props} from '@theme/Playground/Container';
+
+import styles from './styles.module.css';
+
+export default function PlaygroundContainer({children}: Props): ReactNode {
+  return <div className={styles.playgroundContainer}>{children}</div>;
+}

package/src/theme/Playground/Container/styles.module.css

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+.playgroundContainer {
+  margin-bottom: var(--ifm-leading);
+  border-radius: var(--ifm-global-radius);
+  box-shadow: var(--ifm-global-shadow-lw);
+  overflow: hidden;
+}

package/src/theme/Playground/Editor/index.tsx

@@ -0,0 +1,35 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type {ReactNode} from 'react';
+import {LiveEditor} from 'react-live';
+import useIsBrowser from '@docusaurus/useIsBrowser';
+import Translate from '@docusaurus/Translate';
+import PlaygroundHeader from '@theme/Playground/Header';
+import ResetButton from '@theme/Playground/Buttons/ResetButton';
+import styles from './styles.module.css';
+
+export default function PlaygroundEditor(): ReactNode {
+  const isBrowser = useIsBrowser();
+  return (
+    <>
+      <PlaygroundHeader buttons={<ResetButton />}>
+        <Translate
+          id="theme.Playground.liveEditor"
+          description="The live editor label of the live codeblocks">
+          Live Editor
+        </Translate>
+      </PlaygroundHeader>
+      <LiveEditor
+        // We force remount the editor on hydration,
+        // otherwise dark prism theme is not applied
+        key={String(isBrowser)}
+        className={styles.playgroundEditor}
+      />
+    </>
+  );
+}

package/src/theme/Playground/Editor/styles.module.css

@@ -0,0 +1,17 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+.playgroundEditor {
+  font: var(--ifm-code-font-size) / var(--ifm-pre-line-height)
+    var(--ifm-font-family-monospace) !important;
+  /* rtl:ignore */
+  direction: ltr;
+}
+
+.playgroundEditor pre {
+  border-radius: 0;
+}

package/src/theme/Playground/Header/index.tsx

@@ -0,0 +1,26 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type {ReactNode} from 'react';
+import clsx from 'clsx';
+import type {Props} from '@theme/Playground/Header';
+
+import styles from './styles.module.css';
+
+export default function PlaygroundHeader({
+  children,
+  buttons,
+}: Props): ReactNode {
+  return (
+    <div className={clsx(styles.playgroundHeader)}>
+      <div className={styles.playgroundHeaderContent}>{children}</div>
+      {buttons && (
+        <div className={styles.playgroundHeaderButtons}>{buttons}</div>
+      )}
+    </div>
+  );
+}

package/src/theme/Playground/Header/styles.module.css

@@ -0,0 +1,29 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+.playgroundHeader {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  letter-spacing: 0.08rem;
+  padding: 0.75rem;
+  text-transform: uppercase;
+  font-weight: bold;
+  background: var(--ifm-color-emphasis-200);
+  color: var(--ifm-color-content);
+  font-size: var(--ifm-code-font-size);
+}
+
+.playgroundHeaderContent {
+  font-weight: var(--ifm-font-weight-bold);
+  font-size: 0.875rem;
+}
+
+.playgroundHeaderButtons {
+  display: flex;
+  gap: 0.5rem;
+}

package/src/theme/Playground/Layout/index.tsx

@@ -0,0 +1,39 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type {ReactNode} from 'react';
+import {useThemeConfig} from '@docusaurus/theme-common';
+import PlaygroundPreview from '@theme/Playground/Preview';
+import PlaygroundEditor from '@theme/Playground/Editor';
+import type {Props} from '@theme/Playground/Layout';
+
+import type {ThemeConfig} from '@docusaurus/theme-live-codeblock';
+
+function useLiveCodeBlockThemeConfig() {
+  const themeConfig = useThemeConfig() as unknown as ThemeConfig;
+  return themeConfig.liveCodeBlock;
+}
+
+export default function PlaygroundLayout(props: Props): ReactNode {
+  const themeConfig = useLiveCodeBlockThemeConfig();
+  const position = props.position ?? themeConfig.playgroundPosition;
+  return (
+    <>
+      {position === 'top' ? (
+        <>
+          <PlaygroundPreview />
+          <PlaygroundEditor />
+        </>
+      ) : (
+        <>
+          <PlaygroundEditor />
+          <PlaygroundPreview />
+        </>
+      )}
+    </>
+  );
+}

package/src/theme/Playground/Preview/index.tsx

@@ -0,0 +1,59 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type {ReactNode} from 'react';
+import {LiveError, LivePreview} from 'react-live';
+import BrowserOnly from '@docusaurus/BrowserOnly';
+import {ErrorBoundaryErrorMessageFallback} from '@docusaurus/theme-common';
+import ErrorBoundary from '@docusaurus/ErrorBoundary';
+import Translate from '@docusaurus/Translate';
+import PlaygroundHeader from '@theme/Playground/Header';
+
+import styles from './styles.module.css';
+
+function Loader() {
+  // Is it worth improving/translating?
+  // eslint-disable-next-line @docusaurus/no-untranslated-text
+  return <div>Loading...</div>;
+}
+
+function PlaygroundLivePreview(): ReactNode {
+  // No SSR for the live preview
+  // See https://github.com/facebook/docusaurus/issues/5747
+  return (
+    <BrowserOnly fallback={<Loader />}>
+      {() => (
+        <>
+          <ErrorBoundary
+            fallback={(params) => (
+              <ErrorBoundaryErrorMessageFallback {...params} />
+            )}>
+            <LivePreview />
+          </ErrorBoundary>
+          <LiveError />
+        </>
+      )}
+    </BrowserOnly>
+  );
+}
+
+export default function PlaygroundPreview(): ReactNode {
+  return (
+    <>
+      <PlaygroundHeader>
+        <Translate
+          id="theme.Playground.result"
+          description="The result label of the live codeblocks">
+          Result
+        </Translate>
+      </PlaygroundHeader>
+      <div className={styles.playgroundPreview}>
+        <PlaygroundLivePreview />
+      </div>
+    </>
+  );
+}

package/src/theme/Playground/Preview/styles.module.css

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+.playgroundPreview {
+  padding: 1rem;
+  background-color: var(--ifm-pre-background);
+}

package/src/theme/Playground/Provider/index.tsx

@@ -0,0 +1,43 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {type ReactNode, useCallback, useMemo, useState} from 'react';
+import {LiveProvider} from 'react-live';
+import {PlaygroundProvider as PlaygroundProviderComponent} from '@docusaurus/theme-live-codeblock/client';
+import {usePrismTheme} from '@docusaurus/theme-common';
+import type {Props} from '@theme/Playground/Provider';
+
+// this should rather be a stable function
+// see https://github.com/facebook/docusaurus/issues/9630#issuecomment-1855682643
+const DEFAULT_TRANSFORM_CODE = (code: string) => `${code};`;
+
+function LiveProviderComponent({code, children, ...props}: Props): ReactNode {
+  const prismTheme = usePrismTheme();
+  const noInline = props.metastring?.includes('noInline') ?? false;
+  return (
+    <LiveProvider
+      noInline={noInline}
+      theme={prismTheme}
+      {...props}
+      code={code?.replace(/\n$/, '')}
+      transformCode={props.transformCode ?? DEFAULT_TRANSFORM_CODE}>
+      {children}
+    </LiveProvider>
+  );
+}
+
+export default function PlaygroundProvider(props: Props): ReactNode {
+  const [resetKey, setResetKey] = useState(0);
+  const reset = useCallback(() => setResetKey((prev) => prev + 1), []);
+  const value = useMemo(() => ({reset}), [reset]);
+
+  return (
+    <PlaygroundProviderComponent key={resetKey} value={value}>
+      <LiveProviderComponent {...props} />
+    </PlaygroundProviderComponent>
+  );
+}