arche 0.3.11 → 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')
 ```
 
-Create dynamic components with props:
-```javascript [playground]
+## 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
+```
+
+## 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,28 +200,10 @@ render(Example())
 // </div>
 ```
 
-## Installation
-with `npm`
-```bash
-npm i arche
-```
-
-browser script, global `Arche`
-```html
-<script src="https://unpkg.com/arche"></script>
-```
-
-browser module
-```javascript
-import Arche from 'https://unpkg.com/arche/es.js'
-```
-
-## Usage
-Set Arche elements globally for a better developer experience.
+Set `ReactElement` globally for a better developer experience.
 
 ```javascript
 // global.js
-
 const ReactElement = Arche(React)
 
 window.ReactElement = ReactElement
@@ -106,43 +212,38 @@ 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')
 ```
 
-## Syntax
-```coffeescript [specscript]
-Arche() -> DocumentElement
-Arche(document Document) -> DocumentElement
+## Syntax with React
 
-DocumentElement(elementType string) -> Element
-DocumentElement(elementType string, props object, text string) -> Element
-
-Arche(React {
+```coffeescript [specscript]
+type React = {
   createElement: (
     elementType string,
-    props? object,
-    children? string|Array<React.Element|string>
-  )=>ReactElement
-}) -> ReactElement
+    props object,
+    children string|Array<React.Element|string>
+  )=>(reactElement React.Element)
+}
 
-ReactElement(elementType string, props object, text string) -> React.Element
+Arche(React) -> ReactElement
 
 ReactElement(
   elementType string,
   props object,
-  children Array<React.Element|string>
-) -> React.Element
-
-ReactElement(elementType string) -> TypedReactElement function
+  text string
+) -> reactElement React.Element
 
-TypedReactElement(props object, text string) -> React.Element
-TypedReactElement(text string)-> React.Element
-TypedReactElement(children Array<React.Element|string>)-> 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
@@ -182,10 +283,51 @@ 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
+To use React Context with Arche, wrap `YourContext.Provider` with `ReactElement` and supply `value` as a prop, specifying children in the next argument.
+
+JSX example:
+```javascript
+function ArticleWrapper () {
+  const [theme, setTheme] = React.useState(themes[0])
+
+  return (
+    <ThemeContext.Provider value={{
+      theme,
+      changeTheme: setTheme
+    }}>
+      <ThemeSwitcher />
+      <Article />
+    </ThemeContext.Provider>
+  )
+}
+```
+
+Translates to the following with Arche:
+```javascript
+const ArticleWrapper = ReactElement(() => {
+  const [theme, setTheme] = React.useState(themes[0])
+
+  return ReactElement(ThemeContext.Provider)({
+    value: { theme, changeTheme: setTheme },
+  }, [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 the base elements. This does not apply to composite components (those created with `ReactElement(props => {...})` syntax)
+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
@@ -208,71 +350,122 @@ const MyComponent = ReactElement(props => {
 
 ## Syntax with styled
 ```coffeescript [specscript]
-strings Array<string>
-values Array<any>
-tagFunctionArgs Array<strings, ...values>
+([css string])=>(reactElement React.Element) -> StyledComponent
 
 type Styled = {
-  h1: (...tagFunctionArgs)=>React.Element,
-  h2: (...tagFunctionArgs)=>React.Element,
-  h3: (...tagFunctionArgs)=>React.Element,
-  h4: (...tagFunctionArgs)=>React.Element,
-  h5: (...tagFunctionArgs)=>React.Element,
-  div: (...tagFunctionArgs)=>React.Element,
-  button: (...tagFunctionArgs)=>React.Element,
-  a: (...tagFunctionArgs)=>React.Element,
-  p: (...tagFunctionArgs)=>React.Element,
-  span: (...tagFunctionArgs)=>React.Element,
-  img: (...tagFunctionArgs)=>React.Element,
-  ul: (...tagFunctionArgs)=>React.Element,
-  ol: (...tagFunctionArgs)=>React.Element,
-  li: (...tagFunctionArgs)=>React.Element,
-  form: (...tagFunctionArgs)=>React.Element,
-  article: (...tagFunctionArgs)=>React.Element,
-  main: (...tagFunctionArgs)=>React.Element,
-  section: (...tagFunctionArgs)=>React.Element,
-  nav: (...tagFunctionArgs)=>React.Element,
+  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,
-    children? string|Array<React.Element|string>,
-  )=>ReactElement
+    props object,
+    textOrChildren string|Array<React.Element|string>
+  )=>(reactElement React.Element)
 }, options {
   styled: Styled,
   styledMemoizationCap?: number
-}) -> ReactElement
-```
+}) -> reactElement ReactElement
 
-## Using React Context
-To use React Context with Arche, wrap `YourContext.Provider` with `ReactElement` and supply `value` as a prop, specifying children in the next argument.
+ReactElement(
+  elementType string,
+  propsWithCss { css: string, ...props object },
+  text string
+) -> reactElement React.Element
 
-JSX example:
-```javascript
-function ArticleWrapper () {
-  const [theme, setTheme] = React.useState(themes[0])
+ReactElement(
+  elementType string,
+  propsWithCss { css: string, ...props object },
+  children Array<React.Element|string>
+) -> reactElement React.Element
 
-  return (
-    <ThemeContext.Provider value={{
-      theme,
-      changeTheme: setTheme
-    }}>
-      <ThemeSwitcher />
-      <Article />
-    </ThemeContext.Provider>
-  )
-}
-```
+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
 
-Translates to the following with Arche:
-```javascript
-const ArticleWrapper = ReactElement(() => {
-  const [theme, setTheme] = React.useState(themes[0])
+TypedReactElement(
+  propsWithCss { css: string, ...props object },
+  text string
+) -> reactElement React.Element
 
-  return ReactElement(ThemeContext.Provider)({
-    value: { theme, changeTheme: setTheme },
-  }, [ThemeSwitcher(), Article()])
-})
+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

package/es.js

@@ -1,7 +1,7 @@
 /**
- * Arche v0.3.11
+ * Arche v1.0.0
  * https://github.com/richytong/arche
- * (c) 2020-2023 Richard Tong
+ * (c) 2026 Richard Tong
  * Arche may be freely distributed under the MIT license.
  */