@ui-doc/html-renderer 0.3.0 → 1.0.0

package/scripts/utils/delay.ts

@@ -0,0 +1,12 @@
+export function throttle<T extends unknown[]>(callback: (...args: T) => void, delay: number) {
+  let timerFlag: number | null = null
+
+  return (...args: T) => {
+    if (timerFlag === null) {
+      callback(...args)
+      timerFlag = window.setTimeout(() => {
+        timerFlag = null
+      }, delay)
+    }
+  }
+}

package/scripts/utils/dom.ts

@@ -0,0 +1,77 @@
+/**
+ * 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 = (): void => {
+    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;
 }

package/styles/01_resets/typography.css

@@ -1,3 +1,16 @@
+/**
+  * @location resets.typography Typography
+  */
+
+/**
+  * @location resets.typography.font Font Style
+  * @example
+  * <div style="font-weight: bold;">Bold | bold | 700</div>
+  * <div style="font-weight: normal;">Normal | normal | 400</div>
+  * <div style="font-weight: bold; font-style: italic;">Bold Italic</div>
+  * <div style="font-weight: normal; font-style: italic;">Normal Italic</div>
+  * @hideCode
+  */
 html {
   font-size: var(--font-size-base);
   -webkit-font-smoothing: antialiased;
@@ -7,7 +20,9 @@ html {
 }
 
 body,
-.font {
+.font,
+.control,
+.btn {
   font-family: var(--font-family);
   font-size: var(--font-size);
   font-weight: var(--font-weight);
@@ -23,40 +38,122 @@ textarea {
   font-family: inherit;
 }
 
+/**
+  * You can use html headline tags or the class `.headline` to define headlines. The hedline class comes in handy if you want to display
+  * a headline without the semantic meaning of a headline tag.
+  *
+  * @location resets.typography.headlines Headlines
+  * @example
+  * <h1>Headline h1</h1>
+  * <h2>Headline h2</h2>
+  * <h3>Headline h3</h3>
+  * <h4>Headline h4</h4>
+  * <h5>Headline h5</h5>
+  * <h6>Headline h6</h6>
+  * <span class="headline h1">Class Headline h1</span>
+  * <span class="headline h2">Class Headline h2</span>
+  * <span class="headline h3">Class Headline h3</span>
+  * <span class="headline h4">Class Headline h4</span>
+  * <span class="headline h5">Class Headline h5</span>
+  * <span class="headline h6">Class Headline h6</span>
+  */
 h1,
 h2,
 h3,
 h4,
 h5,
-h6 {
+h6,
+.headline {
+  display: block;
+
+  margin-top: calc(var(--font-space-unit) * var(--headline-space, var(--space-normal)));
+  margin-bottom: 0;
+
   font-family: var(--headline-family, inherit);
   font-size: calc(var(--font-size-normal) * var(--headline-scale, 1));
-  font-weight: var(--headline-weight, inherit);
+  font-weight: var(--headline-weight, var(--font-weight-bold));
   line-height: var(--headline-line-height, inherit);
   color: rgb(var(--headline-color, inherit));
 }
 
-h1 {
+h1,
+.headline.h1 {
   --headline-scale: 2.5;
 }
 
-h2 {
+h2,
+.headline.h2 {
   --headline-scale: 2;
 }
 
-h3 {
+h3,
+.headline.h3 {
   --headline-scale: 1.75;
 }
 
-h4 {
+h4,
+.headline.h4 {
   --headline-scale: 1.5;
 }
 
+h5,
+.headline.h5 {
+  --headline-scale: 1.2;
+}
+
+h6,
+.headline.h6 {
+  --headline-scale: 1.1;
+}
+
+/**
+  * You can use the `.no-space` class to remove the margin from the headline class.
+  *
+  * @location resets.typography.headlines.no-space Headlines without space
+  * @example
+  * <span class="headline h1 no-space">Class Headline h1</span>
+  * <span class="headline h2 no-space">Class Headline h2</span>
+  */
+.headline.no-space {
+  --headline-space: 0;
+}
+
+/**
+  * @location resets.typography.text Text / Paragraph
+  * @example
+  * <p>Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. </p>
+  * <p>Duis autem vel eum iriure dolor in hendrerit in vulputate velit esse molestie consequat, vel illum dolore eu feugiat nulla facilisis at vero eros et accumsan et iusto odio dignissim qui blandit praesent luptatum zzril delenit augue duis dolore te feugait nulla facilisi. Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat.</p>
+  * <p>Ut wisi enim ad minim veniam, quis nostrud exerci tation ullamcorper suscipit lobortis nisl ut aliquip ex ea commodo consequat. Duis autem vel eum iriure dolor in hendrerit in vulputate velit esse molestie consequat, vel illum dolore eu feugiat nulla facilisis at vero eros et accumsan et iusto odio dignissim qui blandit praesent luptatum zzril delenit augue duis dolore te feugait nulla facilisi.</p>
+  */
+
+/* p {} */
+
+/**
+  * @location resets.typography.link Link
+  * @example
+  * <a href="#">Link Text</a>
+  */
 a {
   color: rgb(var(--link-color, inherit));
-  text-decoration: var(--link-decoration, none);
+  text-decoration: var(--link-decoration, underline);
+  transition: color ease var(--link-animation-time, var(--animation-time)) text-decoration ease
+    var(--link-animation-time, var(--animation-time));
+
+  &:hover {
+    --link-color: var(--link-hover-color, var(--accent-color));
+    --link-decoration: var(--link-hover-decoration, none);
+  }
 }
 
+/**
+  * @location resets.typography.format Format
+  * @example
+  * <span>Normal Text</span><br>
+  * <strong>Strong Text</strong><br>
+  * <small>Small Text</small><br>
+  * <em>Emphasis Text</em><br>
+  * <i>Italic Text</i>
+  */
 b,
 strong {
   --font-weight: var(--font-weight-bold);

package/styles/02_utils/background.css

@@ -0,0 +1,14 @@
+/**
+  * The `.bg` class can be used to set backgrounds, depending on the selected
+  * variant css variables will be changed, so all colors used inside will fit to
+  * the background.
+  *
+  * @location utils.background Background
+  */
+.bg {
+  --selection-bg-color: var(--font-color);
+  --selection-color: var(--bg-color);
+
+  color: rgb(var(--font-color));
+  background: rgb(var(--bg-color));
+}

package/styles/02_utils/control.css

@@ -0,0 +1,41 @@
+/**
+  * The `.control` class is used as base for all controls either by extending or using the class directly.
+  *
+  * @location utils.control Control
+  * @example
+  * <a class="control">Link control</a><br>
+  * <button type="button" class="control">Button control</button><br>
+  * <button type="button" class="control" disabled>Button control disabeled</button><br>
+  * <button type="button" class="control no-hover">Disable hover effect</button><br>
+  */
+.control,
+.btn {
+  --space-px: 0;
+  --space-py: 0;
+
+  cursor: pointer;
+
+  display: inline-block;
+
+  padding: var(--py, calc(var(--space-unit) * var(--space-py)))
+    var(--px, calc(var(--space-unit) * var(--space-px)));
+
+  text-align: center;
+  text-decoration: none;
+  word-break: keep-all;
+
+  appearance: none;
+  background: rgb(var(--control-bg-color, transparent));
+  border: none;
+  border-radius: unset;
+  outline: none;
+
+  &:hover:not([aria-disabled="true"], [disabled], .btn[class*="bg-"], .no-hover) {
+    --font-color: var(--control-hover-color, var(--accent-color));
+  }
+
+  &[aria-disabled="true"],
+  &:disabled {
+    cursor: not-allowed;
+  }
+}