forlogic-core 2.1.5 → 2.2.0

package/dist/components/ui/tabs.d.ts

@@ -1,7 +1,66 @@
+/**
+ * @module Tabs
+ * Sistema de abas para alternar entre visões. Use `defaultValue` para modo não controlado
+ * ou `value` + `onValueChange` para controle externo (sincronizar com URL, por exemplo).
+ *
+ * Composição: `Tabs` (raiz) + `TabsList` + `TabsTrigger` (um por aba) + `TabsContent` (conteúdo).
+ *
+ * @see `docs/design-system/navigation.md`
+ */
 import * as React from "react";
 import * as TabsPrimitive from "@radix-ui/react-tabs";
+/**
+ * Raiz do sistema de abas. Re-exporta `TabsPrimitive.Root` do Radix.
+ *
+ * @example Não controlado
+ * ```tsx
+ * <Tabs defaultValue="geral">
+ *   <TabsList>
+ *     <TabsTrigger value="geral">Geral</TabsTrigger>
+ *     <TabsTrigger value="avancado">Avançado</TabsTrigger>
+ *   </TabsList>
+ *   <TabsContent value="geral">...</TabsContent>
+ *   <TabsContent value="avancado">...</TabsContent>
+ * </Tabs>
+ * ```
+ *
+ * @example Controlado (sincronizado com URL)
+ * ```tsx
+ * <Tabs value={tab} onValueChange={setTab}>...</Tabs>
+ * ```
+ */
 declare const Tabs: React.ForwardRefExoticComponent<TabsPrimitive.TabsProps & React.RefAttributes<HTMLDivElement>>;
+/**
+ * Container horizontal dos triggers de aba. Aparência de "pill group" com fundo `muted`.
+ *
+ * @example
+ * ```tsx
+ * <TabsList>
+ *   <TabsTrigger value="a">A</TabsTrigger>
+ *   <TabsTrigger value="b">B</TabsTrigger>
+ * </TabsList>
+ * ```
+ */
 declare const TabsList: React.ForwardRefExoticComponent<Omit<TabsPrimitive.TabsListProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+/**
+ * Botão de uma aba. O `value` deve corresponder a um `TabsContent` irmão.
+ *
+ * @example
+ * ```tsx
+ * <TabsTrigger value="settings">Configurações</TabsTrigger>
+ * ```
+ */
 declare const TabsTrigger: React.ForwardRefExoticComponent<Omit<TabsPrimitive.TabsTriggerProps & React.RefAttributes<HTMLButtonElement>, "ref"> & React.RefAttributes<HTMLButtonElement>>;
+/**
+ * Conteúdo associado a um `TabsTrigger`. O `value` deve casar com o trigger.
+ * Renderizado apenas quando a aba está ativa (forceMount=false por padrão).
+ *
+ * @example
+ * ```tsx
+ * <TabsContent value="settings">
+ *   <SettingsForm />
+ * </TabsContent>
+ * ```
+ */
 declare const TabsContent: React.ForwardRefExoticComponent<Omit<TabsPrimitive.TabsContentProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export { Tabs, TabsList, TabsTrigger, TabsContent };

package/dist/components/ui/terms-of-use-dialog.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Termo de uso a ser exibido. `file` é base64 (PDF/imagem); `description` aceita HTML.
+ *
+ * @example
+ * ```tsx
+ * const term: TermOfUse = { id: 'v3', description: '<p>Atualizamos...</p>', hasUserSignature: false };
+ * ```
+ */
 export interface TermOfUse {
     /** Unique identifier */
     id: string;
@@ -10,6 +18,15 @@ export interface TermOfUse {
     /** Whether the current user has already signed this term */
     hasUserSignature?: boolean;
 }
+/**
+ * Props do `TermsOfUseDialog`. `onAgree` recebe o `term.id` para
+ * registrar a assinatura no backend.
+ *
+ * @example
+ * ```tsx
+ * const props: TermsOfUseDialogProps = { term, open, onClose, onAgree: signTerm };
+ * ```
+ */
 export interface TermsOfUseDialogProps {
     /** The term of use to display */
     term: TermOfUse;
@@ -28,6 +45,14 @@ export interface TermsOfUseDialogProps {
     /** Override t('terms_view_short') button text */
     viewTermLabel?: string;
 }
+/**
+ * Props do `TermsOfUseViewer`. Use `viewOnly` para esconder o botão de assinar.
+ *
+ * @example
+ * ```tsx
+ * const props: TermsOfUseViewerProps = { term, open, onClose, viewOnly: true };
+ * ```
+ */
 export interface TermsOfUseViewerProps {
     /** The term of use to display */
     term: TermOfUse;
@@ -45,12 +70,33 @@ export interface TermsOfUseViewerProps {
     signLabel?: string;
 }
 /**
- * Dialog that notifies the user about updated terms of use.
- * Shows a description and buttons to view the full term, dismiss, or agree.
+ * Dialog que notifica o usuário sobre uma versão atualizada dos termos de uso.
+ * Mostra a descrição (HTML) e botões para visualizar o arquivo completo,
+ * adiar ("ver depois") ou concordar.
+ *
+ * @example
+ * ```tsx
+ * <TermsOfUseDialog
+ *   term={currentTerm}
+ *   open={hasNewTerm}
+ *   onClose={() => setHasNewTerm(false)}
+ *   onAgree={(id) => api.signTerm(id)}
+ * />
+ * ```
  */
 export declare function TermsOfUseDialog({ term, open, onClose, onAgree, title, seeLaterLabel, agreeLabel, viewTermLabel, }: TermsOfUseDialogProps): import("react/jsx-runtime").JSX.Element;
 /**
- * Full-screen viewer for a term of use file (PDF, etc.) embedded in an iframe.
- * Optionally shows a "sign" button for users who haven't signed yet.
+ * Visualizador full-screen do arquivo do termo de uso (PDF etc.) em iframe.
+ * Mostra opcionalmente um botão de assinar (oculto se `viewOnly` ou se já assinado).
+ *
+ * @example
+ * ```tsx
+ * <TermsOfUseViewer
+ *   term={term}
+ *   open={open}
+ *   onClose={() => setOpen(false)}
+ *   onSign={(id) => api.signTerm(id)}
+ * />
+ * ```
  */
 export declare function TermsOfUseViewer({ term, open, onClose, onSign, viewOnly, title, signLabel, }: TermsOfUseViewerProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/ui/textarea.d.ts

@@ -1,6 +1,33 @@
 import * as React from "react";
+/**
+ * Props do `Textarea`. Estende todos os atributos HTML padrão.
+ *
+ * @example
+ * ```tsx
+ * const props: TextareaProps = { showCharCount: true, maxLength: 200 };
+ * ```
+ */
 export interface TextareaProps extends React.TextareaHTMLAttributes<HTMLTextAreaElement> {
+    /**
+     * Quando `true` e `maxLength` for definido, exibe contador `N / max`
+     * abaixo do textarea (alinhado à direita).
+     */
     showCharCount?: boolean;
 }
+/**
+ * Textarea padrão da lib com hover/focus refinados (border-primary no hover).
+ * Aceita `showCharCount` + `maxLength` para exibir contador automaticamente.
+ *
+ * @example
+ * ```tsx
+ * <Textarea
+ *   placeholder="Descreva o ocorrido..."
+ *   maxLength={500}
+ *   showCharCount
+ * />
+ * ```
+ *
+ * @see `docs/design-system/inputs.md`
+ */
 declare const Textarea: React.ForwardRefExoticComponent<TextareaProps & React.RefAttributes<HTMLTextAreaElement>>;
 export { Textarea };

package/dist/components/ui/timepicker.d.ts

@@ -1,4 +1,13 @@
 import * as React from 'react';
+/**
+ * Props do `Timepicker`. Estende `<input>` (exceto `type`/`onChange`/`value`,
+ * que são gerenciados internamente).
+ *
+ * @example
+ * ```tsx
+ * const props: TimepickerProps = { value: '14:30', onChange: setHora, label: 'Horário' };
+ * ```
+ */
 export interface TimepickerProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'type' | 'onChange' | 'value'> {
     value?: string;
     onChange?: (value: string) => void;
@@ -7,5 +16,19 @@ export interface TimepickerProps extends Omit<React.InputHTMLAttributes<HTMLInpu
     error?: string;
     format?: '12h' | '24h';
 }
+/**
+ * Campo de seleção de horário (`<input type="time">`) com label, ícone de relógio
+ * e mensagem de erro integrados. Usa formato 24h por padrão.
+ *
+ * @example
+ * ```tsx
+ * <Timepicker
+ *   label="Início do expediente"
+ *   value={hora}
+ *   onChange={setHora}
+ *   error={errors.hora?.message}
+ * />
+ * ```
+ */
 declare const Timepicker: React.ForwardRefExoticComponent<TimepickerProps & React.RefAttributes<HTMLInputElement>>;
 export { Timepicker };

package/dist/components/ui/toggle-group.d.ts

@@ -1,10 +1,35 @@
 import * as React from "react";
 import * as ToggleGroupPrimitive from "@radix-ui/react-toggle-group";
 import { type VariantProps } from "class-variance-authority";
+/**
+ * Grupo de toggles (single ou multiple). Compartilha `variant`/`size` com seus
+ * `ToggleGroupItem` filhos via Context. Use `type="single"` para seleção única
+ * (rádio-like) ou `type="multiple"` para múltipla.
+ *
+ * @example
+ * ```tsx
+ * <ToggleGroup type="single" value={align} onValueChange={setAlign} variant="outline">
+ *   <ToggleGroupItem value="left"><AlignLeft /></ToggleGroupItem>
+ *   <ToggleGroupItem value="center"><AlignCenter /></ToggleGroupItem>
+ *   <ToggleGroupItem value="right"><AlignRight /></ToggleGroupItem>
+ * </ToggleGroup>
+ * ```
+ */
 declare const ToggleGroup: React.ForwardRefExoticComponent<((Omit<ToggleGroupPrimitive.ToggleGroupSingleProps & React.RefAttributes<HTMLDivElement>, "ref"> | Omit<ToggleGroupPrimitive.ToggleGroupMultipleProps & React.RefAttributes<HTMLDivElement>, "ref">) & VariantProps<(props?: {
     variant?: "outline" | "default";
     size?: "default" | "sm" | "lg";
 } & import("class-variance-authority/types").ClassProp) => string>) & React.RefAttributes<HTMLDivElement>>;
+/**
+ * Item individual de um `ToggleGroup`. Herda `variant`/`size` do grupo, mas
+ * pode sobrescrever localmente.
+ *
+ * @example
+ * ```tsx
+ * <ToggleGroupItem value="bold" aria-label="Negrito">
+ *   <Bold className="h-4 w-4" />
+ * </ToggleGroupItem>
+ * ```
+ */
 declare const ToggleGroupItem: React.ForwardRefExoticComponent<Omit<ToggleGroupPrimitive.ToggleGroupItemProps & React.RefAttributes<HTMLButtonElement>, "ref"> & VariantProps<(props?: {
     variant?: "outline" | "default";
     size?: "default" | "sm" | "lg";

package/dist/components/ui/toggle.d.ts

@@ -1,10 +1,31 @@
 import * as React from "react";
 import * as TogglePrimitive from "@radix-ui/react-toggle";
 import { type VariantProps } from "class-variance-authority";
+/**
+ * Variantes do `Toggle` (cva). Combina `variant` (`default` | `outline`) e
+ * `size` (`default` | `sm` | `lg`). Reutilizado por `ToggleGroupItem`.
+ *
+ * @example
+ * ```tsx
+ * <button className={toggleVariants({ variant: 'outline', size: 'sm' })}>B</button>
+ * ```
+ */
 declare const toggleVariants: (props?: {
     variant?: "outline" | "default";
     size?: "default" | "sm" | "lg";
 } & import("class-variance-authority/types").ClassProp) => string;
+/**
+ * Botão alternável (on/off). Use para ações binárias como "Negrito", "Itálico"
+ * em editores ou "Modo escuro" em preferências. Estado controlado via `pressed` +
+ * `onPressedChange` (Radix Toggle).
+ *
+ * @example
+ * ```tsx
+ * <Toggle variant="outline" pressed={bold} onPressedChange={setBold}>
+ *   <Bold className="h-4 w-4" />
+ * </Toggle>
+ * ```
+ */
 declare const Toggle: React.ForwardRefExoticComponent<Omit<TogglePrimitive.ToggleProps & React.RefAttributes<HTMLButtonElement>, "ref"> & VariantProps<(props?: {
     variant?: "outline" | "default";
     size?: "default" | "sm" | "lg";

package/dist/components/ui/tooltip.d.ts

@@ -1,7 +1,55 @@
+/**
+ * @module Tooltip
+ * Tooltip por hover/focus. Composição: `TooltipProvider` (envolve a árvore — pode ser global)
+ * + `Tooltip` (raiz por instância) + `TooltipTrigger` (use `asChild` para reaproveitar elemento)
+ * + `TooltipContent` (texto, com `side`, `sideOffset`, etc).
+ *
+ * `delayDuration` padrão de **300ms** (override do shadcn). Reduz flicker em listas densas.
+ */
 import * as React from "react";
 import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+/**
+ * Provider global de tooltips. Envolva a árvore uma única vez (já incluso em `CoreProviders`).
+ * `delayDuration` padrão: **300ms**.
+ *
+ * @example
+ * ```tsx
+ * <TooltipProvider delayDuration={300}>
+ *   <App />
+ * </TooltipProvider>
+ * ```
+ */
 declare const TooltipProvider: ({ delayDuration, ...props }: React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Provider>) => import("react/jsx-runtime").JSX.Element;
+/**
+ * Raiz de uma instância de tooltip. Re-exporta `TooltipPrimitive.Root` do Radix.
+ *
+ * @example
+ * ```tsx
+ * <Tooltip>
+ *   <TooltipTrigger asChild><Button>?</Button></TooltipTrigger>
+ *   <TooltipContent>Ajuda</TooltipContent>
+ * </Tooltip>
+ * ```
+ */
 declare const Tooltip: React.FC<TooltipPrimitive.TooltipProps>;
+/**
+ * Trigger do tooltip. Use `asChild` para herdar o elemento filho (recomendado para botões/ícones).
+ *
+ * @example
+ * ```tsx
+ * <TooltipTrigger asChild>
+ *   <Button variant="icon"><Info /></Button>
+ * </TooltipTrigger>
+ * ```
+ */
 declare const TooltipTrigger: React.ForwardRefExoticComponent<TooltipPrimitive.TooltipTriggerProps & React.RefAttributes<HTMLButtonElement>>;
+/**
+ * Conteúdo do tooltip. Aceita `side` (`top`/`right`/`bottom`/`left`) e `sideOffset` (padrão 4).
+ *
+ * @example
+ * ```tsx
+ * <TooltipContent side="right" sideOffset={8}>Texto explicativo</TooltipContent>
+ * ```
+ */
 declare const TooltipContent: React.ForwardRefExoticComponent<Omit<TooltipPrimitive.TooltipContentProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider };

package/dist/components/ui/truncated-cell.d.ts

@@ -3,5 +3,18 @@ interface TruncatedCellProps {
     children: React.ReactNode;
     className?: string;
 }
+/**
+ * Célula com `text-overflow: ellipsis` que detecta truncamento via `ResizeObserver`
+ * e exibe automaticamente um `Tooltip` com o conteúdo completo apenas quando há overflow.
+ *
+ * Disponível também como **alias `EllipsisText`** (padrão de mercado, exportado em `forlogic-core`).
+ *
+ * @example
+ * ```tsx
+ * <TruncatedCell>{textoLongo}</TruncatedCell>
+ * ```
+ *
+ * @see `docs/design-system/data-display.md`
+ */
 export declare function TruncatedCell({ children, className }: TruncatedCellProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/ui/typography.d.ts

@@ -1,16 +1,135 @@
+/**
+ * @module Typography
+ * Conjunto de 11 componentes tipográficos prontos seguindo a escala da lib:
+ * `H1`, `H2`, `H3`, `H4`, `P`, `Lead`, `Large`, `Small`, `Muted`, `InlineCode`, `Blockquote`, `List`.
+ *
+ * Use sempre que possível ao invés de aplicar classes Tailwind soltas em `<h1>`, `<p>`, etc.
+ * Garante consistência com a fonte base Inter (13px) e a escala definida em `index.css`.
+ *
+ * @see `docs/design-system/foundation.md`
+ */
 import * as React from "react";
+/**
+ * Props compartilhadas por todos os componentes tipográficos.
+ * Estende os atributos HTML padrão do elemento (heading, paragraph, etc.).
+ *
+ * @example
+ * ```tsx
+ * const Custom: React.FC<TypographyProps> = (props) => <H2 {...props} />;
+ * ```
+ */
 export interface TypographyProps extends React.HTMLAttributes<HTMLElement> {
 }
+/**
+ * Título principal da página (`<h1>`). Use **uma única vez** por página (regra SEO).
+ *
+ * @example
+ * ```tsx
+ * <H1>Painel de Controle</H1>
+ * ```
+ */
 declare const H1: React.ForwardRefExoticComponent<TypographyProps & React.RefAttributes<HTMLHeadingElement>>;
+/**
+ * Título de seção (`<h2>`). Inclui borda inferior automática para dividir blocos.
+ *
+ * @example
+ * ```tsx
+ * <H2>Configurações gerais</H2>
+ * ```
+ */
 declare const H2: React.ForwardRefExoticComponent<TypographyProps & React.RefAttributes<HTMLHeadingElement>>;
+/**
+ * Subtítulo (`<h3>`). Use dentro de seções marcadas por `H2`.
+ *
+ * @example
+ * ```tsx
+ * <H3>Notificações por email</H3>
+ * ```
+ */
 declare const H3: React.ForwardRefExoticComponent<TypographyProps & React.RefAttributes<HTMLHeadingElement>>;
+/**
+ * Título menor (`<h4>`). Útil para subdivisões de cards/painéis.
+ *
+ * @example
+ * ```tsx
+ * <H4>Detalhes do item</H4>
+ * ```
+ */
 declare const H4: React.ForwardRefExoticComponent<TypographyProps & React.RefAttributes<HTMLHeadingElement>>;
+/**
+ * Parágrafo padrão (`<p>`). Aplica `mt-6` quando não é o primeiro filho.
+ *
+ * @example
+ * ```tsx
+ * <P>Texto descritivo regular.</P>
+ * ```
+ */
 declare const P: React.ForwardRefExoticComponent<TypographyProps & React.RefAttributes<HTMLParagraphElement>>;
+/**
+ * Subtítulo grande/lead (`text-xl`, cor `muted-foreground`). Use logo abaixo de `H1`/`H2`.
+ *
+ * @example
+ * ```tsx
+ * <H1>Bem-vindo</H1>
+ * <Lead>Comece configurando sua primeira unidade.</Lead>
+ * ```
+ */
 declare const Lead: React.ForwardRefExoticComponent<TypographyProps & React.RefAttributes<HTMLParagraphElement>>;
+/**
+ * Texto destacado em tamanho `text-lg` semi-bold. Renderiza um `<div>`.
+ *
+ * @example
+ * ```tsx
+ * <Large>R$ 1.250,00</Large>
+ * ```
+ */
 declare const Large: React.ForwardRefExoticComponent<TypographyProps & React.RefAttributes<HTMLDivElement>>;
+/**
+ * Texto secundário em `<small>` (`text-sm font-medium`). Útil para legendas.
+ *
+ * @example
+ * ```tsx
+ * <Small>Atualizado há 5 minutos</Small>
+ * ```
+ */
 declare const Small: React.ForwardRefExoticComponent<TypographyProps & React.RefAttributes<HTMLElement>>;
+/**
+ * Texto auxiliar atenuado (`text-sm text-muted-foreground`). Use para hints e helper text.
+ *
+ * @example
+ * ```tsx
+ * <Muted>Este campo é opcional.</Muted>
+ * ```
+ */
 declare const Muted: React.ForwardRefExoticComponent<TypographyProps & React.RefAttributes<HTMLParagraphElement>>;
+/**
+ * Código inline (`<code>`) com fundo `muted` e fonte mono.
+ *
+ * @example
+ * ```tsx
+ * <P>Use o comando <InlineCode>npm install</InlineCode> para começar.</P>
+ * ```
+ */
 declare const InlineCode: React.ForwardRefExoticComponent<TypographyProps & React.RefAttributes<HTMLElement>>;
+/**
+ * Citação em bloco (`<blockquote>`) com borda lateral esquerda.
+ *
+ * @example
+ * ```tsx
+ * <Blockquote>"O design é como funciona, não como parece."</Blockquote>
+ * ```
+ */
 declare const Blockquote: React.ForwardRefExoticComponent<TypographyProps & React.RefAttributes<HTMLQuoteElement>>;
+/**
+ * Lista não-ordenada (`<ul>`) com `list-disc` e espaçamento padrão entre itens.
+ *
+ * @example
+ * ```tsx
+ * <List>
+ *   <li>Item um</li>
+ *   <li>Item dois</li>
+ * </List>
+ * ```
+ */
 declare const List: React.ForwardRefExoticComponent<TypographyProps & React.RefAttributes<HTMLUListElement>>;
 export { H1, H2, H3, H4, P, Lead, Large, Small, Muted, InlineCode, Blockquote, List, };

package/dist/components/ui/updates-notification.d.ts

@@ -3,6 +3,17 @@ import { type UpdateNotificationItem } from '../../hooks/useUpdatesNotification'
 /** @deprecated Use `UpdateNotificationItem` instead */
 export type UpdateNotification = UpdateNotificationItem;
 export type { UpdateNotificationItem };
+/**
+ * Props do `UpdatesNotification`. Quando `updates` é `undefined`, ativa o modo
+ * automático (busca da API via `useUpdatesNotification`); quando é um array,
+ * o componente fica controlado.
+ *
+ * @example
+ * ```tsx
+ * // Modo controlado:
+ * const props: UpdatesNotificationProps = { updates: [], badgeCount: 0 };
+ * ```
+ */
 export interface UpdatesNotificationProps {
     /** Lista de atualizações (undefined = modo automático, [] = vazio controlado) */
     updates?: UpdateNotificationItem[];
@@ -11,4 +22,26 @@ export interface UpdatesNotificationProps {
     onOpen?: () => void;
     onViewAll?: () => void;
 }
+/**
+ * Botão de notificações do header (ícone de café ☕). Possui dois modos:
+ *
+ * - **Automático** (sem props): busca atualizações via `useUpdatesNotification`,
+ *   marca como visualizado ao abrir e abre o portal Qualiex no "Ver todas".
+ * - **Controlado**: passe `updates` + `badgeCount` + `onOpen` + `onViewAll`.
+ *
+ * @example Automático (recomendado dentro do AppHeader)
+ * ```tsx
+ * <UpdatesNotification />
+ * ```
+ *
+ * @example Controlado
+ * ```tsx
+ * <UpdatesNotification
+ *   updates={updates}
+ *   badgeCount={updates.length}
+ *   onOpen={markAllRead}
+ *   onViewAll={() => navigate('/updates')}
+ * />
+ * ```
+ */
 export declare const UpdatesNotification: React.ForwardRefExoticComponent<UpdatesNotificationProps & React.RefAttributes<HTMLButtonElement>>;

package/dist/components/ui/users-groups-selector.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Usuário disponível para seleção. `groupIds` permite o filtro por grupo no header.
+ *
+ * @example
+ * ```tsx
+ * const u: UsersGroupUser = { id: '42', name: 'Ana', email: 'ana@x.com', groupIds: ['g1'] };
+ * ```
+ */
 export interface UsersGroupUser {
     id: string;
     name: string;
@@ -5,10 +13,29 @@ export interface UsersGroupUser {
     avatar?: string;
     groupIds?: string[];
 }
+/**
+ * Grupo usado para filtrar a lista de usuários.
+ *
+ * @example
+ * ```tsx
+ * const g: UsersGroup = { id: 'g1', name: 'Liderança' };
+ * ```
+ */
 export interface UsersGroup {
     id: string;
     name: string;
 }
+/**
+ * Props do `UsersGroupsSelector`. Componente controlado: passe `value` (IDs
+ * selecionados) + `onChange`. Quando `disabled`, esconde o header de edição.
+ *
+ * @example
+ * ```tsx
+ * const props: UsersGroupsSelectorProps = {
+ *   users, groups, value, onChange: setSelected
+ * };
+ * ```
+ */
 export interface UsersGroupsSelectorProps {
     /** Available users to select from */
     users: UsersGroupUser[];
@@ -41,4 +68,20 @@ export interface UsersGroupsSelectorProps {
     /** Additional className */
     className?: string;
 }
+/**
+ * Seletor de usuários com avatar, busca por nome/email, filtro por grupo e
+ * "selecionar todos". Possui dois modos visuais alternados pelo header:
+ * **leitura** (mostra apenas selecionados) e **edição** (lista completa filtrável).
+ *
+ * @example
+ * ```tsx
+ * const [selected, setSelected] = useState<string[]>([]);
+ * <UsersGroupsSelector
+ *   users={users}
+ *   groups={groups}
+ *   value={selected}
+ *   onChange={setSelected}
+ * />
+ * ```
+ */
 export declare function UsersGroupsSelector({ users, groups, value, onChange, disabled, maxHeight, hideGroupFilter, searchPlaceholder, selectLabel, doneLabel, allLabel, emptyLabel, selectedLabel, selectedPluralLabel, className, }: UsersGroupsSelectorProps): import("react/jsx-runtime").JSX.Element;