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

package/docs/markdown.json

@@ -0,0 +1,461 @@
+{
+  "family": "markdown",
+  "ui": "markdown",
+  "binding": "angular",
+  "catalog": {
+    "group": "Data display",
+    "summary": "Renders Markdown with an element allowlist."
+  },
+  "axes": {},
+  "members": {
+    "markdown": {
+      "nativeElement": "div",
+      "defaults": {
+        "status": "ready",
+        "loading": false,
+        "streaming": false,
+        "external": "new-tab",
+        "headingAnchors": false,
+        "headingOffset": 0,
+        "idPrefix": "",
+        "alerts": true,
+        "unwrapDisallowed": false
+      },
+      "capabilities": [
+        "appearance",
+        "size",
+        "status",
+        "content",
+        "loading",
+        "external",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "focus-visible",
+        "loading"
+      ],
+      "parts": [
+        "root",
+        "embed",
+        "alert-body",
+        "task-list",
+        "task",
+        "task-body",
+        "backref",
+        "empty",
+        "error"
+      ]
+    }
+  },
+  "docs": {
+    "markdown": {
+      "imports": {
+        "source": "import {\n  SlMarkdown,\n  SlMarkdownChildren,\n  SlMarkdownEmpty,\n  SlMarkdownNode,\n  provideMarkdownDefaults,\n} from '@slotted/angular/markdown';\nimport { completeMarkdown, fromMarkedTokens, prepareMarkdown } from '@slotted/core/markdown';",
+        "selector": "[slMarkdown], ng-template[slMarkdownNode], [slMarkdownChildren], [slMarkdownEmpty]",
+        "exportAs": "slMarkdown"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "div",
+          "required": true,
+          "purpose": "A família: data-ui=\"markdown\", data-status, data-flow, data-loading, data-empty, data-streaming e aria-busy. Os estados vazio, erro e carregamento desenham-se aqui, fora da tipografia da região."
+        },
+        {
+          "part": "embed",
+          "element": "div",
+          "required": false,
+          "purpose": "Segura um code-block ou um alert e dá-lhe o fluxo da região, lido dos tokens públicos de prose; prose só espaça os elementos que conhece."
+        },
+        {
+          "part": "alert-body",
+          "element": "div",
+          "required": false,
+          "purpose": "Os blocos de um alerta do GitHub dentro da descrição do alert; o primeiro começa rente ao título."
+        },
+        {
+          "part": "task-list",
+          "element": "ul | ol",
+          "required": false,
+          "purpose": "Uma lista em que pelo menos um item é tarefa. Os itens comuns mantêm o marcador."
+        },
+        {
+          "part": "task",
+          "element": "li",
+          "required": false,
+          "purpose": "Uma grelha de duas colunas: o checkbox onde estava o marcador, depois o corpo. O texto começa na mesma aresta que o de um item comum."
+        },
+        {
+          "part": "task-body",
+          "element": "div",
+          "required": false,
+          "purpose": "O conteúdo da tarefa, incluindo uma lista aninhada."
+        },
+        {
+          "part": "backref",
+          "element": "a",
+          "required": false,
+          "purpose": "O retorno de uma nota de rodapé à sua referência: uma seta para cima num alvo de 24 px, uma por referência."
+        },
+        {
+          "part": "empty",
+          "element": "p",
+          "required": false,
+          "purpose": "O documento não tem conteúdo: messages.empty, ou o nó do consumidor em empty."
+        },
+        {
+          "part": "error",
+          "element": "div",
+          "required": false,
+          "purpose": "A fonte não chegou: inline-message em danger com messages.error e, com retryable, um botão de repetir."
+        }
+      ],
+      "api": [
+        {
+          "name": "tree",
+          "type": "MarkdownNode | null",
+          "defaultValue": "—",
+          "appliesTo": "[slMarkdown]",
+          "description": "O documento em mdast; nunca HTML"
+        },
+        {
+          "name": "size",
+          "type": "'md' | 'lg' | 'xl'",
+          "defaultValue": "lg",
+          "appliesTo": "[slMarkdown]",
+          "description": "O degrau de tipo da região, de prose"
+        },
+        {
+          "name": "flow",
+          "type": "'tight' | 'normal' | 'loose'",
+          "defaultValue": "normal",
+          "appliesTo": "[slMarkdown]",
+          "description": "O espaço entre blocos, de prose"
+        },
+        {
+          "name": "status",
+          "type": "'ready' | 'error'",
+          "defaultValue": "ready",
+          "appliesTo": "[slMarkdown]",
+          "description": "error troca o documento pela parte error"
+        },
+        {
+          "name": "loading",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "[slMarkdown]",
+          "description": "Um parágrafo de espera, depois do delay do skeleton"
+        },
+        {
+          "name": "streaming",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "[slMarkdown]",
+          "description": "aria-busy enquanto a fonte chega"
+        },
+        {
+          "name": "external",
+          "type": "'new-tab' | 'same-tab'",
+          "defaultValue": "new-tab",
+          "appliesTo": "[slMarkdown]",
+          "description": "Onde abre um link que sai da aplicação"
+        },
+        {
+          "name": "headingAnchors",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "[slMarkdown]",
+          "description": "Um permalink em cada título"
+        },
+        {
+          "name": "headingOffset",
+          "type": "number",
+          "defaultValue": "0",
+          "appliesTo": "[slMarkdown]",
+          "description": "Somado ao nível de cada título, até seis"
+        },
+        {
+          "name": "idPrefix",
+          "type": "string",
+          "defaultValue": "",
+          "appliesTo": "[slMarkdown]",
+          "description": "Antes de cada id gerado; obrigatório com duas regiões na página"
+        },
+        {
+          "name": "alerts",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "[slMarkdown]",
+          "description": "Lê > [!NOTE] e os irmãos como alert"
+        },
+        {
+          "name": "allow",
+          "type": "string[]",
+          "defaultValue": "CommonMark + GFM sem html",
+          "appliesTo": "[slMarkdown]",
+          "description": "Os tipos mdast desenhados"
+        },
+        {
+          "name": "unwrapDisallowed",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "[slMarkdown]",
+          "description": "Um tipo recusado entrega os filhos ao pai"
+        },
+        {
+          "name": "transformUrl",
+          "type": "(url, kind, node) => string | null",
+          "defaultValue": "safeUrl",
+          "appliesTo": "[slMarkdown]",
+          "description": "A política de URL; null recusa"
+        },
+        {
+          "name": "isExternal",
+          "type": "(href) => boolean",
+          "defaultValue": "isExternalUrl",
+          "appliesTo": "[slMarkdown]",
+          "description": "Se um link sai da aplicação"
+        },
+        {
+          "name": "messages",
+          "type": "PartialMessages<MarkdownMessages>",
+          "defaultValue": "—",
+          "appliesTo": "[slMarkdown]",
+          "description": "As palavras da família sobre o idioma em vigor, chave a chave"
+        },
+        {
+          "name": "editableTasks",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "[slMarkdown]",
+          "description": "Liga os checkboxes das tarefas; um output não diz se alguém o ouve"
+        },
+        {
+          "name": "retryable",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "[slMarkdown]",
+          "description": "Desenha o botão de repetir na parte error"
+        }
+      ],
+      "composition": [
+        {
+          "name": "ng-template[slMarkdownNode]",
+          "type": "kind | type",
+          "defaultValue": "—",
+          "appliesTo": "conteúdo",
+          "description": "Substitui o elemento de um tipo conhecido, ou desenha um tipo desconhecido; recebe o elemento preparado"
+        },
+        {
+          "name": "[slMarkdownChildren]",
+          "type": "MarkdownElement",
+          "defaultValue": "—",
+          "appliesTo": "ng-container",
+          "description": "Desenha os filhos de um elemento dentro de um template, sem elemento próprio"
+        },
+        {
+          "name": "[slMarkdownEmpty]",
+          "type": "conteúdo projetado",
+          "defaultValue": "—",
+          "appliesTo": "conteúdo",
+          "description": "O conteúdo da parte empty"
+        },
+        {
+          "name": "exportAs",
+          "type": "slMarkdown",
+          "defaultValue": "—",
+          "appliesTo": "[slMarkdown]",
+          "description": "document(): os headings e as notas, com os ids da página"
+        },
+        {
+          "name": "provideMarkdownDefaults",
+          "type": "external | headingAnchors | alerts | allow | transformUrl | isExternal",
+          "defaultValue": "—",
+          "appliesTo": "Aplicação",
+          "description": "Decidido uma vez para todos os documentos por baixo; um input ganha"
+        },
+        {
+          "name": "prepareMarkdown",
+          "type": "(tree, options) => MarkdownDocument",
+          "defaultValue": "—",
+          "appliesTo": "@slotted/core/markdown",
+          "description": "headings para um índice, com os ids da página"
+        },
+        {
+          "name": "completeMarkdown",
+          "type": "(source) => string",
+          "defaultValue": "—",
+          "appliesTo": "@slotted/core/markdown",
+          "description": "Fecha uma fonte cortada antes do parser"
+        },
+        {
+          "name": "fromMarkedTokens",
+          "type": "(tokens) => MarkdownNode",
+          "defaultValue": "—",
+          "appliesTo": "@slotted/core/markdown",
+          "description": "O lexer do marked como mdast"
+        },
+        {
+          "name": "id, aria-*, data-*",
+          "type": "atributos nativos",
+          "defaultValue": "—",
+          "appliesTo": "[slMarkdown]",
+          "description": "Ficam no elemento do consumidor"
+        }
+      ],
+      "events": [
+        {
+          "name": "taskChange",
+          "payload": "{ index, checked, offset, request }",
+          "when": "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."
+        },
+        {
+          "name": "retry",
+          "payload": "'pointer' | 'keyboard'",
+          "when": "Quando o leitor pressiona o botão de repetir da parte error, desenhado com retryable."
+        }
+      ],
+      "accessibility": [
+        "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": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "Um runbook escrito em Markdown, passado pelo lexer do marked e por fromMarkedTokens. Os controlos por baixo do palco movem o tamanho, o fluxo, as âncoras e o deslocamento dos títulos.",
+      "language": "html",
+      "source": "<div slMarkdown headingAnchors [tree]=\"tree\"></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "document",
+      "title": "Um documento inteiro",
+      "note": "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.",
+      "language": "html",
+      "source": "<div slMarkdown headingAnchors [tree]=\"tree\"></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "tables",
+      "title": "Tabelas do GFM",
+      "note": "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.",
+      "language": "markdown",
+      "source": "| Plano | Lugares |   Preço |\n| :---- | :-----: | ------: |\n| Team  |   10    | $120.00 |\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "code",
+      "title": "Cercas com code-block",
+      "note": "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.",
+      "language": "markdown",
+      "source": "```ts title=\"deploy.ts\" {2} showLineNumbers\nimport { deploy } from '@acme/cli';\nawait deploy({ env: 'production' });\n```\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "tasks",
+      "title": "Listas de tarefas",
+      "note": "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.",
+      "language": "html",
+      "source": "<div\n  slMarkdown\n  editableTasks\n  [tree]=\"tree\"\n  (taskChange)=\"source.set(toggleTask(source(), $event.index, $event.checked))\"\n></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "alerts",
+      "title": "Alertas do GitHub",
+      "note": "> [!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.",
+      "language": "markdown",
+      "source": "> [!WARNING]\n> A deployment during a migration waits for the migration to finish.\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "footnotes",
+      "title": "Notas de rodapé",
+      "note": "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.",
+      "language": "html",
+      "source": "<div slMarkdown [messages]=\"{ footnotes: 'Notas' }\" [tree]=\"tree\"></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "links",
+      "title": "Links internos e externos",
+      "note": "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.",
+      "language": "html",
+      "source": "<div slMarkdown [isExternal]=\"isOwnDomainInternal\" [tree]=\"tree\"></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "sanitisation",
+      "title": "Sanitização por construção",
+      "note": "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.",
+      "language": "html",
+      "source": "<div\n  slMarkdown\n  unwrapDisallowed\n  [allow]=\"['paragraph', 'text', 'emphasis', 'strong', 'link']\"\n  [tree]=\"tree\"\n></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "renderers",
+      "title": "Renderizadores e extensões",
+      "note": "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.",
+      "language": "html",
+      "source": "<div slMarkdown [tree]=\"withMentions(tree)\">\n  <ng-template slMarkdownNode=\"mention\" let-element\n    ><span slTag>&#64;{{ element.node?.value }}</span></ng-template\n  >\n  <ng-template slMarkdownNode=\"link\" let-element\n    ><a [routerLink]=\"element.href\"><ng-container [slMarkdownChildren]=\"element\" /></a\n  ></ng-template>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "streaming",
+      "title": "Uma resposta que ainda está a chegar",
+      "note": "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.",
+      "language": "html",
+      "source": "<div\n  slMarkdown\n  [idPrefix]=\"'msg-' + message.id + '-'\"\n  [streaming]=\"streaming()\"\n  [tree]=\"tree()\"\n></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "states",
+      "title": "Carregando, vazio e erro",
+      "note": "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.",
+      "language": "html",
+      "source": "<div\n  slMarkdown\n  retryable\n  [loading]=\"loading()\"\n  [status]=\"failed() ? 'error' : 'ready'\"\n  [tree]=\"tree()\"\n  (retry)=\"reload()\"\n>\n  <span slMarkdownEmpty>Este serviço ainda não tem runbook.</span>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Numa página de documentação",
+      "note": "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.",
+      "language": "html",
+      "source": "<nav aria-label=\"Nesta página\">\n  @for (heading of outline.headings; track heading.id) {\n    <a [href]=\"'#' + heading.id\">{{ heading.text }}</a>\n  }\n</nav>\n<div slContainer size=\"measure\"><div slMarkdown headingAnchors [tree]=\"tree\"></div></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "accessibility",
+      "title": "Teclado e leitor de ecrã",
+      "note": "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.",
+      "language": "html",
+      "source": "<div slMarkdown headingAnchors [headingOffset]=\"1\" [tree]=\"tree\"></div>\n",
+      "verdict": "excerpt"
+    }
+  ]
+}