@simple-reporting/base 0.1.111 → 1.0.0

package/scripts/utils.d.ts

@@ -1,49 +1,64 @@
 /**
- * Replaces underscore (_) placeholders with spaces and replaces '_and_' with a forward slash (/) separator.
- *
- * @param {string} name - The name to modify.
- * @return {string} The modified name with replaced placeholders.
+ * Formats a group name for Livingdocs.
+ * @param {string} name - The original group name.
+ * @returns {string} The formatted group name.
  */
 export function lddGroupNames(name: string): string;
 /**
- * Reads the contents of the package.json file.
- *
- * @returns {Promise<Object>} A Promise that resolves to the parsed contents of the package.json file.
+ * Reads and caches the package.json file.
+ * @returns {Promise<Object>} The parsed package.json object.
+ */
+export function updatePackageJson(): Promise<any>;
+/**
+ * Returns the cached package.json object or reads it if not cached.
+ * @returns {Promise<Object>} The package.json object.
  */
 export function readPackageJson(): Promise<any>;
 /**
- * Writes a package.json file with the given configuration object.
- *
- * @param {Object} config - The configuration object for the package.json file.
- * @return {Boolean} - Returns true if the package.json file is successfully written, else returns false.
+ * Writes the current package.json object to the file.
+ * @returns {Promise<boolean>} True if successful.
  */
-export function writePackageJson(config: any): boolean;
+export function writePackageJson(): Promise<boolean>;
 /**
- * Reads the contents of the "livingdocs.config.json" file and returns the parsed JSON.
- *
- * @return {Promise<Object>} A promise that resolves to the parsed JSON from the file.
+ * Reads and caches the livingdocs.config.json file.
+ * @returns {Promise<Object>} The parsed livingdocs.config.json object.
+ */
+export function updateLivingDocsJson(): Promise<any>;
+/**
+ * Returns the cached livingdocs.config.json object or reads it if not cached.
+ * @returns {Promise<Object>} The livingdocs.config.json object.
  */
 export function readLivingDocsJson(): Promise<any>;
 /**
- * Writes the given configuration object to a JSON file.
- *
- * @param {Object} config - The configuration object to write.
- * @returns {Promise<boolean>} - A Promise that resolves to true if the file was successfully written, otherwise false.
+ * Writes the current livingdocs.config.json object to the file.
+ * @returns {Promise<boolean>} True if successful.
+ */
+export function writeLivingDocsJson(): Promise<boolean>;
+/**
+ * Reads and caches the srl.config.json file.
+ * @returns {Promise<Object>} The parsed srl.config.json object.
  */
-export function writeLivingDocsJson(config: any): Promise<boolean>;
+export function updateNsWowJson(): Promise<any>;
 /**
- * Reads the contents of the `nswow.config.json` file and returns the parsed JSON object.
- *
- * @returns {Promise<Object>} - Resolves to the parsed JSON object from the `nswow.config.json` file.
+ * Returns the cached srl.config.json object or reads it if not cached.
+ * @returns {Promise<Object>} The srl.config.json object.
  */
 export function readNsWowJson(): Promise<any>;
 /**
- * Writes the given configuration object to an nswow.config.json file.
- * If no configuration object is provided, the method does nothing.
- *
- * @param {Object} config - The configuration object to write.
- *
- * @return {boolean} - Returns true if the configuration was successfully written, otherwise false.
+ * Writes the current srl.config.json object to the file.
+ * @returns {Promise<boolean>} True if successful.
+ */
+export function writeNsWowJson(): Promise<boolean>;
+/**
+ * Converts a string to camelCase.
+ * @param {string} str - The input string.
+ * @returns {string} The camelCase string.
+ */
+export function camelCase(str: string): string;
+/**
+ * Gets the version of an npm package.
+ * @param {string} packageName - The name of the npm package.
+ * @returns {Promise<string>} The package version.
  */
-export function writeNsWowJson(config: any): boolean;
+export function getPackageVersion(packageName: string): Promise<string>;
 export { writeJson };

package/scripts/utils.js

@@ -1,106 +1,163 @@
-import { resolve } from 'node:path';
-import { readFileSync } from 'node:fs';
-import { createRequire } from 'node:module';
-
-const require = createRequire(import.meta.url);
-/**
- * A module for writing JSON data to a file.
- *
- * @module writeJson
- */
-const writeJson = require('write-json');
-
-/**
- * Replaces underscore (_) placeholders with spaces and replaces '_and_' with a forward slash (/) separator.
- *
- * @param {string} name - The name to modify.
- * @return {string} The modified name with replaced placeholders.
- */
-function lddGroupNames(name) {
-  return name.replace('_and_', ' / ').replace('_', ' ');
-}
-
-/**
- * Reads the contents of the package.json file.
- *
- * @returns {Promise<Object>} A Promise that resolves to the parsed contents of the package.json file.
- */
-async function readPackageJson() {
-  const file = resolve(process.cwd(), './package.json');
-  return JSON.parse(await readFileSync(file));
-}
-
-/**
- * Writes a package.json file with the given configuration object.
- *
- * @param {Object} config - The configuration object for the package.json file.
- * @return {Boolean} - Returns true if the package.json file is successfully written, else returns false.
- */
-async function writePackageJson(config) {
-  if (config) {
-    const file = resolve(process.cwd(), './package.json');
-    writeJson.sync(file, config);
-  }
-  return true;
-}
-
-/**
- * Reads the contents of the "livingdocs.config.json" file and returns the parsed JSON.
- *
- * @return {Promise<Object>} A promise that resolves to the parsed JSON from the file.
- */
-async function readLivingDocsJson() {
-  const file = resolve(process.cwd(), './livingdocs.config.json');
-  return JSON.parse(await readFileSync(file));
-}
-
-/**
- * Writes the given configuration object to a JSON file.
- *
- * @param {Object} config - The configuration object to write.
- * @returns {Promise<boolean>} - A Promise that resolves to true if the file was successfully written, otherwise false.
- */
-async function writeLivingDocsJson(config) {
-  if (config) {
-    const file = resolve(process.cwd(), './livingdocs.config.json');
-    writeJson.sync(file, config);
-  }
-  return true;
-}
-
-/**
- * Reads the contents of the `nswow.config.json` file and returns the parsed JSON object.
- *
- * @returns {Promise<Object>} - Resolves to the parsed JSON object from the `nswow.config.json` file.
- */
-async function readNsWowJson() {
-  const file = resolve(process.cwd(), './nswow.config.json');
-  return JSON.parse(await readFileSync(file));
-}
-
-/**
- * Writes the given configuration object to an nswow.config.json file.
- * If no configuration object is provided, the method does nothing.
- *
- * @param {Object} config - The configuration object to write.
- *
- * @return {boolean} - Returns true if the configuration was successfully written, otherwise false.
- */
-async function writeNsWowJson(config) {
-  if (config) {
-    const file = resolve(process.cwd(), './nswow.config.json');
-    writeJson.sync(file, config);
-  }
-  return true;
-}
-
-export {
-  writeJson,
-  lddGroupNames,
-  readPackageJson,
-  writePackageJson,
-  readLivingDocsJson,
-  writeLivingDocsJson,
-  readNsWowJson,
-  writeNsWowJson,
-};
+import { join } from 'node:path/posix';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { exec } from 'child_process';
+
+const require = createRequire(import.meta.url);
+
+const writeJson = require('write-json');
+
+const data = {
+  packageJson: null,
+  livingDocsJson: null,
+  nsWowJson: null,
+}
+
+/**
+ * Formats a group name for Livingdocs.
+ * @param {string} name - The original group name.
+ * @returns {string} The formatted group name.
+ */
+function lddGroupNames(name) {
+  const arrName = name.split('.');
+  if (arrName.length > 1) {
+    arrName.shift();
+    name = arrName.join('.');
+  }
+  return name.replace('_and_', ' / ').replace('_', ' ');
+}
+
+/**
+ * Reads and caches the package.json file.
+ * @returns {Promise<Object>} The parsed package.json object.
+ */
+async function updatePackageJson() {
+  data.packageJson = JSON.parse(
+    await readFileSync(
+      join(process.cwd(), 'package.json')
+    )
+  );
+  return data.packageJson;
+}
+
+/**
+ * Returns the cached package.json object or reads it if not cached.
+ * @returns {Promise<Object>} The package.json object.
+ */
+async function readPackageJson() {
+  return data.packageJson || updatePackageJson();
+}
+
+/**
+ * Writes the current package.json object to the file.
+ * @returns {Promise<boolean>} True if successful.
+ */
+async function writePackageJson() {
+  const file = join(process.cwd(), 'package.json');
+  await writeJson.sync(file, data.packageJson);
+  return true;
+}
+
+/**
+ * Reads and caches the livingdocs.config.json file.
+ * @returns {Promise<Object>} The parsed livingdocs.config.json object.
+ */
+async function updateLivingDocsJson() {
+  data.livingDocsJson = JSON.parse(
+    await readFileSync(
+      join(process.cwd(), 'livingdocs.config.json')
+    )
+  );
+  return data.livingDocsJson;
+}
+
+/**
+ * Returns the cached livingdocs.config.json object or reads it if not cached.
+ * @returns {Promise<Object>} The livingdocs.config.json object.
+ */
+async function readLivingDocsJson() {
+  return data.livingDocsJson || updateLivingDocsJson();
+}
+
+/**
+ * Writes the current livingdocs.config.json object to the file.
+ * @returns {Promise<boolean>} True if successful.
+ */
+async function writeLivingDocsJson() {
+  const file = join(process.cwd(), 'livingdocs.config.json');
+  await writeJson.sync(file, data.livingDocsJson);
+  return true;
+}
+
+/**
+ * Reads and caches the srl.config.json file.
+ * @returns {Promise<Object>} The parsed srl.config.json object.
+ */
+async function updateNsWowJson() {
+  data.nsWowJson = JSON.parse(
+    await readFileSync(
+      join(process.cwd(), 'srl.config.json')
+    )
+  );
+  return data.nsWowJson;
+}
+
+/**
+ * Returns the cached srl.config.json object or reads it if not cached.
+ * @returns {Promise<Object>} The srl.config.json object.
+ */
+async function readNsWowJson() {
+  return data.nsWowJson || updateNsWowJson();
+}
+
+/**
+ * Writes the current srl.config.json object to the file.
+ * @returns {Promise<boolean>} True if successful.
+ */
+async function writeNsWowJson() {
+  const file = join(process.cwd(), 'srl.config.json');
+  await writeJson.sync(file, data.nsWowJson);
+  return true;
+}
+
+/**
+ * Converts a string to camelCase.
+ * @param {string} str - The input string.
+ * @returns {string} The camelCase string.
+ */
+function camelCase(str) {
+  return str.replace(/[._-](\w|$)/g, (_, x) => x.toUpperCase());
+}
+
+/**
+ * Gets the version of an npm package.
+ * @param {string} packageName - The name of the npm package.
+ * @returns {Promise<string>} The package version.
+ */
+function getPackageVersion(packageName) {
+  return new Promise((resolve, reject) => {
+    exec(`npm view ${packageName} version`, (error, stdout, stderr) => {
+      let version = stdout.trim();
+      if (version === '') {
+        version = '0.0.0';
+      }
+      resolve(version);
+    });
+  });
+}
+
+export {
+  writeJson,
+  lddGroupNames,
+  updatePackageJson,
+  readPackageJson,
+  writePackageJson,
+  updateLivingDocsJson,
+  readLivingDocsJson,
+  writeLivingDocsJson,
+  updateNsWowJson,
+  readNsWowJson,
+  writeNsWowJson,
+  camelCase,
+  getPackageVersion,
+};

package/srl/components/Srl/Aria/TabChain.vue

@@ -0,0 +1,100 @@
+<script setup lang="ts">
+/**
+ * `SrlAriaTabChain.vue`
+ *
+ * This Vue 3 component implements a closed tab navigation chain.
+ * It monitors focusable elements within the container and ensures that
+ * tab navigation works as a closed cycle: tabbing on the last element returns
+ * to the first element, and shift+tab on the first element jumps to the last.
+ *
+ * ## Reactive Variables
+ * - `availableTabs`: Array of all focusable elements in the container
+ * - `rootElement`: Reference to the root <div> element of the component
+ * - `firstElement`: Reference to the first focusable element
+ * - `lastElement`: Reference to the last focusable element
+ *
+ * ## Methods
+ * - `registerTabs()`: Finds all focusable elements in the container and stores references
+ * - `next(event)`: Handler for Tab key, jumps from last to first element
+ * - `prev(event)`: Handler for Shift+Tab key, jumps from first to last element
+ *
+ * ## Lifecycle Hooks
+ * - On mounting and after updates, `registerTabs()` is called to capture focusable elements
+ *
+ * ## Event Handlers
+ * - `@keydown.tab.stop`: Intercepts Tab key and calls `next()`
+ * - `@keydown.shift.tab.stop.prevent`: Intercepts Shift+Tab and calls `prev()`
+ *
+ * ## Usage Example
+ * ```vue
+ * <SrlAriaTabChain>
+ *   <button>First Button</button>
+ *   <input type="text" />
+ *   <button>Last Button</button>
+ * </SrlAriaTabChain>
+ */
+import { ref, nextTick, onMounted, onUpdated } from 'vue';
+
+const availableTabs = ref<Array<HTMLElement>>([]);
+const rootElement = ref<HTMLDivElement>();
+const firstElement = ref<HTMLElement>();
+const lastElement = ref<HTMLElement>();
+
+function registerTabs(): void {
+  availableTabs.value = Array.from(
+    rootElement.value.querySelectorAll<HTMLElement>(
+      'a[href], button, input, select, textarea, [tabindex]:not([tabindex="-1"])',
+    ),
+  );
+  firstElement.value = availableTabs.value[0];
+  lastElement.value = availableTabs.value.at(-1);
+}
+
+onMounted(() => {
+  nextTick(registerTabs);
+});
+
+onUpdated(() => {
+  nextTick(registerTabs);
+});
+
+function next(event) {
+  if (availableTabs.value.length === 0) {
+    return;
+  }
+
+  const focusedElement = document.activeElement as HTMLElement;
+
+  if (focusedElement === lastElement.value) {
+    event.preventDefault();
+    firstElement.value.focus();
+  }
+}
+
+function prev(event) {
+  if (availableTabs.value.length === 0) {
+    return;
+  }
+
+  const currentIndex = availableTabs.value.indexOf(event.target);
+
+  if (currentIndex === -1) {
+    firstElement.value.focus();
+  } else if (currentIndex === 0) {
+    lastElement.value.focus();
+  } else {
+    availableTabs.value[currentIndex - 1].focus();
+  }
+}
+</script>
+
+<template>
+  <div
+    ref="rootElement"
+    tabindex="-1"
+    @keydown.tab.stop="next"
+    @keydown.shift.tab.stop.prevent="prev"
+  >
+    <slot />
+  </div>
+</template>

package/srl/components/Srl/Article/Autoload.vue

@@ -0,0 +1,41 @@
+<script setup lang="ts">
+/**
+ * `Autoload.vue`
+ *
+ * This Vue 3 component automatically initializes the `Autoload` functionality
+ * on the root element when the component is mounted.
+ *
+ * ## Imports
+ * - `Autoload`: A module imported from `@/Autoload.ts` that provides the `init` method.
+ * - `onMounted`: A Vue lifecycle hook used to execute logic after the component is mounted.
+ * - `ref`: A Vue function to create a reactive reference for the root element.
+ *
+ * ## Refs
+ * - `rootElement`: A reactive reference to the root `<div>` element of the component.
+ *
+ * ## Lifecycle Hooks
+ * - `onMounted`: Invokes the `Autoload.init` method with the `rootElement` when the component is mounted.
+ *
+ * ## Template
+ * Renders a `<div>` element with a `ref` attribute set to `rootElement`. The component uses a `slot` to allow custom content to be passed into the `<div>`.
+ *
+ * ## Usage Example
+ * ```vue
+ * <SrlArticleAutoload>
+ *   <p>Content to be autoloaded</p>
+ * </SrlArticleAutoload>
+ */
+import Autoload from '@/Autoload.ts';
+import { onMounted, ref } from 'vue';
+const rootElement = ref<HTMLDivElement>();
+
+onMounted(() => {
+  !rootElement.value || Autoload.init(rootElement.value);
+});
+</script>
+
+<template>
+  <div ref="rootElement">
+    <slot />
+  </div>
+</template>

package/srl/components/Srl/Article/DialogButton.vue

@@ -0,0 +1,55 @@
+<script setup lang="ts">
+import { ref, useId } from 'vue';
+import { useArticles, useConfig } from '#composables';
+import { prepareHtmlContent } from '#utils';
+
+const props = defineProps<{
+  uuid: string;
+}>();
+
+const config = useConfig();
+const articles = useArticles();
+const id = ref<string>(`srl-page__dialog-${useId()}`);
+const content = ref<string>('');
+const dialog = ref<typeof SrlPageDialog | null>(null);
+async function loadContent() {
+  const article = articles.value.find((article) => article.uuid === props.uuid);
+  if (article) {
+    const file = `./html/${config.value.locale}/${article.name}.html`;
+    try {
+      const req = await fetch(file);
+      const text = await req.text();
+      content.value = prepareHtmlContent(text);
+    } catch (error) {
+      console.error(`Failed to load article content from ${file}:`, error);
+    }
+  }
+}
+
+loadContent();
+async function open() {
+  dialog.value.open();
+}
+</script>
+
+<template>
+  <button
+    class="srl-dialog-button"
+    type="button"
+    :aria-controls="id"
+    aria-haspopup="dialog"
+    :aria-expanded="dialog?.dialogState ?? false"
+    @click="open"
+  >
+    <slot />
+    <Teleport to="body">
+      <SrlPageDialog
+        v-if="content"
+        :id="id"
+        ref="dialog"
+        :content="content"
+        @close="expanded = false"
+      />
+    </Teleport>
+  </button>
+</template>

package/srl/components/Srl/Article/Root.vue

@@ -0,0 +1,76 @@
+<script setup lang="ts">
+/**
+ * `Root.vue`
+ *
+ * This Vue 3 component serves as the main container for rendering dynamic article content.
+ * It uses VRuntimeTemplate to render HTML content from pageData and initializes automatic
+ * loading functionality after content changes.
+ *
+ * ## Imports
+ * - `nextTick`, `ref`, `watch`: Vue core functionality
+ * - `VRuntimeTemplate`: Library for rendering dynamic templates at runtime
+ * - `usePageData`: Composable that provides access to the current page data
+ * - `Autoload`: Utility for initializing dynamic content
+ *
+ * ## Reactive Variables
+ * - `pageData`: Data from the usePageData composable containing article content
+ * - `articleRoot`: Reference to the root article element
+ *
+ * ## Watchers
+ * - Watches for changes in `pageData` and runs Autoload.init on the article root element
+ *   after the DOM has updated
+ *
+ * ## Template
+ * - Renders an article element with the class "srl-article-root"
+ * - Uses VRuntimeTemplate to dynamically render the HTML content from pageData.content
+ *
+ * ## Usage
+ * This component is typically used as part of a page layout system to display
+ * the main content of articles that may contain dynamic elements requiring initialization.
+ */
+import { nextTick, ref, onMounted } from 'vue';
+import VRuntimeTemplate from 'vue3-runtime-template';
+import Autoload from '@/Autoload.ts';
+import { useRoute } from 'vue-router';
+import { useArticle, useArticles, useConfig, useRoot } from '#composables';
+import { prepareHtmlContent } from '#utils';
+
+const articleRoot = ref<HTMLDivElement | null>(null);
+const config = useConfig();
+const route = useRoute();
+const articles = useArticles();
+const content = ref<string>('');
+const locale = route.params.locale as string;
+const article = useArticle();
+
+if (article.value) {
+  const file = `./html/${locale}/${article.value.name}.html`;
+  try {
+    const req = await fetch(file);
+    let text = await req.text();
+
+    document.title = article.value.translatedTitle;
+    content.value = prepareHtmlContent(text);
+  } catch (error) {
+    console.error(`Failed to load article content from ${file}:`, error);
+  }
+}
+
+onMounted(() => {
+  nextTick(() => {
+    Autoload.init(articleRoot.value);
+    if (route.hash) {
+      const target = document.querySelector(route.hash);
+      if (target) {
+        target.scrollIntoView({ behavior: 'instant', block: 'start' });
+      }
+    }
+  });
+});
+</script>
+
+<template>
+  <article ref="articleRoot" class="srl-article-root">
+    <VRuntimeTemplate :template="content" />
+  </article>
+</template>

package/srl/components/Srl/Menu/Item/Content/Image.vue

@@ -0,0 +1,12 @@
+<script setup lang="ts">
+const props = defineProps<{
+  item: NsWowNavigationItem;
+}>();
+</script>
+
+<template>
+  <img
+    :src="props.item.img.src"
+    :alt="props.item.img.alt ?? props.item.label"
+  />
+</template>

package/srl/components/Srl/Menu/Item/Content/ImageAfter.vue

@@ -0,0 +1,13 @@
+<script setup lang="ts">
+const props = defineProps<{
+  item: NsWowNavigationItem;
+}>();
+</script>
+
+<template>
+  <span>{{ props.item.label }}</span>
+  <img
+    :src="props.item.imgAfter.src"
+    :alt="props.item.imgAfter.alt ?? props.item.label"
+  />
+</template>