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

package/docs/schema-view/README.md

@@ -0,0 +1,439 @@
+# schema-view
+
+Tela de criar/editar gerada a partir de um schema: um input por campo, carregamento do registro pela rota, validação e
+salvamento. Na criação envia todos os valores (`POST`) e depois abre a edição do registro criado; na edição envia só os
+campos alterados (`PATCH`).
+
+Feita para trabalhar junto com o [schema-table](../schema-table/README.md) (a listagem).
+
+## Uso
+
+```ts
+import { SchemaViewComponent, SchemaViewContentDirective } from '@schema-kit';
+```
+
+### 1. O service
+
+O jeito mais comum é passar um `SchemaService`: ele dá os campos, carrega o registro e salva. Os exemplos deste README
+usam este service:
+
+```ts
+import { inject, Injectable } from '@angular/core';
+import { min, required } from '@angular/forms/signals';
+import { FieldType, IView, SchemaService } from '@schema-kit';
+
+export interface IProduto extends IView {
+  nome: string;
+  preco: number;
+  ativo: boolean;
+  uuidCategoria: string | null;
+  foto: string | File | null;
+  descricao: string | null;
+}
+
+@Injectable({ providedIn: 'root' })
+export class ProdutoService extends SchemaService<IProduto> {
+  constructor() {
+    // `this` não existe antes do super(): injete as dependências em variáveis locais
+    const categoriaService = inject(CategoriaService);
+
+    super({
+      endpoint: '/produtos',
+      title: 'Produtos',
+      bindLabel: 'nome',
+      bindValue: 'uuid',
+      schema: {
+        uuid:  { type: FieldType.UUID,     label: 'UUID',  hidden: true },
+        nome:  { type: FieldType.String,   label: 'Nome',  validators: required },
+        preco: {
+          type: FieldType.Currency,
+          label: 'Preço',
+          validators: [required, (path) => min(path, 0, { message: 'O preço não pode ser negativo' })],
+        },
+        ativo: { type: FieldType.Bool, label: 'Ativo', defaultValue: true },
+        uuidCategoria: {
+          type: FieldType.Select,
+          label: 'Categoria',
+          tooltipInfo: 'Define em qual seção da loja o produto aparece',
+          options: { service: () => categoriaService, clearable: true },
+        },
+        foto:      { type: FieldType.File,     label: 'Foto', options: { clearable: true } },
+        descricao: { type: FieldType.TextArea, label: 'Descrição' },
+      },
+    });
+  }
+}
+```
+
+### 2. As rotas
+
+O componente lê o uuid do parâmetro da rota. Sem uuid, é criação; com uuid, é edição. Use a mesma estrutura que o
+schema-table navega (`./view` e `./view/:uuid`):
+
+```ts
+const routes: Routes = [
+  { path: '', component: ProdutoListComponent },
+  { path: 'view', component: ProdutoViewComponent },       // criar
+  { path: 'view/:uuid', component: ProdutoViewComponent }, // editar
+];
+```
+
+Se o parâmetro tiver outro nome (ex.: `view/:id`), informe em `uuidIdentifier="id"`.
+
+#### Sem rota: input `uuid`
+
+Fora dessa estrutura (ex.: um dialog), informe o registro pelo input `uuid`. Ele tem prioridade sobre a rota, e cada
+troca de valor carrega o novo registro. Sem valor (`null`), volta para a criação com os valores iniciais.
+
+```html
+<schema-view
+  [schemaService]="produtoService"
+  [uuid]="uuidProduto()"
+  [redirectOnCreate]="false"
+  [noBack]="true"
+  (onDidSave)="fechar()"
+/>
+```
+
+### 3. O componente
+
+```ts
+@Component({
+  selector: 'produto-view',
+  imports: [SchemaViewComponent],
+  template: `<schema-view [schemaService]="produtoService" />`,
+})
+export class ProdutoViewComponent {
+  protected produtoService = inject(ProdutoService);
+}
+```
+
+Só com isso a tela tem: breadcrumb (`Produtos > Novo` ou `Produtos > Edição`), botões **Voltar** e **Novo**, um input
+por campo e o botão **Salvar**.
+
+## Inputs
+
+| Input            | Tipo                                       | Padrão   | Descrição                                                              |
+| ---------------- | ------------------------------------------ | -------- | ---------------------------------------------------------------------- |
+| `schemaService`  | `SchemaService<T, IP> \| null`             | `null`   | Campos, breadcrumb, carregamento (`show`) e salvamento (`create`/`patch`) |
+| `schema`         | `SchemaFieldOptionsRecord<T> \| null`      | `null`   | Campos da tela (inputs e form), no lugar do schema do service. Ver [Personalizando os campos](#personalizando-os-campos) |
+| `saveFn`         | `(values: Partial<T>) => Promise<R>`       | `null`   | Substitui o `create`/`patch` do service. Ver [Salvando sem service](#salvando-sem-service) |
+| `redirectOnCreate` | `string \| false`                          | `'../view'` | Para onde ir depois de **criar**: `[redirectOnCreate, uuid]`, relativo à rota atual. `false`: fica na tela e vira edição do registro criado |
+| `uuid`           | `string \| null`                           | —        | Registro a editar, no lugar do parâmetro da rota. Ver [Sem rota](#sem-rota-input-uuid) |
+| `uuidIdentifier` | `string`                                   | `'uuid'` | Nome do parâmetro da rota com o uuid                                   |
+| `lstBreadCrumbs` | `IBreadcrumbItem[]`                        | `[]`     | Substitui o breadcrumb                                                 |
+| `noBack`         | `boolean`                                  | `false`  | Esconde Voltar                                                         |
+| `noNew`          | `boolean`                                  | `false`  | Esconde Novo                                                           |
+| `noSave`         | `boolean`                                  | `false`  | Esconde Salvar (tela só de leitura)                                    |
+
+É preciso informar `schemaService` ou `schema`.
+
+## Outputs
+
+| Output      | Tipo    | Descrição                                                                                              |
+| ----------- | ------- | ------------------------------------------------------------------------------------------------------ |
+| `onDidSave` | `R`     | Depois de salvar (criação ou edição), com o que o salvamento devolveu. Vem vazio se a resposta for vazia (ex.: `204`). Não emite sem alterações, em erro nem com form inválido |
+| `novo`      | `Event` | Clique em Novo, antes de navegar. `event.preventDefault()` cancela                                     |
+
+`R` é o tipo que o salvamento devolve: o retorno do `saveFn`, ou `T` quando quem salva é o service.
+
+Voltar para a listagem depois de salvar (desligue o redirect para a navegação ficar só com você):
+
+```html
+<schema-view [schemaService]="produtoService" [redirectOnCreate]="false" (onDidSave)="aoSalvar($event)" />
+```
+
+```ts
+private router = inject(Router);
+
+protected aoSalvar(produto: IProduto) {
+  console.log('Salvo:', produto.uuid);
+  this.router.navigate(['/produtos']);
+}
+```
+
+## Membros públicos
+
+Acessíveis por uma referência de template (`#view`) ou `viewChild(SchemaViewComponent)`:
+
+| Membro      | Tipo                  | Descrição                                       |
+| ----------- | --------------------- | ----------------------------------------------- |
+| `form()`    | `FieldTree<T>`        | O form (signal forms). Recriado quando o `schema` ou o `schemaService` muda |
+| `uuid`      | `WritableSignal<string>` | uuid em edição (input `uuid` ou rota). Vazio na criação. `uuid.set()` troca o registro sem navegar |
+| `loading()` | `boolean`             | Carregando ou salvando (inputs em skeleton)     |
+| `saving()`  | `boolean`             | Salvando                                        |
+| `save()`    | `Promise<void>`       | O mesmo que clicar em Salvar                    |
+| `load(uuid?)` | `Promise<void>`     | Recarrega o registro (padrão: o `uuid()` atual). Precisa de `schemaService` |
+
+## Template: `schemaViewContent`
+
+Conteúdo extra dentro do card. Não tem contexto: para ler o form, use a referência do componente.
+
+| Input      | Tipo               | Padrão  | Descrição                                                                 |
+| ---------- | ------------------ | ------- | ------------------------------------------------------------------------- |
+| `position` | `'start' \| 'end'` | `'end'` | `start`: entre os botões do topo e os campos. `end`: depois dos campos, antes de Salvar |
+
+```html
+<schema-view #view [schemaService]="produtoService">
+  <ng-template schemaViewContent position="start">
+    @if (!view.form().ativo().value()) {
+      <div class="rounded-lg bg-muted p-2 text-sm">
+        Produto inativo: não aparece na loja.
+      </div>
+    }
+  </ng-template>
+</schema-view>
+```
+
+## Campos
+
+Cada campo do schema vira um input, na ordem em que foi declarado:
+
+| Tipo                                     | Input                                                                                   |
+| ---------------------------------------- | --------------------------------------------------------------------------------------- |
+| `String`, `UUID`                         | [input-string](../inputs/input-string/README.md). `options.type` define o `type` do `<input>` (ex.: `'email'`) |
+| `TextArea`                               | [input-text-area](../inputs/input-text-area/README.md)                                  |
+| `Number` / `Decimal` / `Currency`        | [input-number / input-decimal / input-currency](../inputs/input-number/README.md)       |
+| `Bool`                                   | [input-bool](../inputs/input-bool/README.md)                                            |
+| `Date` / `DateTime` / `Time`             | [input-date](../inputs/date/input-date/README.md) / [input-date-time](../inputs/date/input-date-time/README.md) / [input-time](../inputs/date/input-time/README.md) |
+| `DateSpan` / `DateTimeSpan` / `TimeSpan` | [input-date-span](../inputs/date/input-date-span/README.md) / [input-date-time-span](../inputs/date/input-date-time-span/README.md) / [input-time-span](../inputs/date/input-time-span/README.md) |
+| `Phone`                                  | [input-phone](../inputs/input-phone/README.md)                                          |
+| `Cpf` / `Cnpj` / `CpfCnpj`               | [input-cpf / input-cnpj / input-cpf-cnpj](../inputs/input-cpf-cnpj/README.md)           |
+| `Mask`                                   | [input-mask](../inputs/input-mask/README.md), com `options.maskitoOptions` e `options.unmaskHandler` |
+| `Select`                                 | [input-select](../inputs/input-select/README.md), com as `options` abaixo               |
+| `Icon`                                   | [input-icon](../inputs/input-icon/README.md)                                            |
+| `File`                                   | [input-file](../inputs/input-file/README.md), com `options.clearable`                   |
+| `JSON`                                   | [input-json](../inputs/input-json/README.md)                                            |
+
+Do schema, cada input recebe `label`, `placeholder`, `tooltipInfo` e `class`.
+
+### Select
+
+Duas formas de `options`:
+
+```ts
+// Busca na API de outro service (paginada, com busca no servidor)
+uuidCategoria: {
+  type: FieldType.Select,
+  label: 'Categoria',
+  options: {
+    service: () => categoriaService,
+    lstFilter: [{ index: 'ativa', value: true }], // filtros enviados no index do outro service
+    clearable: true,
+  },
+},
+
+// Lista fixa: bindValue precisa produzir o tipo do campo
+unidade: {
+  type: FieldType.Select,
+  label: 'Unidade',
+  options: {
+    lstOptions: [
+      { id: 'UN', nome: 'Unidade' },
+      { id: 'KG', nome: 'Quilo' },
+    ],
+    bindValue: 'id',
+    bindLabel: 'nome',
+  },
+},
+```
+
+### Layout
+
+Os campos ficam num grid de 12 colunas. O `class` do campo define a largura:
+
+| Tipo        | `class` padrão                            | Resultado                                 |
+| ----------- | ----------------------------------------- | ----------------------------------------- |
+| `TextArea`  | `col-span-full`                           | Linha inteira                             |
+| os demais   | `xl:col-span-3 md:col-span-6 col-span-full` | 4 por linha no `xl`, 2 no `md`, 1 no celular |
+
+```ts
+nome: { type: FieldType.String, label: 'Nome', class: 'md:col-span-8 col-span-full' },
+preco: { type: FieldType.Currency, label: 'Preço', class: 'md:col-span-4 col-span-full' },
+```
+
+`hidden: true` ou `hidden: { hiddenForm: true }` esconde o input, mas o campo continua no form (o valor é enviado na
+criação).
+
+### Valores iniciais
+
+Na criação, cada campo começa com o `defaultValue` do schema ou, sem ele, com o padrão do tipo:
+
+| Tipo                              | Padrão  |
+| --------------------------------- | ------- |
+| `Number`, `Decimal`, `Currency`   | `0`     |
+| `Bool`                            | `false` |
+| os demais                         | `null`  |
+
+### Validação e somente leitura
+
+`validators` recebe uma regra ou uma lista de regras do signal forms (`(path) => void`):
+
+```ts
+import { email, maxLength, required } from '@angular/forms/signals';
+import { cpfValidator, urlValidator } from '@schema-kit';
+
+email: { type: FieldType.String, label: 'E-mail', options: { type: 'email' }, validators: [required, email] },
+sku:   { type: FieldType.String, label: 'SKU', validators: (path) => maxLength(path, 20) },
+cpf:   { type: FieldType.Cpf, label: 'CPF', validators: cpfValidator },
+site:  { type: FieldType.String, label: 'Site', validators: urlValidator },
+```
+
+Validators prontos do `@schema-kit`: `cpfValidator`, `cnpjValidator`, `cpfCnpjValidator`, `urlValidator`,
+`partialUrlValidator` e `passwordValidator`.
+
+Ao salvar com o form inválido, todos os campos são marcados como tocados (as mensagens aparecem embaixo de cada input) e
+um toast lista os labels dos campos com erro.
+
+Para um campo só de leitura, use `readonly: true` (aplica a regra `readonly` do signal forms):
+
+```ts
+criadoPor: { type: FieldType.String, label: 'Criado por', readonly: true },
+```
+
+O valor continua no form: vai no `POST` da criação e, como não pode ser alterado, nunca entra no `PATCH`. Para uma tela
+inteira só de leitura, combine `readonly` nos campos com `[noSave]="true"`.
+
+## Salvando
+
+| Modo                   | Ao abrir                       | Ao salvar                                                   | Depois                         |
+| ---------------------- | ------------------------------ | ----------------------------------------------------------- | ------------------------------ |
+| Criação (sem uuid)     | Form com os valores iniciais   | `POST ${endpoint}` com **todos** os valores                 | Vai para `../view/<uuid>`      |
+| Edição (com uuid)      | `GET ${endpoint}/${uuid}`      | `PATCH ${endpoint}/${uuid}` só com os campos **alterados**  | Fica na tela                   |
+
+```jsonc
+// Na edição de /produtos/view/3f2a…, mudando só o preço:
+// PATCH /produtos/3f2a…
+{ "preco": 19.9 }
+```
+
+- Sem alterações, nada é enviado e aparece o toast "Nenhum dado foi alterado".
+- Se algum valor for arquivo (`File`, `File[]`, `FileList`), o corpo vai como `FormData`: o arquivo na chave do campo,
+  listas em `campo[]` e os demais valores serializados em JSON.
+- Sucesso e erro mostram um toast. Os inputs ficam em skeleton enquanto salva.
+- Depois de criar, a tela navega para `[redirectOnCreate, uuid]` (padrão `../view/<uuid>`), substituindo a URL: ela passa
+  para edição, recarrega o registro, e o próximo Salvar envia um `PATCH`. Voltar no navegador não retorna para o form de
+  criação.
+- Com `[redirectOnCreate]="false"`, a tela não navega: o uuid do registro criado vira o `uuid()`, o form é recarregado
+  (sem `schemaService`, fica com os valores digitados) e o próximo Salvar envia um `PATCH`.
+- Nos dois casos, é preciso que a resposta da criação tenha `uuid`. Sem ele (ex.: um `saveFn` que devolve outro tipo,
+  ou resposta vazia), não há registro para editar: o form volta para os valores iniciais, pronto para outra criação.
+
+### Salvando sem service
+
+Com `saveFn`, o componente chama a função no lugar do `create`/`patch`. Ela recebe os mesmos valores (todos na criação,
+só os alterados na edição) e devolve uma `Promise` com o resultado:
+
+- o valor resolvido é o `$event` do `onDidSave` (e define o tipo `R`; pode ser diferente do tipo do form);
+- se o valor tiver `uuid`, a criação faz o redirect de `redirectOnCreate` (ou, com `false`, vira edição na mesma tela);
+- se vier vazio (ex.: resposta `204`), o toast de sucesso aparece e o `onDidSave` emite vazio;
+- se rejeitar, aparece o toast de erro.
+
+Junto com `schema`, dá para montar um formulário sem service:
+
+```ts
+import { email, required } from '@angular/forms/signals';
+import { FieldType, IView, SchemaFieldOptionsRecord, SchemaViewComponent } from '@schema-kit';
+
+// O componente exige `T extends IView`
+interface IContato extends IView {
+  nome: string;
+  email: string;
+  mensagem: string;
+}
+
+@Component({
+  selector: 'contato',
+  imports: [SchemaViewComponent],
+  template: `
+    <schema-view
+      [schema]="schema"
+      [saveFn]="enviar"
+      [redirectOnCreate]="false"
+      [lstBreadCrumbs]="[{ label: 'Contato' }]"
+      [noBack]="true"
+      [noNew]="true"
+      (onDidSave)="enviado($event)"
+    />
+  `,
+})
+export class ContatoComponent {
+  private http = inject(HttpClient);
+  private router = inject(Router);
+
+  protected schema: SchemaFieldOptionsRecord<IContato> = {
+    nome:     { type: FieldType.String,   label: 'Nome',     validators: required },
+    email:    { type: FieldType.String,   label: 'E-mail',   options: { type: 'email' }, validators: [required, email] },
+    mensagem: { type: FieldType.TextArea, label: 'Mensagem', validators: required },
+  };
+
+  // Arrow function: mantém o `this` quando o schema-view chama a função.
+  // A API devolve um protocolo, não um IContato: `R` vira IProtocolo
+  protected enviar = (values: Partial<IContato>) =>
+    lastValueFrom(this.http.post<IProtocolo>('/api/contato', values));
+
+  protected enviado(protocolo: IProtocolo) {
+    this.router.navigate(['/contato/enviado', protocolo.numero]);
+  }
+}
+
+interface IProtocolo {
+  numero: string;
+}
+```
+
+Sem service não há como carregar o registro: com um uuid (rota ou input), o form não é preenchido. Na edição, o
+`saveFn` recebe só os campos alterados; o uuid do registro fica em `uuid()` (via referência `#view`). Fora da estrutura
+`view`/`view/:uuid` (rota própria, dialog), passe `[redirectOnCreate]="false"`.
+
+## Personalizando os campos
+
+Com `schemaService` **e** `schema`, o `schema` substitui o do service na tela: define os inputs e o form (valores
+iniciais, `validators` e `readonly`). O service continua carregando e salvando. Útil para ajustar uma tela sem mexer no
+service.
+
+O `schema` **substitui**, não completa: um campo do service que não estiver nele não aparece nem vai no form. Para
+manter os outros campos, parta do schema do service:
+
+```ts
+export class ProdutoViewComponent {
+  protected produtoService = inject(ProdutoService);
+  uuidCategoria = input<string>(); // parâmetro da rota, com withComponentInputBinding()
+
+  // Parte do schema do service: esconde a foto e já cria o produto na categoria da rota
+  protected schema = computed<SchemaFieldOptionsRecord<IProduto>>(() => ({
+    ...this.produtoService.schema,
+    foto: { ...this.produtoService.schema.foto!, hidden: { hiddenForm: true } },
+    uuidCategoria: { ...this.produtoService.schema.uuidCategoria!, defaultValue: this.uuidCategoria() ?? null },
+  }));
+}
+```
+
+```html
+<schema-view [schemaService]="produtoService" [schema]="schema()" />
+```
+
+O `schema` é reativo (pode ser um `computed`). Mudar o valor recria o form:
+
+- o que o usuário já alterou continua, nos campos que ainda existem;
+- os outros campos voltam ao valor inicial do schema novo (ex.: um `defaultValue` que mudou);
+- na edição, o registro é recarregado, e o que foi alterado se perde.
+
+## Navegação e breadcrumb
+
+| Botão  | Aparece                           | Vai para                                                    |
+| ------ | --------------------------------- | ----------------------------------------------------------- |
+| Voltar | Sempre (exceto com `noBack`)      | A listagem: `../` em `view`, `../../` em `view/:uuid`. Depende só da rota, não do input `uuid` |
+| Novo   | Só na edição (exceto com `noNew`) | `../view` (criação). Se o uuid não veio da rota, volta para a criação na mesma tela. Cancelável com `(novo)` |
+| Salvar | Sempre (exceto com `noSave`)      | Na criação, `[redirectOnCreate, uuid]` (padrão `../view/<uuid>`); com `false`, fica e vira edição. Na edição, não navega |
+
+O breadcrumb vem, nesta ordem, de: `lstBreadCrumbs`; `breadcrumbs` das opções do service; ou o padrão
+`[{ label: title, routerLink: endpoint }, { label: 'Novo' | 'Edição' }]`.
+
+```ts
+interface IBreadcrumbItem {
+  label: string;
+  routerLink?: string;
+  icon?: string;
+}
+```

package/docs/ui/blurry-text-reveal/README.md

@@ -0,0 +1,49 @@
+# blurry-text-reveal
+
+Exibe um texto com animação de entrada letra a letra: cada caractere surge desfocado, transparente e um pouco abaixo da
+posição final, e assenta no lugar 30 ms depois do anterior.
+
+Exemplo real de uso: [login](../../../../../../../src/app/pages/auth/login/login.component.html) (título "Backoffice").
+
+## Uso
+
+```ts
+import { BlurryTextRevealComponent } from '@schema-kit';
+
+@Component({
+  imports: [BlurryTextRevealComponent],
+  // ...
+})
+export class ExemploComponent {}
+```
+
+```html
+<blurry-text-reveal class="font-garamond text-5xl font-semibold text-primary" text="Backoffice" />
+```
+
+Coloque as classes de tipografia e cor no próprio `<blurry-text-reveal>`: as letras herdam fonte, tamanho e cor do host.
+
+## API
+
+### Inputs
+
+| Input  | Tipo     | Padrão   | Descrição                                                           |
+| ------ | -------- | -------- | ------------------------------------------------------------------- |
+| `text` | `string` | `'Text'` | Texto animado. É dividido em caracteres, com um `<span>` para cada um |
+
+## Comportamentos a saber
+
+- **Estilos:** a animação vem do utilitário `letter-reveal`
+  ([letter-reveal.css](../../../styles/directives/letter-reveal.css)), carregado pelo `styles.scss` da lib. O `.scss` do
+  componente é vazio, então o app precisa importar os estilos da lib.
+- **Duração:** cada letra anima por 500 ms, com atraso de `(posição - 1) × 30 ms`. Um texto de 10 letras termina em
+  cerca de 770 ms.
+- **`sibling-index()`:** o atraso é calculado com essa função CSS, que é recente. Em navegadores sem suporte, a
+  declaração do `animation-delay` é descartada e todas as letras animam ao mesmo tempo.
+- **Espaços:** cada caractere vira um `<span>` `inline-block`, e um `inline-block` que contém só um espaço fica com
+  largura zero. Em textos com mais de uma palavra, os espaços somem ("Novo Backoffice" aparece como "NovoBackoffice").
+  Os usos atuais são de uma palavra só.
+- **Troca de texto:** os `<span>` são rastreados pela posição (`track $index`). Ao mudar `text`, as letras nas posições
+  que já existiam só trocam de conteúdo, sem animar de novo. Só as posições novas (quando o texto fica mais longo)
+  animam.
+- **Movimento reduzido:** a animação não respeita `prefers-reduced-motion`.

package/docs/ui/breadcrumbs/README.md

@@ -0,0 +1,62 @@
+# breadcrumbs
+
+Trilha de navegação (breadcrumb) montada a partir de uma lista de itens, com os primitivos `hlmBreadcrumb*` do Spartan.
+
+Usado no topo do [schema-table](../../schema-table/schema-table.component.html) e do
+[schema-view](../../schema-view/schema-view.component.html).
+
+## Uso
+
+```ts
+import { BreadcrumbsComponent, IBreadcrumbItem } from '@schema-kit';
+
+@Component({
+  imports: [BreadcrumbsComponent],
+  // ...
+})
+export class ExemploComponent {
+  items: IBreadcrumbItem[] = [
+    { label: 'Módulos', routerLink: '/modulo' },
+    { label: 'Edição' },
+  ];
+}
+```
+
+```html
+<breadcrumbs [items]="items" />
+```
+
+### Nas telas de schema
+
+Com `schema-table` e `schema-view`, o componente não é usado diretamente: os itens vêm do `SchemaService`.
+
+- Se as opções do service têm `breadcrumbs`, essa lista é usada nas duas telas.
+- Senão, a listagem mostra só o `title`, e a edição mostra o `title` (com link para o `endpoint` do service) seguido de
+  "Edição" ou "Novo".
+- O `schema-view` também aceita o input `lstBreadCrumbs`, que tem prioridade sobre o service.
+
+## API
+
+### `IBreadcrumbItem`
+
+| Campo        | Tipo      | Descrição                                                       |
+| ------------ | --------- | --------------------------------------------------------------- |
+| `label`      | `string`  | Texto exibido                                                   |
+| `routerLink` | `string?` | Rota do item, passada para o `routerLink` do Angular            |
+| `icon`       | `string?` | Ainda não é exibido pelo componente                             |
+
+### Inputs
+
+| Input   | Tipo                | Padrão | Descrição                                 |
+| ------- | ------------------- | ------ | ----------------------------------------- |
+| `items` | `IBreadcrumbItem[]` | `[]`   | Itens, do mais geral até a página atual   |
+
+## Comportamentos a saber
+
+- **Último item:** é sempre a página atual e aparece como texto (`hlmBreadcrumbPage`), mesmo que tenha `routerLink`.
+- **Itens sem link:** itens intermediários sem `routerLink` também usam `hlmBreadcrumbPage`, que marca o elemento com
+  `aria-current="page"`. Com mais de um item assim, leitores de tela anunciam mais de uma "página atual".
+- **Rotas relativas:** um `routerLink` sem `/` no início é resolvido a partir da rota em que o componente está. Os
+  `endpoint`s dos services começam com `/`, então os links gerados por eles são absolutos.
+- **Separador:** o ícone (`lucideChevronRight`) já é registrado pelo `hlmBreadcrumbSeparator`.
+- **Trilhas longas:** não há colapso com reticências (`hlmBreadcrumbEllipsis`): todos os itens são exibidos.

package/docs/ui/file-preview/README.md

@@ -0,0 +1,60 @@
+# file-preview
+
+Botão pequeno (`icon-xs`) de um arquivo. Imagens abrem uma pré-visualização num popover, com o [loading](../loading/README.md)
+por cima enquanto a imagem carrega; os demais arquivos abrem/baixam pelo link.
+
+Exemplos reais de uso: [input-file](../../inputs/input-file/input-file.component.html) (arquivo selecionado ou já salvo) e
+[schema-table](../../schema-table/schema-table.component.html) (template das colunas `FieldType.File`).
+
+## Uso
+
+```ts
+import { FilePreviewComponent, fileItemsFromValue } from '@schema-kit';
+
+@Component({
+  imports: [FilePreviewComponent],
+  // ...
+})
+export class ExemploComponent {
+  arquivos = computed(() => fileItemsFromValue(this.registro().arquivo));
+}
+```
+
+```html
+@for (arquivo of arquivos(); track arquivo.url) {
+  <file-preview [item]="arquivo" />
+}
+```
+
+## API
+
+### Inputs
+
+| Input  | Tipo       | Padrão        | Descrição          |
+| ------ | ---------- | ------------- | ------------------ |
+| `item` | `FileItem` | (obrigatório) | Arquivo a exibir   |
+
+### `FileItem`
+
+| Campo   | Tipo      | Descrição                                                                 |
+| ------- | --------- | ------------------------------------------------------------------------- |
+| `name`  | `string`  | Nome exibido nos rótulos de acessibilidade e usado no download de `file`  |
+| `url`   | `string`  | URL da imagem ou do link                                                  |
+| `image` | `boolean` | Abre a pré-visualização em vez do link                                    |
+| `file`  | `File?`   | Arquivo local (a `url` é uma object URL); o link baixa com o nome `name`  |
+
+### Funções
+
+- **`fileItemFromUrl(url)`:** item de um arquivo já existente. O nome é o último segmento do caminho da URL (o nome
+  original, nas URLs assinadas do bucket) e `image` vem da extensão.
+- **`fileItemsFromValue(value)`:** itens de um valor vindo da API (`string`, `string[]` ou vazio). Ignora o que não for
+  string.
+
+## Comportamentos a saber
+
+- **Loading só na primeira abertura:** o popover recria a imagem a cada abertura, mas o navegador reaproveita a já
+  carregada. O loading volta a aparecer quando a `url` muda (ex.: nova URL assinada após recarregar o registro).
+- **Erro ao carregar:** o loading some e fica o texto alternativo da imagem.
+- **Cliques:** o componente não para a propagação do clique. Dentro de algo clicável (ex.: linha da tabela), envolva com
+  `(click)="$event.stopPropagation()"`.
+- **Object URLs:** quem cria a object URL de um `File` é responsável por revogá-la (o `input-file` já faz isso).

package/docs/ui/infinte-scroll/README.md

@@ -0,0 +1,10 @@
+# infinte-scroll
+
+> **Não implementado.** A pasta contém só o esqueleto gerado pelo Angular CLI.
+
+- O template só exibe `infinte-scroll works!`. Não há inputs, outputs nem lógica.
+- O componente (`InfinteScrollComponent`, seletor `lib-infinte-scroll`) **não é exportado** no
+  [index.ts](../../../index.ts), então não está disponível via `@schema-kit`.
+- O nome da pasta, dos arquivos e da classe tem um erro de digitação ("infinte" em vez de "infinite"). Vale corrigir
+  ao implementar, antes que alguém passe a usar.
+- O seletor usa o prefixo `lib-`, diferente dos outros componentes de `ui/`, que não têm prefixo.