@hanzo/ui

Blocos

Conteúdo como dados. Uma página é uma lista de blocos; cada um nomeia o seu tipo, o tipo escolhe o renderizador, e o renderizador lê o resto.

import { Content, type Block } from '@hanzo/ui/blocks'

<Content blocks={page} />

Um bloco é dado: blockType escolhe o renderizador e os outros campos são a entrada desse renderizador. Então uma página pode ser escrita num CMS, commitada num repositório ou produzida por um servidor, e é tipada de qualquer jeito. Cada campo specifiers é um saco separado por espaços de dicas de layout que o renderizador lê; é uma string e não uma união, então um site acrescenta uma dica digitando-a, e uma dica desconhecida é ignorada em vez de falhar o build.

Uma página

import { Content, type Block } from '@hanzo/ui/blocks'

const page: Block[] = [
  {
    blockType: 'enh-heading',
    preheading: { text: 'Blocks' },
    heading: { text: 'Content as data', level: 2 },
    byline: { text: 'A page is a list of blocks; the type picks the renderer.' },
  },
  { blockType: 'space', sizes: 4 },
  {
    blockType: 'bullet-cards',
    grid: { at: { xs: { columns: 1, gap: 2 }, md: { columns: 3, gap: 3 } } },
    cards: [{ text: 'Typed either way' }, { text: 'Authored anywhere' }, { text: 'Rendered once' }],
  },
  { blockType: 'space', sizes: 4 },
  {
    blockType: 'cta',
    elements: [
      { title: 'Read the docs', href: '/docs' },
      { title: 'Source', href: 'https://github.com/hanzoai/ui', variant: 'outline' },
    ],
  },
]

<Content blocks={page} />

Blocks

Content as data

A page is a list of blocks; the type picks the renderer.

Typed either way

Authored anywhere

Rendered once

O vocabulário

TipoO que desenha
headingUm título com uma linha de apoio opcional, level 0 para um parágrafo e 1 a 6 para as tags.
enh-headingAs partes nomeadas: um pré-título acima, o título, uma linha de apoio abaixo, cada um com o próprio nível e margem.
imageUma imagem a partir de um ImageDef — src, alt, dim — com alinhamento e dicas de telefone em specifiers.
videoUm VideoDef: fontes, um poster, dimensionamento por degrau.
spaceEspaço vertical em unidades de espaçamento, por degrau ou um número para todos.
ctaUma fileira de links e botões: fill, left, right, e as dicas de telefone.
cardUm painel titulado com mídia, conteúdo e uma chamada para ação.
bullet-cardsUma grade de cards de uma linha, cada um um ícone ao lado do texto.
gridUm GridDef — colunas e gap por degrau, em ordem crescente — sobre cells.
groupUm wrapper sobre elements, para dicas que valem para o conjunto.
accordianGatilhos e o conteúdo deles.
carte-blancheUm painel livre: qualquer coisa acima, um título, qualquer coisa abaixo, uma chamada para ação no pé.
screenfulUma tela cheia: um banner opcional sobre uma a três colunas, com uma ordem no telefone.
elementUm nó que o autor já construiu. Não tem renderizador, de propósito, e é isso que deixa uma página de blocos conter qualquer coisa.

Cada forma é exportada como um tipo do mesmo subpath — HeadingBlock, CTABlock, ScreenfulBlock e o resto — ao lado das definições que elas compartilham: GridDef, ImageDef, VideoDef, LinkDef, ButtonDef. Um LinkDef com um href http ou mailto é externo por si e abre numa nova aba com rel="noreferrer noopener"; declare external só onde o esquema não consegue dizer.

O dispositivo é uma prop

Todo renderizador recebe agent, a classe do dispositivo, em vez de ler uma media query. Esses blocos renderizam num servidor que tem de emitir a marcação certa na primeira vez: um layout de telefone que chega como marcação de desktop e se corrige na hidratação é um salto visível, e para os blocos de vídeo um download desperdiçado.

<Content blocks={page} agent={isPhone ? 'phone' : 'desktop'} />

Os seus próprios tipos

O mapa de tipo para renderizador é o ponto de extensão. Um host acrescenta um tipo próprio, ou substitui um — que é como um app Next troca a imagem pela versão que otimiza, e como qualquer coisa que a biblioteca não traz chega à página.

import { registerBlockType, type BlockComponentProps } from '@hanzo/ui/blocks'

registerBlockType('quote', ({ block }: BlockComponentProps) => (
  <blockquote>{(block as { text: string }).text}</blockquote>
))

has(specifiers, token) responde se uma dica está num saco, e fit(dim, within) é a maior caixa de uma proporção dentro de outra; os dois são exportados para um renderizador seu. O catálogo Blocos renderiza os exemplos de cada renderizador ao lado dos tipos.