arche 0.3.10 → 1.0.0

package/.eslintrc.js

@@ -75,10 +75,7 @@ module.exports = {
         'func-call-spacing': 'error',
         'func-name-matching': 'off',
         'func-names': 'off',
-        'func-style': [
-            'error',
-            'expression'
-        ],
+        'func-style': 'off',
         'function-call-argument-newline': [
             'error',
             'consistent'

package/CONTRIBUTING.md

@@ -0,0 +1,24 @@
+# Contributing
+
+## Steps to release
+
+1. Bump the repo version
+
+```
+npm version patch|minor|major
+```
+
+2. Copy everything in the scope starting with 'use strict' in `index.js` to `es.js` and `index.mjs`
+
+3. Manually update the code versions and year
+
+4. Commit the changes
+
+```
+git commit -m "distribute"
+```
+
+5. Publish the new version
+```
+npm publish
+```

package/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2020 Richard Tong
+Copyright (c) 2025 Richard Tong
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -5,33 +5,156 @@
 ![Node.js CI](https://github.com/richytong/arche/actions/workflows/nodejs.yml/badge.svg)
 [![codecov](https://codecov.io/gh/richytong/arche/branch/master/graph/badge.svg)](https://codecov.io/gh/richytong/arche)
 
-HTML as JavaScript. 
+Simplified DOM interface / React in pure JavaScript.
 
-```javascript [playground]
-const ReactElement = Arche(React)
-// supply the React library
-
-const { Div, H1, P } = ReactElement
-// some common building blocks are provided on ReactElement
-// as property functions.
+```javascript
+const DocumentElement = Arche(document)
+const { Div, H1, P } = DocumentElement
 
-const myElement = Div([
+const myElement = Div({ id: 'my-element' }, [
   H1('I am a heading'),
   P('paragraph'),
   P('lorem ipsum'),
 ])
 
-render(myElement)
-// <div>
-//   <h1>I am a heading</h1>
-//   <p>paragraph</p>
-//   <p>lorem ipsum</p>
+document.getElementById('#my-container').appendChild(myElement)
+// <div id="my-container">
+//   <div id="my-element">
+//     <h1>I am a heading</h1>
+//     <p>paragraph</p>
+//     <p>lorem ipsum</p>
+//   </div>
 // </div>
+
+const ReactElement = Arche(React)
+const { Div, H1, P, Button, Img } = ReactElement
+
+const UserCard = ReactElement(({
+  firstName, lastName, age,
+}) => Div([
+  H1(`${firstName} ${lastName}`),
+  Img({ src: 'https://via.placeholder.com/150x150', alt: 'placeholder' }),
+  P({ style: { color: 'lightgrey' } }, `age: ${age}`),
+]))
+
+ReactDOM.render(
+  UserCard({ firstName: 'Example', lastName: 'Name', age: 32 }),
+  document.getElementById('react-root')
+)
+```
+
+## Installation
+with `npm`
+
+```bash
+npm i arche
+```
+
+with browser script, sets `window.Arche`
+
+```html
+<script src="https://unpkg.com/arche"></script>
+```
+
+with [ES Modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules)
+```javascript
+import Arche from 'https://unpkg.com/arche/es.js'
+```
+
+Set `DocumentElement` globally for a better developer experience.
+
+```javascript
+// global.js
+const DocumentElement = Arche()
+
+window.DocumentElement = DocumentElement
+
+for (const elementName in DocumentElement) {
+  window[elementName] = DocumentElement[elementName]
+}
+
+// set missing elements
+window.Aside = DocumentElement('aside')
+window.Svg = DocumentElement('svg')
+window.Path = DocumentElement('path')
+```
+
+## Syntax
+```coffeescript [specscript]
+Arche() -> DocumentElement
+Arche(document Document) -> DocumentElement
+
+DocumentElement(
+  elementType string,
+  props object,
+  text string
+) -> element Element
+
+DocumentElement(
+  elementType string,
+  props object,
+  children Array<Element|string>
+) -> element Element
+
+DocumentElement(elementType string) -> TypedDocumentElement
+DocumentElement.A -> TypedDocumentElement
+DocumentElement.P -> TypedDocumentElement
+DocumentElement.B -> TypedDocumentElement
+DocumentElement.Q -> TypedDocumentElement
+DocumentElement.I -> TypedDocumentElement
+DocumentElement.Ul -> TypedDocumentElement
+DocumentElement.Ol -> TypedDocumentElement
+DocumentElement.Li -> TypedDocumentElement
+DocumentElement.H1 -> TypedDocumentElement
+DocumentElement.H2 -> TypedDocumentElement
+DocumentElement.H3 -> TypedDocumentElement
+DocumentElement.H4 -> TypedDocumentElement
+DocumentElement.H5 -> TypedDocumentElement
+DocumentElement.H6 -> TypedDocumentElement
+DocumentElement.Hr -> TypedDocumentElement
+DocumentElement.Br -> TypedDocumentElement
+DocumentElement.Script -> TypedDocumentElement
+DocumentElement.Html -> TypedDocumentElement
+DocumentElement.Body -> TypedDocumentElement
+DocumentElement.Nav -> TypedDocumentElement
+DocumentElement.Section -> TypedDocumentElement
+DocumentElement.Article -> TypedDocumentElement
+DocumentElement.Footer -> TypedDocumentElement
+DocumentElement.Span -> TypedDocumentElement
+DocumentElement.Div -> TypedDocumentElement
+DocumentElement.Img -> TypedDocumentElement
+DocumentElement.Video -> TypedDocumentElement
+DocumentElement.Form -> TypedDocumentElement
+DocumentElement.Fieldset -> TypedDocumentElement
+DocumentElement.Input -> TypedDocumentElement
+DocumentElement.Label -> TypedDocumentElement
+DocumentElement.Textarea -> TypedDocumentElement
+DocumentElement.Select -> TypedDocumentElement
+DocumentElement.Option -> TypedDocumentElement
+DocumentElement.Button -> TypedDocumentElement
+DocumentElement.Iframe -> TypedDocumentElement
+DocumentElement.Blockquote -> TypedDocumentElement
+DocumentElement.Code -> TypedDocumentElement
+DocumentElement.Pre -> TypedDocumentElement
+
+TypedDocumentElement(props object, text string) -> element Element
+TypedDocumentElement(text string) -> element Element
+TypedDocumentElement(props object, children Array<Element|string>) -> element Element
+TypedDocumentElement(children Array<Element|string>) -> element Element
 ```
 
-Create dynamic components with props:
-```javascript [playground]
+## Using React
+To use Arche with [React](https://react.dev/), simply provide the React library.
+
+```javascript
 const ReactElement = Arche(React)
+```
+
+Create dynamic components with props.
+
+```javascript
+const ReactElement = Arche(React)
+
 const { Div, H1, P, Button, Img } = ReactElement
 
 const UserCard = ReactElement(({
@@ -42,16 +165,17 @@ const UserCard = ReactElement(({
   P({ style: { color: 'lightgrey' } }, `age: ${age}`),
 ]))
 
-render(UserCard({ firstName: 'George', lastName: 'Henry', age: 32 }))
+render(UserCard({ firstName: 'Example', lastName: 'Name', age: 32 }))
 // <div>
-//   <h1>George Henry</h1>
+//   <h1>Example Name</h1>
 //   <img src="https://via.placeholder.com/150x150" alt="placeholder">
 //   <p style="color: lightgrey">age: 32</p>
 // </div>
 ```
 
-Complete interoperability with React hooks (converted from [this example](https://reactjs.org/docs/hooks-intro.html)):
-```javascript [playground]
+Complete interoperability with React hooks (converted from [this example](https://reactjs.org/docs/hooks-intro.html)).
+
+```javascript
 const ReactElement = Arche(React)
 const { Div, P, Button } = ReactElement
 const { useState } = React
@@ -76,44 +200,10 @@ render(Example())
 // </div>
 ```
 
-# Installation
-with `npm`
-```bash
-npm i arche
-```
-
-browser script, global `Arche`
-```html
-<script src="https://unpkg.com/arche"></script>
-```
+Set `ReactElement` globally for a better developer experience.
 
-browser module
-```javascript
-import Arche from 'https://unpkg.com/arche/es.js'
-```
-
-# Syntax
-```coffeescript [specscript]
-Arche() -> DocumentElement
-Arche(document Document) -> DocumentElement
-Arche(React {
-  createElement: (type, props?, children?)=>ReactElement,
-}, options? {
-  styled?: {
-    div: function,
-    p: funcion,
-    span: function,
-    // etc
-  },
-  styledMemoizationCap?: number, // defaults to 1000
-}) -> ReactElement
-```
-
-# Usage
-Set Arche elements globally for a great developer experience.
 ```javascript
 // global.js
-
 const ReactElement = Arche(React)
 
 window.ReactElement = ReactElement
@@ -122,33 +212,87 @@ for (const elementName in ReactElement) {
   window[elementName] = ReactElement[elementName]
 }
 
-// Arche for now does not export every element
-// create the ones you need like so
+// set missing elements
 window.Aside = ReactElement('aside')
 window.Svg = ReactElement('svg')
 window.Path = ReactElement('path')
 ```
 
-## Using styled
-Arche accepts a `styled` option from css-in-js libraries like [Styled Components](https://styled-components.com/) to enable a `css` prop on the base elements. This does not apply to composite components (those created with `ReactElement(props => {...})` syntax)
+## Syntax with React
 
-```javascript
-// global.js
-const ReactElement = Arche(React, { styled })
-```
+```coffeescript [specscript]
+type React = {
+  createElement: (
+    elementType string,
+    props object,
+    children string|Array<React.Element|string>
+  )=>(reactElement React.Element)
+}
 
-Elements can now specify a `css` prop to use css-in-js.
+Arche(React) -> ReactElement
 
-```javascript
-// MyComponent.js
-const MyComponent = ReactElement(props => {
-  return Div({
-    css: `
-      width: 500px;
-      background-color: pink;
-    `,
-  })
-})
+ReactElement(
+  elementType string,
+  props object,
+  text string
+) -> reactElement React.Element
+
+ReactElement(
+  elementType string,
+  props object,
+  children Array<React.Element|string>
+) -> reactElement React.Element
+
+ReactElement(elementType string) -> TypedReactElement
+ReactElement.A -> TypedReactElement
+ReactElement.P -> TypedReactElement
+ReactElement.B -> TypedReactElement
+ReactElement.Q -> TypedReactElement
+ReactElement.I -> TypedReactElement
+ReactElement.Ul -> TypedReactElement
+ReactElement.Ol -> TypedReactElement
+ReactElement.Li -> TypedReactElement
+ReactElement.H1 -> TypedReactElement
+ReactElement.H2 -> TypedReactElement
+ReactElement.H3 -> TypedReactElement
+ReactElement.H4 -> TypedReactElement
+ReactElement.H5 -> TypedReactElement
+ReactElement.H6 -> TypedReactElement
+ReactElement.Hr -> TypedReactElement
+ReactElement.Br -> TypedReactElement
+ReactElement.Script -> TypedReactElement
+ReactElement.Html -> TypedReactElement
+ReactElement.Body -> TypedReactElement
+ReactElement.Nav -> TypedReactElement
+ReactElement.Section -> TypedReactElement
+ReactElement.Article -> TypedReactElement
+ReactElement.Footer -> TypedReactElement
+ReactElement.Span -> TypedReactElement
+ReactElement.Div -> TypedReactElement
+ReactElement.Img -> TypedReactElement
+ReactElement.Video -> TypedReactElement
+ReactElement.Form -> TypedReactElement
+ReactElement.Fieldset -> TypedReactElement
+ReactElement.Input -> TypedReactElement
+ReactElement.Label -> TypedReactElement
+ReactElement.Textarea -> TypedReactElement
+ReactElement.Select -> TypedReactElement
+ReactElement.Option -> TypedReactElement
+ReactElement.Button -> TypedReactElement
+ReactElement.Iframe -> TypedReactElement
+ReactElement.Blockquote -> TypedReactElement
+ReactElement.Code -> TypedReactElement
+ReactElement.Pre -> TypedReactElement
+
+TypedReactElement(props object, text string) -> reactElement React.Element
+TypedReactElement(text string) -> reactElement React.Element
+
+TypedReactElement(
+  props object,
+  children Array<React.Element|string>
+) -> reactElement React.Element
+
+TypedReactElement(children Array<React.Element|string>) -> reactElement React.Element
 ```
 
 ## Using React Context
@@ -181,3 +325,147 @@ const ArticleWrapper = ReactElement(() => {
   }, [ThemeSwitcher(), Article()])
 })
 ```
+
+## Using styled
+Arche accepts a `styled` option from css-in-js libraries like [Styled Components](https://styled-components.com/) to enable a `css` prop on `ReactElement` and `TypedReactElement`.
+
+```javascript
+// global.js
+const ReactElement = Arche(React, { styled })
+```
+
+Elements can now specify a `css` prop to use css-in-js.
+
+```javascript
+// MyComponent.js
+const MyComponent = ReactElement(props => {
+  return Div({
+    css: `
+      width: 500px;
+      background-color: pink;
+    `,
+  })
+})
+```
+
+## Syntax with styled
+```coffeescript [specscript]
+([css string])=>(reactElement React.Element) -> StyledComponent
+
+type Styled = {
+  h1: StyledComponent,
+  h2: StyledComponent,
+  h3: StyledComponent,
+  h4: StyledComponent,
+  h5: StyledComponent,
+  div: StyledComponent,
+  button: StyledComponent,
+  a: StyledComponent,
+  p: StyledComponent,
+  span: StyledComponent,
+  img: StyledComponent,
+  ul: StyledComponent,
+  ol: StyledComponent,
+  li: StyledComponent,
+  form: StyledComponent,
+  article: StyledComponent,
+  main: StyledComponent,
+  section: StyledComponent,
+  nav: StyledComponent,
+}
+
+Arche(React {
+  createElement: (
+    elementType string,
+    props object,
+    textOrChildren string|Array<React.Element|string>
+  )=>(reactElement React.Element)
+}, options {
+  styled: Styled,
+  styledMemoizationCap?: number
+}) -> reactElement ReactElement
+
+ReactElement(
+  elementType string,
+  propsWithCss { css: string, ...props object },
+  text string
+) -> reactElement React.Element
+
+ReactElement(
+  elementType string,
+  propsWithCss { css: string, ...props object },
+  children Array<React.Element|string>
+) -> reactElement React.Element
+
+ReactElement(elementType string) -> TypedReactElement
+ReactElement.A -> TypedReactElement
+ReactElement.P -> TypedReactElement
+ReactElement.B -> TypedReactElement
+ReactElement.Q -> TypedReactElement
+ReactElement.I -> TypedReactElement
+ReactElement.Ul -> TypedReactElement
+ReactElement.Ol -> TypedReactElement
+ReactElement.Li -> TypedReactElement
+ReactElement.H1 -> TypedReactElement
+ReactElement.H2 -> TypedReactElement
+ReactElement.H3 -> TypedReactElement
+ReactElement.H4 -> TypedReactElement
+ReactElement.H5 -> TypedReactElement
+ReactElement.H6 -> TypedReactElement
+ReactElement.Hr -> TypedReactElement
+ReactElement.Br -> TypedReactElement
+ReactElement.Script -> TypedReactElement
+ReactElement.Html -> TypedReactElement
+ReactElement.Body -> TypedReactElement
+ReactElement.Nav -> TypedReactElement
+ReactElement.Section -> TypedReactElement
+ReactElement.Article -> TypedReactElement
+ReactElement.Footer -> TypedReactElement
+ReactElement.Span -> TypedReactElement
+ReactElement.Div -> TypedReactElement
+ReactElement.Img -> TypedReactElement
+ReactElement.Video -> TypedReactElement
+ReactElement.Form -> TypedReactElement
+ReactElement.Fieldset -> TypedReactElement
+ReactElement.Input -> TypedReactElement
+ReactElement.Label -> TypedReactElement
+ReactElement.Textarea -> TypedReactElement
+ReactElement.Select -> TypedReactElement
+ReactElement.Option -> TypedReactElement
+ReactElement.Button -> TypedReactElement
+ReactElement.Iframe -> TypedReactElement
+ReactElement.Blockquote -> TypedReactElement
+ReactElement.Code -> TypedReactElement
+ReactElement.Pre -> TypedReactElement
+
+TypedReactElement(
+  propsWithCss { css: string, ...props object },
+  text string
+) -> reactElement React.Element
+
+TypedReactElement(text string) -> reactElement React.Element
+
+TypedReactElement(
+  propsWithCss { css: string, ...props object },
+  children Array<React.Element|string>
+) -> reactElement React.Element
+
+TypedReactElement(children Array<React.Element|string>) -> reactElement React.Element
+```
+
+# Contributing
+Your feedback and contributions are welcome. If you have a suggestion, please raise an issue. Prior to that, please search through the issues first in case your suggestion has been made already. If you decide to work on an issue, please create a pull request.
+
+Pull requests should provide some basic context and link the relevant issue. Here is an [example pull request](https://github.com/a-synchronous/rubico/pull/12). If you are interested in contributing, the [help wanted](https://github.com/richytong/arche/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) tag is a good place to start.
+
+For more information please see [CONTRIBUTING.md](/CONTRIBUTING.md)
+
+# License
+Arche is [MIT Licensed](https://github.com/a-synchronous/rubico/blob/master/LICENSE).
+
+# Support
+ * minimum Node.js version: 14
+ * minimum Chrome version: 63
+ * minimum Firefox version: 57
+ * minimum Edge version: 79
+ * minimum Safari version: 11.1