@slotted/angular 0.0.0-stage → 0.1.0-beta.0

package/docs/markdown.md

@@ -0,0 +1,266 @@
+<!-- index: ./index.md -->
+# markdown
+
+`data-ui="markdown"` · Renders Markdown with an element allowlist.
+
+## Import
+
+```ts
+import {
+  SlMarkdown,
+  SlMarkdownChildren,
+  SlMarkdownEmpty,
+  SlMarkdownNode,
+  provideMarkdownDefaults,
+} from '@slotted/angular/markdown';
+import { completeMarkdown, fromMarkedTokens, prepareMarkdown } from '@slotted/core/markdown';
+```
+
+Selector: `[slMarkdown], ng-template[slMarkdownNode], [slMarkdownChildren], [slMarkdownEmpty]` · exportAs: `slMarkdown`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<div slMarkdown headingAnchors [tree]="tree"></div>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div | yes |
+| `embed` | div | no |
+| `alert-body` | div | no |
+| `task-list` | ul \| ol | no |
+| `task` | li | no |
+| `task-body` | div | no |
+| `backref` | a | no |
+| `empty` | p | no |
+| `error` | div | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `tree` | `MarkdownNode \| null` | — | [slMarkdown] | O documento em mdast; nunca HTML |
+| `size` | `'md' \| 'lg' \| 'xl'` | lg | [slMarkdown] | O degrau de tipo da região, de prose |
+| `flow` | `'tight' \| 'normal' \| 'loose'` | normal | [slMarkdown] | O espaço entre blocos, de prose |
+| `status` | `'ready' \| 'error'` | ready | [slMarkdown] | error troca o documento pela parte error |
+| `loading` | `boolean` | false | [slMarkdown] | Um parágrafo de espera, depois do delay do skeleton |
+| `streaming` | `boolean` | false | [slMarkdown] | aria-busy enquanto a fonte chega |
+| `external` | `'new-tab' \| 'same-tab'` | new-tab | [slMarkdown] | Onde abre um link que sai da aplicação |
+| `headingAnchors` | `boolean` | false | [slMarkdown] | Um permalink em cada título |
+| `headingOffset` | `number` | 0 | [slMarkdown] | Somado ao nível de cada título, até seis |
+| `idPrefix` | `string` |  | [slMarkdown] | Antes de cada id gerado; obrigatório com duas regiões na página |
+| `alerts` | `boolean` | true | [slMarkdown] | Lê > [!NOTE] e os irmãos como alert |
+| `allow` | `string[]` | CommonMark + GFM sem html | [slMarkdown] | Os tipos mdast desenhados |
+| `unwrapDisallowed` | `boolean` | false | [slMarkdown] | Um tipo recusado entrega os filhos ao pai |
+| `transformUrl` | `(url, kind, node) => string \| null` | safeUrl | [slMarkdown] | A política de URL; null recusa |
+| `isExternal` | `(href) => boolean` | isExternalUrl | [slMarkdown] | Se um link sai da aplicação |
+| `messages` | `PartialMessages<MarkdownMessages>` | — | [slMarkdown] | As palavras da família sobre o idioma em vigor, chave a chave |
+| `editableTasks` | `boolean` | false | [slMarkdown] | Liga os checkboxes das tarefas; um output não diz se alguém o ouve |
+| `retryable` | `boolean` | false | [slMarkdown] | Desenha o botão de repetir na parte error |
+| `ng-template[slMarkdownNode]` | `kind \| type` | — | conteúdo | Substitui o elemento de um tipo conhecido, ou desenha um tipo desconhecido; recebe o elemento preparado |
+| `[slMarkdownChildren]` | `MarkdownElement` | — | ng-container | Desenha os filhos de um elemento dentro de um template, sem elemento próprio |
+| `[slMarkdownEmpty]` | `conteúdo projetado` | — | conteúdo | O conteúdo da parte empty |
+| `exportAs` | `slMarkdown` | — | [slMarkdown] | document(): os headings e as notas, com os ids da página |
+| `provideMarkdownDefaults` | `external \| headingAnchors \| alerts \| allow \| transformUrl \| isExternal` | — | Aplicação | Decidido uma vez para todos os documentos por baixo; um input ganha |
+| `prepareMarkdown` | `(tree, options) => MarkdownDocument` | — | @slotted/core/markdown | headings para um índice, com os ids da página |
+| `completeMarkdown` | `(source) => string` | — | @slotted/core/markdown | Fecha uma fonte cortada antes do parser |
+| `fromMarkedTokens` | `(tokens) => MarkdownNode` | — | @slotted/core/markdown | O lexer do marked como mdast |
+| `id, aria-*, data-*` | `atributos nativos` | — | [slMarkdown] | Ficam no elemento do consumidor |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `taskChange` | `{ index, checked, offset, request }` | Quando o leitor marca ou desmarca uma tarefa com editableTasks ligado, com a razão pointer ou keyboard em request. A caixa não se move: a árvore nova do consumidor é que a move. |
+| `retry` | `'pointer' \| 'keyboard'` | Quando o leitor pressiona o botão de repetir da parte error, desenhado com retryable. |
+
+## Rules
+
+- Nenhuma string da fonte chega a innerHTML: a família recebe uma árvore, recusa HTML cru e esquemas executáveis por omissão, e cada elemento é criado pelo framework.
+- Os títulos são títulos de verdade, deslocáveis com headingOffset para caberem no esboço da página; a âncora fica na ordem de tabulação e na árvore de acessibilidade, com o nome "Link to section: <título>".
+- Uma tarefa é um checkbox nomeado pelo texto do item; sem editableTasks é aria-readonly, não disabled, por isso continua focável e legível.
+- Cada referência de nota tem aria-describedby para o título escondido da secção, e cada retorno diz para qual referência volta; um alerta do GitHub é live="off", porque é conteúdo e não um evento.
+- streaming e loading põem aria-busy na raiz, e o skeleton faz um único anúncio educado; nada move o foco quando o conteúdo chega.
+
+## Tokens
+
+`--slotted-control-font-size-md`, `--slotted-font-family-sans`, `--slotted-font-size-md`, `--slotted-line-height-md`, `--slotted-markdown-backref-size`, `--slotted-markdown-task-gap`, `--slotted-prose-flow-loose`, `--slotted-prose-flow-normal`, `--slotted-prose-flow-tight`, `--slotted-prose-list-inset`, `--slotted-prose-marker-gap`, `--slotted-space-1`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-target-min`, `--slotted-text-muted`
+
+## Examples
+
+### Um documento inteiro
+
+Títulos com id estável, ênfase, código em linha, listas aninhadas, uma citação e uma régua: tudo em prose, cuja tipografia é a da região. Passe o ponteiro por um título para ver a âncora; com Tab ela aparece também.
+
+Excerpt — not a complete module
+
+```html
+<div slMarkdown headingAnchors [tree]="tree"></div>
+```
+
+### Tabelas do GFM
+
+O alinhamento :-- e --: chega como start e end, por isso uma tabela vista em RTL mantém os preços contra a aresta onde a leitura termina. Uma tabela mais larga do que a coluna rola dentro da parte scroll de prose, que só ganha tabindex e nome enquanto transborda.
+
+Excerpt — not a complete module
+
+```markdown
+| Plano | Lugares |   Preço |
+| :---- | :-----: | ------: |
+| Team  |   10    | $120.00 |
+```
+
+### Cercas com code-block
+
+Cada cerca é um CodeBlock: a linguagem da info string, e o que vem depois dela — title="…", {2} e showLineNumbers — chega como título, linha realçada e números. O realce de sintaxe é o do CodeBlockDefaultsProvider.
+
+Excerpt — not a complete module
+
+````markdown
+```ts title="deploy.ts" {2} showLineNumbers
+import { deploy } from '@acme/cli';
+await deploy({ env: 'production' });
+```
+````
+
+### Listas de tarefas
+
+Sem editableTasks as caixas são checkbox em readOnly: focáveis, anunciadas como só de leitura. Com ele, marcar uma tarefa pede a mudança com o índice e o offset na fonte; a caixa só se move quando a árvore nova chega.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slMarkdown
+  editableTasks
+  [tree]="tree"
+  (taskChange)="source.set(toggleTask(source(), $event.index, $event.checked))"
+></div>
+```
+
+### Alertas do GitHub
+
+> [!NOTE], [!TIP], [!IMPORTANT], [!WARNING] e [!CAUTION] tornam-se alert em reach="section" e live="off" — conteúdo, não anúncio — nos tons accent, success, secondary, warning e danger. alerts={false} devolve a citação.
+
+Excerpt — not a complete module
+
+```markdown
+> [!WARNING]
+> A deployment during a migration waits for the migration to finish.
+```
+
+### Notas de rodapé
+
+Numeradas pela primeira referência, com uma seta de retorno por referência dentro do último parágrafo da nota. A secção tem um título escondido que dá nome ao conjunto; uma definição que ninguém referencia não é desenhada, como no GitHub.
+
+Excerpt — not a complete module
+
+```html
+<div slMarkdown [messages]="{ footnotes: 'Notas' }" [tree]="tree"></div>
+```
+
+### Links internos e externos
+
+Um endereço absoluto http(s) sai da aplicação: é um Link com o glifo e a dica de nova aba. Um caminho relativo é um a simples. external="same-tab" mantém a aba; isExternal decide quais hosts são da casa.
+
+Excerpt — not a complete module
+
+```html
+<div slMarkdown [isExternal]="isOwnDomainInternal" [tree]="tree"></div>
+```
+
+### Sanitização por construção
+
+A família nunca escreve innerHTML. HTML cru não é desenhado; javascript:, data: e as grafias disfarçadas perdem o link e ficam como texto; uma imagem recusada fica como o seu texto alternativo. transformUrl troca a política; allow restringe os tipos.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slMarkdown
+  unwrapDisallowed
+  [allow]="['paragraph', 'text', 'emphasis', 'strong', 'link']"
+  [tree]="tree"
+></div>
+```
+
+### Renderizadores e extensões
+
+ng-template[slMarkdownNode] com o nome de um tipo conhecido substitui o seu elemento — aqui o link vira o routerLink da aplicação — e slMarkdownChildren desenha os filhos no lugar. Com o nome de um tipo desconhecido, desenha esse tipo: aqui uma menção a uma pessoa, que um passo sobre a árvore criou. Um tipo sem renderizador não aparece.
+
+Excerpt — not a complete module
+
+```html
+<div slMarkdown [tree]="withMentions(tree)">
+  <ng-template slMarkdownNode="mention" let-element
+    ><span slTag>&#64;{{ element.node?.value }}</span></ng-template
+  >
+  <ng-template slMarkdownNode="link" let-element
+    ><a [routerLink]="element.href"><ng-container [slMarkdownChildren]="element" /></a
+  ></ng-template>
+</div>
+```
+
+### Uma resposta que ainda está a chegar
+
+completeMarkdown fecha o que o fluxo deixou aberto — a cerca, o **, a crase, o link cortado — antes do parser. Os blocos já desenhados mantêm a chave e não voltam a montar; streaming põe aria-busy na região até ao fim.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slMarkdown
+  [idPrefix]="'msg-' + message.id + '-'"
+  [streaming]="streaming()"
+  [tree]="tree()"
+></div>
+```
+
+### Carregando, vazio e erro
+
+loading desenha um parágrafo de três linhas depois do delay do skeleton, na tipografia da região; vazio escreve messages.empty ou o conteúdo projetado em slMarkdownEmpty; status="error" troca o documento por uma mensagem e, com retryable, um botão que emite retry.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slMarkdown
+  retryable
+  [loading]="loading()"
+  [status]="failed() ? 'error' : 'ready'"
+  [tree]="tree()"
+  (retry)="reload()"
+>
+  <span slMarkdownEmpty>Este serviço ainda não tem runbook.</span>
+</div>
+```
+
+### Numa página de documentação
+
+slContainer dá a medida, prepareMarkdown dá o índice com os mesmos ids que a página desenha — e exportAs dá o mesmo document() a partir do template —, e provideMarkdownDefaults diz uma vez, em português, o que a família escreve.
+
+Excerpt — not a complete module
+
+```html
+<nav aria-label="Nesta página">
+  @for (heading of outline.headings; track heading.id) {
+    <a [href]="'#' + heading.id">{{ heading.text }}</a>
+  }
+</nav>
+<div slContainer size="measure"><div slMarkdown headingAnchors [tree]="tree"></div></div>
+```
+
+### Teclado e leitor de ecrã
+
+Tab percorre as âncoras dos títulos, os links, uma tabela que rola, os controlos de um bloco de código, as tarefas editáveis e os retornos das notas. A família não acrescenta tecla nenhuma: cada parada é de uma família composta.
+
+Excerpt — not a complete module
+
+```html
+<div slMarkdown headingAnchors [headingOffset]="1" [tree]="tree"></div>
+```