@hanzo/ui

Blocs

Le contenu comme données. Une page est une liste de blocs ; chacun nomme son type, le type choisit le renderer, et le renderer lit le reste.

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

<Content blocks={page} />

Un bloc est une donnée : blockType choisit le renderer et les autres champs sont l’entrée de ce renderer. Une page peut donc être rédigée dans un CMS, versée dans un dépôt ou produite par un serveur, et elle est typée dans les trois cas. Chaque champ specifiers est un sac, séparé par des espaces, de pistes de disposition que le renderer lit ; c’est une chaîne plutôt qu’une union, donc un site ajoute une piste en l’écrivant, et une piste inconnue est ignorée au lieu de faire échouer un build.

Une page

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

Le vocabulaire

TypeCe qu’il dessine
headingUn titre avec une ligne d’accompagnement facultative, level 0 pour un paragraphe et de 1 à 6 pour les balises.
enh-headingLes parties nommées : un surtitre au-dessus, le titre, une ligne d’accompagnement en dessous, chacun avec son niveau et sa marge.
imageUne image à partir d’un ImageDef — src, alt, dim — avec l’alignement et les pistes pour le téléphone dans specifiers.
videoUn VideoDef : des sources, une affiche, le dimensionnement par barreau.
spaceDe l’espace vertical en unités d’espacement, par barreau ou un seul nombre pour tous.
ctaUne rangée de liens et de boutons : fill, left, right, et les pistes pour le téléphone.
cardUn panneau titré, avec média, contenu et un appel à l’action.
bullet-cardsUne grille de cartes d’une ligne, chacune une icône à côté de son texte.
gridUn GridDef — colonnes et écart par barreau, dans l’ordre croissant — par-dessus cells.
groupUne enveloppe sur elements, pour des pistes qui valent pour l’ensemble.
accordianLes déclencheurs et leur contenu.
carte-blancheUn panneau libre : n’importe quoi au-dessus, un titre, n’importe quoi en dessous, un appel à l’action au pied.
screenfulUn écran plein : une bannière facultative sur une à trois colonnes, avec un ordre pour le téléphone.
elementUn nœud que l’auteur a déjà construit. Il n’a pas de renderer, et c’est voulu : c’est ce qui permet à une page de blocs de contenir n’importe quoi.

Chaque forme est exportée comme type depuis le même subpath — HeadingBlock, CTABlock, ScreenfulBlock et le reste — à côté des définitions qu’elles partagent : GridDef, ImageDef, VideoDef, LinkDef, ButtonDef. Un LinkDef dont le href est http ou mailto est externe de lui-même et s’ouvre dans un nouvel onglet avec rel="noreferrer noopener" ; indiquez external seulement là où le schéma ne peut pas le dire.

L’appareil est une prop

Chaque renderer reçoit agent, la classe d’appareil, plutôt que de lire une media query. Ces blocs se rendent sur un serveur qui doit émettre le bon balisage du premier coup : une disposition de téléphone qui arrive en balisage de bureau et se corrige à l’hydratation est un saut visible, et pour les blocs vidéo un téléchargement pour rien.

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

Vos propres types

La correspondance du type vers le renderer est le point d’extension. Un hôte ajoute un type à lui, ou en remplace un — c’est ainsi qu’une app Next substitue son image qui optimise, et qu’arrive dans la page tout ce que la bibliothèque ne livre pas.

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

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

has(specifiers, token) dit si une piste est dans un sac, et fit(dim, within) est la plus grande boîte d’un ratio dans une autre ; les deux sont exportés pour un renderer à vous. Le catalogue Blocs rend les exemples de chaque renderer à côté de ses types.