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

package/dist/docs/markdown.json

@@ -0,0 +1,459 @@
+{
+  "family": "markdown",
+  "ui": "markdown",
+  "binding": "react",
+  "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 { Markdown, MarkdownDefaultsProvider } from '@slotted/react';\nimport { completeMarkdown, fromMarkedTokens, prepareMarkdown } from '@slotted/core/markdown';"
+      },
+      "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 onRetry, um botão de repetir."
+        }
+      ],
+      "api": [
+        {
+          "name": "tree",
+          "type": "MarkdownNode | null",
+          "defaultValue": "—",
+          "appliesTo": "Markdown",
+          "description": "O documento em mdast; nunca HTML"
+        },
+        {
+          "name": "size",
+          "type": "'md' | 'lg' | 'xl'",
+          "defaultValue": "lg",
+          "appliesTo": "Markdown",
+          "description": "O degrau de tipo da região, de prose"
+        },
+        {
+          "name": "flow",
+          "type": "'tight' | 'normal' | 'loose'",
+          "defaultValue": "normal",
+          "appliesTo": "Markdown",
+          "description": "O espaço entre blocos, de prose"
+        },
+        {
+          "name": "status",
+          "type": "'ready' | 'error'",
+          "defaultValue": "ready",
+          "appliesTo": "Markdown",
+          "description": "error troca o documento pela parte error"
+        },
+        {
+          "name": "loading",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Markdown",
+          "description": "Um parágrafo de espera, depois do delay do skeleton"
+        },
+        {
+          "name": "streaming",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Markdown",
+          "description": "aria-busy enquanto a fonte chega"
+        },
+        {
+          "name": "external",
+          "type": "'new-tab' | 'same-tab'",
+          "defaultValue": "new-tab",
+          "appliesTo": "Markdown",
+          "description": "Onde abre um link que sai da aplicação"
+        },
+        {
+          "name": "headingAnchors",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Markdown",
+          "description": "Um permalink em cada título"
+        },
+        {
+          "name": "headingOffset",
+          "type": "number",
+          "defaultValue": "0",
+          "appliesTo": "Markdown",
+          "description": "Somado ao nível de cada título, até seis"
+        },
+        {
+          "name": "idPrefix",
+          "type": "string",
+          "defaultValue": "",
+          "appliesTo": "Markdown",
+          "description": "Antes de cada id gerado; obrigatório com duas regiões na página"
+        },
+        {
+          "name": "alerts",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "Markdown",
+          "description": "Lê > [!NOTE] e os irmãos como alert"
+        },
+        {
+          "name": "allow",
+          "type": "string[]",
+          "defaultValue": "CommonMark + GFM sem html",
+          "appliesTo": "Markdown",
+          "description": "Os tipos mdast desenhados"
+        },
+        {
+          "name": "unwrapDisallowed",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Markdown",
+          "description": "Um tipo recusado entrega os filhos ao pai"
+        },
+        {
+          "name": "transformUrl",
+          "type": "(url, kind, node) => string | null",
+          "defaultValue": "safeUrl",
+          "appliesTo": "Markdown",
+          "description": "A política de URL; null recusa"
+        },
+        {
+          "name": "isExternal",
+          "type": "(href) => boolean",
+          "defaultValue": "isExternalUrl",
+          "appliesTo": "Markdown",
+          "description": "Se um link sai da aplicação"
+        },
+        {
+          "name": "renderers",
+          "type": "MarkdownRenderers",
+          "defaultValue": "—",
+          "appliesTo": "Markdown",
+          "description": "Substitui o elemento de um tipo conhecido"
+        },
+        {
+          "name": "extensions",
+          "type": "MarkdownExtensions",
+          "defaultValue": "—",
+          "appliesTo": "Markdown",
+          "description": "Desenha um tipo que a família não conhece"
+        },
+        {
+          "name": "messages",
+          "type": "PartialMessages<MarkdownMessages>",
+          "defaultValue": "—",
+          "appliesTo": "Markdown",
+          "description": "As palavras da família sobre o idioma em vigor, chave a chave"
+        },
+        {
+          "name": "empty",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "Markdown",
+          "description": "O conteúdo da parte empty"
+        }
+      ],
+      "composition": [
+        {
+          "name": "render",
+          "type": "(props) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "Markdown",
+          "description": "A raiz noutro elemento: article, section"
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLDivElement>",
+          "defaultValue": "—",
+          "appliesTo": "Markdown",
+          "description": "O elemento da raiz"
+        },
+        {
+          "name": "MarkdownDefaultsProvider",
+          "type": "external | headingAnchors | alerts | allow | transformUrl | isExternal",
+          "defaultValue": "—",
+          "appliesTo": "Aplicação",
+          "description": "Decidido uma vez para todos os documentos por baixo; uma prop 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": "CodeBlockDefaultsProvider",
+          "type": "highlight",
+          "defaultValue": "—",
+          "appliesTo": "Aplicação",
+          "description": "O motor de realce de cada cerca"
+        },
+        {
+          "name": "id, aria-*, data-*, on*",
+          "type": "props nativas",
+          "defaultValue": "—",
+          "appliesTo": "Markdown",
+          "description": "Chegam à raiz"
+        }
+      ],
+      "events": [
+        {
+          "name": "onTaskChange",
+          "payload": "({ index, checked, offset }, request)",
+          "when": "Quando o leitor marca ou desmarca uma tarefa, com a razão pointer ou keyboard. A caixa não se move: a árvore nova do consumidor é que a move."
+        },
+        {
+          "name": "onRetry",
+          "payload": "(reason: 'pointer' | 'keyboard')",
+          "when": "Quando o leitor pressiona o botão de repetir da parte error."
+        }
+      ],
+      "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 onTaskChange é 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": "tsx",
+      "source": "import { marked } from 'marked';\n\nconst tree = fromMarkedTokens(marked.lexer(source));\n\n<Markdown headingAnchors tree={tree} />;\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": "tsx",
+      "source": "<Markdown headingAnchors tree={tree} />;\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 onTaskChange 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": "tsx",
+      "source": "<Markdown\n  onTaskChange={({ index, checked }) => setSource(toggleTask(source, index, checked))}\n  tree={fromMarkedTokens(marked.lexer(source))}\n/>;\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": "tsx",
+      "source": "<Markdown messages={{ footnotes: 'Notas' }} tree={tree} />;\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": "tsx",
+      "source": "<Markdown\n  isExternal={(href) => /^https?:\\/\\//.test(href) && !href.startsWith('https://acme.example')}\n  tree={tree}\n/>;\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": "tsx",
+      "source": "<Markdown\n  allow={['paragraph', 'text', 'emphasis', 'strong', 'link']}\n  tree={tree}\n  unwrapDisallowed\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "renderers",
+      "title": "Renderizadores e extensões",
+      "note": "renderers substitui o elemento de um tipo conhecido — aqui o link vira o link do router da aplicação. extensions desenha um tipo que a família não conhece: uma menção @nome que um passo sobre a árvore criou. Um tipo sem renderizador não aparece.",
+      "language": "tsx",
+      "source": "<Markdown\n  extensions={{ mention: ({ element }) => <Tag>@{String(element.node.value)}</Tag> }}\n  renderers={{\n    link: ({ element, children }) => <RouterLink to={element.href}>{children}</RouterLink>,\n  }}\n  tree={withMentions(tree)}\n/>;\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": "tsx",
+      "source": "<Markdown\n  idPrefix={`msg-${message.id}-`}\n  streaming={status === 'streaming'}\n  tree={fromMarkedTokens(marked.lexer(completeMarkdown(message.text)))}\n/>;\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 nó do consumidor; status=\"error\" troca o documento por uma mensagem e, com onRetry, um botão.",
+      "language": "tsx",
+      "source": "<Markdown\n  loading={query.isLoading}\n  onRetry={query.refetch}\n  status={query.isError ? 'error' : 'ready'}\n  tree={query.data}\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Numa página de documentação",
+      "note": "Container dá a medida, prepareMarkdown dá o índice com os mesmos ids que a página desenha, e MarkdownDefaultsProvider diz uma vez, em português, o que a família escreve.",
+      "language": "tsx",
+      "source": "const { headings } = prepareMarkdown(tree);\n\n<MarkdownDefaultsProvider headingAnchors>\n  <Container size=\"measure\">\n    <Markdown messages={{ footnotes: 'Notas' }} tree={tree} />\n  </Container>\n</MarkdownDefaultsProvider>;\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": "tsx",
+      "source": "<Markdown headingAnchors headingOffset={1} tree={tree} />;\n",
+      "verdict": "excerpt"
+    }
+  ]
+}