Merge pull request #44 from 21TORR/remaining-dune-docs

Add remaining dune docs

blog/2024-05-06-symfony-libs.mdx

@@ -1,7 +1,11 @@
 ---
 title: "Document Symfony + PHP Libs"
 authors: [jannik]
-tags: [simple-normalizer]
+tags:
+    - simple-normalizer
+    - task-manager
+    - html-builder
+    - dune
 ---
 
 A bunch of new docs were written:
@@ -18,7 +22,7 @@ Also the TS docs were updated:
 - [Dune DOM helpers] are now documented.
 
 
-[Dune DOM helpers]: /docs/ts-scss/dune/dom
+[Dune DOM helpers]: /docs/ts-scss/dune/helpers
 [HTML Builder]: /docs/php/library/html-builder
 [Simple Normalizer]: /docs/php/symfony/simple-normalizer
 [Task Manager]: /docs/php/symfony/task-manager

blog/2024-05-07-dune-docs.mdx

@@ -0,0 +1,29 @@
+---
+title: "Finalize Dune Docs"
+authors: [jannik]
+tags: [dune]
+---
+
+The [Dune] docs were finalized:
+
+- [DOM Attribute helpers] are now documented.
+- [JSON helpers] are now documented.
+- [Network helpers] are now documented.
+- [Popup Interaction helpers] are now documented.
+- [Timing helpers] are now documented.
+- [Usercentrics] component and hooks is documented.
+- [HTTP Basic Auth middleware] is documented.
+- [Media Query Hooks] are documented.
+- [Debounce Hook] is documented.
+
+
+[Debounce Hook]: /docs/ts-scss/dune/react/debounce
+[DOM Attribute helpers]: /docs/ts-scss/dune/helpers#dom-attribute
+[Dune]: /docs/ts-scss/dune
+[HTTP Basic Auth middleware]: /docs/ts-scss/dune/react/http-auth
+[JSON helpers]: /docs/ts-scss/dune/helpers#json
+[Media Query Hooks]: /docs/ts-scss/dune/react/media-query
+[Network helpers]: /docs/ts-scss/dune/helpers#network
+[Popup Interaction helpers]: /docs/ts-scss/dune/helpers#popup-interaction
+[Timing helpers]: /docs/ts-scss/dune/helpers#timing
+[Usercentrics]: /docs/ts-scss/dune/react/usercentrics

docs/php/tooling/janus-php.mdx

@@ -96,9 +96,9 @@ We use our own [PHP-CS-Fixer] package, as it adds custom configuration for our u
 
 
 
-[Composer bin plugin]: /docs/php/tooling#composer-bin-plugin
+[Composer bin plugin]: /docs/php/tooling/#composer-bin-plugin
 [Composer Normalize]: https://github.com/ergebnis/composer-normalize
 [PHP CS Fixer]: https://github.com/PHP-CS-Fixer/PHP-CS-Fixer
 [PHP-CS-Fixer]: /docs/php/tooling/php-cs-fixer
 [PHPStan]: https://phpstan.org/
-[the note about it]: /docs/php/tooling#phpunit
+[the note about it]: /docs/php/tooling/#phpunit

docs/php/tooling/php-cs-fixer.mdx

@@ -46,4 +46,4 @@ After installation, you can run the tools like this:
 ./vendor/bin/php-cs-fixer fix --dry-run --diff --config vendor-bin/cs-fixer/vendor/21torr/php-cs-fixer/.php-cs-fixer.dist.php
 ```
 
-[Composer bin plugin]: /docs/php/tooling#composer-bin-plugin
+[Composer bin plugin]: /docs/php/tooling/#composer-bin-plugin

docs/ts-scss/dune/dom.mdx → docs/ts-scss/dune/helpers.mdx

@@ -1,10 +1,92 @@
-# DOM Helpers
+# Helpers
 
-The library contains several helper functions for working with the DOM.
 
-## HTML Attributes
+## DOM Attribute
 
-## Events
+### `toggleClass()`
+
+```typescript
+toggleClass(element, className, addClass)
+```
+
+A helper, where you can control via the `addClass` parameter whether to add or remove classes.
+
+- You can pass an array of elements as `element`.
+- You can also pass multiple classes as array in `className`.
+
+
+
+## DOM Traversal
+
+### `findFirst()`
+
+```typescript
+findFirst(selector, context)
+```
+
+Small wrapper around `querySelector()`. Pass the container as `context` you want to search in, by default `document` is used.
+
+
+### `find()`
+
+```typescript
+find(selector, context)
+```
+
+Wrapper around `querySelectorAll`, always returns a (real) array. Pass the container as `context` you want to search in, by default `document` is used.
+
+
+### `children()`
+
+```typescript
+children(parent, selector = null)
+```
+
+Returns all children elements of the given `parent`. Can be directly filtered by the given selector.
+
+
+### `prev()`
+
+```typescript
+prev(element, selector = null)
+```
+
+Returns all previous siblings, optionally only those matching a given selector. Excludes the `element` itself.
+
+
+### `next()`
+
+```typescript
+next(element, selector = null)
+```
+
+Returns all following siblings, optionally only those matching a given selector. Excludes the `element` itself.
+
+
+### `closest()`
+
+```typescript
+closest(element, selector, rootElement = null)
+```
+
+Finds the nearest parent that matches the given selector. The element itself is **included**, if it matches.
+
+You can optionally pass a maximum root element, where the search should stop, so that you can contain the search to a specific subtree.
+
+
+### `isChildOf()`
+
+```typescript
+isChildOf(parent, node)
+```
+
+Checks, whether the given `node` is a child of the `parent`.
+
+Will return `true` if both parameters are the same node.
+
+
+
+## Event
 
 ### `on()`
 
@@ -137,70 +219,145 @@ trigger(button, "click", {
 ```
 
 
-## DOM Traversal
 
-### `findFirst()`
+## JSON
+
+### `safeParseJson()`
 
 ```typescript
-findFirst(selector, context)
+safeParseJson<DataType>(value)
 ```
 
-Small wrapper around `querySelector()`. Pass the container as `context` you want to search in, by default `document` is used.
+Parses the given value as JSON and returns it cast as the `DataType`.
+
+:::caution
+This function doesn't validate the data in any way. It is recommended to use zod to validate the schema.
+:::
 
 
-### `find()`
+### `parseElementContentAsJson()`
 
 ```typescript
-find(selector, context)
+parseElementContentAsJson<DataType>(element)
 ```
 
-Wrapper around `querySelectorAll`, always returns a (real) array. Pass the container as `context` you want to search in, by default `document` is used.
+Uses the text content of the given element, parses it as JSON and returns the parsed json.
+
+This is especially useful when hydrating `<script type="application/json">` tags.
+
+:::caution
+This function doesn't validate the data in any way. It is recommended to use zod to validate the schema.
+:::
 
 
-### `children()`
+
+## Network
+
+### `isAbortError()`
 
 ```typescript
-children(parent, selector = null)
+isAbortError(error)
 ```
 
-Returns all children elements of the given `parent`. Can be directly filtered by the given selector.
+A helper to help when catching fetch failures. They occur frequently when fetching in an effect in React and eagerly aborting the request when rerunning the effect.
 
+```typescript
+import {isAbortError} from "@21torr/dune/network";
+
+useEffect(() =>
+{
+	const controller = new AbortController();
+
+	fetch(..., {
+		signal: controller.signal,
+	})
+		.then(...)
+		.catch(error =>
+		{
+			if (isAbortError(error))
+			{
+				// don't do anything for abort errors
+				return;
+			}
+
+			// ...
+		});
+
+	return () =>
+	{
+		controller.abort();
+	};
+}, [...]);
+```
+
+:::best-practice
+Always properly abort your `fetch()` requests in effects when rerunning.
+:::
 
-### `prev()`
+
+
+## Popup Interaction
+
+These helpers provide support for overlay integrations.
+
+### `registerBodyClickHandler()`
 
 ```typescript
-prev(element, selector = null)
+registerBodyClickHandler(allowedClickTargets, onInvalidTargetClick) : UnregisterCallback
 ```
 
-Returns all previous siblings, optionally only those matching a given selector. Excludes the `element` itself.
+Registers a global click handler, that checks for every click if it is in one of the `allowedClickTargets`. If it isn't, the `onInvalidTargetClick` callback is triggered.
 
+Returns an unregister callback to remove the global click listener.
+
+> This is useful for implementing overlays: you can detect clicks outside the overlay, but add the overlay itself as allowed click target.
 
-### `next()`
+
+### `initDismissibleContainer()`
 
 ```typescript
-next(element, selector = null)
+initDismissibleContainer(
+	trigger,
+	allowedContainers,
+	callback,
+) : DismissibleContainerDirector
 ```
 
-Returns all following siblings, optionally only those matching a given selector. Excludes the `element` itself.
+It takes a list of `triggers` and a list of `allowedContainers`. To integrate the interaction, you pass a `callback`.
 
+The integration does the following things:
 
-### `closest()`
+- if the status changes, the `callback` is called with a boolean parameter, that tells you whether it is active or not
+- A click on a trigger toggles the active state
+- When active, a click outside the `triggers` / the `allowedContainers` sets the state to inactive.
+
+It returns a director, that can be called directly to set the state to inactive, and has an additional `destroy()` helper:
 
 ```typescript
-closest(element, selector, rootElement = null)
+const director = initDismissibleContainer(...);
+
+// set the state to inactive
+director();
+
+// destroy the integration (= removes all listeners etc)
+directory.destroy();
 ```
 
-Finds the nearest parent that matches the given selector. The element itself is **included**, if it matches.
 
-You can optionally pass a maximum root element, where the search should stop, so that you can contain the search to a specific sub tree.
+> This helps you to implement an overview, just like [`registerBodyClickHandler()`](#registerbodyclickhandler). The additional feature here is the automatic integration of external triggers.
+>
+> So in this example the overlay might be a navigation drawer, that can be toggled by a hamburger button somewhere in the page.
 
 
-### `isChildOf()`
+
+## Timing
+
+### `onNextAnimationFrame()`
 
 ```typescript
-isChildOf(parent, node)
+onNextAnimationFrame(callback)
 ```
 
-Checks, whether the given `node` is a child of the `parent`.
+Helper to integrate in animation frames. This will combine multiple calls during the same frame to a single call.
 
-Will return `true` if both parameters are the same node.
+> This is useful to debounce fast triggering events, like `mousemove`, `scroll` or `resize`.

docs/ts-scss/dune/index.mdx

@@ -11,3 +11,49 @@ import {LinkList} from "../../../src/components/Link/LinkList";
 
 It provides standalone functions, React components and Next.js-integrated components.
 
+
+
+## DOM + JS Helpers
+
+- [`children()`](/docs/ts-scss/dune/helpers#children)
+- [`closest()`](/docs/ts-scss/dune/helpers#closest)
+- [`delegate()`](/docs/ts-scss/dune/helpers#delegate)
+- [`find()`](/docs/ts-scss/dune/helpers#find)
+- [`findFirst()`](/docs/ts-scss/dune/helpers#findfirst)
+- [`initDismissibleContainer()`](/docs/ts-scss/dune/helpers#initdismissiblecontainer)
+- [`isAbortError()`](/docs/ts-scss/dune/helpers#isaborterror)
+- [`isChildOf()`](/docs/ts-scss/dune/helpers#ischildof)
+- [`next()`](/docs/ts-scss/dune/helpers#next)
+- [`off()`](/docs/ts-scss/dune/helpers#off)
+- [`on()`](/docs/ts-scss/dune/helpers#on)
+- [`once()`](/docs/ts-scss/dune/helpers#once)
+- [`onNextAnimationFrame()`](/docs/ts-scss/dune/helpers#onnextanimationframe)
+- [`onOff()`](/docs/ts-scss/dune/helpers#onoff)
+- [`parseElementContentAsJson()`](/docs/ts-scss/dune/helpers#parseelementcontentasjson)
+- [`prev()`](/docs/ts-scss/dune/helpers#prev)
+- [`registerBodyClickHandler()`](/docs/ts-scss/dune/helpers#registerbodyclickhandler)
+- [`safeParseJson()`](/docs/ts-scss/dune/helpers#safeparsejson)
+- [`toggleClass()`](/docs/ts-scss/dune/helpers#toggleclass)
+- [`trigger()`](/docs/ts-scss/dune/helpers#trigger)
+
+
+
+## React Helpers
+
+Some of these components / hooks are intended to be used in Next.js only, some can be used in a standalone React project. Look at the imports of the implementation to see which is Next.js-only.
+
+- **React Components**
+	- [`<AnchorIntegration />`](/docs/ts-scss/dune/react/anchor-integration)
+	- [`<ClientOnlyPortal />`](/docs/ts-scss/dune/react/client-only-portal)
+	- [`<Cookiebot />`](/docs/ts-scss/dune/react/cookiebot#component)
+	- [`<Usercentrics />`](/docs/ts-scss/dune/react/usercentrics#component)
+
+- **React Hooks**
+	- [`useCookiebot()`](/docs/ts-scss/dune/react/cookiebot#hook)
+	- [`useDebounced()`](/docs/ts-scss/dune/react/debounce)
+	- [`useMediaQuery()`](/docs/ts-scss/dune/react/media-query)
+	- [`useUsercentrics()`](/docs/ts-scss/dune/react/usercentrics#hook)
+
+
+- **Next.js Middleware Integrations**
+	- [`handleHttpBasicAuth()`](/docs/ts-scss/dune/react/http-auth)

docs/ts-scss/dune/react/anchor-integration.mdx

@@ -15,7 +15,7 @@ This element circumvents the issue, by waiting after the initial render (and the
 You should load this component once in your app. If you are using Next.js, a (fairly top-level) layout would be the correct place for it.
 
 ```tsx
-import {AnchorIntegration} from "@21torr/dune/next/components/Structure/AnchorIntegration.js";
+import {AnchorIntegration} from "@21torr/dune/next/components/Structure/AnchorIntegration";
 
 <AnchorIntegration />
 ```