tailjng 0.1.12 → 0.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tailjng",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "peerDependencies": {
     "@angular/common": "^19.2.0",
     "@angular/core": "^19.2.0",

package/src/lib/components/filter/filter-complete/complete-filter.util.ts

@@ -1,4 +1,4 @@
-import type { FilterSelect } from 'tailjng';
+import type { FilterSelect } from '../../../interfaces/crud/filter.interface';
 
 /** Whether search text or any filter select differs from its initial value. */
 export function hasActiveFilters(

package/src/lib/components/toggle-radio/shared/toggle-options.types.ts

@@ -1,6 +1,7 @@
 export type ToggleOption<T = unknown> = {
   value: T;
   label: string;
+  original?: unknown;
 };
 
 export type ToggleSortOrder = 'ASC' | 'DESC';

package/src/lib/components/toggle-radio/shared/toggle-options.util.ts

@@ -18,22 +18,105 @@ export function buildToggleLoadParams(
   return params;
 }
 
+/** Reads a nested property using dot notation (`a.b.c`). */
+export function getNestedToggleRawValue(obj: unknown, path: string): unknown {
+  if (!path?.trim()) {
+    return '';
+  }
+
+  let value: unknown = obj;
+
+  for (const part of path.split('.').filter(Boolean)) {
+    if (value == null || typeof value !== 'object') {
+      return '';
+    }
+
+    value = (value as Record<string, unknown>)[part];
+  }
+
+  return value ?? '';
+}
+
 /**
- * Reads a nested property using dot notation.
+ * Reads a nested property using dot notation and returns a display string.
  */
 export function getNestedToggleValue(obj: unknown, path: string): string {
-  if (!obj || typeof obj !== 'object') {
-    return '';
+  const value = getNestedToggleRawValue(obj, path);
+  return value == null || value === '' ? '' : String(value);
+}
+
+/**
+ * Resolves the options array from `response.data`.
+ *
+ * Use `dataPath` with dot notation for nested shapes, e.g.:
+ * - `users` → `data.users`
+ * - `typeAccess.options` → `data.typeAccess.options`
+ *
+ * When `dataPath` / `responseKey` are omitted, falls back to legacy behavior:
+ * `data[firstEndpointSegment]` if it is an array (e.g. endpoint `role/list` → `data.role`).
+ */
+export function extractToggleOptionsFromResponse(
+  responseData: Record<string, unknown> | undefined | null,
+  endpoint = '',
+  responseKey?: string,
+  dataPath?: string,
+): unknown[] {
+  if (!responseData || typeof responseData !== 'object') {
+    return [];
   }
 
-  const value = path.split('.').reduce<unknown>((acc, part) => {
-    if (acc && typeof acc === 'object' && part in (acc as Record<string, unknown>)) {
-      return (acc as Record<string, unknown>)[part];
+  const explicitPath = dataPath?.trim() || responseKey?.trim() || '';
+
+  if (explicitPath) {
+    const node = getNestedToggleRawValue(responseData, explicitPath);
+    return Array.isArray(node) ? node : [];
+  }
+
+  const legacyKey = endpoint.split('/').filter(Boolean)[0];
+  if (legacyKey) {
+    const legacyNode = responseData[legacyKey];
+    if (Array.isArray(legacyNode)) {
+      return legacyNode;
+    }
+  }
+
+  return Array.isArray(responseData) ? (responseData as unknown[]) : [];
+}
+
+/** Builds the display label from a template like `Acceso {label} (id {value})`. */
+export function resolveToggleOptionLabelFromTemplate(
+  option: Record<string, unknown>,
+  template: string,
+): string {
+  return template.replace(/\{([^}]+)\}/g, (_, path: string) => {
+    const value = getNestedToggleRawValue(option, path.trim());
+    if (value == null || value === '') {
+      return '';
     }
-    return undefined;
-  }, obj);
 
-  return value == null ? '' : String(value);
+    return String(value);
+  });
+}
+
+/** Builds the display label for one option object. */
+export function resolveToggleOptionLabel(
+  option: Record<string, unknown>,
+  optionLabel: string | string[],
+  labelSeparator: string,
+  optionLabelTemplate?: string,
+): string {
+  if (optionLabelTemplate?.trim()) {
+    return resolveToggleOptionLabelFromTemplate(option, optionLabelTemplate);
+  }
+
+  if (Array.isArray(optionLabel)) {
+    return optionLabel
+      .map((key) => getNestedToggleValue(option, key))
+      .filter(Boolean)
+      .join(labelSeparator);
+  }
+
+  return getNestedToggleValue(option, optionLabel);
 }
 
 /**
@@ -41,18 +124,34 @@ export function getNestedToggleValue(obj: unknown, path: string): string {
  */
 export function normalizeToggleOptions(
   options: unknown[],
-  optionLabel: string,
+  optionLabel: string | string[],
   optionValue: string,
+  labelSeparator = ' ',
+  optionLabelTemplate?: string,
+  optionLabelFn?: (option: Record<string, unknown>) => string,
 ): ToggleOption[] {
   if (!options.length) {
     return [];
   }
 
   if (typeof options[0] === 'object' && options[0] !== null) {
-    return options.map((opt) => ({
-      value: (opt as Record<string, unknown>)[optionValue],
-      label: getNestedToggleValue(opt, optionLabel),
-    }));
+    return options.map((opt) => {
+      const record = opt as Record<string, unknown>;
+      const label = optionLabelFn
+        ? optionLabelFn(record)
+        : resolveToggleOptionLabel(
+            record,
+            optionLabel,
+            labelSeparator,
+            optionLabelTemplate,
+          );
+
+      return {
+        value: getNestedToggleRawValue(record, optionValue),
+        label,
+        original: record,
+      };
+    });
   }
 
   return options.map((opt) => ({

package/src/lib/components/toggle-radio/toggle-radio/toggle-radio.component.ts

@@ -14,7 +14,11 @@ import { ControlValueAccessor, NG_VALUE_ACCESSOR } from '@angular/forms';
 import { JGenericCrudService } from 'tailjng';
 import { Icons } from '../../.config/icons/icons.lucide';
 import { JIconComponent } from '../../icon/icon.component';
-import { normalizeToggleOptions, buildToggleLoadParams } from '../shared/toggle-options.util';
+import {
+  buildToggleLoadParams,
+  extractToggleOptionsFromResponse,
+  normalizeToggleOptions,
+} from '../shared/toggle-options.util';
 import { ToggleOption, ToggleRadioLayout, ToggleSortOrder } from '../shared/toggle-options.types';
 
 export type { ToggleOption, ToggleRadioLayout, ToggleSortOrder } from './toggle-radio.types';
@@ -25,6 +29,18 @@ let radioGroupCounter = 0;
  * Classic radio group with circular indicators and labels.
  *
  * Install: `npx tailjng add toggle-radio`
+ *
+ * ```html
+ * <JToggleRadio
+ *   endpoint="enum/typeAccess"
+ *   dataPath="typeAccess.options"
+ *   optionLabel="label"
+ *   optionValue="value"
+ *   optionLabelTemplate="Acceso {label} (id {value})"
+ *   [loadOnInit]="true"
+ *   [(ngModel)]="selected"
+ * />
+ * ```
  */
 @Component({
   selector: 'JToggleRadio',
@@ -45,8 +61,32 @@ export class JToggleRadioComponent implements OnInit, OnChanges, ControlValueAcc
   @Input() name = `j-toggle-radio-${++radioGroupCounter}`;
   @Input() endpoint = '';
   @Input() options: unknown[] = [];
-  @Input() optionLabel = 'label';
+  @Input() optionLabel: string | string[] = 'label';
   @Input() optionValue = 'value';
+
+  /** Separator when `optionLabel` is an array of keys. */
+  @Input() labelSeparator = ' ';
+
+  /**
+   * Custom label template per option. Use `{field}` placeholders with dot paths.
+   * Example: `Acceso {label} (id {value})`.
+   */
+  @Input() optionLabelTemplate = '';
+
+  /**
+   * Optional formatter for full control over the displayed label.
+   * Takes precedence over `optionLabelTemplate` when provided.
+   */
+  @Input() optionLabelFn?: (option: Record<string, unknown>) => string;
+
+  /** @deprecated Alias of `dataPath` for a single top-level key in `response.data`. */
+  @Input() responseKey = '';
+
+  /**
+   * Dot path from `response.data` to the options array.
+   * Examples: `users`, `typeAccess.options`, `catalog.items`.
+   */
+  @Input() dataPath = '';
   @Input() sort: ToggleSortOrder = 'ASC';
   @Input() defaultFilters: Record<string, unknown> = {};
   @Input() loadOnInit = false;
@@ -99,7 +139,16 @@ export class JToggleRadioComponent implements OnInit, OnChanges, ControlValueAcc
   }
 
   ngOnChanges(changes: SimpleChanges): void {
-    if (changes['options'] && !this.endpoint) {
+    const optionInputs = [
+      'options',
+      'optionLabel',
+      'optionValue',
+      'labelSeparator',
+      'optionLabelTemplate',
+      'optionLabelFn',
+    ];
+
+    if (optionInputs.some((key) => changes[key]) && !this.endpoint) {
       this.processOptions();
     }
   }
@@ -119,7 +168,12 @@ export class JToggleRadioComponent implements OnInit, OnChanges, ControlValueAcc
 
     this.genericService.findAll<unknown>({ endpoint: this.endpoint, params }).subscribe({
       next: (res) => {
-        const data = (res.data as Record<string, unknown[]>)[this.endpoint] ?? [];
+        const data = extractToggleOptionsFromResponse(
+          res.data as Record<string, unknown>,
+          this.endpoint,
+          this.responseKey || undefined,
+          this.dataPath || undefined,
+        );
         this.options = data;
         this.processOptions();
         this.isLoading = false;
@@ -135,7 +189,14 @@ export class JToggleRadioComponent implements OnInit, OnChanges, ControlValueAcc
   }
 
   processOptions(): void {
-    this.internalOptions = normalizeToggleOptions(this.options, this.optionLabel, this.optionValue);
+    this.internalOptions = normalizeToggleOptions(
+      this.options,
+      this.optionLabel,
+      this.optionValue,
+      this.labelSeparator,
+      this.optionLabelFn ? undefined : this.optionLabelTemplate || undefined,
+      this.optionLabelFn,
+    );
   }
 
   select(value: unknown): void {

package/src/lib/components/toggle-radio/toggle-segment/segment-toggle.component.ts

@@ -14,7 +14,11 @@ import { ControlValueAccessor, NG_VALUE_ACCESSOR } from '@angular/forms';
 import { JGenericCrudService } from 'tailjng';
 import { Icons } from '../../.config/icons/icons.lucide';
 import { JIconComponent } from '../../icon/icon.component';
-import { normalizeToggleOptions, buildToggleLoadParams } from '../shared/toggle-options.util';
+import {
+  buildToggleLoadParams,
+  extractToggleOptionsFromResponse,
+  normalizeToggleOptions,
+} from '../shared/toggle-options.util';
 import { ToggleOption, ToggleSortOrder } from '../shared/toggle-options.types';
 
 export type { ToggleOption, ToggleSortOrder } from './segment-toggle.types';
@@ -23,6 +27,18 @@ export type { ToggleOption, ToggleSortOrder } from './segment-toggle.types';
  * Segmented single-select control (pill/tab style).
  *
  * Install: `npx tailjng add toggle-segment`
+ *
+ * ```html
+ * <JToggleSegment
+ *   endpoint="enum/typeAccess"
+ *   dataPath="typeAccess.options"
+ *   optionLabel="label"
+ *   optionValue="value"
+ *   optionLabelTemplate="Acceso {label} (id {value})"
+ *   [loadOnInit]="true"
+ *   [(ngModel)]="selected"
+ * />
+ * ```
  */
 @Component({
   selector: 'JToggleSegment',
@@ -42,8 +58,32 @@ export class JToggleSegmentComponent implements OnInit, OnChanges, ControlValueA
 
   @Input() endpoint = '';
   @Input() options: unknown[] = [];
-  @Input() optionLabel = 'label';
+  @Input() optionLabel: string | string[] = 'label';
   @Input() optionValue = 'value';
+
+  /** Separator when `optionLabel` is an array of keys. */
+  @Input() labelSeparator = ' ';
+
+  /**
+   * Custom label template per option. Use `{field}` placeholders with dot paths.
+   * Example: `Acceso {label} (id {value})`.
+   */
+  @Input() optionLabelTemplate = '';
+
+  /**
+   * Optional formatter for full control over the displayed label.
+   * Takes precedence over `optionLabelTemplate` when provided.
+   */
+  @Input() optionLabelFn?: (option: Record<string, unknown>) => string;
+
+  /** @deprecated Alias of `dataPath` for a single top-level key in `response.data`. */
+  @Input() responseKey = '';
+
+  /**
+   * Dot path from `response.data` to the options array.
+   * Examples: `users`, `typeAccess.options`, `catalog.items`.
+   */
+  @Input() dataPath = '';
   @Input() sort: ToggleSortOrder = 'ASC';
   @Input() defaultFilters: Record<string, unknown> = {};
   @Input() loadOnInit = false;
@@ -95,7 +135,16 @@ export class JToggleSegmentComponent implements OnInit, OnChanges, ControlValueA
   }
 
   ngOnChanges(changes: SimpleChanges): void {
-    if (changes['options'] && !this.endpoint) {
+    const optionInputs = [
+      'options',
+      'optionLabel',
+      'optionValue',
+      'labelSeparator',
+      'optionLabelTemplate',
+      'optionLabelFn',
+    ];
+
+    if (optionInputs.some((key) => changes[key]) && !this.endpoint) {
       this.processOptions();
     }
   }
@@ -115,7 +164,12 @@ export class JToggleSegmentComponent implements OnInit, OnChanges, ControlValueA
 
     this.genericService.findAll<unknown>({ endpoint: this.endpoint, params }).subscribe({
       next: (res) => {
-        const data = (res.data as Record<string, unknown[]>)[this.endpoint] ?? [];
+        const data = extractToggleOptionsFromResponse(
+          res.data as Record<string, unknown>,
+          this.endpoint,
+          this.responseKey || undefined,
+          this.dataPath || undefined,
+        );
         this.options = data;
         this.processOptions();
         this.isLoading = false;
@@ -131,7 +185,14 @@ export class JToggleSegmentComponent implements OnInit, OnChanges, ControlValueA
   }
 
   processOptions(): void {
-    this.internalOptions = normalizeToggleOptions(this.options, this.optionLabel, this.optionValue);
+    this.internalOptions = normalizeToggleOptions(
+      this.options,
+      this.optionLabel,
+      this.optionValue,
+      this.labelSeparator,
+      this.optionLabelFn ? undefined : this.optionLabelTemplate || undefined,
+      this.optionLabelFn,
+    );
   }
 
   select(value: unknown): void {