Componentes · Ola 3 · Contenido

Code block

Bloque de código para leer y copiar: comandos, fragmentos de archivos y registros, en mono y sin resaltado de sintaxis. El código es luz en IBM Plex Mono sobre surface: los colores de sintaxis competirían con los de estado. Tiene una cabecera con el lenguaje y un botón de copiar, números de línea opcionales, líneas resaltadas y desplazamiento horizontal propio o ajuste de línea.

import { CodeBlock } from '@archeblack/ui';

Ejemplos

Comando

language pone la etiqueta en la cabecera y el botón de copiar está por defecto. Al copiar, el ícono se confirma y una región viva anuncia «Copiado».

npm install @archeblack/ui

Svelte

<script lang="ts">
	import { CodeBlock } from '@archeblack/ui';
</script>

<CodeBlock language="bash" code="npm install @archeblack/ui" />

Números de línea y líneas resaltadas

lineNumbers suma el margen con los números, que no se copian ni se seleccionan. highlight acepta líneas sueltas y rangos.

import { toast } from '@archeblack/ui';export async function publish(project: string) {	const response = await fetch(`/api/projects/${project}/deploy`, { method: 'POST' });	if (!response.ok) {		toast({ variant: 'danger', title: 'No se pudo publicar' });		return;	}	toast({ variant: 'success', title: 'Publicado' });}

Svelte

<script lang="ts">
	import { CodeBlock } from '@archeblack/ui';

	const code = `import { toast } from '@archeblack/ui';

export async function publish(project: string) {
	const response = await fetch(\`/api/projects/\${project}/deploy\`, { method: 'POST' });
	if (!response.ok) {
		toast({ variant: 'danger', title: 'No se pudo publicar' });
		return;
	}
	toast({ variant: 'success', title: 'Publicado' });
}
`;
</script>

<CodeBlock language="ts" {code} lineNumbers highlight={[4, [5, 8]]} />

Fragmento de un archivo

startLine numera desde la línea del archivo, y highlight usa esos mismos números.

[data-product='example'] {	--arche-color-accent: #e98950;	--arche-color-accent-hover: #ee9d6e;	--arche-color-accent-soft: #2b211f;	--arche-color-accent-border: #674231;	--arche-color-accent-tint: rgb(233 137 80 / 0.07);}

Svelte

<script lang="ts">
	import { CodeBlock } from '@archeblack/ui';

	const code = `[data-product='example'] {
	--arche-color-accent: #e98950;
	--arche-color-accent-hover: #ee9d6e;
	--arche-color-accent-soft: #2b211f;
	--arche-color-accent-border: #674231;
	--arche-color-accent-tint: rgb(233 137 80 / 0.07);
}`;
</script>

<CodeBlock language="css" {code} lineNumbers startLine={6} highlight={[7]} />

Código ancho

Una línea que no entra se desplaza dentro del bloque, sin mover la página. El área se puede enfocar con Tab y desplazar con las flechas.

curl -X POST https://api.arche.dev/v1/projects/portal-clientes/domains -H "Authorization: Bearer $ARCHE_TOKEN" -d '{"domain":"portal.arche.dev"}'

Svelte

<script lang="ts">
	import { CodeBlock } from '@archeblack/ui';

	const code = `curl -X POST https://api.arche.dev/v1/projects/portal-clientes/domains -H "Authorization: Bearer $ARCHE_TOKEN" -d '{"domain":"portal.arche.dev"}'`;
</script>

<CodeBlock language="bash" {code} />

Ajuste de línea

wrap parte las líneas largas: conviene en un registro, donde importa leer cada mensaje entero. Sin copia (copyable={false}), la cabecera muestra solo el lenguaje.

12:04:31 build  Compilando 214 módulos para portal-clientes con la configuración de producción12:04:38 build  Listo en 6,9 s: 38 archivos, 412 kB (128 kB comprimidos)12:04:39 deploy La región sa-east-1 tardó más de lo esperado en responder; se reintenta con la región us-east-1 como respaldo12:04:44 deploy Publicado en https://portal.arche.dev

Svelte

<script lang="ts">
	import { CodeBlock } from '@archeblack/ui';

	const code = `12:04:31 build  Compilando 214 módulos para portal-clientes con la configuración de producción
12:04:38 build  Listo en 6,9 s: 38 archivos, 412 kB (128 kB comprimidos)
12:04:39 deploy La región sa-east-1 tardó más de lo esperado en responder; se reintenta con la región us-east-1 como respaldo
12:04:44 deploy Publicado en https://portal.arche.dev`;
</script>

<CodeBlock language="log" {code} wrap copyable={false} />

Sin cabecera

Sin language y con copyable={false} el bloque es solo el código.

ARCHE_TOKEN=arc_live_…ARCHE_PROJECT=portal-clientes

Svelte

<script lang="ts">
	import { CodeBlock } from '@archeblack/ui';

	const code = `ARCHE_TOKEN=arc_live_…
ARCHE_PROJECT=portal-clientes`;
</script>

<CodeBlock {code} copyable={false} />

Props

Props de CodeBlock
Prop	Descripción
`code` `string`	El código, tal cual. Un salto de línea al final no suma una línea vacía, así se puede pasar el contenido de un archivo o una plantilla de texto.
`language?` `string`	Lenguaje o formato (`bash`, `ts`, `json`…). Se muestra en la cabecera como etiqueta mono de 12 px en mayúsculas y nombra el área cuando se desplaza («Código bash»). No cambia los colores: no hay resaltado de sintaxis.
`copyable?` `boolean` Por defecto `true`	Muestra el botón de copiar en la cabecera. Sin `language` ni `copyable` el bloque no tiene cabecera.
`copyLabel?` `string` Por defecto `'Copiar código'`	Nombre accesible del botón de copiar, que solo tiene un ícono.
`copiedLabel?` `string` Por defecto `'Copiado'`	Confirmación de la copia. Se ve junto al botón y la anuncia una región viva; a los 2 s vuelve al estado inicial.
`copyErrorLabel?` `string` Por defecto `'No se pudo copiar: el código quedó seleccionado'`	Aviso si el portapapeles no está disponible (una página sin HTTPS, un permiso denegado). El código queda seleccionado para copiarlo con el teclado.
`onCopy?` `(code: string) => void`	Se llama con el texto copiado, después de escribirlo en el portapapeles.
`lineNumbers?` `boolean` Por defecto `false`	Números de línea en el margen, en `text-subtle`. No se seleccionan, no se copian y los lectores de pantalla no los leen.
`startLine?` `number` Por defecto `1`	Número de la primera línea, para mostrar un fragmento de un archivo más largo.
`highlight?` `(number \| [number, number])[]`	Líneas resaltadas, con el número que se ve en el margen: `[4, [5, 8]]`. Llevan el fondo `color-selected-soft` (el de la fila elegida de Table), una barra de 2 px en `color-selected` y el texto en `text-strong`, y son un `<mark>`.
`wrap?` `boolean` Por defecto `false`	Ajuste de línea: las líneas largas se parten en lugar de desplazarse. Para registros y mensajes; el código se lee mejor sin partir.
`label?` `string`	Nombre accesible del área cuando el código no entra y se puede enfocar. Por defecto, «Código» más el lenguaje.
`class?` `ClassValue`	Clases del producto; se suman a `arche-code-block`.
`...rest` `HTMLAttributes<HTMLDivElement>`	Cualquier otro atributo va a la raíz (un `<div>`).

Accesibilidad

El código va en <pre><code>, siempre de izquierda a derecha (dir="ltr"), también en una página RTL.
Si el código no entra, el área se desplaza sola, sin mover la página. Entonces es una parada de Tab (tabindex="0") y una región con nombre («Código bash» o el label), así se puede desplazar con las flechas. Si entra, no suma una parada vacía.
El botón de copiar es un Button ghost de solo ícono con aria-label («Copiar código»). Al copiar, el ícono pasa a una marca de verificación y una región viva (role="status"), que existe desde el montaje, anuncia «Copiado»; a los 2 s vuelve. El nombre del botón no cambia.
Si el portapapeles falla, la región viva lo avisa y el código queda seleccionado para copiarlo con Ctrl+C o Cmd+C.
Los números de línea salen de CSS (::before con attr() y texto alternativo vacío) dentro de un elemento con aria-hidden: no se leen, no se seleccionan y no se copian.
Las líneas resaltadas son un <mark> y no dependen solo del color: llevan una barra al inicio. En colores forzados pasan a Highlight. Explica en el texto de al lado por qué están resaltadas.
El texto del código es text (86 %) sobre surface, y los números text-subtle, con contraste AA también sobre el fondo selected-soft de una línea resaltada.

Qué evitar

Colores de sintaxis o de estado dentro del código. El código en luz, como lo muestra el bloque. Para señalar una parte, highlight y una línea de texto que diga por qué.
Un CodeBlock para un nombre, un comando corto o un valor dentro de un párrafo. Código en línea (<code>), que sigue el renglón.
wrap en código fuente: las sangrías se pierden cuando una línea se parte. El desplazamiento horizontal por defecto, y wrap solo para registros o mensajes largos.
Números de línea en un comando de una sola línea. lineNumbers en fragmentos de archivos, sobre todo si el texto cita líneas.
Secretos reales en los ejemplos: el botón de copiar los lleva al portapapeles. Valores de ejemplo recortados (arc_live_…) o variables de entorno.