@orgajs/orgx 1.0.7 → 2.0.0

package/lib/plugin/rehype-recma.js

@@ -0,0 +1,218 @@
+/**
+ * @typedef {import('estree-jsx').Program} Program
+ * @typedef {import('estree-jsx').Expression} Expression
+ * @typedef {import('estree-jsx').ModuleDeclaration} ModuleDeclaration
+ * @typedef {import('hast').Root} Root
+ * @typedef {import('hast-util-to-estree').Handle} Handle
+ * @typedef {import('hast-util-to-estree').Options} HastToEstreeOptions
+ */
+
+/**
+ * @typedef {'html' | 'react'} ElementAttributeNameCase
+ *   Specify casing to use for attribute names.
+ *
+ *   HTML casing is for example `class`, `stroke-linecap`, `xml:lang`.
+ *   React casing is for example `className`, `strokeLinecap`, `xmlLang`.
+ *
+ * @typedef {'css' | 'dom'} StylePropertyNameCase
+ *   Casing to use for property names in `style` objects.
+ *
+ *   CSS casing is for example `background-color` and `-webkit-line-clamp`.
+ *   DOM casing is for example `backgroundColor` and `WebkitLineClamp`.
+ */
+
+/**
+ * @typedef MoreOptions
+ *   Configuration for internal plugin `rehype-recma`.
+ * @property {ElementAttributeNameCase | undefined | null} [elementAttributeNameCase='react']
+ *   Specify casing to use for attribute names.
+ *
+ *   This casing is used for hast elements, not for embedded Org JSX nodes
+ *   (components that someone authored manually).
+ * @property {StylePropertyNameCase | undefined | null} [stylePropertyNameCase='dom']
+ *   Specify casing to use for property names in `style` objects.
+ *
+ *   This casing is used for hast elements, not for embedded Org JSX nodes
+ *   (components that someone authored manually).
+ * @property {boolean} [skipImport=false] - Whether to skip imports
+ * @property {string[]} [parseJSX=['jsx.value']] - Specify which hast properties to parse as JSX.
+ *
+ * @typedef {HastToEstreeOptions & MoreOptions} Options
+ */
+
+import { toEstree } from 'hast-util-to-estree'
+import { Parser } from 'acorn'
+import jsx from 'acorn-jsx'
+import renderError from '../util/render-error.js'
+
+/**
+ * A plugin to transform an HTML (hast) tree to a JS (estree).
+ * `hast-util-to-estree` does all the work for us!
+ *
+ * @type {import('unified').Plugin<[Options | undefined] | [], Root, Program>}
+ */
+export function rehypeRecma(options = {}) {
+  const {
+    skipImport = false,
+    parseJSX = ['jsx.value'],
+    ...otherOptions
+  } = options
+  const handlers = options.handlers || {}
+
+  for (const p of parseJSX) {
+    const [key, ...rest] = p.split('.')
+    if (!key) {
+      throw new Error('somethings wrong')
+    }
+    const path = rest.length > 0 ? rest.join('.') : 'value'
+    handlers[key] = jsxHandle(path, skipImport)
+  }
+
+  return (tree) => {
+    const data = tree.data || {}
+    const { layout, ...otherData } = data
+    /** @type {ModuleDeclaration[]} */
+    const prepand = []
+    if (typeof layout === 'string') {
+      prepand.push({
+        type: 'ImportDeclaration',
+        specifiers: [
+          {
+            type: 'ImportDefaultSpecifier',
+            local: {
+              type: 'Identifier',
+              name: 'OrgaLayout',
+            },
+          },
+        ],
+        source: {
+          type: 'Literal',
+          value: `${layout}`,
+          raw: `'${layout}'`,
+        },
+      })
+    }
+    Object.entries(otherData).forEach(([k, v]) => {
+      prepand.push(createExport(k, v))
+    })
+    const estree = toEstree(tree, { ...otherOptions, handlers })
+    estree.body.unshift(...prepand)
+    return estree
+  }
+}
+
+/**
+ * @param {string} p
+ * @param {any} o
+ * @returns {any}
+ */
+function deepGet(p, o) {
+  return p.split('.').reduce((a, v) => a[v], o)
+}
+
+const jsxParser = Parser.extend(jsx())
+
+/**
+ * @param {string} code
+ */
+const parse = (code) => {
+  try {
+    return jsxParser.parse(code, {
+      sourceType: 'module',
+      ecmaVersion: 2020,
+    })
+  } catch (err) {
+    // @ts-ignore
+    return renderError(err)
+  }
+}
+
+/**
+ * @param {import('acorn').Node | Program} node
+ * @returns {node is Program}
+ */
+function isProgram(node) {
+  return node.type === 'Program'
+}
+
+/**
+ *
+ * @param {string} path
+ * @param {boolean} skipImport
+ * @returns {Handle}
+ */
+function jsxHandle(path, skipImport) {
+  /** @type {Handle} */
+  const handle = (node, state) => {
+    const estree = parse(deepGet(path, node))
+    /** @type {Expression[]} */
+    const expressions = []
+    if (isProgram(estree)) {
+      estree.body.forEach((child) => {
+        if (child.type === 'ImportDeclaration') {
+          if (!skipImport) {
+            state.esm.push(child)
+          }
+          return false
+        } else if (child.type === 'ExpressionStatement') {
+          expressions.push(child.expression)
+        } else if (
+          child.type === 'ExportDefaultDeclaration' ||
+          child.type === 'ExportNamedDeclaration'
+        ) {
+          state.esm.push(child)
+        } else {
+          throw new Error(`unexpected node: ${child.type}`)
+        }
+      })
+    }
+
+    // @ts-ignore it works
+    return expressions
+  }
+  return handle
+}
+
+/**
+ * @param {string} text
+ * @returns {string}
+ */
+function removeQuotes(text) {
+  return text.trim().replace(/^["'](.+(?=["']$))["']$/, '$1')
+}
+
+/**
+ * @param {string} k
+ * @param {any} v
+ * @returns {ModuleDeclaration}
+ */
+function createExport(k, v) {
+  /** @type {(text: string) => Expression} */
+  const createLiteral = (text) => {
+    const value = removeQuotes(`${text}`)
+    return { type: 'Literal', value, raw: `'${value}'` }
+  }
+  /** @type {Expression} */
+  const init = Array.isArray(v)
+    ? {
+        type: 'ArrayExpression',
+        elements: v.map(createLiteral),
+      }
+    : createLiteral(v)
+  return {
+    type: 'ExportNamedDeclaration',
+    declaration: {
+      type: 'VariableDeclaration',
+      declarations: [
+        {
+          type: 'VariableDeclarator',
+          id: { type: 'Identifier', name: k },
+          init,
+        },
+      ],
+      kind: 'const',
+    },
+    specifiers: [],
+    source: null,
+  }
+}

package/lib/run.js

@@ -0,0 +1,31 @@
+/** @type {new (code: string, ...args: Array<unknown>) => Function} **/
+const AsyncFunction = Object.getPrototypeOf(run).constructor
+
+/**
+ * Asynchronously run code.
+ *
+ * @param {{toString(): string}} file
+ *   JS document to run.
+ * @param {unknown} options
+ *   Parameter.
+ * @return {Promise<any>}
+ *   Anything.
+ */
+export async function run(file, options) {
+  return new AsyncFunction(String(file))(options)
+}
+
+/**
+ * Synchronously run code.
+ *
+ * @param {{toString(): string}} file
+ *   JS document to run.
+ * @param {unknown} options
+ *   Parameter.
+ * @return {any}
+ *   Anything.
+ */
+export function runSync(file, options) {
+  // eslint-disable-next-line no-new-func
+  return new Function(String(file))(options)
+}

package/lib/types.d.ts

@@ -0,0 +1,46 @@
+type FunctionComponent<Props> = (props: Props) => JSX.Element | null
+type ClassComponent<Props> = new (props: Props) => JSX.ElementClass
+type Component<Props> =
+  | FunctionComponent<Props>
+  | ClassComponent<Props>
+  | keyof JSX.IntrinsicElements
+
+interface NestedOrgComponents {
+  [key: string]: NestedOrgComponents | Component<any>
+}
+
+export type OrgComponents = NestedOrgComponents & {
+  [Key in keyof JSX.IntrinsicElements]?: Component<JSX.IntrinsicElements[Key]>
+} & {
+  /**
+   * If a wrapper component is defined, the org content will be wrapped inside of it.
+   */
+  wrapper?: Component<any>
+}
+
+export interface OrgProps {
+  /**
+   * Which props exactly may be passed into the component depends on the contents of the org
+   * file.
+   */
+  [key: string]: unknown
+
+  /**
+   * This prop may be used to customize how certain components are rendered.
+   */
+  components?: OrgComponents
+}
+
+export type OrgContent = (props: OrgProps) => JSX.Element
+
+export interface OrgModule {
+  /**
+   * This could be any value that is exported from the org file.
+   */
+  [key: string]: unknown
+
+  /**
+   * A functional JSX component which renders the content of the org file.
+   */
+  default: OrgContent
+}

package/lib/util/estree-util-create.js

@@ -0,0 +1,27 @@
+/**
+ * @typedef {import('estree-jsx').Node} Node
+ */
+
+/**
+ * @param {Node} from
+ *   Node to take from.
+ * @param {Node} to
+ *   Node to add to.
+ * @returns {void}
+ *   Nothing.
+ */
+export function create(from, to) {
+  /** @type {Array<keyof Node>} */
+  // @ts-expect-error: `start`, `end`, `comments` are custom Acorn fields.
+  const fields = ['start', 'end', 'loc', 'range', 'comments']
+  let index = -1
+
+  while (++index < fields.length) {
+    const field = fields[index]
+
+    if (field in from) {
+      // @ts-expect-error: assume they’re settable.
+      to[field] = from[field]
+    }
+  }
+}

package/lib/util/estree-util-declaration-to-expression.js

@@ -0,0 +1,32 @@
+/**
+ * @typedef {import('estree-jsx').Declaration} Declaration
+ * @typedef {import('estree-jsx').Expression} Expression
+ */
+
+/**
+ * Turn a declaration into an expression.
+ *
+ * Doesn’t work for variable declarations, but that’s fine for our use case
+ * because currently we’re using this utility for export default declarations,
+ * which can’t contain variable declarations.
+ *
+ * @param {Declaration} declaration
+ *   Declaration.
+ * @returns {Expression}
+ *   Expression.
+ */
+export function declarationToExpression(declaration) {
+  if (declaration.type === 'FunctionDeclaration') {
+    return {...declaration, type: 'FunctionExpression'}
+  }
+
+  if (declaration.type === 'ClassDeclaration') {
+    return {...declaration, type: 'ClassExpression'}
+    /* Internal utility so the next shouldn’t happen or a maintainer is making a
+     * mistake. */
+    /* c8 ignore next 4 */
+  }
+
+  // Probably `VariableDeclaration`.
+  throw new Error('Cannot turn `' + declaration.type + '` into an expression')
+}

package/lib/util/estree-util-is-declaration.js

@@ -0,0 +1,20 @@
+/**
+ * @typedef {import('estree-jsx').Node} Node
+ * @typedef {import('estree-jsx').Declaration} Declaration
+ */
+
+/**
+ * Check if `node` is a declaration.
+ *
+ * @param {Node} node
+ *   Node to check.
+ * @returns {node is Declaration}
+ *   Whether `node` is a declaration.
+ */
+export function isDeclaration(node) {
+  return Boolean(
+    node.type === 'FunctionDeclaration' ||
+      node.type === 'ClassDeclaration' ||
+      node.type === 'VariableDeclaration'
+  )
+}

package/lib/util/estree-util-specifiers-to-declarations.js

@@ -0,0 +1,90 @@
+/**
+ * @typedef {import('estree-jsx').AssignmentProperty} AssignmentProperty
+ * @typedef {import('estree-jsx').ExportSpecifier} ExportSpecifier
+ * @typedef {import('estree-jsx').Expression} Expression
+ * @typedef {import('estree-jsx').Identifier} Identifier
+ * @typedef {import('estree-jsx').ImportDefaultSpecifier} ImportDefaultSpecifier
+ * @typedef {import('estree-jsx').ImportNamespaceSpecifier} ImportNamespaceSpecifier
+ * @typedef {import('estree-jsx').ImportSpecifier} ImportSpecifier
+ * @typedef {import('estree-jsx').VariableDeclarator} VariableDeclarator
+ */
+
+import {create} from './estree-util-create.js'
+
+/**
+ * @param {Array<ImportSpecifier | ImportDefaultSpecifier | ImportNamespaceSpecifier | ExportSpecifier>} specifiers
+ * @param {Expression} init
+ * @returns {Array<VariableDeclarator>}
+ */
+export function specifiersToDeclarations(specifiers, init) {
+  let index = -1
+  /** @type {Array<VariableDeclarator>} */
+  const declarations = []
+  /** @type {Array<ImportSpecifier | ImportDefaultSpecifier | ExportSpecifier>} */
+  const otherSpecifiers = []
+  // Can only be one according to JS syntax.
+  /** @type {ImportNamespaceSpecifier | undefined} */
+  let importNamespaceSpecifier
+
+  while (++index < specifiers.length) {
+    const specifier = specifiers[index]
+
+    if (specifier.type === 'ImportNamespaceSpecifier') {
+      importNamespaceSpecifier = specifier
+    } else {
+      otherSpecifiers.push(specifier)
+    }
+  }
+
+  if (importNamespaceSpecifier) {
+    /** @type {VariableDeclarator} */
+    const declarator = {
+      type: 'VariableDeclarator',
+      id: importNamespaceSpecifier.local,
+      init
+    }
+    create(importNamespaceSpecifier, declarator)
+    declarations.push(declarator)
+  }
+
+  declarations.push({
+    type: 'VariableDeclarator',
+    id: {
+      type: 'ObjectPattern',
+      properties: otherSpecifiers.map((specifier) => {
+        /** @type {Identifier} */
+        let key =
+          specifier.type === 'ImportSpecifier'
+            ? specifier.imported
+            : specifier.type === 'ExportSpecifier'
+            ? specifier.exported
+            : {type: 'Identifier', name: 'default'}
+        let value = specifier.local
+
+        // Switch them around if we’re exporting.
+        if (specifier.type === 'ExportSpecifier') {
+          value = key
+          key = specifier.local
+        }
+
+        /** @type {AssignmentProperty} */
+        const property = {
+          type: 'Property',
+          kind: 'init',
+          shorthand: key.name === value.name,
+          method: false,
+          computed: false,
+          key,
+          value
+        }
+        create(specifier, property)
+        return property
+      })
+    },
+    init: importNamespaceSpecifier
+      ? {type: 'Identifier', name: importNamespaceSpecifier.local.name}
+      : init
+  })
+
+  return declarations
+}

package/lib/util/estree-util-to-binary-addition.js

@@ -0,0 +1,23 @@
+/**
+ * @typedef {import('estree-jsx').Expression} Expression
+ */
+
+/**
+ * @param {Array<Expression>} expressions
+ */
+export function toBinaryAddition(expressions) {
+  let index = -1
+  /** @type {Expression | undefined} */
+  let left
+
+  while (++index < expressions.length) {
+    const right = expressions[index]
+    left = left ? {type: 'BinaryExpression', left, operator: '+', right} : right
+  }
+
+  // Just for types.
+  /* c8 ignore next */
+  if (!left) throw new Error('Expected non-empty `expressions` to be passed')
+
+  return left
+}

package/lib/util/estree-util-to-id-or-member-expression.js

@@ -0,0 +1,108 @@
+/**
+ * @typedef {import('estree-jsx').Identifier} Identifier
+ * @typedef {import('estree-jsx').JSXIdentifier} JSXIdentifier
+ * @typedef {import('estree-jsx').JSXMemberExpression} JSXMemberExpression
+ * @typedef {import('estree-jsx').Literal} Literal
+ * @typedef {import('estree-jsx').MemberExpression} MemberExpression
+ */
+
+import {
+  start as esStart,
+  cont as esCont,
+  name as isIdentifierName
+} from 'estree-util-is-identifier-name'
+
+export const toIdOrMemberExpression = toIdOrMemberExpressionFactory(
+  'Identifier',
+  'MemberExpression',
+  isIdentifierName
+)
+
+export const toJsxIdOrMemberExpression =
+  // @ts-expect-error: fine
+  /** @type {(ids: Array<string | number>) => JSXIdentifier | JSXMemberExpression)} */
+  (
+    toIdOrMemberExpressionFactory(
+      'JSXIdentifier',
+      'JSXMemberExpression',
+      isJsxIdentifierName
+    )
+  )
+
+/**
+ * @param {string} idType
+ * @param {string} memberType
+ * @param {(value: string) => boolean} isIdentifier
+ */
+function toIdOrMemberExpressionFactory(idType, memberType, isIdentifier) {
+  return toIdOrMemberExpression
+  /**
+   * @param {Array<string | number>} ids
+   * @returns {Identifier | MemberExpression}
+   */
+  function toIdOrMemberExpression(ids) {
+    let index = -1
+    /** @type {Identifier | Literal | MemberExpression | undefined} */
+    let object
+
+    while (++index < ids.length) {
+      const name = ids[index]
+      const valid = typeof name === 'string' && isIdentifier(name)
+
+      // A value of `asd.123` could be turned into `asd['123']` in the JS form,
+      // but JSX does not have a form for it, so throw.
+      /* c8 ignore next 3 */
+      if (idType === 'JSXIdentifier' && !valid) {
+        throw new Error('Cannot turn `' + name + '` into a JSX identifier')
+      }
+
+      /** @type {Identifier | Literal} */
+      // @ts-expect-error: JSX is fine.
+      const id = valid ? {type: idType, name} : {type: 'Literal', value: name}
+      // @ts-expect-error: JSX is fine.
+      object = object
+        ? {
+            type: memberType,
+            object,
+            property: id,
+            computed: id.type === 'Literal',
+            optional: false
+          }
+        : id
+    }
+
+    // Just for types.
+    /* c8 ignore next 3 */
+    if (!object) throw new Error('Expected non-empty `ids` to be passed')
+    if (object.type === 'Literal')
+      throw new Error('Expected identifier as left-most value')
+
+    return object
+  }
+}
+
+/**
+ * Checks if the given string is a valid JSX identifier name.
+ * @param {string} name
+ */
+function isJsxIdentifierName(name) {
+  let index = -1
+
+  while (++index < name.length) {
+    // We currently receive valid input, but this catches bugs and is needed
+    // when externalized.
+    /* c8 ignore next */
+    if (!(index ? jsxCont : esStart)(name.charCodeAt(index))) return false
+  }
+
+  // `false` if `name` is empty.
+  return index > 0
+}
+
+/**
+ * Checks if the given character code can continue a JSX identifier.
+ * @param {number} code
+ */
+function jsxCont(code) {
+  return code === 45 /* `-` */ || esCont(code)
+}

package/lib/util/render-error.js

@@ -0,0 +1,91 @@
+/**
+ * @param {SyntaxError} error
+ * @param {string} bg
+ * @param {string} color
+ * @returns {import('estree-jsx').Program}
+ */
+export default (error, bg = '#F44336', color = 'white') => {
+  return {
+    type: 'Program',
+    body: [
+      {
+        type: 'ExpressionStatement',
+        expression: {
+          type: 'JSXElement',
+          openingElement: {
+            type: 'JSXOpeningElement',
+            attributes: [
+              {
+                type: 'JSXAttribute',
+                name: {
+                  type: 'JSXIdentifier',
+                  name: 'style',
+                },
+                value: {
+                  type: 'JSXExpressionContainer',
+                  expression: {
+                    type: 'ObjectExpression',
+                    properties: [
+                      {
+                        type: 'Property',
+                        method: false,
+                        shorthand: false,
+                        computed: false,
+                        key: {
+                          type: 'Identifier',
+                          name: 'backgroundColor',
+                        },
+                        value: {
+                          type: 'Literal',
+                          value: bg,
+                          raw: `'${bg}'`,
+                        },
+                        kind: 'init',
+                      },
+                      {
+                        type: 'Property',
+                        method: false,
+                        shorthand: false,
+                        computed: false,
+                        key: {
+                          type: 'Identifier',
+                          name: 'color',
+                        },
+                        value: {
+                          type: 'Literal',
+                          value: color,
+                          raw: `'${color}'`,
+                        },
+                        kind: 'init',
+                      },
+                    ],
+                  },
+                },
+              },
+            ],
+            name: {
+              type: 'JSXIdentifier',
+              name: 'pre',
+            },
+            selfClosing: false,
+          },
+          closingElement: {
+            type: 'JSXClosingElement',
+            name: {
+              type: 'JSXIdentifier',
+              name: 'pre',
+            },
+          },
+          children: [
+            {
+              type: 'JSXText',
+              value: error.message,
+              raw: error.message,
+            },
+          ],
+        },
+      },
+    ],
+    sourceType: 'module',
+  }
+}