docs(jsx): add details to documentation (#909)

* docs(jsx): add details to documentation

* docs: update packages/jsx/README.md

Co-authored-by: Raman Aktsisiuk <[email protected]>

---------

Co-authored-by: Arutiunian Artem <[email protected]>
Co-authored-by: Raman Aktsisiuk <[email protected]>

packages/jsx/README.md

@@ -130,6 +130,24 @@ Object-valued `style` prop applies styles granularly: `style={{top: 0, display:
 
 `false`, `null` and `undefined` style values remove the property. Non-string style values are stringified (we don't add `px` to numeric values automatically).
 
+Incorrect:
+```tsx
+<div
+  style={atom((ctx) => ctx.spy(bool)
+    ? ({top: 0})
+    : ({bottom: 0}))}
+></div>
+```
+
+Correct:
+```tsx
+<div
+  style={atom((ctx) => ctx.spy(bool)
+    ? ({top: 0; bottom: undefined})
+    : ({top: undefined; bottom: 0}))}
+></div>
+```
+
 ### CSS-in-JS
 
 We have a minimal, intuitive, and efficient styling engine tightly integrated with components. You can set a styles in `css` prop and all relative css-variables to `css:variable-name` prop.
@@ -185,7 +203,9 @@ In Reatom, there is no concept of "rerender" like React. Instead, we have a spec
 
 ```tsx
 <div
-  $spread={atom((ctx) => (ctx.spy(valid) ? { disabled: true, readonly: true } : { disabled: false, readonly: false }))}
+  $spread={atom((ctx) => (ctx.spy(valid)
+    ? { disabled: true, readonly: true }
+    : { disabled: false, readonly: false }))}
 />
 ```
 
@@ -201,6 +221,68 @@ const anSvgElement = (
 )
 ```
 
+If you need to use SVG as a string, you can choose from these options:
+
+Option 1:
+
+```tsx
+const SvgIcon = (props: {svg: string}) => {
+  const svgEl = new DOMParser()
+    .parseFromString(props.svg, 'image/svg+xml')
+    .children
+    .item(0) as SVGElement
+  return svgEl
+}
+```
+
+Option 2:
+
+```tsx
+const SvgIcon = (props: {svg: string}) => {
+  return (
+    <svg:svg
+      prop:outerHTML={props.svg}
+    ><svg:svg>
+  )
+}
+```
+
+### Ref
+
+The `ref` property is used to create and track references to DOM elements, allowing actions to be performed when these elements are mounted and unmounted.
+
+
+```tsx
+<button ref={(ctx: Ctx, el: HTMLButtonElement) => {
+  el.focus()
+  return (ctx: Ctx, el: HTMLButtonElement) => el.blur()
+}}></button>
+```
+
+Mounting and unmounting functions are called in order from child to parent.
+
+```tsx
+<div ref={(ctx: Ctx, el: HTMLDivElement) => {
+  console.log('mount', 'parent')
+  return () => console.log('unmount', 'parent')
+}}>
+  <span ref={(ctx: Ctx, el: HTMLSpanElement) => {
+    console.log('mount', 'child')
+    return () => console.log('unmount', 'child')
+  }}>
+  </span>
+</div>
+```
+
+When this code is executed, the console will display the following result:
+
+```ts
+mount child
+mount parent
+unmount child
+unmount parent
+```
+
 <!-- ### Lifecycle
 
 In Reatom, every atom has lifecycle events to which you can subscribe with `onConnect`/`onDisconnect` functions. By default, components don't have an atom associated with them, but you may wrap the component code in an atom manually to achieve the same result:
@@ -283,3 +365,10 @@ These limitations will be fixed in the feature
 
 - No DOM-less SSR (requires a DOM API implementation like `linkedom` to be provided)
 - No keyed lists support
+- A component should have no more than one root element. If this interferes with the layout, you can wrap the parent elements in another element with the style `display: "contents"`:
+```tsx
+<div style={'display: "contents";'}>
+  <div class="parent-1">
+  <div class="parent-2">
+</div>
+```

packages/jsx/src/index.test.tsx

@@ -498,9 +498,11 @@ test('ref mount and unmount callbacks order', async () => {
   const order: number[] = []
 
   const createRef = (index: number) => {
-    order.push(index)
     return () => {
       order.push(index)
+      return () => {
+        order.push(index)
+      }
     }
   }
 
@@ -517,7 +519,33 @@ test('ref mount and unmount callbacks order', async () => {
   parent.remove()
   await sleep()
 
-  assert.equal(order, [0, 1, 2, 2, 1, 0])
+  assert.equal(order, [2, 1, 0, 2, 1, 0])
+})
+
+test('style object update', () => {
+  const { ctx, h, hf, parent, mount, window } = setup()
+
+  const styleAtom = atom({
+    top: '0',
+    right: undefined,
+    bottom: null as unknown as undefined,
+    left: '0',
+  } as JSX.CSSProperties)
+
+  const component = (
+    <div style={styleAtom}></div>
+  )
+
+  mount(parent, component)
+
+  assert.is(component.getAttribute('style'), 'top:0;left:0')
+
+  styleAtom(ctx, {
+    top: undefined,
+    bottom: '0',
+  })
+
+  assert.is(component.getAttribute('style'), 'left:0;bottom:0')
 })
 
 test.run()