@rio-cloud/rio-uikit 1.11.0 → 1.13.0

package/src/utils/fuelTypeUtils.d.ts

@@ -0,0 +1,62 @@
+import type { IconType } from '../components/rioglyph/Rioglyph';
+export type FuelType = 'unknown' | 'gas' | 'diesel' | 'kerosene' | 'heavy_fuel_oil' | 'methanol' | 'ethanol' | 'lpg' | 'cng' | 'propane' | 'ng' | 'ng_compressed' | 'electric' | 'bi_fuel_gas' | 'bi_fuel_methanol' | 'bi_fuel_ethanol' | 'bi_fuel_lpg' | 'bi_fuel_cng' | 'bi_fuel_ng' | 'bi_fuel_diesel' | 'bi_fuel_propane' | 'bi_fuel_battery' | 'bi_fuel_battery_combustion' | 'hybrid_gas' | 'hybrid_gas_ethanol' | 'hybrid_diesel' | 'hybrid_battery' | 'hybrid_battery_combustion' | 'hybrid_regeneration_mode' | 'dual_fuel_diesel_cng' | 'dual_fuel_diesel_lng' | 'hydrogen' | 'fuel_cell_hydrogen';
+export type FuelTypeGroup = 'liquid' | 'gas' | 'electric' | 'hydrogen' | 'hybrid' | 'unknown';
+/**
+ * Maps each fuel type group to its representative icon.
+ *
+ * This icon can be used to visually identify the group in the UI,
+ * such as in filter buttons or labels.
+ */
+export declare const fuelTypeGroupIcons: Record<FuelTypeGroup, IconType>;
+/**
+ * List of all defined fuel type groups (excluding "unknown").
+ *
+ * Used to render UI elements like filter buttons or fuel group selectors.
+ */
+export declare const fuelTypeGroups: FuelTypeGroup[];
+/**
+ * Returns the icon for a given fuel type group.
+ *
+ * @param fuelTypeGroup - The fuel group to get the icon for.
+ * @returns The corresponding icon for the group.
+ *
+ * @example
+ * getFuelTypeGroupIcon('gas') // → 'rioglyph-fuel-gas'
+ */
+export declare const getFuelTypeGroupIcon: (fuelTypeGroup: FuelTypeGroup) => "rioglyph-status-available" | "rioglyph-status-working" | "rioglyph-status-driving" | "rioglyph-status-resting" | "rioglyph-arrow-left" | "rioglyph-remove" | "rioglyph-arrow-right" | "rioglyph-empty" | "rioglyph-truck-breakdown" | "rioglyph-chevron-down" | "rioglyph-ban-circle" | "rioglyph-wrench" | "rioglyph-stars" | "rioglyph-looking-glass-man" | "rioglyph-academic-cap" | "rioglyph-addressbook" | "rioglyph-air-pay" | "rioglyph-am" | "rioglyph-angle-double-down" | "rioglyph-angle-double-left" | "rioglyph-angle-double-right" | "rioglyph-angle-double-up" | "rioglyph-antenna" | "rioglyph-api" | "rioglyph-archive" | "rioglyph-area-chart" | "rioglyph-area-in" | "rioglyph-area-out" | "rioglyph-arrow-down" | "rioglyph-arrow-up" | "rioglyph-axle" | "rioglyph-battery-level-empty" | "rioglyph-battery-level-full" | "rioglyph-battery-level-low" | "rioglyph-beacon" | "rioglyph-book" | "rioglyph-bookable-poi" | "rioglyph-bookmark-square" | "rioglyph-bookmark" | "rioglyph-border-crossing" | "rioglyph-brake" | "rioglyph-building" | "rioglyph-bus-baseline" | "rioglyph-bus-breakdown" | "rioglyph-bus" | "rioglyph-businessman" | "rioglyph-calendar-parking" | "rioglyph-calendar-plus" | "rioglyph-calendar-today" | "rioglyph-calendar" | "rioglyph-camera" | "rioglyph-car-baseline" | "rioglyph-car-wash" | "rioglyph-car" | "rioglyph-card-hotel" | "rioglyph-card-reader" | "rioglyph-cards-add" | "rioglyph-cards-grid" | "rioglyph-cards-list" | "rioglyph-cards-table" | "rioglyph-cargo" | "rioglyph-carrier" | "rioglyph-chat" | "rioglyph-check-badge" | "rioglyph-check-shield" | "rioglyph-checkbox-checked" | "rioglyph-checkbox" | "rioglyph-checkboxes" | "rioglyph-chevron-left" | "rioglyph-chevron-right" | "rioglyph-chevron-up" | "rioglyph-circle-stack" | "rioglyph-click" | "rioglyph-climate-control" | "rioglyph-clipboard" | "rioglyph-cloud-download" | "rioglyph-cloud-not-saved" | "rioglyph-cloud-upload" | "rioglyph-cloud" | "rioglyph-coasting" | "rioglyph-code-braces" | "rioglyph-code-brackets" | "rioglyph-cog" | "rioglyph-color-swatch" | "rioglyph-comment" | "rioglyph-compare" | "rioglyph-component-custom-recurrent" | "rioglyph-component-custom" | "rioglyph-component" | "rioglyph-construction" | "rioglyph-cookie" | "rioglyph-cooling" | "rioglyph-cost-efficency" | "rioglyph-cruise-control" | "rioglyph-csv" | "rioglyph-currency-euro" | "rioglyph-damages" | "rioglyph-dangerousgoods" | "rioglyph-dashboard" | "rioglyph-delivery-completed" | "rioglyph-delivery-error" | "rioglyph-delivery-late" | "rioglyph-delivery-on-track" | "rioglyph-delivery-warning" | "rioglyph-delivery" | "rioglyph-design" | "rioglyph-desktop" | "rioglyph-detail-view-info" | "rioglyph-detail-view" | "rioglyph-direction" | "rioglyph-document-out" | "rioglyph-document" | "rioglyph-download" | "rioglyph-drag-n-drop" | "rioglyph-drive-history" | "rioglyph-driver-card" | "rioglyph-driver" | "rioglyph-drivercard-in" | "rioglyph-drivercard-out" | "rioglyph-duplicate" | "rioglyph-earphone" | "rioglyph-engine" | "rioglyph-envelope-indicator" | "rioglyph-envelope-open" | "rioglyph-envelope" | "rioglyph-erase" | "rioglyph-error-sign" | "rioglyph-euro-note" | "rioglyph-exclamation-sign" | "rioglyph-exclamation" | "rioglyph-eye-close" | "rioglyph-eye-option" | "rioglyph-face-frown" | "rioglyph-face-neutral" | "rioglyph-face-smile" | "rioglyph-facetime-video" | "rioglyph-factory" | "rioglyph-file-signature" | "rioglyph-files" | "rioglyph-fill" | "rioglyph-filling-e-station" | "rioglyph-filling-station" | "rioglyph-filter-active" | "rioglyph-filter" | "rioglyph-fingerprint" | "rioglyph-finish" | "rioglyph-fire" | "rioglyph-flag" | "rioglyph-flash" | "rioglyph-folder-closed" | "rioglyph-folder-open" | "rioglyph-fuel-diesel" | "rioglyph-fuel-electric" | "rioglyph-fuel-gas" | "rioglyph-fuel-hydrogen" | "rioglyph-fuel-liquid" | "rioglyph-fuel-mix" | "rioglyph-fullscreen" | "rioglyph-geofence" | "rioglyph-globe" | "rioglyph-group" | "rioglyph-hand-down" | "rioglyph-hand-left" | "rioglyph-hand-right" | "rioglyph-hand-up" | "rioglyph-handshake" | "rioglyph-hash" | "rioglyph-heart" | "rioglyph-heating" | "rioglyph-home-sign" | "rioglyph-home" | "rioglyph-hour-glass" | "rioglyph-id" | "rioglyph-inbox-in" | "rioglyph-inbox-out" | "rioglyph-inbox-stack" | "rioglyph-inbox" | "rioglyph-info-sign" | "rioglyph-info" | "rioglyph-key" | "rioglyph-kickdown" | "rioglyph-language" | "rioglyph-layer-pois" | "rioglyph-layer" | "rioglyph-light-bulb" | "rioglyph-line-chart" | "rioglyph-link" | "rioglyph-load-unload" | "rioglyph-load" | "rioglyph-location-arrow" | "rioglyph-lock-open" | "rioglyph-lock" | "rioglyph-log-in" | "rioglyph-logout" | "rioglyph-looking-glass" | "rioglyph-maintenance-components" | "rioglyph-map-location" | "rioglyph-map-marker" | "rioglyph-map" | "rioglyph-megaphone" | "rioglyph-menu-hamburger" | "rioglyph-merge" | "rioglyph-milage" | "rioglyph-minus-light" | "rioglyph-minus-sign" | "rioglyph-minus" | "rioglyph-missing" | "rioglyph-mode-dark-light" | "rioglyph-more" | "rioglyph-new-window" | "rioglyph-newspaper" | "rioglyph-notification" | "rioglyph-number-1" | "rioglyph-number-2" | "rioglyph-number-3" | "rioglyph-off" | "rioglyph-oil-can" | "rioglyph-ok-circle" | "rioglyph-ok-sign" | "rioglyph-ok" | "rioglyph-onboarding" | "rioglyph-ongoing" | "rioglyph-option-horizontal" | "rioglyph-option-vertical" | "rioglyph-order" | "rioglyph-palette-broken" | "rioglyph-palette" | "rioglyph-paper-clip" | "rioglyph-parcel-broken" | "rioglyph-parcel" | "rioglyph-parking" | "rioglyph-pause-circle" | "rioglyph-pause" | "rioglyph-pdf-file" | "rioglyph-pencil-square" | "rioglyph-pencil" | "rioglyph-phone" | "rioglyph-pictures" | "rioglyph-pin-range" | "rioglyph-pin" | "rioglyph-play-circle" | "rioglyph-play" | "rioglyph-plugged-off" | "rioglyph-plugged-on" | "rioglyph-plus-light" | "rioglyph-plus-sign" | "rioglyph-plus" | "rioglyph-pm" | "rioglyph-poi" | "rioglyph-polygon" | "rioglyph-position" | "rioglyph-print" | "rioglyph-progress-ongoing" | "rioglyph-progress-remaining" | "rioglyph-pto-off" | "rioglyph-pto-on" | "rioglyph-pushpin" | "rioglyph-puzzle" | "rioglyph-pylon" | "rioglyph-qr-code" | "rioglyph-question-sign" | "rioglyph-question" | "rioglyph-record" | "rioglyph-refresh" | "rioglyph-remove-circle" | "rioglyph-remove-sign" | "rioglyph-repeat" | "rioglyph-resize-full" | "rioglyph-resize-horizontal" | "rioglyph-resize-small" | "rioglyph-resize-vertical" | "rioglyph-retrofit" | "rioglyph-retweet" | "rioglyph-revert" | "rioglyph-rio-marker" | "rioglyph-rio" | "rioglyph-road-restrictions" | "rioglyph-road" | "rioglyph-robot" | "rioglyph-rocket" | "rioglyph-role-management" | "rioglyph-route-option" | "rioglyph-route-view" | "rioglyph-route" | "rioglyph-ruler" | "rioglyph-save" | "rioglyph-scale" | "rioglyph-scan" | "rioglyph-scissors" | "rioglyph-search-list" | "rioglyph-search-truck" | "rioglyph-search" | "rioglyph-send" | "rioglyph-series" | "rioglyph-server-stack" | "rioglyph-settings" | "rioglyph-share-alt" | "rioglyph-share-nodes" | "rioglyph-share" | "rioglyph-ship" | "rioglyph-shopping-bag" | "rioglyph-shopping-cart" | "rioglyph-signature" | "rioglyph-slope-down-max" | "rioglyph-slope-down-min" | "rioglyph-slope-up-max" | "rioglyph-slope-up-min" | "rioglyph-sort-by-attributes-alt" | "rioglyph-sort-by-attributes" | "rioglyph-sort" | "rioglyph-sparkles" | "rioglyph-speed" | "rioglyph-sphere" | "rioglyph-spinner" | "rioglyph-split-view" | "rioglyph-stack" | "rioglyph-star-empty" | "rioglyph-star" | "rioglyph-start" | "rioglyph-stats" | "rioglyph-steering-wheel" | "rioglyph-stopover" | "rioglyph-support" | "rioglyph-table-view" | "rioglyph-tachograph-download" | "rioglyph-tachograph" | "rioglyph-tag" | "rioglyph-tasks" | "rioglyph-temperature" | "rioglyph-th-list" | "rioglyph-thumbs-down" | "rioglyph-thumbs-up" | "rioglyph-tickets" | "rioglyph-time-alt" | "rioglyph-time-cancle" | "rioglyph-time" | "rioglyph-tire" | "rioglyph-tms" | "rioglyph-to-bottom" | "rioglyph-to-left" | "rioglyph-to-right" | "rioglyph-to-top" | "rioglyph-traffic-lights" | "rioglyph-trailer-baseline" | "rioglyph-trailer" | "rioglyph-trailerposition" | "rioglyph-train" | "rioglyph-transfer" | "rioglyph-trash" | "rioglyph-triangle-bottom" | "rioglyph-triangle-left" | "rioglyph-triangle-right" | "rioglyph-triangle-top" | "rioglyph-trophy" | "rioglyph-truck-baseline" | "rioglyph-truck-unit" | "rioglyph-truck" | "rioglyph-unlink" | "rioglyph-upload" | "rioglyph-user-add" | "rioglyph-user-group" | "rioglyph-user-ok" | "rioglyph-user-remove" | "rioglyph-user-sign-off" | "rioglyph-user-sign" | "rioglyph-user" | "rioglyph-van-baseline" | "rioglyph-van" | "rioglyph-volume" | "rioglyph-wallet" | "rioglyph-warning-sign" | "rioglyph-weather-cloudy" | "rioglyph-weather-icy" | "rioglyph-weather-overcast" | "rioglyph-weather-raining" | "rioglyph-weather-snowing" | "rioglyph-weather-stormy" | "rioglyph-weather-sunny" | "rioglyph-weather-thundering" | "rioglyph-weather-windy" | "rioglyph-weight" | "rioglyph-width" | "rioglyph-wifi-off" | "rioglyph-wifi" | "rioglyph-window" | "rioglyph-workshop" | "rioglyph-xmas-raindeer" | "rioglyph-xmas-santa" | "rioglyph-video-off" | "rioglyph-video" | "rioglyph-circle-dashed" | "rioglyph-cube-dashed" | "rioglyph-dashboard-view" | "rioglyph-group-blocks" | "rioglyph-square-dashed" | "rioglyph-cube" | "rioglyph-ok-dashed" | "rioglyph-prompt" | "rioglyph-recycle" | "rioglyph-status-change" | "rioglyph-transition-right" | "rioglyph-transition-push-right" | "rioglyph-status-change-horizontal" | "rioglyph-warehouse" | "rioglyph-migrate" | "rioglyph-shelve" | "rioglyph-convert" | "rioglyph-conveyor-belt" | "rioglyph-tracking-package" | "rioglyph-issue-tracking";
+/**
+ * Returns the representative icon for a specific fuel type.
+ *
+ * This function maps a fuel type to its logical fuel group,
+ * and returns the icon associated with that group.
+ *
+ * @param fuelType - The specific fuel type of the item. Default is 'unknown'.
+ * @returns The icon associated with the resolved fuel group.
+ *
+ * @example
+ * getFuelIcon('cng') // → 'rioglyph-fuel-gas'
+ */
+export declare const getFuelIcon: (fuelType?: FuelType) => IconType;
+/**
+ * Filters a list of items by fuel group.
+ *
+ * @param items - The list of items to filter.
+ * @param activeGroups - The selected fuel type groups to include in the result.
+ * @param getFuelType - Function to extract the fuel type from an item.
+ * @returns The filtered list containing only items that belong to one of the specified fuel groups.
+ *
+ * @example
+ * filterByFuelTypeGroup(vehicles, ['electric'], v => v.fuelType);
+ */
+export declare const filterByFuelTypeGroup: <T>(items: T[], activeGroups: FuelTypeGroup[], getFuelType: (item: T) => FuelType | undefined) => T[];
+/**
+ * Counts how many items belong to each fuel type group.
+ *
+ * @param items - The list of items to count.
+ * @param getFuelType - Function to extract the fuel type from an item.
+ * @returns An object mapping each fuel type group to its count.
+ *
+ * @example
+ * countFuelTypeGroups(vehicles, v => v.fuelType);
+ */
+export declare const countFuelTypeGroups: <T>(items: T[], getFuelType: (item: T) => FuelType | undefined) => Record<FuelTypeGroup, number>;

package/src/utils/fuelTypeUtils.js

@@ -0,0 +1,128 @@
+const fuelGroupMap = {
+    unknown: 'unknown',
+    gas: 'liquid', // Gasoline/petrol
+    diesel: 'liquid', // Diesel
+    kerosene: 'liquid', // Kerosene
+    heavy_fuel_oil: 'liquid', // Heavy Fuel Oil
+    methanol: 'gas', // Methanol
+    ethanol: 'gas', // Ethanol
+    lpg: 'gas', // Liquefied Petroleum Gas (LPG)
+    cng: 'gas', // Compressed Natural Gas (CNG)
+    propane: 'gas', // Propane
+    ng: 'gas', // Natural Gas (NG)
+    ng_compressed: 'gas', // Natural Gas (Compressed or Liquefied Natural Gas)
+    electric: 'electric', // Battery/electric
+    bi_fuel_gas: 'hybrid', // Bi-fuel vehicle using gasoline
+    bi_fuel_methanol: 'hybrid', // Bi-fuel vehicle using methanol
+    bi_fuel_ethanol: 'hybrid', // Bi-fuel vehicle using ethanol
+    bi_fuel_lpg: 'hybrid', // Bi-fuel vehicle using LPG
+    bi_fuel_cng: 'hybrid', // Bi-fuel vehicle using CNG
+    bi_fuel_ng: 'hybrid', // Bi-fuel vehicle using NG
+    bi_fuel_diesel: 'hybrid', // Bi-fuel using diesel
+    bi_fuel_propane: 'hybrid', // Bi-fuel vehicle using propane
+    bi_fuel_battery: 'hybrid', // Bi-fuel vehicle using battery
+    bi_fuel_battery_combustion: 'hybrid', // Bi-fuel vehicle using battery and combustion
+    hybrid_gas: 'hybrid', // Hybrid vehicle using gasoline engine
+    hybrid_gas_ethanol: 'hybrid', // Hybrid vehicle using gasoline engine on ethanol
+    hybrid_diesel: 'hybrid', // Hybrid vehicle using diesel engine
+    hybrid_battery: 'hybrid', // Hybrid vehicle using battery
+    hybrid_battery_combustion: 'hybrid', // Hybrid vehicle using battery and combustion
+    hybrid_regeneration_mode: 'hybrid', // Hybrid vehicle in regeneration mode
+    dual_fuel_diesel_cng: 'hybrid', // Dual Fuel – Diesel and CNG
+    dual_fuel_diesel_lng: 'hybrid', // Dual Fuel – Diesel and LNG
+    hydrogen: 'hydrogen', // Hydrogen Internal Combustion
+    fuel_cell_hydrogen: 'hydrogen', // Fuel Cell Utilizing Hydrogen Engine
+};
+/**
+ * Maps each fuel type group to its representative icon.
+ *
+ * This icon can be used to visually identify the group in the UI,
+ * such as in filter buttons or labels.
+ */
+export const fuelTypeGroupIcons = {
+    liquid: 'rioglyph-fuel-liquid',
+    gas: 'rioglyph-fuel-gas',
+    electric: 'rioglyph-fuel-electric',
+    hydrogen: 'rioglyph-fuel-hydrogen',
+    hybrid: 'rioglyph-fuel-mix',
+    unknown: 'rioglyph-question',
+};
+/**
+ * List of all defined fuel type groups (excluding "unknown").
+ *
+ * Used to render UI elements like filter buttons or fuel group selectors.
+ */
+export const fuelTypeGroups = ['liquid', 'gas', 'electric', 'hydrogen', 'hybrid'];
+/**
+ * Returns the icon for a given fuel type group.
+ *
+ * @param fuelTypeGroup - The fuel group to get the icon for.
+ * @returns The corresponding icon for the group.
+ *
+ * @example
+ * getFuelTypeGroupIcon('gas') // → 'rioglyph-fuel-gas'
+ */
+export const getFuelTypeGroupIcon = (fuelTypeGroup) => fuelTypeGroupIcons[fuelTypeGroup];
+/**
+ * Returns the representative icon for a specific fuel type.
+ *
+ * This function maps a fuel type to its logical fuel group,
+ * and returns the icon associated with that group.
+ *
+ * @param fuelType - The specific fuel type of the item. Default is 'unknown'.
+ * @returns The icon associated with the resolved fuel group.
+ *
+ * @example
+ * getFuelIcon('cng') // → 'rioglyph-fuel-gas'
+ */
+export const getFuelIcon = (fuelType = 'unknown') => {
+    const group = fuelGroupMap[fuelType] ?? 'unknown';
+    return fuelTypeGroupIcons[group] ?? fuelTypeGroupIcons.unknown;
+};
+/**
+ * Filters a list of items by fuel group.
+ *
+ * @param items - The list of items to filter.
+ * @param activeGroups - The selected fuel type groups to include in the result.
+ * @param getFuelType - Function to extract the fuel type from an item.
+ * @returns The filtered list containing only items that belong to one of the specified fuel groups.
+ *
+ * @example
+ * filterByFuelTypeGroup(vehicles, ['electric'], v => v.fuelType);
+ */
+export const filterByFuelTypeGroup = (items, activeGroups, getFuelType) => {
+    if (activeGroups.length === 0) {
+        return items;
+    }
+    return items.filter(item => {
+        const fuelType = getFuelType(item);
+        const group = fuelType ? (fuelGroupMap[fuelType] ?? 'unknown') : 'unknown';
+        return activeGroups.includes(group);
+    });
+};
+/**
+ * Counts how many items belong to each fuel type group.
+ *
+ * @param items - The list of items to count.
+ * @param getFuelType - Function to extract the fuel type from an item.
+ * @returns An object mapping each fuel type group to its count.
+ *
+ * @example
+ * countFuelTypeGroups(vehicles, v => v.fuelType);
+ */
+export const countFuelTypeGroups = (items, getFuelType) => {
+    const counts = {
+        liquid: 0,
+        gas: 0,
+        electric: 0,
+        hydrogen: 0,
+        hybrid: 0,
+        unknown: 0,
+    };
+    for (const item of items) {
+        const fuelType = getFuelType(item);
+        const group = fuelType ? (fuelGroupMap[fuelType] ?? 'unknown') : 'unknown';
+        counts[group]++;
+    }
+    return counts;
+};

package/src/utils/hidePiiData.d.ts

@@ -0,0 +1,62 @@
+/****
+ * hidePiiData.ts
+ *
+ * Purpose
+ * -------
+ * Utilities for anonymizing Personally Identifiable Information (PII) in rendered DOM content.
+ * The main entry point is `hidePiiData`, which shuffles visible text inside a target element.
+ *
+ * Integration / Activation
+ * -----------------------
+ * Activation can be toggled with **Ctrl+Shift+U / Cmd+Shift+U**, or by setting the
+ * `<html>` attribute `data-hide-pii="shuffle"`. When activated, new or changed content
+ * marked with `data-pii="visible"` is processed by this module.
+ * This file does not attach observers by itself. It only exposes pure DOM utilities.
+ *
+ * High level behavior
+ * -------------------
+ * 1. Tokenize text on whitespace while preserving the original whitespace.
+ * 2. For email tokens, clean punctuation, pad each part to at least six characters,
+ *    shuffle both parts independently, and rejoin with `@`.
+ * 3. For normal tokens shorter than six characters, pad with random alphanumerics before shuffling.
+ * 4. Preserve capitalization pattern for simple Name like tokens (e.g. `Alice`) after shuffling.
+ *
+ * Data attributes used
+ * --------------------
+ * - `data-pii="visible"` marks elements that should be anonymized.
+ * - `data-pii="hidden"` is written to elements that have already been processed to help external code introspect state.
+ * - `data-hide-pii="shuffle"` on `<html>` is used by an external observer to decide when to call `hidePiiData`.
+ */
+/**
+ * Shuffle text while preserving whitespace.
+ *
+ * Behavior
+ * --------
+ * - Tokenization uses `\S+` to process non whitespace runs and preserves the original whitespace.
+ * - Email like tokens are handled by `shuffleEmail`.
+ * - Non email tokens shorter than six characters are padded with random alphanumerics before shuffling.
+ * - For simple Name like tokens (regex `^[A-Z][a-z]+$`), capitalization is preserved after shuffling.
+ */
+export declare const shuffleText: (str: string, preserveCase?: boolean) => string;
+export declare const shufflePii: (text: string) => string;
+/**
+ * Shuffle text nodes or input values inside the provided element(s).
+ *
+ * Parameters
+ * ----------
+ * - `target`: either a single `Element` or a `NodeListOf<Element>`.
+ * - `forceResult`: optional string to override output directly.
+ *
+ * How it works
+ * ------------
+ * - Marks each processed element with `data-pii="hidden"`.
+ * - If the element is an `<input>`, it shuffles the `value` string and writes it back.
+ * - For non input elements, it walks text nodes with a `TreeWalker` and replaces the node values
+ *   with their shuffled variants.
+ *
+ * Performance notes
+ * -----------------
+ * - Work is proportional to the number of text nodes in `target`.
+ * - Avoid calling this repeatedly on large subtrees without batching.
+ */
+export declare const hidePiiData: (target: Element | NodeListOf<Element>, forceResult?: string) => void;

package/src/utils/hidePiiData.js

@@ -0,0 +1,394 @@
+/****
+ * hidePiiData.ts
+ *
+ * Purpose
+ * -------
+ * Utilities for anonymizing Personally Identifiable Information (PII) in rendered DOM content.
+ * The main entry point is `hidePiiData`, which shuffles visible text inside a target element.
+ *
+ * Integration / Activation
+ * -----------------------
+ * Activation can be toggled with **Ctrl+Shift+U / Cmd+Shift+U**, or by setting the
+ * `<html>` attribute `data-hide-pii="shuffle"`. When activated, new or changed content
+ * marked with `data-pii="visible"` is processed by this module.
+ * This file does not attach observers by itself. It only exposes pure DOM utilities.
+ *
+ * High level behavior
+ * -------------------
+ * 1. Tokenize text on whitespace while preserving the original whitespace.
+ * 2. For email tokens, clean punctuation, pad each part to at least six characters,
+ *    shuffle both parts independently, and rejoin with `@`.
+ * 3. For normal tokens shorter than six characters, pad with random alphanumerics before shuffling.
+ * 4. Preserve capitalization pattern for simple Name like tokens (e.g. `Alice`) after shuffling.
+ *
+ * Data attributes used
+ * --------------------
+ * - `data-pii="visible"` marks elements that should be anonymized.
+ * - `data-pii="hidden"` is written to elements that have already been processed to help external code introspect state.
+ * - `data-hide-pii="shuffle"` on `<html>` is used by an external observer to decide when to call `hidePiiData`.
+ */
+/**
+ * In place Fisher Yates shuffle.
+ * Randomizes the order of the given array using `Math.random()`.
+ * This is sufficient for UI anonymization but is not cryptographically secure.
+ */
+const fyShuffle = (arr) => {
+    for (let i = arr.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        const tmp = arr[i];
+        arr[i] = arr[j];
+        arr[j] = tmp;
+    }
+};
+/** Returns true if (A-Z, a-z, 0-9). */
+const isTextOrNumber = (el) => {
+    return /[A-Za-z0-9]/.test(el);
+};
+/**
+ * Generate a random ASCII alphanumeric string of length `n`.
+ * Used to pad very short tokens before shuffling to increase anonymity.
+ */
+const addRandomCharacter = (el) => {
+    const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+    let out = '';
+    for (let i = 0; i < el; i++) {
+        out += chars.charAt(Math.floor(Math.random() * chars.length)).toLocaleLowerCase();
+    }
+    return out;
+};
+/**
+ * Ensure a minimum length by appending random alphanumerics when `s` is shorter than `minLen`.
+ * Defaults to 6 which balances privacy and UI density.
+ */
+const ensureMinLength = (el, minLen = 6) => {
+    if (el.length >= minLen) {
+        return el;
+    }
+    return el + addRandomCharacter(minLen - el.length);
+};
+/** Generate a random numeric string of length `n`. */
+const randomDigits = (n) => {
+    const digits = '0123456789';
+    let out = '';
+    for (let i = 0; i < n; i++) {
+        out += digits.charAt(Math.floor(Math.random() * digits.length));
+    }
+    return out;
+};
+/** Ensure a minimum length by appending random digits (for phone numbers). */
+const ensureMinDigits = (s, minLen = 6) => {
+    if (s.length >= minLen) {
+        return s;
+    }
+    return s + randomDigits(minLen - s.length);
+};
+/**
+ * Shuffle a token while trying to keep an alphanumeric character at both boundaries.
+ *
+ * Why boundaries matter
+ * ---------------------
+ * Many UI layouts expect words to begin and end with letters or digits. By forcing
+ * alphanumeric characters to the first and last positions when possible, we avoid
+ * odd leading punctuation or trailing punctuation that could break alignment or
+ * cause misleading visual cues.
+ *
+ * Rules
+ * -----
+ * - If there are no alphanumerics, the original string is returned unchanged.
+ * - If there is only one alphanumeric and length is at least 2, it also returns unchanged,
+ *   since we cannot satisfy both boundaries.
+ * - Non alphanumeric characters are placed only in interior positions.
+ */
+const shuffle = (el) => {
+    const n = el.length;
+    const chars = el.split('');
+    // Separate alphanumeric and non-alphanumeric characters
+    const alnums = [];
+    const nonAlnums = [];
+    for (const char of chars) {
+        if (isTextOrNumber(char)) {
+            alnums.push(char);
+        }
+        else {
+            nonAlnums.push(char);
+        }
+    }
+    // If we cannot satisfy the boundary rule, keep original
+    if (alnums.length === 0) {
+        return el;
+    }
+    if (n >= 2 && alnums.length === 1) {
+        return el; // cannot put alnum at both ends
+    }
+    fyShuffle(alnums);
+    fyShuffle(nonAlnums);
+    // If there are more non alphanumerics than interior slots, bail out to keep boundaries valid
+    const interiorSlots = Math.max(0, n - 2);
+    if (nonAlnums.length > interiorSlots) {
+        return el;
+    }
+    // Build output with alnum at boundaries
+    const out = new Array(n);
+    out[0] = alnums.pop(); // left boundary alnum (safe due to earlier guard)
+    out[n - 1] = alnums.pop(); // right boundary alnum
+    // Fill interior positions randomly with remaining characters
+    const interiorPositions = [];
+    for (let i = 1; i <= n - 2; i++) {
+        interiorPositions.push(i);
+    }
+    fyShuffle(interiorPositions);
+    let k = 0;
+    for (const char of nonAlnums) {
+        out[interiorPositions[k++]] = char; // place all non-alnums inside
+    }
+    for (const char of alnums) {
+        out[interiorPositions[k++]] = char; // then remaining alnums
+    }
+    return out.join('');
+};
+/**
+ * Shuffle an email address in a privacy aware way.
+ *
+ * Steps
+ * -----
+ * 1. Split on `@` into local and domain.
+ * 2. Remove any non alphanumeric characters from both parts (drop dots and dashes).
+ * 3. Pad each part to a minimum of six characters to avoid very short outputs.
+ * 4. Shuffle the local and domain parts independently and rejoin with `@`.
+ *
+ * Rationale
+ * ---------
+ * Emails often contain structure that makes simple shuffling ineffective. By stripping
+ * punctuation and enforcing a minimum length, we reduce the chance of hinting at the
+ * original identity while still returning something that looks like an email.
+ */
+const shuffleEmail = (email) => {
+    const [local, domain] = email.split('@');
+    // Remove all non-alphanumeric characters from both parts
+    const cleanName = local.replace(/[^A-Za-z0-9]/g, '');
+    const cleanDomain = domain.replace(/[^A-Za-z0-9]/g, '');
+    const paddedName = ensureMinLength(cleanName, 6);
+    const shuffledName = shuffleText(paddedName, false);
+    const shuffledDomain = shuffleText(cleanDomain, false);
+    /**
+     * Get a two-letter locale suffix based on the user's browser locale.
+     * Prefers the region subtag (e.g., "en-US" -> "US"). Falls back to the language
+     * subtag (e.g., "de" -> "DE"). Returns "XX" if unavailable.
+     */
+    const getLocaleSuffix = () => {
+        try {
+            const langRaw = typeof navigator !== 'undefined' ? navigator.languages?.[0] || navigator.language || '' : '';
+            const lang = (langRaw || '').replace('_', '-');
+            if (!lang) {
+                return 'com';
+            }
+            const parts = lang.split('-');
+            const region = parts[1] || parts[0];
+            const code = (region || '').slice(0, 2).toLocaleLowerCase();
+            return code || 'com';
+        }
+        catch {
+            return 'com';
+        }
+    };
+    return `${shuffledName}@${shuffledDomain}.${getLocaleSuffix()}`;
+};
+/**
+ * Shuffle a phone number while preserving its structure.
+ * Removes non-digits, pads if too short, shuffles digits, then reinserts formatting.
+ */
+const shufflePhone = (phone) => {
+    const countryPrefix = phone.startsWith('+') ? phone.slice(1).match(/^\d{1,3}/)?.[0] || '' : '';
+    // Extract all digits and split into country code vs. rest
+    const allDigits = phone.replace(/\D/g, '');
+    const restDigits = countryPrefix ? allDigits.slice(countryPrefix.length) : allDigits;
+    if (restDigits.length < 4) {
+        return phone; // too short to anonymize meaningfully beyond the country code
+    }
+    // Pad and shuffle only the rest (not the country code)
+    const paddedRest = ensureMinDigits(restDigits, 6);
+    const shuffledRest = shuffle(paddedRest);
+    // Reinsert digits into original format:
+    // - Keep the first `countryPrefix.length` digits after '+' unchanged
+    // - Replace subsequent digits with shuffledRest
+    let i = 0; // index into shuffledRest
+    let prefixLeft = countryPrefix.length;
+    let inPrefixBlock = !!countryPrefix; // true if we saw leading '+' and have prefix digits to preserve
+    return phone.replace(/\d/g, phoneNumber => {
+        if (inPrefixBlock) {
+            // We are preserving digits immediately after the leading '+'
+            // Once we consume `prefixLeft` digits, we stop preserving
+            if (prefixLeft > 0) {
+                prefixLeft -= 1;
+                if (prefixLeft === 0) {
+                    inPrefixBlock = false;
+                }
+                return phoneNumber; // keep country code digit as-is
+            }
+            inPrefixBlock = false;
+        }
+        // Replace with next shuffled digit (fallback '0' if exhausted, though length should suffice)
+        return shuffledRest[i++] || '0';
+    });
+};
+/**
+ * Shuffle text while preserving whitespace.
+ *
+ * Behavior
+ * --------
+ * - Tokenization uses `\S+` to process non whitespace runs and preserves the original whitespace.
+ * - Email like tokens are handled by `shuffleEmail`.
+ * - Non email tokens shorter than six characters are padded with random alphanumerics before shuffling.
+ * - For simple Name like tokens (regex `^[A-Z][a-z]+$`), capitalization is preserved after shuffling.
+ */
+export const shuffleText = (str, preserveCase = true) => {
+    if (str.length < 2) {
+        return str;
+    }
+    const lettersOnly = str.replace(/[^A-Za-z]/g, '');
+    const paddedToken = ensureMinLength(lettersOnly, 6);
+    const shuffled = shuffle(paddedToken);
+    if (preserveCase) {
+        return shuffled.charAt(0).toUpperCase() + shuffled.slice(1).toLowerCase();
+    }
+    return shuffled;
+};
+export const shufflePii = (text) => {
+    // First pass: handle phone numbers that may span multiple tokens (spaces, dashes, parentheses)
+    const phoneSeq = /(^|[^A-Za-z0-9])(\+?\d(?:[ \t\-()]*\d){6,})(?=$|[^A-Za-z0-9])/g;
+    const withPhonesShuffled = text.replace(phoneSeq, (_m, pre, num) => pre + shufflePhone(num));
+    // Second pass: token-wise processing for remaining tokens
+    return withPhonesShuffled.replace(/\S+/g, (token) => {
+        // Email detected: delegate to email specific logic
+        if (/^[^@]+@[^@]+$/.test(token)) {
+            return shuffleEmail(token);
+        }
+        // Phone number detected (single-token formats): delegate to phone logic
+        if (/^\+?[0-9][0-9\s\-()]{3,}$/.test(token)) {
+            return shufflePhone(token);
+        }
+        // If the token has no letters at all, leave it unchanged (avoid turning digits into letters)
+        if (!/[A-Za-z]/.test(token)) {
+            return token;
+        }
+        // Enforce a minimum token length for short text tokens
+        const paddedToken = token.length < 6 ? token + addRandomCharacter(6 - token.length) : token;
+        const shuffled = shuffleText(paddedToken);
+        return shuffled;
+    });
+};
+/**
+ * Shuffle text nodes or input values inside the provided element(s).
+ *
+ * Parameters
+ * ----------
+ * - `target`: either a single `Element` or a `NodeListOf<Element>`.
+ * - `forceResult`: optional string to override output directly.
+ *
+ * How it works
+ * ------------
+ * - Marks each processed element with `data-pii="hidden"`.
+ * - If the element is an `<input>`, it shuffles the `value` string and writes it back.
+ * - For non input elements, it walks text nodes with a `TreeWalker` and replaces the node values
+ *   with their shuffled variants.
+ *
+ * Performance notes
+ * -----------------
+ * - Work is proportional to the number of text nodes in `target`.
+ * - Avoid calling this repeatedly on large subtrees without batching.
+ */
+export const hidePiiData = (target, forceResult) => {
+    const elements = target instanceof Element ? [target] : Array.from(target);
+    for (const el of elements) {
+        // Mark the element as processed so other parts of the app can detect its state
+        el.setAttribute('data-pii', 'hidden');
+        const beforeText = (el.textContent || '').trim();
+        // If the selected element is an <input>, shuffle its value instead of text nodes
+        if (el.matches?.('input') || el.tagName === 'INPUT') {
+            const input = el;
+            const val = input.value || '';
+            if (typeof forceResult === 'string' && forceResult.length > 0) {
+                el.setAttribute('data-original-pii', val);
+                input.value = forceResult;
+                el.setAttribute('data-obfuscated-pii', input.value);
+                continue;
+            }
+            el.setAttribute('data-original-pii', val);
+            const trimmed = val.trim();
+            if (trimmed.length > 0) {
+                const shuffled = shufflePii(val);
+                if (shuffled !== val) {
+                    input.value = shuffled;
+                }
+                el.setAttribute('data-obfuscated-pii', input.value);
+            }
+            continue; // skip text-node processing for inputs
+        }
+        // Helper: safely apply a forced text replacement without destroying markup
+        const applyForcedText = (root, value) => {
+            // Case 1: Exactly one element child that itself has no element children
+            // e.g. <td><span>Text</span></td> -> replace span textContent only
+            if (root.children.length === 1) {
+                const onlyChild = root.children[0];
+                if (onlyChild && onlyChild.children.length === 0) {
+                    onlyChild.textContent = value;
+                    return;
+                }
+            }
+            // Case 2: Replace text nodes directly while preserving structure
+            const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT, null);
+            const textNodes = [];
+            let n = walker.nextNode();
+            while (n) {
+                const t = n;
+                if ((t.nodeValue || '').trim().length > 0) {
+                    textNodes.push(t);
+                }
+                n = walker.nextNode();
+            }
+            if (textNodes.length === 0) {
+                // As a last resort, fall back to setting textContent (no visible text nodes found)
+                root.textContent = value;
+                return;
+            }
+            // Put the forced value into the first non-empty text node,
+            // and clear the remainder to avoid duplicated content
+            textNodes[0].nodeValue = value;
+            for (let i = 1; i < textNodes.length; i++) {
+                textNodes[i].nodeValue = '';
+            }
+        };
+        if (typeof forceResult === 'string' && forceResult.length > 0) {
+            if (beforeText) {
+                el.setAttribute('data-original-pii', beforeText);
+            }
+            applyForcedText(el, forceResult);
+            el.setAttribute('data-obfuscated-pii', (el.textContent || '').trim());
+            continue;
+        }
+        let anyTextChanged = false;
+        // Walk only text nodes to avoid touching markup and attributes
+        const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT, null);
+        let node = walker.nextNode();
+        while (node) {
+            const txtNode = node;
+            const original = txtNode.nodeValue || '';
+            const trimmed = original.trim();
+            if (trimmed.length > 0) {
+                const shuffled = shufflePii(original);
+                if (shuffled !== original) {
+                    txtNode.nodeValue = shuffled;
+                    anyTextChanged = true;
+                }
+            }
+            node = walker.nextNode();
+        }
+        const currentText = (el.textContent || '').trim();
+        if (anyTextChanged && currentText) {
+            el.setAttribute('data-obfuscated-pii', currentText);
+            if (beforeText) {
+                el.setAttribute('data-original-pii', beforeText);
+            }
+        }
+    }
+};