arche 0.3.11 → 1.0.1

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

@@ -1,56 +1,112 @@
 # Arche
 ![arche-logo](https://raw.githubusercontent.com/a-synchronous/assets/master/arche-logo-226x226.png)
-> Arche (/ˈɑːrki/; Ancient Greek: ἀρχή) is a Greek word with primary senses "beginning", "origin" or "source of action" (ἐξ' ἀρχῆς: from the beginning, οr ἐξ' ἀρχῆς λόγος: the original argument), and later "first principle" or "element". ([wikipedia](https://en.wikipedia.org/wiki/Arche))
+> Arche (/ˈɑːrki/; Ancient Greek: ἀρχή) is a Greek word with primary senses "beginning", "origin" or "source of action" (ἐξ' ἀρχῆς: from the beginning, οr ἐξ' ἀρχῆς λόγος: the original argument), and later "first principle" or "element".
 
 ![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)
+[![npm version](https://img.shields.io/npm/v/arche.svg?style=flat)](https://www.npmjs.com/package/arche)
 
-HTML as JavaScript. 
+Simplified DOM interface / React in pure JavaScript.
 
 ```javascript [playground]
-const ReactElement = Arche(React)
-// supply the React library
+{
+  const DocumentElement = Arche(document)
+  const { Div, H1, P } = DocumentElement
+
+  const myElement = Div({ id: 'my-element' }, [
+    H1('DOM Example'),
+    P('paragraph'),
+    P('lorem ipsum'),
+  ])
 
-const { Div, H1, P } = ReactElement
-// some common building blocks are provided on ReactElement
-// as property functions.
-
-const myElement = Div([
-  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>
-// </div>
+  document.getElementById('dom-container').appendChild(myElement)
+}
+
+{
+  const ReactElement = Arche(React)
+  const { Div, H1, P, Button, Img } = ReactElement
+
+  const UserCard = ReactElement(({
+    firstName, lastName, age,
+  }) => Div([
+    H1(`${firstName} ${lastName}`),
+    Img({ src: 'https://placehold.co/300x300', alt: 'placeholder' }),
+    P({ style: { color: 'lightgrey' } }, `age: ${age}`),
+  ]))
+
+  ReactDOM.render(
+    UserCard({ firstName: 'React', lastName: 'ExampleUser', 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:
+## 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 [playground]
 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' }),
+  Img({ src: 'https://placehold.co/300x300', alt: 'placeholder' }),
   P({ style: { color: 'lightgrey' } }, `age: ${age}`),
 ]))
 
-render(UserCard({ firstName: 'George', lastName: 'Henry', age: 32 }))
-// <div>
-//   <h1>George Henry</h1>
-//   <img src="https://via.placeholder.com/150x150" alt="placeholder">
-//   <p style="color: lightgrey">age: 32</p>
-// </div>
+ReactDOM.render(
+  UserCard({ firstName: 'Example', lastName: 'Name', age: 32 }),
+  document.getElementById('react-root')
+)
 ```
 
-Complete interoperability with React hooks (converted from [this example](https://reactjs.org/docs/hooks-intro.html)):
+Complete interoperability with React hooks (converted from [this example](https://reactjs.org/docs/hooks-intro.html)).
+
 ```javascript [playground]
 const ReactElement = Arche(React)
 const { Div, P, Button } = ReactElement
@@ -69,35 +125,13 @@ const Example = ReactElement(() => {
   ])
 })
 
-render(Example())
-// <div>
-//   <p>You clicked {count} times</p>
-//   <button onclick="setCount(count + 1)">Click me</button>
-// </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'
+ReactDOM.render(Example(), document.getElementById('react-root'))
 ```
 
-## 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,146 +140,12 @@ 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
-
-DocumentElement(elementType string) -> Element
-DocumentElement(elementType string, props object, text string) -> Element
-
-Arche(React {
-  createElement: (
-    elementType string,
-    props? object,
-    children? string|Array<React.Element|string>
-  )=>ReactElement
-}) -> ReactElement
-
-ReactElement(elementType string, props object, text string) -> React.Element
-
-ReactElement(
-  elementType string,
-  props object,
-  children Array<React.Element|string>
-) -> React.Element
-
-ReactElement(elementType string) -> TypedReactElement function
-
-TypedReactElement(props object, text string) -> React.Element
-TypedReactElement(text string)-> React.Element
-TypedReactElement(children Array<React.Element|string>)-> React.Element
-
-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
-```
-
-## 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)
-
-```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]
-strings Array<string>
-values Array<any>
-tagFunctionArgs Array<strings, ...values>
-
-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,
-}
-
-Arche(React {
-  createElement: (
-    elementType string,
-    props? object,
-    children? string|Array<React.Element|string>,
-  )=>ReactElement
-}, options {
-  styled: Styled,
-  styledMemoizationCap?: number
-}) -> 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.
 
@@ -276,3 +176,49 @@ 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
+const ReactElement = Arche(React, { styled })
+```
+
+Elements can now specify a `css` prop to use css-in-js.
+
+```javascript [playground]
+const ReactElement = Arche(React, { styled })
+const { Div, H1, P } = ReactElement
+
+const MyComponent = ReactElement(() => {
+  return Div({
+    css: `
+      height: 500px;
+      width: 100%;
+      background-color: pink;
+    `,
+  }, [
+    H1('Styled Example'),
+    P('Text'),
+  ])
+})
+
+ReactDOM.render(MyComponent(), document.getElementById('react-root'))
+```
+
+# 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. 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](https://github.com/richytong/arche/blob/master/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