@simple-reporting/base 0.1.112 → 1.0.0

package/srl/components/Srl/Menu/List.vue

@@ -0,0 +1,184 @@
+<script setup lang="ts">
+/**
+ * `SrlMenu.vue`
+ *
+ * This Vue 3 component implements a hierarchical menu system with various navigation capabilities.
+ * It manages a list of menu items with support for opening/closing items, keyboard navigation,
+ * and parent-child menu relationships.
+ *
+ * ## Props
+ * - `name`: String - Identifier for the menu
+ * - `menu`: Array<NsWowNavigationItem> - Menu items data structure
+ * - `disableTab`: Boolean - Disables tab navigation when true (default: false)
+ * - `disableTabIndex`: Boolean - Disables tabindex attributes when true (default: false)
+ * - `initOpen`: Number - Initial depth level that should be open (default: 0)
+ * - `singleOpen`: Boolean - Only allows one menu item to be open at a time (default: true)
+ * - `depth`: Number - Current depth level of this menu (default: 0)
+ *
+ * ## Emits
+ * - `close`: When the menu is closed
+ * - `closeSub`: When a submenu is closed
+ * - `link`: When a link item is activated
+ * - `routerChange`: When navigation occurs via router
+ * - `nextExceeded`, `prevExceeded`: When navigation exceeds boundaries
+ * - `tab`: When tab navigation occurs
+ * - `back`: When back navigation is triggered
+ *
+ * ## Reactive Variables
+ * - `items`: Reference array to MenuItem components
+ * - `opened`: v-model for the open/closed state of the menu
+ * - `$el`: Reference to the root <ul> element
+ *
+ * ## Methods
+ * - `open(event)`: Opens a menu item, closing others if singleOpen is true
+ * - `close()`: Closes the current menu or emits close events based on depth
+ * - `next(event)`: Focuses the next menu item with circular navigation
+ * - `prev(event)`: Focuses the previous menu item with circular navigation
+ * - `closeAll(keep?)`: Closes all menu items except the one specified by index
+ *
+ * ## Exposed API
+ * - `closeAll`: Method to close all menu items except one (optional)
+ * - `$el`: Reference to the root element
+ * - `items`: Array of menu item components
+ *
+ * ## Usage Example
+ * ```vue
+ * <SrlMenuList
+ *   name="main-nav"
+ *   :menu="navigationItems"
+ *   :singleOpen="true"
+ *   @link="handleNavigation"
+ * />
+ */
+import { ref } from 'vue';
+import MenuItem from './Item.vue';
+
+const props = withDefaults(
+  defineProps<{
+    name: string;
+    menu: NsWowNavigationItem[];
+    disableTab?: boolean;
+    disableTabIndex?: boolean;
+    initOpen?: number;
+    singleOpen?: boolean;
+    depth?: number;
+  }>(),
+  {
+    disableTab: false,
+    disableTabIndex: false,
+    initOpen: 0,
+    singleOpen: true,
+    depth: 0,
+  },
+);
+
+const emit = defineEmits([
+  'close',
+  'closeSub',
+  'link',
+  'routerChange',
+  'nextExceeded',
+  'prevExceeded',
+  'tab',
+  'back',
+]);
+const items = ref<Array<typeof MenuItem>>([]);
+
+const opened = defineModel('opened', { type: Boolean, default: true });
+
+function open(event: { index: number }) {
+  if (props.singleOpen) {
+    closeAll(event.index);
+  }
+}
+
+function close() {
+  if (props.initOpen < props.depth) {
+    opened.value = false;
+    emit('closeSub');
+  } else {
+    emit('close');
+  }
+}
+
+function next(event: { index: number }) {
+  let newIndex = event.index + 1;
+  let exceeded = false;
+  if (newIndex >= items.value.length) {
+    exceeded = true;
+    newIndex = 0;
+  }
+  const item = items.value[newIndex].$el;
+  item.$el ? item.$el.focus() : item.focus();
+  !exceeded || emit('nextExceeded');
+}
+
+function prev(event: { index: number }) {
+  let newIndex = event.index - 1;
+  let exceeded = false;
+  if (newIndex < 0) {
+    exceeded = true;
+    newIndex = items.value.length - 1;
+  }
+  const item = items.value[newIndex].$el;
+  item.$el ? item.$el.focus() : item.focus();
+  !exceeded || emit('prevExceeded');
+}
+
+function tab() {
+  emit('tab');
+}
+
+function back() {
+  emit('back');
+}
+
+function link() {
+  emit('link');
+}
+
+function routerChange() {
+  emit('routerChange');
+}
+
+function closeAll(keep?: number | string) {
+  items.value.forEach((item: typeof MenuItem, index: number) => {
+    if (keep !== index) item.closeItem();
+  });
+}
+
+const $el = ref<HTMLUListElement>();
+
+defineExpose({
+  closeAll,
+  $el,
+  items,
+});
+</script>
+
+<template>
+  <ul ref="$el" :hidden="!opened">
+    <template v-for="(item, index) in props.menu" :key="index">
+      <MenuItem
+        ref="items"
+        :item="item"
+        :name="props.name"
+        :index="index"
+        :disableTab="props.disableTab"
+        :disableTabIndex="props.disableTabIndex"
+        :initOpen="props.initOpen"
+        :depth="props.depth"
+        @open="open"
+        @close="close"
+        @next="next"
+        @prev="prev"
+        @tab="tab"
+        @back="back"
+        @link="link"
+        @routerChange="routerChange"
+      />
+    </template>
+  </ul>
+</template>
+
+<style scoped lang="scss"></style>

package/srl/components/Srl/Page/App.vue

@@ -0,0 +1,65 @@
+<script setup lang="ts">
+/**
+ * `SrlPageApp.vue`
+ *
+ * This Vue 3 component serves as the primary layout orchestrator for the application.
+ * It coordinates the loading and rendering of main application components within
+ * Suspense boundaries to handle asynchronous loading states.
+ *
+ * ## Imports
+ * - `App`: Main application component
+ * - `SrlPageData`: Component responsible for loading and preparing page content
+ * - `SrlPageModal`: Modal dialog component for displaying dynamic content
+ * - `ref`: Vue reactivity utility for creating mutable references
+ *
+ * ## Reactive State
+ * - `modal`: Reference to the SrlPageModal component instance
+ *
+ * ## Methods
+ * - `modalContent(html)`: Asynchronous method to set the content of the modal dialog
+ *   - Delegates to the modal component's setContent method
+ *   - Takes HTML string as input for display in the modal
+ *
+ * ## Exposed API
+ * - The component exposes the modal reference and modalContent function
+ *   for parent components to access and control the modal dialog
+ *
+ * ## Template Structure
+ * - Uses three Suspense components to handle asynchronous loading:
+ *   1. SrlPageData: Loads and prepares page content based on current route
+ *   2. App: Main application component with primary UI elements
+ *   3. SrlPageModal: Modal dialog component for overlay content
+ *
+ * ## Usage Context
+ * This component acts as the structural foundation of the application,
+ * managing the loading sequence of content and providing modal functionality
+ * to other components in the application.
+ */
+import App from '@/App.vue';
+import { ref, watch } from 'vue';
+
+const styleElement = document.createElement('style');
+document.head.appendChild(styleElement);
+
+const styleContent = ref<string[]>([]);
+function addCssStyles(styles: string) {
+  styleContent.value.includes(styles) || styleContent.value.push(styles);
+}
+watch(
+  styleContent.value,
+  (newStyles) => {
+    styleElement.innerHTML = newStyles.join('');
+  },
+  { immediate: true },
+);
+
+defineExpose({
+  addCssStyles,
+});
+</script>
+
+<template>
+  <suspense>
+    <App />
+  </suspense>
+</template>

package/srl/components/Srl/Page/Dialog.vue

@@ -0,0 +1,71 @@
+<script setup lang="ts">
+import { ref } from 'vue';
+import SrlPageCustomDialog from '@//Dialog.vue';
+import Autoload from '@/Autoload.ts';
+
+const props = withDefaults(
+  defineProps<{
+    header?: string;
+    content?: string;
+  }>(),
+  {
+    header: '',
+    content: '',
+  },
+);
+
+const $el = ref<HTMLDialogElement | null>(null);
+const dialogState = ref<boolean>(false);
+
+const header = ref<string>(props.header);
+const content = ref<string>(props.content);
+
+function setDialogContent(template: string) {
+  content.value = template;
+}
+
+function setDialogContentAndOpen(template: string) {
+  setDialogContent(template);
+  open();
+}
+
+function open() {
+  $el.value?.showModal();
+  dialogState.value = true;
+  $el.value?.querySelector('.srl-dialog__main')?.focus();
+  Autoload.init($el.value);
+}
+
+function close() {
+  $el.value?.close();
+  dialogState.value = false;
+}
+
+function clearContent() {
+  header.value = '';
+  content.value = '';
+}
+
+defineExpose({
+  $el,
+  dialogState,
+  setDialogContent,
+  setDialogContentAndOpen,
+  open,
+  close,
+});
+</script>
+
+<template>
+  <dialog
+    ref="$el"
+    id="srl-page__dialog"
+    class="srl-page__dialog"
+    aria-modal="true"
+    @click.stop="close"
+  >
+    <SrlAriaTabChain @click.stop>
+      <SrlPageCustomDialog :header="header" :content="content" @close="close" />
+    </SrlAriaTabChain>
+  </dialog>
+</template>

package/srl/composables/article.ts

@@ -0,0 +1,24 @@
+import { computed, type ComputedRef } from 'vue';
+import { useRoute } from 'vue-router';
+import useArticles from './articles';
+
+const articles = useArticles();
+
+export default function useArticle(): ComputedRef<NsWowArticle | undefined> {
+  const route = useRoute();
+  return computed<NsWowArticle | undefined>(() => {
+    const slug = route.params.slug
+      ? (route.params.slug[0] as string)
+      : undefined;
+    const article = !slug
+      ? articles.value.find((article) => article.index)
+      : articles.value.find((article) => article.slug === slug);
+
+    if (!article) {
+      console.error(`Article not found for slug: ${route.path}`);
+      return undefined;
+    }
+
+    return article;
+  });
+}

package/srl/composables/articles.ts

@@ -0,0 +1,41 @@
+/**
+ * `articles.ts`
+ *
+ * This Vue 3 composable provides access to localized article data.
+ * It implements a singleton pattern to ensure only one computed reference
+ * is created and reused across the application.
+ *
+ * ## Imports
+ * - `useConfig`: Composable for accessing application configuration
+ * - `computed`, `ComputedRef`: Vue reactivity utilities
+ *
+ * ## Variables
+ * - `computedStorage`: Singleton storage for the computed article reference
+ *
+ * ## Function: useArticles
+ * - Asynchronous function that returns a computed reference to articles
+ * - Only initializes the computed reference on first call
+ * - Returns the same reference on subsequent calls
+ * - Articles are filtered by the current locale from the configuration
+ *
+ * ## Return Value
+ * - ComputedRef<NsWowArticle[]>: A computed reference to an array of articles
+ *   in the current locale
+ *
+ * ## Usage Example
+ * ```typescript
+ * const articles = await useArticles()
+ * console.log(articles.value) // Array of articles in the current locale
+ */
+import { computed, type ComputedRef } from 'vue';
+import useConfig from './config.ts';
+
+const config = useConfig();
+
+const articles = computed<NsWowArticle[]>(
+  () => config.value?.articles[config.value.locale],
+);
+
+export default function useArticles(): ComputedRef<NsWowArticle[]> {
+  return articles;
+}

package/srl/composables/config.ts

@@ -0,0 +1,165 @@
+/**
+ * `src/composables/config.ts`
+ *
+ * A Vue 3 composable that manages the application configuration.
+ * Handles loading and accessing various configuration aspects including
+ * settings, translations, article data, and menu structures.
+ *
+ * ## Core Functionality
+ * - Loads configuration from multiple JSON files
+ * - Manages application settings and supported languages
+ * - Handles internationalization with translations
+ * - Provides routing information for different locales
+ * - Manages downloadable content references
+ * - Offers environment detection helpers
+ *
+ * ## Data Structure
+ * - `NsWowConfig`: Main configuration object containing:
+ *   - `locale`: Current active locale
+ *   - `settings`: Application settings
+ *   - `articles`: Article data by language
+ *   - `menus`: Menu structures by language
+ *   - `translations`: Translation strings by language
+ *   - `downloads`: Download data by language
+ *
+ * ## Main Functions
+ * - `setConfig()`: Initializes the full configuration by loading all data files
+ * - `loadSettings()`: Loads application settings from JSON
+ * - `loadTranslations()`: Loads translation data
+ * - `loadRouting(locale)`: Loads routing information for specified locale
+ * - `loadDownloads(locale)`: Loads download data for specified locale
+ * - `useConfig()`: Returns the reactive configuration reference
+ *
+ * ## Environment Helpers
+ * - `isPreview()`: Checks if application is running in preview mode
+ * - `isDevelopment()`: Checks if application is running in development mode
+ * - `isWorkboxEnabled()`: Determines if service worker functionality is enabled
+ *
+ * ## Usage
+ * const config = useConfig()
+ */
+import { ref, type Ref } from 'vue';
+
+const config = ref<NsWowConfig>({
+  locale: 'de',
+  settings: {
+    languages: ['de', 'en'],
+    defaultLanguage: 'de',
+    shortBreadcrumb: false,
+    search: {
+      boldTheWord: true,
+    },
+    categories: [],
+  },
+  articles: {},
+  menus: {},
+  translations: {},
+  downloads: {},
+});
+
+async function setConfig(): Promise<Ref<NsWowConfig>> {
+  await loadSettings();
+  await loadTranslations();
+
+  const defaultMessages = import.meta.glob('@/locales/*.json', {
+    eager: true,
+    import: 'default',
+  });
+
+  for (const locale of config.value.settings.languages) {
+    await loadRouting(locale);
+    await loadDownloads(locale);
+
+    config.value.translations[locale] = config.value.translations[locale] || {};
+
+    const defaultMessages = import.meta.glob('@/locales/*.json', {
+      eager: true,
+      import: 'default',
+    });
+
+    const path = `/src/locales/${locale}.json`;
+    if (defaultMessages[path]) {
+      config.value.translations[locale] = Object.assign(
+        defaultMessages[path],
+        config.value.translations[locale],
+      );
+    }
+  }
+  return config;
+}
+
+async function loadSettings() {
+  const file = `./json/settings.json`;
+  try {
+    const response: Response = await fetch(file);
+    const data: NsWowSettings = await response.json();
+    config.value.settings = Object.assign(config.value.settings, data);
+    config.value.locale = data.defaultLanguage;
+    document.documentElement.lang = data.defaultLanguage;
+  } catch (e) {
+    errorLog(`"${file}" could not be loaded.`, e);
+  }
+}
+
+async function loadTranslations() {
+  const file = `./json/translations_hosting.json`;
+  try {
+    const response: Response = await fetch(file);
+    const data: NsWowTranslations = await response.json();
+    config.value.translations = data;
+  } catch (e) {
+    errorLog(`"${file}" could not be loaded.`, e);
+  }
+}
+
+async function loadRouting(locale: string) {
+  const file: string = `./json/routing_${locale}.json`;
+  try {
+    const response: Response = await fetch(file);
+    const routing: NsWowResponseRouting = await response.json();
+    config.value.articles[locale] = routing.pages;
+    config.value.menus[locale] = routing.menu;
+  } catch (e) {
+    errorLog(`"${file}" could not be loaded.`, e);
+  }
+}
+
+async function loadDownloads(locale: string) {
+  config.value.downloads[locale] = {};
+  const file: string = `./downloads/downloads_${locale}.json`;
+  try {
+    const response: Response = await fetch(file);
+    const data = await response.json();
+    config.value.downloads[locale] = data;
+  } catch (e) {
+    errorLog(`"${file}" could not be loaded.`, e);
+  }
+}
+
+function useConfig(): Ref<NsWowConfig> {
+  return config;
+}
+
+function isPreview(): boolean {
+  return window.location.pathname.includes('/preview/');
+}
+
+function isDevelopment(): boolean {
+  return import.meta.env.DEV;
+}
+
+function isWorkboxEnabled(): boolean {
+  return (
+    (!isPreview() && !isDevelopment()) ||
+    (isDevelopment() && import.meta.env.VITE_WORKBOX === 'true')
+  );
+}
+
+function errorLog(message: string, error: Error): void {
+  isDevelopment() || isPreview()
+    ? console.error(`Error: ${message}`, error)
+    : null;
+}
+
+export default useConfig;
+export { setConfig, useConfig, isPreview, isDevelopment };

package/srl/composables/downloads.ts

@@ -0,0 +1,46 @@
+/**
+ * `downloads.ts`
+ *
+ * This Vue 3 composable provides access to localized download data.
+ * It loads download information from JSON files for each supported language
+ * and returns a computed reference to the data in the current locale.
+ *
+ * ## Imports
+ * - `computed`, `ref`, `ComputedRef`: Vue reactivity utilities
+ * - `useConfig`: Composable for accessing application configuration
+ *
+ * ## Reactive Variables
+ * - `downloads`: Reference object storing download data for all languages
+ * - `computedDownloads`: Singleton computed reference for current locale's download data
+ *
+ * ## Function: useDownloads
+ * - Asynchronous function that returns a computed reference to download data
+ * - Loads download data JSON files for all configured languages on first call
+ * - Initializes the computed reference if not already created
+ * - Returns the same computed reference on subsequent calls
+ * - Download data is filtered by the current locale from the configuration
+ *
+ * ## Return Value
+ * - ComputedRef<NsWowDownloads>: A computed reference to download data
+ *   in the current locale
+ *
+ * ## Usage Example
+ * ```typescript
+ * const downloads = await useDownloads()
+ * console.log(downloads.value.structure) // Array of download structure items
+ */
+import { computed, type ComputedRef } from 'vue';
+import useConfig from './config';
+
+const config = useConfig();
+
+const downloads = computed<NsWowDownload[]>(() => {
+  if (!config.value.downloads[config.value.locale]) {
+    return [];
+  }
+  return config.value.downloads[config.value.locale].structure;
+});
+
+export default function useDownloads(): ComputedRef<NsWowDownload[]> {
+  return downloads;
+}

package/srl/composables/index.ts

@@ -0,0 +1,34 @@
+import _useArticle from './article';
+import _useArticles from './articles';
+import _useConfig from './config';
+import _useDownloads from './downloads';
+import _useLocale from './locale';
+import _useMenu from './menu';
+import _useRoot from './root';
+import _useSearch from './search';
+import _useSettings from './settings';
+import _useViewPort from './viewPort';
+
+export const useArticle = _useArticle;
+export const useArticles = _useArticles;
+export const useConfig = _useConfig;
+export const useDownloads = _useDownloads;
+export const useLocale = _useLocale;
+export const useMenu = _useMenu;
+export const useRoot = _useRoot;
+export const useSearch = _useSearch;
+export const useSettings = _useSettings;
+export const useViewPort = _useViewPort;
+
+export default {
+  useArticle,
+  useArticles,
+  useConfig,
+  useDownloads,
+  useLocale,
+  useMenu,
+  useRoot,
+  useSearch,
+  useSettings,
+  useViewPort,
+};

package/srl/composables/locale.ts

@@ -0,0 +1,8 @@
+import useConfig from './config';
+import { computed, type ComputedRef } from 'vue';
+
+const config = useConfig();
+const locale = computed<string>(() => config.value.locale);
+export default function useLocale(): ComputedRef<string> {
+  return locale;
+}