tailjng 0.1.12 → 0.1.14

package/cli/component-manager.js

@@ -1,6 +1,6 @@
 // component-manager.js
 
-const { copyComponentFiles } = require("./file-operations");
+const { copyComponentFiles, resetInstalledSharedFolders } = require("./file-operations");
 const { installDependencies } = require("./dependency-manager");
 const { COLORS } = require("./settings/colors");
 const { collectDependencyTree } = require("./settings/lib-utils");
@@ -50,6 +50,7 @@ function logInstallPlan(componentName, componentList) {
 
 async function addComponent(componentName, componentList) {
   resetOverwritePolicy();
+  resetInstalledSharedFolders();
   installedComponentsGlobal.clear();
 
   const componentData = componentList[componentName];
@@ -96,6 +97,7 @@ async function addComponent(componentName, componentList) {
 
 async function installAllComponents(componentList) {
   resetOverwritePolicy();
+  resetInstalledSharedFolders();
   installedComponentsGlobal.clear();
 
   const allNames = Object.keys(componentList);

package/cli/file-operations.js

@@ -5,14 +5,29 @@ const path = require("path")
 const { COLORS } = require("./settings/colors")
 const { generateHeaderComment } = require("./settings/header-generator")
 const { askOverwrite } = require("./settings/prompt-utils")
-const { buildTargetPath, parseComponentPath } = require("./settings/path-utils")
+const { getPackageRoot } = require("./settings/lib-utils")
+const {
+    buildTargetPath,
+    buildSharedFolderTargetPath,
+    getSharedFolderInfo,
+    parseComponentPath,
+} = require("./settings/path-utils")
+
+/** Avoid copying the same group `shared/` folder twice per install session. */
+const installedSharedFolders = new Set()
 
 const TEXT_EXTENSIONS = new Set([".ts", ".js", ".html", ".css", ".scss", ".json", ".md"])
+const LIB_PACKAGE_IMPORT_RE =
+    /from\s+['"](?:\.\.\/)+(?:interfaces|services|config)\/[^'"]+['"]/g
 
 function shouldAddHeader(fileName) {
     return TEXT_EXTENSIONS.has(path.extname(fileName).toLowerCase())
 }
 
+function patchConsumerImports(content) {
+    return content.replace(LIB_PACKAGE_IMPORT_RE, "from 'tailjng'")
+}
+
 function copyFileWithHeader(srcFile, destFile) {
     fs.mkdirSync(path.dirname(destFile), { recursive: true })
 
@@ -22,6 +37,9 @@ function copyFileWithHeader(srcFile, destFile) {
     }
 
     let content = fs.readFileSync(srcFile, "utf8")
+    if (path.extname(srcFile).toLowerCase() === ".ts") {
+        content = patchConsumerImports(content)
+    }
     const headerComment = generateHeaderComment(path.basename(srcFile))
     content = headerComment + "\n\n" + content
     fs.writeFileSync(destFile, content)
@@ -49,7 +67,11 @@ function copyDirectoryRecursive(srcDir, destDir, projectRoot) {
     }
 }
 
-async function copyComponentFiles(componentName, componentPath, isDependency = false) {
+function resetInstalledSharedFolders() {
+    installedSharedFolders.clear()
+}
+
+function findTailjngPackageRoot() {
     let currentDir = process.cwd()
     while (!fs.existsSync(path.join(currentDir, "node_modules"))) {
         currentDir = path.dirname(currentDir)
@@ -59,7 +81,74 @@ async function copyComponentFiles(componentName, componentPath, isDependency = f
         }
     }
 
-    const nodeModulesPath = path.join(currentDir, "node_modules", "tailjng", componentPath)
+    return getPackageRoot(path.join(currentDir, "node_modules", "tailjng", "cli"))
+}
+
+async function copySharedFolderIfNeeded(componentPath, isDependency = false, options = {}) {
+    const { forceSync = false } = options
+    const sharedInfo = getSharedFolderInfo(componentPath)
+    if (!sharedInfo) {
+        return true
+    }
+
+    if (installedSharedFolders.has(sharedInfo.groupKey)) {
+        return true
+    }
+
+    const packageRoot = findTailjngPackageRoot()
+    const sharedSrc = path.join(packageRoot, ...sharedInfo.sourceRelative.split("/"))
+    if (!fs.existsSync(sharedSrc)) {
+        console.error(
+            `${COLORS.red}${COLORS.bright}[tailjng CLI]${COLORS.reset} ${COLORS.red}ERROR: Shared utilities ${COLORS.bright}"${sharedInfo.groupKey}/shared"${COLORS.reset} ${COLORS.red}not found in package.${COLORS.reset}`,
+        )
+        console.error(`${COLORS.dim}   Expected: ${sharedSrc}${COLORS.reset}`)
+        return false
+    }
+
+    const projectRoot = process.cwd()
+    const sharedDest = buildSharedFolderTargetPath(projectRoot, componentPath)
+    if (!sharedDest) {
+        return true
+    }
+
+    const sharedLabel = `${sharedInfo.groupKey}/shared`
+    const relativeTargetPath = path.relative(projectRoot, sharedDest)
+    const sharedMissing = !fs.existsSync(sharedDest)
+
+    if (!forceSync && !sharedMissing) {
+        const shouldOverwrite = await askOverwrite(sharedLabel, relativeTargetPath, isDependency)
+        if (!shouldOverwrite) {
+            console.log(
+                `${COLORS.dim}${COLORS.bright}[tailjng CLI]${COLORS.reset} ${COLORS.dim}Skipping ${COLORS.bright}"${sharedLabel}"${COLORS.reset} ${COLORS.dim}- keeping existing version.${COLORS.reset}`,
+            )
+            return true
+        }
+
+        console.log(
+            `${COLORS.yellow}${COLORS.bright}[tailjng CLI]${COLORS.reset} ${COLORS.yellow}Removing existing ${COLORS.bright}"${sharedLabel}"${COLORS.reset} ${COLORS.yellow}to overwrite...${COLORS.reset}`,
+        )
+        fs.rmSync(sharedDest, { recursive: true, force: true })
+    } else if (!sharedMissing) {
+        console.log(
+            `${COLORS.yellow}${COLORS.bright}[tailjng CLI]${COLORS.reset} ${COLORS.yellow}Updating shared utilities ${COLORS.bright}"${sharedLabel}"${COLORS.reset} ${COLORS.yellow}with the installed component...${COLORS.reset}`,
+        )
+        fs.rmSync(sharedDest, { recursive: true, force: true })
+    }
+
+    console.log(
+        `${COLORS.blue}${COLORS.bright}[tailjng CLI]${COLORS.reset} ${COLORS.blue}Copying shared utilities ${COLORS.bright}"${sharedLabel}"${COLORS.reset} → ${relativeTargetPath}${COLORS.reset}`,
+    )
+
+    fs.mkdirSync(sharedDest, { recursive: true })
+    copyDirectoryRecursive(sharedSrc, sharedDest, projectRoot)
+    installedSharedFolders.add(sharedInfo.groupKey)
+
+    return true
+}
+
+async function copyComponentFiles(componentName, componentPath, isDependency = false) {
+    const packageRoot = findTailjngPackageRoot()
+    const nodeModulesPath = path.join(packageRoot, ...componentPath.split("/"))
     const projectRoot = process.cwd()
     const targetPath = buildTargetPath(projectRoot, componentName, componentPath)
     const pathInfo = parseComponentPath(componentPath)
@@ -77,6 +166,7 @@ async function copyComponentFiles(componentName, componentPath, isDependency = f
 
         if (!shouldOverwrite) {
             console.log(`${COLORS.dim}${COLORS.bright}[tailjng CLI]${COLORS.reset} ${COLORS.dim}Skipping ${COLORS.bright}"${componentName}"${COLORS.reset} ${COLORS.dim}- keeping existing version.${COLORS.reset}`)
+            await copySharedFolderIfNeeded(componentPath, isDependency, { forceSync: false })
             return false
         }
 
@@ -99,8 +189,9 @@ async function copyComponentFiles(componentName, componentPath, isDependency = f
 
     fs.mkdirSync(targetPath, { recursive: true })
     copyDirectoryRecursive(nodeModulesPath, targetPath, projectRoot)
+    await copySharedFolderIfNeeded(componentPath, isDependency, { forceSync: true })
 
     return true
 }
 
-module.exports = { copyComponentFiles }
+module.exports = { copyComponentFiles, resetInstalledSharedFolders }

package/cli/settings/path-utils.js

@@ -58,9 +58,44 @@ function isComponentInstalled(projectRoot, componentName, componentPath) {
     return fs.existsSync(buildTargetPath(projectRoot, componentName, componentPath))
 }
 
+/**
+ * When a registry path is nested (e.g. toggle-radio/toggle-radio), returns sibling `shared/` info.
+ * Used by the CLI to copy group-level utilities alongside the component folder.
+ */
+function getSharedFolderInfo(componentPath) {
+    if (!componentPath.startsWith(COMPONENTS_SOURCE_PREFIX)) {
+        return null
+    }
+
+    const relativePath = componentPath.slice(COMPONENTS_SOURCE_PREFIX.length)
+    const pathParts = relativePath.split("/")
+    if (pathParts.length < 2) {
+        return null
+    }
+
+    const groupKey = pathParts.slice(0, -1).join("/")
+
+    return {
+        groupKey,
+        sourceRelative: `${COMPONENTS_SOURCE_PREFIX}${groupKey}/shared`,
+        targetRelative: `${groupKey}/shared`,
+    }
+}
+
+function buildSharedFolderTargetPath(projectRoot, componentPath) {
+    const sharedInfo = getSharedFolderInfo(componentPath)
+    if (!sharedInfo) {
+        return null
+    }
+
+    return path.join(getComponentsBasePath(projectRoot), sharedInfo.targetRelative)
+}
+
 module.exports = {
     parseComponentPath,
     buildTargetPath,
+    buildSharedFolderTargetPath,
+    getSharedFolderInfo,
     isComponentInstalled,
     isConfigPath,
     CONFIG_SOURCE_PREFIX,

package/package.json

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

package/src/lib/components/filter/filter-complete/complete-filter.component.html

@@ -139,68 +139,64 @@
       <div class="flex flex-col gap-2">
         @for (filter of filtersSelect; track $index) {
           @if (filter.isVisible ?? true) {
-            @switch (filter.type) {
-              @case ("dropdown") {
-                <div class="relative">
-                  <JDropdownSelect
-                    [type]="'dropdown'"
-                    [(ngModel)]="filter.selected"
-                    (selectionChange)="
-                      filter.onSelected ? filter.onSelected($event) : null
-                    "
-                    [optionLabel]="filter.optionLabel ?? ''"
-                    [optionValue]="filter.optionValue ?? ''"
-                    [labelSeparator]="filter.labelSeparator ?? ''"
-                    [optionLabelTemplate]="filter.optionLabelTemplate ?? ''"
-                    [optionLabelFn]="filter.optionLabelFn"
-                    [placeholder]="filter.placeholder ?? ''"
-                    [showClear]="filter.showClear ?? false"
-                    [options]="filter.options"
-                    [sort]="filter.sort ?? 'ASC'"
-                    [showAllOption]="filter.showAllOption ?? false"
-                    [isFilterSelect]="true"
-                  />
-                </div>
-              }
-              @case ("searchable") {
-                <div class="relative">
-                  <JDropdownSelect
-                    [type]="'searchable'"
-                    [(ngModel)]="filter.selected"
-                    (selectionChange)="filter.onSelected?.($event)"
-                    [endpoint]="filter.endpoint"
-                    [optionLabel]="filter.optionLabel"
-                    [optionValue]="filter.optionValue"
-                    [labelSeparator]="filter.labelSeparator ?? ''"
-                    [optionLabelTemplate]="filter.optionLabelTemplate ?? ''"
-                    [optionLabelFn]="filter.optionLabelFn"
-                    [responseKey]="filter.responseKey ?? ''"
-                    [dataPath]="filter.dataPath ?? ''"
-                    [placeholder]="filter.placeholder ?? ''"
-                    [showClear]="filter.showClear ?? false"
-                    [loadOnInit]="filter.loadOnInit ?? false"
-                    [isSearch]="filter.isSearch ?? true"
-                    [searchFields]="filter.searchFields || []"
-                    [defaultFilters]="filter.defaultFilters || {}"
-                    [sort]="filter.sort ?? 'ASC'"
-                    [showAllOption]="filter.showAllOption ?? false"
-                    [isFilterSelect]="true"
-                  />
-                </div>
-              }
-              @case ("multi-table") {
-                <div class="relative">
-                  <JMultiTableSelect
-                    [(ngModel)]="filter.selected"
-                    (selectionChange)="
-                      filter.onSelected ? filter.onSelected($event) : null
-                    "
-                    [columns]="filter.columns"
-                    [btnText]="filter.btnText ?? ''"
-                    [isFilterSelect]="true"
-                  />
-                </div>
-              }
+            @if (isDropdownFilter(filter)) {
+              <div class="relative">
+                <JDropdownSelect
+                  [type]="'dropdown'"
+                  [(ngModel)]="filter.selected"
+                  (selectionChange)="
+                    filter.onSelected ? filter.onSelected($event) : null
+                  "
+                  [optionLabel]="filter.optionLabel ?? ''"
+                  [optionValue]="filter.optionValue ?? ''"
+                  [labelSeparator]="filter.labelSeparator ?? ''"
+                  [optionLabelTemplate]="filter.optionLabelTemplate ?? ''"
+                  [optionLabelFn]="filter.optionLabelFn"
+                  [placeholder]="filter.placeholder ?? ''"
+                  [showClear]="filter.showClear ?? false"
+                  [options]="filter.options"
+                  [sort]="filter.sort ?? 'ASC'"
+                  [showAllOption]="filter.showAllOption ?? false"
+                  [isFilterSelect]="true"
+                />
+              </div>
+            } @else if (isSearchableFilter(filter)) {
+              <div class="relative">
+                <JDropdownSelect
+                  [type]="'searchable'"
+                  [(ngModel)]="filter.selected"
+                  (selectionChange)="filter.onSelected?.($event)"
+                  [endpoint]="filter.endpoint"
+                  [optionLabel]="filter.optionLabel"
+                  [optionValue]="filter.optionValue"
+                  [labelSeparator]="filter.labelSeparator ?? ''"
+                  [optionLabelTemplate]="filter.optionLabelTemplate ?? ''"
+                  [optionLabelFn]="filter.optionLabelFn"
+                  [responseKey]="filter.responseKey ?? ''"
+                  [dataPath]="filter.dataPath ?? ''"
+                  [placeholder]="filter.placeholder ?? ''"
+                  [showClear]="filter.showClear ?? false"
+                  [loadOnInit]="filter.loadOnInit ?? false"
+                  [isSearch]="filter.isSearch ?? true"
+                  [searchFields]="filter.searchFields || []"
+                  [defaultFilters]="filter.defaultFilters || {}"
+                  [sort]="filter.sort ?? 'ASC'"
+                  [showAllOption]="filter.showAllOption ?? false"
+                  [isFilterSelect]="true"
+                />
+              </div>
+            } @else if (isMultiTableFilter(filter)) {
+              <div class="relative">
+                <JMultiTableSelect
+                  [(ngModel)]="filter.selected"
+                  (selectionChange)="
+                    filter.onSelected ? filter.onSelected($event) : null
+                  "
+                  [columns]="filter.columns"
+                  [btnText]="filter.btnText ?? ''"
+                  [isFilterSelect]="true"
+                />
+              </div>
             }
           }
         }

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

@@ -3,20 +3,27 @@ import { NgClass } from '@angular/common';
 import { FormsModule } from '@angular/forms';
 import { Subject, Subscription, debounceTime, filter, forkJoin } from 'rxjs';
 import { TableColumn, FilterButton, JUploadFilterService, JAlertDialogService, JAlertToastService, JGenericCrudService, LoadingState, JExcelService, JExcelFilterService } from 'tailjng';
-import type { FilterSelect } from '../../../interfaces/crud/filter.interface';
+import type {
+  CompleteFilterAdditionalButtonLoading,
+  CompleteFilterDropdownSelect,
+  CompleteFilterMultiTableSelect,
+  CompleteFilterSearchableSelect,
+  CompleteFilterSelect,
+} from './complete-filter.types';
 import { JDropdownSelectComponent } from '../../select/select-dropdown/dropdown-select.component';
 import { JMultiTableSelectComponent } from '../../select/select-multi-table/multi-table-select.component';
 import { JSwitchCheckboxComponent } from '../../checkbox/checkbox-switch/switch-checkbox.component';
 import { JDialogComponent } from '../../dialog/dialog.component';
 import { JButtonComponent } from '../../button/button.component';
-import type { CompleteFilterAdditionalButtonLoading } from './complete-filter.types';
 import { hasActiveFilters } from './complete-filter.util';
 import { Icons } from '../../.config/icons/icons.lucide';
 import { JIconComponent } from '../../icon/icon.component';
 
 export type {
   CompleteFilterAdditionalButtonLoading,
-  CompleteFilterClearReason} from './complete-filter.types';
+  CompleteFilterClearReason,
+  CompleteFilterSelect,
+} from './complete-filter.types';
 export { hasActiveFilters } from './complete-filter.util';
 
 /**
@@ -111,7 +118,19 @@ export class JCompleteFilterComponent implements OnInit, OnDestroy {
   @Input() filtersButton: FilterButton[] = [];
 
   // Filtros de tabla
-  @Input() filtersSelect: FilterSelect[] = [];
+  @Input() filtersSelect: CompleteFilterSelect[] = [];
+
+  isDropdownFilter(filter: CompleteFilterSelect): filter is CompleteFilterDropdownSelect {
+    return filter.type === 'dropdown';
+  }
+
+  isSearchableFilter(filter: CompleteFilterSelect): filter is CompleteFilterSearchableSelect {
+    return filter.type === 'searchable';
+  }
+
+  isMultiTableFilter(filter: CompleteFilterSelect): filter is CompleteFilterMultiTableSelect {
+    return filter.type === 'multi-table';
+  }
 
   get visibleColumns(): TableColumn<any>[] {
     return this.columns.filter(col => !col.hidden);

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

@@ -1,4 +1,71 @@
-import type { LoadingState } from 'tailjng';
+import type { LoadingState, TableColumn } from 'tailjng';
+
+/**
+ * Filter-select shapes for JFilter templates.
+ * Prefixed with `CompleteFilter*` to avoid clashing with `tailjng` exports during strict template narrowing.
+ */
+export interface CompleteFilterDropdownSelect {
+  type: 'dropdown';
+  selected: unknown;
+  initSelected?: unknown;
+  onSelected?: (value: unknown) => void;
+  optionLabel?: string | string[];
+  optionValue?: string;
+  labelSeparator?: string;
+  optionLabelTemplate?: string;
+  optionLabelFn?: (option: Record<string, unknown>) => string;
+  placeholder?: string;
+  showClear?: boolean;
+  options: unknown[];
+  deep?: string;
+  sort?: 'ASC' | 'DESC';
+  isVisible?: ((data?: unknown) => boolean) | boolean;
+  showAllOption?: boolean;
+}
+
+export interface CompleteFilterSearchableSelect {
+  type: 'searchable';
+  selected: unknown;
+  initSelected?: unknown;
+  onSelected?: (value: unknown) => void;
+  endpoint: string;
+  isSearch?: boolean;
+  optionLabel: string | string[];
+  optionValue: string;
+  labelSeparator?: string;
+  optionLabelTemplate?: string;
+  optionLabelFn?: (option: Record<string, unknown>) => string;
+  responseKey?: string;
+  dataPath?: string;
+  placeholder?: string;
+  showClear?: boolean;
+  loadOnInit?: boolean;
+  searchFields?: string[];
+  defaultFilters?: Record<string, unknown>;
+  deep?: string;
+  sort?: 'ASC' | 'DESC';
+  isVisible?: ((data?: unknown) => boolean) | boolean;
+  showAllOption?: boolean;
+}
+
+export interface CompleteFilterMultiTableSelect {
+  type: 'multi-table';
+  selected: unknown;
+  initSelected?: unknown;
+  onSelected?: (value: unknown) => void;
+  columns: TableColumn<unknown>[];
+  btnText?: string;
+  placeholder?: string;
+  deep?: string;
+  sort?: 'ASC' | 'DESC';
+  isVisible?: ((data?: unknown) => boolean) | boolean;
+  showAllOption?: boolean;
+}
+
+export type CompleteFilterSelect =
+  | CompleteFilterDropdownSelect
+  | CompleteFilterSearchableSelect
+  | CompleteFilterMultiTableSelect;
 
 /** Event payload from `(clearFilters)` — typically `'clear'`. */
 export type CompleteFilterClearReason = string;

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

@@ -1,16 +1,16 @@
-import type { FilterSelect } from 'tailjng';
-
-/** Whether search text or any filter select differs from its initial value. */
-export function hasActiveFilters(
-  searchQuery: string,
-  filtersSelect: FilterSelect[],
-): boolean {
-  const hasActiveSearch = searchQuery?.trim().length > 0;
-  const hasSelectedFilters = filtersSelect.some((filter) => {
-    const actual = filter.selected;
-    const initial = filter.initSelected ?? null;
-    return JSON.stringify(actual) !== JSON.stringify(initial);
-  });
-
-  return hasActiveSearch || hasSelectedFilters;
-}
+import type { CompleteFilterSelect } from './complete-filter.types';
+
+/** Whether search text or any filter select differs from its initial value. */
+export function hasActiveFilters(
+  searchQuery: string,
+  filtersSelect: CompleteFilterSelect[],
+): boolean {
+  const hasActiveSearch = searchQuery?.trim().length > 0;
+  const hasSelectedFilters = filtersSelect.some((filter) => {
+    const actual = filter.selected;
+    const initial = filter.initSelected ?? null;
+    return JSON.stringify(actual) !== JSON.stringify(initial);
+  });
+
+  return hasActiveSearch || hasSelectedFilters;
+}

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 {