@graupl/graupl 1.0.0-alpha.9 → 1.0.0-beta.0

package/src/js/carousel/index.js

@@ -0,0 +1,10 @@
+import Carousel from "./Carousel.js";
+
+document.addEventListener("DOMContentLoaded", () => {
+  document.querySelectorAll(".carousel").forEach((carouselElement) => {
+    new Carousel({
+      carouselElement,
+      initialize: true,
+    });
+  });
+});

package/src/js/domHelpers.js

@@ -0,0 +1,37 @@
+/**
+ * Add a class or array of classes to an element.
+ *
+ * @param {string|string[]} className - The class or classes to add.
+ * @param {HTMLElement} element - The element to add the class to.
+ */
+export function addClass(className, element) {
+  // Gracefully handle empty strings or arrays.
+  if (className === "" || className.length === 0) {
+    return;
+  }
+
+  if (typeof className === "string") {
+    element.classList.add(className);
+  } else {
+    element.classList.add(...className);
+  }
+}
+
+/**
+ * Remove a class or array of classes from an element.
+ *
+ * @param {string|string[]} className - The class or classes to remove.
+ * @param {HTMLElement} element - The element to remove the class from.
+ */
+export function removeClass(className, element) {
+  // Gracefully handle empty strings or arrays.
+  if (className === "" || className.length === 0) {
+    return;
+  }
+
+  if (typeof className === "string") {
+    element.classList.remove(className);
+  } else {
+    element.classList.remove(...className);
+  }
+}

package/src/js/eventHandlers.js

@@ -0,0 +1,39 @@
+/**
+ * Retrieves the pressed key from an event.
+ *
+ * @param   {KeyboardEvent} event - The keyboard event.
+ * @return  {string}              - The name of the key or an empty string.
+ */
+export function keyPress(event) {
+  try {
+    // Use event.key or event.keyCode to support older browsers.
+    const key = event.key || event.keyCode;
+    const keys = {
+      Enter: key === "Enter" || key === 13,
+      Space: key === " " || key === "Spacebar" || key === 32,
+      Escape: key === "Escape" || key === "Esc" || key === 27,
+      ArrowUp: key === "ArrowUp" || key === "Up" || key === 38,
+      ArrowRight: key === "ArrowRight" || key === "Right" || key === 39,
+      ArrowDown: key === "ArrowDown" || key === "Down" || key === 40,
+      ArrowLeft: key === "ArrowLeft" || key === "Left" || key === 37,
+      Home: key === "Home" || key === 36,
+      End: key === "End" || key === 35,
+      Tab: key === "Tab" || key === 9,
+    };
+
+    return Object.keys(keys).find((key) => keys[key] === true) || "";
+  } catch {
+    // Return an empty string if something goes wrong.
+    return "";
+  }
+}
+
+/**
+ * Stops an event from taking action.
+ *
+ * @param {Event} event - The event.
+ */
+export function preventEvent(event) {
+  event.preventDefault();
+  event.stopPropagation();
+}

package/src/js/navigation/index.js

@@ -0,0 +1,36 @@
+import storage from "../storage.js";
+
+document.addEventListener("DOMContentLoaded", function () {
+  const navs = document.querySelectorAll(".navigation");
+
+  navs.forEach((nav) => {
+    const MenuConstructor = nav.dataset.grauplMenuType || DisclosureMenu;
+
+    if (window[MenuConstructor] === undefined) {
+      console.warn(
+        `Graupl navigation requires accessible-menu's ${MenuConstructor}. Please make sure to include it on this page.`
+      );
+
+      return;
+    }
+
+    const menuOptions =
+      JSON.parse(nav.dataset.grauplMenuOptions.replace(/'/g, '"')) || {};
+    const menuElement = nav.querySelector(".menu");
+    const controllerElement = nav.querySelector(".navigation-toggle") || null;
+    const containerElement = controllerElement ? nav : null;
+    const menu = new window[MenuConstructor]({
+      menuElement,
+      menuItemSelector: ".menu-item",
+      menuLinkSelector: ".menu-link",
+      submenuItemSelector: ".submenu-item",
+      submenuToggleSelector: ".submenu-toggle",
+      controllerElement,
+      containerElement,
+      ...menuOptions,
+    });
+
+    storage.initializeStorage("menus");
+    storage.pushToStorage("menus", menu.dom.menu.id, menu);
+  });
+});

package/src/js/storage.js

@@ -0,0 +1,106 @@
+/**
+ * @file
+ * Provides a system to get and store Graupl data in the browser.
+ */
+
+import { isValidType } from "./validate.js";
+
+/**
+ * Initializes the storage system.
+ *
+ * @param {?string} [type = null] - The type of storage to initialize.
+ */
+export function initializeStorage(type = null) {
+  window.Graupl = window.Graupl || {};
+
+  if (isValidType("string", { type })) {
+    window.Graupl[type] = window.Graupl[type] || {};
+  }
+}
+
+/**
+ * Get the storage object.
+ *
+ * @param  {?string} type - The type of storage to get.
+ * @return {object}       - The storage object.
+ */
+export function getStorage(type = null) {
+  if (isValidType("string", { type })) {
+    return window.Graupl[type];
+  }
+
+  return window.Graupl;
+}
+
+/**
+ * Set the storage object of a given type.
+ *
+ * @param {string} type - The type of storage to set.
+ * @param {object} data - The data to set.
+ */
+export function setStorage(type, data = {}) {
+  if (isValidType("string", { type }) && isValidType("object", { data })) {
+    window.Graupl[type] = data;
+  }
+}
+
+/**
+ * Clear the storage object of a given type.
+ *
+ * @param {string} type - The type of storage to clear.
+ */
+export function clearStorage(type) {
+  if (isValidType("string", { type })) {
+    window.Graupl[type] = {};
+  }
+}
+
+/**
+ * Push a value to the storage object.
+ *
+ * @param {string} type  - The type of storage to push to.
+ * @param {string} key   - The key to use for the value.
+ * @param {*}      value - The value to store.
+ */
+export function pushToStorage(type, key, value) {
+  if (isValidType("string", { type, key })) {
+    window.Graupl[type][key] = value;
+  }
+}
+
+/**
+ * Get a value from the storage object.
+ *
+ * @param  {string }type - The type of storage to get from.
+ * @param  {string }key  - The key to get the value from.
+ * @return {*}           - The value from the storage object.
+ */
+export function getFromStorage(type, key) {
+  if (isValidType("string", { type, key })) {
+    return window.Graupl[type][key];
+  }
+
+  return null;
+}
+
+/**
+ * Remove a value from the storage object.
+ *
+ * @param {string} type - The type of storage to remove from.
+ * @param {string} key  - The key to remove the value from.
+ */
+export function removeFromStorage(type, key) {
+  if (isValidType("string", { type, key })) {
+    delete window.Graupl[type][key];
+  }
+}
+
+export default {
+  initializeStorage,
+  getStorage,
+  setStorage,
+  clearStorage,
+  pushToStorage,
+  getFromStorage,
+  removeFromStorage,
+};

package/src/js/validate.js

@@ -0,0 +1,225 @@
+/**
+ * Check to see if the provided elements have a specific contructor.
+ *
+ * The values must be provided inside of an object
+ * so the variable name can be retrieved in case of errors.
+ *
+ * This is essentially just a wrapper function around checking instanceof with
+ * more descriptive error message to help debugging.
+ *
+ * Will return `{ status: true }` if the check is successful.
+ *
+ * @param  {object}                  contructor - The constructor to check for.
+ * @param  {object}                  elements   - The element(s) to check.
+ * @return {Object<boolean, string>}            - The result of the check.
+ */
+export function isValidInstance(contructor, elements) {
+  try {
+    if (typeof elements !== "object") {
+      const elementsType = typeof elements;
+
+      throw new TypeError(
+        `Elements given to isValidInstance() must be inside of an object. "${elementsType}" given.`
+      );
+    }
+
+    for (const key in elements) {
+      if (!(elements[key] instanceof contructor)) {
+        const elementType = typeof elements[key];
+        throw new TypeError(
+          `${key} must be an instance of ${contructor.name}. "${elementType}" given.`
+        );
+      }
+    }
+
+    return {
+      status: true,
+      error: null,
+    };
+  } catch (error) {
+    return {
+      status: false,
+      error,
+    };
+  }
+}
+
+/**
+ * Check to see if the provided values are of a specific type.
+ *
+ * The values must be provided inside of an object
+ * so the variable name can be retrieved in case of errors.
+ *
+ * This is essentially just a wrapper function around checking typeof with
+ * more descriptive error message to help debugging.
+ *
+ * Will return `{ status: true }` if the check is successful.
+ *
+ * @param  {string}                  type   - The type to check for.
+ * @param  {object}                  values - The value(s) to check.
+ * @return {Object<boolean, string>}        - The result of the check.
+ */
+export function isValidType(type, values) {
+  try {
+    if (typeof values !== "object") {
+      const valuesType = typeof values;
+
+      throw new TypeError(
+        `Values given to isValidType() must be inside of an object. "${valuesType}" given.`
+      );
+    }
+
+    for (const key in values) {
+      const valueType = typeof values[key];
+
+      if (valueType !== type) {
+        throw new TypeError(`${key} must be a ${type}. "${valueType}" given.`);
+      }
+    }
+
+    return {
+      status: true,
+      error: null,
+    };
+  } catch (error) {
+    return {
+      status: false,
+      error,
+    };
+  }
+}
+
+/**
+ * Checks to see if the provided values are valid query selectors.
+ *
+ * The values must be provided inside of an object
+ * so the variable name can be retrieved in case of errors.
+ *
+ * Will return `{ status: true }` if the check is successful.
+ *
+ * @param  {Object<string>}          values - The value(s) to check.
+ * @return {Object<boolean, string>}        - The result of the check.
+ */
+export function isQuerySelector(values) {
+  try {
+    if (typeof values !== "object") {
+      const type = typeof values;
+
+      throw new TypeError(
+        `Values given to isQuerySelector() must be inside of an object. "${type}" given.`
+      );
+    }
+
+    for (const key in values) {
+      try {
+        if (values[key] === null) {
+          throw new Error();
+        }
+
+        document.querySelector(values[key]);
+      } catch {
+        throw new TypeError(
+          `${key} must be a valid query selector. "${values[key]}" given.`
+        );
+      }
+    }
+
+    return {
+      status: true,
+      error: null,
+    };
+  } catch (error) {
+    return {
+      status: false,
+      error,
+    };
+  }
+}
+
+/**
+ * Checks to see if the provided value is either a string or an array of strings.
+ *
+ * The values must be provided inside of an object
+ * so the variable name can be retrieved in case of errors.
+ *
+ * Will return `{ status: true }` if the check is successful.
+ *
+ * @param  {Object<string, string[]>} values - The value(s) to check.
+ * @return {Object<boolean, string>}         - The result of the check.
+ */
+export function isValidClassList(values) {
+  try {
+    if (typeof values !== "object" || Array.isArray(values)) {
+      const type = typeof values;
+
+      throw new TypeError(
+        `Values given to isValidClassList() must be inside of an object. "${type}" given.`
+      );
+    }
+
+    for (const key in values) {
+      const type = typeof values[key];
+
+      if (type !== "string") {
+        if (Array.isArray(values[key])) {
+          values[key].forEach((value) => {
+            if (typeof value !== "string") {
+              throw new TypeError(
+                `${key} must be a string or an array of strings. An array containing non-strings given.`
+              );
+            }
+          });
+        } else {
+          throw new TypeError(
+            `${key} must be a string or an array of strings. "${type}" given.`
+          );
+        }
+      } else {
+        const obj = {};
+        obj[key] = values[key];
+
+        isQuerySelector(obj);
+      }
+    }
+
+    return {
+      status: true,
+      error: null,
+    };
+  } catch (error) {
+    return {
+      status: false,
+      error,
+    };
+  }
+}
+
+/**
+ * Checks to see if the provided elements are using a specific tag.
+ *
+ * The elements must be provided inside of an object
+ * so the variable name can be retrieved in case of errors.
+ *
+ * Will return `true` if the check is successful.
+ *
+ * @param  {string}               tagName - The name of the tag.
+ * @param  {Object<HTMLElement>} elements - The element(s) to check.
+ * @return {boolean}                      - The result of the check.
+ */
+export function isTag(tagName, elements) {
+  if (
+    isValidType("string", { tagName }).status &&
+    isValidInstance(HTMLElement, elements).status
+  ) {
+    const tag = tagName.toLowerCase();
+    let check = true;
+
+    for (const key in elements) {
+      if (elements[key].tagName.toLowerCase() !== tag) check = false;
+    }
+
+    return check;
+  } else {
+    return false;
+  }
+}

package/src/scss/_defaults.scss

@@ -1,8 +1,10 @@
-// Default values for Graupl.
+// @graupl/graupl default values.
 //
-// Generally, these should not be used directly when styling components.
-// They are mainly used to provide default fallbacks for custom properties
-// which can be found in the `variables.scss` file.
+// Generally, these should not be used directly when styling components unless a static value is needed.
+// They are mainly used to provide class selectors, fallbacks for custom properties, or loop values.
+//
+// They should not be used to define direct property values (i.e. font-size, color, etc.).
+// Those should be defined as custom properties in the `_variables.scss` file.
 
 @use "sass:map";
 
@@ -11,16 +13,52 @@ $prefix: "graupl" !default;
 
 // Settings.
 $use-important: true !default;
+$responsive-utilities: true !default;
 
 // Layout properties.
 $content-max-width: 96ch !default;
 
 // Screen sizes.
 $base-screen-sizes: (
-  xs: "(0 <= width <= 48ch)",
+  xs: 0,
+  sm: 48ch,
+  md: 72ch,
+  lg: 108ch,
+  xl: 156ch,
 );
 $custom-screen-sizes: () !default;
 $screen-sizes: map.merge($base-screen-sizes, $custom-screen-sizes);
+$base-screen-size-triggers: (
+  navigation-collapse: (
+    mixin: "down",
+    args: (
+      "sm",
+    ),
+  ),
+  navigation-expand: (
+    mixin: "up",
+    args: (
+      "md",
+    ),
+  ),
+  force-vertical-card: (
+    mixin: "down",
+    args: (
+      "sm",
+    ),
+  ),
+  force-single-column: (
+    mixin: "down",
+    args: (
+      "xs",
+    ),
+  ),
+);
+$custom-screen-size-triggers: () !default;
+$screen-size-triggers: map.merge(
+  $base-screen-size-triggers,
+  $custom-screen-size-triggers
+);
 
 // Spacing properties.
 $spacer: 1rem !default;
@@ -65,3 +103,34 @@ $transition-durations: map.merge(
   $base-transition-durations,
   $custom-transition-durations
 );
+
+// State selectors.
+$base-state-selectors: (
+  visited: (
+    ".visited",
+    ":visited",
+  ),
+  focus: (
+    ".focus",
+    ":focus-visible",
+  ),
+  hover: (
+    ".hover",
+    ":hover",
+  ),
+  active: (
+    ".active",
+    ":active",
+  ),
+  disabled: (
+    ".disabled",
+    ":disabled",
+    "[disabled]",
+    "[aria-disabled=true]",
+  ),
+);
+$custom-state-selectors: () !default;
+$state-selectors: map.merge($base-state-selectors, $custom-state-selectors);
+
+// Responsive utility separator.
+$responsive-separator: "\\:" !default;

package/src/scss/_index.scss

@@ -1,10 +1,11 @@
-// Graupl Components.
-//
-// Forwards all components for easy development.
+// @graupl/graupl styles.
 
 // Forward the layer initialization.
 @forward "init";
 
+// Forward normalize.
+@forward "normalize";
+
 // Forward all layers.
 @forward "base";
 @forward "layout";

package/src/scss/_init.scss

@@ -1,3 +1,3 @@
-// Graupl layer initialization.
+// @graupl/graupl layer initialization styles.
 
-@layer graupl.base, graupl.layout, graupl.component, graupl.theme, graupl.utilities, graupl.state;
+@layer graupl.normalize, graupl.base, graupl.layout, graupl.component, graupl.theme, graupl.utilities, graupl.state;