@ui-doc/html-renderer 0.3.0 → 0.4.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ui-doc/html-renderer",
   "description": "HTML renderer for UI-Doc.",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "license": "MIT",
   "keywords": [
     "ui-doc",
@@ -55,7 +55,7 @@
   },
   "sideEffects": false,
   "peerDependencies": {
-    "@ui-doc/core": "^0.3.0"
+    "@ui-doc/core": "^0.3.1"
   },
   "optionalDependencies": {
     "@highlightjs/cdn-assets": "^11.9.0"
@@ -63,7 +63,7 @@
   "scripts": {
     "build": "rollup -c",
     "prebuild": "rm -rf dist dist",
-    "prerelease": "pnpm build",
+    "prepublish": "pnpm build",
     "release": "pnpm --workspace-root package:release $(pwd)",
     "release:dry": "pnpm --workspace-root package:release-dry $(pwd)",
     "test": "jest"

package/scripts/app.ts

@@ -1,8 +1,10 @@
-import { initExample } from './src/example'
-import { initSidebar } from './src/sidebar'
-import { ready } from './src/utils'
+import { initExample } from './services/example'
+import { initExpand } from './services/expand'
+import { initSidebar } from './services/sidebar'
+import { ready } from './utils/dom'
 
 ready(() => {
+  initExpand()
   initExample()
   initSidebar()
 })

package/scripts/services/expand.ts

@@ -0,0 +1,207 @@
+import { animate } from '../utils/dom'
+import { queryParentSelector } from '../utils/select'
+
+/**
+ * Sometimes you need to prevent the user from interacting with other elements while an element is expanded. Then you need the [inert](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/inert) attribute.
+ * You can set the `data-inert` attribute with selectors (comma separated) to control the `inert` attribute of elements matching your selectors.
+ * @location functions.expand.with-inerts Expand controlling inert
+ * @order 30
+ * @example
+ * <style>
+ * button::after {
+ *   content: ' ' attr(aria-expanded);
+ * }
+ * </style>
+ * <button aria-expanded="false" aria-controls="target">Expanded:</button>
+ * <div id="target" hidden data-inert="[data-inert-controlled],#inert-controlled-2">Controlled Target</div>
+ * <div data-inert-controlled=""><button>Button 1.1</button><button>Button 1.2</button></div>
+ * <div id="inert-controlled-2"><button>Button 2.1</button><button>Button 2.2</button></div>
+ * @code
+ * <button aria-expanded="false" aria-controls="target">Expanded:</button>
+ * <div id="target" hidden data-inert="[data-inert-controlled],#inert-controlled-2">Controlled Target</div>
+ * <div data-inert-controlled="1"><button>Button 1.1</button><button>Button 1.2</button></div>
+ * <div id="inert-controlled-2"><button>Button 2.1</button><button>Button 2.2</button></div>
+ */
+function toggleInert(target: HTMLElement, show: boolean): void {
+  const inertSelector = target.getAttribute('data-inert')
+
+  if (!inertSelector) {
+    return
+  }
+
+  inertSelector.split(',').forEach(selector => {
+    // if the target is inside an element with the same selector, we don't want to remove the inert attribute
+    const activeParentWithSameSelector = !show
+      ? queryParentSelector(
+          target.parentElement,
+          `[data-inert="${selector}"],[data-inert^="${selector},"],[data-inert$=",${selector}"],[data-inert*=",${selector},"]`,
+        )
+      : null
+
+    if (activeParentWithSameSelector) {
+      return
+    }
+
+    document.querySelectorAll(selector).forEach(invertOn => {
+      if (show) {
+        invertOn.setAttribute('inert', '')
+      } else {
+        invertOn.removeAttribute('inert')
+      }
+    })
+  })
+}
+
+/**
+ * If you want to control a specific aria you can combine [aria-expanded](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) attribute with [aria-controls](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls) attribute.
+ *
+ * When an element with the `aria-expanded` attribute is clicked, the value of the attribute will be toggled between `true` and `false`. Also the element with the id specified in the `aria-controls` attribute will be toggled between `aria-hidden="true"` and `aria-hidden="false"`. If no `aria-hidden` attribute is present, the `hidden` attribute will be used.`
+ *
+ * @location functions.expand.with-controls Expand with controls
+ * @order 10
+ * @example
+ * <style>
+ * button::after {
+ *   content: ' ' attr(aria-expanded);
+ * }
+ * </style>
+ * <button aria-expanded="true" aria-controls="target-aria-hidden">Expanded:</button>
+ * <div id="target-aria-hidden" aria-hidden="false">Controlled Target</div>
+ * <hr>
+ * <button aria-expanded="true" aria-controls="target-hidden">Expanded:</button>
+ * <div id="target-hidden">Controlled Target</div>
+ * @code
+ * <button aria-expanded="true" aria-controls="target-aria-hidden">Expanded:</button>
+ * <div id="target-aria-hidden" aria-hidden="false">Controlled Target</div>
+ * <hr>
+ * <button aria-expanded="true" aria-controls="target-hidden">Expanded:</button>
+ * <div id="target-hidden">Controlled Target</div>
+ */
+
+/**
+ * You can add animations/transitions on the controlled element by adding the `data-animate` attribute with the animation name.
+ * The animation name will be used to add the necessary classes to the element to trigger the animation.
+ * Please refer to the animate function for more information, what classes will be added and when.
+ *
+ * @location functions.expand.with-animation Expand with animation
+ * @order 20
+ * @example
+ * <style>
+ *   .fade-enter-active,
+ *   .fade-leave-active {
+ *     transition: opacity 0.5s ease;
+ *   }
+ *
+ *   .fade-enter-from,
+ *   .fade-leave-to {
+ *     opacity: 0;
+ *   }
+ * </style>
+ * <button aria-expanded="true" aria-controls="target-hidden">Toggle Controlled Area</button>
+ * <div id="target-hidden" data-animate="fade">Controlled Target</div>
+ */
+function toggleControlTarget(selector: string, show: boolean, callback: () => void): void {
+  const target = document.querySelector<HTMLElement>(selector)
+
+  if (!target) {
+    return
+  }
+
+  const animationName = target.getAttribute('data-animate')
+  const toggleHide = () => {
+    if (target.hasAttribute('aria-hidden')) {
+      target.setAttribute('aria-hidden', show ? 'false' : 'true')
+    } else if (show) {
+      target.removeAttribute('hidden')
+    } else {
+      target.setAttribute('hidden', '')
+    }
+
+    callback()
+  }
+
+  if (show) {
+    // set tabindex=0 for all elements with tabindex=-1 that are not inside an aria-hidden element
+    target
+      .querySelectorAll<HTMLElement>(
+        ':scope > [tabindex="-1"], [tabindex="-1"]:not([aria-hidden="true"] [tabindex="-1"], [hidden] [tabindex="-1"])',
+      )
+      .forEach(el => {
+        el.setAttribute('tabindex', '0')
+      })
+  } else {
+    // set tabindex=-1 for all elements with tabindex=0
+    target.querySelectorAll<HTMLElement>('[tabindex="0"]').forEach(el => {
+      el.setAttribute('tabindex', '-1')
+    })
+  }
+
+  toggleInert(target, show)
+
+  if (animationName) {
+    if (show) {
+      toggleHide()
+      animate(target, animationName, show)
+    } else {
+      animate(target, animationName, show, toggleHide)
+    }
+  } else {
+    toggleHide()
+  }
+}
+
+/**
+ * Initialize expandable/collapsable elements by using the [aria-expanded](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) attribute.
+ *
+ * When an element with the `aria-expanded` attribute is clicked, the value of the attribute will be toggled between `true` and `false`.
+ *
+ * @location functions.expand Expand
+ * @example
+ * <style>
+ * button::after {
+ *   content: ' ' attr(aria-expanded);
+ * }
+ * </style>
+ * <button aria-expanded="false">Expanded:</button>
+ * @code
+ * <button aria-expanded="false">Expanded:</button>
+ */
+export function initExpand(): void {
+  document.querySelectorAll<HTMLElement>('[aria-expanded]').forEach(expander => {
+    const controlTarget = expander.getAttribute('aria-controls')
+    const toggle = (e: MouseEvent) => {
+      const expanded = expander.getAttribute('aria-expanded') === 'true'
+      const toggleExpanded = () => {
+        expander.setAttribute('aria-expanded', expanded ? 'false' : 'true') // when expanded we need to set false
+      }
+
+      // if data-hide-same-level is set, we need to klick all other expanded elements to close them
+      if (expander.parentElement && expander.hasAttribute('data-hide-same-level')) {
+        Array.from(expander.parentElement.querySelectorAll(':scope > [aria-expanded="true"]'))
+          .filter(el => el !== expander && el !== e.relatedTarget)
+          .forEach(sibling => {
+            sibling.dispatchEvent(
+              new MouseEvent('click', { bubbles: true, relatedTarget: expander }),
+            )
+          })
+      }
+
+      if (controlTarget) {
+        toggleControlTarget(`#${controlTarget}`, !expanded, toggleExpanded)
+      } else {
+        toggleExpanded()
+      }
+    }
+
+    expander.addEventListener('click', toggle)
+
+    if (controlTarget) {
+      // select all controls inside the controlled area that have the same aria-controls attribute
+      document
+        .querySelectorAll<HTMLElement>(`#${controlTarget} [aria-controls="${controlTarget}"]`)
+        .forEach(control => {
+          control.addEventListener('click', toggle)
+        })
+    }
+  })
+}

package/scripts/{src/utils.ts → utils/delay.ts}

@@ -1,11 +1,3 @@
-export function ready(callback: () => void) {
-  if (document.readyState !== 'loading') {
-    callback()
-  } else {
-    document.addEventListener('DOMContentLoaded', callback)
-  }
-}
-
 export function throttle(callback: (...args: any[]) => void, delay: number) {
   let timerFlag: number | null = null
 

package/scripts/utils/dom.ts

@@ -0,0 +1,73 @@
+/**
+ * Run function when dom is ready
+ *
+ * @param callback function to run when dom is ready
+ */
+export function ready(callback: (this: Document) => void): void {
+  if (document.readyState !== 'loading') {
+    callback.call(document)
+  } else {
+    document.addEventListener('DOMContentLoaded', callback)
+  }
+}
+
+/**
+ * Animate an element using css animations/transitions. This function will add the necessary classes to the element to trigger the animation.
+ * When doing an entering animation following classes will be added:
+ * - `[animation-name]-enter-active`
+ * - `[animation-name]-enter-from`
+ * - `[animation-name]-enter-to`
+ * When doing a leaving animation following classes will be added:
+ * - `[animation-name]-leave-active`
+ * - `[animation-name]-leave-from`
+ * - `[animation-name]-leave-to`
+ *
+ * The animation classes will be removed after the animation is done. If a callback is provided it will be called after the animation is done.
+ *
+ * The `-active` class will stay on the element until the animation is done. The `-from` class will be removed after the first frame and the `-to`
+ * class will be added after the first frame.
+ *
+ * @param target html element to animate
+ * @param animationName animation name to be used
+ * @param entering determine if the elements animation should be entering or leaving
+ * @param callback to be called after the animation is done
+ */
+export function animate(
+  target: HTMLElement,
+  animationName: string,
+  entering: boolean,
+  callback?: () => void,
+): void {
+  const animationState = entering ? 'enter' : 'leave'
+  const animateClassActive = `${animationName}-${animationState}-active`
+  const animateClassTo = `${animationName}-${animationState}-to`
+  const animateClassFrom = `${animationName}-${animationState}-from`
+  const afterAnimation = () => {
+    target.classList.remove(animateClassTo, animateClassActive)
+    target.removeEventListener('animationend', afterAnimation)
+    target.removeEventListener('transitionend', afterAnimation)
+
+    if (callback) {
+      callback()
+    }
+  }
+
+  target.addEventListener('animationend', afterAnimation)
+  target.addEventListener('transitionend', afterAnimation)
+
+  target.addEventListener('animationcancel', afterAnimation)
+  target.addEventListener('transitioncancel', afterAnimation)
+
+  target.classList.add(animateClassActive, animateClassFrom)
+  requestAnimationFrame(() => {
+    const styles = window.getComputedStyle(target)
+
+    // if the element has no transition or animation we can call the afterAnimation function in the next frame
+    if (['all', 'none'].includes(styles.transition) && styles.animationName === 'none') {
+      requestAnimationFrame(afterAnimation)
+    }
+
+    target.classList.remove(animateClassFrom)
+    target.classList.add(animateClassTo)
+  })
+}

package/scripts/utils/select.ts

@@ -0,0 +1,46 @@
+/**
+ * Query the first parent element that matches the selector
+ *
+ * @param element to search in
+ * @param selector to be matched
+ * @param maxDepth maximum depth to search
+ * @returns element that matches the selector
+ */
+
+export function queryParentSelector<K extends keyof HTMLElementTagNameMap>(
+  element: HTMLElement | null,
+  selector: K,
+  maxDepth?: number,
+): HTMLElementTagNameMap[K] | null
+export function queryParentSelector<K extends keyof SVGElementTagNameMap>(
+  element: HTMLElement | null,
+  selector: K,
+  maxDepth?: number,
+): SVGElementTagNameMap[K] | null
+export function queryParentSelector<K extends keyof MathMLElementTagNameMap>(
+  element: HTMLElement | null,
+  selectors: K,
+  maxDepth?: number,
+): MathMLElementTagNameMap[K] | null
+export function queryParentSelector<E extends Element = Element>(
+  element: HTMLElement | null,
+  selector: string,
+  maxDepth?: number,
+): E | null
+export function queryParentSelector(
+  element: HTMLElement | null,
+  selector: string,
+  maxDepth = 10,
+): Element | null {
+  if (maxDepth <= 0 || element === null) {
+    return null
+  }
+
+  if (element.matches(selector)) {
+    return element as Element
+  }
+
+  return element.parentElement
+    ? queryParentSelector(element.parentElement, selector, maxDepth - 1)
+    : null
+}

package/styles/01_resets/initial.css

@@ -1,6 +1,5 @@
 * {
   box-sizing: border-box;
-  margin: 0;
 }
 
 *::after,
@@ -10,9 +9,15 @@
 
 ::selection {
   color: rgb(var(--selection-color));
-  background-color: rgb(var(--selection-bg-color));
+  background: rgb(var(--selection-bg-color));
+}
+
+html {
+  scroll-behavior: smooth;
+  scroll-padding-top: var(--scroll-padding-top, 0);
 }
 
 body {
-  background-color: rgb(var(--bg-color));
+  margin: 0;
+  background: rgb(var(--bg-color));
 }

package/styles/01_resets/root/color.css

@@ -0,0 +1,19 @@
+/**
+  * The color variables are used to define the color palette.
+  *
+  * The color variables are defined by RGB value. When you want to use a color you need use the `rgb()` function. For example: `rgb(var(--color-black))`.
+  *
+  * @location variables.colors Colors
+  * @color {0 0 0|255 255 255} --color-black | Black
+  * @color {20 33 61|255 255 255} --color-blue | Blue
+  * @color {252 163 17} --color-yellow | Yellow
+  * @color {229 229 229} --color-gray | Gray
+  * @color {255 255 255} --color-white | White
+  */
+:root {
+  --color-black: 0 0 0;
+  --color-blue: 20 33 61;
+  --color-yellow: 252 163 17;
+  --color-gray: 229 229 229;
+  --color-white: 255 255 255;
+}

package/styles/01_resets/root/font.css

@@ -0,0 +1,28 @@
+/**
+  * Set of predefined font variables.
+  *
+  * @location variables.font Font
+  */
+:root {
+  /**
+    * Font weights are a set of predefined values that can be used to define the weight of a font:
+    * - **--font-weight-normal**
+    * - **--font-weight-bold**
+    *
+    * @location variables.font.weight Font weight
+    */
+  --font-weight-normal: 400;
+  --font-weight-bold: 700;
+
+  /**
+    * Font sizes are a set of predefined values that can be used to define the size of a font:
+    * - **--font-size-sm**
+    * - **--font-size-normal**
+    * - **--font-size-md**
+    *
+    * @location variables.font.size Font size
+    */
+  --font-size-sm: 0.85em;
+  --font-size-normal: 1em;
+  --font-size-md: 1.2em;
+}

package/styles/01_resets/root/space.css

@@ -0,0 +1,30 @@
+/**
+  * Space are a set of predefined values that can be used to define the space of an element.
+  * When spaces are used there is always a set of two variables you can use the `--space-unit` and `--space-<size>`.
+  * The `--space-unit` is the base unit that will be multiplied by the `--space-<size>`. Depending on the context
+  * you are using the space `<size>` changes.
+  *
+  * The predefined space can the be set in a specific context by defining the `--space-<size>` variable.
+  * For example the space unit is `1rem` and we are in the padding context, we can use `--space-pt: var(--space-md);` to change the padding
+  * top to the medium space.
+  *
+  * @location variables.spaces Spaces
+  * @space {0.35em} --space-xxs | Extra extra small
+  * @space {0.5em} --space-xs | Extra small
+  * @space {0.7em} --space-sm | Small
+  * @space {1em} --space-normal | Normal
+  * @space {1.3em} --space-md | Medium
+  * @space {1.8em} --space-lg | Large
+  * @space {3.2em} --space-xl | Extra large
+  * @space {4.8em} --space-xxl | Extra extra large
+  */
+:root {
+  --space-xxs: 0.35;
+  --space-xs: 0.5;
+  --space-sm: 0.7;
+  --space-normal: 1;
+  --space-md: 1.3;
+  --space-lg: 1.8;
+  --space-xl: 3.2;
+  --space-xxl: 4.8;
+}

package/styles/01_resets/root/witdh.css

@@ -0,0 +1,12 @@
+/**
+  * Widths are a set of predefined values that can be used to limit the content width.
+  *
+  * - `--width-min-offset-x` - The minimum space on the left and right side.
+  * - `--width-content` - The width of the content.
+  *
+  * @location variables.width Width (Content)
+  */
+:root {
+  --width-min-offset-x: 22px;
+  --width-content: 1200px;
+}

package/styles/01_resets/root.css

@@ -1,36 +1,74 @@
+@import url("./root/color.css");
+@import url("./root/font.css");
+@import url("./root/space.css");
+@import url("./root/witdh.css");
+
+/**
+  * There are some global veriables that are used in the project. These variables are a base set and can be changed depending on context and requirements. All components are using these variables to define the style or as a fallback if there more specific named variable is not present.
+  *
+  * @location variables.global Globals
+  */
 :root {
-  --font-weight-normal: 400;
-  --font-weight-bold: 700;
-  --font-size-sm: 0.85em;
-  --font-size-normal: 1em;
-  --font-size-md: 1.2em;
-  --font-size-lg: 1.7em;
+  /**
+    * - `--font-space-unit` - The spacing unit when using font related spaces (see the spaces documentation for mor details).
+    * - `--font-size-base` - The base font size.
+    * - `--font-color` - used font color.
+    * - `--font-family` - uded font family.
+    * - `--font-weight` - used font weight.
+    * - `--font-size` - used font size.
+    * - `--font-line-height` - used font line height.
+    *
+    * @location variables.global.font Font
+    */
+  --font-space-unit: 1em;
   --font-size-base: 16px;
-  --font-color: 3 3 3;
+  --font-color: var(--color-black);
   --font-family: system-ui, "Segoe UI", roboto, helvetica, arial, sans-serif, "Apple Color Emoji",
     "Segoe UI Emoji", "Segoe UI Symbol";
   --font-weight: var(--font-weight-normal);
   --font-size: var(--font-size-normal);
   --font-line-height: 1.4;
-  --headline-weight: var(--font-weight-bold);
-  --bg-color: 255 255 255;
-  --accent-color: 3 3 200;
-  --border-color: 5 5 5;
+
+  /**
+    * - `--bg-color` - used background color
+    * - `--accent-color` - used accent color
+    * - `--selection-color` - used selection color
+    * - `--selection-bg-color` - used selection background color
+    * - `--animation-time` - used animation time
+    *
+    * @location variables.global.colors Colors
+    */
+  --bg-color: var(--color-white);
+  --accent-color: var(--color-yellow);
   --selection-color: var(--bg-color);
   --selection-bg-color: var(--font-color);
-  --size-base-unit: 1rem;
-  --size-xs: calc(0.5 * var(--size-base-unit));
-  --size-sm: calc(0.8 * var(--size-base-unit));
-  --size-normal: var(--size-base-unit);
-  --size-md: calc(1.2 * var(--size-base-unit));
-  --size-lg: calc(1.6 * var(--size-base-unit));
-  --size-xl: calc(2.4 * var(--size-base-unit));
-  --nav-main-menu-item-px: var(--size-sm);
-  --nav-main-menu-item-py: var(--size-xs);
-  --nav-main-menu-item-font-size: var(--font-size-md);
-  --nav-main-height: calc(
-    var(--nav-main-menu-item-py) * 2 + var(--nav-main-menu-item-font-size) * var(--font-line-height)
+  --space-unit: 1em;
+
+  /**
+    *
+    * - `--animation-time` - used animation time
+    *
+    * @location variables.global.animation Animation
+    */
+  --animation-time: 0.25s;
+
+  /**
+    * @location variables.global.nav-main Main navigation
+    */
+  --nav-main-bar-item-space-x: var(--space-normal);
+  --nav-main-bar-item-space-y: var(--space-sm);
+  --nav-main-bar-item-height: calc(
+    (var(--font-size) * var(--font-line-height)) +
+      (var(--space-unit) * var(--nav-main-bar-item-space-y) * 2)
   );
+  --nav-main-menu-space-t: var(--space-sm);
+  --nav-main-menu-space-b: var(--space-normal);
+  --nav-main-height: var(--nav-main-bar-item-height);
+
+  /**
+    * @location variables.global.nav-main Main navigation
+    */
+  --scroll-padding-top: var(--nav-main-height);
 
   color-scheme: light;
 }