@firedesktop/react-base 2.1.25 → 3.0.1

package/docs/LABELS.md

@@ -0,0 +1,148 @@
+# Labels (i18n)
+
+Runtime internationalization system that loads locale JSON files and provides dot-notation label access.
+
+## Components
+
+### LanguageLoader (Redux)
+
+Headless component that loads labels on mount and dispatches to Redux.
+
+```javascript
+import { LanguageLoader } from '@firedesktop/react-base';
+```
+
+#### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `updateAppState` | `(name: string, value: object) => any` | Yes | -- | Redux action creator |
+| `language` | `string` | Yes | -- | Locale code (e.g., `'it-IT'`, `'en'`) |
+| `path` | `string` | No | -- | Custom labels directory path |
+
+#### Usage
+
+```jsx
+import { LanguageLoader } from '@firedesktop/react-base';
+import { Provider } from 'react-redux';
+
+<Provider store={store}>
+  <LanguageLoader updateAppState={updateAppState} language="it-IT" />
+  <App />
+</Provider>
+```
+
+With base + custom labels:
+
+```jsx
+<LanguageLoader
+  updateAppState={updateAppState}
+  language="it-IT"
+  path="labels/custom"
+/>
+```
+
+When `path` is provided, the loader fetches both `./labels/{language}.json` (base) and `./{path}/{language}.json` (custom), then deep-merges custom labels on top of base labels.
+
+### LanguageReturner (Callback)
+
+For applications not using Redux. Loads labels and calls a callback.
+
+```javascript
+import { LanguageReturner } from '@firedesktop/react-base';
+```
+
+#### Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `labels` | `{ language: string }` | No | Current labels state (prevents re-loading) |
+| `language` | `string` | Yes | Locale code |
+| `onLanguageLoad` | `(labels?) => void` | Yes | Callback receiving loaded labels |
+| `path` | `string` | Yes | Path to the labels directory |
+
+## Label File Format
+
+Place locale files in `public/labels/`:
+
+**`it-IT.json`**
+```json
+{
+  "language": "it-IT",
+  "common": {
+    "save": "Salva",
+    "cancel": "Annulla",
+    "delete": "Elimina"
+  },
+  "errors": {
+    "required": "Campo obbligatorio",
+    "invalid_email": "Email non valida"
+  }
+}
+```
+
+**`en.json`**
+```json
+{
+  "language": "en",
+  "common": {
+    "save": "Save",
+    "cancel": "Cancel",
+    "delete": "Delete"
+  },
+  "errors": {
+    "required": "Required field",
+    "invalid_email": "Invalid email"
+  }
+}
+```
+
+The response must be a plain JSON object (not an array or primitive).
+
+## Reading Labels
+
+### LanguageManager
+
+```javascript
+import { Utils } from '@firedesktop/react-base';
+const { getLabel } = Utils.Labels();
+```
+
+#### `getLabel(labels, id, defaultValue?)`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `labels` | `object` | Labels object from Redux state |
+| `id` | `string` | Dot-notation path to the label (e.g., `'common.save'`) |
+| `defaultValue` | `string` | Fallback if the label is not found (defaults to `id`) |
+
+### Usage in components
+
+```jsx
+import { useSelector } from 'react-redux';
+import { Utils } from '@firedesktop/react-base';
+
+const { getLabel } = Utils.Labels();
+
+function MyComponent() {
+  const { labels } = useSelector(state => state);
+
+  return (
+    <div>
+      <button>{getLabel(labels, 'common.save', 'Save')}</button>
+      <button>{getLabel(labels, 'common.cancel', 'Cancel')}</button>
+    </div>
+  );
+}
+```
+
+## Behavior
+
+- Fetches with cache-busting timestamp query parameter
+- Sets `Cache-Control`, `pragma`, `Expires` headers
+- Validates HTTP status (`res.ok`) before parsing
+- Validates the response is a plain object
+- Re-loads when the `language` prop changes
+- Deep merge uses a safe merge function that blocks prototype pollution keys (`__proto__`, `constructor`, `prototype`)
+- Dispatches as `updateAppState('labels', mergedLabels)` (Redux variant)
+- Errors are logged via [Logger](LOGGER.md) (silent by default)

package/docs/LOGGER.md

@@ -0,0 +1,112 @@
+# Logger
+
+`@firedesktop/react-base` includes a built-in Logger utility that controls all internal diagnostic output. It is **disabled by default**, meaning the library produces zero console output in production unless explicitly enabled by the consumer application.
+
+## Why
+
+Previous versions of this library logged configuration paths, label data, fetch URLs, and error objects directly to `console.log/warn/error` in all environments. This caused:
+
+- Sensitive configuration data visible in production browser consoles
+- Internal file paths exposed to end users
+- Noisy console output that obscured application-level logs
+- No way for consumers to suppress library logging
+
+The Logger centralizes all internal logging behind a single opt-in flag, resolving these issues.
+
+## Quick Start
+
+```javascript
+import { Logger } from '@firedesktop/react-base';
+
+// Enable debug logging (typically in your app entry point)
+Logger.enableDebug(process.env.NODE_ENV === 'development');
+```
+
+All internal library logs will now appear in the browser console, prefixed with `[react-base]`.
+
+## API Reference
+
+### `Logger.enableDebug(enabled: boolean): void`
+
+Turns debug logging on or off globally. Affects all `Logger.debug`, `Logger.warn`, and `Logger.error` calls across the library.
+
+```javascript
+// Enable
+Logger.enableDebug(true);
+
+// Disable (default state)
+Logger.enableDebug(false);
+```
+
+### `Logger.isEnabled(): boolean`
+
+Returns the current debug state. Useful for conditional logic in consumer code.
+
+```javascript
+if (Logger.isEnabled()) {
+    // additional app-level debugging
+}
+```
+
+### `Logger.debug(message: string, ...args: any[]): void`
+
+Logs an informational message via `console.log` when debug is enabled. Used internally for loading progress (e.g., "Loading Configuration...", "Loaded Labels...").
+
+```javascript
+Logger.debug('Custom message', { someData: 123 });
+// Output when enabled: [react-base] Custom message { someData: 123 }
+```
+
+### `Logger.warn(message: string, ...args: any[]): void`
+
+Logs a warning via `console.warn` when debug is enabled. Used internally for non-critical failures (e.g., labels file not found, fetch errors).
+
+### `Logger.error(message: string, ...args: any[]): void`
+
+Logs an error via `console.error` when debug is enabled. Used internally for loading failures (e.g., configuration load error, label parse error).
+
+## Usage Patterns
+
+### Development only
+
+```javascript
+Logger.enableDebug(process.env.NODE_ENV === 'development');
+```
+
+### Feature flag controlled
+
+```javascript
+Logger.enableDebug(window.__DEBUG_REACT_BASE__ === true);
+```
+
+### Conditional at runtime
+
+```javascript
+// Enable from browser DevTools at any time:
+// window.__REACT_BASE_DEBUG = true
+
+Logger.enableDebug(window.__REACT_BASE_DEBUG === true);
+```
+
+### Disable completely (default)
+
+No action needed. The Logger is off by default. If you never call `Logger.enableDebug(true)`, zero console output is produced by the library.
+
+## Filtering in Browser DevTools
+
+When enabled, all messages are prefixed with `[react-base]`. To filter:
+
+1. Open browser DevTools > Console
+2. Type `[react-base]` in the filter box
+3. Only library logs are shown
+
+## Import Paths
+
+```javascript
+// Top-level export (recommended)
+import { Logger } from '@firedesktop/react-base';
+
+// Via Utils namespace
+import { Utils } from '@firedesktop/react-base';
+Utils.Logger.enableDebug(true);
+```