@dev-tcloud/tcloud-ui 6.29.0 → 6.30.1-beta.1

package/docs/tcloud-ui-popover.md

@@ -2,6 +2,37 @@
 
 O componente `tcloud-ui-popover` exibe um painel flutuante simples, ancorado ao elemento de origem. Ele aceita HTML livre e componentes Angular dentro do conteúdo projetado.
 
+## Instalação
+
+Instale a biblioteca no projeto consumidor:
+
+```bash
+npm install @dev-tcloud/tcloud-ui
+```
+
+Para usar o componente em um componente standalone, importe `TCloudUiPopoverComponent`:
+
+```ts
+import { TCloudUiPopoverComponent } from '@dev-tcloud/tcloud-ui';
+
+@Component({
+  standalone: true,
+  imports: [TCloudUiPopoverComponent]
+})
+export class ExampleComponent {}
+```
+
+Em módulos Angular, importe o `TCloudUiModule` uma vez no módulo onde o popover será usado:
+
+```ts
+import { TCloudUiModule } from '@dev-tcloud/tcloud-ui';
+
+@NgModule({
+  imports: [TCloudUiModule]
+})
+export class ExampleModule {}
+```
+
 ## Uso básico
 
 ```html
@@ -20,7 +51,7 @@ O componente `tcloud-ui-popover` exibe um painel flutuante simples, ancorado ao
 |------|------|-----------|---------|
 | `position` | `'top' \| 'right' \| 'bottom' \| 'left'` | Define o lado em que o popover será aberto. | `'bottom'` |
 | `align` | `'start' \| 'center' \| 'end'` | Define o alinhamento do painel em relação ao trigger. | `'start'` |
-| `maxWidth` | `number \| string` | Define a largura máxima do painel. Números são tratados como pixels. | `320` |
+| `maxWidth` | `number \| string` | Define a largura do painel aberto. Números são tratados como pixels. | `320` |
 | `disabled` | `boolean` | Desabilita a abertura do popover. | `false` |
 | `showCloseIcon` | `boolean` | Exibe um botão `X` para fechar o popover. | `false` |
 | `open` | `boolean` | Permite controlar a abertura via binding externo. | `false` |
@@ -39,6 +70,8 @@ O popover fecha ao clicar fora do componente ou ao pressionar `ESC`. Quando `sho
 
 Use `position` para definir o lado de abertura e `align` para definir a borda de ancoragem. Por exemplo, com `position="bottom"` e `align="end"`, o painel abre abaixo do trigger e cresce para a esquerda, mantendo a borda direita alinhada ao botão.
 
+Use `maxWidth` para definir o tamanho do painel aberto. O popover ocupa 100% do valor informado em `maxWidth` e respeita o limite da viewport para evitar estouro horizontal.
+
 ```html
 <tcloud-ui-popover position="bottom" align="end" maxWidth="420px">
   <button type="button" popover-trigger>Open</button>
@@ -49,6 +82,36 @@ Use `position` para definir o lado de abertura e `align` para definir a borda de
 </tcloud-ui-popover>
 ```
 
+## Largura customizada
+
+Informe `maxWidth` como numero ou string para definir a largura do popover aberto. Quando o valor for numerico, ele sera convertido para pixels; quando for string, o valor sera aplicado diretamente como CSS.
+
+```html
+<tcloud-ui-popover position="right" align="start" [maxWidth]="560">
+  <button type="button" popover-trigger>Detalhes</button>
+
+  <div popover-content>
+    Este popover abre com 560px de largura, ocupando 100% do valor informado em maxWidth.
+  </div>
+</tcloud-ui-popover>
+
+<tcloud-ui-popover position="bottom" align="center" maxWidth="min(640px, 90vw)">
+  <button type="button" popover-trigger>Resumo</button>
+
+  <div popover-content>
+    Este popover usa uma largura CSS customizada e continua respeitando o limite da viewport.
+  </div>
+</tcloud-ui-popover>
+```
+
+## Posicionamento e camada
+
+O painel do popover e renderizado dentro do proprio componente. O container usa `position: relative` e o painel usa `position: absolute`, permitindo que as posicoes `top`, `right`, `bottom` e `left` sejam calculadas a partir do trigger.
+
+O `z-index` padrao do painel e `4006`. Esse valor posiciona o popover acima de dropdowns comuns da biblioteca e abaixo de camadas globais como tooltips e menus de sistema.
+
 ## Dark mode
 
 O componente usa tokens CSS `--c-*`, então acompanha o dark mode aplicado pela classe `.tc-dark` do projeto.
+
+O background default do painel e `var(--c-neutral-50)`. No tema claro, esse token resolve para `#FFFFFF`; em `body.tc-dark`, resolve para `#0F1117`.