@sapphire-caitlyn/schema-kit-ng 0.0.4 → 0.0.6

package/docs/ui/loading/README.md

@@ -0,0 +1,62 @@
+# loading
+
+Indicador de carregamento: um spinner (`hlm-spinner`) centralizado sobre um fundo translúcido com bordas esmaecidas, que
+entra e sai com animação.
+
+Exemplos reais de uso: [profile](../../../../../../../src/app/pages/profile/profile.component.html) (sobre um card) e
+[login](../../../../../../../src/app/pages/auth/login/login.component.html) (dentro de botões).
+
+## Uso
+
+```ts
+import { LoadingComponent } from '@schema-kit';
+
+@Component({
+  imports: [LoadingComponent],
+  // ...
+})
+export class ExemploComponent {}
+```
+
+### Sobre uma área (`absolute`, padrão)
+
+Cobre o elemento pai inteiro. O pai precisa ser posicionado (`relative`, `absolute` etc.):
+
+```html
+<div class="relative">
+  <loading [active]="carregando()" />
+  <!-- conteúdo -->
+</div>
+```
+
+### Dentro de um botão (`relative`)
+
+Ocupa espaço no layout, ao lado do texto. Ao ficar inativo, a largura vai a 0 com transição e o restante do botão
+desliza para o lugar. Use `gap-0` no botão para não sobrar espaço quando o indicador some:
+
+```html
+<button hlmBtn class="gap-0" [disabled]="enviando()" (click)="enviar()">
+  <loading [active]="enviando()" position="relative" />
+  {{ enviando() ? 'Enviando...' : 'Enviar' }}
+</button>
+```
+
+## API
+
+### Inputs
+
+| Input      | Tipo                       | Padrão       | Descrição                                                                              |
+| ---------- | -------------------------- | ------------ | -------------------------------------------------------------------------------------- |
+| `active`   | `boolean`                  | `true`       | Exibe ou esconde o indicador                                                           |
+| `position` | `'absolute' \| 'relative'` | `'absolute'` | `absolute`: cobre o pai (`absolute inset-0`). `relative`: ocupa espaço no layout       |
+
+## Comportamentos a saber
+
+- **Continua no DOM:** com `active` = `false` o elemento não é removido. Ele faz fade out, passa a
+  `pointer-events-none` (não bloqueia cliques) e segue na árvore de acessibilidade. Para removê-lo de fato, use `@if`.
+- **Animação:** entra com fade deslizando a partir da esquerda e sai deslizando para a esquerda (classes do
+  `tw-animate-css`).
+- **Sobreposição:** no modo `absolute`, enquanto ativo, fica por cima do conteúdo não posicionado do pai e recebe os
+  cliques. Não há `z-index`: elementos posicionados que vêm depois dele no DOM ficam por cima.
+- **Acessibilidade:** o `hlm-spinner` tem `role="status"` e `aria-label="Loading"`, em inglês. O componente não permite
+  trocar esse rótulo.

package/docs/ui/save-button/README.md

@@ -0,0 +1,68 @@
+# save-button
+
+Botão padrão de salvar, com estado "salvando": troca o ícone por um spinner, o texto por "Salvando..." e mostra um brilho
+percorrendo a borda (`border-shimmer`).
+
+Usado no rodapé do [schema-view](../../schema-view/schema-view.component.html) e em dialogs como o
+[modulo-create-dialog](../../../../../../../src/app/pages/modulo/modulo-create-dialog/modulo-create-dialog.component.html).
+
+## Uso
+
+```ts
+import { SaveButtonComponent } from '@schema-kit';
+
+@Component({
+  imports: [SaveButtonComponent],
+  // ...
+})
+export class ExemploComponent {}
+```
+
+```html
+<save-button [saving]="salvando()" (save)="salvar()" />
+```
+
+### Com um `schema-view`
+
+Para colocar o botão fora do `schema-view` (ex.: no rodapé de um dialog), esconda o botão dele com `noSave` e ligue o
+`save-button` ao estado do view:
+
+```html
+<schema-view #view [noSave]="true" [schema]="schema()" ... />
+
+<hlm-dialog-footer>
+  <save-button [saving]="view.saving()" (save)="view.save()" />
+</hlm-dialog-footer>
+```
+
+## API
+
+### Inputs
+
+| Input    | Tipo      | Padrão  | Descrição                       |
+| -------- | --------- | ------- | ------------------------------- |
+| `saving` | `boolean` | `false` | Ativa o estado "Salvando..."    |
+
+### Outputs
+
+| Output | Tipo   | Descrição              |
+| ------ | ------ | ---------------------- |
+| `save` | `void` | Emitido a cada clique  |
+
+### Estados
+
+| Estado   | Variante                     | Ícone                             | Texto         |
+| -------- | ---------------------------- | --------------------------------- | ------------- |
+| Normal   | `default`                    | `lucideSave`               | Salvar        |
+| Salvando | `ghost` + `border-shimmer`   | `lucideRefreshCw` (girando)   | Salvando...   |
+
+## Comportamentos a saber
+
+- **Não desabilita:** durante `saving` o botão continua clicável, e cada clique emite `save` de novo. Se a ação não
+  pode rodar duas vezes ao mesmo tempo, proteja no handler. O `save()` do `schema-view` também não verifica se já está
+  salvando.
+- **`type`:** o `<button>` não define `type`, então dentro de um `<form>` ele funciona como `submit`.
+- **Fixos:** os textos ("Salvar" / "Salvando...") e o tamanho (`sm`) não são configuráveis.
+- **Ícones:** o componente não registra os próprios ícones. Ele depende do `provideIcons` global do app
+  ([app.config.ts](../../../../../../../src/app/app.config.ts)), que registra todos os ícones Lucide. Em outro app,
+  registre `lucideSave` e `lucideRefreshCw`.

package/docs/ui/schema-dialog/README.md

@@ -0,0 +1,154 @@
+# schema-dialog
+
+Abre dialogs (`hlm-dialog` do Spartan) por código e devolve o resultado como uma `Promise`. São duas peças:
+
+- `SchemaDialogComponent<Result>`: classe base do componente do dialog;
+- `SchemaDialogController`: serviço que cria o componente, passa os inputs, abre o dialog e resolve `closed` quando ele
+  fecha.
+
+Exemplos reais de uso: [modulo-create-dialog](../../../../../../../src/app/pages/modulo/modulo-create-dialog/modulo-create-dialog.component.ts)
+(fecha com `true` ao criar; aberto em [modulo.component.ts](../../../../../../../src/app/pages/modulo/modulo.component.ts))
+e [perfil-reorder](../../../../../../../src/app/pages/perfil/perfil-reorder/perfil-reorder.component.ts) (fecha com a
+hierarquia montada).
+
+## Uso
+
+### 1. O componente do dialog
+
+Estenda `SchemaDialogComponent` informando o tipo do resultado. O template precisa ter um `<hlm-dialog>`, com o conteúdo
+dentro de `*hlmDialogPortal`:
+
+```ts
+import { SchemaDialogComponent } from '@schema-kit';
+
+/** Fecha com `true` quando o módulo é criado. */
+@Component({
+  selector: 'modulo-create-dialog',
+  templateUrl: './modulo-create-dialog.component.html',
+})
+export class ModuloCreateDialogComponent extends SchemaDialogComponent<boolean> {
+  uuidModulo = input<string>();
+
+  async criar() {
+    // ...
+    this.close(true);
+  }
+}
+```
+
+```html
+<hlm-dialog>
+  <hlm-dialog-content *hlmDialogPortal="let ctx">
+    <hlm-dialog-header>
+      <h3 hlmDialogTitle>Novo módulo</h3>
+    </hlm-dialog-header>
+
+    <!-- conteúdo -->
+
+    <hlm-dialog-footer>
+      <button hlmBtn variant="outline" hlmDialogClose>Cancelar</button>
+      <button hlmBtn (click)="criar()">Criar</button>
+    </hlm-dialog-footer>
+  </hlm-dialog-content>
+</hlm-dialog>
+```
+
+### 2. Abrindo o dialog
+
+```ts
+import { SchemaDialogController } from '@schema-kit';
+
+export class ModuloComponent {
+  private schemaDialogController = inject(SchemaDialogController);
+
+  async openCreateDialog() {
+    const { closed } = this.schemaDialogController.open(ModuloCreateDialogComponent, { uuidModulo: this.uuidModulo() });
+    if (await closed) {
+      this.table().refresh();
+    }
+  }
+}
+```
+
+O segundo argumento é tipado a partir do componente: aceita só os inputs de signal (`input()` / `model()`), com o valor
+direto (não o signal). `closed` usa o `Result` da classe base: aqui, `Promise<boolean | undefined>`.
+
+## API
+
+### `SchemaDialogComponent<Result = void>`
+
+| Membro          | Tipo                         | Descrição                                                                          |
+| --------------- | ---------------------------- | ---------------------------------------------------------------------------------- |
+| `dialog`        | `Signal<HlmDialog>`          | O `hlm-dialog` do template (`viewChild.required`). Dá acesso a `open()` e `close()` |
+| `close(result)` | `(result: Result) => void`   | Fecha o dialog e resolve `closed` com `result`                                     |
+
+Com `Result = void`, `close()` pode ser chamado sem argumento.
+
+### `SchemaDialogController.open(component, inputs?, options?)`
+
+| Parâmetro   | Tipo                   | Descrição                                                                       |
+| ----------- | ---------------------- | ------------------------------------------------------------------------------- |
+| `component` | `Type<T>`              | Componente do dialog (`T` estende `SchemaDialogComponent`)                      |
+| `inputs`    | `DialogInputs<T>?`     | Valores dos inputs, aplicados com `setInput` antes de abrir                     |
+| `options`   | `ISchemaDialogOptions?`| Ver abaixo                                                                      |
+
+`ISchemaDialogOptions`:
+
+| Opção            | Tipo      | Padrão | Descrição                                  |
+| ---------------- | --------- | ------ | ------------------------------------------ |
+| `destroyOnClose` | `boolean` | `true` | Destrói o componente quando o dialog fecha |
+| `open`           | `boolean` | `true` | Abre o dialog logo depois de criar         |
+
+Retorno, `ISchemaDialogReturn<T>`:
+
+| Campo       | Tipo                           | Descrição                                                                                     |
+| ----------- | ------------------------------ | --------------------------------------------------------------------------------------------- |
+| `component` | `ComponentRef<T>`              | Ref do componente criado                                                                      |
+| `instance`  | `T`                            | Instância do componente                                                                       |
+| `closed`    | `Promise<Result \| undefined>` | Resolve quando o dialog fecha. Ver [Resultado](#resultado)                                    |
+
+## Ciclo de vida
+
+### Resultado
+
+`closed` resolve **uma única vez**, no primeiro fechamento:
+
+| Como fechou                                         | Valor                |
+| --------------------------------------------------- | -------------------- |
+| `close(result)`                                     | `result`             |
+| `hlmDialogClose`, ESC, clique fora, `dialog().close()` | `undefined`       |
+| Ref destruída sem o dialog ter fechado              | `undefined`          |
+
+Por isso, trate `undefined` como "cancelado": `if (await closed)` só segue quando houve resultado.
+
+### Destruição
+
+- **Padrão:** ao fechar, `closed` resolve primeiro e o componente é destruído em seguida.
+- **`destroyOnClose: false`:** o componente sobrevive ao fechamento e pode ser reaberto com `instance.dialog().open()`
+  (sem novo valor em `closed`). Destruir a ref com `component.destroy()` fica a cargo de quem abriu.
+- **`open: false`:** o componente é criado, mas não abre. Abra depois com `instance.dialog().open()`; a partir daí vale o
+  `destroyOnClose`. Se o dialog nunca for aberto, quem chamou precisa destruir a ref.
+
+## Comportamentos a saber
+
+- **Injeção:** o componente é criado com o `EnvironmentInjector` raiz (o controller é um `@Service()` global). Ele não
+  enxerga providers do componente que o abriu, nem de rotas ou módulos lazy. Os serviços que o dialog injeta precisam
+  estar na raiz (`@Service()` ou `providedIn: 'root'`).
+- **Fora do DOM:** o elemento host do componente não é inserido na página; só o conteúdo de `*hlmDialogPortal` aparece,
+  no overlay do dialog. O que estiver no template fora do portal nunca é exibido.
+- **Detecção de mudanças:** a view é anexada ao `ApplicationRef`, então o dialog é atualizado como qualquer outro
+  componente.
+- **`dialog` obrigatório:** o `<hlm-dialog>` precisa estar no template do próprio componente, não em um filho. Sem ele, o
+  `viewChild.required` lança erro na abertura.
+- **`<schema-dialog>`:** não use o seletor diretamente. O template da classe base é só um aviso de implementação
+  incorreta; as subclasses sempre declaram o próprio template.
+- **Inputs com `@Input()`:** não entram no tipo `DialogInputs` e não podem ser passados em `open`. Use `input()` ou
+  `model()`.
+
+## Implementação
+
+| Arquivo                               | Conteúdo                                                                         |
+| ------------------------------------- | -------------------------------------------------------------------------------- |
+| `schema-dialog.component.ts`          | Classe base `SchemaDialogComponent`                                              |
+| `schema-dialog.component.html`        | Aviso exibido apenas se `<schema-dialog>` for usado diretamente                  |
+| `schema-dialog-controller.service.ts` | `SchemaDialogController`, `ISchemaDialogOptions`, `ISchemaDialogReturn` e os tipos internos `DialogInputs` / `DialogResult` |

package/docs/ui/suspended-slider/README.md

@@ -0,0 +1,95 @@
+# suspended-slider
+
+Alterna entre slides nomeados, com transição: o slide ativo entra com fade deslizando da direita e o anterior sai para a
+direita. Os slides inativos continuam renderizados ("suspensos"), então mantêm o estado (formulários, scroll,
+componentes filhos) quando voltam a ficar ativos.
+
+Exemplos reais de uso: [login](../../../../../../../src/app/pages/auth/login/login.component.html) (etapas de login,
+"esqueci a senha" e OTP) e [nav-sidebar](../../../../../../../src/app/components/nav-sidebar/nav-sidebar.component.html)
+(um slide por menu de primeiro nível, gerados com `@for`).
+
+## Uso
+
+Importe o componente e a diretiva dos slides:
+
+```ts
+import { SuspendedSlideDirective, SuspendedSliderComponent } from '@schema-kit';
+
+@Component({
+  imports: [SuspendedSliderComponent, SuspendedSlideDirective],
+  // ...
+})
+export class ExemploComponent {
+  step = signal<'login' | 'senha'>('login');
+}
+```
+
+```html
+<suspended-slider class="h-96" [step]="step()">
+  <ng-template suspendedSlide="login">
+    <!-- formulário de login -->
+    <a (click)="step.set('senha')">Esqueceu sua senha?</a>
+  </ng-template>
+
+  <ng-template suspendedSlide="senha">
+    <!-- formulário de recuperação -->
+    <button (click)="step.set('login')">Voltar</button>
+  </ng-template>
+</suspended-slider>
+```
+
+Os slides também podem ser gerados dinamicamente:
+
+```html
+<suspended-slider class="min-h-0 flex-1" [step]="activeMenu()">
+  @for (topLevel of items(); track topLevel.uuid) {
+    <ng-template [suspendedSlide]="topLevel.uuid">
+      <ul class="size-full overflow-y-auto">
+        <!-- ... -->
+      </ul>
+    </ng-template>
+  }
+</suspended-slider>
+```
+
+## API
+
+### `suspended-slider`
+
+| Input  | Tipo                    | Descrição            |
+| ------ | ----------------------- | -------------------- |
+| `step` | `string` (obrigatório)  | Nome do slide ativo  |
+
+### `ng-template[suspendedSlide]`
+
+| Input            | Tipo                   | Descrição                            |
+| ---------------- | ---------------------- | ------------------------------------ |
+| `suspendedSlide` | `string` (obrigatório) | Nome do slide, comparado com `step`  |
+
+## Layout
+
+- Os slides são empilhados com `absolute inset-0`, então **o slider não cresce com o conteúdo**. Dê um tamanho a ele
+  (ex.: `absolute inset-0`, `h-96` ou `flex-1 min-h-0` dentro de um container flex). O host é `block`.
+- Cada slide ocupa a área toda e centraliza o conteúdo nos dois eixos (`flex items-center justify-center`). Para
+  rolagem, use `size-full overflow-y-auto` no conteúdo do slide, como no nav-sidebar.
+- As camadas internas usam `p-[inherit]`: o padding aplicado no host se propaga para dentro dos slides.
+
+## Comportamentos a saber
+
+- **Todos os slides ficam montados:** cada template é instanciado uma vez e continua no DOM mesmo inativo. Componentes,
+  `effect`s e requisições dentro de slides inativos seguem vivos. Se isso for um problema, use `@if` dentro do slide,
+  sabendo que o conteúdo perde o estado e some sem a animação de saída.
+- **Slides inativos:** recebem `inert` e `aria-hidden="true"`. Não recebem foco nem cliques e ficam ocultos para leitores
+  de tela.
+- **`step` sem slide correspondente:** nenhum slide fica visível.
+- **Nomes únicos:** os slides são rastreados pelo nome (`track slide.name()`). Dois slides com o mesmo nome ficam ativos
+  juntos, e o Angular avisa sobre chaves duplicadas.
+- **Direção:** a transição é sempre para a direita, independentemente da ordem dos slides. Não há animação invertida ao
+  "voltar".
+
+## Implementação
+
+| Arquivo                              | Conteúdo                                                              |
+| ------------------------------------ | --------------------------------------------------------------------- |
+| `suspended-slider.component.ts/html` | Componente: empilha os slides e aplica as classes de entrada e saída  |
+| `suspended-slide.directive.ts`       | Diretiva `suspendedSlide`, que expõe o `TemplateRef` e o nome do slide |

package/docs/ui/tree-drag-drop/README.md

@@ -0,0 +1,202 @@
+# tree-drag-drop
+
+Árvore com reordenação por drag and drop, inclusive entre níveis: um item pode ser reordenado entre os irmãos, virar
+filho de outro ou subir de nível. Também funciona pelo teclado.
+
+Exemplo real de uso: [perfil-reorder](../../../../../../../src/app/pages/perfil/perfil-reorder/perfil-reorder.component.ts).
+
+## Uso
+
+Importe o componente e, se for customizar o conteúdo dos nós, a diretiva:
+
+```ts
+import { ITreeNode, ITreeNodeMove, TreeDragDropComponent, TreeDragDropNodeDirective } from '@schema-kit';
+
+@Component({
+  imports: [TreeDragDropComponent, TreeDragDropNodeDirective],
+  // ...
+})
+export class ExemploComponent {
+  tree = signal<ITreeNode<IPerfil>[]>([]);
+
+  onMoved(event: ITreeNodeMove<IPerfil>) {
+    // `tree` já está atualizada aqui
+  }
+}
+```
+
+```html
+<tree-drag-drop [(nodes)]="tree" label="Hierarquia dos perfis" (nodeMoved)="onMoved($event)" />
+```
+
+A árvore é controlada por `nodes`: a cada movimentação o componente grava uma **nova referência** da árvore no
+`model`, e quem usa decide quando e como persistir.
+
+### Montando a árvore
+
+O componente recebe a árvore pronta. A partir de uma lista plana com o id do pai:
+
+```ts
+function buildTree(lstPerfil: IPerfil[]): ITreeNode<IPerfil>[] {
+  const setUuid = new Set(lstPerfil.map((p) => p.uuid));
+  const build = (isChild: (p: IPerfil) => boolean): ITreeNode<IPerfil>[] =>
+    lstPerfil
+      .filter(isChild)
+      .map((perfil) => ({
+        id: perfil.uuid,
+        label: perfil.nome,
+        data: perfil,
+        children: build((p) => p.uuidPerfilPai === perfil.uuid),
+      }));
+  // Raízes: sem pai ou com o pai fora da lista
+  return build((p) => !p.uuidPerfilPai || !setUuid.has(p.uuidPerfilPai));
+}
+```
+
+### Lendo o resultado
+
+Para salvar, percorra `nodes` em pré-ordem: o pai de cada item é o nó em que ele está, e a posição entre os irmãos é a
+ordem. Por exemplo, para atribuir uma `ordem` sequencial em cada nível:
+
+```ts
+function toOrdem(nodes: ITreeNode<IMenu>[], uuidPai: string | null = null): { uuid: string; uuidPai: string | null; ordem: number }[] {
+  return nodes.flatMap((node, index) => [
+    { uuid: node.data!.uuid, uuidPai, ordem: index + 1 },
+    ...toOrdem(node.children ?? [], node.data!.uuid),
+  ]);
+}
+```
+
+Se a lista vier filtrada (ex.: por módulo), itens cujo pai ficou de fora aparecem na raiz. Ao salvar, preserve o pai
+original desses itens para não desfazer o vínculo sem querer (o `toHierarquia` do perfil-reorder faz isso).
+
+## API
+
+### `ITreeNode<T>`
+
+| Campo      | Tipo               | Descrição                                                          |
+| ---------- | ------------------ | ------------------------------------------------------------------ |
+| `id`       | `string \| number` | Identificador único na árvore inteira                              |
+| `label`    | `string`           | Texto exibido e nome acessível do item                             |
+| `icon`     | `string?`          | Nome de um ícone registrado no ng-icons, exibido antes do label    |
+| `data`     | `T?`               | Objeto de origem; o componente nunca o altera                      |
+| `children` | `ITreeNode<T>[]?`  | Filhos, na ordem de exibição                                       |
+
+### Inputs
+
+| Input       | Tipo                                                         | Padrão       | Descrição                                                                                 |
+| ----------- | ------------------------------------------------------------ | ------------ | ----------------------------------------------------------------------------------------- |
+| `nodes`     | `ITreeNode<T>[]` (model, obrigatório)                        | —            | Árvore exibida. Use `[(nodes)]` para receber as atualizações                              |
+| `label`     | `string`                                                     | —            | Rótulo acessível da árvore (`aria-label`)                                                 |
+| `indent`    | `number`                                                     | `24`         | Recuo, em px, de cada nível. Também é quanto se arrasta na horizontal para mudar de nível |
+| `maxLevels` | `number`                                                     | `Infinity`   | Quantidade máxima de níveis (1 = lista plana)                                             |
+| `canDrop`   | `(node: ITreeNode<T>, parent: ITreeNode<T> \| null) => boolean` | `() => true` | Define se `node` pode ser filho de `parent` (`null` = raiz)                               |
+| `canDrag`   | `(node: ITreeNode<T>) => boolean`                            | `() => true` | Define se `node` pode ser movido. Os bloqueados mostram um cadeado no lugar da alça       |
+| `disabled`  | `boolean`                                                    | `false`      | Bloqueia arrasto e movimentação pelo teclado; a navegação continua funcionando            |
+
+### Outputs
+
+| Output      | Tipo               | Descrição                                                            |
+| ----------- | ------------------ | -------------------------------------------------------------------- |
+| `nodeMoved` | `ITreeNodeMove<T>` | Emitido após cada movimentação, com `nodes` já atualizada            |
+
+`ITreeNodeMove<T>`:
+
+| Campo            | Tipo                   | Descrição                                       |
+| ---------------- | ---------------------- | ----------------------------------------------- |
+| `node`           | `ITreeNode<T>`         | Nó movido (mesma referência, com os filhos)     |
+| `previousParent` | `ITreeNode<T> \| null` | Pai anterior (`null` = raiz)                    |
+| `previousIndex`  | `number`               | Posição anterior entre os irmãos                |
+| `parent`         | `ITreeNode<T> \| null` | Novo pai, já com `node` entre os filhos         |
+| `index`          | `number`               | Nova posição entre os irmãos                    |
+
+Soltar o item onde ele já estava não emite nada.
+
+### Template do nó: `treeDragDropNode`
+
+Substitui o conteúdo padrão (ícone + label) de cada item. A alça de arrasto e o botão de expandir continuam sendo do
+componente.
+
+```html
+<tree-drag-drop [(nodes)]="tree">
+  <ng-template treeDragDropNode let-node let-level="level" let-expanded="expanded">
+    <div class="flex min-w-0 flex-col">
+      <span class="truncate text-sm">{{ node.label }}</span>
+      <span class="text-muted-foreground truncate text-xs">{{ node.data.descricao }}</span>
+    </div>
+  </ng-template>
+</tree-drag-drop>
+```
+
+| Variável     | Tipo           | Descrição                                       |
+| ------------ | -------------- | ----------------------------------------------- |
+| `$implicit`  | `ITreeNode<T>` | O nó                                            |
+| `level`      | `number`       | Nível, começando em 1                           |
+| `expanded`   | `boolean`      | Se os filhos estão visíveis                     |
+
+## Interação
+
+### Mouse e toque
+
+O arrasto começa pela alça (ícone à esquerda do item). Itens bloqueados por `canDrag` mostram um cadeado no lugar dela
+e não podem ser arrastados.
+
+- **Vertical** define a posição.
+- **Horizontal** define o nível: cada `indent` px para a direita desce um nível, para a esquerda sobe um.
+
+O placeholder tracejado mostra onde o item vai cair, já no nível final. O nível possível fica sempre entre o do próximo
+item (para não tomar os filhos dele) e o do item de cima + 1 (no máximo vira filho dele). Dentro desse intervalo, vale o
+nível mais próximo do arrasto que `maxLevels` e `canDrop` aceitarem. Se nenhum for aceito, o placeholder fica vermelho e
+soltar ali não altera nada.
+
+Ao arrastar um item com filhos, os descendentes saem da lista e vão junto com ele; o preview mostra quantos são
+(`+N`). Soltar logo abaixo de um item recolhido, com recuo, coloca o item como **primeiro** filho dele. O pai que recebe
+um item é expandido.
+
+### Teclado
+
+A árvore segue o padrão WAI-ARIA de tree view, com um único item na ordem de Tab.
+
+| Tecla                 | Ação                                                       |
+| --------------------- | ---------------------------------------------------------- |
+| `↑` / `↓`             | Item anterior / próximo                                    |
+| `Home` / `End`        | Primeiro / último item                                     |
+| `→`                   | Expande; se já expandido, vai para o primeiro filho        |
+| `←`                   | Recolhe; se já recolhido ou sem filhos, vai para o pai     |
+| `Alt` + `↑` / `↓`     | Move entre os irmãos                                       |
+| `Alt` + `→`           | Vira o **último** filho do irmão de cima                   |
+| `Alt` + `←`           | Sobe um nível, logo depois do pai atual                    |
+
+As movimentações pelo teclado respeitam `canDrag`, `maxLevels` e `canDrop` e são anunciadas para leitores de tela. Em
+um item bloqueado, o leitor anuncia que ele não pode ser movido.
+
+## Comportamentos a saber
+
+- **Validação:** `maxLevels` considera a subárvore inteira do item movido: um item com netos ocupa três níveis.
+  No arrasto, `canDrop` é consultado com o pai de destino em toda posição, mesmo quando o pai não muda; pelo teclado,
+  só em `Alt` + `→` / `←` (reordenar entre irmãos com `Alt` + `↑` / `↓` não consulta). `canDrag` bloqueia apenas o
+  próprio item: um item bloqueado ainda pode receber filhos, se `canDrop` permitir.
+- **Ciclos:** não é possível colocar um item dentro dos próprios descendentes (eles saem da lista durante o arrasto).
+- **Estado de expansão:** é interno e começa com tudo expandido.
+- **Imutabilidade:** a cada movimentação só os nós no caminho até o pai antigo e o novo são recriados; os demais mantêm
+  a referência, e `data` nunca é alterado.
+- **Dentro de dialogs:** durante o arrasto o CDK move o item para o `<body>`, e o clique ao soltar seria interpretado
+  como clique fora do dialog, fechando-o. O componente descarta esse clique.
+- **Rolagem automática:** para rolar enquanto arrasta dentro de um container com scroll próprio (ex.: corpo de um
+  dialog), marque o container com `cdkScrollable` (`@angular/cdk/scrolling`). Sem isso, o CDK só rola a janela e a
+  própria lista.
+- **`id`s** precisam ser únicos na árvore inteira, não só entre irmãos.
+
+## Implementação
+
+| Arquivo                              | Conteúdo                                                                  |
+| ------------------------------------ | ------------------------------------------------------------------------- |
+| `tree-drag-drop.component.ts`        | Componente, tipos públicos, navegação e movimentação pelo teclado          |
+| `tree-drag-drop.component.html/scss` | Lista, placeholder, preview e estados visuais do arrasto                  |
+| `tree-drag-drop.utils.ts`            | Funções puras: achatar a árvore, calcular onde o item cai, mover nós      |
+| `tree-drag-drop-node.directive.ts`   | Diretiva `treeDragDropNode`                                               |
+
+A árvore é renderizada como **uma única lista achatada** (`cdkDropList`) com recuo por nível, em vez de um
+`cdkDropList` por nível. Listas aninhadas do CDK não funcionam bem para mover entre níveis: a lista externa captura o
+drop destinado à interna e itens sem filhos não têm onde receber um drop. Na lista achatada, o CDK só cuida da posição
+vertical; o nível vem do deslocamento horizontal (`projectDrop` em `tree-drag-drop.utils.ts`).