forlogic-core 2.1.5 → 2.2.0

package/dist/components/ui/viewer-dialog.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Tipos de viewer suportados pelo `ViewerDialog`. Resolvido automaticamente
+ * pela extensão do arquivo via `getViewerType`.
+ *
+ * @example
+ * ```tsx
+ * if (type === FileViewerType.image) { ... }
+ * ```
+ */
 export declare enum FileViewerType {
     none = 0,
     image = 1,
@@ -7,17 +16,42 @@ export declare enum FileViewerType {
     onlineEditor = 5,
     report = 6
 }
+/**
+ * Modo de impressão para documentos controlados (cópia gerenciada / não gerenciada).
+ *
+ * @example
+ * ```tsx
+ * config.printType = FilePrintType.ManagedCopy;
+ * ```
+ */
 export declare enum FilePrintType {
     SimplePrint = 0,
     ManagedCopy = 1,
     NonManagedCopy = 2
 }
+/**
+ * Descritor de um arquivo a ser visualizado pelo `ViewerDialog`.
+ *
+ * @example
+ * ```tsx
+ * const tpl: FileViewerTemplate = { name: 'manual.pdf', extension: '.pdf', url: '/files/123' };
+ * ```
+ */
 export interface FileViewerTemplate {
     code?: string;
     name: string;
     extension?: string;
     url: string;
 }
+/**
+ * Configuração para visualização de documentos controlados (Qualiex).
+ * Reúne callbacks para criação de cópia física e marca d'água.
+ *
+ * @example
+ * ```tsx
+ * const cfg: ViewerDocumentControlConfig = { isControlledDocument: true, physicalCopyCode: 'C-001' };
+ * ```
+ */
 export interface ViewerDocumentControlConfig {
     isControlledDocument?: boolean;
     physicalCopyCode?: string | null;
@@ -32,6 +66,15 @@ export interface ViewerDocumentControlConfig {
         isDownload?: boolean;
     }) => Promise<any>;
 }
+/**
+ * Props do `ViewerDialog`. Suporta imagem, vídeo, áudio, PDF/Office (WOPI),
+ * editor online (Google Docs) e relatórios (iframe genérico).
+ *
+ * @example
+ * ```tsx
+ * const props: ViewerDialogProps = { open, onOpenChange, template };
+ * ```
+ */
 export interface ViewerDialogProps {
     open: boolean;
     onOpenChange: (open: boolean) => void;
@@ -62,9 +105,51 @@ export interface ViewerDialogProps {
     /** Custom className for the dialog */
     className?: string;
 }
+/**
+ * Resolve o `FileViewerType` a partir da extensão do arquivo (case-insensitive).
+ * Retorna `FileViewerType.none` quando a extensão não é suportada.
+ *
+ * @example
+ * ```tsx
+ * getViewerType('.pdf'); // FileViewerType.wopi
+ * getViewerType('.png'); // FileViewerType.image
+ * ```
+ */
 export declare function getViewerType(extension?: string): FileViewerType;
+/**
+ * Resolve qual editor online (Google Docs vs Sheets) deve ser usado pela extensão.
+ *
+ * @example
+ * ```tsx
+ * getOnlineViewerType('.gsheets'); // 'spreadsheets'
+ * ```
+ */
 export declare function getOnlineViewerType(extension: string): 'document' | 'spreadsheets';
+/**
+ * Resolve a rota WOPI (Office Web Apps) para a extensão informada.
+ * Retorna string vazia quando não suportado.
+ *
+ * @example
+ * ```tsx
+ * getWopiViewer('.docx'); // 'wv/wordviewerframe.aspx?'
+ * ```
+ */
 export declare function getWopiViewer(extension: string): string;
+/**
+ * Constrói a URL completa do WOPI viewer com query params (`access_token`, `WOPISrc`, `ui`).
+ * Retorna `null` se a extensão não tiver viewer WOPI mapeado.
+ *
+ * @example
+ * ```tsx
+ * const url = buildWopiUrl({
+ *   viewerUrl: 'https://wopi.qualiex.com/',
+ *   wopiUrl: 'https://api.qualiex.com/wopi/files/',
+ *   fileId: '42',
+ *   token: 'abc',
+ *   extension: '.pdf',
+ * });
+ * ```
+ */
 export declare function buildWopiUrl(params: {
     viewerUrl: string;
     wopiUrl: string;
@@ -73,5 +158,27 @@ export declare function buildWopiUrl(params: {
     extension: string;
     language?: string;
 }): string | null;
+/**
+ * Dialog full-screen para visualizar arquivos de qualquer tipo. Detecta
+ * automaticamente o viewer apropriado pela extensão (`getViewerType`):
+ * imagem (`<img>`), vídeo (`<video>`), áudio (`<audio>`), PDF/Office (iframe WOPI),
+ * editor online (Google Docs/Sheets) ou relatório (iframe).
+ *
+ * Recursos do header: botão de download, favoritar e confirmação de leitura
+ * (com timer mínimo opcional). Fecha com **ESC** ou clique no X.
+ *
+ * @example
+ * ```tsx
+ * <ViewerDialog
+ *   open={open}
+ *   onOpenChange={setOpen}
+ *   template={{ name: 'Manual.pdf', extension: '.pdf', url: pdfUrl }}
+ *   enableDownload
+ *   onDownload={handleDownload}
+ * />
+ * ```
+ *
+ * @see `docs/design-system/dialogs.md`
+ */
 export declare function ViewerDialog({ open, onOpenChange, template, viewerType: viewerTypeProp, isLoading, enableDownload, onDownload, isDownloading, enableFavorite, isFavorite, onFavorite, isFavoriting, enableConfirmReading, readingConfirmationDate, onConfirmReading, isConfirmingReading, readingConfirmationTimeRemaining, onIframeLoad, className, }: ViewerDialogProps): import("react/jsx-runtime").JSX.Element;
 export default ViewerDialog;

package/dist/crud/components/ActionMenuItems.d.ts

@@ -13,5 +13,10 @@ interface ActionMenuItemsProps {
     }>;
     renderAs: 'dropdown' | 'context';
 }
+/**
+ * Componente `ActionMenuItems` da lib.
+ * @example
+ * <ActionMenuItems />
+ */
 export declare const ActionMenuItems: React.FC<ActionMenuItemsProps>;
 export {};

package/dist/crud/components/BaseForm.d.ts

@@ -1,4 +1,50 @@
 import type { BaseFormProps } from '../../types';
+/**
+ * Formulário modal genérico baseado em configuração declarativa de seções e campos.
+ *
+ * Renderiza um `Dialog` com navegação por seções (sidebar) quando há 2+ seções, ou um único
+ * painel para forms simples. Suporta os tipos: `text`, `number`, `select`, `multiselect`,
+ * `textarea`, `switch`, `checkbox`, `color`, `icon`, `qualiex-user` e custom render.
+ *
+ * Normalmente é renderizado automaticamente por `createCrudPage` — use diretamente apenas
+ * para forms standalone (fora do pipeline CRUD).
+ *
+ * @example
+ * const sections: FormSection[] = [
+ *   {
+ *     id: 'general',
+ *     title: 'Dados gerais',
+ *     fields: [
+ *       { key: 'title', label: 'Título', type: 'text', required: true },
+ *       { key: 'description', label: 'Descrição', type: 'textarea' },
+ *       {
+ *         key: 'status',
+ *         label: 'Status',
+ *         type: 'select',
+ *         options: [
+ *           { label: 'Ativo', value: 'active' },
+ *           { label: 'Pausado', value: 'paused' },
+ *         ],
+ *       },
+ *     ],
+ *   },
+ *   {
+ *     id: 'responsible',
+ *     title: 'Responsável',
+ *     fields: [{ key: 'id_user', label: 'Usuário', type: 'qualiex-user', required: true }],
+ *   },
+ * ];
+ *
+ * <BaseForm
+ *   open={isOpen}
+ *   title="Novo plano de ação"
+ *   sections={sections}
+ *   initialData={editing ?? undefined}
+ *   isLoading={manager.isCreating || manager.isUpdating}
+ *   onSubmit={(data) => onSave(data)}
+ *   onCancel={() => setIsOpen(false)}
+ * />
+ */
 declare function BaseForm<T extends Record<string, any>>({ title, sections, initialData, onSubmit, onCancel, open, submitButtonText, isLoading, usersData }: BaseFormProps<T> & {
     usersData?: any[];
     isLoading?: boolean;

package/dist/crud/components/ColumnSettingsPopover.d.ts

@@ -1,4 +1,9 @@
 import type { CrudColumn, BaseEntity } from '../../types';
+/**
+ * Tipo `ColumnSettingsPopoverProps` exportado pela lib.
+ * @example
+ * const value: ColumnSettingsPopoverProps = {} as ColumnSettingsPopoverProps;
+ */
 export interface ColumnSettingsPopoverProps<T> {
     columns: CrudColumn<T>[];
     columnOrder: string[];
@@ -15,4 +20,9 @@ export interface ColumnSettingsPopoverProps<T> {
     addGroupByColumn?: (key: string) => void;
     removeGroupByColumn?: (key: string) => void;
 }
+/**
+ * Função utilitária `ColumnSettingsPopover`.
+ * @example
+ * ColumnSettingsPopover();
+ */
 export declare function ColumnSettingsPopover<T extends BaseEntity>({ columns, columnOrder, isColumnHidden, toggleColumn, showAllColumns, reorderColumns, groupByColumn, setGroupByColumn, groupByColumns, addGroupByColumn, removeGroupByColumn, resetColumns, }: ColumnSettingsPopoverProps<T>): import("react/jsx-runtime").JSX.Element;

package/dist/crud/components/CrudActionBar.d.ts

@@ -1,5 +1,10 @@
 import React from 'react';
 import type { BaseEntity, BulkAction } from '../../types';
+/**
+ * Tipo `CustomAction` exportado pela lib.
+ * @example
+ * const value: CustomAction = {} as CustomAction;
+ */
 export interface CustomAction {
     label: string;
     icon?: React.ComponentType<{
@@ -11,7 +16,17 @@ export interface CustomAction {
     disabled?: boolean;
     disabledReason?: string;
 }
+/**
+ * Tipo `ViewMode` exportado pela lib.
+ * @example
+ * const value: ViewMode = {} as ViewMode;
+ */
 export type ViewMode = 'table' | 'list' | 'grid';
+/**
+ * Tipo `CrudActionBarProps` exportado pela lib.
+ * @example
+ * const value: CrudActionBarProps = {} as CrudActionBarProps;
+ */
 export interface CrudActionBarProps<T extends BaseEntity = BaseEntity> {
     onNew?: () => void;
     newButtonLabel?: string;
@@ -35,5 +50,10 @@ export interface CrudActionBarProps<T extends BaseEntity = BaseEntity> {
     className?: string;
 }
 declare function CrudActionBarComponent<T extends BaseEntity = BaseEntity>({ onNew, newButtonLabel, showNewButton, showSearch, searchValue, onSearchChange, searchPlaceholder, showBulkActions, selectedCount, bulkActions, onBulkDelete, onClearSelection, customActions, filters, viewMode, onViewModeChange, showViewToggle, availableViewModes, rightSlot, className, }: CrudActionBarProps<T>): import("react/jsx-runtime").JSX.Element;
+/**
+ * Componente `CrudActionBar` da lib.
+ * @example
+ * <CrudActionBar />
+ */
 export declare const CrudActionBar: typeof CrudActionBarComponent;
 export default CrudActionBar;

package/dist/crud/components/CrudGrid.d.ts

@@ -1,6 +1,11 @@
 import React from 'react';
 import type { CrudColumn, CrudManager, BaseEntity, BulkAction } from '../../types';
 import { type CustomAction, type ViewMode } from './CrudActionBar';
+/**
+ * Tipo `CrudGridProps` exportado pela lib.
+ * @example
+ * const value: CrudGridProps = {} as CrudGridProps;
+ */
 export interface CrudGridProps<T extends BaseEntity & {
     is_actived?: boolean;
 }> {
@@ -39,5 +44,10 @@ export interface CrudGridProps<T extends BaseEntity & {
     gridCardRenderer?: (item: T) => React.ReactNode;
     showViewToggle?: boolean;
 }
+/**
+ * Componente `CrudGrid` da lib.
+ * @example
+ * <CrudGrid />
+ */
 export declare const CrudGrid: <T extends BaseEntity>({ manager, columns, onEdit, onView, onToggleStatus, onDelete, renderActions, customRowActions, enableBulkActions, onNew, newButtonLabel, showNewButton, customActions, hideActionBar, showActionBar, showSearch, searchValue, onSearchChange, searchPlaceholder, bulkActions, onBulkDelete, filters, gridColumns, renderCard, viewMode, onViewModeChange, listCardRenderer, gridCardRenderer, showViewToggle }: CrudGridProps<T>) => import("react/jsx-runtime").JSX.Element;
 export default CrudGrid;

package/dist/crud/components/CrudPagination.d.ts

@@ -8,5 +8,10 @@ import type { CrudManager, BaseEntity } from '../../types';
 interface CrudPaginationProps<T extends BaseEntity> {
     manager: Pick<CrudManager<T>, 'pagination' | 'handlePageChange' | 'handleItemsPerPageChange'>;
 }
+/**
+ * Função utilitária `CrudPagination`.
+ * @example
+ * CrudPagination();
+ */
 export declare function CrudPagination<T extends BaseEntity>({ manager }: CrudPaginationProps<T>): import("react/jsx-runtime").JSX.Element;
 export { CrudPagination as TableFooter };

package/dist/crud/components/CrudTable.d.ts

@@ -57,5 +57,10 @@ export interface CrudTableProps<T extends BaseEntity & {
     /** Oculta a coluna de ações separada. Útil quando ações são renderizadas dentro de uma coluna customizada. */
     hideActionsColumn?: boolean;
 }
+/**
+ * Componente `CrudTable` da lib.
+ * @example
+ * <CrudTable />
+ */
 export declare const CrudTable: <T extends BaseEntity>({ manager, columns, onEdit, onView, onToggleStatus, onDelete, renderActions, customRowActions, enableBulkActions, rowActionsVariant, onNew, newButtonLabel, showNewButton, customActions, hideActionBar, showActionBar, showSearch, searchValue, onSearchChange, searchPlaceholder, bulkActions, onBulkDelete, filters, viewMode, onViewModeChange, showViewToggle, enableColumnResize, resizeStorageKey, enableColumnManager, columnManagerStorageKey, defaultHiddenColumns, enableGrouping, enableExpandableRows, renderExpandedContent, expandedRowIds: controlledExpandedIds, onToggleExpand: controlledToggleExpand, defaultExpandAll, hideActionsColumn, }: CrudTableProps<T>) => import("react/jsx-runtime").JSX.Element;
 export default CrudTable;

package/dist/crud/components/TableRowActions.d.ts

@@ -10,5 +10,10 @@ interface TableRowActionsProps {
         onClick: () => void;
     }>;
 }
+/**
+ * Componente `TableRowActions` da lib.
+ * @example
+ * <TableRowActions />
+ */
 export declare const TableRowActions: React.FC<TableRowActionsProps>;
 export {};

package/dist/crud/createCrudPage.d.ts

@@ -57,6 +57,11 @@ interface CrudPageGeneratorConfig<T extends CrudEntity> {
     onEdit?: (entity: T) => T | void | Promise<T | void>;
     onToggleStatus?: (item: T) => void;
 }
+/**
+ * Função utilitária `CrudPageInternal`.
+ * @example
+ * CrudPageInternal();
+ */
 declare function CrudPageInternal<T extends CrudEntity>({ manager, config, formSections, onSave, onToggleStatus, defaultSort, }: {
     manager: any;
     config: CrudPageConfig<T>;
@@ -69,18 +74,46 @@ declare function CrudPageInternal<T extends CrudEntity>({ manager, config, formS
     };
 }): import("react/jsx-runtime").JSX.Element;
 /**
- * Gera uma página CRUD completa
+ * Gera uma página CRUD completa (toolbar + tabela + paginação + form modal + confirmações).
  *
- * @example
- * ```typescript
- * const CrudPage = createCrudPage({
- *   manager,
- *   config: { entityName: 'Funcionário', ... },
- *   onSave: handleSave
+ * **IMPORTANTE**: a config deve ser memoizada (`useMemo` ou definida fora do componente)
+ * para evitar desmontagem e flicker no render — ver
+ * `mem://patterns/admin-render-optimization`.
+ *
+ * @example Pipeline completo
+ * ```tsx
+ * const employeesService = createSimpleService<Employee>({
+ *   tableName: 'employees',
+ *   schema: 'common',
  * });
+ *
+ * function EmployeesPage() {
+ *   const manager = useCrudHook(employeesService);
+ *
+ *   const Page = useMemo(() => createCrudPage<Employee>({
+ *     manager,
+ *     config: {
+ *       entityName: 'Funcionário',
+ *       entityNamePlural: 'Funcionários',
+ *       columns: [...],
+ *       formSections: [...],
+ *       defaultHiddenColumns: ['created_at'], // formato: column.key
+ *     },
+ *     onSave: createSimpleSaveHandler(manager, c => c, u => u),
+ *   }), [manager]);
+ *
+ *   return <Page />;
+ * }
  * ```
  *
- * Ver README para exemplos completos
+ * @remarks
+ * - `onNew`: handler customizado para o botão "Novo" (abre wizard ao invés do modal padrão).
+ * - `useCustomRouting`: desabilita o `BaseForm` interno (use quando o "Novo/Editar" navega para outra rota).
+ * - `defaultHiddenColumns`: chaves de coluna escondidas no primeiro acesso (ignorado se houver
+ *   estado salvo do column manager).
+ * - `hideNewButton`: **deprecated** — use `showNewButton={false}`.
+ *
+ * @see `docs/design-system/crud.md`
  */
 export declare function createCrudPage<T extends CrudEntity>(generatorConfig: CrudPageGeneratorConfig<T>): React.FC<{
     manager?: any;

package/dist/crud/generateCrudConfig.d.ts

@@ -1,16 +1,21 @@
 import { GeneratedCrudConfig, EntityWithId } from '../types';
 /**
- * Gera automaticamente configuração CRUD a partir de uma interface TypeScript
+ * Gera automaticamente configuração CRUD a partir de uma interface TypeScript.
  *
- * **USO AVANÇADO:** Para a maioria dos casos, use `useMemo` direto com config manual.
- * Esta função é útil para gerar configs dinamicamente em tempo de execução.
+ * **USO AVANÇADO:** Para a maioria dos casos, prefira config manual memoizada com
+ * `useMemo` (ver {@link createCrudPage}). Esta função é útil para gerar configs
+ * dinamicamente em runtime a partir de uma entidade-amostra.
  *
- * Analisa os campos da entidade e cria colunas com tipos inteligentes baseados em:
- * - Nome do campo (ex: "email" → type: 'email')
- * - Tipo do valor (ex: boolean → type: 'boolean')
- * - Padrões comuns (ex: "description" → type: 'textarea')
+ * @remarks
+ * A inferência roda em runtime via `Object.keys(sampleEntity)` — campos que não estão
+ * presentes em `sampleEntity` (ainda que existam no tipo `T`) **não geram coluna**.
+ * Sempre passe um objeto com todas as chaves desejadas, mesmo com valores vazios/zero.
  *
- * Para exemplos completos de configuração manual, veja o README (Tutorial CRUD de Examples).
+ * Heurísticas de tipo:
+ * - Nome do campo (ex: "email" → `type: 'email'`, "description" → `type: 'textarea'`).
+ * - Tipo do valor (boolean/number/Date).
+ *
+ * @see {@link createCrudPage} para o fluxo recomendado.
  *
  * @example
  * ```typescript

package/dist/crud/hooks/useBaseForm.d.ts

@@ -1,4 +1,43 @@
 import { FormField } from '../../types';
+/**
+ * Hook que gerencia estado, validação e defaults de um formulário declarativo (FormField[]).
+ *
+ * É o motor interno do {@link BaseForm} — exporte para reaproveitar o sistema de campos
+ * fora do `Dialog` padrão (ex: forms inline, wizards, drawers).
+ *
+ * Aplica defaults por tipo (`text` → `''`, `switch` → `false`, `multiselect` → `[]`, etc.)
+ * e expõe `setField`, `validate` e `reset`.
+ *
+ * @example
+ * const fields: FormField[] = [
+ *   { key: 'title', label: 'Título', type: 'text', required: true },
+ *   { key: 'is_active', label: 'Ativo', type: 'switch', defaultValue: true },
+ * ];
+ *
+ * function MyDrawerForm({ initial, onSave }) {
+ *   const { formData, errors, setField, validate, reset } = useBaseForm(
+ *     fields,
+ *     initial,
+ *     (data) => console.log('changed', data),
+ *     true, // open
+ *   );
+ *
+ *   const handleSubmit = () => {
+ *     if (validate()) onSave(formData);
+ *   };
+ *
+ *   return (
+ *     <>
+ *       <Input
+ *         value={formData.title ?? ''}
+ *         onChange={(e) => setField('title', e.target.value)}
+ *         error={errors.title}
+ *       />
+ *       <Button onClick={handleSubmit}>Salvar</Button>
+ *     </>
+ *   );
+ * }
+ */
 export declare function useBaseForm<T extends Record<string, any>>(fields: FormField[], initialData?: Partial<T>, onFormDataChange?: (data: T) => void, open?: boolean): {
     formData: T;
     errors: Record<string, string>;

package/dist/crud/hooks/useColumnManager.d.ts

@@ -1,9 +1,19 @@
 import type { CrudColumn, BaseEntity } from '../../types';
+/**
+ * Tipo `ColumnManagerState` exportado pela lib.
+ * @example
+ * const value: ColumnManagerState = {} as ColumnManagerState;
+ */
 export interface ColumnManagerState {
     hiddenColumns: Set<string>;
     columnOrder: string[];
     groupByColumns: string[];
 }
+/**
+ * Tipo `UseColumnManagerOptions` exportado pela lib.
+ * @example
+ * const value: UseColumnManagerOptions = {} as UseColumnManagerOptions;
+ */
 export interface UseColumnManagerOptions<T> {
     columns: CrudColumn<T>[];
     storageKey?: string;
@@ -11,6 +21,11 @@ export interface UseColumnManagerOptions<T> {
     /** Column keys to hide by default (before any user interaction). Only applied when no saved state exists. */
     defaultHiddenColumns?: string[];
 }
+/**
+ * Tipo `UseColumnManagerReturn` exportado pela lib.
+ * @example
+ * const value: UseColumnManagerReturn = {} as UseColumnManagerReturn;
+ */
 export interface UseColumnManagerReturn<T> {
     /** Columns filtered by visibility and reordered */
     visibleColumns: CrudColumn<T>[];
@@ -49,6 +64,11 @@ export interface UseColumnManagerReturn<T> {
     /** Toggle group collapse */
     toggleGroupCollapse: (groupKey: string) => void;
 }
+/**
+ * Tipo `GroupedData` exportado pela lib.
+ * @example
+ * const value: GroupedData = {} as GroupedData;
+ */
 export interface GroupedData<T> {
     groupKey: string;
     groupValue: string;
@@ -57,4 +77,9 @@ export interface GroupedData<T> {
     level: number;
     children?: GroupedData<T>[];
 }
+/**
+ * Função utilitária `useColumnManager`.
+ * @example
+ * useColumnManager();
+ */
 export declare function useColumnManager<T extends BaseEntity>({ columns, storageKey, enabled, defaultHiddenColumns, }: UseColumnManagerOptions<T>): UseColumnManagerReturn<T>;

package/dist/crud/hooks/useCrud.d.ts

@@ -72,6 +72,41 @@ interface CrudConfig<T, TInsert = Partial<T>, TUpdate = Partial<T>> {
     additionalFilters?: Record<string, any>;
     onSuccess?: () => void;
 }
+/**
+ * Hook genérico para operações CRUD com React Query (busca, paginação, mutations, bulk).
+ *
+ * **Uso recomendado**: invoque via `createSimpleService` — ele já configura `queryKey` e `service`.
+ * Use diretamente apenas quando precisar de um service customizado (RPC, edge function, etc).
+ *
+ * @example
+ * // Via createSimpleService (recomendado)
+ * const { useCrudHook } = createSimpleService<Employee>({
+ *   tableName: 'employees',
+ *   schema: 'central',
+ *   searchFields: ['name', 'email'],
+ * });
+ * const manager = useCrudHook();
+ *
+ * @example
+ * // Uso direto com service customizado
+ * const manager = useCrud<Project>({
+ *   queryKey: 'projects',
+ *   entityName: 'projeto',
+ *   service: {
+ *     getAll: (params) => projectsApi.list(params),
+ *     create: (data) => projectsApi.create(data),
+ *     update: (id, data) => projectsApi.update(id, data),
+ *     delete: (id) => projectsApi.softDelete(id),
+ *   },
+ *   additionalFilters: { id_status: 'active' },
+ *   onSuccess: () => navigate('/projects'),
+ * });
+ *
+ * @example
+ * // Consumindo o manager retornado
+ * const { entities, isLoading, createEntity, deleteEntity, pagination, handleSort } = manager;
+ * <Button onClick={() => createEntity({ title: 'Novo' })}>Criar</Button>
+ */
 export declare function useCrud<T extends {
     id: string;
 }, TInsert = Partial<T>, TUpdate = Partial<T>>({ queryKey, service, entityName, searchFields, additionalFilters, onSuccess }: CrudConfig<T, TInsert, TUpdate>): {

package/dist/crud/primitives/ActionMenu.d.ts

@@ -25,4 +25,45 @@
  * ```
  */
 import type { ActionMenuProps } from './types';
+/**
+ * Menu de ações por linha — renderiza dropdown (`renderAs="dropdown"`) ou botões inline
+ * (`renderAs="inline"`). Acoplado às convenções do CRUD (Edit / Delete / Toggle Status)
+ * mas extensível via `customActions`.
+ *
+ * Para tabelas inteiras, prefira a prop `rowActions` do `CrudTable` — só use este primitive
+ * quando precisar de um menu fora do contexto de tabela.
+ *
+ * @example
+ * // Dropdown padrão (3 dots) com Edit + Delete
+ * <ActionMenu
+ *   onEdit={() => openEdit(row)}
+ *   onDelete={() => confirmDelete(row.id)}
+ *   canDelete={row.id_user === currentUser.id}
+ * />
+ *
+ * @example
+ * // Inline compacto com ações customizadas + bloqueio condicional
+ * <ActionMenu
+ *   renderAs="inline"
+ *   variant="compact"
+ *   onEdit={() => openEdit(row)}
+ *   customActions={[
+ *     { label: 'Duplicar', icon: Copy, onClick: () => duplicate(row) },
+ *     {
+ *       label: 'Arquivar',
+ *       icon: Archive,
+ *       onClick: () => archive(row),
+ *       disabled: row.status === 'completed',
+ *       disabledReason: 'Planos concluídos não podem ser arquivados',
+ *     },
+ *   ]}
+ * />
+ *
+ * @example
+ * // Toggle de status (ativar/desativar) com ícone dinâmico
+ * <ActionMenu
+ *   onToggleStatus={() => toggleActive(row.id)}
+ *   isActive={row.is_actived}
+ * />
+ */
 export declare function ActionMenu({ onEdit, onDelete, onToggleStatus, isActive, canEdit, canDelete, customActions, renderAs, variant }: ActionMenuProps): import("react/jsx-runtime").JSX.Element;

package/dist/crud/primitives/FilterBar.d.ts

@@ -21,4 +21,49 @@
  * ```
  */
 import type { FilterBarProps } from './types';
+/**
+ * Barra de filtros primitiva: busca textual + slots para filtros customizados (selects,
+ * date ranges, etc) + botão "Limpar filtros" automático.
+ *
+ * Para CRUDs completos, prefira `CrudActionBar` (já integra com o manager). Use este
+ * primitive apenas para listas/dashboards fora do pipeline CRUD.
+ *
+ * Ver `mem://patterns/primitive-search-strategies` para a diferença entre busca local
+ * (`DataFilterBar`) e busca global (`AppHeader`).
+ *
+ * @example
+ * // Busca + 2 filtros customizados horizontais
+ * const [search, setSearch] = useState('');
+ * const [status, setStatus] = useState('all');
+ * const [responsible, setResponsible] = useState<string | null>(null);
+ *
+ * <FilterBar
+ *   searchValue={search}
+ *   onSearchChange={setSearch}
+ *   customFilters={[
+ *     <Combobox
+ *       key="status"
+ *       options={statusOptions}
+ *       value={status}
+ *       onChange={setStatus}
+ *       placeholder="Status"
+ *     />,
+ *     <QualiexUserField
+ *       key="responsible"
+ *       value={responsible}
+ *       onChange={setResponsible}
+ *       placeholder="Responsável"
+ *     />,
+ *   ]}
+ *   onClearFilters={() => {
+ *     setSearch('');
+ *     setStatus('all');
+ *     setResponsible(null);
+ *   }}
+ * />
+ *
+ * @example
+ * // Layout vertical (sidebar de filtros)
+ * <FilterBar layout="vertical" searchValue={s} onSearchChange={setS} customFilters={[...]} />
+ */
 export declare function FilterBar({ searchValue, onSearchChange, customFilters, onClearFilters, showClearButton, layout }: FilterBarProps): import("react/jsx-runtime").JSX.Element;

package/dist/crud/primitives/Pagination.d.ts

@@ -21,4 +21,9 @@
  * ```
  */
 import type { PaginationProps } from "./types";
+/**
+ * Função utilitária `Pagination`.
+ * @example
+ * Pagination();
+ */
 export declare function Pagination({ currentPage, totalPages, totalItems, itemsPerPage, onPageChange, onItemsPerPageChange, variant, }: PaginationProps): import("react/jsx-runtime").JSX.Element;