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

package/docs/code-block.md

@@ -0,0 +1,303 @@
+<!-- index: ./index.md -->
+# code-block
+
+`data-ui="code-block"` · Highlighted source code with copy and line limits.
+
+## Import
+
+```ts
+import {
+  SlCodeBlock,
+  SlCodeBlockAction,
+  SlCodeBlockLine,
+  provideCodeBlockDefaults,
+} from '@slotted/angular/code-block';
+import { fromPrismTokens, fromShikiTokens } from '@slotted/core/code';
+```
+
+Selector: `[slCodeBlock], [slCodeBlockAction], ng-template[slCodeBlockLine]` · exportAs: `slCodeBlock`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<div
+  slCodeBlock
+  [code]="source"
+  language="ts"
+  lineNumbers
+  [marks]="{ highlight: '5-6' }"
+  title="group.ts"
+></div>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div | yes |
+| `header` | div | no |
+| `icon` | span | no |
+| `title` | span | no |
+| `language` | span | no |
+| `actions` | div | no |
+| `wrap` | button | no |
+| `copy` | button | no |
+| `body` | div | yes |
+| `pre` | pre | yes |
+| `code` | code | yes |
+| `line` | span | yes |
+| `number` | span | yes |
+| `marker` | span | yes |
+| `text` | span | yes |
+| `token` | span | no |
+| `reveal` | button | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `code` | `string` | — | CodeBlock | A fonte, como texto. Nunca HTML |
+| `language` | `string` | text | CodeBlock | data-language e class="language-<x>" |
+| `highlight` | `CodeHighlighter \| null` | — | CodeBlock | O motor; null recusa o do injector |
+| `tokens` | `CodeLine[]` | — | CodeBlock | Linhas já tokenizadas pelo consumidor |
+| `title` | `string` | — | CodeBlock | O nome do ficheiro no cabeçalho, e o nome da região |
+| `fileName` | `string` | — | CodeBlock | O nome para o glifo, quando o título não é o nome |
+| `lineNumbers` | `boolean` | false | CodeBlock | O contador na goteira |
+| `start` | `number` | 1 | CodeBlock | O número da primeira linha |
+| `marks` | `CodeMarks` | — | CodeBlock | highlight, add, remove, focus, error, warning — intervalos "1,4-6" ou listas |
+| `wrap` | `model<boolean \| undefined>` | — | CodeBlock | [(wrap)]: presente é controlado, para a vida do bloco |
+| `defaultWrap` | `boolean` | false | CodeBlock | Onde um bloco não controlado começa |
+| `collapseAfter` | `number` | — | CodeBlock | Linhas visíveis antes do controle de revelar |
+| `revealed` | `model<boolean \| undefined>` | — | CodeBlock | [(revealed)]: presente é controlado |
+| `defaultRevealed` | `boolean` | false | CodeBlock | Onde um bloco não controlado começa |
+| `maxLines` | `number` | — | CodeBlock | Linhas antes de o corpo rolar |
+| `copy` | `boolean` | true | CodeBlock | O controle de cópia |
+| `copyRemoved` | `boolean` | false | CodeBlock | Mantém as linhas removidas na cópia |
+| `loading` | `boolean` | false | CodeBlock | Skeletons na altura de seis linhas, aria-busy, sem cópia |
+| `tabSize` | `number` | 2 | CodeBlock | Largura de um tab, para o indent da continuação |
+| `messages` | `PartialMessages<CodeBlockMessages>` | — | slCodeBlock | As palavras da família sobre o idioma em vigor, chave a chave |
+| `ng-template[slCodeBlockLine]` | `projeção` | — | CodeBlock | Substitui a corrida de tokens de cada linha; recebe os tokens, o número, a marca e o esmaecer |
+| `[slCodeBlockAction]` | `projeção` | — | CodeBlock | Controles do consumidor ao lado de copy e wrap |
+| `exportAs` | `slCodeBlock` | — | CodeBlock | Alcança a instância a partir da template: #block="slCodeBlock" e block.copyCode() ou block.scrollToLine(12) |
+| `ng-template[slCodeBlockLine]` | `let-tokens, let-number="number", let-mark="mark", let-dim="dim"` | — | CodeBlock | A linha à maneira da aplicação; a goteira fica da família |
+| `[slCodeBlockAction]` | `ng-content` | — | CodeBlock | Um "Run" ou um "Open in editor" ao lado dos controles |
+| `provideCodeBlockDefaults()` | `highlight \| lineNumbers \| copy` | — | Injector | O motor carregado uma vez, para todos os blocos por baixo; um input no bloco ganha |
+| `slTabs` | `composição` | — | em volta | Vários ficheiros: um bloco por painel |
+| `id, aria-*, data-*, (keydown)` | `atributos nativos` | — | CodeBlock | Ficam no elemento host; o listener do consumidor corre a par do da família |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `(wrapChangeRequest)` | `ChangeRequest<boolean>` | Antes de as linhas quebrarem ou desquebrarem; [(wrap)] é a outra metade, o valor. O pedido leva a razão — pointer, keyboard ou programmatic — e o evento de origem; cancelá-lo não move nada. |
+| `(revealedChangeRequest)` | `ChangeRequest<boolean>` | Antes de o bloco revelar ou dobrar as linhas escondidas; [(revealed)] é o valor. A razão é pointer, keyboard, escape ou programmatic. |
+| `(copyRequest)` | `{ value, copied, reason, source }` | Depois de o controle, ou copyCode(), escrever na área de transferência. copied é false quando a plataforma recusou. |
+| `(highlightError)` | `unknown` | Quando o motor rejeita. O texto puro fica. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `lineNumbers` | `false`, `true` | `false` |
+| `copy` | `true`, `false` | `true` |
+| `copyRemoved` | `false`, `true` | `false` |
+
+## Rules
+
+- O bloco não tem papel: é texto, lido como texto. O role="textbox" com aria-readonly do Carbon num bloco que ninguém edita é recusado por escrito no contrato.
+- O corpo é um scroll-area: role="region", tabindex="0" e um nome — o título, depois aria-label, depois "Code" — só enquanto o código transborda, que é o que SC 2.1.1 e scrollable-region-focusable pedem. As teclas de rolar são as da plataforma; a família não escreve nenhuma.
+- A goteira dos números e dos sinais é aria-hidden e user-select: none: um leitor de ecrã ouve o código e não uma contagem, e uma seleção pelo bloco copia código e nada mais.
+- O controle de cópia anuncia "Copied" ou "Copy failed" pelo live-announcer partilhado e troca o glifo além da cor; o de wrap é aria-pressed; o de revelar leva aria-expanded e aria-controls para o corpo.
+- Um HTML de motor nunca entra: os tokens são texto em spans, e um <script> numa amostra são os seis caracteres que é.
+
+## Tokens
+
+`--slotted-border-subtle`, `--slotted-border-width-thick`, `--slotted-border-width-thin`, `--slotted-code-attribute`, `--slotted-code-block-border-color`, `--slotted-code-block-color`, `--slotted-code-block-color-muted`, `--slotted-code-block-font-family`, `--slotted-code-block-font-size`, `--slotted-code-block-inset-block`, `--slotted-code-block-inset-inline`, `--slotted-code-block-line-height`, `--slotted-code-block-radius`, `--slotted-code-block-surface`, `--slotted-code-block-tab-size`, `--slotted-code-comment`, `--slotted-code-constant`, `--slotted-code-function`, `--slotted-code-keyword`, `--slotted-code-number`, `--slotted-code-property`, `--slotted-code-punctuation`, `--slotted-code-string`, `--slotted-code-tag`, `--slotted-code-type`, `--slotted-code-variable`, `--slotted-control-gap-sm`, `--slotted-control-height-sm`, `--slotted-control-icon-size-md`, `--slotted-control-radius`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-duration-medium`, `--slotted-duration-short`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-family-mono`, `--slotted-font-family-sans`, `--slotted-font-size-sm`, `--slotted-font-size-xs`, `--slotted-font-weight-medium`, `--slotted-highlight-tint-opacity`, `--slotted-line-height-md`, `--slotted-radius-md`, `--slotted-radius-sm`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-6`, `--slotted-surface-sunken`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-subtle-active`, `--slotted-tone-accent-subtle-hover`, `--slotted-tone-accent-surface`, `--slotted-tone-accent-text`, `--slotted-tone-danger-text`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-tone-success-text`, `--slotted-tone-warning-text`
+
+## Examples
+
+### Texto primeiro, tokens quando chegam
+
+O bloco desenha o texto puro no primeiro paint e troca os tokens linha a linha quando o motor responde: a altura não muda, porque cada linha é uma fila da grelha. As cores são a escala --slotted-code-* do tema, e mudam com o esquema.
+
+Excerpt — not a complete module
+
+```html
+<div slCodeBlock [code]="source" [highlight]="tokenise" language="ts"></div>
+```
+
+### Prism e Shiki entram pelos mapeamentos
+
+A família não carrega gramática nenhuma. fromPrismTokens dobra os nomes padrão do Prism sobre os doze escopos; fromShikiTokens lê o último escopo TextMate de cada token. Um HTML de motor nunca entra: o que chega é texto em spans.
+
+Excerpt — not a complete module
+
+```ts
+const prism = (code, lang) => fromPrismTokens(Prism.tokenize(code, Prism.languages[lang]));
+const shiki = async (code, lang) =>
+  fromShikiTokens(
+    await codeToTokens(code, { includeExplanation: 'scopeName', lang, theme: 'none' }),
+  );
+```
+
+### Números de linha
+
+lineNumbers desenha um contador numa goteira larga o bastante para o último número, medida em ch; start diz por onde começa. A goteira é aria-hidden e user-select: none, por isso uma seleção pelo bloco copia código e nada mais.
+
+Excerpt — not a complete module
+
+```html
+<div slCodeBlock [code]="source" language="ts" lineNumbers start="98"></div>
+```
+
+### Linhas marcadas
+
+marks toma intervalos "1,4-6" ou listas de números: highlight tinge com o acento e uma barra na ponta; error e warning com danger e warning. A tinta é do texto do tom a 7,5%, para nenhum escopo cair abaixo de 4,5:1.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slCodeBlock
+  [code]="source"
+  language="sh"
+  [marks]="{ error: '3', highlight: '1', warning: [4] }"
+></div>
+```
+
+### Um diff
+
+add e remove tingem com success e danger e escrevem + e − na goteira, por CSS. O controle de cópia deixa as linhas removidas de fora, porque o código depois da mudança é o que se cola; copyRemoved mantém-nas.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slCodeBlock
+  [code]="source"
+  language="css"
+  lineNumbers
+  [marks]="{ add: '4-6', remove: '2-3' }"
+></div>
+```
+
+### Foco numa parte do bloco
+
+focus esmaece e desfoca as linhas fora do intervalo; o bloco levanta o véu com o ponteiro em cima ou o foco dentro, por isso quem quer o resto tem-no. Sob reduced-motion o desfoque sai e o esmaecer fica, porque é a informação.
+
+Excerpt — not a complete module
+
+```html
+<div slCodeBlock [code]="source" language="json" [marks]="{ focus: '3-6' }"></div>
+```
+
+### Quebrar linhas longas
+
+O controle de wrap só aparece enquanto uma linha transborda — a regra do Docusaurus — e é um botão pressionado. A continuação de uma linha quebrada indenta-se ao próprio indent do código, medido uma vez por linha em ch.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slCodeBlock
+  [code]="command"
+  defaultWrap
+  language="sh"
+  (wrapChangeRequest)="log($event.reason)"
+></div>
+```
+
+### Um ficheiro com nome
+
+title põe o cabeçalho com o nome em mono, o glifo da espécie do ficheiro — uma folha de texto para um .ts, uma folha de tabela para um .csv — e a linguagem no fim. O título é também o nome da região de rolagem.
+
+Excerpt — not a complete module
+
+```html
+<div slCodeBlock [code]="rows" language="csv" title="orders-2026-09.csv"></div>
+```
+
+### Dobrado atrás de "Show more"
+
+collapseAfter esconde o que passa de n linhas atrás de um controle; a última linha visível desvanece-se nele. revealed é o modelo de estado; Escape dentro do bloco revelado dobra-o e mantém o foco. As linhas escondidas ficam no DOM e numa seleção.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slCodeBlock
+  [code]="source"
+  collapseAfter="6"
+  language="json"
+  [(revealed)]="revealed"
+  (revealedChangeRequest)="track($event.value)"
+></div>
+```
+
+### Rolar além de um máximo
+
+maxLines limita a altura do corpo e o scroll-area rola o resto, com a região nomeada e alcançável por Tab. Compõe com collapseAfter: um bloco dobrado a oito e, revelado, rolando além de quarenta.
+
+Excerpt — not a complete module
+
+```html
+<div slCodeBlock [code]="log" language="text" lineNumbers maxLines="12"></div>
+```
+
+### Copiar
+
+O controle escreve o código que o consumidor deu, nunca o texto do DOM: nem números, nem sinais, nem quebras. Terminado, o check fica dois segundos no lugar das folhas e "Copied" é anunciado; copy="false" tira o controle; copyCode() copia sem ele.
+
+Excerpt — not a complete module
+
+```html
+<div slCodeBlock [code]="source" (copyRequest)="$event.copied && toast('Copiado')"></div>
+```
+
+### Código a caminho, e nenhum código
+
+loading desenha a moldura à altura de seis linhas com skeletons dentro e aria-busy, sem controle de cópia — não um spinner, que é para uma região que já tem conteúdo. Uma string vazia é uma linha vazia com o seu número.
+
+Excerpt — not a complete module
+
+```html
+<div slCodeBlock code="" loading title="deploy.log"></div>
+```
+
+### Conteúdo que a família não escolheu
+
+Uma linha de 400 caracteres rola e, sob wrap, parte-se num token indivisível em vez de escapar da caixa; código árabe numa página RTL lê-se da esquerda para a direita; um <script> na amostra são seis caracteres.
+
+Excerpt — not a complete module
+
+```html
+<div slCodeBlock [code]="'<script>alert(1)</script>'" language="html"></div>
+```
+
+### Composição
+
+Vários ficheiros são tabs com um bloco por painel; uma ação do consumidor entra em actions ao lado do copy, por slCodeBlockAction; um ng-template slCodeBlockLine desenha uma linha à maneira da aplicação; provideCodeBlockDefaults entrega o motor uma vez ao injector.
+
+Excerpt — not a complete module
+
+```ts
+providers: [provideCodeBlockDefaults({ highlight: shiki, lineNumbers: true })];
+
+// <div slCodeBlock [code]="a" language="ts" title="a.ts"></div>
+// <div slCodeBlock [code]="b" language="css" title="a.css">
+//   <button slCodeBlockAction slButton size="xs" variant="ghost">Run</button>
+// </div>
+```
+
+### Teclado
+
+Tab: copy, wrap, reveal, e o corpo quando transborda. No corpo as setas, Page, Home, End e Space são os da plataforma; Enter e Space nos controles; Escape num bloco revelado dobra-o e mantém o foco.
+
+Excerpt — not a complete module
+
+```html
+<!-- "group.ts, region" — o título, porque o corpo só é uma região com nome enquanto o código transborda. -->
+<div slCodeBlock [code]="wide" language="ts" title="group.ts"></div>
+```